@prestack/thread 0.0.1

package/dist/integrity/generators/rule.js

@@ -0,0 +1,213 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { argv, stdout } from 'node:process';
+import { exit } from "../../core/invoked.js";
+import { ELSEWHERE, RECEIPT, answer, answering, asking, asksOf, bodied, given as pipedIn, guidance, issue, marked, named as answerNames, needed, only, ownAnswers, refuse, rowLines, seeding, spend, stating, within, wordsIn } from "../../core/asking.js";
+import { holdsRow, listBounds, withRow } from "../../core/rows.js";
+import { named } from "../../core/scope.js";
+import { findTree, inTree } from "../../core/tree.js";
+import { ROOT, SEEDED, declareSeeded, rules, scaffold, slopnatorName, write } from "../slopnator.js";
+const TREE = findTree();
+const FILE = 'rules.ts';
+const LIST = 'RULES';
+const at = within(TREE.at, inTree(TREE, FILE));
+const kebab = (one) => one.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+export const ASKS = asksOf('rule', 'Constraint', {
+    name: { guide: 'kebab-case, e.g. no-fetch-in-a-screen', asks: 'name: ' },
+    describes: {
+        guide: 'one sentence a reader who has not seen the code could act on',
+        asks: 'describes — one sentence a reader who has not seen the code could act on: ',
+    },
+    where: {
+        guide: 'comma separated path fragments this governs, e.g. app/, src/nodes/',
+        asks: 'where (comma separated path fragments this governs, e.g. app/, src/nodes/): ',
+    },
+    except: {
+        guide: 'optional — comma separated path fragments to leave out',
+        asks: 'except (comma separated, blank for none): ',
+    },
+    bans: { guide: 'the exact form this refuses, in one line', asks: 'bans — the exact form this refuses, in one line: ' },
+    because: { guide: 'a fact somebody measured — why this is refused', asks: 'because — a fact somebody measured: ' },
+    instead: { guide: 'what to do instead', asks: 'instead — what to do instead: ' },
+    wrong: {
+        guide: 'one line of the form this refuses — its trial',
+        asks: 'wrong — one line of the form this refuses, its trial: ',
+    },
+    right: {
+        guide: 'one line of the form this allows — its trial',
+        asks: 'right — one line of the form this allows, its trial: ',
+    },
+    severity: {
+        guide: 'optional — forbidden (default, leave blank) or warning',
+        asks: 'severity — forbidden or warning (blank for forbidden): ',
+    },
+    finds: {
+        guide: 'one sentence saying what the check looks for, read by whoever opens it next',
+        asks: 'finds — one sentence saying what the check looks for: ',
+    },
+    body: {
+        guide: 'the check itself, written where it is asked for. Leave it blank and the rule is declared with nothing behind it, which `npx thread trials` reports unproven',
+        asks: 'body: ',
+        optional: true,
+    },
+}, ['id', 'at', 'version']);
+const said = (one) => ASKS.find((each) => each.at === one)?.asks ?? `${one}: `;
+import { quoted } from "../../core/rows.js";
+const held = await rules();
+if (held === undefined) {
+    refuse(`there is no ${at} declaring \`${LIST}\` here, so a rule has nowhere to go. ` +
+        `Run \`npx thread attach ${named('integrity')}\` — the sheet is the package's to write, not yours.`);
+}
+const existing = held;
+const mark = (one) => marked([one.id, one.describes, one.bans, one.because, one.instead, one.wrong, one.right, JSON.stringify(one.where), one.severity ?? '']);
+const listing = [
+    existing.length === 0
+        ? 'no rules of its own yet — this app enforces only what the packages it attached ship.'
+        : `${String(existing.length)} rule(s) this app adds of its own:`,
+    ...existing.map((one) => `  [${mark(one)}] ${one.id} — ${one.bans}${one.severity === 'warning' ? ' (warning)' : ''}`),
+].join('\n');
+const words = wordsIn(['new']);
+stdout.write(`${listing}\n`);
+const flagged = argv.indexOf(RECEIPT);
+if (flagged === -1) {
+    const nonce = issue(TREE.at, listing);
+    stdout.write([
+        '',
+        ...answering('rule'),
+        '',
+        ...guidance(ASKS),
+        '',
+        `  npx thread create rule new <name> ${RECEIPT} ${nonce}`,
+        '',
+        ...ELSEWHERE,
+        '',
+        `${RECEIPT} is spent by one run, and is refused if ${at} changed after it was issued.`,
+        '',
+        'this writes three things, not one. The row goes in the sheet, the check goes in the file it ' +
+            'seeds from the `body` you give, and the trial comes from `wrong` and `right`.',
+        '',
+        'then it runs every generator this tree declares, that trial among them, so before this command ' +
+            'returns you see whether the rule fires at the form it refuses and stays silent at the fix it ' +
+            'names. Leave `body` blank and the row is declared with nothing behind it, and `npx thread ' +
+            'trials` reports it unproven until somebody writes the check.',
+        '',
+    ].join('\n'));
+    stdout.write(`create: receipt ${nonce} — spent on use, and stale the moment ${at} changes.\n`);
+    exit(0);
+}
+spend(TREE.at, listing, argv[flagged + 1], at);
+const all = pipedIn();
+const { piped, ask, line, shut } = asking(all);
+const own = ownAnswers(all);
+if (piped)
+    only(own, answerNames(ASKS), '`new`');
+const name = kebab(words[1] ?? (piped ? needed(own, 'name', '`new`') : await ask('name', said('name'))));
+if (!KEBAB.test(name)) {
+    shut();
+    refuse(`\`${name}\` cannot be the id of a rule — it is kebab-case, e.g. no-fetch-in-a-screen.`);
+}
+if (existing.some((one) => one.id === name)) {
+    shut();
+    refuse(`\`${name}\` is already declared in ${at}. One id, one rule — two would silently keep whichever ran second.`);
+}
+const describes = piped
+    ? needed(own, 'describes', '`new`')
+    : await ask('describes', said('describes'));
+if (describes === '') {
+    shut();
+    refuse(`\`${name}\` was given no meaning, and a row without one is a name nobody can read.`);
+}
+const whereSaid = piped ? needed(own, 'where', '`new`') : await ask('where', said('where'));
+const paths = whereSaid.split(',').map((one) => one.trim()).filter((one) => one !== '');
+if (paths.length === 0) {
+    shut();
+    refuse(`\`${name}\` names no path, so it would govern nothing — a rule that cannot fire is indistinguishable from a rule being obeyed.`);
+}
+const exceptSaid = piped ? (answer(own, 'except') ?? '') : await ask('except', said('except'));
+const except = exceptSaid.split(',').map((one) => one.trim()).filter((one) => one !== '');
+const bans = piped ? needed(own, 'bans', '`new`') : await ask('bans', said('bans'));
+if (bans === '') {
+    shut();
+    refuse(`\`${name}\` names no \`bans\`, and a rule that does not say what form it refuses cannot be told from one refusing nothing.`);
+}
+const because = piped ? needed(own, 'because', '`new`') : await ask('because', said('because'));
+if (because === '') {
+    shut();
+    refuse(`\`${name}\` names no \`because\`, and a refusal with no reason is an order rather than a rule.`);
+}
+const instead = piped ? needed(own, 'instead', '`new`') : await ask('instead', said('instead'));
+if (instead === '') {
+    shut();
+    refuse(`\`${name}\` names no \`instead\`, so whoever it refuses is told only what they did wrong.`);
+}
+const wrong = piped ? needed(own, 'wrong', '`new`') : await ask('wrong', said('wrong'));
+if (wrong === '') {
+    shut();
+    refuse(`\`${name}\` names no \`wrong\`, and a rule with nothing it refuses is a predicate with no trial to prove it fires.`);
+}
+const right = piped ? needed(own, 'right', '`new`') : await ask('right', said('right'));
+if (right === '') {
+    shut();
+    refuse(`\`${name}\` names no \`right\`, and a rule that only shows what it refuses cannot prove it stays silent on the fix it recommends.`);
+}
+const severity = piped ? (answer(own, 'severity') ?? '') : await ask('severity', said('severity'));
+if (severity !== '' && severity !== 'forbidden' && severity !== 'warning') {
+    shut();
+    refuse(`\`${severity}\` is not a severity — a rule is \`forbidden\` (the default, leave blank to use it) or \`warning\`.`);
+}
+const finds = piped ? needed(own, 'finds', '`new`') : await ask('finds', said('finds'));
+if (finds === '') {
+    shut();
+    refuse(`\`${name}\` says nothing about what its check looks for, and that sentence is the only thing between the ` +
+        'next person and opening the file. Say what THIS one looks for, not what a check is.');
+}
+const body = await bodied(`the check for \`${name}\``, scaffold(), piped, all, line);
+const { stated, kids } = await stating(ASKS, all, piped, ask, line, ['name', 'id', 'at', 'describes', 'version', 'where', 'except', 'bans', 'because', 'instead', 'wrong', 'right', 'severity', 'finds', 'body']);
+shut();
+const row = [
+    '  {',
+    `    id: ${quoted(name)},`,
+    `    at: ${quoted(at)},`,
+    `    describes: ${quoted(describes)},`,
+    '    version: 1,',
+    `    where: { paths: [${paths.map(quoted).join(', ')}]${except.length === 0 ? '' : `, except: [${except.map(quoted).join(', ')}]`} },`,
+    `    bans: ${quoted(bans)},`,
+    `    because: ${quoted(because)},`,
+    `    instead: ${quoted(instead)},`,
+    `    wrong: ${quoted(wrong)},`,
+    `    right: ${quoted(right)},`,
+    ...(severity === '' || severity === 'forbidden' ? [] : [`    severity: ${quoted(severity)},`]),
+    ...rowLines('    ', stated, kids),
+    '  },',
+].join('\n');
+const path = inTree(TREE, FILE);
+const text = readFileSync(path, 'utf8');
+const where = listBounds(text, LIST);
+if (where === undefined)
+    refuse(`${at} states no \`${LIST}\` list to declare a rule in.`);
+if (holdsRow(text, where, name))
+    refuse(`\`${name}\` is already declared in ${at}.`);
+writeFileSync(path, withRow(text, where, row), 'utf8');
+stdout.write(`create: declared ${name} in ${at}.\n`);
+const slopAt = `${SEEDED}/${slopnatorName(name)}.ts`;
+if (existsSync(join(ROOT, slopAt))) {
+    stdout.write(`create: ${slopAt} is already on disk — left untouched, and declared below.\n`);
+}
+else {
+    write(ROOT, { path: slopAt, content: body ?? scaffold() });
+    stdout.write(body === undefined
+        ? `create: seeded ${slopAt} with nothing behind it — its \`holds\` answers NOT_WRITTEN.\n`
+        : `create: seeded ${slopAt} with the check you wrote.\n`);
+}
+for (const told of seeding(kids, ROOT))
+    stdout.write(`create: ${told}\n`);
+const declared = await declareSeeded(ROOT, [name], finds);
+if (declared.length > 0)
+    stdout.write(`create: declared the check for "${name}" in its own row.\n`);
+stdout.write(body === undefined
+    ? `create: ${name} refuses nothing yet — write ${slopAt}, matching the shape any file already under ` +
+        'slopnators/ uses. `npx thread trials` reports it unproven until you do.\n'
+    : `create: ${name} is declared and its check is written. The trial derived from \`wrong\` and \`right\` ` +
+        'runs below — it proves the rule fires at the form it refuses and stays silent at the fix it names.\n');
+exit(0);

