tslaws 0.6.4 → 0.7.0

package/README.md

@@ -133,7 +133,7 @@ Anything else leaves the law `tested`, or a `law proved` `open`, with the reason
 
 ## Browser laws
 
-A law file named `*.browser.laws.ts` runs in a real browser (Chrome, Edge or Chromium; `TSLAWS_BROWSER` names another
+A laws file that imports `tslaws/browser` (directly or through a helper module of yours) runs in a real browser (Chrome, Edge or Chromium; `TSLAWS_BROWSER` names another
 executable). Node generates and shrinks the inputs; each one is sent to a page where the compiled law and your code run
 against a live DOM. The law may be `async`. `tslaws/browser` has `mount`, `settle`, `click`, `type` and `fire`, and works with
 any framework or none: `mount(el => render(el))` accepts whatever renders into an element and may return its unmount.
@@ -141,7 +141,7 @@ any framework or none: `mount(el => render(el))` accepts whatever renders into a
 `mountComponent` with the React, Angular, DOM and custom-element adapters tests one component in isolation with props generated from its props type (function-typed props included), plus `spy`, `rendersSame` and Testing Library style queries.
 Browser laws are `tested`, never `proved`. See [docs/laws.md](../../docs/laws.md#browser-laws).
 
-A `*.browser.laws.ts` file that imports `tslaws/e2e` instead is an end-to-end law: it runs in Node and drives your whole running app through a real browser (`page()`, `open`, `newPage`, `route`, `settle`, `accessible`). Configure `e2e.server` in `tslaws.json` and the runner starts and stops your dev server. See [End-to-end laws](../../docs/laws.md#end-to-end-laws).
+A laws file that imports `tslaws/e2e` instead is an end-to-end law (a file that reaches both is an error; by default the level comes from the name, `.browser.laws.ts` or `.e2e.laws.ts`, and `"levels": "imports"` in `tslaws.json` makes the imports decide instead): it runs in Node and drives your whole running app through a real browser (`page()`, `open`, `newPage`, `route`, `settle`, `accessible`). Configure `e2e.server` in `tslaws.json` and the runner starts and stops your dev server. See [End-to-end laws](../../docs/laws.md#end-to-end-laws).
 
 - **Frameworks:** `tslaws.json` `compilerOptions` (`jsx`, `jsxFactory`, `jsxFragmentFactory`, `jsxImportSource`, `experimentalDecorators`,
   `emitDecoratorMetadata`, `useDefineForClassFields`, `lib`, `types`, `strict`, ...) and `.tsx` sources let React, Angular and any DOM
@@ -166,8 +166,8 @@ See [docs/laws.md](../../docs/laws.md#the-dashboard).
 
 `tsc-laws.lock` holds a hash of every law declaration and the list of coverage exemptions. A change, an added law, a removed
 law or a new `@tslaws-exempt` fails the check until a person runs `tslaws accept`, which refuses to run without a terminal,
-under `CI`, or with `TSLAWS_AGENT` set, unless a person has lent it for a limited time with `tslaws delegate grant`. Agents propose laws in `*.proposed.laws.ts` and try them with `tslaws check
---proposed` (no lock, no coverage gate); a person moves them into a `*.laws.ts` file and accepts.
+under `CI`, or with `TSLAWS_AGENT` set, unless a person has lent it for a limited time with `tslaws delegate grant`. Agents propose laws in `*.proposed.laws.ts` files (or optionally in `.tslaws/proposals/`, outside the tree and git-ignored; `tslaws propose` or the MCP tool) and try them with `tslaws check
+--proposed` (no lock, no coverage gate); a person moves one into the tree with `tslaws promote` and accepts. Every laws file in the tree must be in the lock.
 
 `hooks/claude-hook.mjs` is a Claude Code hook that blocks `git commit` and sends an agent back to work when the check fails;
 `hooks/claude-settings.example.json` wires it up and `hooks/AGENTS.snippet.md` tells the agent the rules.
@@ -199,13 +199,13 @@ tslaws check [files...] [--json] [--summary] [--watch] [--runs N] [--seed N] [--
 - `check --reporter text|json|junit|github` picks the output: `junit` is JUnit XML for CI test reports, `github` prints workflow
   annotations and appends a table to `GITHUB_STEP_SUMMARY`. See "CI reporters" in `docs/laws.md`.
 
-- `tslaws mcp` serves `tslaws_check`, `tslaws_check_proposed`, `tslaws_explain` and `tslaws_propose` over MCP (stdio) for
-  agents; it cannot accept laws or touch the lock. `tslaws promote` is the person's step that moves proposed laws into the
-  accepted file. See [docs/laws.md](../../docs/laws.md#agent-integration-mcp).
+- `tslaws mcp` serves `tslaws_check`, `tslaws_check_proposed`, `tslaws_explain`, `tslaws_list` and `tslaws_propose` over MCP (stdio) for
+  agents; it cannot accept laws, promote a proposal or touch the lock. `tslaws promote <proposal> [--to PATH]` is the person's step that moves a proposal into the
+  tree; `tslaws propose <file.ts>` writes one; `tslaws list [--json]` says which files are laws files, at what level, and whether each is accepted. See [docs/laws.md](../../docs/laws.md#agent-integration-mcp).
 - Counterexamples are kept in `.tslaws/regressions` (committable) and replayed before the random search, so a fixed bug cannot
   return unnoticed. `check --no-regressions` skips the corpus; `tslaws regressions [list|clear]` shows or deletes it.
 
-Without files, every `*.laws.ts` under the current directory is used. The compiler is `--compiler`, `TSC_LAWS_BIN`, or
+Without files, every `*.laws.ts` under the current directory is used, and every file the `"laws"` globs of `tslaws.json` pick that declares a law. The compiler is `--compiler`, `TSC_LAWS_BIN`, or
 `tsc-laws` on `PATH`; it finds its lib files through `TSC_TS_LIB_DIR`, or the TypeScript 7 libs scriptc installs in
 `node_modules/@scriptc/*`.
 

package/dist/api.d.ts

@@ -57,3 +57,13 @@ type Registry = Map<string, fc.Arbitrary<unknown>>;
 export declare function arbitraryRegistry(): Registry;
 /** Registers the generator used for every parameter whose type is named `typeName`. */
 export declare function arbitrary<T>(typeName: string, generator: fc.Arbitrary<T>): void;
+/** What a law may return: `false` fails it, anything else holds. A law may be async (browser laws wait for the page). */
+export type LawBody = (...args: any[]) => boolean | void | Promise<boolean | void>;
+export interface LawDeclare {
+    /** Declares a law: `law('name', (x: int) => holds(x))`. Parameters need type annotations, inputs are generated from them. */
+    (name: string, body: LawBody): void;
+    /** A law the prover must prove for every input; `open` when it cannot. */
+    proved(name: string, body: LawBody): void;
+}
+/** Declares a law. `tslaws` lowers these calls to checked functions before it runs them; they never run as written. */
+export declare const law: LawDeclare;

package/dist/api.js

@@ -101,3 +101,10 @@ export function arbitraryRegistry() {
 export function arbitrary(typeName, generator) {
     arbitraryRegistry().set(typeName, generator);
 }
+function notRun() {
+    throw new Error('law() declares a specification and is run by `tslaws check`, not called at runtime');
+}
+/** Declares a law. `tslaws` lowers these calls to checked functions before it runs them; they never run as written. */
+export const law = Object.assign((_name, _body) => notRun(), {
+    proved: (_name, _body) => notRun(),
+});

package/dist/browser.d.ts

@@ -2,8 +2,6 @@ import { type Browser } from 'playwright-core';
 import type * as fc from 'fast-check';
 import { type PropertyOutcome } from './property.ts';
 import type { CheckOptions } from './types.ts';
-/** `a.browser.laws.ts` runs in a browser. */
-export declare function isBrowserLawFile(file: string): boolean;
 export type BrowserEngine = 'chromium' | 'firefox' | 'webkit';
 /** The engine to use: the requested one, else `TSLAWS_BROWSER_ENGINE`, else chromium. Throws on an unknown name. */
 export declare function resolveEngine(requested?: string, env?: NodeJS.ProcessEnv): BrowserEngine;
@@ -17,6 +15,8 @@ export declare function closeBrowser(): Promise<void>;
 export interface BrowserLaw {
     file: string;
     name: string;
+    /** The exported function the law lowers to; defaults to `name`. */
+    symbol?: string;
     jsFile: string;
     generators: fc.Arbitrary<unknown>[];
 }

package/dist/browser.js

@@ -9,10 +9,6 @@ import { readConfig } from "./coverage.js";
 import { chromium, firefox, webkit } from 'playwright-core';
 import { toWire } from "./generators.js";
 import { runProperty, summarise } from "./property.js";
-/** `a.browser.laws.ts` runs in a browser. */
-export function isBrowserLawFile(file) {
-    return /\.browser\.laws\.[cm]?ts$/.test(file);
-}
 function findBrowser() {
     const fromEnv = process.env.TSLAWS_BROWSER;
     if (fromEnv !== undefined && fromEnv !== '')
@@ -226,7 +222,7 @@ async function bundleOf(jsFile, cwd) {
 /** Runs the counterexample once more, leaves the DOM as it is, and photographs the page. Best effort. */
 async function capture(page, law, args, options) {
     try {
-        await page.evaluate(([name, input]) => window.__runLaw(name, input, true), [law.name, toWire(args)]);
+        await page.evaluate(([name, input]) => window.__runLaw(name, input, true), [law.symbol ?? law.name, toWire(args)]);
         const relative = `.tslaws/screenshots/${law.name.replace(/[^\w-]/g, '_')}.png`;
         mkdirSync(join(options.cwd, '.tslaws/screenshots'), { recursive: true });
         await page.screenshot({ path: join(options.cwd, relative) });
@@ -273,7 +269,7 @@ export async function runBrowserLaw(law, options) {
         await page.addScriptTag({ content: code });
         await page.addScriptTag({ content: harness });
         const call = async (...args) => {
-            const outcome = (await page.evaluate(([name, input, pause]) => window.__runLaw(name, input, false, pause), [law.name, toWire(args), calls++ < 12 ? (options.browserPauseMs ?? 0) : 0]));
+            const outcome = (await page.evaluate(([name, input, pause]) => window.__runLaw(name, input, false, pause), [law.symbol ?? law.name, toWire(args), calls++ < 12 ? (options.browserPauseMs ?? 0) : 0]));
             if (outcome.error !== undefined) {
                 const error = new Error(outcome.error.message);
                 error.name = outcome.error.name ?? 'Error';

package/dist/check.d.ts

@@ -4,6 +4,8 @@ export interface CheckReport {
     compileDiagnostics: string;
     compileOk: boolean;
     lockMissing: boolean;
+    /** Things worth a person's attention that do not fail the check: a file name that its imports do not back. */
+    notices: string[];
     /** Whether every law holds and nothing is open, failed or tampered with. */
     ok: boolean;
 }

package/dist/check.js

@@ -1,16 +1,44 @@
-import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { join } from 'node:path';
+import { resolve } from 'node:path';
 import ts from 'typescript';
 import { build, readManifest } from "./compile.js";
-import { compilerOptions, declarationFiles, isDiscard, jsPath, runLawGuarded, typesOf, } from "./property.js";
+import { compilerOptions, declarationFiles, isDiscard, jsPath, runLawGuarded, warmWorkers, typesOf, } from "./property.js";
 import { analyzeCoverage, coverFiles, readConfig } from "./coverage.js";
+import { derivedStore } from "./derived.js";
+import { jobs } from "./pool.js";
 import { compareLock, lawKey, readLock } from "./lock.js";
 import { proveLaw } from "./smt.js";
 import { decodeExample, loadExamples, regressionMessage, saveExample } from "./regressions.js";
 import { closeBrowser, runBrowserLaw } from "./browser.js";
-import { ensureServer, importsBoth, lawMode, runE2eLaw, stopServer } from "./e2e.js";
+import { ensureServer, runE2eLaw, stopServer } from "./e2e.js";
+import { inProposals } from "./lawFiles.js";
+import { classifyLawFile } from "./lawKinds.js";
+import { normaliseProposal } from "./proposals.js";
 import { declarationOf, exercisesOf, markFailing, Sources } from "./exercises.js";
+/** Runs at most `limit` tasks at once. */
+class Semaphore {
+    free;
+    queue = [];
+    constructor(limit) {
+        this.free = limit;
+    }
+    async run(task) {
+        if (this.free > 0)
+            this.free -= 1;
+        else
+            await new Promise((resolve) => this.queue.push(resolve));
+        try {
+            return await task();
+        }
+        finally {
+            const next = this.queue.shift();
+            if (next === undefined)
+                this.free += 1;
+            else
+                next();
+        }
+    }
+}
 /** The `@tslaws-exempt` functions of the project, for `tslaws accept` to record. */
 export function exemptionsOf(options) {
     const covered = coverFiles(options.cwd, readConfig(options.cwd).cover ?? []);
@@ -26,9 +54,27 @@ export function exemptionsOf(options) {
     }).exempt;
 }
 export async function check(options, enforceLock) {
+    // A proposal placed in .tslaws/proposals by hand may write its imports from the project root; store them where they resolve.
+    for (const file of options.files)
+        if (inProposals(file))
+            normaliseProposal(options.cwd, file);
     const laws = readManifest(options.compiler, options.files, options.cwd);
     const results = [];
     const blocked = new Set();
+    const notices = [];
+    // The level of a laws file comes from its name (the default) or its imports (`levels: "imports"`); looked at once per file.
+    const levelsMode = readConfig(options.cwd).levels ?? 'names';
+    const verdicts = new Map();
+    const verdictOf = (file) => {
+        let verdict = verdicts.get(file);
+        if (verdict === undefined) {
+            verdict = classifyLawFile(options.cwd, file, levelsMode);
+            verdicts.set(file, verdict);
+            for (const notice of verdict.notices)
+                notices.push(notice);
+        }
+        return verdict;
+    };
     const sources = new Sources(options.cwd);
     // What a law reaches is syntactic and cheap; a project that cannot be read this way just has no locations.
     const exercisesFor = (law) => {
@@ -61,7 +107,14 @@ export async function check(options, enforceLock) {
         lock = readLock(options.lockFile);
         lockMissing = lock === undefined;
         const byKey = new Map(laws.map((l) => [lawKey(l.file, l.name), l]));
-        for (const violation of compareLock(lock?.laws, laws)) {
+        // With levels from imports (or a lock that recorded levels), the resolved level of each laws file is part of the lock.
+        const levels = levelsMode === 'imports' || lock?.levels !== undefined
+            ? {
+                locked: lock?.levels,
+                now: Object.fromEntries([...new Set(laws.map((l) => l.file.replaceAll('\\', '/')))].map((f) => [f, verdictOf(f).kind])),
+            }
+            : undefined;
+        for (const violation of compareLock(lock?.laws, laws, levels)) {
             const law = byKey.get(violation.key);
             if (law === undefined) {
                 const [file, name] = violation.key.split('::');
@@ -78,7 +131,9 @@ export async function check(options, enforceLock) {
                 add(law, 'tampered', 'lock', {
                     message: violation.reason === 'added'
                         ? 'law is not in the lock; a person must run `tslaws accept`'
-                        : 'law changed since the lock was accepted',
+                        : violation.reason === 'level'
+                            ? 'the level this laws file runs at (node, browser or e2e) changed since the lock was accepted; a person must run `tslaws accept`'
+                            : 'law changed since the lock was accepted',
                 });
             }
         }
@@ -89,53 +144,61 @@ export async function check(options, enforceLock) {
     }
     const covered = coverFiles(options.cwd, readConfig(options.cwd).cover ?? []);
     const compiled = [...new Set([...options.files, ...covered])];
+    warmWorkers(laws.filter((law) => law.problems.length === 0 && verdictOf(law.file).kind === 'node').length);
     const built = build(options.compiler, compiled, options.cwd);
-    const program = ts.createProgram(declarationFiles(built.outDir), compilerOptions);
+    // What the type checker works out is kept with the build it came from, so an unchanged project skips the checker.
+    const derived = derivedStore(options.cwd, built.key);
+    let programOf;
+    const program = () => (programOf ??= built.program ?? ts.createProgram(declarationFiles(built.outDir), compilerOptions));
+    const sourceCwd = built.program === undefined ? undefined : options.cwd;
     const require = createRequire(import.meta.url);
-    for (const law of laws) {
+    const runOne = async (law, index) => {
+        const buffered = [];
+        try {
+            await runBody(law, (l, status, method, extra = {}) => {
+                buffered.push(() => add(l, status, method, extra));
+            });
+        }
+        finally {
+            finished.set(index, buffered);
+            flush();
+        }
+    };
+    const runBody = async (law, add) => {
         if (options.only !== undefined && !options.only.includes(law.name))
-            continue;
+            return;
         if (blocked.has(lawKey(law.file, law.name)))
-            continue;
+            return;
         options.onEvent?.({ type: 'start', file: law.file, name: law.name });
         let types;
         try {
-            types = typesOf(program, built.outDir, law);
+            types = derived.law(law, () => typesOf(program(), built.outDir, law, sourceCwd));
         }
         catch (error) {
             add(law, 'error', 'generators', { message: error.message });
-            continue;
-        }
-        let source = '';
-        try {
-            source = readFileSync(join(options.cwd, law.file), 'utf8');
+            return;
         }
-        catch {
-            // The compiler already reported an unreadable file.
-        }
-        if (importsBoth(source)) {
-            add(law, 'error', 'manifest', {
-                message: `${law.file}: a browser laws file is either component level (tslaws/browser) or end-to-end (tslaws/e2e), not both`,
-            });
-            continue;
+        const verdict = verdictOf(law.file);
+        if (verdict.error !== undefined) {
+            add(law, 'error', 'manifest', { message: verdict.error });
+            return;
         }
-        const mode = lawMode(law.file, source);
-        const browser = mode === 'component';
-        const e2e = mode === 'e2e';
+        const browser = verdict.kind === 'browser';
+        const e2e = verdict.kind === 'e2e';
         const method = browser ? 'browser' : e2e ? 'e2e' : 'property';
         let fn;
         // A browser law touches the DOM when it loads, so only the browser loads it.
         if (!browser) {
             try {
-                fn = require(jsPath(built.outDir, law.file))[law.name];
+                fn = require(jsPath(built.outDir, law.file))[law.symbol ?? law.name];
             }
             catch (error) {
                 add(law, 'error', 'load', { message: `cannot load compiled law: ${error.message}` });
-                continue;
+                return;
             }
             if (typeof fn !== 'function') {
                 add(law, 'error', 'load', { message: 'compiled module does not export the law' });
-                continue;
+                return;
             }
         }
         let details;
@@ -156,18 +219,24 @@ export async function check(options, enforceLock) {
             details = e2e
                 ? await runE2eLaw({ file: law.file, name: law.name, fn: fn, generators: types.generators }, lawOptions, await ensureServer(e2eConfig ?? {}, options.cwd), limitMs)
                 : browser
-                    ? await runBrowserLaw({ file: law.file, name: law.name, jsFile: jsPath(built.outDir, law.file), generators: types.generators }, lawOptions)
-                    : await runLawGuarded(built.outDir, law, lawOptions);
+                    ? await runBrowserLaw({
+                        file: law.file,
+                        name: law.name,
+                        symbol: law.symbol,
+                        jsFile: jsPath(built.outDir, law.file),
+                        generators: types.generators,
+                    }, lawOptions)
+                    : await runLawGuarded(built.outDir, law, lawOptions, types.plans);
         }
         catch (error) {
             add(law, 'error', method, { message: error.message });
-            continue;
+            return;
         }
         if (details === 'timeout') {
             add(law, 'error', method, {
                 message: `property test ran longer than ${limitMs / 1000}s; the law or the code it calls may not terminate`,
             });
-            continue;
+            return;
         }
         if (details.failed) {
             if (details.counterexample === undefined) {
@@ -192,7 +261,7 @@ export async function check(options, enforceLock) {
                     message: details.regression ? `${regressionMessage} (${details.counterexample}): ${reason}` : reason,
                 });
             }
-            continue;
+            return;
         }
         // Browser and async laws are tested, never proved: the prover cannot model a DOM or an await.
         const unprovable = browser || e2e ? 'runs in a browser' : fn.constructor.name === 'AsyncFunction' ? 'is async' : undefined;
@@ -206,7 +275,7 @@ export async function check(options, enforceLock) {
                         : 'marked proved but proving is disabled'
                     : undefined,
             });
-            continue;
+            return;
         }
         const holds = (inputs) => {
             try {
@@ -248,15 +317,38 @@ export async function check(options, enforceLock) {
             });
         else
             add(law, 'tested', 'property', { runs: details.numRuns, seed: details.seed, message: proof.reason });
-    }
+    };
+    const finished = new Map();
+    let nextToFlush = 0;
+    const flush = () => {
+        for (let ready = finished.get(nextToFlush); ready !== undefined; ready = finished.get(nextToFlush)) {
+            for (const emit of ready)
+                emit();
+            finished.delete(nextToFlush);
+            nextToFlush += 1;
+        }
+    };
+    // Property laws and proofs share the cores; browser and end-to-end laws share one page and one server, so they queue.
+    const lanes = { cpu: new Semaphore(jobs()), page: new Semaphore(1) };
+    await Promise.all(laws.map(async (law, index) => {
+        const skipped = (options.only !== undefined && !options.only.includes(law.name)) || blocked.has(lawKey(law.file, law.name));
+        if (skipped) {
+            finished.set(index, []);
+            flush();
+            return;
+        }
+        const lane = verdictOf(law.file).kind !== 'node' ? lanes.page : lanes.cpu;
+        await lane.run(() => runOne(law, index));
+    }));
     if (enforceLock) {
-        const coverage = analyzeCoverage({
+        const coverage = derived.coverage(() => analyzeCoverage({
             cwd: options.cwd,
             outDir: built.outDir,
             lawFiles: options.files,
             coverFiles: covered,
-            program,
-        });
+            program: program(),
+            moduleOf: sourceCwd === undefined ? undefined : (file) => resolve(sourceCwd, file),
+        }));
         for (const { file, name } of coverage.uncovered) {
             results.push({
                 file,
@@ -286,5 +378,5 @@ export async function check(options, enforceLock) {
     const ok = built.ok &&
         !lockMissing &&
         results.every((r) => r.status === 'proved' || r.status === 'bounded' || r.status === 'tested');
-    return { results, compileDiagnostics: built.diagnostics, compileOk: built.ok, lockMissing, ok };
+    return { results, compileDiagnostics: built.diagnostics, compileOk: built.ok, lockMissing, notices, ok };
 }

package/dist/cli.d.ts

@@ -1,3 +1,4 @@
+export declare function watched(filename: string | null): boolean;
 /** What a command needs from its caller. `home` is for unit tests; the CLI never sets it. */
 export interface CommandContext {
     isTTY: boolean;
@@ -10,4 +11,21 @@ export interface CommandContext {
 export declare function acceptCommand(cwd: string, flags: Map<string, string | true>, files: string[], ctx: CommandContext): Promise<number>;
 /** `tslaws delegate <action> [--for D] [--root DIR]`; `argv` is everything after `delegate`. */
 export declare function runDelegateCommand(argv: string[], cwd: string, ctx: CommandContext): number;
+/** What `promote` and `propose` ask of their surroundings, beyond the context every command has. `ask`, `stdin` and `checkFile` are for unit tests; the CLI never sets them. */
+export interface ProposalContext extends CommandContext {
+    ask?: (question: string) => Promise<string>;
+    stdin?: () => Promise<string>;
+    checkFile?: (file: string) => Promise<Map<string, string>>;
+}
+/**
+ * `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 declare function proposeCommand(cwd: string, flags: Map<string, string | true>, files: string[], ctx: ProposalContext): Promise<number>;
+/**
+ * `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 declare function promoteCommand(cwd: string, flags: Map<string, string | true>, files: string[], ctx: ProposalContext): Promise<number>;
 export declare function main(args: string[]): Promise<number>;