@shrkcrft/inspector 0.1.0-alpha.30 → 0.1.0-alpha.32

package/dist/knowledge-authoring.js

@@ -14,6 +14,8 @@
  *   - Remove always reports reverse references and refuses by default if any
  *     remain.
  */
+import { knowledgeAnchors, knowledgeReferences, } from '@shrkcrft/knowledge';
+import { KNOWLEDGE_BACKED_KINDS, reverseXrefs } from "./declared-cross-references.js";
 export const KNOWLEDGE_AUTHORING_SCHEMA = 'sharkcraft.knowledge-authoring/v1';
 export var KnowledgeAuthoringOperation;
 (function (KnowledgeAuthoringOperation) {
@@ -55,29 +57,58 @@ function tsObject(value, indent) {
         .map((line, idx) => (idx === 0 ? line : indent + line))
         .join('\n'));
 }
-function findReverseReferences(entries, targetId) {
+/**
+ * Everything that points at `targetId`. The structured `references[].id` and
+ * `anchors[].targetId` are scanned here; every DECLARED cross-reference field
+ * (knowledge `related` / `seeAlso` / `supersededBy` / action hints, construct
+ * `related*` + declared facets, boundary `related*`, template `related`) comes
+ * from THE collector when the caller supplied it — this used to be a private
+ * knowledge-only `related` loop, so an entry a construct relied on could be
+ * removed without a word.
+ */
+function findReverseReferences(entries, targetId, declaredXrefs) {
     const out = [];
     for (const e of entries) {
         if (e.id === targetId)
             continue;
-        for (const r of e.related ?? []) {
-            if (r === targetId) {
-                out.push({ fromEntryId: e.id, field: 'related' });
+        if (!declaredXrefs) {
+            for (const r of e.related ?? []) {
+                if (r === targetId) {
+                    out.push({ fromEntryId: e.id, field: 'related' });
+                }
             }
         }
-        for (const ref of e.references ?? []) {
+        for (const ref of knowledgeReferences(e)) {
             if (ref.id === targetId) {
                 out.push({ fromEntryId: e.id, field: 'reference.id', note: ref.note });
             }
         }
-        for (const a of e.anchors ?? []) {
+        for (const a of knowledgeAnchors(e)) {
             if (a.targetId === targetId) {
                 out.push({ fromEntryId: e.id, field: 'anchor.targetId', note: a.description });
             }
         }
     }
+    if (declaredXrefs) {
+        // Only fields that could mean THIS entry: a construct's
+        // `relatedTemplates: ['x']` is not a reference to a knowledge entry `x`.
+        for (const row of reverseXrefs(declaredXrefs, targetId, KNOWLEDGE_BACKED_KINDS)) {
+            if (row.sourceKind === 'knowledge' && row.sourceId === targetId)
+                continue;
+            out.push({
+                fromEntryId: row.sourceId,
+                ...(row.sourceKind !== 'knowledge' ? { sourceKind: row.sourceKind } : {}),
+                field: row.field,
+                ...(row.facetId ? { note: `facet value ${row.facetId}` } : {}),
+            });
+        }
+    }
     return out;
 }
+/** `construct:fx-construct` — or the bare id for a knowledge entry (the shape it always had). */
+export function reverseReferenceLabel(rr) {
+    return rr.sourceKind && rr.sourceKind !== 'knowledge' ? `${rr.sourceKind}:${rr.fromEntryId}` : rr.fromEntryId;
+}
 function buildEntryFromAdd(input) {
     return {
         id: input.id,
@@ -135,7 +166,7 @@ function applyUpdateOps(current, ops, changes) {
         }
     }
     if (ops.addReferences && ops.addReferences.length > 0) {
-        const merged = [...(next.references ?? [])];
+        const merged = [...knowledgeReferences(next)];
         const added = [];
         for (const r of ops.addReferences) {
             const dup = merged.find((m) => m.kind === r.kind &&
@@ -153,7 +184,7 @@ function applyUpdateOps(current, ops, changes) {
         }
     }
     if (ops.removeReferences && ops.removeReferences.length > 0) {
-        const before = next.references ?? [];
+        const before = knowledgeReferences(next);
         const keep = before.filter((m) => {
             return !ops.removeReferences.some((rm) => m.kind === rm.kind &&
                 (m.id ?? '') === (rm.id ?? '') &&
@@ -167,7 +198,7 @@ function applyUpdateOps(current, ops, changes) {
         }
     }
     if (ops.addAnchors && ops.addAnchors.length > 0) {
-        const merged = [...(next.anchors ?? [])];
+        const merged = [...knowledgeAnchors(next)];
         const added = [];
         for (const a of ops.addAnchors) {
             if (!merged.some((m) => m.id === a.id)) {
@@ -181,7 +212,7 @@ function applyUpdateOps(current, ops, changes) {
         }
     }
     if (ops.removeAnchorIds && ops.removeAnchorIds.length > 0) {
-        const before = next.anchors ?? [];
+        const before = knowledgeAnchors(next);
         const keep = before.filter((a) => !ops.removeAnchorIds.includes(a.id));
         const removed = before.filter((a) => ops.removeAnchorIds.includes(a.id));
         next.anchors = keep;
@@ -266,7 +297,7 @@ function buildExplainer(input, result) {
         lines.push(`## Reverse references`);
         lines.push('');
         for (const rr of result.reverseReferences) {
-            lines.push(`- \`${rr.fromEntryId}\` → \`${rr.field}\`${rr.note ? ` — ${rr.note}` : ''}`);
+            lines.push(`- \`${reverseReferenceLabel(rr)}\` → \`${rr.field}\`${rr.note ? ` — ${rr.note}` : ''}`);
         }
         lines.push('');
     }
@@ -453,15 +484,24 @@ export function buildKnowledgeAuthoringPreview(input, context) {
                 refused.explainer = files.explainer;
                 return refused;
             }
-            const reverseReferences = findReverseReferences(context.entries, input.id);
+            const reverseReferences = findReverseReferences(context.entries, input.id, context.declaredXrefs);
+            if (!context.declaredXrefs) {
+                // An unmeasured "no references" must not read as a clean one.
+                warnings.push('reverse references checked in knowledge only — constructs / boundaries / templates were not consulted (pass declaredXrefs from buildDeclaredXrefReport).');
+            }
+            const fromOtherKinds = reverseReferences.filter((r) => r.sourceKind !== undefined && r.sourceKind !== 'knowledge').length;
             if (reverseReferences.length > 0 && !input.forcePreview) {
+                const n = reverseReferences.length;
+                const refusal = fromOtherKinds === 0
+                    ? `Refused: ${n} other entr${n === 1 ? 'y references' : 'ies reference'} "${input.id}".`
+                    : `Refused: ${n} declared reference${n === 1 ? '' : 's'} point${n === 1 ? 's' : ''} at "${input.id}" — ${n - fromOtherKinds} from knowledge, ${fromOtherKinds} from constructs / boundary rules / templates.`;
                 const refused = {
                     schema: KNOWLEDGE_AUTHORING_SCHEMA,
                     generatedAt: nowIso(),
                     operation: input.operation,
                     entryId: input.id,
                     ok: false,
-                    refusal: `Refused: ${reverseReferences.length} other entr${reverseReferences.length === 1 ? 'y references' : 'ies reference'} "${input.id}". Pass --force-preview to preview removal anyway, or prefer deprecation via \`shrk knowledge update ${input.id} --mark-deprecated\`.`,
+                    refusal: `${refusal} Pass --force-preview to preview removal anyway, or prefer deprecation via \`shrk knowledge update ${input.id} --mark-deprecated\`.`,
                     tsDraft: emptyDraftFile(input.id, input.operation, 'typescript'),
                     jsonManifest: emptyDraftFile(input.id, input.operation, 'json'),
                     explainer: emptyDraftFile(input.id, input.operation, 'markdown'),

package/dist/knowledge-contribution-slots.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The pack manifest slots whose files the KNOWLEDGE loaders read — THE answer
+ * to "is this contribution file knowledge?" (round 15 follow-up, F11).
+ *
+ * The inspection reads every file of these slots with the knowledge loaders (a
+ * TypeScript / JavaScript module, or a Markdown document), and every other
+ * slot's files with an importing loader. `packs test --load` used to decide
+ * "Markdown knowledge" by the `.md` extension instead: a `.md` declared under
+ * `templateFiles` was validated as if it were knowledge (while the consumer
+ * imports it as a template module), and a knowledge-slot file no knowledge
+ * loader reads passed in silence (while the consumer skips it as an
+ * "unsupported contribution file"). The slot decides now; which knowledge loader
+ * reads the file stays the runtime's own choice (`validateContributionFile`).
+ */
+export declare const KNOWLEDGE_CONTRIBUTION_SLOTS: readonly string[];
+/** Does the manifest slot `slot` feed the knowledge loaders? */
+export declare function isKnowledgeContributionSlot(slot: string): boolean;
+//# sourceMappingURL=knowledge-contribution-slots.d.ts.map

package/dist/knowledge-contribution-slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-contribution-slots.d.ts","sourceRoot":"","sources":["../src/knowledge-contribution-slots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,4BAA4B,EAAE,SAAS,MAAM,EAMzD,CAAC;AAEF,gEAAgE;AAChE,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE"}

package/dist/knowledge-contribution-slots.js

@@ -0,0 +1,25 @@
+/**
+ * The pack manifest slots whose files the KNOWLEDGE loaders read — THE answer
+ * to "is this contribution file knowledge?" (round 15 follow-up, F11).
+ *
+ * The inspection reads every file of these slots with the knowledge loaders (a
+ * TypeScript / JavaScript module, or a Markdown document), and every other
+ * slot's files with an importing loader. `packs test --load` used to decide
+ * "Markdown knowledge" by the `.md` extension instead: a `.md` declared under
+ * `templateFiles` was validated as if it were knowledge (while the consumer
+ * imports it as a template module), and a knowledge-slot file no knowledge
+ * loader reads passed in silence (while the consumer skips it as an
+ * "unsupported contribution file"). The slot decides now; which knowledge loader
+ * reads the file stays the runtime's own choice (`validateContributionFile`).
+ */
+export const KNOWLEDGE_CONTRIBUTION_SLOTS = [
+    'knowledgeFiles',
+    'ruleFiles',
+    'pathFiles',
+    'pathConventionFiles',
+    'docsFiles',
+];
+/** Does the manifest slot `slot` feed the knowledge loaders? */
+export function isKnowledgeContributionSlot(slot) {
+    return KNOWLEDGE_CONTRIBUTION_SLOTS.includes(slot);
+}

package/dist/knowledge-entry-rejections.d.ts

@@ -0,0 +1,17 @@
+import { ContributionKind } from './contribution-kind.js';
+import type { IKnowledgeRejectedEntry } from './knowledge-rejected-entry.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+/** Every contribution kind the knowledge loaders read (knowledge, rules, paths, path conventions, docs). */
+export declare const KNOWLEDGE_CONTRIBUTION_KINDS: readonly ContributionKind[];
+/** The label every surface prints before a refused entry's reasons. */
+export declare const REJECTED_AT_LOAD = "rejected at load \u2014 not checked";
+/** `rejected at load — not checked: <reason>; <reason>` — THE row wording. */
+export declare function rejectedAtLoadMessage(reasons: readonly string[]): string;
+/**
+ * Every knowledge-family entry the loaders refused, in THE channel's order
+ * (file, then position), each with the file to edit and the owning pack.
+ * Synchronous: the knowledge loaders run at inspection time, so their
+ * rejections are already on `inspection.loaderDiagnostics`.
+ */
+export declare function knowledgeRejectedEntries(inspection: ISharkcraftInspection): readonly IKnowledgeRejectedEntry[];
+//# sourceMappingURL=knowledge-entry-rejections.d.ts.map

package/dist/knowledge-entry-rejections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-entry-rejections.d.ts","sourceRoot":"","sources":["../src/knowledge-entry-rejections.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAC7E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,4GAA4G;AAC5G,eAAO,MAAM,4BAA4B,EAAE,SAAS,gBAAgB,EAMnE,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,wCAAmC,CAAC;AAEjE,8EAA8E;AAC9E,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,qBAAqB,GAAG,SAAS,uBAAuB,EAAE,CAiC9G"}

package/dist/knowledge-entry-rejections.js

@@ -0,0 +1,79 @@
+/**
+ * THE knowledge-family reading of the round-12 rejection channel (round 15
+ * follow-up, F3): every knowledge / rule / path / docs entry an inspection-time
+ * loader REFUSED — a TypeScript entry missing its `content`, a Markdown file
+ * whose frontmatter cannot be read as declared.
+ *
+ * A refused entry never reaches `inspection.knowledgeEntries`, so the
+ * stale-check swept the survivors and printed "N of N entries verified ✓" at
+ * exit 0 over a corpus it had not fully read, and `quality` and `shrk doctor`
+ * agreed — only `self-config doctor` and `knowledge list` named it. The
+ * stale-check (an INVALID-class row), `quality`'s knowledge item and `shrk
+ * doctor` now read this ONE list, and each counts every entry on it as
+ * UNEXAMINED: exit 2 by default (`--fail-on invalid` makes it 1), never a pass.
+ *
+ * The list is never narrowed by a changeset: a refused entry's references were
+ * never read, so no scope can prove it untouched (the load-failure precedent).
+ *
+ * A `duplicate-id` rejection is NOT listed: the id it collided with belongs to
+ * an entry that IS checked (the first one wins), and the validator reports the
+ * duplicate — the precedent `seamRejectedRules` set for gate rules.
+ */
+import { RejectionCause } from '@shrkcrft/core';
+import { ContributionKind } from "./contribution-kind.js";
+import { collectContributionRejections, contributionFileLabel } from "./contribution-load-failures.js";
+/** Every contribution kind the knowledge loaders read (knowledge, rules, paths, path conventions, docs). */
+export const KNOWLEDGE_CONTRIBUTION_KINDS = [
+    ContributionKind.Knowledge,
+    ContributionKind.Rule,
+    ContributionKind.Path,
+    ContributionKind.PathConvention,
+    ContributionKind.Docs,
+];
+/** The label every surface prints before a refused entry's reasons. */
+export const REJECTED_AT_LOAD = 'rejected at load — not checked';
+/** `rejected at load — not checked: <reason>; <reason>` — THE row wording. */
+export function rejectedAtLoadMessage(reasons) {
+    return `${REJECTED_AT_LOAD}: ${reasons.join('; ')}`;
+}
+/**
+ * Every knowledge-family entry the loaders refused, in THE channel's order
+ * (file, then position), each with the file to edit and the owning pack.
+ * Synchronous: the knowledge loaders run at inspection time, so their
+ * rejections are already on `inspection.loaderDiagnostics`.
+ */
+export function knowledgeRejectedEntries(inspection) {
+    const out = [];
+    // A label names ONE refused declaration (the conventions-check precedent,
+    // round 15 follow-up F2): an id a loaded entry, or an earlier refused
+    // declaration, already holds is qualified by its declaration site — two
+    // refused `k.bad`s (a local one and a pack's) read `k.bad, k.bad` in every
+    // coverage list and shared one doctor check id.
+    const loaded = new Set(inspection.knowledgeEntries.map((e) => e.id));
+    const refusedIds = new Set();
+    for (const r of collectContributionRejections(inspection)) {
+        if (!KNOWLEDGE_CONTRIBUTION_KINDS.includes(r.kind) || r.cause === RejectionCause.DuplicateId)
+            continue;
+        const source = contributionFileLabel(inspection.projectRoot, r.file);
+        const at = r.index >= 0 ? `${r.exportName ?? 'default'}[${r.index}]` : r.exportName;
+        const site = at !== undefined ? `${source} ${at}` : source;
+        const label = r.entryId === undefined
+            ? site
+            : loaded.has(r.entryId) || refusedIds.has(r.entryId)
+                ? `${r.entryId} (${site})`
+                : r.entryId;
+        if (r.entryId !== undefined)
+            refusedIds.add(r.entryId);
+        out.push({
+            ...(r.entryId !== undefined ? { entryId: r.entryId } : {}),
+            label,
+            source,
+            ...(at !== undefined ? { at } : {}),
+            kind: r.kind,
+            ...(r.packageName !== undefined ? { pack: r.packageName } : {}),
+            reasons: r.reasons,
+            message: rejectedAtLoadMessage(r.reasons),
+        });
+    }
+    return out;
+}

package/dist/knowledge-entry-verdict-record.d.ts

@@ -0,0 +1,34 @@
+import type { KnowledgeSourceFormat } from '@shrkcrft/knowledge';
+import type { KnowledgeEntryVerdict } from './knowledge-entry-verdict.js';
+import type { KnowledgeUnverifiableReason } from './knowledge-unverifiable-reason.js';
+/** One entry in scope, classified — the unit the stale-check's coverage counts. */
+export interface IKnowledgeEntryVerdictRecord {
+    readonly entryId: string;
+    readonly verdict: KnowledgeEntryVerdict;
+    /** Set when {@link verdict} is `unverifiable`. */
+    readonly reason?: KnowledgeUnverifiableReason;
+    /**
+     * Where the entry is declared, relative to the project root
+     * (`sharkcraft/rules.ts`) — so the fix for an unverifiable entry names the
+     * file to edit. `(unknown source)` when the loader recorded none.
+     */
+    readonly source: string;
+    /**
+     * The format the entry is declared in (round 15) — what the remedy for an
+     * unverifiable entry names: `references[]` in TypeScript, a `references:`
+     * frontmatter list in Markdown.
+     */
+    readonly sourceFormat: KnowledgeSourceFormat;
+    /**
+     * The pack that contributed the entry (its package name) — absent for a
+     * local one. A pack entry is fixed upstream, or accepted locally.
+     */
+    readonly pack?: string;
+    /** The entry's knowledge `type` (`rule`, `path`, `technical`, …). */
+    readonly type: string;
+    /** References + anchors whose outcome was a real check (ok / stale / missing). */
+    readonly checkable: number;
+    /** Of {@link checkable}, how many did not resolve (stale / missing). */
+    readonly failing: number;
+}
+//# sourceMappingURL=knowledge-entry-verdict-record.d.ts.map

package/dist/knowledge-entry-verdict-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-entry-verdict-record.d.ts","sourceRoot":"","sources":["../src/knowledge-entry-verdict-record.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AAEtF,mFAAmF;AACnF,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,2BAA2B,CAAC;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,qBAAqB,CAAC;IAC7C;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B"}

package/dist/knowledge-entry-verdict-record.js

@@ -0,0 +1 @@
+export {};

package/dist/knowledge-entry-verdict.d.ts

@@ -0,0 +1,17 @@
+/**
+ * One entry's verdict in the staleness sweep — three buckets, never one.
+ *
+ * The sweep used to report only reference-level counts, so an entry that
+ * declared NO references contributed nothing and was folded into the healthy
+ * total: the less verifiable a corpus was, the healthier it looked. An entry
+ * the check could not examine is its own bucket, reported with its id.
+ */
+export declare enum KnowledgeEntryVerdict {
+    /** At least one reference / anchor was checked, and every checked one resolved. */
+    Verified = "verified",
+    /** At least one checked reference / anchor did not resolve. */
+    Stale = "stale",
+    /** Nothing about this entry could be checked — see its reason. */
+    Unverifiable = "unverifiable"
+}
+//# sourceMappingURL=knowledge-entry-verdict.d.ts.map

package/dist/knowledge-entry-verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-entry-verdict.d.ts","sourceRoot":"","sources":["../src/knowledge-entry-verdict.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,oBAAY,qBAAqB;IAC/B,mFAAmF;IACnF,QAAQ,aAAa;IACrB,+DAA+D;IAC/D,KAAK,UAAU;IACf,kEAAkE;IAClE,YAAY,iBAAiB;CAC9B"}

package/dist/knowledge-entry-verdict.js

@@ -0,0 +1,17 @@
+/**
+ * One entry's verdict in the staleness sweep — three buckets, never one.
+ *
+ * The sweep used to report only reference-level counts, so an entry that
+ * declared NO references contributed nothing and was folded into the healthy
+ * total: the less verifiable a corpus was, the healthier it looked. An entry
+ * the check could not examine is its own bucket, reported with its id.
+ */
+export var KnowledgeEntryVerdict;
+(function (KnowledgeEntryVerdict) {
+    /** At least one reference / anchor was checked, and every checked one resolved. */
+    KnowledgeEntryVerdict["Verified"] = "verified";
+    /** At least one checked reference / anchor did not resolve. */
+    KnowledgeEntryVerdict["Stale"] = "stale";
+    /** Nothing about this entry could be checked — see its reason. */
+    KnowledgeEntryVerdict["Unverifiable"] = "unverifiable";
+})(KnowledgeEntryVerdict || (KnowledgeEntryVerdict = {}));

package/dist/knowledge-graph.d.ts

@@ -22,6 +22,12 @@ export interface IKnowledgeGraph {
     edges: IGraphEdge[];
     /** Convenience: lookup by composite id (kind:id). */
     byId: ReadonlyMap<string, IGraphNode>;
+    /**
+     * Declared edges NOT drawn because an endpoint is not a node of this graph
+     * (a dangling id, or a kind the graph does not model). A shrunken graph says
+     * it shrank — `shrk self-config xrefs --dangling-only` lists the ids.
+     */
+    droppedEdges?: number;
 }
 /**
  * Build the full SharkCraft knowledge graph for the current inspection.

package/dist/knowledge-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge-graph.d.ts","sourceRoot":"","sources":["../src/knowledge-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,MAAM,GACN,MAAM,GACN,UAAU,GACV,UAAU,GACV,QAAQ,GACR,MAAM,GACN,UAAU,GACV,KAAK,CAAC;AAEV,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,iBAAiB,GACzB,kBAAkB,GAClB,cAAc,GACd,cAAc,GACd,iBAAiB,GACjB,mBAAmB,GACnB,0BAA0B,GAC1B,kBAAkB,GAClB,uBAAuB,GACvB,uBAAuB,GACvB,UAAU,CAAC;AAEf,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,qDAAqD;IACrD,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACvC;AAMD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,qBAAqB,GAAG,eAAe,CAyQtF;AAED,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,GAAG,CAAC,EAAE;QAAE,QAAQ,EAAE,iBAAiB,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAC7C,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC1C,UAAU,CA+DZ;AAgDD;;GAEG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE;IAAE,IAAI,CAAC,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACxC;IACD,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB,GAAG,IAAI,CA+BP"}
+{"version":3,"file":"knowledge-graph.d.ts","sourceRoot":"","sources":["../src/knowledge-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,MAAM,GACN,MAAM,GACN,UAAU,GACV,UAAU,GACV,QAAQ,GACR,MAAM,GACN,UAAU,GACV,KAAK,CAAC;AAEV,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,iBAAiB,GACzB,kBAAkB,GAClB,cAAc,GACd,cAAc,GACd,iBAAiB,GACjB,mBAAmB,GACnB,0BAA0B,GAC1B,kBAAkB,GAClB,uBAAuB,GACvB,uBAAuB,GACvB,UAAU,CAAC;AAEf,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,qDAAqD;IACrD,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACtC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,qBAAqB,GAAG,eAAe,CA0RtF;AAED,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,GAAG,CAAC,EAAE;QAAE,QAAQ,EAAE,iBAAiB,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAC7C,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC1C,UAAU,CA+DZ;AAgDD;;GAEG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE;IAAE,IAAI,CAAC,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACxC;IACD,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB,GAAG,IAAI,CA+BP"}

package/dist/knowledge-graph.js

@@ -9,6 +9,7 @@ export function buildKnowledgeGraph(inspection) {
     const nodes = [];
     const edges = [];
     const byId = new Map();
+    let droppedEdges = 0;
     function addNode(n) {
         const key = nodeKey(n.kind, n.id);
         if (byId.has(key))
@@ -19,10 +20,12 @@ export function buildKnowledgeGraph(inspection) {
     function addEdge(from, to, relation, why) {
         const fromKey = nodeKey(from.kind, from.id);
         const toKey = nodeKey(to.kind, to.id);
-        if (!byId.has(toKey))
-            return; // don't add edges to nodes we didn't see
-        if (!byId.has(fromKey))
+        // An edge to a node we didn't see is not drawn — but it is COUNTED, so the
+        // graph never reads as complete while it silently lost edges.
+        if (!byId.has(toKey) || !byId.has(fromKey)) {
+            droppedEdges += 1;
             return;
+        }
         edges.push({ from: fromKey, to: toKey, relation, why });
     }
     function sourceOf(map, id) {
@@ -142,8 +145,10 @@ export function buildKnowledgeGraph(inspection) {
                             : byId.has(kKey)
                                 ? 'knowledge'
                                 : null;
-                if (!targetKind)
+                if (!targetKind) {
+                    droppedEdges += 1;
                     continue;
+                }
                 addEdge({ kind: 'pipeline', id: pipeline.id }, { kind: targetKind, id: ref }, 'pipeline-step-references', `step ${step.id} references`);
             }
         }
@@ -157,11 +162,17 @@ export function buildKnowledgeGraph(inspection) {
             addEdge({ kind: 'boundary', id: r.id }, { kind: 'path', id }, 'boundary-related-path', 'relatedPathConventions');
         }
     }
-    // Pack contributions: pack → its contributed items.
+    // Pack contributions: pack → its contributed items. A contributed rule or
+    // path convention is a `rule:` / `path:` node, not a `knowledge:` one — the
+    // edge used to target `knowledge:<id>` and was silently dropped for both.
+    const entryKinds = new Map();
+    for (const e of inspection.knowledgeEntries) {
+        entryKinds.set(e.id, String(e.type) === 'rule' ? 'rule' : String(e.type) === 'path' ? 'path' : 'knowledge');
+    }
     for (const [id, src] of inspection.entrySources) {
         if (src.type !== 'pack' || !src.packageName)
             continue;
-        addEdge({ kind: 'pack', id: src.packageName }, { kind: 'knowledge', id }, 'pack-contributes', 'knowledge entry');
+        addEdge({ kind: 'pack', id: src.packageName }, { kind: entryKinds.get(id) ?? 'knowledge', id }, 'pack-contributes', 'knowledge entry');
     }
     for (const [id, src] of inspection.templateSources) {
         if (src.type !== 'pack' || !src.packageName)
@@ -183,7 +194,7 @@ export function buildKnowledgeGraph(inspection) {
             continue;
         addEdge({ kind: 'pack', id: src.packageName }, { kind: 'boundary', id }, 'pack-contributes', 'boundary rule');
     }
-    return { nodes, edges, byId };
+    return { nodes, edges, byId, droppedEdges };
 }
 /**
  * Find the shortest directed path (BFS) between two graph nodes. Edges are

package/dist/knowledge-kind-bucket.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Per-kind counts of a staleness sweep — by asset kind (knowledge / boundary
+ * rule / policy) and by knowledge entry `type`.
+ *
+ * `scanned: 0` means the kind was NOT IN THE SWEEP, which a renderer must say
+ * in words — a row of zeros cannot tell "clean" from "never looked".
+ */
+export interface IKnowledgeKindBucket {
+    /** Subjects of this kind the sweep visited. */
+    scanned: number;
+    /** Of those, how many declare no references / anchors at all. */
+    zeroReferences: number;
+    /** References + anchors checked for this kind. */
+    referencesChecked: number;
+    verified: number;
+    stale: number;
+    unverifiable: number;
+}
+//# sourceMappingURL=knowledge-kind-bucket.d.ts.map

package/dist/knowledge-kind-bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-kind-bucket.d.ts","sourceRoot":"","sources":["../src/knowledge-kind-bucket.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB"}

package/dist/knowledge-kind-bucket.js

@@ -0,0 +1 @@
+export {};

package/dist/knowledge-load-failure.d.ts

@@ -0,0 +1,23 @@
+/**
+ * One knowledge-bearing file (`knowledgeFiles` / `ruleFiles` / `pathFiles` /
+ * `docsFiles`, local or pack-contributed) whose entries never reached the
+ * corpus — it failed to import, timed out, was skipped as a cached failure, or
+ * is declared by the config and does not exist.
+ *
+ * Read off `inspection.loaderDiagnostics` (the ONE record of what each loader
+ * did) by `describeInspectionDiscovery`. A corpus verdict over a load failure
+ * examined part of what it was told to, so it is never a pass.
+ */
+export interface IKnowledgeLoadFailure {
+    /** Project-relative when inside the project, else absolute. */
+    readonly file: string;
+    /** The loader slot (`knowledge` / `rules` / `paths` / `docs`). */
+    readonly kind: string;
+    /** `failed` / `timeout` / `cached-failed` / `missing`. */
+    readonly status: string;
+    /** The loader's message (the import error), or why nothing was read. */
+    readonly message: string;
+    /** Set for a pack-contributed file. */
+    readonly packName?: string;
+}
+//# sourceMappingURL=knowledge-load-failure.d.ts.map

package/dist/knowledge-load-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-load-failure.d.ts","sourceRoot":"","sources":["../src/knowledge-load-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B"}

package/dist/knowledge-load-failure.js

@@ -0,0 +1 @@
+export {};

package/dist/knowledge-min-referenced-valve.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Which `minReferenced` valve a surface can name. `shrk knowledge stale-check`
+ * takes the flag; `shrk quality` refuses `--min-referenced` (exit 3) and reads
+ * the config block only — so its remedy names `knowledgeCheck.minReferenced`.
+ */
+export declare enum KnowledgeMinReferencedValve {
+    /** `--min-referenced <ratio>` on the verb (the config key works there too). */
+    Flag = "flag",
+    /** `knowledgeCheck.minReferenced` in `sharkcraft.config.ts` — the only valve `quality` reads. */
+    Config = "config"
+}
+//# sourceMappingURL=knowledge-min-referenced-valve.d.ts.map

package/dist/knowledge-min-referenced-valve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-min-referenced-valve.d.ts","sourceRoot":"","sources":["../src/knowledge-min-referenced-valve.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,oBAAY,2BAA2B;IACrC,+EAA+E;IAC/E,IAAI,SAAS;IACb,iGAAiG;IACjG,MAAM,WAAW;CAClB"}

package/dist/knowledge-min-referenced-valve.js

@@ -0,0 +1,12 @@
+/**
+ * Which `minReferenced` valve a surface can name. `shrk knowledge stale-check`
+ * takes the flag; `shrk quality` refuses `--min-referenced` (exit 3) and reads
+ * the config block only — so its remedy names `knowledgeCheck.minReferenced`.
+ */
+export var KnowledgeMinReferencedValve;
+(function (KnowledgeMinReferencedValve) {
+    /** `--min-referenced <ratio>` on the verb (the config key works there too). */
+    KnowledgeMinReferencedValve["Flag"] = "flag";
+    /** `knowledgeCheck.minReferenced` in `sharkcraft.config.ts` — the only valve `quality` reads. */
+    KnowledgeMinReferencedValve["Config"] = "config";
+})(KnowledgeMinReferencedValve || (KnowledgeMinReferencedValve = {}));

package/dist/knowledge-reference-kind-bucket.d.ts

@@ -0,0 +1,11 @@
+/** Per-reference-kind outcome counts of a staleness sweep (`file`, `symbol`, `template`, …). */
+export interface IKnowledgeReferenceKindBucket {
+    checked: number;
+    ok: number;
+    stale: number;
+    missing: number;
+    unknown: number;
+    /** Malformed references of this kind (a missing required field) — never checked. */
+    invalid: number;
+}
+//# sourceMappingURL=knowledge-reference-kind-bucket.d.ts.map

package/dist/knowledge-reference-kind-bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-reference-kind-bucket.d.ts","sourceRoot":"","sources":["../src/knowledge-reference-kind-bucket.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/knowledge-reference-kind-bucket.js

@@ -0,0 +1 @@
+export {};

package/dist/knowledge-rejected-entry.d.ts

@@ -0,0 +1,28 @@
+import type { ContributionKind } from './contribution-kind.js';
+/**
+ * One knowledge-family entry (knowledge / rule / path / docs) its loader
+ * REFUSED — read off THE rejection channel by `knowledgeRejectedEntries`
+ * (round 15 follow-up, F3). The entry never reached the corpus, so nothing it
+ * claims was checked: the stale-check prints it as an INVALID-class row, the
+ * `quality` knowledge item and `shrk doctor` name it, and every one of them
+ * counts it UNEXAMINED — never a clean pass.
+ */
+export interface IKnowledgeRejectedEntry {
+    /** The id the entry declared, when it declared one. */
+    readonly entryId?: string;
+    /** What a row names it by: the id, else `<file> <where>` (or the file alone). */
+    readonly label: string;
+    /** The declaring file — project-relative (POSIX), absolute outside the project. */
+    readonly source: string;
+    /** Where in the file (`default[1]`, a named export), when the loader recorded a position. */
+    readonly at?: string;
+    /** The contribution kind whose loader refused it. */
+    readonly kind: ContributionKind;
+    /** The pack that contributed the file — absent for a local one. */
+    readonly pack?: string;
+    /** Why the loader refused it, as the loader said. */
+    readonly reasons: readonly string[];
+    /** THE row wording: `rejected at load — not checked: <reasons>`. */
+    readonly message: string;
+}
+//# sourceMappingURL=knowledge-rejected-entry.d.ts.map

package/dist/knowledge-rejected-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-rejected-entry.d.ts","sourceRoot":"","sources":["../src/knowledge-rejected-entry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC,uDAAuD;IACvD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,mEAAmE;IACnE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B"}

package/dist/knowledge-rejected-entry.js

@@ -0,0 +1 @@
+export {};