tslaws 0.6.4 → 0.7.0

package/dist/lawKinds.d.ts

@@ -0,0 +1,38 @@
+export type LawKind = 'node' | 'browser' | 'e2e';
+/** Where a laws file's level comes from: its name (the default) or its import graph (opt-in). */
+export type LevelsMode = 'names' | 'imports';
+export interface ImportFacts {
+    /** The chain of project files from the laws file to the one that imports a browser law entry point, if any. */
+    browser: string[] | undefined;
+    e2e: string[] | undefined;
+}
+export interface KindVerdict {
+    kind: LawKind;
+    /** Set when the file cannot run at one level; the message names the files involved. */
+    error?: string;
+    /** Things worth saying that do not stop the file: a name hint that the imports contradict or do not back. */
+    notices: string[];
+    imports: ImportFacts;
+}
+export interface Specifier {
+    value: string;
+    /** Offsets of the text between the quotes, for a rewrite. */
+    start: number;
+    end: number;
+    /** Used only as a type: erased from the output, so it loads nothing at run time. */
+    typeOnly: boolean;
+}
+/** Every module specifier of a file: imports, re-exports, `import x = require()`, `require()` and `import()`. */
+export declare function moduleSpecifiers(text: string, fileName?: string): Specifier[];
+/** The module specifiers a file loads at run time: static imports, re-exports, `require` and dynamic `import()`. */
+export declare function runtimeSpecifiers(text: string, fileName?: string): Specifier[];
+/** Walks the import graph from `file` and finds the first chain that reaches each level's entry point. */
+export declare function importFacts(cwd: string, file: string): ImportFacts;
+/** Classifies a laws file (project-relative path) by its name (default) or, with `levels: "imports"`, its imports. */
+export declare function classifyLawFile(cwd: string, file: string, mode?: LevelsMode): KindVerdict;
+/** The project sources a file imports directly, project-relative, in the order they are imported. */
+export declare function directProjectImports(cwd: string, file: string): string[];
+/** The resolved level of each laws file, as the lock records it; none when levels come from names (the default). */
+export declare function lockLevels(cwd: string, laws: {
+    file: string;
+}[], mode: LevelsMode): Record<string, LawKind> | undefined;

package/dist/lawKinds.js