package/dist/integrity/generators/seal.d.ts

@@ -0,0 +1,4 @@
+export declare const SEALED_AT = "sealed.ts";
+export declare function sealable(home?: string): readonly string[];
+export declare function sealOf(home?: string): Readonly<Record<string, string>>;
+export declare function content(seal: Readonly<Record<string, string>>): string;

package/dist/integrity/generators/seal.js

@@ -0,0 +1,101 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { argv, stderr, stdout } from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { runChecker } from "../../core/finding.js";
+import { exit, invoked } from "../../core/invoked.js";
+import { findTree, inTree } from "../../core/tree.js";
+import { SEALED } from "../sealed.js";
+export const SEALED_AT = 'sealed.ts';
+const HERE = fileURLToPath(import.meta.url);
+const FROM_SOURCE = HERE.endsWith('.ts');
+const ROOT = FROM_SOURCE ? findTree().at : resolve(HERE, '../..');
+const DOMAIN = basename(resolve(HERE, '../..'));
+const WRITTEN = join(dirname(HERE), '..', SEALED_AT);
+const BUILT = SEALED_AT.replace(/\.ts$/, '.js');
+const CODE = /\.js$/;
+const SHEET = 'packaging.ts';
+async function declared() {
+    const sheet = inTree(findTree(), SHEET);
+    if (!existsSync(sheet))
+        return [];
+    const loaded = (await import(__rewriteRelativeImportExtension(pathToFileURL(sheet).href)));
+    return loaded.PACKAGES ?? [];
+}
+const PACKAGES = FROM_SOURCE ? await declared() : [];
+function built() {
+    if (!FROM_SOURCE)
+        return ROOT;
+    const folders = PACKAGES.map((one) => one.folder ?? '').filter((one) => one !== '');
+    const holder = folders.find((folder) => existsSync(join(ROOT, folder, 'dist', DOMAIN)));
+    if (holder === undefined) {
+        stderr.write(`seal: no package built here holds \`${DOMAIN}\` — ${folders.length === 0 ? '_threads/packaging.ts declares no package' : `none of ${folders.join(', ')} has a dist/${DOMAIN}`}. ` +
+            `Run \`thread packaged --build\` first, and if no package row carries the ${DOMAIN} words, put them on one in _threads/packaging.ts.\n`);
+        exit(1);
+    }
+    return join(ROOT, holder, 'dist', DOMAIN);
+}
+export function sealable(home = built()) {
+    const found = [];
+    const step = (at) => {
+        for (const entry of readdirSync(at).sort()) {
+            const here = join(at, entry);
+            if (statSync(here).isDirectory())
+                step(here);
+            else if (CODE.test(entry) && relative(home, here) !== BUILT)
+                found.push(here);
+        }
+    };
+    step(home);
+    return found.sort();
+}
+export function sealOf(home = built()) {
+    const held = {};
+    for (const file of sealable(home)) {
+        held[relative(home, file)] = createHash('sha256').update(readFileSync(file)).digest('hex');
+    }
+    return held;
+}
+export function content(seal) {
+    const rows = Object.entries(seal).map(([at, hash]) => `  '${at}': '${hash}',`);
+    return [
+        'export const SEALED: Readonly<Record<string, string>> = {',
+        ...rows,
+        '}',
+        '',
+    ].join('\n');
+}
+if (invoked(import.meta.url)) {
+    const seal = sealOf();
+    const emitted = content(seal);
+    if (argv.includes('--check')) {
+        const sealed = Object.keys(seal).length;
+        const findings = content(SEALED) === emitted
+            ? []
+            : [
+                {
+                    detail: `${SEALED_AT} is not the bytes this package is made of`,
+                    instead: 'run `thread seal` and commit what it writes — the seal is what proves an installed copy is the one that shipped',
+                    file: relative(ROOT, WRITTEN),
+                },
+            ];
+        runChecker('seal', findings, `${String(sealed)} file(s) sealed`);
+        exit(findings.length === 0 ? 0 : 1);
+    }
+    if (!FROM_SOURCE) {
+        stderr.write('seal: this copy is installed, and a seal is written where the package is made. Nothing was rewritten — `thread seal --check` says whether this copy is the one that shipped.\n');
+        exit(1);
+    }
+    mkdirSync(dirname(WRITTEN), { recursive: true });
+    writeFileSync(WRITTEN, emitted);
+    stdout.write(`seal: wrote ${SEALED_AT} — ${String(Object.keys(seal).length)} file(s).\n`);
+}

