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

package/dist/commands/policy-lint.command.js

@@ -1,13 +1,115 @@
 import * as nodePath from 'node:path';
-import { runPolicyLint } from '@shrkcrft/boundaries';
+import { runPolicyLint, } from '@shrkcrft/boundaries';
 import { classifyChangedScope, resolveChangedFiles, resolveProjectConfig } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 const VALID_SURFACES = new Set(['template', 'style', 'ts']);
+export const POLICY_EXPLAIN_SCHEMA = 'sharkcraft.policy-explain/v1';
+/**
+ * Dry-run ONE policy rule and return everything it saw — including the hits an
+ * exemption swallowed.
+ *
+ * Showing suppressed hits is the point: an exemption that silently deletes a
+ * finding is indistinguishable from a stale glob, so both the kept and the
+ * dropped hits are reported, each labelled with the exemption that applied.
+ */
+export function runPolicyExplain(cwd, rule, excludeDirs) {
+    const report = runPolicyLint(cwd, [rule], { excludeDirs });
+    const result = report.rules[0];
+    const skip = report.skipped[0];
+    return {
+        schema: POLICY_EXPLAIN_SCHEMA,
+        ruleId: rule.id,
+        ...(rule.description ? { description: rule.description } : {}),
+        surface: rule.surface,
+        severity: rule.severity ?? 'error',
+        pattern: rule.pattern,
+        scan: rule.scan ?? 'all',
+        unitsScanned: result?.unitsScanned ?? 0,
+        status: result?.status ?? 'error',
+        findings: report.findings,
+        suppressed: report.suppressed,
+        exemptFiles: rule.exemptFiles ?? [],
+        ...(rule.exemptLines ? { exemptLines: rule.exemptLines } : {}),
+        diagnostics: report.diagnostics,
+        ...(skip ? { skipReason: skip.reason } : {}),
+    };
+}
+/** Render an {@link IPolicyExplain}. Always returns 0 — explain is informational. */
+export function renderPolicyExplain(explain, wantJson) {
+    if (wantJson) {
+        process.stdout.write(asJson(explain) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Policy explain: ${explain.ruleId} (${explain.surface})`));
+    if (explain.description)
+        process.stdout.write(`  ${explain.description}\n`);
+    process.stdout.write(kv('pattern', `/${explain.pattern}/`) + '\n');
+    process.stdout.write(kv('scan zone', explain.scan) + '\n');
+    process.stdout.write(kv('units scanned', String(explain.unitsScanned)) + '\n');
+    process.stdout.write(kv('status', explain.status) + '\n');
+    if (explain.exemptFiles.length > 0) {
+        process.stdout.write(kv('exemptFiles', explain.exemptFiles.join(', ')) + '\n');
+    }
+    if (explain.exemptLines)
+        process.stdout.write(kv('exemptLines', explain.exemptLines) + '\n');
+    process.stdout.write(`\nHits that COUNT (${explain.findings.length}):\n`);
+    for (const f of explain.findings.slice(0, 60)) {
+        process.stdout.write(`  ✗ ${f.match}  (${f.file}:${f.line})${f.inlineTemplate ? ' [inline template]' : ''}\n`);
+    }
+    if (explain.findings.length > 60) {
+        process.stdout.write(`  … (${explain.findings.length - 60} more)\n`);
+    }
+    if (explain.suppressed.length > 0) {
+        process.stdout.write(`\nHits an exemption DROPPED (${explain.suppressed.length}):\n`);
+        for (const s of explain.suppressed.slice(0, 60)) {
+            process.stdout.write(`  – ${s.match}  (${s.file}:${s.line})  via ${s.via}\n`);
+        }
+        if (explain.suppressed.length > 60) {
+            process.stdout.write(`  … (${explain.suppressed.length - 60} more)\n`);
+        }
+    }
+    if (explain.skipReason) {
+        process.stdout.write(`\n! SKIPPED — ${explain.skipReason}. A rule that scans nothing is a bug in the rule,\n` +
+            '  not a pass. Fix the glob, or set `failOnEmpty: true` to make this a hard failure.\n');
+    }
+    for (const d of explain.diagnostics)
+        process.stdout.write(`  ! ${d}\n`);
+    return 0;
+}
+export const policyLintExplainCommand = {
+    name: 'explain',
+    description: 'Dry-run ONE policyRule and print every hit with file:line — INCLUDING the hits an exemption or the scan zone dropped, each labelled with which one applied.',
+    usage: 'shrk policy-lint explain <ruleId> [--json]',
+    booleanFlags: new Set(['json']),
+    async run(args) {
+        const id = args.positional[0] ?? flagString(args, 'id');
+        if (!id) {
+            process.stderr.write('Usage: shrk policy-lint explain <ruleId> [--json]\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const loaded = await resolveProjectConfig(cwd);
+        if (!loaded.ok) {
+            process.stderr.write(`Could not load config: ${loaded.error.message}\n`);
+            return 2;
+        }
+        const rules = loaded.value.config.policyRules ?? [];
+        const rule = rules.find((r) => r.id === id);
+        if (!rule) {
+            process.stderr.write(`No policy rule "${id}". Configured: ${rules.map((r) => r.id).join(', ') || '(none)'}\n`);
+            return 2;
+        }
+        const rel = nodePath.relative(cwd, loaded.value.sharkcraftDir).split(nodePath.sep).join('/');
+        const excludeDirs = rel && !rel.startsWith('..') ? [rel] : [];
+        return renderPolicyExplain(runPolicyExplain(cwd, rule, excludeDirs), flagBool(args, 'json'));
+    },
+};
 export const policyLintCommand = {
     name: 'policy-lint',
     description: 'Lint template/markup, stylesheet, and AOT-invisible TS surfaces against data-defined policyRules[] (e.g. flag raw markup when a primitive exists). Sees `.html` files AND inline `template:` strings — surfaces tsc/AOT cannot. Deterministic; no AI.',
     usage: 'shrk [--cwd <dir>] policy-lint [--surface template|style|ts] [--changed-only] [--new-only] [--since <ref>] [--only <ids>] [--json]\n         (--changed-only SCANS just the changed files; --new-only scans the whole tree but shows only findings the change introduced, hiding pre-existing baseline debt)',
+    booleanFlags: new Set(['json', 'changed-only', 'new-only']),
     async run(args) {
         const cwd = resolveCwd(args);
         const wantJson = flagBool(args, 'json');
@@ -126,12 +228,23 @@ export const policyLintCommand = {
         if (report.evaluated === 0) {
             process.stdout.write(`  ! Nothing evaluated — ${report.rules.length} rule(s) configured but none matched files in scope` +
                 (changedOnly || since ? ' (changed-only).\n' : '.\n'));
-            return 0;
+            for (const sk of report.skipped) {
+                process.stdout.write(`    – ${sk.ruleId}: ${sk.reason}${sk.failed ? '  (failOnEmpty → FAILED)' : ''}\n`);
+            }
+            // Scanning nothing is not a pass. `2` = not verified (the repo-wide
+            // contract); a `failOnEmpty` rule promotes it to a real failure.
+            return report.skipped.some((sk) => sk.failed) ? 1 : 2;
         }
         process.stdout.write(kv('rules evaluated', `${report.evaluated} of ${report.rules.length}`) + '\n');
         const errors = report.findings.filter((f) => f.severity === 'error').length;
         const warnings = report.findings.filter((f) => f.severity === 'warning').length;
         process.stdout.write(kv('findings', `${errors} error(s), ${warnings} warning(s)`) + '\n');
+        if (report.suppressed.length > 0) {
+            process.stdout.write(kv('suppressed', `${report.suppressed.length} hit(s) dropped by an exemption — see \`policy-lint explain <id>\``) + '\n');
+        }
+        for (const sk of report.skipped) {
+            process.stdout.write(`  ${sk.failed ? '✗' : '–'} ${sk.ruleId} ${sk.failed ? 'FAILED' : 'SKIPPED'} — ${sk.reason}\n`);
+        }
         if (newOnly) {
             process.stdout.write(kv('scope', `new-only (${hiddenBaseline} pre-existing finding(s) hidden — run without --new-only to see all)`) + '\n');
         }
