tslaws 0.6.4 → 0.7.0

package/dist/migrate/source.js

@@ -0,0 +1,163 @@
+// A source file with the edits made to it so far, and the means to copy parts of it into a new file: text is taken from
+// the original (comments and all), edits are applied to it, and the indentation is changed without touching template strings.
+import ts from 'typescript';
+export function scriptKindOf(file) {
+    if (file.endsWith('.tsx'))
+        return ts.ScriptKind.TSX;
+    if (file.endsWith('.jsx'))
+        return ts.ScriptKind.JSX;
+    if (/\.[cm]?js$/.test(file))
+        return ts.ScriptKind.JS;
+    return ts.ScriptKind.TS;
+}
+export class Source {
+    file;
+    text;
+    edits = new Map();
+    lines;
+    protectedLines = new Set();
+    /** Every identifier that appears anywhere in the file, so new names can avoid them. */
+    taken = new Set();
+    path;
+    constructor(path, text) {
+        this.path = path;
+        this.text = text;
+        this.file = ts.createSourceFile(path, text, ts.ScriptTarget.ES2022, true, scriptKindOf(path));
+        this.lines = text.split('\n');
+        const visit = (node) => {
+            if (ts.isIdentifier(node))
+                this.taken.add(node.text);
+            if (ts.isNoSubstitutionTemplateLiteral(node) || ts.isTemplateExpression(node)) {
+                const from = this.lineOf(node.getStart(this.file)) - 1;
+                const to = this.lineOf(node.end) - 1;
+                for (let i = from + 1; i <= to; i += 1)
+                    this.protectedLines.add(i);
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(this.file);
+    }
+    /** 1-based line of a position. */
+    lineOf(pos) {
+        return this.file.getLineAndCharacterOfPosition(pos).line + 1;
+    }
+    lineOfNode(node) {
+        return this.lineOf(node.getStart(this.file));
+    }
+    /** Replaces `start..end` with a single line of text; the same edit made twice counts once. */
+    edit(start, end, text) {
+        if (text.includes('\n'))
+            throw new Error('an edit may not add or remove lines');
+        this.edits.set(`${start}:${end}`, { start, end, text });
+    }
+    /** The original text of `start..end` with the edits inside it applied. */
+    render(start, end) {
+        const inside = [...this.edits.values()]
+            .filter((e) => e.start >= start && e.end <= end)
+            .sort((a, b) => a.start - b.start);
+        let out = '';
+        let at = start;
+        for (const e of inside) {
+            if (e.start < at)
+                continue;
+            out += this.text.slice(at, e.start) + e.text;
+            at = e.end;
+        }
+        return out + this.text.slice(at, end);
+    }
+    /** The text of a node, edits applied, on its own (no reindentation). */
+    textOf(node) {
+        return this.render(node.getStart(this.file), node.end);
+    }
+    /** A statement's range including the comments written above it and a comment after it on the same line. */
+    rangeOf(node) {
+        const leading = ts.getLeadingCommentRanges(this.text, node.pos) ?? [];
+        const trailing = ts.getTrailingCommentRanges(this.text, node.end) ?? [];
+        const start = leading[0]?.pos ?? node.getStart(this.file);
+        const end = trailing.length > 0 ? trailing[trailing.length - 1].end : node.end;
+        return [start, end];
+    }
+    /** The statements' text at `depth` levels of two spaces, comments included, template strings untouched. */
+    statements(nodes, depth) {
+        return nodes.flatMap((n) => this.block(...this.rangeOf(n), depth));
+    }
+    /** Copies `start..end` as lines at `depth`, keeping the shape the code had. */
+    block(start, end, depth) {
+        const raw = this.render(start, end).split('\n');
+        const startLine = this.lineOf(start) - 1;
+        let first = 0;
+        while (first < raw.length && raw[first].trim() === '')
+            first += 1;
+        let last = raw.length;
+        while (last > first && raw[last - 1].trim() === '')
+            last -= 1;
+        if (first >= last)
+            return [];
+        const base = /^[ \t]*/.exec(this.lines[startLine + first] ?? '')[0].length;
+        const pad = '  '.repeat(depth);
+        const out = [];
+        for (let i = first; i < last; i += 1) {
+            const line = raw[i];
+            if (this.protectedLines.has(startLine + i))
+                out.push(line);
+            else if (line.trim() === '')
+                out.push('');
+            else {
+                const lead = /^[ \t]*/.exec(line)[0].length;
+                out.push(pad + line.slice(Math.min(base, lead)));
+            }
+        }
+        return out;
+    }
+}
+/** Names a statement declares at its top level (variables, destructured ones, functions, classes). */
+export function declaredNames(statement) {
+    const names = [];
+    const fromBinding = (name) => {
+        if (ts.isIdentifier(name))
+            names.push(name.text);
+        else
+            for (const element of name.elements)
+                if (ts.isBindingElement(element))
+                    fromBinding(element.name);
+    };
+    if (ts.isVariableStatement(statement))
+        for (const d of statement.declarationList.declarations)
+            fromBinding(d.name);
+    else if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name !== undefined)
+        names.push(statement.name.text);
+    return names;
+}
+/** Every identifier written inside `node`. */
+export function identifiersIn(node, into) {
+    if (ts.isIdentifier(node))
+        into.add(node.text);
+    ts.forEachChild(node, (child) => identifiersIn(child, into));
+}
+/** A string as a single-quoted TypeScript literal. */
+export function quote(value) {
+    const escapes = {
+        '\\': '\\\\',
+        "'": "\\'",
+        '\n': '\\n',
+        '\r': '\\r',
+        '\u2028': '\\u2028',
+        '\u2029': '\\u2029',
+    };
+    let out = "'";
+    for (const ch of value)
+        out += escapes[ch] ?? ch;
+    return `${out}'`;
+}
+/** A string literal's value when `node` is a plain string or a template with no substitutions. */
+export function literalText(node) {
+    if (node !== undefined && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)))
+        return node.text;
+    return undefined;
+}
+export function unwrap(node) {
+    let current = node;
+    while (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isNonNullExpression(current))
+        current = current.expression;
+    return current;
+}