package/dist/integrity/generators/trial.d.ts

@@ -0,0 +1,39 @@
+import type { Rule } from 'eslint';
+import type { Constraint } from '../constraint.ts';
+import { type Byproduct, type Slopnator, type Sourced } from '../slopnator.ts';
+export declare const TRIALS_PATH: string;
+export interface Scenario {
+    readonly files: readonly Sourced[];
+    readonly at: string;
+}
+export interface Trial {
+    readonly id: string;
+    readonly rule: string;
+    readonly name: string;
+    readonly scenario: Scenario;
+    readonly verdict: {
+        readonly reports: boolean;
+    };
+    readonly requires: string;
+}
+export interface Derivation {
+    readonly trials: readonly Trial[];
+}
+export interface Outcome {
+    readonly id: string;
+    readonly rule: string;
+    readonly passed: boolean;
+    readonly failures: readonly string[];
+    readonly parsed: boolean;
+}
+export interface Run {
+    readonly outcomes: readonly Outcome[];
+    readonly passed: number;
+    readonly failed: number;
+    readonly measured: number;
+}
+export declare function probeAt(rule: Constraint): string;
+export declare function deriveTrials(all: readonly Constraint[], slopnators: ReadonlyMap<string, Slopnator>): Derivation;
+export declare function trialsByproduct(derivation: Derivation): Byproduct;
+export declare function runTrial(trial: Trial, rule: Constraint, module: Rule.RuleModule, parser: unknown, slopnator?: Slopnator): Outcome;
+export declare function runTrials(trials: readonly Trial[], all: readonly Constraint[], rules: Readonly<Record<string, Rule.RuleModule>>, parser: unknown, slopnators?: ReadonlyMap<string, Slopnator>): Run;

