oxmutate 2.3.0 → 2.5.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

@@ -44,8 +44,20 @@ function summaryData(r, written) {
     return data;
 }
 const WEAKENED_SHOWN = 3;
-function overridesFrom(o, root) {
+function staticOverridesFrom(o) {
     const overrides = {};
+    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['staticReaders'] === true)
+        overrides.staticReaders = 'on';
+    return overrides;
+}
+function overridesFrom(o, root) {
+    const overrides = { ...staticOverridesFrom(o) };
     if (typeof o['since'] === 'string')
         overrides.since = o['since'];
     if (typeof o['frozenOracle'] === 'string')
@@ -60,10 +72,6 @@ function overridesFrom(o, root) {
         overrides.strykerCompat = true;
     if (o['ignoreStatic'] === true)
         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['incremental'] === true)
         overrides.incremental = true;
     if (typeof o['flakyReruns'] === 'number')
@@ -96,6 +104,8 @@ const runCommand = defineCommand({
         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' },
+        staticReaders: { type: 'boolean', description: 'run each static mutant only in the test files that read its value (a heuristic, audited)' },
+        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)' },
@@ -129,6 +139,10 @@ const runCommand = defineCommand({
             stderr.write(`oxmutate: the change weakened its tests: ${String(weakened.length)} mutant(s) the tests at ${result.frozen?.base ?? ''} detect now survive (${weakened.slice(0, WEAKENED_SHOWN).map((w) => `${w.file}:${String(w.line)} ${w.mutatorName}`).join('; ')}). fix: restore the assertions the change removed, or replace them with ones that kill these mutants\n`);
             data['exitCode'] = ExitCode.RUNTIME;
         }
+        if ((result.stats.staticReaders?.auditDisagreed ?? 0) > 0) {
+            stderr.write(`oxmutate: ${String(result.stats.staticReaders?.auditDisagreed ?? 0)} static mutant(s) that survived the files reading their value were killed in a file that loads it; they are reported Killed. fix: run without --static-readers; a test reads the value through a path the tracking does not see\n`);
+            data['exitCode'] = ExitCode.RUNTIME;
+        }
         if (result.stats.staticAuditDisagreed > 0) {
             stderr.write(`oxmutate: ${String(result.stats.staticAuditDisagreed)} mutant(s) reported as survivors by a group were killed when run alone; they are reported Killed. fix: run without static.group (--static-group 1); two of this file's mutants hide each other when armed together\n`);
             data['exitCode'] = ExitCode.RUNTIME;

package/dist/config.d.ts

@@ -33,6 +33,15 @@ export interface Options {
      * 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.
+     * `'on'`: the same dry run, and then each static mutant runs only in the files that read its
+     * value. A heuristic: one survivor in twenty is run again in every file that loads it, and one
+     * that fails there is reported Killed and fails the run.
+     */
+    staticReaders: 'off' | 'report' | 'on';
     strykerCompat: boolean;
     reporters: string[];
     jsonReport: string;

package/dist/config.js

@@ -12,6 +12,9 @@ function staticBudgetOf(ms) {
     return asked >= 1 ? asked : undefined;
 }
 export const STATIC_BUDGET_REASON = 'static mutant (static budget spent)';
+function staticReadersOf(readers) {
+    return readers === 'report' || readers === 'on' ? readers : 'off';
+}
 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',
@@ -111,6 +114,7 @@ export async function loadOptions(root, overrides = {}, configFile) {
         ignoreStatic: raw['ignoreStatic'] === true,
         staticGroup: staticGroupOf(raw['static']?.group),
         staticBudgetMs: staticBudgetOf(raw['static']?.budgetMs),
+        staticReaders: staticReadersOf(raw['static']?.readers),
         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,20 @@ 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;
+        auditSampled?: number;
+        auditDisagreed?: 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

@@ -49,6 +49,8 @@ const verdictOptions = (o) => ({
     vitestConfig: o.vitestConfig && existsSync(o.vitestConfig) ? sha(readFileSync(o.vitestConfig, 'utf8')) : null,
 });
 const UNIT_PAIRS = 400;
+const READERS_AUDIT_EVERY = 20;
+const auditedReader = (id) => env['OXMUTATE_STATIC_AUDIT'] === 'all' || [...id].reduce((sum, c) => sum + (c.codePointAt(0) ?? 0), 0) % READERS_AUDIT_EVERY === 0;
 const detected = (s) => s === 'Killed' || s === 'Timeout';
 const AUDIT_SHARE = 0.05;
 const DEADLOCK_REASON = 'its test deadlocked: nothing left in the worker could resume it (a hang, called in under a second)';
@@ -121,6 +123,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) {
@@ -139,8 +142,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',
@@ -184,8 +190,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) => {
@@ -202,10 +208,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) {
@@ -214,12 +223,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 !== 'off' && trackedIds.size > 0)
+            progress.phase('dry run with reads tracked (static.readers)');
+        const tracking = options.staticReaders !== 'off' && 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`);
@@ -576,6 +590,37 @@ export async function run(options) {
             const covering = byCost([...new Set(tests)]);
             return [...covering, ...byAffinity(m.file, [...loaders].filter((f) => !covering.includes(f)))];
         };
+        const readerFiles = new Map();
+        const trackingTests = tracking?.tests ?? [];
+        const readsTracked = tracking !== undefined && !trackingTests.some((t) => t.state === 'fail');
+        const trackedReads = tracking?.reads ?? { static: {}, perTest: {} };
+        for (const [key, ids] of Object.entries(trackedReads.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);
+        }
+        const readersFor = (m) => readsTracked && trackedIds.has(m.id) && !(m.id in trackedReads.static) ? filesFor(m).filter((f) => readerFiles.get(m.id)?.has(f)) : undefined;
+        const staticFilesFor = (m) => (options.staticReaders === 'on' ? readersFor(m) ?? filesFor(m) : filesFor(m));
+        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);
+            let loaderTests = 0;
+            let readerTests = 0;
+            let fellBack = 0;
+            for (const m of items) {
+                const loaders = filesFor(m);
+                const readers = readersFor(m);
+                loaderTests += sum(loaders);
+                if (!readers)
+                    fellBack++;
+                readerTests += sum(readers ?? loaders);
+            }
+            return { mutants: items.length, loaderTests, readerTests, fellBack };
+        };
         const testsRun = (id) => {
             const m = byId.get(id);
             const fs = m ? filesFor(m) : allTestFiles;
@@ -590,7 +635,7 @@ export async function run(options) {
             return Math.min(MAX_TEST_MS * testsRun(id), 1500 + options.timeoutMS + options.timeoutFactor * ms * 2);
         };
         const isolatedCapped = (id, slack) => Math.min(slack * isolatedBudget(id), MAX_TEST_MS * testsRun(id));
-        const decideStaticLive = async (items) => {
+        const decideStaticLive = async (items, filesOfMutant = staticFilesFor) => {
             if (items.length === 0)
                 return [];
             const STATIC_BATCH = 25;
@@ -661,7 +706,7 @@ export async function run(options) {
                 return unit.staticIds.length > 0;
             };
             const open = (m) => !killed.has(m.id) && !back.has(m.id);
-            const rounds = [(m) => filesFor(m).slice(0, 1), (m) => (open(m) ? filesFor(m).slice(1) : [])];
+            const rounds = [(m) => filesOfMutant(m).slice(0, 1), (m) => (open(m) ? filesOfMutant(m).slice(1) : [])];
             for (const [i, round] of rounds.entries())
                 await staticPool.drain(unitsFor(round, i > 0), (_, id) => isolatedCapped(id, 2), afterStatic, keepUndecided);
             const undecided = [];
@@ -672,7 +717,7 @@ export async function run(options) {
                     m.killedBy = [...new Set(k.killedBy)];
                     m.testsCompleted = ran.get(m.id) ?? 0;
                 }
-                else if (!back.has(m.id) && filesFor(m).every((f) => passed.get(m.id)?.has(f))) {
+                else if (!back.has(m.id) && filesOfMutant(m).every((f) => passed.get(m.id)?.has(f))) {
                     m.status = 'Survived';
                     m.testsCompleted = ran.get(m.id) ?? 0;
                 }
@@ -727,8 +772,21 @@ 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);
+        if (options.staticReaders === 'on' && stats.staticReaders) {
+            const sampled = staticMutants.filter((m) => m.status === 'Survived' && staticFilesFor(m).length < filesFor(m).length && auditedReader(m.id));
+            for (const m of sampled)
+                m.status = 'NoCoverage';
+            await decideStaticLive(sampled, filesFor);
+            stats.staticReaders.auditSampled = sampled.length;
+            stats.staticReaders.auditDisagreed = sampled.filter((m) => m.status === 'Killed' || m.status === 'Timeout').length;
+            for (const m of sampled)
+                if (m.status === 'NoCoverage')
+                    m.status = 'Survived';
+        }
         stats.staticMs = performance.now() - s0;
         stats.isolatedByCause.static = staticBack.length;
         isolatedQueue.push(...staticBack);

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

@@ -140,6 +140,13 @@ 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` : '';
+        const inUse = sr.auditSampled !== undefined;
+        const how = inUse ? `in use, ${String(sr.auditSampled)} survivor(s) audited in every loader, ${String(sr.auditDisagreed ?? 0)} disagreed` : 'report only';
+        lines.push(`  static readers: ${String(sr.mutants)} static mutants ${inUse ? 'ran' : '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 (${how}, ${(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.3.0",
+  "version": "2.5.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>",