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

package/dist/reuse/rank-reuse-candidates.js

@@ -0,0 +1,212 @@
+import { MatchConfidenceVerdict, ReuseCandidateSource, ReuseMatchSource, ReuseNameMatch, } from '@shrkcrft/core';
+import { curatedReuseSuggestion, rankReuseSuggestions } from "./rank-reuse-suggestions.js";
+import { isCuratedExport } from "./resolve-curated-reuse.js";
+import { tokenizeReuseIntent } from "./reuse-tokenize.js";
+import { reuseNameExtraTokens, reuseNameHits, scoreReuseName } from "./score-reuse-name.js";
+import { isConfidentReuseMatch, reuseConfidenceFloor, scoreReusePrimitive, } from "./score-reuse-primitive.js";
+/** Declaration kinds that exist only at the type level. */
+const TYPE_KINDS = new Set(['interface', 'type-alias']);
+/** A type-only export (interface / type alias) — excluded from reuse answers unless asked for. */
+export function isReuseTypeKind(declKind) {
+    return TYPE_KINDS.has(declKind);
+}
+/** A test file never holds a construct to reuse. */
+export function isReuseTestPath(path) {
+    return (/\.(test|spec)\.[cm]?[jt]sx?$/.test(path) || path.includes('/__tests__/') || path.startsWith('__tests__/'));
+}
+/** A NAME that answers the intent: every intent token is one of its name tokens (exact / covers). */
+export function reuseNameAnswers(m) {
+    return m === ReuseNameMatch.Exact || m === ReuseNameMatch.Covers;
+}
+/**
+ * THE curation-gap predicate. The lookup's `curationGap` and `shrk reuse
+ * coverage`'s `shadowed` both call it, so the two agree by construction: an
+ * uncurated export answers the intent by NAME (exact / covers) while the best
+ * curated candidate names it only in part, or not at all (it matched through
+ * its roles / keywords / description).
+ */
+export function isReuseCurationGap(bestCuratedNameMatch, uncuratedNameAnswers) {
+    return uncuratedNameAnswers > 0 && bestCuratedNameMatch !== undefined && !reuseNameAnswers(bestCuratedNameMatch);
+}
+/**
+ * Intent → the construct to reuse, ranked over the curated `reusePrimitives[]`
+ * AND (when a surface is given) the workspace's public export surface.
+ *
+ * Pure: the surface is INJECTED (the CLI reads it from the code graph), so the
+ * engine stays callable from a read-only MCP tool and the inspector never
+ * imports the graph.
+ *
+ * Tiers (lower wins; see `IReuseCandidate.tier`): curated whose NAME answers
+ * the intent (exact / covers) → uncurated exact name → uncurated name covering
+ * the intent → curated that names it only in part, or only through metadata.
+ * Within a tier: score desc, then the closer name (fewer extra name tokens),
+ * then symbol, then declaring file. An uncurated PARTIAL name match never
+ * becomes an answer; it is offered as a did-you-mean only when nothing is.
+ *
+ * The export pool excludes constructs already curated (name AND declaring
+ * file, see `curatedDeclaredIn`), names a curated entry `supersedes` (reported
+ * in `superseded`), type-level kinds unless `includeTypes`, and test files.
+ */
+export function rankReuseCandidates(primitives, surface, intent, opts = {}) {
+    const tokens = tokenizeReuseIntent(intent);
+    const count = tokens.length;
+    const limit = Math.max(1, Math.floor(opts.limit ?? 3));
+    const suggestLimit = Math.max(1, Math.floor(opts.suggestLimit ?? 5));
+    const confidenceOf = (hits) => (count === 0 ? 0 : hits / count);
+    // ── curated ────────────────────────────────────────────────────────────
+    const scored = primitives
+        .map((p) => ({ p, d: scoreReusePrimitive(p, tokens) }))
+        .filter((x) => x.d.score > 0)
+        .sort((a, b) => b.d.score - a.d.score || a.p.symbol.localeCompare(b.p.symbol));
+    const confidentCurated = scored.filter((x) => isConfidentReuseMatch(x.d, count));
+    const curatedCandidate = (x, tier) => ({
+        symbol: x.p.symbol,
+        source: ReuseCandidateSource.Curated,
+        tier,
+        score: x.d.score,
+        confidence: confidenceOf(x.d.matched.length),
+        matched: x.d.matched,
+        matchedVia: x.d.matchedVia,
+        nameMatch: x.d.nameMatch,
+        primitive: x.p,
+    });
+    // Tier 1 only when the curated NAME answers the intent. A curated entry that
+    // shares one token of a three-token intent (`RangeSlider` for "date range
+    // picker") must not outrank the exactly-named export: it ranks with the
+    // metadata-only matches, below every uncurated exact / covering name.
+    const tier1 = confidentCurated.filter((x) => reuseNameAnswers(x.d.nameMatch)).map((x) => curatedCandidate(x, 1));
+    const tier4 = confidentCurated.filter((x) => !reuseNameAnswers(x.d.nameMatch)).map((x) => curatedCandidate(x, 4));
+    // ── uncurated export surface ──────────────────────────────────────────
+    const surfaceSearched = surface !== undefined && opts.curatedOnly !== true;
+    const superseded = [];
+    const exact = [];
+    const covers = [];
+    const partial = [];
+    if (surface !== undefined && surfaceSearched) {
+        const curatedNames = new Set(primitives.map((p) => p.symbol));
+        const supersededBy = new Map();
+        for (const p of primitives) {
+            for (const name of p.supersedes ?? []) {
+                const by = supersededBy.get(name);
+                if (by)
+                    by.push(p.symbol);
+                else
+                    supersededBy.set(name, [p.symbol]);
+            }
+        }
+        const packageDir = new Map(surface.roots.map((r) => [r.package, r.dir]));
+        const bySymbolId = new Map();
+        for (const e of surface.exports) {
+            if (isReuseTestPath(e.declaredIn))
+                continue;
+            if (opts.includeTypes !== true && isReuseTypeKind(e.declKind))
+                continue;
+            if (isCuratedExport(e, curatedNames, opts.curatedDeclaredIn))
+                continue;
+            const nameMatch = scoreReuseName(e.name, tokens);
+            if (nameMatch === ReuseNameMatch.None)
+                continue;
+            const by = supersededBy.get(e.name);
+            if (by) {
+                superseded.push({ symbol: e.name, package: e.package, supersededBy: by });
+                continue;
+            }
+            const hits = reuseNameHits(e.name, tokens);
+            const candidate = {
+                symbol: e.name,
+                source: ReuseCandidateSource.ExportSurface,
+                tier: nameMatch === ReuseNameMatch.Exact ? 2 : nameMatch === ReuseNameMatch.Covers ? 3 : 0,
+                score: hits.length,
+                confidence: confidenceOf(hits.length),
+                matched: hits,
+                matchedVia: [ReuseMatchSource.Symbol],
+                nameMatch,
+                export: e,
+            };
+            // One construct exposed by several packages (a sibling re-exports it):
+            // keep the package that DECLARES it — that is the import to copy. The
+            // surface is sorted by package, so without an owner the first one stays.
+            const prev = bySymbolId.get(e.symbolId)?.export;
+            const replaces = prev === undefined ||
+                (declaresOwnExport(e, packageDir) && !declaresOwnExport(prev, packageDir));
+            if (replaces)
+                bySymbolId.set(e.symbolId, candidate);
+        }
+        for (const c of bySymbolId.values()) {
+            if (c.nameMatch === ReuseNameMatch.Exact)
+                exact.push(c);
+            else if (c.nameMatch === ReuseNameMatch.Covers)
+                covers.push(c);
+            else
+                partial.push(c);
+        }
+        const byUncurated = (a, b) => b.score - a.score ||
+            reuseNameExtraTokens(a.symbol, tokens) - reuseNameExtraTokens(b.symbol, tokens) ||
+            compare(a.symbol, b.symbol) ||
+            compare(a.export?.declaredIn ?? '', b.export?.declaredIn ?? '') ||
+            compare(a.export?.package ?? '', b.export?.package ?? '');
+        exact.sort(byUncurated);
+        covers.sort(byUncurated);
+        partial.sort(byUncurated);
+    }
+    const results = [...tier1, ...exact, ...covers, ...tier4].slice(0, limit);
+    const nameAnswered = tier1.length + exact.length + covers.length > 0;
+    // The best curated candidate is tier 1's head when any curated NAME answers.
+    const curationGap = isReuseCurationGap((tier1[0] ?? tier4[0])?.nameMatch, exact.length + covers.length);
+    let verdict;
+    let suggestions;
+    if (results.length > 0) {
+        verdict = MatchConfidenceVerdict.Confident;
+        suggestions = [];
+    }
+    else {
+        const weak = [
+            ...scored.map((x) => curatedReuseSuggestion(x.p, x.d, count)),
+            ...partial.map(uncuratedSuggestion),
+        ];
+        if (weak.length > 0) {
+            verdict = MatchConfidenceVerdict.NoConfidentMatch;
+            suggestions = weak.slice(0, suggestLimit);
+        }
+        else {
+            verdict = MatchConfidenceVerdict.NoMatch;
+            suggestions = rankReuseSuggestions(primitives, tokens, suggestLimit);
+        }
+    }
+    const bestScore = Math.max(0, ...results.map((r) => r.score), ...suggestions.map((s) => s.score));
+    return {
+        tokens,
+        confident: results.length > 0,
+        verdict,
+        floor: reuseConfidenceFloor(count),
+        bestScore,
+        results,
+        suggestions,
+        superseded,
+        curationGap,
+        nameAnswered,
+        surfaceSearched,
+    };
+}
+function uncuratedSuggestion(c) {
+    return {
+        symbol: c.symbol,
+        score: c.score,
+        confidence: c.confidence,
+        matched: c.matched,
+        roles: [],
+        source: c.source,
+        nameMatch: c.nameMatch,
+        matchedVia: c.matchedVia,
+        ...(c.export ? { package: c.export.package, declaredIn: c.export.declaredIn } : {}),
+    };
+}
+/** Is `e` exposed by the package whose directory declares it? */
+function declaresOwnExport(e, packageDir) {
+    const dir = packageDir.get(e.package);
+    return dir !== undefined && dir.length > 0 && (e.declaredIn === dir || e.declaredIn.startsWith(`${dir}/`));
+}
+/** Locale-independent ordering, so a ranking is byte-stable across machines. */
+function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}

