tslaws 0.6.4 → 0.7.0

package/dist/promote.js

@@ -1,15 +1,20 @@
 // `tslaws promote`: the pure core. A person moves proposed laws into the accepted file; the lock is not touched here.
-import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, posix, relative } from 'node:path';
 import ts from 'typescript';
-/** `foo.proposed.laws.ts` -> `foo.laws.ts`; undefined for any other name. */
+import { ignoredDirs, namesLawsFile } from "./lawFiles.js";
+import { directProjectImports } from "./lawKinds.js";
+import { acceptedLawName, isProposedLawFile } from "./lawNames.js";
+import { existingProposal, importsForTarget, ProposalError } from "./proposals.js";
+/**
+ * `foo.proposed.laws.ts` -> `foo.laws.ts`, `foo.browser.proposed.laws.ts` -> `foo.browser.laws.ts` and
+ * `foo.e2e.proposed.laws.ts` -> `foo.e2e.laws.ts`, so a proposal lands in a file of its own kind; undefined for any other name.
+ */
 export function acceptedPathFor(proposed) {
-    return proposed.endsWith('.proposed.laws.ts')
-        ? `${proposed.slice(0, -'.proposed.laws.ts'.length)}.laws.ts`
-        : undefined;
+    return isProposedLawFile(proposed) ? acceptedLawName(proposed) : undefined;
 }
 /**
- * Finds the import statements and the `export law ...` declarations of a laws file. `law` is not standard TypeScript, so
+ * Finds the import statements and the laws of a laws file, as `export law ...` declarations or as `law('name', ...)` calls. The keyword is not standard TypeScript, so
  * this scans tokens with the TypeScript scanner (strings, comments and templates are skipped correctly) and matches
  * brackets: a law ends at its closing `}` or at a `;` at depth 0.
  */
@@ -107,8 +112,37 @@ export function parseLawFile(text) {
         kind = scanner.scan();
     }
     finish(text.length);
+    for (const call of callLaws(text))
+        if (!laws.some((l) => call.start >= l.start && call.start < l.end))
+            laws.push(call);
+    laws.sort((a, b) => a.start - b.start);
     return { imports, laws };
 }
