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

package/dist/declared-gate-plane-rules.js

@@ -0,0 +1,39 @@
+import { GATE_PLANE_CONFIG_KEY, GATE_PLANE_ORDER } from '@shrkcrft/config';
+import { isProjectConfigAbsent, resolveProjectConfig } from "./resolve-project-config.js";
+/**
+ * How many data-defined gate-plane rules the project declares, per plane —
+ * read through `resolveProjectConfig` (THE config reader that sees
+ * pack-contributed planes) under THE plane → config-key list beside the config
+ * schema (`GATE_PLANE_CONFIG_KEY`), the one the CLI's `collectGateRules` reads.
+ *
+ * Two "no config was read" answers, kept apart (round 11 review R12-REG-2):
+ *   - NO config — the loader found no `sharkcraft/` folder
+ *     (`isProjectConfigAbsent`, the answer `finish` reads as "gate not
+ *     applicable"): zero rules and no `loadError`; there are no planes to run;
+ *   - a config that EXISTS but failed to load: `loadError` is set, since
+ *     nothing can be said about what it declares.
+ *
+ * `buildQualityReport` consumers other than `shrk quality` (MCP, the
+ * dashboard, the report site) do not run the planes — some spawn shells — so
+ * they report a not-run `gate-planes` row from this count; `shrk quality`
+ * runs them.
+ */
+export async function declaredGatePlaneRules(projectRoot) {
+    const resolved = await resolveProjectConfig(projectRoot);
+    if (!resolved.ok) {
+        return isProjectConfigAbsent(resolved.error)
+            ? { total: 0, byPlane: {} }
+            : { total: 0, byPlane: {}, loadError: resolved.error.message };
+    }
+    const config = resolved.value.config;
+    const byPlane = {};
+    let total = 0;
+    for (const plane of GATE_PLANE_ORDER) {
+        const list = config[GATE_PLANE_CONFIG_KEY[plane]];
+        const n = Array.isArray(list) ? list.length : 0;
+        if (n > 0)
+            byPlane[plane] = n;
+        total += n;
+    }
+    return { total, byPlane };
+}

package/dist/declared-reference-coverage.d.ts

@@ -0,0 +1,27 @@
+import type { IVerdictCoverage } from '@shrkcrft/core';
+import { type IKnowledgeAnchorCheck, type IKnowledgeReferenceCheck } from './knowledge-stale.js';
+/** Why a malformed reference is unexamined — the words every surface prints. */
+export declare const MALFORMED_REFERENCE_REASON = "malformed (a kind outside the vocabulary, or a required field missing), so never checked \u2014 `shrk doctor` names each";
+/**
+ * THE fold of declared references into one coverage record.
+ *
+ * A reference whose outcome was CHECKED (ok / stale / missing —
+ * `isCheckableOutcome`) was examined. A MALFORMED one (`invalid`) was declared
+ * to be checked and never was: it is expected, not examined, so a run holding
+ * one is never a clean pass. An `unknown` one (a url, an unpinned or ambiguous
+ * symbol, a file that failed to read) is neither: the stale-check accounts for
+ * it at the ENTRY level (an entry with nothing checkable is unverifiable), so
+ * it leaves both sides here — which is why a scope of ONLY unknown references
+ * is `expected: 0`, "nothing to examine", never a pass.
+ *
+ * `shrk knowledge stale-check` / `verify` (and so `shrk quality`, MCP
+ * `get_quality_report`, the dashboard) and the `shrk gate` knowledge-symbol
+ * gate all settle on this one record — the gate used to count every
+ * non-stale, non-missing reference as "resolving", so a malformed or unpinned
+ * reference read as a pass there while the stale-check said 2.
+ */
+export declare function declaredReferenceCoverage(input: {
+    readonly references: readonly IKnowledgeReferenceCheck[];
+    readonly anchors?: readonly IKnowledgeAnchorCheck[];
+}): IVerdictCoverage;
+//# sourceMappingURL=declared-reference-coverage.d.ts.map

package/dist/declared-reference-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared-reference-coverage.d.ts","sourceRoot":"","sources":["../src/declared-reference-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,EAGL,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAK9B,gFAAgF;AAChF,eAAO,MAAM,0BAA0B,6HACgF,CAAC;AAExH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,QAAQ,CAAC,UAAU,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACrD,GAAG,gBAAgB,CA0BnB"}