package/dist/reuse/rank-reuse-options.d.ts

@@ -0,0 +1,20 @@
+/** Options for `rankReuseCandidates`. */
+export interface IRankReuseOptions {
+    /** Cap on confident results. Default 3. */
+    readonly limit?: number;
+    /** Cap on did-you-mean suggestions. Default 5. */
+    readonly suggestLimit?: number;
+    /** Consider type-level exports (interfaces, type aliases). Default false. */
+    readonly includeTypes?: boolean;
+    /** Ignore the export surface: curated `reusePrimitives[]` only (the pre-round-11 ranking). */
+    readonly curatedOnly?: boolean;
+    /**
+     * Curated symbol → the file its RESOLVED declaration lives in (build it with
+     * `curatedDeclarationMap` over `resolveCuratedReuse` — the same map `shrk
+     * reuse coverage` excludes by). An export with a curated name declared
+     * ELSEWHERE is a different construct and stays a candidate. A name absent
+     * from the map is excluded by name alone.
+     */
+    readonly curatedDeclaredIn?: ReadonlyMap<string, readonly string[]>;
+}
+//# sourceMappingURL=rank-reuse-options.d.ts.map

package/dist/reuse/rank-reuse-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rank-reuse-options.d.ts","sourceRoot":"","sources":["../../src/reuse/rank-reuse-options.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,8FAA8F;IAC9F,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;CACrE"}

