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

package/dist/sharkcraft-inspector.js

@@ -1,8 +1,19 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { createImportContext, DEFAULT_SAFE_IMPORT_TIMEOUT_MS, } from '@shrkcrft/core';
+import { createImportContext, DEFAULT_SAFE_IMPORT_TIMEOUT_MS, ERROR_CODES, RejectionCause, } from '@shrkcrft/core';
 import { inspectWorkspace } from '@shrkcrft/workspace';
-import { loadProjectConfig } from '@shrkcrft/config';
+import { DEFAULT_DOC_FILES, DEFAULT_KNOWLEDGE_FILES, DEFAULT_PATH_FILES, DEFAULT_RULE_FILES, loadProjectConfig, } from '@shrkcrft/config';
+/**
+ * The knowledge-bearing files the config loader fills in by DEFAULT. They are
+ * optional by nature — a repo without `rules.ts` never asked for one — so only
+ * a file the config names BEYOND these is recorded `missing` when absent.
+ */
+const OPTIONAL_DEFAULT_KNOWLEDGE_FILES = new Set([
+    ...DEFAULT_KNOWLEDGE_FILES,
+    ...DEFAULT_RULE_FILES,
+    ...DEFAULT_PATH_FILES,
+    ...DEFAULT_DOC_FILES,
+]);
 import { KnowledgeIndex, MarkdownKnowledgeLoader, TypeScriptKnowledgeLoader, validateKnowledgeEntries, } from '@shrkcrft/knowledge';
 import { RuleService } from '@shrkcrft/rules';
 import { PathService } from '@shrkcrft/paths';
@@ -12,6 +23,7 @@ import { discoverPacks } from '@shrkcrft/packs';
 import { BUILTIN_PRESETS, loadPresetsFromFile, PresetRegistry } from '@shrkcrft/presets';
 import { BoundaryRegistry, loadBoundaryRulesFromFile } from '@shrkcrft/boundaries';
 import { DoctorSeverity } from "./doctor-result.js";
+import { registryLifecycleSkipDirsWarning, resolveRegistryLifecycleSkipDirs, } from "./registry-lifecycle.js";
 import { diagnoseActionHints } from "./action-hint-diagnostics.js";
 import { buildCodeIntelligenceChecks, } from "./code-intelligence-doctor.js";
 import { loadSearchTuning } from "./search-tuning-registry.js";
@@ -19,6 +31,8 @@ import { buildDelegateRecipeChecks } from "./delegate-doctor.js";
 import { computeFileFingerprint, createInspectorCache, } from "./inspector-cache.js";
 import { DEFAULT_SLOW_LOADER_THRESHOLD_MS, LARGE_FILE_THRESHOLD_BYTES, } from "./loader-diagnostics.js";
 import { suggestSurfaceProfile } from "./surface-profile-detect.js";
