Pre-commit Tool

This Pre commit tool to identify rule violation (impact based) in development cycle

Mutation Testing

The mutation module uses Stryker Mutator to run mutation testing on files that changed relative to a release branch. It automatically:

1. Detects changed source & test files via git diff
2. Resolves source ↔ test file pairs (co-located, __tests__/, or mirrored directories)
3. Runs Stryker on matched files
4. Generates a mutation summary report (JSON) and a SonarQube-compatible external issues report

Dependencies

The following packages are required (already listed in package.json):

| Package | Version | Purpose | |---|---|---| | @stryker-mutator/core | 5.0.0 | Stryker mutation testing engine | | @stryker-mutator/jest-runner | 5.0.0 | Runs Jest tests for each mutant | | jest | 29.7.0 | Test runner (must already be present) | | glob | ^8.1.0 | File pattern matching for test resolution |

Install all dependencies:

npm install

Or install mutation-specific packages manually:

npm install @stryker-mutator/core@5 @stryker-mutator/jest-runner@5 glob@8

How to Run

Via npx (recommended)

# Local / pre-commit mode — uses staged files + diff vs release branch
npx ZDLintFramework mutate --mode=local --release=<branch>

# CI mode — uses diff vs release branch only
npx ZDLintFramework mutate --mode=ci --release=<branch>

Via npm scripts

# Local mode
npm run mutate:local -- --release=release

# CI mode
npm run mutate:ci -- --release=release

Directly via node

node bin/cliCI.js mutate --mode=local --release=release
node bin/cliCI.js mutate --mode=ci --release=release

CLI Flags

| Flag | Required | Default | Description | |---|---|---|---| | --mode=local\|ci | Yes | — | local = staged + branch diff; ci = branch diff only | | --release=<branch> | Yes | — | Release/target branch to diff against (e.g. release, main) | | --outputDir=<dir> | No | reports/mutation | Directory for output reports | | --outputFileName=<name> | No | mutation-report.json | Name of the mutation summary file | | --logLevel=<level> | No | info | Stryker log level (off, fatal, error, warn, info, debug, trace) |

Output

Two report files are generated in the output directory (default reports/mutation/):

1. mutation-report.json — Full mutation summary including mutation score, per-file breakdown, and mutant details.
2. sonar-mutation-report.json — SonarQube generic issue import format. Survived and no-coverage mutants appear as issues.

Example summary output

{
  "summary": {
    "totalMutants": 42,
    "killed": 35,
    "survived": 5,
    "timeout": 2,
    "noCoverage": 0,
    "ignored": 0,
    "runtimeErrors": 0,
    "compileErrors": 0,
    "mutationScore": 88.10
  }
}

How It Works

| Mode | Step 1: File Collection | Step 2 | Step 3 | Step 4 | |---|---|---|---|---| | local | git diff --staged + git diff <release> | Resolve source↔test pairs | Run Stryker on matched files | Write JSON reports | | ci | git diff <release> | Resolve source↔test pairs | Run Stryker on matched files | Write JSON reports |

Programmatic API

const { MutationRunner, MutationCli, StrykerWrapper } = require('./src/mutation');

// Option 1: Use MutationCli (parses CLI args)
const cli = new MutationCli();
cli.execute(['mutate', '--mode=local', '--release=release']).then(result => {
  console.log(result);
});

// Option 2: Use MutationRunner directly
const runner = new MutationRunner({
  outputDir: 'reports/mutation',
  logLevel: 'info'
});
runner.runLocal('release').then(result => {
  console.log('Score:', result.report.summary.mutationScore);
});

// Option 3: Use StrykerWrapper for full control
const stryker = new StrykerWrapper({ concurrency: 4 });
stryker.run(['src/utils/hash.js'], {
  testFiles: ['src/utils/__tests__/hash.test.js']
}).then(result => {
  console.log(result.summary);
});

Default Mutate Pattern

When no specific source files are provided, Stryker uses the default pattern from mutatePattern.json:

src/**/*.js

File Resolution Strategies

The FileResolver automatically finds test files for source files using these strategies (in order):

1. Co-located: src/foo.js → src/foo.test.js
2. __tests__ subdir: src/foo.js → src/__tests__/foo.test.js
3. Mirror structure: src/x/foo.js → test/x/foo.test.js

Supported test suffixes: .test.js, .test.ts, .test.jsx, .test.tsx

SonarQube Integration

Add the sonar report path to your sonar-project.properties:

sonar.externalIssuesReportPaths=reports/mutation/sonar-mutation-report.json

Troubleshooting

| Issue | Fix | |---|---| | Failed to load @stryker-mutator/core | Run npm install @stryker-mutator/core@5 @stryker-mutator/jest-runner@5 | | Branch 'X' not found | Run git fetch origin <branch> first | | No files to mutate | Ensure changed files have matching test files | | Low mutation score | Add tests that assert specific behavior, not just "no error" |