@shrkcrft/inspector 0.1.0-alpha.2

package/dist/ranker-explainability.js

@@ -0,0 +1,550 @@
+import { buildSearchIndex, searchIndex, } from "./search-index.js";
+import { listSearchTuning, tuningBoostFor, } from "./search-tuning-registry.js";
+import { rankAll } from "./task-ranker.js";
+export const RANKER_EXPLAINABILITY_SCHEMA = 'sharkcraft.ranker-explainability/v1';
+export var RankerExplainKind;
+(function (RankerExplainKind) {
+    RankerExplainKind["Knowledge"] = "knowledge";
+    RankerExplainKind["Template"] = "template";
+    RankerExplainKind["Rule"] = "rule";
+    RankerExplainKind["Helper"] = "helper";
+    RankerExplainKind["Playbook"] = "playbook";
+    RankerExplainKind["Construct"] = "construct";
+    RankerExplainKind["Policy"] = "policy";
+    RankerExplainKind["Command"] = "command";
+    RankerExplainKind["Path"] = "path";
+    RankerExplainKind["Preset"] = "preset";
+    RankerExplainKind["Pipeline"] = "pipeline";
+})(RankerExplainKind || (RankerExplainKind = {}));
+function sourceLabel(s) {
+    if (!s)
+        return 'local';
+    if (s.loader)
+        return s.loader;
+    if (s.origin)
+        return s.origin;
+    return 'local';
+}
+function listRegistryHits(inspection) {
+    const out = [];
+    for (const r of inspection.ruleService.list()) {
+        out.push({
+            id: r.id,
+            kind: 'rule',
+            title: r.title ?? r.id,
+            source: sourceLabel(r.source),
+            ...(r.tags ? { tags: r.tags } : {}),
+            ...(r.appliesWhen ? { appliesWhen: r.appliesWhen } : {}),
+        });
+    }
+    for (const p of inspection.pathService.list()) {
+        out.push({
+            id: p.id,
+            kind: 'path',
+            title: p.title ?? p.id,
+            source: sourceLabel(p.source),
+            ...(p.tags ? { tags: p.tags } : {}),
+            ...(p.appliesWhen ? { appliesWhen: p.appliesWhen } : {}),
+        });
+    }
+    for (const t of inspection.templates) {
+        out.push({
+            id: t.id,
+            kind: 'template',
+            title: t.name ?? t.id,
+            source: 'local',
+            ...(t.tags ? { tags: t.tags } : {}),
+            ...(t.appliesWhen ? { appliesWhen: t.appliesWhen } : {}),
+        });
+    }
+    for (const k of inspection.knowledgeEntries) {
+        if (!out.some((o) => o.id === k.id)) {
+            out.push({
+                id: k.id,
+                kind: 'knowledge',
+                title: k.title ?? k.id,
+                source: sourceLabel(k.source),
+                ...(k.tags ? { tags: k.tags } : {}),
+                ...(k.appliesWhen ? { appliesWhen: k.appliesWhen } : {}),
+            });
+        }
+    }
+    for (const p of inspection.pipelines) {
+        out.push({
+            id: p.id,
+            kind: 'pipeline',
+            title: p.title ?? p.id,
+            source: 'local',
+            ...(p.tags ? { tags: p.tags } : {}),
+        });
+    }
+    for (const p of inspection.presetRegistry.list()) {
+        out.push({
+            id: p.id,
+            kind: 'preset',
+            title: p.title ?? p.id,
+            source: 'local',
+            ...(p.tags ? { tags: p.tags } : {}),
+        });
+    }
+    return out;
+}
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    const dp = new Array(n + 1);
+    for (let j = 0; j <= n; j += 1)
+        dp[j] = j;
+    for (let i = 1; i <= m; i += 1) {
+        let prev = dp[0];
+        dp[0] = i;
+        for (let j = 1; j <= n; j += 1) {
+            const tmp = dp[j];
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[j] = Math.min(dp[j] + 1, dp[j - 1] + 1, prev + cost);
+            prev = tmp;
+        }
+    }
+    return dp[n];
+}
+function nearestIds(hits, target, limit = 5) {
+    return hits
+        .map((h) => ({ id: h.id, kind: h.kind, distance: levenshtein(h.id, target) }))
+        .filter((h) => h.distance <= Math.max(3, Math.floor(target.length * 0.4)))
+        .sort((a, b) => a.distance - b.distance)
+        .slice(0, limit);
+}
+function tokenize(s) {
+    return s
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length >= 3);
+}
+function rankForTask(inspection, task) {
+    const all = rankAll(inspection, task, 50);
+    return {
+        rules: all.rules.map((r) => ({ id: r.item.id, score: r.score, reasons: r.reasons })),
+        paths: all.paths.map((r) => ({ id: r.item.id, score: r.score, reasons: r.reasons })),
+        templates: all.templates.map((r) => ({ id: r.item.id, score: r.score, reasons: r.reasons })),
+        pipelines: all.pipelines.map((r) => ({ id: r.item.id, score: r.score, reasons: r.reasons })),
+        presets: all.presets.map((r) => ({ id: r.item.id, score: r.score, reasons: r.reasons })),
+    };
+}
+function suggestedFixes(taskOrQuery, hit, matched, missing) {
+    const out = [];
+    const lower = taskOrQuery.toLowerCase();
+    const tokens = new Set(tokenize(taskOrQuery));
+    const itemTags = new Set((hit.tags ?? []).map((t) => t.toLowerCase()));
+    const itemAW = new Set((hit.appliesWhen ?? []).map((t) => t.toLowerCase()));
+    if (missing.some((s) => s.signal === 'token-hits-title')) {
+        out.push(`Mention one of these tokens in title/description so token hits score: ${[...tokens].slice(0, 5).join(', ')}`);
+    }
+    if (missing.some((s) => s.signal === 'tags')) {
+        const candidate = inferDomainTags(lower);
+        if (candidate.length > 0) {
+            out.push(`Add a tag matching the task domain: ${candidate.filter((t) => !itemTags.has(t)).join(', ')}`);
+        }
+    }
+    if (missing.some((s) => s.signal === 'appliesWhen')) {
+        const candidate = inferDomainAppliesWhen(lower);
+        if (candidate.length > 0) {
+            out.push(`Declare an appliesWhen value matching task intent: ${candidate.filter((a) => !itemAW.has(a)).join(', ')}`);
+        }
+    }
+    if (matched.length === 0 && missing.length > 0) {
+        out.push('No signals matched. Add tags/appliesWhen referencing the task domain, or include domain tokens in the title.');
+    }
+    return out;
+}
+/**
+ * Generic domain-token inference. Project-specific tokens (e.g.
+ * "primitive", "adapter", "sandbox") move to pack-contributed search-tuning
+ * rather than hardcoded heuristics in the engine.
+ */
+function inferDomainTags(taskLower) {
+    const out = [];
+    if (/\bplugin\b/.test(taskLower))
+        out.push('plugin');
+    if (/\brenderer\b/.test(taskLower))
+        out.push('renderer');
+    if (/\b(angular|react)\b/.test(taskLower))
+        out.push(/\bangular\b/.test(taskLower) ? 'angular' : 'react');
+    if (/\b(layout|drag|drop)\b/.test(taskLower))
+        out.push('layout');
+    return Array.from(new Set(out));
+}
+function inferDomainAppliesWhen(taskLower) {
+    const out = [];
+    if (/\b(create|add|new|generate|build)\b/.test(taskLower))
+        out.push('generate-code');
+    if (/\bplugin\b/.test(taskLower))
+        out.push('create-plugin');
+    if (/\b(rename|move)\b/.test(taskLower))
+        out.push('refactor');
+    if (/\bcapability\b/.test(taskLower))
+        out.push('create-capability');
+    return Array.from(new Set(out));
+}
+function commonSuggestedCommands(found, hit) {
+    if (!found) {
+        return [
+            'shrk commands suggest "<partial id>"',
+            'shrk find <text>',
+            'shrk search <text> --explain',
+        ];
+    }
+    const out = [];
+    out.push(`shrk why-not ${hit?.id ?? '<id>'} --for-task "<task>"`);
+    out.push('shrk search "<task>" --explain');
+    out.push('shrk search tuning explain "<task>"');
+    out.push('shrk coverage scaffolds --task "<task>"');
+    return out;
+}
+function deriveMatchedAndMissing(hit, taskOrQuery) {
+    if (!hit)
+        return { matched: [], missing: [] };
+    const taskTokens = new Set(tokenize(taskOrQuery));
+    const titleTokens = new Set(tokenize(hit.title));
+    const idTokens = new Set(tokenize(hit.id));
+    const tagSet = new Set((hit.tags ?? []).map((t) => t.toLowerCase()));
+    const awSet = new Set((hit.appliesWhen ?? []).map((t) => t.toLowerCase()));
+    const inferredTags = new Set(inferDomainTags(taskOrQuery.toLowerCase()));
+    const inferredAW = new Set(inferDomainAppliesWhen(taskOrQuery.toLowerCase()));
+    const titleHits = [];
+    for (const t of taskTokens)
+        if (titleTokens.has(t))
+            titleHits.push(t);
+    const idHits = [];
+    for (const t of taskTokens)
+        if (idTokens.has(t))
+            idHits.push(t);
+    const tagHits = [];
+    for (const t of inferredTags)
+        if (tagSet.has(t))
+            tagHits.push(t);
+    const awHits = [];
+    for (const a of inferredAW)
+        if (awSet.has(a))
+            awHits.push(a);
+    const matched = [];
+    const missing = [];
+    if (titleHits.length > 0)
+        matched.push({ signal: 'token-hits-title', matched: true, detail: titleHits.join(', ') });
+    else
+        missing.push({ signal: 'token-hits-title', matched: false });
+    if (idHits.length > 0)
+        matched.push({ signal: 'id-tokens', matched: true, detail: idHits.join(', ') });
+    else
+        missing.push({ signal: 'id-tokens', matched: false });
+    if (tagHits.length > 0)
+        matched.push({ signal: 'tags', matched: true, detail: tagHits.join(', ') });
+    else
+        missing.push({ signal: 'tags', matched: false });
+    if (awHits.length > 0)
+        matched.push({ signal: 'appliesWhen', matched: true, detail: awHits.join(', ') });
+    else
+        missing.push({ signal: 'appliesWhen', matched: false });
+    return { matched, missing };
+}
+function gatherTuningTrace(hit, tuning, taskOrQuery) {
+    if (!hit)
+        return [];
+    const tokens = tokenize(taskOrQuery);
+    const boost = tuningBoostFor({
+        id: hit.id,
+        kind: hit.kind,
+        ...(hit.tags ? { tags: hit.tags } : {}),
+        source: hit.source,
+    }, tokens, tuning);
+    if (!boost.composition || boost.composition.length === 0) {
+        if (boost.reasons.length === 0)
+            return [];
+        return [{ tuningId: '(combined)', reasons: boost.reasons, delta: boost.delta ?? 0 }];
+    }
+    const traces = [];
+    for (const c of boost.composition) {
+        for (const x of c.contributors) {
+            traces.push({
+                tuningId: x.tuningId,
+                reasons: [`${c.key} ${x.value > 0 ? '+' : ''}${x.value}`],
+                delta: x.value,
+            });
+        }
+    }
+    return traces;
+}
+export function explainRankerDecision(inspection, request, options = {}) {
+    const topN = options.topN ?? 10;
+    const hits = listRegistryHits(inspection);
+    const id = request.id;
+    const found = hits.find((h) => h.id === id);
+    const taskOrQuery = request.task ?? request.query ?? '';
+    const tuning = listSearchTuning(inspection);
+    // Build search-based ranking for query mode (no task).
+    let ranker;
+    let documentSnapshot;
+    let searchScore;
+    let searchRank;
+    let searchThreshold;
+    if (request.task) {
+        ranker = rankForTask(inspection, request.task);
+    }
+    if (request.query) {
+        const index = buildSearchIndex(inspection);
+        const result = searchIndex(index, { query: request.query, limit: Math.max(topN, 20), explain: true }, inspection);
+        const targetHit = result.hits.find((h) => h.document.id === id);
+        if (targetHit) {
+            documentSnapshot = targetHit.document;
+            searchScore = targetHit.score;
+            searchRank = result.hits.indexOf(targetHit) + 1;
+        }
+        const tail = result.hits[Math.min(topN, result.hits.length) - 1];
+        if (tail)
+            searchThreshold = tail.score;
+    }
+    // For task ranking, find which kind contains the target.
+    let rank;
+    let score;
+    let threshold;
+    let kindContainer;
+    if (ranker) {
+        for (const key of ['rules', 'paths', 'templates', 'pipelines', 'presets']) {
+            const arr = ranker[key];
+            const idx = arr.findIndex((r) => r.id === id);
+            if (idx >= 0) {
+                rank = idx + 1;
+                score = arr[idx].score;
+                const tail = arr[Math.min(topN, arr.length) - 1];
+                threshold = tail ? tail.score : 0;
+                kindContainer = key;
+                break;
+            }
+        }
+    }
+    const included = ranker ? !!(rank && rank <= topN) : !!(searchRank && searchRank <= topN);
+    // Matched / missing signals derived from the task/query vs hit metadata.
+    const sig = deriveMatchedAndMissing(found, taskOrQuery);
+    // Items that outranked the target.
+    const outranked = [];
+    if (ranker && kindContainer) {
+        const arr = ranker[kindContainer];
+        const myIdx = arr.findIndex((r) => r.id === id);
+        if (myIdx > 0) {
+            for (const better of arr.slice(0, myIdx)) {
+                outranked.push({ id: better.id, kind: kindContainer.slice(0, -1), score: better.score, reasons: better.reasons.slice(0, 3) });
+            }
+        }
+    }
+    if (!ranker && request.query && documentSnapshot && searchRank && searchRank > 1) {
+        const index = buildSearchIndex(inspection);
+        const r = searchIndex(index, { query: request.query, limit: Math.max(topN, 20), explain: true }, inspection);
+        for (let i = 0; i < searchRank - 1; i += 1) {
+            const h = r.hits[i];
+            if (!h)
+                break;
+            outranked.push({ id: h.document.id, kind: String(h.document.kind), score: h.score, reasons: h.reasons.slice(0, 3) });
+        }
+    }
+    const tuningTrace = gatherTuningTrace(found, tuning, taskOrQuery);
+    const matchedSignals = sig.matched;
+    const missingSignals = sig.missing;
+    const suggestedMetadataFixes = found
+        ? suggestedFixes(taskOrQuery, found, matchedSignals, missingSignals)
+        : [];
+    const suggestedCommands = commonSuggestedCommands(!!found, found);
+    const diagnostics = [];
+    if (!found)
+        diagnostics.push(`id "${id}" was not found in any registry`);
+    if (found && !taskOrQuery)
+        diagnostics.push('no --for-task or --for-query provided — only structural info available');
+    if (options.whyNot && included)
+        diagnostics.push('why-not asked, but the id IS included for this task');
+    if (!options.whyNot && !found)
+        diagnostics.push('cannot include a missing id — see nearestIds[]');
+    const report = {
+        schema: RANKER_EXPLAINABILITY_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        request,
+        found: !!found,
+        ...(found ? { resolvedKind: found.kind } : {}),
+        included,
+        ...(rank !== undefined ? { rank } : searchRank !== undefined ? { rank: searchRank } : {}),
+        ...(score !== undefined ? { score } : searchScore !== undefined ? { score: searchScore } : {}),
+        ...(threshold !== undefined ? { threshold } : searchThreshold !== undefined ? { threshold: searchThreshold } : {}),
+        matchedSignals,
+        missingSignals,
+        outrankedBy: outranked.slice(0, 5),
+        tuningTrace,
+        suggestedMetadataFixes,
+        suggestedCommands,
+        nearestIds: found ? [] : nearestIds(hits, id),
+        diagnostics,
+    };
+    return report;
+}
+// ── Rendering ───────────────────────────────────────────────────────────
+export function renderRankerExplainText(report, whyNot) {
+    const lines = [];
+    const heading = whyNot ? `=== shrk why-not ${report.request.id} ===` : `=== shrk why ${report.request.id} ===`;
+    lines.push(heading);
+    if (report.request.task)
+        lines.push(`task: ${report.request.task}`);
+    if (report.request.query)
+        lines.push(`query: ${report.request.query}`);
+    lines.push('');
+    lines.push(`found:        ${report.found ? 'yes' : 'no'}`);
+    if (report.resolvedKind)
+        lines.push(`kind:         ${report.resolvedKind}`);
+    lines.push(`included:     ${report.included ? 'yes' : 'no'}`);
+    if (report.rank !== undefined)
+        lines.push(`rank:         ${report.rank}`);
+    if (report.score !== undefined)
+        lines.push(`score:        ${report.score}`);
+    if (report.threshold !== undefined)
+        lines.push(`threshold:    ${report.threshold}`);
+    lines.push('');
+    if (report.matchedSignals.length > 0) {
+        lines.push('Matched signals:');
+        for (const s of report.matchedSignals) {
+            lines.push(`  + ${s.signal}${s.detail ? `: ${s.detail}` : ''}`);
+        }
+    }
+    else {
+        lines.push('Matched signals: (none)');
+    }
+    if (report.missingSignals.length > 0) {
+        lines.push('Missing signals:');
+        for (const s of report.missingSignals) {
+            lines.push(`  - ${s.signal}`);
+        }
+    }
+    if (report.outrankedBy.length > 0) {
+        lines.push('');
+        lines.push('Outranked by:');
+        for (const o of report.outrankedBy) {
+            lines.push(`  [${o.score}] ${o.id} (${o.kind})  ${o.reasons.join('; ')}`);
+        }
+    }
+    if (report.tuningTrace.length > 0) {
+        lines.push('');
+        lines.push('Search tuning trace:');
+        for (const t of report.tuningTrace) {
+            lines.push(`  · ${t.tuningId}  delta=${t.delta}  ${t.reasons.join('; ')}`);
+        }
+    }
+    if (report.suggestedMetadataFixes.length > 0) {
+        lines.push('');
+        lines.push('Suggested metadata fixes:');
+        for (const f of report.suggestedMetadataFixes)
+            lines.push(`  • ${f}`);
+    }
+    if (report.suggestedCommands.length > 0) {
+        lines.push('');
+        lines.push('Next commands:');
+        for (const c of report.suggestedCommands)
+            lines.push(`  $ ${c}`);
+    }
+    if (report.nearestIds.length > 0) {
+        lines.push('');
+        lines.push('Nearest ids:');
+        for (const n of report.nearestIds)
+            lines.push(`  ~ ${n.id} (${n.kind})  distance=${n.distance}`);
+    }
+    if (report.diagnostics.length > 0) {
+        lines.push('');
+        lines.push('Diagnostics:');
+        for (const d of report.diagnostics)
+            lines.push(`  · ${d}`);
+    }
+    return lines.join('\n') + '\n';
+}
+function escHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+export function renderRankerExplainMarkdown(report, whyNot) {
+    const lines = [];
+    lines.push(`# ${whyNot ? 'shrk why-not' : 'shrk why'} \`${report.request.id}\``);
+    if (report.request.task)
+        lines.push(`Task: \`${report.request.task}\``);
+    if (report.request.query)
+        lines.push(`Query: \`${report.request.query}\``);
+    lines.push('');
+    lines.push('| Field | Value |');
+    lines.push('| --- | --- |');
+    lines.push(`| found | ${report.found ? 'yes' : 'no'} |`);
+    if (report.resolvedKind)
+        lines.push(`| kind | ${report.resolvedKind} |`);
+    lines.push(`| included | ${report.included ? 'yes' : 'no'} |`);
+    if (report.rank !== undefined)
+        lines.push(`| rank | ${report.rank} |`);
+    if (report.score !== undefined)
+        lines.push(`| score | ${report.score} |`);
+    if (report.threshold !== undefined)
+        lines.push(`| threshold | ${report.threshold} |`);
+    lines.push('');
+    if (report.matchedSignals.length > 0) {
+        lines.push('## Matched signals');
+        for (const s of report.matchedSignals)
+            lines.push(`- ${s.signal}${s.detail ? `: ${s.detail}` : ''}`);
+        lines.push('');
+    }
+    if (report.missingSignals.length > 0) {
+        lines.push('## Missing signals');
+        for (const s of report.missingSignals)
+            lines.push(`- ${s.signal}`);
+        lines.push('');
+    }
+    if (report.outrankedBy.length > 0) {
+        lines.push('## Outranked by');
+        for (const o of report.outrankedBy) {
+            lines.push(`- \`${o.id}\` (${o.kind}) score=${o.score} — ${o.reasons.join('; ')}`);
+        }
+        lines.push('');
+    }
+    if (report.tuningTrace.length > 0) {
+        lines.push('## Search tuning trace');
+        for (const t of report.tuningTrace) {
+            lines.push(`- \`${t.tuningId}\` delta=${t.delta} — ${t.reasons.join('; ')}`);
+        }
+        lines.push('');
+    }
+    if (report.suggestedMetadataFixes.length > 0) {
+        lines.push('## Suggested metadata fixes');
+        for (const f of report.suggestedMetadataFixes)
+            lines.push(`- ${f}`);
+        lines.push('');
+    }
+    if (report.suggestedCommands.length > 0) {
+        lines.push('## Next commands');
+        for (const c of report.suggestedCommands)
+            lines.push(`- \`${c}\``);
+        lines.push('');
+    }
+    if (report.nearestIds.length > 0) {
+        lines.push('## Nearest ids');
+        for (const n of report.nearestIds)
+            lines.push(`- \`${n.id}\` (${n.kind}) distance=${n.distance}`);
+        lines.push('');
+    }
+    if (report.diagnostics.length > 0) {
+        lines.push('## Diagnostics');
+        for (const d of report.diagnostics)
+            lines.push(`- ${d}`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+export function renderRankerExplainHtml(report, whyNot) {
+    const md = renderRankerExplainMarkdown(report, whyNot);
+    return [
+        '<!doctype html><html><head><meta charset="utf-8">',
+        `<title>SharkCraft — ${whyNot ? 'why-not' : 'why'} ${escHtml(report.request.id)}</title>`,
+        '<style>body{font:14px/1.5 -apple-system,sans-serif;max-width:880px;margin:24px auto;padding:0 16px}h1{font-size:20px;border-bottom:1px solid #d0d7de;padding-bottom:8px}h2{font-size:16px;margin-top:24px}code{background:#f6f8fa;padding:1px 4px;border-radius:4px;font-size:12px}table{border-collapse:collapse}th,td{border:1px solid #d0d7de;padding:4px 10px}</style></head><body>',
+        '<pre>' + escHtml(md) + '</pre>',
+        '</body></html>',
+    ].join('\n');
+}

package/dist/reference-lookup.d.ts

@@ -0,0 +1,8 @@
+import type { IReferenceLookup } from '@shrkcrft/presets';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+/**
+ * Adapt a SharkCraft inspection to the {@link IReferenceLookup} contract the
+ * preset reference resolver expects. Pure read-through; no state.
+ */
+export declare function inspectionReferenceLookup(inspection: ISharkcraftInspection): IReferenceLookup;
+//# sourceMappingURL=reference-lookup.d.ts.map

package/dist/reference-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-lookup.d.ts","sourceRoot":"","sources":["../src/reference-lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,qBAAqB,GAChC,gBAAgB,CAalB"}

package/dist/reference-lookup.js

@@ -0,0 +1,18 @@
+/**
+ * Adapt a SharkCraft inspection to the {@link IReferenceLookup} contract the
+ * preset reference resolver expects. Pure read-through; no state.
+ */
+export function inspectionReferenceLookup(inspection) {
+    const knowledgeIds = new Set(inspection.knowledgeEntries.map((e) => e.id));
+    const ruleIds = new Set(inspection.ruleService.list().map((r) => r.id));
+    const pathIds = new Set(inspection.pathService.list().map((p) => p.id));
+    const templateIds = new Set(inspection.templates.map((t) => t.id));
+    const pipelineIds = new Set(inspection.pipelines.map((p) => p.id));
+    return {
+        hasKnowledge: (id) => knowledgeIds.has(id),
+        hasRule: (id) => ruleIds.has(id),
+        hasPath: (id) => pathIds.has(id),
+        hasTemplate: (id) => templateIds.has(id),
+        hasPipeline: (id) => pipelineIds.has(id),
+    };
+}

package/dist/registration-hint-registry.d.ts

@@ -0,0 +1,55 @@
+import { type IRegistrationHint, type IRegistrationHintOperation } from '@shrkcrft/plugin-api';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const REGISTRATION_HINT_REGISTRY_SCHEMA = "sharkcraft.registration-hint-registry/v1";
+export declare enum RegistrationHintSource {
+    Local = "local",
+    Pack = "pack",
+    Fixture = "fixture"
+}
+export interface IRegistrationHintEntry {
+    readonly hint: IRegistrationHint;
+    readonly source: RegistrationHintSource;
+    readonly packageName?: string;
+    readonly sourceFile: string;
+}
+export interface IRegistrationHintDoctorIssue {
+    readonly severity: 'info' | 'warning' | 'error';
+    readonly code: string;
+    readonly message: string;
+    readonly hintId?: string;
+    readonly source?: string;
+}
+export declare function loadRegistrationHints(inspection: ISharkcraftInspection): Promise<{
+    entries: readonly IRegistrationHintEntry[];
+    issues: readonly IRegistrationHintDoctorIssue[];
+}>;
+export declare function listRegistrationHints(inspection: ISharkcraftInspection): Promise<readonly IRegistrationHintEntry[]>;
+export declare function getRegistrationHint(inspection: ISharkcraftInspection, hintId: string): Promise<IRegistrationHintEntry | null>;
+export interface IRegistrationHintPreviewOperation {
+    readonly kind: IRegistrationHintOperation['kind'];
+    readonly anchor?: string;
+    readonly snippet?: string;
+    /** Pretty-printed description for human review. */
+    readonly description: string;
+}
+export interface IRegistrationHintPreview {
+    readonly schema: 'sharkcraft.registration-hint-preview/v1';
+    readonly hintId: string;
+    readonly title: string;
+    readonly targetFile: string | null;
+    readonly candidates: readonly string[];
+    /** True when discovery is ambiguous (multiple candidates) or no file matches. */
+    readonly ambiguous: boolean;
+    readonly requiresHumanReview: boolean;
+    readonly operations: readonly IRegistrationHintPreviewOperation[];
+    readonly missingVariables: readonly string[];
+    readonly safetyNotes: readonly string[];
+    readonly validationCommands: readonly string[];
+    readonly nextCommand: string;
+}
+export interface IRegistrationHintPreviewOptions {
+    readonly variables?: Readonly<Record<string, string>>;
+}
+export declare function previewRegistrationHint(inspection: ISharkcraftInspection, hintId: string, options?: IRegistrationHintPreviewOptions): Promise<IRegistrationHintPreview | null>;
+export declare function listRegistrationHintIssues(inspection: ISharkcraftInspection): Promise<readonly IRegistrationHintDoctorIssue[]>;
+//# sourceMappingURL=registration-hint-registry.d.ts.map

package/dist/registration-hint-registry.d.ts.map

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