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

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

@@ -1,6 +1,6 @@
-import { type IBaselineRule, type IGeneratedArtifactRule, type IPolicyRule, type IRegistrationIdiom, type IRegistryDeclaration, type IRuleSelfTest, type IWiringRule } from '@shrkcrft/core';
+import { type IBaselineRule, type IDocReferenceRule, type IGeneratedArtifactRule, type IPolicyRule, type IRegistrationIdiom, type IRegistryDeclaration, type IRuleSelfTest, type IWiringRule } from '@shrkcrft/core';
 /** Which data-defined plane a rule belongs to. */
-export type GatePlane = 'wiring' | 'policy' | 'registry' | 'registration' | 'baseline' | 'generated';
+export type GatePlane = 'wiring' | 'policy' | 'registry' | 'registration' | 'baseline' | 'generated' | 'doc-reference';
 /** Every plane, in the order `shrk gates list` prints them. */
 export declare const GATE_PLANES: readonly GatePlane[];
 /**
@@ -17,9 +17,14 @@ export interface IGateRuleView {
     readonly severity: 'error' | 'warning';
     /** True when a zero-match is a hard failure rather than a loud skip. */
     readonly failOnEmpty: boolean;
+    /**
+     * True when an EMPTY result is the rule's passing state (a fence). The
+     * loud-skip contract is inverted for these, and only for these.
+     */
+    readonly expectEmpty?: boolean;
     readonly selfTest?: IRuleSelfTest;
     /** The underlying rule, for the plane-specific explainer. */
