@codeyam/codeyam-cli 0.1.0-staging.28f73cf → 0.1.0-staging.2ea44f6

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

@@ -0,0 +1,1493 @@
+import { buildReverseDependencyGraph, classifyDirectChanges, computeEntityChangeStatus, buildChangedFilesMap, pageNameFromUrl, buildEntityInfosFromScenarios, buildEntityInfosFromGlossary, filterGroupsByChangeStatus, filterGlossaryByChangeStatus, filterScenarioScreenshotsByChangeStatus, } from "../entityChangeStatus.js";
+import { scanPageFilePaths, detectFirstFeature, readFeatureStartedAt, } from "../entityChangeStatus.server.js";
+import * as fsModule from 'fs';
+import * as pathModule from 'path';
+import * as os from 'os';
+// ── Helpers ──────────────────────────────────────────────────────────────
+/** Shorthand to build an EntityInfo with importedBy metadata */
+function entity(name, filePath, importedBy) {
+    if (!importedBy)
+        return { name, filePath };
+    // Convert simplified { filePath: [importerName, ...] } to DB format
+    const dbFormat = {};
+    for (const [fp, importers] of Object.entries(importedBy)) {
+        dbFormat[fp] = {};
+        for (const imp of importers) {
+            dbFormat[fp][imp] = { shas: ['test-sha'] };
+        }
+    }
+    return { name, filePath, importedBy: dbFormat };
+}
+/** Helper: get sorted impactedBy names from a result */
+function impactNames(result, entityName) {
+    return (result[entityName]?.impactedBy || []).map((d) => d.name).sort();
+}
+// ── Tests ────────────────────────────────────────────────────────────────
+describe('entityChangeStatus', () => {
+    // ── buildChangedFilesMap ───────────────────────────────────────────────
+    describe('buildChangedFilesMap', () => {
+        it('should map "added" files to "new"', () => {
+            const files = [
+                { path: 'components/New.tsx', status: 'added' },
+            ];
+            const result = buildChangedFilesMap(files, false);
+            expect(result.get('components/New.tsx')).toBe('new');
+        });
+        it('should map "untracked" files to "new"', () => {
+            const files = [
+                { path: 'components/Untracked.tsx', status: 'untracked' },
+            ];
+            const result = buildChangedFilesMap(files, false);
+            expect(result.get('components/Untracked.tsx')).toBe('new');
+        });
+        it('should map "modified" files to "edited"', () => {
+            const files = [
+                { path: 'components/Modified.tsx', status: 'modified' },
+            ];
+            const result = buildChangedFilesMap(files, false);
+            expect(result.get('components/Modified.tsx')).toBe('edited');
+        });
+        it('should ignore "deleted" files', () => {
+            const files = [
+                { path: 'components/Deleted.tsx', status: 'deleted' },
+            ];
+            const result = buildChangedFilesMap(files, false);
+            expect(result.size).toBe(0);
+        });
+        it('should ignore "renamed" files', () => {
+            const files = [
+                { path: 'components/Renamed.tsx', status: 'renamed' },
+            ];
+            const result = buildChangedFilesMap(files, false);
+            expect(result.size).toBe(0);
+        });
+        it('should treat ALL non-deleted files as "new" when isFirstFeature is true', () => {
+            const files = [
+                { path: 'components/Modified.tsx', status: 'modified' },
+                { path: 'components/Added.tsx', status: 'added' },
+                { path: 'components/Untracked.tsx', status: 'untracked' },
+                { path: 'components/Renamed.tsx', status: 'renamed' },
+                { path: 'components/Deleted.tsx', status: 'deleted' },
+            ];
+            const result = buildChangedFilesMap(files, true);
+            // Everything except deleted should be 'new'
+            expect(result.get('components/Modified.tsx')).toBe('new');
+            expect(result.get('components/Added.tsx')).toBe('new');
+            expect(result.get('components/Untracked.tsx')).toBe('new');
+            expect(result.get('components/Renamed.tsx')).toBe('new');
+            expect(result.has('components/Deleted.tsx')).toBe(false);
+        });
+        it('should return empty map for empty input', () => {
+            expect(buildChangedFilesMap([], false).size).toBe(0);
+            expect(buildChangedFilesMap([], true).size).toBe(0);
+        });
+        it('should handle mix of statuses correctly', () => {
+            const files = [
+                { path: 'a.tsx', status: 'added' },
+                { path: 'b.tsx', status: 'modified' },
+                { path: 'c.tsx', status: 'untracked' },
+                { path: 'd.tsx', status: 'deleted' },
+            ];
+            const result = buildChangedFilesMap(files, false);
+            expect(result.get('a.tsx')).toBe('new');
+            expect(result.get('b.tsx')).toBe('edited');
+            expect(result.get('c.tsx')).toBe('new');
+            expect(result.has('d.tsx')).toBe(false);
+            expect(result.size).toBe(3);
+        });
+    });
+    // ── pageNameFromUrl ───────────────────────────────────────────────────
+    describe('pageNameFromUrl', () => {
+        it('should return "Home" for null', () => {
+            expect(pageNameFromUrl(null)).toBe('Home');
+        });
+        it('should return "Home" for undefined', () => {
+            expect(pageNameFromUrl(undefined)).toBe('Home');
+        });
+        it('should return "Home" for root path "/"', () => {
+            expect(pageNameFromUrl('/')).toBe('Home');
+        });
+        it('should capitalize first segment for simple paths', () => {
+            expect(pageNameFromUrl('/about')).toBe('About');
+            expect(pageNameFromUrl('/drinks')).toBe('Drinks');
+            expect(pageNameFromUrl('/settings')).toBe('Settings');
+        });
+        it('should use only the first segment for nested paths', () => {
+            expect(pageNameFromUrl('/drinks/123')).toBe('Drinks');
+            expect(pageNameFromUrl('/blog/posts/latest')).toBe('Blog');
+        });
+        it('should strip query parameters', () => {
+            expect(pageNameFromUrl('/settings?tab=profile')).toBe('Settings');
+            expect(pageNameFromUrl('/drinks?sort=name&filter=ipa')).toBe('Drinks');
+        });
+        it('should handle paths without leading slash', () => {
+            expect(pageNameFromUrl('about')).toBe('About');
+        });
+        it('should handle empty string as Home', () => {
+            // Empty string: after stripping '/', split gives [''], charAt(0) is ''
+            // This is an edge case — empty string is falsy so returns Home
+            expect(pageNameFromUrl('')).toBe('Home');
+        });
+        it('should handle dynamic route segments', () => {
+            expect(pageNameFromUrl('/drinks/[id]')).toBe('Drinks');
+            expect(pageNameFromUrl('/users/[userId]/posts')).toBe('Users');
+        });
+    });
+    // ── buildEntityInfosFromScenarios ─────────────────────────────────────
+    describe('buildEntityInfosFromScenarios', () => {
+        it('should extract component entity from scenario with componentName/componentPath', () => {
+            const scenarios = [
+                {
+                    componentName: 'DrinkCard',
+                    componentPath: 'components/DrinkCard.tsx',
+                },
+            ];
+            const result = buildEntityInfosFromScenarios(scenarios, {}, []);
+            expect(result).toEqual([
+                { name: 'DrinkCard', filePath: 'components/DrinkCard.tsx' },
+            ]);
+        });
+        it('should extract page entity from scenario with URL', () => {
+            const scenarios = [
+                { componentName: null, componentPath: null, url: '/' },
+            ];
+            const pageFilePaths = { Home: 'app/page.tsx' };
+            const result = buildEntityInfosFromScenarios(scenarios, pageFilePaths, []);
+            expect(result).toEqual([{ name: 'Home', filePath: 'app/page.tsx' }]);
+        });
+        it('should derive page name from URL using pageNameFromUrl', () => {
+            const scenarios = [
+                { componentName: null, componentPath: null, url: '/drinks/123' },
+            ];
+            const pageFilePaths = { Drinks: 'app/drinks/page.tsx' };
+            const result = buildEntityInfosFromScenarios(scenarios, pageFilePaths, []);
+            expect(result).toEqual([
+                { name: 'Drinks', filePath: 'app/drinks/page.tsx' },
+            ]);
+        });
+        it('should skip page scenarios when page file path is not found', () => {
+            const scenarios = [
+                { componentName: null, componentPath: null, url: '/nonexistent' },
+            ];
+            const result = buildEntityInfosFromScenarios(scenarios, {}, []);
+            expect(result).toEqual([]);
+        });
+        it('should deduplicate by entity name (first occurrence wins)', () => {
+            const scenarios = [
+                {
+                    componentName: 'DrinkCard',
+                    componentPath: 'components/DrinkCard.tsx',
+                },
+                {
+                    componentName: 'DrinkCard',
+                    componentPath: 'components/DrinkCard.tsx',
+                },
+                {
+                    componentName: 'DrinkCard',
+                    componentPath: 'components/DrinkCard2.tsx',
+                },
+            ];
+            const result = buildEntityInfosFromScenarios(scenarios, {}, []);
+            expect(result).toHaveLength(1);
+            expect(result[0].filePath).toBe('components/DrinkCard.tsx');
+        });
+        it('should enrich entities with importedBy metadata from entity DB', () => {
+            const scenarios = [
+                {
+                    componentName: 'DrinkCard',
+                    componentPath: 'components/DrinkCard.tsx',
+                },
+            ];
+            const entitiesWithMetadata = [
+                {
+                    name: 'DrinkCard',
+                    metadata: {
+                        importedBy: {
+                            'components/DrinkCard.tsx': {
+                                DrinkList: { shas: ['abc'] },
+                            },
+                        },
+                    },
+                },
+            ];
+            const result = buildEntityInfosFromScenarios(scenarios, {}, entitiesWithMetadata);
+            expect(result[0].importedBy).toEqual({
+                'components/DrinkCard.tsx': {
+                    DrinkList: { shas: ['abc'] },
+                },
+            });
+        });
+        it('should handle entities without matching metadata (no importedBy)', () => {
+            const scenarios = [
+                {
+                    componentName: 'DrinkCard',
+                    componentPath: 'components/DrinkCard.tsx',
+                },
+            ];
+            const entitiesWithMetadata = [
+                { name: 'UnrelatedEntity', metadata: null },
+            ];
+            const result = buildEntityInfosFromScenarios(scenarios, {}, entitiesWithMetadata);
+            expect(result[0].importedBy).toBeUndefined();
+        });
+        it('should handle mixed component and page scenarios', () => {
+            const scenarios = [
+                {
+                    componentName: 'DrinkCard',
+                    componentPath: 'components/DrinkCard.tsx',
+                },
+                { componentName: null, componentPath: null, url: '/' },
+                { componentName: 'Header', componentPath: 'components/Header.tsx' },
+                { componentName: null, componentPath: null, url: '/drinks' },
+            ];
+            const pageFilePaths = {
+                Home: 'app/page.tsx',
+                Drinks: 'app/drinks/page.tsx',
+            };
+            const result = buildEntityInfosFromScenarios(scenarios, pageFilePaths, []);
+            expect(result.map((e) => e.name)).toEqual([
+                'DrinkCard',
+                'Home',
+                'Header',
+                'Drinks',
+            ]);
+        });
+        it('should skip scenarios with componentName but no componentPath', () => {
+            const scenarios = [
+                { componentName: 'DrinkCard', componentPath: null },
+            ];
+            const result = buildEntityInfosFromScenarios(scenarios, {}, []);
+            expect(result).toEqual([]);
+        });
+        it('should handle empty inputs', () => {
+            expect(buildEntityInfosFromScenarios([], {}, [])).toEqual([]);
+        });
+        it('should handle scenarios where url is undefined (not a page scenario)', () => {
+            // A scenario with no componentName and no url — should be skipped
+            const scenarios = [
+                { componentName: null, componentPath: null },
+            ];
+            const result = buildEntityInfosFromScenarios(scenarios, {}, []);
+            expect(result).toEqual([]);
+        });
+        it('should handle entity metadata with null metadata field', () => {
+            const scenarios = [
+                { componentName: 'Card', componentPath: 'components/Card.tsx' },
+            ];
+            const metadata = [
+                { name: 'Card', metadata: null },
+            ];
+            const result = buildEntityInfosFromScenarios(scenarios, {}, metadata);
+            expect(result[0].importedBy).toBeUndefined();
+        });
+    });
+    // ── buildReverseDependencyGraph ──────────────────────────────────────
+    describe('buildReverseDependencyGraph', () => {
+        it('should return empty map for empty entities', () => {
+            expect(buildReverseDependencyGraph([]).size).toBe(0);
+        });
+        it('should build reverse graph from a single importer', () => {
+            const result = buildReverseDependencyGraph([
+                entity('DrinkCard', 'components/DrinkCard.tsx', {
+                    'components/DrinkCard.tsx': ['DrinkList'],
+                }),
+            ]);
+            expect(result.get('DrinkCard')).toEqual(new Set(['DrinkList']));
+        });
+        it('should collect multiple importers across file paths', () => {
+            const result = buildReverseDependencyGraph([
+                entity('Button', 'components/Button.tsx', {
+                    'components/Button.tsx': ['LoginForm'],
+                    'lib/ui/Button.tsx': ['SignupForm'],
+                }),
+            ]);
+            expect(result.get('Button')).toEqual(new Set(['LoginForm', 'SignupForm']));
+        });
+        it('should deduplicate importers appearing under multiple file paths', () => {
+            const result = buildReverseDependencyGraph([
+                entity('Icon', 'components/Icon.tsx', {
+                    'components/Icon.tsx': ['Header'],
+                    'lib/Icon.tsx': ['Header'],
+                }),
+            ]);
+            expect(result.get('Icon')).toEqual(new Set(['Header']));
+        });
+        it('should skip entities with no importedBy metadata', () => {
+            const result = buildReverseDependencyGraph([
+                entity('Orphan', 'components/Orphan.tsx'),
+                entity('Used', 'components/Used.tsx', {
+                    'components/Used.tsx': ['Parent'],
+                }),
+            ]);
+            expect(result.has('Orphan')).toBe(false);
+            expect(result.get('Used')).toEqual(new Set(['Parent']));
+        });
+        it('should handle empty importedBy object gracefully', () => {
+            const entities = [
+                { name: 'Empty', filePath: 'components/Empty.tsx', importedBy: {} },
+            ];
+            const result = buildReverseDependencyGraph(entities);
+            expect(result.has('Empty')).toBe(false);
+        });
+        it('should handle multiple importers under a single file path', () => {
+            const result = buildReverseDependencyGraph([
+                entity('utils', 'lib/utils.ts', {
+                    'lib/utils.ts': ['DrinkCard', 'DrinkList', 'Header'],
+                }),
+            ]);
+            expect(result.get('utils')).toEqual(new Set(['DrinkCard', 'DrinkList', 'Header']));
+        });
+    });
+    // ── classifyDirectChanges ────────────────────────────────────────────
+    describe('classifyDirectChanges', () => {
+        it('should classify entities whose file paths match changed files', () => {
+            const changedFiles = new Map([
+                ['components/DrinkCard.tsx', 'edited'],
+                ['app/page.tsx', 'new'],
+            ]);
+            const entities = [
+                entity('DrinkCard', 'components/DrinkCard.tsx'),
+                entity('Home', 'app/page.tsx'),
+                entity('Header', 'components/Header.tsx'),
+            ];
+            const result = classifyDirectChanges(changedFiles, entities);
+            expect(result.get('DrinkCard')).toBe('edited');
+            expect(result.get('Home')).toBe('new');
+            expect(result.has('Header')).toBe(false);
+        });
+        it('should return empty map when no files match', () => {
+            const changedFiles = new Map([
+                ['unrelated/file.ts', 'edited'],
+            ]);
+            const result = classifyDirectChanges(changedFiles, [
+                entity('DrinkCard', 'components/DrinkCard.tsx'),
+            ]);
+            expect(result.size).toBe(0);
+        });
+        it('should return empty map for empty inputs', () => {
+            expect(classifyDirectChanges(new Map(), [])).toEqual(new Map());
+        });
+        it('should match file paths exactly (no normalization)', () => {
+            const changedFiles = new Map([
+                ['components/DrinkCard.tsx', 'edited'],
+            ]);
+            // Slightly different path should NOT match
+            const result = classifyDirectChanges(changedFiles, [
+                entity('DrinkCard', './components/DrinkCard.tsx'),
+            ]);
+            expect(result.size).toBe(0);
+        });
+    });
+    // ── computeEntityChangeStatus ────────────────────────────────────────
+    describe('computeEntityChangeStatus', () => {
+        // ── Basic classification ───────────────────────────────────────────
+        it('should mark entity as "new" when its file is added', () => {
+            const result = computeEntityChangeStatus(new Map([['components/DrinkCard.tsx', 'new']]), [entity('DrinkCard', 'components/DrinkCard.tsx')]);
+            expect(result['DrinkCard']).toEqual({ status: 'new' });
+        });
+        it('should mark entity as "edited" when its file is modified', () => {
+            const result = computeEntityChangeStatus(new Map([['components/DrinkCard.tsx', 'edited']]), [entity('DrinkCard', 'components/DrinkCard.tsx')]);
+            expect(result['DrinkCard']).toEqual({ status: 'edited' });
+        });
+        it('should omit unchanged entities with no impacted deps', () => {
+            const result = computeEntityChangeStatus(new Map([['components/DrinkCard.tsx', 'edited']]), [
+                entity('DrinkCard', 'components/DrinkCard.tsx'),
+                entity('Header', 'components/Header.tsx'),
+            ]);
+            expect(result['DrinkCard']).toBeDefined();
+            expect(result['Header']).toBeUndefined();
+        });
+        it('should return empty map for empty inputs', () => {
+            expect(computeEntityChangeStatus(new Map(), [])).toEqual({});
+        });
+        it('should return empty map when changedFiles has entries but no entity matches', () => {
+            const result = computeEntityChangeStatus(new Map([['unrelated/file.ts', 'edited']]), [entity('DrinkCard', 'components/DrinkCard.tsx')]);
+            expect(result).toEqual({});
+        });
+        // ── Single-level impact ────────────────────────────────────────────
+        it('should mark single-level impact: A imports B, B edited → A impacted by B', () => {
+            const result = computeEntityChangeStatus(new Map([['components/DrinkCard.tsx', 'edited']]), [
+                entity('DrinkCard', 'components/DrinkCard.tsx', {
+                    'components/DrinkCard.tsx': ['DrinkList'],
+                }),
+                entity('DrinkList', 'components/DrinkList.tsx'),
+            ]);
+            expect(result['DrinkCard']).toEqual({ status: 'edited' });
+            expect(result['DrinkList']).toEqual({
+                status: 'impacted',
+                impactedBy: [
+                    {
+                        name: 'DrinkCard',
+                        filePath: 'components/DrinkCard.tsx',
+                        changeType: 'edited',
+                    },
+                ],
+            });
+        });
+        it('should preserve changeType correctly: "new" root cause shows as "new" in impactedBy', () => {
+            const result = computeEntityChangeStatus(new Map([['components/DrinkCard.tsx', 'new']]), [
+                entity('DrinkCard', 'components/DrinkCard.tsx', {
+                    'components/DrinkCard.tsx': ['DrinkList'],
+                }),
+                entity('DrinkList', 'components/DrinkList.tsx'),
+            ]);
+            expect(result['DrinkList']?.impactedBy?.[0]?.changeType).toBe('new');
+        });
+        // ── Multi-level transitive ─────────────────────────────────────────
+        it('should trace multi-level transitive: Icon→DrinkCard→DrinkList, Icon edited → all impacted by Icon', () => {
+            const result = computeEntityChangeStatus(new Map([['components/Icon.tsx', 'edited']]), [
+                entity('Icon', 'components/Icon.tsx', {
+                    'components/Icon.tsx': ['DrinkCard'],
+                }),
+                entity('DrinkCard', 'components/DrinkCard.tsx', {
+                    'components/DrinkCard.tsx': ['DrinkList'],
+                }),
+                entity('DrinkList', 'components/DrinkList.tsx'),
+            ]);
+            expect(result['Icon']).toEqual({ status: 'edited' });
+            // Both should trace back to Icon as root cause (not intermediate DrinkCard)
+            expect(result['DrinkCard']?.impactedBy).toEqual([
+                { name: 'Icon', filePath: 'components/Icon.tsx', changeType: 'edited' },
+            ]);
+            expect(result['DrinkList']?.impactedBy).toEqual([
+                { name: 'Icon', filePath: 'components/Icon.tsx', changeType: 'edited' },
+            ]);
+        });
+        // ── Multiple root causes ───────────────────────────────────────────
+        it('should track multiple root causes: DrinkCard imports Icon and utils (both changed)', () => {
+            const result = computeEntityChangeStatus(new Map([
+                ['components/Icon.tsx', 'edited'],
+                ['lib/utils.ts', 'new'],
+            ]), [
+                entity('Icon', 'components/Icon.tsx', {
+                    'components/Icon.tsx': ['DrinkCard'],
+                }),
+                entity('utils', 'lib/utils.ts', {
+                    'lib/utils.ts': ['DrinkCard'],
+                }),
+                entity('DrinkCard', 'components/DrinkCard.tsx'),
+            ]);
+            expect(result['DrinkCard']?.status).toBe('impacted');
+            expect(impactNames(result, 'DrinkCard')).toEqual(['Icon', 'utils']);
+            // Verify changeTypes are preserved
+            const iconDep = result['DrinkCard']?.impactedBy?.find((d) => d.name === 'Icon');
+            const utilsDep = result['DrinkCard']?.impactedBy?.find((d) => d.name === 'utils');
+            expect(iconDep?.changeType).toBe('edited');
+            expect(utilsDep?.changeType).toBe('new');
+        });
+        // ── Diamond dependency (BFS root cause propagation) ────────────────
+        it('should propagate ALL root causes through diamond: D1→A→C→E, D2→B→C→E', () => {
+            // This tests that when two paths converge at C and C has downstream
+            // importers (E), ALL root causes propagate through — not just the
+            // ones from whichever path was processed first.
+            //
+            //  D1(edited) ──importedBy──→ A ──importedBy──→ C ──importedBy──→ E
+            //  D2(new)    ──importedBy──→ B ──importedBy──→ C
+            //
+            const result = computeEntityChangeStatus(new Map([
+                ['components/D1.tsx', 'edited'],
+                ['components/D2.tsx', 'new'],
+            ]), [
+                entity('D1', 'components/D1.tsx', {
+                    'components/D1.tsx': ['A'],
+                }),
+                entity('D2', 'components/D2.tsx', {
+                    'components/D2.tsx': ['B'],
+                }),
+                entity('A', 'components/A.tsx', {
+                    'components/A.tsx': ['C'],
+                }),
+                entity('B', 'components/B.tsx', {
+                    'components/B.tsx': ['C'],
+                }),
+                entity('C', 'components/C.tsx', {
+                    'components/C.tsx': ['E'],
+                }),
+                entity('E', 'components/E.tsx'),
+            ]);
+            // C should have both root causes
+            expect(result['C']?.status).toBe('impacted');
+            expect(impactNames(result, 'C')).toEqual(['D1', 'D2']);
+            // E (downstream of C) must also have both root causes
+            expect(result['E']?.status).toBe('impacted');
+            expect(impactNames(result, 'E')).toEqual(['D1', 'D2']);
+        });
+        it('should propagate root causes through diamond with unequal path lengths', () => {
+            // D1 reaches C directly (depth 1), D2 reaches C via B (depth 2).
+            // C has downstream E. E must get both root causes.
+            //
+            //  D1(edited) ──importedBy──→ C ──importedBy──→ E
+            //  D2(new)    ──importedBy──→ B ──importedBy──→ C
+            //
+            const result = computeEntityChangeStatus(new Map([
+                ['components/D1.tsx', 'edited'],
+                ['components/D2.tsx', 'new'],
+            ]), [
+                entity('D1', 'components/D1.tsx', {
+                    'components/D1.tsx': ['C'],
+                }),
+                entity('D2', 'components/D2.tsx', {
+                    'components/D2.tsx': ['B'],
+                }),
+                entity('B', 'components/B.tsx', {
+                    'components/B.tsx': ['C'],
+                }),
+                entity('C', 'components/C.tsx', {
+                    'components/C.tsx': ['E'],
+                }),
+                entity('E', 'components/E.tsx'),
+            ]);
+            expect(impactNames(result, 'C')).toEqual(['D1', 'D2']);
+            expect(impactNames(result, 'E')).toEqual(['D1', 'D2']);
+        });
+        // ── Cycles ─────────────────────────────────────────────────────────
+        it('should handle simple cycle without infinite loop: A↔B, A edited', () => {
+            const result = computeEntityChangeStatus(new Map([['components/A.tsx', 'edited']]), [
+                entity('A', 'components/A.tsx', {
+                    'components/A.tsx': ['B'],
+                }),
+                entity('B', 'components/B.tsx', {
+                    'components/B.tsx': ['A'],
+                }),
+            ]);
+            expect(result['A']).toEqual({ status: 'edited' });
+            expect(result['B']).toEqual({
+                status: 'impacted',
+                impactedBy: [
+                    { name: 'A', filePath: 'components/A.tsx', changeType: 'edited' },
+                ],
+            });
+        });
+        it('should handle three-node cycle: A→B→C→A, A edited', () => {
+            const result = computeEntityChangeStatus(new Map([['components/A.tsx', 'edited']]), [
+                entity('A', 'components/A.tsx', {
+                    'components/A.tsx': ['B'],
+                }),
+                entity('B', 'components/B.tsx', {
+                    'components/B.tsx': ['C'],
+                }),
+                entity('C', 'components/C.tsx', {
+                    'components/C.tsx': ['A'],
+                }),
+            ]);
+            expect(result['A']).toEqual({ status: 'edited' });
+            expect(result['B']?.status).toBe('impacted');
+            expect(result['C']?.status).toBe('impacted');
+            expect(impactNames(result, 'B')).toEqual(['A']);
+            expect(impactNames(result, 'C')).toEqual(['A']);
+        });
+        it('should handle cycle with multiple seeds: A→B→C→A, A and C both edited', () => {
+            const result = computeEntityChangeStatus(new Map([
+                ['components/A.tsx', 'edited'],
+                ['components/C.tsx', 'new'],
+            ]), [
+                entity('A', 'components/A.tsx', {
+                    'components/A.tsx': ['B'],
+                }),
+                entity('B', 'components/B.tsx', {
+                    'components/B.tsx': ['C'],
+                }),
+                entity('C', 'components/C.tsx', {
+                    'components/C.tsx': ['A'],
+                }),
+            ]);
+            // A and C directly changed
+            expect(result['A']).toEqual({ status: 'edited' });
+            expect(result['C']).toEqual({ status: 'new' });
+            // B is impacted by both (A importedBy B via A→B, C importedBy B via C→...→B)
+            expect(result['B']?.status).toBe('impacted');
+            expect(impactNames(result, 'B')).toEqual(['A', 'C']);
+        });
+        it('should handle self-import cycle gracefully', () => {
+            // Entity lists itself as its own importer
+            const result = computeEntityChangeStatus(new Map([['components/A.tsx', 'edited']]), [
+                entity('A', 'components/A.tsx', {
+                    'components/A.tsx': ['A'],
+                }),
+            ]);
+            // A is directly changed — self-loop should not create an impacted entry
+            expect(result['A']).toEqual({ status: 'edited' });
+        });
+        // ── Direct change priority ─────────────────────────────────────────
+        it('should NOT mark directly-changed entities as impacted even if they import other changed entities', () => {
+            const result = computeEntityChangeStatus(new Map([
+                ['components/A.tsx', 'edited'],
+                ['components/B.tsx', 'new'],
+            ]), [
+                entity('A', 'components/A.tsx', {
+                    'components/A.tsx': ['B'],
+                }),
+                entity('B', 'components/B.tsx'),
+            ]);
+            expect(result['A']).toEqual({ status: 'edited' });
+            expect(result['B']).toEqual({ status: 'new' });
+        });
+        it('should not produce impacted entries when ALL entities are directly changed', () => {
+            const result = computeEntityChangeStatus(new Map([
+                ['components/A.tsx', 'edited'],
+                ['components/B.tsx', 'new'],
+                ['components/C.tsx', 'edited'],
+            ]), [
+                entity('A', 'components/A.tsx', {
+                    'components/A.tsx': ['B'],
+                }),
+                entity('B', 'components/B.tsx', {
+                    'components/B.tsx': ['C'],
+                }),
+                entity('C', 'components/C.tsx'),
+            ]);
+            expect(Object.values(result).every((s) => s.status !== 'impacted')).toBe(true);
+            expect(result['A']?.status).toBe('edited');
+            expect(result['B']?.status).toBe('new');
+            expect(result['C']?.status).toBe('edited');
+        });
+        // ── Missing metadata / graceful degradation ────────────────────────
+        it('should handle missing importedBy metadata gracefully (no impact propagation)', () => {
+            const result = computeEntityChangeStatus(new Map([['components/DrinkCard.tsx', 'edited']]), [
+                entity('DrinkCard', 'components/DrinkCard.tsx'),
+                entity('DrinkList', 'components/DrinkList.tsx'),
+            ]);
+            expect(result['DrinkCard']).toEqual({ status: 'edited' });
+            expect(result['DrinkList']).toBeUndefined();
+        });
+        it('should skip phantom importers (importedBy references entity not in entities list)', () => {
+            // DrinkCard's importedBy references "PhantomPage" which is not in entities
+            const result = computeEntityChangeStatus(new Map([['components/DrinkCard.tsx', 'edited']]), [
+                entity('DrinkCard', 'components/DrinkCard.tsx', {
+                    'components/DrinkCard.tsx': ['PhantomPage', 'DrinkList'],
+                }),
+                entity('DrinkList', 'components/DrinkList.tsx'),
+            ]);
+            // PhantomPage should not appear in results (not in entities list)
+            expect(result['PhantomPage']).toBeUndefined();
+            // DrinkList should still be impacted
+            expect(result['DrinkList']?.status).toBe('impacted');
+        });
+        // ── maxDepth ───────────────────────────────────────────────────────
+        it('should enforce maxDepth and stop propagation beyond limit', () => {
+            // Chain: D → C → B → A
+            const result = computeEntityChangeStatus(new Map([['components/D.tsx', 'edited']]), [
+                entity('D', 'components/D.tsx', { 'components/D.tsx': ['C'] }),
+                entity('C', 'components/C.tsx', { 'components/C.tsx': ['B'] }),
+                entity('B', 'components/B.tsx', { 'components/B.tsx': ['A'] }),
+                entity('A', 'components/A.tsx'),
+            ], 2);
+            expect(result['D']).toEqual({ status: 'edited' });
+            expect(result['C']?.status).toBe('impacted');
+            expect(result['B']?.status).toBe('impacted');
+            // A at depth 3 is cut off
+            expect(result['A']).toBeUndefined();
+        });
+        it('should use default maxDepth of 20 when not specified', () => {
+            // Build a chain of depth 15 — should all be reached with default maxDepth
+            const entities = [];
+            for (let i = 0; i < 16; i++) {
+                const name = `E${i}`;
+                const filePath = `components/${name}.tsx`;
+                if (i < 15) {
+                    entities.push(entity(name, filePath, { [filePath]: [`E${i + 1}`] }));
+                }
+                else {
+                    entities.push(entity(name, filePath));
+                }
+            }
+            const result = computeEntityChangeStatus(new Map([['components/E0.tsx', 'edited']]), entities);
+            // E15 at depth 15 should still be reached (within default maxDepth of 20)
+            expect(result['E15']?.status).toBe('impacted');
+        });
+        // ── Fan-out ────────────────────────────────────────────────────────
+        it('should handle large fan-out: one changed entity imported by many', () => {
+            const importers = Array.from({ length: 10 }, (_, i) => `Comp${i}`);
+            const entities = [
+                entity('SharedUtil', 'lib/shared.ts', {
+                    'lib/shared.ts': importers,
+                }),
+                ...importers.map((name) => entity(name, `components/${name}.tsx`)),
+            ];
+            const result = computeEntityChangeStatus(new Map([['lib/shared.ts', 'edited']]), entities);
+            expect(result['SharedUtil']).toEqual({ status: 'edited' });
+            for (const name of importers) {
+                expect(result[name]?.status).toBe('impacted');
+                expect(result[name]?.impactedBy).toEqual([
+                    {
+                        name: 'SharedUtil',
+                        filePath: 'lib/shared.ts',
+                        changeType: 'edited',
+                    },
+                ]);
+            }
+        });
+        // ── Deterministic output ───────────────────────────────────────────
+        it('should sort impactedBy array by name for deterministic output', () => {
+            const result = computeEntityChangeStatus(new Map([
+                ['components/Zebra.tsx', 'edited'],
+                ['components/Apple.tsx', 'new'],
+                ['components/Mango.tsx', 'edited'],
+            ]), [
+                entity('Zebra', 'components/Zebra.tsx', {
+                    'components/Zebra.tsx': ['Target'],
+                }),
+                entity('Apple', 'components/Apple.tsx', {
+                    'components/Apple.tsx': ['Target'],
+                }),
+                entity('Mango', 'components/Mango.tsx', {
+                    'components/Mango.tsx': ['Target'],
+                }),
+                entity('Target', 'components/Target.tsx'),
+            ]);
+            expect(impactNames(result, 'Target')).toEqual([
+                'Apple',
+                'Mango',
+                'Zebra',
+            ]);
+        });
+        // ── Realistic integration-style scenarios ──────────────────────────
+        it('should compute correct status for a realistic Next.js app scenario', () => {
+            // Simulates a real editor session:
+            //   - User edited DrinkCard component and added a new formatPrice utility
+            //   - DrinkCard is imported by DrinkList component and Home page
+            //   - formatPrice is imported by DrinkCard
+            //   - Header is unchanged and imports nothing changed
+            //
+            // Expected:
+            //   - DrinkCard: edited (directly changed)
+            //   - formatPrice: new (directly changed)
+            //   - DrinkList: impacted by [DrinkCard, formatPrice] (DrinkCard is edited,
+            //     and formatPrice flows through DrinkCard)
+            //   - Home: impacted by [DrinkCard, formatPrice] (same reasoning)
+            //   - Header: not in results (unchanged, no changed deps)
+            const result = computeEntityChangeStatus(new Map([
+                ['components/DrinkCard.tsx', 'edited'],
+                ['lib/formatPrice.ts', 'new'],
+            ]), [
+                entity('formatPrice', 'lib/formatPrice.ts', {
+                    'lib/formatPrice.ts': ['DrinkCard'],
+                }),
+                entity('DrinkCard', 'components/DrinkCard.tsx', {
+                    'components/DrinkCard.tsx': ['DrinkList', 'Home'],
+                }),
+                entity('DrinkList', 'components/DrinkList.tsx'),
+                entity('Home', 'app/page.tsx'),
+                entity('Header', 'components/Header.tsx'),
+            ]);
+            expect(result['formatPrice']).toEqual({ status: 'new' });
+            expect(result['DrinkCard']).toEqual({ status: 'edited' });
+            expect(result['Header']).toBeUndefined();
+            // DrinkList and Home are impacted by DrinkCard (directly, its an importer)
+            // AND by formatPrice (transitively via DrinkCard)
+            expect(result['DrinkList']?.status).toBe('impacted');
+            expect(impactNames(result, 'DrinkList')).toEqual([
+                'DrinkCard',
+                'formatPrice',
+            ]);
+            expect(result['Home']?.status).toBe('impacted');
+            expect(impactNames(result, 'Home')).toEqual(['DrinkCard', 'formatPrice']);
+        });
+        it('should handle a realistic scenario where component is both directly changed AND an intermediate', () => {
+            // DrinkCard is edited AND it imports formatPrice (also changed).
+            // DrinkCard should be marked 'edited' (direct), not 'impacted'.
+            // DrinkList imports DrinkCard → impacted by both DrinkCard and formatPrice.
+            const result = computeEntityChangeStatus(new Map([
+                ['components/DrinkCard.tsx', 'edited'],
+                ['lib/formatPrice.ts', 'new'],
+            ]), [
+                entity('formatPrice', 'lib/formatPrice.ts', {
+                    'lib/formatPrice.ts': ['DrinkCard'],
+                }),
+                entity('DrinkCard', 'components/DrinkCard.tsx', {
+                    'components/DrinkCard.tsx': ['DrinkList'],
+                }),
+                entity('DrinkList', 'components/DrinkList.tsx'),
+            ]);
+            // DrinkCard is directly changed — status should be 'edited', no impactedBy
+            expect(result['DrinkCard']).toEqual({ status: 'edited' });
+            // DrinkList is impacted by BOTH root causes
+            expect(result['DrinkList']?.status).toBe('impacted');
+            expect(impactNames(result, 'DrinkList')).toEqual([
+                'DrinkCard',
+                'formatPrice',
+            ]);
+        });
+        // ── End-to-end pipeline test ───────────────────────────────────────
+        it('should produce correct results through the full pipeline: git files → scenarios → entity infos → status', () => {
+            // This tests the complete data flow that both route handlers execute:
+            // 1. buildChangedFilesMap from git status
+            // 2. buildEntityInfosFromScenarios from scenario data + metadata
+            // 3. computeEntityChangeStatus from the above
+            // Step 1: Git status
+            const gitFiles = [
+                { path: 'components/DrinkCard.tsx', status: 'modified' },
+                { path: 'lib/formatPrice.ts', status: 'added' },
+                { path: 'components/Header.tsx', status: 'deleted' },
+            ];
+            const changedFiles = buildChangedFilesMap(gitFiles, false);
+            expect(changedFiles.get('components/DrinkCard.tsx')).toBe('edited');
+            expect(changedFiles.get('lib/formatPrice.ts')).toBe('new');
+            expect(changedFiles.has('components/Header.tsx')).toBe(false);
+            // Step 2: Build entity infos from scenarios
+            const scenarios = [
+                {
+                    componentName: 'DrinkCard',
+                    componentPath: 'components/DrinkCard.tsx',
+                },
+                { componentName: null, componentPath: null, url: '/' },
+                {
+                    componentName: 'DrinkList',
+                    componentPath: 'components/DrinkList.tsx',
+                },
+            ];
+            const pageFilePaths = { Home: 'app/page.tsx' };
+            const metadata = [
+                {
+                    name: 'DrinkCard',
+                    metadata: {
+                        importedBy: {
+                            'components/DrinkCard.tsx': {
+                                DrinkList: { shas: ['sha1'] },
+                                Home: { shas: ['sha2'] },
+                            },
+                        },
+                    },
+                },
+                { name: 'DrinkList', metadata: null },
+            ];
+            const entityInfos = buildEntityInfosFromScenarios(scenarios, pageFilePaths, metadata);
+            expect(entityInfos).toHaveLength(3);
+            expect(entityInfos.find((e) => e.name === 'DrinkCard')?.importedBy).toBeDefined();
+            // Step 3: Compute status
+            const result = computeEntityChangeStatus(changedFiles, entityInfos);
+            expect(result['DrinkCard']).toEqual({ status: 'edited' });
+            expect(result['DrinkList']?.status).toBe('impacted');
+            expect(result['Home']?.status).toBe('impacted');
+            expect(impactNames(result, 'DrinkList')).toEqual(['DrinkCard']);
+            expect(impactNames(result, 'Home')).toEqual(['DrinkCard']);
+        });
+        it('should produce correct results for first-feature pipeline (all files new)', () => {
+            const gitFiles = [
+                { path: 'components/DrinkCard.tsx', status: 'modified' },
+                { path: 'app/page.tsx', status: 'modified' },
+                { path: 'components/Header.tsx', status: 'untracked' },
+            ];
+            // isFirstFeature = true → all become 'new'
+            const changedFiles = buildChangedFilesMap(gitFiles, true);
+            expect(changedFiles.get('components/DrinkCard.tsx')).toBe('new');
+            expect(changedFiles.get('app/page.tsx')).toBe('new');
+            expect(changedFiles.get('components/Header.tsx')).toBe('new');
+            const scenarios = [
+                {
+                    componentName: 'DrinkCard',
+                    componentPath: 'components/DrinkCard.tsx',
+                },
+                { componentName: null, componentPath: null, url: '/' },
+                { componentName: 'Header', componentPath: 'components/Header.tsx' },
+            ];
+            const entityInfos = buildEntityInfosFromScenarios(scenarios, { Home: 'app/page.tsx' }, []);
+            const result = computeEntityChangeStatus(changedFiles, entityInfos);
+            // All should be 'new' — none impacted
+            expect(result['DrinkCard']).toEqual({ status: 'new' });
+            expect(result['Home']).toEqual({ status: 'new' });
+            expect(result['Header']).toEqual({ status: 'new' });
+            expect(Object.values(result).some((s) => s.status === 'impacted')).toBe(false);
+        });
+        // ── Pass-through propagation ─────────────────────────────────────
+        it('should propagate root causes THROUGH a directly-changed intermediate entity', () => {
+            // D is edited, A is also edited, A importedBy B.
+            // D importedBy A (so D flows through A).
+            // B should be impacted by BOTH D (transitive through A) and A (direct importer).
+            //
+            //  D(edited) ──importedBy──→ A(edited) ──importedBy──→ B
+            //
+            const result = computeEntityChangeStatus(new Map([
+                ['components/D.tsx', 'edited'],
+                ['components/A.tsx', 'edited'],
+            ]), [
+                entity('D', 'components/D.tsx', {
+                    'components/D.tsx': ['A'],
+                }),
+                entity('A', 'components/A.tsx', {
+                    'components/A.tsx': ['B'],
+                }),
+                entity('B', 'components/B.tsx'),
+            ]);
+            expect(result['D']).toEqual({ status: 'edited' });
+            expect(result['A']).toEqual({ status: 'edited' });
+            // B must see BOTH root causes — D propagated through A
+            expect(result['B']?.status).toBe('impacted');
+            expect(impactNames(result, 'B')).toEqual(['A', 'D']);
+        });
+        it('should propagate through a chain of directly-changed entities: D→C→B→A all changed except A', () => {
+            // D, C, B all directly changed. A imports B.
+            // A should see D, C, B as root causes.
+            const result = computeEntityChangeStatus(new Map([
+                ['components/D.tsx', 'edited'],
+                ['components/C.tsx', 'new'],
+                ['components/B.tsx', 'edited'],
+            ]), [
+                entity('D', 'components/D.tsx', { 'components/D.tsx': ['C'] }),
+                entity('C', 'components/C.tsx', { 'components/C.tsx': ['B'] }),
+                entity('B', 'components/B.tsx', { 'components/B.tsx': ['A'] }),
+                entity('A', 'components/A.tsx'),
+            ]);
+            expect(result['A']?.status).toBe('impacted');
+            expect(impactNames(result, 'A')).toEqual(['B', 'C', 'D']);
+        });
+        // ── Wide diamond ─────────────────────────────────────────────────
+        it('should handle wide diamond: 3+ paths converging then fanning out', () => {
+            // D1, D2, D3 all edited, all importedBy Merge, Merge importedBy [Out1, Out2]
+            //
+            //  D1 ─┐
+            //  D2 ─┼──importedBy──→ Merge ──importedBy──→ Out1
+            //  D3 ─┘                       └──importedBy──→ Out2
+            //
+            const result = computeEntityChangeStatus(new Map([
+                ['components/D1.tsx', 'edited'],
+                ['components/D2.tsx', 'new'],
+                ['components/D3.tsx', 'edited'],
+            ]), [
+                entity('D1', 'components/D1.tsx', { 'components/D1.tsx': ['Merge'] }),
+                entity('D2', 'components/D2.tsx', { 'components/D2.tsx': ['Merge'] }),
+                entity('D3', 'components/D3.tsx', { 'components/D3.tsx': ['Merge'] }),
+                entity('Merge', 'components/Merge.tsx', {
+                    'components/Merge.tsx': ['Out1', 'Out2'],
+                }),
+                entity('Out1', 'components/Out1.tsx'),
+                entity('Out2', 'components/Out2.tsx'),
+            ]);
+            // Merge gets all 3 root causes
+            expect(impactNames(result, 'Merge')).toEqual(['D1', 'D2', 'D3']);
+            // Out1 and Out2 also get all 3 root causes (propagated through Merge)
+            expect(impactNames(result, 'Out1')).toEqual(['D1', 'D2', 'D3']);
+            expect(impactNames(result, 'Out2')).toEqual(['D1', 'D2', 'D3']);
+        });
+        // ── changedFiles with non-entity entries ─────────────────────────
+        it('should ignore changedFiles entries that do not match any entity file path', () => {
+            // Git shows many changed files, but only some are entities
+            const result = computeEntityChangeStatus(new Map([
+                ['components/DrinkCard.tsx', 'edited'],
+                ['package.json', 'edited'],
+                ['README.md', 'new'],
+                ['.env', 'edited'],
+                ['tsconfig.json', 'edited'],
+            ]), [
+                entity('DrinkCard', 'components/DrinkCard.tsx', {
+                    'components/DrinkCard.tsx': ['DrinkList'],
+                }),
+                entity('DrinkList', 'components/DrinkList.tsx'),
+            ]);
+            expect(result['DrinkCard']).toEqual({ status: 'edited' });
+            expect(result['DrinkList']?.status).toBe('impacted');
+            // Only entities should appear in results
+            expect(Object.keys(result)).toEqual(['DrinkCard', 'DrinkList']);
+        });
+    });
+    // ── buildEntityInfosFromScenarios — additional edge cases ────────
+    describe('buildEntityInfosFromScenarios (edge cases)', () => {
+        it('should deduplicate page scenarios with different URLs resolving to same name', () => {
+            // /drinks and /drinks/123 both resolve to "Drinks"
+            const scenarios = [
+                { componentName: null, componentPath: null, url: '/drinks' },
+                { componentName: null, componentPath: null, url: '/drinks/123' },
+                {
+                    componentName: null,
+                    componentPath: null,
+                    url: '/drinks/456?tab=reviews',
+                },
+            ];
+            const pageFilePaths = { Drinks: 'app/drinks/page.tsx' };
+            const result = buildEntityInfosFromScenarios(scenarios, pageFilePaths, []);
+            // Should deduplicate to a single "Drinks" entity
+            expect(result).toHaveLength(1);
+            expect(result[0]).toEqual({
+                name: 'Drinks',
+                filePath: 'app/drinks/page.tsx',
+            });
+        });
+        it('should handle component and page scenario with same conceptual name (component wins)', () => {
+            // A component named "Home" AND a page URL "/" both produce name "Home"
+            // Component scenario comes first — it should win
+            const scenarios = [
+                { componentName: 'Home', componentPath: 'components/Home.tsx' },
+                { componentName: null, componentPath: null, url: '/' },
+            ];
+            const pageFilePaths = { Home: 'app/page.tsx' };
+            const result = buildEntityInfosFromScenarios(scenarios, pageFilePaths, []);
+            expect(result).toHaveLength(1);
+            // Component path should win (first occurrence)
+            expect(result[0].filePath).toBe('components/Home.tsx');
+        });
+        it('should handle multiple scenarios for the same component (only first is included)', () => {
+            const scenarios = [
+                {
+                    componentName: 'DrinkCard',
+                    componentPath: 'components/DrinkCard.tsx',
+                },
+                {
+                    componentName: 'DrinkCard',
+                    componentPath: 'components/DrinkCard.tsx',
+                },
+                {
+                    componentName: 'DrinkCard',
+                    componentPath: 'components/DrinkCard.tsx',
+                },
+            ];
+            const metadata = [
+                {
+                    name: 'DrinkCard',
+                    metadata: {
+                        importedBy: {
+                            'components/DrinkCard.tsx': { DrinkList: { shas: ['abc'] } },
+                        },
+                    },
+                },
+            ];
+            const result = buildEntityInfosFromScenarios(scenarios, {}, metadata);
+            expect(result).toHaveLength(1);
+            expect(result[0].importedBy).toBeDefined();
+        });
+    });
+    // ── Full pipeline regression tests ───────────────────────────────
+    describe('full pipeline regression tests', () => {
+        it('regression: entity with changed file AND imported by other unchanged entities should propagate', () => {
+            // This catches the old regex-based bug: previously, "impacted" was marked
+            // for every entity not directly changed, even if no dependency was actually changed.
+            // With the new system, only entities that transitively import a changed entity get impacted.
+            const gitFiles = [
+                { path: 'lib/formatPrice.ts', status: 'added' },
+            ];
+            const changedFiles = buildChangedFilesMap(gitFiles, false);
+            const scenarios = [
+                {
+                    componentName: 'DrinkCard',
+                    componentPath: 'components/DrinkCard.tsx',
+                },
+                { componentName: 'Header', componentPath: 'components/Header.tsx' },
+                { componentName: null, componentPath: null, url: '/' },
+            ];
+            const pageFilePaths = { Home: 'app/page.tsx' };
+            const metadata = [
+                {
+                    name: 'formatPrice',
+                    metadata: {
+                        importedBy: {
+                            'lib/formatPrice.ts': { DrinkCard: { shas: ['sha1'] } },
+                        },
+                    },
+                },
+                {
+                    name: 'DrinkCard',
+                    metadata: {
+                        importedBy: {
+                            'components/DrinkCard.tsx': { Home: { shas: ['sha2'] } },
+                        },
+                    },
+                },
+            ];
+            // formatPrice is not a scenario entity — only DrinkCard, Header, Home are.
+            // But formatPrice IS in the metadata as importedBy DrinkCard.
+            // We need to include formatPrice in entityInfos for the graph to work.
+            // However, buildEntityInfosFromScenarios only builds from scenarios,
+            // so formatPrice won't be in the entities list → DrinkCard won't be impacted.
+            //
+            // This test documents the current behavior: only entities from scenarios
+            // participate in the change status graph. Changed files that aren't entities
+            // don't propagate impact (they'd need to be in the entities list).
+            const entityInfos = buildEntityInfosFromScenarios(scenarios, pageFilePaths, metadata);
+            const result = computeEntityChangeStatus(changedFiles, entityInfos);
+            // formatPrice is not in scenarios, so not in entityInfos
+            expect(entityInfos.find((e) => e.name === 'formatPrice')).toBeUndefined();
+            // No entity files match changed files → empty result
+            // DrinkCard and Home are NOT impacted because formatPrice is not in entities
+            expect(result['DrinkCard']).toBeUndefined();
+            expect(result['Header']).toBeUndefined();
+            expect(result['Home']).toBeUndefined();
+        });
+        it('pipeline: changed utility file that IS an entity propagates impact correctly', () => {
+            // When the changed utility IS registered as a scenario entity,
+            // the full chain works end-to-end.
+            const gitFiles = [
+                { path: 'lib/formatPrice.ts', status: 'added' },
+            ];
+            const changedFiles = buildChangedFilesMap(gitFiles, false);
+            const scenarios = [
+                { componentName: 'formatPrice', componentPath: 'lib/formatPrice.ts' },
+                {
+                    componentName: 'DrinkCard',
+                    componentPath: 'components/DrinkCard.tsx',
+                },
+                { componentName: null, componentPath: null, url: '/' },
+            ];
+            const pageFilePaths = { Home: 'app/page.tsx' };
+            const metadata = [
+                {
+                    name: 'formatPrice',
+                    metadata: {
+                        importedBy: {
+                            'lib/formatPrice.ts': { DrinkCard: { shas: ['sha1'] } },
+                        },
+                    },
+                },
+                {
+                    name: 'DrinkCard',
+                    metadata: {
+                        importedBy: {
+                            'components/DrinkCard.tsx': { Home: { shas: ['sha2'] } },
+                        },
+                    },
+                },
+            ];
+            const entityInfos = buildEntityInfosFromScenarios(scenarios, pageFilePaths, metadata);
+            const result = computeEntityChangeStatus(changedFiles, entityInfos);
+            expect(result['formatPrice']).toEqual({ status: 'new' });
+            expect(result['DrinkCard']?.status).toBe('impacted');
+            expect(impactNames(result, 'DrinkCard')).toEqual(['formatPrice']);
+            expect(result['Home']?.status).toBe('impacted');
+            expect(impactNames(result, 'Home')).toEqual(['formatPrice']);
+        });
+        it('pipeline: renamed file status is correctly ignored', () => {
+            const gitFiles = [
+                { path: 'components/OldName.tsx', status: 'renamed' },
+                { path: 'components/DrinkCard.tsx', status: 'modified' },
+            ];
+            const changedFiles = buildChangedFilesMap(gitFiles, false);
+            // Renamed file should not appear
+            expect(changedFiles.has('components/OldName.tsx')).toBe(false);
+            expect(changedFiles.get('components/DrinkCard.tsx')).toBe('edited');
+        });
+        it('pipeline: first feature mode with import graph still marks everything new', () => {
+            // Even with importedBy metadata, first-feature mode should mark
+            // all entities as 'new' with no 'impacted' entries.
+            const gitFiles = [
+                { path: 'components/DrinkCard.tsx', status: 'modified' },
+                { path: 'app/page.tsx', status: 'modified' },
+            ];
+            const changedFiles = buildChangedFilesMap(gitFiles, true); // first feature!
+            const scenarios = [
+                {
+                    componentName: 'DrinkCard',
+                    componentPath: 'components/DrinkCard.tsx',
+                },
+                { componentName: null, componentPath: null, url: '/' },
+            ];
+            const metadata = [
+                {
+                    name: 'DrinkCard',
+                    metadata: {
+                        importedBy: {
+                            'components/DrinkCard.tsx': { Home: { shas: ['sha1'] } },
+                        },
+                    },
+                },
+            ];
+            const entityInfos = buildEntityInfosFromScenarios(scenarios, { Home: 'app/page.tsx' }, metadata);
+            const result = computeEntityChangeStatus(changedFiles, entityInfos);
+            // Both are directly changed (new) → no impact propagation
+            expect(result['DrinkCard']).toEqual({ status: 'new' });
+            expect(result['Home']).toEqual({ status: 'new' });
+        });
+    });
+    // ── filterGroupsByChangeStatus ──────────────────────────────────────────
+    describe('filterGroupsByChangeStatus', () => {
+        const groups = [
+            ['Home', ['s1', 's2']],
+            ['About', ['s3']],
+            ['Header', ['s4']],
+        ];
+        it('should return all groups when entityChangeStatus is undefined', () => {
+            expect(filterGroupsByChangeStatus(groups, undefined)).toEqual(groups);
+        });
+        it('should return all groups when entityChangeStatus is empty', () => {
+            expect(filterGroupsByChangeStatus(groups, {})).toEqual(groups);
+        });
+        it('should filter to only groups with a change status', () => {
+            const status = {
+                Home: { status: 'new' },
+                Header: { status: 'edited' },
+            };
+            const result = filterGroupsByChangeStatus(groups, status);
+            expect(result).toEqual([
+                ['Home', ['s1', 's2']],
+                ['Header', ['s4']],
+            ]);
+        });
+        it('should return empty array when no groups match', () => {
+            const status = {
+                Footer: { status: 'new' },
+            };
+            const result = filterGroupsByChangeStatus(groups, status);
+            expect(result).toEqual([]);
+        });
+    });
+    // ── buildEntityInfosFromGlossary ────────────────────────────────────
+    describe('buildEntityInfosFromGlossary', () => {
+        it('should convert glossary entries to EntityInfo with name and filePath', () => {
+            const glossary = [
+                { name: 'pad', filePath: 'app/lib/calendar.ts' },
+                { name: 'formatDate', filePath: 'app/lib/calendar.ts' },
+            ];
+            const result = buildEntityInfosFromGlossary(glossary);
+            expect(result).toEqual([
+                { name: 'pad', filePath: 'app/lib/calendar.ts' },
+                { name: 'formatDate', filePath: 'app/lib/calendar.ts' },
+            ]);
+        });
+        it('should deduplicate by name (first occurrence wins)', () => {
+            const glossary = [
+                { name: 'pad', filePath: 'app/lib/calendar.ts' },
+                { name: 'pad', filePath: 'app/lib/other.ts' },
+            ];
+            const result = buildEntityInfosFromGlossary(glossary);
+            expect(result).toHaveLength(1);
+            expect(result[0].filePath).toBe('app/lib/calendar.ts');
+        });
+        it('should skip entries already present in existingNames set', () => {
+            const glossary = [
+                { name: 'Home', filePath: 'app/lib/calendar.ts' },
+                { name: 'pad', filePath: 'app/lib/calendar.ts' },
+            ];
+            const existing = new Set(['Home']);
+            const result = buildEntityInfosFromGlossary(glossary, existing);
+            expect(result).toHaveLength(1);
+            expect(result[0].name).toBe('pad');
+        });
+        it('should return empty array for empty input', () => {
+            expect(buildEntityInfosFromGlossary([])).toEqual([]);
+        });
+    });
+    // ── filterGlossaryByChangeStatus ──────────────────────────────────────
+    describe('filterGlossaryByChangeStatus', () => {
+        const functions = [
+            {
+                name: 'pad',
+                filePath: 'lib/calendar.ts',
+                description: '',
+                testFile: 'test.ts',
+            },
+            {
+                name: 'formatDate',
+                filePath: 'lib/calendar.ts',
+                description: '',
+                testFile: 'test.ts',
+            },
+            {
+                name: 'getDays',
+                filePath: 'lib/calendar.ts',
+                description: '',
+                testFile: 'test.ts',
+            },
+        ];
+        it('should return all functions when entityChangeStatus is undefined', () => {
+            expect(filterGlossaryByChangeStatus(functions, undefined)).toEqual(functions);
+        });
+        it('should return all functions when entityChangeStatus is empty', () => {
+            expect(filterGlossaryByChangeStatus(functions, {})).toEqual(functions);
+        });
+        it('should filter to only functions with a change status', () => {
+            const status = {
+                pad: { status: 'new' },
+                getDays: { status: 'edited' },
+            };
+            const result = filterGlossaryByChangeStatus(functions, status);
+            expect(result).toHaveLength(2);
+            expect(result.map((f) => f.name)).toEqual(['pad', 'getDays']);
+        });
+        it('should return empty array when no functions match', () => {
+            const status = {
+                SomeOtherThing: { status: 'new' },
+            };
+            const result = filterGlossaryByChangeStatus(functions, status);
+            expect(result).toEqual([]);
+        });
+    });
+    // ── filterScenarioScreenshotsByChangeStatus ───────────────────────────
+    describe('filterScenarioScreenshotsByChangeStatus', () => {
+        const screenshots = [
+            { name: 'Busy Month', path: 'busy.png' },
+            { name: 'Empty Calendar', path: 'empty.png' },
+            { name: 'EventPill - Default', path: 'pill.png' },
+            { name: 'ErrorState - Server Error', path: 'error.png' },
+            { name: 'CalendarGrid - Default', path: 'grid.png' },
+        ];
+        const pageNames = new Set(['Home']);
+        it('should return all screenshots when entityChangeStatus is undefined', () => {
+            expect(filterScenarioScreenshotsByChangeStatus(screenshots, undefined, pageNames)).toEqual(screenshots);
+        });
+        it('should return all screenshots when entityChangeStatus is empty', () => {
+            expect(filterScenarioScreenshotsByChangeStatus(screenshots, {}, pageNames)).toEqual(screenshots);
+        });
+        it('should filter screenshots to only those matching entities with a change status', () => {
+            const status = {
+                ErrorState: { status: 'new' },
+                Home: { status: 'edited' },
+            };
+            const result = filterScenarioScreenshotsByChangeStatus(screenshots, status, pageNames);
+            // App-level screenshots (no prefix) match because Home page has status
+            // "ErrorState - *" matches the ErrorState entity
+            expect(result.map((s) => s.name)).toEqual([
+                'Busy Month',
+                'Empty Calendar',
+                'ErrorState - Server Error',
+            ]);
+        });
+        it('should handle screenshots without component prefix (app-level)', () => {
+            const appScreenshots = [
+                { name: 'Busy Month', path: 'busy.png' },
+                { name: 'Empty Calendar', path: 'empty.png' },
+            ];
+            const status = {
+                Home: { status: 'edited' },
+            };
+            const result = filterScenarioScreenshotsByChangeStatus(appScreenshots, status, pageNames);
+            expect(result).toEqual(appScreenshots);
+        });
+        it('should exclude app-level screenshots when no page entity has a status', () => {
+            const status = {
+                SomeComponent: { status: 'new' },
+            };
+            const result = filterScenarioScreenshotsByChangeStatus(screenshots, status, pageNames);
+            // No page entity has status, so app-level screenshots are excluded
+            // SomeComponent doesn't match any screenshot prefix either
+            expect(result).toEqual([]);
+        });
+        it('should include app-level and matching component screenshots together', () => {
+            const status = {
+                Home: { status: 'edited' },
+                EventPill: { status: 'new' },
+            };
+            const result = filterScenarioScreenshotsByChangeStatus(screenshots, status, pageNames);
+            expect(result.map((s) => s.name)).toEqual([
+                'Busy Month',
+                'Empty Calendar',
+                'EventPill - Default',
+            ]);
+        });
+        it('should handle legacy "App - " prefixed scenario names (backward compat)', () => {
+            const legacyScreenshots = [
+                { name: 'App - Busy Month', path: 'busy.png' },
+                { name: 'App - Empty Calendar', path: 'empty.png' },
+                { name: 'EventPill - Default', path: 'pill.png' },
+            ];
+            const status = {
+                Home: { status: 'edited' },
+            };
+            const result = filterScenarioScreenshotsByChangeStatus(legacyScreenshots, status, pageNames);
+            expect(result.map((s) => s.name)).toEqual([
+                'App - Busy Month',
+                'App - Empty Calendar',
+            ]);
+        });
+    });
+    // ── scanPageFilePaths ───────────────────────────────────────────────────
+    describe('scanPageFilePaths', () => {
+        let tempDir;
+        beforeEach(() => {
+            tempDir = fsModule.mkdtempSync(pathModule.join(os.tmpdir(), 'scanpages-test-'));
+        });
+        afterEach(() => {
+            fsModule.rmSync(tempDir, { recursive: true, force: true });
+        });
+        it('should find page.tsx files in nested app/ structure', () => {
+            const appDir = pathModule.join(tempDir, 'app');
+            fsModule.mkdirSync(appDir, { recursive: true });
+            fsModule.writeFileSync(pathModule.join(appDir, 'page.tsx'), '');
+            fsModule.mkdirSync(pathModule.join(appDir, 'drinks'), {
+                recursive: true,
+            });
+            fsModule.writeFileSync(pathModule.join(appDir, 'drinks', 'page.tsx'), '');
+            fsModule.mkdirSync(pathModule.join(appDir, 'settings', 'profile'), {
+                recursive: true,
+            });
+            fsModule.writeFileSync(pathModule.join(appDir, 'settings', 'profile', 'page.tsx'), '');
+            const result = scanPageFilePaths(tempDir);
+            expect(result).toEqual({
+                Home: 'app/page.tsx',
+                Drinks: 'app/drinks/page.tsx',
+                Settings: 'app/settings/profile/page.tsx',
+            });
+        });
+        it('should find page.js files', () => {
+            const appDir = pathModule.join(tempDir, 'app');
+            fsModule.mkdirSync(appDir, { recursive: true });
+            fsModule.writeFileSync(pathModule.join(appDir, 'page.js'), '');
+            const result = scanPageFilePaths(tempDir);
+            expect(result).toEqual({ Home: 'app/page.js' });
+        });
+        it('should skip codeyam-isolate directories', () => {
+            const appDir = pathModule.join(tempDir, 'app');
+            fsModule.mkdirSync(pathModule.join(appDir, 'codeyam-isolate', 'test'), {
+                recursive: true,
+            });
+            fsModule.writeFileSync(pathModule.join(appDir, 'codeyam-isolate', 'test', 'page.tsx'), '');
+            const result = scanPageFilePaths(tempDir);
+            expect(result).toEqual({});
+        });
+        it('should return empty map when app/ does not exist', () => {
+            const result = scanPageFilePaths(tempDir);
+            expect(result).toEqual({});
+        });
+    });
+    // ── detectFirstFeature ─────────────────────────────────────────────────
+    describe('detectFirstFeature', () => {
+        it('should return true when git has 0 or 1 commits', () => {
+            const tempDir = fsModule.mkdtempSync(pathModule.join(os.tmpdir(), 'firstfeat-test-'));
+            try {
+                // Init a git repo with no commits
+                require('child_process').execSync('git init', {
+                    cwd: tempDir,
+                    stdio: 'ignore',
+                });
+                expect(detectFirstFeature(tempDir)).toBe(true);
+            }
+            finally {
+                fsModule.rmSync(tempDir, { recursive: true, force: true });
+            }
+        });
+        it('should return false when git has multiple commits', () => {
+            const tempDir = fsModule.mkdtempSync(pathModule.join(os.tmpdir(), 'firstfeat-test-'));
+            try {
+                require('child_process').execSync('git init && git config user.email "test@test.com" && git config user.name "test" && git commit --allow-empty -m "first" && git commit --allow-empty -m "second"', { cwd: tempDir, stdio: 'ignore' });
+                expect(detectFirstFeature(tempDir)).toBe(false);
+            }
+            finally {
+                fsModule.rmSync(tempDir, { recursive: true, force: true });
+            }
+        });
+        it('should return true when not a git repo', () => {
+            const tempDir = fsModule.mkdtempSync(pathModule.join(os.tmpdir(), 'firstfeat-test-'));
+            try {
+                expect(detectFirstFeature(tempDir)).toBe(true);
+            }
+            finally {
+                fsModule.rmSync(tempDir, { recursive: true, force: true });
+            }
+        });
+    });
+    // ── readFeatureStartedAt ───────────────────────────────────────────────
+    describe('readFeatureStartedAt', () => {
+        let tempDir;
+        beforeEach(() => {
+            tempDir = fsModule.mkdtempSync(pathModule.join(os.tmpdir(), 'featurets-test-'));
+            fsModule.mkdirSync(pathModule.join(tempDir, '.codeyam'), {
+                recursive: true,
+            });
+        });
+        afterEach(() => {
+            fsModule.rmSync(tempDir, { recursive: true, force: true });
+        });
+        it('should return featureStartedAt from editor-step.json', () => {
+            fsModule.writeFileSync(pathModule.join(tempDir, '.codeyam', 'editor-step.json'), JSON.stringify({ featureStartedAt: '2026-03-01T10:00:00.000Z' }));
+            expect(readFeatureStartedAt(tempDir)).toBe('2026-03-01T10:00:00.000Z');
+        });
+        it('should return null when file does not exist', () => {
+            expect(readFeatureStartedAt(tempDir)).toBeNull();
+        });
+        it('should return null when featureStartedAt is not set', () => {
+            fsModule.writeFileSync(pathModule.join(tempDir, '.codeyam', 'editor-step.json'), JSON.stringify({ step: 5 }));
+            expect(readFeatureStartedAt(tempDir)).toBeNull();
+        });
+        it('should return null for invalid JSON', () => {
+            fsModule.writeFileSync(pathModule.join(tempDir, '.codeyam', 'editor-step.json'), 'not json');
+            expect(readFeatureStartedAt(tempDir)).toBeNull();
+        });
+    });
+});
+//# sourceMappingURL=entityChangeStatus.test.js.map