tslaws 0.6.4 → 0.7.0

package/dist/cli.js

@@ -1,22 +1,28 @@
 import { createInterface } from 'node:readline/promises';
-import { readdirSync, statSync, watch } from 'node:fs';
+import { readFileSync, 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 { discoverLaws, discoverProposals, ignoredDirs } from "./lawFiles.js";
+import { isProposedLawFile } from "./lawNames.js";
 import { init, nextStep } from "./init.js";
+import { listLawFiles, renderList } from "./list.js";
 import { serveMcp } from "./mcp.js";
-import { promoteFiles } from "./promote.js";
+import { promoteFiles, promoteProposal } from "./promote.js";
+import { addProposal, ProposalError } from "./proposals.js";
 import { clearCorpus, listCorpus } from "./regressions.js";
 import { reporterNames, reportAs } from "./reporters.js";
 import { readConfig } from "./coverage.js";
+import { migrateCommand, migrateUsage } from "./migrate/index.js";
 import { mutate, renderMutation } from "./mutate.js";
 import { mutateDefaults, resolveSettings } from "./settings.js";
 import { serveUi } from "./ui.js";
 import { acceptGate, defaultDuration, describeGrants, fileHash, grantFor, logDelegatedAccept, parseDuration, personOnly, revokeFor, } from "./delegation.js";
 import { writeLock } from "./lock.js";
+import { lockLevels } from "./lawKinds.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|ndjson] [--law NAME[,NAME]] [--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
@@ -26,10 +32,14 @@ tslaws accept [files...]     record the current laws in tsc-laws.lock (people on
 tslaws delegate grant [--for 1h|8h|1d|7d] [--root DIR]   lend accept to an agent for a limited time (people only; default 8h, max 7d)
 tslaws delegate revoke [--root DIR]   withdraw the delegation for a project (people only)
 tslaws delegate status        list delegations and when they end
-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)
+tslaws propose <file.ts> [--from PATH]   write a proposal into .tslaws/proposals/ from PATH or stdin (outside the tree, git-ignored; never touches the lock or any other file)
+tslaws promote <proposal> [--to PATH]   move a proposal from .tslaws/proposals/ into the tree at a path you confirm (people only: needs a terminal; run accept afterwards). In-tree *.proposed.laws.ts files (the usual proposals) promote with --all or by name
+tslaws list [--json]   the laws files and proposals of the project: the level each runs at (from its name, or its imports with levels: imports) and whether it is accepted, unaccepted or proposed (reads files and the lock; runs nothing)
+tslaws mcp [--compiler PATH]   serve check, check_proposed, explain and propose as Model Context Protocol tools on stdio (cannot accept, promote or touch the lock)
+${migrateUsage}
 
-Without files, every *.laws.ts under the current directory is checked (*.proposed.laws.ts only with --proposed).
+Without files, every *.laws.ts under the current directory (and every file the "laws" globs of tslaws.json pick that declares a law) is checked; with --proposed, the in-tree *.proposed.laws.ts files are (and any proposals in .tslaws/proposals/), with no lock and no coverage gate.
+A laws file\'s level comes from its name by default: *.browser.laws.ts is a browser law, *.e2e.laws.ts an end-to-end law, anything else runs in Node. With "levels": "imports" in tslaws.json it comes from the import graph instead (tslaws/browser, tslaws/adapters/* or tslaws/e2e, directly or through the file\'s own modules), and the names are hints.
 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), github (workflow annotations; appends a table to $GITHUB_STEP_SUMMARY) or ndjson (one JSON event per line as the check proceeds, then the report; for editors)
@@ -37,23 +47,9 @@ Exit status is 0 only when every law is proved, bounded or tested and nothing is
   --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();
+    return proposed ? [...discoverLaws(cwd, true), ...discoverProposals(cwd)] : discoverLaws(cwd, false);
 }
 function parse(args) {
     const flags = new Map();
@@ -73,6 +69,9 @@ function parse(args) {
         'max',
         'for',
         'root',
+        'to',
+        'from',
+        'out',
     ]);
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
@@ -92,6 +91,9 @@ function parse(args) {
                 arg === 'regressions' ||
                 arg === 'mcp' ||
                 arg === 'promote' ||
+                arg === 'propose' ||
+                arg === 'list' ||
+                arg === 'migrate' ||
                 arg === 'delegate'))
             command = arg;
         else