package/dist/reuse/rank-reuse-options.js

@@ -0,0 +1 @@
+export {};

package/dist/reuse/rank-reuse-suggestions.d.ts

@@ -0,0 +1,15 @@
+import { type IReusePrimitive } from '@shrkcrft/core';
+import type { IReuseMatchDetail } from './reuse-match-detail.js';
+import type { IReuseSuggestion } from './reuse-suggestion.js';
+/**
+ * Rank ALL curated primitives by the matcher's own score (descending; ties
+ * broken by symbol name so the order is deterministic), then return the top-`k`
+ * as scored did-you-mean suggestions. Pure — no graph, no IO. When every
+ * candidate scores 0 (a nonsense intent that shares no term) the result is the
+ * alphabetically-first `k` primitives, each with `score: 0`; the caller states
+ * "no candidate shares any term" in that case rather than dumping the catalog.
+ */
+export declare function rankReuseSuggestions(primitives: readonly IReusePrimitive[], tokens: readonly string[], k: number): IReuseSuggestion[];
+/** One curated primitive as a suggestion row. */
+export declare function curatedReuseSuggestion(p: IReusePrimitive, detail: IReuseMatchDetail, tokenCount: number): IReuseSuggestion;
+//# sourceMappingURL=rank-reuse-suggestions.d.ts.map

