@shrkcrft/inspector 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/tuning-query-tokens.d.ts

@@ -0,0 +1,29 @@
+/**
+ * THE tokenizer for search-tuning TRIGGERS — the `tokens` a query/task yields
+ * for `tuningBoostFor`, which a `taskHints[].whenTokens` entry must appear in.
+ *
+ * Five call sites used to tokenize for the same matcher five ways:
+ *
+ *   - `shrk search` and `search tuning explain`: split on whitespace and
+ *     `, . ; : /` — keeps `changed-only`, `c#`, `foo_bar` whole;
+ *   - the task ranker and the context re-ranker: split on `[^a-z0-9]` —
+ *     `changed-only` became `changed`, `only`;
+ *   - ranker explain: `[^a-z0-9]` AND dropped tokens shorter than 3 — `go`,
+ *     `pr`, `ci` vanished.
+ *
+ * So a hyphenated trigger fired in `shrk search` and never in `shrk task` /
+ * `shrk context`, and `shrk why` reported a tuning trace the rankers did not
+ * apply. This returns the UNION: each whitespace/punctuation token whole, plus
+ * its alphanumeric pieces (from THE identifier splitter), dropping tokens
+ * shorter than 2. It is a superset of every former variant, so no trigger that
+ * fired anywhere stops firing; one that fired in only one ranker now fires in
+ * all of them. Order is first-seen; duplicates are dropped.
+ */
+export declare function tuningQueryTokens(text: string): string[];
+/**
+ * Can a query ever produce `whenToken`? A trigger with whitespace, a separator
+ * (`, . ; : /`) or fewer than 2 characters never appears in
+ * {@link tuningQueryTokens}' output, so its task hint can never apply.
+ */
+export declare function isReachableTuningTrigger(whenToken: string): boolean;
+//# sourceMappingURL=tuning-query-tokens.d.ts.map

package/dist/tuning-query-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tuning-query-tokens.d.ts","sourceRoot":"","sources":["../src/tuning-query-tokens.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAiBxD;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAGnE"}

package/dist/tuning-query-tokens.js

@@ -0,0 +1,51 @@
+import { splitIdentifierTokens } from "./split-identifier.js";
+/**
+ * THE tokenizer for search-tuning TRIGGERS — the `tokens` a query/task yields
+ * for `tuningBoostFor`, which a `taskHints[].whenTokens` entry must appear in.
+ *
+ * Five call sites used to tokenize for the same matcher five ways:
+ *
+ *   - `shrk search` and `search tuning explain`: split on whitespace and
+ *     `, . ; : /` — keeps `changed-only`, `c#`, `foo_bar` whole;
+ *   - the task ranker and the context re-ranker: split on `[^a-z0-9]` —
+ *     `changed-only` became `changed`, `only`;
+ *   - ranker explain: `[^a-z0-9]` AND dropped tokens shorter than 3 — `go`,
+ *     `pr`, `ci` vanished.
+ *
+ * So a hyphenated trigger fired in `shrk search` and never in `shrk task` /
+ * `shrk context`, and `shrk why` reported a tuning trace the rankers did not
+ * apply. This returns the UNION: each whitespace/punctuation token whole, plus
+ * its alphanumeric pieces (from THE identifier splitter), dropping tokens
+ * shorter than 2. It is a superset of every former variant, so no trigger that
+ * fired anywhere stops firing; one that fired in only one ranker now fires in
+ * all of them. Order is first-seen; duplicates are dropped.
+ */
+export function tuningQueryTokens(text) {
+    const out = [];
+    const seen = new Set();
+    const add = (token) => {
+        if (token.length < 2 || seen.has(token))
+            return;
+        seen.add(token);
+        out.push(token);
+    };
+    for (const raw of text.toLowerCase().split(/[\s,.;:/]+/)) {
+        const token = raw.trim();
+        add(token);
+        // The input is already lowercase, so the splitter's camelCase rules are
+        // inert here: this is exactly the old `[^a-z0-9]+` split, from the one
+        // identifier tokenizer.
+        for (const piece of splitIdentifierTokens(token))
+            add(piece);
+    }
+    return out;
+}
+/**
+ * Can a query ever produce `whenToken`? A trigger with whitespace, a separator
+ * (`, . ; : /`) or fewer than 2 characters never appears in
+ * {@link tuningQueryTokens}' output, so its task hint can never apply.
+ */
+export function isReachableTuningTrigger(whenToken) {
+    const lower = whenToken.toLowerCase();
+    return tuningQueryTokens(lower).includes(lower);
+}