package/dist/declared-reference-coverage.js

@@ -0,0 +1,50 @@
+import { formatKnowledgeReference } from '@shrkcrft/knowledge';
+import { isCheckableOutcome, ReferenceCheckOutcome, } from "./knowledge-stale.js";
+/** Unexamined labels carried on the coverage record (the full list is in the JSON). */
+const LABEL_CAP = 20;
+/** Why a malformed reference is unexamined — the words every surface prints. */
+export const MALFORMED_REFERENCE_REASON = 'malformed (a kind outside the vocabulary, or a required field missing), so never checked — `shrk doctor` names each';
+/**
+ * THE fold of declared references into one coverage record.
+ *
+ * A reference whose outcome was CHECKED (ok / stale / missing —
+ * `isCheckableOutcome`) was examined. A MALFORMED one (`invalid`) was declared
+ * to be checked and never was: it is expected, not examined, so a run holding
+ * one is never a clean pass. An `unknown` one (a url, an unpinned or ambiguous
+ * symbol, a file that failed to read) is neither: the stale-check accounts for
+ * it at the ENTRY level (an entry with nothing checkable is unverifiable), so
+ * it leaves both sides here — which is why a scope of ONLY unknown references
+ * is `expected: 0`, "nothing to examine", never a pass.
+ *
+ * `shrk knowledge stale-check` / `verify` (and so `shrk quality`, MCP
+ * `get_quality_report`, the dashboard) and the `shrk gate` knowledge-symbol
+ * gate all settle on this one record — the gate used to count every
+ * non-stale, non-missing reference as "resolving", so a malformed or unpinned
+ * reference read as a pass there while the stale-check said 2.
+ */
+export function declaredReferenceCoverage(input) {
+    const anchors = input.anchors ?? [];
+    const invalidRefs = input.references.filter((c) => c.outcome === ReferenceCheckOutcome.Invalid);
+    const invalidAnchors = anchors.filter((a) => a.outcome === ReferenceCheckOutcome.Invalid);
+    const invalidCount = invalidRefs.length + invalidAnchors.length;
+    const invalidLabels = [
+        ...invalidRefs.map((c) => `${c.entryId} → ${formatKnowledgeReference(c.reference)}`),
+        ...invalidAnchors.map((a) => `${a.entryId} anchor[${a.anchor.id}]`),
+    ];
+    const checkable = input.references.filter((c) => isCheckableOutcome(c.outcome)).length +
+        anchors.filter((a) => isCheckableOutcome(a.outcome)).length;
+    return {
+        unit: 'declared references',
+        expected: checkable + invalidCount,
+        examined: checkable,
+        ...(invalidCount > 0
+            ? {
+                unexamined: invalidLabels.slice(0, LABEL_CAP),
+                unexaminedTotal: invalidCount,
+                reason: MALFORMED_REFERENCE_REASON,
+            }
+            : checkable === 0
+                ? { reason: 'no entry in scope declares a checkable reference' }
+                : {}),
+    };
+}

package/dist/declared-xref-status.d.ts

@@ -0,0 +1,19 @@
+/**
+ * How one declared cross-reference id resolved.
+ *
+ * `Unverified` is its own outcome, never folded into either of the others: an
+ * id checked against a registry that was never warmed (or is empty) could not
+ * be looked up, and reporting it `Dangling` is how a correct id gets flagged,
+ * while reporting it `Ok` is how a dead one ships.
+ */
+export declare enum DeclaredXrefStatus {
+    /** Resolves in a kind the field accepts. */
+    Ok = "ok",
+    /** Resolves in NO registry. */
+    Dangling = "dangling",
+    /** Resolves, but only in kinds the field does not accept (a template id in `relatedRules`). */
+    WrongKind = "wrong-kind",
+    /** Could not be decided — an accepted registry was not warmed, or is empty. NOT VERIFIED. */
+    Unverified = "unverified"
+}
+//# sourceMappingURL=declared-xref-status.d.ts.map

package/dist/declared-xref-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared-xref-status.d.ts","sourceRoot":"","sources":["../src/declared-xref-status.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,oBAAY,kBAAkB;IAC5B,4CAA4C;IAC5C,EAAE,OAAO;IACT,+BAA+B;IAC/B,QAAQ,aAAa;IACrB,+FAA+F;IAC/F,SAAS,eAAe;IACxB,6FAA6F;IAC7F,UAAU,eAAe;CAC1B"}