@@ -0,0 +1,210 @@
+// The level a laws file runs at. By default (`levels: "names"` in tslaws.json) it comes from the file name:
+// `*.browser.laws.ts` is a browser law (an end-to-end law when it imports `tslaws/e2e`), `*.e2e.laws.ts` is end to end,
+// anything else is a Node law. With `levels: "imports"` it comes from what the file imports, as follows.
+//
+// From what it imports. A file that reaches the browser law API (`tslaws/browser`, or one
+// of the `tslaws/adapters/*` entry points) is a browser law; a file that reaches the end-to-end API (`tslaws/e2e`) is an
+// end-to-end law; a file that reaches both is refused; a file that reaches neither is a Node law. "Reaches" follows the
+// project's own import graph: a helper module the law imports, or a re-export, counts. Imports used only as types, and
+// modules under node_modules, do not.
+//
+// The `.browser.laws.ts` and `.e2e.laws.ts` names stay as hints. They never override an import, and a hint that
+// disagrees with the imports is reported.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import ts from 'typescript';
+import { suffixKind } from "./lawNames.js";
+const browserEntry = /^tslaws\/(?:browser|adapters\/(?:dom|react|angular|element))$/;
+const e2eEntry = 'tslaws/e2e';
+/** Every module specifier of a file: imports, re-exports, `import x = require()`, `require()` and `import()`. */
+export function moduleSpecifiers(text, fileName = 'laws.ts') {
+    const source = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const found = [];
+    const literal = (node, typeOnly) => {
+        if (node !== undefined && ts.isStringLiteralLike(node))
+            found.push({ value: node.text, start: node.getStart(source) + 1, end: node.getEnd() - 1, typeOnly });
+    };
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node)) {
+            const clause = node.importClause;
+            const bindings = clause?.namedBindings;
+            const typeOnly = clause !== undefined &&
+                (clause.isTypeOnly ||
+                    (clause.name === undefined &&
+                        bindings !== undefined &&
+                        ts.isNamedImports(bindings) &&
+                        bindings.elements.length > 0 &&
+                        bindings.elements.every((e) => e.isTypeOnly)));
+            literal(node.moduleSpecifier, typeOnly);
+        }
+        else if (ts.isExportDeclaration(node)) {
+            const clause = node.exportClause;
+            literal(node.moduleSpecifier, node.isTypeOnly ||
+                (clause !== undefined &&
+                    ts.isNamedExports(clause) &&
+                    clause.elements.length > 0 &&
+                    clause.elements.every((e) => e.isTypeOnly)));
+        }
+        else if (ts.isImportEqualsDeclaration(node)) {
+            if (ts.isExternalModuleReference(node.moduleReference))
+                literal(node.moduleReference.expression, node.isTypeOnly);
+        }
+        else if (ts.isCallExpression(node) && node.arguments.length >= 1) {
+            const callee = node.expression;
+            if (callee.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(callee) && callee.text === 'require'))
+                literal(node.arguments[0], false);
+        }
+        else if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) {
+            literal(node.argument.literal, true);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return found;
+}
+/** The module specifiers a file loads at run time: static imports, re-exports, `require` and dynamic `import()`. */
+export function runtimeSpecifiers(text, fileName = 'laws.ts') {
+    return moduleSpecifiers(text, fileName).filter((s) => !s.typeOnly);
+}
+const resolveOptions = {
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    module: ts.ModuleKind.ESNext,
+    target: ts.ScriptTarget.ES2022,
+    allowJs: true,
+    resolveJsonModule: false,
+};
+/** The project source a specifier names, or undefined for a package, a declaration file or something unresolved. */
+function projectSource(specifier, from) {
+    if (!specifier.startsWith('.') && !specifier.startsWith('/'))
+        return undefined;
+    const resolved = ts.resolveModuleName(specifier, from, resolveOptions, ts.sys).resolvedModule;
+    if (resolved === undefined || resolved.isExternalLibraryImport === true)
+        return undefined;
+    const file = resolved.resolvedFileName;
+    if (/[\\/]node_modules[\\/]/.test(file) || /\.d\.[cm]?ts$/.test(file) || !existsSync(file))
+        return undefined;
+    return file;
+}
+/** Walks the import graph from `file` and finds the first chain that reaches each level's entry point. */
+export function importFacts(cwd, file) {
+    const start = resolve(cwd, file);
+    const facts = { browser: undefined, e2e: undefined };
+    const seen = new Set([start]);
+    const queue = [{ path: start, chain: [file.replaceAll('\\', '/')] }];
+    for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
+        let text;
+        try {
+            text = readFileSync(next.path, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const { value } of runtimeSpecifiers(text, next.path)) {
+            if (browserEntry.test(value))
+                facts.browser ??= next.chain;
+            else if (value === e2eEntry)
+                facts.e2e ??= next.chain;
+            const target = projectSource(value, join(dirname(next.path), 'x.ts'));
+            if (target === undefined || seen.has(target))
+                continue;
+            seen.add(target);
+            const inside = relative(resolve(cwd), resolve(target));
+            const shown = inside.startsWith('..') || isAbsolute(inside) ? target : inside;
+            queue.push({ path: target, chain: [...next.chain, shown.replaceAll('\\', '/')] });
+        }
+    }
+    return facts;
+}
+const via = (chain) => (chain.length <= 1 ? 'directly' : `through ${chain.slice(1).join(' > ')}`);
+const importsModule = (text, module) => new RegExp(`(?:from|import)\\s*['"]${module}['"]`).test(text);
+/** The level a file's name gives it: the way levels were always decided, and still the default. */
+function classifyByName(cwd, file) {
+    const imports = { browser: undefined, e2e: undefined };
+    let text = '';
+    try {
+        text = readFileSync(resolve(cwd, file), 'utf8');
+    }
+    catch {
+        // The compiler already reports an unreadable file.
+    }
+    const base = file.replaceAll('\\', '/');
+    if (importsModule(text, 'tslaws/e2e') && importsModule(text, 'tslaws/browser'))
+        return {
+            kind: 'node',
+            imports,
+            notices: [],
+            error: `${base}: a browser laws file is either component level (tslaws/browser) or end-to-end (tslaws/e2e), not both`,
+        };
+    const hint = suffixKind(file);
+    const kind = hint === 'e2e' ? 'e2e' : hint === 'browser' ? (importsModule(text, 'tslaws/e2e') ? 'e2e' : 'browser') : 'node';
+    return { kind, imports, notices: [] };
+}
+/** Classifies a laws file (project-relative path) by its name (default) or, with `levels: "imports"`, its imports. */
+export function classifyLawFile(cwd, file, mode = 'names') {
+    if (mode === 'names')
+        return classifyByName(cwd, file);
+    return classifyByImports(cwd, file);
+}
+/** Classifies a laws file by its imports, checking the name hint against them. */
+function classifyByImports(cwd, file) {
+    const imports = importFacts(cwd, file);
+    const hint = suffixKind(file);
+    const notices = [];
+    const base = file.replaceAll('\\', '/');
+    if (imports.browser !== undefined && imports.e2e !== undefined)
+        return {
+            kind: 'node',
+            imports,
+            notices,
+            error: `${base}: a laws file is either component level (tslaws/browser) or end-to-end (tslaws/e2e), not both ` +
+                `(browser API reached ${via(imports.browser)}; end-to-end API reached ${via(imports.e2e)})`,
+        };
+    const kind = imports.e2e !== undefined ? 'e2e' : imports.browser !== undefined ? 'browser' : 'node';
+    if (hint === undefined || hint === kind)
+        return { kind, imports, notices };
+    if (kind === 'node') {
+        // Nothing imported says which level, so the name still stands: a law may use the page's globals directly.
+        notices.push(`${base}: the name says ${hint}, but nothing it imports is the ${hint === 'e2e' ? 'end-to-end' : 'browser'} law API; ` +
+            `the name is used as the level. Import ${hint === 'e2e' ? 'tslaws/e2e' : 'tslaws/browser'} (the name is only a hint)`);
+        return { kind: hint, imports, notices };
+    }
+    if (hint === 'browser') {
+        // A browser-named file that drives an app is an end-to-end law, as it always was.
+        notices.push(`${base}: the name says browser, but it reaches the end-to-end API ${via(imports.e2e)}; it runs end to end`);
+        return { kind, imports, notices };
+    }
+    return {
+        kind,
+        imports,
+        notices,
+        error: `${base}: the name says end-to-end, but it reaches the browser API ${via(imports.browser)} and not tslaws/e2e; rename it or fix its imports`,
+    };
+}
+/** The project sources a file imports directly, project-relative, in the order they are imported. */
+export function directProjectImports(cwd, file) {
+    const from = resolve(cwd, file);
+    const found = [];
+    let text;
+    try {
+        text = readFileSync(from, 'utf8');
+    }
+    catch {
+        return found;
+    }
+    for (const { value } of moduleSpecifiers(text, from)) {
+        const target = projectSource(value, from);
+        if (target === undefined)
+            continue;
+        const inside = relative(resolve(cwd), resolve(target)).replaceAll('\\', '/');
+        if (!inside.startsWith('..') && !isAbsolute(inside) && !found.includes(inside))
+            found.push(inside);
+    }
+    return found;
+}
+/** The resolved level of each laws file, as the lock records it; none when levels come from names (the default). */
+export function lockLevels(cwd, laws, mode) {
+    if (mode !== 'imports')
+        return undefined;
+    const files = [...new Set(laws.map((l) => l.file.replaceAll(String.fromCharCode(92), '/')))];
+    return Object.fromEntries(files.map((f) => [f, classifyLawFile(cwd, f, mode).kind]));
+}

