@codeyam/codeyam-cli 0.1.0-staging.b8b17a5 → 0.1.0-staging.ba3f279

package/codeyam-cli/src/utils/editorAudit.js

@@ -4,16 +4,34 @@
  * Cross-references glossary entries against registered scenarios (components)
  * and test files (functions) to detect gaps Claude may have missed.
  */
+import { isIsolationUrl, scenarioEntityName, } from "./entityChangeStatus.js";
 // ─── Logic ───────────────────────────────────────────────────────────
 const COMPONENT_RETURN_PATTERNS = ['JSX', 'React', 'Element', 'ReactNode'];
+/** File names that indicate page/route files — these are visual components
+ * verified via screenshots, not functions that need unit tests. */
+const PAGE_FILE_NAMES = new Set([
+    'page.tsx',
+    'page.ts',
+    'index.tsx',
+    'index.ts',
+]);
 /**
- * Returns true when the entry's returnType indicates a React component
- * (contains "JSX", "React", "Element", or "ReactNode").
+ * Returns true when the entry represents a visual component (needs scenarios,
+ * not unit tests). Matches on returnType containing JSX/React patterns, OR
+ * on file path patterns for page/route files.
  */
 export function isComponent(entry) {
-    if (!entry.returnType)
-        return false;
-    return COMPONENT_RETURN_PATTERNS.some((pat) => entry.returnType.includes(pat));
+    if (entry.returnType &&
+        COMPONENT_RETURN_PATTERNS.some((pat) => entry.returnType.includes(pat))) {
+        return true;
+    }
+    // Page/route files are visual components — verified via app scenarios, not tests
+    if (entry.filePath) {
+        const fileName = entry.filePath.split('/').pop() || '';
+        if (PAGE_FILE_NAMES.has(fileName))
+            return true;
+    }
+    return false;
 }
 /**
  * Split glossary entries into components (JSX-returning) and functions (everything else).
@@ -39,14 +57,28 @@ export function classifyGlossaryEntries(entries) {
  * @param scenarioCounts - Map of component_name → number of registered scenarios
  * @param testFileExistence - Map of testFile path → whether the file exists on disk
  */
