@shrkcrft/inspector 0.1.0-alpha.1

package/dist/knowledge-authoring.js

@@ -0,0 +1,586 @@
+/**
+ * Knowledge authoring preview.
+ *
+ * Pure, deterministic builders that take a structured authoring request
+ * (add / update / remove) and return a draft + patch preview. Preview-only:
+ * this module never writes — the CLI adapter materialises the preview under
+ * `.sharkcraft/authoring/` (drafts) or `.sharkcraft/fixes/` (lint output).
+ *
+ * Hard rules:
+ *   - No mutation of `sharkcraft/knowledge.ts` or any pack `assets/knowledge.ts`.
+ *   - Generated content references real, deterministic IKnowledgeEntry fields.
+ *   - Add refuses to overwrite an existing id unless told to.
+ *   - Update preserves all unspecified fields verbatim.
+ *   - Remove always reports reverse references and refuses by default if any
+ *     remain.
+ */
+export const KNOWLEDGE_AUTHORING_SCHEMA = 'sharkcraft.knowledge-authoring/v1';
+export var KnowledgeAuthoringOperation;
+(function (KnowledgeAuthoringOperation) {
+    KnowledgeAuthoringOperation["Add"] = "add";
+    KnowledgeAuthoringOperation["Update"] = "update";
+    KnowledgeAuthoringOperation["Remove"] = "remove";
+})(KnowledgeAuthoringOperation || (KnowledgeAuthoringOperation = {}));
+const ID_RE = /^[a-z0-9]+([.\-][a-z0-9]+)*$/;
+function nowIso() {
+    return new Date().toISOString();
+}
+function clone(v) {
+    return JSON.parse(JSON.stringify(v));
+}
+function idToConst(id) {
+    return id
+        .split(/[.\-]/)
+        .map((p, i) => (i === 0 ? p : p.charAt(0).toUpperCase() + p.slice(1)))
+        .join('');
+}
+function fileSafeId(id) {
+    return id.replace(/[^a-zA-Z0-9]+/g, '-');
+}
+function tsScalar(v) {
+    return JSON.stringify(v ?? null);
+}
+function tsArray(items, indent) {
+    if (items.length === 0)
+        return '[]';
+    return ('[\n' +
+        items.map((it) => `${indent}  ${JSON.stringify(it)},`).join('\n') +
+        `\n${indent}]`);
+}
+function tsObject(value, indent) {
+    // We keep this conservative — the goal is a TS-pasteable literal, not a
+    // full TS pretty-printer. JSON-compatible values only.
+    return (JSON.stringify(value, null, 2)
+        .split('\n')
+        .map((line, idx) => (idx === 0 ? line : indent + line))
+        .join('\n'));
+}
+function findReverseReferences(entries, targetId) {
+    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' });
+            }
+        }
+        for (const ref of e.references ?? []) {
+            if (ref.id === targetId) {
+                out.push({ fromEntryId: e.id, field: 'reference.id', note: ref.note });
+            }
+        }
+        for (const a of e.anchors ?? []) {
+            if (a.targetId === targetId) {
+                out.push({ fromEntryId: e.id, field: 'anchor.targetId', note: a.description });
+            }
+        }
+    }
+    return out;
+}
+function buildEntryFromAdd(input) {
+    return {
+        id: input.id,
+        title: input.title ?? input.id,
+        type: input.type ?? 'documentation',
+        priority: input.priority ?? 'medium',
+        scope: input.scope ? [...input.scope] : [],
+        tags: input.tags ? [...input.tags] : [],
+        appliesWhen: input.appliesWhen ? [...input.appliesWhen] : [],
+        content: input.content ?? `TODO: describe ${input.id}.`,
+        ...(input.summary ? { summary: input.summary } : {}),
+        ...(input.related ? { related: [...input.related] } : {}),
+        ...(input.references ? { references: input.references.map(clone) } : {}),
+        ...(input.anchors ? { anchors: input.anchors.map(clone) } : {}),
+        ...(input.actionHints ? { actionHints: clone(input.actionHints) } : {}),
+        ...(input.reason
+            ? { metadata: { authoring: { reason: input.reason, generatedAt: nowIso() } } }
+            : {}),
+    };
+}
+function applyUpdateOps(current, ops, changes) {
+    const next = clone(current);
+    if (ops.setSummary !== undefined) {
+        changes.push({ op: 'replace', field: 'summary', before: current.summary, after: ops.setSummary });
+        next.summary = ops.setSummary;
+    }
+    if (ops.setContent !== undefined) {
+        changes.push({ op: 'replace', field: 'content', before: current.content, after: ops.setContent });
+        next.content = ops.setContent;
+    }
+    if (ops.setPriority !== undefined) {
+        changes.push({ op: 'replace', field: 'priority', before: current.priority, after: ops.setPriority });
+        next.priority = ops.setPriority;
+    }
+    if (ops.addRelated && ops.addRelated.length > 0) {
+        const existing = new Set(next.related ?? []);
+        const added = [];
+        for (const r of ops.addRelated) {
+            if (!existing.has(r)) {
+                existing.add(r);
+                added.push(r);
+            }
+        }
+        next.related = [...existing];
+        if (added.length > 0) {
+            changes.push({ op: 'add', field: 'related', after: added });
+        }
+    }
+    if (ops.removeRelated && ops.removeRelated.length > 0) {
+        const keep = (next.related ?? []).filter((r) => !ops.removeRelated.includes(r));
+        const removed = (next.related ?? []).filter((r) => ops.removeRelated.includes(r));
+        next.related = keep;
+        if (removed.length > 0) {
+            changes.push({ op: 'remove', field: 'related', before: removed });
+        }
+    }
+    if (ops.addReferences && ops.addReferences.length > 0) {
+        const merged = [...(next.references ?? [])];
+        const added = [];
+        for (const r of ops.addReferences) {
+            const dup = merged.find((m) => m.kind === r.kind &&
+                (m.id ?? '') === (r.id ?? '') &&
+                (m.path ?? '') === (r.path ?? '') &&
+                (m.symbol ?? '') === (r.symbol ?? ''));
+            if (!dup) {
+                merged.push(clone(r));
+                added.push(r);
+            }
+        }
+        next.references = merged;
+        if (added.length > 0) {
+            changes.push({ op: 'add', field: 'references', after: added });
+        }
+    }
+    if (ops.removeReferences && ops.removeReferences.length > 0) {
+        const before = next.references ?? [];
+        const keep = before.filter((m) => {
+            return !ops.removeReferences.some((rm) => m.kind === rm.kind &&
+                (m.id ?? '') === (rm.id ?? '') &&
+                (m.path ?? '') === (rm.path ?? '') &&
+                (m.symbol ?? '') === (rm.symbol ?? ''));
+        });
+        const removed = before.filter((m) => !keep.includes(m));
+        next.references = keep;
+        if (removed.length > 0) {
+            changes.push({ op: 'remove', field: 'references', before: removed });
+        }
+    }
+    if (ops.addAnchors && ops.addAnchors.length > 0) {
+        const merged = [...(next.anchors ?? [])];
+        const added = [];
+        for (const a of ops.addAnchors) {
+            if (!merged.some((m) => m.id === a.id)) {
+                merged.push(clone(a));
+                added.push(a);
+            }
+        }
+        next.anchors = merged;
+        if (added.length > 0) {
+            changes.push({ op: 'add', field: 'anchors', after: added });
+        }
+    }
+    if (ops.removeAnchorIds && ops.removeAnchorIds.length > 0) {
+        const before = next.anchors ?? [];
+        const keep = before.filter((a) => !ops.removeAnchorIds.includes(a.id));
+        const removed = before.filter((a) => ops.removeAnchorIds.includes(a.id));
+        next.anchors = keep;
+        if (removed.length > 0) {
+            changes.push({ op: 'remove', field: 'anchors', before: removed });
+        }
+    }
+    if (ops.markDeprecated) {
+        const md = (next.metadata ?? {});
+        if (!md.deprecated) {
+            next.metadata = { ...md, deprecated: true };
+            changes.push({ op: 'add', field: 'metadata.deprecated', after: true });
+        }
+    }
+    if (ops.unmarkDeprecated) {
+        const md = (next.metadata ?? {});
+        if (md.deprecated) {
+            const { deprecated, ...rest } = md;
+            void deprecated;
+            next.metadata = rest;
+            changes.push({ op: 'remove', field: 'metadata.deprecated', before: true });
+        }
+    }
+    return next;
+}
+function buildTsDraft(entry, op) {
+    const constName = idToConst(entry.id);
+    const fields = [];
+    fields.push(`  id: ${tsScalar(entry.id)},`);
+    fields.push(`  title: ${tsScalar(entry.title)},`);
+    fields.push(`  type: ${tsScalar(entry.type)},`);
+    fields.push(`  priority: ${tsScalar(entry.priority)},`);
+    fields.push(`  scope: ${tsArray(entry.scope, '  ')},`);
+    fields.push(`  tags: ${tsArray(entry.tags, '  ')},`);
+    fields.push(`  appliesWhen: ${tsArray(entry.appliesWhen, '  ')},`);
+    if (entry.summary)
+        fields.push(`  summary: ${tsScalar(entry.summary)},`);
+    fields.push(`  content: ${tsScalar(entry.content)},`);
+    if (entry.related && entry.related.length > 0)
+        fields.push(`  related: ${tsArray(entry.related, '  ')},`);
+    if (entry.references && entry.references.length > 0)
+        fields.push(`  references: ${tsObject(entry.references, '  ')},`);
+    if (entry.anchors && entry.anchors.length > 0)
+        fields.push(`  anchors: ${tsObject(entry.anchors, '  ')},`);
+    if (entry.actionHints)
+        fields.push(`  actionHints: ${tsObject(entry.actionHints, '  ')},`);
+    if (entry.metadata)
+        fields.push(`  metadata: ${tsObject(entry.metadata, '  ')},`);
+    return (`// Generated by \`shrk knowledge ${op}\` (preview only — not yet written).\n` +
+        `// Paste into sharkcraft/knowledge.ts or a pack's assets/knowledge.ts.\n` +
+        `\n` +
+        `export const ${constName} = {\n` +
+        fields.join('\n') +
+        '\n};\n');
+}
+function buildJsonManifest(result) {
+    return JSON.stringify(result, null, 2) + '\n';
+}
+function buildExplainer(input, result) {
+    const op = result.operation;
+    const lines = [];
+    lines.push(`# Knowledge authoring preview — ${op} ${result.entryId}`);
+    lines.push('');
+    if (!result.ok) {
+        lines.push(`> Refused: ${result.refusal ?? 'unknown reason'}.`);
+        lines.push('');
+    }
+    lines.push(`Generated: ${nowIso()}`);
+    lines.push('');
+    lines.push(`## What this preview is`);
+    lines.push('');
+    lines.push(`Preview-only. Nothing was written to \`sharkcraft/knowledge.ts\` or to any pack's \`assets/knowledge.ts\`. ` +
+        'The TypeScript draft on disk is a copy you (or an agent) can paste into the canonical file.');
+    lines.push('');
+    if (input.reason) {
+        lines.push(`## Reason`);
+        lines.push('');
+        lines.push(input.reason);
+        lines.push('');
+    }
+    if (result.reverseReferences && result.reverseReferences.length > 0) {
+        lines.push(`## Reverse references`);
+        lines.push('');
+        for (const rr of result.reverseReferences) {
+            lines.push(`- \`${rr.fromEntryId}\` → \`${rr.field}\`${rr.note ? ` — ${rr.note}` : ''}`);
+        }
+        lines.push('');
+    }
+    if (result.suggestedDeprecationInstead) {
+        lines.push(`## Suggested safer alternative`);
+        lines.push('');
+        lines.push('This entry is referenced elsewhere. Removing it can produce stale references. ' +
+            `Consider marking it deprecated instead by running:\n\n` +
+            '```\n' +
+            `shrk knowledge update ${result.entryId} --mark-deprecated --reason "<why>"\n` +
+            '```');
+        lines.push('');
+    }
+    lines.push(`## Next commands`);
+    lines.push('');
+    for (const c of result.nextCommands)
+        lines.push(`- \`${c}\``);
+    lines.push('');
+    return lines.join('\n');
+}
+function buildResultFiles(entryId, op, tsBody, manifestBody, explainerBody) {
+    const slug = fileSafeId(entryId);
+    return {
+        tsDraft: {
+            path: `.sharkcraft/authoring/knowledge-${op}-${slug}.draft.ts`,
+            body: tsBody,
+            language: 'typescript',
+        },
+        jsonManifest: {
+            path: `.sharkcraft/authoring/knowledge-${op}-${slug}.manifest.json`,
+            body: manifestBody,
+            language: 'json',
+        },
+        explainer: {
+            path: `.sharkcraft/authoring/knowledge-${op}-${slug}.md`,
+            body: explainerBody,
+            language: 'markdown',
+        },
+    };
+}
+export function buildKnowledgeAuthoringPreview(input, context) {
+    const warnings = [];
+    if (!ID_RE.test(input.id)) {
+        warnings.push(`id "${input.id}" does not match the recommended pattern <namespace>.<kebab-id>.`);
+    }
+    const existing = context.entries.find((e) => e.id === input.id);
+    switch (input.operation) {
+        case KnowledgeAuthoringOperation.Add: {
+            if (existing && !input.allowOverwrite) {
+                const refused = {
+                    schema: KNOWLEDGE_AUTHORING_SCHEMA,
+                    generatedAt: nowIso(),
+                    operation: input.operation,
+                    entryId: input.id,
+                    ok: false,
+                    refusal: `An entry with id "${input.id}" already exists. Use \`shrk knowledge update ${input.id}\` instead, or pass --allow-overwrite to draft a replacement.`,
+                    tsDraft: emptyDraftFile(input.id, input.operation, 'typescript'),
+                    jsonManifest: emptyDraftFile(input.id, input.operation, 'json'),
+                    explainer: emptyDraftFile(input.id, input.operation, 'markdown'),
+                    warnings,
+                    nextCommands: [`shrk knowledge update ${input.id} --reason "<why>"`],
+                    current: existing,
+                };
+                const files = buildResultFiles(input.id, input.operation, '// Refused — entry already exists.\n', buildJsonManifest(refused), buildExplainer(input, refused));
+                refused.tsDraft = files.tsDraft;
+                refused.jsonManifest = files.jsonManifest;
+                refused.explainer = files.explainer;
+                return refused;
+            }
+            const next = buildEntryFromAdd(input);
+            if (!input.reason)
+                warnings.push('No --reason provided. Provenance entry will record source only.');
+            if (!input.summary && !input.content)
+                warnings.push('Neither --summary nor --content provided. Body is a TODO stub.');
+            const result = {
+                schema: KNOWLEDGE_AUTHORING_SCHEMA,
+                generatedAt: nowIso(),
+                operation: input.operation,
+                entryId: input.id,
+                ok: true,
+                tsDraft: emptyDraftFile(input.id, input.operation, 'typescript'),
+                jsonManifest: emptyDraftFile(input.id, input.operation, 'json'),
+                explainer: emptyDraftFile(input.id, input.operation, 'markdown'),
+                warnings,
+                next,
+                nextCommands: nextCommandsForAdd(input),
+            };
+            const files = buildResultFiles(input.id, input.operation, buildTsDraft(next, input.operation), buildJsonManifest({
+                schema: KNOWLEDGE_AUTHORING_SCHEMA,
+                generatedAt: result.generatedAt,
+                operation: result.operation,
+                entryId: result.entryId,
+                ok: true,
+                next,
+                warnings,
+            }), buildExplainer(input, result));
+            result.tsDraft = files.tsDraft;
+            result.jsonManifest = files.jsonManifest;
+            result.explainer = files.explainer;
+            return result;
+        }
+        case KnowledgeAuthoringOperation.Update: {
+            if (!existing) {
+                const refused = {
+                    schema: KNOWLEDGE_AUTHORING_SCHEMA,
+                    generatedAt: nowIso(),
+                    operation: input.operation,
+                    entryId: input.id,
+                    ok: false,
+                    refusal: `No entry with id "${input.id}" exists. Use \`shrk knowledge add\` instead.`,
+                    tsDraft: emptyDraftFile(input.id, input.operation, 'typescript'),
+                    jsonManifest: emptyDraftFile(input.id, input.operation, 'json'),
+                    explainer: emptyDraftFile(input.id, input.operation, 'markdown'),
+                    warnings,
+                    nextCommands: [`shrk knowledge add --id ${input.id}`],
+                };
+                const files = buildResultFiles(input.id, input.operation, '// Refused — entry does not exist.\n', buildJsonManifest(refused), buildExplainer(input, refused));
+                refused.tsDraft = files.tsDraft;
+                refused.jsonManifest = files.jsonManifest;
+                refused.explainer = files.explainer;
+                return refused;
+            }
+            const changes = [];
+            const next = input.updateOps
+                ? applyUpdateOps(existing, input.updateOps, changes)
+                : applyUpdateOps(existing, deriveOpsFromInput(input), changes);
+            if (changes.length === 0) {
+                warnings.push('No updateOps produced changes. Preview will mirror the existing entry.');
+            }
+            const result = {
+                schema: KNOWLEDGE_AUTHORING_SCHEMA,
+                generatedAt: nowIso(),
+                operation: input.operation,
+                entryId: input.id,
+                ok: true,
+                tsDraft: emptyDraftFile(input.id, input.operation, 'typescript'),
+                jsonManifest: emptyDraftFile(input.id, input.operation, 'json'),
+                explainer: emptyDraftFile(input.id, input.operation, 'markdown'),
+                warnings,
+                current: existing,
+                next,
+                patch: {
+                    schema: 'sharkcraft.knowledge-authoring-patch/v1',
+                    operation: input.operation,
+                    entryId: input.id,
+                    changes,
+                },
+                nextCommands: nextCommandsForUpdate(input),
+            };
+            const files = buildResultFiles(input.id, input.operation, buildTsDraft(next, input.operation), buildJsonManifest({
+                schema: KNOWLEDGE_AUTHORING_SCHEMA,
+                generatedAt: result.generatedAt,
+                operation: result.operation,
+                entryId: result.entryId,
+                ok: true,
+                current: existing,
+                next,
+                patch: result.patch,
+                warnings,
+            }), buildExplainer(input, result));
+            result.tsDraft = files.tsDraft;
+            result.jsonManifest = files.jsonManifest;
+            result.explainer = files.explainer;
+            return result;
+        }
+        case KnowledgeAuthoringOperation.Remove: {
+            if (!existing) {
+                const refused = {
+                    schema: KNOWLEDGE_AUTHORING_SCHEMA,
+                    generatedAt: nowIso(),
+                    operation: input.operation,
+                    entryId: input.id,
+                    ok: false,
+                    refusal: `No entry with id "${input.id}" exists — nothing to remove.`,
+                    tsDraft: emptyDraftFile(input.id, input.operation, 'typescript'),
+                    jsonManifest: emptyDraftFile(input.id, input.operation, 'json'),
+                    explainer: emptyDraftFile(input.id, input.operation, 'markdown'),
+                    warnings,
+                    nextCommands: [],
+                };
+                const files = buildResultFiles(input.id, input.operation, '// Refused — entry does not exist.\n', buildJsonManifest(refused), buildExplainer(input, refused));
+                refused.tsDraft = files.tsDraft;
+                refused.jsonManifest = files.jsonManifest;
+                refused.explainer = files.explainer;
+                return refused;
+            }
+            const reverseReferences = findReverseReferences(context.entries, input.id);
+            if (reverseReferences.length > 0 && !input.forcePreview) {
+                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\`.`,
+                    tsDraft: emptyDraftFile(input.id, input.operation, 'typescript'),
+                    jsonManifest: emptyDraftFile(input.id, input.operation, 'json'),
+                    explainer: emptyDraftFile(input.id, input.operation, 'markdown'),
+                    warnings,
+                    reverseReferences,
+                    suggestedDeprecationInstead: true,
+                    current: existing,
+                    nextCommands: [
+                        `shrk knowledge update ${input.id} --mark-deprecated --reason "${input.reason ?? '<why>'}"`,
+                        `shrk knowledge remove ${input.id} --force-preview --reason "${input.reason ?? '<why>'}"`,
+                    ],
+                };
+                const files = buildResultFiles(input.id, input.operation, `// Refused — ${reverseReferences.length} reverse reference(s). See manifest.\n`, buildJsonManifest(refused), buildExplainer(input, refused));
+                refused.tsDraft = files.tsDraft;
+                refused.jsonManifest = files.jsonManifest;
+                refused.explainer = files.explainer;
+                return refused;
+            }
+            const result = {
+                schema: KNOWLEDGE_AUTHORING_SCHEMA,
+                generatedAt: nowIso(),
+                operation: input.operation,
+                entryId: input.id,
+                ok: true,
+                tsDraft: emptyDraftFile(input.id, input.operation, 'typescript'),
+                jsonManifest: emptyDraftFile(input.id, input.operation, 'json'),
+                explainer: emptyDraftFile(input.id, input.operation, 'markdown'),
+                warnings,
+                reverseReferences,
+                current: existing,
+                patch: {
+                    schema: 'sharkcraft.knowledge-authoring-patch/v1',
+                    operation: input.operation,
+                    entryId: input.id,
+                    changes: [{ op: 'remove', field: '*', before: existing }],
+                },
+                nextCommands: nextCommandsForRemove(input),
+            };
+            const files = buildResultFiles(input.id, input.operation, buildRemovalNotice(existing), buildJsonManifest({
+                schema: KNOWLEDGE_AUTHORING_SCHEMA,
+                generatedAt: result.generatedAt,
+                operation: result.operation,
+                entryId: result.entryId,
+                ok: true,
+                current: existing,
+                reverseReferences,
+                warnings,
+            }), buildExplainer(input, result));
+            result.tsDraft = files.tsDraft;
+            result.jsonManifest = files.jsonManifest;
+            result.explainer = files.explainer;
+            return result;
+        }
+    }
+}
+function buildRemovalNotice(entry) {
+    return (`// Knowledge removal preview for ${entry.id}.\n` +
+        `// Delete the following const from the knowledge file:\n` +
+        `//\n` +
+        entry.content
+            .split('\n')
+            .slice(0, 6)
+            .map((l) => `//   ${l}`)
+            .join('\n') +
+        `\n`);
+}
+function deriveOpsFromInput(input) {
+    // When the caller passes flat fields instead of an explicit updateOps
+    // block, derive the conservative ops it implies. We only set fields the
+    // caller explicitly provided.
+    const ops = {};
+    if (input.summary !== undefined)
+        ops.setSummary = input.summary;
+    if (input.content !== undefined)
+        ops.setContent = input.content;
+    if (input.priority !== undefined)
+        ops.setPriority = input.priority;
+    if (input.references && input.references.length > 0)
+        ops.addReferences = input.references;
+    if (input.anchors && input.anchors.length > 0)
+        ops.addAnchors = input.anchors;
+    if (input.related && input.related.length > 0)
+        ops.addRelated = input.related;
+    return ops;
+}
+function nextCommandsForAdd(input) {
+    const targetHint = input.target?.filePath
+        ? `# Target: ${input.target.filePath}`
+        : '# Target: sharkcraft/knowledge.ts (or a pack assets/knowledge.ts)';
+    return [
+        targetHint,
+        `shrk knowledge stale-check --ci`,
+        `shrk self-config doctor`,
+        `shrk packs signature-status`,
+        `# Pack edits make signatures stale — see \`shrk packs sign --print-command\` when secret is available.`,
+    ];
+}
+function nextCommandsForUpdate(input) {
+    return [
+        `# Apply the patch to ${input.target?.filePath ?? 'the knowledge file that owns this entry'}.`,
+        `shrk knowledge stale-check --ci`,
+        `shrk self-config doctor`,
+        `shrk packs signature-status`,
+    ];
+}
+function nextCommandsForRemove(input) {
+    return [
+        `# Delete the entry from ${input.target?.filePath ?? 'the knowledge file that owns this entry'}.`,
+        `shrk knowledge stale-check --ci`,
+        `shrk self-config doctor`,
+        `shrk packs signature-status`,
+    ];
+}
+function emptyDraftFile(id, op, language) {
+    const slug = fileSafeId(id);
+    const ext = language === 'typescript' ? 'draft.ts' : language === 'json' ? 'manifest.json' : 'md';
+    return {
+        path: `.sharkcraft/authoring/knowledge-${op}-${slug}.${ext}`,
+        body: '',
+        language,
+    };
+}

