tslaws 0.0.0-stage → 0.3.2

package/dist/cli.js

@@ -0,0 +1,360 @@
+import { createInterface } from 'node:readline/promises';
+import { readdirSync, statSync, watch } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { resolveEngine } from "./browser.js";
+import { bundledCompiler, checkoutCompiler } from "./bundled.js";
+import { check, exemptionsOf } from "./check.js";
+import { readManifest } from "./compile.js";
+import { hintFor } from "./hints.js";
+import { init, nextStep } from "./init.js";
+import { serveMcp } from "./mcp.js";
+import { promoteFiles } from "./promote.js";
+import { clearCorpus, listCorpus } from "./regressions.js";
+import { reporterNames, reportAs } from "./reporters.js";
+import { readConfig } from "./coverage.js";
+import { mutate, renderMutation } from "./mutate.js";
+import { mutateDefaults, resolveSettings } from "./settings.js";
+import { serveUi } from "./ui.js";
+import { writeLock } from "./lock.js";
+const usage = `tslaws init [--force]       scaffold tslaws.json, .gitignore, AGENTS.md, Claude Code hooks and a starter law (never writes the lock)
+tslaws check [files...] [--reporter text|json|junit|github] [--json] [--summary] [--watch] [--runs N] [--seed N] [--no-prove] [--no-regressions] [--bound N] [--proof-timeout MS] [--property-timeout MS] [--proposed] [--compiler PATH] [--browser chromium|firefox|webkit]
+tslaws ui [files...] [--port N] [--no-open] [--tab]   open a dashboard of the laws in its own desktop window (--tab: a browser tab): tree, filters, search, source, live reruns on save
+tslaws mutate [files...] [--max N] [--seed N] [--runs N] [--bound N] [--proof-timeout MS] [--property-timeout MS] [--browser ENGINE] [--json]   mutation-test the laws: mutate covered code, report mutants no law kills
+tslaws regressions [list|clear]   show or delete the stored counterexamples (.tslaws/regressions); check replays them first, --no-regressions skips them
+tslaws accept [files...]     record the current laws in tsc-laws.lock (people only: needs a terminal)
+tslaws promote [file] [--all]   move proposed laws (*.proposed.laws.ts) into the accepted *.laws.ts, asking per law (people only: needs a terminal; run accept afterwards)
+tslaws mcp [--compiler PATH]   serve check, check_proposed, explain and propose as Model Context Protocol tools on stdio (cannot accept or touch the lock)
+
+Without files, every *.laws.ts under the current directory is checked (*.proposed.laws.ts only with --proposed).
+Exit status is 0 only when every law is proved, bounded or tested and nothing is open, failed, uncovered or tampered with.
+  --json      machine-readable report; each result carries a hint with the next action (same as --reporter json)
+  --reporter  text (default), json, junit (JUnit XML) or github (workflow annotations; appends a table to $GITHUB_STEP_SUMMARY)
+  --summary   one line per non-passing law, then the totals line
+  --watch     rerun the check when a .ts file under the current directory changes (Ctrl+C exits)
+  --force     init: overwrite tslaws.json and replace the AGENTS.md section`;
+const ignoredDirs = new Set(['node_modules', '.tslaws', '.git']);
+const passing = new Set(['proved', 'bounded', 'tested']);
+function discover(cwd, proposed) {
+    const found = [];
+    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 (entry.endsWith('.laws.ts') && entry.endsWith('.proposed.laws.ts') === proposed)
+                found.push(full);
+        }
+    };
+    walk(cwd);
+    return found.map((f) => relative(cwd, f).replace(/\\/g, '/')).sort();
+}
+function parse(args) {
+    const flags = new Map();
+    const files = [];
+    let command = 'check';
+    const valued = new Set([
+        'runs',
+        'seed',
+        'compiler',
+        'bound',
+        'proof-timeout',
+        'property-timeout',
+        'browser',
+        'port',
+        'reporter',
+        'max',
+    ]);
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            const name = arg.slice(2);
+            if (valued.has(name))
+                flags.set(name, args[(i += 1)] ?? '');
+            else
+                flags.set(name, true);
+        }
+        else if (i === 0 &&
+            (arg === 'check' ||
+                arg === 'accept' ||
+                arg === 'init' ||
+                arg === 'ui' ||
+                arg === 'mutate' ||
+                arg === 'regressions' ||
+                arg === 'mcp' ||
+                arg === 'promote'))
+            command = arg;
+        else
+            files.push(arg);
+    }
+    return { command, flags, files };
+}
+function describe(result) {
+    const where = `${result.file}:${result.line}`;
+    const head = `${result.status.toUpperCase().padEnd(8)} ${result.name} (${where}) [${result.method}]`;
+    const lines = [head];
+    if (result.message !== undefined)
+        lines.push(`         ${result.message}`);
+    if (result.counterexample !== undefined)
+        lines.push(`         counterexample: ${result.counterexample}`);
+    if (result.status === 'failed' && result.seed !== undefined)
+        lines.push(`         reproduce with --seed ${result.seed}`);
+    const hint = hintFor(result);
+    if (hint !== undefined)
+        lines.push(`         hint: ${hint}`);
+    return lines.join('\n');
+}
+function summarise(result) {
+    const detail = [
+        result.message,
+        result.counterexample !== undefined ? `counterexample: ${result.counterexample}` : undefined,
+    ]
+        .filter((d) => d !== undefined)
+        .join(' | ')
+        .replace(/\s+/g, ' ');
+    return `${result.status.toUpperCase()} ${result.name} (${result.file}:${result.line})${detail === '' ? '' : ` ${detail}`}`;
+}
+function totals(report) {
+    const count = (status) => report.results.filter((r) => r.status === status).length;
+    return `${report.results.length} laws: ${count('proved')} proved, ${count('bounded')} bounded, ${count('tested')} tested, ${count('open')} open, ${count('failed')} failed, ${count('tampered')} tampered, ${count('error')} errors`;
+}
+function render(report, flags) {
+    const reporter = String(flags.get('reporter') ?? (flags.has('json') ? 'json' : 'text'));
+    if (!reporterNames.includes(reporter)) {
+        throw new Error(`unknown reporter '${reporter}' (expected ${reporterNames.join(', ')})`);
+    }
+    if (reporter === 'junit' || reporter === 'github')
+        return reportAs(reporter, report);
+    if (reporter === 'json') {
+        return `${JSON.stringify({ ...report, results: report.results.map((r) => ({ ...r, hint: hintFor(r) })) }, null, 2)}\n`;
+    }
+    let text = '';
+    if (report.compileDiagnostics !== '')
+        text += `${report.compileDiagnostics}\n\n`;
+    if (report.lockMissing)
+        text += 'tsc-laws.lock is missing: a person must run `tslaws accept`\n\n';
+    if (flags.has('summary')) {
+        for (const result of report.results)
+            if (!passing.has(result.status))
+                text += `${summarise(result)}\n`;
+        return `${text}${totals(report)}\n`;
+    }
+    for (const result of report.results)
+        text += `${describe(result)}\n`;
+    return `${text}\n${totals(report)}\n`;
+}
+function options(cwd, flags, chosen) {
+    const settings = resolveSettings(flags, readConfig(cwd));
+    return {
+        files: chosen,
+        cwd,
+        runs: settings.runs,
+        seed: flags.has('seed') ? Number(flags.get('seed')) : undefined,
+        compiler: String(flags.get('compiler') ?? process.env.TSC_LAWS_BIN ?? bundledCompiler() ?? checkoutCompiler(cwd) ?? 'tsc-laws'),
+        lockFile: join(cwd, 'tsc-laws.lock'),
+        noProve: flags.has('no-prove'),
+        noRegressions: flags.has('no-regressions'),
+        bound: settings.bound,
+        proofTimeoutMs: settings.proofTimeoutMs,
+        propertyTimeoutMs: settings.propertyTimeoutMs,
+        explicit: settings.explicit,
+        browser: flags.has('browser')
+            ? resolveEngine(String(flags.get('browser')))
+            : undefined,
+    };
+}
+function lawFiles(cwd, flags, files) {
+    return files.length > 0
+        ? files.map((f) => relative(cwd, resolve(cwd, f)).replace(/\\/g, '/'))
+        : discover(cwd, flags.has('proposed'));
+}
+/** One check of the project. Resolves the exit status. */
+async function runCheck(cwd, flags, files) {
+    const chosen = lawFiles(cwd, flags, files);
+    if (chosen.length === 0) {
+        process.stderr.write('no laws files found (looking for *.laws.ts)\n');
+        return 1;
+    }
+    const report = await check(options(cwd, flags, chosen), !flags.has('proposed'));
+    process.stdout.write(render(report, flags));
+    return report.ok ? 0 : 1;
+}
+function watched(filename) {
+    if (filename === null || !filename.endsWith('.ts'))
+        return false;
+    return !filename.split(/[\\/]/).some((part) => ignoredDirs.has(part));
+}
+/** Checks now and after every .ts change under cwd (debounced 300 ms). Resolves the last exit status on Ctrl+C. */
+async function watchChecks(cwd, flags, files) {
+    let last = 0;
+    let running = false;
+    let queued;
+    let timer;
+    const cycle = async (why) => {
+        if (running) {
+            queued = why;
+            return;
+        }
+        running = true;
+        let next = why;
+        while (next !== undefined) {
+            queued = undefined;
+            process.stdout.write(`\n==== ${new Date().toLocaleTimeString()} tslaws check (${next}) ====\n`);
+            try {
+                last = await runCheck(cwd, flags, files);
+            }
+            catch (error) {
+                process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+                last = 1;
+            }
+            process.stdout.write(`==== exit status ${last}${last === 0 ? ' (ok)' : ' (failing)'}; watching for changes, Ctrl+C exits ====\n`);
+            next = queued;
+        }
+        running = false;
+    };
+    await cycle('initial run');
+    return new Promise((done) => {
+        const watcher = watch(cwd, { recursive: true }, (_event, filename) => {
+            const name = filename === null ? null : String(filename);
+            if (name === null || !watched(name))
+                return;
+            clearTimeout(timer);
+            timer = setTimeout(() => void cycle(`changed: ${name.split(sep).join('/')}`), 300);
+        });
+        process.once('SIGINT', () => {
+            clearTimeout(timer);
+            watcher.close();
+            done(last);
+        });
+    });
+}
+export async function main(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        process.stdout.write(`${usage}\n`);
+        return 0;
+    }
+    const { command, flags, files } = parse(args);
+    const cwd = process.cwd();
+    if (command === 'init') {
+        process.stdout.write(`${init({ cwd, force: flags.has('force') }).join('\n')}\n\n${nextStep}\n`);
+        return 0;
+    }
+    if (command === 'accept') {
+        const chosen = lawFiles(cwd, flags, files);
+        if (chosen.length === 0) {
+            process.stderr.write('no laws files found (looking for *.laws.ts)\n');
+            return 1;
+        }
+        if (!process.stdin.isTTY || process.env.TSLAWS_AGENT !== undefined || process.env.CI !== undefined) {
+            process.stderr.write('accept records laws as correct and needs a person at a terminal; it will not run here\n');
+            return 1;
+        }
+        const opts = options(cwd, flags, chosen);
+        const laws = readManifest(opts.compiler, opts.files, cwd);
+        process.stdout.write(`${laws.length} laws in ${chosen.length} files:\n${laws.map((l) => `  ${l.file}:${l.line} ${l.name}`).join('\n')}\n`);
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await rl.question('Type ACCEPT to write tsc-laws.lock: ');
+        rl.close();
+        if (answer.trim() !== 'ACCEPT')
+            return 1;
+        const exempt = exemptionsOf(opts);
+        if (exempt.length > 0)
+            process.stdout.write(`exempt from coverage:\n${exempt.map((e) => `  ${e}`).join('\n')}\n`);
+        writeLock(opts.lockFile, laws, exempt);
+        process.stdout.write('tsc-laws.lock written\n');
+        return 0;
+    }
+    if (command === 'mcp')
+        return serveMcp({ cwd, compiler: options(cwd, flags, []).compiler });
+    if (command === 'promote') {
+        if (!process.stdin.isTTY || process.env.TSLAWS_AGENT !== undefined || process.env.CI !== undefined) {
+            process.stderr.write('promote moves laws into the accepted set and needs a person at a terminal; it will not run here\n');
+            return 1;
+        }
+        const proposedFiles = files.length > 0 ? lawFiles(cwd, flags, files) : flags.has('all') ? discover(cwd, true) : [];
+        if (proposedFiles.length === 0) {
+            const known = discover(cwd, true).map((f) => `  ${f}`);
+            process.stderr.write(files.length > 0 || flags.has('all')
+                ? 'no proposed laws files found (looking for *.proposed.laws.ts)\n'
+                : `name a proposed file or pass --all:\n${known.join('\n')}\n`);
+            return 1;
+        }
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            await promoteFiles({
+                cwd,
+                ask: (question) => rl.question(question),
+                out: (text) => process.stdout.write(text),
+                checkFile: async (file) => {
+                    const report = await check(options(cwd, flags, [file]), false);
+                    const brief = (r) => r.message === undefined ? r.status : `${r.status}: ${r.message.split('\n')[0]}`;
+                    return new Map(report.results.map((r) => [r.name, brief(r)]));
+                },
+            }, proposedFiles);
+        }
+        finally {
+            rl.close();
+        }
+        return 0;
+    }
+    if (command === 'mutate') {
+        // *.laws.ts arguments choose the laws; other files restrict which covered sources are mutated.
+        const chosen = lawFiles(cwd, flags, files.filter((f) => f.endsWith('.laws.ts')));
+        if (chosen.length === 0) {
+            process.stderr.write('no laws files found (looking for *.laws.ts)\n');
+            return 1;
+        }
+        const settings = resolveSettings(flags, readConfig(cwd), mutateDefaults);
+        const report = await mutate({
+            cwd,
+            lawFiles: chosen,
+            lawsNamed: files.some((f) => f.endsWith('.laws.ts')),
+            runs: settings.runs,
+            bound: settings.bound,
+            proofTimeoutMs: settings.proofTimeoutMs,
+            propertyTimeoutMs: settings.propertyTimeoutMs,
+            browser: options(cwd, flags, chosen).browser,
+            targets: files.filter((f) => !f.endsWith('.laws.ts')).map((f) => relative(cwd, resolve(cwd, f))),
+            compiler: options(cwd, flags, chosen).compiler,
+            max: Number(flags.get('max') ?? 50),
+            seed: flags.has('seed') ? Number(flags.get('seed')) : undefined,
+            onProgress: flags.has('json') ? undefined : (line) => process.stderr.write(`${line}\n`),
+        });
+        process.stdout.write(flags.has('json') ? `${JSON.stringify(report, null, 2)}\n` : renderMutation(report));
+        return report.ok ? 0 : 1;
+    }
+    if (command === 'regressions') {
+        const action = files[0] ?? 'list';
+        if (action === 'clear') {
+            process.stdout.write(clearCorpus(cwd) ? 'cleared .tslaws/regressions\n' : 'no regression corpus to clear\n');
+            return 0;
+        }
+        if (action !== 'list') {
+            process.stderr.write(`unknown action '${action}' (expected list or clear)\n`);
+            return 1;
+        }
+        const corpus = listCorpus(cwd);
+        process.stdout.write(corpus.length === 0
+            ? 'no stored counterexamples\n'
+            : `${corpus.map((e) => `${e.file} ${e.law}: ${e.count} example${e.count === 1 ? '' : 's'}`).join('\n')}\n`);
+        return 0;
+    }
+    if (command === 'ui') {
+        const chosen = lawFiles(cwd, flags, files);
+        if (chosen.length === 0) {
+            process.stderr.write('no laws files found (looking for *.laws.ts)\n');
+            return 1;
+        }
+        return serveUi({
+            cwd,
+            port: Number(flags.get('port') ?? 51205),
+            open: !flags.has('no-open'),
+            appWindow: !flags.has('tab'),
+            // A watcher sees a browser page only if it stays as the law left it for a moment.
+            run: (only, onEvent, laws) => check({ ...options(cwd, flags, only ?? chosen), only: laws, onEvent, browserPauseMs: 120 }, !flags.has('proposed')),
+            log: (line) => process.stdout.write(`${line}\n`),
+        });
+    }
+    return flags.has('watch') ? watchChecks(cwd, flags, files) : runCheck(cwd, flags, files);
+}