+/** The call-style laws: top-level `law('name', ...)` and `law.proved('name', ...)` statements, found in the syntax tree. */
+function callLaws(text) {
+    const source = ts.createSourceFile('laws.ts', text, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+    const found = [];
+    for (const statement of source.statements) {
+        if (!ts.isExpressionStatement(statement) || !ts.isCallExpression(statement.expression))
+            continue;
+        const { expression: callee, arguments: args } = statement.expression;
+        const isLaw = (ts.isIdentifier(callee) && callee.text === 'law') ||
+            (ts.isPropertyAccessExpression(callee) &&
+                ts.isIdentifier(callee.expression) &&
+                callee.expression.text === 'law' &&
+                callee.name.text === 'proved');
+        const name = args[0];
+        if (!isLaw || name === undefined || !(ts.isStringLiteral(name) || ts.isNoSubstitutionTemplateLiteral(name)))
+            continue;
+        found.push({
+            name: name.text,
+            text: text.slice(statement.getStart(source), statement.end),
+            start: statement.getStart(source),
+            end: statement.end,
+        });
+    }
+    return found;
+}
 const squash = (s) => s.replace(/\s+/g, ' ').trim();
 /** Joins the import statements, dropping repeats by whitespace-insensitive text. */
 export function dedupeImports(existing, added) {
@@ -215,3 +249,95 @@ export async function promoteFiles(host, proposedFiles) {
         host.out('\nThe lock is unchanged. Review the diff, then run `tslaws accept` to record these laws.\n');
     return promoted;
 }
+/** The path `promote` suggests for a proposal: beside the source it imports, else under `laws/`. */
+export function defaultTarget(cwd, proposal) {
+    const name = posix
+        .basename(proposal)
+        .replace(/\.(?:ts|mts|cts)$/, '')
+        .replace(/\.laws$/, '');
+    const source = directProjectImports(cwd, proposal).find((file) => !file.startsWith('.tslaws/'));
+    const dir = source === undefined ? 'laws' : posix.dirname(source);
+    return `${dir === '.' ? '' : `${dir}/`}${name}.laws.ts`;
+}
+/**
+ * A path a promoted proposal may be written to, as a project-relative slash path: inside the project, a name laws
+ * files have (`*.laws.ts`, or a path a `laws` glob picks), not in a reserved directory, and not through a link.
+ */
+export function promotionTarget(cwd, to) {
+    if (isAbsolute(to))
+        throw new ProposalError(`'${to}' must be relative to the project root`);
+    const rel = posix.normalize(to.replaceAll('\\', '/'));
+    if (rel.startsWith('..') || rel === '.' || rel.startsWith('/'))
+        throw new ProposalError(`'${to}' is outside the project`);
+    if (rel.split('/').some((part) => ignoredDirs.has(part)))
+        throw new ProposalError(`'${to}' is in a reserved directory (node_modules, .tslaws or .git)`);
+    if (!namesLawsFile(cwd, rel))
+        throw new ProposalError(`'${to}' would not be found as a laws file: name it *.laws.ts, or list a glob for it in "laws" in tslaws.json`);
+    const abs = join(cwd, rel);
+    let probe = dirname(abs);
+    while (!existsSync(probe))
+        probe = dirname(probe);
+    const back = relative(realpathSync(cwd), realpathSync(probe));
+    if (back.startsWith('..') || isAbsolute(back))
+        throw new ProposalError(`'${to}' is outside the project`);
+    try {
+        if (lstatSync(abs).isSymbolicLink())
+            throw new ProposalError(`'${to}' is a link`);
+    }
+    catch (error) {
+        if (error instanceof ProposalError)
+            throw error;
+    }
+    return rel;
+}
+const plural = (n) => `${n} law${n === 1 ? '' : 's'}`;
+/**
+ * Moves one proposal into the tree. Shows each law with its result, asks the person to confirm the target path (the
+ * default, or `to` when given, or another typed path), rewrites the proposal's relative imports for the new directory,
+ * merges into the target if it already exists, and removes the proposal. The lock is never written: the laws stay
+ * unaccepted, and `check` fails them as not in the lock until a person runs `tslaws accept`.
+ */
+export async function promoteProposal(host, file, to) {
+    const { rel, abs } = existingProposal(host.cwd, file);
+    const text = readFileSync(abs, 'utf8');
+    const parsed = parseLawFile(text);
+    if (parsed.laws.length === 0) {
+        host.out(`${rel}: no laws\n`);
+        return {};
+    }
+    const results = await host.checkFile(rel);
+    for (const law of parsed.laws)
+        host.out(`\n${rel}: ${law.name}  [${results.get(law.name) ?? 'not checked'}]\n${law.text.trim()}\n`);
+    const suggested = to ?? defaultTarget(host.cwd, rel);
+    const answer = (await host.ask(`\nmove ${plural(parsed.laws.length)} to ${suggested}?\nEnter accepts that path, another path replaces it, n cancels: `)).trim();
+    if (answer.toLowerCase() === 'n' || answer.toLowerCase() === 'no') {
+        host.out('nothing moved\n');
+        return {};
+    }
+    let target;
+    try {
+        target = promotionTarget(host.cwd, answer === '' || answer.toLowerCase() === 'y' ? suggested : answer);
+    }
+    catch (error) {
+        host.out(`${error instanceof Error ? error.message : String(error)}; nothing moved\n`);
+        return {};
+    }
+    const targetPath = join(host.cwd, target);
+    const existing = existsSync(targetPath) ? readFileSync(targetPath, 'utf8') : undefined;
+    const toDir = posix.dirname(target);
+    const moved = parseLawFile(importsForTarget(text, toDir === '.' ? '' : toDir));
+    let built;
+    try {
+        built = buildAccepted(existing, moved.imports, moved.laws);
+    }
+    catch (error) {
+        host.out(`${target}: ${error instanceof Error ? error.message : String(error)}; nothing moved\n`);
+        return {};
+    }
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, built);
+    rmSync(abs);
+    host.out(`${plural(parsed.laws.length)} moved to ${target}; ${rel} removed\n` +
+        'The lock is unchanged: until a person runs `tslaws accept`, `tslaws check` fails these laws as not in the lock.\n');
+    return { target };
+}

package/dist/property.d.ts

@@ -1,39 +1,25 @@
-import * as fc from 'fast-check';
+import type * as fc from 'fast-check';
 import ts from 'typescript';
+import { type Plan } from './plan.ts';
+import { type PropertyOutcome } from './propertyRun.ts';
 import type { Shape } from './smt.ts';
 import type { CheckOptions, ManifestLaw } from './types.ts';
+export { isDiscard, jsPath, runLaw, runProperty, summarise, type PropertyOutcome } from './propertyRun.ts';
 export interface LawTypes {
     generators: fc.Arbitrary<unknown>[];
+    /** The generators as data, for a worker that does not load TypeScript. */
+    plans: Plan[];
     shapes: Shape[];
 }
 /** Every declaration file the compiler emitted: the laws' own do not import the code they are about. */
 export declare function declarationFiles(outDir: string): string[];
 export declare function dtsPath(outDir: string, file: string): string;
-export declare function jsPath(outDir: string, file: string): string;
 /** What the prover models of `type`: numbers, `int`s, bigints, strings, booleans, arrays and records of them. */
 export declare function shapeOf(checker: ts.TypeChecker, type: ts.Type): Shape;
-export declare function typesOf(program: ts.Program, outDir: string, law: ManifestLaw): LawTypes;
-export declare function isDiscard(error: unknown): boolean;
-/** Runs `call` on generated inputs. `call` may be async (a law that waits, or one that runs in a browser). */
-export declare function runProperty(call: (...args: unknown[]) => unknown, generators: fc.Arbitrary<unknown>[], options: CheckOptions): Promise<fc.RunDetails<unknown[]>>;
-export declare const runLaw: typeof runProperty;
+/** `cwd` is given when `program` is the one that compiled the laws, whose source files hold the types the declarations would. */
+export declare function typesOf(program: ts.Program, outDir: string, law: ManifestLaw, cwd?: string): LawTypes;
 export declare const compilerOptions: ts.CompilerOptions;
-/** The outcome of a law's property test, without the generated values' prototypes so it can cross a thread. */
-export interface PropertyOutcome {
-    failed: boolean;
-    numRuns: number;
-    seed: number;
-    /** Absent when the law failed because `assume` discarded nearly every input. */
-    counterexample?: string;
-    message?: string;
-    /** The stack of the error the law threw, to say which function threw. */
-    stack?: string;
-    screenshot?: string;
-    /** The counterexample in the regression corpus's encoding; absent when it cannot be stored. */
-    encoded?: string;
-    /** Whether the counterexample is one that was replayed from the corpus. */
-    regression?: boolean;
-}
-export declare function summarise(details: fc.RunDetails<unknown[]>, options?: CheckOptions): PropertyOutcome;
-/** Runs the property test of `law` in a worker, giving up on it after `options.propertyTimeoutMs`. */
-export declare function runLawGuarded(outDir: string, law: ManifestLaw, options: CheckOptions): Promise<PropertyOutcome | 'timeout'>;
+/** Starts `n` property workers ahead of the first law, so they load while the code compiles. */
+export declare function warmWorkers(n: number): void;
+/** Runs the property test of `law` in a pooled worker, giving up on it after `options.propertyTimeoutMs`. */
+export declare function runLawGuarded(outDir: string, law: ManifestLaw, options: CheckOptions, plans: Plan[]): Promise<PropertyOutcome | 'timeout'>;

package/dist/property.js

@@ -1,10 +1,11 @@
 import { Worker } from 'node:worker_threads';
 import { readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
-import * as fc from 'fast-check';
+import { join, resolve } from 'node:path';
 import ts from 'typescript';
-import { GeneratorFactory, UnsupportedType } from "./generators.js";
-import { decodeExample, encodeExample } from "./regressions.js";
+import { GeneratorFactory } from "./generators.js";
+import { arbitraryOf, UnsupportedType } from "./plan.js";
+import { WorkerPool } from "./pool.js";
+export { isDiscard, jsPath, runLaw, runProperty, summarise } from "./propertyRun.js";
 /** Every declaration file the compiler emitted: the laws' own do not import the code they are about. */
 export function declarationFiles(outDir) {
     const found = [];
@@ -25,9 +26,6 @@ export function declarationFiles(outDir) {
 export function dtsPath(outDir, file) {
     return join(outDir, file.replace(/\.(ts|tsx|mts|cts)$/, '.d.ts'));
 }
-export function jsPath(outDir, file) {
-    return join(outDir, file.replace(/\.(ts|tsx|mts|cts)$/, '.js'));
-}
 /** What the prover models of `type`: numbers, `int`s, bigints, strings, booleans, arrays and records of them. */
 export function shapeOf(checker, type) {
     if ((type.aliasSymbol ?? type.getSymbol())?.getName() === 'int' &&
@@ -61,22 +59,25 @@ export function shapeOf(checker, type) {
     }
     return { fields };
 }
-export function typesOf(program, outDir, law) {
+/** `cwd` is given when `program` is the one that compiled the laws, whose source files hold the types the declarations would. */
+export function typesOf(program, outDir, law, cwd) {
     const checker = program.getTypeChecker();
-    const source = program.getSourceFile(dtsPath(outDir, law.file));
+    const source = cwd === undefined
+        ? program.getSourceFile(dtsPath(outDir, law.file))
+        : program.getSourceFile(resolve(cwd, law.file));
     if (source === undefined)
         throw new UnsupportedType(`no declaration output for ${law.file}`);
     const moduleSymbol = checker.getSymbolAtLocation(source);
     const exported = moduleSymbol === undefined
         ? undefined
-        : checker.getExportsOfModule(moduleSymbol).find((s) => s.getName() === law.name);
+        : checker.getExportsOfModule(moduleSymbol).find((s) => s.getName() === (law.symbol ?? law.name));
     if (exported === undefined)
         throw new UnsupportedType(`law ${law.name} is not in the declaration output`);
     const signature = checker.getTypeOfSymbol(exported).getCallSignatures()[0];
     if (signature === undefined)
         throw new UnsupportedType(`law ${law.name} is not a function`);
     const factory = new GeneratorFactory(checker);
-    const generators = [];
+    const plans = [];
     const shapes = [];
     for (const parameter of signature.getParameters()) {
         const declaration = parameter.valueDeclaration ?? parameter.declarations?.[0];
@@ -85,35 +86,10 @@ export function typesOf(program, outDir, law) {
         const type = checker.getTypeOfSymbolAtLocation(parameter, declaration);
         shapes.push(shapeOf(checker, type));
         const optional = (parameter.flags & ts.SymbolFlags.Optional) !== 0;
-        generators.push(factory.of(optional ? checker.getNonNullableType(type) : type));
+        plans.push(factory.plan(optional ? checker.getNonNullableType(type) : type));
     }
-    return { generators, shapes };
-}
-export function isDiscard(error) {
-    return error instanceof Error && error.name === 'LawDiscard';
-}
-/** Runs `call` on generated inputs. `call` may be async (a law that waits, or one that runs in a browser). */
-export async function runProperty(call, generators, options) {
-    const property = fc.asyncProperty(...generators, async (...args) => {
-        try {
-            return (await call(...args)) !== false;
-        }
-        catch (error) {
-            if (isDiscard(error)) {
-                fc.pre(false);
-                return true;
-            }
-            throw error;
-        }
-    });
-    return (await fc.check(property, {
-        numRuns: options.runs,
-        seed: options.seed,
-        maxSkipsPerRun: 100,
-        ...(options.regressionExamples?.length ? { examples: options.regressionExamples.map(decodeExample) } : {}),
-    }));
+    return { generators: plans.map(arbitraryOf), plans, shapes };
 }
-export const runLaw = runProperty;
 export const compilerOptions = {
     skipLibCheck: true,
     strict: true,
@@ -122,52 +98,35 @@ export const compilerOptions = {
     moduleResolution: ts.ModuleResolutionKind.Bundler,
     types: [],
 };
-export function summarise(details, options) {
-    const message = details.errorInstance instanceof Error ? details.errorInstance.message : undefined;
-    let encoded;
-    if (details.failed && details.counterexample !== null) {
-        try {
-            encoded = encodeExample(details.counterexample);
-        }
-        catch {
-            // Not storable (a class instance, a function): it is reported but not kept.
-        }
-    }
-    return {
-        encoded,
-        regression: encoded !== undefined && options?.regressionExamples?.includes(encoded) === true,
-        failed: details.failed,
-        numRuns: details.numRuns,
-        seed: details.seed,
-        counterexample: details.counterexample === null ? undefined : fc.stringify(details.counterexample),
-        message,
-        stack: details.errorInstance instanceof Error ? details.errorInstance.stack : undefined,
-    };
-}
-let worker;
-/** Runs the property test of `law` in a worker, giving up on it after `options.propertyTimeoutMs`. */
-export function runLawGuarded(outDir, law, options) {
+const workers = new WorkerPool(() => {
     const ext = import.meta.url.endsWith('.ts') ? '.ts' : '.js';
-    if (worker === undefined) {
-        worker = new Worker(new URL(`./propertyWorker${ext}`, import.meta.url));
-        worker.unref();
-    }
-    const current = worker;
+    const worker = new Worker(new URL(`./propertyWorker${ext}`, import.meta.url));
+    worker.unref();
+    return worker;
+});
+/** Starts `n` property workers ahead of the first law, so they load while the code compiles. */
+export function warmWorkers(n) {
+    workers.warm(n);
+}
+/** Runs the property test of `law` in a pooled worker, giving up on it after `options.propertyTimeoutMs`. */
+export async function runLawGuarded(outDir, law, options, plans) {
+    const current = await workers.acquire();
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
-            if (worker === current)
-                worker = undefined;
-            void current.terminate();
+            current.off('message', onMessage);
+            workers.discard(current);
             resolve('timeout');
         }, options.propertyTimeoutMs ?? 30000);
-        current.once('message', (message) => {
+        const onMessage = (message) => {
             clearTimeout(timer);
+            workers.release(current);
             if (message.ok !== undefined)
                 resolve(message.ok);
             else
                 reject(new Error(message.error));
-        });
+        };
+        current.once('message', onMessage);
         // Functions cannot cross to the worker; it needs only the numbers.
-        current.postMessage({ outDir, law, options: { ...options, onEvent: undefined } });
+        current.postMessage({ outDir, law, plans, options: { ...options, onEvent: undefined } });
     });
 }

package/dist/propertyRun.d.ts

@@ -0,0 +1,24 @@
+import * as fc from 'fast-check';
+import type { CheckOptions } from './types.ts';
+export declare function jsPath(outDir: string, file: string): string;
+export declare function isDiscard(error: unknown): boolean;
+/** Runs `call` on generated inputs. `call` may be async (a law that waits, or one that runs in a browser). */
+export declare function runProperty(call: (...args: unknown[]) => unknown, generators: fc.Arbitrary<unknown>[], options: CheckOptions): Promise<fc.RunDetails<unknown[]>>;
+export declare const runLaw: typeof runProperty;
+/** The outcome of a law's property test, without the generated values' prototypes so it can cross a thread. */
+export interface PropertyOutcome {
+    failed: boolean;
+    numRuns: number;
+    seed: number;
+    /** Absent when the law failed because `assume` discarded nearly every input. */
+    counterexample?: string;
+    message?: string;
+    /** The stack of the error the law threw, to say which function threw. */
+    stack?: string;
+    screenshot?: string;
+    /** The counterexample in the regression corpus's encoding; absent when it cannot be stored. */
+    encoded?: string;
+    /** Whether the counterexample is one that was replayed from the corpus. */
+    regression?: boolean;
+}
+export declare function summarise(details: fc.RunDetails<unknown[]>, options?: CheckOptions): PropertyOutcome;

package/dist/propertyRun.js

@@ -0,0 +1,56 @@
+// Running a property test, without the TypeScript compiler: this is all a property worker loads.
+import { join } from 'node:path';
+import * as fc from 'fast-check';
+import { decodeExample, encodeExample } from "./regressions.js";
+export function jsPath(outDir, file) {
+    return join(outDir, file.replace(/\.(ts|tsx|mts|cts)$/, '.js'));
+}
+export function isDiscard(error) {
+    return error instanceof Error && error.name === 'LawDiscard';
+}
+/** Runs `call` on generated inputs. `call` may be async (a law that waits, or one that runs in a browser). */
+export async function runProperty(call, generators, options) {
+    // fast-check needs at least one arbitrary: a law without parameters gets a stand-in and runs once.
+    const none = generators.length === 0;
+    const property = fc.asyncProperty(...(none ? [fc.constant(undefined)] : generators), async (...args) => {
+        try {
+            return (await call(...(none ? [] : args))) !== false;
+        }
+        catch (error) {
+            if (isDiscard(error)) {
+                fc.pre(false);
+                return true;
+            }
+            throw error;
+        }
+    });
+    return (await fc.check(property, {
+        numRuns: none ? 1 : options.runs,
+        seed: options.seed,
+        maxSkipsPerRun: 100,
+        ...(!none && options.regressionExamples?.length ? { examples: options.regressionExamples.map(decodeExample) } : {}),
+    }));
+}
+export const runLaw = runProperty;
+export function summarise(details, options) {
+    const message = details.errorInstance instanceof Error ? details.errorInstance.message : undefined;
+    let encoded;
+    if (details.failed && details.counterexample !== null) {
+        try {
+            encoded = encodeExample(details.counterexample);
+        }
+        catch {
+            // Not storable (a class instance, a function): it is reported but not kept.
+        }
+    }
+    return {
+        encoded,
+        regression: encoded !== undefined && options?.regressionExamples?.includes(encoded) === true,
+        failed: details.failed,
+        numRuns: details.numRuns,
+        seed: details.seed,
+        counterexample: details.counterexample === null ? undefined : fc.stringify(details.counterexample),
+        message,
+        stack: details.errorInstance instanceof Error ? details.errorInstance.stack : undefined,
+    };
+}

package/dist/propertyWorker.js

@@ -1,22 +1,20 @@
 import { createRequire } from 'node:module';
 import { parentPort } from 'node:worker_threads';
-import ts from 'typescript';
-import { compilerOptions, declarationFiles, jsPath, runLaw, summarise, typesOf } from "./property.js";
+import { arbitraryOf } from "./plan.js";
+import { jsPath, runLaw, summarise } from "./propertyRun.js";
 // Property tests run here so that a law over code that never terminates costs a timeout, not the whole check.
+// The main process read the types and sends the generators as plans, so a worker never loads the TypeScript compiler.
 const require = createRequire(import.meta.url);
-let programOf;
 parentPort.on('message', async (request) => {
     try {
-        const { outDir, law, options } = request;
-        if (programOf?.outDir !== outDir)
-            programOf = { outDir, program: ts.createProgram(declarationFiles(outDir), compilerOptions) };
-        const types = typesOf(programOf.program, outDir, law);
+        const { outDir, law, plans, options } = request;
+        const generators = plans.map(arbitraryOf);
         // The worker outlives a check, and the code may have been recompiled since the last one.
         for (const loaded of Object.keys(require.cache))
             if (loaded.startsWith(outDir))
                 delete require.cache[loaded];
-        const fn = require(jsPath(outDir, law.file))[law.name];
-        parentPort.postMessage({ ok: summarise(await runLaw(fn, types.generators, options), options) });
+        const fn = require(jsPath(outDir, law.file))[law.symbol ?? law.name];
+        parentPort.postMessage({ ok: summarise(await runLaw(fn, generators, options), options) });
     }
     catch (error) {
         parentPort.postMessage({ error: error.message });

package/dist/proposals.d.ts

@@ -0,0 +1,43 @@
+/** A refusal with a message for the person or agent that asked. */
+export declare class ProposalError extends Error {
+}
+/**
+ * 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 declare function proposalsDirectory(cwd: string, create: boolean): string | undefined;
+/**
+ * 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 declare function proposalName(file: string): string;
+/** The absolute path of an existing proposal for reading or removing; refuses links the same way. */
+export declare function existingProposal(cwd: string, file: string): {
+    rel: string;
+    abs: string;
+};
+/** Stores root-relative `./x` imports relative to the proposals directory. Idempotent for stored text. */
+export declare function toStoredImports(text: string): string;
+/** Re-expresses the relative imports of a stored proposal for a file in the project-relative directory `toDir`. */
+export declare function importsForTarget(text: string, toDir: string): string;
+/** 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 interface Written {
+    /** Project-relative path of the proposal. */
+    file: string;
+    /** The names of the laws the source declared. */
+    laws: string[];
+}
+/**
+ * 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 declare function addProposal(cwd: string, file: string, source: string, only?: string): Written;
+/**
+ * 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 declare function normaliseProposal(cwd: string, file: string): boolean;