@shrkcrft/cli 0.1.0-alpha.29 → 0.1.0-alpha.31

package/dist/gates/run-gate-planes.d.ts

@@ -0,0 +1,58 @@
+import { type ISharkcraftInspection } from '@shrkcrft/inspector';
+import type { IGateRuleResult } from './gate-envelope.js';
+import type { IUnitStateNoteRow } from './i-unit-state-note-row.js';
+import type { IGateRuleView } from './gate-rule-view.js';
+/**
+ * Run every data-defined plane's VIOLATION check and normalize the results.
+ *
+ * Each plane already has a verb, but gating a change meant running five of them
+ * and `&&`-chaining five exit codes — so in practice people ran one or two. The
+ * value here is that one call answers "does this change violate any declared
+ * rule?" with one exit code, and it does so by calling the SAME evaluators the
+ * per-plane verbs call. A second implementation of any plane's check would
+ * eventually disagree with the verb, and the aggregate — the one wired into CI
+ * — would be the copy nobody notices is wrong.
+ *
+ * The same holds for COVERAGE: each rule's `coverage` comes from the plane's
+ * own coverage function (the one its verb uses), so `gates check` and the
+ * per-plane verb can never disagree about how much of a rule's scope was
+ * examined. Round 13: so does each rule's `expectEmpty` acceptance
+ * (`unitAcceptance`, folded into the envelope's one settle) and its unit lines.
+ */
+export interface IRunGatePlanesOptions {
+    readonly cwd: string;
+    readonly excludeDirs: readonly string[];
+    /**
+     * Restrict to rules whose footprint intersects these changed files. Scoping
+     * is applied by the CALLER (it owns the git diff); this is passed through to
+     * the plane engines that scope internally.
+     */
+    readonly changedFiles?: readonly string[];
+    /**
+     * Skip every check that would SPAWN a shell (a `command` baseline compute, a
+     * generated `regen`). The header/classification halves still run, so the
+     * result stays honest — a skipped drift check is reported as skipped, never
+     * folded into a pass.
+     */
+    readonly noSpawn?: boolean;
+    /**
+     * Registries for the doc-reference plane. Built lazily by the caller — a
+     * repo without that plane never loads them.
+     */
+    readonly inspection?: ISharkcraftInspection;
+}
+/** One plane's contribution, plus any engine diagnostics it produced. */
+export interface IGatePlaneRun {
+    readonly results: readonly IGateRuleResult[];
+    readonly diagnostics: readonly string[];
+    /**
+     * Each rule's settled non-live selector units (round 13, K2) — what THE
+     * shared unit-state renderer (`unitStateNotes`) reads, so `gates check` lists
+     * a dead unit or a went-live marker exactly as the plane verb does. Kept off
+     * the envelope rows, which carry the `units` lines only.
+     */
+    readonly noteRows?: readonly IUnitStateNoteRow[];
+}
+/** Evaluate the given rules, dispatching each to its plane's real engine. */
+export declare function runGatePlanes(rules: readonly IGateRuleView[], options: IRunGatePlanesOptions): IGatePlaneRun;
+//# sourceMappingURL=run-gate-planes.d.ts.map

package/dist/gates/run-gate-planes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-gate-planes.d.ts","sourceRoot":"","sources":["../../src/gates/run-gate-planes.ts"],"names":[],"mappings":"AAYA,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AA+BrF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAa,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIpE;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC;CAC7C;AAED,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAClD;AAqCD,6EAA6E;AAC7E,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,OAAO,EAAE,qBAAqB,GAC7B,aAAa,CA2Bf"}

package/dist/gates/run-gate-planes.js