@@ -146,6 +148,10 @@ function render(report, flags) {
         text += `${report.compileDiagnostics}\n\n`;
     if (report.lockMissing)
         text += 'tsc-laws.lock is missing: a person must run `tslaws accept`\n\n';
+    for (const notice of report.notices)
+        text += `notice: ${notice}\n`;
+    if (report.notices.length > 0)
+        text += '\n';
     if (flags.has('summary')) {
         for (const result of report.results)
             if (!passing.has(result.status))
@@ -201,10 +207,14 @@ async function runCheck(cwd, flags, files) {
     process.stdout.write(render(report, flags));
     return report.ok ? 0 : 1;
 }
-function watched(filename) {
+export function watched(filename) {
     if (filename === null || !filename.endsWith('.ts'))
         return false;
-    return !filename.split(/[\\/]/).some((part) => ignoredDirs.has(part));
+    const parts = filename.split(/[\\/]/);
+    // The proposals directory is watched (a saved proposal reruns `check --proposed`); the rest of .tslaws is not.
+    if (parts[0] === '.tslaws' && parts[1] === 'proposals' && !parts.slice(2, -1).some((p) => ignoredDirs.has(p)))
+        return true;
+    return !parts.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) {
@@ -270,16 +280,22 @@ export async function acceptCommand(cwd, flags, files, ctx) {
     out(`${laws.length} laws in ${chosen.length} files:\n${laws.map((l) => `  ${l.file}:${l.line} ${l.name}`).join('\n')}\n`);
     if (!gate.delegated) {
         const rl = createInterface({ input: process.stdin, output: process.stdout });
-        const answer = await rl.question('Type ACCEPT to write tsc-laws.lock: ');
+        const answer = await rl.question('Write tsc-laws.lock? Type accept, yes or y to confirm: ');
         rl.close();
-        if (answer.trim() !== 'ACCEPT')
+        if (!['accept', 'yes', 'y'].includes(answer.trim().toLowerCase())) {
+            out('Nothing written: the answer was not accept, yes or y. Run `tslaws accept` again to retry.\n');
             return 1;
+        }
     }
     const before = fileHash(opts.lockFile);
     const exempt = exemptionsOf(opts);
     if (exempt.length > 0)
         out(`exempt from coverage:\n${exempt.map((e) => `  ${e}`).join('\n')}\n`);
-    writeLock(opts.lockFile, laws, exempt);
+    // With levels from imports the lock records each laws file's resolved level, so a helper that starts importing
+    // tslaws/browser reads as tampered until a person accepts again. By name (the default) the lock is unchanged.
+    const mode = readConfig(cwd).levels ?? 'names';
+    const levels = lockLevels(cwd, laws, mode);
+    writeLock(opts.lockFile, laws, exempt, levels);
     out('tsc-laws.lock written\n');
     if (gate.delegated) {
         logDelegatedAccept(cwd, gate.grant, before, fileHash(opts.lockFile), ctx.now ?? new Date());
@@ -333,6 +349,105 @@ function delegateCommand(cwd, action, flags, ctx) {
     out(`accept is lent to agents for ${granted.root} until ${granted.expires}\n`);
     return 0;
 }
+const readStdin = async () => {
+    let text = '';
+    for await (const chunk of process.stdin)
+        text += String(chunk);
+    return text;
+};
+/**
+ * `tslaws propose <file> [--from PATH]`: writes a proposal into `.tslaws/proposals/` from `--from PATH` or from stdin.
+ * Anyone may run it, agents included: it writes only that directory and never touches the lock or the tree.
+ */
+export async function proposeCommand(cwd, flags, files, ctx) {
+    const out = ctx.out ?? stdoutWrite;
+    const err = ctx.err ?? stderrWrite;
+    const [file] = files;
+    if (file === undefined || files.length > 1) {
+        err('usage: tslaws propose <file.ts> [--from PATH]   (the proposal comes from PATH, or from stdin)\n');
+        return 1;
+    }
+    const from = flags.get('from');
+    if (from === true || from === '') {
+        err('--from takes a path\n');
+        return 1;
+    }
+    if (from === undefined && ctx.isTTY && ctx.stdin === undefined) {
+        err('pipe the proposal in on stdin, or name a file with --from PATH\n');
+        return 1;
+    }
+    try {
+        const source = from === undefined ? await (ctx.stdin ?? readStdin)() : readFileSync(resolve(cwd, from), 'utf8');
+        const written = addProposal(cwd, file, source);
+        out(`${written.file}: ${written.laws.length} law${written.laws.length === 1 ? '' : 's'} (${written.laws.join(', ')})\n` +
+            `Try it with \`tslaws check --proposed\`. A proposal protects nothing: a person promotes it with \`tslaws promote ${written.file}\`.\n`);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof ProposalError || error.code === 'ENOENT') {
+            err(`${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
+        throw error;
+    }
+}
+/**
+ * `tslaws promote <proposal> [--to PATH]`: a person moves a proposal out of `.tslaws/proposals/` into the tree. Refused
+ * without a terminal, under CI, as an agent and with TSLAWS_AGENT set; a delegation does not cover it. Never writes the
+ * lock. In-tree `*.proposed.laws.ts` files promote, per law, into the file of the same kind.
+ */
+export async function promoteCommand(cwd, flags, files, ctx) {
+    const out = ctx.out ?? stdoutWrite;
+    const err = ctx.err ?? stderrWrite;
+    if (!personOnly({ isTTY: ctx.isTTY, env: ctx.env })) {
+        err('promote moves laws into the tree and needs a person at a terminal; it will not run here\n');
+        return 1;
+    }
+    const older = discoverLaws(cwd, true);
+    const known = [...discoverProposals(cwd), ...older];
+    const chosen = files.length > 0 ? files : flags.has('all') ? older : [];
+    if (chosen.length === 0) {
+        err(known.length === 0
+            ? 'no proposals found (they live in .tslaws/proposals/)\n'
+            : `name a proposal to promote:\n${known.map((f) => `  ${f}`).join('\n')}\n`);
+        return 1;
+    }
+    const to = flags.get('to');
+    if (to === true || to === '' || (to !== undefined && chosen.length > 1)) {
+        err('--to takes one path, for one proposal\n');
+        return 1;
+    }
+    const rl = ctx.ask === undefined ? createInterface({ input: process.stdin, output: process.stdout }) : undefined;
+    const ask = ctx.ask ?? ((question) => rl.question(question));
+    const checkFile = ctx.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)]));
+        });
+    try {
+        for (const file of chosen) {
+            const rel = relative(cwd, resolve(cwd, file)).replaceAll('\\', '/');
+            if (isProposedLawFile(rel) && !file.startsWith('.tslaws')) {
+                await promoteFiles({ cwd, ask, out, checkFile }, [rel]);
+                continue;
+            }
+            try {
+                await promoteProposal({ cwd, ask, out, checkFile }, file, to);
+            }
+            catch (error) {
+                if (!(error instanceof ProposalError))
+                    throw error;
+                err(`${error.message}\n`);
+                return 1;
+            }
+        }
+    }
+    finally {
+        rl?.close();
+    }
+    return 0;
+}
 export async function main(args) {
     if (args.includes('--help') || args.includes('-h')) {
         process.stdout.write(`${usage}\n`);
@@ -348,39 +463,19 @@ export async function main(args) {
         return acceptCommand(cwd, flags, files, { isTTY: process.stdin.isTTY === true, env: process.env });
     if (command === 'delegate')
         return delegateCommand(cwd, files[0], flags, { isTTY: process.stdin.isTTY === true, env: process.env });
+    if (command === 'migrate')
+        return migrateCommand(cwd, files[0], files.slice(1), flags, (text) => process.stdout.write(text));
     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();
-        }
+    if (command === 'promote')
+        return promoteCommand(cwd, flags, files, { isTTY: process.stdin.isTTY === true, env: process.env });
+    if (command === 'list') {
+        const listed = listLawFiles(cwd);
+        process.stdout.write(flags.has('json') ? `${JSON.stringify({ files: listed }, null, 2)}\n` : renderList(listed));
         return 0;
     }
+    if (command === 'propose')
+        return proposeCommand(cwd, flags, files, { isTTY: process.stdin.isTTY === true, env: process.env });
     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')));

package/dist/compile.d.ts

@@ -1,10 +1,22 @@
+import ts from 'typescript';
 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;
+    /** Names this exact build (laws, options, every file read); set when the compiler ran in-process, so derived results can be kept. */
+    key?: string;
+    /** The program the in-process compiler built, still holding its type checker; not stored with the build cache. */
+    program?: ts.Program;
 }
+/** The compiler name that selects the built-in path: stock TypeScript, with laws written as `law(...)` calls. */
+export declare const builtinCompiler = "builtin";
+/**
+ * Whether these files go through the built-in path. An explicit `builtin` always does; otherwise a project that
+ * still writes `law name(...)` keeps using the tsc-laws compiler, the only parser of that syntax.
+ */
+export declare function usesBuiltin(compiler: string, files: string[], cwd: string): 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

package/dist/compile.js

@@ -1,6 +1,10 @@
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { transformSync } from 'esbuild';
+import ts from 'typescript';
+import { lowerLawFile, usesLegacySyntax } from "./lower.js";
 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
@@ -42,7 +46,63 @@ function cannotRun(compiler, error) {
         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}`;
 }
+/** The compiler name that selects the built-in path: stock TypeScript, with laws written as `law(...)` calls. */
+export const builtinCompiler = 'builtin';
+const slash = (path) => path.replaceAll(String.fromCharCode(92), '/');
+const lowered = new Map();
+/** Lowers `file` (project-relative), reusing the last result while its text is unchanged. */
+function lowerFile(file, cwd) {
+    const text = readFileSync(join(cwd, file), 'utf8');
+    const key = slash(resolve(cwd, file));
+    const cached = lowered.get(key);
+    if (cached?.text === text)
+        return cached.result;
+    const result = lowerLawFile(slash(file), text);
+    lowered.set(key, { text, result });
+    return result;
+}
+/**
+ * Whether the file holds laws: a `.laws.ts` name, or any file the project points at (a "laws" glob, a proposal in
+ * `.tslaws/proposals`) whose text declares a law, as a call or with the keyword.
+ */
+function isLawFile(file, cwd) {
+    if (/\.laws\.tsx?$/.test(file))
+        return true;
+    if (!existsSync(join(cwd, file)))
+        return false;
+    const text = readFileSync(join(cwd, file), 'utf8');
+    return /\blaw\b/.test(text) && (usesLegacySyntax(text) || lowerFile(file, cwd).laws.length > 0);
+}
+/**
+ * Whether these files go through the built-in path. An explicit `builtin` always does; otherwise a project that
+ * still writes `law name(...)` keeps using the tsc-laws compiler, the only parser of that syntax.
+ */
+export function usesBuiltin(compiler, files, cwd) {
+    if (compiler === builtinCompiler)
+        return true;
+    return !files.some((f) => isLawFile(f, cwd) && existsSync(join(cwd, f)) && usesLegacySyntax(readFileSync(join(cwd, f), 'utf8')));
+}
+/**
+ * The tsc-laws compiler runs a project that uses the keyword syntax (`export law name(...)`) and does not know
+ * `law('name', ...)` calls, so a project holding both would silently lose the calls. Say so instead.
+ */
+function assertOneSyntax(files, cwd) {
+    const present = files.filter((f) => isLawFile(f, cwd) && existsSync(join(cwd, f)));
+    const keyword = present.filter((f) => usesLegacySyntax(readFileSync(join(cwd, f), 'utf8')));
+    if (keyword.length === 0)
+        return;
+    const calls = present.filter((f) => lowerFile(f, cwd).laws.length > 0);
+    if (calls.length === 0)
+        return;
+    throw new Error(`this project mixes the two ways of writing a law: ${keyword.join(', ')} use the keyword syntax (\`export law name(...)\`, which needs the tsc-laws compiler) and ${calls.join(', ')} call \`law('name', ...)\`. ` +
+        'Write every law one way: convert the keyword laws to calls to drop the custom compiler, or keep the keyword syntax throughout.');
+}
 export function readManifest(compiler, files, cwd) {
+    if (usesBuiltin(compiler, files, cwd))
+        return files
+            .filter((f) => isLawFile(f, cwd))
+            .flatMap((f) => (existsSync(join(cwd, f)) ? lowerFile(f, cwd).laws : []));
+    assertOneSyntax(files, cwd);
     const run = launch(compiler, ['--laws-manifest', ...files], {
         cwd,
         encoding: 'utf8',
@@ -105,10 +165,6 @@ export function compilerFlags(options) {
 /** 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',
@@ -129,6 +185,16 @@ export function build(compiler, files, cwd) {
         ...extra,
         ...files,
     ];
+    const builtin = usesBuiltin(compiler, files, cwd);
+    const reused = builtin ? cachedBuild(args, files, cwd, outDir) : undefined;
+    if (reused !== undefined)
+        return reused;
+    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' }));
+    if (builtin)
+        return buildBuiltin(args, files, cwd, outDir);
     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 &&
@@ -140,3 +206,138 @@ export function build(compiler, files, cwd) {
         throw new Error(cannotRun(compiler, run.error));
     return { outDir, diagnostics: `${run.stdout ?? ''}${run.stderr ?? ''}`.trim(), ok: run.status === 0 };
 }
+/** Every `node_modules/@types` from `cwd` upwards: where the compiler looks for global declarations by default. */
+function typeRootsOf(cwd) {
+    const roots = [];
+    for (let dir = resolve(cwd);; dir = dirname(dir)) {
+        const candidate = join(dir, 'node_modules', '@types');
+        if (existsSync(candidate))
+            roots.push(candidate);
+        if (dirname(dir) === dir)
+            return roots;
+    }
+}
+/** Compiles in-process with stock TypeScript: law files are lowered in memory, nothing is written next to them. */
+function buildBuiltin(args, files, cwd, outDir) {
+    const at = args.indexOf('--moduleResolution');
+    const parsed = ts.parseCommandLine(at < 0 ? args : [...args.slice(0, at), ...args.slice(at + 2)]);
+    // Types resolve the bundler way, so package `exports` (tslaws/browser) work; the ES output is made CommonJS below.
+    const options = {
+        ...parsed.options,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        noEmitOnError: false,
+        // Every @types package in the tree is a parse the laws rarely need; none is read unless `types` says so or the laws fail
+        // to compile without them (below).
+        ...(parsed.options.types === undefined ? { types: [] } : {}),
+        // The DOM declarations are a megabyte to parse; only laws that run in a page (or an `lib` setting) ask for them.
+        ...(parsed.options.lib === undefined && !files.some((f) => /\.(browser|e2e)\.laws\.[cm]?ts$/.test(f))
+            ? { lib: ['lib.es2022.d.ts'] }
+            : {}),
+    };
+    const overrides = new Map();
+    for (const file of files)
+        if (isLawFile(file, cwd) && existsSync(join(cwd, file)))
+            overrides.set(slash(resolve(cwd, file)), lowerFile(file, cwd).text);
+    const host = ts.createCompilerHost(options);
+    const getSourceFile = host.getSourceFile.bind(host);
+    host.getSourceFile = (name, languageVersion, onError, shouldCreate) => {
+        const text = overrides.get(slash(resolve(name)));
+        return text === undefined
+            ? getSourceFile(name, languageVersion, onError, shouldCreate)
+            : ts.createSourceFile(name, text, languageVersion, true);
+    };
+    const roots = parsed.fileNames.map((f) => resolve(cwd, f));
+    let program = ts.createProgram(roots, options, host);
+    let diagnostics = ts.getPreEmitDiagnostics(program);
+    // An error may only be a global the narrow setup left out (`process`, `document`, a test runner's types): check again
+    // with exactly what the compiler's own defaults include before reporting it, so no law is judged on less than before.
+    if ((options.types !== parsed.options.types || options.lib !== parsed.options.lib) &&
+        diagnostics.some((d) => d.category === ts.DiagnosticCategory.Error)) {
+        // `@types` is looked up from the project, not from wherever the process happens to be (the compiler remembers the first directory it saw).
+        const typeRoots = parsed.options.typeRoots ?? typeRootsOf(cwd);
+        const full = { ...options, types: parsed.options.types, lib: parsed.options.lib, typeRoots };
+        program = ts.createProgram(roots, full, host);
+        diagnostics = ts.getPreEmitDiagnostics(program);
+    }
+    program.emit(undefined, (name, text) => {
+        mkdirSync(dirname(name), { recursive: true });
+        const code = name.endsWith('.js')
+            ? transformSync(text, { format: 'cjs', target: 'es2022', sourcefile: name }).code
+            : text;
+        writeFileSync(name, code);
+    });
+    const text = ts.formatDiagnostics(diagnostics, {
+        getCanonicalFileName: (f) => f,
+        getCurrentDirectory: () => cwd,
+        getNewLine: () => String.fromCharCode(10),
+    });
+    const result = {
+        outDir,
+        diagnostics: text.trim(),
+        ok: diagnostics.every((d) => d.category !== ts.DiagnosticCategory.Error),
+    };
+    Object.defineProperty(result, 'program', { value: program, enumerable: false });
+    saveBuildCache(args, files, cwd, result, program
+        .getSourceFiles()
+        .map((f) => f.fileName)
+        .filter((f) => !overrides.has(slash(resolve(f)))));
+    return result;
+}
+const buildCachePath = (cwd) => join(cwd, '.tslaws', 'build-cache.json');
+function buildKey(args, files, cwd) {
+    const hash = createHash('sha256');
+    hash.update(JSON.stringify([args, ts.version, toolStamp]));
+    for (const file of files)
+        if (isLawFile(file, cwd) && existsSync(join(cwd, file)))
+            hash.update(`
+${file}
+${lowerFile(file, cwd).text}`);
+    return hash.digest('hex');
+}
+/** Changes whenever this compiler code does, so a new tslaws never reuses output made by an old one. */
+const toolStamp = (() => {
+    try {
+        return statSync(new URL(import.meta.url)).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+})();
+function cachedBuild(args, files, cwd, outDir) {
+    try {
+        const cache = JSON.parse(readFileSync(buildCachePath(cwd), 'utf8'));
+        if (cache.base !== buildKey(args, files, cwd) || !existsSync(join(outDir, 'package.json')))
+            return undefined;
+        for (const [file, [size, mtime]] of Object.entries(cache.files)) {
+            const stat = statSync(file);
+            if (stat.size !== size || stat.mtimeMs !== mtime)
+                return undefined;
+        }
+        return cache.result;
+    }
+    catch {
+        return undefined;
+    }
+}
+function saveBuildCache(args, files, cwd, result, read) {
+    try {
+        const stats = {};
+        for (const file of read) {
+            const stat = statSync(file);
+            stats[file] = [stat.size, stat.mtimeMs];
+        }
+        const base = buildKey(args, files, cwd);
+        // The key also names the files read, so anything worked out from this build is dropped when one of them changes.
+        result.key = createHash('sha256').update(base).update(JSON.stringify(stats)).digest('hex');
+        // A failed build is not kept: the file it could not find is not among the files read, so creating it would not
+        // invalidate the entry and the failure would be served again.
+        if (!result.ok)
+            return;
+        const cache = { base, result, files: stats };
+        writeFileSync(buildCachePath(cwd), JSON.stringify(cache));
+    }
+    catch {
+        // No cache is only slower.
+    }
+}

package/dist/coverage.d.ts

@@ -6,6 +6,16 @@ export interface CoverageConfig {
     compilerOptions?: Record<string, unknown>;
     /** End-to-end laws: the app to drive; see `parseE2eConfig`. */
     e2e?: E2eConfig;
+    /**
+     * Extra globs for laws files with other names: any file they match that declares a top-level `export law` is a laws
+     * file, besides every file named `*.laws.ts`. A leading `!` excludes. Default: none.
+     */
+    laws?: string[];
+    /**
+     * Where a laws file's level (Node, browser, end to end) comes from. `names` (the default): the file name
+     * (`*.browser.laws.ts`, `*.e2e.laws.ts`). `imports`: the file's import graph; names are still recognised as hints.
+     */
+    levels?: 'names' | 'imports';
     /** esbuild plugin modules (paths relative to tslaws.json) that teach the browser bundler new source formats. */
     bundlerPlugins?: string[];
     /** Run settings; a command line flag beats them and they beat the built-in default. */
@@ -36,7 +46,9 @@ export interface CoverageInput {
     lawFiles: string[];
     /** Files named by the `cover` globs; empty means every module the laws reach. */
     coverFiles: string[];
-    /** Declarations the compiler emitted for the program. */
+    /** Declarations the compiler emitted for the program, or the program that compiled the code (then `moduleOf` is given). */
     program: ts.Program;
+    /** Where a module's exports are read from, by its path relative to `cwd`; the emitted declaration when absent. */
+    moduleOf?: (file: string) => string;
 }
 export declare function analyzeCoverage(input: CoverageInput): CoverageReport;