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

package/dist/commands/generated.command.d.ts

@@ -1,6 +1,38 @@
+import { type IGeneratedArtifactRule } from '@shrkcrft/core';
+import { type IGeneratedTreeDiff, type IProvenanceFinding } from '@shrkcrft/boundaries';
 import { type ICommandHandler } from '../command-registry.js';
+/**
+ * One rule's outcome. Exported so `shrk gates check` aggregates the SAME
+ * evaluation the per-plane verb runs, rather than a second implementation that
+ * could drift from it.
+ */
+export interface IGeneratedOutcome {
+    readonly rule: IGeneratedArtifactRule;
+    readonly status: 'passed' | 'failed' | 'skipped' | 'error';
+    readonly committedCount: number;
+    readonly treeDiff?: IGeneratedTreeDiff;
+    readonly provenance: readonly IProvenanceFinding[];
+    readonly error?: string;
+    readonly skipReason?: string;
+    /** True when the drift half was deliberately not run (`--headers-only` / no `regen`). */
+    readonly driftChecked: boolean;
+    /** Files excluded from every check by `handMaintained`. */
+    readonly handMaintained: readonly string[];
+    /** Per-writer drift results, for a multi-writer rule. */
+    readonly writers: readonly IWriterOutcome[];
+}
+/** One writer's slice result inside a multi-writer rule. */
+interface IWriterOutcome {
+    readonly label: string;
+    readonly committedCount: number;
+    readonly differences: number;
+    readonly error?: string;
+}
+export declare function evaluateGeneratedRule(cwd: string, rule: IGeneratedArtifactRule, excludeDirs: readonly string[], headersOnly: boolean): IGeneratedOutcome;
+export declare function generatedHintFor(rule: IGeneratedArtifactRule): string;
 export declare const generatedListCommand: ICommandHandler;
 export declare const generatedCheckCommand: ICommandHandler;
 export declare const generatedUpdateCommand: ICommandHandler;
 export declare const generatedExplainCommand: ICommandHandler;
+export {};
 //# sourceMappingURL=generated.command.d.ts.map

package/dist/commands/generated.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generated.command.d.ts","sourceRoot":"","sources":["../../src/commands/generated.command.ts"],"names":[],"mappings":"AA+BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAyShC,eAAO,MAAM,oBAAoB,EAAE,eA2ClC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAuHnC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAmDpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiErC,CAAC"}
+{"version":3,"file":"generated.command.d.ts","sourceRoot":"","sources":["../../src/commands/generated.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAkB,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAML,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0LhC;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;IAC3D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C;AAED,4DAA4D;AAC5D,UAAU,cAAc;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,sBAAsB,EAC5B,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,WAAW,EAAE,OAAO,GACnB,iBAAiB,CAqFnB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAOrE;AAwED,eAAO,MAAM,oBAAoB,EAAE,eA4DlC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAgInC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAgEpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAyGrC,CAAC"}

package/dist/commands/generated.command.js

@@ -127,16 +127,23 @@ function alignToCommitted(temp, committed) {
     }
     return out;
 }
