@shrkcrft/inspector 0.1.0-alpha.1

package/dist/search-index.d.ts

@@ -0,0 +1,75 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+import { type ISearchTuningEntry } from './search-tuning-registry.js';
+export declare const SEARCH_INDEX_SCHEMA = "sharkcraft.search-index/v1";
+export declare enum SearchKind {
+    Knowledge = "knowledge",
+    Rule = "rule",
+    Path = "path",
+    Template = "template",
+    Pipeline = "pipeline",
+    Preset = "preset",
+    Pack = "pack",
+    Boundary = "boundary",
+    Policy = "policy",
+    Doc = "doc",
+    Session = "session",
+    Bundle = "bundle",
+    Construct = "construct",
+    ConstructFacet = "construct-facet",
+    Playbook = "playbook",
+    ScaffoldPattern = "scaffold-pattern",
+    Command = "command"
+}
+export declare enum SearchSource {
+    Local = "local",
+    Pack = "pack",
+    Session = "session",
+    Bundle = "bundle",
+    Builtin = "builtin",
+    Doc = "doc"
+}
+export interface ISearchDocument {
+    id: string;
+    kind: SearchKind;
+    title: string;
+    content?: string;
+    tags?: readonly string[];
+    appliesWhen?: readonly string[];
+    source: SearchSource;
+    sourcePackage?: string;
+    sourceFile?: string;
+    priority?: 'low' | 'medium' | 'high' | 'critical';
+    fields?: Record<string, string | readonly string[]>;
+    relatedIds?: readonly string[];
+}
+export interface ISearchOptions {
+    query: string;
+    /** Filter to one or more `kind`s. Empty ⇒ all. */
+    kinds?: readonly SearchKind[];
+    /** Filter to one or more sources. */
+    sources?: readonly SearchSource[];
+    /** Limit the total results. Default: 30. */
+    limit?: number;
+    /** Include reasons / why-matched for each hit. */
+    explain?: boolean;
+    /** Tuning entries to bias scoring. Defaults to the inspection's loaded set. */
+    tuning?: readonly ISearchTuningEntry[];
+}
+export interface ISearchHit {
+    document: ISearchDocument;
+    score: number;
+    matchedFields: readonly string[];
+    reasons: readonly string[];
+    snippet?: string;
+}
+export interface ISearchResult {
+    query: string;
+    total: number;
+    truncated: boolean;
+    hits: readonly ISearchHit[];
+    grouped: ReadonlyMap<SearchKind, readonly ISearchHit[]>;
+}
+export declare function buildSearchIndex(inspection: ISharkcraftInspection): ISearchDocument[];
+export declare function searchIndex(index: readonly ISearchDocument[], options: ISearchOptions, inspection?: ISharkcraftInspection): ISearchResult;
+export declare function renderSearchText(result: ISearchResult): string;
+//# sourceMappingURL=search-index.d.ts.map

package/dist/search-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-index.d.ts","sourceRoot":"","sources":["../src/search-index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAKvE,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,6BAA6B,CAAC;AAErC,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAEhE,oBAAY,UAAU;IACpB,SAAS,cAAc;IACvB,IAAI,SAAS;IACb,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,GAAG,QAAQ;IACX,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,SAAS,cAAc;IACvB,cAAc,oBAAoB;IAClC,QAAQ,aAAa;IACrB,eAAe,qBAAqB;IACpC,OAAO,YAAY;CACpB;AAED,oBAAY,YAAY;IACtB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,GAAG,QAAQ;CACZ;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC;IACpD,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,KAAK,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC9B,qCAAqC;IACrC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAClC,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,SAAS,UAAU,EAAE,CAAC;IAC5B,OAAO,EAAE,WAAW,CAAC,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC,CAAC;CACzD;AA0FD,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,qBAAqB,GAAG,eAAe,EAAE,CAgOrF;AAmHD,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,eAAe,EAAE,EACjC,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,qBAAqB,GACjC,aAAa,CA2Df;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAe9D"}

package/dist/search-index.js

