oxmutate 0.0.0-stage → 1.0.0

package/dist/files.js

@@ -0,0 +1,62 @@
+/**
+ * The files to mutate, from Stryker-style globs (`src/**\/*.ts`, `!src/**\/*.test.ts`, `{a,b}`).
+ * No dependency: a glob is translated to one regular expression, and the walk skips the
+ * directories a project never mutates.
+ */
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.turbo', '.oxmutate', '.stryker-tmp', 'reports']);
+const escapeRegExp = (s) => s.replace(/[.+^$()|[\]\\]/g, '\\$&');
+/** Translate one glob (without a leading `!`) into an anchored regular expression. */
+export function globToRegExp(glob) {
+    let re = '';
+    // Stryker disable next-line EqualityOperator: one step past the end reads charAt(length), an empty string, which appends nothing
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob.charAt(i);
+        if (c === '*') {
+            if (glob[i + 1] === '*') {
+                // `**/` matches zero or more directories; a bare `**` matches anything.
+                if (glob[i + 2] === '/') {
+                    re += '(?:.*/)?';
+                    i += 2;
+                }
+                else {
+                    re += '.*';
+                    i += 1;
+                }
+            }
+            else
+                re += '[^/]*';
+        }
+        else if (c === '?')
+            re += '[^/]';
+        else if (c === '{') {
+            const close = glob.indexOf('}', i);
+            re += `(?:${glob.slice(i + 1, close).split(',').map(escapeRegExp).join('|')})`;
+            i = close;
+        }
+        else
+            re += escapeRegExp(c);
+    }
+    return new RegExp(`^${re}$`);
+}
+/** Repository-relative paths (forward slashes) of files matching the include and exclude globs. */
+export function matchFiles(root, patterns) {
+    const include = patterns.filter((p) => !p.startsWith('!')).map(globToRegExp);
+    const exclude = patterns.filter((p) => p.startsWith('!')).map((p) => globToRegExp(p.slice(1)));
+    const out = [];
+    const walk = (dir) => {
+        for (const e of readdirSync(path.join(root, dir), { withFileTypes: true })) {
+            const rel = dir ? `${dir}/${e.name}` : e.name;
+            if (e.isDirectory()) {
+                if (!SKIP.has(e.name))
+                    walk(rel);
+            }
+            else if (include.some((r) => r.test(rel)) && !exclude.some((r) => r.test(rel)))
+                out.push(rel);
+        }
+    };
+    walk('');
+    return out.sort();
+}
+//# sourceMappingURL=files.js.map

package/dist/frozen.d.ts

@@ -0,0 +1,19 @@
+import { type RunResult } from './coordinator.js';
+export interface FrozenOracle {
+    base: string;
+    /** Test files the change edited or added, repository-relative. */
+    changedTests: string[];
+    /** Mutation score with the base ref's tests, and with the change's. */
+    baseScore: number;
+    headScore: number;
+    delta: number;
+    /** Detected by the base tests, undetected by the change's: the tests got weaker here. */
+    weakened: {
+        id: string;
+        file: string;
+        line: number;
+        mutatorName: string;
+        replacement: string;
+    }[];
+}
+export declare function frozenOracle(head: RunResult, base: string): Promise<FrozenOracle>;

package/dist/frozen.js

