oxmutate 2.3.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

@@ -64,6 +64,8 @@ function overridesFrom(o, root) {
         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')
@@ -96,6 +98,7 @@ 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' },
+        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

@@ -33,6 +33,12 @@ 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.
+     */
+    staticReaders: 'off' | 'report';
     strykerCompat: boolean;
     reporters: string[];
     jsonReport: string;

package/dist/config.js

@@ -111,6 +111,7 @@ export async function loadOptions(root, overrides = {}, configFile) {
         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

@@ -121,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) {
@@ -139,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',
@@ -184,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) => {
@@ -202,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) {
@@ -214,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`);
@@ -576,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;
@@ -727,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

@@ -140,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.3.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>",