package/dist/typecheck-files.d.ts

@@ -0,0 +1,36 @@
+export interface ITypecheckFilesResult {
+    /** False when there was nothing to check, or TypeScript could not run. */
+    readonly ran: boolean;
+    readonly errors: readonly {
+        readonly file: string;
+        readonly line: number;
+        readonly column: number;
+        readonly code: number;
+        readonly message: string;
+    }[];
+    /** Absolute paths of the root files the program was built from. */
+    readonly checkedFiles: readonly string[];
+    /** The tsconfig whose options were applied, or null for the built-in defaults. */
+    readonly tsconfigPath: string | null;
+    /** Human note (why it did not run, or which tsconfig it used). */
+    readonly note?: string;
+}
+/**
+ * Type-check `rootNames` (absolute or `root`-relative) against `root`'s
+ * tsconfig (auto-detected unless `tsconfigPath` is given; `null` forces the
+ * strict defaults). `overlay` supplies in-memory contents for paths that are
+ * not on disk yet. By default only diagnostics IN the root files are reported;
+ * `reportOnlyUnder` widens that to every program file under a directory (so a
+ * group module an aggregator imports is checked too), excluding node_modules.
+ */
+export declare function typecheckFiles(root: string, options: {
+    readonly rootNames: readonly string[];
+    readonly overlay?: ReadonlyMap<string, string>;
+    readonly tsconfigPath?: string | null;
+    readonly reportOnlyUnder?: string;
+    /** With no tsconfig, allow `.ts` import specifiers (Bun-loaded pack assets use them). */
+    readonly allowTsExtensionsByDefault?: boolean;
+    /** Report options/global diagnostics (e.g. a broken tsconfig) as errors too. */
+    readonly includeGlobalDiagnostics?: boolean;
+}): ITypecheckFilesResult;
+//# sourceMappingURL=typecheck-files.d.ts.map

package/dist/typecheck-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typecheck-files.d.ts","sourceRoot":"","sources":["../src/typecheck-files.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS;QACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,EAAE,CAAC;IACJ,mEAAmE;IACnE,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,kFAAkF;IAClF,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAmCD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IACP,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,yFAAyF;IACzF,QAAQ,CAAC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IAC9C,gFAAgF;IAChF,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAC;CAC7C,GACA,qBAAqB,CAyGvB"}

package/dist/typecheck-files.js