@@ -0,0 +1,403 @@
+import { failsWhenEmpty, resolveSourceGlobs, RuleEmptiness, settleRuleEmptiness, unitStateLists, UnitLivenessState, } from '@shrkcrft/core';
+import { checkDocReferences } from '@shrkcrft/inspector';
+import { buildRegistrationGraph, globListSelects, readScopeCoverage, readScopeHasUnread, registrationOrphans, registrationUnprovided, registryDuplicates, runPolicyLint, runWiring, scanRegistry, settleGlobLists, } from '@shrkcrft/boundaries';
+import { baselineCoverage, evaluateBaselineRule } from "../commands/baseline.command.js";
+import { evaluateGeneratedRule, generatedCoverage, generatedHintFor, } from "../commands/generated.command.js";
+import { docReferenceCoverage } from "../commands/docs-references.command.js";
+import { policyRuleCoverage } from "../commands/policy-lint.command.js";
+import { measureRegistrationRoles } from "./measure-registration-roles.js";
+import { registryLiveness } from "./registry-liveness.js";
+/** The unit fields a plane engine put on its result, passed through to the envelope rule (round 13). */
+function unitFields(r) {
+    return {
+        ...(r.unitAcceptance !== undefined ? { unitAcceptance: r.unitAcceptance } : {}),
+        ...(r.units !== undefined ? { units: r.units } : {}),
+        ...(r.unitLiveness !== undefined && r.unitLiveness.length > 0 ? { unitLiveness: r.unitLiveness } : {}),
+    };
+}
+/** The same, from a settle this module ran itself. */
+function livenessFields(l) {
+    if (l === undefined)
+        return {};
+    const nonLive = l.units.filter((u) => u.state !== UnitLivenessState.Live);
+    return {
+        ...(l.acceptance !== undefined ? { unitAcceptance: l.acceptance } : {}),
+        ...(l.dead.length + l.intendedEmpty.length + l.wentLive.length > 0 ? { units: unitStateLists(l) } : {}),
+        ...(nonLive.length > 0 ? { unitLiveness: nonLive } : {}),
+    };
+}
+/** Evaluate the given rules, dispatching each to its plane's real engine. */
+export function runGatePlanes(rules, options) {
+    const results = [];
+    const diagnostics = [];
+    const byPlane = (plane) => rules.filter((r) => r.plane === plane).map((r) => r.raw);
+    const planeResults = [
+        ...runWiringPlane(byPlane('wiring'), options, diagnostics),
+        ...runPolicyPlane(byPlane('policy'), options),
+        ...runRegistryPlane(byPlane('registry'), options),
+        ...runRegistrationPlane(byPlane('registration'), options),
+        ...runBaselinePlane(byPlane('baseline'), options),
+        ...runGeneratedPlane(byPlane('generated'), options),
+        ...runDocReferencePlane(byPlane('doc-reference'), options),
+    ];
+    // Each rule's settled units leave its envelope row (the envelope carries the
+    // `units` lines) for the note rows THE shared unit-state renderer reads (K2).
+    const noteRows = [];
+    for (const r of planeResults) {
+        const { unitLiveness, ...row } = r;
+        results.push(row);
+        if (unitLiveness !== undefined) {
+            noteRows.push({ id: r.id, unitLiveness, reportedEmpty: r.status === 'skipped' || r.skipReason !== undefined });
+        }
+    }
+    return { results, diagnostics, noteRows };
+}
+function runWiringPlane(rules, options, diagnostics) {
+    if (rules.length === 0)
+        return [];
+    const report = runWiring(options.cwd, rules, { excludeDirs: options.excludeDirs });
+    diagnostics.push(...report.diagnostics);
+    return report.rules.map((r) => {
+        const skip = report.skipped.find((s) => s.ruleId === r.ruleId);
+        return {
+            id: r.ruleId,
+            type: 'wiring',
+            status: r.status,
+            severity: r.severity,
+            counts: { declared: r.declaredCount, registered: r.registeredCount },
+            violations: r.violations.map((v) => ({
+                id: v.token,
+                ...(v.file ? { file: v.file } : {}),
+                ...(v.line !== undefined ? { line: v.line } : {}),
+                ...(v.message ? { message: v.message } : {}),
+                ...(v.hint ? { hint: v.hint } : {}),
+            })),
+            ...(skip ? { skipReason: skip.reason } : {}),
+            ...(r.error ? { error: r.error } : {}),
+            // The engine's own coverage — a subset rule's registered-only tokens
+            // arrive here as unexamined, which is what makes it `partial`.
+            coverage: r.coverage,
+            ...unitFields(r),
+        };
+    });
+}
+function runPolicyPlane(rules, options) {
+    if (rules.length === 0)
+        return [];
+    const report = runPolicyLint(options.cwd, rules, { excludeDirs: options.excludeDirs });
+    return report.rules.map((r) => {
+        const rule = rules.find((x) => x.id === r.ruleId);
+        const findings = report.findings.filter((f) => f.ruleId === r.ruleId);
+        const skip = report.skipped.find((s) => s.ruleId === r.ruleId);
+        return {
+            id: r.ruleId,
+            type: 'policy',
+            status: r.status,
+            severity: r.severity,
+            counts: { units: r.unitsScanned, findings: r.findingCount, suppressed: r.suppressedCount },
+            violations: findings.map((f) => ({
+                id: f.file,
+                file: f.file,
+                line: f.line,
+                message: f.message,
+                ...(f.suggest ?? rule?.suggest ? { hint: f.suggest ?? rule.suggest } : {}),
+            })),
+            ...(skip ? { skipReason: skip.reason } : {}),
+            ...(r.error ? { error: r.error } : {}),
+            coverage: policyRuleCoverage(r),
+            ...unitFields(r),
+        };
+    });
+}
+/**
+ * The registry plane's violation check is DUPLICATES: two roots claiming one id
+ * compile fine, and whichever registration wins at runtime is an accident of
+ * load order. (Presence queries are lookups, not gates, so they are not run.)
+ */
+function runRegistryPlane(decls, options) {
+    return decls.map((decl) => {
+        const inventory = scanRegistry(options.cwd, decl, { excludeDirs: options.excludeDirs });
+        const dupes = registryDuplicates(inventory);
+        // A source file the reader could not read (over the read cap) makes the
+        // inventory incomplete. Zero ids over it is not "matched nothing" (never a
+        // failOnEmpty failure), and "no duplicates" over it is not a pass: its
+        // coverage is the file record, so the rule settles PARTIAL.
+        const empty = inventory.entries.length === 0 && !readScopeHasUnread(inventory.readScope);
+        // The registry's globs settled with their `expectEmpty` markers (round 13)
+        // — only when a unit is marked, or the inventory is empty (what it is
+        // decided from). The registry verbs read the same `registryLiveness`.
+        const marked = [decl.source, decl.consumer].some((s) => (s?.expectEmptyUnits?.length ?? 0) > 0);
+        const liveness = marked || empty ? registryLiveness(options.cwd, decl, options.excludeDirs) : undefined;
+        // `failOnEmpty` makes a dead inventory BLOCK, exactly as a failOnEmpty
+        // wiring rule does; without it an empty registry stays a loud skip. A
+        // registry has no severity of its own, so THE failOnEmpty authority answers
+        // for a warning-severity rule (default off; an explicit `true` promotes it).
+        const failOnEmpty = failsWhenEmpty({
+            ...(decl.failOnEmpty !== undefined ? { failOnEmpty: decl.failOnEmpty } : {}),
+            severity: 'warning',
+        });
+        const staleReason = failOnEmpty
+            ? 'matched 0 ids — failOnEmpty: the source selector is probably stale'
+            : 'matched 0 ids — the source selector is probably stale';
+        // THE rule-emptiness settle: every source inclusion glob marked
+        // `expectEmpty` and no source file matched → an inventory over a planned
+        // directory, accepted and printed; anything else is the loud skip.
+        const emptiness = empty && liveness !== undefined
+            ? settleRuleEmptiness({
+                subject: decl.name,
+                unitLabel: 'ids',
+                filesMatched: inventory.readScope.read,
+                unitsMatched: 0,
+                unread: false,
+                liveness,
+                primaryLists: ['source.files'],
+                failOnEmpty,
+                noFilesReason: staleReason,
+                noUnitsReason: staleReason,
+            })
+            : undefined;
+        const intended = emptiness?.state === RuleEmptiness.IntendedEmpty && emptiness.coverage !== undefined;
+        const skipped = emptiness?.skipped === true;
+        const skipReason = emptiness?.skipReason ?? staleReason;
+        return {
+            id: decl.name,
+            type: 'registry',
+            status: skipped
+                ? emptiness?.fails
+                    ? 'failed'
+                    : 'skipped'
+                : dupes.length > 0
+                    ? 'failed'
+                    : 'passed',
+            severity: emptiness?.fails ? 'error' : 'warning',
+            counts: { ids: inventory.entries.length, duplicates: dupes.length },
+            violations: dupes.map((d) => ({
+                id: d.id,
+                ...(d.sites[0] ? { file: d.sites[0].file, line: d.sites[0].line } : {}),
+                message: `declared in ${d.sites.length} places: ${d.sites.map((s) => `${s.file}:${s.line}`).join(', ')}`,
+                hint: 'remove the duplicate declaration — which one wins is load-order roulette',
+            })),
+            ...(skipped ? { skipReason } : {}),
+            coverage: intended && emptiness?.coverage !== undefined
+                ? emptiness.coverage
+                : readScopeCoverage({
+                    unit: 'ids',
+                    expected: inventory.entries.length,
+                    examined: inventory.entries.length,
+                    ...(skipped ? { reason: skipReason } : {}),
+                }, inventory.readScope),
+            ...livenessFields(liveness),
+        };
+    });
+}
+/**
+ * The registration plane's violation check is UNPROVIDED: a token declared or
+ * consumed but provided by nothing resolves to nothing at runtime — invisible
+ * to the compiler, which is the entire reason this plane exists. Orphans (a
+ * provider nothing consumes) are COUNTED but do not fail: a registration ahead
+ * of its consumer is a normal intermediate state, not a defect.
+ */
+function runRegistrationPlane(idioms, options) {
+    if (idioms.length === 0)
+        return [];
+    // The graph is built from EVERY idiom at once (that is what makes a
+    // declared→provided→consumed chain traceable across them), so a finding has
+    // to be attributed back by matching its sites against each idiom's own globs.
+    // Dumping every finding on the first idiom would leave the others reading
+    // `passed` while their tokens resolve to nothing — a green that means nothing.
+    const graph = buildRegistrationGraph(options.cwd, idioms, { excludeDirs: options.excludeDirs });
+    const unprovided = registrationUnprovided(graph, options.changedFiles);
+    const orphans = registrationOrphans(graph, options.changedFiles);
+    // Per ROLE list: a role's `!x` subtracts from that role only, so it never
+    // disowns a file another role of the idiom reads.
+    const ownsFile = (idiom, file) => [idiom.declared, idiom.consumed, idiom.provided].some((role) => globListSelects(file, resolveSourceGlobs(role)));
+    return idioms.map((idiom) => {
+        const mine = unprovided.filter((t) => [...t.declared, ...t.consumed].some((site) => ownsFile(idiom, site.file)));
+        const myOrphans = orphans.filter((t) => t.provided.some((site) => ownsFile(idiom, site.file)));
+        // "Is this idiom empty?" and "which role examined nothing?" come from the
+        // ONE measurement `gates coverage` reads too. Keying emptiness on the
+        // graph's token union used to print a ✓ over an idiom whose declared glob
+        // had moved (its provided/consumed roles kept the union non-empty), while
+        // coverage FAILED the same idiom.
+        const roles = measureRegistrationRoles(options.cwd, idiom, options.excludeDirs);
+        const failOnEmpty = failsWhenEmpty({
+            ...(idiom.failOnEmpty !== undefined ? { failOnEmpty: idiom.failOnEmpty } : {}),
+            severity: 'warning',
+        });
+        const staleReason = `the declared role extracted 0 tokens${failOnEmpty ? ' (failOnEmpty)' : ''}, ` +
+            'so the declared selector is probably stale';
+        // THE rule-emptiness settle (round 13) on the declared role — the idiom's
+        // primary selector: every declared inclusion glob marked `expectEmpty` and
+        // no declared file matched → a planned token space, accepted; 0 tokens out
+        // of live declared files is the loud skip it always was.
+        const emptiness = roles.error === undefined && roles.empty
+            ? settleRuleEmptiness({
+                subject: idiom.name,
+                unitLabel: 'declared tokens',
+                filesMatched: roles.declared.filesScanned,
+                unitsMatched: 0,
+                unread: false,
+                liveness: roles.liveness ?? settleGlobLists({ subject: idiom.name, lists: [], marks: [] }),
+                primaryLists: ['declared.files'],
+                failOnEmpty,
+                noFilesReason: staleReason,
+                noUnitsReason: staleReason,
+            })
+            : undefined;
+        const skipped = emptiness?.skipped === true;
+        return {
+            id: idiom.name,
+            type: 'registration',
+            status: roles.error !== undefined
+                ? 'error'
+                : skipped
+                    ? emptiness?.fails
+                        ? 'failed'
+                        : 'skipped'
+                    : mine.length > 0
+                        ? 'failed'
+                        : 'passed',
+            severity: emptiness?.fails ? 'error' : 'warning',
+            counts: { tokens: graph.tokens.length, unprovided: mine.length, orphans: myOrphans.length },
+            violations: mine.map((t) => ({
+                id: t.token,
+                ...(t.declared[0] ? { file: t.declared[0].file, line: t.declared[0].line } : {}),
+                message: 'declared/consumed but provided by nothing — resolves to nothing at runtime',
+                hint: `trace it with \`shrk wiring chain ${t.token}\``,
+            })),
+            ...(skipped ? { skipReason: emptiness?.skipReason ?? staleReason } : {}),
+            ...(roles.error !== undefined ? { error: roles.error } : {}),
+            // A dead role is an unexamined unit: the rule settles to `partial`, never
+            // ✓. An intended-empty role rides on the acceptance instead.
+            coverage: roles.coverage,
+            ...livenessFields(roles.liveness),
+        };
+    });
+}
+function runBaselinePlane(rules, options) {
+    return rules.map((rule) => {
+        // A `command` compute spawns a shell. Under --no-spawn it is reported as
+        // skipped WITH the reason, never silently treated as clean.
+        if (options.noSpawn && rule.compute.kind === 'command') {
+            return {
+                id: rule.id,
+                type: 'baseline',
+                status: 'skipped',
+                severity: rule.severity ?? 'error',
+                counts: { committed: 0, current: 0 },
+                violations: [],
+                skipReason: '`command` compute skipped by --no-spawn',
+                coverage: { unit: 'baseline computes', expected: 1, examined: 0, reason: 'skipped by --no-spawn' },
+            };
+        }
+        const o = evaluateBaselineRule(options.cwd, rule, options.excludeDirs, options.changedFiles);
+        return {
+            id: o.rule.id,
+            type: 'baseline',
+            status: o.status,
+            severity: o.rule.severity ?? 'error',
+            counts: { committed: o.committedCount, current: o.currentCount },
+            violations: [
+                ...(o.diff?.added ?? []).map((e) => ({ id: e, message: 'gained since the baseline was blessed' })),
+                ...(o.diff?.removed ?? []).map((e) => ({ id: e, message: 'LOST since the baseline was blessed' })),
+            ].map((v) => ({ ...v, hint: rule.hint ?? `bless with \`shrk baseline update --id ${rule.id}\`` })),
+            ...(o.skipReason ? { skipReason: o.skipReason } : {}),
+            ...(o.error ? { error: o.error } : {}),
+            coverage: baselineCoverage(o),
+            ...unitFields(o),
+        };
+    });
+}
+/**
+ * The doc-reference plane's violation check: an id cited in prose that resolves
+ * to nothing. Skipped honestly when the registries were not loaded — claiming a
+ * pass without having checked is the failure mode this whole surface exists to
+ * prevent.
+ */
+function runDocReferencePlane(rules, options) {
+    if (rules.length === 0)
+        return [];
+    const inspection = options.inspection;
+    if (!inspection) {
+        const skipReason = 'registries not loaded — doc references were not resolved';
+        return rules.map((rule) => ({
+            id: rule.id,
+            type: 'doc-reference',
+            status: 'skipped',
+            severity: rule.severity ?? 'error',
+            counts: { files: 0, tokens: 0 },
+            violations: [],
+            skipReason,
+            coverage: { unit: 'references', expected: 0, examined: 0, reason: skipReason },
+        }));
+    }
+    return rules.map((rule) => {
+        const res = checkDocReferences(options.cwd, rule, inspection, options.excludeDirs);
+        return {
+            id: res.ruleId,
+            type: 'doc-reference',
+            status: res.status,
+            severity: res.severity,
+            counts: { files: res.filesScanned, tokens: res.tokensChecked, skipped: res.tokensSkipped },
+            violations: res.findings.map((f) => ({
+                id: f.token,
+                file: f.file,
+                line: f.line,
+                message: f.message,
+                ...(f.didYouMean.length > 0 ? { hint: `did you mean: ${f.didYouMean.join(', ')}` } : {}),
+            })),
+            ...(res.skipReason ? { skipReason: res.skipReason } : {}),
+            ...(res.error ? { error: res.error } : {}),
+            coverage: docReferenceCoverage(res),
+            ...unitFields(res),
+        };
+    });
+}
+function runGeneratedPlane(rules, options) {
+    return rules.map((rule) => {
+        // --no-spawn keeps the header + classification halves (pure reads) and
+        // drops only the regen diff, which is reported as a partial run.
+        const headersOnly = options.noSpawn === true;
+        const o = evaluateGeneratedRule(options.cwd, rule, options.excludeDirs, headersOnly);
+        const spawnSkipped = headersOnly && (rule.regen !== undefined || (rule.sources?.length ?? 0) > 0);
+        // A rule whose DRIFT half was skipped has not passed — it partially ran. A
+        // header contract holding proves nothing about whether the file was
+        // hand-edited, so reporting `passed` here would be the exact false green
+        // this plane exists to prevent. Findings still fail; the clean case
+        // downgrades to `skipped` so the aggregate exit is 2, not 0.
+        const status = spawnSkipped && o.status === 'passed' ? 'skipped' : o.status;
+        return {
+            id: o.rule.id,
+            type: 'generated',
+            status,
+            severity: o.rule.severity ?? 'error',
+            counts: {
+                files: o.committedCount,
+                differences: o.treeDiff?.differences.length ?? 0,
+                provenance: o.provenance.length,
+            },
+            violations: [
+                ...(o.treeDiff?.differences ?? []).map((d) => ({
+                    id: d.file,
+                    file: d.file,
+                    message: d.kind,
+                    hint: generatedHintFor(o.rule),
+                })),
+                ...o.provenance.map((f) => ({
+                    id: f.file,
+                    file: f.file,
+                    message: f.message,
+                    hint: generatedHintFor(o.rule),
+                })),
+            ],
+            ...(o.skipReason
+                ? { skipReason: o.skipReason }
+                : spawnSkipped
+                    ? { skipReason: 'regen drift check skipped by --no-spawn (headers + classification still ran)' }
+                    : {}),
+            ...(o.error ? { error: o.error } : {}),
+            coverage: generatedCoverage(o, spawnSkipped),
+            ...unitFields(o),
+        };
+    });
+}

