@codeyam/codeyam-cli 0.1.19 → 0.1.21

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

@@ -1,6 +1,6 @@
 import Database from 'better-sqlite3';
 import { Kysely, SqliteDialect } from 'kysely';
-import { isComponent, classifyGlossaryEntries, computeAudit, filterGlossaryByChangeStatus, resolveAuditSessionScope, queryScenarioCounts, queryPageScenarioCounts, queryIncompleteEntities, queryMiscategorizedScenarios, isOnlyIncompleteEntities, isAutoRemediable, identifyScenariosNeedingRecapture, detectDuplicateNames, } from "../editorAudit.js";
+import { isComponent, classifyGlossaryEntries, computeAudit, filterGlossaryByChangeStatus, resolveAuditSessionScope, queryScenarioCounts, queryPageScenarioCounts, queryIncompleteEntities, queryMiscategorizedScenarios, queryUnassociatedScenarios, isOnlyIncompleteEntities, isOnlyPreExistingIncomplete, isAutoRemediable, identifyScenariosNeedingRecapture, detectDuplicateNames, } from "../editorAudit.js";
 describe('editorAudit', () => {
     describe('isComponent', () => {
         it('should return true for JSX.Element return type', () => {
@@ -1466,6 +1466,279 @@ describe('editorAudit', () => {
             expect(auditResult.summary.incompleteEntities).toBeUndefined();
         });
     });
+    // ── filterToIncompleteFilePaths ──────────────────────────────────────
+    describe('filterToIncompleteFilePaths', () => {
+        // analyze-imports processes ALL file paths (~120 files) even when only
+        // a few need analysis. This function filters to files that have no
+        // entity with an analysis record.
+        let db;
+        let rawDb;
+        const projectId = 'test-project-id';
+        beforeEach(async () => {
+            rawDb = new Database(':memory:');
+            db = new Kysely({ dialect: new SqliteDialect({ database: rawDb }) });
+            await db.schema
+                .createTable('analyses')
+                .addColumn('id', 'varchar', (col) => col.primaryKey())
+                .addColumn('entity_sha', 'varchar')
+                .addColumn('entity_name', 'varchar')
+                .addColumn('project_id', 'varchar')
+                .execute();
+            await db.schema
+                .createTable('entities')
+                .addColumn('sha', 'varchar', (col) => col.primaryKey())
+                .addColumn('name', 'varchar')
+                .addColumn('entity_type', 'varchar')
+                .addColumn('file_path', 'varchar')
+                .execute();
+        });
+        afterEach(async () => {
+            await db.destroy();
+        });
+        it('should exclude files that have an entity with an analysis', async () => {
+            const { filterToIncompleteFilePaths } = require('../editorAudit');
+            // Entity with analysis — skip
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-header',
+                name: 'Header',
+                entity_type: 'visual',
+                file_path: 'app/components/Header.tsx',
+            })
+                .execute();
+            await db
+                .insertInto('analyses')
+                .values({
+                id: 'a-1',
+                entity_sha: 'sha-header',
+                entity_name: 'Header',
+                project_id: projectId,
+            })
+                .execute();
+            // Entity without analysis — needs analysis
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-rule',
+                name: 'RuleBuilder',
+                entity_type: 'visual',
+                file_path: 'app/components/RuleBuilder.tsx',
+            })
+                .execute();
+            const allFilePaths = [
+                'app/components/Header.tsx',
+                'app/components/RuleBuilder.tsx',
+                'app/components/Footer.tsx', // no entity — needs analysis
+            ];
+            const result = await filterToIncompleteFilePaths(db, projectId, allFilePaths);
+            expect(result).toContain('app/components/RuleBuilder.tsx');
+            expect(result).toContain('app/components/Footer.tsx');
+            expect(result).not.toContain('app/components/Header.tsx');
+        });
+        it('should return all file paths when no entities exist yet', async () => {
+            const { filterToIncompleteFilePaths } = require('../editorAudit');
+            const filePaths = ['app/Foo.tsx', 'app/Bar.tsx'];
+            const result = await filterToIncompleteFilePaths(db, projectId, filePaths);
+            expect(result).toEqual(filePaths);
+        });
+        it('should return empty when all files have analyzed entities', async () => {
+            const { filterToIncompleteFilePaths } = require('../editorAudit');
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-a',
+                name: 'CompA',
+                entity_type: 'visual',
+                file_path: 'app/CompA.tsx',
+            })
+                .execute();
+            await db
+                .insertInto('analyses')
+                .values({
+                id: 'a-1',
+                entity_sha: 'sha-a',
+                entity_name: 'CompA',
+                project_id: projectId,
+            })
+                .execute();
+            const result = await filterToIncompleteFilePaths(db, projectId, [
+                'app/CompA.tsx',
+            ]);
+            expect(result).toEqual([]);
+        });
+        it('should skip files with analysis even without scenarios', async () => {
+            const { filterToIncompleteFilePaths } = require('../editorAudit');
+            // Entity with analysis but NO scenarios — still complete
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-util',
+                name: 'utils',
+                entity_type: 'library',
+                file_path: 'app/lib/utils.ts',
+            })
+                .execute();
+            await db
+                .insertInto('analyses')
+                .values({
+                id: 'a-1',
+                entity_sha: 'sha-util',
+                entity_name: 'utils',
+                project_id: projectId,
+            })
+                .execute();
+            const result = await filterToIncompleteFilePaths(db, projectId, [
+                'app/lib/utils.ts',
+            ]);
+            expect(result).toEqual([]);
+        });
+    });
+    // ── phantom entity SHAs ─────────────────────────────────────────────
+    describe('queryIncompleteEntities with phantom entity SHAs', () => {
+        // Root cause of the Margo/reader step-blocking bug:
+        // Scenarios registered without component_path got a phantom entity_sha
+        // computed from component_name alone. These SHAs have NO entity record
+        // in the entities table and NO analyses. syncScenarioEntityShas can't
+        // fix them (it skips scenarios without component_path). So they remain
+        // "incomplete" forever, blocking step progression.
+        //
+        // Fix: queryIncompleteEntities should not report scenarios whose
+        // entity_sha has no entity record — these are orphaned data, not
+        // fixable by running analyze-imports.
+        let db;
+        let rawDb;
+        const projectId = 'test-project-id';
+        beforeEach(async () => {
+            rawDb = new Database(':memory:');
+            db = new Kysely({ dialect: new SqliteDialect({ database: rawDb }) });
+            await db.schema
+                .createTable('editor_scenarios')
+                .addColumn('id', 'varchar', (col) => col.primaryKey())
+                .addColumn('project_id', 'varchar', (col) => col.notNull())
+                .addColumn('name', 'varchar', (col) => col.notNull())
+                .addColumn('component_name', 'varchar')
+                .addColumn('component_path', 'varchar')
+                .addColumn('entity_sha', 'varchar')
+                .addColumn('display_name', 'varchar')
+                .addColumn('page_file_path', 'varchar')
+                .addColumn('url', 'varchar')
+                .addColumn('created_at', 'datetime')
+                .addColumn('updated_at', 'datetime')
+                .execute();
+            await db.schema
+                .createTable('analyses')
+                .addColumn('id', 'varchar', (col) => col.primaryKey())
+                .addColumn('entity_sha', 'varchar')
+                .addColumn('entity_name', 'varchar')
+                .addColumn('project_id', 'varchar')
+                .execute();
+            await db.schema
+                .createTable('entities')
+                .addColumn('sha', 'varchar', (col) => col.primaryKey())
+                .addColumn('name', 'varchar')
+                .addColumn('entity_type', 'varchar')
+                .addColumn('file_path', 'varchar')
+                .execute();
+        });
+        afterEach(async () => {
+            await db.destroy();
+        });
+        it('should not report scenarios with phantom entity SHAs (no entity record exists)', async () => {
+            // Real entity — has an entity record, analyses, and scenarios. Complete.
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-real',
+                name: 'RuleBuilder',
+                entity_type: 'visual',
+                file_path: 'app/components/RuleBuilder.tsx',
+            })
+                .execute();
+            await db
+                .insertInto('analyses')
+                .values({
+                id: 'a-1',
+                entity_sha: 'sha-real',
+                entity_name: 'RuleBuilder',
+                project_id: projectId,
+            })
+                .execute();
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-good',
+                project_id: projectId,
+                name: 'RuleBuilder - Empty',
+                component_name: 'RuleBuilder',
+                component_path: 'app/components/RuleBuilder.tsx',
+                entity_sha: 'sha-real',
+                created_at: '2026-03-16 23:00:00',
+            })
+                .execute();
+            // Phantom entity — scenario points to a SHA that doesn't exist
+            // in the entities table (registered without component_path).
+            // No entity record, no analyses, unfixable by analyze-imports.
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-phantom',
+                project_id: projectId,
+                name: 'Empty',
+                component_name: 'RuleBuilder',
+                component_path: null,
+                entity_sha: 'sha-phantom-no-entity-record',
+                created_at: '2026-03-16 22:00:00',
+            })
+                .execute();
+            const incomplete = await queryIncompleteEntities(db, projectId, null);
+            // Should NOT report phantom SHAs as incomplete — they can't be fixed
+            // by running analyze-imports (no entity record exists to resolve).
+            expect(incomplete).toHaveLength(0);
+        });
+        it('should still report real incomplete entities (entity exists but no analysis)', async () => {
+            // Real entity without analysis — this IS a legitimate incomplete entity
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-noanalysis',
+                name: 'Footer',
+                entity_type: 'visual',
+                file_path: 'app/components/Footer.tsx',
+            })
+                .execute();
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-1',
+                project_id: projectId,
+                name: 'Footer - Default',
+                component_name: 'Footer',
+                component_path: 'app/components/Footer.tsx',
+                entity_sha: 'sha-noanalysis',
+                created_at: '2026-03-16 23:00:00',
+            })
+                .execute();
+            // Phantom scenario (shouldn't affect results)
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-phantom',
+                project_id: projectId,
+                name: 'Footer - Alt',
+                component_name: 'Footer',
+                component_path: null,
+                entity_sha: 'sha-phantom-does-not-exist',
+                created_at: '2026-03-16 22:00:00',
+            })
+                .execute();
+            const incomplete = await queryIncompleteEntities(db, projectId, null);
+            // Should report Footer (real entity, no analysis) but NOT the phantom
+            expect(incomplete).toHaveLength(1);
+            expect(incomplete[0].name).toBe('Footer');
+            expect(incomplete[0].entitySha).toBe('sha-noanalysis');
+        });
+    });
     // ── queryMiscategorizedScenarios ─────────────────────────────────────
     describe('queryMiscategorizedScenarios', () => {
         let db;
@@ -1717,7 +1990,10 @@ describe('editorAudit', () => {
     });
     // ── isAutoRemediable ─────────────────────────────────────────────────
     describe('isAutoRemediable', () => {
-        it('should return true on first attempt when only incomplete entities', () => {
+        // isAutoRemediable always returns false — the audit never triggers
+        // full analyze-imports inline. It takes minutes on large projects.
+        // Only lightweight backfill is acceptable during audit.
+        it('should return false even on first attempt with only incomplete entities', () => {
             const result = isAutoRemediable({
                 componentsMissing: 0,
                 componentsWithErrors: 0,
@@ -1729,11 +2005,9 @@ describe('editorAudit', () => {
                 incompleteEntities: 3,
                 allPassing: false,
             }, false);
-            expect(result).toBe(true);
+            expect(result).toBe(false);
         });
-        it('should return false on second attempt (already tried once)', () => {
-            // This is the key fix: if we already tried analyze-imports and
-            // entities are STILL incomplete, don't try again — report the failure
+        it('should return false on second attempt', () => {
             const result = isAutoRemediable({
                 componentsMissing: 0,
                 componentsWithErrors: 0,
@@ -2187,8 +2461,11 @@ describe('editorAudit', () => {
                 },
             ]);
         });
-        it('should use entity name from entities table, falling back to component_name', async () => {
-            // Scenario has entity_sha but entity record doesn't exist
+        it('should skip phantom SHAs (entity_sha with no entity record)', async () => {
+            // Scenario has entity_sha but entity record doesn't exist.
+            // These are "phantom SHAs" created when scenarios were registered
+            // without component_path — they can never be fixed by analyze-imports
+            // and should not block audit progression.
             await db
                 .insertInto('editor_scenarios')
                 .values({
@@ -2201,14 +2478,8 @@ describe('editorAudit', () => {
             })
                 .execute();
             const result = await queryIncompleteEntities(db, projectId, null);
-            expect(result).toEqual([
-                {
-                    entitySha: 'sha-ghost',
-                    name: 'GhostComponent',
-                    scenarioCount: 1,
-                    preExisting: false,
-                },
-            ]);
+            // Phantom SHAs are excluded — not reportable as incomplete
+            expect(result).toEqual([]);
         });
         it('should detect incomplete entity whose scenario predates the session', async () => {
             // Entity with no analyses, scenario created BEFORE session
@@ -2676,5 +2947,613 @@ describe('editorAudit', () => {
             expect(result.summary.componentsMissing).toBe(1);
         });
     });
+    // ── queryUnassociatedScenarios ──────────────────────────────────────
+    describe('queryUnassociatedScenarios', () => {
+        let db;
+        let rawDb;
+        const projectId = 'test-project-id';
+        beforeEach(async () => {
+            rawDb = new Database(':memory:');
+            db = new Kysely({ dialect: new SqliteDialect({ database: rawDb }) });
+            await db.schema
+                .createTable('editor_scenarios')
+                .addColumn('id', 'varchar', (col) => col.primaryKey())
+                .addColumn('project_id', 'varchar', (col) => col.notNull())
+                .addColumn('name', 'varchar', (col) => col.notNull())
+                .addColumn('component_name', 'varchar')
+                .addColumn('component_path', 'varchar')
+                .addColumn('entity_sha', 'varchar')
+                .addColumn('display_name', 'varchar')
+                .addColumn('page_file_path', 'varchar')
+                .addColumn('url', 'varchar')
+                .addColumn('type', 'varchar')
+                .addColumn('created_at', 'datetime')
+                .addColumn('updated_at', 'datetime')
+                .execute();
+        });
+        afterEach(async () => {
+            await db.destroy();
+        });
+        it('should return empty when all scenarios have entity_sha', async () => {
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-1',
+                project_id: projectId,
+                name: 'Header - Default',
+                component_name: 'Header',
+                component_path: 'src/components/Header.tsx',
+                entity_sha: 'sha-header',
+                created_at: '2026-03-16 23:00:00',
+                updated_at: '2026-03-16 23:00:00',
+            })
+                .execute();
+            const result = await queryUnassociatedScenarios(db, projectId, null);
+            expect(result).toEqual([]);
+        });
+        it('should find component scenarios with NULL entity_sha', async () => {
+            // This reproduces the Margo testapp bug: subagent registered scenarios
+            // but entity records didn't exist yet, so entity_sha was never set
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-1',
+                project_id: projectId,
+                name: 'SearchBar - Default',
+                component_name: 'SearchBar',
+                component_path: 'src/components/SearchBar.tsx',
+                entity_sha: null,
+                created_at: '2026-03-20 18:45:00',
+                updated_at: '2026-03-20 18:45:00',
+            })
+                .execute();
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-2',
+                project_id: projectId,
+                name: 'SearchBar - With Results',
+                component_name: 'SearchBar',
+                component_path: 'src/components/SearchBar.tsx',
+                entity_sha: null,
+                created_at: '2026-03-20 18:45:05',
+                updated_at: '2026-03-20 18:45:05',
+            })
+                .execute();
+            const result = await queryUnassociatedScenarios(db, projectId, null);
+            expect(result).toHaveLength(1);
+            expect(result[0].name).toBe('SearchBar');
+            expect(result[0].filePath).toBe('src/components/SearchBar.tsx');
+            expect(result[0].scenarioCount).toBe(2);
+            expect(result[0].scenarioNames).toEqual(expect.arrayContaining([
+                'SearchBar - Default',
+                'SearchBar - With Results',
+            ]));
+        });
+        it('should find page scenarios with NULL entity_sha', async () => {
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-1',
+                project_id: projectId,
+                name: 'Full Page — Rich Library',
+                component_name: null,
+                component_path: null,
+                page_file_path: 'src/library/LibraryApp.tsx',
+                entity_sha: null,
+                created_at: '2026-03-20 18:50:00',
+                updated_at: '2026-03-20 18:50:00',
+            })
+                .execute();
+            const result = await queryUnassociatedScenarios(db, projectId, null);
+            expect(result).toHaveLength(1);
+            expect(result[0].name).toBe('LibraryApp');
+            expect(result[0].filePath).toBe('src/library/LibraryApp.tsx');
+            expect(result[0].scenarioCount).toBe(1);
+        });
+        it('should ignore scenarios without any file path (orphans without component_path or page_file_path)', async () => {
+            // Scenarios with no file path at all can't be associated — they're not
+            // actionable, so don't report them as unassociated
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-1',
+                project_id: projectId,
+                name: 'Some Orphan',
+                component_name: null,
+                component_path: null,
+                page_file_path: null,
+                entity_sha: null,
+                created_at: '2026-03-20 18:50:00',
+                updated_at: '2026-03-20 18:50:00',
+            })
+                .execute();
+            const result = await queryUnassociatedScenarios(db, projectId, null);
+            expect(result).toEqual([]);
+        });
+        it('should group multiple components separately', async () => {
+            // Two different components both missing entity_sha
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-1',
+                project_id: projectId,
+                name: 'FullPageHeader - Default',
+                component_name: 'FullPageHeader',
+                component_path: 'src/components/FullPageHeader.tsx',
+                entity_sha: null,
+                created_at: '2026-03-20 18:45:00',
+                updated_at: '2026-03-20 18:45:00',
+            })
+                .execute();
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-2',
+                project_id: projectId,
+                name: 'SaveConfirmation - Visible',
+                component_name: 'SaveConfirmation',
+                component_path: 'src/components/SaveConfirmation.tsx',
+                entity_sha: null,
+                created_at: '2026-03-20 19:00:00',
+                updated_at: '2026-03-20 19:00:00',
+            })
+                .execute();
+            const result = await queryUnassociatedScenarios(db, projectId, null);
+            expect(result).toHaveLength(2);
+            const names = result.map((r) => r.name).sort();
+            expect(names).toEqual(['FullPageHeader', 'SaveConfirmation']);
+        });
+        it('should only include scenarios from the specified project', async () => {
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-1',
+                project_id: 'other-project',
+                name: 'SearchBar - Default',
+                component_name: 'SearchBar',
+                component_path: 'src/components/SearchBar.tsx',
+                entity_sha: null,
+                created_at: '2026-03-20 18:45:00',
+                updated_at: '2026-03-20 18:45:00',
+            })
+                .execute();
+            const result = await queryUnassociatedScenarios(db, projectId, null);
+            expect(result).toEqual([]);
+        });
+        it('should scope to feature session when featureStartedAt is provided', async () => {
+            // Pre-existing unassociated scenario (before session)
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-old',
+                project_id: projectId,
+                name: 'OldComponent - Default',
+                component_name: 'OldComponent',
+                component_path: 'src/components/OldComponent.tsx',
+                entity_sha: null,
+                created_at: '2026-03-19 10:00:00',
+                updated_at: '2026-03-19 10:00:00',
+            })
+                .execute();
+            // New unassociated scenario (during session)
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-new',
+                project_id: projectId,
+                name: 'NewComponent - Default',
+                component_name: 'NewComponent',
+                component_path: 'src/components/NewComponent.tsx',
+                entity_sha: null,
+                created_at: '2026-03-20 18:45:00',
+                updated_at: '2026-03-20 18:45:00',
+            })
+                .execute();
+            const result = await queryUnassociatedScenarios(db, projectId, '2026-03-20T18:00:00.000Z');
+            // Should only find the session-scoped one
+            expect(result).toHaveLength(1);
+            expect(result[0].name).toBe('NewComponent');
+        });
+        it('should include re-registered scenarios (updated_at in session) even if created before', async () => {
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-1',
+                project_id: projectId,
+                name: 'SearchBar - Default',
+                component_name: 'SearchBar',
+                component_path: 'src/components/SearchBar.tsx',
+                entity_sha: null,
+                created_at: '2026-03-19 10:00:00',
+                updated_at: '2026-03-20 18:45:00', // re-registered during session
+            })
+                .execute();
+            const result = await queryUnassociatedScenarios(db, projectId, '2026-03-20T18:00:00.000Z');
+            expect(result).toHaveLength(1);
+            expect(result[0].name).toBe('SearchBar');
+        });
+        it('should not include scenarios with entity_sha set (even if stale)', async () => {
+            // This scenario has an entity_sha — even if it's stale, that's a
+            // different problem (handled by queryIncompleteEntities)
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-1',
+                project_id: projectId,
+                name: 'Header - Default',
+                component_name: 'Header',
+                component_path: 'src/components/Header.tsx',
+                entity_sha: 'sha-old-version',
+                created_at: '2026-03-20 18:45:00',
+                updated_at: '2026-03-20 18:45:00',
+            })
+                .execute();
+            const result = await queryUnassociatedScenarios(db, projectId, null);
+            expect(result).toEqual([]);
+        });
+    });
+    // ── isAutoRemediable with unassociatedScenarios ────────────────────
+    describe('isAutoRemediable always returns false (no inline full analysis)', () => {
+        // Full analyze-imports takes minutes on large projects. The audit should
+        // never trigger it — only the lightweight backfill path is acceptable.
+        it('should return false for unassociatedScenarios only', () => {
+            expect(isAutoRemediable({ unassociatedScenarios: 3 }, false)).toBe(false);
+        });
+        it('should return false for incompleteEntities + unassociatedScenarios', () => {
+            expect(isAutoRemediable({ incompleteEntities: 1, unassociatedScenarios: 2 }, false)).toBe(false);
+        });
+        it('should return false even with no other failures', () => {
+            expect(isAutoRemediable({ unassociatedScenarios: 2 }, false)).toBe(false);
+        });
+        it('should return false when already attempted', () => {
+            expect(isAutoRemediable({ unassociatedScenarios: 3 }, true)).toBe(false);
+        });
+    });
+    describe('suggestedTestFile for functions without testFile', () => {
+        it('should suggest conventional .test.ts path when testFile is undefined', () => {
+            const result = computeAudit({
+                components: [],
+                functions: [
+                    { name: 'useLibraryShell', filePath: 'app/library/context.tsx' },
+                ],
+                scenarioCounts: {},
+                testFileExistence: {},
+            });
+            expect(result.functions[0].suggestedTestFile).toBe('app/library/context.test.ts');
+            expect(result.functions[0].status).toBe('missing');
+        });
+        it('should suggest .test.ts for .ts files', () => {
+            const result = computeAudit({
+                components: [],
+                functions: [{ name: 'calculatePrice', filePath: 'app/lib/pricing.ts' }],
+                scenarioCounts: {},
+                testFileExistence: {},
+            });
+            expect(result.functions[0].suggestedTestFile).toBe('app/lib/pricing.test.ts');
+        });
+        it('should not set suggestedTestFile when testFile is already specified', () => {
+            const result = computeAudit({
+                components: [],
+                functions: [
+                    {
+                        name: 'calculatePrice',
+                        filePath: 'app/lib/pricing.ts',
+                        testFile: 'app/lib/pricing.test.ts',
+                    },
+                ],
+                scenarioCounts: {},
+                testFileExistence: { 'app/lib/pricing.test.ts': true },
+            });
+            expect(result.functions[0].suggestedTestFile).toBeUndefined();
+        });
+    });
+    describe('hint for missing components', () => {
+        it('should hint that layout files need app-level scenarios', () => {
+            const result = computeAudit({
+                components: [
+                    { name: 'LibraryLayout', filePath: 'app/library/layout.tsx' },
+                ],
+                functions: [],
+                scenarioCounts: {},
+                testFileExistence: {},
+            });
+            expect(result.components[0].hint).toContain('layout');
+            expect(result.components[0].hint).toContain('pageFilePath');
+        });
+        it('should hint that page files need app-level scenarios', () => {
+            const result = computeAudit({
+                components: [
+                    { name: 'InboxPage', filePath: 'app/library/inbox/page.tsx' },
+                ],
+                functions: [],
+                scenarioCounts: {},
+                testFileExistence: {},
+            });
+            expect(result.components[0].hint).toContain('page');
+            expect(result.components[0].hint).toContain('pageFilePath');
+        });
+        it('should hint that regular components need isolation routes', () => {
+            const result = computeAudit({
+                components: [
+                    { name: 'DrinkCard', filePath: 'app/components/DrinkCard.tsx' },
+                ],
+                functions: [],
+                scenarioCounts: {},
+                testFileExistence: {},
+            });
+            expect(result.components[0].hint).toContain('isolated-components');
+        });
+        it('should not set hint when component has scenarios', () => {
+            const result = computeAudit({
+                components: [
+                    { name: 'DrinkCard', filePath: 'app/components/DrinkCard.tsx' },
+                ],
+                functions: [],
+                scenarioCounts: { DrinkCard: 2 },
+                testFileExistence: {},
+            });
+            expect(result.components[0].hint).toBeUndefined();
+        });
+    });
+    describe('formatIncompleteEntityGuidance', () => {
+        it('should include the entity name and scenario count', () => {
+            const { formatIncompleteEntityGuidance } = require('../editorAudit');
+            const result = formatIncompleteEntityGuidance({
+                entitySha: 'abc123',
+                name: 'RuleBuilder',
+                scenarioCount: 5,
+                preExisting: false,
+            });
+            expect(result).toContain('RuleBuilder');
+            expect(result).toContain('5');
+        });
+        it('should tell Claude the exact fix command', () => {
+            const { formatIncompleteEntityGuidance } = require('../editorAudit');
+            const result = formatIncompleteEntityGuidance({
+                entitySha: 'abc123',
+                name: 'RuleBuilder',
+                scenarioCount: 5,
+                preExisting: false,
+            });
+            expect(result).toContain('codeyam editor analyze-imports');
+        });
+        it('should flag pre-existing issues as non-blocking', () => {
+            const { formatIncompleteEntityGuidance } = require('../editorAudit');
+            const result = formatIncompleteEntityGuidance({
+                entitySha: 'abc123',
+                name: 'RuleBuilder',
+                scenarioCount: 5,
+                preExisting: true,
+            });
+            expect(result).toContain('pre-existing');
+        });
+        it('should explain what incomplete means', () => {
+            const { formatIncompleteEntityGuidance } = require('../editorAudit');
+            const result = formatIncompleteEntityGuidance({
+                entitySha: 'abc123',
+                name: 'RuleBuilder',
+                scenarioCount: 5,
+                preExisting: false,
+            });
+            // Should explain the root cause, not just the symptom
+            expect(result).toMatch(/scenario.*without.*import graph|import graph.*not.*built/i);
+        });
+    });
+    describe('getIncompleteEntityFilePaths', () => {
+        // The audit should auto-fix incomplete entities by running analysis on
+        // just their specific file paths, not all 117+ files. This function
+        // resolves entity SHAs to file paths for targeted analysis.
+        let db;
+        let rawDb;
+        beforeEach(async () => {
+            rawDb = new Database(':memory:');
+            db = new Kysely({ dialect: new SqliteDialect({ database: rawDb }) });
+            await db.schema
+                .createTable('entities')
+                .addColumn('sha', 'varchar', (col) => col.primaryKey())
+                .addColumn('name', 'varchar')
+                .addColumn('file_path', 'varchar')
+                .addColumn('project_id', 'varchar')
+                .addColumn('entity_type', 'varchar')
+                .execute();
+        });
+        afterEach(() => {
+            rawDb.close();
+        });
+        it('should resolve entity SHAs to file paths from the entities table', async () => {
+            const { getIncompleteEntityFilePaths } = require('../editorAudit');
+            await db
+                .insertInto('entities')
+                .values([
+                {
+                    sha: 'sha-rule',
+                    name: 'RuleBuilder',
+                    file_path: 'app/components/RuleBuilder.tsx',
+                    project_id: 'p1',
+                    entity_type: 'component',
+                },
+                {
+                    sha: 'sha-row',
+                    name: 'ArticleTableRow',
+                    file_path: 'app/components/ArticleTableRow.tsx',
+                    project_id: 'p1',
+                    entity_type: 'component',
+                },
+            ])
+                .execute();
+            const result = await getIncompleteEntityFilePaths(db, [
+                {
+                    entitySha: 'sha-rule',
+                    name: 'RuleBuilder',
+                    scenarioCount: 5,
+                    preExisting: false,
+                },
+                {
+                    entitySha: 'sha-row',
+                    name: 'ArticleTableRow',
+                    scenarioCount: 2,
+                    preExisting: false,
+                },
+            ]);
+            expect(result).toContain('app/components/RuleBuilder.tsx');
+            expect(result).toContain('app/components/ArticleTableRow.tsx');
+            expect(result).toHaveLength(2);
+        });
+        it('should skip entities whose SHA is not in the entities table', async () => {
+            const { getIncompleteEntityFilePaths } = require('../editorAudit');
+            const result = await getIncompleteEntityFilePaths(db, [
+                {
+                    entitySha: 'nonexistent-sha',
+                    name: 'Ghost',
+                    scenarioCount: 1,
+                    preExisting: false,
+                },
+            ]);
+            expect(result).toHaveLength(0);
+        });
+        it('should deduplicate file paths', async () => {
+            const { getIncompleteEntityFilePaths } = require('../editorAudit');
+            await db
+                .insertInto('entities')
+                .values([
+                {
+                    sha: 'sha-v1',
+                    name: 'Foo',
+                    file_path: 'app/Foo.tsx',
+                    project_id: 'p1',
+                    entity_type: 'component',
+                },
+                {
+                    sha: 'sha-v2',
+                    name: 'Foo',
+                    file_path: 'app/Foo.tsx',
+                    project_id: 'p1',
+                    entity_type: 'component',
+                },
+            ])
+                .execute();
+            const result = await getIncompleteEntityFilePaths(db, [
+                {
+                    entitySha: 'sha-v1',
+                    name: 'Foo',
+                    scenarioCount: 3,
+                    preExisting: false,
+                },
+                {
+                    entitySha: 'sha-v2',
+                    name: 'Foo',
+                    scenarioCount: 1,
+                    preExisting: false,
+                },
+            ]);
+            expect(result).toEqual(['app/Foo.tsx']);
+        });
+    });
+    describe('isAutoRemediable never triggers full analysis', () => {
+        // The audit must NEVER run handleAnalyzeImports inline — it takes minutes
+        // for large projects. Auto-remediation should only do the lightweight
+        // entity SHA backfill. isAutoRemediable is now always false; the callers
+        // use needsBackfillOnly for the fast path instead.
+        it('should always return false regardless of summary state', () => {
+            expect(isAutoRemediable({ incompleteEntities: 5 }, false)).toBe(false);
+            expect(isAutoRemediable({ unassociatedScenarios: 3 }, false)).toBe(false);
+            expect(isAutoRemediable({ incompleteEntities: 1, unassociatedScenarios: 2 }, false)).toBe(false);
+        });
+    });
+    // ── isOnlyPreExistingIncomplete ─────────────────────────────────────
+    describe('isOnlyPreExistingIncomplete', () => {
+        it('should return true when all incomplete entities are pre-existing and no other failures', () => {
+            expect(isOnlyPreExistingIncomplete({
+                incompleteEntities: 2,
+                preExistingIncompleteEntities: 2,
+                componentsMissing: 0,
+                componentsWithErrors: 0,
+                functionsFailing: 0,
+                functionsNameMismatch: 0,
+                functionsMissing: 0,
+                missingFromGlossary: 0,
+                miscategorizedScenarios: 0,
+                scenariosNeedingRecapture: 0,
+            }, [
+                {
+                    entitySha: 'a',
+                    name: 'RuleBuilder',
+                    scenarioCount: 5,
+                    preExisting: true,
+                },
+                {
+                    entitySha: 'b',
+                    name: 'ArticleTableRow',
+                    scenarioCount: 2,
+                    preExisting: true,
+                },
+            ])).toBe(true);
+        });
+        it('should return false when some incomplete entities are NOT pre-existing', () => {
+            expect(isOnlyPreExistingIncomplete({
+                incompleteEntities: 2,
+                preExistingIncompleteEntities: 1,
+                componentsMissing: 0,
+                componentsWithErrors: 0,
+                functionsFailing: 0,
+                functionsNameMismatch: 0,
+                functionsMissing: 0,
+                missingFromGlossary: 0,
+                miscategorizedScenarios: 0,
+                scenariosNeedingRecapture: 0,
+            }, [
+                {
+                    entitySha: 'a',
+                    name: 'RuleBuilder',
+                    scenarioCount: 5,
+                    preExisting: true,
+                },
+                {
+                    entitySha: 'b',
+                    name: 'NewComponent',
+                    scenarioCount: 1,
+                    preExisting: false,
+                },
+            ])).toBe(false);
+        });
+        it('should return false when there are other failures besides incomplete entities', () => {
+            expect(isOnlyPreExistingIncomplete({
+                incompleteEntities: 2,
+                preExistingIncompleteEntities: 2,
+                componentsMissing: 1,
+            }, [
+                {
+                    entitySha: 'a',
+                    name: 'RuleBuilder',
+                    scenarioCount: 5,
+                    preExisting: true,
+                },
+                {
+                    entitySha: 'b',
+                    name: 'ArticleTableRow',
+                    scenarioCount: 2,
+                    preExisting: true,
+                },
+            ])).toBe(false);
+        });
+        it('should return false when incomplete entities array is empty', () => {
+            expect(isOnlyPreExistingIncomplete({ incompleteEntities: 0 }, [])).toBe(false);
+        });
+        it('should return false when incomplete entities array is missing', () => {
+            expect(isOnlyPreExistingIncomplete({ incompleteEntities: 2, preExistingIncompleteEntities: 2 }, undefined)).toBe(false);
+        });
+    });
+    describe('isOnlyIncompleteEntities with unassociatedScenarios', () => {
+        it('should return true when only unassociatedScenarios present', () => {
+            expect(isOnlyIncompleteEntities({ unassociatedScenarios: 5 })).toBe(true);
+        });
+        it('should return false when unassociatedScenarios present with other failures', () => {
+            expect(isOnlyIncompleteEntities({
+                unassociatedScenarios: 5,
+                functionsMissing: 1,
+            })).toBe(false);
+        });
+    });
 });
 //# sourceMappingURL=editorAudit.test.js.map