@codeyam/codeyam-cli 0.1.0-staging.eb21b2f → 0.1.0-staging.f3b710d

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

@@ -0,0 +1,849 @@
+/**
+ * Pure logic for `codeyam editor audit` — zero I/O, fully testable.
+ *
+ * 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 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 &&
+        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).
+ */
+export function classifyGlossaryEntries(entries) {
+    const components = [];
+    const functions = [];
+    for (const entry of entries) {
+        if (isComponent(entry)) {
+            components.push(entry);
+        }
+        else {
+            functions.push(entry);
+        }
+    }
+    return { components, functions };
+}
+/**
+ * Given classified entries and coverage data, produce a structured audit result.
+ *
+ * @param components  - Glossary entries classified as components
+ * @param functions   - Glossary entries classified as functions
+ * @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, totalScenarioCounts, entityChangeStatus, analysisFailedEntities, testCaseCounts, }) {
+    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 (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';
+        }
+        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: status === 'needs_recapture' ? totalCount : count,
+            status,
+            ...(hasErrors ? { clientErrors: errors } : {}),
+            ...(hint ? { hint } : {}),
+        };
+    });
+    const functionResults = functions.map((f) => {
+        const exists = f.testFile
+            ? (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
+        const tr = f.testFile && testResults ? testResults[f.testFile] : undefined;
+        if (!tr) {
+            // No test results available — fall back to existence-only check
+            return {
+                name: f.name,
+                filePath: f.filePath,
+                testFile: f.testFile,
+                testFileExists: true,
+                status: 'ok',
+            };
+        }
+        let status;
+        if (!tr.passing && tr.errorMessage) {
+            status = 'runner_error';
+        }
+        else if (!tr.passing) {
+            status = 'failing';
+        }
+        else if (!tr.hasEntityNameDescribe) {
+            status = 'name_mismatch';
+        }
+        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,
+            testFile: f.testFile,
+            testFileExists: true,
+            testsPassing: tr.passing,
+            testsVisibleInUi: tr.hasEntityNameDescribe,
+            status,
+            ...(tr.errorMessage ? { errorMessage: tr.errorMessage } : {}),
+            ...(hint ? { hint } : {}),
+            ...(testCaseCounts?.[f.name] !== undefined
+                ? { testCaseCount: testCaseCounts[f.name] }
+                : {}),
+        };
+    });
+    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;
+    const functionsNameMismatch = functionResults.filter((f) => f.status === 'name_mismatch').length;
+    const functionsMissing = functionResults.filter((f) => f.status === 'missing').length;
+    const functionsThinCoverage = functionResults.filter((f) => f.status === 'ok' && f.testCaseCount !== undefined && f.testCaseCount < 3).length;
+    return {
+        components: componentResults,
+        functions: functionResults,
+        summary: {
+            totalComponents: componentResults.length,
+            componentsOk,
+            componentsMissing,
+            componentsWithErrors,
+            componentsNeedingRecapture,
+            componentsAnalysisFailed,
+            totalFunctions: functionResults.length,
+            functionsOk,
+            functionsMissing,
+            functionsFailing,
+            functionsRunnerError,
+            functionsNameMismatch,
+            functionsThinCoverage,
+            allPassing: componentsMissing === 0 &&
+                componentsWithErrors === 0 &&
+                componentsAnalysisFailed === 0 &&
+                functionsFailing === 0 &&
+                functionsRunnerError === 0 &&
+                functionsNameMismatch === 0 &&
+                functionsMissing === 0,
+        },
+    };
+}
+/**
+ * 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) {
+    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 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.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 —
+ * are consistent. When entityChangeStatus is empty/undefined (meaning the glossary
+ * will fall back to "audit all entries"), we must also drop the featureStartedAt
+ * filter so scenario counts include ALL scenarios, not just the current session.
+ *
+ * Without this, Feature 1 components get audited but their scenarios (created before
+ * the current feature session) aren't counted, causing false "no scenarios" failures.
+ */
+export function resolveAuditSessionScope({ featureStartedAt, entityChangeStatus, }) {
+    const hasChangeStatus = entityChangeStatus && Object.keys(entityChangeStatus).length > 0;
+    if (!hasChangeStatus) {
+        // Glossary will include all entries — scenario counts must also include all
+        return { featureStartedAt: null, entityChangeStatus };
+    }
+    return { featureStartedAt, entityChangeStatus };
+}
+/**
+ * Filter glossary entries to only those whose entities are new, edited, or impacted
+ * in the current working session. When entityChangeStatus is empty or undefined,
+ * falls back to returning all entries (no filtering).
+ *
+ * Matches by entity name first, then by filePath as a fallback.
+ */
+export function filterGlossaryByChangeStatus(entries, entityChangeStatus) {
+    if (!entityChangeStatus || Object.keys(entityChangeStatus).length === 0) {
+        return entries;
+    }
+    return entries.filter((entry) => {
+        // Match by entity name
+        if (entityChangeStatus[entry.name])
+            return true;
+        // Match by file path (entity names in changeStatus may be file-path keyed)
+        if (entityChangeStatus[entry.filePath])
+            return true;
+        return false;
+    });
+}
+/**
+ * Find entities that have scenarios but no analysis records.
+ * These entities need `codeyam editor analyze-imports` to run.
+ *
+ * Optionally scoped to the current feature session via featureStartedAt.
+ */
+export async function queryIncompleteEntities(db, projectId, featureStartedAt) {
+    // Step 1: Get distinct entity SHAs from scenarios (with counts)
+    // 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');
+    const scenarioRows = await scenarioQuery.execute();
+    if (scenarioRows.length === 0)
+        return [];
+    const scenarioShas = scenarioRows.map((r) => r.entity_sha);
+    // Step 2: Get entity SHAs that have analyses
+    const analysisRows = await db
+        .selectFrom('analyses')
+        .select('entity_sha')
+        .where('entity_sha', 'in', scenarioShas)
+        .groupBy('entity_sha')
+        .execute();
+    const analyzedShas = new Set(analysisRows.map((r) => r.entity_sha));
+    // Step 3: Find scenario entity SHAs without direct analyses
+    const incompleteShas = scenarioRows.filter((r) => !analyzedShas.has(r.entity_sha));
+    if (incompleteShas.length === 0)
+        return [];
+    // Step 4: Look up entity names for incomplete SHAs
+    const incompleteShalist = incompleteShas.map((r) => r.entity_sha);
+    const entityRows = await db
+        .selectFrom('entities')
+        .select(['sha', 'name', 'file_path'])
+        .where('sha', 'in', incompleteShalist)
+        .execute();
+    const entityNameMap = new Map(entityRows.map((r) => [r.sha, r.name]));
+    // Step 4.5: Check for inherited analyses from sibling entity versions.
+    // 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.
+    // 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 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', 'entities.file_path'])
+            .where('entities.name', 'in', entityNames)
+            .groupBy(['entities.name', 'entities.file_path'])
+            .execute();
+        keysWithInheritedAnalyses = new Set(siblingRows.map((r) => `${r.name}::${r.file_path}`));
+    }
+    // Filter out entities that have inherited analyses (same name+filePath)
+    const trulyIncompleteShas = incompleteShas.filter((r) => {
+        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 [];
+    const trulyIncompleteShalist = trulyIncompleteShas.map((r) => r.entity_sha);
+    // Step 5: Also get component_name from scenarios as fallback for name
+    const scenarioNameRows = await db
+        .selectFrom('editor_scenarios')
+        .select(['entity_sha', 'component_name'])
+        .where('project_id', '=', projectId)
+        .where('entity_sha', 'in', trulyIncompleteShalist)
+        .where('component_name', 'is not', null)
+        .groupBy('entity_sha')
+        .execute();
+    const scenarioNameMap = new Map(scenarioNameRows.map((r) => [
+        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,
+        };
+    });
+}
+/**
+ * Find component scenarios that use non-isolation URLs.
+ *
+ * Component scenarios should always use `/isolated-components/...` URLs.
+ * When a component scenario points at a real page URL (e.g., `/library`),
+ * it's miscategorized — it should either be an application scenario
+ * (no componentName, with pageFilePath) or use an isolation route.
+ *
+ * Optionally scoped to the current feature session via featureStartedAt.
+ */
+export async function queryMiscategorizedScenarios(db, projectId, featureStartedAt) {
+    let query = db
+        .selectFrom('editor_scenarios')
+        .select(['component_name', 'name', 'url'])
+        .where('project_id', '=', projectId)
+        .where('component_name', 'is not', null)
+        .where('url', '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();
+    // Filter to only rows where URL is NOT an isolation route
+    const miscategorized = rows.filter((r) => r.url && !isIsolationUrl(r.url));
+    if (miscategorized.length === 0)
+        return [];
+    // Group by (component_name, url)
+    const groups = new Map();
+    for (const row of miscategorized) {
+        const key = `${row.component_name}::${row.url}`;
+        const existing = groups.get(key);
+        if (existing) {
+            existing.scenarioNames.push(row.name);
+        }
+        else {
+            groups.set(key, {
+                componentName: row.component_name,
+                scenarioNames: [row.name],
+                url: row.url,
+            });
+        }
+    }
+    return [...groups.values()];
+}
+/**
+ * Query scenario counts per component, optionally scoped to the current
+ * feature session via featureStartedAt.
+ *
+ * A scenario belongs to the current session if it was created OR updated
+ * after featureStartedAt — re-registering a scenario during a new feature
+ * session updates `updated_at` but preserves the original `created_at`.
+ */
+export async function queryScenarioCounts(db, projectId, featureStartedAt) {
+    let query = db
+        .selectFrom('editor_scenarios')
+        .select(['component_name'])
+        .select(db.fn.count('id').as('count'))
+        .where('project_id', '=', projectId)
+        .where('component_name', 'is not', null)
+        .groupBy('component_name');
+    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.component_name) {
+            counts[row.component_name] = Number(row.count);
+        }
+    }
+    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