package/dist/lawNames.d.ts

@@ -0,0 +1,6 @@
+/** Whether the file is a proposed laws file, of any kind. */
+export declare function isProposedLawFile(file: string): boolean;
+/** The accepted name a proposed file stands for; other names come back unchanged. */
+export declare function acceptedLawName(file: string): string;
+/** The level a file name hints at: `.browser.laws.ts` and `.e2e.laws.ts` (proposed or accepted). Only a hint; imports decide. */
+export declare function suffixKind(file: string): 'browser' | 'e2e' | undefined;

package/dist/lawNames.js

@@ -0,0 +1,22 @@
+// Law file names. By default a law's level (Node, browser or end to end) comes from the name: `.browser.` and `.e2e.`
+// before `.laws.ts`; with `levels: "imports"` in tslaws.json it comes from the imports (see lawKinds.ts) and the suffixes are
+// hints. A proposed file is the accepted name with `.proposed` before `.laws`: `a.proposed.laws.ts` proposes
+// `a.laws.ts`, `a.browser.proposed.laws.ts` proposes `a.browser.laws.ts` and `a.e2e.proposed.laws.ts` proposes
+// `a.e2e.laws.ts`. A proposed file keeps the kind of the file it proposes, so it runs at the same level.
+/** Whether the file is a proposed laws file, of any kind. */
+export function isProposedLawFile(file) {
+    return file.endsWith('.proposed.laws.ts');
+}
+/** The accepted name a proposed file stands for; other names come back unchanged. */
+export function acceptedLawName(file) {
+    return isProposedLawFile(file) ? `${file.slice(0, -'.proposed.laws.ts'.length)}.laws.ts` : file;
+}
+/** The level a file name hints at: `.browser.laws.ts` and `.e2e.laws.ts` (proposed or accepted). Only a hint; imports decide. */
+export function suffixKind(file) {
+    const accepted = acceptedLawName(file);
+    if (/\.e2e\.laws\.[cm]?ts$/.test(accepted))
+        return 'e2e';
+    if (/\.browser\.laws\.[cm]?ts$/.test(accepted))
+        return 'browser';
+    return undefined;
+}