package/dist/compile.d.ts

@@ -0,0 +1,15 @@
+import type { ManifestLaw } from './types.ts';
+export interface BuildResult {
+    outDir: string;
+    /** Diagnostics the compiler printed; empty when the files type-check. */
+    diagnostics: string;
+    ok: boolean;
+}
+export declare function readManifest(compiler: string, files: string[], cwd: string): ManifestLaw[];
+/**
+ * The compiler flags for the `compilerOptions` of tslaws.json. Only the supported keys pass; anything else is an
+ * error rather than an arbitrary flag handed to the compiler. `strict` is the one default these can override.
+ */
+export declare function compilerFlags(options: Record<string, unknown> | undefined): string[];
+/** Compiles `files` to CommonJS plus declarations in `.tslaws/out` under `cwd`, so `node_modules` still resolves. */
+export declare function build(compiler: string, files: string[], cwd: string): BuildResult;

package/dist/compile.js

@@ -0,0 +1,142 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { readConfig } from "./coverage.js";
+/**
+ * Runs the compiler, trying again when the system could not start it. On Windows a freshly built executable can be
+ * briefly unavailable (a scanner holds it, the machine is out of handles), which surfaces as ENOENT or UNKNOWN.
+ */
+function launch(compiler, args, options) {
+    let run = spawnSync(compiler, args, options);
+    for (let attempt = 0; attempt < 4 && run.error !== undefined && /UNKNOWN|EBUSY|EAGAIN|EMFILE/.test(String(run.error)); attempt += 1) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 250 * (attempt + 1));
+        run = spawnSync(compiler, args, options);
+    }
+    return run;
+}
+/** The compiler finds its lib files in TSC_TS_LIB_DIR; without it, use the TypeScript 7 libs scriptc ships. */
+function compilerEnv(cwd, compiler) {
+    if (process.env.TSC_TS_LIB_DIR !== undefined)
+        return process.env;
+    // The npm compiler package keeps the lib files beside the executable.
+    const beside = dirname(compiler);
+    if (existsSync(join(beside, 'lib.d.ts')))
+        return { ...process.env, TSC_TS_LIB_DIR: beside };
+    for (let dir = cwd;; dir = dirname(dir)) {
+        const scope = join(dir, 'node_modules', '@scriptc');
+        if (existsSync(scope)) {
+            for (const entry of readdirSync(scope)) {
+                const lib = join(scope, entry, 'dist', 'lib', 'typescript', 'lib');
+                if (existsSync(join(lib, 'lib.d.ts')))
+                    return { ...process.env, TSC_TS_LIB_DIR: lib };
+            }
+        }
+        if (dirname(dir) === dir)
+            return process.env;
+    }
+}
+/** Lists the laws of `files` with the problems that stop them running. */
+/** Says what to do when the compiler cannot start, in particular when none was found at all. */
+function cannotRun(compiler, error) {
+    if (error.code === 'ENOENT')
+        return `no tsc-laws compiler found (${compiler}): install the tslaws-compiler package for this platform, or set TSC_LAWS_BIN / --compiler to the compiler executable`;
+    return `cannot run ${compiler}: ${error.message}`;
+}
+export function readManifest(compiler, files, cwd) {
+    const run = launch(compiler, ['--laws-manifest', ...files], {
+        cwd,
+        encoding: 'utf8',
+        maxBuffer: 64 << 20,
+        env: compilerEnv(cwd, compiler),
+    });
+    if (run.error !== undefined)
+        throw new Error(cannotRun(compiler, run.error));
+    const text = (run.stdout ?? '').trim();
+    if (text === '')
+        throw new Error(`${compiler} --laws-manifest printed nothing: ${run.stderr ?? ''}`);
+    return JSON.parse(text).laws;
+}
+const stringOptions = ['jsx', 'jsxFactory', 'jsxFragmentFactory', 'jsxImportSource'];
+const booleanOptions = [
+    'experimentalDecorators',
+    'emitDecoratorMetadata',
+    'useDefineForClassFields',
+    'strict',
+    'noUncheckedIndexedAccess',
+    'exactOptionalPropertyTypes',
+    'allowJs',
+    'checkJs',
+];
+const listOptions = ['lib', 'types'];
+const jsxModes = ['react', 'react-jsx', 'react-jsxdev', 'preserve'];
+const supportedOptions = [...stringOptions, ...booleanOptions, ...listOptions];
+/**
+ * The compiler flags for the `compilerOptions` of tslaws.json. Only the supported keys pass; anything else is an
+ * error rather than an arbitrary flag handed to the compiler. `strict` is the one default these can override.
+ */
+export function compilerFlags(options) {
+    const flags = [];
+    for (const [key, value] of Object.entries(options ?? {})) {
+        if (!supportedOptions.includes(key))
+            throw new Error(`tslaws.json compilerOptions: unsupported option "${key}"; supported options are ${supportedOptions.join(', ')}`);
+        const bad = (expected) => new Error(`tslaws.json compilerOptions: "${key}" must be ${expected}, got ${JSON.stringify(value)}`);
+        if (stringOptions.includes(key)) {
+            if (typeof value !== 'string' || value === '')
+                throw bad('a string');
+            if (key === 'jsx' && !jsxModes.includes(value))
+                throw bad(`one of ${jsxModes.join(', ')}`);
+            flags.push(`--${key}`, value);
+        }
+        else if (booleanOptions.includes(key)) {
+            if (typeof value !== 'boolean')
+                throw bad('true or false');
+            flags.push(`--${key}`);
+            if (!value)
+                flags.push('false');
+        }
+        else {
+            if (!Array.isArray(value) || value.some((v) => typeof v !== 'string'))
+                throw bad('an array of strings');
+            flags.push(`--${key}`, value.join(','));
+        }
+    }
+    return flags;
+}
+/** Compiles `files` to CommonJS plus declarations in `.tslaws/out` under `cwd`, so `node_modules` still resolves. */
+export function build(compiler, files, cwd) {
+    const outDir = join(cwd, '.tslaws', 'out');
+    rmSync(outDir, { recursive: true, force: true });
+    mkdirSync(outDir, { recursive: true });
+    // The output is CommonJS whatever the project's own package.json says.
+    writeFileSync(join(outDir, 'package.json'), JSON.stringify({ type: 'commonjs' }));
+    const extra = compilerFlags(readConfig(cwd).compilerOptions);
+    const args = [
+        '--ignoreConfig',
+        '--target',
+        'es2022',
+        '--module',
+        'commonjs',
+        '--moduleResolution',
+        'bundler',
+        ...(extra.includes('--strict') ? [] : ['--strict']),
+        '--skipLibCheck',
+        '--esModuleInterop',
+        '--declaration',
+        '--rootDir',
+        cwd,
+        '--outDir',
+        outDir,
+        ...extra,
+        ...files,
+    ];
+    let run = launch(compiler, args, { cwd, encoding: 'utf8', maxBuffer: 64 << 20, env: compilerEnv(cwd, compiler) });
+    // A compiler that dies without a word (out of memory on a busy machine) is run again; a type error always says so.
+    for (let attempt = 0; attempt < 2 &&
+        run.error === undefined &&
+        run.status !== 0 &&
+        `${run.stdout ?? ''}${run.stderr ?? ''}`.trim() === ''; attempt += 1)
+        run = launch(compiler, args, { cwd, encoding: 'utf8', maxBuffer: 64 << 20, env: compilerEnv(cwd, compiler) });
+    if (run.error !== undefined)
+        throw new Error(cannotRun(compiler, run.error));
+    return { outDir, diagnostics: `${run.stdout ?? ''}${run.stderr ?? ''}`.trim(), ok: run.status === 0 };
+}