package/dist/gates/scaffold-selftest.d.ts

@@ -0,0 +1,56 @@
+import type { IGateCoverage } from './rule-coverage.js';
+/**
+ * A scaffolded `selfTest`, ready to paste (or to insert with `--write`).
+ *
+ * The trust layer asks every rule to carry `failOnEmpty` + a `selfTest`, so a
+ * stale glob after a directory move fails LOUD instead of passing over an empty
+ * set. In practice the selfTest is the step that gets skipped — not from
+ * disagreement, but because authoring the fixture inline (which ids to pin,
+ * what floor to set) is a blank page at the exact moment the author just wants
+ * the rule to work. A rule with no selfTest is invisible to the stale-glob
+ * detector, so the friction converts directly into missing coverage.
+ */
+export interface IScaffoldedSelfTest {
+    readonly ruleId: string;
+    readonly plane: string;
+    /** What the rule matches right now — the number the floor is derived from. */
+    readonly currentCount: number;
+    readonly expectMatchesAtLeast: number;
+    readonly expectIds: readonly string[];
+    /** The percentage of headroom left below the current count. */
+    readonly marginPercent: number;
+    /** The literal block to paste into the rule. */
+    readonly snippet: string;
+    /**
+     * Why some extracted ids were NOT pinned, or why `expectIds` is empty. Today
+     * this applies to the policy plane: a live finding is debt, and pinning it
+     * would turn paying the debt into a gate failure.
+     */
+    readonly note?: string;
+}
+/**
+ * Build a ready-to-commit `selfTest` from what the rule matches TODAY.
+ *
+ * The floor is deliberately BELOW the current count: pinning the exact number
+ * would turn every legitimate addition into a failure, and a rule that cries
+ * wolf on normal work gets its expectations deleted rather than fixed. The
+ * margin is what keeps the assertion about "the selector still bites" rather
+ * than about "the set never changes".
+ */
+export declare function scaffoldSelfTest(coverage: IGateCoverage, marginPercent: number, sampleSize?: number): IScaffoldedSelfTest;
+/** Outcome of inserting a scaffolded selfTest into the config text. */
+export interface IInsertResult {
+    readonly ok: boolean;
+    readonly text?: string;
+    readonly error?: string;
+}
+/**
+ * Insert the block into the rule whose `id` matches, in place.
+ *
+ * Refuses rather than guesses. A config is the file every gate reads, so a
+ * write that lands in the wrong rule — or in one of two rules sharing an id —
+ * would silently re-point an assertion at a different set, which is worse than
+ * making the author paste three lines by hand.
+ */
+export declare function insertSelfTest(configText: string, ruleId: string, snippet: string): IInsertResult;
+//# sourceMappingURL=scaffold-selftest.d.ts.map