package/dist/reuse/rank-reuse-suggestions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rank-reuse-suggestions.d.ts","sourceRoot":"","sources":["../../src/reuse/rank-reuse-suggestions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAG9D;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,CAAC,EAAE,MAAM,GACR,gBAAgB,EAAE,CAOpB;AAED,iDAAiD;AACjD,wBAAgB,sBAAsB,CACpC,CAAC,EAAE,eAAe,EAClB,MAAM,EAAE,iBAAiB,EACzB,UAAU,EAAE,MAAM,GACjB,gBAAgB,CAWlB"}

package/dist/reuse/rank-reuse-suggestions.js

@@ -0,0 +1,31 @@
+import { ReuseCandidateSource } from '@shrkcrft/core';
+import { scoreReusePrimitive } from "./score-reuse-primitive.js";
+/**
+ * Rank ALL curated primitives by the matcher's own score (descending; ties
+ * broken by symbol name so the order is deterministic), then return the top-`k`
+ * as scored did-you-mean suggestions. Pure — no graph, no IO. When every
+ * candidate scores 0 (a nonsense intent that shares no term) the result is the
+ * alphabetically-first `k` primitives, each with `score: 0`; the caller states
+ * "no candidate shares any term" in that case rather than dumping the catalog.
+ */
+export function rankReuseSuggestions(primitives, tokens, k) {
+    const cap = Math.max(1, Math.floor(k));
+    return primitives
+        .map((p) => ({ p, detail: scoreReusePrimitive(p, tokens) }))
+        .sort((a, b) => b.detail.score - a.detail.score || a.p.symbol.localeCompare(b.p.symbol))
+        .slice(0, cap)
+        .map(({ p, detail }) => curatedReuseSuggestion(p, detail, tokens.length));
+}
+/** One curated primitive as a suggestion row. */
+export function curatedReuseSuggestion(p, detail, tokenCount) {
+    return {
+        symbol: p.symbol,
+        score: detail.score,
+        confidence: tokenCount === 0 ? 0 : detail.matched.length / tokenCount,
+        matched: detail.matched,
+        roles: p.roles,
+        source: ReuseCandidateSource.Curated,
+        nameMatch: detail.nameMatch,
+        matchedVia: detail.matchedVia,
+    };
+}

package/dist/reuse/resolve-curated-reuse.d.ts