package/dist/component.d.ts

@@ -0,0 +1,37 @@
+import { type Queries } from './queries.ts';
+/** What `render` hands back: nothing, an unmount function, or an object that can update and unmount. */
+export type Rendered<P> = void | (() => void) | {
+    update?(props: P): void | Promise<void>;
+    unmount?(): void;
+};
+/** Teaches `mountComponent` one framework. `render` may be async (Angular bootstraps asynchronously). */
+export interface Adapter<C, P> {
+    render(container: HTMLElement, component: C, props: P): Rendered<P> | Promise<Rendered<P>>;
+}
+export interface Mounted<P> {
+    /** The container the component rendered into. */
+    el: HTMLElement;
+    /** The props of the latest render. */
+    props: P;
+    /** Renders again with new props and waits for the DOM to settle. */
+    rerender(next: P): Promise<void>;
+    /** Unmounts now; the end of the law does it anyway. */
+    unmount(): void;
+    /** Queries bound to `el`. */
+    query: Queries;
+}
+/**
+ * Renders `component` with `props` into a fresh container (see `mount`), waits for the DOM to settle, and unmounts at
+ * the end of the law.
+ */
+export declare function mountComponent<C, P>(adapter: Adapter<C, P>, component: C, props: P): Promise<Mounted<P>>;
+/** A callback you can observe: records the arguments of each call. `impl` runs and its result is returned. */
+export declare function spy<A extends unknown[], R>(impl?: (...a: A) => R): ((...a: A) => R) & {
+    calls: A[];
+    count: number;
+};
+/**
+ * The classic component law: rendering is a pure function of props. Renders with `a`, rerenders with `b`, and compares
+ * the markup with a fresh render of `b`.
+ */
+export declare function rendersSame<C, P>(adapter: Adapter<C, P>, component: C, a: P, b: P): Promise<boolean>;

