@shrkcrft/inspector 0.1.0-alpha.2

package/dist/knowledge-graph.js

@@ -0,0 +1,336 @@
+function nodeKey(kind, id) {
+    return `${kind}:${id}`;
+}
+/**
+ * Build the full SharkCraft knowledge graph for the current inspection.
+ * Pure — no I/O beyond what the inspection already cached.
+ */
+export function buildKnowledgeGraph(inspection) {
+    const nodes = [];
+    const edges = [];
+    const byId = new Map();
+    function addNode(n) {
+        const key = nodeKey(n.kind, n.id);
+        if (byId.has(key))
+            return;
+        byId.set(key, n);
+        nodes.push(n);
+    }
+    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))
+            return;
+        edges.push({ from: fromKey, to: toKey, relation, why });
+    }
+    function sourceOf(map, id) {
+        const s = map.get(id);
+        if (!s)
+            return 'builtin';
+        if (s.type === 'pack')
+            return `pack:${s.packageName ?? '<unknown>'}`;
+        return 'local';
+    }
+    // ── Nodes ─────────────────────────────────────────────────────────────
+    for (const e of inspection.knowledgeEntries) {
+        const kind = String(e.type) === 'rule' ? 'rule' : String(e.type) === 'path' ? 'path' : 'knowledge';
+        addNode({
+            id: e.id,
+            kind,
+            title: e.title,
+            summary: e.content.slice(0, 120),
+            source: sourceOf(inspection.entrySources, e.id),
+        });
+    }
+    for (const t of inspection.templates) {
+        addNode({
+            id: t.id,
+            kind: 'template',
+            title: t.name,
+            summary: t.description,
+            source: sourceOf(inspection.templateSources, t.id),
+        });
+    }
+    for (const p of inspection.pipelines) {
+        addNode({
+            id: p.id,
+            kind: 'pipeline',
+            title: p.title,
+            summary: p.description,
+            source: sourceOf(inspection.pipelineSources, p.id),
+        });
+    }
+    for (const preset of inspection.presetRegistry.list()) {
+        addNode({
+            id: preset.id,
+            kind: 'preset',
+            title: preset.title,
+            summary: preset.description,
+            source: sourceOf(inspection.presetSources, preset.id),
+        });
+    }
+    for (const r of inspection.boundaryRegistry.list()) {
+        addNode({
+            id: r.id,
+            kind: 'boundary',
+            title: r.title,
+            summary: r.description,
+            source: sourceOf(inspection.boundarySources, r.id),
+        });
+    }
+    for (const pack of inspection.packs.discoveredPacks) {
+        addNode({
+            id: pack.packageName,
+            kind: 'pack',
+            title: `${pack.packageName}@${pack.packageVersion}`,
+            summary: pack.manifest?.info.description,
+            source: 'pack',
+        });
+    }
+    // ── Edges ─────────────────────────────────────────────────────────────
+    // Action hints → related templates / paths / rules.
+    for (const e of inspection.knowledgeEntries) {
+        const ah = e.actionHints;
+        if (!ah)
+            continue;
+        const fromKind = String(e.type) === 'rule' ? 'rule' : String(e.type) === 'path' ? 'path' : 'knowledge';
+        for (const id of ah.relatedTemplates ?? []) {
+            addEdge({ kind: fromKind, id: e.id }, { kind: 'template', id }, 'related-template', 'actionHints.relatedTemplates');
+        }
+        for (const id of ah.relatedPathConventions ?? []) {
+            addEdge({ kind: fromKind, id: e.id }, { kind: 'path', id }, 'related-path', 'actionHints.relatedPathConventions');
+        }
+    }
+    // Preset includes/references/composes.
+    for (const preset of inspection.presetRegistry.list()) {
+        for (const id of preset.includes.templateIds ?? []) {
+            addEdge({ kind: 'preset', id: preset.id }, { kind: 'template', id }, 'preset-references', 'includes.templateIds');
+        }
+        for (const id of preset.includes.pipelineIds ?? []) {
+            addEdge({ kind: 'preset', id: preset.id }, { kind: 'pipeline', id }, 'preset-references', 'includes.pipelineIds');
+        }
+        for (const id of preset.includes.ruleIds ?? []) {
+            addEdge({ kind: 'preset', id: preset.id }, { kind: 'rule', id }, 'preset-references', 'includes.ruleIds');
+        }
+        for (const id of preset.includes.pathConventionIds ?? []) {
+            addEdge({ kind: 'preset', id: preset.id }, { kind: 'path', id }, 'preset-references', 'includes.pathConventionIds');
+        }
+        for (const id of preset.includes.knowledgeIds ?? []) {
+            addEdge({ kind: 'preset', id: preset.id }, { kind: 'knowledge', id }, 'preset-references', 'includes.knowledgeIds');
+        }
+        for (const id of preset.composes ?? []) {
+            addEdge({ kind: 'preset', id: preset.id }, { kind: 'preset', id }, 'composes', 'composes');
+        }
+    }
+    // Pipeline step references.
+    for (const pipeline of inspection.pipelines) {
+        for (const step of pipeline.steps ?? []) {
+            for (const ref of step.references ?? []) {
+                // Try template first, then knowledge.
+                const tplKey = nodeKey('template', ref);
+                const ruleKey = nodeKey('rule', ref);
+                const pathKey = nodeKey('path', ref);
+                const kKey = nodeKey('knowledge', ref);
+                const targetKind = byId.has(tplKey)
+                    ? 'template'
+                    : byId.has(ruleKey)
+                        ? 'rule'
+                        : byId.has(pathKey)
+                            ? 'path'
+                            : byId.has(kKey)
+                                ? 'knowledge'
+                                : null;
+                if (!targetKind)
+                    continue;
+                addEdge({ kind: 'pipeline', id: pipeline.id }, { kind: targetKind, id: ref }, 'pipeline-step-references', `step ${step.id} references`);
+            }
+        }
+    }
+    // Boundary rules: related rules / paths.
+    for (const r of inspection.boundaryRegistry.list()) {
+        for (const id of r.relatedRules ?? []) {
+            addEdge({ kind: 'boundary', id: r.id }, { kind: 'rule', id }, 'boundary-related-rule', 'relatedRules');
+        }
+        for (const id of r.relatedPathConventions ?? []) {
+            addEdge({ kind: 'boundary', id: r.id }, { kind: 'path', id }, 'boundary-related-path', 'relatedPathConventions');
+        }
+    }
+    // Pack contributions: pack → its contributed items.
+    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');
+    }
+    for (const [id, src] of inspection.templateSources) {
+        if (src.type !== 'pack' || !src.packageName)
+            continue;
+        addEdge({ kind: 'pack', id: src.packageName }, { kind: 'template', id }, 'pack-contributes', 'template');
+    }
+    for (const [id, src] of inspection.pipelineSources) {
+        if (src.type !== 'pack' || !src.packageName)
+            continue;
+        addEdge({ kind: 'pack', id: src.packageName }, { kind: 'pipeline', id }, 'pack-contributes', 'pipeline');
+    }
+    for (const [id, src] of inspection.presetSources) {
+        if (src.type !== 'pack' || !src.packageName)
+            continue;
+        addEdge({ kind: 'pack', id: src.packageName }, { kind: 'preset', id }, 'pack-contributes', 'preset');
+    }
+    for (const [id, src] of inspection.boundarySources) {
+        if (src.type !== 'pack' || !src.packageName)
+            continue;
+        addEdge({ kind: 'pack', id: src.packageName }, { kind: 'boundary', id }, 'pack-contributes', 'boundary rule');
+    }
+    return { nodes, edges, byId };
+}
+/**
+ * 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 function findGraphPath(graph, fromRef, toRef) {
+    const fromNode = getGraphNode(graph, fromRef);
+    const toNode = getGraphNode(graph, toRef);
+    if (!fromNode) {
+        return {
+            found: false,
+            steps: [],
+            reason: 'from node not found',
+            explanation: `From node "${fromRef.id}" not in the graph. Try \`shrk graph --type <kind>\` to list available ids.`,
+        };
+    }
+    if (!toNode) {
+        return {
+            found: false,
+            steps: [],
+            reason: 'to node not found',
+            explanation: `To node "${toRef.id}" not in the graph. Try \`shrk graph --type <kind>\` to list available ids.`,
+        };
+    }
+    const fromKey = nodeKey(fromNode.node.kind, fromNode.node.id);
+    const toKey = nodeKey(toNode.node.kind, toNode.node.id);
+    if (fromKey === toKey)
+        return { found: true, steps: [{ node: fromKey }] };
+    const adj = new Map();
+    for (const e of graph.edges) {
+        const list = adj.get(e.from) ?? [];
+        list.push({ to: e.to, relation: e.relation, why: e.why });
+        adj.set(e.from, list);
+    }
+    const parents = new Map();
+    const visited = new Set([fromKey]);
+    const queue = [fromKey];
+    while (queue.length) {
+        const cur = queue.shift();
+        if (cur === toKey) {
+            const reversed = [{ node: toKey }];
+            let pivot = toKey;
+            while (parents.has(pivot)) {
+                const p = parents.get(pivot);
+                reversed.push({ node: p.from, via: { relation: p.relation, why: p.why } });
+                pivot = p.from;
+            }
+            const steps = reversed.reverse();
+            const cleaned = [];
+            for (let i = 0; i < steps.length; i += 1) {
+                const s = steps[i];
+                if (i === 0)
+                    cleaned.push({ node: s.node });
+                else
+                    cleaned.push({ node: s.node, via: steps[i - 1].via });
+            }
+            return { found: true, steps: cleaned };
+        }
+        for (const e of adj.get(cur) ?? []) {
+            if (visited.has(e.to))
+                continue;
+            visited.add(e.to);
+            parents.set(e.to, { from: cur, relation: e.relation, why: e.why });
+            queue.push(e.to);
+        }
+    }
+    return {
+        found: false,
+        steps: [],
+        reason: 'no path',
+        explanation: explainNoPath(fromNode.node.kind, toNode.node.kind, fromRef.id, toRef.id),
+    };
+}
+/**
+ * Build a kind-aware "why is there no path" explanation. Most kinds in
+ * the SharkCraft graph connect via tag overlap / appliesWhen / scope —
+ * not via direct edges — so an empty BFS result is the expected case
+ * for many queries. The explanation makes that visible.
+ */
+function explainNoPath(fromKind, toKind, fromId, toId) {
+    if (fromKind === toKind) {
+        if (fromKind === 'rule') {
+            return `No direct graph edge between ${fromKind}:${fromId} and ${toKind}:${toId}. Rules connect via tags / appliesWhen, not direct edges. Try: shrk rules get ${fromId} --json | jq '.appliesWhen,.tags'`;
+        }
+        if (fromKind === 'knowledge') {
+            return `No direct graph edge between ${fromKind}:${fromId} and ${toKind}:${toId}. Knowledge entries connect via scope / tags, not direct edges. Try: shrk knowledge get ${fromId} --json | jq '.scope,.tags'`;
+        }
+        if (fromKind === 'path') {
+            return `No direct graph edge between ${fromKind}:${fromId} and ${toKind}:${toId}. Path conventions are siblings — they don't reference each other. Try: shrk paths get ${fromId}`;
+        }
+        return `No direct graph edge between ${fromKind}:${fromId} and ${toKind}:${toId}.`;
+    }
+    // Heterogeneous pair — explain the actual connection model.
+    const connector = HETEROGENEOUS_CONNECTORS[`${fromKind}->${toKind}`]
+        ?? HETEROGENEOUS_CONNECTORS[`${toKind}->${fromKind}`];
+    if (connector) {
+        return `No direct edge between ${fromKind}:${fromId} and ${toKind}:${toId}. ${connector}`;
+    }
+    return `No direct edge between ${fromKind}:${fromId} and ${toKind}:${toId}. Graph edges exist for related-template / preset-references / pipeline-step-references / boundary-source-target relations — try \`shrk graph ${toId}\` to inspect ${toKind}:${toId}'s neighbours.`;
+}
+const HETEROGENEOUS_CONNECTORS = Object.freeze({
+    'rule->pipeline': 'Rules attach to pipelines via tag overlap and appliesWhen — not direct edges. Try `shrk pipelines get <id>` to see the pipeline\'s tags and `shrk rules get <id>` to see the rule\'s appliesWhen.',
+    'rule->template': 'Rules apply to templates via tag overlap — not direct edges. Try `shrk task "<task>" --json` to see the ranker output for both at once.',
+    'rule->knowledge': 'Rules and knowledge entries don\'t connect via the graph. They are siblings in the asset registries — both surfaced together by the task-packet ranker.',
+    'knowledge->pipeline': 'Knowledge entries reference pipelines indirectly via scope / appliesWhen. Try `shrk pipelines get <id>` to see the pipeline\'s tags.',
+    'knowledge->template': 'Knowledge entries reference templates via the `related` field. Try `shrk knowledge get <id>` to see related ids.',
+    'template->pipeline': 'Templates are referenced from pipeline steps via `cliCommands`. Try `shrk pipelines get <id>` and look for `gen <template-id>` in step commands.',
+    'preset->knowledge': 'Presets bundle knowledge entries via `contributes`. Try `shrk presets get <id>` to see what the preset includes.',
+    'preset->rule': 'Presets bundle rules via `contributes`. Try `shrk presets get <id>`.',
+    'pack->knowledge': 'Packs ship knowledge entries. Try `shrk packs get <name>` to see what the pack contributes.',
+    'pack->rule': 'Packs ship rules. Try `shrk packs get <name>`.',
+});
+/**
+ * Get a node + its incoming/outgoing edges grouped by kind.
+ */
+export function getGraphNode(graph, ref) {
+    let node = null;
+    if (ref.kind) {
+        node = graph.byId.get(nodeKey(ref.kind, ref.id)) ?? null;
+    }
+    else {
+        // Try each kind.
+        for (const k of [
+            'preset',
+            'template',
+            'pipeline',
+            'rule',
+            'path',
+            'knowledge',
+            'boundary',
+            'pack',
+            'doc',
+        ]) {
+            const found = graph.byId.get(nodeKey(k, ref.id));
+            if (found) {
+                node = found;
+                break;
+            }
+        }
+    }
+    if (!node)
+        return null;
+    const key = nodeKey(node.kind, node.id);
+    return {
+        node,
+        outgoing: graph.edges.filter((e) => e.from === key),
+        incoming: graph.edges.filter((e) => e.to === key),
+    };
+}

