Skip to main content

Transformation: TypeScript

Open Repo Download ZIP

git clone https://github.com/AEEF-AI/aeef-transform.git

The Transformation tier extends the Quick Start TypeScript setup with a full 7-stage CI pipeline, mutation testing, schema validation, and provenance generation. This guide walks through every addition and how it maps to AEEF standards.

Full Pipeline Walkthrough​

The CI pipeline runs seven stages in sequence. A failure at any stage blocks the PR:

lint --> typecheck --> test --> mutation --> SAST --> SCA+license --> schema-validate

Stage 1: Lint​

- name: Lint
  run: npm run lint

Uses the ESLint flat config with strict TypeScript rules. See the ESLint configuration section below for details.

Stage 2: Type Check​

- name: Type Check
  run: npx tsc --noEmit

Runs the TypeScript compiler in check-only mode. Catches type errors that ESLint rules cannot detect.

Stage 3: Test with Coverage​

- name: Test
  run: npm run test

Runs Vitest with enforced coverage thresholds configured in vitest.config.ts (80% lines, 70% branches). Coverage reports are uploaded as CI artifacts.

Stage 4: Mutation Testing​

- name: Mutation Testing
  run: npm run test:mutation

Stryker Mutator introduces small changes (mutations) to source code and verifies that tests catch them. Configured via stryker.config.mjs with Vitest runner.

Stage 5: SAST (Semgrep)​

- name: SAST
  run: npx semgrep --config .semgrep/ --config p/typescript src/

Runs Semgrep with both custom AEEF rules and the community TypeScript ruleset.

Stage 6: SCA and License Check​

- name: SCA
  run: |
    npm audit --audit-level=high
    npx license-checker --onlyAllow 'MIT;ISC;BSD-2-Clause;BSD-3-Clause;Apache-2.0'

Checks for known vulnerabilities in dependencies and verifies all dependency licenses are on the allow list.

Stage 7: Schema Validation​

- name: Schema Validation
  run: npx ajv validate -s schemas/kpi-record.schema.json -d 'metrics/*.json'

Validates that all KPI records and provenance logs conform to the AEEF JSON schemas.

ESLint Flat Config​

The Transformation tier ESLint configuration extends the Quick Start config with additional rules:

import js from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  js.configs.recommended,
  ...tseslint.configs.strictTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
    rules: {
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
      '@typescript-eslint/explicit-function-return-type': ['warn', {
        allowExpressions: true,
        allowTypedFunctionExpressions: true,
      }],
      '@typescript-eslint/no-floating-promises': 'error',
      '@typescript-eslint/no-misused-promises': 'error',
      '@typescript-eslint/strict-boolean-expressions': 'warn',
      'no-console': ['warn', { allow: ['warn', 'error'] }],
      'no-eval': 'error',
      'prefer-const': 'error',
    },
  },
);

Stryker Mutation Testing Setup​

Stryker is configured via stryker.config.mjs:

/** @type {import('@stryker-mutator/api/core').PartialStrykerOptions} */
export default {
  packageManager: 'npm',
  reporters: ['html', 'clear-text', 'progress'],
  testRunner: 'vitest',
  checkers: ['typescript'],
  tsconfigFile: 'tsconfig.json',
  vitest: {
    configFile: 'vitest.config.ts',
  },
  thresholds: {
    high: 80,
    low: 60,
    break: 50,
  },
  mutate: [
    'src/**/*.ts',
    '!src/**/*.test.ts',
    '!src/index.ts',
  ],
};

The break threshold means any mutation score below 50% fails the pipeline, enforcing meaningful test quality beyond line coverage. Raise the threshold as your test suite matures.

Schema Validation CI Step​

The Transformation tier introduces JSON schemas for AEEF artifacts. CI validates:

  • metrics/*.json against schemas/kpi-record.schema.json
  • provenance/*.json against schemas/provenance-log.schema.json
  • ai/contracts/*.json against schemas/agent-contract.schema.json

This prevents data quality drift in the metrics pipeline and agent SDLC configuration.

Provenance Generator​

Every CI run produces a provenance record:

{
  "buildId": "ci-12345",
  "timestamp": "2025-01-15T10:30:00Z",
  "repository": "my-org/my-project",
  "branch": "feat/user-validation",
  "commit": "abc123def",
  "stages": {
    "lint": { "status": "pass", "duration": 12 },
    "typecheck": { "status": "pass", "duration": 8 },
    "test": { "status": "pass", "coverage": 87.3, "duration": 45 },
    "mutation": { "status": "pass", "score": 74.2, "duration": 120 },
    "sast": { "status": "pass", "findings": 0, "duration": 15 },
    "sca": { "status": "pass", "vulnerabilities": 0, "duration": 5 },
    "schema": { "status": "pass", "duration": 2 }
  },
  "aiContribution": {
    "disclosed": true,
    "tools": ["cursor", "copilot"]
  }
}

Next Steps​

Last updated on by BalrogEg