package/dist/list.d.ts

@@ -0,0 +1,22 @@
+import { type LawKind } from './lawKinds.ts';
+export interface ListedFile {
+    /** Project-relative path with forward slashes. */
+    file: string;
+    /** The level it runs at: from its name by default, from what it imports with `levels: "imports"`. */
+    kind: LawKind;
+    /**
+     * `accepted`: the lock has laws of this file. `unaccepted`: in the tree, but the lock has none of it, so `check`
+     * fails it until a person runs `tslaws accept`. `proposed`: a proposal (in `.tslaws/proposals`, or an
+     * in-tree `*.proposed.laws.ts`); no lock, no coverage.
+     */
+    status: 'accepted' | 'unaccepted' | 'proposed';
+    /** Set when the file cannot run at one level (it reaches both APIs). */
+    error?: string;
+    /** Where a proposal lives: `proposals` (the directory) or `name` (an in-tree `*.proposed.laws.ts` name). */
+    proposal?: 'proposals' | 'name';
+    notices: string[];
+}
+/** Every laws file and proposal of the project, sorted by path, accepted and unaccepted before proposed. */
+export declare function listLawFiles(cwd: string): ListedFile[];
+/** One line per file: `kind status path`. */
+export declare function renderList(files: ListedFile[]): string;

package/dist/list.js