@@ -0,0 +1,531 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { listFeatureBundles } from "./feature-bundle.js";
+import { listDevSessionsDetailed } from "./dev-session.js";
+import { listConstructs } from "./construct-registry.js";
+import { listPlaybooks } from "./playbook-registry.js";
+import { listSearchTuning, tuningBoostFor, } from "./search-tuning-registry.js";
+export const SEARCH_INDEX_SCHEMA = 'sharkcraft.search-index/v1';
+export var SearchKind;
+(function (SearchKind) {
+    SearchKind["Knowledge"] = "knowledge";
+    SearchKind["Rule"] = "rule";
+    SearchKind["Path"] = "path";
+    SearchKind["Template"] = "template";
+    SearchKind["Pipeline"] = "pipeline";
+    SearchKind["Preset"] = "preset";
+    SearchKind["Pack"] = "pack";
+    SearchKind["Boundary"] = "boundary";
+    SearchKind["Policy"] = "policy";
+    SearchKind["Doc"] = "doc";
+    SearchKind["Session"] = "session";
+    SearchKind["Bundle"] = "bundle";
+    SearchKind["Construct"] = "construct";
+    SearchKind["ConstructFacet"] = "construct-facet";
+    SearchKind["Playbook"] = "playbook";
+    SearchKind["ScaffoldPattern"] = "scaffold-pattern";
+    SearchKind["Command"] = "command";
+})(SearchKind || (SearchKind = {}));
+export var SearchSource;
+(function (SearchSource) {
+    SearchSource["Local"] = "local";
+    SearchSource["Pack"] = "pack";
+    SearchSource["Session"] = "session";
+    SearchSource["Bundle"] = "bundle";
+    SearchSource["Builtin"] = "builtin";
+    SearchSource["Doc"] = "doc";
+})(SearchSource || (SearchSource = {}));
+const KIND_WEIGHTS = {
+    [SearchKind.Rule]: 5,
+    [SearchKind.Knowledge]: 4,
+    [SearchKind.Template]: 4,
+    [SearchKind.Pipeline]: 4,
+    [SearchKind.Construct]: 4,
+    [SearchKind.Playbook]: 4,
+    [SearchKind.Policy]: 3,
+    [SearchKind.Boundary]: 3,
+    [SearchKind.Path]: 3,
+    [SearchKind.Pack]: 3,
+    [SearchKind.Preset]: 3,
+    [SearchKind.ScaffoldPattern]: 2,
+    [SearchKind.Session]: 2,
+    [SearchKind.Bundle]: 2,
+    [SearchKind.ConstructFacet]: 2,
+    [SearchKind.Doc]: 1,
+    [SearchKind.Command]: 1,
+};
+const PRIORITY_WEIGHTS = {
+    critical: 8,
+    high: 5,
+    medium: 2,
+    low: 1,
+};
+function safeContent(value, max = 400) {
+    if (!value)
+        return undefined;
+    return value.length > max ? value.slice(0, max) + '…' : value;
+}
+function toLower(s) {
+    return s.toLowerCase();
+}
+function makeSnippet(text, terms) {
+    if (!text)
+        return undefined;
+    const haystack = text;
+    const lower = haystack.toLowerCase();
+    for (const term of terms) {
+        const idx = lower.indexOf(term.toLowerCase());
+        if (idx >= 0) {
+            const start = Math.max(0, idx - 40);
+            const end = Math.min(haystack.length, idx + term.length + 80);
+            const snip = haystack.slice(start, end).replace(/\s+/g, ' ').trim();
+            return (start > 0 ? '…' : '') + snip + (end < haystack.length ? '…' : '');
+        }
+    }
+    return undefined;
+}
+function loadDocFiles(projectRoot) {
+    const docsDir = nodePath.join(projectRoot, 'docs');
+    if (!existsSync(docsDir))
+        return [];
+    const out = [];
+    try {
+        for (const f of readdirSync(docsDir)) {
+            if (!f.endsWith('.md'))
+                continue;
+            const full = nodePath.join(docsDir, f);
+            try {
+                if (!statSync(full).isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            let content = '';
+            try {
+                content = readFileSync(full, 'utf8');
+            }
+            catch {
+                /* ignore */
+            }
+            const titleMatch = /^#\s+(.+)/m.exec(content);
+            const title = titleMatch?.[1]?.trim() ?? f.replace(/\.md$/, '');
+            out.push({
+                id: `doc:${f}`,
+                kind: SearchKind.Doc,
+                title,
+                content: safeContent(content, 1200),
+                source: SearchSource.Doc,
+                sourceFile: `docs/${f}`,
+            });
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return out;
+}
+export function buildSearchIndex(inspection) {
+    const docs = [];
+    for (const k of inspection.knowledgeEntries) {
+        const src = inspection.entrySources.get(k.id);
+        docs.push({
+            id: `knowledge:${k.id}`,
+            kind: SearchKind.Knowledge,
+            title: k.title ?? k.id,
+            content: safeContent([k.summary ?? '', k.content ?? ''].filter(Boolean).join('\n\n'), 1200),
+            ...(k.tags ? { tags: k.tags } : {}),
+            ...(k.appliesWhen ? { appliesWhen: k.appliesWhen } : {}),
+            ...(k.priority ? { priority: k.priority } : {}),
+            source: src?.type === 'pack' ? SearchSource.Pack : SearchSource.Local,
+            ...(src?.packageName ? { sourcePackage: src.packageName } : {}),
+            ...(src?.file ? { sourceFile: src.file } : {}),
+        });
+    }
+    for (const r of inspection.ruleService.list()) {
+        docs.push({
+            id: `rule:${r.id}`,
+            kind: SearchKind.Rule,
+            title: r.title ?? r.id,
+            content: safeContent(r.summary ?? r.content ?? '', 800),
+            ...(r.tags
+                ? { tags: r.tags ?? [] }
+                : {}),
+            ...(r.appliesWhen
+                ? { appliesWhen: r.appliesWhen ?? [] }
+                : {}),
+            ...(r.priority
+                ? { priority: r.priority }
+                : {}),
+            source: SearchSource.Local,
+        });
+    }
+    for (const p of inspection.pathService.list()) {
+        const meta = (p.metadata ?? {});
+        docs.push({
+            id: `path:${p.id}`,
+            kind: SearchKind.Path,
+            title: p.title ?? p.id,
+            content: safeContent(meta.description ?? p.summary ?? p.content ?? '', 400),
+            ...(p.tags
+                ? { tags: p.tags ?? [] }
+                : {}),
+            source: SearchSource.Local,
+            fields: {
+                path: meta.path ?? '',
+            },
+        });
+    }
+    for (const t of inspection.templateRegistry.list()) {
+        const src = inspection.templateSources.get(t.id);
+        docs.push({
+            id: `template:${t.id}`,
+            kind: SearchKind.Template,
+            title: t.name ?? t.id,
+            content: safeContent(t.description ?? '', 800),
+            ...(t.tags
+                ? { tags: t.tags ?? [] }
+                : {}),
+            source: src?.type === 'pack' ? SearchSource.Pack : SearchSource.Local,
+            ...(src?.packageName ? { sourcePackage: src.packageName } : {}),
+            ...(src?.file ? { sourceFile: src.file } : {}),
+        });
+    }
+    for (const p of inspection.pipelineRegistry.list()) {
+        const src = inspection.pipelineSources.get(p.id);
+        docs.push({
+            id: `pipeline:${p.id}`,
+            kind: SearchKind.Pipeline,
+            title: p.title ?? p.id,
+            content: safeContent(p.description ?? '', 800),
+            ...(p.tags
+                ? { tags: p.tags ?? [] }
+                : {}),
+            source: src?.type === 'pack' ? SearchSource.Pack : SearchSource.Local,
+            ...(src?.packageName ? { sourcePackage: src.packageName } : {}),
+        });
+    }
+    try {
+        const presets = inspection.presetRegistry.list();
+        for (const p of presets) {
+            const src = inspection.presetSources?.get(p.id);
+            docs.push({
+                id: `preset:${p.id}`,
+                kind: SearchKind.Preset,
+                title: p.name ?? p.id,
+                content: safeContent(p.description ?? '', 400),
+                source: src?.type === 'pack' ? SearchSource.Pack : SearchSource.Builtin,
+                ...(src?.packageName ? { sourcePackage: src.packageName } : {}),
+            });
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    for (const pack of inspection.packs.validPacks ?? []) {
+        docs.push({
+            id: `pack:${pack.packageName}`,
+            kind: SearchKind.Pack,
+            title: pack.packageName,
+            content: safeContent(pack.manifest?.info?.description ?? '', 400),
+            source: SearchSource.Pack,
+            sourcePackage: pack.packageName,
+            fields: {
+                version: pack.packageVersion,
+            },
+        });
+    }
+    for (const r of inspection.boundaryRegistry.list()) {
+        const rb = r;
+        docs.push({
+            id: `boundary:${r.id}`,
+            kind: SearchKind.Boundary,
+            title: rb.title ?? r.id,
+            content: safeContent(rb.description ?? rb.message ?? '', 400),
+            ...(rb.tags ? { tags: rb.tags } : {}),
+            source: SearchSource.Local,
+            fields: {
+                from: (rb.from ?? []).join(', '),
+                forbidden: (rb.forbiddenImports ?? []).join(', '),
+                allowed: (rb.allowedImports ?? []).join(', '),
+            },
+        });
+    }
+    // Policies (registered checks).
+    try {
+        const cfg = inspection.config;
+        void cfg;
+    }
+    catch {
+        /* ignore */
+    }
+    // Bundles, sessions.
+    try {
+        const bundles = listFeatureBundles(inspection.projectRoot);
+        for (const b of bundles) {
+            docs.push({
+                id: `bundle:${b.id}`,
+                kind: SearchKind.Bundle,
+                title: b.task ?? b.id,
+                content: safeContent(b.task ?? '', 400),
+                source: SearchSource.Bundle,
+                fields: { status: b.status, risk: b.riskLevel },
+            });
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    try {
+        const sessions = listDevSessionsDetailed(inspection.projectRoot);
+        for (const s of sessions) {
+            docs.push({
+                id: `session:${s.id}`,
+                kind: SearchKind.Session,
+                title: s.task || s.id,
+                source: SearchSource.Session,
+                fields: { phase: s.phase ?? '', nextAction: s.nextAction ?? '' },
+            });
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    // Constructs / facets / playbooks (loaded lazily via registries).
+    try {
+        const constructs = listConstructs(inspection);
+        for (const c of constructs) {
+            docs.push({
+                id: `construct:${c.id}`,
+                kind: SearchKind.Construct,
+                title: c.title ?? c.id,
+                content: safeContent(c.description ?? '', 600),
+                ...(c.tags ? { tags: c.tags } : {}),
+                source: c.source === 'pack' ? SearchSource.Pack : SearchSource.Local,
+                ...(c.packageName ? { sourcePackage: c.packageName } : {}),
+                fields: { type: c.type },
+            });
+            for (const f of facetsFor(c)) {
+                docs.push({
+                    id: `facet:${c.id}:${f.id}`,
+                    kind: SearchKind.ConstructFacet,
+                    title: `${c.id} / ${f.kind}: ${f.value}`,
+                    content: safeContent(f.description ?? '', 200),
+                    source: c.source === 'pack' ? SearchSource.Pack : SearchSource.Local,
+                    fields: { construct: c.id, kind: f.kind, value: f.value },
+                });
+            }
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    try {
+        const playbooks = listPlaybooks(inspection);
+        for (const p of playbooks) {
+            docs.push({
+                id: `playbook:${p.id}`,
+                kind: SearchKind.Playbook,
+                title: p.title ?? p.id,
+                content: safeContent(p.description ?? '', 600),
+                ...(p.tags ? { tags: p.tags } : {}),
+                source: p.source === 'pack' ? SearchSource.Pack : SearchSource.Local,
+                ...(p.packageName ? { sourcePackage: p.packageName } : {}),
+            });
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    // Docs.
+    docs.push(...loadDocFiles(inspection.projectRoot));
+    return docs;
+}
+function facetsFor(c) {
+    const explicit = c.facets ?? {};
+    const out = [];
+    for (const [kind, list] of Object.entries(explicit)) {
+        for (const value of list) {
+            out.push({
+                id: value.id,
+                constructId: c.id,
+                kind,
+                value: value.value,
+                ...(value.description ? { description: value.description } : {}),
+            });
+        }
+    }
+    for (const e of c.events ?? []) {
+        out.push({ id: `event:${e}`, constructId: c.id, kind: 'event', value: e });
+    }
+    for (const t of c.tokens ?? []) {
+        out.push({ id: `token:${t}`, constructId: c.id, kind: 'token', value: t });
+    }
+    for (const a of c.publicApi ?? []) {
+        out.push({ id: `api:${a}`, constructId: c.id, kind: 'api', value: a });
+    }
+    return out;
+}
+function tokenize(input) {
+    return input
+        .split(/[\s,\.;:\/]+/)
+        .map((t) => t.trim())
+        .filter((t) => t.length > 1);
+}
+function scoreDocument(doc, query, tokens, options) {
+    const lowerQuery = query.toLowerCase();
+    const matchedFields = new Set();
+    const reasons = [];
+    let score = 0;
+    const lowerId = doc.id.toLowerCase();
+    const lowerTitle = doc.title.toLowerCase();
+    if (lowerId === lowerQuery || lowerId.endsWith(':' + lowerQuery)) {
+        score += 100;
+        matchedFields.add('id');
+        reasons.push('exact id match');
+    }
+    else if (lowerId.includes(lowerQuery)) {
+        score += 20;
+        matchedFields.add('id');
+        reasons.push('id contains query');
+    }
+    if (lowerTitle === lowerQuery) {
+        score += 40;
+        matchedFields.add('title');
+        reasons.push('exact title match');
+    }
+    else if (lowerTitle.includes(lowerQuery)) {
+        score += 12;
+        matchedFields.add('title');
+        reasons.push('title contains query');
+    }
+    for (const tag of doc.tags ?? []) {
+        if (tokens.some((t) => tag.toLowerCase() === t)) {
+            score += 6;
+            matchedFields.add('tags');
+            reasons.push(`tag ${tag}`);
+            break;
+        }
+    }
+    for (const applies of doc.appliesWhen ?? []) {
+        if (tokens.some((t) => applies.toLowerCase().includes(t))) {
+            score += 4;
+            matchedFields.add('appliesWhen');
+            reasons.push(`appliesWhen ${applies}`);
+            break;
+        }
+    }
+    for (const tok of tokens) {
+        if (doc.content && doc.content.toLowerCase().includes(tok)) {
+            score += 2;
+            matchedFields.add('content');
+            reasons.push(`content has "${tok}"`);
+        }
+        if (doc.fields) {
+            for (const [k, v] of Object.entries(doc.fields)) {
+                const str = Array.isArray(v) ? v.join(' ') : String(v);
+                if (str.toLowerCase().includes(tok)) {
+                    score += 1;
+                    matchedFields.add(`field:${k}`);
+                }
+            }
+        }
+        for (const rel of doc.relatedIds ?? []) {
+            if (rel.toLowerCase().includes(tok)) {
+                score += 2;
+                matchedFields.add('relatedIds');
+            }
+        }
+    }
+    const kindWeight = KIND_WEIGHTS[doc.kind] ?? 1;
+    score *= 1 + kindWeight / 10;
+    if (doc.priority) {
+        score += PRIORITY_WEIGHTS[doc.priority] ?? 0;
+        matchedFields.add(`priority:${doc.priority}`);
+    }
+    if (options.kinds && !options.kinds.includes(doc.kind))
+        score = 0;
+    if (options.sources && !options.sources.includes(doc.source))
+        score = 0;
+    return { score, matchedFields: [...matchedFields], reasons };
+}
+export function searchIndex(index, options, inspection) {
+    const query = options.query.trim();
+    if (!query) {
+        return {
+            query: '',
+            total: 0,
+            truncated: false,
+            hits: [],
+            grouped: new Map(),
+        };
+    }
+    const tokens = tokenize(query.toLowerCase());
+    const tuning = options.tuning ?? (inspection ? listSearchTuning(inspection) : []);
+    const hits = [];
+    for (const doc of index) {
+        const { score, matchedFields, reasons } = scoreDocument(doc, query, tokens, options);
+        if (score <= 0)
+            continue;
+        let finalScore = score;
+        let finalReasons = options.explain ? [...reasons] : [];
+        if (tuning.length > 0) {
+            const boost = tuningBoostFor({ id: doc.id, kind: doc.kind, ...(doc.tags ? { tags: doc.tags } : {}), source: doc.source }, tokens, tuning);
+            if (boost.delta !== 0) {
+                finalScore += boost.delta;
+                if (options.explain)
+                    finalReasons.push(...boost.reasons);
+                matchedFields.push('tuning');
+            }
+        }
+        const hit = {
+            document: doc,
+            score: Math.round(finalScore * 100) / 100,
+            matchedFields,
+            reasons: finalReasons,
+        };
+        const snippet = makeSnippet(doc.content, tokens);
+        if (snippet)
+            hit.snippet = snippet;
+        hits.push(hit);
+    }
+    hits.sort((a, b) => b.score - a.score || a.document.id.localeCompare(b.document.id));
+    const limit = options.limit ?? 30;
+    const truncated = hits.length > limit;
+    const top = hits.slice(0, limit);
+    const grouped = new Map();
+    for (const h of top) {
+        const arr = grouped.get(h.document.kind) ?? [];
+        arr.push(h);
+        grouped.set(h.document.kind, arr);
+    }
+    return {
+        query,
+        total: hits.length,
+        truncated,
+        hits: top,
+        grouped,
+    };
+}
+export function renderSearchText(result) {
+    const lines = [];
+    lines.push(`Search: "${result.query}" — ${result.total} match(es)${result.truncated ? ' (truncated)' : ''}`);
+    for (const [kind, hits] of result.grouped) {
+        lines.push('');
+        lines.push(`# ${kind} (${hits.length})`);
+        for (const h of hits) {
+            lines.push(`  ${h.score.toString().padStart(6)}  ${h.document.id}  — ${h.document.title}`);
+            if (h.snippet)
+                lines.push(`         ${h.snippet}`);
+            if (h.reasons.length > 0) {
+                lines.push(`         (${h.reasons.slice(0, 3).join(', ')})`);
+            }
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+function toLowerCase(s) {
+    return s.toLowerCase();
+}
+void toLower;
+void toLowerCase;

package/dist/search-tuning-explain.d.ts

@@ -0,0 +1,68 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const SEARCH_TUNING_EXPLAIN_SCHEMA = "sharkcraft.search-tuning-explain/v1";
+export interface ISearchTuningExplainOptions {
+    /** Limit how many top results to compare before/after. Default: 5. */
+    topN?: number;
+}
+export interface IPerHitTuningExplain {
+    docId: string;
+    title: string;
+    kind: string;
+    baselineScore: number;
+    tunedScore: number;
+    delta: number;
+    reasons: readonly string[];
+    /** Per-key composition: contributors, merge strategy applied, combined value. */
+    composition?: readonly {
+        key: string;
+        strategy: 'sum' | 'max';
+        contributors: readonly {
+            tuningId: string;
+            value: number;
+        }[];
+        combined: number;
+    }[];
+}
+export interface ITuningMatch {
+    tuningId: string;
+    source: string;
+    packageName?: string;
+    matchedTags: readonly string[];
+    matchedKinds: readonly string[];
+    matchedIds: readonly string[];
+    matchedSources: readonly string[];
+    taskHints: readonly {
+        whenTokens: readonly string[];
+        matched: boolean;
+    }[];
+}
+export interface ISearchTuningExplainReport {
+    schema: typeof SEARCH_TUNING_EXPLAIN_SCHEMA;
+    generatedAt: string;
+    query: string;
+    tokens: readonly string[];
+    loadedTunings: readonly {
+        id: string;
+        source: string;
+        packageName?: string;
+        sourceFile?: string;
+        mergeStrategy?: 'sum' | 'max';
+    }[];
+    matched: readonly ITuningMatch[];
+    cappedBoosts: readonly {
+        tuningId: string;
+        key: string;
+        original: number;
+        clamped: number;
+    }[];
+    topResults: readonly IPerHitTuningExplain[];
+    warnings: readonly {
+        code: string;
+        message: string;
+        tuningId?: string;
+    }[];
+}
+export declare function explainSearchTuning(inspection: ISharkcraftInspection, query: string, options?: ISearchTuningExplainOptions): Promise<ISearchTuningExplainReport>;
+export declare function renderTuningExplainMarkdown(report: ISearchTuningExplainReport): string;
+export declare function renderTuningExplainHtml(report: ISearchTuningExplainReport): string;
+//# sourceMappingURL=search-tuning-explain.d.ts.map

package/dist/search-tuning-explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-tuning-explain.d.ts","sourceRoot":"","sources":["../src/search-tuning-explain.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,4BAA4B,wCAAwC,CAAC;AAElF,MAAM,WAAW,2BAA2B;IAC1C,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,iFAAiF;IACjF,WAAW,CAAC,EAAE,SAAS;QACrB,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,EAAE,KAAK,GAAG,KAAK,CAAC;QACxB,YAAY,EAAE,SAAS;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAC7D,QAAQ,EAAE,MAAM,CAAC;KAClB,EAAE,CAAC;CACL;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,SAAS,EAAE,SAAS;QAAE,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CAC3E;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,OAAO,4BAA4B,CAAC;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,SAAS;QACtB,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;KAC/B,EAAE,CAAC;IACJ,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC,YAAY,EAAE,SAAS;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9F,UAAU,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC5C,QAAQ,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3E;AAyCD,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,0BAA0B,CAAC,CA0ErC;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,0BAA0B,GAAG,MAAM,CA0DtF;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,0BAA0B,GAAG,MAAM,CAiClF"}