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

package/dist/resolve-project-config.js

@@ -19,12 +19,63 @@
  * dropped with a diagnostic. Pack elements are validated with the SAME exported
  * zod schemas the config loader uses, so a malformed pack element is skipped
  * (with a diagnostic) rather than crashing config resolution.
+ *
+ * Round 12 (12.1): every pack element the merge refuses — schema-invalid, a
+ * vetoed shell command, a key collision, an unresolvable `$use` — is also a
+ * structured rejection in {@link IResolvedProjectConfig.planeOutcomes}, and
+ * every adopted one an accepted entry, so THE contribution rejection channel
+ * reports gate-plane contributions like every other kind.
  */
 import { existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { importModuleViaLoader, ok, } from '@shrkcrft/core';
-import { BaselineRuleSchema, GeneratedArtifactRuleSchema, loadProjectConfig, PolicyRuleSchema, RegistrationIdiomSchema, RegistryDeclarationSchema, ReusePrimitiveSchema, WiringRuleSchema, } from '@shrkcrft/config';
+import { ERROR_CODES, importModuleViaLoader, ok, RejectionCause, resolvePlaneExtractors, unitProblemsOf, validateResolvedPlaneSources, } from '@shrkcrft/core';
+import { BaselineRuleSchema, DocReferenceRuleSchema, GeneratedArtifactRuleSchema, loadProjectConfig, normalizePlaneRule, PolicyRuleSchema, RegistrationIdiomSchema, RegistryDeclarationSchema, ReusePrimitiveSchema, WiringRuleSchema, } from '@shrkcrft/config';
 import { discoverPacks } from '@shrkcrft/packs';
+import { ContributionKind } from "./contribution-kind.js";
+/**
+ * The gate plane a `mergePlane` label merges (round 13), so the seam
+ * normalises a pack element's markable lists through the ONE per-plane
+ * normaliser the loader uses (`normalizePlaneRule`). `reusePrimitive` is not a
+ * gate plane and has no markable list.
+ */
+function gatePlaneOfLabel(planeLabel) {
+    const planes = {
+        wiringRule: 'wiring',
+        registry: 'registry',
+        registrationIdiom: 'registration',
+        policyRule: 'policy',
+        baseline: 'baseline',
+        generatedArtifact: 'generated',
+        docReference: 'doc-reference',
+    };
+    return planes[planeLabel];
+}
+/**
+ * THE "is there no SharkCraft config at all?" answer for a failed
+ * {@link resolveProjectConfig}: the loader found no `sharkcraft/` folder. A
+ * config that EXISTS but failed to load is a different answer — an error.
+ * `finish` (the plane gates are "not applicable") and the quality report's
+ * plane row (no row) both read this, so the two cannot disagree about one
+ * repo (round 11 review R12-REG-2).
+ */
+export function isProjectConfigAbsent(error) {
+    return error.code === ERROR_CODES.SHARKCRAFT_FOLDER_NOT_FOUND;
+}
+/**
+ * THE per-element validation of a gate-plane pack contribution: one
+ * `<path>: <message>` per zod issue, `[]` when accepted. The merge below and
+ * `packs test --load` (`validateContributionFile`) both call it with the SAME
+ * exported schema the config loader validates a local element with.
+ */
+export function planeElementRejectionReasons(schema, raw) {
+    const parsed = schema.safeParse(raw);
+    if (parsed.success)
+        return [];
+    const issues = parsed.error?.issues ?? [];
+    return issues.length > 0
+        ? issues.map((iss) => `${iss.path.join('.') || '(entry)'}: ${iss.message}`)
+        : ['(entry): invalid element'];
+}
 /**
  * Generic per-plane load + validate + merge. Seeds the merged map from the
  * LOCAL array (keyed by `keyOf`), then folds in pack elements only when their
@@ -33,6 +84,8 @@ import { discoverPacks } from '@shrkcrft/packs';
  * throw.
  */
 async function mergePlane(localArr, packContribs, schema, keyOf, planeLabel, diagnostics, 
+/** Where the structured outcome is recorded — absent for a plane with no manifest slot. */
+outcome, 
 /**
  * Optional per-item veto applied to PACK elements only. Returns the
  * diagnostic to record when the element must not be adopted (used by the
@@ -41,6 +94,9 @@ async function mergePlane(localArr, packContribs, schema, keyOf, planeLabel, dia
 packGuard) {
     const merged = new Map();
     const localKeys = new Set();
+    // A plane with no manifest slot records into a sink nobody reads.
+    const kind = outcome?.kind ?? ContributionKind.PolicyRule;
+    const sink = outcome?.sink ?? { accepted: [], rejected: [], loadFailures: [], adopted: new Map() };
     for (const item of localArr) {
         const key = keyOf(item);
         merged.set(key, item);
@@ -57,7 +113,14 @@ packGuard) {
             mod = await importModuleViaLoader(full);
         }
         catch (e) {
-            diagnostics.push(`pack ${contrib.packageName}: failed to load ${planeLabel} file ${contrib.rel} — ${e.message}`);
+            const message = e.message;
+            diagnostics.push(`pack ${contrib.packageName}: failed to load ${planeLabel} file ${contrib.rel} — ${message}`);
+            sink.loadFailures.push({
+                file: full,
+                kind,
+                packageName: contrib.packageName,
+                message: (message.split('\n')[0] ?? message).trim(),
+            });
             continue;
         }
         const arr = mod.default;
@@ -65,33 +128,80 @@ packGuard) {
             diagnostics.push(`pack ${contrib.packageName}: ${planeLabel} file ${contrib.rel} default export is not an array — skipped`);
             continue;
         }
-        for (const raw of arr) {
-            const parsed = schema.safeParse(raw);
-            if (!parsed.success) {
-                const summary = (parsed.error?.issues ?? [])
-                    .map((iss) => `${iss.path.join('.') || '<root>'}: ${iss.message}`)
-                    .join('; ') || 'invalid element';
-                diagnostics.push(`pack ${contrib.packageName}: invalid ${planeLabel} element in ${contrib.rel} — ${summary} — skipped`);
-                continue;
+        arr.forEach((raw, index) => {
+            const reject = (reasons, cause, entryId) => {
+                const id = entryId ?? planeElementKey(raw);
+                sink.rejected.push({
+                    file: full,
+                    index,
+                    exportName: 'default',
+                    ...(id !== undefined ? { entryId: id } : {}),
+                    reasons,
+                    cause,
+                    kind,
+                    packageName: contrib.packageName,
+                    via: 'config-plane',
+                });
+            };
+            const reasons = planeElementRejectionReasons(schema, raw);
+            if (reasons.length > 0) {
+                diagnostics.push(`pack ${contrib.packageName}: invalid ${planeLabel} element in ${contrib.rel} — ${reasons.join('; ')} — skipped`);
+                reject(reasons, RejectionCause.Invalid);
+                return;
             }
-            const item = parsed.data;
+            const parsedItem = schema.safeParse(raw).data;
+            // Round 13: normalise the element's markable lists the way the loader
+            // normalises a local rule (`normalizePlaneRule`) — plain string lists
+            // plus `expectEmptyUnits` — and STAMP every marker with the contributing
+            // pack, so a pack marker that went live reads as INFO and never fails the
+            // consumer. The schema above already refused a malformed marker (the
+            // round-12 rejection channel); a failure here is refused the same way.
+            const plane = gatePlaneOfLabel(planeLabel);
+            const normalized = plane !== undefined ? normalizePlaneRule(plane, parsedItem, contrib.packageName) : undefined;
+            if (normalized !== undefined && !normalized.ok) {
+                const problems = unitProblemsOf(normalized.error);
+                diagnostics.push(`pack ${contrib.packageName}: invalid ${planeLabel} element in ${contrib.rel} — ${problems.join('; ')} — skipped`);
+                reject(problems, RejectionCause.Invalid);
+                return;
+            }
+            const item = normalized !== undefined ? normalized.value : parsedItem;
             const veto = packGuard?.(item, contrib.packageName);
             if (veto !== undefined) {
-                diagnostics.push(veto);
-                continue;
+                diagnostics.push(veto.diagnostic);
+                reject([veto.reason], RejectionCause.Invalid, keyOf(item));
+                return;
             }
             const key = keyOf(item);
             if (merged.has(key)) {
-                diagnostics.push(localKeys.has(key)
+                const local = localKeys.has(key);
+                diagnostics.push(local
                     ? `pack ${contrib.packageName}: ${planeLabel} "${key}" already provided by local config — skipped`
                     : `pack ${contrib.packageName}: ${planeLabel} "${key}" already provided — skipped`);
-                continue;
+                reject([`id: "${key}" is already provided by ${local ? 'the local config' : 'an earlier pack'} — local wins`], RejectionCause.DuplicateId, key);
+                return;
             }
             merged.set(key, item);
-        }
+            const entry = { kind, file: full, packageName: contrib.packageName, id: key };
+            sink.accepted.push(entry);
+            sink.adopted.set(`${kind}:${key}`, { entry, index });
+        });
     }
     return [...merged.values()];
 }
+/**
+ * THE id of a raw gate-plane element — its `id` / `name` / `symbol`, whichever
+ * string it carries first — for a rejection record. The merge seam and `packs
+ * test --load` (`validateContributionFile`) both name a refused element by it.
+ */
+export function planeElementKey(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    for (const k of ['id', 'name', 'symbol'])
+        if (typeof r[k] === 'string')
+            return r[k];
+    return undefined;
+}
 /** Collect every pack contribution file for one manifest slot across valid packs. */
 function gatherPackContribs(validPacks, slot) {
     const out = [];
@@ -106,6 +216,63 @@ function gatherPackContribs(validPacks, slot) {
     }
     return out;
 }
+/** The shell-command veto of a pack-contributed baseline: `compute.run` is never auto-run. */
+function baselinePackVeto(item, packName) {
+    return item.compute?.kind === 'command'
+        ? {
+            diagnostic: `pack ${packName}: baseline "${item.id}" declares a shell \`compute.run\` — pack-contributed commands are never auto-run — skipped`,
+            reason: 'compute.run: a pack-contributed shell command is never auto-run',
+        }
+        : undefined;
+}
+/** The shell-command veto of a pack-contributed generated artifact: `regen` is never auto-run. */
+function generatedPackVeto(item, packName) {
+    return item.regen !== undefined
+        ? {
+            diagnostic: `pack ${packName}: generatedArtifact "${item.id}" declares a \`regen\` command — pack-contributed commands are never auto-run — skipped`,
+            reason: 'regen: a pack-contributed shell command is never auto-run',
+        }
+        : undefined;
+}
+/** Each gate-plane manifest slot → THE schema its elements validate against, and its pack veto. */
+const PACK_PLANE_SLOTS = {
+    wiringRuleFiles: { schema: WiringRuleSchema },
+    registryFiles: { schema: RegistryDeclarationSchema },
+    registrationGraphFiles: { schema: RegistrationIdiomSchema },
+    policyRuleFiles: { schema: PolicyRuleSchema },
+    reusePrimitiveFiles: { schema: ReusePrimitiveSchema },
+    baselineFiles: { schema: BaselineRuleSchema, veto: baselinePackVeto },
+    generatedArtifactFiles: {
+        schema: GeneratedArtifactRuleSchema,
+        veto: generatedPackVeto,
+    },
+    // Round 13 (P3): no shell, so no veto — only the plane's schema.
+    docReferenceFiles: { schema: DocReferenceRuleSchema },
+};
+/**
+ * Why a PACK element of a gate-plane slot would be refused by the merge seam
+ * — THE same schema + shell veto `resolveProjectConfig` applies — or
+ * `undefined` for a slot that is not a gate plane. `packs test --load` reads
+ * it (`validateContributionFile`). A `$use` reference is resolved against the
+ * CONSUMING repo's extractors, so it cannot be judged from the pack alone.
+ */
+export function packPlaneElementRejectionReasons(slot, raw) {
+    const spec = PACK_PLANE_SLOTS[slot];
+    if (!spec)
+        return undefined;
+    const reasons = planeElementRejectionReasons(spec.schema, raw);
+    if (reasons.length > 0)
+        return reasons;
+    const veto = spec.veto?.(spec.schema.safeParse(raw).data, '(pack)');
+    return veto ? [veto.reason] : [];
+}
+/** The plane a `$use` resolution error path names (`wiringRules[<id>]…`) → its contribution kind. */
+const EXTRACTOR_PLANE_KIND = {
+    wiringRules: ContributionKind.WiringRule,
+    registries: ContributionKind.Registry,
+    registrationGraph: ContributionKind.RegistrationIdiom,
+    baselines: ContributionKind.Baseline,
+};
 /**
  * Load the project config, then merge pack-contributed `wiringRules` /
  * `registries` / `policyRules` / `reusePrimitives` over the local config
@@ -119,6 +286,7 @@ export async function resolveProjectConfig(cwd) {
     if (!loaded.ok)
         return loaded;
     const diagnostics = [];
+    const sink = { accepted: [], rejected: [], loadFailures: [], adopted: new Map() };
     const base = loaded.value;
     let validPacks = [];
     try {
@@ -128,10 +296,10 @@ export async function resolveProjectConfig(cwd) {
     catch (e) {
         diagnostics.push(`pack discovery failed — pack-contributed planes skipped: ${e.message}`);
     }
-    const wiringRules = await mergePlane(base.config.wiringRules ?? [], gatherPackContribs(validPacks, 'wiringRuleFiles'), WiringRuleSchema, (r) => r.id, 'wiringRule', diagnostics);
-    const registries = await mergePlane(base.config.registries ?? [], gatherPackContribs(validPacks, 'registryFiles'), RegistryDeclarationSchema, (r) => r.name, 'registry', diagnostics);
-    const registrationGraph = await mergePlane(base.config.registrationGraph ?? [], gatherPackContribs(validPacks, 'registrationGraphFiles'), RegistrationIdiomSchema, (r) => r.name, 'registrationIdiom', diagnostics);
-    const policyRules = await mergePlane(base.config.policyRules ?? [], gatherPackContribs(validPacks, 'policyRuleFiles'), PolicyRuleSchema, (r) => r.id, 'policyRule', diagnostics);
+    const wiringRules = await mergePlane(base.config.wiringRules ?? [], gatherPackContribs(validPacks, 'wiringRuleFiles'), WiringRuleSchema, (r) => r.id, 'wiringRule', diagnostics, { kind: ContributionKind.WiringRule, sink });
+    const registries = await mergePlane(base.config.registries ?? [], gatherPackContribs(validPacks, 'registryFiles'), RegistryDeclarationSchema, (r) => r.name, 'registry', diagnostics, { kind: ContributionKind.Registry, sink });
+    const registrationGraph = await mergePlane(base.config.registrationGraph ?? [], gatherPackContribs(validPacks, 'registrationGraphFiles'), RegistrationIdiomSchema, (r) => r.name, 'registrationIdiom', diagnostics, { kind: ContributionKind.RegistrationIdiom, sink });
+    const policyRules = await mergePlane(base.config.policyRules ?? [], gatherPackContribs(validPacks, 'policyRuleFiles'), PolicyRuleSchema, (r) => r.id, 'policyRule', diagnostics, { kind: ContributionKind.PolicyRule, sink });
     // The two SHELL-EXECUTING planes. A pack ships code the repo did not write;
     // letting it also ship a command that `shrk baseline check` would then RUN is
     // the same hazard the "pack-contributed verification commands are NOT
@@ -139,25 +307,83 @@ export async function resolveProjectConfig(cwd) {
     // extractor computes and header-only generated rules — and drops the rest
     // with a diagnostic. The guarantee is structural: no downstream caller has to
     // remember to re-check provenance.
-    const baselines = await mergePlane(base.config.baselines ?? [], gatherPackContribs(validPacks, 'baselineFiles'), BaselineRuleSchema, (r) => r.id, 'baseline', diagnostics, (item, packName) => item.compute?.kind === 'command'
-        ? `pack ${packName}: baseline "${item.id}" declares a shell \`compute.run\` — pack-contributed commands are never auto-run — skipped`
-        : undefined);
-    const generatedArtifacts = await mergePlane(base.config.generatedArtifacts ?? [], gatherPackContribs(validPacks, 'generatedArtifactFiles'), GeneratedArtifactRuleSchema, (r) => r.id, 'generatedArtifact', diagnostics, (item, packName) => item.regen !== undefined
-        ? `pack ${packName}: generatedArtifact "${item.id}" declares a \`regen\` command — pack-contributed commands are never auto-run — skipped`
-        : undefined);
-    const reusePrimitives = await mergePlane(base.config.reusePrimitives ?? [], gatherPackContribs(validPacks, 'reusePrimitiveFiles'), ReusePrimitiveSchema, (r) => r.symbol, 'reusePrimitive', diagnostics);
+    const baselines = await mergePlane(base.config.baselines ?? [], gatherPackContribs(validPacks, 'baselineFiles'), BaselineRuleSchema, (r) => r.id, 'baseline', diagnostics, { kind: ContributionKind.Baseline, sink }, baselinePackVeto);
+    const generatedArtifacts = await mergePlane(base.config.generatedArtifacts ?? [], gatherPackContribs(validPacks, 'generatedArtifactFiles'), GeneratedArtifactRuleSchema, (r) => r.id, 'generatedArtifact', diagnostics, { kind: ContributionKind.GeneratedArtifact, sink }, generatedPackVeto);
+    // No shell, no writes — a pack may contribute a prose-reference rule freely,
+    // unlike the two shell-executing planes above. Round 13 (P3):
+    // `docReferenceFiles` is a DECLARED manifest slot, so its outcome joins the
+    // round-12 channel — a refused element is a structured rejection (`packs
+    // contributions`, `packs list`, the gates ERRORED row), never only a
+    // diagnostic string, and an adopted one is an accepted entry.
+    const docReferences = await mergePlane(base.config.docReferences ?? [], gatherPackContribs(validPacks, 'docReferenceFiles'), DocReferenceRuleSchema, (r) => r.id, 'docReference', diagnostics, { kind: ContributionKind.DocReference, sink });
+    const reusePrimitives = await mergePlane(base.config.reusePrimitives ?? [], gatherPackContribs(validPacks, 'reusePrimitiveFiles'), ReusePrimitiveSchema, (r) => r.symbol, 'reusePrimitive', diagnostics, { kind: ContributionKind.ReusePrimitive, sink });
+    // Pack-contributed elements have NOT been through the loader's `$use`
+    // resolution (that ran on the local config only), so resolve the merged
+    // planes here. A pack rule referencing an extractor this repo does not
+    // declare is DROPPED with a diagnostic — never kept half-resolved, which
+    // would read as "a source with no files" and match nothing, i.e. a silent
+    // pass. Local rules are already resolved, so every error found here belongs
+    // to a pack element by construction.
+    const resolvedPlanes = resolvePlaneExtractors({ wiringRules, registries, registrationGraph, baselines }, base.config.extractors);
+    const dropped = new Set();
+    /** Drop the pack element a source `path` belongs to; the adopted entry becomes a rejection. */
+    const dropPackElement = (path, diagnostic, reason) => {
+        const prefix = path.slice(0, path.indexOf(']') + 1);
+        diagnostics.push(diagnostic);
+        if (dropped.has(prefix))
+            return;
+        dropped.add(prefix);
+        // The adopted pack element becomes a rejection — it never takes effect.
+        const m = /^(\w+)\[(.*)\]$/.exec(prefix);
+        const kind = m ? EXTRACTOR_PLANE_KIND[m[1]] : undefined;
+        const adopted = kind !== undefined ? sink.adopted.get(`${kind}:${m[2]}`) : undefined;
+        if (!adopted)
+            return;
+        const at = sink.accepted.indexOf(adopted.entry);
+        if (at >= 0)
+            sink.accepted.splice(at, 1);
+        sink.rejected.push({
+            file: adopted.entry.file,
+            index: adopted.index,
+            exportName: 'default',
+            entryId: adopted.entry.id,
+            reasons: [reason],
+            cause: RejectionCause.Invalid,
+            kind: adopted.entry.kind,
+            ...(adopted.entry.packageName ? { packageName: adopted.entry.packageName } : {}),
+            via: 'config-plane',
+        });
+    };
+    const fieldOf = (path) => path.slice(path.indexOf(']') + 1).replace(/^\./, '');
+    for (const e of resolvedPlanes.errors) {
+        dropPackElement(e.path, `${e.path}: ${e.message} — rule skipped`, `${fieldOf(e.path) || '$use'}: ${e.message}`);
+    }
+    // Then THE post-resolution check the loader runs on a local rule (core's
+    // `validateResolvedPlaneSources`): a `$use` source is judged on its MERGED
+    // shape. Without it a pack rule overriding an extractor with a negation-only
+    // `files` was adopted — `packs contributions` said accepted, `check wiring`
+    // said misconfigured (round 12 review, R12-X3). Local rules passed the
+    // loader's identical check, so a problem here is a pack element's.
+    for (const p of validateResolvedPlaneSources(resolvedPlanes)) {
+        if (dropped.has(p.path.slice(0, p.path.indexOf(']') + 1)))
+            continue;
+        dropPackElement(p.path, `${p.path} ${p.message} — rule skipped`, `${fieldOf(p.path)} ${p.message}`);
+    }
+    const keep = (items, plane, keyOf) => dropped.size === 0 ? items : items.filter((i) => !dropped.has(`${plane}[${keyOf(i)}]`));
     return ok({
         ...base,
         config: {
             ...base.config,
-            wiringRules,
-            registries,
-            registrationGraph,
+            wiringRules: keep(resolvedPlanes.wiringRules ?? wiringRules, 'wiringRules', (r) => r.id),
+            registries: keep(resolvedPlanes.registries ?? registries, 'registries', (r) => r.name),
+            registrationGraph: keep(resolvedPlanes.registrationGraph ?? registrationGraph, 'registrationGraph', (r) => r.name),
             policyRules,
-            baselines,
+            baselines: keep(resolvedPlanes.baselines ?? baselines, 'baselines', (r) => r.id),
             generatedArtifacts,
+            docReferences,
             reusePrimitives,
         },
         planeDiagnostics: diagnostics,
+        planeOutcomes: { accepted: sink.accepted, rejected: sink.rejected, loadFailures: sink.loadFailures },
     });
 }

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

@@ -0,0 +1,29 @@
+import type { IPublicExportSurface, IReusePrimitive } from '@shrkcrft/core';
+import type { IReuseCoverageReport } from './reuse-coverage-report.js';
+import type { IReuseSymbolLookup } from './reuse-symbol-lookup.js';
+/** Default cap on the listed uncovered exports (`--all` lifts it). */
+export declare const REUSE_UNCOVERED_CAP = 50;
+/**
+ * Measure the curated `reusePrimitives[]` against the public export surface.
+ *
+ * Pure: the surface and the graph lookups are INJECTED. Every question is
+ * answered by an existing authority, the SAME one the lookup uses:
+ *   - the surface by the graph's `enumeratePublicSurface`;
+ *   - which construct a curated entry names, its import line, and whether that
+ *     import compiles by `resolveCuratedReuse` — the record `shrk reuse`
+ *     prints the entry's row from;
+ *   - which exports a curated entry already covers by `isCuratedExport` over
+ *     `curatedDeclarationMap` — the exclusion `rankReuseCandidates` applies;
+ *   - a curation gap by `isReuseCurationGap` over the lookup's own ranker —
+ *     exactly what `shrk reuse "<the export's words>"` reports as `curationGap`.
+ *
+ * `packageFilter` narrows deliberately: only those packages' exports count,
+ * and a curated entry is in scope when its `importPath` is one of them or a
+ * declaration lives in one of them.
+ */
+export declare function computeReuseCoverage(primitives: readonly IReusePrimitive[], surface: IPublicExportSurface, lookup: IReuseSymbolLookup, opts?: {
+    readonly includeTypes?: boolean;
+    readonly packageFilter?: readonly string[];
+    readonly all?: boolean;
+}): IReuseCoverageReport;
+//# sourceMappingURL=compute-reuse-coverage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compute-reuse-coverage.d.ts","sourceRoot":"","sources":["../../src/reuse/compute-reuse-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,oBAAoB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAU3F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAGvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAGnE,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,OAAO,EAAE,oBAAoB,EAC7B,MAAM,EAAE,kBAAkB,EAC1B,IAAI,GAAE;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,GACjH,oBAAoB,CA0KtB"}

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

@@ -0,0 +1,198 @@
+import { splitIdentifierTokens } from "../split-identifier.js";
+import { isReuseCurationGap, isReuseTestPath, isReuseTypeKind, rankReuseCandidates, reuseNameAnswers, } from "./rank-reuse-candidates.js";
+import { curatedDeclarationMap, isCuratedExport, resolveCuratedReuse } from "./resolve-curated-reuse.js";
+import { ReuseCuratedStatus } from "./reuse-curated-status.js";
+import { scoreReuseName } from "./score-reuse-name.js";
+/** Default cap on the listed uncovered exports (`--all` lifts it). */
+export const REUSE_UNCOVERED_CAP = 50;
+/**
+ * Measure the curated `reusePrimitives[]` against the public export surface.
+ *
+ * Pure: the surface and the graph lookups are INJECTED. Every question is
+ * answered by an existing authority, the SAME one the lookup uses:
+ *   - the surface by the graph's `enumeratePublicSurface`;
+ *   - which construct a curated entry names, its import line, and whether that
+ *     import compiles by `resolveCuratedReuse` — the record `shrk reuse`
+ *     prints the entry's row from;
+ *   - which exports a curated entry already covers by `isCuratedExport` over
+ *     `curatedDeclarationMap` — the exclusion `rankReuseCandidates` applies;
+ *   - a curation gap by `isReuseCurationGap` over the lookup's own ranker —
+ *     exactly what `shrk reuse "<the export's words>"` reports as `curationGap`.
+ *
+ * `packageFilter` narrows deliberately: only those packages' exports count,
+ * and a curated entry is in scope when its `importPath` is one of them or a
+ * declaration lives in one of them.
+ */
+export function computeReuseCoverage(primitives, surface, lookup, opts = {}) {
+    const selected = opts.packageFilter !== undefined && opts.packageFilter.length > 0 ? new Set(opts.packageFilter) : undefined;
+    const inScope = (pkg) => selected === undefined || selected.has(pkg);
+    const packageDirs = [...surface.roots, ...surface.packagesWithoutEntry]
+        .map((p) => ({ package: p.package, dir: p.dir.replace(/\/+$/, '') }))
+        .filter((p) => p.dir.length > 0)
+        .sort((a, b) => b.dir.length - a.dir.length);
+    const packageOf = (path) => packageDirs.find((p) => path === p.dir || path.startsWith(`${p.dir}/`))?.package;
+    const withoutEntry = new Set(surface.packagesWithoutEntry.map((w) => w.package));
+    const exports = surface.exports.filter((e) => inScope(e.package) && !isReuseTestPath(e.declaredIn));
+    // ONE resolution per curated entry — every entry, in or out of scope, since
+    // an out-of-scope entry still covers its own construct.
+    const resolutions = primitives.map((p) => resolveCuratedReuse(p, surface, lookup));
+    const curatedNames = new Set(primitives.map((p) => p.symbol));
+    const curatedDeclaredIn = curatedDeclarationMap(primitives, resolutions);
+    // ── curated entries ───────────────────────────────────────────────────
+    const curated = [];
+    /** The construct each reported entry names (parallel to `curated`). */
+    const curatedSymbolIds = [];
+    let curatedOutOfScope = 0;
+    primitives.forEach((p, i) => {
+        const res = resolutions[i];
+        const decls = lookup.declarationsOf(p.symbol);
+        if (selected !== undefined) {
+            const declaredInScope = decls.some((d) => {
+                const pkg = packageOf(d.path);
+                return pkg !== undefined && selected.has(pkg);
+            });
+            if (!declaredInScope && !(p.importPath !== undefined && selected.has(p.importPath))) {
+                curatedOutOfScope += 1;
+                return;
+            }
+        }
+        // Only the construct the entry NAMES is "this entry on the surface": a
+        // same-named export of a different construct in another package is not.
+        const self = res.declaration?.symbolId;
+        const publicHits = surface.exports.filter((e) => e.name === p.symbol && (self === undefined || e.symbolId === self));
+        const publicIn = [...new Set(publicHits.map((e) => e.package))].sort(compare);
+        const exported = decls.filter((d) => d.isExported);
+        let status;
+        let statusNote;
+        if (publicIn.length > 0)
+            status = ReuseCuratedStatus.Public;
+        // Its importPath module exports it (checked), yet no package root does.
+        else if (res.importPathAgrees === true)
+            status = ReuseCuratedStatus.ExportedNotPublic;
+        else if (decls.length === 0)
+            status = ReuseCuratedStatus.NotFound;
+        else if (exported.length === 0)
+            status = ReuseCuratedStatus.NotExported;
+        else
+            status = exported.length > 1 ? ReuseCuratedStatus.Ambiguous : ReuseCuratedStatus.ExportedNotPublic;
+        if (status === ReuseCuratedStatus.ExportedNotPublic || status === ReuseCuratedStatus.Ambiguous) {
+            const unmeasured = [
+                ...new Set(exported.map((d) => packageOf(d.path)).filter((pkg) => pkg !== undefined && withoutEntry.has(pkg))),
+            ].sort(compare);
+            if (unmeasured.length > 0) {
+                statusNote = `declared in ${unmeasured.join(', ')}, which has no resolved entry — whether it is public was not measured`;
+            }
+        }
+        const declKind = res.declaration?.declKind ?? publicHits[0]?.declKind;
+        const consumers = self !== undefined && lookup.consumerCount !== undefined ? lookup.consumerCount(self) : undefined;
+        curated.push({
+            symbol: p.symbol,
+            status,
+            statusMeasured: statusNote === undefined,
+            ...(statusNote !== undefined ? { statusNote } : {}),
+            publicIn,
+            declaredIn: [...new Set(decls.map((d) => d.path))].sort(compare),
+            ...(declKind !== undefined ? { declKind } : {}),
+            ...(consumers !== undefined ? { consumers } : {}),
+            ...(p.importPath !== undefined ? { importPath: p.importPath } : {}),
+            ...(res.importPathAgrees !== undefined ? { importPathAgrees: res.importPathAgrees } : {}),
+            ...(res.importPathNote !== undefined ? { importPathNote: res.importPathNote } : {}),
+            ...(res.importStyle !== undefined ? { importStyle: res.importStyle } : {}),
+            ...(res.importLine !== undefined ? { importLine: res.importLine } : {}),
+        });
+        curatedSymbolIds.push(self);
+    });
+    // ── the surface ───────────────────────────────────────────────────────
+    const byKind = {};
+    for (const e of exports)
+        byKind[e.declKind] = (byKind[e.declKind] ?? 0) + 1;
+    const valueExports = exports.filter((e) => !isReuseTypeKind(e.declKind));
+    let curatedPublic = 0;
+    let curatedPublicValue = 0;
+    curated.forEach((c, i) => {
+        if (c.status !== ReuseCuratedStatus.Public || !c.publicIn.some(inScope))
+            return;
+        curatedPublic += 1;
+        const self = curatedSymbolIds[i];
+        if (valueExports.some((e) => e.name === c.symbol && (self === undefined || e.symbolId === self))) {
+            curatedPublicValue += 1;
+        }
+    });
+    // ── uncovered, superseded, shadowed ──────────────────────────────────
+    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 uncovered = [];
+    const superseded = [];
+    const shadowed = [];
+    for (const e of exports) {
+        if (isCuratedExport(e, curatedNames, curatedDeclaredIn))
+            continue;
+        if (opts.includeTypes !== true && isReuseTypeKind(e.declKind))
+            continue;
+        const by = supersededBy.get(e.name);
+        if (by) {
+            superseded.push({ export: e.name, package: e.package, supersededBy: by });
+            continue;
+        }
+        uncovered.push(e);
+        // The lookup's own ranker (curated-only: its best curated candidate) and
+        // its own gap predicate — what `shrk reuse "<e's words>"` reports as its
+        // `curationGap`, with `e` the uncurated export that answers by name.
+        const ranking = rankReuseCandidates(primitives, undefined, splitIdentifierTokens(e.name).join(' '), {
+            curatedOnly: true,
+            limit: 1,
+        });
+        const answer = ranking.results[0];
+        const selfAnswers = reuseNameAnswers(scoreReuseName(e.name, ranking.tokens)) ? 1 : 0;
+        if (answer !== undefined && isReuseCurationGap(answer.nameMatch, selfAnswers)) {
+            shadowed.push({
+                export: e.name,
+                package: e.package,
+                declaredIn: e.declaredIn,
+                answeredBy: answer.symbol,
+                matchedVia: answer.matchedVia,
+                nameMatch: answer.nameMatch,
+            });
+        }
+    }
+    const cap = opts.all === true ? uncovered.length : REUSE_UNCOVERED_CAP;
+    const unfollowedReExports = surface.unfollowedReExports.filter((u) => inScope(u.package));
+    return {
+        curated,
+        curatedOutOfScope,
+        surface: {
+            roots: surface.roots.filter((r) => inScope(r.package)),
+            packagesWithoutEntry: surface.packagesWithoutEntry.filter((w) => inScope(w.package)),
+            all: exports.length,
+            value: valueExports.length,
+            byKind,
+            unresolvedReExports: unfollowedReExports.length,
+            unfollowedReExports,
+        },
+        curatedPublic,
+        curatedPublicValue,
+        ...(valueExports.length > 0 ? { ratioValue: curatedPublicValue / valueExports.length } : {}),
+        ...(exports.length > 0 ? { ratioAll: curatedPublic / exports.length } : {}),
+        uncovered: uncovered.slice(0, cap).map((e) => ({
+            name: e.name,
+            package: e.package,
+            declaredIn: e.declaredIn,
+            declKind: e.declKind,
+        })),
+        uncoveredTotal: uncovered.length,
+        shadowed,
+        superseded,
+    };
+}
+/** Locale-independent ordering, so a report is byte-stable across machines. */
+function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}

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