@@ -0,0 +1,43 @@
+import { ReuseImportStyle, type IPublicExportSurface, type IReusePrimitive } from '@shrkcrft/core';
+import type { IReuseCuratedResolution } from './reuse-curated-resolution.js';
+import type { IReuseSymbolLookup } from './reuse-symbol-lookup.js';
+/**
+ * Resolve ONE curated entry against the code: which declaration it names,
+ * whether its `importPath` exposes it, and how the copy-paste import binds it.
+ *
+ * The one authority for all three: `shrk reuse` prints a curated row from it,
+ * and `shrk reuse coverage` judges the entry by it — so the printed import line
+ * and "would that import compile?" cannot disagree (a DEFAULT export gets
+ * `import X from '…'`, never a named import that does not exist), and the
+ * curated construct excluded from the uncurated pool is the same in both.
+ *
+ * The `importPath` is checked against the module's real export surface: a
+ * workspace package root through the public surface, any other specifier
+ * through `lookup.specifierExport` (the same ESM walk, from the file consumers'
+ * imports of it resolved to).
+ *
+ * Pure: surface and lookup are injected (the inspector never imports the
+ * graph). Without them nothing is checked — the import is printed as
+ * configured, named, and `importPathAgrees` is absent.
+ */
+export declare function resolveCuratedReuse(p: IReusePrimitive, surface: IPublicExportSurface | undefined, lookup: IReuseSymbolLookup | undefined): IReuseCuratedResolution;
+/** The copy-paste import line for `symbol` from `specifier`, bound the way the module exports it. */
+export declare function reuseImportLine(symbol: string, specifier: string, style: ReuseImportStyle): string;
+/**
+ * Curated symbol → the file(s) its resolved declaration lives in — the exact
+ * `curatedDeclaredIn` the ranker excludes by, and the one coverage excludes by.
+ * A curated name whose declaration did not resolve is absent (so it is excluded
+ * by name alone).
+ */
+export declare function curatedDeclarationMap(primitives: readonly IReusePrimitive[], resolutions: readonly IReuseCuratedResolution[]): Map<string, string[]>;
+/**
+ * Is export `e` a construct a curated entry already names? Name AND declaring
+ * file: an export sharing a curated name but declared ELSEWHERE is a different
+ * construct and stays a candidate. A curated name absent from the map (its
+ * declaration did not resolve) is matched by name alone.
+ */
+export declare function isCuratedExport(e: {
+    readonly name: string;
+    readonly declaredIn: string;
+}, curatedNames: ReadonlySet<string>, curatedDeclaredIn: ReadonlyMap<string, readonly string[]> | undefined): boolean;
+//# sourceMappingURL=resolve-curated-reuse.d.ts.map

package/dist/reuse/resolve-curated-reuse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-curated-reuse.d.ts","sourceRoot":"","sources":["../../src/reuse/resolve-curated-reuse.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAEhB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAC7E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAInE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,eAAe,EAClB,OAAO,EAAE,oBAAoB,GAAG,SAAS,EACzC,MAAM,EAAE,kBAAkB,GAAG,SAAS,GACrC,uBAAuB,CA0DzB;AAED,qGAAqG;AACrG,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAIlG;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,WAAW,EAAE,SAAS,uBAAuB,EAAE,GAC9C,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAUvB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,CAAC,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EACzD,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,EACjC,iBAAiB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,GAAG,SAAS,GACpE,OAAO,CAIT"}

package/dist/reuse/resolve-curated-reuse.js