package/dist/declared-xref-status.js

@@ -0,0 +1,19 @@
+/**
+ * How one declared cross-reference id resolved.
+ *
+ * `Unverified` is its own outcome, never folded into either of the others: an
+ * id checked against a registry that was never warmed (or is empty) could not
+ * be looked up, and reporting it `Dangling` is how a correct id gets flagged,
+ * while reporting it `Ok` is how a dead one ships.
+ */
+export var DeclaredXrefStatus;
+(function (DeclaredXrefStatus) {
+    /** Resolves in a kind the field accepts. */
+    DeclaredXrefStatus["Ok"] = "ok";
+    /** Resolves in NO registry. */
+    DeclaredXrefStatus["Dangling"] = "dangling";
+    /** Resolves, but only in kinds the field does not accept (a template id in `relatedRules`). */
+    DeclaredXrefStatus["WrongKind"] = "wrong-kind";
+    /** Could not be decided — an accepted registry was not warmed, or is empty. NOT VERIFIED. */
+    DeclaredXrefStatus["Unverified"] = "unverified";
+})(DeclaredXrefStatus || (DeclaredXrefStatus = {}));

package/dist/delegate-pack-recipes.d.ts

@@ -1,5 +1,5 @@
-import { type IDelegateRecipe } from '@shrkcrft/core';
-import type { ISharkCraftConfig } from '@shrkcrft/config';
+import { type IDelegateRecipe, type IRejectedEntry } from '@shrkcrft/core';
+import { type ISharkCraftConfig } from '@shrkcrft/config';
 import { type IDiscoveredPack } from '@shrkcrft/packs';
 import { type IResolvedDelegateRecipe } from './delegate-catalog.js';
 export interface IPackDelegateRecipe {
@@ -12,11 +12,22 @@ export interface IPackRecipeIssue {
     severity: 'warning' | 'error';
     message: string;
     source?: string;
+    /** `load-failed` / `missing-file` — lifted into THE contribution load-failure map (round 12). */
+    code?: 'load-failed' | 'missing-file';
 }
 export interface ILoadPackRecipesResult {
     recipes: readonly IPackDelegateRecipe[];
     issues: readonly IPackRecipeIssue[];
+    /** Every declared recipe the loader refused — invalid or a duplicate id (round 12, 12.1). */
+    rejected: readonly IRejectedEntry[];
 }
+/**
+ * THE pack delegate-recipe acceptance predicate (round 12, 12.1): the SAME
+ * zod schema the config loader validates an inline recipe with
+ * (`DelegateRecipeSchema`), one `<path>: <message>` per issue — `[]` means
+ * accepted. A pack recipe used to be accepted with no validation at all.
+ */
+export declare function delegateRecipeRejectionReasons(raw: unknown): readonly string[];
 export declare function loadDelegateRecipesFromPacks(validPacks: readonly IDiscoveredPack[]): Promise<ILoadPackRecipesResult>;
 /**
  * One-shot: discover packs under `projectRoot`, load their delegate recipes, and

package/dist/delegate-pack-recipes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delegate-pack-recipes.d.ts","sourceRoot":"","sources":["../src/delegate-pack-recipes.ts"],"names":[],"mappings":"AAWA,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAA0B,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAE7F,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACrC;AAaD,wBAAsB,4BAA4B,CAChD,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,OAAO,CAAC,sBAAsB,CAAC,CA8BjC;AAED;;;;;;GAMG;AACH,wBAAsB,gCAAgC,CACpD,MAAM,EAAE,iBAAiB,EACzB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,SAAS,uBAAuB,EAAE,CAAC,CAY7C"}
+{"version":3,"file":"delegate-pack-recipes.d.ts","sourceRoot":"","sources":["../src/delegate-pack-recipes.ts"],"names":[],"mappings":"AAWA,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAA0B,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAE7F,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,IAAI,CAAC,EAAE,aAAa,GAAG,cAAc,CAAC;CACvC;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACpC,6FAA6F;IAC7F,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAI9E;AAED,wBAAsB,4BAA4B,CAChD,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,OAAO,CAAC,sBAAsB,CAAC,CA0DjC;AAED;;;;;;GAMG;AACH,wBAAsB,gCAAgC,CACpD,MAAM,EAAE,iBAAiB,EACzB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,SAAS,uBAAuB,EAAE,CAAC,CAY7C"}

package/dist/delegate-pack-recipes.js

@@ -9,22 +9,27 @@
  */
 import { existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { importModuleViaLoader } from '@shrkcrft/core';
+import { importModuleViaLoader, readContributionExport, RejectionCause, } from '@shrkcrft/core';
+import { DelegateRecipeSchema } from '@shrkcrft/config';
 import { discoverPacks } from '@shrkcrft/packs';
 import { resolveDelegateCatalog } from "./delegate-catalog.js";
-async function importRecipes(file) {
-    const mod = (await importModuleViaLoader(file));
-    if (Array.isArray(mod.default))
-        return mod.default;
-    if (mod.default && typeof mod.default === 'object')
-        return [mod.default];
-    if (Array.isArray(mod.delegateRecipes))
-        return mod.delegateRecipes;
-    return [];
+/**
+ * THE pack delegate-recipe acceptance predicate (round 12, 12.1): the SAME
+ * zod schema the config loader validates an inline recipe with
+ * (`DelegateRecipeSchema`), one `<path>: <message>` per issue — `[]` means
+ * accepted. A pack recipe used to be accepted with no validation at all.
+ */
+export function delegateRecipeRejectionReasons(raw) {
+    const parsed = DelegateRecipeSchema.safeParse(raw);
+    if (parsed.success)
+        return [];
+    return parsed.error.issues.map((i) => `${i.path.join('.') || '(entry)'}: ${i.message}`);
 }
 export async function loadDelegateRecipesFromPacks(validPacks) {
     const recipes = [];
     const issues = [];
+    const rejected = [];
+    const seen = new Map();
     for (const pack of validPacks) {
         const files = pack.manifest?.contributions?.delegateRecipeFiles ?? [];
         for (const rel of files) {
@@ -32,27 +37,53 @@ export async function loadDelegateRecipesFromPacks(validPacks) {
             if (!existsSync(file)) {
                 issues.push({
                     severity: 'warning',
+                    code: 'missing-file',
                     message: `Pack ${pack.packageName} declares ${rel} but the file is missing.`,
                     source: file,
                 });
                 continue;
             }
             try {
-                const list = await importRecipes(file);
-                for (const recipe of list) {
+                const exp = readContributionExport(await importModuleViaLoader(file), { namedKeys: ['delegateRecipes'] });
+                exp.items.forEach((raw, i) => {
+                    const at = {
+                        file,
+                        index: exp.single ? -1 : i,
+                        ...(exp.exportName ? { exportName: exp.exportName } : {}),
+                    };
+                    const rawId = raw && typeof raw === 'object' ? raw.id : undefined;
+                    const id = typeof rawId === 'string' ? rawId : undefined;
+                    const reasons = delegateRecipeRejectionReasons(raw);
+                    if (reasons.length > 0) {
+                        rejected.push({ ...at, ...(id ? { entryId: id } : {}), reasons, cause: RejectionCause.Invalid });
+                        return;
+                    }
+                    const recipe = raw;
+                    const prev = seen.get(recipe.id);
+                    if (prev !== undefined) {
+                        rejected.push({
+                            ...at,
+                            entryId: recipe.id,
+                            reasons: [`id: "${recipe.id}" is already declared in ${prev}`],
+                            cause: RejectionCause.DuplicateId,
+                        });
+                        return;
+                    }
+                    seen.set(recipe.id, `${pack.packageName} (${rel})`);
                     recipes.push({ recipe, packageName: pack.packageName, sourceFile: rel });
-                }
+                });
             }
             catch (e) {
                 issues.push({
                     severity: 'warning',
+                    code: 'load-failed',
                     message: `Pack ${pack.packageName} (${rel}): ${e.message}`,
                     source: file,
                 });
             }
         }
     }
-    return { recipes, issues };
+    return { recipes, issues, rejected };
 }
 /**
  * One-shot: discover packs under `projectRoot`, load their delegate recipes, and

package/dist/demo-package.js

@@ -12,7 +12,7 @@ function readme(scenarios) {
     const lines = [];
     lines.push('# SharkCraft demo package');
     lines.push('');
-    lines.push('Generated by `shrk demo package`. Drop this folder onto another machine,');
+    lines.push('Generated by SharkCraft (demo package). Drop this folder onto another machine,');
     lines.push('read `expected-commands.md`, then run `demo.sh` after reviewing it.');
     lines.push('');
     lines.push('## Scenarios');
@@ -45,7 +45,7 @@ function readme(scenarios) {
 function combinedDemoScript(scenarios) {
     const lines = [];
     lines.push('#!/usr/bin/env bash');
-    lines.push('# SharkCraft demo bundle — generated by `shrk demo package`.');
+    lines.push('# SharkCraft demo bundle — generated by SharkCraft (demo package).');
     lines.push('# Each scenario is delegated to its scenario-<name>.sh file so you can');
     lines.push('# run them individually or as a group. Nothing destructive runs here.');
     lines.push('set -euo pipefail');

package/dist/demo-script.js

@@ -111,8 +111,8 @@ const SCRIPTS = {
             {
                 title: 'Compare quality baselines',
                 commands: [
-                    'shrk quality baseline history',
-                    'shrk quality baseline diff latest previous --json',
+                    'shrk quality --json',
+                    'shrk report quality --format json',
                 ],
             },
             {

package/dist/demo-workflow.js

@@ -9,7 +9,7 @@ export const DEMO_WORKFLOW_SCHEMA = 'sharkcraft.demo-workflow/v1';
 function ghaPrReview(bun) {
     const lines = [];
     lines.push('# SharkCraft demo PR review workflow.');
-    lines.push('# Generated by `shrk demo workflow pr-review --provider github-actions`.');
+    lines.push('# Generated by SharkCraft (demo PR-review workflow, github-actions).');
     lines.push('# - runs the read-only review surface on every PR.');
     lines.push('# - no publishing, no posting comments by default.');
     lines.push('# - uncomment the optional `gh pr comment` step to opt into PR comment posting.');
@@ -70,7 +70,7 @@ function ghaPrReview(bun) {
 function gitlabPrReview(bun) {
     const lines = [];
     lines.push('# SharkCraft demo PR review pipeline.');
-    lines.push('# Generated by `shrk demo workflow pr-review --provider gitlab`.');
+    lines.push('# Generated by SharkCraft (demo PR-review workflow, gitlab).');
     lines.push('# - runs the read-only review surface on every MR.');
     lines.push('# - no publishing, no posting comments by default.');
     lines.push('');
@@ -114,7 +114,7 @@ function gitlabPrReview(bun) {
 function bitbucketPrReview(bun) {
     const lines = [];
     lines.push('# SharkCraft demo PR review pipeline.');
-    lines.push('# Generated by `shrk demo workflow pr-review --provider bitbucket`.');
+    lines.push('# Generated by SharkCraft (demo PR-review workflow, bitbucket).');
     lines.push('# - runs the read-only review surface on every pull request.');
     lines.push('# - no publishing, no posting comments by default.');
     lines.push('');

package/dist/dev-cycle.js

@@ -63,7 +63,7 @@ const RELEASE = {
         { id: 'release-readiness', title: 'Release readiness (strict)', command: 'shrk release readiness --strict', canFail: false, category: 'gate' },
         { id: 'release-smoke', title: 'Release smoke (default scenarios)', command: 'shrk release smoke', canFail: true, category: 'gate' },
         { id: 'safety-audit', title: 'Safety audit', command: 'shrk safety audit', canFail: false, category: 'audit' },
-        { id: 'product-check', title: 'Product check', command: 'shrk product check', canFail: true, category: 'gate' },
+        { id: 'product-check', title: 'Product check', command: 'shrk quality', canFail: true, category: 'gate' },
         { id: 'commands-doctor', title: 'Commands doctor', command: 'shrk commands doctor', canFail: true, category: 'doctor' },
     ],
 };

package/dist/dev-session.js

@@ -243,7 +243,7 @@ export function computeDevNextAction(load) {
     if (state?.phase === DevSessionPhase.Completed) {
         return {
             action: 'Session complete',
-            command: `shrk session show ${id}`,
+            command: `shrk dev reports ${id}`,
             reason: 'Final report has been generated.',
             requiresHumanApproval: false,
         };

package/dist/doc-references.d.ts

@@ -0,0 +1,80 @@
+import { type IDocReferenceRule, type IUnitLiveness, type IUnitStateLists, type IVerdictCoverage } from '@shrkcrft/core';
+import { type IReadScope } from '@shrkcrft/boundaries';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+/**
+ * The prose-reference linter.
+ *
+ * Scans configured docs for id-shaped tokens and asserts each resolves to a
+ * real registered id. The failure it exists to catch is silent: a table of
+ * template ids in a README or an agent skill file drifts from the registry and
+ * nothing — no build, no type-check, no existing gate — notices until someone
+ * runs the command and it fails.
+ *
+ * Everything here is deterministic text work plus a registry lookup. No model,
+ * no network, no guessing what a doc "meant".
+ */
+/** One token the rule considered. */
+export interface IDocReferenceToken {
+    readonly token: string;
+    /** Project-relative path of the document. */
+    readonly file: string;
+    /** 1-based line. */
+    readonly line: number;
+    /** The registry that accepted it, when it resolved. */
+    readonly resolvedAs?: string;
+    /** Why it was not treated as a reference, when it was skipped. */
+    readonly skipped?: 'context' | 'exempt' | 'exempt-marker';
+}
+/** An id-shaped token that resolved to nothing. */
+export interface IDocReferenceFinding {
+    readonly ruleId: string;
+    readonly token: string;
+    readonly file: string;
+    readonly line: number;
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    /** Closest registered ids, nearest first. Empty when nothing is close. */
+    readonly didYouMean: readonly string[];
+    readonly hint?: string;
+}
+/** One rule's outcome. */
+export interface IDocReferenceResult {
+    readonly ruleId: string;
+    readonly description?: string;
+    readonly severity: 'error' | 'warning';
+    readonly status: 'passed' | 'failed' | 'skipped' | 'error';
+    /** Documents the globs matched. */
+    readonly filesScanned: number;
+    /** Tokens that counted as references (context-gated, non-exempt). */
+    readonly tokensChecked: number;
+    /** Tokens matched but deliberately not treated as references. */
+    readonly tokensSkipped: number;
+    readonly findings: readonly IDocReferenceFinding[];
+    /** Every token considered — the `explain` view. */
+    readonly tokens: readonly IDocReferenceToken[];
+    readonly skipReason?: string;
+    readonly error?: string;
+    /**
+     * Set only when a document the globs matched was NOT read (over the read
+     * cap, or unreadable): the documents read, and the unread ones. A reference
+     * in an unread document was never checked, so the rule's coverage names it
+     * (`readScopeCoverage`) and it is never a pass.
+     */
+    readonly readScope?: IReadScope;
+    /**
+     * Set only when the rule is INTENDED-empty (round 13): every inclusion glob
+     * of its `files` is marked `expectEmpty` and no document matched. It is the
+     * settle's acceptance and stands in for the rule's own coverage record
+     * (`docReferenceCoverage`), so the rule passes with the acceptance printed.
+     */
+    readonly emptyCoverage?: IVerdictCoverage;
+    /** Settle record B of the rule's `files` — the acceptance of its intended-empty units. */
+    readonly unitAcceptance?: IVerdictCoverage;
+    /** The rule's dead / intended-empty / went-live `files` units as printed lines (`unitStateLists`). */
+    readonly units?: IUnitStateLists;
+    /** The rule's non-live `files` units, for `--fail-on-dead-units` (`selectorUnitFails`). */
+    readonly unitLiveness?: readonly IUnitLiveness[];
+}
+/** Evaluate one doc-reference rule against the tree. */
+export declare function checkDocReferences(projectRoot: string, authored: IDocReferenceRule, inspection: ISharkcraftInspection, excludeDirs?: readonly string[]): IDocReferenceResult;
+//# sourceMappingURL=doc-references.d.ts.map

package/dist/doc-references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-references.d.ts","sourceRoot":"","sources":["../src/doc-references.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,sBAAsB,CAAC;AAS9B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE;;;;;;;;;;;GAWG;AAEH,qCAAqC;AACrC,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oBAAoB;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,eAAe,CAAC;CAC3D;AAED,mDAAmD;AACnD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,0BAA0B;AAC1B,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;IAC3D,mCAAmC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,qEAAqE;IACrE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACnD,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,gBAAgB,CAAC;IAC1C,0FAA0F;IAC1F,QAAQ,CAAC,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAC3C,sGAAsG;IACtG,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,2FAA2F;IAC3F,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CAClD;AAmDD,wDAAwD;AACxD,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,UAAU,EAAE,qBAAqB,EACjC,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,mBAAmB,CA4OrB"}