tslaws 0.6.3 → 0.7.0

package/dist/mcp.js

@@ -1,22 +1,30 @@
 // `tslaws mcp`: a Model Context Protocol server over stdio (JSON-RPC 2.0, one message per line).
 //
 // Safety property: an agent that talks to this server can run checks and write PROPOSED laws, nothing else. No tool
-// accepts laws, writes tsc-laws.lock or edits a `*.laws.ts` file that is not a `*.proposed.laws.ts`; the server sets
-// TSLAWS_AGENT so nothing it spawns can run `accept` either. A person promotes proposals with `tslaws promote`.
+// accepts laws, promotes a proposal, writes tsc-laws.lock or edits a file of the tree; the only files it writes are
+// proposals in `.tslaws/proposals/`. The server sets TSLAWS_AGENT so nothing it spawns can run `accept` or `promote`
+// either. A person promotes proposals with `tslaws promote`.
 // stdout is the protocol channel: this module writes nothing else to it.
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { check } from "./check.js";
 import { readConfig } from "./coverage.js";
 import { hintFor } from "./hints.js";
+import { discoverLaws, discoverProposals, ignoredDirs } from "./lawFiles.js";
+import { listLawFiles } from "./list.js";
 import { parseLawFile } from "./promote.js";
+import { addProposal, mergeProposal, ProposalError } from "./proposals.js";
 import { resolveSettings } from "./settings.js";
-const ignoredDirs = new Set(['node_modules', '.tslaws', '.git']);
 const passing = new Set(['proved', 'bounded', 'tested']);
 const supportedVersions = ['2025-06-18', '2025-03-26', '2024-11-05'];