package/dist/integrity/generators/trial.js

@@ -0,0 +1,254 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { exit, invoked } from "../../core/invoked.js";
+import { Linter } from 'eslint';
+const TREE = findTree();
+import { CONSTRAINTS } from "../constraint.js";
+import { NOT_WRITTEN, ROOT, governs, load, proofsOf, reads, rules, slopnatorName, sweeps, write } from "../slopnator.js";
+import { forget } from "../slopnators/sl_unthreaded.js";
+import { findTree } from "../../core/tree.js";
+export const TRIALS_PATH = `${findTree().name}/_generated/trials.ts`;
+const PROBE = 'probe.tsx';
+const WRAPPINGS = [
+    (source) => source,
+    (source) => `const _probe = { ${source} }`,
+    (source) => `const _probe = <Probe ${source} />`,
+    (source) => `const _probe = () => { ${source} }`,
+    (source) => `const _probe = <Probe>{${source}}</Probe>`,
+];
+export function probeAt(rule) {
+    const path = rule.where.paths[0] ?? 'src/';
+    if (path === '.')
+        return PROBE;
+    return path.endsWith('/') ? `${path}${PROBE}` : `${path}/${PROBE}`;
+}
+function requiresOf(rule, reports) {
+    return reports
+        ? `${rule.id} reports on this source, at a path it governs`
+        : `${rule.id} stays silent on this source — the fix it recommends is not itself refused`;
+}
+function scenarioOf(rule, proof) {
+    if (typeof proof !== 'string')
+        return proof;
+    const path = probeAt(rule);
+    return { files: [{ at: path, source: proof }], at: path };
+}
+function spoken(scenario) {
+    const target = scenario.files.find((file) => file.at === scenario.at) ?? scenario.files[0];
+    const rest = scenario.files.length - 1;
+    return `${target?.source ?? ''}${rest > 0 ? ` (beside ${String(rest)} more file(s))` : ''}`;
+}
+export function deriveTrials(all, slopnators) {
+    const trials = [];
+    for (const rule of all) {
+        const proofs = proofsOf(rule, slopnators);
+        const put = (proof, index, reports) => {
+            const scenario = scenarioOf(rule, proof);
+            trials.push({
+                id: `trl_rule_${rule.id.replace(/-/g, '_')}_${reports ? 'refuses' : 'accepts'}_${String(index)}`,
+                rule: rule.id,
+                name: `${rule.id} ${reports ? 'refuses' : 'accepts'}: ${spoken(scenario)}`,
+                scenario,
+                verdict: { reports },
+                requires: requiresOf(rule, reports),
+            });
+        };
+        proofs.wrong.forEach((proof, index) => { put(proof, index, true); });
+        proofs.right.forEach((proof, index) => { put(proof, index, false); });
+    }
+    return { trials: trials.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)) };
+}
+export function trialsByproduct(derivation) {
+    return {
+        path: TRIALS_PATH,
+        content: `export const RULE_TRIALS = ${JSON.stringify(derivation.trials, null, 2)} as const
+`,
+    };
+}
+function config(rule, module, parser) {
+    return [
+        {
+            files: ['**/*.ts', '**/*.tsx'],
+            languageOptions: {
+                parser,
+                parserOptions: { ecmaVersion: 'latest', sourceType: 'module', ecmaFeatures: { jsx: true } },
+            },
+            plugins: { rule: { rules: { [rule.id]: module } } },
+            rules: { [`rule/`]: 'error' },
+        },
+    ];
+}
+export function runTrial(trial, rule, module, parser, slopnator) {
+    const linter = new Linter();
+    const failures = [];
+    if (!governs(rule, trial.scenario.at)) {
+        return {
+            id: trial.id,
+            rule: rule.id,
+            passed: false,
+            parsed: false,
+            failures: [`the trial's own path "${trial.scenario.at}" is not one the rule governs, so nothing could have run`],
+        };
+    }
+    const target = trial.scenario.files.find((file) => file.at === trial.scenario.at);
+    if (target === undefined) {
+        return {
+            id: trial.id,
+            rule: rule.id,
+            passed: false,
+            parsed: false,
+            failures: [`the scenario writes no file at "${trial.scenario.at}", the path it lints, so nothing could have been measured`],
+        };
+    }
+    for (const file of trial.scenario.files) {
+        if (!existsSync(join(ROOT, file.at)))
+            continue;
+        return {
+            id: trial.id,
+            rule: rule.id,
+            passed: false,
+            parsed: false,
+            failures: [`the scenario would overwrite "${file.at}", which is a real file in this repository — a trial may not stand on a path somebody authored`],
+        };
+    }
+    const written = [];
+    const created = [];
+    let parsed = false;
+    let satisfied = false;
+    try {
+        for (const file of trial.scenario.files) {
+            const path = join(ROOT, file.at);
+            const made = mkdirSync(dirname(path), { recursive: true });
+            if (made !== undefined)
+                created.push(made);
+            writeFileSync(path, file.source);
+            written.push(path);
+        }
+        forget();
+        const path = join(ROOT, trial.scenario.at);
+        if (slopnator !== undefined && !reads(slopnator)) {
+            parsed = true;
+            satisfied = slopnator.checks(ROOT).length > 0 === trial.verdict.reports;
+        }
+        else if (slopnator !== undefined && sweeps(slopnator)) {
+            const held = slopnator.holds(undefined, {
+                filename: trial.scenario.at,
+                text: target.source,
+                ancestors: () => [],
+                comments: () => [],
+            });
+            parsed = true;
+            satisfied = (held !== false && held !== NOT_WRITTEN) === trial.verdict.reports;
+        }
+        else {
+            for (const wrap of WRAPPINGS) {
+                const text = wrap(target.source);
+                writeFileSync(path, text);
+                const messages = linter.verify(text, config(rule, module, parser), trial.scenario.at);
+                if (messages.some((message) => message.fatal === true))
+                    continue;
+                parsed = true;
+                satisfied = messages.some((message) => message.ruleId === `rule/`) === trial.verdict.reports;
+                break;
+            }
+        }
+    }
+    finally {
+        for (const path of written)
+            if (existsSync(path))
+                rmSync(path);
+        for (const path of created)
+            if (existsSync(path))
+                rmSync(path, { recursive: true });
+        forget();
+    }
+    if (!parsed) {
+        failures.push('no wrapping of this source parsed, so nothing was measured — a trial that cannot run is not a trial that passed');
+    }
+    else if (!satisfied) {
+        failures.push(trial.verdict.reports
+            ? `expected  to report on this source and it stayed silent — the rule documents a form its own slopnator does not refuse`
+            : `expected  to stay silent on this source and it reported — the rule refuses the fix it recommends`);
+    }
+    return { id: trial.id, rule: rule.id, passed: failures.length === 0, parsed, failures };
+}
+export function runTrials(trials, all, rules, parser, slopnators) {
+    const byName = new Map(all.map((rule) => [rule.id, rule]));
+    const outcomes = trials.map((trial) => {
+        const rule = byName.get(trial.rule);
+        const module = rules[trial.rule];
+        if (rule === undefined || module === undefined) {
+            return {
+                id: trial.id,
+                rule: trial.rule,
+                passed: false,
+                parsed: false,
+                failures: [`no rule named "${trial.rule}" is registered, so this trial is about nothing — regenerate with \`thread trials\``],
+            };
+        }
+        return runTrial(trial, rule, module, parser, slopnators?.get(slopnatorName(rule.id)));
+    });
+    return {
+        outcomes,
+        passed: outcomes.filter((outcome) => outcome.passed).length,
+        failed: outcomes.filter((outcome) => !outcome.passed).length,
+        measured: outcomes.filter((outcome) => outcome.parsed).length,
+    };
+}
+if (invoked(import.meta.url)) {
+    const own = await rules();
+    const governing = own ?? CONSTRAINTS;
+    const source = own === undefined
+        ? `the ${String(CONSTRAINTS.length)} constraint(s) this tree authors`
+        : `the ${String(own.length)} rule(s) this tree declares — a shipped constraint is proved in the package that ships it, against the paths that package governs`;
+    const slopnators = await load(ROOT, governing);
+    const derivation = deriveTrials(governing, slopnators);
+    const byproduct = trialsByproduct(derivation);
+    if (process.argv.includes('--check')) {
+        const path = join(ROOT, byproduct.path);
+        const current = existsSync(path) ? readFileSync(path, 'utf8') : '';
+        const drifted = current !== byproduct.content;
+        if (drifted)
+            console.error(`trial: ${byproduct.path} is not what the rules derive. Run \`thread trials\` and commit the result.`);
+        console.log(`trial: ${String(derivation.trials.length)} derived from ${source}, ${String(drifted ? 1 : 0)} findings.`);
+        exit(drifted ? 1 : 0);
+    }
+    if (process.argv.includes('--try')) {
+        const at = process.argv.indexOf('--rule');
+        const only = at === -1 ? undefined : (process.argv[at + 1] ?? '').split(',').map((one) => one.trim()).filter(Boolean);
+        const unknown = (only ?? []).filter((id) => !governing.some((rule) => rule.id === id));
+        if (unknown.length > 0) {
+            console.error(`trial: no rule is called ${unknown.join(', ')} — a filter naming nothing would measure nothing and exit 0`);
+            exit(1);
+        }
+        const chosen = only === undefined ? derivation.trials : derivation.trials.filter((trial) => only.includes(trial.rule));
+        if (chosen.length === 0) {
+            if (only !== undefined) {
+                console.error('trial: the filter selected no trials, and measuring nothing must not exit 0');
+                exit(1);
+            }
+            if (governing.length > 0) {
+                console.error(`trial: ${String(governing.length)} rule(s) govern and none derived a trial — every rule owes a \`wrong\` and a \`right\`, so measuring nothing must not exit 0`);
+                exit(1);
+            }
+            console.log(`trial: nothing to prove — ${source}.`);
+            exit(0);
+        }
+        const { default: plugin } = await import("../lint.js");
+        const parser = (await import('typescript-eslint')).parser;
+        const run = runTrials(chosen, governing, plugin.rules, parser, slopnators);
+        for (const outcome of run.outcomes) {
+            if (outcome.passed)
+                continue;
+            for (const failure of outcome.failures)
+                console.error(`trial: ${outcome.id} — ${failure}`);
+        }
+        console.log(`trial: ${String(run.passed)} of ${String(run.outcomes.length)} passed, ${String(run.measured)} measured.`);
+        if (only !== undefined) {
+            console.log(`trial: PARTIAL RUN — ${String(derivation.trials.length - chosen.length)} of ${String(derivation.trials.length)} derived trials did not run. \`thread trials\` with no arguments runs every one.`);
+        }
+        exit(run.failed === 0 ? 0 : 1);
+    }
+    write(ROOT, byproduct);
+    console.log(`trial: wrote ${byproduct.path} — ${String(derivation.trials.length)} trials from ${source}.`);
+}