-    readonly raw: IWiringRule | IPolicyRule | IRegistryDeclaration | IRegistrationIdiom | IBaselineRule | IGeneratedArtifactRule;
+    readonly raw: IWiringRule | IPolicyRule | IRegistryDeclaration | IRegistrationIdiom | IBaselineRule | IGeneratedArtifactRule | IDocReferenceRule;
 }
 /** The config planes this view is built from. */
 export interface IGatePlanes {
@@ -29,6 +34,7 @@ export interface IGatePlanes {
     readonly registrationGraph?: readonly IRegistrationIdiom[];
     readonly baselines?: readonly IBaselineRule[];
     readonly generatedArtifacts?: readonly IGeneratedArtifactRule[];
+    readonly docReferences?: readonly IDocReferenceRule[];
 }
 /** Flatten every declared rule across every plane into one iterable list. */
 export declare function collectGateRules(planes: IGatePlanes): IGateRuleView[];

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

@@ -1 +1 @@
-{"version":3,"file":"gate-rule-view.d.ts","sourceRoot":"","sources":["../../src/gates/gate-rule-view.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,gBAAgB,CAAC;AAExB,kDAAkD;AAClD,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,cAAc,GAAG,UAAU,GAAG,WAAW,CAAC;AAErG,+DAA+D;AAC/D,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAO3C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,EACR,WAAW,GACX,WAAW,GACX,oBAAoB,GACpB,kBAAkB,GAClB,aAAa,GACb,sBAAsB,CAAC;CAC5B;AAED,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9C,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACtD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC3D,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACjE;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,EAAE,CAqErE"}
+{"version":3,"file":"gate-rule-view.d.ts","sourceRoot":"","sources":["../../src/gates/gate-rule-view.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,gBAAgB,CAAC;AAExB,kDAAkD;AAClD,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,cAAc,GACd,UAAU,GACV,WAAW,GACX,eAAe,CAAC;AAEpB,+DAA+D;AAC/D,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAQ3C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,EACR,WAAW,GACX,WAAW,GACX,oBAAoB,GACpB,kBAAkB,GAClB,aAAa,GACb,sBAAsB,GACtB,iBAAiB,CAAC;CACvB;AAED,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9C,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACtD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC3D,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACvD;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,EAAE,CAiFrE"}

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

@@ -7,6 +7,7 @@ export const GATE_PLANES = [
     'registration',
     'baseline',
     'generated',
+    'doc-reference',
 ];
 /** Flatten every declared rule across every plane into one iterable list. */
 export function collectGateRules(planes) {
@@ -62,6 +63,18 @@ export function collectGateRules(planes) {
             ...(r.description ? { description: r.description } : {}),
             severity: r.severity ?? 'error',
             failOnEmpty: failsWhenEmpty(r),
+            ...(r.expectEmpty === true ? { expectEmpty: true } : {}),
+            ...(r.selfTest ? { selfTest: r.selfTest } : {}),
+            raw: r,
+        });
+    }
+    for (const r of planes.docReferences ?? []) {
+        out.push({
+            id: r.id,
+            plane: 'doc-reference',
+            ...(r.description ? { description: r.description } : {}),
+            severity: r.severity ?? 'error',
+            failOnEmpty: failsWhenEmpty(r),
             ...(r.selfTest ? { selfTest: r.selfTest } : {}),
             raw: r,
         });

package/dist/gates/rule-coverage.d.ts

@@ -1,3 +1,5 @@
+import type { IWiringSource } from '@shrkcrft/core';
+import { type ISharkcraftInspection } from '@shrkcrft/inspector';
 import type { IGateRuleView } from './gate-rule-view.js';
 export declare const GATE_COVERAGE_SCHEMA: "sharkcraft.gate-coverage/v1";
 /**
@@ -23,11 +25,45 @@ export interface IGateCoverage {
     readonly unitLabel: string;
     /** A few of the extracted ids, so the author can eyeball correctness. */
     readonly sampleIds: readonly string[];
+    /**
+     * Every extracted id. Populated only when the caller asks (`includeAllIds`),
+     * because a full set on every rule would bloat `gates coverage --json` for a
+     * fact almost no consumer of it needs — `gates try --full` does.
+     */
+    readonly allIds?: readonly string[];
     /** True when a zero match is a hard failure for this rule. */
     readonly failOnEmpty: boolean;
     readonly error?: string;
+    /**
+     * A diagnosis for a zero-match that is correct but probably not intended —
+     * e.g. an `import-edges` rule targeting `to.files` against barrel imports.
+     */
+    readonly hint?: string;
     /** Unmet `selfTest` expectations, each a human-readable sentence. */
     readonly expectationFailures: readonly string[];
+    /**
+     * Named extractor this rule's primary selector came from. Present only for a
+     * `$use` consumer — the answer to "is this rule looking at the shared set, or
+     * a copy of it that has since drifted?".
+     */
+    readonly viaExtractor?: string;
+}
+/**
+ * One named extractor, reported ONCE with the rules that share it.
+ *
+ * The point of a shared extractor is that its consumers cannot disagree about
+ * which set they check. Reporting it once — with its match count and its
+ * consumer list — makes that guarantee visible: one line proves N rules are
+ * pointed at the same, live, non-empty set.
+ */
+export interface ISharedExtractorCoverage {
+    readonly id: string;
+    /** Rule ids (plane-qualified) that resolve their primary selector from it. */
+    readonly consumers: readonly string[];
+    readonly filesMatched: number;
+    readonly idsMatched: number;
+    readonly sampleIds: readonly string[];
+    readonly error?: string;
 }
 export interface IGateCoverageReport {
     readonly schema: typeof GATE_COVERAGE_SCHEMA;
@@ -36,6 +72,8 @@ export interface IGateCoverageReport {
     readonly empty: number;
     readonly errored: number;
     readonly expectationFailures: number;
+    /** Named extractors referenced by at least one rule, each reported once. */
+    readonly extractors: readonly ISharedExtractorCoverage[];
     /**
      * `pass` — every rule matched something and met its expectations.
      * `stale` — at least one rule matched nothing (or broke an expectation).
@@ -49,5 +87,5 @@ export interface IGateCoverageReport {
  * without side effects; it is reported as un-inspected (never as `empty`), so
  * the report never claims a fact it did not check.
  */
-export declare function buildGateCoverage(cwd: string, rules: readonly IGateRuleView[], excludeDirs?: readonly string[]): IGateCoverageReport;
+export declare function buildGateCoverage(cwd: string, rules: readonly IGateRuleView[], excludeDirs?: readonly string[], extractors?: Readonly<Record<string, IWiringSource>>, includeAllIds?: boolean, inspection?: ISharkcraftInspection): IGateCoverageReport;
 //# sourceMappingURL=rule-coverage.d.ts.map

package/dist/gates/rule-coverage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule-coverage.d.ts","sourceRoot":"","sources":["../../src/gates/rule-coverage.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,eAAO,MAAM,oBAAoB,EAAG,6BAAsC,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,OAAO,GAAG,OAAO,GAAG,oBAAoB,CAAC;AAEjF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,iDAAiD;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,oBAAoB,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACpC;AAsHD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,mBAAmB,CA4DrB"}
+{"version":3,"file":"rule-coverage.d.ts","sourceRoot":"","sources":["../../src/gates/rule-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAQV,aAAa,EAEd,MAAM,gBAAgB,CAAC;AAWxB,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,eAAO,MAAM,oBAAoB,EAAG,6BAAsC,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,OAAO,GAAG,OAAO,GAAG,oBAAoB,CAAC;AAEjF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,iDAAiD;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,oBAAoB,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACzD;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACpC;AAyKD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,WAAW,GAAE,SAAS,MAAM,EAAO,EACnC,UAAU,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAM,EACxD,aAAa,UAAQ,EACrB,UAAU,CAAC,EAAE,qBAAqB,GACjC,mBAAmB,CAOrB"}

package/dist/gates/rule-coverage.js

@@ -1,4 +1,7 @@
-import { inspectSource, runPolicyLint, scanGeneratedFiles, wiringSourceSide, } from '@shrkcrft/boundaries';
+import { referencedExtractorIds } from '@shrkcrft/core';
+import { inspectSource, runPolicyLint, scanGeneratedFiles, walkMatching, withFileReadCache, wiringSourceSide, } from '@shrkcrft/boundaries';
+import { gateRuleSources } from "./gate-rule-globs.js";
+import { checkDocReferences } from '@shrkcrft/inspector';
 export const GATE_COVERAGE_SCHEMA = 'sharkcraft.gate-coverage/v1';
 /** Evaluate the author's declared expectations against what the rule extracted. */
 function checkExpectations(selfTest, ids, unitsMatched) {
@@ -30,7 +33,9 @@ function matchWiring(cwd, rule, excludeDirs) {
         unitsMatched: insp.ids.length,
         unitLabel: 'ids',
         ids: insp.ids,
+        ...(side.$use ? { viaExtractor: side.$use } : {}),
         ...(insp.error ? { error: insp.error } : {}),
+        ...(insp.hint ? { hint: insp.hint } : {}),
     };
 }
 function matchPolicy(cwd, rule, excludeDirs) {
@@ -52,7 +57,9 @@ function matchRegistry(cwd, decl, excludeDirs) {
         unitsMatched: insp.ids.length,
         unitLabel: 'ids',
         ids: insp.ids,
+        ...(decl.source.$use ? { viaExtractor: decl.source.$use } : {}),
         ...(insp.error ? { error: insp.error } : {}),
+        ...(insp.hint ? { hint: insp.hint } : {}),
     };
 }
 function matchRegistration(cwd, idiom, excludeDirs) {
@@ -62,7 +69,9 @@ function matchRegistration(cwd, idiom, excludeDirs) {
         unitsMatched: insp.ids.length,
         unitLabel: 'declared tokens',
         ids: insp.ids,
+        ...(idiom.declared.$use ? { viaExtractor: idiom.declared.$use } : {}),
         ...(insp.error ? { error: insp.error } : {}),
+        ...(insp.hint ? { hint: insp.hint } : {}),
     };
 }
 function matchBaseline(cwd, rule, excludeDirs) {
@@ -70,11 +79,28 @@ function matchBaseline(cwd, rule, excludeDirs) {
     // compute is reported honestly as un-inspectable rather than guessed at —
     // `shrk baseline explain --id X` runs it on purpose.
     if (rule.compute.kind !== 'extractor' || !rule.compute.source) {
+        // ...but its INPUTS can still be probed. `watchFiles` names the files that
+        // feed the command, so globbing them (never spawning) answers the one
+        // question the trust layer otherwise cannot: is this rule still connected
+        // to the repo at all? A command baseline whose watchFiles point at a moved
+        // directory is indistinguishable from a healthy one without this.
+        const watch = rule.watchFiles ?? [];
+        if (watch.length === 0) {
+            return {
+                filesMatched: 0,
+                unitsMatched: 0,
+                unitLabel: 'entries (command compute — not inspected; add `watchFiles` to enable the probe)',
+                ids: [],
+            };
+        }
+        const probed = walkMatching(cwd, watch, new Set(excludeDirs));
         return {
-            filesMatched: 0,
-            unitsMatched: 0,
-            unitLabel: 'entries (command compute — not inspected)',
-            ids: [],
+            filesMatched: probed.length,
+            unitsMatched: probed.length,
+            // A zero here is a REAL empty (stale watchFiles), so the label must not
+            // carry the "not inspected" marker that suppresses the empty verdict.
+            unitLabel: 'watchFiles input(s) (compute unverified — command never run)',
+            ids: probed.slice(0, 5),
         };
     }
     const insp = inspectSource(cwd, rule.compute.source, excludeDirs);
@@ -83,7 +109,26 @@ function matchBaseline(cwd, rule, excludeDirs) {
         unitsMatched: insp.ids.length,
         unitLabel: 'entries',
         ids: insp.ids,
+        ...(rule.compute.source.$use ? { viaExtractor: rule.compute.source.$use } : {}),
         ...(insp.error ? { error: insp.error } : {}),
+        ...(insp.hint ? { hint: insp.hint } : {}),
+    };
+}
+/**
+ * A doc-reference rule's "match" is how many id-shaped TOKENS it validated.
+ *
+ * Files alone would lie: a rule whose globs match 40 docs but whose
+ * `requireContext` gate rejects every token is enforcing nothing, and coverage
+ * exists precisely to make that visible.
+ */
+function matchDocReference(cwd, rule, inspection, excludeDirs) {
+    const res = checkDocReferences(cwd, rule, inspection, excludeDirs);
+    return {
+        filesMatched: res.filesScanned,
+        unitsMatched: res.tokensChecked,
+        unitLabel: 'doc reference(s)',
+        ids: [...new Set(res.tokens.filter((t) => t.skipped === undefined).map((t) => t.token))].sort(),
+        ...(res.error ? { error: res.error } : {}),
     };
 }
 function matchGenerated(cwd, rule, excludeDirs) {
@@ -103,7 +148,13 @@ function matchGenerated(cwd, rule, excludeDirs) {
  * without side effects; it is reported as un-inspected (never as `empty`), so
  * the report never claims a fact it did not check.
  */
-export function buildGateCoverage(cwd, rules, excludeDirs = []) {
+export function buildGateCoverage(cwd, rules, excludeDirs = [], extractors = {}, includeAllIds = false, inspection) {
+    // Safe to memo the tree reads for exactly this call: coverage NEVER spawns
+    // (the `command` baseline is probed, not run) and never writes, so nothing
+    // can change the tree between the first rule's scan and the last one's.
+    return withFileReadCache(() => buildGateCoverageUncached(cwd, rules, excludeDirs, extractors, includeAllIds, inspection));
+}
+function buildGateCoverageUncached(cwd, rules, excludeDirs, extractors, includeAllIds, inspection) {
     const out = [];
     for (const view of rules) {
         let match;
@@ -123,17 +174,33 @@ export function buildGateCoverage(cwd, rules, excludeDirs = []) {
             case 'baseline':
                 match = matchBaseline(cwd, view.raw, excludeDirs);
                 break;
+            case 'doc-reference':
+                // The inspection is only built when this plane is actually present, so
+                // a repo without it never pays for the registries.
+                match = inspection
+                    ? matchDocReference(cwd, view.raw, inspection, excludeDirs)
+                    : {
+                        filesMatched: 0,
+                        unitsMatched: 0,
+                        unitLabel: 'doc reference(s) (registries not loaded — not inspected)',
+                        ids: [],
+                    };
+                break;
             default:
                 match = matchGenerated(cwd, view.raw, excludeDirs);
                 break;
         }
         const expectationFailures = checkExpectations(view.selfTest, match.ids, match.unitsMatched);
         const uninspected = match.unitLabel.includes('not inspected');
+        // A FENCE asserts emptiness, so for it a zero match is the verified state,
+        // not a stale-selector suspect. Without this the rule is permanently red in
+        // `gates coverage` and could never be part of a green CI.
+        const emptyIsExpected = view.expectEmpty === true && match.unitsMatched === 0;
         const status = match.error !== undefined
             ? 'error'
             : expectationFailures.length > 0
                 ? 'failed-expectation'
-                : match.unitsMatched === 0 && !uninspected
+                : match.unitsMatched === 0 && !uninspected && !emptyIsExpected
                     ? 'empty'
                     : 'ok';
         out.push({
@@ -143,13 +210,60 @@ export function buildGateCoverage(cwd, rules, excludeDirs = []) {
             status,
             filesMatched: match.filesMatched,
             unitsMatched: match.unitsMatched,
-            unitLabel: match.unitLabel,
+            unitLabel: emptyIsExpected ? `${match.unitLabel} (empty — the asserted state)` : match.unitLabel,
             sampleIds: match.ids.slice(0, 5),
+            ...(includeAllIds ? { allIds: match.ids } : {}),
             failOnEmpty: view.failOnEmpty,
             ...(match.error ? { error: match.error } : {}),
+            ...(match.hint ? { hint: match.hint } : {}),
+            ...(match.viaExtractor ? { viaExtractor: match.viaExtractor } : {}),
             expectationFailures,
         });
     }
+    // Report each SHARED extractor once, with the rules that consume it. One
+    // resolve per extractor, not per consumer — the shared definition is a single
+    // fact about the tree, and stating it N times would invite the reader to
+    // treat N agreeing consumers as N independent confirmations.
+    //
+    // Consumers are collected from EVERY side of every rule, not just the side
+    // coverage happens to inspect: a rule bound to the extractor through its
+    // `registered` sink is every bit as bound as one using it for `declared`, and
+    // listing half of them would understate the guarantee.
+    const consumersByExtractor = new Map();
+    for (const view of rules) {
+        const label = `${view.plane}:${view.id}`;
+        for (const id of referencedExtractorIds(gateRuleSources(view))) {
+            const list = consumersByExtractor.get(id) ?? [];
+            if (!list.includes(label))
+                list.push(label);
+            consumersByExtractor.set(id, list);
+        }
+    }
+    const extractorCoverage = [...consumersByExtractor.keys()]
+        .sort()
+        .map((id) => {
+        const definition = extractors[id];
+        if (!definition) {
+            return {
+                id,
+                consumers: consumersByExtractor.get(id),
+                filesMatched: 0,
+                idsMatched: 0,
+                sampleIds: [],
+                error: 'referenced but not declared in `extractors`',
+            };
+        }
+        const insp = inspectSource(cwd, definition, excludeDirs);
+        return {
+            id,
+            consumers: consumersByExtractor.get(id),
+            filesMatched: insp.filesScanned,
+            idsMatched: insp.ids.length,
+            sampleIds: insp.ids.slice(0, 5),
+            ...(insp.error ? { error: insp.error } : {}),
+            ...(insp.hint ? { hint: insp.hint } : {}),
+        };
+    });
     const empty = out.filter((r) => r.status === 'empty').length;
     const errored = out.filter((r) => r.status === 'error').length;
     const expectationFailures = out.filter((r) => r.status === 'failed-expectation').length;
@@ -160,6 +274,7 @@ export function buildGateCoverage(cwd, rules, excludeDirs = []) {
         empty,
         errored,
         expectationFailures,
+        extractors: extractorCoverage,
         verdict: empty + errored + expectationFailures > 0 ? 'stale' : 'pass',
     };
 }

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

@@ -0,0 +1,44 @@
+import { type ISharkcraftInspection } from '@shrkcrft/inspector';
+import type { IGateRuleResult } from './gate-envelope.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.
+ */
+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[];
+}
+/** 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":"AACA,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAsBrF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAa,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpE;;;;;;;;;;GAUG;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;CACzC;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,OAAO,EAAE,qBAAqB,GAC7B,aAAa,CAef"}