oxmutate 0.0.0-stage → 1.0.0

package/dist/config.js

@@ -0,0 +1,172 @@
+/**
+ * Options, read from `stryker.config.*` as it stands (migration is a no-op: the file Stryker reads
+ * is the file oxmutate reads) and from `oxmutate.config.*`, which wins where both set a key.
+ * Every key Stryker documents that oxmutate does not use is reported, never silently dropped
+ * (spec R15).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { availableParallelism } from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {} from './native.js';
+import { resolveEsm } from './resolve.js';
+import {} from './spec-oracle.js';
+const NOT_NEEDED = {
+    inPlace: 'oxmutate never copies or rewrites the project; instrumented sources are served from memory',
+    tempDirName: 'no sandbox directory exists',
+    cleanTempDir: 'no sandbox directory exists',
+    symlinkNodeModules: 'no sandbox directory exists',
+    plugins: 'no runtime plugin loading; operators and ignorers are data',
+    appendPlugins: 'no runtime plugin loading',
+    packageManager: 'oxmutate never installs anything',
+    coverageAnalysis: 'always perTest',
+    maxTestRunnerReuse: 'workers are replaced on pollution and runaways, automatically',
+    dashboard: 'the Stryker Dashboard reporter is M4 work',
+    clearTextReporter: 'the summary is always printed',
+    eventReporter: 'not implemented',
+    logLevel: 'not implemented',
+    fileLogLevel: 'not implemented',
+    allowConsoleColors: 'colour follows the terminal (roundel policy)',
+    disableTypeChecks: 'always on: instrumented files carry // @ts-nocheck, and the checker reads the original sources',
+    ignorers: 'ignorer plugins are code; oxmutate takes the same rules as data in `ignore` (see the README)',
+    disableBail: 'oxmutate always stops at the first killing test',
+    testFiles: 'test files come from the Vitest config',
+    ignorePatterns: 'oxmutate never copies the project, so there is nothing to ignore',
+    force: 'use --no-incremental',
+    checkerNodeArgs: 'not implemented',
+};
+/**
+ * Defaults where the config sets nothing. Stryker's, except the per-mutant slack: Stryker's
+ * `timeoutMS` is 5000, and a warm run needs far less (cli.ts `--mutant-timeout`).
+ */
+const MAX_DEFAULT_CONCURRENCY = 8;
+const DEFAULT_TIMEOUT_MS = 500;
+const DEFAULT_TIMEOUT_FACTOR = 1.5;
+const DEFAULT_THRESHOLD_HIGH = 80;
+const DEFAULT_THRESHOLD_LOW = 60;
+const DEFAULT_DRY_RUN_MINUTES = 5;
+const USED = new Set(['mutate', 'vitest', 'concurrency', 'timeoutMS', 'timeoutFactor', 'thresholds', 'ignoreStatic', 'reporters', 'jsonReporter', 'htmlReporter', 'incremental', 'incrementalFile', '$schema', 'mutator', 'dryRunOnly', 'dryRunTimeoutMinutes', 'buildCommand', 'testRunnerNodeArgs', 'allowEmpty', 'warnings', 'testRunner', 'commandRunner', 'checkers', 'tsconfigFile']);
+async function loadFile(file) {
+    if (file.endsWith('.json')) {
+        // Stryker disable next-line StringLiteral: without an encoding readFileSync returns a Buffer, which JSON.parse reads as UTF-8 text all the same
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    const mod = (await import(pathToFileURL(file).href));
+    const value = mod.default ?? mod;
+    return (typeof value === 'function' ? await value() : value);
+}
+function find(root, base) {
+    for (const ext of ['.mjs', '.js', '.cjs', '.json', '.mts', '.ts']) {
+        const f = path.join(root, `${base}.config${ext}`);
+        if (existsSync(f))
+            return f;
+    }
+    return undefined;
+}
+/** The Vite (and Vite+) config files, in the order Vite and Vitest look for them. */
+const VITE_CONFIGS = ['vite.config', 'vitest.config'].flatMap((base) => ['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs'].map((ext) => `${base}${ext}`));
+/**
+ * The `mutate` block of the project's Vite config — the Vite+ shape, one file for test, lint, fmt
+ * and mutate. Loaded with the project's own Vite (`loadConfigFromFile`), so a TypeScript config and
+ * its imports work as Vite sees them. Inside the block the file list is `include`, as Vitest names
+ * it; Stryker's `mutate` is accepted too. No Vite installed, or no block: nothing.
+ */
+async function fromViteConfig(root) {
+    const file = VITE_CONFIGS.map((f) => path.join(root, f)).find((f) => existsSync(f));
+    // Stryker disable next-line ConditionalExpression: without the guard Vite searches the root for the same names, finds none, and returns null, which returns undefined below
+    if (!file)
+        return undefined;
+    let vite;
+    try {
+        vite = (await import(resolveEsm('vite', root)));
+    }
+    catch {
+        return undefined;
+    }
+    // Stryker disable next-line StringLiteral: the log level only decides whether Vite prints, and a config that loads prints nothing at any level
+    const level = 'silent';
+    const loaded = await vite.loadConfigFromFile({ command: 'serve', mode: 'test' }, file, root, level);
+    // Stryker disable next-line OptionalChaining: given a file that exists, Vite returns a config or throws; null is its answer only when it found no file
+    const block = loaded?.config['mutate'];
+    if (!block || typeof block !== 'object')
+        return undefined;
+    // `include` is the Vitest spelling; Stryker's `mutate`, when given too, is spread over it.
+    const { include, ...rest } = block;
+    return { file, block: { mutate: include, ...rest } };
+}
+export async function loadOptions(root, overrides = {}, configFile) {
+    const strykerFile = find(root, 'stryker');
+    const oxFile = configFile ? path.resolve(root, configFile) : find(root, 'oxmutate');
+    const stryker = strykerFile ? await loadFile(strykerFile) : {};
+    const vite = oxFile ? undefined : await fromViteConfig(root);
+    const ox = oxFile ? await loadFile(oxFile) : (vite?.block ?? {});
+    const raw = { ...stryker, ...ox };
+    const unused = [];
+    for (const key of Object.keys(stryker)) {
+        if (USED.has(key))
+            continue;
+        unused.push({ key, why: NOT_NEEDED[key] ?? 'not a Stryker 10.0.0 option oxmutate knows' });
+    }
+    const thresholds = (raw['thresholds'] ?? {});
+    const vitest = (raw['vitest'] ?? {});
+    const json = (raw['jsonReporter'] ?? {});
+    const html = (raw['htmlReporter'] ?? {});
+    const mutator = (raw['mutator'] ?? {});
+    const mutate = raw['mutate'] ?? ['src/**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}', '!src/**/*.{test,spec}.*', '!src/**/*.d.ts'];
+    return {
+        root,
+        mutate,
+        vitestConfig: vitest.configFile ? path.resolve(root, vitest.configFile) : undefined,
+        concurrency: Number(raw['concurrency'] ?? Math.max(1, Math.min(MAX_DEFAULT_CONCURRENCY, availableParallelism() - 1))),
+        timeoutMS: Number(raw['timeoutMS'] ?? DEFAULT_TIMEOUT_MS),
+        timeoutFactor: Number(raw['timeoutFactor'] ?? DEFAULT_TIMEOUT_FACTOR),
+        thresholds: { high: thresholds.high ?? DEFAULT_THRESHOLD_HIGH, low: thresholds.low ?? DEFAULT_THRESHOLD_LOW, break: thresholds.break ?? null },
+        excludedMutations: mutator.excludedMutations ?? [],
+        ignoreStatic: raw['ignoreStatic'] === true,
+        strykerCompat: raw['strykerCompat'] === true,
+        reporters: raw['reporters'] ?? ['clear-text', 'json'],
+        jsonReport: path.resolve(root, json.fileName ?? 'reports/mutation/mutation.json'),
+        sarifReport: path.resolve(root, raw['sarifReport'] ?? 'reports/mutation/mutation.sarif'),
+        htmlReport: path.resolve(root, html.fileName ?? 'reports/mutation/mutation.html'),
+        incremental: raw['incremental'] === true,
+        incrementalFile: path.resolve(root, raw['incrementalFile'] ?? 'reports/oxmutate-incremental.json'),
+        flakyReruns: Number(raw['flakyReruns'] ?? 2),
+        unused,
+        configFile: oxFile ?? vite?.file ?? strykerFile,
+        dryRunOnly: raw['dryRunOnly'] === true,
+        dryRunTimeoutMinutes: Number(raw['dryRunTimeoutMinutes'] ?? DEFAULT_DRY_RUN_MINUTES),
+        buildCommand: typeof raw['buildCommand'] === 'string' ? raw['buildCommand'] : undefined,
+        testRunnerNodeArgs: raw['testRunnerNodeArgs'] ?? [],
+        allowEmpty: raw['allowEmpty'] === true,
+        specOracles: raw['specOracles'] ?? [],
+        ignore: raw['ignore'] ?? [],
+        // Stryker disable next-line ArrayDeclaration: a placeholder element is not 'typescript' either, so includes() is false as for an empty list
+        typeCheck: (raw['checkers'] ?? []).includes('typescript'),
+        tsconfigFile: raw['tsconfigFile'] ?? 'tsconfig.json',
+        typeChecker: typeof raw['typeChecker'] === 'string' ? raw['typeChecker'] : undefined,
+        commandRunner: raw['testRunner'] === 'command' ? (raw['commandRunner']?.command ?? 'npm test') : undefined,
+        warnUnused: raw['warnings'] !== false && raw['warnings']?.unknownOptions !== false,
+        ...overrides,
+    };
+}
+// One `\s` after next-line is enough: the list's class takes any further whitespace, and is trimmed.
+const DIRECTIVE = /\/\/\s*(?:Stryker|oxmutate)\s+disable\s+next-line\s([\w,\s]+?|all)\s*:\s*(.*)/i;
+const NO_REASON = /\/\/\s*(?:Stryker|oxmutate)\s+disable\s+next-line\s([\w,\s]+?|all)\s*$/i;
+/** Disable directives in a file. A directive without a reason is an error (burgee's own rule). */
+export function disables(source, file) {
+    const out = [];
+    const errors = [];
+    source.split('\n').forEach((line, i) => {
+        const m = DIRECTIVE.exec(line);
+        if (m) {
+            // Stryker disable next-line StringLiteral: both groups take part in every match, so the fallback is never used; it is there for the type
+            const [list, reason] = [(m[1] ?? '').trim(), (m[2] ?? '').trim()];
+            out.push({ line: i + 2, mutators: list.toLowerCase() === 'all' ? 'all' : list.split(',').map((s) => s.trim()).filter(Boolean), reason });
+        }
+        else if (NO_REASON.test(line)) {
+            errors.push(`${file}:${String(i + 1)}: disable comment without a reason. fix: add ": <why this mutant cannot be killed>"`);
+        }
+    });
+    return { disables: out, errors };
+}
+//# sourceMappingURL=config.js.map

package/dist/coordinator.d.ts

@@ -0,0 +1,83 @@
+import { type Options } from './config.js';
+import type { FrozenOracle } from './frozen.js';
+import { type NativeMutant } from './native.js';
+import { type SpecSummary } from './spec-oracle.js';
+export type Status = 'Killed' | 'Survived' | 'Timeout' | 'NoCoverage' | 'RuntimeError' | 'CompileError' | 'Ignored';
+export interface MutantResult extends NativeMutant {
+    file: string;
+    status: Status;
+    statusReason?: string | undefined;
+    coveredBy: string[];
+    /** A spec oracle's replay tests that reach this mutant (spec-oracle.ts); not in `coveredBy`. */
+    specCoveredBy?: string[] | undefined;
+    /** The spec oracle's verdict, beside the tests' `status`. */
+    spec?: {
+        oracle: string;
+        status: 'Killed' | 'Survived' | 'Unknown';
+        killedBy?: string[] | undefined;
+    } | undefined;
+    killedBy?: string[] | undefined;
+    testsCompleted?: number | undefined;
+    static?: boolean | undefined;
+    /** The verdict changed between re-runs: the covering tests are nondeterministic. */
+    flaky?: boolean | undefined;
+    /** Reused from the incremental cache, not run. */
+    reused?: boolean | undefined;
+}
+export interface TestInfo {
+    id: string;
+    file: string;
+    name: string;
+    ms: number;
+}
+export interface RunStats {
+    files: number;
+    mutants: number;
+    instrumentMs: number;
+    dryRunMs: number;
+    mutationMs: number;
+    isolatedMs: number;
+    wallMs: number;
+    testExecutions: number;
+    watchdogKills: number;
+    crashes: number;
+    canaryFiles: number;
+    /** Contexts restarted because a mutant left state behind (the per-execution canary fired). */
+    pollutionRestarts: number;
+    /** Survivors of the warm run that a whole-file re-run killed (cross-test effects). */
+    survivorsOverturned: number;
+    /** Watchdog timeouts that finished when re-run with 3x the budget: the machine was slow, not the mutant. */
+    timeoutsOverturned: number;
+    /** Survivors the type checker refused (checker.ts): CompileError, out of the score. */
+    compileErrors: number;
+    isolatedRuns: number;
+    reused: number;
+    flakyTests: number;
+    flakyMutants: number;
+    units: number;
+    serversSpawned: number;
+}
+export interface RunResult {
+    root: string;
+    options: Options;
+    sources: Record<string, string>;
+    mutants: MutantResult[];
+    tests: TestInfo[];
+    stats: RunStats;
+    score: {
+        detected: number;
+        undetected: number;
+        total: number;
+        mutationScore: number;
+        covered: number;
+    };
+    /** Each spec oracle's F metrics (spec-oracle.ts). */
+    spec?: SpecSummary[] | undefined;
+    /** The frozen oracle's comparison, when `frozenOracle` was set (frozen.ts). */
+    frozen?: FrozenOracle | undefined;
+    /** Set when the run stopped after the dry run (`dryRunOnly`): no verdicts, no reports. */
+    dryRunOnly?: boolean | undefined;
+}
+export declare class InstrumentFault extends Error {
+}
+export declare function run(options: Options): Promise<RunResult>;