tslaws 0.0.0-stage → 0.3.2

package/dist/coverage.d.ts

@@ -0,0 +1,40 @@
+import ts from 'typescript';
+import { type E2eConfig } from './e2e.ts';
+export interface CoverageConfig {
+    cover?: string[];
+    /** Compiler options the runner passes to tsc; see `compilerFlags` in compile.ts for the supported keys. */
+    compilerOptions?: Record<string, unknown>;
+    /** End-to-end laws: the app to drive; see `parseE2eConfig`. */
+    e2e?: E2eConfig;
+    /** Run settings; a command line flag beats them and they beat the built-in default. */
+    runs?: number;
+    propertyTimeoutMs?: number;
+    proofTimeoutMs?: number;
+    bound?: number;
+}
+export interface Uncovered {
+    file: string;
+    name: string;
+}
+export interface CoverageReport {
+    uncovered: Uncovered[];
+    /** `file::name` of every function marked `@tslaws-exempt`. */
+    exempt: string[];
+    /** The source files the check covers, for the compiler to emit. */
+    files: string[];
+}
+/** Validates the top level of tslaws.json: known keys only, and the run settings are integers of at least 1. */
+export declare function parseConfig(raw: unknown): CoverageConfig;
+export declare function readConfig(cwd: string): CoverageConfig;
+/** Source files matching the `cover` globs (a leading `!` excludes), minus laws files and declarations. */
+export declare function coverFiles(cwd: string, globs: string[]): string[];
+export interface CoverageInput {
+    cwd: string;
+    outDir: string;
+    lawFiles: string[];
+    /** Files named by the `cover` globs; empty means every module the laws reach. */
+    coverFiles: string[];
+    /** Declarations the compiler emitted for the program. */
+    program: ts.Program;
+}
+export declare function analyzeCoverage(input: CoverageInput): CoverageReport;

package/dist/coverage.js