@@ -0,0 +1,36 @@
+// `tslaws list`: the laws files of the project with the level each runs at and where it stands, so an editor or an agent
+// can ask the tool instead of matching file names. It reads files and the lock; it compiles and runs nothing.
+import { join } from 'node:path';
+import { discoverLaws, discoverProposals } from "./lawFiles.js";
+import { readConfig } from "./coverage.js";
+import { classifyLawFile } from "./lawKinds.js";
+import { readLock } from "./lock.js";
+/** Every laws file and proposal of the project, sorted by path, accepted and unaccepted before proposed. */
+export function listLawFiles(cwd) {
+    const mode = readConfig(cwd).levels ?? 'names';
+    const lock = readLock(join(cwd, 'tsc-laws.lock'));
+    const locked = new Set(Object.keys(lock?.laws ?? {}).map((key) => key.slice(0, key.indexOf('::'))));
+    const entry = (file, status, proposal) => {
+        const verdict = classifyLawFile(cwd, file, mode);
+        return {
+            file,
+            kind: verdict.kind,
+            status,
+            ...(verdict.error === undefined ? {} : { error: verdict.error }),
+            ...(proposal === undefined ? {} : { proposal }),
+            notices: verdict.notices,
+        };
+    };
+    return [
+        ...discoverLaws(cwd).map((file) => entry(file, locked.has(file) ? 'accepted' : 'unaccepted')),
+        ...discoverLaws(cwd, true).map((file) => entry(file, 'proposed', 'name')),
+        ...discoverProposals(cwd).map((file) => entry(file, 'proposed', 'proposals')),
+    ];
+}
+/** One line per file: `kind status path`. */
+export function renderList(files) {
+    if (files.length === 0)
+        return 'no laws files found\n';
+    const width = Math.max(...files.map((f) => f.kind.length));
+    return `${files.map((f) => `${f.kind.padEnd(width)}  ${f.status.padEnd(10)}  ${f.file}${f.error === undefined ? '' : `  (${f.error})`}`).join('\n')}\n`;
+}

package/dist/lock.d.ts

@@ -4,13 +4,26 @@ export interface Lock {
     laws: LockEntries;
     /** `file::name` of the functions a person exempted from coverage. */
     exempt: string[];
+    /**
+     * Only in a lock accepted with `levels: "imports"`: the level each laws file resolved to. A lock accepted by name
+     * (the default) has no such section and keeps the format it always had.
+     */
+    levels?: Record<string, string>;
 }
 export declare function lawKey(file: string, name: string): string;
 export declare function lawHash(law: ManifestLaw): string;
 export declare function readLock(path: string): Lock | undefined;
-export declare function writeLock(path: string, laws: ManifestLaw[], exempt?: string[]): void;
+export declare function writeLock(path: string, laws: ManifestLaw[], exempt?: string[], levels?: Record<string, string>): void;
 export interface LockViolation {
     key: string;
-    reason: 'changed' | 'added' | 'removed';
+    reason: 'changed' | 'added' | 'removed' | 'level';
 }
-export declare function compareLock(lock: LockEntries | undefined, laws: ManifestLaw[]): LockViolation[];
+/**
+ * `levels` is the level each laws file resolves to now, or undefined when levels come from names and the lock has no
+ * levels section (then nothing about levels is compared). A law whose file's level is not the locked one, or is not
+ * locked at all, is a violation until a person accepts again.
+ */
+export declare function compareLock(lock: LockEntries | undefined, laws: ManifestLaw[], levels?: {
+    locked: Record<string, string> | undefined;
+    now: Record<string, string>;
+}): LockViolation[];

package/dist/lock.js

@@ -13,15 +13,29 @@ export function readLock(path) {
     if (!existsSync(path))
         return undefined;
     const lock = JSON.parse(readFileSync(path, 'utf8'));
-    return { laws: lock.laws, exempt: lock.exempt ?? [] };
+    return { laws: lock.laws, exempt: lock.exempt ?? [], ...(lock.levels === undefined ? {} : { levels: lock.levels }) };
 }