@@ -0,0 +1,47 @@
+/**
+ * The frozen oracle (spec R14): a change that edits tests is also scored against the base ref's
+ * tests. The code under test is the same in both runs, so the mutants and their ids are the same;
+ * only the test files differ. A mutant the base tests detect and the changed tests do not is a test
+ * the change weakened, which is how a patch that "makes the check pass" by editing the check shows
+ * up (the reward-hacking concern in the intent, written as a CI result).
+ *
+ * The base tests are served to Vitest from memory, the way instrumented sources are: nothing in
+ * the working tree is touched.
+ */
+import path from 'node:path';
+import { ambientRuntime, run as spawn } from 'bellpull';
+import { run } from './coordinator.js';
+const detected = (m) => m?.status === 'Killed' || m?.status === 'Timeout';
+const undetected = (m) => m?.status === 'Survived' || m?.status === 'NoCoverage';
+/**
+ * A test file the change added has no base version. It is served as one skipped test, so the base
+ * run has the file (Vitest finds it on disk) and none of its tests.
+ */
+const ABSENT_AT_BASE = "import { it } from 'vitest';\nit.skip('absent at the base ref (oxmutate frozen oracle)', () => {});\n";
+async function git(root, args) {
+    const r = await spawn('git', args, { cwd: root, runtime: ambientRuntime() });
+    return { ok: r.ok, out: r.stdout };
+}
+export async function frozenOracle(head, base) {
+    const root = head.root;
+    const top = (await git(root, ['rev-parse', '--show-toplevel'])).out.trim() || root;
+    const diff = await git(root, ['diff', '--name-only', base, '--']);
+    if (!diff.ok)
+        throw new Error(`git diff ${base} failed. fix: pass a ref this checkout has (fetch it first in CI)`);
+    const changed = new Set(diff.out.split('\n').filter(Boolean).map((f) => path.join(top, f)));
+    const testFiles = [...new Set(head.tests.map((t) => t.file))].filter((f) => changed.has(f));
+    const result = { base, changedTests: testFiles.map((f) => path.relative(root, f)), baseScore: head.score.mutationScore, headScore: head.score.mutationScore, delta: 0, weakened: [] };
+    if (testFiles.length === 0)
+        return result;
+    const shown = await Promise.all(testFiles.map((f) => git(root, ['show', `${base}:${path.relative(top, f).split(path.sep).join('/')}`])));
+    const testOverrides = Object.fromEntries(testFiles.map((f, i) => [f, shown[i]?.ok ? shown[i].out : ABSENT_AT_BASE]));
+    const frozen = await run({ ...head.options, testOverrides, incremental: false });
+    const byId = new Map(frozen.mutants.map((m) => [m.id, m]));
+    result.baseScore = frozen.score.mutationScore;
+    result.delta = head.score.mutationScore - frozen.score.mutationScore;
+    result.weakened = head.mutants
+        .filter((m) => undetected(m) && detected(byId.get(m.id)))
+        .map((m) => ({ id: m.id, file: m.file, line: m.start.line, mutatorName: m.mutatorName, replacement: m.replacement }));
+    return result;
+}
+//# sourceMappingURL=frozen.js.map

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * oxmutate's programmatic API. The CLI (`oxmutate run`) is this, declared on burgee.
+ */
+export { loadOptions, type MutateConfig, type Options, type Thresholds } from './config.js';
+export { InstrumentFault, run, type MutantResult, type RunResult, type RunStats, type Status } from './coordinator.js';
+export { changedLines, parseShard, shardOf } from './lanes.js';
+export { native } from './native.js';
+export { sarifReport, strykerReport, textSummary, VERSION } from './reports.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * oxmutate's programmatic API. The CLI (`oxmutate run`) is this, declared on burgee.
+ */
+export { loadOptions } from './config.js';
+export { InstrumentFault, run } from './coordinator.js';
+export { changedLines, parseShard, shardOf } from './lanes.js';
+export { native } from './native.js';
+export { sarifReport, strykerReport, textSummary, VERSION } from './reports.js';
+//# sourceMappingURL=index.js.map

package/dist/lanes.d.ts

@@ -0,0 +1,38 @@
+export type LineRanges = Map<string, [number, number][]>;
+/** Added or changed line ranges per repository-relative path, new side. */
+export declare function changedLines(root: string, base: string): Promise<LineRanges>;
+export declare function parseDiff(diff: string): LineRanges;
+export declare function touches(ranges: LineRanges, file: string, startLine: number, endLine: number): boolean;
+/** FNV-1a 32 over the stable id: the shard a mutant belongs to. */
+export declare function shardOf(id: string, count: number): number;
+export declare function parseShard(value: string): {
+    index: number;
+    count: number;
+};
+/** A Stryker `mutate` range: lines 1-based, columns 0-based and inclusive (`src/a.ts:5:4-6:4`). */
+export interface MutateRange {
+    start: {
+        line: number;
+        column: number;
+    };
+    end: {
+        line: number;
+        column: number;
+    };
+}
+/** A `mutate` entry split into its glob and, when it names one, its range. */
+export declare function parseMutateSpec(spec: string): {
+    glob: string;
+    range?: MutateRange;
+};
+/**
+ * Is the mutant wholly inside the range, as Stryker decides it (`locationIncluded`)? The mutant's
+ * columns are the report's, 1-based with the end exclusive; the range's are Stryker's, 0-based.
+ */
+export declare function withinRange(range: MutateRange, start: {
+    line: number;
+    column: number;
+}, end: {
+    line: number;
+    column: number;
+}): boolean;

