oxmutate 2.2.0 → 2.4.0

package/dist/child.js

@@ -75,6 +75,10 @@ async function runIsolated(unit) {
 }
 async function runUnit(unit) {
     env['OXMUTATE_MODE'] = unit.mode;
+    if (unit.trackReads)
+        env['__OXMUTATE_TRACK_READS__'] = '1';
+    else
+        delete env['__OXMUTATE_TRACK_READS__'];
     env['OXMUTATE_RESULTS'] = unit.results;
     env['OXMUTATE_PROGRESS'] = unit.progress;
     if (unit.plan)

package/dist/cli.js

@@ -62,6 +62,10 @@ function overridesFrom(o, root) {
         overrides.ignoreStatic = true;
     if (typeof o['staticGroup'] === 'number')
         overrides.staticGroup = Math.max(1, Math.floor(o['staticGroup']));
+    if (typeof o['staticBudget'] === 'number' && o['staticBudget'] >= 1)
+        overrides.staticBudgetMs = Math.floor(o['staticBudget']);
+    if (o['reportStaticReaders'] === true)
+        overrides.staticReaders = 'report';
     if (o['incremental'] === true)
         overrides.incremental = true;
     if (typeof o['flakyReruns'] === 'number')
@@ -93,6 +97,8 @@ const runCommand = defineCommand({
         strykerCompat: { type: 'boolean', description: 'reproduce Stryker 10.0.0 skips (no mutants inside `as` casts or enums)' },
         ignoreStatic: { type: 'boolean', description: 'skip static mutants (module-level code): faster, and the score leaves them out' },
         staticGroup: { type: 'number', description: 'arm this many static mutants together in a file that is not their first (default 1; a heuristic, audited)' },
+        staticBudget: { type: 'number', description: 'the most the static phase may take, ms; static mutants still undecided then are left out of the score' },
+        reportStaticReaders: { type: 'boolean', description: 'one more dry run that reports how many tests static mutants would need if each ran only where its value is read; changes no verdict' },
         incremental: { type: 'boolean', description: 'reuse verdicts whose source and covering tests did not change' },
         flakyReruns: { type: 'number', description: 're-runs for verdicts with nondeterministic tests (default 2; 0 disables)' },
         reporter: { type: 'string', description: 'comma-separated: clear-text, json, sarif, html (default clear-text,json)' },

package/dist/config.d.ts

@@ -6,6 +6,8 @@ export interface Thresholds {
     /** Fail the run (exit 1) below this score. `null`: never fail on score. */
     break: number | null;
 }
+/** Why a static mutant is Ignored when `static.budgetMs` ran out before it was decided; the summary counts them by it. */
+export declare const STATIC_BUDGET_REASON = "static mutant (static budget spent)";
 /** Why a static mutant is Ignored under `ignoreStatic`; the summary counts them by it. */
 export declare const IGNORE_STATIC_REASON = "static mutant (ignoreStatic)";
 export interface Options {
@@ -25,6 +27,18 @@ export interface Options {
      * heuristic: two mutants can hide each other, so one in twenty group survivors is run again alone.
      */
     staticGroup: number;
+    /**
+     * The most the static phase may take, in milliseconds (`static.budgetMs`). No new static unit
+     * starts once it is spent; a static mutant still undecided then is Ignored, with a reason, and
+     * left out of the score. A kill found before that stands. Unset: no limit.
+     */
+    staticBudgetMs?: number | undefined;
+    /**
+     * `static.readers: 'report'`: one more dry run, with every module-level literal reporting which
+     * tests read each of its properties, and a summary line of how many tests the static phase would
+     * run if each static mutant ran only where its value is read (roadmap 2.4). Changes no verdict.
+     */
+    staticReaders: 'off' | 'report';
     strykerCompat: boolean;
     reporters: string[];
     jsonReport: string;

package/dist/config.js

@@ -7,6 +7,11 @@ function staticGroupOf(group) {
     const asked = Math.floor(Number(group));
     return asked >= 2 ? asked : 1;
 }
+function staticBudgetOf(ms) {
+    const asked = Math.floor(Number(ms));
+    return asked >= 1 ? asked : undefined;
+}
+export const STATIC_BUDGET_REASON = 'static mutant (static budget spent)';
 export const IGNORE_STATIC_REASON = 'static mutant (ignoreStatic)';
 const NOT_NEEDED = {
     inPlace: 'oxmutate never copies or rewrites the project; instrumented sources are served from memory',
@@ -105,6 +110,8 @@ export async function loadOptions(root, overrides = {}, configFile) {
         excludedMutations: mutator.excludedMutations ?? [],
         ignoreStatic: raw['ignoreStatic'] === true,
         staticGroup: staticGroupOf(raw['static']?.group),
+        staticBudgetMs: staticBudgetOf(raw['static']?.budgetMs),
+        staticReaders: raw['static']?.readers === 'report' ? 'report' : 'off',
         strykerCompat: raw['strykerCompat'] === true,
         reporters: raw['reporters'] ?? ['clear-text', 'json'],
         jsonReport: path.resolve(root, json.fileName ?? 'reports/mutation/mutation.json'),

package/dist/coordinator.d.ts

@@ -76,6 +76,18 @@ export interface RunStats {
     pollutionRestarts: number;
     /** Units after which the project on disk had changed (diskguard.ts): put back, and their verdicts and those of the units running beside them re-run. */
     diskWrites: number;
+    /**
+     * `static.readers: 'report'` (roadmap 2.4): over the static mutants, the tests of every file that
+     * loads each one's module (what the static phase runs), and the tests of only the files that read
+     * its value. A mutant whose value is untracked, or read while a module loaded, counts its loaders.
+     */
+    staticReaders?: {
+        mutants: number;
+        loaderTests: number;
+        readerTests: number;
+        fellBack: number;
+        dryRunMs: number;
+    } | undefined;
     /** The first few paths those writes touched, so a suite's own scratch in a tracked folder can be told from a mutant's write. */
     diskWritePaths: string[];
     /** Survivors of the warm run that a whole-file re-run killed (cross-test effects). */

package/dist/coordinator.js

@@ -5,7 +5,7 @@ import path from 'node:path';
 import { ambientRuntime, run as spawn } from 'bellpull';
 import { checkSurvivors } from './checker.js';
 import { runCommandMutants } from './command-runner.js';
-import { IGNORE_STATIC_REASON, disables } from './config.js';
+import { IGNORE_STATIC_REASON, STATIC_BUDGET_REASON, disables } from './config.js';
 import { rangeDisables } from './directives.js';
 import { guardDisk, isClean } from './diskguard.js';
 import { globToRegExp, matchFiles } from './files.js';
@@ -43,6 +43,7 @@ const verdictOptions = (o) => ({
     excludedMutations: [...o.excludedMutations].sort(),
     ignoreStatic: o.ignoreStatic,
     staticGroup: o.staticGroup,
+    staticBudgetMs: o.staticBudgetMs,
     strykerCompat: o.strykerCompat,
     testOverrides: o.testOverrides,
     vitestConfig: o.vitestConfig && existsSync(o.vitestConfig) ? sha(readFileSync(o.vitestConfig, 'utf8')) : null,
@@ -120,6 +121,7 @@ export async function run(options) {
             throw new InstrumentFault(`cannot parse ${String(parseErrors.length)} file(s): ${parseErrors.slice(0, 3).join('; ')}`);
         const changed = options.since ? await changedLines(root, options.since) : undefined;
         const mutants = [];
+        const trackedIds = new Set();
         const codeMap = {};
         const directiveErrors = [];
         for (const f of instrumented) {
@@ -138,8 +140,11 @@ export async function run(options) {
                 const off = offs.find((d) => d.line === m.start.line && (d.mutators === 'all' || d.mutators.includes(m.mutatorName)));
                 const inRange = ranged.reasonFor(m.start.line, m.mutatorName);
                 const excluded = options.excludedMutations.includes(m.mutatorName);
+                if (m.tracked)
+                    trackedIds.add(m.id);
+                const { tracked: _tracked, ...plain } = m;
                 mutants.push({
-                    ...m,
+                    ...plain,
                     file: f.path,
                     coveredBy: [],
                     status: off || inRange !== undefined || excluded || m.ignoredReason ? 'Ignored' : 'NoCoverage',
@@ -183,8 +188,8 @@ export async function run(options) {
             env[SPEC_TRACES_ENV] = JSON.stringify(traceDirs);
         const dryPool = createPool({ root, vitestConfig: options.vitestConfig, workers: options.concurrency, instrumentedMap: mapFile, nodeArgs: options.testRunnerNodeArgs }, 1, work, 'dry');
         pools.push(dryPool);
-        const dryRun = async () => {
-            const unit = { mode: 'dry', files: [], results: fileFor('dry', 'jsonl'), progress: fileFor('dry', 'progress') };
+        const dryRun = async (trackReads = false) => {
+            const unit = { mode: 'dry', files: [], results: fileFor('dry', 'jsonl'), progress: fileFor('dry', 'progress'), ...(trackReads && { trackReads: true }) };
             let failure;
             let overBudget = false;
             await dryPool.drain([unit], () => options.dryRunTimeoutMinutes * MS_PER_MINUTE, (_, o) => {
@@ -201,10 +206,13 @@ export async function run(options) {
                 throw new InstrumentFault(`the dry run did not complete: ${failure.stderr.slice(-1500)}`);
             const perTest = {};
             const stat = {};
+            const reads = { static: {}, perTest: {} };
             for (const r of recs) {
                 Object.assign(perTest, r.coverage?.perTest ?? {});
                 for (const [k, v] of Object.entries(r.coverage?.static ?? {}))
                     stat[k] = (stat[k] ?? 0) + v;
+                Object.assign(reads.perTest, r.reads?.perTest ?? {});
+                Object.assign(reads.static, r.reads?.static ?? {});
             }
             const fileErrors = recs.flatMap((r) => r.fileErrors ?? []);
             if (fileErrors.length) {
@@ -213,12 +221,17 @@ export async function run(options) {
             const unhandled = recs.reduce((n, r) => n + (r.unhandled ?? 0), 0);
             if (unhandled > 0)
                 throw new InstrumentFault(`the suite raised ${String(unhandled)} unhandled error(s) with no mutant active, so no verdict can be trusted. fix: make \`vitest run\` pass with no "Unhandled Errors" first`);
-            return { tests: recs.flatMap((r) => r.tests ?? []), perTest, static: stat, runOnce: recs.flatMap((r) => r.runOnce ?? []), modules: Object.assign({}, ...recs.map((r) => r.modules ?? {})) };
+            return { tests: recs.flatMap((r) => r.tests ?? []), perTest, static: stat, runOnce: recs.flatMap((r) => r.runOnce ?? []), modules: Object.assign({}, ...recs.map((r) => r.modules ?? {})), reads };
         };
         progress.phase('dry run');
         const d0 = performance.now();
         const dry = await dryRun();
         stats.dryRunMs = performance.now() - d0;
+        const r0 = performance.now();
+        if (options.staticReaders === 'report' && trackedIds.size > 0)
+            progress.phase('dry run with reads tracked (static.readers)');
+        const tracking = options.staticReaders === 'report' && trackedIds.size > 0 ? await dryRun(true) : undefined;
+        const readersDryRunMs = performance.now() - r0;
         const failing = dry.tests.filter((t) => t.state === 'fail');
         if (failing.length)
             throw new InstrumentFault(`${String(failing.length)} test(s) fail with no mutant active, so no verdict can be trusted: ${failing.slice(0, 5).map((t) => t.name).join('; ')}. fix: make the suite pass first`);
@@ -575,6 +588,36 @@ export async function run(options) {
             const covering = byCost([...new Set(tests)]);
             return [...covering, ...byAffinity(m.file, [...loaders].filter((f) => !covering.includes(f)))];
         };
+        const readersOf = (items) => {
+            const testsIn = new Map();
+            for (const t of dry.tests)
+                testsIn.set(t.file, (testsIn.get(t.file) ?? 0) + 1);
+            const sum = (files) => [...files].reduce((n, f) => n + (testsIn.get(f) ?? 0), 0);
+            const reads = tracking?.reads ?? { static: {}, perTest: {} };
+            const broken = tracking?.tests.some((t) => t.state === 'fail') ?? true;
+            const readerFiles = new Map();
+            for (const [key, ids] of Object.entries(reads.perTest)) {
+                const file = key.startsWith(FILE_KEY) ? key.slice(FILE_KEY.length) : testInfo.get(key)?.file;
+                if (!file)
+                    continue;
+                for (const id of Object.keys(ids))
+                    (readerFiles.get(id) ?? readerFiles.set(id, new Set()).get(id))?.add(file);
+            }
+            let loaderTests = 0;
+            let readerTests = 0;
+            let fellBack = 0;
+            for (const m of items) {
+                const loaders = filesFor(m);
+                loaderTests += sum(loaders);
+                if (broken || !trackedIds.has(m.id) || m.id in reads.static) {
+                    fellBack++;
+                    readerTests += sum(loaders);
+                }
+                else
+                    readerTests += sum(loaders.filter((f) => readerFiles.get(m.id)?.has(f)));
+            }
+            return { mutants: items.length, loaderTests, readerTests, fellBack };
+        };
         const testsRun = (id) => {
             const m = byId.get(id);
             const fs = m ? filesFor(m) : allTestFiles;
@@ -649,7 +692,11 @@ export async function run(options) {
                             back.add(id);
                 return [];
             };
+            const deadline = options.staticBudgetMs === undefined ? Infinity : performance.now() + options.staticBudgetMs;
+            const spent = () => performance.now() >= deadline;
             const keepUndecided = (unit) => {
+                if (spent())
+                    return false;
                 unit.staticIds = (unit.staticIds ?? []).filter((id) => !killed.has(id) && !back.has(id));
                 if (unit.staticGroups)
                     unit.staticGroups = unit.staticGroups.map((g) => g.filter((id) => !killed.has(id) && !back.has(id))).filter((g) => g.length > 0);
@@ -671,6 +718,10 @@ export async function run(options) {
                     m.status = 'Survived';
                     m.testsCompleted = ran.get(m.id) ?? 0;
                 }
+                else if (spent()) {
+                    m.status = 'Ignored';
+                    m.statusReason = STATIC_BUDGET_REASON;
+                }
                 else
                     undecided.push(m);
             }
@@ -718,6 +769,8 @@ export async function run(options) {
                     verdicts.set(m.id, { status: 'RuntimeError' });
             return verdicts;
         };
+        if (tracking)
+            stats.staticReaders = { ...readersOf(staticMutants), dryRunMs: readersDryRunMs };
         const s0 = performance.now();
         const staticBack = env['OXMUTATE_ISOLATE_STATIC'] ? staticMutants : await decideStaticLive(staticMutants);
         stats.staticMs = performance.now() - s0;

package/dist/native.d.ts

@@ -10,6 +10,8 @@ export interface NativeMutant {
     end: Location;
     /** Set when an ignore rule covers the mutant: reported as Ignored, never placed in the code. */
     ignoredReason?: string;
+    /** Reads of the property holding it are reported by a tracking dry run (`oxmTrack`, roadmap 2.4). */
+    tracked?: boolean;
 }
 export interface InstrumentedFile {
     path: string;

package/dist/reports.js

@@ -1,7 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { IGNORE_STATIC_REASON } from './config.js';
+import { IGNORE_STATIC_REASON, STATIC_BUDGET_REASON } from './config.js';
 export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 const REPLACEMENT_WIDTH = 60;
 const ELLIPSIS = '...';
@@ -128,6 +128,9 @@ function staticLine(r) {
     if (ignored > 0)
         return [`  static mutants: ${String(ignored)} ignored (ignoreStatic), not scored`];
     const share = r.stats.wallMs > 0 ? r.stats.staticMs / r.stats.wallMs : 0;
+    const unspent = statics.filter((m) => m.statusReason === STATIC_BUDGET_REASON).length;
+    if (unspent > 0)
+        return [`  static mutants: ${String(statics.length - unspent)} decided in ${(r.stats.staticMs / MS_PER_S).toFixed(1)} s, ${String(unspent)} left undecided when the static budget ran out, not scored`];
     const hint = share >= STATIC_SHARE_WORTH_SAYING ? '; --ignore-static skips them, and the score then leaves them out' : '';
     return [`  static mutants: ${String(statics.length)} decided in ${(r.stats.staticMs / MS_PER_S).toFixed(1)} s, ${(share * PERCENT).toFixed(0)}% of the run${hint}`];
 }
@@ -137,6 +140,11 @@ function whereItWent(r) {
     if (s.warmUnitMs > 0)
         lines.push(`  warm servers ran ${(s.warmUnitMs / MS_PER_S).toFixed(1)} s, ${(s.warmArmedMs / MS_PER_S).toFixed(1)} s of it inside test runs`);
     lines.push(...staticLine(r));
+    const sr = s.staticReaders;
+    if (sr && sr.mutants > 0) {
+        const ratio = sr.readerTests > 0 ? `, ${(sr.loaderTests / sr.readerTests).toFixed(1)}x fewer` : '';
+        lines.push(`  static readers: ${String(sr.mutants)} static mutants would run ${String(sr.readerTests)} tests where their value is read, against ${String(sr.loaderTests)} in every file that loads them${ratio}; ${String(sr.fellBack)} kept every loader (report only, ${(sr.dryRunMs / MS_PER_S).toFixed(1)} s)`);
+    }
     const c = s.isolatedByCause;
     const causes = [`static ${String(c.static)}`, `stopped ${String(c.stopped)}`, `unfinished ${String(c.unfinished)}`, `re-run ${String(c.rerun)}`, `survivors confirmed ${String(c.confirm)}`, `flaky ${String(c.flaky)}`];
     if (s.isolatedRuns > 0)

package/dist/runner.js

@@ -655,7 +655,7 @@ export default class OxmutateRunner extends Base {
                 if (result?.state === 'fail' && !f.tasks?.length)
                     fileErrors.push({ file: filepath, error: (result.errors?.[0]?.message ?? 'failed to collect').slice(0, FILE_ERROR_CHARS) });
             }
-            emit({ type: 'dry', tests, coverage: ns.mutantCoverage, fileErrors, runOnce: [...runOnce], modules: Object.fromEntries(dryModules), unhandled });
+            emit({ type: 'dry', tests, coverage: ns.mutantCoverage, reads: ns.readCoverage, fileErrors, runOnce: [...runOnce], modules: Object.fromEntries(dryModules), unhandled });
         }
         else if (mode === 'isolated') {
             const failed = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxmutate",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Mutation testing for JavaScript and TypeScript on the oxc engine, run warm inside the project's own Vitest, with CI lanes, SARIF and an agent surface. No dependency outside the burgee family. A Stryker migration path.",
   "license": "MIT",
   "author": "Ofri Peretz <ofriperetzdev@gmail.com>",