-export function writeLock(path, laws, exempt = []) {
+export function writeLock(path, laws, exempt = [], levels) {
     const entries = {};
     for (const law of [...laws].sort((a, b) => lawKey(a.file, a.name).localeCompare(lawKey(b.file, b.name))))
         entries[lawKey(law.file, law.name)] = lawHash(law);
-    writeFileSync(path, JSON.stringify({ version: 1, laws: entries, exempt: [...exempt].sort() }, null, 2) + '\n');
+    const recorded = {};
+    for (const file of Object.keys(levels ?? {}).sort())
+        recorded[file.replaceAll('\\', '/')] = levels[file];
+    const body = {
+        version: 1,
+        laws: entries,
+        exempt: [...exempt].sort(),
+        ...(levels === undefined ? {} : { levels: recorded }),
+    };
+    writeFileSync(path, JSON.stringify(body, null, 2) + '\n');
 }
-export function compareLock(lock, laws) {
+/**
+ * `levels` is the level each laws file resolves to now, or undefined when levels come from names and the lock has no
+ * levels section (then nothing about levels is compared). A law whose file's level is not the locked one, or is not
+ * locked at all, is a violation until a person accepts again.
+ */
+export function compareLock(lock, laws, levels) {
     const violations = [];
     const seen = new Set();
     for (const law of laws) {
@@ -32,6 +46,11 @@ export function compareLock(lock, laws) {
             violations.push({ key, reason: 'added' });
         else if (locked !== lawHash(law))
             violations.push({ key, reason: 'changed' });
+        else if (levels !== undefined) {
+            const file = law.file.replaceAll('\\', '/');
+            if (levels.locked?.[file] !== levels.now[file])
+                violations.push({ key, reason: 'level' });
+        }
     }
     for (const key of Object.keys(lock ?? {}))
         if (!seen.has(key))

package/dist/lower.d.ts

@@ -0,0 +1,10 @@
+import type { ManifestLaw } from './types.ts';
+export interface Lowered {
+    /** The file text with every law call replaced by an exported function. */
+    text: string;
+    laws: ManifestLaw[];
+}
+/** The pre-call syntax (`export law name(...)`), which only the tsc-laws compiler parses. */
+export declare function usesLegacySyntax(text: string): boolean;
+/** Lowers the law calls of one file; `file` is the project-relative path the results carry. */
+export declare function lowerLawFile(file: string, text: string): Lowered;

package/dist/lower.js

@@ -0,0 +1,178 @@
+// Laws as calls: `law('name', (x: int) => ...)` and `law.proved(...)` in a `*.laws.ts` file are ordinary TypeScript. The
+// runner lowers each top-level call to the exported function the rest of tslaws already runs, proves and tests, keeping
+// every line where it was so diagnostics and counterexamples point at the file the person wrote.
+import ts from 'typescript';
+/** The pre-call syntax (`export law name(...)`), which only the tsc-laws compiler parses. */
+export function usesLegacySyntax(text) {
+    if (!/\blaw\b/.test(text))
+        return false;
+    // Scan tokens, so a declaration shown in a comment or a string is not mistaken for one.
+    const scanner = ts.createScanner(ts.ScriptTarget.Latest, true, ts.LanguageVariant.Standard, text);
+    const tokens = [];
+    // The scanner does not follow `${...}` inside a template on its own: track the braces and rescan the template parts.
+    const braces = [];
+    for (let kind = scanner.scan(); kind !== ts.SyntaxKind.EndOfFileToken; kind = scanner.scan()) {
+        if (kind === ts.SyntaxKind.TemplateHead)
+            braces.push('template');
+        else if (kind === ts.SyntaxKind.OpenBraceToken)
+            braces.push('brace');
+        else if (kind === ts.SyntaxKind.CloseBraceToken && braces.pop() === 'template') {
+            kind = scanner.reScanTemplateToken(false);
+            if (kind === ts.SyntaxKind.TemplateMiddle)
+                braces.push('template');
+        }
+        tokens.push({ kind, text: scanner.getTokenText(), newline: scanner.hasPrecedingLineBreak() });
+    }
+    // A law may be named with a word that is also a keyword (`never`, `type`), so any word-like token is a name.
+    const word = (i, value) => {
+        const token = tokens[i];
+        if (token === undefined)
+            return false;
+        const wordLike = token.kind === ts.SyntaxKind.Identifier ||
+            (token.kind >= ts.SyntaxKind.FirstKeyword && token.kind <= ts.SyntaxKind.LastKeyword);
+        return wordLike && (value === undefined || token.text === value);
+    };
+    for (let i = 0; i < tokens.length; i += 1) {
+        if (tokens[i].text !== 'law')
+            continue;
+        // Starts a statement: first on its line, or right after `export` / `async` that does.
+        let start = i;
+        while (start > 0 && ['export', 'async'].includes(tokens[start - 1].text))
+            start -= 1;
+        if (start > 0 && !tokens[start].newline)
+            continue;
+        let next = i + 1;
+        if (word(next, 'proved') && word(next + 1))
+            next += 1;
+        const after = tokens[next + 1]?.kind;
+        if (word(next) && (after === ts.SyntaxKind.OpenParenToken || after === ts.SyntaxKind.LessThanToken))
+            return true;
+    }
+    return false;
+}
+function newlines(text) {
+    let count = 0;
+    for (const ch of text)
+        if (ch === '\n')
+            count += 1;
+    return count;
+}
+/** `law` or `law.proved` as the callee of a call; undefined when the call is something else. */
+function lawCallee(call) {
+    const callee = call.expression;
+    if (ts.isIdentifier(callee) && callee.text === 'law')
+        return { proved: false };
+    if (ts.isPropertyAccessExpression(callee) &&
+        ts.isIdentifier(callee.expression) &&
+        callee.expression.text === 'law' &&
+        callee.name.text === 'proved')
+        return { proved: true };
+    return undefined;
+}
+function identifierFor(name, taken) {
+    let id = name.replace(/[^\w$]/g, '_');
+    if (id === '' || /^\d/.test(id))
+        id = `_${id}`;
+    let unique = id;
+    for (let n = 2; taken.has(unique); n += 1)
+        unique = `${id}_${n}`;
+    taken.add(unique);
+    return unique;
+}
+/** Why a law's function cannot be run, or undefined when it can. */
+function problemsOf(fn) {
+    const problems = [];
+    if (!ts.isArrowFunction(fn) && fn.asteriskToken !== undefined)
+        problems.push('a law cannot be a generator');
+    for (const parameter of fn.parameters) {
+        if (!ts.isIdentifier(parameter.name))
+            problems.push('a law parameter must be a plain identifier');
+        else if (parameter.type === undefined)
+            problems.push(`parameter ${parameter.name.text} of a law needs a type annotation so inputs can be generated`);
+    }
+    return problems;
+}
+/** Lowers the law calls of one file; `file` is the project-relative path the results carry. */
+export function lowerLawFile(file, text) {
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.ES2022, true, scriptKind(file));
+    const taken = new Set();
+    for (const statement of source.statements)
+        if (ts.isFunctionDeclaration(statement) && statement.name !== undefined)
+            taken.add(statement.name.text);
+        else if (ts.isVariableStatement(statement))
+            for (const d of statement.declarationList.declarations)
+                if (ts.isIdentifier(d.name))
+                    taken.add(d.name.text);
+    const laws = [];
+    const edits = [];
+    const checks = [];
+    const seen = new Set();
+    for (const statement of source.statements) {
+        if (!ts.isExpressionStatement(statement) || !ts.isCallExpression(statement.expression))
+            continue;
+        const call = statement.expression;
+        const callee = lawCallee(call);
+        if (callee === undefined)
+            continue;
+        const start = call.getStart(source);
+        const line = source.getLineAndCharacterOfPosition(start).line + 1;
+        const [nameArg, bodyArg] = call.arguments;
+        const lawText = text.slice(start, call.end);
+        const base = { file, exported: true, proved: callee.proved, line, text: lawText };
+        if (nameArg === undefined || !(ts.isStringLiteral(nameArg) || ts.isNoSubstitutionTemplateLiteral(nameArg))) {
+            laws.push({
+                ...base,
+                name: `law@${line}`,
+                params: [],
+                body: '',
+                problems: ['the name of a law must be a string literal'],
+            });
+            continue;
+        }
+        const name = nameArg.text;
+        if (bodyArg === undefined || !(ts.isArrowFunction(bodyArg) || ts.isFunctionExpression(bodyArg))) {
+            laws.push({ ...base, name, params: [], body: '', problems: ['a law needs a function as its second argument'] });
+            continue;
+        }
+        const problems = problemsOf(bodyArg);
+        if (seen.has(name))
+            problems.push(`there is already a law named "${name}" in this file`);
+        seen.add(name);
+        const params = bodyArg.parameters.map((p) => p.name.getText(source));
+        const body = text.slice(bodyArg.body.getStart(source), bodyArg.body.end);
+        const entry = { ...base, name, symbol: name, params, body, problems };
+        laws.push(entry);
+        if (problems.length > 0)
+            continue;
+        const id = identifierFor(name, taken);
+        entry.symbol = id;
+        const isAsync = bodyArg.modifiers?.some((m) => m.kind === ts.SyntaxKind.AsyncKeyword) === true;
+        const typeParameters = bodyArg.typeParameters === undefined
+            ? ''
+            : `<${text.slice(bodyArg.typeParameters.pos, bodyArg.typeParameters.end)}>`;
+        const parameterText = text.slice(bodyArg.parameters.pos, bodyArg.parameters.end);
+        const returnType = bodyArg.type === undefined ? '' : `: ${text.slice(bodyArg.type.getStart(source), bodyArg.type.end)}`;
+        const header = `export ${isAsync ? 'async ' : ''}function ${id}${typeParameters}(${parameterText})${returnType}`;
+        const bodyStart = bodyArg.body.getStart(source);
+        const dropped = newlines(text.slice(start, bodyStart)) - newlines(parameterText) - newlines(returnType);
+        const pad = '\n'.repeat(Math.max(0, dropped));
+        const tail = '\n'.repeat(newlines(text.slice(bodyArg.body.end, statement.end)));
+        const inner = text.slice(bodyStart, bodyArg.body.end);
+        const replacement = ts.isBlock(bodyArg.body)
+            ? `${header} ${pad}${inner}${tail}`
+            : `${header} {${pad} return ${inner};${tail} }`;
+        edits.push({ start: statement.getStart(source), end: statement.end, replacement });
+        checks.push(`type __LawResult_${id} = __LawReturns<typeof ${id}>;`);
+    }
+    let lowered = text;
+    for (const edit of edits.sort((a, b) => b.start - a.start))
+        lowered = lowered.slice(0, edit.start) + edit.replacement + lowered.slice(edit.end);
+    if (checks.length > 0)
+        lowered += `\ntype __LawReturns<F extends (...args: never[]) => boolean | void | Promise<boolean | void>> = F;${checks.join('')}`;
+    return { text: lowered, laws };
+}
+function scriptKind(file) {
+    if (file.endsWith('.tsx'))
+        return ts.ScriptKind.TSX;
+    return ts.ScriptKind.TS;
+}

package/dist/mcp.d.ts

@@ -1,3 +1,4 @@
+import { mergeProposal } from './proposals.ts';
 interface Tool {
     name: string;
     description: string;
@@ -8,8 +9,6 @@ export interface McpOptions {
     cwd: string;
     compiler: string;
 }
-/** The only files a tool may write. */
-export declare function proposalPath(cwd: string, file: string): string;
 export declare class Session {
     private readonly last;
     private readonly opts;
@@ -18,13 +17,8 @@ export declare class Session {
     private run;
     call(name: string, args: Record<string, unknown>): Promise<unknown>;
 }
-/** The proposed file with the proposal's laws appended (same-named laws replaced) and its imports added once. */
-export declare function mergeProposal(current: string, imports: string[], laws: {
-    name: string;
-    text: string;
-}[]): string;
+export { mergeProposal };
 /** The reply line for one request line, or undefined for a notification. */
 export declare function handleLine(session: Session, line: string): Promise<string | undefined>;
 /** Serves MCP on stdin/stdout until stdin closes. Resolves the exit status. */
 export declare function serveMcp(opts: McpOptions): Promise<number>;
-export {};