@@ -0,0 +1,158 @@
+/**
+ * THE in-process TypeScript check — one `ts.Program` builder shared by
+ * `gen --typecheck` (emitted, not-yet-written files over an overlay) and
+ * `packs test|doctor|release-check --typecheck` (a pack's own assets).
+ *
+ * It used to live in the CLI layer only, so nothing below the CLI could
+ * type-check a pack; pack loading is transpile-only (Bun), and an asset with an
+ * implicit-any parameter or a misspelled field loaded with every signal green.
+ *
+ * Deterministic, read-only, never emits. Only errors (not warnings) are
+ * reported, and only for the files the caller scoped the check to.
+ */
+import * as ts from 'typescript';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve, sep } from 'node:path';
+const TSCONFIG_NAMES = ['tsconfig.json', 'tsconfig.base.json'];
+const TS_SOURCE = /\.(?:[cm]?ts|tsx)$/;
+function findTsconfig(root) {
+    for (const name of TSCONFIG_NAMES) {
+        const p = resolve(root, name);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+function pushDiagnostic(out, d, fallbackFile) {
+    if (d.category !== ts.DiagnosticCategory.Error)
+        return;
+    let line = 0;
+    let column = 0;
+    if (d.file && typeof d.start === 'number') {
+        const lc = d.file.getLineAndCharacterOfPosition(d.start);
+        line = lc.line + 1;
+        column = lc.character + 1;
+    }
+    out.push({
+        file: resolve(d.file?.fileName ?? fallbackFile),
+        line,
+        column,
+        code: d.code,
+        message: ts.flattenDiagnosticMessageText(d.messageText, '\n'),
+    });
+}
+/**
+ * Type-check `rootNames` (absolute or `root`-relative) against `root`'s
+ * tsconfig (auto-detected unless `tsconfigPath` is given; `null` forces the
+ * strict defaults). `overlay` supplies in-memory contents for paths that are
+ * not on disk yet. By default only diagnostics IN the root files are reported;
+ * `reportOnlyUnder` widens that to every program file under a directory (so a
+ * group module an aggregator imports is checked too), excluding node_modules.
+ */
+export function typecheckFiles(root, options) {
+    const rootNames = options.rootNames.map((p) => resolve(root, p)).filter((p) => TS_SOURCE.test(p));
+    if (rootNames.length === 0) {
+        return { ran: false, errors: [], checkedFiles: [], tsconfigPath: null, note: 'no TS/TSX files to check' };
+    }
+    let compilerOptions = {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        strict: true,
+        esModuleInterop: true,
+        ...(options.allowTsExtensionsByDefault ? { allowImportingTsExtensions: true } : {}),
+    };
+    const tsconfigPath = options.tsconfigPath === null
+        ? null
+        : options.tsconfigPath !== undefined
+            ? resolve(root, options.tsconfigPath)
+            : findTsconfig(root);
+    if (tsconfigPath) {
+        const read = ts.readConfigFile(tsconfigPath, (p) => {
+            try {
+                return readFileSync(p, 'utf8');
+            }
+            catch {
+                return undefined;
+            }
+        });
+        if (!read.error) {
+            const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(tsconfigPath));
+            compilerOptions = parsed.options;
+        }
+    }
+    // Force a non-emitting, lib-skipping check regardless of the project's config.
+    compilerOptions.noEmit = true;
+    compilerOptions.skipLibCheck = true;
+    compilerOptions.incremental = false;
+    delete compilerOptions.composite;
+    delete compilerOptions.outDir;
+    delete compilerOptions.declaration;
+    const overlay = new Map();
+    for (const [k, v] of options.overlay ?? [])
+        overlay.set(resolve(k), v);
+    const errors = [];
+    try {
+        const host = ts.createCompilerHost(compilerOptions, true);
+        const origGetSourceFile = host.getSourceFile.bind(host);
+        const origReadFile = host.readFile.bind(host);
+        const origFileExists = host.fileExists.bind(host);
+        host.readFile = (fileName) => {
+            const k = resolve(fileName);
+            return overlay.has(k) ? overlay.get(k) : origReadFile(fileName);
+        };
+        host.fileExists = (fileName) => overlay.has(resolve(fileName)) || origFileExists(fileName);
+        host.getSourceFile = (fileName, languageVersionOrOptions, onError, shouldCreate) => {
+            const body = overlay.get(resolve(fileName));
+            if (body !== undefined)
+                return ts.createSourceFile(fileName, body, languageVersionOrOptions, true);
+            return origGetSourceFile(fileName, languageVersionOrOptions, onError, shouldCreate);
+        };
+        const program = ts.createProgram({ rootNames, options: compilerOptions, host });
+        if (options.includeGlobalDiagnostics) {
+            for (const d of [...program.getOptionsDiagnostics(), ...program.getGlobalDiagnostics()]) {
+                pushDiagnostic(errors, d, tsconfigPath ?? root);
+            }
+        }
+        const scoped = [];
+        if (options.reportOnlyUnder) {
+            const under = resolve(options.reportOnlyUnder) + sep;
+            const roots = new Set(rootNames);
+            for (const sf of program.getSourceFiles()) {
+                const f = resolve(sf.fileName);
+                if (!roots.has(f) && (!f.startsWith(under) || f.includes(`${sep}node_modules${sep}`) || sf.isDeclarationFile)) {
+                    continue;
+                }
+                scoped.push(sf);
+            }
+        }
+        else {
+            for (const rn of rootNames) {
+                const sf = program.getSourceFile(rn);
+                if (sf)
+                    scoped.push(sf);
+            }
+        }
+        for (const sf of scoped) {
+            for (const d of [...program.getSyntacticDiagnostics(sf), ...program.getSemanticDiagnostics(sf)]) {
+                pushDiagnostic(errors, d, sf.fileName);
+            }
+        }
+    }
+    catch (e) {
+        return {
+            ran: false,
+            errors: [],
+            checkedFiles: rootNames,
+            tsconfigPath,
+            note: `TypeScript could not run: ${e.message}`,
+        };
+    }
+    return {
+        ran: true,
+        errors,
+        checkedFiles: rootNames,
+        tsconfigPath,
+        note: tsconfigPath ? `checked against ${tsconfigPath}` : 'no tsconfig found — used defaults',
+    };
+}

package/dist/uncertainty.js

@@ -85,7 +85,7 @@ function buildSuggestedCommands(task, signals) {
         out.push(`shrk coverage scaffolds --task "${task}"`);
     }
     if (signals.some((s) => s.code === 'weak-knowledge-matches' || s.code === 'low-ranker-confidence')) {
-        out.push(`shrk why-not <id> --for-task "${task}"`);
+        out.push(`shrk task "${task}" --explain-ranking`);
         out.push(`shrk search tuning explain "${task}"`);
         out.push(`shrk search "${task}" --explain`);
     }

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

@@ -1 +1 @@
-{"version":3,"file":"universal-search.d.ts","sourceRoot":"","sources":["../src/universal-search.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAgC,KAAK,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGhG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AAExE,oBAAY,gBAAgB;IAC1B,OAAO,YAAY;IACnB,OAAO,aAAa;IACpB,SAAS,cAAc;IACvB,IAAI,SAAS;IACb,IAAI,SAAS;IACb,UAAU,eAAe;IACzB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,SAAS,cAAc;IACvB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,eAAe,qBAAqB;IACpC,gBAAgB,sBAAsB;IACtC,gBAAgB,sBAAsB;IACtC,YAAY,kBAAkB;IAC9B,eAAe,sBAAsB;IACrC,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,MAAM,WAAW;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAClD,QAAQ,CAAC,aAAa,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACvD,QAAQ,CAAC,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACnD,QAAQ,CAAC,UAAU,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACrD;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,OAAO,uBAAuB,CAAC;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC;IAC5C,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AA+CD,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CA4NjC;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAmDhF;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CA8BpF"}
+{"version":3,"file":"universal-search.d.ts","sourceRoot":"","sources":["../src/universal-search.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAgC,KAAK,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGhG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AAExE,oBAAY,gBAAgB;IAC1B,OAAO,YAAY;IACnB,OAAO,aAAa;IACpB,SAAS,cAAc;IACvB,IAAI,SAAS;IACb,IAAI,SAAS;IACb,UAAU,eAAe;IACzB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,SAAS,cAAc;IACvB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,eAAe,qBAAqB;IACpC,gBAAgB,sBAAsB;IACtC,gBAAgB,sBAAsB;IACtC,YAAY,kBAAkB;IAC9B,eAAe,sBAAsB;IACrC,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,MAAM,WAAW;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAClD,QAAQ,CAAC,aAAa,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACvD,QAAQ,CAAC,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACnD,QAAQ,CAAC,UAAU,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACrD;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,OAAO,uBAAuB,CAAC;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC;IAC5C,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AA+CD,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CA8NjC;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAmDhF;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CA8BpF"}

package/dist/universal-search.js

@@ -13,7 +13,7 @@
  *   6. Uncertainty / no-match explanation
  *   7. Why these ranked
  */
-import { buildPackContributionsInventory } from "./pack-contributions-inventory.js";
+import { buildPackContributionsInventoryAsync } from "./pack-contributions-inventory.js";
 import { listConventions } from "./convention-registry.js";
 import { listPackHelpers } from "./pack-helper-registry.js";
 import { explainTaskRouting } from "./task-routing-hint-registry.js";
@@ -83,7 +83,9 @@ export async function buildUniversalSearch(inspection, query, options = {}) {
     const q = query.trim();
     const limit = options.limit ?? 8;
     // Pull pieces we'll rank against.
-    const inv = buildPackContributionsInventory(inspection);
+    // The async inventory: loader-backed ids (never the sync regex scrape's
+    // "unverified" guesses), so a search hit is an id the registry really holds.
+    const inv = await buildPackContributionsInventoryAsync(inspection);
     const conventions = await listConventions(inspection);
     const helpers = await listPackHelpers(inspection);
     const routing = await explainTaskRouting(inspection, q);
@@ -230,7 +232,7 @@ export async function buildUniversalSearch(inspection, query, options = {}) {
         sections.validation.length;
     const nextSuggestions = [];
     if (totalHits === 0) {
-        nextSuggestions.push(`shrk coverage scaffolds --task "${q}"`, `shrk feedback ingest <file>`, `shrk why <id> --for-task "${q}"`, `shrk commands suggest "${q}"`);
+        nextSuggestions.push(`shrk coverage scaffolds --task "${q}"`, `shrk feedback ingest <file>`, `shrk why <id> --for-task "${q}"`, `shrk commands search "${q}"`);
     }
     const whyTheseRanked = [
         'Scoring: exact match +20, substring +10, token ≥3 chars +3 per match.',

package/dist/unregistered-exports.d.ts

@@ -0,0 +1,19 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export interface IUnregisteredExport {
+    /** `knowledge` covers knowledge / rule / path entries; `template` covers templates. */
+    readonly kind: 'knowledge' | 'template';
+    /** Project-relative path of the aggregator (the loaded contribution file). */
+    readonly aggregator: string;
+    /** Project-relative path of the group module that exports the entry. */
+    readonly group: string;
+    readonly exportName: string;
+    readonly id: string;
+    /** 1-based line of the export in the group module (0 when not located). */
+    readonly line: number;
+    /** Owning pack when the aggregator is a pack contribution. */
+    readonly packageName?: string;
+    readonly message: string;
+}
+/** Every unregistered entry export, sorted by group then line. */
+export declare function detectUnregisteredExports(inspection: ISharkcraftInspection): Promise<readonly IUnregisteredExport[]>;
+//# sourceMappingURL=unregistered-exports.d.ts.map

package/dist/unregistered-exports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unregistered-exports.d.ts","sourceRoot":"","sources":["../src/unregistered-exports.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,MAAM,WAAW,mBAAmB;IAClC,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC;IACxC,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAgCD,kEAAkE;AAClE,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CA2EzC"}

package/dist/unregistered-exports.js

@@ -0,0 +1,141 @@
+/**
+ * Entries exported by a GROUP module that the AGGREGATOR registering it never
+ * registers — "added an entry to a group file, and it is silently invisible".
+ *
+ * A contribution file (the aggregator) imports named entries from group
+ * modules and lists them in its default array. An entry added to a group and
+ * not to that list compiles, ships, and is unknown to every lookup, with no
+ * warning. This check diffs, one level deep and deterministically:
+ *
+ *   - aggregators = the contribution files the inspection's loaders actually
+ *     imported cleanly (knowledge / rules / paths / templates — the kinds whose
+ *     loader collects entry-shaped exports);
+ *   - groups = each aggregator's RELATIVE imports (parsed by the one import
+ *     parser, `parseImportStatements`) that resolve to a file under the same
+ *     sharkcraft dir / pack root and are not themselves loaded;
+ *   - an entry-shaped export of a group (the loader's OWN predicate:
+ *     `isLikelyEntry` / `isTemplate`) whose id no registry holds is a finding.
+ *
+ * No directory globbing, and nothing is flagged for a file the aggregator
+ * never references. `export * from './group'` registers the whole group
+ * implicitly, so it yields zero findings by construction.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { safeImport } from '@shrkcrft/core';
+import { parseImportStatements } from '@shrkcrft/boundaries';
+import { isLikelyEntry } from '@shrkcrft/knowledge';
+import { isTemplate } from '@shrkcrft/templates';
+const PROBES = ['', '.ts', '.tsx', '.mts', '.js', '.mjs', '/index.ts', '/index.tsx', '/index.js'];
+const AGGREGATOR_KINDS = new Set(['knowledge', 'rules', 'paths', 'templates']);
+function isFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function resolveRelativeImport(fromFile, specifier) {
+    const base = nodePath.resolve(nodePath.dirname(fromFile), specifier);
+    const candidates = PROBES.map((ext) => base + ext);
+    // TS ESM style: `./group.js` written for `./group.ts`.
+    if (/\.m?js$/.test(specifier))
+        candidates.push(base.replace(/\.js$/, '.ts'), base.replace(/\.mjs$/, '.mts'));
+    for (const c of candidates)
+        if (isFile(c))
+            return c;
+    return null;
+}
+function exportLine(content, name) {
+    const re = name === 'default'
+        ? /^[ \t]*export[ \t]+default\b/m
+        : new RegExp(`^[ \\t]*export[ \\t]+(?:const|let|var|function|class)[ \\t]+${name.replace(/[$]/g, '\\$')}\\b`, 'm');
+    const m = re.exec(content);
+    if (!m)
+        return 0;
+    return content.slice(0, m.index).split('\n').length;
+}
+/** Every unregistered entry export, sorted by group then line. */
+export async function detectUnregisteredExports(inspection) {
+    const out = [];
+    const projectRoot = inspection.projectRoot;
+    const rel = (abs) => nodePath.relative(projectRoot, abs) || abs;
+    const loaded = new Set((inspection.loaderDiagnostics ?? []).map((d) => nodePath.resolve(d.filePath)));
+    const packRoots = new Map();
+    for (const p of inspection.packs.validPacks ?? [])
+        packRoots.set(p.packageName, nodePath.resolve(p.packageRoot));
+    // What the registries hold — the same sets `knowledge list` / `templates list` print.
+    const registered = {
+        knowledge: new Set(inspection.knowledgeEntries.map((e) => e.id)),
+        template: new Set(inspection.templateRegistry.list().map((t) => t.id)),
+    };
+    const seen = new Set();
+    const aggregators = (inspection.loaderDiagnostics ?? []).filter((d) => d.status === 'ok' && AGGREGATOR_KINDS.has(d.kind) && /\.(?:[cm]?[jt]s|tsx)$/.test(d.filePath));
+    for (const d of aggregators) {
+        const aggregator = nodePath.resolve(d.filePath);
+        const kind = d.kind === 'templates' ? 'template' : 'knowledge';
+        const root = d.packName ? packRoots.get(d.packName) : inspection.sharkcraftDir ? nodePath.resolve(inspection.sharkcraftDir) : undefined;
+        if (!root || !existsSync(aggregator))
+            continue;
+        let content;
+        try {
+            content = readFileSync(aggregator, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const imp of parseImportStatements(content)) {
+            if (imp.typeOnly || !imp.specifier.startsWith('.'))
+                continue;
+            const group = resolveRelativeImport(aggregator, imp.specifier);
+            if (!group || !group.startsWith(root + nodePath.sep) || loaded.has(group))
+                continue;
+            const imported = await safeImport(group);
+            // A group that cannot be imported breaks its aggregator too — that is the
+            // loader's failure to report, not an unregistered export.
+            if (!imported.ok)
+                continue;
+            let groupContent = '';
+            try {
+                groupContent = readFileSync(group, 'utf8');
+            }
+            catch {
+                /* line stays 0 */
+            }
+            const predicate = kind === 'template' ? isTemplate : isLikelyEntry;
+            for (const exportName of Object.keys(imported.module)) {
+                let value;
+                try {
+                    value = imported.module[exportName];
+                }
+                catch {
+                    continue;
+                }
+                const items = predicate(value) ? [value] : Array.isArray(value) ? value.filter((v) => predicate(v)) : [];
+                for (const item of items) {
+                    if (registered[kind].has(item.id))
+                        continue;
+                    const key = `${kind}\0${group}\0${exportName}\0${item.id}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    const groupRel = rel(group);
+                    const aggregatorRel = rel(aggregator);
+                    out.push({
+                        kind,
+                        aggregator: aggregatorRel,
+                        group: groupRel,
+                        exportName,
+                        id: item.id,
+                        line: exportLine(groupContent, exportName),
+                        ...(d.packName ? { packageName: d.packName } : {}),
+                        message: `export '${exportName}' (id '${item.id}') in ${groupRel} is not registered by ${aggregatorRel} — ` +
+                            `add it to the aggregator's array, or re-export the group with \`export * from './${nodePath.basename(group)}'\``,
+                    });
+                }
+            }
+        }
+    }
+    return out.sort((a, b) => a.group.localeCompare(b.group) || a.line - b.line || a.id.localeCompare(b.id));
+}

package/dist/unresolvable-reason.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Why a declared reference could not be resolved — as opposed to resolving
+ * NOWHERE (a `*-missing` finding) (round 12, ONE-CHANGE).
+ */
+export declare enum UnresolvableReason {
+    /** Its kind's registry is empty in this workspace — declare one (the declaration table names how). */
+    RegistryEmpty = "registry-empty",
+    /** No builtin, config key, local file or pack key can EVER fill its kind (THE declarability authority). */
+    UndeclarableKind = "undeclarable-kind"
+}
+//# sourceMappingURL=unresolvable-reason.d.ts.map

package/dist/unresolvable-reason.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unresolvable-reason.d.ts","sourceRoot":"","sources":["../src/unresolvable-reason.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,oBAAY,kBAAkB;IAC5B,sGAAsG;IACtG,aAAa,mBAAmB;IAChC,2GAA2G;IAC3G,gBAAgB,sBAAsB;CACvC"}

package/dist/unresolvable-reason.js

@@ -0,0 +1,11 @@
+/**
+ * Why a declared reference could not be resolved — as opposed to resolving
+ * NOWHERE (a `*-missing` finding) (round 12, ONE-CHANGE).
+ */
+export var UnresolvableReason;
+(function (UnresolvableReason) {
+    /** Its kind's registry is empty in this workspace — declare one (the declaration table names how). */
+    UnresolvableReason["RegistryEmpty"] = "registry-empty";
+    /** No builtin, config key, local file or pack key can EVER fill its kind (THE declarability authority). */
+    UnresolvableReason["UndeclarableKind"] = "undeclarable-kind";
+})(UnresolvableReason || (UnresolvableReason = {}));

package/dist/upgrade-advisor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade-advisor.d.ts","sourceRoot":"","sources":["../src/upgrade-advisor.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,sBAAsB,kCAAkC,CAAC;AAEtE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,sBAAsB,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAiDD,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3C,oBAAoB,CAwDtB"}
+{"version":3,"file":"upgrade-advisor.d.ts","sourceRoot":"","sources":["../src/upgrade-advisor.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGvE,eAAO,MAAM,sBAAsB,kCAAkC,CAAC;AAEtE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,sBAAsB,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAiDD,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3C,oBAAoB,CA8DtB"}

package/dist/upgrade-advisor.js

@@ -6,6 +6,7 @@
  */
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { detectSharkcraftRepo } from "./self-audit.js";
 export const UPGRADE_ADVISOR_SCHEMA = 'sharkcraft.upgrade-advisor/v1';
 function detectSchemaVersion(text) {
     const m = /"schema"\s*:\s*"([^"]+)"/.exec(text);
@@ -68,7 +69,7 @@ export function buildUpgradeAdvice(inspection, options = {}) {
             id: 'repository-map-v1-present',
             severity: 'info',
             message: 'sharkcraft.repository-map/v1 artefacts found. sharkcraft.repository-intelligence/v1 ships alongside it.',
-            suggestedAction: 'No action required; run `shrk intelligence graph` for the new surface.',
+            suggestedAction: 'No action required; run `shrk graph hubs` for the new surface.',
         });
     }
     if (detected['sharkcraft.feature-bundle/v1']) {
@@ -89,14 +90,20 @@ export function buildUpgradeAdvice(inspection, options = {}) {
             suggestedAction: 'After upgrade, re-run adoption with `--record-checkpoint` if hashes diverge.',
         });
     }
-    const recommendedSteps = [
-        'shrk doctor',
-        'shrk commands doctor',
-        'shrk safety audit',
-        'shrk release readiness',
-        'bun x tsc -p tsconfig.base.json --noEmit',
-        'bun test',
-    ];
+    // `commands doctor` / `release readiness` (and the tool's own tsc / test
+    // scripts) maintain SharkCraft itself: outside its repository they exit 78
+    // through the surface gate (THE host authority, `detectSharkcraftRepo`), so a
+    // consumer is pointed at the aggregate gate instead.
+    const recommendedSteps = detectSharkcraftRepo(inspection.projectRoot)
+        ? [
+            'shrk doctor',
+            'shrk commands doctor',
+            'shrk safety audit',
+            'shrk release readiness',
+            'bun x tsc -p tsconfig.base.json --noEmit',
+            'bun test',
+        ]
+        : ['shrk doctor', 'shrk safety audit', 'shrk quality'];
     return {
         schema: UPGRADE_ADVISOR_SCHEMA,
         generatedAt: new Date().toISOString(),

package/dist/validate-contribution-file.d.ts

@@ -0,0 +1,4 @@
+import type { IContributionFileValidation } from './i-contribution-file-validation.js';
+/** Validate `file`, declared under manifest `slot`. */
+export declare function validateContributionFile(slot: string, file: string): Promise<IContributionFileValidation>;
+//# sourceMappingURL=validate-contribution-file.d.ts.map

package/dist/validate-contribution-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-contribution-file.d.ts","sourceRoot":"","sources":["../src/validate-contribution-file.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAsEvF,uDAAuD;AACvD,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAyI/G"}