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

package/dist/registration-hint-registry.js

@@ -8,10 +8,13 @@
  * Read-only: hints can be listed, fetched by id, validated, and previewed
  * against the live file system, but the engine never auto-applies them.
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { validateRegistrationHint, } from '@shrkcrft/plugin-api';
-import { importModuleViaLoader } from '@shrkcrft/core';
+import { normalizeRegistrationHint, validateRegistrationHint, } from '@shrkcrft/plugin-api';
+import { SKIP_DIRS } from '@shrkcrft/boundaries';
+import { DEAD_SELECTOR_CAUSES, importModuleViaLoader, MARKABLE_UNIT_LISTS, MarkableUnitList, normalizeUnitList, normalizeUnitScalar, qualifyListPath, qualifyUnitMarks, readContributionExport, RejectionCause, settleUnitLiveness, UnitDeadCause, UnitDeadWeight, UnitLivenessState, unitProblemsOf, } from '@shrkcrft/core';
+import { substitutePlaceholders } from "./substitute-placeholders.js";
+import { RegistrationHintDiscoveryStatus } from "./registration-hint-discovery-status.js";
 export const REGISTRATION_HINT_REGISTRY_SCHEMA = 'sharkcraft.registration-hint-registry/v1';
 export var RegistrationHintSource;
 (function (RegistrationHintSource) {
@@ -19,15 +22,20 @@ export var RegistrationHintSource;
     RegistrationHintSource["Pack"] = "pack";
     RegistrationHintSource["Fixture"] = "fixture";
 })(RegistrationHintSource || (RegistrationHintSource = {}));