@@ -140,6 +253,10 @@ export const policyLintCommand = {
             for (const d of report.diagnostics)
                 process.stdout.write(`  ! ${d}\n`);
         }
+        if (report.skipped.some((sk) => sk.failed)) {
+            process.stdout.write('\nA rule with `failOnEmpty: true` matched nothing — that is a bug in the rule, not a pass.\n');
+            return 1;
+        }
         if (report.findings.length === 0 && report.diagnostics.length === 0) {
             process.stdout.write(newOnly
                 ? `\nNo NEW policy violations from this change${hiddenBaseline > 0 ? ` (${hiddenBaseline} pre-existing hidden)` : ''}. ✓\n`

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

@@ -1 +1 @@
-{"version":3,"file":"registry.command.d.ts","sourceRoot":"","sources":["../../src/commands/registry.command.ts"],"names":[],"mappings":"AA4BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC,eAAO,MAAM,wBAAwB,EAAE,eA8CtC,CAAC;AA6IF,eAAO,MAAM,eAAe,EAAE,eA4B7B,CAAC"}
+{"version":3,"file":"registry.command.d.ts","sourceRoot":"","sources":["../../src/commands/registry.command.ts"],"names":[],"mappings":"AA8BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC,eAAO,MAAM,wBAAwB,EAAE,eA8CtC,CAAC;AAoLF,eAAO,MAAM,eAAe,EAAE,eA4B7B,CAAC"}

package/dist/commands/registry.command.js

@@ -8,13 +8,14 @@
  *       [--fail-if-taken]                       #   guard: non-zero when taken (free → 0)
  *       [--fail-if-missing]                     #   guard: non-zero when NOT registered
  *   shrk registry <name> where <id> [--json]    # declaration (+ consumer) sites
+ *   shrk registry <name> duplicates [--json]    # ids declared in more than one place
  *
  * `<name>` resolves a `registries[]` declaration in sharkcraft.config.ts — one
  * deterministic multi-root scan that answers "is this id taken / where is it"
  * without an agent re-running a fragile grep.
  */
 import { buildRegistryLifecycleReport, renderRegistryLifecycleReportText, resolveChangedFiles, resolveProjectConfig, } from '@shrkcrft/inspector';
-import { scanRegistry, registryExists, registryWhere, } from '@shrkcrft/boundaries';
+import { scanRegistry, registryDuplicates, registryExists, registryWhere, } from '@shrkcrft/boundaries';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { ExitCode } from "../exit-codes.js";
 import { asJson } from "../output/format-output.js";
@@ -166,6 +167,37 @@ async function runRegistryInventory(args, name) {
         process.stdout.write(`${exists ? 'yes' : 'no'} — "${canonical}" is ${exists ? 'declared' : 'NOT declared'} in registry "${inventory.name}".\n`);
         return code;
     }
+    if (action === 'duplicates') {
+        // Two roots claiming the same id compile fine; whichever registration wins
+        // at runtime is an accident of load order. Every site is printed so the
+        // duplicate can be resolved, not merely detected.
+        const dupes = registryDuplicates(inventory);
+        if (json) {
+            process.stdout.write(asJson({
+                name: inventory.name,
+                scanned: inventory.entries.length,
+                duplicates: dupes,
+                diagnostics: [...inventory.diagnostics, ...loaded.planeDiagnostics],
+            }) + '\n');
+            return inventory.entries.length === 0 ? 2 : dupes.length > 0 ? 1 : 0;
+        }
+        if (inventory.entries.length === 0) {
+            process.stdout.write(`Registry "${inventory.name}" matched 0 ids — nothing was checked. This is NOT a pass;\n` +
+                '  the source selector is probably stale (see `shrk gates coverage`).\n');
+            return 2;
+        }
+        if (dupes.length === 0) {
+            process.stdout.write(`No duplicate ids in registry "${inventory.name}" (${inventory.entries.length} scanned). ✓\n`);
+            return 0;
+        }
+        process.stdout.write(`Duplicate ids in registry "${inventory.name}" (${dupes.length}):\n`);
+        for (const e of dupes) {
+            process.stdout.write(`  ✗ ${e.id}  (${e.sites.length} declarations)\n`);
+            for (const s of e.sites)
+                process.stdout.write(`      ${s.file}:${s.line}\n`);
+        }
+        return 1;
+    }
     if (action === 'where') {
         if (!id) {
             process.stderr.write(`Usage: shrk registry ${name} where <id>\n`);
@@ -187,13 +219,13 @@ async function runRegistryInventory(args, name) {
             process.stdout.write(`  consumed  ${s.file}:${s.line}\n`);
         return 0;
     }
-    process.stderr.write(`Unknown action "${action}". Usage: shrk registry ${name} list | exists <id> | where <id>\n`);
+    process.stderr.write(`Unknown action "${action}". Usage: shrk registry ${name} list | exists <id> | where <id> | duplicates\n`);
     return 2;
 }
 export const registryCommand = {
     name: 'registry',
     description: 'Registry inspections: lifecycle symmetry + declared-registry inventory. Read-only.',
-    usage: 'shrk registry lifecycle | <name> list | <name> exists <id> [--resolve] [--fail-if-taken|--fail-if-missing] | <name> where <id>',
+    usage: 'shrk registry lifecycle | <name> list | <name> exists <id> [--resolve] [--fail-if-taken|--fail-if-missing] | <name> where <id> | <name> duplicates',
     // Guard-mode + query flags take no value — declare them so `exists <id>
     // --fail-if-taken` (flag last) and `exists --resolve <id>` (flag first) both
     // keep the id as a positional instead of swallowing it.
@@ -211,7 +243,7 @@ export const registryCommand = {
         const cwd = resolveCwd(args);
         const loaded = await loadRegistries(cwd);
         const names = loaded.ok ? loaded.registries.map((r) => r.name) : [];
-        process.stderr.write('Usage: shrk registry lifecycle | <name> list | <name> exists <id> | <name> where <id>\n' +
+        process.stderr.write('Usage: shrk registry lifecycle | <name> list | <name> exists <id> | <name> where <id> | <name> duplicates\n' +
             (names.length > 0 ? `Declared registries: ${names.join(', ')}.\n` : 'No registries declared (sharkcraft.config.ts `registries[]`).\n'));
         return 2;
     },

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,CAsDrF;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,CAoFrF;AAyZD,eAAO,MAAM,aAAa,EAAE,eAgB3B,CAAC"}

package/dist/commands/wiring.command.js

@@ -24,6 +24,10 @@ export function renderWiringExplain(report, wantJson) {
         process.stdout.write(`  ${report.description}\n`);
     if (report.groupBy)
         process.stdout.write(kv('groupBy', report.groupBy) + '\n');
+    if (report.registeredMode === 'intersection') {
+        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');
@@ -52,6 +56,27 @@ export function renderWiringExplain(report, wantJson) {
             process.stdout.write(`  … (${report.registeredNotDeclared.length - SITE_DISPLAY_CAP} more)\n`);
         }
     }
+    if (report.overlap.length > 0) {
+        process.stdout.write(`\nPresent on BOTH sides (disjoint, ${report.overlap.length}):\n`);
+        for (const s of report.overlap.slice(0, SITE_DISPLAY_CAP)) {
+            process.stdout.write(`  ✗ ${s.token}  (${s.file}:${s.line})\n`);
+        }
+        if (report.overlap.length > SITE_DISPLAY_CAP) {
+            process.stdout.write(`  … (${report.overlap.length - SITE_DISPLAY_CAP} more)\n`);
+        }
+    }
+    if (report.hops && report.hops.length > 0) {
+        process.stdout.write('\nChain hops:\n');
+        for (const h of report.hops) {
+            process.stdout.write(`  hop ${h.index}: ${h.fromCount} → ${h.toCount}` +
+                `${h.missing > 0 ? `  ✗ ${h.missing} missing` : '  ✓'}\n`);
+        }
+    }
+    // A rule that checked NOTHING must never read like a clean pass.
+    if (report.skipReason) {
+        process.stdout.write(`\n! SKIPPED — ${report.skipReason}. A rule that matches nothing is a bug in the rule,\n` +
+            '  not a pass. Fix the selector, or set `failOnEmpty: true` to make this a hard failure.\n');
+    }
     for (const d of report.diagnostics)
         process.stdout.write(`  ! ${d}\n`);
     process.stdout.write(`\nVerdict: ${report.verdict}\n`);

package/dist/finish/run-finish.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-finish.d.ts","sourceRoot":"","sources":["../../src/finish/run-finish.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAiB7B,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,eAAO,MAAM,aAAa,EAAG,sBAA+B,CAAC;AAQ7D,2FAA2F;AAC3F,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;IAClG,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;QACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,cAAc,CAAC;IACnD,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;IACzD,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;CACtC;AAmBD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAmJnF"}
+{"version":3,"file":"run-finish.d.ts","sourceRoot":"","sources":["../../src/finish/run-finish.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAiB7B,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,eAAO,MAAM,aAAa,EAAG,sBAA+B,CAAC;AAQ7D,2FAA2F;AAC3F,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;IAClG,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;QACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,cAAc,CAAC;IACnD,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;IACzD,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;CACtC;AAmBD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CA2JnF"}

package/dist/finish/run-finish.js

@@ -88,16 +88,22 @@ export async function runFinishGates(input) {
         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(),
             })),
         });
     }

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"}