+import { boundaryFileLabel, boundaryLoadIssuesFromFile, classifyLocalBoundaryFiles, } from "./boundary-configuration-status.js";
+import { describePackAssetFreshness, detectPackAssetFreshness, packHasCompiledContributions, } from "./pack-asset-freshness.js";
 /**
  * Find SharkCraft packs that live IN the repo but are not discovered (i.e.
  * not linked into node_modules). Discovery scans node_modules; an unlinked
@@ -102,6 +116,22 @@ function recordDiagnostic(ctx, d) {
     ctx.diagnostics.push(d);
     ctx.onLoaderDiagnostic?.(d);
 }
+/**
+ * A boundary rule file's invalid rules as THE rejection channel's records
+ * (round 12, 12.1) — the boundary loader's structured `invalid[]`, one record
+ * per rule with every failing field.
+ */
+function boundaryRejections(file, invalid) {
+    return invalid.map((inv) => ({
+        file,
+        index: inv.index,
+        // The export the rule array came from — `(default[1])`, one wording with every kind.
+        ...(inv.exportName !== undefined ? { exportName: inv.exportName } : {}),
+        ...(inv.ruleId !== undefined ? { entryId: inv.ruleId } : {}),
+        reasons: inv.issues.map((i) => `${i.field}: ${i.message}`),
+        cause: RejectionCause.Invalid,
+    }));
+}
 async function loadAssetTracked(ctx, filePath, kind, origin, packName, performLoad) {
     const start = Date.now();
     let sizeBytes;
@@ -191,6 +221,7 @@ async function loadAssetTracked(ctx, filePath, kind, origin, packName, performLo
         elapsedMs,
         status,
         count: loaded.count,
+        ...(loaded.rejected && loaded.rejected.length > 0 ? { rejected: loaded.rejected } : {}),
         warningCount: loaded.warnings.length,
         errorMessage,
         deduped: dedupedBefore,
@@ -227,20 +258,45 @@ export async function inspectSharkcraft(options = {}) {
     const knowledgeEntries = [];
     const templates = [];
     const pipelines = [];
+    // The file each LOCAL template / pipeline came from, so their sources carry a
+    // `file` like knowledge and pack entries do (the contributions inventory and
+    // the unregistered-export check attribute ids by file).
+    const localTemplateFiles = new Map();
+    const localPipelineFiles = new Map();
     if (cfg) {
         const tsLoader = new TypeScriptKnowledgeLoader({ importContext });
         const mdLoader = new MarkdownKnowledgeLoader();
         const collectFile = async (relPath, kindHint) => {
             const full = nodePath.join(cfg.sharkcraftDir, relPath);
-            if (!existsSync(full))
+            if (!existsSync(full)) {
+                // A default slot file (`rules.ts`, `docs/overview.md`, …) is optional.
+                if (OPTIONAL_DEFAULT_KNOWLEDGE_FILES.has(relPath.replace(/^\.\//, '')))
+                    return;
+                // The config NAMES this file; loading nothing from it is a fact a
+                // corpus verdict must see (it used to vanish: no diagnostic, no warning).
+                recordDiagnostic(ctx, {
+                    filePath: full,
+                    kind: kindHint,
+                    origin: 'local-config',
+                    elapsedMs: 0,
+                    status: 'missing',
+                    count: 0,
+                    warningCount: 0,
+                    errorMessage: `declared in ${kindHint === 'rules' ? 'ruleFiles' : kindHint === 'paths' ? 'pathFiles' : `${kindHint}Files`} but the file does not exist`,
+                    deduped: false,
+                    largeFile: false,
+                    slow: false,
+                    suggestedNextCommand: suggestNextCommand(kindHint),
+                });
                 return;
+            }
             sourceFiles.push(full);
             if (tsLoader.canLoad(full)) {
                 const tracked = await loadAssetTracked(ctx, full, kindHint, 'local-config', undefined, async () => {
                     const r = await tsLoader.load(full);
                     knowledgeEntries.push(...r.entries);
                     warnings.push(...r.warnings);
-                    return { count: r.entries.length, warnings: r.warnings };
+                    return { count: r.entries.length, warnings: r.warnings, ...(r.rejected ? { rejected: r.rejected } : {}) };
                 });
                 if (tracked.skipped)
                     warnings.push(...tracked.warnings);
@@ -250,7 +306,7 @@ export async function inspectSharkcraft(options = {}) {
                     const r = await mdLoader.load(full);
                     knowledgeEntries.push(...r.entries);
                     warnings.push(...r.warnings);
-                    return { count: r.entries.length, warnings: r.warnings };
+                    return { count: r.entries.length, warnings: r.warnings, ...(r.rejected ? { rejected: r.rejected } : {}) };
                 });
                 if (tracked.skipped)
                     warnings.push(...tracked.warnings);
@@ -279,8 +335,11 @@ export async function inspectSharkcraft(options = {}) {
             const tracked = await loadAssetTracked(ctx, full, 'templates', 'local-config', undefined, async () => {
                 const r = await loadTemplatesFromFile(full, { importContext });
                 templates.push(...r.templates);
+                for (const t of r.templates)
+                    if (!localTemplateFiles.has(t.id))
+                        localTemplateFiles.set(t.id, full);
                 warnings.push(...r.warnings);
-                return { count: r.templates.length, warnings: r.warnings };
+                return { count: r.templates.length, warnings: r.warnings, rejected: r.rejected };
             });
             if (tracked.skipped)
                 warnings.push(...tracked.warnings);
@@ -293,8 +352,11 @@ export async function inspectSharkcraft(options = {}) {
             const tracked = await loadAssetTracked(ctx, full, 'pipelines', 'local-config', undefined, async () => {
                 const r = await loadPipelinesFromFile(full, { importContext });
                 pipelines.push(...r.pipelines);
+                for (const p of r.pipelines)
+                    if (!localPipelineFiles.has(p.id))
+                        localPipelineFiles.set(p.id, full);
                 warnings.push(...r.warnings);
-                return { count: r.pipelines.length, warnings: r.warnings };
+                return { count: r.pipelines.length, warnings: r.warnings, rejected: r.rejected };
             });
             if (tracked.skipped)
                 warnings.push(...tracked.warnings);
@@ -309,11 +371,13 @@ export async function inspectSharkcraft(options = {}) {
     }
     const templateSources = new Map();
     for (const t of templates) {
-        templateSources.set(t.id, { type: 'local' });
+        const file = localTemplateFiles.get(t.id);
+        templateSources.set(t.id, { type: 'local', ...(file ? { file } : {}) });
     }
     const pipelineSources = new Map();
     for (const p of pipelines) {
-        pipelineSources.set(p.id, { type: 'local' });
+        const file = localPipelineFiles.get(p.id);
+        pipelineSources.set(p.id, { type: 'local', ...(file ? { file } : {}) });
     }
     const packs = await discoverPacks({
         projectRoot: workspace.projectRoot,
@@ -364,7 +428,7 @@ export async function inspectSharkcraft(options = {}) {
                         resolved.templates += 1;
                     }
                     warnings.push(...r.warnings);
-                    return { count: r.templates.length, warnings: r.warnings };
+                    return { count: r.templates.length, warnings: r.warnings, rejected: r.rejected };
                 });
                 if (tracked.skipped)
                     warnings.push(...tracked.warnings);
@@ -382,7 +446,7 @@ export async function inspectSharkcraft(options = {}) {
                         resolved.pipelines += 1;
                     }
                     warnings.push(...r.warnings);
-                    return { count: r.pipelines.length, warnings: r.warnings };
+                    return { count: r.pipelines.length, warnings: r.warnings, rejected: r.rejected };
                 });
                 if (tracked.skipped)
                     warnings.push(...tracked.warnings);
@@ -413,7 +477,7 @@ export async function inspectSharkcraft(options = {}) {
                     if (kind === 'docs')
                         resolved.docs += 1;
                     warnings.push(...r.warnings);
-                    return { count: r.entries.length, warnings: r.warnings };
+                    return { count: r.entries.length, warnings: r.warnings, ...(r.rejected ? { rejected: r.rejected } : {}) };
                 });
                 if (tracked.skipped)
                     warnings.push(...tracked.warnings);
@@ -490,7 +554,7 @@ export async function inspectSharkcraft(options = {}) {
                     if (pack.resolvedCounts)
                         pack.resolvedCounts.presets += 1;
                 }
-                return { count: r.presets.length, warnings: r.warnings };
+                return { count: r.presets.length, warnings: r.warnings, rejected: r.rejected };
             });
             if (tracked.skipped)
                 warnings.push(...tracked.warnings);
@@ -511,24 +575,39 @@ export async function inspectSharkcraft(options = {}) {
                 presetRegistry.add(preset);
                 presetSources.set(preset.id, { type: 'local', file: full });
             }
-            return { count: r.presets.length, warnings: r.warnings };
+            return { count: r.presets.length, warnings: r.warnings, rejected: r.rejected };
         });
         if (tracked.skipped)
             warnings.push(...tracked.warnings);
     }
     const boundaryRegistry = new BoundaryRegistry();
     const boundarySources = new Map();
+    // Round 11: every configured-but-unevaluable boundary rule / file, structured
+    // so each boundary surface reports it as an ERRORED rule (never a warning
+    // string nobody renders).
+    const boundaryLoadIssues = [];
     for (const pack of packs.validPacks) {
         const c = pack.manifest.contributions;
         for (const rel of c.boundaryFiles ?? []) {
             const full = nodePath.resolve(pack.packageRoot, rel);
             if (!existsSync(full)) {
                 warnings.push(`pack ${pack.packageName}: missing boundary file ${rel}`);
+                boundaryLoadIssues.push({
+                    file: boundaryFileLabel(workspace.projectRoot, full),
+                    kind: 'missing-file',
+                    origin: 'pack',
+                    packageName: pack.packageName,
+                    issues: [`pack ${pack.packageName} declares boundary file ${rel}, which does not exist`],
+                });
                 continue;
             }
             const tracked = await loadAssetTracked(ctx, full, 'boundaries', 'pack-manifest', pack.packageName, async () => {
-                const r = await loadBoundaryRulesFromFile(full, { importContext });
+                // Round 13 (lane B): the pack's name is stamped on each expectEmpty
+                // marker of its rules — a pack marker that went live is INFO, never a
+                // failure for the consumer, who cannot edit it.
+                const r = await loadBoundaryRulesFromFile(full, { importContext, packageName: pack.packageName });
                 warnings.push(...r.warnings);
+                boundaryLoadIssues.push(...boundaryLoadIssuesFromFile(r, workspace.projectRoot, 'pack', pack.packageName));
                 for (const rule of r.rules) {
                     if (boundaryRegistry.has(rule.id)) {
                         warnings.push(`pack ${pack.packageName}: boundary "${rule.id}" already provided — pack version skipped`);
@@ -542,29 +621,62 @@ export async function inspectSharkcraft(options = {}) {
                         file: full,
                     });
                 }
-                return { count: r.rules.length, warnings: r.warnings };
+                return { count: r.rules.length, warnings: r.warnings, rejected: boundaryRejections(full, r.invalid) };
             });
-            if (tracked.skipped)
+            if (tracked.skipped) {
                 warnings.push(...tracked.warnings);
+                boundaryLoadIssues.push({
+                    file: boundaryFileLabel(workspace.projectRoot, full),
+                    kind: 'load-error',
+                    origin: 'pack',
+                    packageName: pack.packageName,
+                    issues: tracked.warnings.length > 0 ? tracked.warnings : ['the rule file failed to load (cached)'],
+                });
+            }
         }
     }
-    for (const rel of cfgExt?.boundaryFiles ?? []) {
-        if (!cfg)
-            continue;
-        const full = nodePath.join(cfg.sharkcraftDir, rel);
-        if (!existsSync(full))
+    // Local rule files, through THE classification the configuration status
+    // reads too — a listed-but-missing file and an unlisted
+    // sharkcraft/boundaries.ts are reported identically everywhere (round 11,
+    // L-1). The unlisted default is reported, never auto-loaded: loading it
+    // silently would start enforcing rules nobody opted into.
+    const localBoundaryFiles = cfg
+        ? classifyLocalBoundaryFiles(cfg.sharkcraftDir, cfgExt?.boundaryFiles ?? [])
+        : { listed: [] };
+    for (const listed of localBoundaryFiles.listed) {
+        const full = listed.abs;
+        if (!listed.exists) {
+            warnings.push(`boundaryFiles lists "${listed.rel}" but ${full} does not exist — no boundary rules load from it`);
+            boundaryLoadIssues.push({
+                file: boundaryFileLabel(workspace.projectRoot, full),
+                kind: 'missing-file',
+                origin: 'local',
+                issues: [`boundaryFiles lists "${listed.rel}", but the file does not exist`],
+            });
             continue;
+        }
         const tracked = await loadAssetTracked(ctx, full, 'boundaries', 'local-config', undefined, async () => {
             const r = await loadBoundaryRulesFromFile(full, { importContext });
             warnings.push(...r.warnings);
+            boundaryLoadIssues.push(...boundaryLoadIssuesFromFile(r, workspace.projectRoot, 'local'));
             for (const rule of r.rules) {
                 boundaryRegistry.add(rule);
                 boundarySources.set(rule.id, { type: 'local', file: full });
             }
-            return { count: r.rules.length, warnings: r.warnings };
+            return { count: r.rules.length, warnings: r.warnings, rejected: boundaryRejections(full, r.invalid) };
         });
-        if (tracked.skipped)
+        if (tracked.skipped) {
             warnings.push(...tracked.warnings);
+            boundaryLoadIssues.push({
+                file: boundaryFileLabel(workspace.projectRoot, full),
+                kind: 'load-error',
+                origin: 'local',
+                issues: tracked.warnings.length > 0 ? tracked.warnings : ['the rule file failed to load (cached)'],
+            });
+        }
+    }
+    if (localBoundaryFiles.unlistedDefault) {
+        warnings.push(`${boundaryFileLabel(workspace.projectRoot, localBoundaryFiles.unlistedDefault)} exists but is not listed in boundaryFiles — its rules are NOT loaded (add \`boundaryFiles: ['boundaries.ts']\` to sharkcraft.config.ts)`);
     }
     const inspection = {
         projectRoot: workspace.projectRoot,
@@ -573,6 +685,7 @@ export async function inspectSharkcraft(options = {}) {
         sharkcraftDir: cfg?.sharkcraftDir ?? workspace.sharkcraftPath ?? null,
         config: cfg?.config ?? null,
         configFile: cfg?.configFile ?? null,
+        ...(cfgResult.ok ? {} : describeConfigLoadError(cfgResult.error)),
         knowledgeEntries: cleanEntries,
         templates,
         pipelines,
@@ -587,12 +700,14 @@ export async function inspectSharkcraft(options = {}) {
         presetSources,
         boundaryRegistry,
         boundarySources,
+        boundaryLoadIssues,
         index,
         ruleService,
         pathService,
         templateRegistry,
         pipelineRegistry,
         loaderDiagnostics: diagnostics,
+        packAssetFreshness: compiledPackFreshness(packs),
         inspectionElapsedMs: Date.now() - inspectStart,
         cacheEnabled: cache.enabled,
         cacheDir: cache.dir,
@@ -608,6 +723,59 @@ export async function inspectSharkcraft(options = {}) {
     }
     return inspection;
 }
+/**
+ * Freshness of every valid pack serving compiled contributions — the one
+ * authority, called only where something compiled can go stale (TS-source packs
+ * are skipped without hashing). Never throws: a pack whose files cannot be read
+ * simply reports what it could.
+ */
+function compiledPackFreshness(packs) {
+    const out = [];
+    for (const pack of packs.validPacks ?? []) {
+        if (!packHasCompiledContributions(pack.manifest))
+            continue;
+        try {
+            out.push(detectPackAssetFreshness(pack));
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    return out;
+}
+/**
+ * Summarise a config LOAD failure for the inspection. Only CONFIG_INVALID is a
+ * failure of a config file that exists; a missing sharkcraft/ folder has its
+ * own doctor check and is not reported here.
+ */
+function describeConfigLoadError(error) {
+    if (error.code !== ERROR_CODES.CONFIG_INVALID)
+        return {};
+    const details = error.details ?? {};
+    const fullPath = details['fullPath'];
+    const issues = [];
+    const rawIssues = details['issues'];
+    if (Array.isArray(rawIssues)) {
+        for (const raw of rawIssues) {
+            const iss = (raw ?? {});
+            const at = (iss.path ?? []).map(String).join('.') || '<root>';
+            issues.push(`${at}: ${typeof iss.message === 'string' ? iss.message : 'invalid value'}`);
+        }
+    }
+    // An import failure (e.g. a syntax error) carries no schema issues; its
+    // cause is the build/evaluation error.
+    const cause = error.cause;
+    if (issues.length === 0 && cause instanceof Error) {
+        issues.push((cause.message.split('\n')[0] ?? cause.message).trim());
+    }
+    return {
+        configLoadError: {
+            file: typeof fullPath === 'string' ? fullPath : null,
+            message: error.message,
+            issues,
+        },
+    };
+}
 export function runDoctor(inspection, options = {}) {
     const checks = [];
     if (!inspection.workspace.hasPackageJson) {
@@ -644,7 +812,25 @@ export function runDoctor(inspection, options = {}) {
             message: `Found at ${inspection.sharkcraftDir}`,
         });
     }
-    if (!inspection.configFile) {
+    if (inspection.configLoadError) {
+        // A config file EXISTS but was rejected. The loader then drops the WHOLE
+        // config — its knowledge/rule/template file lists and every config-declared
+        // plane — so this is an error, and it is never also "no config file".
+        const failure = inspection.configLoadError;
+        const where = failure.file ?? 'sharkcraft/sharkcraft.config.ts';
+        const detail = failure.issues.length > 0 ? failure.issues.join('; ') : failure.message;
+        checks.push({
+            id: 'config',
+            title: 'sharkcraft.config.ts',
+            severity: DoctorSeverity.Error,
+            category: 'config-invalid',
+            code: 'config-invalid',
+            message: `Invalid config ${where} — NOT loaded, every config-declared setting and plane is dropped: ${detail}`,
+            fix: `Fix the listed fields in ${where} (every key is validated against SharkCraftConfigSchema), then re-run \`shrk doctor\`.`,
+            whyThisMatters: 'An invalid config is discarded whole: its knowledge/rule/template file lists and every gate plane (wiring rules, registries, policy rules, baselines, …) silently fall back to nothing.',
+        });
+    }
+    else if (!inspection.configFile) {
         checks.push({
             id: 'config',
             title: 'sharkcraft.config.ts',
@@ -661,6 +847,22 @@ export function runDoctor(inspection, options = {}) {
             message: `Loaded from ${inspection.configFile}`,
         });
     }
+    // A replacing `registryLifecycle.skipDirs` that drops node_modules / dist / …
+    // makes the lifecycle scan read vendored and generated code. The one
+    // skip-dir authority decides; this only reports what it dropped.
+    const lifecycleSkip = inspection.config?.registryLifecycle;
+    if (lifecycleSkip?.skipDirs !== undefined) {
+        const { droppedDefaults } = resolveRegistryLifecycleSkipDirs(lifecycleSkip);
+        if (droppedDefaults.length > 0) {
+            checks.push({
+                id: 'registry-lifecycle-skip-dirs',
+                title: 'registryLifecycle.skipDirs',
+                severity: DoctorSeverity.Warning,
+                message: registryLifecycleSkipDirsWarning(droppedDefaults),
+                fix: `Use \`registryLifecycle.skipDirsAdd\` (extends the defaults), or add ${droppedDefaults.join(', ')} back to \`skipDirs\`.`,
+            });
+        }
+    }
     if (inspection.knowledgeEntries.length === 0) {
         checks.push({
             id: 'knowledge',
@@ -729,6 +931,25 @@ export function runDoctor(inspection, options = {}) {
             });
         }
     }
+    // Compiled pack contributions served from an older build (or with no build
+    // record at all). The one freshness authority computed this at inspection;
+    // absent for TS-source packs, so a repo without compiled packs sees nothing.
+    for (const f of inspection.packAssetFreshness ?? []) {
+        if (f.build.state !== 'stale' && f.build.state !== 'unrecorded')
+            continue;
+        const said = describePackAssetFreshness(f).build;
+        if (!said)
+            continue;
+        checks.push({
+            id: `pack-compiled-artifacts-${f.packageName}`,
+            title: 'Pack compiled artifacts',
+            severity: DoctorSeverity.Warning,
+            category: 'pack-compiled-artifacts',
+            code: f.build.state === 'stale' ? 'compiled-artifacts-stale' : 'compiled-artifacts-unrecorded',
+            message: said,
+            ...(f.build.rebuildCommand ? { fix: `(cd ${f.packageRoot} && ${f.build.rebuildCommand})` } : {}),
+        });
+    }
     if (inspection.pipelines.length === 0) {
         checks.push({
             id: 'pipelines',
@@ -763,6 +984,10 @@ export function runDoctor(inspection, options = {}) {
         });
     }
     for (const w of inspection.warnings) {
+        // The config load failure is already reported above as an error; do not
+        // repeat it as a second, weaker "Loader warning".
+        if (w === inspection.configLoadError?.message)
+            continue;
         checks.push({
             id: `warning-${checks.length}`,
             title: 'Loader warning',
@@ -851,7 +1076,29 @@ export function runDoctor(inspection, options = {}) {
             summary.advisoryCount += 1;
         }
     }
-    return { passed: summary.errors === 0, checks, summary };
+    // A compiled pack build with NO build record was never compared with its
+    // source, so the build the pack serves is unverified. The warning check above
+    // names it; this record is what keeps `shrk doctor` from reading "Ready ✓"
+    // over it (settled NOT VERIFIED, 2, like `packs doctor`). A stale build WAS
+    // compared (its finding stays a warning), and a repo with no compiled pack,
+    // or only fresh builds, gets no record at all.
+    const compiledBuilds = (inspection.packAssetFreshness ?? []).filter((f) => f.build.state !== 'not-compiled');
+    const unrecordedBuilds = compiledBuilds
+        .filter((f) => f.build.state === 'unrecorded')
+        .map((f) => f.packageName)
+        .sort();
+    const coverage = unrecordedBuilds.length > 0
+        ? [
+            {
+                unit: 'compiled pack builds',
+                expected: compiledBuilds.length,
+                examined: compiledBuilds.length - unrecordedBuilds.length,
+                unexamined: unrecordedBuilds,
+                reason: 'no build record, so the compiled artifacts they serve were never compared with their source (rebuild the pack to record one)',
+            },
+        ]
+        : [];
+    return { passed: summary.errors === 0, checks, summary, ...(coverage.length > 0 ? { coverage } : {}) };
 }
 function actionHintWhyThisMatters(code) {
     switch (code) {

package/dist/spec/spec-evidence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spec-evidence.d.ts","sourceRoot":"","sources":["../../src/spec/spec-evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,uEAAuE;AACvE,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,cAAc,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,CAAC;AAE1F,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACvD,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,oFAAoF;IACpF,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAgCD;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,4BAA4B,GAClC,wBAAwB,CAQ1B"}
+{"version":3,"file":"spec-evidence.d.ts","sourceRoot":"","sources":["../../src/spec/spec-evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH,uEAAuE;AACvE,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,cAAc,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,CAAC;AAE1F,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACvD,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,oFAAoF;IACpF,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAgCD;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,4BAA4B,GAClC,wBAAwB,CAQ1B"}

package/dist/spec/spec-evidence.js

@@ -20,6 +20,9 @@
  * for collecting `changedFiles` + `fileContents` (see the CLI
  * `collectChangedPaths` helper and `spec verify --coverage`).
  */
+// THE identifier tokenizer — shared with reuse and the recommender.
+import { matchesAny, TEST_FILE_GLOBS } from '@shrkcrft/boundaries';
+import { splitIdentifierTokens } from "../split-identifier.js";
 /** Cap on evidence items retained per criterion (deterministic, insertion-ordered). */
 const MAX_EVIDENCE_PER_CRITERION = 12;
 /**
@@ -83,7 +86,7 @@ function analyzeCriterion(criterion, input) {
     };
 }
 function collectFileEvidence(file, content, keywords, push) {
-    const pathTokens = tokenizeIdentifier(stripExtension(baseName(file)));
+    const pathTokens = splitIdentifierTokens(stripExtension(baseName(file)));
     if (isTestFile(file)) {
         // A new test backs a criterion when its path (or an exported helper)
         // names the feature. Test files are reported ONLY as `test` evidence.
@@ -93,7 +96,7 @@ function collectFileEvidence(file, content, keywords, push) {
             return;
         }
         for (const symbol of extractExportedSymbols(content)) {
-            const hit = firstMatch(tokenizeIdentifier(symbol), keywords);
+            const hit = firstMatch(splitIdentifierTokens(symbol), keywords);
             if (hit) {
                 push({ kind: 'test', file, detail: symbol, matched: hit });
                 return;
@@ -108,7 +111,7 @@ function collectFileEvidence(file, content, keywords, push) {
     }
     // symbol: a newly exported declaration names the feature.
     for (const symbol of extractExportedSymbols(content)) {
-        const hit = firstMatch(tokenizeIdentifier(symbol), keywords);
+        const hit = firstMatch(splitIdentifierTokens(symbol), keywords);
         if (hit)
             push({ kind: 'symbol', file, detail: symbol, matched: hit });
     }
@@ -119,7 +122,7 @@ function collectFileEvidence(file, content, keywords, push) {
             continue;
         const member = registrationMember(line);
         if (member) {
-            const hit = firstMatch(tokenizeIdentifier(member), keywords);
+            const hit = firstMatch(splitIdentifierTokens(member), keywords);
             if (hit) {
                 const kind = ROUTE_MARKER.test(line) ? 'route' : 'registration';
                 push({ kind, file, detail: member, matched: hit });
@@ -174,25 +177,13 @@ function extractExportedSymbols(content) {
 function extractKeywords(text) {
     const out = new Set();
     for (const raw of text.toLowerCase().match(/[a-z0-9][a-z0-9_-]*/g) ?? []) {
-        for (const tok of tokenizeIdentifier(raw)) {
+        for (const tok of splitIdentifierTokens(raw)) {
             if (tok.length >= 3 && !STOPWORDS.has(tok))
                 out.add(tok);
         }
     }
     return out;
 }
-/**
- * Split an identifier into lowercase tokens across camelCase, PascalCase,
- * snake_case, kebab-case and digit boundaries.
- */
-function tokenizeIdentifier(name) {
-    return name
-        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
-        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
-        .split(/[^A-Za-z0-9]+/)
-        .map((t) => t.toLowerCase())
-        .filter((t) => t.length > 0);
-}
 function firstMatch(tokens, keywords) {
     for (const t of tokens) {
         if (keywords.has(t))
@@ -200,10 +191,13 @@ function firstMatch(tokens, keywords) {
     }
     return null;
 }
+/**
+ * "Is this a test file?" through THE test-file layout list, `TEST_FILE_GLOBS`
+ * (the one a boundary rule's `excludeTests: true` expands to), so spec
+ * evidence and the boundary gate agree on which files are tests.
+ */
 function isTestFile(file) {
-    return (/\.(test|spec)\.[cm]?[jt]sx?$/.test(file) ||
-        file.includes('/__tests__/') ||
-        file.startsWith('__tests__/'));
+    return matchesAny(file.split('\\').join('/'), TEST_FILE_GLOBS);
 }
 function baseName(file) {
     const norm = file.split('\\').join('/');

package/dist/split-identifier.d.ts

@@ -0,0 +1,21 @@
+/**
+ * THE identifier tokenizer.
+ *
+ * Splits an identifier (or a free-text phrase) into lowercase tokens across
+ * camelCase, PascalCase, acronym runs, snake_case, kebab-case, whitespace and
+ * lower/digit→Upper boundaries:
+ *
+ *   DateRangePicker          → [date, range, picker]
+ *   IDateRangePickerOptions  → [i, date, range, picker, options]
+ *   HTTPServer               → [http, server]
+ *   date_range-picker        → [date, range, picker]
+ *
+ * One splitter for every "does this name match these words?" question —
+ * reuse name matching, spec evidence and the recommender's term matcher all
+ * read it — so two callers can never disagree about where a word boundary is.
+ * Do not write another. Order is preserved and duplicates are kept (callers
+ * that need a set build one); empty fragments are dropped. No stop-word or
+ * length filtering happens here — that is a caller's policy, not a boundary.
+ */
+export declare function splitIdentifierTokens(name: string): string[];
+//# sourceMappingURL=split-identifier.d.ts.map

package/dist/split-identifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"split-identifier.d.ts","sourceRoot":"","sources":["../src/split-identifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAO5D"}

package/dist/split-identifier.js

@@ -0,0 +1,27 @@
+/**
+ * THE identifier tokenizer.
+ *
+ * Splits an identifier (or a free-text phrase) into lowercase tokens across
+ * camelCase, PascalCase, acronym runs, snake_case, kebab-case, whitespace and
+ * lower/digit→Upper boundaries:
+ *
+ *   DateRangePicker          → [date, range, picker]
+ *   IDateRangePickerOptions  → [i, date, range, picker, options]
+ *   HTTPServer               → [http, server]
+ *   date_range-picker        → [date, range, picker]
+ *
+ * One splitter for every "does this name match these words?" question —
+ * reuse name matching, spec evidence and the recommender's term matcher all
+ * read it — so two callers can never disagree about where a word boundary is.
+ * Do not write another. Order is preserved and duplicates are kept (callers
+ * that need a set build one); empty fragments are dropped. No stop-word or
+ * length filtering happens here — that is a caller's policy, not a boundary.
+ */
+export function splitIdentifierTokens(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .split(/[^A-Za-z0-9]+/)
+        .map((t) => t.toLowerCase())
+        .filter((t) => t.length > 0);
+}