tslaws 0.6.3 → 0.7.0

package/dist/coverage.js

@@ -8,8 +8,10 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import ts from 'typescript';
 import { parseE2eConfig } from "./e2e.js";
+import { globMatcher } from "./globs.js";
+import { customLawFile } from "./lawFiles.js";
 const settingKeys = ['runs', 'propertyTimeoutMs', 'proofTimeoutMs', 'bound'];
-const configKeys = ['cover', 'compilerOptions', 'e2e', 'bundlerPlugins', ...settingKeys];
+const configKeys = ['cover', 'laws', 'levels', 'compilerOptions', 'e2e', 'bundlerPlugins', ...settingKeys];
 /** Validates the top level of tslaws.json: known keys only, and the run settings are integers of at least 1. */
 export function parseConfig(raw) {
     const fail = (message) => {
@@ -31,6 +33,14 @@ export function parseConfig(raw) {
     if (plugins !== undefined &&
         (!Array.isArray(plugins) || plugins.some((entry) => typeof entry !== 'string' || entry === '')))
         fail(`"bundlerPlugins" must be an array of module paths, got ${JSON.stringify(plugins)}`);
+    const levels = object.levels;
+    if (levels !== undefined && levels !== 'names' && levels !== 'imports')
+        fail(`"levels" must be "names" or "imports", got ${JSON.stringify(levels)}`);
+    const laws = object.laws;
+    if (laws !== undefined &&
+        (!Array.isArray(laws) ||
+            laws.some((entry) => typeof entry !== 'string' || entry.replace(/^!/, '') === '' || entry.startsWith('/'))))
+        fail(`"laws" must be an array of project-relative globs, got ${JSON.stringify(laws)}`);
     return object;
 }
 export function readConfig(cwd) {
@@ -42,29 +52,12 @@ export function readConfig(cwd) {
         config.e2e = parseE2eConfig(config.e2e);
     return config;
 }
-function globToRegExp(glob) {
-    let out = '';
-    for (let i = 0; i < glob.length; i += 1) {
-        const ch = glob[i];
-        if (ch === '*' && glob[i + 1] === '*') {
-            out += '.*';
-            i += glob[i + 2] === '/' ? 2 : 1;
-        }
-        else if (ch === '*')
-            out += '[^/]*';
-        else if (ch === '?')
-            out += '[^/]';
-        else
-            out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
-    }
-    return new RegExp(`^${out}$`);
-}
 /** Source files matching the `cover` globs (a leading `!` excludes), minus laws files and declarations. */
 export function coverFiles(cwd, globs) {
     // Plain JavaScript sources are covered only when the project compiles them (`allowJs`).
     const js = readConfig(cwd).compilerOptions?.allowJs === true;
-    const include = globs.filter((g) => !g.startsWith('!')).map(globToRegExp);
-    const exclude = globs.filter((g) => g.startsWith('!')).map((g) => globToRegExp(g.slice(1)));
+    const covered = globMatcher(globs);
+    const isLaws = customLawFile(cwd);
     const found = [];
     const walk = (dir) => {
         for (const entry of readdirSync(dir)) {
@@ -77,9 +70,9 @@ export function coverFiles(cwd, globs) {
                 const file = relative(cwd, full).replaceAll('\\', '/');
                 if (!(js ? /\.(ts|tsx|mts|cts|js)$/ : /\.(ts|tsx|mts|cts)$/).test(file))
                     continue;
-                if (/\.d\.(ts|mts|cts)$/.test(file) || /\.laws\.ts$/.test(file))
+                if (/\.d\.(ts|mts|cts)$/.test(file) || file.endsWith('.laws.ts'))
                     continue;
-                if (include.some((r) => r.test(file)) && !exclude.some((r) => r.test(file)))
+                if (covered(file) && !isLaws(file))
                     found.push(file);
             }
         }
@@ -225,7 +218,7 @@ export function analyzeCoverage(input) {
         if (module === undefined)
             continue;
         const file = sourceOf(input.outDir, input.cwd, js);
-        for (const name of exportedFunctions(input.program, dtsOf(input.outDir, file))) {
+        for (const name of exportedFunctions(input.program, input.moduleOf?.(file) ?? dtsOf(input.outDir, file))) {
             const node = module.nodes.get(name);
             if (node?.exempt === true)
                 exempt.push(`${file}::${name}`);

package/dist/derived.d.ts

@@ -0,0 +1,8 @@
+import type { CoverageReport } from './coverage.ts';
+import type { LawTypes } from './property.ts';
+import type { ManifestLaw } from './types.ts';
+export interface DerivedStore {
+    law(law: ManifestLaw, compute: () => LawTypes): LawTypes;
+    coverage(compute: () => CoverageReport): CoverageReport;
+}
+export declare function derivedStore(cwd: string, key: string | undefined): DerivedStore;

package/dist/derived.js

@@ -0,0 +1,52 @@
+// What the type checker works out from a build (each law's generator plans and shapes, the coverage report) depends
+// on nothing but that build, so it is kept next to it: an unchanged project never starts the checker.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { arbitraryOf } from "./plan.js";
+export function derivedStore(cwd, key) {
+    if (key === undefined)
+        return { law: (_law, compute) => compute(), coverage: (compute) => compute() };
+    const path = join(cwd, '.tslaws', 'derived.json');
+    let stored = { key, laws: {} };
+    try {
+        const read = JSON.parse(readFileSync(path, 'utf8'));
+        if (read.key === key)
+            stored = read;
+    }
+    catch {
+        // Nothing kept yet.
+    }
+    const save = () => {
+        try {
+            mkdirSync(join(cwd, '.tslaws'), { recursive: true });
+            writeFileSync(path, JSON.stringify(stored));
+        }
+        catch {
+            // Not keeping it is only slower.
+        }
+    };
+    return {
+        law(law, compute) {
+            const id = `${law.file}::${law.symbol ?? law.name}`;
+            const kept = stored.laws[id];
+            if (kept !== undefined)
+                return {
+                    generators: kept.plans.map(arbitraryOf),
+                    plans: kept.plans,
+                    shapes: kept.shapes.map((shape) => shape ?? undefined),
+                };
+            const types = compute();
+            stored.laws[id] = { plans: types.plans, shapes: types.shapes.map((shape) => shape ?? null) };
+            save();
+            return types;
+        },
+        coverage(compute) {
+            if (stored.coverage !== undefined)
+                return stored.coverage;
+            const report = compute();
+            stored.coverage = report;
+            save();
+            return report;
+        },
+    };
+}

package/dist/e2e.d.ts

@@ -1,15 +1,6 @@
 import type * as fc from 'fast-check';
 import { type PropertyOutcome } from './property.ts';
 import type { CheckOptions } from './types.ts';
-/** `a.e2e.laws.ts` is an accepted alias: it always drives a running app. */
-export declare function isE2eLawFile(file: string): boolean;
-/** Whether a law file imports both helper sets, which would put one file at two levels. */
-export declare function importsBoth(text: string): boolean;
-/**
- * The level a law file runs at. `*.browser.laws.ts` is a component law (in a page) unless it imports from
- * `tslaws/e2e`, which makes it an end-to-end law (in Node, driving a running app); `*.e2e.laws.ts` is always e2e.
- */
-export declare function lawMode(file: string, text: string): 'node' | 'component' | 'e2e';
 export interface E2eServerConfig {
     /** Shell command that starts the app. It runs from your project, like a package script. */
     command: string;

package/dist/e2e.js

@@ -7,26 +7,6 @@ import { join, resolve } from 'node:path';
 import { launch, resolveEngine } from "./browser.js";
 import { withE2e } from "./e2eApi.js";
 import { runProperty, summarise } from "./property.js";
-/** `a.e2e.laws.ts` is an accepted alias: it always drives a running app. */
-export function isE2eLawFile(file) {
-    return /\.e2e\.laws\.[cm]?ts$/.test(file);
-}
-const importsOf = (module) => new RegExp(`(?:from|import)\\s*['"]${module}['"]`);
-/** Whether a law file imports both helper sets, which would put one file at two levels. */
-export function importsBoth(text) {
-    return importsOf('tslaws/e2e').test(text) && importsOf('tslaws/browser').test(text);
-}
-/**
- * The level a law file runs at. `*.browser.laws.ts` is a component law (in a page) unless it imports from
- * `tslaws/e2e`, which makes it an end-to-end law (in Node, driving a running app); `*.e2e.laws.ts` is always e2e.
- */
-export function lawMode(file, text) {
-    if (isE2eLawFile(file))
-        return 'e2e';
-    if (!/\.browser\.laws\.[cm]?ts$/.test(file))
-        return 'node';
-    return importsOf('tslaws/e2e').test(text) ? 'e2e' : 'component';
-}
 const topKeys = ['baseURL', 'server', 'runs', 'timeoutMs'];
 const serverKeys = ['command', 'url', 'timeoutMs', 'reuseExisting', 'cwd'];
 /** Checks the `e2e` section of tslaws.json; unknown keys and wrong types are errors that say where. */

package/dist/generators.d.ts

@@ -1,16 +1,16 @@
-import * as fc from 'fast-check';
+import type * as fc from 'fast-check';
 import ts from 'typescript';
-export declare class UnsupportedType extends Error {
-}
-/** Marks a generated function on the wire: browser laws receive their arguments as structured data. */
-export declare const wireKey = "$tslawsFn";
-/** Replaces generated functions inside arguments with a structured-clone-safe marker `{ $tslawsFn: samples }`. */
-export declare function toWire(value: unknown): unknown;
+import { type Plan } from './plan.ts';
+export { toWire, UnsupportedType, wireKey } from './plan.ts';
 export declare class GeneratorFactory {
     private readonly checker;
     private readonly active;
     constructor(checker: ts.TypeChecker);
-    of(type: ts.Type, depth?: number): fc.Arbitrary<unknown>;
+    /** The arbitrary for `type`, built in this process. */
+    of(type: ts.Type): fc.Arbitrary<unknown>;
+    plan(type: ts.Type, depth?: number): Plan;
+    private structural;
+    /** A type with a registered generator keeps its name in the plan, so a registration made later still applies. */
     private registered;
     private union;
     private template;

package/dist/generators.js

@@ -1,104 +1,59 @@
-// Derives fast-check generators from the declared parameter types of laws, read from the declaration
-// files the compiler emitted. Full TypeScript types map: primitives, literals, unions, enums, arrays,
-// tuples, object types, index signatures, type parameters (via their constraint) and registered names.
-import * as fc from 'fast-check';
 import ts from 'typescript';
 import { arbitraryRegistry } from "./api.js";
-import { sequence } from "./sequence.js";
-export class UnsupportedType extends Error {
-}
-const numbers = fc.oneof({ weight: 4, arbitrary: fc.integer({ min: -8, max: 8 }) }, { weight: 3, arbitrary: fc.integer({ min: -1000, max: 1000 }) }, { weight: 1, arbitrary: fc.integer() }, { weight: 2, arbitrary: fc.double({ noNaN: true, noDefaultInfinity: true }) });
-// `int` from 'tslaws': whole numbers, biased to small ones.
-arbitraryRegistry().set('int', fc.oneof({ weight: 4, arbitrary: fc.integer({ min: -8, max: 8 }) }, { weight: 3, arbitrary: fc.integer({ min: -1000, max: 1000 }) }, { weight: 1, arbitrary: fc.integer({ min: -Number.MAX_SAFE_INTEGER, max: Number.MAX_SAFE_INTEGER }) }));
-/** Marks a generated function on the wire: browser laws receive their arguments as structured data. */
-export const wireKey = '$tslawsFn';
-function pick(samples, args) {
-    let key = '';
-    try {
-        key = JSON.stringify(args) ?? '';
-    }
-    catch {
-        // Arguments that are not JSON (a node, a cycle) all share the first sample.
-    }
-    let h = 5381;
-    for (let i = 0; i < key.length; i++)
-        h = (Math.imul(h, 33) + key.charCodeAt(i)) | 0;
-    return samples[(h >>> 0) % samples.length];
-}
-/**
- * A function of a type with one call signature: it returns one of a few values generated from the return type,
- * chosen by its arguments (like `fc.func`: the same arguments give the same result, `void` gives `undefined`).
- * `samples` rides along so a browser law can rebuild the function in the page.
- */
-function generatedFunction(samples) {
-    const fn = (...args) => pick(samples, args);
-    Object.defineProperty(fn, wireKey, { value: samples, enumerable: false });
-    Object.defineProperty(fn, 'toString', { value: () => `[generated function]`, enumerable: false });
-    return fn;
-}
-/** Replaces generated functions inside arguments with a structured-clone-safe marker `{ $tslawsFn: samples }`. */
-export function toWire(value) {
-    if (typeof value === 'function') {
-        const samples = value[wireKey];
-        return { [wireKey]: Array.isArray(samples) ? samples : [undefined] };
-    }
-    if (Array.isArray(value))
-        return value.map(toWire);
-    if (value !== null && typeof value === 'object') {
-        const proto = Object.getPrototypeOf(value);
-        if (proto === Object.prototype || proto === null)
-            return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, toWire(v)]));
-    }
-    return value;
-}
+import { arbitraryOf, UnsupportedType } from "./plan.js";
+export { toWire, UnsupportedType, wireKey } from "./plan.js";
 export class GeneratorFactory {
     checker;
     active = new Set();
     constructor(checker) {
         this.checker = checker;
     }
-    of(type, depth = 0) {
-        const named = this.registered(type);
-        if (named !== undefined)
-            return named;
+    /** The arbitrary for `type`, built in this process. */
+    of(type) {
+        return arbitraryOf(this.plan(type));
+    }
+    plan(type, depth = 0) {
+        return this.registered(type, depth) ?? this.structural(type, depth);
+    }
+    structural(type, depth) {
         const f = type.flags;
         if (f & ts.TypeFlags.Any || f & ts.TypeFlags.Unknown)
-            return fc.anything();
+            return { k: 'anything' };
         if (f & ts.TypeFlags.Never)
             throw new UnsupportedType('type never has no values');
         if (f & ts.TypeFlags.Void || f & ts.TypeFlags.Undefined)
-            return fc.constant(undefined);
+            return { k: 'const', v: undefined };
         if (f & ts.TypeFlags.Null)
-            return fc.constant(null);
+            return { k: 'const', v: null };
         if (f & ts.TypeFlags.BooleanLiteral)
-            return fc.constant(this.checker.typeToString(type) === 'true');
+            return { k: 'const', v: this.checker.typeToString(type) === 'true' };
         if (f & ts.TypeFlags.Boolean)
-            return fc.boolean();
+            return { k: 'boolean' };
         if (f & ts.TypeFlags.NumberLiteral)
-            return fc.constant(type.value);
+            return { k: 'const', v: type.value };
         if (f & ts.TypeFlags.StringLiteral)
-            return fc.constant(type.value);
+            return { k: 'const', v: type.value };
         if (f & ts.TypeFlags.BigIntLiteral) {
             const v = type.value;
-            return fc.constant(BigInt(`${v.negative ? '-' : ''}${v.base10Value}`));
+            return { k: 'bigconst', v: `${v.negative ? '-' : ''}${v.base10Value}` };
         }
         if (f & ts.TypeFlags.EnumLiteral && f & ts.TypeFlags.Union)
             return this.union(type, depth);
         if (f & ts.TypeFlags.Number)
-            return numbers;
+            return { k: 'number' };
         if (f & ts.TypeFlags.String)
-            return fc.string({ maxLength: 24 });
+            return { k: 'string' };
         if (f & ts.TypeFlags.BigInt)
-            return fc.bigInt();
+            return { k: 'bigint' };
         if (f & ts.TypeFlags.ESSymbol)
-            return fc.string().map((s) => Symbol(s));
+            return { k: 'symbol' };
         if (f & ts.TypeFlags.TemplateLiteral)
             return this.template(type, depth);
         if (f & ts.TypeFlags.TypeParameter) {
             const constraint = this.checker.getBaseConstraintOfType(type);
             if (constraint === undefined || constraint === type)
-                return fc.anything();
-            return this.of(constraint, depth);
+                return { k: 'anything' };
+            return this.plan(constraint, depth);
         }
         if (f & ts.TypeFlags.Union)
             return this.union(type, depth);
@@ -107,59 +62,66 @@ export class GeneratorFactory {
         if (f & ts.TypeFlags.Object)
             return this.object(type, depth);
         if (f & ts.TypeFlags.NonPrimitive)
-            return fc.object();
+            return { k: 'object' };
         throw new UnsupportedType(`no generator for type ${this.checker.typeToString(type)}`);
     }
-    registered(type) {
+    /** A type with a registered generator keeps its name in the plan, so a registration made later still applies. */
+    registered(type, depth) {
         const symbol = type.aliasSymbol ?? type.getSymbol();
         if (symbol === undefined)
             return undefined;
-        return arbitraryRegistry().get(symbol.getName());
+        const name = symbol.getName();
+        if (!arbitraryRegistry().has(name))
+            return undefined;
+        if (name === 'int')
+            return { k: 'named', name };
+        // What to generate if the registration is not there where the plan is used (a worker has only the built-in ones).
+        // `int` and the like are intersections that have no useful structure, so a type that cannot be planned has none.
+        try {
+            return { k: 'named', name, fallback: this.structural(type, depth) };
+        }
+        catch (error) {
+            if (error instanceof UnsupportedType)
+                return { k: 'named', name };
+            throw error;
+        }
     }
     union(type, depth) {
         const members = type.types.filter((t) => !(t.flags & ts.TypeFlags.Never));
-        return fc.oneof(...members.map((member) => this.of(member, depth)));
+        return { k: 'union', of: members.map((member) => this.plan(member, depth)) };
     }
     template(type, depth) {
-        const parts = [fc.constant(type.texts[0] ?? '')];
-        type.types.forEach((t, i) => {
-            parts.push(this.of(t, depth).map(String));
-            parts.push(fc.constant(type.texts[i + 1] ?? ''));
-        });
-        return fc.tuple(...parts).map((p) => p.join(''));
+        return { k: 'template', texts: [...type.texts], parts: type.types.map((t) => this.plan(t, depth)) };
     }
     object(type, depth) {
         const checker = this.checker;
         if (this.active.has(type) || depth > 4)
-            return fc.constant(undefined);
+            return { k: 'const', v: undefined };
         const name = type.getSymbol()?.getName();
         if (name === 'Date')
-            return fc.date({ noInvalidDate: true });
+            return { k: 'date' };
         if (name === 'RegExp')
-            return fc.constant(/x/);
+            return { k: 'regexp' };
         if (checker.isArrayType(type)) {
             const element = checker.getTypeArguments(type)[0];
-            return sequence(this.of(element, depth + 1), { maxLength: 8 });
+            return { k: 'array', of: this.plan(element, depth + 1) };
         }
         if (checker.isTupleType(type)) {
             const target = type.target;
             const args = checker.getTypeArguments(type);
-            const required = args.slice(0, target.minLength).map((t) => this.of(t, depth + 1));
-            const optional = args.slice(target.minLength).map((t) => this.of(t, depth + 1));
-            return fc.tuple(...required).chain((head) => {
-                if (optional.length === 0)
-                    return fc.constant(head);
-                return fc.tuple(...optional).map((tail) => [...head, ...tail]);
-            });
+            return {
+                k: 'tuple',
+                required: args.slice(0, target.minLength).map((t) => this.plan(t, depth + 1)),
+                optional: args.slice(target.minLength).map((t) => this.plan(t, depth + 1)),
+            };
         }
         if (type.getCallSignatures().length > 0) {
             const signature = type.getCallSignatures()[0];
-            const returns = this.of(checker.getReturnTypeOfSignature(signature), depth + 1);
-            return fc.array(returns, { minLength: 1, maxLength: 4 }).map(generatedFunction);
+            return { k: 'fn', returns: this.plan(checker.getReturnTypeOfSignature(signature), depth + 1) };
         }
         this.active.add(type);
         try {
-            const model = {};
+            const fields = {};
             const required = [];
             for (const property of checker.getPropertiesOfType(type)) {
                 const declaration = property.valueDeclaration ?? property.declarations?.[0];
@@ -167,16 +129,14 @@ export class GeneratorFactory {
                     continue;
                 const propertyType = checker.getTypeOfSymbolAtLocation(property, declaration);
                 const optional = (property.flags & ts.SymbolFlags.Optional) !== 0;
-                const generator = this.of(optional ? checker.getNonNullableType(propertyType) : propertyType, depth + 1);
-                model[property.getName()] = generator;
+                fields[property.getName()] = this.plan(optional ? checker.getNonNullableType(propertyType) : propertyType, depth + 1);
                 if (!optional)
                     required.push(property.getName());
             }
             const index = checker.getIndexInfosOfType(type)[0];
-            if (index !== undefined && Object.keys(model).length === 0) {
-                return fc.dictionary(fc.string({ maxLength: 6 }), this.of(index.type, depth + 1), { maxKeys: 6 });
-            }
-            return fc.record(model, { requiredKeys: required });
+            if (index !== undefined && Object.keys(fields).length === 0)
+                return { k: 'dict', of: this.plan(index.type, depth + 1) };
+            return { k: 'record', fields, required };
         }
         finally {
             this.active.delete(type);

package/dist/globs.d.ts

@@ -0,0 +1,3 @@
+export declare function globToRegExp(glob: string): RegExp;
+/** A predicate for a list of globs: a path matches when an include glob matches and no `!` glob does. */
+export declare function globMatcher(globs: string[]): (file: string) => boolean;

package/dist/globs.js

@@ -0,0 +1,24 @@
+// Glob matching for the path settings of tslaws.json (`cover`, `laws`): `*` stays in one directory, `**` crosses them.
+export function globToRegExp(glob) {
+    let out = '';
+    for (let i = 0; i < glob.length; i += 1) {
+        const ch = glob[i];
+        if (ch === '*' && glob[i + 1] === '*') {
+            out += '.*';
+            i += glob[i + 2] === '/' ? 2 : 1;
+        }
+        else if (ch === '*')
+            out += '[^/]*';
+        else if (ch === '?')
+            out += '[^/]';
+        else
+            out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^${out}$`);
+}
+/** A predicate for a list of globs: a path matches when an include glob matches and no `!` glob does. */
+export function globMatcher(globs) {
+    const include = globs.filter((g) => !g.startsWith('!')).map(globToRegExp);
+    const exclude = globs.filter((g) => g.startsWith('!')).map((g) => globToRegExp(g.slice(1)));
+    return (file) => include.some((r) => r.test(file)) && !exclude.some((r) => r.test(file));
+}

package/dist/init.js

@@ -6,13 +6,13 @@ export const agentsBegin = '<!-- tslaws:begin -->';
 export const agentsEnd = '<!-- tslaws:end -->';
 export const nextStep = 'Next, a person at a terminal runs `tslaws accept` to record the laws in tsc-laws.lock.';
 const hooksDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'hooks');
-const starterLaws = `// A starter law. A person owns this file: agents propose laws in *.proposed.laws.ts instead.
+const starterLaws = `// A starter law, written as a call so it needs only stock TypeScript (with the tsc-laws compiler it can also be
+// written as \`export law additionCommutes(a: int, b: int) { ... }\`). A person owns this file: agents propose laws in
+// *.proposed.laws.ts instead.
 // Replace it with laws about your own code, then run \`tslaws accept\`.
-import type { int } from 'tslaws';
+import { law, type int } from 'tslaws';
 
-export law additionCommutes(a: int, b: int) {
-  return a + b === b + a;
-}
+law('addition commutes', (a: int, b: int) => a + b === b + a);
 `;
 function writeFile(file, text) {
     mkdirSync(dirname(file), { recursive: true });

package/dist/lawFiles.d.ts

@@ -0,0 +1,21 @@
+/** Directories no walk enters. */
+export declare const ignoredDirs: Set<string>;
+/** The tool-owned directory proposals live in, relative to the project root. */
+export declare const proposalsDir = ".tslaws/proposals";
+/** Whether the text declares a law at the top level (cheap test first, then the real scan). */
+export declare function declaresLaw(text: string): boolean;
+/** A predicate for files the `laws` globs of tslaws.json pick, which still have to declare a law to count. */
+export declare function customLawFile(cwd: string, globs?: string[] | undefined): (file: string) => boolean;
+/**
+ * The laws files of the tree, project-relative and sorted: `*.laws.ts` plus the files the `laws` globs find. With
+ * `proposed`, the in-tree `*.proposed.laws.ts` files instead (the usual proposals; `discoverProposals` finds the optional ones in `.tslaws/proposals`).
+ */
+export declare function discoverLaws(cwd: string, proposed?: boolean): string[];
+/** The files in `.tslaws/proposals/` (any name ending `.ts`), project-relative and sorted. */
+export declare function discoverProposals(cwd: string): string[];
+/** Whether a project-relative path is a laws file of the tree (not a proposal). */
+export declare function isLawsFile(cwd: string, file: string): boolean;
+/** Whether a project-relative path is inside the proposals directory. */
+export declare function inProposals(file: string): boolean;
+/** Whether a (possibly new) path is a name a laws file may have: `*.laws.ts`, or a path a `laws` glob picks. */
+export declare function namesLawsFile(cwd: string, file: string): boolean;

package/dist/lawFiles.js

@@ -0,0 +1,95 @@
+// Which files are laws files. Every `*.laws.ts` is one; with a `laws` setting in tslaws.json, so is any file the globs
+// match that declares a top-level `export law`. Proposals are separate: they live in `.tslaws/proposals/`, outside the
+// tree the lock covers (in-tree `*.proposed.laws.ts` files are the usual proposals and keep working).
+import { existsSync, lstatSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { readConfig } from "./coverage.js";
+import { globMatcher } from "./globs.js";
+import { isProposedLawFile } from "./lawNames.js";
+import { parseLawFile } from "./promote.js";
+/** Directories no walk enters. */
+export const ignoredDirs = new Set(['node_modules', '.tslaws', '.git']);
+/** The tool-owned directory proposals live in, relative to the project root. */
+export const proposalsDir = '.tslaws/proposals';
+const slash = (path) => path.replaceAll('\\', '/');
+/** Whether the text declares a law at the top level (cheap test first, then the real scan). */
+export function declaresLaw(text) {
+    return /\bexport\s+(?:async\s+)?law\b/.test(text) && parseLawFile(text).laws.length > 0;
+}
+function walk(cwd, visit) {
+    const step = (dir) => {
+        for (const entry of readdirSync(dir).sort()) {
+            if (ignoredDirs.has(entry))
+                continue;
+            const full = join(dir, entry);
+            if (statSync(full).isDirectory())
+                step(full);
+            else
+                visit(slash(relative(cwd, full)));
+        }
+    };
+    step(cwd);
+}
+/** A predicate for files the `laws` globs of tslaws.json pick, which still have to declare a law to count. */
+export function customLawFile(cwd, globs = readConfig(cwd).laws) {
+    if (globs === undefined || globs.length === 0)
+        return () => false;
+    const matches = globMatcher(globs);
+    return (file) => {
+        if (!/\.(ts|tsx|mts|cts)$/.test(file) || /\.d\.(ts|mts|cts)$/.test(file) || !matches(file))
+            return false;
+        try {
+            return declaresLaw(readFileSync(join(cwd, file), 'utf8'));
+        }
+        catch {
+            return false;
+        }
+    };
+}
+/**
+ * The laws files of the tree, project-relative and sorted: `*.laws.ts` plus the files the `laws` globs find. With
+ * `proposed`, the in-tree `*.proposed.laws.ts` files instead (the usual proposals; `discoverProposals` finds the optional ones in `.tslaws/proposals`).
+ */
+export function discoverLaws(cwd, proposed = false) {
+    const custom = customLawFile(cwd);
+    const found = [];
+    walk(cwd, (file) => {
+        const name = file.slice(file.lastIndexOf('/') + 1);
+        if (name.endsWith('.laws.ts')) {
+            if (isProposedLawFile(name) === proposed)
+                found.push(file);
+        }
+        else if (!proposed && custom(file))
+            found.push(file);
+    });
+    return found.sort();
+}
+/** The files in `.tslaws/proposals/` (any name ending `.ts`), project-relative and sorted. */
+export function discoverProposals(cwd) {
+    const dir = join(cwd, proposalsDir);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((entry) => /\.(ts|mts|cts)$/.test(entry) && !/\.d\.(ts|mts|cts)$/.test(entry) && lstatSync(join(dir, entry)).isFile())
+        .map((entry) => `${proposalsDir}/${entry}`)
+        .sort();
+}
+/** Whether a project-relative path is a laws file of the tree (not a proposal). */
+export function isLawsFile(cwd, file) {
+    const name = slash(file);
+    return name.endsWith('.laws.ts') || customLawFile(cwd)(name);
+}
+/** Whether a project-relative path is inside the proposals directory. */
+export function inProposals(file) {
+    return slash(file).startsWith(`${proposalsDir}/`);
+}
+/** Whether a (possibly new) path is a name a laws file may have: `*.laws.ts`, or a path a `laws` glob picks. */
+export function namesLawsFile(cwd, file) {
+    const name = slash(file);
+    if (isProposedLawFile(name))
+        return false;
+    if (name.endsWith('.laws.ts'))
+        return true;
+    const globs = readConfig(cwd).laws;
+    return globs !== undefined && /\.(ts|mts|cts)$/.test(name) && globMatcher(globs)(name);
+}