package/dist/integrity/lint.d.ts

@@ -0,0 +1,50 @@
+import { type Rule } from 'eslint';
+import { type Constraint } from './constraint.ts';
+import { type Slopnator } from './slopnator.ts';
+export declare function ruleMessage(rule: Constraint): string;
+export declare function agentInstructions(): readonly string[];
+export declare function defineRule(rule: Constraint, slopnators: ReadonlyMap<string, Slopnator>): Constraint;
+export declare function defineRules(slopnators: ReadonlyMap<string, Slopnator>): readonly Constraint[];
+export declare function ruleRule(rule: Constraint, slopnators: ReadonlyMap<string, Slopnator>): Rule.RuleModule;
+export declare function ruleRules(slopnators: ReadonlyMap<string, Slopnator>): Readonly<Record<string, Rule.RuleModule>>;
+export declare function ruleSeverities(): Readonly<Record<string, 'error' | 'warn'>>;
+export declare const plugin: {
+    rules: Readonly<Record<string, Rule.RuleModule>>;
+};
+export default plugin;
+export declare const rules: {
+    files: string[];
+    ignores: readonly string[];
+    languageOptions: {
+        parser: import("typescript-eslint").CompatibleParser;
+        parserOptions: {
+            ecmaVersion: string;
+            sourceType: string;
+            ecmaFeatures: {
+                jsx: boolean;
+            };
+        };
+    };
+    plugins: {
+        lint: {
+            rules: Readonly<Record<string, Rule.RuleModule>>;
+        };
+    };
+    rules: Readonly<Record<string, "error" | "warn">>;
+};
+export declare function ruleDeclarations(): readonly (Constraint & {
+    readonly name: string;
+})[];
+export interface RuleViolation {
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+    readonly rule: string;
+    readonly message: string;
+    readonly bans?: string;
+    readonly instead?: string;
+    readonly wrong?: string;
+    readonly right?: string;
+}
+export type RuleRunner = (file: string, source: string) => readonly RuleViolation[];
+export declare function theRules(): RuleRunner;