@shrkcrft/inspector 0.1.0-alpha.2

package/dist/search-tuning-explain.js

@@ -0,0 +1,207 @@
+import { buildSearchIndex, searchIndex } from "./search-index.js";
+import { listSearchTuning, listSearchTuningIssues, loadSearchTuning, tuningBoostFor, } from "./search-tuning-registry.js";
+export const SEARCH_TUNING_EXPLAIN_SCHEMA = 'sharkcraft.search-tuning-explain/v1';
+function tokenize(query) {
+    return query
+        .toLowerCase()
+        .split(/[\s,\.;:\/]+/)
+        .map((t) => t.trim())
+        .filter((t) => t.length > 1);
+}
+function describeBoost(entry, tokens) {
+    const matchedTags = entry.boostTags ? Object.keys(entry.boostTags) : [];
+    const matchedKinds = [];
+    const matchedIds = entry.boostIds ? Object.keys(entry.boostIds) : [];
+    const matchedSources = entry.boostSources ? Object.keys(entry.boostSources) : [];
+    const taskHints = (entry.taskHints ?? []).map((h) => ({
+        whenTokens: h.whenTokens ?? [],
+        matched: (h.whenTokens ?? []).length === 0 ||
+            (h.whenTokens ?? []).every((t) => tokens.includes(t.toLowerCase())),
+    }));
+    for (const h of entry.taskHints ?? []) {
+        if (h.boostKinds)
+            for (const k of Object.keys(h.boostKinds))
+                if (!matchedKinds.includes(k))
+                    matchedKinds.push(k);
+        if (h.boostIds)
+            for (const id of Object.keys(h.boostIds))
+                if (!matchedIds.includes(id))
+                    matchedIds.push(id);
+        if (h.boostTags)
+            for (const t of Object.keys(h.boostTags))
+                if (!matchedTags.includes(t))
+                    matchedTags.push(t);
+    }
+    const out = {
+        tuningId: entry.id,
+        source: entry.source,
+        matchedTags,
+        matchedKinds,
+        matchedIds,
+        matchedSources,
+        taskHints,
+    };
+    if (entry.packageName)
+        out.packageName = entry.packageName;
+    return out;
+}
+export async function explainSearchTuning(inspection, query, options = {}) {
+    await loadSearchTuning(inspection);
+    const tuning = listSearchTuning(inspection);
+    const issues = listSearchTuningIssues(inspection);
+    const tokens = tokenize(query);
+    const matched = tuning.map((t) => describeBoost(t, tokens));
+    const cappedBoosts = issues
+        .filter((i) => i.code === 'boost-clamped')
+        .map((i) => {
+        const parsed = /Boost for "([^"]+)" clamped to (\S+) \(was (\S+)\)/.exec(i.message);
+        return {
+            ...(i.tuningId ? { tuningId: i.tuningId } : { tuningId: '(unknown)' }),
+            key: parsed?.[1] ?? '?',
+            clamped: parsed ? Number(parsed[2]) : 0,
+            original: parsed ? Number(parsed[3]) : 0,
+        };
+    });
+    const index = buildSearchIndex(inspection);
+    const opts = { query, limit: Math.max(5, options.topN ?? 5), explain: true };
+    const baseline = searchIndex(index, { ...opts, tuning: [] });
+    const tuned = searchIndex(index, opts, inspection);
+    const tunedById = new Map(tuned.hits.map((h) => [h.document.id, h]));
+    const topResults = [];
+    const considered = baseline.hits.slice(0, options.topN ?? 5);
+    for (const h of considered) {
+        const t = tunedById.get(h.document.id);
+        if (!t)
+            continue;
+        const boost = tuningBoostFor({
+            id: h.document.id,
+            kind: h.document.kind,
+            ...(h.document.tags ? { tags: h.document.tags } : {}),
+            source: h.document.source,
+        }, tokens, tuning);
+        topResults.push({
+            docId: h.document.id,
+            title: h.document.title,
+            kind: h.document.kind,
+            baselineScore: h.score,
+            tunedScore: t.score,
+            delta: Number((t.score - h.score).toFixed(2)),
+            reasons: boost.reasons,
+            ...(boost.composition && boost.composition.length > 0 ? { composition: boost.composition } : {}),
+        });
+    }
+    return {
+        schema: SEARCH_TUNING_EXPLAIN_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        query,
+        tokens,
+        loadedTunings: tuning.map((t) => ({
+            id: t.id,
+            source: t.source,
+            ...(t.packageName ? { packageName: t.packageName } : {}),
+            ...(t.sourceFile ? { sourceFile: t.sourceFile } : {}),
+            ...(t.mergeStrategy ? { mergeStrategy: t.mergeStrategy } : {}),
+        })),
+        matched,
+        cappedBoosts,
+        topResults,
+        warnings: issues
+            .filter((i) => i.severity !== 'info')
+            .map((i) => {
+            const out = {
+                code: i.code,
+                message: i.message,
+            };
+            if (i.tuningId)
+                out.tuningId = i.tuningId;
+            return out;
+        }),
+    };
+}
+export function renderTuningExplainMarkdown(report) {
+    const lines = [];
+    lines.push(`# Search tuning explain`);
+    lines.push('');
+    lines.push(`Query: \`${report.query}\``);
+    lines.push(`Tokens: ${report.tokens.map((t) => '`' + t + '`').join(', ') || '_none_'}`);
+    lines.push('');
+    lines.push(`## Loaded tunings (${report.loadedTunings.length})`);
+    if (report.loadedTunings.length === 0)
+        lines.push('_(none — no tuning files contributed)_');
+    for (const t of report.loadedTunings) {
+        const strategy = t.mergeStrategy ? ` · merge=${t.mergeStrategy}` : '';
+        lines.push(`- \`${t.id}\` (${t.source}${t.packageName ? ' / ' + t.packageName : ''}${strategy})`);
+    }
+    lines.push('');
+    lines.push(`## Top result deltas`);
+    if (report.topResults.length === 0)
+        lines.push('_No matches in the top window._');
+    lines.push('');
+    if (report.topResults.length > 0) {
+        lines.push('| Doc | Kind | Baseline | Tuned | Δ |');
+        lines.push('| --- | --- | ---: | ---: | ---: |');
+        for (const r of report.topResults) {
+            lines.push(`| \`${r.docId}\` | ${r.kind} | ${r.baselineScore} | ${r.tunedScore} | ${r.delta} |`);
+        }
+        // Show composition for hits whose key got contributions from >1 tuning.
+        const interesting = report.topResults
+            .filter((r) => (r.composition ?? []).some((c) => c.contributors.length > 1));
+        if (interesting.length > 0) {
+            lines.push('');
+            lines.push('### Composition');
+            for (const r of interesting) {
+                lines.push(`- \`${r.docId}\``);
+                for (const c of r.composition ?? []) {
+                    if (c.contributors.length <= 1)
+                        continue;
+                    const parts = c.contributors.map((x) => `${x.tuningId} ${x.value > 0 ? '+' : ''}${x.value}`).join(', ');
+                    lines.push(`  - ${c.key} (strategy=${c.strategy}): [${parts}] → ${c.combined > 0 ? '+' : ''}${c.combined}`);
+                }
+            }
+        }
+    }
+    if (report.cappedBoosts.length > 0) {
+        lines.push('');
+        lines.push('## Capped boosts');
+        for (const c of report.cappedBoosts) {
+            lines.push(`- \`${c.tuningId}\` ${c.key}: ${c.original} → ${c.clamped}`);
+        }
+    }
+    if (report.warnings.length > 0) {
+        lines.push('');
+        lines.push('## Warnings');
+        for (const w of report.warnings) {
+            lines.push(`- [${w.code}] ${w.message}${w.tuningId ? ` (${w.tuningId})` : ''}`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+export function renderTuningExplainHtml(report) {
+    const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    const lines = [];
+    lines.push('<!doctype html><html><head><meta charset="utf-8">');
+    lines.push('<title>SharkCraft — search tuning explain</title>');
+    lines.push('<style>body{font:14px/1.5 -apple-system,sans-serif;max-width:900px;margin:24px auto;padding:0 16px}h1{font-size:20px;border-bottom:1px solid #d0d7de;padding-bottom:8px}table{border-collapse:collapse;width:100%}th,td{border:1px solid #d0d7de;padding:6px 10px}th{background:#f6f8fa}code{background:#f6f8fa;padding:1px 4px;border-radius:4px;font-size:12px}</style></head><body>');
+    lines.push(`<h1>Search tuning explain</h1>`);
+    lines.push(`<p>Query: <code>${esc(report.query)}</code></p>`);
+    lines.push(`<p>Tokens: ${report.tokens.map((t) => `<code>${esc(t)}</code>`).join(', ') || '<em>none</em>'}</p>`);
+    lines.push(`<h2>Loaded tunings (${report.loadedTunings.length})</h2><ul>`);
+    for (const t of report.loadedTunings) {
+        lines.push(`<li><code>${esc(t.id)}</code> · ${esc(t.source)}${t.packageName ? ' / ' + esc(t.packageName) : ''}</li>`);
+    }
+    if (report.loadedTunings.length === 0)
+        lines.push('<li><em>(none)</em></li>');
+    lines.push('</ul>');
+    lines.push(`<h2>Top result deltas</h2>`);
+    if (report.topResults.length === 0)
+        lines.push('<p><em>No matches in the top window.</em></p>');
+    else {
+        lines.push('<table><thead><tr><th>Doc</th><th>Kind</th><th>Baseline</th><th>Tuned</th><th>Δ</th></tr></thead><tbody>');
+        for (const r of report.topResults) {
+            lines.push(`<tr><td><code>${esc(r.docId)}</code></td><td>${esc(r.kind)}</td><td>${r.baselineScore}</td><td>${r.tunedScore}</td><td>${r.delta}</td></tr>`);
+        }
+        lines.push('</tbody></table>');
+    }
+    lines.push('</body></html>');
+    return lines.join('\n') + '\n';
+}

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

@@ -0,0 +1,54 @@
+import type { ISearchTuning } from '@shrkcrft/plugin-api';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const SEARCH_TUNING_SCHEMA = "sharkcraft.search-tuning-registry/v1";
+export interface ISearchTuningEntry extends ISearchTuning {
+    source: 'local' | 'pack';
+    packageName?: string;
+    sourceFile?: string;
+}
+export interface ISearchTuningDoctorIssue {
+    severity: 'info' | 'warning' | 'error';
+    code: string;
+    message: string;
+    tuningId?: string;
+    source?: string;
+}
+export declare function loadSearchTuning(inspection: ISharkcraftInspection): Promise<{
+    entries: readonly ISearchTuningEntry[];
+    issues: readonly ISearchTuningDoctorIssue[];
+}>;
+export declare function listSearchTuning(inspection: ISharkcraftInspection): readonly ISearchTuningEntry[];
+export declare function listSearchTuningIssues(inspection: ISharkcraftInspection): readonly ISearchTuningDoctorIssue[];
+export interface ISearchTuningBoost {
+    delta: number;
+    reasons: string[];
+    /** Per-key contributors and the merge strategy applied to each key. */
+    composition?: readonly ISearchTuningComposition[];
+}
+export interface ISearchTuningContribution {
+    tuningId: string;
+    value: number;
+}
+export interface ISearchTuningComposition {
+    /** e.g. `tag:plugin`, `id:<pack>.plugin`, `source:<pack>`, `task-kind:rule`. */
+    key: string;
+    strategy: 'sum' | 'max';
+    contributors: readonly ISearchTuningContribution[];
+    /** Final value after the strategy is applied (before global cap). */
+    combined: number;
+}
+/** Compute the boost contribution for a single document. Returns the additive
+ *  delta, the matching reasons, and the per-key composition (so explain
+ *  reports can show "two tunings contributed +3 each but max strategy keeps
+ *  only +3 instead of +6").
+ *
+ *  Merge strategy: when ANY contributor on a key declares `mergeStrategy:'max'`,
+ *  the key uses max-by-absolute-value; otherwise it sums. The global ±10 cap
+ *  applies after composition. */
+export declare function tuningBoostFor(doc: {
+    id: string;
+    kind: string;
+    tags?: readonly string[];
+    source: string;
+}, tokens: readonly string[], entries: readonly ISearchTuningEntry[]): ISearchTuningBoost;
+//# sourceMappingURL=search-tuning-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search-tuning-registry.d.ts","sourceRoot":"","sources":["../src/search-tuning-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,oBAAoB,yCAAyC,CAAC;AAE3E,MAAM,WAAW,kBAAmB,SAAQ,aAAa;IACvD,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA0GD,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC;IAAE,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAAC,MAAM,EAAE,SAAS,wBAAwB,EAAE,CAAA;CAAE,CAAC,CA4DlG;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,qBAAqB,GAAG,SAAS,kBAAkB,EAAE,CAGjG;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,qBAAqB,GAAG,SAAS,wBAAwB,EAAE,CAG7G;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,uEAAuE;IACvE,WAAW,CAAC,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACnD;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,KAAK,GAAG,KAAK,CAAC;IACxB,YAAY,EAAE,SAAS,yBAAyB,EAAE,CAAC;IACnD,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAqBD;;;;;;;iCAOiC;AACjC,wBAAgB,cAAc,CAC5B,GAAG,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC3E,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,OAAO,EAAE,SAAS,kBAAkB,EAAE,GACrC,kBAAkB,CAoGpB"}

package/dist/search-tuning-registry.js

@@ -0,0 +1,303 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { pathToFileURL } from 'node:url';
+export const SEARCH_TUNING_SCHEMA = 'sharkcraft.search-tuning-registry/v1';
+const CACHE = new Map();
+const MAX_BOOST = 5;
+async function importDefault(file) {
+    const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+    if (Array.isArray(mod.default))
+        return mod.default;
+    if (mod.default && typeof mod.default === 'object')
+        return [mod.default];
+    if (Array.isArray(mod.searchTuning))
+        return mod.searchTuning;
+    return [];
+}
+function localTuningFiles(inspection) {
+    const out = [];
+    const dir = inspection.sharkcraftDir;
+    if (!dir)
+        return [];
+    for (const f of ['search-tuning.ts', 'search-tuning/index.ts']) {
+        const full = nodePath.join(dir, f);
+        if (existsSync(full))
+            out.push(full);
+    }
+    const cfg = inspection.config;
+    for (const rel of cfg?.searchTuningFiles ?? []) {
+        out.push(nodePath.join(dir, rel));
+    }
+    return out;
+}
+function clampBoost(value) {
+    if (typeof value !== 'number' || Number.isNaN(value))
+        return 0;
+    if (value > MAX_BOOST)
+        return MAX_BOOST;
+    if (value < -MAX_BOOST)
+        return -MAX_BOOST;
+    return value;
+}
+function sanitize(raw, source, packageName, sourceFile, issues) {
+    if (typeof raw.id !== 'string' || raw.id.length === 0) {
+        issues.push({
+            severity: 'warning',
+            code: 'missing-id',
+            message: 'Tuning entry has no id; skipped.',
+            source: sourceFile,
+        });
+        return null;
+    }
+    const out = {
+        id: raw.id,
+        source,
+        ...(packageName ? { packageName } : {}),
+        sourceFile,
+    };
+    if (raw.appliesToKinds)
+        out.appliesToKinds = raw.appliesToKinds;
+    if (raw.mergeStrategy === 'sum' || raw.mergeStrategy === 'max') {
+        out.mergeStrategy = raw.mergeStrategy;
+    }
+    const sanitizeRecord = (rec) => {
+        if (!rec)
+            return undefined;
+        const result = {};
+        for (const [k, v] of Object.entries(rec)) {
+            const clamped = clampBoost(v);
+            if (clamped !== v) {
+                issues.push({
+                    severity: 'info',
+                    code: 'boost-clamped',
+                    message: `Boost for "${k}" clamped to ${clamped} (was ${v}).`,
+                    tuningId: raw.id,
+                    source: sourceFile,
+                });
+            }
+            result[k] = clamped;
+        }
+        return result;
+    };
+    const boostTags = sanitizeRecord(raw.boostTags);
+    if (boostTags)
+        out.boostTags = boostTags;
+    const boostIds = sanitizeRecord(raw.boostIds);
+    if (boostIds)
+        out.boostIds = boostIds;
+    const boostSources = sanitizeRecord(raw.boostSources);
+    if (boostSources)
+        out.boostSources = boostSources;
+    if (raw.taskHints) {
+        out.taskHints = raw.taskHints.map((h) => ({
+            ...(h.whenTokens ? { whenTokens: h.whenTokens.map((t) => t.toLowerCase()) } : {}),
+            ...(h.boostTags ? { boostTags: sanitizeRecord(h.boostTags) } : {}),
+            ...(h.boostKinds ? { boostKinds: sanitizeRecord(h.boostKinds) } : {}),
+            ...(h.boostIds ? { boostIds: sanitizeRecord(h.boostIds) } : {}),
+        }));
+    }
+    return out;
+}
+export async function loadSearchTuning(inspection) {
+    const cacheKey = `${inspection.projectRoot}:${inspection.packs.validPacks
+        .map((p) => p.packageName + '@' + p.packageVersion)
+        .join(',')}`;
+    const cached = CACHE.get(inspection.projectRoot);
+    if (cached && cached.cacheKey === cacheKey) {
+        return { entries: cached.entries, issues: cached.issues };
+    }
+    const entries = [];
+    const issues = [];
+    for (const file of localTuningFiles(inspection)) {
+        try {
+            const list = await importDefault(file);
+            for (const raw of list) {
+                const ent = sanitize(raw, 'local', undefined, nodePath.relative(inspection.projectRoot, file), issues);
+                if (ent)
+                    entries.push(ent);
+            }
+        }
+        catch (e) {
+            issues.push({
+                severity: 'warning',
+                code: 'load-failed',
+                message: `Failed to load ${file}: ${e.message}`,
+                source: file,
+            });
+        }
+    }
+    for (const pack of inspection.packs.validPacks ?? []) {
+        const contributions = (pack.manifest?.contributions ?? {});
+        for (const rel of contributions.searchTuningFiles ?? []) {
+            const file = nodePath.resolve(pack.packageRoot, rel);
+            if (!existsSync(file)) {
+                issues.push({
+                    severity: 'warning',
+                    code: 'missing-file',
+                    message: `Pack ${pack.packageName} declares tuning ${rel} but the file is missing.`,
+                    source: file,
+                });
+                continue;
+            }
+            try {
+                const list = await importDefault(file);
+                for (const raw of list) {
+                    const ent = sanitize(raw, 'pack', pack.packageName, rel, issues);
+                    if (ent)
+                        entries.push(ent);
+                }
+            }
+            catch (e) {
+                issues.push({
+                    severity: 'warning',
+                    code: 'load-failed',
+                    message: `Pack ${pack.packageName} (${rel}): ${e.message}`,
+                    source: file,
+                });
+            }
+        }
+    }
+    CACHE.set(inspection.projectRoot, { cacheKey, entries, issues });
+    return { entries, issues };
+}
+export function listSearchTuning(inspection) {
+    const cached = CACHE.get(inspection.projectRoot);
+    return cached?.entries ?? [];
+}
+export function listSearchTuningIssues(inspection) {
+    const cached = CACHE.get(inspection.projectRoot);
+    return cached?.issues ?? [];
+}
+function pushContribution(buf, key, tuningId, value) {
+    if (value === 0)
+        return;
+    let list = buf.byKey.get(key);
+    if (!list) {
+        list = [];
+        buf.byKey.set(key, list);
+    }
+    list.push({ tuningId, value });
+}
+/** Compute the boost contribution for a single document. Returns the additive
+ *  delta, the matching reasons, and the per-key composition (so explain
+ *  reports can show "two tunings contributed +3 each but max strategy keeps
+ *  only +3 instead of +6").
+ *
+ *  Merge strategy: when ANY contributor on a key declares `mergeStrategy:'max'`,
+ *  the key uses max-by-absolute-value; otherwise it sums. The global ±10 cap
+ *  applies after composition. */
+export function tuningBoostFor(doc, tokens, entries) {
+    const buf = { byKey: new Map() };
+    const strategyByKey = new Map();
+    const setStrategy = (key, entry) => {
+        if (entry.mergeStrategy === 'max')
+            strategyByKey.set(key, 'max');
+        else if (!strategyByKey.has(key))
+            strategyByKey.set(key, 'sum');
+    };
+    for (const e of entries) {
+        if (e.appliesToKinds && !e.appliesToKinds.includes(doc.kind))
+            continue;
+        if (e.boostTags && doc.tags) {
+            for (const t of doc.tags) {
+                const b = e.boostTags[t];
+                if (typeof b === 'number' && b !== 0) {
+                    const key = `tag:${t}`;
+                    pushContribution(buf, key, e.id, b);
+                    setStrategy(key, e);
+                }
+            }
+        }
+        if (e.boostIds) {
+            const b = e.boostIds[doc.id];
+            if (typeof b === 'number' && b !== 0) {
+                const key = `id:${doc.id}`;
+                pushContribution(buf, key, e.id, b);
+                setStrategy(key, e);
+            }
+        }
+        if (e.boostSources) {
+            const b = e.boostSources[doc.source];
+            if (typeof b === 'number' && b !== 0) {
+                const key = `source:${doc.source}`;
+                pushContribution(buf, key, e.id, b);
+                setStrategy(key, e);
+            }
+        }
+        if (e.taskHints) {
+            for (const h of e.taskHints) {
+                if (!h.whenTokens || h.whenTokens.length === 0)
+                    continue;
+                const queryMatches = h.whenTokens.every((wt) => tokens.includes(wt));
+                if (!queryMatches)
+                    continue;
+                if (h.boostTags && doc.tags) {
+                    for (const t of doc.tags) {
+                        const b = h.boostTags[t];
+                        if (typeof b === 'number' && b !== 0) {
+                            const key = `task-hint:tag:${t}`;
+                            pushContribution(buf, key, e.id, b);
+                            setStrategy(key, e);
+                        }
+                    }
+                }
+                if (h.boostKinds) {
+                    const b = h.boostKinds[doc.kind];
+                    if (typeof b === 'number' && b !== 0) {
+                        const key = `task-hint:kind:${doc.kind}`;
+                        pushContribution(buf, key, e.id, b);
+                        setStrategy(key, e);
+                    }
+                }
+                if (h.boostIds) {
+                    const b = h.boostIds[doc.id];
+                    if (typeof b === 'number' && b !== 0) {
+                        const key = `task-hint:id:${doc.id}`;
+                        pushContribution(buf, key, e.id, b);
+                        setStrategy(key, e);
+                    }
+                }
+            }
+        }
+    }
+    // Compose per key.
+    let delta = 0;
+    const reasons = [];
+    const composition = [];
+    for (const [key, contributors] of buf.byKey) {
+        const strategy = strategyByKey.get(key) ?? 'sum';
+        let combined = 0;
+        if (strategy === 'max') {
+            // Strongest absolute value wins; preserves sign.
+            let pick = contributors[0];
+            for (const c of contributors) {
+                if (Math.abs(c.value) > Math.abs(pick.value))
+                    pick = c;
+            }
+            combined = pick.value;
+        }
+        else {
+            for (const c of contributors)
+                combined += c.value;
+        }
+        delta += combined;
+        composition.push({ key, strategy, contributors, combined });
+        for (const c of contributors) {
+            reasons.push(`tuning:${c.tuningId} ${key} ${c.value > 0 ? '+' : ''}${c.value}${contributors.length > 1 ? ' (strategy=' + strategy + ')' : ''}`);
+        }
+    }
+    // Global cap so tuning can't dominate the natural signal.
+    if (delta > MAX_BOOST * 2)
+        delta = MAX_BOOST * 2;
+    if (delta < -MAX_BOOST * 2)
+        delta = -MAX_BOOST * 2;
+    return { delta, reasons, composition };
+}

package/dist/self-audit.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `shrk self audit` — meaningful only inside the SharkCraft repo itself.
+ *
+ * Aggregates several existing read-only audits:
+ *  - shrk commands doctor (catalog completeness)
+ *  - mcp audit (no writable tools)
+ *  - docs check
+ *  - examples check
+ *  - release readiness
+ *  - runtime doctor
+ *  - compat:node static report
+ *  - packs doctor on example packs
+ *
+ * The aggregation is intentionally lightweight — every component is its own
+ * command. `self audit` just wires the verdicts into one pass/fail and
+ * suggests the next CLI step.
+ *
+ * When run outside the SharkCraft repo, the command returns a single
+ * "not-applicable" finding instead of running anything.
+ */
+export declare const SELF_AUDIT_SCHEMA = "sharkcraft.self-audit/v1";
+export interface ISelfAuditFinding {
+    id: string;
+    title: string;
+    status: 'pass' | 'warn' | 'fail' | 'skipped';
+    message: string;
+    /** Suggested next command. */
+    nextCommand?: string;
+}
+export interface ISelfAuditReport {
+    schema: typeof SELF_AUDIT_SCHEMA;
+    generatedAt: string;
+    projectRoot: string;
+    isSharkcraftRepo: boolean;
+    findings: readonly ISelfAuditFinding[];
+    ok: boolean;
+}
+export declare function detectSharkcraftRepo(projectRoot: string): boolean;
+export interface ISelfAuditInput {
+    /** Caller can pass pre-computed verdicts. */
+    releaseReadinessReady?: boolean;
+    releaseReadinessBlockers?: number;
+    releaseReadinessWarnings?: number;
+    commandsDoctorErrors?: number;
+    commandsDoctorWarnings?: number;
+    mcpAuditWriteToolCount?: number;
+    docsCheckOk?: boolean;
+    examplesCheckOk?: boolean;
+    /** Has runtime doctor been run? Pass `null` to mark skipped. */
+    runtimeDoctorOk?: boolean | null;
+    /** Has compat:node been run? Pass `null` to mark skipped. */
+    compatNodeOk?: boolean | null;
+    /** Pack doctor verdict. Pass `null` to mark skipped. */
+    packsDoctorOk?: boolean | null;
+    demoPackageValidateOk?: boolean | null;
+}
+export declare function buildSelfAudit(projectRoot: string, input?: ISelfAuditInput): ISelfAuditReport;
+export declare function renderSelfAuditText(report: ISelfAuditReport): string;
+//# sourceMappingURL=self-audit.d.ts.map

package/dist/self-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-audit.d.ts","sourceRoot":"","sources":["../src/self-audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,iBAAiB,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC,EAAE,EAAE,OAAO,CAAC;CACb;AAED,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAajE;AAED,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gEAAgE;IAChE,eAAe,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,wDAAwD;IACxD,aAAa,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,qBAAqB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACxC;AAED,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,GAAE,eAAoB,GAAG,gBAAgB,CAgIjG;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAWpE"}