tslaws 0.6.3 → 0.7.0

package/dist/proposals.js

@@ -0,0 +1,192 @@
+// Proposals: laws an agent (or a person) suggests, kept in `.tslaws/proposals/` at the project root. The directory is
+// tool-owned and git-ignored, outside the tree the lock covers, so a proposal protects nothing and an edit to the tree
+// can never turn an accepted law into a proposed one. Only this module writes there; it never touches the lock.
+//
+// Imports in a proposal that start with `./` are written relative to the PROJECT ROOT (`./src/cart`), which is what an
+// author at the project root expects. They are stored relative to the file (`../../src/cart`), so the stored file is
+// ordinary TypeScript that resolves, type-checks and runs where it is. `../` and package imports are left alone.
+// `promote` rewrites the stored form again for the directory the law moves to.
+import { constants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, writeSync, closeSync, appendFileSync, writeFileSync, } from 'node:fs';
+import { join, posix } from 'node:path';
+import { moduleSpecifiers } from "./lawKinds.js";
+import { proposalsDir } from "./lawFiles.js";
+import { parseLawFile } from "./promote.js";
+/** A refusal with a message for the person or agent that asked. */
+export class ProposalError extends Error {
+}
+const nameShape = /^[A-Za-z0-9][A-Za-z0-9._-]*\.(?:ts|mts|cts)$/;
+const isLink = (path) => {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * The proposals directory, checked on the real file system: neither `.tslaws` nor `proposals` may be a link (or a
+ * junction) that leads out of the project. Creates the directory when `create` is set.
+ */
+export function proposalsDirectory(cwd, create) {
+    let real = realpathSync(cwd);
+    let shown = cwd;
+    for (const part of ['.tslaws', 'proposals']) {
+        shown = join(shown, part);
+        const expected = join(real, part);
+        if (existsSync(shown) || isLink(shown)) {
+            if (isLink(shown) || realpathSync(shown) !== expected)
+                throw new ProposalError(`${posix.join('.tslaws', part)} is a link that leaves the project; proposals are written inside the project only`);
+        }
+        else if (create)
+            mkdirSync(shown);
+        else
+            return undefined;
+        real = expected;
+    }
+    return shown;
+}
+/**
+ * The project-relative path of a proposal: `name.ts` or `.tslaws/proposals/name.ts`. Anything that names another
+ * directory, climbs out, is absolute or is not a plain `.ts` file name is refused.
+ */
+export function proposalName(file) {
+    const given = file.replaceAll('\\', '/').replace(/^\.\//, '');
+    const bare = given.startsWith(`${proposalsDir}/`) ? given.slice(proposalsDir.length + 1) : given;
+    if (!nameShape.test(bare) || /\.d\.(?:ts|mts|cts)$/.test(bare) || bare.includes('..'))
+        throw new ProposalError(`'${file}' is not a proposal file: proposals are plain .ts files directly inside ${proposalsDir}/ (for example ${proposalsDir}/cart.ts)`);
+    return `${proposalsDir}/${bare}`;
+}
+/** The absolute path a write to a proposal may use, after refusing links. Creates the directory. */
+function writablePath(cwd, file) {
+    const rel = proposalName(file);
+    const dir = proposalsDirectory(cwd, true);
+    const abs = join(dir, rel.slice(proposalsDir.length + 1));
+    if (isLink(abs))
+        throw new ProposalError(`${rel} is a link; a proposal must be a plain file`);
+    if (existsSync(abs) && !lstatSync(abs).isFile())
+        throw new ProposalError(`${rel} is not a plain file`);
+    return { rel, abs };
+}
+/** The absolute path of an existing proposal for reading or removing; refuses links the same way. */
+export function existingProposal(cwd, file) {
+    const rel = proposalName(file);
+    const dir = proposalsDirectory(cwd, false);
+    const abs = dir === undefined ? undefined : join(dir, rel.slice(proposalsDir.length + 1));
+    if (abs === undefined || !existsSync(abs))
+        throw new ProposalError(`no proposal ${rel}`);
+    if (isLink(abs) || !lstatSync(abs).isFile())
+        throw new ProposalError(`${rel} is not a plain file`);
+    return { rel, abs };
+}
+function rewrite(text, change) {
+    let out = text;
+    for (const spec of moduleSpecifiers(text, 'proposal.ts').reverse()) {
+        const next = change(spec.value);
+        if (next !== undefined && next !== spec.value)
+            out = out.slice(0, spec.start) + next + out.slice(spec.end);
+    }
+    return out;
+}
+const dotted = (path) => (path.startsWith('.') ? path : `./${path}`);
+/** Stores root-relative `./x` imports relative to the proposals directory. Idempotent for stored text. */
+export function toStoredImports(text) {
+    return rewrite(text, (specifier) => {
+        if (!specifier.startsWith('./'))
+            return undefined;
+        const fromRoot = posix.normalize(specifier);
+        if (fromRoot.startsWith('..'))
+            throw new ProposalError(`import '${specifier}' leaves the project; imports starting with ./ are relative to the project root`);
+        return dotted(posix.relative(proposalsDir, fromRoot));
+    });
+}
+/** Re-expresses the relative imports of a stored proposal for a file in the project-relative directory `toDir`. */
+export function importsForTarget(text, toDir) {
+    return rewrite(text, (specifier) => {
+        if (!specifier.startsWith('.'))
+            return undefined;
+        return dotted(posix.relative(toDir === '' ? '.' : toDir, posix.join(proposalsDir, specifier)));
+    });
+}
+/** The proposal's own text after `parseLawFile`: only imports and law declarations are allowed in one. */
+function parts(source) {
+    const parsed = parseLawFile(source);
+    let rest = source;
+    for (const part of [...parsed.laws, ...parsed.imports.map((text) => ({ text }))])
+        rest = rest.replace(part.text, '');
+    if (rest.trim() !== '')
+        throw new ProposalError('a proposal may contain only imports and law declarations');
+    return parsed;
+}
+/** 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}`;
+}
+function write(abs, text) {
+    // No following of a link planted at the last moment, where the platform can say so.
+    const fd = openSync(abs, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | (constants.O_NOFOLLOW ?? 0), 0o644);
+    try {
+        writeSync(fd, text);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Keeps the proposals directory out of git, on first use: appends `.tslaws/proposals` to an existing .gitignore (or
+ * creates one in a git checkout) unless `.tslaws` or the directory is already listed. `tslaws init` leaves this to us.
+ */
+function ignoreProposals(cwd) {
+    const ignore = join(cwd, '.gitignore');
+    const has = existsSync(ignore);
+    if (!has && !existsSync(join(cwd, '.git')))
+        return;
+    const text = has ? readFileSync(ignore, 'utf8') : '';
+    const listed = text.split(/\r?\n/).map((l) => l.trim().replace(/^\//, '').replace(/\/$/, ''));
+    if (listed.includes('.tslaws') || listed.includes('.tslaws/proposals'))
+        return;
+    const lead = text === '' || text.endsWith('\n') ? '' : '\n';
+    if (has)
+        appendFileSync(ignore, `${lead}.tslaws/proposals\n`);
+    else
+        writeFileSync(ignore, '.tslaws/proposals\n');
+}
+/**
+ * Adds laws to a proposal (appended; a law of the same name is replaced). `source` holds only imports and `export law`
+ * declarations; with `only`, it must declare that law. Writes inside `.tslaws/proposals/` and nowhere else.
+ */
+export function addProposal(cwd, file, source, only) {
+    const { rel, abs } = writablePath(cwd, file);
+    const stored = toStoredImports(source);
+    const parsed = parts(stored);
+    if (parsed.laws.length === 0)
+        throw new ProposalError('source must declare at least one law (`export law name(...) ...`)');
+    if (only !== undefined && !parsed.laws.some((l) => l.name === only))
+        throw new ProposalError(`source must contain \`export law ${only}\`…`);
+    const current = existsSync(abs) ? readFileSync(abs, 'utf8') : '';
+    write(abs, mergeProposal(current, parsed.imports, parsed.laws));
+    ignoreProposals(cwd);
+    return { file: rel, laws: parsed.laws.map((l) => l.name) };
+}
+/**
+ * Stores the root-relative imports of a proposal someone placed in the directory by hand, so it resolves where it is.
+ * Returns whether the file changed. Does nothing for a path that is not a plain file in the directory.
+ */
+export function normaliseProposal(cwd, file) {
+    const { abs } = existingProposal(cwd, file);
+    const text = readFileSync(abs, 'utf8');
+    const stored = toStoredImports(text);
+    if (stored === text)
+        return false;
+    write(abs, stored);
+    return true;
+}

package/dist/regressions.js

@@ -1,5 +1,6 @@
 // The regression corpus: every counterexample a property test finds is kept under `.tslaws/regressions` and replayed
 // before the random search on later runs, so a bug that was found once cannot silently come back.
+import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 /** The most examples kept per law. */
@@ -38,7 +39,12 @@ export function encodeValue(value) {
             throw new Error('cannot store a non-plain object');
         const fields = {};
         for (const key of Object.keys(value))
-            fields[key] = encodeValue(value[key]);
+            Object.defineProperty(fields, key, {
+                value: encodeValue(value[key]),
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
         return { $t: 'object', v: fields };
     }
     throw new Error(`cannot store a ${typeof value}`);
@@ -84,8 +90,21 @@ export function decodeExample(text) {
 const root = (cwd) => join(cwd, '.tslaws', 'regressions');
 /** `.tslaws/regressions/<law file with / as __>/<law>.json` */
 export function regressionFile(cwd, file, name) {
+    return join(root(cwd), file.replace(/[\\/]/g, '__'), `${safeName(name)}.json`);
+}
+function legacyFile(cwd, file, name) {
     return join(root(cwd), file.replace(/[\\/]/g, '__'), `${name}.json`);
 }
+/** A law name as a file name on every platform: characters Windows refuses become `_`, and a hash keeps two names apart. */
+function safeName(name) {
+    const safe = [...name]
+        .map((ch) => (ch.charCodeAt(0) < 32 || '<>:"/\\|?*'.includes(ch) ? '_' : ch))
+        .join('')
+        .replace(/[. ]+$/, '');
+    if (safe === name)
+        return name;
+    return `${safe}-${createHash('sha256').update(name).digest('hex').slice(0, 8)}`;
+}
 function readCorpus(path) {
     try {
         const corpus = JSON.parse(readFileSync(path, 'utf8'));
@@ -97,7 +116,9 @@ function readCorpus(path) {
 }
 /** The stored examples of a law as the texts `encodeExample` makes, newest first. */
 export function loadExamples(cwd, file, name) {
-    const corpus = readCorpus(regressionFile(cwd, file, name));
+    // Before names were made safe for Windows the file was named with the law's name as written: read that too, so
+    // counterexamples an earlier version stored are still replayed (the next save writes the new name).
+    const corpus = readCorpus(regressionFile(cwd, file, name)) ?? readCorpus(legacyFile(cwd, file, name));
     return corpus === undefined ? [] : corpus.examples.map((e) => JSON.stringify(e));
 }
 /** Stores `args` as the newest example; an equal older one moves to the front. Returns false when `args` cannot be stored. */

package/dist/smt.js

@@ -11,6 +11,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { Worker } from 'node:worker_threads';
+import { jobs, WorkerPool } from "./pool.js";
 import { dirname, join } from 'node:path';
 import ts from 'typescript';
 import { Executor, SpuriousModel, Unsupported, and } from "./symbolic.js";
@@ -219,7 +220,6 @@ parentPort.on('message', async ({ id, query, values }) => {
   }
 });
 `;
-let worker;
 let nextId = 0;
 function startWorker() {
     const w = new Worker(workerSource, {
@@ -229,6 +229,8 @@ function startWorker() {
     w.unref();
     return w;
 }
+// Each Z3 instance holds a large WebAssembly heap; more than four at once run out of memory on the bigger queries.
+const solvers = new WorkerPool(startWorker, Math.min(4, jobs()));
 /**
  * Runs the query, and runs it again in a fresh worker when the solver itself fell over (a WebAssembly allocation that
  * fails on a machine short of memory). A query that merely ran too long is not retried: it would only run long again.
@@ -247,8 +249,7 @@ async function solve(query, values, timeoutMs) {
 }
 /** One try: gives up on the whole worker after the timeout plus a grace period. */
 async function solveOnce(query, values, timeoutMs) {
-    worker ??= startWorker();
-    const current = worker;
+    const current = await solvers.acquire();
     const id = (nextId += 1);
     return new Promise((resolve, reject) => {
         const drop = () => {
@@ -257,9 +258,7 @@ async function solveOnce(query, values, timeoutMs) {
             current.off('error', onError);
         };
         const kill = () => {
-            void current.terminate();
-            if (worker === current)
-                worker = undefined;
+            solvers.discard(current);
         };
         const timer = setTimeout(() => {
             drop();
@@ -274,8 +273,10 @@ async function solveOnce(query, values, timeoutMs) {
                 kill();
                 reject(new Unsupported(`the solver crashed: ${reply.error}`));
             }
-            else
+            else {
+                solvers.release(current);
                 resolve({ out: reply.out ?? '', vals: reply.vals ?? '' });
+            }
         };
         const onError = (error) => {
             drop();
@@ -334,7 +335,7 @@ function containsInt(shape) {
 async function attempt(input, intLimit) {
     {
         const source = ts.createSourceFile(input.jsFile, readFileSync(input.jsFile, 'utf8'), ts.ScriptTarget.ES2022, true, ts.ScriptKind.JS);
-        const fn = source.statements.find((s) => ts.isFunctionDeclaration(s) && s.name?.text === input.law.name);
+        const fn = source.statements.find((s) => ts.isFunctionDeclaration(s) && s.name?.text === (input.law.symbol ?? input.law.name));
         if (fn === undefined || fn.body === undefined)
             throw new Unsupported('law function not found in the compiled output');
         if (fn.parameters.length !== input.shapes.length)

package/dist/types.d.ts

@@ -2,6 +2,8 @@ export type LawStatus = 'proved' | 'bounded' | 'tested' | 'open' | 'failed' | 't
 export interface ManifestLaw {
     file: string;
     name: string;
+    /** The exported function the law lowers to, when its name is not itself an identifier. Defaults to `name`. */
+    symbol?: string;
     exported: boolean;
     proved: boolean;
     line: number;

package/hooks/AGENTS.snippet.md

@@ -1,10 +1,10 @@
 ## Laws
 
-This project states behaviour as `law` declarations in `*.laws.ts`. They are the person's side of the contract.
+This project states behaviour as laws in `*.laws.ts`, written as calls, `law('name', (a: int) => ...)` and `law.proved('name', ...)`, or, with the tsc-laws compiler, as `export law name(a: int) { ... }` declarations. Use the syntax the existing laws use and never mix the two in one project. They are the person's side of the contract.
 
 - Run `npx tslaws check` before you finish or commit. It must exit 0: every law `proved` or `tested`, none `open`, `failed` or `tampered`.
 - Every exported function must be reached by a law (`uncovered` fails). Do not add `@tslaws-exempt` yourself; the lock rejects it. If code needs a law, ask for one or write it in a `*.proposed.laws.ts`.
 - A failed law means the code is wrong. Fix the code. Never edit, weaken, delete or add a law in a `*.laws.ts` file, and never run `tslaws accept`; the lock (`tsc-laws.lock`) will reject the change anyway.
-- To suggest a law, write it in `<name>.proposed.laws.ts` and run `npx tslaws check --proposed` to see whether it holds. A person promotes it.
+- To suggest a law, write it in `<name>.proposed.laws.ts` (in the project's syntax) and run `npx tslaws check --proposed` to see whether it holds. A person promotes it.
 - If the `tslaws` MCP server is configured (`npx tslaws mcp`), use its tools `tslaws_check`, `tslaws_check_proposed`, `tslaws_explain` and `tslaws_propose` instead of the shell; they cannot accept laws or change the lock. `tslaws promote` moves proposed laws into the accepted file and is the person's step, like `tslaws accept`; never run either.
 - `proved` laws need a proof the prover can find for every input. Keep proved code to `int`/`bigint`/`boolean`/`string`, records and `const`/`if`/`return`/calls; arrays and plain loops only reach `bounded`. To prove a scalar loop for every input, write `invariant(...)` first in its body (it is code, so it is yours to write). Use the `int` type from `tslaws` for whole numbers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tslaws",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Runs and checks `law` declarations compiled by tsc-laws: property tests, SMT proofs, tamper lock.",
   "bin": {
     "tslaws": "bin/tslaws.js"
@@ -42,12 +42,14 @@
       "types": "./dist/adapters/element.d.ts",
       "default": "./dist/adapters/element.js"
     },
+    "./internal/*": "./dist/*.js",
     "./package.json": "./package.json"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "node --test --test-concurrency=1 test/*.test.ts",
     "check": "node bin/tslaws.js check",
+    "laws": "node bin/tslaws.js check laws/core.laws.ts",
     "check:watch": "node bin/tslaws.js check --watch"
   },
   "dependencies": {
@@ -71,11 +73,11 @@
     }
   },
   "optionalDependencies": {
-    "tslaws-compiler-darwin-arm64": "0.6.3",
-    "tslaws-compiler-darwin-x64": "0.6.3",
-    "tslaws-compiler-linux-arm64-gnu": "0.6.3",
-    "tslaws-compiler-linux-x64-gnu": "0.6.3",
-    "tslaws-compiler-win32-x64-msvc": "0.6.3"
+    "tslaws-compiler-darwin-arm64": "0.7.0",
+    "tslaws-compiler-darwin-x64": "0.7.0",
+    "tslaws-compiler-linux-arm64-gnu": "0.7.0",
+    "tslaws-compiler-linux-x64-gnu": "0.7.0",
+    "tslaws-compiler-win32-x64-msvc": "0.7.0"
   },
   "publishConfig": {
     "access": "public"