@@ -0,0 +1,115 @@
+import { ReuseImportStyle, } from '@shrkcrft/core';
+/**
+ * Resolve ONE curated entry against the code: which declaration it names,
+ * whether its `importPath` exposes it, and how the copy-paste import binds it.
+ *
+ * The one authority for all three: `shrk reuse` prints a curated row from it,
+ * and `shrk reuse coverage` judges the entry by it — so the printed import line
+ * and "would that import compile?" cannot disagree (a DEFAULT export gets
+ * `import X from '…'`, never a named import that does not exist), and the
+ * curated construct excluded from the uncurated pool is the same in both.
+ *
+ * The `importPath` is checked against the module's real export surface: a
+ * workspace package root through the public surface, any other specifier
+ * through `lookup.specifierExport` (the same ESM walk, from the file consumers'
+ * imports of it resolved to).
+ *
+ * Pure: surface and lookup are injected (the inspector never imports the
+ * graph). Without them nothing is checked — the import is printed as
+ * configured, named, and `importPathAgrees` is absent.
+ */
+export function resolveCuratedReuse(p, surface, lookup) {
+    const decls = lookup?.declarationsOf(p.symbol) ?? [];
+    let target;
+    let importPathAgrees;
+    let importPathNote;
+    if (p.importPath !== undefined && surface !== undefined) {
+        const spec = p.importPath;
+        if (surface.roots.some((r) => r.package === spec)) {
+            target = surface.exports.find((e) => e.package === spec && e.name === p.symbol);
+            importPathAgrees = target !== undefined;
+        }
+        else if (surface.packagesWithoutEntry.some((w) => w.package === spec)) {
+            importPathNote = `package ${spec} has no resolved entry, so the import line was not checked`;
+        }
+        else {
+            const hit = lookup?.specifierExport?.(spec, p.symbol);
+            if (hit === undefined) {
+                importPathNote = `'${spec}' is not a workspace package root and no indexed import resolves it, so the import line was not checked`;
+            }
+            else {
+                importPathAgrees = hit !== null;
+                if (hit !== null)
+                    target = hit;
+            }
+        }
+    }
+    // The declaration: pinned by the importPath when it resolved; otherwise the
+    // same deterministic pick `shrk reuse` always made (exported first, by path),
+    // with a public one ahead of both.
+    const onSurface = new Set((surface?.exports ?? []).filter((e) => e.name === p.symbol).map((e) => e.symbolId));
+    const rank = (d) => onSurface.has(d.symbolId) ? 0 : d.isExported ? 1 : 2;
+    const ordered = [...decls].sort((a, b) => rank(a) - rank(b) || a.path.localeCompare(b.path));
+    const declaration = target !== undefined
+        ? {
+            path: target.declaredIn,
+            symbolId: target.symbolId,
+            isExported: true,
+            ...(target.line !== undefined ? { line: target.line } : {}),
+            ...(target.declKind !== undefined ? { declKind: target.declKind } : {}),
+        }
+        : ordered[0];
+    const exported = decls.filter((d) => d.isExported);
+    const pool = exported.length > 0 ? exported : decls;
+    const alternates = [...new Set(pool.map((d) => d.path))]
+        .filter((path) => path !== declaration?.path)
+        .sort((a, b) => a.localeCompare(b));
+    const importStyle = target?.isDefault === true ? ReuseImportStyle.Default : ReuseImportStyle.Named;
+    return {
+        ...(declaration !== undefined ? { declaration } : {}),
+        alternates,
+        ...(p.importPath !== undefined
+            ? { importStyle, importLine: reuseImportLine(p.symbol, p.importPath, importStyle) }
+            : {}),
+        ...(importPathAgrees !== undefined ? { importPathAgrees } : {}),
+        ...(importPathNote !== undefined ? { importPathNote } : {}),
+    };
+}
+/** The copy-paste import line for `symbol` from `specifier`, bound the way the module exports it. */
+export function reuseImportLine(symbol, specifier, style) {
+    return style === ReuseImportStyle.Default
+        ? `import ${symbol} from '${specifier}';`
+        : `import { ${symbol} } from '${specifier}';`;
+}
+/**
+ * Curated symbol → the file(s) its resolved declaration lives in — the exact
+ * `curatedDeclaredIn` the ranker excludes by, and the one coverage excludes by.
+ * A curated name whose declaration did not resolve is absent (so it is excluded
+ * by name alone).
+ */
+export function curatedDeclarationMap(primitives, resolutions) {
+    const out = new Map();
+    primitives.forEach((p, i) => {
+        const path = resolutions[i]?.declaration?.path;
+        if (path === undefined)
+            return;
+        const list = out.get(p.symbol);
+        if (list === undefined)
+            out.set(p.symbol, [path]);
+        else if (!list.includes(path))
+            list.push(path);
+    });
+    return out;
+}
+/**
+ * Is export `e` a construct a curated entry already names? Name AND declaring
+ * file: an export sharing a curated name but declared ELSEWHERE is a different
+ * construct and stays a candidate. A curated name absent from the map (its
+ * declaration did not resolve) is matched by name alone.
+ */
+export function isCuratedExport(e, curatedNames, curatedDeclaredIn) {
+    if (!curatedNames.has(e.name))
+        return false;
+    const known = curatedDeclaredIn?.get(e.name);
+    return known === undefined || known.length === 0 || known.includes(e.declaredIn);
+}

package/dist/reuse/reuse-candidate.d.ts