package/dist/lanes.js

@@ -0,0 +1,92 @@
+/**
+ * The CI lanes' selection rules: which mutants a run owns.
+ *
+ * - `since <ref>` (the PR lane): mutants on lines the change added or modified, from
+ *   `git diff -U0 <ref>`, working tree included, so a local run and CI select the same set.
+ * - `shard i/n` (a CI matrix): a mutant belongs to shard `fnv(id) mod n`, so a shard's share
+ *   does not move when unrelated code changes, and the shards partition the run exactly.
+ */
+import { ambientRuntime, run } from 'bellpull';
+const NEW_FILE = '+++ ';
+/** FNV-1a 32-bit parameters. */
+const FNV_OFFSET = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+/** Added or changed line ranges per repository-relative path, new side. */
+export async function changedLines(root, base) {
+    const diff = await run('git', ['diff', '-U0', '--no-color', '--no-ext-diff', base, '--'], { cwd: root, runtime: ambientRuntime() });
+    if (!diff.ok)
+        throw new Error(`git diff ${base} failed: ${diff.stderr.trim()}. fix: pass a ref this checkout has (fetch it first in CI)`);
+    return parseDiff(diff.stdout);
+}
+export function parseDiff(diff) {
+    const out = new Map();
+    let file;
+    for (const line of diff.split('\n')) {
+        if (line.startsWith(NEW_FILE)) {
+            const p = line.slice(NEW_FILE.length).trim();
+            file = p === '/dev/null' ? undefined : p.replace(/^b\//, '');
+            continue;
+        }
+        const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
+        if (!hunk || !file)
+            continue;
+        const start = Number(hunk[1]);
+        const count = hunk[2] === undefined ? 1 : Number(hunk[2]);
+        if (count === 0)
+            continue; // a pure deletion adds no line to mutate
+        // Stryker disable next-line OptionalChaining: the get after a set always finds the list; `?.` is only for the type
+        (out.get(file) ?? out.set(file, []).get(file))?.push([start, start + count - 1]);
+    }
+    return out;
+}
+export function touches(ranges, file, startLine, endLine) {
+    // Stryker disable next-line ArrayDeclaration: a string element destructures to letters, and a number compared with a letter is false, as with no ranges
+    return (ranges.get(file) ?? []).some(([a, b]) => startLine <= b && endLine >= a);
+}
+/** FNV-1a 32 over the stable id: the shard a mutant belongs to. */
+export function shardOf(id, count) {
+    let h = FNV_OFFSET;
+    // Ids are hex (`native/src/stable_id.rs`), so a code point is a code unit and the shards are
+    // the ones `charCodeAt` gave.
+    for (let i = 0; i < id.length; i++) {
+        h ^= id.codePointAt(i) ?? 0;
+        h = Math.imul(h, FNV_PRIME) >>> 0;
+    }
+    return h % count;
+}
+export function parseShard(value) {
+    const m = /^(\d+)\/(\d+)$/.exec(value);
+    const index = Number(m?.[1]);
+    const count = Number(m?.[2]);
+    // `count < 1` needs no check of its own: with 1 <= index <= count it cannot hold.
+    if (!m || index < 1 || index > count)
+        throw new Error(`--shard must be i/n with 1 <= i <= n, got "${value}"`);
+    return { index: index - 1, count };
+}
+/**
+ * The range end of Stryker's pattern (`mutate-pattern-constants.js`): `<glob>:<line>[:<col>]-<line>[:<col>]`.
+ * Only the suffix is matched; the glob is what comes before it. Stryker's lazy `^(.*?):` glob group
+ * backtracks polynomially (CodeQL js/polynomial-redos), and the leftmost match is the same split.
+ */
+const RANGE = /:(\d+)(?::(\d+))?-(\d+)(?::(\d+))?$/;
+/** A `mutate` entry split into its glob and, when it names one, its range. */
+export function parseMutateSpec(spec) {
+    const m = RANGE.exec(spec);
+    if (!m)
+        return { glob: spec };
+    // Stryker disable next-line StringLiteral: Number('') is 0 as Number('0') is
+    const [, startLine, startColumn = '0', endLine, endColumn = String(Number.MAX_SAFE_INTEGER)] = m;
+    return { glob: spec.slice(0, m.index), range: { start: { line: Number(startLine), column: Number(startColumn) }, end: { line: Number(endLine), column: Number(endColumn) } } };
+}
+/**
+ * Is the mutant wholly inside the range, as Stryker decides it (`locationIncluded`)? The mutant's
+ * columns are the report's, 1-based with the end exclusive; the range's are Stryker's, 0-based.
+ */
+export function withinRange(range, start, end) {
+    const from = start.column - 1;
+    const to = end.column - 1;
+    const startIn = range.start.line < start.line || (range.start.line === start.line && range.start.column <= from);
+    const endIn = range.end.line > end.line || (range.end.line === end.line && range.end.column >= to);
+    return startIn && endIn;
+}
+//# sourceMappingURL=lanes.js.map

package/dist/native.d.ts

@@ -0,0 +1,36 @@
+export interface Location {
+    line: number;
+    column: number;
+}
+export interface NativeMutant {
+    id: string;
+    mutatorName: string;
+    replacement: string;
+    start: Location;
+    end: Location;
+    /** Set when an ignore rule covers the mutant: reported as Ignored, never placed in the code. */
+    ignoredReason?: string;
+}
+export interface InstrumentedFile {
+    path: string;
+    code?: string;
+    mutants: NativeMutant[];
+    error?: string;
+}
+/** A call whose subtree is not mutated (Stryker's ignorers, as data): `console.*`, `**.debug`. */
+export interface IgnoreRule {
+    call: string;
+    reason?: string | undefined;
+}
+interface Binding {
+    instrumentFiles(files: {
+        path: string;
+        source: string;
+    }[], options?: {
+        strykerCompat?: boolean;
+        ignore?: IgnoreRule[];
+    }): InstrumentedFile[];
+    nativeVersion(): string;
+}
+export declare function native(): Binding;
+export {};

package/dist/native.js

@@ -0,0 +1,40 @@
+/**
+ * The native core (`native/`, Rust on oxc), loaded for this platform. It ships as one prebuilt
+ * `.node` per platform (PRINCIPLES rule 9, `native-engine`): 0.1 bundles all six in the tarball as
+ * `binding/oxmutate.<tag>.node` (`platform.ts` names the tag); development builds
+ * `binding/oxmutate.<platform>-<arch>.node`; the `oxmutate-<tag>` platform package comes last.
+ */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { bindingNames, platformPackage } from './platform.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const target = `${process.platform}-${process.arch}`;
+/** This machine, as `platform.ts` reads it: glibc's runtime version from `process.report` (absent on musl). */
+function machine() {
+    const glibc = process.platform === 'linux' ? process.report?.getReport()?.header?.glibcVersionRuntime : undefined;
+    return { platform: process.platform, arch: process.arch, glibc };
+}
+let binding;
+export function native() {
+    if (binding)
+        return binding;
+    const self = machine();
+    // `binding/` beside `dist/` (published) or `src/` (development), then one level up.
+    const candidates = [path.join(here, '..', 'binding'), path.join(here, '..', '..', 'binding')].flatMap((dir) => bindingNames(self).map((name) => path.join(dir, name)));
+    try {
+        // `process.dlopen` loads a native addon straight from its path, the way `require` does it
+        // underneath. Since 0.1 the six release cores ship inside the tarball as
+        // `binding/oxmutate.<tag>.node`; the platform package (its `main`, `oxmutate.node`) is last,
+        // for when those publish.
+        const file = candidates.find((c) => existsSync(c)) ?? fileURLToPath(import.meta.resolve(platformPackage(self)));
+        const addon = { exports: {} };
+        process.dlopen(addon, file);
+        binding = addon.exports;
+    }
+    catch (error) {
+        throw new Error(`oxmutate: no native core for ${target}. fix: install the platform package (npm i ${platformPackage(machine())}) or build it (npm run build:native in packages/oxmutate)`, { cause: error });
+    }
+    return binding;
+}
+//# sourceMappingURL=native.js.map

package/dist/platform.js

@@ -0,0 +1,27 @@
+/**
+ * Which native core a machine needs, as napi-rs names it: `<platform>-<arch>[-gnu|-musl|-msvc]`.
+ * The tag names the bundled core (`binding/oxmutate.<tag>.node`), the platform package
+ * (`oxmutate-<tag>`, `npm/<tag>`) and the release matrix leg, so all three agree by construction.
+ * Pure: the machine is passed in, so every branch is testable on any one machine.
+ */
+/** `darwin-arm64`, `linux-x64-gnu`, `linux-x64-musl`, `win32-x64-msvc`, … */
+export function platformTag({ platform, arch, glibc }) {
+    if (platform === 'win32')
+        return `win32-${arch}-msvc`;
+    if (platform === 'linux')
+        return `linux-${arch}-${glibc ? 'gnu' : 'musl'}`;
+    return `${platform}-${arch}`;
+}
+/** The npm package that carries the tag's core once the platform packages publish. */
+export function platformPackage(machine) {
+    return `oxmutate-${platformTag(machine)}`;
+}
+/**
+ * The files to try, in order, under each `binding/` directory: the bundled release core for this
+ * tag, then the development build `scripts/copy-binding.mjs` writes (`<platform>-<arch>`, which is
+ * the same name on macOS).
+ */
+export function bindingNames(machine) {
+    return [...new Set([`oxmutate.${platformTag(machine)}.node`, `oxmutate.${machine.platform}-${machine.arch}.node`])];
+}
+//# sourceMappingURL=platform.js.map

package/dist/progress.js

@@ -0,0 +1,40 @@
+/**
+ * Stryker's `progress` reporters, one implementation: the phase, its own count and the time so
+ * far, on stderr. On a terminal the line rewrites itself every second (`progress`); anywhere else,
+ * or with `progress-append-only` (Stryker's `ci` alias), a new line every few seconds, so a CI log
+ * shows the run moving without a carriage-return mess. Off unless a progress reporter is named.
+ */
+const REPORTERS = new Set(['progress', 'progress-append-only', 'ci', 'dots']);
+const TTY_EVERY_MS = 1000;
+const APPEND_EVERY_MS = 10_000;
+const MS_PER_S = 1000;
+export function startProgress(reporters, out, now = () => performance.now()) {
+    const enabled = reporters.some((r) => REPORTERS.has(r));
+    const rewrite = Boolean(out.isTTY) && reporters.includes('progress');
+    const start = now();
+    // Stryker disable next-line StringLiteral: line() runs only after phase() has set the name, so the initial value is never printed
+    let name = '';
+    let detail;
+    let timer;
+    const line = () => `oxmutate: ${name}${detail ? `, ${detail()}` : ''}, ${((now() - start) / MS_PER_S).toFixed(0)} s`;
+    const tick = () => {
+        out.write(rewrite ? `\r\u001B[2K${line()}` : `${line()}\n`);
+    };
+    return {
+        phase(next, nextDetail) {
+            if (!enabled)
+                return;
+            name = next;
+            detail = nextDetail;
+            tick();
+            timer ??= setInterval(tick, rewrite ? TTY_EVERY_MS : APPEND_EVERY_MS);
+            timer.unref();
+        },
+        stop() {
+            clearInterval(timer);
+            if (enabled && rewrite)
+                out.write('\n');
+        },
+    };
+}
+//# sourceMappingURL=progress.js.map

package/dist/reports.d.ts

@@ -0,0 +1,20 @@
+import type { MutantResult, RunResult } from './coordinator.js';
+/** The package's own version, read from its manifest so `--version` and the reports never drift from it. */
+export declare const VERSION: string;
+/** `mutation-testing-report-schema` 2, the format Stryker writes (`jsonReporter`). */
+export declare function strykerReport(r: RunResult): object;
+/** SARIF 2.1.0: one result per surviving or uncovered mutant, fingerprinted by stable id. */
+export declare function sarifReport(r: RunResult): object;
+export declare function describe(m: MutantResult): string;
+/** The terminal summary: the score, what to look at first, what the run corrected. */
+export declare function textSummary(r: RunResult, opts?: {
+    survivors?: number;
+}): string;
+/**
+ * Stryker's HTML report: the JSON report rendered by `mutation-testing-elements`. The component is
+ * inlined from the project's own install when it has one (Stryker brings it), so the page works
+ * offline as Stryker's does; otherwise the page loads that exact version from a CDN. oxmutate does
+ * not depend on it.
+ */
+export declare function htmlReport(r: RunResult): string;
+export declare function writeReports(r: RunResult): string[];