@shrkcrft/cli 0.1.0-alpha.26 → 0.1.0-alpha.28

package/dist/finish/run-finish.js

@@ -1,9 +1,23 @@
-import { buildImportHygieneReport, filterViolationsToChangedScope, inspectSharkcraft, resolveChangedFiles, resolveProjectConfig, } from '@shrkcrft/inspector';
+import { buildImportHygieneReport, filterViolationsToChangedScope, gitShowFile, inspectSharkcraft, resolveChangedFiles, resolveProjectConfig, } from '@shrkcrft/inspector';
 import { existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { evaluateBoundaries, loadTsconfigPaths, runPolicyLint, runWiring, scanImports, } from '@shrkcrft/boundaries';
+import { buildRegistrationGraph, evaluateBoundaries, loadTsconfigPaths, providedTokensFromEntries, registrationTouchesChanged, registrationUnprovided, runPolicyLint, runWiring, scanImports, } from '@shrkcrft/boundaries';
 import { computeDeletedOrphans } from "../diff/deleted-orphans.js";
+import { ExitCode } from "../exit-codes.js";
 export const FINISH_SCHEMA = 'sharkcraft.finish/v1';
+/** Files in the boundary/import/wiring domain — a change outside it evaluates nothing there. */
+const CODE_FILE = /\.(?:m|c)?[jt]sx?$/;
+function codeFilesOf(files) {
+    return files.filter((f) => CODE_FILE.test(f));
+}
+/** The base ref the unprovided gate diffs against to spot removed providers. */
+function baseRefFor(input) {
+    if (input.mode === 'files')
+        return undefined; // an explicit file list has no diff base
+    if (input.mode === 'since' && input.scope.since)
+        return input.scope.since;
+    return 'HEAD'; // worktree + staged both diff vs HEAD
+}
 /** Map the changed-scope onto the orphan check's diff inputs. */
 function orphanOptsFor(input) {
     if (input.mode === 'files')
@@ -29,6 +43,11 @@ export async function runFinishGates(input) {
     const { cwd } = input;
     const changed = resolveChangedFiles(input.scope);
     const changedFiles = changed.files;
+    // The boundary/import/wiring engines only reason about code files. A change to
+    // non-code files (docs, JSON, config) evaluates NOTHING in those gates, so they
+    // must SKIP, not trivially pass — otherwise a markdown-only change paints green
+    // ("evaluated nothing" must read as not-verified, never a `0`).
+    const codeChanged = codeFilesOf(changedFiles);
     const gates = [];
     // ── boundaries (changed-only) ────────────────────────────────────────
     const inspection = await inspectSharkcraft({ cwd });
@@ -36,8 +55,8 @@ export async function runFinishGates(input) {
     if (boundaryRules.length === 0) {
         gates.push(skip('boundaries', 'no boundary rules configured'));
     }
-    else if (changedFiles.length === 0) {
-        gates.push(skip('boundaries', 'no files in changed scope'));
+    else if (codeChanged.length === 0) {
+        gates.push(skip('boundaries', 'no code files in changed scope'));
     }
     else {
         const scan = scanImports({ projectRoot: cwd });
@@ -62,23 +81,29 @@ export async function runFinishGates(input) {
         });
     }
     // ── import hygiene (changed-only) ────────────────────────────────────
-    if (changedFiles.length === 0) {
-        gates.push(skip('imports', 'no files in changed scope'));
+    if (codeChanged.length === 0) {
+        gates.push(skip('imports', 'no code files in changed scope'));
     }
     else {
-        const report = buildImportHygieneReport(cwd, { files: changedFiles });
+        const report = buildImportHygieneReport(cwd, { files: codeChanged });
         const errors = report.counts?.['error'] ?? (report.verdict === 'errors' ? report.findings.length : 0);
         const warnings = report.counts?.['warning'] ?? (report.verdict === 'warnings' ? report.findings.length : 0);
+        // Only the findings that actually DRIVE the verdict become "failing items".
+        // An allowlisted import is downgraded to `info` by design and is not what
+        // failed — listing it anyway pads the renderer's 15-item cap and can push a
+        // real error out of view, while its allowlist justification reads like a
+        // fix instruction. A fix-list that names non-failures is not a fix-list.
+        const driving = report.findings.filter((f) => report.verdict === 'errors' ? f.severity === 'error' : f.severity === 'warning');
         gates.push({
             name: 'imports',
             status: report.verdict === 'errors' ? 'fail' : 'pass',
-            detail: `verdict=${report.verdict} (${report.findings.length} finding(s))`,
+            detail: `verdict=${report.verdict} (${driving.length} of ${report.findings.length} finding(s) drive it)`,
             errors,
             warnings,
-            items: report.findings.map((f) => ({
+            items: driving.map((f) => ({
                 file: f.file,
                 line: f.line,
-                message: `${f.kind}: ${f.suggestedFix || f.reason || f.snippet}`.trim(),
+                message: `[${f.severity}] ${f.kind}: ${f.suggestedFix || f.reason || f.snippet}`.trim(),
             })),
         });
     }
@@ -96,34 +121,61 @@ export async function runFinishGates(input) {
             ? `config did not load: ${loaded.error.message}`
             : 'no sharkcraft config (gate not applicable)';
         gates.push(skip('wiring', detail));
+        gates.push(skip('unprovided', detail));
         gates.push(skip('policy', detail));
     }
     else {
-        gates.push(wiringGate(cwd, loaded.value.config.wiringRules ?? [], changedFiles), policyGate(cwd, loaded.value.config.policyRules ?? [], changedFiles));
+        gates.push(wiringGate(cwd, loaded.value.config.wiringRules ?? [], changedFiles), unprovidedGate(cwd, loaded.value.config.registrationGraph ?? [], changedFiles, baseRefFor(input)), policyGate(cwd, loaded.value.config.policyRules ?? [], changedFiles));
     }
     // ── deleted-orphans (write-safety) ───────────────────────────────────
     gates.push(await orphansGate(input));
+    // ── architecture (advisory): cycles the change participates in ───────
+    gates.push(await archGate(cwd, changedFiles));
     // ── impact summary (informational, best-effort) ──────────────────────
     const impact = await impactSummary(cwd, changedFiles);
-    // ── fold into one verdict ────────────────────────────────────────────
-    const failed = gates.filter((g) => g.status === 'fail');
+    // ── fold into one honest 0/1/2 verdict ───────────────────────────────
+    // Only NON-advisory ("deciding") gates decide the verdict. A deciding fail (or
+    // a config that could not load) is `1`. Otherwise, if NO deciding gate actually
+    // evaluated anything (all skipped), the run verified nothing → `2` (never a
+    // green `0`). Only when at least one deciding gate ran over a real scope and
+    // none failed is it a true `0`.
+    const deciding = gates.filter((g) => !g.advisory);
+    const failed = deciding.filter((g) => g.status === 'fail');
+    const anyEvaluated = deciding.some((g) => g.status === 'pass');
     const warnings = gates.reduce((n, g) => n + g.warnings, 0);
-    const verdict = failed.length > 0 || configError ? 'fail' : 'pass';
+    let verdict;
+    let exit;
+    if (failed.length > 0 || configError) {
+        verdict = 'fail';
+        exit = ExitCode.Failure;
+    }
+    else if (!anyEvaluated) {
+        verdict = 'not-verified';
+        exit = ExitCode.NotVerified;
+    }
+    else {
+        verdict = 'pass';
+        exit = ExitCode.VerifiedPass;
+    }
     const skipped = gates.filter((g) => g.status === 'skipped').map((g) => g.name);
+    const advisoryWarned = gates.filter((g) => g.advisory && g.warnings > 0).map((g) => g.name);
     const summary = verdict === 'fail'
         ? `Not safe to finish: ${configError ? 'config failed to load; ' : ''}${failed.map((g) => `${g.name} (${g.errors} error(s))`).join(', ') || 'see gates'}.`
-        : changedFiles.length === 0 && input.mode !== 'files'
-            ? 'No files in the changed scope — nothing to gate.'
-            : `Safe to finish: every applicable gate passed${warnings > 0 ? ` (${warnings} non-blocking warning(s))` : ''}${skipped.length > 0 ? `; skipped: ${skipped.join(', ')}` : ''}.`;
+        : verdict === 'not-verified'
+            ? `Not verified: no gate evaluated the changed scope${changedFiles.length === 0 ? ' (nothing changed)' : ' (nothing in it is gate-relevant)'} — this is NOT a pass. Re-run over a scope with code changes, or gate explicitly.`
+            : `Safe to finish: every applicable gate passed${warnings > 0 ? ` (${warnings} non-blocking warning(s)${advisoryWarned.length > 0 ? ` — see ${advisoryWarned.join(', ')}` : ''})` : ''}${skipped.length > 0 ? `; skipped: ${skipped.join(', ')}` : ''}.`;
     const nextAction = verdict === 'fail'
         ? 'Fix every failing gate item (each carries file:line), then re-run `shrk finish`.'
-        : 'Safe to declare done.';
+        : verdict === 'not-verified'
+            ? 'Nothing was verified — do not treat this as done.'
+            : 'Safe to declare done.';
     return {
         schema: FINISH_SCHEMA,
         scope: { mode: input.mode, files: changedFiles, fileCount: changedFiles.length },
         gates,
         impact,
         verdict,
+        exit,
         warnings,
         ...(configError ? { configError } : {}),
         summary,
@@ -133,6 +185,10 @@ export async function runFinishGates(input) {
 function skip(name, detail) {
     return { name, status: 'skipped', detail, errors: 0, warnings: 0, items: [] };
 }
+/** A skipped ADVISORY gate — reports its detail but never decides the verdict. */
+function advisorySkip(name, detail) {
+    return { name, status: 'skipped', detail, errors: 0, warnings: 0, items: [], advisory: true };
+}
 function wiringGate(cwd, rules, changedFiles) {
     if (rules.length === 0)
         return skip('wiring', 'no wiring rules configured');
@@ -188,6 +244,126 @@ function policyGate(cwd, rules, changedFiles) {
         ],
     };
 }
+/**
+ * The runtime-wiring `unprovided` gate — the silent-at-runtime class imports
+ * can't see: a token DECLARED or INJECTED but never PROVIDED (typecheck-green,
+ * absent at runtime). Backed by the registration/DI graph, scoped to the
+ * changeset so only tokens THIS change touches decide the verdict. Skips (never
+ * fails) when no idioms are configured or the change touched no wiring — so a
+ * repo that never modeled its DI is not penalized.
+ */
+function unprovidedGate(cwd, idioms, changedFiles, baseRef) {
+    if (idioms.length === 0)
+        return skip('unprovided', 'no registration idioms configured');
+    const graph = buildRegistrationGraph(cwd, idioms);
+    const diag = graph.diagnostics;
+    // Two ways THIS change can leave a token unprovided:
+    //  (1) a declared/injected site added in a changed file with no provider —
+    //      caught by scoping the graph query to the changed files;
+    //  (2) the last PROVIDER removed from a changed file — which leaves NO site in
+    //      the changed file, so (1) structurally can't see it. Recover it by
+    //      diffing the base content of the changed files (providerRegressions).
+    const scoped = registrationUnprovided(graph, changedFiles);
+    const regressions = baseRef ? providerRegressions(cwd, idioms, graph, changedFiles, baseRef) : [];
+    const byToken = new Map();
+    for (const u of [...scoped, ...regressions])
+        if (!byToken.has(u.token))
+            byToken.set(u.token, u);
+    const unprovided = [...byToken.values()].sort((a, b) => a.token.localeCompare(b.token));
+    // Skip (evaluated nothing) only when the change touched no registration site
+    // AND removed no provider AND has no misconfigured idiom — never a silent pass.
+    if (!registrationTouchesChanged(graph, changedFiles) && unprovided.length === 0 && diag.length === 0) {
+        return skip('unprovided', 'no registration sites in the changed scope');
+    }
+    return {
+        name: 'unprovided',
+        status: unprovided.length > 0 || diag.length > 0 ? 'fail' : 'pass',
+        detail: `${unprovided.length} unprovided token(s) attributable to the change${diag.length > 0 ? `, ${diag.length} misconfigured idiom(s)` : ''}`,
+        errors: unprovided.length + diag.length,
+        warnings: 0,
+        items: [
+            ...unprovided.map((u) => {
+                const site = u.declared[0] ?? u.consumed[0];
+                return {
+                    ...(site ? { file: site.file, line: site.line } : {}),
+                    message: `"${u.token}" declared/injected but never provided (silent at runtime)`,
+                };
+            }),
+            ...diag.map((d) => ({ message: `misconfigured idiom: ${d}` })),
+        ],
+    };
+}
+/**
+ * Tokens whose LAST provider this change removed. Reads the base content of each
+ * changed code file, extracts what it USED to provide, and keeps any token now
+ * provided nowhere in the worktree but still declared/consumed — the runtime
+ * break (`inject(T)` → undefined) that deleting a provider registration causes,
+ * which leaves no site in the changed file for post-change scoping to catch.
+ */
+function providerRegressions(cwd, idioms, graph, changedFiles, baseRef) {
+    const codeChanged = codeFilesOf(changedFiles);
+    if (codeChanged.length === 0)
+        return [];
+    const baseEntries = [];
+    for (const f of codeChanged) {
+        const content = gitShowFile(cwd, baseRef, f);
+        if (content !== null)
+            baseEntries.push({ path: f, content });
+    }
+    if (baseEntries.length === 0)
+        return [];
+    const wasProvided = providedTokensFromEntries(idioms, baseEntries);
+    const out = [];
+    for (const token of wasProvided) {
+        const node = graph.tokens.find((t) => t.token === token);
+        if (node && node.provided.length === 0 && (node.declared.length > 0 || node.consumed.length > 0)) {
+            out.push({ token, declared: node.declared, consumed: node.consumed });
+        }
+    }
+    return out;
+}
+/**
+ * Advisory architecture gate: does any changed file participate in a runtime
+ * import cycle? Distinct from the `boundaries` gate (which sees layer violations,
+ * not cycles). Deliberately ADVISORY — a pre-existing cycle a change merely
+ * touches must not be attributed to this changeset, so it reports as a
+ * non-blocking warning and never fails the composite. Type-only import edges are
+ * excluded (they erase at emit and can't cause a runtime cycle). Best-effort:
+ * a missing graph index degrades to skip, never fail.
+ */
+async function archGate(cwd, changedFiles) {
+    const codeChanged = codeFilesOf(changedFiles);
+    if (codeChanged.length === 0)
+        return advisorySkip('arch', 'no code files in changed scope');
+    try {
+        const { GraphStore, GraphQueryApi } = await import('@shrkcrft/graph');
+        if (!new GraphStore(cwd).exists()) {
+            return advisorySkip('arch', 'code-graph index missing — run `shrk graph index`');
+        }
+        const api = GraphQueryApi.fromStore(cwd);
+        const cycles = api.cycles(); // runtime cycles only (type-only edges excluded)
+        const scope = new Set(codeChanged.map((f) => f.replace(/\\/g, '/').replace(/^\.\//, '')));
+        const touching = cycles.filter((c) => (c.paths ?? c.nodeIds.map((id) => id.replace(/^file:/, ''))).some((p) => scope.has(p)));
+        if (touching.length === 0) {
+            return advisorySkip('arch', `no changed file participates in an import cycle (${cycles.length} runtime cycle(s) in repo)`);
+        }
+        return {
+            name: 'arch',
+            status: 'pass', // advisory: reports cycles as warnings, never fails the composite
+            advisory: true,
+            detail: `${touching.length} changed file(s) participate in a runtime import cycle (advisory — not attributed to this change)`,
+            errors: 0,
+            warnings: touching.length,
+            items: touching.slice(0, 15).map((c) => {
+                const paths = c.paths ?? c.nodeIds.map((id) => id.replace(/^file:/, ''));
+                return { message: `import cycle (size ${c.size}): ${paths.join(' → ')}` };
+            }),
+        };
+    }
+    catch (e) {
+        return advisorySkip('arch', `arch check unavailable: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
 async function orphansGate(input) {
     const opts = orphanOptsFor(input);
     if (!opts)

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

@@ -0,0 +1,35 @@
+import type { IBaselineRule, IGeneratedArtifactRule, IPolicyRule, IRegistrationIdiom, IRegistryDeclaration, IRuleSelfTest, IWiringRule } from '@shrkcrft/core';
+/** Which data-defined plane a rule belongs to. */
+export type GatePlane = 'wiring' | 'policy' | 'registry' | 'registration' | 'baseline' | 'generated';
+/** Every plane, in the order `shrk gates list` prints them. */
+export declare const GATE_PLANES: readonly GatePlane[];
+/**
+ * One data-defined rule, normalized across planes.
+ *
+ * The trust layer's whole job is to answer "what did this rule actually match?"
+ * for ANY rule, so it needs one shape to iterate. The plane-specific rule object
+ * rides along in `raw` for the explain dispatch.
+ */
+export interface IGateRuleView {
+    readonly id: string;
+    readonly plane: GatePlane;
+    readonly description?: string;
+    readonly severity: 'error' | 'warning';
+    /** True when a zero-match is a hard failure rather than a loud skip. */
+    readonly failOnEmpty: boolean;
+    readonly selfTest?: IRuleSelfTest;
+    /** The underlying rule, for the plane-specific explainer. */
+    readonly raw: IWiringRule | IPolicyRule | IRegistryDeclaration | IRegistrationIdiom | IBaselineRule | IGeneratedArtifactRule;
+}
+/** The config planes this view is built from. */
+export interface IGatePlanes {
+    readonly wiringRules?: readonly IWiringRule[];
+    readonly policyRules?: readonly IPolicyRule[];
+    readonly registries?: readonly IRegistryDeclaration[];
+    readonly registrationGraph?: readonly IRegistrationIdiom[];
+    readonly baselines?: readonly IBaselineRule[];
+    readonly generatedArtifacts?: readonly IGeneratedArtifactRule[];
+}
+/** Flatten every declared rule across every plane into one iterable list. */
+export declare function collectGateRules(planes: IGatePlanes): IGateRuleView[];
+//# sourceMappingURL=gate-rule-view.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gate-rule-view.d.ts","sourceRoot":"","sources":["../../src/gates/gate-rule-view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,sBAAsB,EACtB,WAAW,EACX,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,EACb,WAAW,EACZ,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"}

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

@@ -0,0 +1,80 @@
+/** Every plane, in the order `shrk gates list` prints them. */
+export const GATE_PLANES = [
+    'wiring',
+    'policy',
+    'registry',
+    'registration',
+    'baseline',
+    'generated',
+];
+/** Flatten every declared rule across every plane into one iterable list. */
+export function collectGateRules(planes) {
+    const out = [];
+    for (const r of planes.wiringRules ?? []) {
+        out.push({
+            id: r.id,
+            plane: 'wiring',
+            ...(r.description ? { description: r.description } : {}),
+            severity: r.severity ?? 'error',
+            failOnEmpty: r.failOnEmpty === true,
+            ...(r.selfTest ? { selfTest: r.selfTest } : {}),
+            raw: r,
+        });
+    }
+    for (const r of planes.policyRules ?? []) {
+        out.push({
+            id: r.id,
+            plane: 'policy',
+            ...(r.description ? { description: r.description } : {}),
+            severity: r.severity ?? 'error',
+            failOnEmpty: r.failOnEmpty === true,
+            ...(r.selfTest ? { selfTest: r.selfTest } : {}),
+            raw: r,
+        });
+    }
+    for (const r of planes.registries ?? []) {
+        out.push({
+            id: r.name,
+            plane: 'registry',
+            ...(r.description ? { description: r.description } : {}),
+            // A registry is an inventory, not a gate — it never fails a build on its
+            // own, so it carries no severity of its own.
+            severity: 'warning',
+            failOnEmpty: false,
+            raw: r,
+        });
+    }
+    for (const r of planes.registrationGraph ?? []) {
+        out.push({
+            id: r.name,
+            plane: 'registration',
+            ...(r.description ? { description: r.description } : {}),
+            severity: 'warning',
+            failOnEmpty: false,
+            raw: r,
+        });
+    }
+    for (const r of planes.baselines ?? []) {
+        out.push({
+            id: r.id,
+            plane: 'baseline',
+            ...(r.description ? { description: r.description } : {}),
+            severity: r.severity ?? 'error',
+            failOnEmpty: r.failOnEmpty === true,
+            ...(r.selfTest ? { selfTest: r.selfTest } : {}),
+            raw: r,
+        });
+    }
+    for (const r of planes.generatedArtifacts ?? []) {
+        out.push({
+            id: r.id,
+            plane: 'generated',
+            ...(r.description ? { description: r.description } : {}),
+            severity: r.severity ?? 'error',
+            failOnEmpty: r.failOnEmpty === true,
+            ...(r.selfTest ? { selfTest: r.selfTest } : {}),
+            raw: r,
+        });
+    }
+    return out;
+}

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

@@ -0,0 +1,53 @@
+import type { IGateRuleView } from './gate-rule-view.js';
+export declare const GATE_COVERAGE_SCHEMA: "sharkcraft.gate-coverage/v1";
+/**
+ * Whether a rule is connected to anything at all.
+ *
+ * `empty` is the finding this whole surface exists for: a stale selector that
+ * matches nothing passes every gate forever, so the ONLY way to notice is to
+ * report the match count itself and flag zero. `failed-expectation` is the
+ * stronger form — the author wrote down what the rule should match, and it
+ * doesn't.
+ */
+export type GateCoverageStatus = 'ok' | 'empty' | 'error' | 'failed-expectation';
+export interface IGateCoverage {
+    readonly id: string;
+    readonly plane: IGateRuleView['plane'];
+    readonly description?: string;
+    readonly status: GateCoverageStatus;
+    /** Files the rule's primary selector matched. */
+    readonly filesMatched: number;
+    /** Ids/units the rule extracted (findings scanned, for the policy plane). */
+    readonly unitsMatched: number;
+    /** What "units" means for this plane, for honest reporting. */
+    readonly unitLabel: string;
+    /** A few of the extracted ids, so the author can eyeball correctness. */
+    readonly sampleIds: readonly string[];
+    /** True when a zero match is a hard failure for this rule. */
+    readonly failOnEmpty: boolean;
+    readonly error?: string;
+    /** Unmet `selfTest` expectations, each a human-readable sentence. */
+    readonly expectationFailures: readonly string[];
+}
+export interface IGateCoverageReport {
+    readonly schema: typeof GATE_COVERAGE_SCHEMA;
+    readonly rules: readonly IGateCoverage[];
+    readonly total: number;
+    readonly empty: number;
+    readonly errored: number;
+    readonly expectationFailures: number;
+    /**
+     * `pass` — every rule matched something and met its expectations.
+     * `stale` — at least one rule matched nothing (or broke an expectation).
+     */
+    readonly verdict: 'pass' | 'stale';
+}
+/**
+ * Resolve every declared rule against the live tree and report what it matched.
+ *
+ * The `command`-compute baseline is the one rule kind that cannot be inspected
+ * 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;
+//# sourceMappingURL=rule-coverage.d.ts.map

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

@@ -0,0 +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"}

package/dist/gates/rule-coverage.js

@@ -0,0 +1,165 @@
+import { inspectSource, runPolicyLint, scanGeneratedFiles, wiringSourceSide, } from '@shrkcrft/boundaries';
+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) {
+    if (!selfTest)
+        return [];
+    const out = [];
+    if (selfTest.expectMatchesAtLeast !== undefined &&
+        unitsMatched < selfTest.expectMatchesAtLeast) {
+        out.push(`expected at least ${selfTest.expectMatchesAtLeast} match(es), got ${unitsMatched}`);
+    }
+    const present = new Set(ids);
+    for (const id of selfTest.expectIds ?? []) {
+        if (!present.has(id))
+            out.push(`expected id "${id}" was NOT extracted`);
+    }
+    for (const id of selfTest.expectNotIds ?? []) {
+        if (present.has(id))
+            out.push(`id "${id}" was extracted but is listed in expectNotIds`);
+    }
+    return out;
+}
+function matchWiring(cwd, rule, excludeDirs) {
+    const side = wiringSourceSide(rule);
+    if (!side)
+        return { filesMatched: 0, unitsMatched: 0, unitLabel: 'ids', ids: [], error: 'rule sets no source side' };
+    const insp = inspectSource(cwd, side, excludeDirs);
+    return {
+        filesMatched: insp.filesScanned,
+        unitsMatched: insp.ids.length,
+        unitLabel: 'ids',
+        ids: insp.ids,
+        ...(insp.error ? { error: insp.error } : {}),
+    };
+}
+function matchPolicy(cwd, rule, excludeDirs) {
+    const report = runPolicyLint(cwd, [rule], { excludeDirs });
+    const result = report.rules[0];
+    return {
+        // A policy rule's "files" and "units" differ only for inline templates.
+        filesMatched: result?.unitsScanned ?? 0,
+        unitsMatched: result?.unitsScanned ?? 0,
+        unitLabel: 'content units',
+        ids: [],
+        ...(result?.error ? { error: result.error } : {}),
+    };
+}
+function matchRegistry(cwd, decl, excludeDirs) {
+    const insp = inspectSource(cwd, decl.source, excludeDirs);
+    return {
+        filesMatched: insp.filesScanned,
+        unitsMatched: insp.ids.length,
+        unitLabel: 'ids',
+        ids: insp.ids,
+        ...(insp.error ? { error: insp.error } : {}),
+    };
+}
+function matchRegistration(cwd, idiom, excludeDirs) {
+    const insp = inspectSource(cwd, idiom.declared, excludeDirs);
+    return {
+        filesMatched: insp.filesScanned,
+        unitsMatched: insp.ids.length,
+        unitLabel: 'declared tokens',
+        ids: insp.ids,
+        ...(insp.error ? { error: insp.error } : {}),
+    };
+}
+function matchBaseline(cwd, rule, excludeDirs) {
+    // Only the EXTRACTOR half can be inspected without spawning. A command
+    // 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) {
+        return {
+            filesMatched: 0,
+            unitsMatched: 0,
+            unitLabel: 'entries (command compute — not inspected)',
+            ids: [],
+        };
+    }
+    const insp = inspectSource(cwd, rule.compute.source, excludeDirs);
+    return {
+        filesMatched: insp.filesScanned,
+        unitsMatched: insp.ids.length,
+        unitLabel: 'entries',
+        ids: insp.ids,
+        ...(insp.error ? { error: insp.error } : {}),
+    };
+}
+function matchGenerated(cwd, rule, excludeDirs) {
+    const scan = scanGeneratedFiles(cwd, rule, excludeDirs);
+    const files = [...scan.generated.keys()];
+    return {
+        filesMatched: files.length,
+        unitsMatched: files.length,
+        unitLabel: 'generated files',
+        ids: files,
+    };
+}
+/**
+ * Resolve every declared rule against the live tree and report what it matched.
+ *
+ * The `command`-compute baseline is the one rule kind that cannot be inspected
+ * 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 = []) {
+    const out = [];
+    for (const view of rules) {
+        let match;
+        switch (view.plane) {
+            case 'wiring':
+                match = matchWiring(cwd, view.raw, excludeDirs);
+                break;
+            case 'policy':
+                match = matchPolicy(cwd, view.raw, excludeDirs);
+                break;
+            case 'registry':
+                match = matchRegistry(cwd, view.raw, excludeDirs);
+                break;
+            case 'registration':
+                match = matchRegistration(cwd, view.raw, excludeDirs);
+                break;
+            case 'baseline':
+                match = matchBaseline(cwd, view.raw, excludeDirs);
+                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');
+        const status = match.error !== undefined
+            ? 'error'
+            : expectationFailures.length > 0
+                ? 'failed-expectation'
+                : match.unitsMatched === 0 && !uninspected
+                    ? 'empty'
+                    : 'ok';
+        out.push({
+            id: view.id,
+            plane: view.plane,
+            ...(view.description ? { description: view.description } : {}),
+            status,
+            filesMatched: match.filesMatched,
+            unitsMatched: match.unitsMatched,
+            unitLabel: match.unitLabel,
+            sampleIds: match.ids.slice(0, 5),
+            failOnEmpty: view.failOnEmpty,
+            ...(match.error ? { error: match.error } : {}),
+            expectationFailures,
+        });
+    }
+    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;
+    return {
+        schema: GATE_COVERAGE_SCHEMA,
+        rules: out,
+        total: out.length,
+        empty,
+        errored,
+        expectationFailures,
+        verdict: empty + errored + expectationFailures > 0 ? 'stale' : 'pass',
+    };
+}

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AA8X/B,wBAAgB,aAAa,IAAI,eAAe,CAiY/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiCrE;AAqID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAMhB,MAAM,uBAAuB,CAAC;AAoZ/B,wBAAgB,aAAa,IAAI,eAAe,CAqZ/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA+CrE;AAwID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}