package/dist/gates/scaffold-selftest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-selftest.d.ts","sourceRoot":"","sources":["../../src/gates/scaffold-selftest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AA0BD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,aAAa,EACvB,aAAa,EAAE,MAAM,EACrB,UAAU,SAAI,GACb,mBAAmB,CA6BrB;AAmBD,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,aAAa,CA8Bf"}

package/dist/gates/scaffold-selftest.js

@@ -0,0 +1,119 @@
+/** Markers that make an id a poor anchor: it is likely to be renamed or removed. */
+const UNSTABLE = /(^|[^a-z])(tmp|temp|draft|wip|scratch|legacy|deprecated|old|new|test|fixture|sample|example|foo|bar|baz)([^a-z]|$)/i;
+/**
+ * How good an anchor an id is, higher is better.
+ *
+ * A selfTest is only as useful as the ids it pins: anchoring on a name that was
+ * always going to be deleted produces a rule that fails for a reason unrelated
+ * to the selector, which trains people to delete the selfTest. So the obviously
+ * temporary and the obviously generated are ranked last, and everything else is
+ * ordered deterministically by name so the same tree always scaffolds the same
+ * fixture.
+ */
+function stability(id) {
+    let score = 100;
+    if (UNSTABLE.test(id))
+        score -= 60;
+    // A long digit or hex run reads as generated (a hash, a timestamp, an index).
+    if (/\d{4,}/.test(id))
+        score -= 40;
+    if (/[0-9a-f]{8,}/i.test(id))
+        score -= 40;
+    // Trailing counters (`handlerV2`, `route3`) churn as versions advance.
+    if (/\d$/.test(id))
+        score -= 15;
+    return score;
+}
+/**
+ * Build a ready-to-commit `selfTest` from what the rule matches TODAY.
+ *
+ * The floor is deliberately BELOW the current count: pinning the exact number
+ * would turn every legitimate addition into a failure, and a rule that cries
+ * wolf on normal work gets its expectations deleted rather than fixed. The
+ * margin is what keeps the assertion about "the selector still bites" rather
+ * than about "the set never changes".
+ */
+export function scaffoldSelfTest(coverage, marginPercent, sampleSize = 3) {
+    // A plane whose extracted set mixes stable anchors with ids that are meant to
+    // go away (the policy plane: a live finding is debt) says which ids are safe
+    // to pin. Only those are scaffolded. Pinning a live violation would make
+    // `gates coverage` fail on the day the author fixes the code the rule forbids.
+    const ids = coverage.pinIds ?? coverage.allIds ?? coverage.sampleIds;
+    const count = coverage.unitsMatched;
+    const floor = Math.max(1, Math.floor(count * (1 - marginPercent / 100)));
+    const expectIds = [...ids]
+        .sort((a, b) => stability(b) - stability(a) || a.localeCompare(b))
+        .slice(0, Math.min(sampleSize, ids.length));
+    const snippet = [
+        'selfTest: {',
+        `  expectMatchesAtLeast: ${floor},`,
+        `  expectIds: [${expectIds.map((i) => `'${i}'`).join(', ')}],`,
+        '  expectNotIds: [],',
+        '},',
+    ].join('\n');
+    const note = pinNote(coverage);
+    return {
+        ruleId: coverage.id,
+        plane: coverage.plane,
+        currentCount: count,
+        expectMatchesAtLeast: floor,
+        expectIds,
+        marginPercent,
+        snippet,
+        ...(note ? { note } : {}),
+    };
+}
+/** Why a plane's pinnable set is narrower than what it extracted, when it is. */
+function pinNote(coverage) {
+    if (coverage.pinIds === undefined)
+        return undefined;
+    const pinnable = new Set(coverage.pinIds);
+    const live = (coverage.allIds ?? coverage.sampleIds).filter((id) => !pinnable.has(id));
+    const skipped = live.length > 0
+        ? `${live.length} id(s) matched by a live finding were not pinned (${live.slice(0, 3).join(', ')}` +
+            `${live.length > 3 ? ', …' : ''}). A finding is debt, and pinning it would fail the gate once the debt is paid. `
+        : '';
+    if (coverage.pinIds.length > 0)
+        return skipped ? skipped.trimEnd() : undefined;
+    return (`${skipped}No exempted hit to pin, so expectIds is left empty. Add a fixture file under the rule's ` +
+        '`exemptFiles` that contains the forbidden pattern. expectIds can then prove the pattern still bites.');
+}
+/**
+ * Insert the block into the rule whose `id` matches, in place.
+ *
+ * Refuses rather than guesses. A config is the file every gate reads, so a
+ * write that lands in the wrong rule — or in one of two rules sharing an id —
+ * would silently re-point an assertion at a different set, which is worse than
+ * making the author paste three lines by hand.
+ */
+export function insertSelfTest(configText, ruleId, snippet) {
+    // A registry declaration is keyed by `name`, every other plane by `id`. Both
+    // are the rule's identity as `gates list` prints it, so both are accepted —
+    // an author should not have to know which plane spells it which way.
+    const idPattern = new RegExp(`^([ \\t]*)(?:id|name):\\s*['"\`]${escapeRegex(ruleId)}['"\`]\\s*,?\\s*$`, 'gm');
+    const matches = [...configText.matchAll(idPattern)];
+    if (matches.length === 0) {
+        return {
+            ok: false,
+            error: `no \`id: '${ruleId}'\` (or \`name:\`) line found in the config — is the rule contributed by a pack?`,
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            ok: false,
+            error: `"${ruleId}" appears ${matches.length} times — refusing to guess which rule to edit`,
+        };
+    }
+    const m = matches[0];
+    const indent = m[1] ?? '  ';
+    const lineEnd = configText.indexOf('\n', m.index);
+    const at = lineEnd === -1 ? configText.length : lineEnd + 1;
+    const block = snippet
+        .split('\n')
+        .map((l) => (l === '' ? l : indent + l))
+        .join('\n');
+    return { ok: true, text: configText.slice(0, at) + block + '\n' + configText.slice(at) };
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}