@@ -0,0 +1,29 @@
+import type { IPublicExport, IReusePrimitive, ReuseCandidateSource, ReuseMatchSource, ReuseNameMatch } from '@shrkcrft/core';
+/** One confident reuse answer, before the CLI enriches it with graph detail. */
+export interface IReuseCandidate {
+    readonly symbol: string;
+    readonly source: ReuseCandidateSource;
+    /**
+     * Ranking tier (lower wins):
+     *   1 — curated, its NAME answers the intent (exact / covers);
+     *   2 — uncurated, exact name match;
+     *   3 — uncurated, the name covers every intent token;
+     *   4 — curated, its name matches only PART of the intent, or it matched
+     *       only through roles / keywords / description.
+     * A curated entry that names the construct stays authoritative over an
+     * uncurated one; an exactly-named export beats a curated hit that shares
+     * one token of its name, or none.
+     */
+    readonly tier: number;
+    readonly score: number;
+    /** Fraction of distinct intent tokens that hit (0..1). */
+    readonly confidence: number;
+    readonly matched: readonly string[];
+    readonly matchedVia: readonly ReuseMatchSource[];
+    readonly nameMatch: ReuseNameMatch;
+    /** Set for `curated` candidates. */
+    readonly primitive?: IReusePrimitive;
+    /** Set for `export-surface` candidates. */
+    readonly export?: IPublicExport;
+}
+//# sourceMappingURL=reuse-candidate.d.ts.map

package/dist/reuse/reuse-candidate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reuse-candidate.d.ts","sourceRoot":"","sources":["../../src/reuse/reuse-candidate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACf,MAAM,gBAAgB,CAAC;AAExB,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,oCAAoC;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;IACrC,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;CACjC"}

package/dist/reuse/reuse-candidate.js

@@ -0,0 +1 @@
+export {};

package/dist/reuse/reuse-coverage-report.d.ts

@@ -0,0 +1,74 @@
+import type { IUnfollowedReExport, ReuseMatchSource, ReuseNameMatch } from '@shrkcrft/core';
+import type { IReuseCuratedCoverage } from './reuse-curated-coverage.js';
+/**
+ * Curated reuse index vs the real public export surface — the numbers that make
+ * curation drift measurable instead of silent (`shrk reuse coverage`).
+ */
+export interface IReuseCoverageReport {
+    /** Every in-scope curated entry, in config order. */
+    readonly curated: readonly IReuseCuratedCoverage[];
+    /** Curated entries a `--package` narrowing excluded (deliberate, not a gap). */
+    readonly curatedOutOfScope: number;
+    readonly surface: {
+        readonly roots: readonly {
+            readonly package: string;
+            readonly dir: string;
+            readonly entryFile: string;
+        }[];
+        /** In-scope packages whose exports were NOT measured, each with why. */
+        readonly packagesWithoutEntry: readonly {
+            readonly package: string;
+            readonly dir: string;
+            readonly reason: string;
+        }[];
+        /** Public exports in scope (per package × name). */
+        readonly all: number;
+        /** Public exports that are not type-level (everything but interfaces / type aliases). */
+        readonly value: number;
+        readonly byKind: Readonly<Record<string, number>>;
+        /** In-scope re-exports not followed to a declaration (`unfollowedReExports.length`). */
+        readonly unresolvedReExports: number;
+        /**
+         * Each of them, classified. An `unresolved` one is part of its package's
+         * surface that was NOT measured; an `external` one leaves the workspace.
+         */
+        readonly unfollowedReExports: readonly IUnfollowedReExport[];
+    };
+    /** In-scope curated entries on the public surface. */
+    readonly curatedPublic: number;
+    /** …of which the public construct is not type-level. */
+    readonly curatedPublicValue: number;
+    /** curatedPublicValue / value — the primary ratio. Absent when value is 0. */
+    readonly ratioValue?: number;
+    /** curatedPublic / all. Absent when all is 0. */
+    readonly ratioAll?: number;
+    /** Public exports no curated entry names or supersedes (capped; see uncoveredTotal). */
+    readonly uncovered: readonly {
+        readonly name: string;
+        readonly package: string;
+        readonly declaredIn: string;
+        readonly declKind: string;
+    }[];
+    readonly uncoveredTotal: number;
+    /**
+     * Curation gaps: an uncovered export whose own name, asked as an intent,
+     * gets a DIFFERENT curated answer from the reuse lookup — the lookup's own
+     * ranker, curated-only, so this list and `shrk reuse --curated-only` cannot
+     * disagree.
+     */
+    readonly shadowed: readonly {
+        readonly export: string;
+        readonly package: string;
+        readonly declaredIn: string;
+        readonly answeredBy: string;
+        readonly matchedVia: readonly ReuseMatchSource[];
+        readonly nameMatch: ReuseNameMatch;
+    }[];
+    /** Public exports a curated entry deliberately `supersedes` — covered by intent. */
+    readonly superseded: readonly {
+        readonly export: string;
+        readonly package: string;
+        readonly supersededBy: readonly string[];
+    }[];
+}
+//# sourceMappingURL=reuse-coverage-report.d.ts.map