package/dist/migrate/tests.d.ts

@@ -0,0 +1,44 @@
+import ts from 'typescript';
+import type { Source } from './source.ts';
+export type FnLike = ts.ArrowFunction | ts.FunctionExpression;
+export declare const isFn: (node: ts.Node | undefined) => node is FnLike;
+export declare function isAsyncFn(fn: FnLike): boolean;
+/** The title of a test or suite: a string, a template, or a plain name such as a class. Undefined when it is computed. */
+export declare function titleOf(node: ts.Expression | undefined, src: Source): string | undefined;
+/** True when the function itself (not a function inside it) returns a value. */
+export declare function returnsValue(fn: FnLike): boolean;
+/** True when `node` contains `await`, or `.resolves` / `.rejects`, outside nested functions. */
+export declare function awaits(node: ts.Node): boolean;
+/** The names a function declares at its top level, for telling when inlining two of them in one block would clash. */
+export declare function blockStatements(fn: FnLike): readonly ts.Statement[];
+export interface Fixtures {
+    /** Local name to the fixture it stands for. */
+    bindings: Map<string, string>;
+    problem?: string;
+}
+/** The fixtures a Playwright callback asks for: `async ({ page, context }) => ...`. */
+export declare function fixturesOf(fn: FnLike): Fixtures;
+export interface Row {
+    /** The arguments the callback receives. */
+    args: ts.Expression[];
+    /** For a table written as a template: the one object the callback receives, as text, and its cells by column. */
+    synthetic?: string;
+    cells?: Map<string, ts.Expression>;
+    /** For rows of objects: the object, whose properties `$name` in a title refers to. */
+    object?: ts.Expression;
+    /** Source text of the arguments for the title. */
+    texts: string[];
+}
+export type Rows = {
+    ok: true;
+    rows: Row[];
+    template: boolean;
+    header: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+/** The rows of ``test.each([...])`` or ``test.each`a | b ...` ``. */
+export declare function rowsOf(each: ts.CallExpression | ts.TaggedTemplateExpression, src: Source, spread: boolean): Rows;
+/** The title of one row of a table, with `%s`-style and `$name` placeholders filled from the row as the framework does. */
+export declare function rowTitle(title: string, row: Row, index: number, src: Source): string;

package/dist/migrate/tests.js

@@ -0,0 +1,184 @@
+// The pieces of a test file that need reading before they become laws: test titles, the callbacks of tests and hooks,
+// the rows of `test.each` tables and the titles they print, and the fixtures of a Playwright test.
+import ts from 'typescript';
+import { chainOf } from "./framework.js";
+import { literalText, unwrap } from "./source.js";
+export const isFn = (node) => node !== undefined && (ts.isArrowFunction(node) || ts.isFunctionExpression(node));
+export function isAsyncFn(fn) {
+    return fn.modifiers?.some((m) => m.kind === ts.SyntaxKind.AsyncKeyword) === true;
+}
+/** The title of a test or suite: a string, a template, or a plain name such as a class. Undefined when it is computed. */
+export function titleOf(node, src) {
+    if (node === undefined)
+        return undefined;
+    const literal = literalText(node);
+    if (literal !== undefined)
+        return literal;
+    if (ts.isTemplateExpression(node))
+        return node.getText(src.file).slice(1, -1);
+    if (chainOf(node) !== undefined)
+        return node.getText(src.file);
+    return undefined;
+}
+/** True when the function itself (not a function inside it) returns a value. */
+export function returnsValue(fn) {
+    let found = false;
+    const visit = (node) => {
+        if (found || (node !== fn.body && ts.isFunctionLike(node)))
+            return;
+        if (ts.isReturnStatement(node) && node.expression !== undefined)
+            found = true;
+        ts.forEachChild(node, visit);
+    };
+    if (ts.isBlock(fn.body))
+        visit(fn.body);
+    return found;
+}
+/** True when `node` contains `await`, or `.resolves` / `.rejects`, outside nested functions. */
+export function awaits(node) {
+    let found = false;
+    const visit = (n) => {
+        if (found || (n !== node && ts.isFunctionLike(n)))
+            return;
+        if (ts.isAwaitExpression(n))
+            found = true;
+        if (ts.isPropertyAccessExpression(n) && (n.name.text === 'resolves' || n.name.text === 'rejects'))
+            found = true;
+        ts.forEachChild(n, visit);
+    };
+    visit(node);
+    return found;
+}
+/** The names a function declares at its top level, for telling when inlining two of them in one block would clash. */
+export function blockStatements(fn) {
+    return ts.isBlock(fn.body) ? fn.body.statements : [];
+}
+/** The fixtures a Playwright callback asks for: `async ({ page, context }) => ...`. */
+export function fixturesOf(fn) {
+    const bindings = new Map();
+    if (fn.parameters.length === 0)
+        return { bindings };
+    if (fn.parameters.length > 1)
+        return { bindings, problem: 'it takes testInfo, which a law has no equivalent of' };
+    const parameter = fn.parameters[0];
+    if (!ts.isObjectBindingPattern(parameter.name))
+        return { bindings, problem: 'its fixtures are not destructured, so they cannot be mapped' };
+    for (const element of parameter.name.elements) {
+        if (element.dotDotDotToken !== undefined || element.initializer !== undefined || !ts.isIdentifier(element.name))
+            return { bindings, problem: 'a fixture is renamed with a default, a rest or a pattern' };
+        const fixture = element.propertyName === undefined
+            ? element.name.text
+            : ts.isIdentifier(element.propertyName)
+                ? element.propertyName.text
+                : undefined;
+        if (fixture === undefined)
+            return { bindings, problem: 'a fixture has a computed name' };
+        if (fixture !== 'page' && fixture !== 'context' && fixture !== 'baseURL')
+            return {
+                bindings,
+                problem: `the fixture ${fixture} has no counterpart in a law (only page, context and baseURL do)`,
+            };
+        bindings.set(element.name.text, fixture);
+    }
+    return { bindings };
+}
+/** The rows of ``test.each([...])`` or ``test.each`a | b ...` ``. */
+export function rowsOf(each, src, spread) {
+    if (ts.isTaggedTemplateExpression(each)) {
+        const template = each.template;
+        if (ts.isNoSubstitutionTemplateLiteral(template))
+            return { ok: true, rows: [], template: true, header: [] };
+        const header = template.head.text
+            .trim()
+            .split('|')
+            .map((h) => h.trim())
+            .filter((h) => h !== '');
+        const cells = template.templateSpans.map((s) => s.expression);
+        if (header.length === 0 || cells.length % header.length !== 0)
+            return { ok: false, reason: 'the table has cells that do not line up with its header' };
+        const rows = [];
+        for (let i = 0; i < cells.length; i += header.length) {
+            const row = cells.slice(i, i + header.length);
+            const key = (h) => (/^[A-Za-z_$][\w$]*$/.test(h) ? h : JSON.stringify(h));
+            const text = `{ ${header.map((h, j) => `${key(h)}: ${src.textOf(row[j])}`).join(', ')} }`;
+            const byColumn = new Map(header.map((h, j) => [h, row[j]]));
+            rows.push({ args: [], synthetic: text, cells: byColumn, texts: [text] });
+        }
+        return { ok: true, rows, template: true, header };
+    }
+    const table = each.arguments[0];
+    if (table === undefined || !ts.isArrayLiteralExpression(unwrap(table)))
+        return { ok: false, reason: 'the table is not an array written in the file, so its rows cannot be listed' };
+    const elements = unwrap(table).elements;
+    if (elements.some((e) => ts.isSpreadElement(e)))
+        return { ok: false, reason: 'the table spreads another array' };
+    const allArrays = spread && elements.length > 0 && elements.every((e) => ts.isArrayLiteralExpression(unwrap(e)));
+    const rows = [];
+    for (const element of elements) {
+        if (allArrays) {
+            const cells = unwrap(element).elements;
+            if (cells.some((c) => ts.isSpreadElement(c)))
+                return { ok: false, reason: 'a row spreads another array' };
+            rows.push({ args: cells.slice(), texts: cells.map((c) => oneLine(src.textOf(c))) });
+        }
+        else {
+            const e = unwrap(element);
+            rows.push({
+                args: [element],
+                object: ts.isObjectLiteralExpression(e) ? e : undefined,
+                texts: [oneLine(src.textOf(element))],
+            });
+        }
+    }
+    return { ok: true, rows, template: false, header: [] };
+}
+const oneLine = (text) => text.replace(/\s+/g, ' ').trim();
+/** What a value prints as in a title: strings without quotes, other values as written. */
+function shown(node, src) {
+    const e = unwrap(node);
+    const literal = literalText(e);
+    if (literal !== undefined)
+        return literal;
+    return oneLine(src.textOf(e));
+}
+/** The title of one row of a table, with `%s`-style and `$name` placeholders filled from the row as the framework does. */
+export function rowTitle(title, row, index, src) {
+    let argument = 0;
+    const filled = title.replace(/%([sdifjopP#$%])/g, (whole, spec) => {
+        if (spec === '%')
+            return '%';
+        if (spec === '#')
+            return String(index);
+        if (spec === '$')
+            return String(index + 1);
+        const node = row.args[argument];
+        const text = row.texts[argument];
+        argument += 1;
+        if (text === undefined)
+            return whole;
+        if (spec === 's' && node !== undefined)
+            return shown(node, src);
+        return text;
+    });
+    return filled.replace(/\$(#|[A-Za-z_][\w]*(?:\.[A-Za-z_][\w]*)*)/g, (whole, path) => {
+        if (path === '#')
+            return String(index);
+        const [head, ...rest] = path.split('.');
+        const cell = row.cells?.get(head);
+        if (cell !== undefined && rest.length === 0)
+            return shown(cell, src);
+        const object = row.object;
+        if (object !== undefined && ts.isObjectLiteralExpression(object)) {
+            for (const p of object.properties) {
+                if (ts.isPropertyAssignment(p) &&
+                    (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+                    p.name.text === head &&
+                    rest.length === 0)
+                    return shown(p.initializer, src);
+                if (ts.isShorthandPropertyAssignment(p) && p.name.text === head && rest.length === 0)
+                    return head;
+            }
+        }
+        return whole;
+    });
+}

package/dist/plan.d.ts

@@ -0,0 +1,50 @@
+import * as fc from 'fast-check';
+export declare class UnsupportedType extends Error {
+}
+export type Plan = {
+    k: 'anything';
+} | {
+    k: 'const';
+    v: undefined | null | boolean | number | string;
+} | {
+    k: 'bigconst';
+    v: string;
+} | {
+    k: 'boolean' | 'number' | 'string' | 'bigint' | 'symbol' | 'object' | 'date' | 'regexp';
+} | {
+    k: 'union';
+    of: Plan[];
+} | {
+    k: 'template';
+    texts: string[];
+    parts: Plan[];
+}
+/** A type with a registered generator; `fallback` is what to generate when none is registered by the time of use. */
+ | {
+    k: 'named';
+    name: string;
+    fallback?: Plan;
+} | {
+    k: 'array';
+    of: Plan;
+} | {
+    k: 'tuple';
+    required: Plan[];
+    optional: Plan[];
+} | {
+    k: 'fn';
+    returns: Plan;
+} | {
+    k: 'record';
+    fields: Record<string, Plan>;
+    required: string[];
+} | {
+    k: 'dict';
+    of: Plan;
+};
+/** 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;
+/** The fast-check arbitrary a plan describes. */
+export declare function arbitraryOf(plan: Plan): fc.Arbitrary<unknown>;

package/dist/plan.js

@@ -0,0 +1,118 @@
+// A generator plan: what to generate for one parameter type, as plain data. The type checker reads a parameter's type
+// once, in the main process, and writes the plan; a worker turns the plan into fast-check arbitraries without loading
+// TypeScript (about 0.8 s of start-up per worker).
+import { sequence } from "./sequence.js";
+import * as fc from 'fast-check';
+import { arbitraryRegistry } from "./api.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;
+}
+/** The fast-check arbitrary a plan describes. */
+export function arbitraryOf(plan) {
+    switch (plan.k) {
+        case 'anything':
+            return fc.anything();
+        case 'const':
+            return fc.constant(plan.v);
+        case 'bigconst':
+            return fc.constant(BigInt(plan.v));
+        case 'boolean':
+            return fc.boolean();
+        case 'number':
+            return numbers;
+        case 'string':
+            return fc.string({ maxLength: 24 });
+        case 'bigint':
+            return fc.bigInt();
+        case 'symbol':
+            return fc.string().map((s) => Symbol(s));
+        case 'object':
+            return fc.object();
+        case 'date':
+            return fc.date({ noInvalidDate: true });
+        case 'regexp':
+            return fc.constant(/x/);
+        case 'union':
+            return fc.oneof(...plan.of.map(arbitraryOf));
+        case 'template': {
+            const parts = [fc.constant(plan.texts[0] ?? '')];
+            plan.parts.forEach((part, i) => {
+                parts.push(arbitraryOf(part).map(String));
+                parts.push(fc.constant(plan.texts[i + 1] ?? ''));
+            });
+            return fc.tuple(...parts).map((p) => p.join(''));
+        }
+        case 'named': {
+            const registered = arbitraryRegistry().get(plan.name);
+            if (registered !== undefined)
+                return registered;
+            if (plan.fallback === undefined)
+                throw new UnsupportedType(`no generator registered for ${plan.name}`);
+            return arbitraryOf(plan.fallback);
+        }
+        case 'array':
+            return sequence(arbitraryOf(plan.of), { maxLength: 8 });
+        case 'tuple': {
+            const required = plan.required.map(arbitraryOf);
+            const optional = plan.optional.map(arbitraryOf);
+            return fc.tuple(...required).chain((head) => {
+                if (optional.length === 0)
+                    return fc.constant(head);
+                return fc.tuple(...optional).map((tail) => [...head, ...tail]);
+            });
+        }
+        case 'fn':
+            return fc.array(arbitraryOf(plan.returns), { minLength: 1, maxLength: 4 }).map(generatedFunction);
+        case 'record': {
+            const model = {};
+            for (const [key, field] of Object.entries(plan.fields))
+                model[key] = arbitraryOf(field);
+            return fc.record(model, { requiredKeys: plan.required });
+        }
+        case 'dict':
+            return fc.dictionary(fc.string({ maxLength: 6 }), arbitraryOf(plan.of), { maxKeys: 6 });
+    }
+}

package/dist/pool.d.ts

@@ -0,0 +1,21 @@
+import type { Worker } from 'node:worker_threads';
+/** How many laws run at once: the machine's cores, up to 8, or TSLAWS_JOBS. */
+export declare function jobs(): number;
+/**
+ * A pool of workers where each request holds one exclusively, so a timeout can terminate its worker without
+ * disturbing a neighbour. Workers start on demand and are reused.
+ */
+export declare class WorkerPool {
+    private readonly idle;
+    private readonly waiting;
+    private count;
+    private readonly start;
+    private readonly size;
+    constructor(start: () => Worker, size?: number);
+    acquire(): Promise<Worker>;
+    /** Starts up to `n` workers now, so they finish loading while the caller does other work. */
+    warm(n: number): void;
+    release(worker: Worker): void;
+    /** Terminates a worker that timed out or crashed; a waiting request gets a fresh one. */
+    discard(worker: Worker): void;
+}

package/dist/pool.js

@@ -0,0 +1,54 @@
+import { availableParallelism } from 'node:os';
+/** How many laws run at once: the machine's cores, up to 8, or TSLAWS_JOBS. */
+export function jobs() {
+    const given = Number(process.env.TSLAWS_JOBS);
+    return Number.isInteger(given) && given > 0 ? given : Math.min(8, availableParallelism());
+}
+/**
+ * A pool of workers where each request holds one exclusively, so a timeout can terminate its worker without
+ * disturbing a neighbour. Workers start on demand and are reused.
+ */
+export class WorkerPool {
+    idle = [];
+    waiting = [];
+    count = 0;
+    start;
+    size;
+    constructor(start, size = jobs()) {
+        this.start = start;
+        this.size = size;
+    }
+    acquire() {
+        const free = this.idle.pop();
+        if (free !== undefined)
+            return Promise.resolve(free);
+        if (this.count < this.size) {
+            this.count += 1;
+            return Promise.resolve(this.start());
+        }
+        return new Promise((resolve) => this.waiting.push(resolve));
+    }
+    /** Starts up to `n` workers now, so they finish loading while the caller does other work. */
+    warm(n) {
+        while (this.count < Math.min(n, this.size)) {
+            this.count += 1;
+            this.idle.push(this.start());
+        }
+    }
+    release(worker) {
+        const next = this.waiting.shift();
+        if (next !== undefined)
+            next(worker);
+        else
+            this.idle.push(worker);
+    }
+    /** Terminates a worker that timed out or crashed; a waiting request gets a fresh one. */
+    discard(worker) {
+        void worker.terminate();
+        const next = this.waiting.shift();
+        if (next === undefined)
+            this.count -= 1;
+        else
+            next(this.start());
+    }
+}

package/dist/promote.d.ts

@@ -10,10 +10,13 @@ export interface ParsedLawFile {
     imports: string[];
     laws: ParsedLaw[];
 }
-/** `foo.proposed.laws.ts` -> `foo.laws.ts`; undefined for any other name. */
+/**
+ * `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 declare function acceptedPathFor(proposed: string): string | 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.
  */
@@ -36,3 +39,28 @@ export interface PromoteHost {
 }
 /** Walks the proposed files, asks per law, and rewrites the accepted and proposed files. Returns the number promoted. */
 export declare function promoteFiles(host: PromoteHost, proposedFiles: string[]): Promise<number>;
+/** The path `promote` suggests for a proposal: beside the source it imports, else under `laws/`. */
+export declare function defaultTarget(cwd: string, proposal: string): string;
+/**
+ * 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 declare function promotionTarget(cwd: string, to: string): string;
+export interface PromoteProposalHost {
+    cwd: string;
+    /** Checks one proposal and returns its results by law name (as `check --proposed` would). */
+    checkFile: (file: string) => Promise<Map<string, string>>;
+    ask: (question: string) => Promise<string>;
+    out: (text: string) => void;
+}
+export interface PromoteProposalResult {
+    /** Project-relative path the laws went to; undefined when the person declined or nothing was moved. */
+    target?: string;
+}
+/**
+ * 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 declare function promoteProposal(host: PromoteProposalHost, file: string, to?: string): Promise<PromoteProposalResult>;