-export function computeAudit({ components, functions, scenarioCounts, testFileExistence, testResults, clientErrors, }) {
+export function computeAudit({ components, functions, scenarioCounts, testFileExistence, testResults, clientErrors, totalScenarioCounts, entityChangeStatus, analysisFailedEntities, }) {
     const componentResults = components.map((c) => {
         const count = scenarioCounts[c.name] || 0;
+        const totalCount = totalScenarioCounts?.[c.name] || 0;
+        const changeStatus = entityChangeStatus?.[c.name];
         const errors = clientErrors?.[c.name];
         const hasErrors = count > 0 && errors && errors.length > 0;
         let status;
-        if (count === 0) {
-            status = 'missing';
+        if (analysisFailedEntities?.has(c.name)) {
+            status = 'analysis_failed';
+        }
+        else if (count === 0) {
+            // Entities with existing scenarios from prior sessions don't need
+            // new scenarios — they need recapture. This applies to both "edited"
+            // and "impacted" entities: an edited page may not have been re-registered
+            // this session, and an impacted page's dependency changed.
+            if (changeStatus && totalCount > 0) {
+                status = 'needs_recapture';
+            }
+            else {
+                status = 'missing';
+            }
         }
         else if (hasErrors) {
             status = 'has_errors';
@@ -54,12 +86,33 @@ export function computeAudit({ components, functions, scenarioCounts, testFileEx
         else {
             status = 'ok';
         }
+        // Generate actionable hint for missing or needs_recapture components
+        let hint;
+        if (status === 'missing') {
+            const fileName = c.filePath.split('/').pop() || '';
+            if (fileName === 'layout.tsx' || fileName === 'layout.ts') {
+                hint = `This is a layout file — register an app-level scenario with pageFilePath instead of componentName: codeyam editor register '{"name":"${c.name} - Default","pageFilePath":"${c.filePath}","url":"/<route>","dimensions":["Desktop"]}'`;
+            }
+            else if (fileName === 'page.tsx' || fileName === 'page.ts') {
+                hint = `This is a page file — register an app-level scenario with pageFilePath: codeyam editor register '{"name":"${c.name} - Default","pageFilePath":"${c.filePath}","url":"/<route>","dimensions":["Desktop"]}'`;
+            }
+            else {
+                hint = `Register a component scenario via an isolation route: codeyam editor isolate ${c.name} then codeyam editor register '{"name":"${c.name} - Default","componentName":"${c.name}","url":"/isolated-components/${c.name}?s=Default","dimensions":["Desktop"]}'`;
+            }
+        }
+        else if (status === 'needs_recapture') {
+            hint = `This component's code or dependencies changed — recapture existing scenarios to update screenshots: codeyam editor recapture ${c.name}`;
+        }
+        else if (status === 'analysis_failed') {
+            hint = `Analysis failed for this component (likely timed out due to complex dependencies). The component has partial data but may be missing some dependency schemas. Try re-analyzing: codeyam editor analyze-imports`;
+        }
         return {
             name: c.name,
             filePath: c.filePath,
-            scenarioCount: count,
+            scenarioCount: status === 'needs_recapture' ? totalCount : count,
             status,
             ...(hasErrors ? { clientErrors: errors } : {}),
+            ...(hint ? { hint } : {}),
         };
     });
     const functionResults = functions.map((f) => {
@@ -67,12 +120,17 @@ export function computeAudit({ components, functions, scenarioCounts, testFileEx
             ? (testFileExistence[f.testFile] ?? false)
             : false;
         if (!exists) {
+            // Suggest conventional test file path when testFile isn't in the glossary
+            const suggestedTestFile = !f.testFile
+                ? f.filePath.replace(/\.tsx?$/, '.test.ts')
+                : undefined;
             return {
                 name: f.name,
                 filePath: f.filePath,
                 testFile: f.testFile,
                 testFileExists: false,
                 status: 'missing',
+                ...(suggestedTestFile ? { suggestedTestFile } : {}),
             };
         }
         // If we have test results for this file, use them for deeper status
@@ -100,6 +158,14 @@ export function computeAudit({ components, functions, scenarioCounts, testFileEx
         else {
             status = 'ok';
         }
+        // Generate actionable hint for non-ok functions
+        let hint;
+        if (status === 'name_mismatch') {
+            hint = `Tests pass but won't show in the CodeYam UI. Add a top-level describe("${f.name}", ...) block in ${f.testFile}`;
+        }
+        else if (status === 'runner_error' && tr.errorMessage) {
+            hint = `Test runner crashed (not a test failure): ${tr.errorMessage}`;
+        }
         return {
             name: f.name,
             filePath: f.filePath,
@@ -109,11 +175,14 @@ export function computeAudit({ components, functions, scenarioCounts, testFileEx
             testsVisibleInUi: tr.hasEntityNameDescribe,
             status,
             ...(tr.errorMessage ? { errorMessage: tr.errorMessage } : {}),
+            ...(hint ? { hint } : {}),
         };
     });
     const componentsOk = componentResults.filter((c) => c.status === 'ok').length;
     const componentsWithErrors = componentResults.filter((c) => c.status === 'has_errors').length;
     const componentsMissing = componentResults.filter((c) => c.status === 'missing').length;
+    const componentsNeedingRecapture = componentResults.filter((c) => c.status === 'needs_recapture').length;
+    const componentsAnalysisFailed = componentResults.filter((c) => c.status === 'analysis_failed').length;
     const functionsOk = functionResults.filter((f) => f.status === 'ok').length;
     const functionsFailing = functionResults.filter((f) => f.status === 'failing').length;
     const functionsRunnerError = functionResults.filter((f) => f.status === 'runner_error').length;
@@ -127,6 +196,8 @@ export function computeAudit({ components, functions, scenarioCounts, testFileEx
             componentsOk,
             componentsMissing,
             componentsWithErrors,
+            componentsNeedingRecapture,
+            componentsAnalysisFailed,
             totalFunctions: functionResults.length,
             functionsOk,
             functionsMissing,
@@ -135,6 +206,7 @@ export function computeAudit({ components, functions, scenarioCounts, testFileEx
             functionsNameMismatch,
             allPassing: componentsMissing === 0 &&
                 componentsWithErrors === 0 &&
+                componentsAnalysisFailed === 0 &&
                 functionsFailing === 0 &&
                 functionsRunnerError === 0 &&
                 functionsNameMismatch === 0 &&
@@ -143,30 +215,166 @@ export function computeAudit({ components, functions, scenarioCounts, testFileEx
     };
 }
 /**
- * Returns true when the audit failure can be auto-fixed by running
- * analyze-imports: incomplete entities are the only issue AND we haven't
- * already tried (to prevent infinite retry loops when analysis has errors).
+ * Returns true when the audit failure can be auto-fixed inline.
+ *
+ * Always returns false — full analyze-imports takes minutes on large projects
+ * and must never run as part of the audit. The audit only does lightweight
+ * entity SHA backfill. Users should run `codeyam editor analyze-imports`
+ * separately if incomplete entities persist.
  */
-export function isAutoRemediable(summary, alreadyAttempted) {
-    if (alreadyAttempted)
-        return false;
-    if (!summary.incompleteEntities || summary.incompleteEntities === 0)
-        return false;
-    return isOnlyIncompleteEntities(summary);
+export function isAutoRemediable(_summary, _alreadyAttempted) {
+    return false;
+}
+/**
+ * Determine whether the audit should auto-recapture stale scenarios.
+ * Returns true when the `--fix` flag is set AND there are stale scenarios.
+ */
+export function shouldAutoRecapture(params) {
+    return params.fix && params.scenariosNeedingRecapture.length > 0;
+}
+/**
+ * Extract unique file paths that need targeted analysis from audit results.
+ *
+ * After a DB-only backfill attempt fails, these are the files that need
+ * `analyze-imports` to create entity records. Unlike full analyze-imports
+ * (which scans ALL glossary + page files), this returns only the specific
+ * files that have unresolved associations — typically 1-3 files.
+ */
+export function determineTargetedAnalysisPaths(auditData) {
+    const paths = new Set();
+    for (const u of auditData.unassociatedScenarios) {
+        if (u.filePath)
+            paths.add(u.filePath);
+    }
+    for (const e of auditData.incompleteEntities) {
+        if (e.filePath)
+            paths.add(e.filePath);
+    }
+    return [...paths];
+}
+/**
+ * Generate clear, actionable guidance for an incomplete entity.
+ *
+ * Tells Claude exactly what's wrong, whether it's pre-existing, and
+ * the exact command to fix it — no guessing required.
+ */
+export function formatIncompleteEntityGuidance(entity) {
+    const parts = [];
+    if (entity.preExisting) {
+        parts.push(`${entity.name}: ${entity.scenarioCount} scenario(s) without import graph (pre-existing issue, not from this session).`);
+        parts.push(`This is non-blocking — the entity had scenarios before this session but analyze-imports was never run for it.`);
+    }
+    else {
+        parts.push(`${entity.name}: ${entity.scenarioCount} scenario(s) without import graph — analyze-imports has not been run for this entity.`);
+        parts.push(`The entity has scenarios registered but its import graph is not built, so the editor cannot track its dependencies.`);
+    }
+    parts.push(`Fix: Run \`codeyam editor analyze-imports\` to build the import graph for all entities.`);
+    return parts.join(' ');
+}
+/**
+ * Generate step-by-step manual analysis instructions for an entity
+ * whose automated analysis has persistently failed.
+ *
+ * Used by the audit when analysis-failures.json contains the entity.
+ * Tells Claude exactly how to read the source, gather imports/types,
+ * and run `codeyam editor manual-entity` to unblock the audit.
+ */
+export function formatManualAnalysisGuidance(entity) {
+    const lines = [];
+    lines.push(`${entity.name}: ${entity.scenarioCount} scenario(s) — automated analysis failed`);
+    lines.push(`Error: ${entity.error}`);
+    lines.push('');
+    lines.push('MANUAL ANALYSIS REQUIRED — follow these steps:');
+    lines.push(`1. Read ${entity.filePath}`);
+    lines.push('2. Identify which glossary entities it imports (check .codeyam/glossary.json)');
+    lines.push('3. Determine entity type: "visual" if it returns JSX, "library" otherwise');
+    lines.push('4. Identify the type structure:');
+    lines.push('   - For components: props interface and hook return types');
+    lines.push('   - For functions: parameter types and return type');
+    lines.push(`5. Write the JSON to .codeyam/tmp/manual-entity.json then run: codeyam editor manual-entity @.codeyam/tmp/manual-entity.json`);
+    return lines.join('\n');
+}
+/**
+ * Resolve incomplete entity SHAs to their source file paths.
+ *
+ * Used by the audit to run targeted analysis on just the files that need it,
+ * instead of scanning all 117+ project files. Returns deduplicated file paths.
+ */
+export async function getIncompleteEntityFilePaths(db, incompleteEntities) {
+    if (incompleteEntities.length === 0)
+        return [];
+    const shas = incompleteEntities.map((e) => e.entitySha);
+    const rows = await db
+        .selectFrom('entities')
+        .select('file_path')
+        .where('sha', 'in', shas)
+        .execute();
+    const paths = new Set();
+    for (const row of rows) {
+        if (row.file_path)
+            paths.add(row.file_path);
+    }
+    return [...paths];
 }
 /**
- * Returns true when incompleteEntities is the ONLY audit failure —
- * all other failure counts are zero. Used to decide whether auto-running
- * analyze-imports can fix the audit without manual intervention.
+ * Returns true when the only audit failures are auto-fixable entity issues
+ * (incompleteEntities and/or unassociatedScenarios) — all other failure
+ * counts are zero. Used to decide whether auto-running analyze-imports +
+ * entity SHA sync can fix the audit without manual intervention.
  */
 export function isOnlyIncompleteEntities(summary) {
     return ((summary.componentsMissing ?? 0) === 0 &&
         (summary.componentsWithErrors ?? 0) === 0 &&
         (summary.functionsFailing ?? 0) === 0 &&
+        (summary.functionsRunnerError ?? 0) === 0 &&
         (summary.functionsNameMismatch ?? 0) === 0 &&
         (summary.functionsMissing ?? 0) === 0 &&
         (summary.missingFromGlossary ?? 0) === 0 &&
-        (summary.miscategorizedScenarios ?? 0) === 0);
+        (summary.miscategorizedScenarios ?? 0) === 0 &&
+        (summary.scenariosNeedingRecapture ?? 0) === 0);
+}
+/**
+ * Returns true when the only audit failures are incomplete entities that ALL
+ * existed before the current session. Used by the step gate to avoid blocking
+ * progress on pre-existing issues the user didn't cause.
+ *
+ * Requires both the summary (to confirm no other failure types) and the
+ * incompleteEntities array (to verify every entry is pre-existing).
+ */
+export function isOnlyPreExistingIncomplete(summary, incompleteEntities) {
+    // Must have at least one incomplete entity to be relevant
+    if (!incompleteEntities || incompleteEntities.length === 0)
+        return false;
+    // All other failure types must be zero
+    if (!isOnlyIncompleteEntities(summary))
+        return false;
+    // Every incomplete entity must be pre-existing
+    return incompleteEntities.every((e) => e.preExisting);
+}
+/**
+ * Filter a list of file paths to only those that need analysis.
+ *
+ * A file is excluded if ANY entity at that file path has an analysis
+ * record (direct or inherited from a sibling version with the same
+ * name+filePath). Everything else passes through.
+ *
+ * Used by handleAnalyzeImports to avoid re-analyzing ~120 files when
+ * only a few need it.
+ */
+export async function filterToIncompleteFilePaths(db, _projectId, allFilePaths) {
+    if (allFilePaths.length === 0)
+        return [];
+    // Single query: find all file paths that have at least one entity
+    // with an analysis record. These are already analyzed and can be skipped.
+    const analyzedRows = await db
+        .selectFrom('entities')
+        .innerJoin('analyses', 'analyses.entity_sha', 'entities.sha')
+        .select('entities.file_path')
+        .where('entities.file_path', 'in', allFilePaths)
+        .groupBy('entities.file_path')
+        .execute();
+    const analyzedFilePaths = new Set(analyzedRows.map((r) => r.file_path));
+    return allFilePaths.filter((fp) => !analyzedFilePaths.has(fp));
 }
 /**
  * Ensures the two audit filters — glossary scoping and scenario-count scoping —
@@ -214,22 +422,15 @@ export function filterGlossaryByChangeStatus(entries, entityChangeStatus) {
  */
 export async function queryIncompleteEntities(db, projectId, featureStartedAt) {
     // Step 1: Get distinct entity SHAs from scenarios (with counts)
-    let scenarioQuery = db
+    // No time filter — we check ALL scenarios to catch entities whose
+    // scenario SHAs were updated mid-session without touching updated_at.
+    const scenarioQuery = db
         .selectFrom('editor_scenarios')
         .select(['entity_sha'])
         .select(db.fn.count('id').as('count'))
         .where('project_id', '=', projectId)
         .where('entity_sha', 'is not', null)
         .groupBy('entity_sha');
-    if (featureStartedAt) {
-        const sqliteTimestamp = featureStartedAt
-            .replace('T', ' ')
-            .replace(/\.\d{3}Z$/, '');
-        scenarioQuery = scenarioQuery.where((eb) => eb.or([
-            eb('created_at', '>=', sqliteTimestamp),
-            eb('updated_at', '>=', sqliteTimestamp),
-        ]));
-    }
     const scenarioRows = await scenarioQuery.execute();
     if (scenarioRows.length === 0)
         return [];
@@ -258,24 +459,41 @@ export async function queryIncompleteEntities(db, projectId, featureStartedAt) {
     // A new entity version (created by the file watcher) may not have direct
     // analyses, but an older version (same name+filePath) might. This matches
     // getAllEntities() behavior which inherits analyses across versions.
-    const entityNames = [
-        ...new Set(entityRows.map((r) => r.name).filter(Boolean)),
+    // IMPORTANT: Must match by name+filePath, not name alone. When a component
+    // is extracted to a new file, the old version (different filePath) may have
+    // analyses but getAllEntities() won't inherit across different file paths.
+    const entityFilePathMap = new Map(entityRows.map((r) => [r.sha, r.file_path]));
+    const entityKeys = [
+        ...new Set(entityRows
+            .map((r) => `${r.name}::${r.file_path}`)
+            .filter((k) => !k.startsWith('::') && !k.endsWith('::'))),
     ];
-    let namesWithInheritedAnalyses = new Set();
-    if (entityNames.length > 0) {
+    let keysWithInheritedAnalyses = new Set();
+    if (entityKeys.length > 0) {
+        // We need to find entities that share name+filePath AND have analyses.
+        // Since Kysely doesn't support WHERE (name || '::' || file_path) IN (...),
+        // query by the entity names and filter by filePath in JS.
+        const entityNames = [
+            ...new Set(entityRows.map((r) => r.name).filter(Boolean)),
+        ];
         const siblingRows = await db
             .selectFrom('entities')
             .innerJoin('analyses', 'analyses.entity_sha', 'entities.sha')
-            .select('entities.name')
+            .select(['entities.name', 'entities.file_path'])
             .where('entities.name', 'in', entityNames)
-            .groupBy('entities.name')
+            .groupBy(['entities.name', 'entities.file_path'])
             .execute();
-        namesWithInheritedAnalyses = new Set(siblingRows.map((r) => r.name));
+        keysWithInheritedAnalyses = new Set(siblingRows.map((r) => `${r.name}::${r.file_path}`));
     }
-    // Filter out entities that have inherited analyses
+    // Filter out entities that have inherited analyses (same name+filePath)
     const trulyIncompleteShas = incompleteShas.filter((r) => {
-        const name = entityNameMap.get(r.entity_sha);
-        return !name || !namesWithInheritedAnalyses.has(name);
+        const sha = r.entity_sha;
+        const name = entityNameMap.get(sha);
+        const filePath = entityFilePathMap.get(sha);
+        if (!name)
+            return false; // No entity record (phantom SHA) — skip, not fixable by analysis
+        const key = `${name}::${filePath}`;
+        return !keysWithInheritedAnalyses.has(key);
     });
     if (trulyIncompleteShas.length === 0)
         return [];
@@ -293,12 +511,34 @@ export async function queryIncompleteEntities(db, projectId, featureStartedAt) {
         r.entity_sha,
         r.component_name,
     ]));
+    // Step 6: Determine preExisting flag — if featureStartedAt is provided,
+    // check which entity SHAs have at least one scenario created/updated
+    // during the session. Those without any are pre-existing issues.
+    let sessionShas = new Set();
+    if (featureStartedAt) {
+        const sqliteTimestamp = featureStartedAt
+            .replace('T', ' ')
+            .replace(/\.\d{3}Z$/, '');
+        const sessionRows = await db
+            .selectFrom('editor_scenarios')
+            .select('entity_sha')
+            .where('project_id', '=', projectId)
+            .where('entity_sha', 'in', trulyIncompleteShalist)
+            .where((eb) => eb.or([
+            eb('created_at', '>=', sqliteTimestamp),
+            eb('updated_at', '>=', sqliteTimestamp),
+        ]))
+            .groupBy('entity_sha')
+            .execute();
+        sessionShas = new Set(sessionRows.map((r) => r.entity_sha));
+    }
     return trulyIncompleteShas.map((r) => {
         const sha = r.entity_sha;
         return {
             entitySha: sha,
             name: entityNameMap.get(sha) || scenarioNameMap.get(sha) || 'Unknown',
             scenarioCount: Number(r.count),
+            preExisting: featureStartedAt ? !sessionShas.has(sha) : false,
         };
     });
 }
@@ -330,7 +570,7 @@ export async function queryMiscategorizedScenarios(db, projectId, featureStarted
     }
     const rows = await query.execute();
     // Filter to only rows where URL is NOT an isolation route
-    const miscategorized = rows.filter((r) => r.url && !r.url.includes('/isolated-components'));
+    const miscategorized = rows.filter((r) => r.url && !isIsolationUrl(r.url));
     if (miscategorized.length === 0)
         return [];
     // Group by (component_name, url)
@@ -385,4 +625,220 @@ export async function queryScenarioCounts(db, projectId, featureStartedAt) {
     }
     return counts;
 }
+/**
+ * Query scenario counts per page file path for app-level scenarios.
+ *
+ * App-level scenarios have `component_name = null` and are linked to pages
+ * via `page_file_path`. This mirrors `queryScenarioCounts` but groups by
+ * `page_file_path` instead of `component_name`.
+ */
+export async function queryPageScenarioCounts(db, projectId, featureStartedAt) {
+    let query = db
+        .selectFrom('editor_scenarios')
+        .select(['page_file_path'])
+        .select(db.fn.count('id').as('count'))
+        .where('project_id', '=', projectId)
+        .where('component_name', 'is', null)
+        .where('page_file_path', 'is not', null)
+        .groupBy('page_file_path');
+    if (featureStartedAt) {
+        const sqliteTimestamp = featureStartedAt
+            .replace('T', ' ')
+            .replace(/\.\d{3}Z$/, '');
+        query = query.where((eb) => eb.or([
+            eb('created_at', '>=', sqliteTimestamp),
+            eb('updated_at', '>=', sqliteTimestamp),
+        ]));
+    }
+    const rows = await query.execute();
+    const counts = {};
+    for (const row of rows) {
+        if (row.page_file_path) {
+            counts[row.page_file_path] = Number(row.count);
+        }
+    }
+    return counts;
+}
+// ─── Unassociated Scenarios ───────────────────────────────────────────
+/**
+ * Find scenarios with NULL entity_sha that have a file path
+ * (component_path or page_file_path). These scenarios were registered
+ * before entity records existed in the DB — typically because a subagent
+ * registered scenarios without running analyze-imports first.
+ *
+ * Fix: run `codeyam editor analyze-imports` to create entity records,
+ * then entity_sha backfill will associate them automatically.
+ *
+ * Optionally scoped to the current feature session via featureStartedAt.
+ */
+export async function queryUnassociatedScenarios(db, projectId, featureStartedAt) {
+    let query = db
+        .selectFrom('editor_scenarios')
+        .select(['component_name', 'component_path', 'page_file_path', 'name'])
+        .where('project_id', '=', projectId)
+        .where('entity_sha', 'is', null)
+        .where((eb) => eb.or([
+        eb('component_path', 'is not', null),
+        eb('page_file_path', 'is not', null),
+    ]));
+    if (featureStartedAt) {
+        const sqliteTimestamp = featureStartedAt
+            .replace('T', ' ')
+            .replace(/\.\d{3}Z$/, '');
+        query = query.where((eb) => eb.or([
+            eb('created_at', '>=', sqliteTimestamp),
+            eb('updated_at', '>=', sqliteTimestamp),
+        ]));
+    }
+    const rows = await query.execute();
+    if (rows.length === 0)
+        return [];
+    // Group by file path (component_path or page_file_path)
+    const groups = new Map();
+    for (const row of rows) {
+        const r = row;
+        const filePath = r.component_path || r.page_file_path;
+        const existing = groups.get(filePath);
+        if (existing) {
+            existing.scenarioNames.push(r.name);
+        }
+        else {
+            // Derive a display name: use component_name if available,
+            // otherwise extract from file path (e.g., "src/lib/LibraryApp.tsx" → "LibraryApp")
+            const displayName = r.component_name ||
+                filePath
+                    .split('/')
+                    .pop()
+                    ?.replace(/\.\w+$/, '') ||
+                filePath;
+            groups.set(filePath, {
+                name: displayName,
+                filePath,
+                scenarioNames: [r.name],
+            });
+        }
+    }
+    return [...groups.values()].map((g) => ({
+        name: g.name,
+        filePath: g.filePath,
+        scenarioCount: g.scenarioNames.length,
+        scenarioNames: g.scenarioNames,
+    }));
+}
+// ─── Duplicate Name Detection ─────────────────────────────────────────
+/**
+ * Detect glossary entries that share the same `name`.
+ *
+ * Returns a Map of name → entries[] for names that appear more than once.
+ * Single-occurrence names are excluded. Used to warn Claude that ambiguous
+ * names will make audit output confusing (e.g., three entries all named "Page").
+ */
+export function detectDuplicateNames(entries) {
+    const groups = new Map();
+    for (const entry of entries) {
+        const existing = groups.get(entry.name);
+        if (existing)
+            existing.push(entry);
+        else
+            groups.set(entry.name, [entry]);
+    }
+    // Only return groups with duplicates
+    for (const [name, group] of groups) {
+        if (group.length <= 1)
+            groups.delete(name);
+    }
+    return groups;
+}
+/**
+ * Identify scenarios that need recapture because their entity (or an entity
+ * in their dependency tree) has changed.
+ *
+ * Each scenario's entity name is resolved from its entity_sha (which points
+ * to the default export for app-level scenarios). The caller joins
+ * editor_scenarios.entity_sha → entities.name before calling this function.
+ *
+ * A scenario needs recapture when its entity has status 'edited' or 'impacted'
+ * AND the scenario was NOT re-registered in the current feature session.
+ */
+export function identifyScenariosNeedingRecapture(params) {
+    const { scenarios, entityChangeStatus } = params;
+    if (!entityChangeStatus || Object.keys(entityChangeStatus).length === 0) {
+        return [];
+    }
+    const result = [];
+    for (const scenario of scenarios) {
+        if (scenario.updatedInSession)
+            continue;
+        if (!scenario.entityName)
+            continue;
+        const changeStatus = entityChangeStatus[scenario.entityName];
+        if (!changeStatus)
+            continue;
+        // "new" entities need initial scenario creation, not recapture.
+        // Only "edited" and "impacted" entities have stale screenshots.
+        if (changeStatus.status === 'new')
+            continue;
+        result.push({
+            scenarioName: scenario.name,
+            entityName: scenario.entityName,
+            status: changeStatus,
+        });
+    }
+    return result;
+}
+// ─── Client Error Aggregation ─────────────────────────────────────────
+/**
+ * Aggregate client errors by component name using scenario metadata.
+ *
+ * Given a map of scenario ID → { scenarioName, errors } and a list of
+ * scenario metadata (with componentName from the DB), group errors by
+ * the component they belong to.
+ *
+ * For component scenarios: use the `componentName` field directly.
+ * For app-level scenarios (no componentName): derive the entity name
+ * using `scenarioEntityName()` — the same canonical function used by
+ * recapture detection and entity change status. This ensures the keys
+ * match what `computeAudit` checks against glossary entry names.
+ *
+ * This replaces the fragile "parse component name from scenario name"
+ * approach which fails for app-level scenarios like "Full Page with Library".
+ */
+export function aggregateClientErrorsByComponent(clientErrors, scenarioMetadata) {
+    const result = {};
+    // Build a lookup from scenario name → component/entity name.
+    // Uses scenarioEntityName() for consistency with the rest of the system
+    // (recapture detection, entity change status, journal filtering).
+    const scenarioToComponent = new Map();
+    for (const meta of scenarioMetadata) {
+        const entityName = scenarioEntityName({
+            componentName: meta.componentName,
+            pageFilePath: meta.pageFilePath,
+            url: meta.url,
+        });
+        if (entityName) {
+            scenarioToComponent.set(meta.name, entityName);
+        }
+    }
+    for (const [, data] of Object.entries(clientErrors)) {
+        if (data.errors.length === 0)
+            continue;
+        // First try: look up via scenario metadata (authoritative)
+        let componentName = scenarioToComponent.get(data.scenarioName);
+        // Fallback: parse from scenario name convention "ComponentName - Variant"
+        if (!componentName) {
+            const dashIndex = data.scenarioName.indexOf(' - ');
+            componentName =
+                dashIndex >= 0
+                    ? data.scenarioName.slice(0, dashIndex)
+                    : data.scenarioName;
+        }
+        if (componentName) {
+            if (!result[componentName]) {
+                result[componentName] = [];
+            }
+            result[componentName].push(...data.errors);
+        }
+    }
+    return result;
+}
 //# sourceMappingURL=editorAudit.js.map