package/dist/knowledge-lint.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Knowledge lint + fix-preview.
+ *
+ * Pure inspector — classifies findings on the current knowledge entries.
+ * Never fills meaningful prose with fake content. Stub candidates use
+ * explicit TODO markers so a human / agent must finish the wording.
+ *
+ * Output schemas:
+ *   - sharkcraft.knowledge-lint/v1
+ *   - sharkcraft.knowledge-lint-fix-preview/v1
+ */
+import type { IKnowledgeEntry } from '@shrkcrft/knowledge';
+export declare const KNOWLEDGE_LINT_SCHEMA = "sharkcraft.knowledge-lint/v1";
+export declare const KNOWLEDGE_LINT_FIX_PREVIEW_SCHEMA = "sharkcraft.knowledge-lint-fix-preview/v1";
+export declare enum KnowledgeLintCategory {
+    SafeMechanicalStub = "safe-mechanical-stub",
+    NeedsHumanWording = "needs-human-wording",
+    ShouldAcknowledge = "should-acknowledge",
+    ObsoleteEntry = "obsolete-entry",
+    StaleReference = "stale-reference",
+    MissingProvenance = "missing-provenance",
+    MissingActionHints = "missing-action-hints"
+}
+export declare enum KnowledgeLintSeverity {
+    Info = "info",
+    Warning = "warning"
+}
+export interface IKnowledgeLintFinding {
+    code: string;
+    category: KnowledgeLintCategory;
+    severity: KnowledgeLintSeverity;
+    entryId: string;
+    field: string;
+    message: string;
+    /** A safe, mechanical hint — ONLY populated when category=SafeMechanicalStub. */
+    stubSuggestion?: string;
+    /** Set when the lint is opt-in advisory (does not affect exit code). */
+    advisory?: boolean;
+}
+export interface IKnowledgeLintReport {
+    schema: typeof KNOWLEDGE_LINT_SCHEMA;
+    generatedAt: string;
+    entries: number;
+    findings: readonly IKnowledgeLintFinding[];
+    counts: Readonly<Record<KnowledgeLintCategory, number>>;
+}
+export interface IKnowledgeLintOptions {
+    /** Restrict lint to specific entry ids. */
+    entryIds?: readonly string[];
+    /** When true, also emit MissingProvenance / MissingActionHints
+     * advisories. Default true. */
+    includeAdvisory?: boolean;
+    /** External signal: ids whose references are known to be stale (from
+     * `buildKnowledgeStaleReport`). The lint just records — it does not
+     * re-run stale-check. */
+    staleReferenceEntryIds?: readonly string[];
+}
+export declare function lintKnowledge(entries: readonly IKnowledgeEntry[], options?: IKnowledgeLintOptions): IKnowledgeLintReport;
+export interface IKnowledgeLintFixPreview {
+    schema: typeof KNOWLEDGE_LINT_FIX_PREVIEW_SCHEMA;
+    generatedAt: string;
+    /** Per-entry list of mechanical stubs that can be safely applied. */
+    safeStubs: ReadonlyArray<{
+        entryId: string;
+        code: string;
+        field: string;
+        suggestion: string;
+    }>;
+    /** Per-entry list of TODO items that need human wording. */
+    todos: ReadonlyArray<{
+        entryId: string;
+        code: string;
+        field: string;
+        description: string;
+    }>;
+    /** Per-entry list of items to acknowledge as intentional. */
+    acknowledgements: ReadonlyArray<{
+        entryId: string;
+        code: string;
+        field: string;
+        description: string;
+    }>;
+    /** Reverse-link to the source lint report. */
+    basedOn: typeof KNOWLEDGE_LINT_SCHEMA;
+    /** Files the CLI adapter would write (preview-only). */
+    files: ReadonlyArray<{
+        path: string;
+        purpose: 'markdown-summary' | 'patch' | 'todos-json';
+        language: 'markdown' | 'json' | 'typescript';
+    }>;
+    /** Next commands an agent should run. */
+    nextCommands: readonly string[];
+}
+export declare function buildKnowledgeLintFixPreview(report: IKnowledgeLintReport): IKnowledgeLintFixPreview;
+export declare function renderKnowledgeLintMarkdown(report: IKnowledgeLintReport): string;
+export declare function renderKnowledgeLintFixPreviewMarkdown(preview: IKnowledgeLintFixPreview): string;
+//# sourceMappingURL=knowledge-lint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-lint.d.ts","sourceRoot":"","sources":["../src/knowledge-lint.ts"],"names":[],"mappings":"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"}