package/dist/knowledge-graph.d.ts

@@ -0,0 +1,76 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export type GraphNodeKind = 'knowledge' | 'rule' | 'path' | 'template' | 'pipeline' | 'preset' | 'pack' | 'boundary' | 'doc';
+export interface IGraphNode {
+    id: string;
+    kind: GraphNodeKind;
+    title: string;
+    /** Optional one-line summary. */
+    summary?: string;
+    /** Source: builtin | local | pack:<name> */
+    source: string;
+}
+export type GraphEdgeRelation = 'related-template' | 'related-path' | 'related-rule' | 'preset-includes' | 'preset-references' | 'pipeline-step-references' | 'pack-contributes' | 'boundary-related-rule' | 'boundary-related-path' | 'composes';
+export interface IGraphEdge {
+    from: string;
+    to: string;
+    relation: GraphEdgeRelation;
+    /** Free-form note explaining why the edge exists. */
+    why: string;
+}
+export interface IKnowledgeGraph {
+    nodes: IGraphNode[];
+    edges: IGraphEdge[];
+    /** Convenience: lookup by composite id (kind:id). */
+    byId: ReadonlyMap<string, IGraphNode>;
+}
+/**
+ * Build the full SharkCraft knowledge graph for the current inspection.
+ * Pure — no I/O beyond what the inspection already cached.
+ */
+export declare function buildKnowledgeGraph(inspection: ISharkcraftInspection): IKnowledgeGraph;
+export interface IGraphPathStep {
+    /** Composite node key `kind:id`. */
+    node: string;
+    /** Edge that led into this node (undefined for the start). */
+    via?: {
+        relation: GraphEdgeRelation;
+        why: string;
+    };
+}
+export interface IGraphPath {
+    found: boolean;
+    steps: IGraphPathStep[];
+    /** When found=false: short reason ("from missing", "to missing", "no path"). */
+    reason?: string;
+    /**
+     * When found=false: a longer, kind-aware explanation that says why
+     * the path doesn't exist and what to try instead. Renderers prefer
+     * this over `reason` when present. Optional for back-compat — JSON
+     * consumers that pin `reason` keep working.
+     */
+    explanation?: string;
+}
+/**
+ * Find the shortest directed path (BFS) between two graph nodes. Edges are
+ * treated in the direction they were added. Returns the node sequence with
+ * the edge that landed on each step explained.
+ */
+export declare function findGraphPath(graph: IKnowledgeGraph, fromRef: {
+    kind?: GraphNodeKind;
+    id: string;
+}, toRef: {
+    kind?: GraphNodeKind;
+    id: string;
+}): IGraphPath;
+/**
+ * Get a node + its incoming/outgoing edges grouped by kind.
+ */
+export declare function getGraphNode(graph: IKnowledgeGraph, ref: {
+    kind?: GraphNodeKind;
+    id: string;
+}): {
+    node: IGraphNode | null;
+    incoming: IGraphEdge[];
+    outgoing: IGraphEdge[];
+} | null;
+//# sourceMappingURL=knowledge-graph.d.ts.map

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

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