package/dist/component.js

@@ -0,0 +1,99 @@
+/// <reference lib="dom" />
+// Component-level testing: render ONE component in isolation with generated props, through a thin adapter for the
+// framework (or none). tslaws has no framework dependency: the adapters take the framework's functions.
+import { mount, settle } from "./browserApi.js";
+import { within } from "./queries.js";
+/**
+ * Renders `component` with `props` into a fresh container (see `mount`), waits for the DOM to settle, and unmounts at
+ * the end of the law.
+ */
+export async function mountComponent(adapter, component, props) {
+    // Registered with the same per-law cleanup as mount(): the container is removed and the component unmounted.
+    const el = mount(() => () => unmount());
+    let handle = {};
+    let pending = Promise.resolve();
+    let live = true;
+    const adopt = (rendered) => {
+        handle = typeof rendered === 'function' ? { unmount: rendered } : (rendered ?? {});
+    };
+    function unmount() {
+        if (!live)
+            return;
+        live = false;
+        handle.unmount?.();
+    }
+    const start = (p) => {
+        const rendered = adapter.render(el, component, p);
+        if (rendered instanceof Promise)
+            pending = rendered.then(adopt);
+        else
+            adopt(rendered);
+    };
+    start(props);
+    await pending;
+    await settle();
+    const mounted = {
+        el,
+        props,
+        query: within(el),
+        unmount,
+        async rerender(next) {
+            if (handle.update !== undefined)
+                await handle.update(next);
+            else {
+                handle.unmount?.();
+                el.replaceChildren();
+                start(next);
+                await pending;
+            }
+            mounted.props = next;
+            await settle();
+        },
+    };
+    return mounted;
+}
+/** A callback you can observe: records the arguments of each call. `impl` runs and its result is returned. */
+export function spy(impl) {
+    const calls = [];
+    const fn = ((...a) => {
+        calls.push(a);
+        return impl?.(...a);
+    });
+    fn.calls = calls;
+    Object.defineProperty(fn, 'count', { get: () => calls.length, enumerable: true });
+    return fn;
+}
+// Markup with the noise removed that differs between a fresh render and an updated one: comment nodes, empty text,
+// whitespace runs and the bookkeeping attributes frameworks add.
+function normalisedHtml(el) {
+    const copy = el.cloneNode(true);
+    const walker = document.createTreeWalker(copy, NodeFilter.SHOW_COMMENT | NodeFilter.SHOW_TEXT);
+    const drop = [];
+    for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+        if (node.nodeType === Node.COMMENT_NODE || (node.textContent ?? '').trim() === '')
+            drop.push(node);
+    }
+    for (const node of drop)
+        node.parentNode?.removeChild(node);
+    for (const node of [copy, ...Array.from(copy.querySelectorAll('*'))]) {
+        for (const name of node.getAttributeNames()) {
+            if (/^(ng-reflect-|_ng(content|host)-|ng-version$|data-reactroot$|data-react)/.test(name))
+                node.removeAttribute(name);
+        }
+    }
+    return copy.innerHTML.replace(/\s+/g, ' ').replace(/> </g, '><').trim();
+}
+/**
+ * The classic component law: rendering is a pure function of props. Renders with `a`, rerenders with `b`, and compares
+ * the markup with a fresh render of `b`.
+ */
+export async function rendersSame(adapter, component, a, b) {
+    const updated = await mountComponent(adapter, component, a);
+    await updated.rerender(b);
+    const first = normalisedHtml(updated.el);
+    updated.unmount();
+    const fresh = await mountComponent(adapter, component, b);
+    const second = normalisedHtml(fresh.el);
+    fresh.unmount();
+    return first === second;
+}