-async function importDefault(file) {
-    const mod = (await importModuleViaLoader(file));
-    if (Array.isArray(mod.default))
-        return mod.default;
-    if (mod.default && typeof mod.default === 'object')
-        return [mod.default];
-    if (Array.isArray(mod.registrationHints))
-        return mod.registrationHints;
-    return [];
+async function importHints(file) {
+    return readContributionExport(await importModuleViaLoader(file), { namedKeys: ['registrationHints'] });
+}
+/**
+ * THE registration-hint acceptance predicate (round 12, 12.1): every issue of
+ * `validateRegistrationHint`, `<field>: <message>` — `[]` means accepted.
+ */
+export function registrationHintRejectionReasons(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return ['(entry): must be an object'];
+    const v = validateRegistrationHint(raw);
+    if (v.valid)
+        return [];
+    return v.issues.length > 0 ? v.issues.map((i) => `${i.field}: ${i.message}`) : ['(entry): failed validation'];
 }
 function localFiles(inspection) {
     const out = [];
@@ -39,54 +47,71 @@ function localFiles(inspection) {
         if (existsSync(abs))
             out.push(abs);
     }
-    const cfg = inspection.config;
-    for (const rel of cfg?.registrationHintFiles ?? []) {
-        out.push(nodePath.isAbsolute(rel) ? rel : nodePath.join(dir, rel));
-    }
+    // More hint files come from pack manifests (`registrationHintFiles`, loaded
+    // below) — there is no local-config key for them; the strict config schema
+    // rejects one, so a local read here could never be reached.
     return out;
 }
 export async function loadRegistrationHints(inspection) {
     const entries = [];
     const issues = [];
-    const seen = new Set();
-    const ingest = (raw, source, packageName, sourceFile) => {
-        const v = validateRegistrationHint(raw);
-        if (!v.valid) {
-            for (const i of v.issues) {
-                issues.push({
-                    severity: 'error',
-                    code: 'invalid-hint',
-                    message: `${i.field}: ${i.message}`,
-                    hintId: typeof raw.id === 'string' ? raw.id : undefined,
-                    source: sourceFile,
-                });
+    const rejected = [];
+    const seen = new Map();
+    const ingest = (raw, source, packageName, sourceFile, at) => {
+        const rawId = raw && typeof raw === 'object' ? raw.id : undefined;
+        const hintId = typeof rawId === 'string' ? rawId : undefined;
+        // THE acceptance predicate, then THE normaliser (round 13): markers in
+        // `discovery` become plain strings + the `expectEmptyUnits` ledger, stamped
+        // with the contributing pack. A normaliser refusal is a rejection too —
+        // never a crash further down (`glob.includes is not a function`).
+        const invalid = registrationHintRejectionReasons(raw);
+        const normalized = invalid.length === 0 ? normalizeRegistrationHint(raw, packageName) : undefined;
+        const reasons = invalid.length > 0 ? invalid : normalized !== undefined && !normalized.ok ? unitProblemsOf(normalized.error) : [];
+        if (normalized === undefined || !normalized.ok) {
+            for (const r of reasons) {
+                issues.push({ severity: 'error', code: 'invalid-hint', message: r, hintId, source: sourceFile });
             }
+            rejected.push({ ...at, ...(hintId !== undefined ? { entryId: hintId } : {}), reasons, cause: RejectionCause.Invalid });
             return;
         }
-        if (seen.has(raw.id)) {
+        const hint = normalized.value;
+        const prev = seen.get(hint.id);
+        if (prev !== undefined) {
             issues.push({
                 severity: 'error',
                 code: 'duplicate-id',
-                message: `Registration hint "${raw.id}" already loaded; skipping ${sourceFile}.`,
-                hintId: raw.id,
+                message: `Registration hint "${hint.id}" already loaded; skipping ${sourceFile}.`,
+                hintId: hint.id,
                 source: sourceFile,
             });
+            rejected.push({
+                ...at,
+                entryId: hint.id,
+                reasons: [`id: "${hint.id}" is already declared in ${prev}`],
+                cause: RejectionCause.DuplicateId,
+            });
             return;
         }
-        seen.add(raw.id);
+        seen.set(hint.id, sourceFile);
         entries.push({
-            hint: raw,
+            hint,
             source,
             ...(packageName ? { packageName } : {}),
             sourceFile,
         });
     };
+    const ingestAll = (exp, file, source, packageName, sourceFile) => {
+        exp.items.forEach((h, i) => ingest(h, source, packageName, sourceFile, {
+            file,
+            index: exp.single ? -1 : i,
+            ...(exp.exportName ? { exportName: exp.exportName } : {}),
+        }));
+    };
     for (const file of localFiles(inspection)) {
         try {
-            const list = await importDefault(file);
+            const exp = await importHints(file);
             const rel = nodePath.relative(inspection.projectRoot, file) || file;
-            for (const h of list)
-                ingest(h, RegistrationHintSource.Local, undefined, rel);
+            ingestAll(exp, file, RegistrationHintSource.Local, undefined, rel);
         }
         catch (e) {
             issues.push({
@@ -111,9 +136,7 @@ export async function loadRegistrationHints(inspection) {
                 continue;
             }
             try {
-                const list = await importDefault(file);
-                for (const h of list)
-                    ingest(h, RegistrationHintSource.Pack, pack.packageName, rel);
+                ingestAll(await importHints(file), file, RegistrationHintSource.Pack, pack.packageName, rel);
             }
             catch (e) {
                 issues.push({
@@ -125,7 +148,7 @@ export async function loadRegistrationHints(inspection) {
             }
         }
     }
-    return { entries, issues };
+    return { entries, issues, rejected };
 }
 export async function listRegistrationHints(inspection) {
     const { entries } = await loadRegistrationHints(inspection);
@@ -148,16 +171,20 @@ export async function previewRegistrationHint(inspection, hintId, options = {})
     // candidates from globs on the live file system.
     let targetFile = null;
     let candidates = [];
+    let discoveryCapped = false;
     if (hint.discovery.targetFile) {
         targetFile = hint.discovery.targetFile;
         candidates = [hint.discovery.targetFile];
     }
     else if (hint.discovery.targetGlobs && hint.discovery.targetGlobs.length > 0) {
-        candidates = await resolveGlobsAgainstRoot(inspection.projectRoot, hint.discovery.targetGlobs);
-        if (candidates.length === 1)
+        // THE discovery authority — the doctor classifies the same candidate set.
+        const found = resolveRegistrationHintCandidates(inspection, hint);
+        candidates = [...found.candidates];
+        discoveryCapped = found.capped;
+        if (candidates.length === 1 && !discoveryCapped)
             targetFile = candidates[0];
     }
-    const ambiguous = candidates.length !== 1;
+    const ambiguous = candidates.length !== 1 || discoveryCapped;
     const requiresHumanReview = hint.requiresHumanReview === true || ambiguous;
     const renderedOps = hint.operations.map((op) => {
         const description = describeOp(op);
@@ -183,68 +210,109 @@ export async function previewRegistrationHint(inspection, hintId, options = {})
         nextCommand: ambiguous
             ? `# Multiple candidates — pick one and apply manually.`
             : `# Preview only. Apply manually after human review.`,
+        ...(discoveryCapped ? { discoveryCapped: true } : {}),
     };
 }
-async function resolveGlobsAgainstRoot(projectRoot, globs) {
-    const out = [];
-    for (const glob of globs) {
-        // Crude glob: only `*` and `**` recognized; fallback to literal.
-        if (!glob.includes('*')) {
-            const abs = nodePath.join(projectRoot, glob);
-            if (existsSync(abs))
-                out.push(glob);
-            continue;
-        }
-        const baseSegments = [];
-        for (const seg of glob.split('/')) {
-            if (seg.includes('*'))
-                break;
-            baseSegments.push(seg);
-        }
-        const base = baseSegments.length > 0 ? nodePath.join(projectRoot, ...baseSegments) : projectRoot;
-        // Replace `**` with `___DOUBLESTAR___` BEFORE escaping; then
-        // escape special chars; then convert single `*` and the placeholder.
-        const escaped = glob
-            .replace(/\*\*/g, '___DOUBLESTAR___')
-            .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
-            .replace(/\*/g, '[^/]*')
-            .replace(/___DOUBLESTAR___/g, '.*');
-        let re;
+/** Directories one glob's discovery walk visits before it reports `capped`. */
+const DISCOVERY_DIR_CAP = 5000;
+/** One glob against the live tree: the preview's own dialect (`*`, `**`, else literal). */
+function walkDiscoveryGlob(projectRoot, glob) {
+    if (!glob.includes('*')) {
+        return { files: existsSync(nodePath.join(projectRoot, glob)) ? [glob] : [], capped: false };
+    }
+    const baseSegments = [];
+    for (const seg of glob.split('/')) {
+        if (seg.includes('*'))
+            break;
+        baseSegments.push(seg);
+    }
+    const base = baseSegments.length > 0 ? nodePath.join(projectRoot, ...baseSegments) : projectRoot;
+    // Replace `**` with a placeholder BEFORE escaping; then escape special chars;
+    // then convert single `*` and the placeholder.
+    const escaped = glob
+        .replace(/\*\*/g, '___DOUBLESTAR___')
+        .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '[^/]*')
+        .replace(/___DOUBLESTAR___/g, '.*');
+    let re;
+    try {
+        re = new RegExp('^' + escaped + '$');
+    }
+    catch {
+        return { files: [], capped: false };
+    }
+    if (!existsSync(base))
+        return { files: [], capped: false };
+    const files = [];
+    const stack = [base];
+    let visited = 0;
+    while (stack.length > 0) {
+        // A truncated walk is REPORTED — a zero from a capped walk is not a dead glob.
+        if (visited >= DISCOVERY_DIR_CAP)
+            return { files, capped: true };
+        const dir = stack.pop();
+        visited += 1;
         try {
-            re = new RegExp('^' + escaped + '$');
-        }
-        catch {
-            // Malformed glob — skip.
-            continue;
-        }
-        if (!existsSync(base))
-            continue;
-        // Walk the base directory looking for matches (capped, deterministic).
-        const stack = [base];
-        let safety = 0;
-        while (stack.length > 0 && safety < 5000) {
-            const dir = stack.pop();
-            safety += 1;
-            try {
-                const { readdirSync } = await import('node:fs');
-                const entries = readdirSync(dir, { withFileTypes: true });
-                for (const e of entries) {
-                    const next = nodePath.join(dir, String(e.name));
-                    if (e.isDirectory())
+            for (const e of readdirSync(dir, { withFileTypes: true })) {
+                const name = String(e.name);
+                const next = nodePath.join(dir, name);
+                // The shared vendor/build/VCS skip list: node_modules is never walked.
+                if (e.isDirectory()) {
+                    if (!SKIP_DIRS.has(name))
                         stack.push(next);
-                    else if (e.isFile()) {
-                        const rel = nodePath.relative(projectRoot, next);
-                        if (re.test(rel))
-                            out.push(rel);
-                    }
+                }
+                else if (e.isFile()) {
+                    const rel = nodePath.relative(projectRoot, next).split(nodePath.sep).join('/');
+                    if (re.test(rel))
+                        files.push(rel);
                 }
             }
-            catch {
-                // ignore traversal errors
-            }
+        }
+        catch {
+            // an unreadable directory contributes nothing
         }
     }
-    return Array.from(new Set(out));
+    return { files, capped: false };
+}
+/**
+ * THE discovery authority for a registration hint: `registrations preview`
+ * acts on it and the doctor classifies it, so "what would this hint target?"
+ * has one answer. A fixed `targetFile` counts as a candidate only when it
+ * exists (preview still names it either way).
+ */
+export function resolveRegistrationHintCandidates(inspection, hint) {
+    // Idempotent defensive normalisation (round 13): a loaded hint is plain
+    // already; a hand-built one carrying `{ pattern, expectEmpty }` markers is
+    // read by its unit instead of crashing the walk (`glob.includes`).
+    const discovery = hint.discovery ?? {};
+    const fileUnit = discovery.targetFile !== undefined ? normalizeUnitScalar(discovery.targetFile, TARGET_FILE) : undefined;
+    const targetFile = fileUnit?.ok ? fileUnit.value.unit : undefined;
+    const globUnits = discovery.targetGlobs !== undefined ? normalizeUnitList(discovery.targetGlobs, TARGET_GLOBS) : undefined;
+    const targetGlobs = globUnits?.ok
+        ? globUnits.value.units
+        : (discovery.targetGlobs ?? []).filter((g) => typeof g === 'string');
+    if (targetFile) {
+        const exists = existsSync(nodePath.join(inspection.projectRoot, targetFile));
+        return {
+            mode: 'fixed',
+            candidates: exists ? [targetFile] : [],
+            perGlob: [{ glob: targetFile, matched: exists ? 1 : 0 }],
+            capped: false,
+        };
+    }
+    if (!targetGlobs || targetGlobs.length === 0) {
+        return { mode: 'none', candidates: [], perGlob: [], capped: false };
+    }
+    const all = [];
+    const perGlob = [];
+    let capped = false;
+    for (const glob of targetGlobs) {
+        const r = walkDiscoveryGlob(inspection.projectRoot, glob);
+        perGlob.push({ glob, matched: r.files.length });
+        all.push(...r.files);
+        capped = capped || r.capped;
+    }
+    return { mode: 'glob', candidates: [...new Set(all)], perGlob, capped };
 }
 function describeOp(op) {
     switch (op.kind) {
@@ -268,52 +336,202 @@ function describeOp(op) {
             return `export${op.symbols ? ` { ${op.symbols.join(', ')} }` : ''} from "${op.from ?? '?'}"`;
     }
 }
+/** THE placeholder substitution, shared with pack-helper plans. */
 function substituteVars(snippet, vars) {
-    return snippet.replace(/\{\{\s*([A-Za-z0-9_]+)\s*\}\}/g, (_m, key) => vars[key] !== undefined ? vars[key] : `{{${key}}}`);
+    return substitutePlaceholders(snippet, vars);
 }
-// ─────────────────────────────────────────────────────────────────────────────
-// Doctor
-// ─────────────────────────────────────────────────────────────────────────────
-export async function listRegistrationHintIssues(inspection) {
-    const { issues, entries } = await loadRegistrationHints(inspection);
-    const out = [...issues];
-    // Cross-validate: target files referenced by hints with a fixed
-    // `targetFile` must currently exist; report missing as warning.
-    for (const e of entries) {
-        if (e.hint.discovery.targetFile) {
-            const abs = nodePath.join(inspection.projectRoot, e.hint.discovery.targetFile);
-            if (!existsSync(abs)) {
-                out.push({
-                    severity: 'warning',
-                    code: 'target-file-missing',
-                    message: `Registration hint "${e.hint.id}" targets ${e.hint.discovery.targetFile} but the file is missing.`,
-                    hintId: e.hint.id,
-                    source: e.sourceFile,
-                });
+const TARGET_GLOBS = MARKABLE_UNIT_LISTS[MarkableUnitList.RegistrationHintTargetGlobs].listPath;
+const TARGET_FILE = MARKABLE_UNIT_LISTS[MarkableUnitList.RegistrationHintTargetFile].listPath;
+/** The list a discovery mode judges — a marker on the other list (a glob beside a fixed target) is never read. */
+function judgedList(mode) {
+    return mode === 'fixed' ? TARGET_FILE : mode === 'glob' ? TARGET_GLOBS : undefined;
+}
+/**
+ * One observation per selector THE discovery authority judged: the fixed
+ * target, or each glob. Existence and liveness are one predicate here (a file
+ * matches, or none does); a zero from a capped walk is unproven, never dead.
+ */
+function discoveryObservations(hint, found) {
+    if (found.mode === 'none') {
+        return [
+            {
+                list: qualifyListPath(hint.id, 'discovery'),
+                unit: 'no discovery',
+                label: `${hint.id}: no discovery`,
+                exists: false,
+                live: false,
+                cause: UnitDeadCause.Defect,
+                deadReason: 'declares neither discovery.targetFile nor discovery.targetGlobs, so it can never target a file',
+            },
+        ];
+    }
+    const fixed = found.mode === 'fixed';
+    const list = qualifyListPath(hint.id, fixed ? TARGET_FILE : TARGET_GLOBS);
+    return found.perGlob.map((g) => {
+        const seen = g.matched > 0 ? true : found.capped ? undefined : false;
+        return {
+            list,
+            unit: g.glob,
+            label: `${hint.id}: ${g.glob}`,
+            exists: seen,
+            live: seen,
+            matched: g.matched,
+            liveBecause: fixed ? 'the target file exists' : `matches ${g.matched} file(s)`,
+            deadReason: fixed ? 'the file is missing' : 'matched no file',
+        };
+    });
+}
+const STATUS_TOTAL = {
+    [RegistrationHintDiscoveryStatus.Verified]: 'verified',
+    [RegistrationHintDiscoveryStatus.Ambiguous]: 'ambiguous',
+    [RegistrationHintDiscoveryStatus.Dead]: 'dead',
+    [RegistrationHintDiscoveryStatus.Unverified]: 'unverified',
+    [RegistrationHintDiscoveryStatus.IntendedEmpty]: 'intendedEmpty',
+};
+/** The anchor check, the same for a fixed target and a single glob candidate. */
+function checkAnchors(inspection, entry, relPath, out) {
+    let content;
+    try {
+        content = readFileSync(nodePath.join(inspection.projectRoot, relPath), 'utf8');
+    }
+    catch {
+        return;
+    }
+    for (const op of entry.hint.operations) {
+        if (!op.anchor || content.includes(op.anchor))
+            continue;
+        out.push({
+            severity: 'info',
+            code: 'anchor-not-present',
+            message: `Hint "${entry.hint.id}" expects anchor "${op.anchor}" in ${relPath} but it is missing today.`,
+            hintId: entry.hint.id,
+            source: entry.sourceFile,
+            target: op.anchor,
+        });
+    }
+}
+/**
+ * Verify every hint's discovery against the live tree through THE discovery
+ * authority. Fixed targets used to be the only ones checked; glob discovery —
+ * used precisely when the author was unsure of the target — got none, so a
+ * dead, an ambiguous and an anchor-less glob hint all read "OK".
+ */
+export async function buildRegistrationHintDoctorReport(inspection) {
+    const { issues: loadIssues, entries } = await loadRegistrationHints(inspection);
+    const issues = [...loadIssues];
+    const hints = [];
+    const totals = { hints: entries.length, verified: 0, ambiguous: 0, dead: 0, unverified: 0, intendedEmpty: 0 };
+    // Observe every selector of every hint, then settle them ONCE through THE
+    // liveness authority (round 13): the state, the dead list and both coverage
+    // records (the shortfall and the expectEmpty acceptance) come from it.
+    const found = entries.map((e) => resolveRegistrationHintCandidates(inspection, e.hint));
+    const observations = [];
+    const marks = [];
+    const spans = [];
+    entries.forEach((e, i) => {
+        const f = found[i];
+        const own = discoveryObservations(e.hint, f);
+        spans.push({ start: observations.length, end: observations.length + own.length });
+        observations.push(...own);
+        const list = judgedList(f.mode);
+        marks.push(...qualifyUnitMarks((e.hint.expectEmptyUnits ?? []).filter((m) => m.list === list), e.hint.id));
+    });
+    const capped = found.some((f) => f.capped);
+    const liveness = settleUnitLiveness({
+        subject: 'registration hints',
+        unitLabel: MARKABLE_UNIT_LISTS[MarkableUnitList.RegistrationHintTargetGlobs].unitLabel,
+        weight: UnitDeadWeight.Coverage,
+        observations,
+        marks,
+        deadSummary: 'matched no file',
+        ...(capped ? { capped: true, cappedReason: `a discovery walk hit its ${DISCOVERY_DIR_CAP}-directory cap` } : {}),
+    });
+    entries.forEach((e, i) => {
+        const f = found[i];
+        const span = spans[i];
+        const units = liveness.units.slice(span.start, span.end);
+        const push = (severity, code, message, target = '(discovery)') => {
+            issues.push({ severity, code, message, hintId: e.hint.id, source: e.sourceFile, target });
+        };
+        for (const u of units)
+            reportDiscoveryUnit(e.hint.id, f.mode, u, push);
+        let status;
+        if (f.mode === 'none') {
+            status = RegistrationHintDiscoveryStatus.Dead;
+        }
+        else if (f.mode === 'fixed') {
+            const u = units[0];
+            if (u?.state === UnitLivenessState.IntendedEmpty) {
+                status = RegistrationHintDiscoveryStatus.IntendedEmpty;
+            }
+            else if (f.candidates.length === 0) {
+                status = RegistrationHintDiscoveryStatus.Dead;
             }
             else {
-                // Sanity: if the hint uses an anchor, verify the anchor exists.
-                for (const op of e.hint.operations) {
-                    if (op.anchor) {
-                        try {
-                            const content = readFileSync(abs, 'utf8');
-                            if (!content.includes(op.anchor)) {
-                                out.push({
-                                    severity: 'info',
-                                    code: 'anchor-not-present',
-                                    message: `Hint "${e.hint.id}" expects anchor "${op.anchor}" in ${e.hint.discovery.targetFile} but it is missing today.`,
-                                    hintId: e.hint.id,
-                                    source: e.sourceFile,
-                                });
-                            }
-                        }
-                        catch {
-                            // ignore read errors
-                        }
-                    }
-                }
+                checkAnchors(inspection, e, f.candidates[0], issues);
+                status = RegistrationHintDiscoveryStatus.Verified;
             }
         }
+        else if (f.capped) {
+            push('info', 'discovery-unverified', `Registration hint "${e.hint.id}" discovery walk hit its ${DISCOVERY_DIR_CAP}-directory cap, so its candidate set is incomplete — NOT verified.`);
+            status = RegistrationHintDiscoveryStatus.Unverified;
+        }
+        else if (f.candidates.length === 0) {
+            // A hint whose every empty selector is intended-empty is not dead: it
+            // targets what the adopting app does not have yet (accepted, printed).
+            if (units.some((u) => u.state === UnitLivenessState.Dead)) {
+                push('warning', 'discovery-dead', `Registration hint "${e.hint.id}" discovery (${f.perGlob.map((g) => g.glob).join(', ')}) matches no file, so it can never target one — ${DEAD_SELECTOR_CAUSES}.`);
+                status = RegistrationHintDiscoveryStatus.Dead;
+            }
+            else {
+                status = RegistrationHintDiscoveryStatus.IntendedEmpty;
+            }
+        }
+        else if (f.candidates.length > 1) {
+            push('info', 'discovery-ambiguous', `Registration hint "${e.hint.id}" discovery matches ${f.candidates.length} files (${f.candidates.slice(0, 5).join(', ')}${f.candidates.length > 5 ? ', …' : ''}); preview will not guess.`);
+            status = RegistrationHintDiscoveryStatus.Ambiguous;
+        }
+        else {
+            checkAnchors(inspection, e, f.candidates[0], issues);
+            status = RegistrationHintDiscoveryStatus.Verified;
+        }
+        totals[STATUS_TOTAL[status]] += 1;
+        hints.push({ id: e.hint.id, discovery: f.mode, candidates: f.candidates.length, status, source: e.sourceFile });
+    });
+    return {
+        issues,
+        hints,
+        totals,
+        coverage: liveness.coverage,
+        deadUnits: liveness.dead.map((u) => `registration hint ${u.label}`),
+        liveness,
+    };
+}
+/**
+ * The per-selector issue for one SETTLED unit: a dead selector is a warning
+ * (the unmarked dead list), an intended-empty one and a stale marker are info
+ * (the acceptance rides in coverage; a went-live marker fails only through
+ * `selectorUnitFails` under `--fail-on-dead-units`, never through `--strict`).
+ */
+function reportDiscoveryUnit(hintId, mode, u, push) {
+    if (u.state === UnitLivenessState.Dead) {
+        if (mode === 'none') {
+            push('warning', 'discovery-missing', `Registration hint "${hintId}" ${u.deadReason ?? 'has no discovery'}.`);
+        }
+        else if (mode === 'fixed') {
+            push('warning', 'target-file-missing', `Registration hint "${hintId}" targets ${u.unit} but the file is missing — ${DEAD_SELECTOR_CAUSES}.`, u.unit);
+        }
+        else {
+            push('warning', 'discovery-glob-matched-nothing', `Registration hint "${hintId}" discovery glob "${u.unit}" matches no file — ${DEAD_SELECTOR_CAUSES}.`, u.unit);
+        }
     }
-    return out;
+    else if (u.state === UnitLivenessState.IntendedEmpty || u.state === UnitLivenessState.WentLive) {
+        // THE settle's sentence, after the selector it is about.
+        const selector = mode === 'fixed' ? `target file ${u.unit}` : `discovery glob "${u.unit}"`;
+        push('info', u.state === UnitLivenessState.IntendedEmpty ? 'discovery-intended-empty' : 'discovery-went-live', `Registration hint "${hintId}" ${selector} — ${u.message}`, u.unit);
+    }
+}
+/** Load issues + discovery findings — {@link buildRegistrationHintDoctorReport}'s issue list. */
+export async function listRegistrationHintIssues(inspection) {
+    return (await buildRegistrationHintDoctorReport(inspection)).issues;
 }