-const defaultProposalFile = 'agent.proposed.laws.ts';
+const defaultProposalFile = 'agent.ts';
 export const tools = [
+    {
+        name: 'tslaws_list',
+        description: 'List the laws files and proposals of the project, as `tslaws list --json`: for each, the level it runs at (node, browser or e2e, from what it imports) and whether it is accepted, unaccepted (in the tree but not in the lock) or proposed. Runs nothing.',
+        inputSchema: { type: 'object', properties: {} },
+    },
     {
         name: 'tslaws_check',
         description: 'Check the accepted laws (*.laws.ts) of the project, as `tslaws check --json`: each result has a status and a hint with the next action. Never changes any file the person owns.',
@@ -30,7 +38,7 @@ export const tools = [
     },
     {
         name: 'tslaws_check_proposed',
-        description: 'Check the proposed laws (*.proposed.laws.ts), as `tslaws check --proposed`.',
+        description: 'Check every proposal in .tslaws/proposals/ (and in-tree *.proposed.laws.ts files), as `tslaws check --proposed`: no lock, no coverage gate.',
         inputSchema: { type: 'object', properties: {} },
     },
     {
@@ -44,15 +52,18 @@ export const tools = [
     },
     {
         name: 'tslaws_propose',
-        description: 'Write a law into a *.proposed.laws.ts file (appended; a law of the same name is replaced) and check it. Only proposed files can be written. A person promotes proposals with `tslaws promote`.',
+        description: 'Write a law into a proposal file in .tslaws/proposals/ (appended; a law of the same name is replaced) and check it. Only that directory can be written. Write imports of project files relative to the project root with a leading ./ (for example ./src/cart); the level (Node, browser, end to end) comes from what the file imports. A person promotes proposals with `tslaws promote`.',
         inputSchema: {
             type: 'object',
             properties: {
                 name: { type: 'string', description: 'the law name' },
-                source: { type: 'string', description: 'the full `export law ...` declaration, with any imports it needs' },
+                source: {
+                    type: 'string',
+                    description: "the full law, as `law('name', ...)` or `export law name ...` (the project's syntax), with any imports it needs",
+                },
                 file: {
                     type: 'string',
-                    description: `project-relative *.proposed.laws.ts path; default ${defaultProposalFile}`,
+                    description: `a plain .ts file name inside .tslaws/proposals/ (or its project-relative path); default ${defaultProposalFile}`,
                 },
             },
             required: ['name', 'source'],
@@ -65,20 +76,7 @@ function slash(path) {
     return path.replace(/\\/g, '/');
 }
 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) => slash(relative(cwd, f))).sort();
+    return proposed ? [...discoverLaws(cwd, true), ...discoverProposals(cwd)] : discoverLaws(cwd, false);
 }
 /** A project-relative path inside the root that names an existing or new file; throws ToolError otherwise. */
 function insideRoot(cwd, file) {
@@ -99,12 +97,6 @@ function insideRoot(cwd, file) {
         throw new ToolError(`'${file}' is outside the project`);
     return full;
 }
-/** The only files a tool may write. */
-export function proposalPath(cwd, file) {
-    if (!file.endsWith('.proposed.laws.ts') || file.endsWith('/.proposed.laws.ts'))
-        throw new ToolError(`'${file}' is not a *.proposed.laws.ts file; only proposed laws can be written`);
-    return insideRoot(cwd, file);
-}
 function options(opts, files) {
     const settings = resolveSettings(new Map(), readConfig(opts.cwd));
     return {
@@ -142,7 +134,9 @@ export class Session {
     }
     async run(files, enforceLock) {
         if (files.length === 0)
-            throw new ToolError(`no ${enforceLock ? '' : 'proposed '}laws files found (looking for *.${enforceLock ? '' : 'proposed.'}laws.ts)`);
+            throw new ToolError(enforceLock
+                ? 'no laws files found (looking for *.laws.ts)'
+                : 'no proposals found (looking in .tslaws/proposals/, and for in-tree *.proposed.laws.ts files)');
         const report = await check(options(this.opts, files), enforceLock);
         this.remember(report);
         return report;
@@ -160,6 +154,8 @@ export class Session {
                 const report = await this.run(files, true);
                 return args.summary === true ? summarised(report) : withHints(report);
             }
+            case 'tslaws_list':
+                return { files: listLawFiles(cwd) };
             case 'tslaws_check_proposed':
                 return withHints(await this.run(discover(cwd, true), false));
             case 'tslaws_explain': {
@@ -185,26 +181,22 @@ export class Session {
                 };
             }
             case 'tslaws_propose': {
-                if (typeof args.name !== 'string' || !/^[A-Za-z_$][\w$]*$/.test(args.name))
-                    throw new ToolError('name must be an identifier');
+                if (typeof args.name !== 'string' || args.name.trim() === '' || /[\r\n]/.test(args.name))
+                    throw new ToolError("name must be the law name: an identifier, or the text of a law('name', ...) call");
                 if (typeof args.source !== 'string')
                     throw new ToolError('source must be a string');
-                const file = slash(typeof args.file === 'string' ? args.file : defaultProposalFile);
-                const target = proposalPath(cwd, file);
-                const proposal = parseLawFile(args.source);
-                const mine = proposal.laws.find((l) => l.name === args.name);
-                if (mine === undefined)
-                    throw new ToolError(`source must contain \`export law ${args.name}\`…`);
-                let rest = args.source;
-                for (const part of [...proposal.laws, ...proposal.imports.map((text) => ({ text }))])
-                    rest = rest.replace(part.text, '');
-                if (rest.trim() !== '')
-                    throw new ToolError('source may contain only imports and law declarations');
-                const current = existsSync(target) ? readFileSync(target, 'utf8') : '';
-                mkdirSync(dirname(target), { recursive: true });
-                writeFileSync(target, mergeProposal(current, proposal.imports, proposal.laws));
+                let written;
+                try {
+                    written = addProposal(cwd, typeof args.file === 'string' ? args.file : defaultProposalFile, args.source, args.name);
+                }
+                catch (error) {
+                    if (error instanceof ProposalError)
+                        throw new ToolError(error.message);
+                    throw error;
+                }
+                const file = written.file;
                 const report = await this.run([file], false);
-                const names = new Set(proposal.laws.map((l) => l.name));
+                const names = new Set(written.laws);
                 const results = report.results.filter((r) => names.has(r.name));
                 return { file, ...withHints({ ...report, results }) };
             }
@@ -213,20 +205,7 @@ export class Session {
         }
     }
 }
-/** The proposed file with the proposal's laws appended (same-named laws replaced) and its imports added once. */
-export function mergeProposal(current, imports, laws) {
-    const parsed = parseLawFile(current);
-    let text = current;
-    for (const law of [...parsed.laws].reverse()) {
-        if (laws.some((l) => l.name === law.name))
-            text = text.slice(0, law.start) + text.slice(law.end);
-    }
-    const have = new Set(parseLawFile(text).imports.map((i) => i.replace(/\s+/g, ' ').trim()));
-    const missing = imports.filter((i) => !have.has(i.replace(/\s+/g, ' ').trim()));
-    const head = missing.length > 0 ? `${missing.join('\n')}\n` : '';
-    const body = `${text.trim() === '' ? '' : `${text.trim()}\n\n`}${laws.map((l) => l.text.trim()).join('\n\n')}\n`;
-    return `${head}${head !== '' && !body.startsWith('import') ? '\n' : ''}${body}`;
-}
+export { mergeProposal };
 function reply(id, result) {
     return `${JSON.stringify({ jsonrpc: '2.0', id, result })}\n`;
 }

package/dist/migrate/arbitraries.d.ts

@@ -0,0 +1,23 @@
+import ts from 'typescript';
+import type { Bindings } from './framework.ts';
+/** A tslaws type for one arbitrary and the conditions that narrow it back to what the arbitrary produced. */
+export interface Typed {
+    type: string;
+    /** Which tslaws helpers the type and conditions use. */
+    uses: Set<'int' | 'forall'>;
+    /** The expression for "`value` is one this arbitrary could have produced", when the type alone is wider. */
+    condition?: (value: string, depth: number) => string;
+}
+export type Mapped = {
+    ok: true;
+    typed: Typed;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The name of the fast-check export an expression refers to (`fc.integer`, or `integer` when imported by name). */
+export declare function fcMember(node: ts.Expression, b: Bindings): string | undefined;
+/** Maps one arbitrary expression to a tslaws type, or says why it has none. */
+export declare function mapArbitrary(node: ts.Expression, b: Bindings): Mapped;
+/** The `assume(...)` argument that narrows `value` to what `typed` produced, or undefined when the type is already exact. */
+export declare function assumption(typed: Typed, value: string): string | undefined;

package/dist/migrate/arbitraries.js

@@ -0,0 +1,202 @@
+// fast-check arbitraries that have a tslaws type: the law gets a typed parameter, and the arbitrary's own limits become
+// `assume(...)` lines. Anything else has no faithful type, so the caller keeps the `fc.assert` as it was.
+import ts from 'typescript';
+import { unwrap } from "./source.js";
+const no = (reason) => ({ ok: false, reason });
+/** The name of the fast-check export an expression refers to (`fc.integer`, or `integer` when imported by name). */
+export function fcMember(node, b) {
+    const e = unwrap(node);
+    if (ts.isPropertyAccessExpression(e) && ts.isIdentifier(e.expression) && b.fcNamespaces.has(e.expression.text))
+        return e.name.text;
+    if (ts.isIdentifier(e))
+        return b.fcNamed.get(e.text);
+    return undefined;
+}
+function numberOf(node) {
+    if (node === undefined)
+        return undefined;
+    const e = unwrap(node);
+    if (ts.isNumericLiteral(e))
+        return Number(e.text);
+    if (ts.isPrefixUnaryExpression(e) && ts.isNumericLiteral(e.operand)) {
+        if (e.operator === ts.SyntaxKind.MinusToken)
+            return -Number(e.operand.text);
+        if (e.operator === ts.SyntaxKind.PlusToken)
+            return Number(e.operand.text);
+    }
+    return undefined;
+}
+/** The `{ key: value }` options of an arbitrary; only the keys in `allowed` are understood. */
+function optionsOf(node, allowed, member) {
+    const values = new Map();
+    if (node === undefined)
+        return { ok: true, values };
+    const e = unwrap(node);
+    if (!ts.isObjectLiteralExpression(e))
+        return { ok: false, reason: `fc.${member} takes options that are not an object literal` };
+    for (const p of e.properties) {
+        if (!ts.isPropertyAssignment(p) || !ts.isIdentifier(p.name) || !allowed.includes(p.name.text))
+            return {
+                ok: false,
+                reason: `fc.${member} has an option tslaws cannot express (${p.name?.getText() ?? 'spread'})`,
+            };
+        values.set(p.name.text, p.initializer);
+    }
+    return { ok: true, values };
+}
+const isTrue = (node) => node === undefined
+    ? undefined
+    : unwrap(node).kind === ts.SyntaxKind.TrueKeyword
+        ? true
+        : unwrap(node).kind === ts.SyntaxKind.FalseKeyword
+            ? false
+            : undefined;
+function combine(parts) {
+    const present = parts.filter((p) => p !== undefined);
+    return present.length === 0 ? undefined : present.join(' && ');
+}
+/** `min` / `max` as comparisons, when both are numeric literals or absent. */
+function range(values, member) {
+    const out = {};
+    for (const key of ['min', 'max']) {
+        const node = values.get(key);
+        if (node === undefined)
+            continue;
+        const n = numberOf(node);
+        if (n === undefined || Number.isNaN(n))
+            return { ok: false, reason: `fc.${member} has a ${key} that is not a number literal` };
+        out[key] = n;
+    }
+    return { ok: true, ...out };
+}
+function bounds(value, r) {
+    return combine([
+        r.min === undefined ? undefined : `${value} >= ${r.min}`,
+        r.max === undefined ? undefined : `${value} <= ${r.max}`,
+    ]);
+}
+/** Maps one arbitrary expression to a tslaws type, or says why it has none. */
+export function mapArbitrary(node, b) {
+    const e = unwrap(node);
+    if (!ts.isCallExpression(e))
+        return no(`${e.getText().slice(0, 40)} is not a plain fc call`);
+    const member = fcMember(e.expression, b);
+    if (member === undefined)
+        return no(`${e.expression.getText().slice(0, 40)} is not an fc arbitrary`);
+    const [first, second] = e.arguments;
+    switch (member) {
+        case 'integer': {
+            const o = optionsOf(first, ['min', 'max'], member);
+            if (!o.ok)
+                return no(o.reason);
+            const r = range(o.values, member);
+            if (!r.ok)
+                return no(r.reason);
+            return { ok: true, typed: { type: 'int', uses: new Set(['int']), condition: (v) => bounds(v, r) ?? 'true' } };
+        }
+        case 'nat': {
+            const max = first === undefined ? undefined : numberOf(first);
+            let upper = max;
+            if (first !== undefined && max === undefined) {
+                const o = optionsOf(first, ['max'], member);
+                if (!o.ok)
+                    return no(o.reason);
+                const r = range(o.values, member);
+                if (!r.ok)
+                    return no(r.reason);
+                upper = r.max;
+            }
+            return {
+                ok: true,
+                typed: { type: 'int', uses: new Set(['int']), condition: (v) => bounds(v, { min: 0, max: upper }) },
+            };
+        }
+        case 'float':
+        case 'double': {
+            const o = optionsOf(first, ['min', 'max', 'noNaN', 'noDefaultInfinity'], member);
+            if (!o.ok)
+                return no(o.reason);
+            const r = range(o.values, member);
+            if (!r.ok)
+                return no(r.reason);
+            const noNaN = isTrue(o.values.get('noNaN'));
+            const noInf = isTrue(o.values.get('noDefaultInfinity'));
+            if ((o.values.has('noNaN') && noNaN === undefined) || (o.values.has('noDefaultInfinity') && noInf === undefined))
+                return no(`fc.${member} has a flag that is not true or false`);
+            const finite = noInf === true && r.min === undefined && r.max === undefined;
+            return {
+                ok: true,
+                typed: {
+                    type: 'number',
+                    uses: new Set(),
+                    condition: (v) => combine([
+                        noNaN === true ? `!Number.isNaN(${v})` : undefined,
+                        finite ? `(${v} !== Infinity && ${v} !== -Infinity)` : undefined,
+                        bounds(v, r),
+                    ]) ?? 'true',
+                },
+            };
+        }
+        case 'string': {
+            const o = optionsOf(first, ['minLength', 'maxLength'], member);
+            if (!o.ok)
+                return no(o.reason);
+            const lo = o.values.has('minLength') ? numberOf(o.values.get('minLength')) : undefined;
+            const hi = o.values.has('maxLength') ? numberOf(o.values.get('maxLength')) : undefined;
+            if ((o.values.has('minLength') && lo === undefined) || (o.values.has('maxLength') && hi === undefined))
+                return no('fc.string has a length that is not a number literal');
+            return {
+                ok: true,
+                typed: {
+                    type: 'string',
+                    uses: new Set(),
+                    condition: (v) => bounds(`${v}.length`, { min: lo, max: hi }) ?? 'true',
+                },
+            };
+        }
+        case 'boolean':
+            if (first !== undefined)
+                return no('fc.boolean takes no arguments');
+            return { ok: true, typed: { type: 'boolean', uses: new Set() } };
+        case 'array': {
+            if (first === undefined)
+                return no('fc.array needs an element arbitrary');
+            const inner = mapArbitrary(first, b);
+            if (!inner.ok)
+                return inner;
+            const o = optionsOf(second, ['minLength', 'maxLength'], member);
+            if (!o.ok)
+                return no(o.reason);
+            const lo = o.values.has('minLength') ? numberOf(o.values.get('minLength')) : undefined;
+            const hi = o.values.has('maxLength') ? numberOf(o.values.get('maxLength')) : undefined;
+            if ((o.values.has('minLength') && lo === undefined) || (o.values.has('maxLength') && hi === undefined))
+                return no('fc.array has a length that is not a number literal');
+            const t = inner.typed;
+            const element = t.condition?.('x', 0) === 'true' ? undefined : t.condition;
+            const uses = new Set(t.uses);
+            if (element !== undefined)
+                uses.add('forall');
+            return {
+                ok: true,
+                typed: {
+                    type: `${t.type}[]`,
+                    uses,
+                    condition: (v, depth) => {
+                        const e = `e${depth}`;
+                        return (combine([
+                            bounds(`${v}.length`, { min: lo, max: hi }),
+                            element === undefined ? undefined : `forall(${v}, (${e}) => ${element(e, depth + 1)})`,
+                        ]) ?? 'true');
+                    },
+                },
+            };
+        }
+        default:
+            return no(`fc.${member}(...) has no tslaws type`);
+    }
+}
+/** The `assume(...)` argument that narrows `value` to what `typed` produced, or undefined when the type is already exact. */
+export function assumption(typed, value) {
+    const text = typed.condition?.(value, 0);
+    return text === undefined || text === 'true' ? undefined : text;
+}

package/dist/migrate/convert.d.ts

@@ -0,0 +1,20 @@
+import { type SourceName } from './framework.ts';
+import type { Entry } from './report.ts';
+import { type Row } from './tests.ts';
+export interface ConvertInput {
+    /** The source file, relative to the working directory. */
+    path: string;
+    text: string;
+    from: SourceName;
+    /** Maps a relative module specifier of the source to the one the converted file needs where it is written. */
+    rewrite: (specifier: string) => string;
+}
+export interface Converted {
+    entries: Entry[];
+    laws: string[];
+    output?: string;
+    /** Whether the laws drive a browser through `tslaws/e2e`, which names the file `*.browser.laws.ts`. */
+    e2e: boolean;
+}
+export declare function convertTestFile(input: ConvertInput): Converted;
+export type { Row };