tslaws 0.0.0-stage → 0.3.2

package/dist/mutate.js

@@ -0,0 +1,293 @@
+// Mutation testing: change the covered code in small ways and re-run the laws. A mutant that no law fails
+// (SURVIVED) shows the laws cannot tell that behaviour apart; a failed, erroring or timed-out check KILLS it.
+// Every mutant is checked in a scratch copy of the project under .tslaws/mutants/<n>; the originals are never written.
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import ts from 'typescript';
+import { check } from "./check.js";
+import { coverFiles, readConfig } from "./coverage.js";
+import { mutateDefaults } from "./settings.js";
+const ignoredDirs = new Set(['node_modules', '.tslaws', '.git']);
+const sourceExt = /\.(ts|tsx|mts|cts)$/;
+const copiedExt = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs|json)$/;
+const relational = {
+    [ts.SyntaxKind.LessThanToken]: ['<=', '>='],
+    [ts.SyntaxKind.LessThanEqualsToken]: ['<', '>'],
+    [ts.SyntaxKind.GreaterThanToken]: ['>=', '<='],
+    [ts.SyntaxKind.GreaterThanEqualsToken]: ['>', '<'],
+    [ts.SyntaxKind.EqualsEqualsToken]: ['!='],
+    [ts.SyntaxKind.ExclamationEqualsToken]: ['=='],
+    [ts.SyntaxKind.EqualsEqualsEqualsToken]: ['!=='],
+    [ts.SyntaxKind.ExclamationEqualsEqualsToken]: ['==='],
+    [ts.SyntaxKind.PlusToken]: ['-'],
+    [ts.SyntaxKind.MinusToken]: ['+'],
+    [ts.SyntaxKind.AsteriskToken]: ['/'],
+    [ts.SyntaxKind.SlashToken]: ['*'],
+    [ts.SyntaxKind.AmpersandAmpersandToken]: ['||'],
+    [ts.SyntaxKind.BarBarToken]: ['&&'],
+};
+/** The source files the laws cover: the `cover` globs, or every project module the laws import. */
+export function mutableFiles(cwd, lawFiles, reachOnly = false) {
+    const globs = readConfig(cwd).cover ?? [];
+    const isLaws = (f) => f.endsWith('.laws.ts');
+    const found = new Set();
+    const reached = new Set();
+    if (globs.length > 0 && !reachOnly)
+        for (const f of coverFiles(cwd, globs))
+            found.add(f);
+    else {
+        const seen = new Set();
+        const visit = (file) => {
+            if (seen.has(file))
+                return;
+            seen.add(file);
+            const full = join(cwd, file);
+            if (!existsSync(full))
+                return;
+            for (const imp of ts.preProcessFile(readFileSync(full, 'utf8'), true, true).importedFiles) {
+                if (!imp.fileName.startsWith('.'))
+                    continue;
+                const base = join(dirname(file), imp.fileName).replaceAll('\\', '/');
+                const stem = base.replace(/\.(js|jsx|mjs|cjs|ts|tsx|mts|cts)$/, '');
+                const hit = [
+                    base,
+                    `${stem}.ts`,
+                    `${stem}.tsx`,
+                    `${stem}.mts`,
+                    `${stem}.cts`,
+                    `${base}/index.ts`,
+                    `${base}/index.tsx`,
+                ].find((c) => sourceExt.test(c) && existsSync(join(cwd, c)) && statSync(join(cwd, c)).isFile());
+                if (hit === undefined)
+                    continue;
+                if (!isLaws(hit))
+                    found.add(hit);
+                visit(hit);
+            }
+        };
+        for (const f of lawFiles)
+            visit(f);
+        // Named laws with a `cover` list: mutate only the covered files those laws reach.
+        if (globs.length > 0) {
+            const covered = new Set(coverFiles(cwd, globs));
+            for (const f of found)
+                if (covered.has(f))
+                    reached.add(f);
+            found.clear();
+            for (const f of reached)
+                found.add(f);
+        }
+    }
+    return [...found]
+        .filter((f) => !/\.d\.(ts|mts|cts)$/.test(f) && !isLaws(f) && !/\.(test|spec)\.(ts|tsx|mts|cts)$/.test(f))
+        .filter((f) => !f.split('/').some((p) => p === 'test' || p === 'tests' || p === '__tests__'))
+        .sort();
+}
+/** Every mutation of one file, in source order. */
+export function mutantsOf(file, text) {
+    const kind = file.endsWith('.tsx') ? ts.ScriptKind.TSX : file.endsWith('.jsx') ? ts.ScriptKind.JSX : ts.ScriptKind.TS;
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.ES2022, true, kind);
+    const out = [];
+    const add = (node, start, end, replacement) => {
+        const ns = node.getStart(source);
+        const ne = node.getEnd();
+        const snip = (s) => {
+            const flat = s.replace(/\s+/g, ' ').trim();
+            return flat.length > 80 ? `${flat.slice(0, 77)}...` : flat;
+        };
+        out.push({
+            file,
+            line: source.getLineAndCharacterOfPosition(start).line + 1,
+            start,
+            end,
+            replacement,
+            original: snip(text.slice(ns, ne)),
+            mutated: snip(text.slice(ns, start) + replacement + text.slice(end, ne)),
+        });
+    };
+    const visit = (node) => {
+        if (ts.isTypeNode(node))
+            return;
+        if (ts.isBinaryExpression(node)) {
+            const token = node.operatorToken;
+            for (const op of relational[token.kind] ?? [])
+                add(node, token.getStart(source), token.getEnd(), op);
+        }
+        else if (node.kind === ts.SyntaxKind.TrueKeyword || node.kind === ts.SyntaxKind.FalseKeyword) {
+            add(node, node.getStart(source), node.getEnd(), node.kind === ts.SyntaxKind.TrueKeyword ? 'false' : 'true');
+        }
+        else if (ts.isNumericLiteral(node)) {
+            const v = Number(node.text);
+            const wrap = (n) => (n < 0 ? `(${n})` : String(n));
+            for (const n of new Set([v + 1, v - 1, 0])) {
+                if (n !== v && Number.isFinite(n))
+                    add(node, node.getStart(source), node.getEnd(), wrap(n));
+            }
+        }
+        else if (ts.isIfStatement(node)) {
+            const c = node.expression;
+            add(node.expression, c.getStart(source), c.getEnd(), `!(${c.getText(source)})`);
+        }
+        else if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.ExclamationToken) {
+            add(node, node.getStart(source), node.operand.getStart(source), '');
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return out;
+}
+function prng(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** At most `max` mutants: all of them when they fit, else a seeded sample kept in source order. */
+export function sample(all, max, seed) {
+    if (all.length <= max)
+        return all;
+    const rand = prng(seed);
+    const idx = all.map((_, i) => i);
+    for (let i = idx.length - 1; i > 0; i -= 1) {
+        const j = Math.floor(rand() * (i + 1));
+        [idx[i], idx[j]] = [idx[j], idx[i]];
+    }
+    return idx
+        .slice(0, max)
+        .sort((a, b) => a - b)
+        .map((i) => all[i]);
+}
+function copyProject(cwd, to) {
+    rmSync(to, { recursive: true, force: true });
+    mkdirSync(to, { recursive: true });
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir)) {
+            if (ignoredDirs.has(entry))
+                continue;
+            const full = join(dir, entry);
+            if (statSync(full).isDirectory())
+                walk(full);
+            else if (copiedExt.test(entry) || entry === 'tsc-laws.lock') {
+                const dest = join(to, relative(cwd, full));
+                mkdirSync(dirname(dest), { recursive: true });
+                cpSync(full, dest);
+            }
+        }
+    };
+    walk(cwd);
+}
+export async function mutate(options) {
+    const { cwd } = options;
+    const say = options.onProgress ?? (() => undefined);
+    const scratchRoot = join(cwd, '.tslaws', 'mutants');
+    const config = readConfig(cwd);
+    const checkOptions = (dir) => ({
+        files: options.lawFiles,
+        cwd: dir,
+        runs: options.runs ?? config.runs ?? mutateDefaults.runs,
+        seed: options.seed,
+        compiler: options.compiler,
+        lockFile: join(dir, 'tsc-laws.lock'),
+        noProve: false,
+        bound: options.bound ?? config.bound ?? mutateDefaults.bound,
+        proofTimeoutMs: options.proofTimeoutMs ?? config.proofTimeoutMs ?? mutateDefaults.proofTimeoutMs,
+        propertyTimeoutMs: options.propertyTimeoutMs ?? config.propertyTimeoutMs ?? mutateDefaults.propertyTimeoutMs,
+        browser: options.browser,
+        // The lock is not enforced on mutants; it is copied so the scratch project is complete.
+        explicit: options.runs === undefined ? [] : ['runs'],
+    });
+    const empty = (baselineError) => ({
+        results: [],
+        killed: 0,
+        survived: 0,
+        skipped: 0,
+        score: 100,
+        baselineError,
+        ok: baselineError === undefined,
+    });
+    try {
+        // The unmutated copy must pass, or every mutant would count as killed.
+        const baseDir = join(scratchRoot, '0');
+        copyProject(cwd, baseDir);
+        const base = await check(checkOptions(baseDir), false);
+        if (!base.compileOk)
+            return empty(`the project does not compile:\n${base.compileDiagnostics}`);
+        if (!base.ok) {
+            const failing = base.results.find((r) => r.status !== 'proved' && r.status !== 'bounded' && r.status !== 'tested');
+            const first = failing?.message?.split(/\r?\n/)[0];
+            const which = failing === undefined
+                ? 'unknown'
+                : `${failing.name} (${failing.file}:${failing.line}) is ${failing.status}${first === undefined ? '' : `: ${first}`}`;
+            return empty(`the laws do not pass on the unmutated code; fix them before mutation testing. First failure: ${which}. If it timed out, raise --proof-timeout or --property-timeout (or set them in tslaws.json)`);
+        }
+        const wanted = new Set((options.targets ?? []).map((t) => t.replaceAll('\\', '/')));
+        const files = mutableFiles(cwd, options.lawFiles, options.lawsNamed === true).filter((f) => wanted.size === 0 || wanted.has(f));
+        const originals = new Map(files.map((f) => [f, readFileSync(join(cwd, f), 'utf8')]));
+        const all = files.flatMap((f) => mutantsOf(f, originals.get(f)));
+        const chosen = sample(all, options.max, options.seed ?? 1);
+        say(`${chosen.length} of ${all.length} mutants in ${files.length} files`);
+        const results = [];
+        for (const [n, mutant] of chosen.entries()) {
+            const dir = join(scratchRoot, String(n + 1));
+            let result;
+            try {
+                copyProject(cwd, dir);
+                const text = originals.get(mutant.file);
+                writeFileSync(join(dir, mutant.file), text.slice(0, mutant.start) + mutant.replacement + text.slice(mutant.end));
+                const report = await check(checkOptions(dir), false);
+                if (!report.compileOk)
+                    result = { ...mutant, status: 'skipped', reason: 'does not compile' };
+                else if (report.ok)
+                    result = { ...mutant, status: 'survived' };
+                else {
+                    const failing = report.results.find((r) => r.status !== 'proved' && r.status !== 'bounded' && r.status !== 'tested');
+                    result = {
+                        ...mutant,
+                        status: 'killed',
+                        reason: failing === undefined ? 'check failed' : `${failing.name}: ${failing.status}`,
+                    };
+                }
+            }
+            catch (error) {
+                result = {
+                    ...mutant,
+                    status: 'killed',
+                    reason: `check errored: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+            finally {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            results.push(result);
+            say(`[${n + 1}/${chosen.length}] ${result.status} ${mutant.file}:${mutant.line} ${mutant.original} -> ${mutant.mutated}`);
+        }
+        const killed = results.filter((r) => r.status === 'killed').length;
+        const survived = results.filter((r) => r.status === 'survived').length;
+        const tried = killed + survived;
+        return {
+            results,
+            killed,
+            survived,
+            skipped: results.length - tried,
+            score: tried === 0 ? 100 : Math.round((killed / tried) * 1000) / 10,
+            ok: survived === 0,
+        };
+    }
+    finally {
+        rmSync(scratchRoot, { recursive: true, force: true });
+    }
+}
+export function renderMutation(report) {
+    if (report.baselineError !== undefined)
+        return `mutation testing not run: ${report.baselineError}\n`;
+    let text = '';
+    for (const r of report.results.filter((x) => x.status === 'survived')) {
+        text += `SURVIVED ${r.file}:${r.line}  ${r.original}  ->  ${r.mutated}\n  hint: add or strengthen a law that tells these apart\n`;
+    }
+    const tried = report.killed + report.survived;
+    return `${text}${text === '' ? '' : '\n'}mutation score ${report.score}% (${report.killed} killed, ${report.survived} survived of ${tried} tried, ${report.skipped} skipped)\n`;
+}

package/dist/promote.d.ts

@@ -0,0 +1,38 @@
+export interface ParsedLaw {
+    name: string;
+    /** The declaration as written, from `export` to its end. */
+    text: string;
+    start: number;
+    end: number;
+}
+export interface ParsedLawFile {
+    /** Whole import statements, in order. */
+    imports: string[];
+    laws: ParsedLaw[];
+}
+/** `foo.proposed.laws.ts` -> `foo.laws.ts`; undefined for any other name. */
+export declare function acceptedPathFor(proposed: string): string | undefined;
+/**
+ * Finds the import statements and the `export law ...` declarations of a laws file. `law` is not standard TypeScript, so
+ * this scans tokens with the TypeScript scanner (strings, comments and templates are skipped correctly) and matches
+ * brackets: a law ends at its closing `}` or at a `;` at depth 0.
+ */
+export declare function parseLawFile(text: string): ParsedLawFile;
+/** Joins the import statements, dropping repeats by whitespace-insensitive text. */
+export declare function dedupeImports(existing: string[], added: string[]): string[];
+/**
+ * The accepted file after promoting `laws` (with the proposed file's imports) into it. `existing` is the current text
+ * of the accepted file, or undefined when it does not exist yet. Throws when a law name is already taken there.
+ */
+export declare function buildAccepted(existing: string | undefined, imports: string[], laws: ParsedLaw[]): string;
+/** The proposed file without the promoted laws, or undefined when no law is left (the file is deleted). */
+export declare function buildRemaining(text: string, promoted: string[]): string | undefined;
+export interface PromoteHost {
+    cwd: string;
+    /** Checks one proposed file and returns its results by law name (as `check --proposed` would). */
+    checkFile: (file: string) => Promise<Map<string, string>>;
+    ask: (question: string) => Promise<string>;
+    out: (text: string) => void;
+}
+/** Walks the proposed files, asks per law, and rewrites the accepted and proposed files. Returns the number promoted. */
+export declare function promoteFiles(host: PromoteHost, proposedFiles: string[]): Promise<number>;

package/dist/promote.js

@@ -0,0 +1,217 @@
+// `tslaws promote`: the pure core. A person moves proposed laws into the accepted file; the lock is not touched here.
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import ts from 'typescript';
+/** `foo.proposed.laws.ts` -> `foo.laws.ts`; undefined for any other name. */
+export function acceptedPathFor(proposed) {
+    return proposed.endsWith('.proposed.laws.ts')
+        ? `${proposed.slice(0, -'.proposed.laws.ts'.length)}.laws.ts`
+        : undefined;
+}
+/**
+ * Finds the import statements and the `export law ...` declarations of a laws file. `law` is not standard TypeScript, so
+ * this scans tokens with the TypeScript scanner (strings, comments and templates are skipped correctly) and matches
+ * brackets: a law ends at its closing `}` or at a `;` at depth 0.
+ */
+export function parseLawFile(text) {
+    const scanner = ts.createScanner(ts.ScriptTarget.Latest, true, ts.LanguageVariant.Standard, text);
+    const imports = [];
+    const laws = [];
+    const templates = []; // depth at which each open template substitution started
+    let depth = 0;
+    let statement;
+    let arrow = false;
+    const finish = (end) => {
+        if (statement === undefined)
+            return;
+        if (statement.kind === 'import')
+            imports.push(text.slice(statement.start, end));
+        else
+            laws.push({ name: statement.name, text: text.slice(statement.start, end), start: statement.start, end });
+        statement = undefined;
+        arrow = false;
+    };
+    let kind = scanner.scan();
+    while (kind !== ts.SyntaxKind.EndOfFileToken) {
+        const tokenStart = scanner.getTokenStart();
+        if (kind === ts.SyntaxKind.CloseBraceToken && templates.length > 0 && templates[templates.length - 1] === depth) {
+            templates.pop();
+            kind = scanner.reScanTemplateToken(false);
+            if (kind === ts.SyntaxKind.TemplateMiddle)
+                templates.push(depth);
+        }
+        else if (kind === ts.SyntaxKind.TemplateHead) {
+            templates.push(depth);
+        }
+        else if (depth === 0 && statement === undefined) {
+            if (kind === ts.SyntaxKind.ImportKeyword) {
+                statement = { kind: 'import', start: tokenStart, name: '', sawString: false };
+            }
+            else if (kind === ts.SyntaxKind.ExportKeyword) {
+                const rest = scanner.getTokenEnd();
+                const next = ts.createScanner(ts.ScriptTarget.Latest, true, ts.LanguageVariant.Standard, text, undefined, rest, text.length - rest);
+                const word = next.scan();
+                if (word === ts.SyntaxKind.Identifier && next.getTokenValue() === 'law') {
+                    let n = next.scan();
+                    if (n === ts.SyntaxKind.Identifier && next.getTokenValue() === 'proved')
+                        n = next.scan();
+                    if (n === ts.SyntaxKind.Identifier || n > ts.SyntaxKind.LastReservedWord)
+                        statement = { kind: 'law', start: tokenStart, name: next.getTokenValue(), sawString: false };
+                }
+            }
+        }
+        if (kind === ts.SyntaxKind.OpenBraceToken ||
+            kind === ts.SyntaxKind.OpenParenToken ||
+            kind === ts.SyntaxKind.OpenBracketToken) {
+            depth += 1;
+        }
+        else if (kind === ts.SyntaxKind.CloseBraceToken ||
+            kind === ts.SyntaxKind.CloseParenToken ||
+            kind === ts.SyntaxKind.CloseBracketToken) {
+            depth = Math.max(0, depth - 1);
+            if (depth === 0 && kind === ts.SyntaxKind.CloseBraceToken && statement?.kind === 'law') {
+                // A block-bodied law ends here; the arrow form ends at its `;`.
+                if (!arrow) {
+                    let end = scanner.getTokenEnd();
+                    const peek = ts.createScanner(ts.ScriptTarget.Latest, true, ts.LanguageVariant.Standard, text, undefined, end, text.length - end);
+                    if (peek.scan() === ts.SyntaxKind.SemicolonToken)
+                        end = peek.getTokenEnd();
+                    finish(end);
+                    if (end > scanner.getTokenEnd())
+                        scanner.resetTokenState(end);
+                    kind = scanner.scan();
+                    continue;
+                }
+            }
+        }
+        else if (depth === 0 && kind === ts.SyntaxKind.EqualsGreaterThanToken && statement?.kind === 'law') {
+            arrow = true;
+        }
+        else if (depth === 0 && kind === ts.SyntaxKind.SemicolonToken) {
+            finish(scanner.getTokenEnd());
+        }
+        else if (depth === 0 && statement?.kind === 'import' && kind === ts.SyntaxKind.StringLiteral) {
+            statement.sawString = true;
+            const end = scanner.getTokenEnd();
+            const peek = ts.createScanner(ts.ScriptTarget.Latest, true, ts.LanguageVariant.Standard, text, undefined, end, text.length - end);
+            const after = peek.scan();
+            const attributes = after === ts.SyntaxKind.WithKeyword ||
+                (after === ts.SyntaxKind.Identifier && peek.getTokenValue() === 'assert');
+            if (!attributes) {
+                const stop = after === ts.SyntaxKind.SemicolonToken ? peek.getTokenEnd() : end;
+                finish(stop);
+                if (stop > end)
+                    scanner.resetTokenState(stop);
+            }
+        }
+        kind = scanner.scan();
+    }
+    finish(text.length);
+    return { imports, laws };
+}
+const squash = (s) => s.replace(/\s+/g, ' ').trim();
+/** Joins the import statements, dropping repeats by whitespace-insensitive text. */
+export function dedupeImports(existing, added) {
+    const seen = new Set(existing.map(squash));
+    const out = [...existing];
+    for (const statement of added) {
+        if (seen.has(squash(statement)))
+            continue;
+        seen.add(squash(statement));
+        out.push(statement);
+    }
+    return out;
+}
+/**
+ * The accepted file after promoting `laws` (with the proposed file's imports) into it. `existing` is the current text
+ * of the accepted file, or undefined when it does not exist yet. Throws when a law name is already taken there.
+ */
+export function buildAccepted(existing, imports, laws) {
+    const base = existing ?? '';
+    const parsed = parseLawFile(base);
+    const taken = new Set(parsed.laws.map((l) => l.name));
+    for (const law of laws)
+        if (taken.has(law.name))
+            throw new Error(`law '${law.name}' already exists in the accepted file`);
+    const missing = dedupeImports(parsed.imports, imports).slice(parsed.imports.length);
+    let text = base;
+    if (missing.length > 0) {
+        // New imports go after the last existing import, or at the top.
+        const lastEnd = parsed.imports.length > 0
+            ? base.indexOf(parsed.imports[parsed.imports.length - 1]) + parsed.imports[parsed.imports.length - 1].length
+            : 0;
+        const block = missing.map((m) => (m.endsWith(';') ? m : `${m};`)).join('\n');
+        text =
+            lastEnd === 0
+                ? `${block}\n${base === '' ? '' : `${base.startsWith('\n') ? '' : '\n'}`}${base}`
+                : `${base.slice(0, lastEnd)}\n${block}${base.slice(lastEnd)}`;
+    }
+    const body = laws.map((l) => l.text.trimEnd()).join('\n\n');
+    const trimmed = text.trimEnd();
+    return `${trimmed === '' ? '' : `${trimmed}\n\n`}${body}\n`;
+}
+/** The proposed file without the promoted laws, or undefined when no law is left (the file is deleted). */
+export function buildRemaining(text, promoted) {
+    const parsed = parseLawFile(text);
+    const drop = new Set(promoted);
+    if (parsed.laws.every((l) => drop.has(l.name)))
+        return undefined;
+    let out = text;
+    for (const law of [...parsed.laws].reverse()) {
+        if (!drop.has(law.name))
+            continue;
+        let end = law.end;
+        while (out[end] === '\r' || out[end] === '\n')
+            end += 1;
+        out = out.slice(0, law.start) + out.slice(end);
+    }
+    return out;
+}
+/** Walks the proposed files, asks per law, and rewrites the accepted and proposed files. Returns the number promoted. */
+export async function promoteFiles(host, proposedFiles) {
+    let promoted = 0;
+    for (const file of proposedFiles) {
+        const accepted = acceptedPathFor(file);
+        if (accepted === undefined) {
+            host.out(`${file}: not a *.proposed.laws.ts file, skipped\n`);
+            continue;
+        }
+        const proposedPath = join(host.cwd, file);
+        const acceptedPath = join(host.cwd, accepted);
+        const text = readFileSync(proposedPath, 'utf8');
+        const parsed = parseLawFile(text);
+        if (parsed.laws.length === 0) {
+            host.out(`${file}: no laws\n`);
+            continue;
+        }
+        const results = await host.checkFile(file);
+        const chosen = [];
+        for (const law of parsed.laws) {
+            host.out(`\n${file}: ${law.name}  [${results.get(law.name) ?? 'not checked'}]\n${law.text.trim()}\n`);
+            if ((await host.ask(`promote ${law.name}? [y/N] `)).trim().toLowerCase() === 'y')
+                chosen.push(law);
+        }
+        if (chosen.length === 0)
+            continue;
+        const existing = existsSync(acceptedPath) ? readFileSync(acceptedPath, 'utf8') : undefined;
+        let built;
+        try {
+            built = buildAccepted(existing, parsed.imports, chosen);
+        }
+        catch (error) {
+            host.out(`${accepted}: ${error instanceof Error ? error.message : String(error)}; nothing promoted from ${file}\n`);
+            continue;
+        }
+        writeFileSync(acceptedPath, built);
+        const remaining = buildRemaining(text, chosen.map((l) => l.name));
+        if (remaining === undefined)
+            rmSync(proposedPath);
+        else
+            writeFileSync(proposedPath, remaining);
+        promoted += chosen.length;
+        host.out(`${chosen.length} law${chosen.length === 1 ? '' : 's'} moved to ${accepted}${remaining === undefined ? `; ${file} removed` : ''}\n`);
+    }
+    if (promoted > 0)
+        host.out('\nThe lock is unchanged. Review the diff, then run `tslaws accept` to record these laws.\n');
+    return promoted;
+}

package/dist/property.d.ts

@@ -0,0 +1,37 @@
+import * as fc from 'fast-check';
+import ts from 'typescript';
+import type { Shape } from './smt.ts';
+import type { CheckOptions, ManifestLaw } from './types.ts';
+export interface LawTypes {
+    generators: fc.Arbitrary<unknown>[];
+    shapes: Shape[];
+}
+/** Every declaration file the compiler emitted: the laws' own do not import the code they are about. */
+export declare function declarationFiles(outDir: string): string[];
+export declare function dtsPath(outDir: string, file: string): string;
+export declare function jsPath(outDir: string, file: string): string;
+/** What the prover models of `type`: numbers, `int`s, bigints, strings, booleans, arrays and records of them. */
+export declare function shapeOf(checker: ts.TypeChecker, type: ts.Type): Shape;
+export declare function typesOf(program: ts.Program, outDir: string, law: ManifestLaw): LawTypes;
+export declare function isDiscard(error: unknown): boolean;
+/** Runs `call` on generated inputs. `call` may be async (a law that waits, or one that runs in a browser). */
+export declare function runProperty(call: (...args: unknown[]) => unknown, generators: fc.Arbitrary<unknown>[], options: CheckOptions): Promise<fc.RunDetails<unknown[]>>;
+export declare const runLaw: typeof runProperty;
+export declare const compilerOptions: ts.CompilerOptions;
+/** The outcome of a law's property test, without the generated values' prototypes so it can cross a thread. */
+export interface PropertyOutcome {
+    failed: boolean;
+    numRuns: number;
+    seed: number;
+    /** Absent when the law failed because `assume` discarded nearly every input. */
+    counterexample?: string;
+    message?: string;
+    screenshot?: string;
+    /** The counterexample in the regression corpus's encoding; absent when it cannot be stored. */
+    encoded?: string;
+    /** Whether the counterexample is one that was replayed from the corpus. */
+    regression?: boolean;
+}
+export declare function summarise(details: fc.RunDetails<unknown[]>, options?: CheckOptions): PropertyOutcome;
+/** Runs the property test of `law` in a worker, giving up on it after `options.propertyTimeoutMs`. */
+export declare function runLawGuarded(outDir: string, law: ManifestLaw, options: CheckOptions): Promise<PropertyOutcome | 'timeout'>;