@@ -0,0 +1,237 @@
+// Coverage: code is checked against the laws only if a law reaches it. Every exported function or class in the
+// covered modules must be reachable from some law through calls, or a person must have exempted it.
+//
+// Covered modules are the `cover` globs of tslaws.json, or, without that file, every module the laws import
+// (directly or through other project modules). A function carrying `@tslaws-exempt` in its doc comment is exempt,
+// but only once the exemption is in tsc-laws.lock, so an agent cannot exempt its own code.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import ts from 'typescript';
+import { parseE2eConfig } from "./e2e.js";
+const settingKeys = ['runs', 'propertyTimeoutMs', 'proofTimeoutMs', 'bound'];
+const configKeys = ['cover', 'compilerOptions', 'e2e', ...settingKeys];
+/** Validates the top level of tslaws.json: known keys only, and the run settings are integers of at least 1. */
+export function parseConfig(raw) {
+    const fail = (message) => {
+        throw new Error(`tslaws.json: ${message}`);
+    };
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return fail('must be a JSON object');
+    const object = raw;
+    for (const key of Object.keys(object)) {
+        if (key !== '$schema' && !configKeys.includes(key))
+            fail(`unknown option "${key}"; supported options are ${configKeys.join(', ')}`);
+    }
+    for (const key of settingKeys) {
+        const value = object[key];
+        if (value !== undefined && (typeof value !== 'number' || !Number.isInteger(value) || value < 1))
+            fail(`"${key}" must be an integer of at least 1, got ${JSON.stringify(value)}`);
+    }
+    return object;
+}
+export function readConfig(cwd) {
+    const path = join(cwd, 'tslaws.json');
+    if (!existsSync(path))
+        return {};
+    const config = parseConfig(JSON.parse(readFileSync(path, 'utf8')));
+    if (config.e2e !== undefined)
+        config.e2e = parseE2eConfig(config.e2e);
+    return config;
+}
+function globToRegExp(glob) {
+    let out = '';
+    for (let i = 0; i < glob.length; i += 1) {
+        const ch = glob[i];
+        if (ch === '*' && glob[i + 1] === '*') {
+            out += '.*';
+            i += glob[i + 2] === '/' ? 2 : 1;
+        }
+        else if (ch === '*')
+            out += '[^/]*';
+        else if (ch === '?')
+            out += '[^/]';
+        else
+            out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^${out}$`);
+}
+/** Source files matching the `cover` globs (a leading `!` excludes), minus laws files and declarations. */
+export function coverFiles(cwd, globs) {
+    // Plain JavaScript sources are covered only when the project compiles them (`allowJs`).
+    const js = readConfig(cwd).compilerOptions?.allowJs === true;
+    const include = globs.filter((g) => !g.startsWith('!')).map(globToRegExp);
+    const exclude = globs.filter((g) => g.startsWith('!')).map((g) => globToRegExp(g.slice(1)));
+    const found = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir)) {
+            if (entry === 'node_modules' || entry === '.tslaws' || entry === '.git')
+                continue;
+            const full = join(dir, entry);
+            if (statSync(full).isDirectory())
+                walk(full);
+            else {
+                const file = relative(cwd, full).replaceAll('\\', '/');
+                if (!(js ? /\.(ts|tsx|mts|cts|js)$/ : /\.(ts|tsx|mts|cts)$/).test(file))
+                    continue;
+                if (/\.d\.(ts|mts|cts)$/.test(file) || /\.laws\.ts$/.test(file))
+                    continue;
+                if (include.some((r) => r.test(file)) && !exclude.some((r) => r.test(file)))
+                    found.push(file);
+            }
+        }
+    };
+    walk(cwd);
+    return found.sort();
+}
+function parseModule(jsFile, modules) {
+    const known = modules.get(jsFile);
+    if (known !== undefined)
+        return known;
+    if (!existsSync(jsFile))
+        return undefined;
+    const text = readFileSync(jsFile, 'utf8');
+    const source = ts.createSourceFile(jsFile, text, ts.ScriptTarget.ES2022, true, ts.ScriptKind.JS);
+    const module = { nodes: new Map(), imports: new Map() };
+    modules.set(jsFile, module);
+    const exempt = (statement) => (ts.getLeadingCommentRanges(text, statement.getFullStart()) ?? []).some((r) => text.slice(r.pos, r.end).includes('@tslaws-exempt'));
+    for (const statement of source.statements) {
+        if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name !== undefined)
+            module.nodes.set(statement.name.text, { name: statement.name.text, body: statement, exempt: exempt(statement) });
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || declaration.initializer === undefined)
+                continue;
+            const init = declaration.initializer;
+            if (ts.isArrowFunction(init) || ts.isFunctionExpression(init) || ts.isClassExpression(init))
+                module.nodes.set(declaration.name.text, { name: declaration.name.text, body: init, exempt: exempt(statement) });
+            else if (ts.isCallExpression(init) &&
+                ts.isIdentifier(init.expression) &&
+                init.expression.text === 'require' &&
+                init.arguments.length === 1 &&
+                ts.isStringLiteral(init.arguments[0]) &&
+                init.arguments[0].text.startsWith('.')) {
+                const base = resolve(dirname(jsFile), init.arguments[0].text);
+                module.imports.set(declaration.name.text, /\.[cm]?js$/.test(base) ? base : `${base}.js`);
+            }
+        }
+    }
+    return module;
+}
+function exportedFunctions(program, dts) {
+    const checker = program.getTypeChecker();
+    const source = program.getSourceFile(dts);
+    const moduleSymbol = source === undefined ? undefined : checker.getSymbolAtLocation(source);
+    if (moduleSymbol === undefined)
+        return [];
+    const names = [];
+    for (const symbol of checker.getExportsOfModule(moduleSymbol)) {
+        const target = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+        if (target.flags & (ts.SymbolFlags.Function | ts.SymbolFlags.Class))
+            names.push(symbol.getName());
+        else if (target.flags & ts.SymbolFlags.Variable) {
+            const declaration = target.valueDeclaration ?? target.declarations?.[0];
+            if (declaration !== undefined &&
+                checker.getTypeOfSymbolAtLocation(target, declaration).getCallSignatures().length > 0)
+                names.push(symbol.getName());
+        }
+    }
+    return names;
+}
+const jsOf = (outDir, file) => join(outDir, file.replace(/\.(ts|tsx|mts|cts)$/, '.js'));
+const dtsOf = (outDir, file) => join(outDir, file.replace(/\.(ts|tsx|mts|cts|js)$/, '.d.ts'));
+/** The project source behind an emitted module: TypeScript, JSX or, with `allowJs`, JavaScript. */
+const sourceOf = (outDir, cwd, js) => {
+    const rel = relative(outDir, js).replaceAll('\\', '/');
+    if (rel === '')
+        return relative(cwd, js);
+    const base = rel.replace(/\.js$/, '');
+    const candidates = [`${base}.ts`, `${base}.tsx`, `${base}.js`];
+    return candidates.find((c) => existsSync(join(cwd, c))) ?? candidates[0];
+};
+export function analyzeCoverage(input) {
+    const modules = new Map();
+    const key = (js, name) => `${js}::${name}`;
+    const edges = (js, node) => {
+        const module = modules.get(js);
+        const out = [];
+        const visit = (n) => {
+            if (ts.isIdentifier(n) && module.nodes.has(n.text) && n.text !== node.name)
+                out.push(key(js, n.text));
+            if (ts.isPropertyAccessExpression(n) && ts.isIdentifier(n.expression)) {
+                const target = module.imports.get(n.expression.text);
+                if (target !== undefined) {
+                    parseModule(target, modules);
+                    out.push(key(target, n.name.text));
+                }
+            }
+            ts.forEachChild(n, visit);
+        };
+        visit(node.body);
+        return out;
+    };
+    // Everything a law calls, transitively, is checked by that law.
+    const reached = new Set();
+    const queue = [];
+    const lawJs = input.lawFiles.map((f) => jsOf(input.outDir, f));
+    for (const js of lawJs) {
+        const module = parseModule(js, modules);
+        if (module === undefined)
+            continue;
+        for (const node of module.nodes.values())
+            queue.push(key(js, node.name));
+    }
+    while (queue.length > 0) {
+        const current = queue.pop();
+        if (reached.has(current))
+            continue;
+        reached.add(current);
+        const [js, name] = current.split('::');
+        const module = parseModule(js, modules);
+        const node = module?.nodes.get(name);
+        if (node !== undefined)
+            for (const next of edges(js, node))
+                if (!reached.has(next))
+                    queue.push(next);
+    }
+    // The modules in scope: the cover globs, or every project module the laws import.
+    const scope = new Set();
+    if (input.coverFiles.length > 0)
+        for (const f of input.coverFiles)
+            scope.add(jsOf(input.outDir, f));
+    else {
+        const visit = (js) => {
+            const module = parseModule(js, modules);
+            if (module === undefined)
+                return;
+            for (const target of module.imports.values()) {
+                if (!scope.has(target) && !lawJs.includes(target)) {
+                    scope.add(target);
+                    visit(target);
+                }
+            }
+        };
+        for (const js of lawJs)
+            visit(js);
+    }
+    const uncovered = [];
+    const exempt = [];
+    for (const js of scope) {
+        const module = parseModule(js, modules);
+        if (module === undefined)
+            continue;
+        const file = sourceOf(input.outDir, input.cwd, js);
+        for (const name of exportedFunctions(input.program, dtsOf(input.outDir, file))) {
+            const node = module.nodes.get(name);
+            if (node?.exempt === true)
+                exempt.push(`${file}::${name}`);
+            else if (!reached.has(key(js, name)))
+                uncovered.push({ file, name });
+        }
+    }
+    return {
+        uncovered: uncovered.sort((a, b) => `${a.file}::${a.name}`.localeCompare(`${b.file}::${b.name}`)),
+        exempt: exempt.sort(),
+        files: [...scope].map((js) => sourceOf(input.outDir, input.cwd, js)).sort(),
+    };
+}

package/dist/e2e.d.ts

@@ -0,0 +1,46 @@
+import type * as fc from 'fast-check';
+import { type PropertyOutcome } from './property.ts';
+import type { CheckOptions } from './types.ts';
+/** `a.e2e.laws.ts` is an accepted alias: it always drives a running app. */
+export declare function isE2eLawFile(file: string): boolean;
+/** Whether a law file imports both helper sets, which would put one file at two levels. */
+export declare function importsBoth(text: string): boolean;
+/**
+ * The level a law file runs at. `*.browser.laws.ts` is a component law (in a page) unless it imports from
+ * `tslaws/e2e`, which makes it an end-to-end law (in Node, driving a running app); `*.e2e.laws.ts` is always e2e.
+ */
+export declare function lawMode(file: string, text: string): 'node' | 'component' | 'e2e';
+export interface E2eServerConfig {
+    /** Shell command that starts the app. It runs from your project, like a package script. */
+    command: string;
+    /** Address that answers (any status below 500) once the app is up. */
+    url: string;
+    /** How long to wait for `url`. Default 60000. */
+    timeoutMs?: number;
+    /** Use a server that already answers at `url` instead of starting one. Default false. */
+    reuseExisting?: boolean;
+    /** Directory the command runs in, relative to the project. Default the project. */
+    cwd?: string;
+}
+export interface E2eConfig {
+    baseURL?: string;
+    server?: E2eServerConfig;
+    /** Generated inputs per law. Default 10. */
+    runs?: number;
+    /** Longest a law may take overall. Default 120000. */
+    timeoutMs?: number;
+}
+/** Checks the `e2e` section of tslaws.json; unknown keys and wrong types are errors that say where. */
+export declare function parseE2eConfig(raw: unknown): E2eConfig;
+/** Stops the server this run started, if any. Safe to call more than once. */
+export declare function stopServer(): Promise<void>;
+/** Starts (once per check run) the server of `config` and waits for it; resolves to the base URL. */
+export declare function ensureServer(config: E2eConfig, cwd: string): Promise<string>;
+export interface E2eLaw {
+    file: string;
+    name: string;
+    fn: (...args: unknown[]) => unknown;
+    generators: fc.Arbitrary<unknown>[];
+}
+/** Property-tests one end-to-end law; `'timeout'` when it does not finish within the time limit. */
+export declare function runE2eLaw(law: E2eLaw, options: CheckOptions, baseURL: string, timeoutMs: number): Promise<PropertyOutcome | 'timeout'>;

package/dist/e2e.js

@@ -0,0 +1,322 @@
+// End-to-end laws: a whole running app, driven from outside through a real browser. The law runs in this process;
+// the runner starts the app's dev server, gives every generated input a fresh browser context, and shrinks failures
+// to a minimal counterexample like any other law.
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { launch, resolveEngine } from "./browser.js";
+import { withE2e } from "./e2eApi.js";
+import { runProperty, summarise } from "./property.js";
+/** `a.e2e.laws.ts` is an accepted alias: it always drives a running app. */
+export function isE2eLawFile(file) {
+    return /\.e2e\.laws\.[cm]?ts$/.test(file);
+}
+const importsOf = (module) => new RegExp(`(?:from|import)\\s*['"]${module}['"]`);
+/** Whether a law file imports both helper sets, which would put one file at two levels. */
+export function importsBoth(text) {
+    return importsOf('tslaws/e2e').test(text) && importsOf('tslaws/browser').test(text);
+}
+/**
+ * The level a law file runs at. `*.browser.laws.ts` is a component law (in a page) unless it imports from
+ * `tslaws/e2e`, which makes it an end-to-end law (in Node, driving a running app); `*.e2e.laws.ts` is always e2e.
+ */
+export function lawMode(file, text) {
+    if (isE2eLawFile(file))
+        return 'e2e';
+    if (!/\.browser\.laws\.[cm]?ts$/.test(file))
+        return 'node';
+    return importsOf('tslaws/e2e').test(text) ? 'e2e' : 'component';
+}
+const topKeys = ['baseURL', 'server', 'runs', 'timeoutMs'];
+const serverKeys = ['command', 'url', 'timeoutMs', 'reuseExisting', 'cwd'];
+/** Checks the `e2e` section of tslaws.json; unknown keys and wrong types are errors that say where. */
+export function parseE2eConfig(raw) {
+    const fail = (message) => {
+        throw new Error(`tslaws.json e2e: ${message}`);
+    };
+    const object = (value, where) => {
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            fail(`${where} must be an object`);
+        return value;
+    };
+    const text = (value, where) => {
+        if (typeof value !== 'string' || value === '')
+            fail(`${where} must be a non-empty string`);
+        return value;
+    };
+    const count = (value, where) => {
+        if (typeof value !== 'number' || !Number.isInteger(value) || value < 1)
+            fail(`${where} must be a positive integer`);
+        return value;
+    };
+    const section = object(raw, 'it');
+    for (const name of Object.keys(section))
+        if (!topKeys.includes(name))
+            fail(`unknown option "${name}"; supported options are ${topKeys.join(', ')}`);
+    const config = {};
+    if (section.baseURL !== undefined)
+        config.baseURL = text(section.baseURL, '"baseURL"');
+    if (section.runs !== undefined)
+        config.runs = count(section.runs, '"runs"');
+    if (section.timeoutMs !== undefined)
+        config.timeoutMs = count(section.timeoutMs, '"timeoutMs"');
+    if (section.server !== undefined) {
+        const server = object(section.server, '"server"');
+        for (const name of Object.keys(server))
+            if (!serverKeys.includes(name))
+                fail(`unknown option "server.${name}"; supported options are ${serverKeys.join(', ')}`);
+        const parsed = {
+            command: text(server.command, '"server.command"'),
+            url: text(server.url, '"server.url"'),
+        };
+        if (server.timeoutMs !== undefined)
+            parsed.timeoutMs = count(server.timeoutMs, '"server.timeoutMs"');
+        if (server.reuseExisting !== undefined) {
+            if (typeof server.reuseExisting !== 'boolean')
+                fail('"server.reuseExisting" must be true or false');
+            parsed.reuseExisting = server.reuseExisting;
+        }
+        if (server.cwd !== undefined)
+            parsed.cwd = text(server.cwd, '"server.cwd"');
+        config.server = parsed;
+    }
+    return config;
+}
+// ---- the dev server ----
+let child;
+let started;
+let startedFor;
+/** Whether `url` answers with anything but a server error. */
+async function answers(url) {
+    try {
+        const response = await fetch(url, { redirect: 'manual', signal: AbortSignal.timeout(2000) });
+        await response.body?.cancel();
+        return response.status < 500;
+    }
+    catch {
+        return false;
+    }
+}
+/** Kills `process` and everything it started. */
+function killTree(process_) {
+    const pid = process_.pid;
+    if (pid === undefined || process_.exitCode !== null || process_.signalCode !== null)
+        return;
+    if (process.platform === 'win32')
+        spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { windowsHide: true });
+    else {
+        try {
+            process.kill(-pid, 'SIGTERM');
+        }
+        catch {
+            // Already gone.
+        }
+        setTimeout(() => {
+            try {
+                process.kill(-pid, 'SIGKILL');
+            }
+            catch {
+                // Already gone.
+            }
+        }, 2000).unref();
+    }
+}
+const onExit = () => {
+    if (child !== undefined)
+        killTree(child);
+};
+const onSignal = () => {
+    onExit();
+    process.exit(130);
+};
+/** Stops the server this run started, if any. Safe to call more than once. */
+export async function stopServer() {
+    const running = child;
+    child = undefined;
+    started = undefined;
+    startedFor = undefined;
+    process.off('exit', onExit);
+    process.off('SIGINT', onSignal);
+    process.off('SIGTERM', onSignal);
+    if (running === undefined)
+        return;
+    const gone = new Promise((done) => {
+        if (running.exitCode !== null || running.signalCode !== null)
+            done();
+        else
+            running.once('exit', () => done());
+    });
+    killTree(running);
+    await Promise.race([gone, new Promise((done) => setTimeout(done, 5000))]);
+}
+/** Starts (once per check run) the server of `config` and waits for it; resolves to the base URL. */
+export async function ensureServer(config, cwd) {
+    const server = config.server;
+    const baseURL = config.baseURL ?? server?.url;
+    if (baseURL === undefined)
+        throw new Error('tslaws.json e2e: set "baseURL" or "server" for end-to-end laws');
+    if (server === undefined)
+        return baseURL;
+    if (started === undefined || startedFor !== server.command) {
+        startedFor = server.command;
+        started = startServer(server, cwd);
+    }
+    await started;
+    return baseURL;
+}
+async function startServer(server, cwd) {
+    const alive = await answers(server.url);
+    if (alive) {
+        if (server.reuseExisting === true)
+            return;
+        throw new Error(`${server.url} already answers, so \`${server.command}\` would clash with it: stop that server, or set e2e.server.reuseExisting to use it`);
+    }
+    const process_ = spawn(server.command, {
+        cwd: resolve(cwd, server.cwd ?? '.'),
+        shell: true,
+        detached: process.platform !== 'win32',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+    });
+    child = process_;
+    process.once('exit', onExit);
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    let output = '';
+    const keep = (chunk) => {
+        output = (output + chunk.toString()).slice(-2000);
+    };
+    process_.stdout?.on('data', keep);
+    process_.stderr?.on('data', keep);
+    let ended;
+    process_.once('error', (error) => (ended = `could not start: ${error.message}`));
+    process_.once('exit', (code, signal) => (ended = `exited with ${code ?? signal}`));
+    const timeoutMs = server.timeoutMs ?? 60000;
+    const deadline = Date.now() + timeoutMs;
+    try {
+        while (!(await answers(server.url))) {
+            const tail = output.trim() === '' ? '' : `\n${output.trim().split('\n').slice(-8).join('\n')}`;
+            if (ended !== undefined)
+                throw new Error(`server \`${server.command}\` ${ended} before ${server.url} answered${tail}`);
+            if (Date.now() > deadline)
+                throw new Error(`server \`${server.command}\` did not answer at ${server.url} within ${timeoutMs / 1000}s${tail}`);
+            await new Promise((done) => setTimeout(done, 200));
+        }
+    }
+    catch (error) {
+        await stopServer();
+        throw error;
+    }
+}
+/** A browser that died under the machine, as opposed to a law that failed. */
+const crashed = /Target (?:page, context or browser has been closed|crashed)|Page crashed|browser has been closed/;
+/** Runs `law` once in a fresh context; `keep` leaves the page open for a photograph. A crashed browser tab is tried again, twice at most. */
+async function runOnce(law, args, contextOf, baseURL, options, track, keep) {
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            return await runAttempt(law, args, contextOf, baseURL, options, track, keep);
+        }
+        catch (error) {
+            if (attempt >= 2 || !crashed.test(error instanceof Error ? error.message : String(error)))
+                throw error;
+        }
+    }
+}
+async function runAttempt(law, args, contextOf, baseURL, options, track, keep) {
+    const context = await contextOf();
+    let closing = true;
+    try {
+        const page = await context.newPage();
+        track(page);
+        if (keep !== undefined) {
+            keep.page = page;
+            keep.context = context;
+            closing = false;
+        }
+        return await withE2e({ context, page, baseURL, cwd: options.cwd, onPage: track }, () => law.fn(...args));
+    }
+    finally {
+        if (closing)
+            await context.close().catch(() => undefined);
+    }
+}
+/** Property-tests one end-to-end law; `'timeout'` when it does not finish within the time limit. */
+export async function runE2eLaw(law, options, baseURL, timeoutMs) {
+    const browser = await launch(resolveEngine(options.browser));
+    const open = new Set();
+    const contextOf = async () => {
+        const context = await browser.newContext({ viewport: { width: 1000, height: 720 } });
+        open.add(context);
+        context.once('close', () => open.delete(context));
+        return context;
+    };
+    let timedOut = false;
+    let latest;
+    const track = (page) => {
+        latest = page;
+    };
+    // While someone watches, photograph the newest page a few times a second.
+    let framing = false;
+    const frames = options.onEvent
+        ? setInterval(() => {
+            const page = latest;
+            if (framing || page === undefined || page.isClosed())
+                return;
+            framing = true;
+            page
+                .screenshot({ type: 'jpeg', quality: 55, timeout: 2000 })
+                .then((jpeg) => options.onEvent?.({ type: 'frame', file: law.file, name: law.name, jpeg }))
+                .catch(() => undefined)
+                .finally(() => (framing = false));
+        }, 120)
+        : undefined;
+    let timer;
+    const limit = new Promise((done) => {
+        timer = setTimeout(() => {
+            timedOut = true;
+            done('timeout');
+        }, timeoutMs);
+    });
+    const call = async (...args) => {
+        if (timedOut)
+            throw new Error('timed out');
+        return runOnce(law, args, contextOf, baseURL, options, track);
+    };
+    try {
+        const finished = await Promise.race([runProperty(call, law.generators, options), limit]);
+        if (finished === 'timeout')
+            return 'timeout';
+        const outcome = summarise(finished, options);
+        if (finished.failed && finished.counterexample !== null)
+            outcome.screenshot = await capture(law, finished.counterexample, contextOf, baseURL, options, track);
+        return outcome;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (frames !== undefined)
+            clearInterval(frames);
+        latest = undefined;
+        // A law that never finishes leaves its pages open; closing the contexts frees them.
+        await Promise.all([...open].map((context) => context.close().catch(() => undefined)));
+    }
+}
+/** Runs the counterexample once more, leaves the page as the law left it, and photographs it. Best effort. */
+async function capture(law, args, contextOf, baseURL, options, track) {
+    const kept = {};
+    try {
+        await runOnce(law, args, contextOf, baseURL, options, track, kept).catch(() => undefined);
+        if (kept.page === undefined || kept.page.isClosed())
+            return undefined;
+        const relative = `.tslaws/screenshots/${law.name.replace(/[^\w-]/g, '_')}.png`;
+        mkdirSync(join(options.cwd, '.tslaws/screenshots'), { recursive: true });
+        await kept.page.screenshot({ path: join(options.cwd, relative), timeout: 10000 });
+        return relative;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await kept.context?.close().catch(() => undefined);
+    }
+}