@@ -0,0 +1,38 @@
+import { ReuseNameMatch, type IPublicExportSurface, type IReusePrimitive } from '@shrkcrft/core';
+import type { IRankReuseOptions } from './rank-reuse-options.js';
+import type { IReuseRanking } from './reuse-ranking.js';
+/** A type-only export (interface / type alias) — excluded from reuse answers unless asked for. */
+export declare function isReuseTypeKind(declKind: string): boolean;
+/** A test file never holds a construct to reuse. */
+export declare function isReuseTestPath(path: string): boolean;
+/** A NAME that answers the intent: every intent token is one of its name tokens (exact / covers). */
+export declare function reuseNameAnswers(m: ReuseNameMatch): boolean;
+/**
+ * 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 declare function isReuseCurationGap(bestCuratedNameMatch: ReuseNameMatch | undefined, uncuratedNameAnswers: number): boolean;
+/**
+ * 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 declare function rankReuseCandidates(primitives: readonly IReusePrimitive[], surface: IPublicExportSurface | undefined, intent: string, opts?: IRankReuseOptions): IReuseRanking;
+//# sourceMappingURL=rank-reuse-candidates.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rank-reuse-candidates.d.ts","sourceRoot":"","sources":["../../src/reuse/rank-reuse-candidates.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,cAAc,EAEd,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAIjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAcxD,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,oDAAoD;AACpD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIrD;AAED,qGAAqG;AACrG,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,oBAAoB,EAAE,cAAc,GAAG,SAAS,EAChD,oBAAoB,EAAE,MAAM,GAC3B,OAAO,CAET;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,OAAO,EAAE,oBAAoB,GAAG,SAAS,EACzC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,iBAAsB,GAC3B,aAAa,CAuIf"}