-/** Run `regen` into a fresh temp dir and read the result back. Always cleans up. */
-function runRegen(cwd, rule, committed) {
+/**
+ * Run ONE regen command into a fresh temp dir and read the result back, keyed
+ * onto the committed paths it corresponds to. Always cleans up.
+ *
+ * `committed` is the slice this command OWNS, not the whole tree — that is what
+ * keeps a multi-writer tree honest: each command's output is aligned against
+ * (and later diffed against) only its own files, so writer A's output can never
+ * be reported as writer B's stale committed file.
+ */
+function runOneRegen(cwd, command, committed, timeoutMs) {
     const tmp = mkdtempSync(nodePath.join(nodeOs.tmpdir(), 'shrk-generated-'));
     try {
-        const command = rule.regen.split('{TMP}').join(tmp);
-        const child = spawnSync(command, {
+        const child = spawnSync(command.split('{TMP}').join(tmp), {
             cwd,
             shell: true,
             encoding: 'utf8',
-            timeout: rule.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            timeout: timeoutMs,
             maxBuffer: 16 * 1024 * 1024,
         });
         if (child.error)
@@ -155,7 +162,27 @@ function runRegen(cwd, rule, committed) {
         rmSync(tmp, { recursive: true, force: true });
     }
 }
-function evaluateRule(cwd, rule, excludeDirs, headersOnly) {
+/**
+ * The regen units for a rule: one per `sources[]` writer, or a single unit for
+ * the classic `regen` form. A rule declaring neither yields none (header-only).
+ */
+function regenUnitsOf(rule, scan) {
+    const fallback = rule.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (scan.slices.length > 0) {
+        return scan.slices.map((slice) => ({
+            label: slice.label,
+            command: slice.regen,
+            committed: slice.files,
+            timeoutMs: slice.timeoutMs ?? fallback,
+        }));
+    }
+    if (rule.regen === undefined)
+        return [];
+    // Single-writer: the checkable set, so a hand-maintained bless inside the
+    // glob is not compared against output no generator produces.
+    return [{ label: rule.id, command: rule.regen, committed: scan.checkable, timeoutMs: fallback }];
+}
+export function evaluateGeneratedRule(cwd, rule, excludeDirs, headersOnly) {
     const scan = scanGeneratedFiles(cwd, rule, excludeDirs);
     const severity = rule.severity ?? 'error';
     if (scan.generated.size === 0) {
@@ -166,10 +193,17 @@ function evaluateRule(cwd, rule, excludeDirs, headersOnly) {
             committedCount: 0,
             provenance: [],
             driftChecked: false,
+            handMaintained: [],
+            writers: [],
             skipReason: `0 files matched generatedGlob (${rule.generatedGlob.join(', ')})`,
         };
     }
-    const headers = checkProvenanceHeaders(rule, scan.generated, scan.outside);
+    // Headers + byte checks run over the CHECKABLE set — a hand-maintained bless
+    // is excluded from both, which is the whole point of declaring it.
+    const headers = checkProvenanceHeaders(rule, scan.checkable, scan.outside, {
+        unclassified: scan.unclassified,
+        staleHandMaintained: scan.staleHandMaintained,
+    });
     if (headers.error) {
         return {
             rule,
@@ -177,21 +211,39 @@ function evaluateRule(cwd, rule, excludeDirs, headersOnly) {
             committedCount: scan.generated.size,
             provenance: [],
             driftChecked: false,
+            handMaintained: scan.handMaintained,
+            writers: [],
             error: headers.error,
         };
     }
-    let treeDiff;
-    let error;
-    const wantDrift = !headersOnly && rule.regen !== undefined;
-    if (wantDrift) {
-        const regen = runRegen(cwd, rule, scan.generated);
-        if (regen.error)
-            error = regen.error;
-        else
-            treeDiff = compareGeneratedTrees(scan.generated, regen.files, rule.compare ?? 'bytes');
+    const units = headersOnly ? [] : regenUnitsOf(rule, scan);
+    const differences = [];
+    const writers = [];
+    const errors = [];
+    let committedCompared = 0;
+    let regeneratedCount = 0;
+    for (const unit of units) {
+        const regen = runOneRegen(cwd, unit.command, unit.committed, unit.timeoutMs);
+        if (regen.error) {
+            errors.push(units.length > 1 ? `${unit.label}: ${regen.error}` : regen.error);
+            writers.push({ label: unit.label, committedCount: unit.committed.size, differences: 0, error: regen.error });
+            continue;
+        }
+        const diff = compareGeneratedTrees(unit.committed, regen.files, rule.compare ?? 'bytes');
+        differences.push(...diff.differences);
+        committedCompared += diff.committedCount;
+        regeneratedCount += diff.regeneratedCount;
+        writers.push({ label: unit.label, committedCount: unit.committed.size, differences: diff.differences.length });
     }
+    const ranAnyWriter = units.length > 0 && errors.length < units.length;
+    const treeDiff = ranAnyWriter
+        ? { differences, committedCount: committedCompared, regeneratedCount }
+        : undefined;
+    const error = errors.length > 0 ? errors.join(' · ') : undefined;
     const hardFindings = headers.findings.filter((f) => f.severity === 'error');
-    const drifted = (treeDiff?.differences.length ?? 0) > 0;
+    const drifted = differences.length > 0;
+    // A writer that failed to RUN proved nothing, so the rule is in error even if
+    // its siblings were clean — a partial regen must never read as a full pass.
     const status = error !== undefined
         ? 'error'
         : drifted || (hardFindings.length > 0 && severity === 'error')
@@ -204,12 +256,14 @@ function evaluateRule(cwd, rule, excludeDirs, headersOnly) {
         ...(treeDiff ? { treeDiff } : {}),
         provenance: headers.findings,
         ...(error ? { error } : {}),
-        driftChecked: wantDrift && error === undefined,
+        driftChecked: units.length > 0 && errors.length === 0,
+        handMaintained: scan.handMaintained,
+        writers: writers.length > 1 ? writers : [],
     };
 }
-function hintFor(rule) {
+export function generatedHintFor(rule) {
     return (rule.hint ??
-        (rule.regen
+        (rule.regen || rule.sources
             ? `regenerate with \`shrk generated update --id ${rule.id}\` and commit the result`
             : 'add the provenance header to the generated file, or move it out of the generated glob'));
 }
@@ -221,11 +275,13 @@ function outcomeJson(o) {
         severity: o.rule.severity ?? 'error',
         committedCount: o.committedCount,
         driftChecked: o.driftChecked,
+        handMaintained: o.handMaintained,
+        ...(o.writers.length > 0 ? { writers: o.writers } : {}),
         ...(o.treeDiff ? { differences: o.treeDiff.differences, regeneratedCount: o.treeDiff.regeneratedCount } : {}),
         provenance: o.provenance,
         ...(o.error ? { error: o.error } : {}),
         ...(o.skipReason ? { skipReason: o.skipReason } : {}),
-        hint: hintFor(o.rule),
+        hint: generatedHintFor(o.rule),
     };
 }
 async function prepare(args) {
@@ -291,6 +347,9 @@ export const generatedListCommand = {
                     description: r.description ?? null,
                     generatedGlob: r.generatedGlob,
                     regen: r.regen ?? null,
+                    sources: r.sources ?? null,
+                    handMaintained: r.handMaintained ?? null,
+                    handMaintainedMarker: r.handMaintainedMarker ?? null,
                     compare: r.compare ?? 'bytes',
                     provenanceHeader: r.provenanceHeader ?? null,
                     failOnEmpty: r.failOnEmpty === true,
@@ -303,7 +362,22 @@ export const generatedListCommand = {
         for (const r of prep.all) {
             process.stdout.write(`  • ${r.id}\n`);
             process.stdout.write(`      glob   ${r.generatedGlob.join(', ')}\n`);
-            process.stdout.write(`      regen  ${r.regen ?? '(header-only — never spawns)'}\n`);
+            if (r.sources && r.sources.length > 0) {
+                process.stdout.write(`      regen  ${r.sources.length} writer(s):\n`);
+                r.sources.forEach((src, i) => {
+                    process.stdout.write(`               [${src.id ?? i}] ${src.regen}\n`);
+                    process.stdout.write(`                    owns ${src.glob.join(', ')}\n`);
+                });
+            }
+            else {
+                process.stdout.write(`      regen  ${r.regen ?? '(header-only — never spawns)'}\n`);
+            }
+            if (r.handMaintained && r.handMaintained.length > 0) {
+                process.stdout.write(`      hand   ${r.handMaintained.join(', ')}  (exempt from header + byte checks)\n`);
+            }
+            if (r.handMaintainedMarker) {
+                process.stdout.write(`      marker /${r.handMaintainedMarker}/  (in-file bless)\n`);
+            }
             if (r.provenanceHeader) {
                 process.stdout.write(`      header /${r.provenanceHeader.mustMatch}/${r.provenanceHeader.forbidOutside ? '  + mislabel check' : ''}\n`);
             }
@@ -328,7 +402,7 @@ export const generatedCheckCommand = {
         const headersOnly = flagBool(args, 'headers-only');
         if (prep.rules.length === 0)
             return writeNoRules(json);
-        const outcomes = prep.rules.map((r) => evaluateRule(prep.cwd, r, prep.excludeDirs, headersOnly));
+        const outcomes = prep.rules.map((r) => evaluateGeneratedRule(prep.cwd, r, prep.excludeDirs, headersOnly));
         const failed = outcomes.filter((o) => o.status === 'failed' || (o.status === 'error' && (o.rule.severity ?? 'error') === 'error'));
         const evaluated = outcomes.filter((o) => o.status !== 'skipped').length;
         const skippedCount = outcomes.length - evaluated;
@@ -361,13 +435,13 @@ export const generatedCheckCommand = {
                             id: d.file,
                             file: d.file,
                             message: d.kind,
-                            hint: hintFor(o.rule),
+                            hint: generatedHintFor(o.rule),
                         })),
                         ...o.provenance.map((f) => ({
                             id: f.file,
                             file: f.file,
                             message: f.message,
-                            hint: hintFor(o.rule),
+                            hint: generatedHintFor(o.rule),
                         })),
                     ],
                     ...(o.skipReason ? { skipReason: o.skipReason } : {}),
@@ -391,11 +465,18 @@ export const generatedCheckCommand = {
             }
             const diffs = o.treeDiff?.differences ?? [];
             if (o.status === 'passed') {
-                process.stdout.write(`  ✓ ${o.rule.id}  (${o.committedCount} files` +
+                const exempt = o.handMaintained.length > 0 ? `, ${o.handMaintained.length} hand-maintained` : '';
+                process.stdout.write(`  ✓ ${o.rule.id}  (${o.committedCount} files${exempt}` +
                     `${o.driftChecked ? ', byte-identical to a fresh regen' : ', headers only'})\n`);
+                for (const w of o.writers) {
+                    process.stdout.write(`      · ${w.label}: ${w.committedCount} file(s) verified\n`);
+                }
             }
             else {
                 process.stdout.write(`  ✗ ${o.rule.id}  ${diffs.length} file(s) differ from a fresh regen\n`);
+                for (const w of o.writers) {
+                    process.stdout.write(`      · ${w.label}: ${w.error ? `ERROR — ${w.error}` : `${w.differences} of ${w.committedCount} differ`}\n`);
+                }
                 for (const d of diffs.slice(0, 25)) {
                     const label = d.kind === 'content'
                         ? 'hand-edited (or source changed)'
@@ -414,7 +495,7 @@ export const generatedCheckCommand = {
                 process.stdout.write(`      … (${o.provenance.length - 25} more header finding(s))\n`);
             }
             if (o.status === 'failed')
-                process.stdout.write(`      → ${hintFor(o.rule)}\n`);
+                process.stdout.write(`      → ${generatedHintFor(o.rule)}\n`);
         }
         for (const d of prep.planeDiagnostics)
             process.stdout.write(`  ! ${d}\n`);
@@ -441,29 +522,41 @@ export const generatedUpdateCommand = {
             return writeNoRules(json);
         const results = [];
         for (const rule of prep.rules) {
-            if (!rule.regen) {
+            // A multi-writer rule blesses by running EVERY writer — regenerating one
+            // slice and calling the artifact updated is how a mixed tree drifts.
+            const commands = rule.sources && rule.sources.length > 0
+                ? rule.sources.map((src, i) => ({
+                    label: `${rule.id}/${src.id ?? i}`,
+                    command: src.regen,
+                    timeoutMs: src.timeoutMs ?? rule.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+                }))
+                : rule.regen
+                    ? [{ label: rule.id, command: rule.regen, timeoutMs: rule.timeoutMs ?? DEFAULT_TIMEOUT_MS }]
+                    : [];
+            if (commands.length === 0) {
                 results.push({ id: rule.id, ran: false, error: 'header-only rule — nothing to regenerate' });
                 continue;
             }
-            // `{TMP}` is the CHECK contract; `update` writes in place, so it is
-            // substituted with the project root and the regen writes its real output.
-            const command = rule.regen.split('{TMP}').join(prep.cwd);
-            const child = spawnSync(command, {
-                cwd: prep.cwd,
-                shell: true,
-                encoding: 'utf8',
-                timeout: rule.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-                maxBuffer: 16 * 1024 * 1024,
-                stdio: json ? 'pipe' : 'inherit',
-            });
-            if (child.error) {
-                results.push({ id: rule.id, ran: false, error: child.error.message });
-            }
-            else if (child.status !== 0) {
-                results.push({ id: rule.id, ran: true, error: `exited ${child.status ?? 'null'}` });
-            }
-            else {
-                results.push({ id: rule.id, ran: true });
+            for (const { label, command, timeoutMs } of commands) {
+                // `{TMP}` is the CHECK contract; `update` writes in place, so it is
+                // substituted with the project root and the regen writes its real output.
+                const child = spawnSync(command.split('{TMP}').join(prep.cwd), {
+                    cwd: prep.cwd,
+                    shell: true,
+                    encoding: 'utf8',
+                    timeout: timeoutMs,
+                    maxBuffer: 16 * 1024 * 1024,
+                    stdio: json ? 'pipe' : 'inherit',
+                });
+                if (child.error) {
+                    results.push({ id: label, ran: false, error: child.error.message });
+                }
+                else if (child.status !== 0) {
+                    results.push({ id: label, ran: true, error: `exited ${child.status ?? 'null'}` });
+                }
+                else {
+                    results.push({ id: label, ran: true });
+                }
             }
         }
         const failed = results.filter((r) => r.error !== undefined);
@@ -502,12 +595,23 @@ export const generatedExplainCommand = {
         }
         // explain never spawns — the point is to show what the rule SEES.
         const scan = scanGeneratedFiles(prep.cwd, rule, prep.excludeDirs);
-        const outcome = evaluateRule(prep.cwd, rule, prep.excludeDirs, true);
+        const outcome = evaluateGeneratedRule(prep.cwd, rule, prep.excludeDirs, true);
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson({
                 schema: 'sharkcraft.generated-explain/v1',
                 ...outcomeJson(outcome),
                 files: [...scan.generated.keys()],
+                checkable: [...scan.checkable.keys()],
+                handMaintained: scan.handMaintained,
+                markedHandMaintained: scan.markedHandMaintained,
+                staleHandMaintained: scan.staleHandMaintained,
+                unclassified: scan.unclassified,
+                slices: scan.slices.map((sl) => ({
+                    label: sl.label,
+                    regen: sl.regen,
+                    glob: sl.glob,
+                    files: [...sl.files.keys()],
+                })),
                 outsideScanned: scan.outside.size,
                 outsideGlobs: scan.outsideGlobs,
                 regen: rule.regen ?? null,
@@ -519,7 +623,34 @@ export const generatedExplainCommand = {
             process.stdout.write(`  ${rule.description}\n`);
         process.stdout.write(kv('glob', rule.generatedGlob.join(', ')) + '\n');
         process.stdout.write(kv('files matched', String(scan.generated.size)) + '\n');
-        process.stdout.write(kv('regen', rule.regen ?? '(header-only)') + '\n');
+        if (scan.slices.length > 0) {
+            process.stdout.write(kv('writers', String(scan.slices.length)) + '\n');
+            for (const sl of scan.slices) {
+                process.stdout.write(`      [${sl.label}] ${sl.files.size} file(s) — ${sl.regen}\n`);
+                process.stdout.write(`            owns ${sl.glob.join(', ')}\n`);
+            }
+        }
+        else {
+            process.stdout.write(kv('regen', rule.regen ?? '(header-only)') + '\n');
+        }
+        if (scan.handMaintained.length > 0) {
+            process.stdout.write(kv('hand-maintained', `${scan.handMaintained.length} file(s) — exempt from header + byte checks`) + '\n');
+            const marked = new Set(scan.markedHandMaintained);
+            // Say WHICH mechanism blessed each file: a config entry and an in-file
+            // marker are reviewed in different places, so "why is this exempt?" has
+            // two different answers and the reader needs to know which one applies.
+            for (const f of scan.handMaintained.slice(0, 20)) {
+                process.stdout.write(`      ${f}${marked.has(f) ? '  (in-file marker)' : '  (handMaintained[])'}\n`);
+            }
+        }
+        if (scan.unclassified.length > 0) {
+            process.stdout.write(kv('unclassified', `${scan.unclassified.length} file(s) — owned by no writer, not blessed`) + '\n');
+            for (const f of scan.unclassified.slice(0, 20))
+                process.stdout.write(`      ${f}\n`);
+        }
+        for (const pattern of scan.staleHandMaintained) {
+            process.stdout.write(`  ! handMaintained "${pattern}" matches no file — stale bless\n`);
+        }
         process.stdout.write(kv('compare', rule.compare ?? 'bytes') + '\n');
         if (rule.provenanceHeader) {
             process.stdout.write(kv('header', `/${rule.provenanceHeader.mustMatch}/`) + '\n');

package/dist/commands/graph-code-subverbs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-code-subverbs.d.ts","sourceRoot":"","sources":["../../src/commands/graph-code-subverbs.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAiE,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAgLxH,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBrE;AA4FD,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkFtE;AAiBD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA2F1E;AAID,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+EpE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+FtE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAwEtE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA2MvE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+HtE;AAID;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgEpE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAiGvE;AAyBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgHpE"}
+{"version":3,"file":"graph-code-subverbs.d.ts","sourceRoot":"","sources":["../../src/commands/graph-code-subverbs.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAiE,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAgLxH,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBrE;AA4FD,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkFtE;AAiBD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA2F1E;AAID,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+EpE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAmGtE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAwEtE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA2MvE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+HtE;AAID;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgEpE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAiGvE;AAyBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgHpE"}

package/dist/commands/graph-code-subverbs.js

@@ -594,7 +594,11 @@ export async function runGraphStatus(args) {
     }
     process.stdout.write(header('Graph status'));
     process.stdout.write(kv('schema', payload.schema) + '\n');
-    process.stdout.write(kv('files', String(payload.fileCount)) + '\n');
+    // "files indexed", not "files": this is the size of the STORED snapshot, and
+    // it deliberately does not move when a new file appears on disk — that shows
+    // up on the `drift` line below. Reading it as a live count is how an added
+    // file looks invisible to the index.
+    process.stdout.write(kv('files indexed', String(payload.fileCount)) + '\n');
     process.stdout.write(kv('nodes', String(payload.nodeCount)) + '\n');
     process.stdout.write(kv('edges', String(payload.edgeCount)) + '\n');
     process.stdout.write(kv('packages', String(payload.workspacePackages.length)) + '\n');

package/dist/commands/wiring.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wiring.command.d.ts","sourceRoot":"","sources":["../../src/commands/wiring.command.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAoFrF;AAyZD,eAAO,MAAM,aAAa,EAAE,eAgB3B,CAAC"}
+{"version":3,"file":"wiring.command.d.ts","sourceRoot":"","sources":["../../src/commands/wiring.command.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAwFrF;AAyZD,eAAO,MAAM,aAAa,EAAE,eAgB3B,CAAC"}

package/dist/commands/wiring.command.js

@@ -28,9 +28,10 @@ export function renderWiringExplain(report, wantJson) {
         process.stdout.write(kv('registeredMode', 'intersection (must be in EVERY sink)') + '\n');
     }
     process.stdout.write(kv('status', report.status) + '\n');
-    process.stdout.write(kv('declared', `${report.declared.distinctCount} distinct across ${report.declared.filesScanned} file(s)`) +
-        '\n');
-    process.stdout.write(kv('registered', `${report.registered.distinctCount} distinct across ${report.registered.filesScanned} file(s)`) + '\n');
+    process.stdout.write(kv('declared', `${report.declared.distinctCount} distinct across ${report.declared.filesScanned} file(s)` +
+        (report.declared.viaExtractor ? `  (via $use:${report.declared.viaExtractor})` : '')) + '\n');
+    process.stdout.write(kv('registered', `${report.registered.distinctCount} distinct across ${report.registered.filesScanned} file(s)` +
+        (report.registered.viaExtractor ? `  (via $use:${report.registered.viaExtractor})` : '')) + '\n');
     if (report.declared.error)
         process.stdout.write(`  ! declared side: ${report.declared.error}\n`);
     if (report.registered.error) {

package/dist/gates/gate-envelope.d.ts

@@ -13,7 +13,7 @@
  */
 export declare const GATE_ENVELOPE_SCHEMA: "sharkcraft.gate/v1";
 /** Which data-defined plane produced a rule result. */
-export type GateRuleType = 'wiring' | 'policy' | 'registry' | 'registration' | 'baseline' | 'generated';
+export type GateRuleType = 'wiring' | 'policy' | 'registry' | 'registration' | 'baseline' | 'generated' | 'doc-reference';
 /**
  * Per-rule outcome, uniform across planes. `skipped` is deliberately a
  * first-class status, not folded into `passed` — a rule that matched nothing

package/dist/gates/gate-envelope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate-envelope.d.ts","sourceRoot":"","sources":["../../src/gates/gate-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,EAAG,oBAA6B,CAAC;AAElE,uDAAuD;AACvD,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,cAAc,GACd,UAAU,GACV,WAAW,CAAC;AAEhB;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEvE,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,UAAU,EAAE,SAAS,cAAc,EAAE,CAAC;IAC/C,gEAAgE;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,oBAAoB,CAAC;IAC7C,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAC3C,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,eAAe,EAAE,GAChC,aAAa,CAUf"}
+{"version":3,"file":"gate-envelope.d.ts","sourceRoot":"","sources":["../../src/gates/gate-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,EAAG,oBAA6B,CAAC;AAElE,uDAAuD;AACvD,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,cAAc,GACd,UAAU,GACV,WAAW,GACX,eAAe,CAAC;AAEpB;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEvE,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,UAAU,EAAE,SAAS,cAAc,EAAE,CAAC;IAC/C,gEAAgE;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,oBAAoB,CAAC;IAC7C,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAC3C,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,eAAe,EAAE,GAChC,aAAa,CAUf"}

package/dist/gates/gate-rule-globs.d.ts

@@ -0,0 +1,33 @@
+import { type IWiringSource } from '@shrkcrft/core';
+import type { IGateRuleView } from './gate-rule-view.js';
+/**
+ * The FOOTPRINT of a gate rule: every project-relative glob it reads.
+ *
+ * `--changed-only` is only trustworthy if the footprint is complete. A rule
+ * scoped by its declared side alone would go unevaluated when the change edits
+ * the REGISTERED side — a registration deleted in file B silently skipping the
+ * rule declared over file A is the precise bug this plane exists to catch, so
+ * every side, every hop, and every watched input counts.
+ */
+export declare function gateRuleGlobs(view: IGateRuleView): readonly string[];
+/**
+ * EVERY extraction source a rule reads — both wiring sides, every union sink,
+ * every chain hop, a registry's consumer, all three registration roles.
+ *
+ * Collecting all of them (not just the rule's primary side) is what lets the
+ * coverage view name every consumer of a shared extractor. A rule that `$use`s
+ * one on its *registered* side is just as bound to that definition as one that
+ * uses it on `declared`, and listing only half of them would understate exactly
+ * the guarantee the shared extractor exists to provide.
+ */
+export declare function gateRuleSources(view: IGateRuleView): readonly IWiringSource[];
+/**
+ * Whether a rule's footprint intersects the changed set.
+ *
+ * A rule with NO resolvable footprint (a command baseline with no
+ * `watchFiles`) cannot be proven out of scope, so it stays IN scope. Guessing
+ * "probably unaffected" is how a `--changed-only` run silently stops checking
+ * the one thing that broke.
+ */
+export declare function ruleTouchedBy(view: IGateRuleView, changed: readonly string[]): boolean;
+//# sourceMappingURL=gate-rule-globs.d.ts.map

package/dist/gates/gate-rule-globs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-rule-globs.d.ts","sourceRoot":"","sources":["../../src/gates/gate-rule-globs.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,MAAM,EAAE,CAqBpE;AAcD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,aAAa,EAAE,CA+B7E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAItF"}

package/dist/gates/gate-rule-globs.js

@@ -0,0 +1,101 @@
+import { resolveSourceGlobs, } from '@shrkcrft/core';
+import { matchesAny } from '@shrkcrft/boundaries';
+/**
+ * The FOOTPRINT of a gate rule: every project-relative glob it reads.
+ *
+ * `--changed-only` is only trustworthy if the footprint is complete. A rule
+ * scoped by its declared side alone would go unevaluated when the change edits
+ * the REGISTERED side — a registration deleted in file B silently skipping the
+ * rule declared over file A is the precise bug this plane exists to catch, so
+ * every side, every hop, and every watched input counts.
+ */
+export function gateRuleGlobs(view) {
+    if (view.plane === 'policy')
+        return view.raw.files ?? [];
+    if (view.plane === 'baseline') {
+        const rule = view.raw;
+        // `watchFiles` is the ONLY footprint a command compute has — without it a
+        // command baseline can never be scoped, so it always runs (see below).
+        return [
+            ...gateRuleSources(view).flatMap(sourceGlobs),
+            ...(rule.watchFiles ?? []),
+            rule.baseline,
+        ];
+    }
+    if (view.plane === 'generated') {
+        const rule = view.raw;
+        return [
+            ...rule.generatedGlob,
+            ...(rule.sources ?? []).flatMap((s) => s.glob),
+            ...(rule.handMaintained ?? []),
+        ];
+    }
+    return gateRuleSources(view).flatMap(sourceGlobs);
+}
+/**
+ * Every glob one source reads: the files it scans, plus an `import-edges`
+ * source's TARGET globs.
+ *
+ * A fence whose footprint covered only the consumer side would go unevaluated
+ * when the target subtree moved — and "cannot be proven out of scope" must
+ * always resolve to staying IN scope, never to a quiet skip.
+ */
+function sourceGlobs(src) {
+    return [...resolveSourceGlobs(src), ...(src.to?.files ?? [])];
+}
+/**
+ * EVERY extraction source a rule reads — both wiring sides, every union sink,
+ * every chain hop, a registry's consumer, all three registration roles.
+ *
+ * Collecting all of them (not just the rule's primary side) is what lets the
+ * coverage view name every consumer of a shared extractor. A rule that `$use`s
+ * one on its *registered* side is just as bound to that definition as one that
+ * uses it on `declared`, and listing only half of them would understate exactly
+ * the guarantee the shared extractor exists to provide.
+ */
+export function gateRuleSources(view) {
+    switch (view.plane) {
+        case 'wiring': {
+            const rule = view.raw;
+            return [
+                rule.declared,
+                ...(Array.isArray(rule.registered)
+                    ? rule.registered
+                    : rule.registered
+                        ? [rule.registered]
+                        : []),
+                ...(rule.chain ?? []),
+            ].filter((s) => s !== undefined);
+        }
+        case 'registry': {
+            const decl = view.raw;
+            return decl.consumer ? [decl.source, decl.consumer] : [decl.source];
+        }
+        case 'registration': {
+            const idiom = view.raw;
+            return [idiom.declared, idiom.provided, idiom.consumed];
+        }
+        case 'baseline': {
+            const source = view.raw.compute.source;
+            return source ? [source] : [];
+        }
+        default:
+            // `policy` and `generated` select files by glob, not by an extraction
+            // source, so neither can reference a shared extractor.
+            return [];
+    }
+}
+/**
+ * Whether a rule's footprint intersects the changed set.
+ *
+ * A rule with NO resolvable footprint (a command baseline with no
+ * `watchFiles`) cannot be proven out of scope, so it stays IN scope. Guessing
+ * "probably unaffected" is how a `--changed-only` run silently stops checking
+ * the one thing that broke.
+ */
+export function ruleTouchedBy(view, changed) {
+    const globs = gateRuleGlobs(view).filter((g) => g.length > 0);
+    if (globs.length === 0)
+        return true;
+    return changed.some((file) => matchesAny(file, globs));
+}