package/dist/reuse/reuse-coverage-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reuse-coverage-report.d.ts","sourceRoot":"","sources":["../../src/reuse/reuse-coverage-report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAEzE;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACnD,gFAAgF;IAChF,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,KAAK,EAAE,SAAS;YAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAC1G,wEAAwE;QACxE,QAAQ,CAAC,oBAAoB,EAAE,SAAS;YAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QACtH,oDAAoD;QACpD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,yFAAyF;QACzF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAClD,wFAAwF;QACxF,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;QACrC;;;WAGG;QACH,QAAQ,CAAC,mBAAmB,EAAE,SAAS,mBAAmB,EAAE,CAAC;KAC9D,CAAC;IACF,sDAAsD;IACtD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,SAAS,EAAE,SAAS;QAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;KAC3B,EAAE,CAAC;IACJ,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;QACjD,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;KACpC,EAAE,CAAC;IACJ,oFAAoF;IACpF,QAAQ,CAAC,UAAU,EAAE,SAAS;QAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;KAC1C,EAAE,CAAC;CACL"}

package/dist/reuse/reuse-coverage-report.js

@@ -0,0 +1 @@
+export {};

package/dist/reuse/reuse-curated-coverage.d.ts

@@ -0,0 +1,36 @@
+import type { ReuseImportStyle } from '@shrkcrft/core';
+import type { ReuseCuratedStatus } from './reuse-curated-status.js';
+/** One curated `reusePrimitives[]` entry measured against the code graph. */
+export interface IReuseCuratedCoverage {
+    readonly symbol: string;
+    readonly status: ReuseCuratedStatus;
+    /**
+     * False when the status could not be measured: the only exported
+     * declarations live in a package with no resolved entry, so whether they are
+     * public is unknown (the status then reads as the best available, NOT as a
+     * finding).
+     */
+    readonly statusMeasured: boolean;
+    /** Why the status was not measured. */
+    readonly statusNote?: string;
+    /** Packages whose public surface exposes the symbol. */
+    readonly publicIn: readonly string[];
+    /** Every indexed declaration of the name. */
+    readonly declaredIn: readonly string[];
+    readonly declKind?: string;
+    /** Real consumer files of the (primary) declaration, when the graph was asked. */
+    readonly consumers?: number;
+    readonly importPath?: string;
+    /**
+     * `true` / `false` when the configured `importPath` was checked: does the
+     * module it names expose the symbol (would the copy-paste import `shrk reuse`
+     * prints compile)? Absent when it could not be checked — see `importPathNote`.
+     */
+    readonly importPathAgrees?: boolean;
+    readonly importPathNote?: string;
+    /** How the printed import binds the symbol — `default` for a default export. */
+    readonly importStyle?: ReuseImportStyle;
+    /** The exact import line `shrk reuse` prints for this entry (same resolver). */
+    readonly importLine?: string;
+}
+//# sourceMappingURL=reuse-curated-coverage.d.ts.map

package/dist/reuse/reuse-curated-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reuse-curated-coverage.d.ts","sourceRoot":"","sources":["../../src/reuse/reuse-curated-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,uCAAuC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,gFAAgF;IAChF,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IACxC,gFAAgF;IAChF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B"}

package/dist/reuse/reuse-curated-coverage.js

@@ -0,0 +1 @@
+export {};