@codeyam/codeyam-cli 0.1.21 → 0.1.23

package/codeyam-cli/src/commands/editorAnalyzeImportsArgs.js

@@ -0,0 +1,23 @@
+/**
+ * Parse file path arguments for `codeyam editor analyze-imports`.
+ *
+ * Supports multiple calling conventions:
+ *   codeyam editor analyze-imports path/to/file.tsx                → json="path/to/file.tsx", extras=[]
+ *   codeyam editor analyze-imports file1.tsx file2.tsx             → json="file1.tsx", extras=["editor","file2.tsx"]
+ *   codeyam editor analyze-imports                                 → json=undefined, extras=[] → empty (all entities)
+ */
+export function parseAnalyzeImportsArgs(json, extras) {
+    const paths = [];
+    if (json) {
+        paths.push(json);
+    }
+    // Collect extra positional args, filtering out "editor" and non-strings
+    for (const arg of extras) {
+        if (typeof arg === 'string' && arg !== 'editor') {
+            paths.push(arg);
+        }
+    }
+    // Deduplicate while preserving order
+    return [...new Set(paths)];
+}
+//# sourceMappingURL=editorAnalyzeImportsArgs.js.map

package/codeyam-cli/src/commands/editorAnalyzeImportsArgs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editorAnalyzeImportsArgs.js","sourceRoot":"","sources":["../../../../src/commands/editorAnalyzeImportsArgs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAwB,EACxB,MAA2B;IAE3B,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,IAAI,IAAI,EAAE,CAAC;QACT,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IAED,wEAAwE;IACxE,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;YAChD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,qCAAqC;IACrC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAC7B,CAAC"}

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, queryUnassociatedScenarios, isOnlyIncompleteEntities, isOnlyPreExistingIncomplete, isAutoRemediable, identifyScenariosNeedingRecapture, detectDuplicateNames, } from "../editorAudit.js";
+import { isComponent, classifyGlossaryEntries, computeAudit, filterGlossaryByChangeStatus, resolveAuditSessionScope, queryScenarioCounts, queryPageScenarioCounts, queryIncompleteEntities, queryMiscategorizedScenarios, queryUnassociatedScenarios, isOnlyIncompleteEntities, isOnlyPreExistingIncomplete, isAutoRemediable, identifyScenariosNeedingRecapture, detectDuplicateNames, aggregateClientErrorsByComponent, determineTargetedAnalysisPaths, shouldAutoRecapture, } from "../editorAudit.js";
 describe('editorAudit', () => {
     describe('isComponent', () => {
         it('should return true for JSX.Element return type', () => {
@@ -1987,6 +1987,24 @@ describe('editorAudit', () => {
                 allPassing: false,
             })).toBe(true);
         });
+        it('should return false when there are also runner errors', () => {
+            // functionsRunnerError means the test runner crashed — a real failure
+            // that cannot be fixed by entity SHA backfill or analyze-imports.
+            // If this returns true, checkAuditGate would attempt a useless backfill
+            // instead of reporting the runner error, and isOnlyPreExistingIncomplete
+            // could let the gate pass entirely.
+            expect(isOnlyIncompleteEntities({
+                componentsMissing: 0,
+                componentsWithErrors: 0,
+                functionsFailing: 0,
+                functionsRunnerError: 2,
+                functionsNameMismatch: 0,
+                functionsMissing: 0,
+                missingFromGlossary: 0,
+                incompleteEntities: 1,
+                allPassing: false,
+            })).toBe(false);
+        });
     });
     // ── isAutoRemediable ─────────────────────────────────────────────────
     describe('isAutoRemediable', () => {
@@ -2779,6 +2797,25 @@ describe('editorAudit', () => {
             });
             expect(result).toHaveLength(0);
         });
+        it('should NOT flag scenarios for new entities (they need creation, not recapture)', () => {
+            // "new" entities are being seen for the first time. Their scenarios need
+            // initial creation, not recapture of old screenshots. Flagging them as
+            // "needs_recapture" sends the wrong remediation signal to Claude.
+            const entityChangeStatus = {
+                NewComponent: { status: 'new' },
+            };
+            const result = identifyScenariosNeedingRecapture({
+                scenarios: [
+                    {
+                        name: 'NewComponent - Default',
+                        entityName: 'NewComponent',
+                        updatedInSession: false,
+                    },
+                ],
+                entityChangeStatus,
+            });
+            expect(result).toHaveLength(0);
+        });
     });
     // ── detectDuplicateNames ──────────────────────────────────────────
     describe('detectDuplicateNames', () => {
@@ -2946,6 +2983,28 @@ describe('editorAudit', () => {
             expect(result.components[0].status).toBe('missing');
             expect(result.summary.componentsMissing).toBe(1);
         });
+        it('should not count needs_recapture components as componentsOk', () => {
+            // A needs_recapture component is not "ok" — it needs action. Counting it
+            // in componentsOk is misleading: if totalComponents=2, componentsOk=2,
+            // and componentsNeedingRecapture=1, the numbers don't add up (2+1 > 2).
+            const result = computeAudit({
+                components: [
+                    { name: 'Library', filePath: 'app/library/page.tsx' },
+                    { name: 'DrinkCard', filePath: 'app/components/DrinkCard.tsx' },
+                ],
+                functions: [],
+                scenarioCounts: { DrinkCard: 2 },
+                testFileExistence: {},
+                totalScenarioCounts: { Library: 3 },
+                entityChangeStatus: { Library: { status: 'impacted' } },
+            });
+            expect(result.components[0].status).toBe('needs_recapture');
+            expect(result.components[1].status).toBe('ok');
+            // needs_recapture is not "ok" — should be counted separately
+            expect(result.summary.componentsOk).toBe(1);
+            expect(result.summary.componentsNeedingRecapture).toBe(1);
+            expect(result.summary.totalComponents).toBe(2);
+        });
     });
     // ── queryUnassociatedScenarios ──────────────────────────────────────
     describe('queryUnassociatedScenarios', () => {
@@ -3248,6 +3307,61 @@ describe('editorAudit', () => {
             expect(result.functions[0].suggestedTestFile).toBeUndefined();
         });
     });
+    describe('hint for function audit entries', () => {
+        it('should include a hint for name_mismatch functions explaining the fix', () => {
+            // Claude sees "name mismatch" with no guidance on what it means or how
+            // to fix it. The hint should explain that a top-level describe block
+            // matching the function name is required for the CodeYam UI.
+            const result = computeAudit({
+                components: [],
+                functions: [
+                    {
+                        name: 'useDrinks',
+                        filePath: 'app/hooks/useDrinks.ts',
+                        testFile: 'app/hooks/useDrinks.test.ts',
+                    },
+                ],
+                scenarioCounts: {},
+                testFileExistence: { 'app/hooks/useDrinks.test.ts': true },
+                testResults: {
+                    'app/hooks/useDrinks.test.ts': {
+                        passing: true,
+                        hasEntityNameDescribe: false,
+                    },
+                },
+            });
+            expect(result.functions[0].status).toBe('name_mismatch');
+            expect(result.functions[0].hint).toBeDefined();
+            expect(result.functions[0].hint).toContain('describe');
+            expect(result.functions[0].hint).toContain('useDrinks');
+        });
+        it('should include a hint for runner_error functions showing the error', () => {
+            // When the test runner crashes, Claude needs to see WHY it crashed
+            // to fix the underlying issue. Without this, Claude loops re-running audit.
+            const result = computeAudit({
+                components: [],
+                functions: [
+                    {
+                        name: 'getTimeAgo',
+                        filePath: 'src/lib/format.ts',
+                        testFile: 'src/lib/format.test.ts',
+                    },
+                ],
+                scenarioCounts: {},
+                testFileExistence: { 'src/lib/format.test.ts': true },
+                testResults: {
+                    'src/lib/format.test.ts': {
+                        passing: false,
+                        hasEntityNameDescribe: false,
+                        errorMessage: 'Cannot find module "@/lib/format"',
+                    },
+                },
+            });
+            expect(result.functions[0].status).toBe('runner_error');
+            expect(result.functions[0].hint).toBeDefined();
+            expect(result.functions[0].hint).toContain('Cannot find module');
+        });
+    });
     describe('hint for missing components', () => {
         it('should hint that layout files need app-level scenarios', () => {
             const result = computeAudit({
@@ -3295,6 +3409,21 @@ describe('editorAudit', () => {
             });
             expect(result.components[0].hint).toBeUndefined();
         });
+        it('should provide a hint for needs_recapture components', () => {
+            // Components with needs_recapture status need guidance on what to do.
+            // Without a hint, Claude has no instructions for fixing the issue.
+            const result = computeAudit({
+                components: [{ name: 'Library', filePath: 'app/library/page.tsx' }],
+                functions: [],
+                scenarioCounts: {},
+                testFileExistence: {},
+                totalScenarioCounts: { Library: 3 },
+                entityChangeStatus: { Library: { status: 'impacted' } },
+            });
+            expect(result.components[0].status).toBe('needs_recapture');
+            expect(result.components[0].hint).toBeDefined();
+            expect(result.components[0].hint).toContain('recapture');
+        });
     });
     describe('formatIncompleteEntityGuidance', () => {
         it('should include the entity name and scenario count', () => {
@@ -3340,6 +3469,60 @@ describe('editorAudit', () => {
             expect(result).toMatch(/scenario.*without.*import graph|import graph.*not.*built/i);
         });
     });
+    describe('formatManualAnalysisGuidance', () => {
+        it('should include entity name, scenario count, and error message', () => {
+            const { formatManualAnalysisGuidance } = require('../editorAudit');
+            const result = formatManualAnalysisGuidance({
+                name: 'Header',
+                filePath: 'src/components/Header.tsx',
+                scenarioCount: 3,
+                error: 'TypeScript parsing error: unexpected token',
+            });
+            expect(result).toContain('Header');
+            expect(result).toContain('3 scenario(s)');
+            expect(result).toContain('TypeScript parsing error');
+        });
+        it('should include MANUAL ANALYSIS REQUIRED header', () => {
+            const { formatManualAnalysisGuidance } = require('../editorAudit');
+            const result = formatManualAnalysisGuidance({
+                name: 'Header',
+                filePath: 'src/components/Header.tsx',
+                scenarioCount: 2,
+                error: 'Parse error',
+            });
+            expect(result).toContain('MANUAL ANALYSIS REQUIRED');
+        });
+        it('should tell Claude to read the source file', () => {
+            const { formatManualAnalysisGuidance } = require('../editorAudit');
+            const result = formatManualAnalysisGuidance({
+                name: 'Header',
+                filePath: 'src/components/Header.tsx',
+                scenarioCount: 2,
+                error: 'Parse error',
+            });
+            expect(result).toContain('Read src/components/Header.tsx');
+        });
+        it('should include the manual-entity command', () => {
+            const { formatManualAnalysisGuidance } = require('../editorAudit');
+            const result = formatManualAnalysisGuidance({
+                name: 'Header',
+                filePath: 'src/components/Header.tsx',
+                scenarioCount: 2,
+                error: 'Parse error',
+            });
+            expect(result).toContain('codeyam editor manual-entity');
+        });
+        it('should tell Claude to check glossary for imports', () => {
+            const { formatManualAnalysisGuidance } = require('../editorAudit');
+            const result = formatManualAnalysisGuidance({
+                name: 'Header',
+                filePath: 'src/components/Header.tsx',
+                scenarioCount: 2,
+                error: 'Parse error',
+            });
+            expect(result).toContain('glossary');
+        });
+    });
     describe('getIncompleteEntityFilePaths', () => {
         // The audit should auto-fix incomplete entities by running analysis on
         // just their specific file paths, not all 117+ files. This function
@@ -3490,6 +3673,29 @@ describe('editorAudit', () => {
                 },
             ])).toBe(true);
         });
+        it('should return false when there are runner errors even if all incompletes are pre-existing', () => {
+            // Safety net: runner errors (crashed test runner) must NEVER bypass the gate.
+            // Without this test, a regression removing functionsRunnerError from
+            // isOnlyIncompleteEntities would silently let broken test infrastructure through.
+            expect(isOnlyPreExistingIncomplete({
+                incompleteEntities: 1,
+                preExistingIncompleteEntities: 1,
+                componentsMissing: 0,
+                componentsWithErrors: 0,
+                functionsFailing: 0,
+                functionsRunnerError: 1,
+                functionsNameMismatch: 0,
+                functionsMissing: 0,
+                missingFromGlossary: 0,
+            }, [
+                {
+                    entitySha: 'a',
+                    name: 'OldComponent',
+                    scenarioCount: 1,
+                    preExisting: true,
+                },
+            ])).toBe(false);
+        });
         it('should return false when some incomplete entities are NOT pre-existing', () => {
             expect(isOnlyPreExistingIncomplete({
                 incompleteEntities: 2,
@@ -3555,5 +3761,254 @@ describe('editorAudit', () => {
             })).toBe(false);
         });
     });
+    // ── aggregateClientErrorsByComponent ─────────────────────────────────
+    describe('aggregateClientErrorsByComponent', () => {
+        it('should attribute errors to component using componentName from metadata', () => {
+            const result = aggregateClientErrorsByComponent({
+                'scenario-1': {
+                    scenarioName: 'DrinkCard - Default',
+                    errors: ['TypeError: Cannot read property "price"'],
+                },
+            }, [
+                {
+                    name: 'DrinkCard - Default',
+                    componentName: 'DrinkCard',
+                },
+            ]);
+            expect(result['DrinkCard']).toEqual([
+                'TypeError: Cannot read property "price"',
+            ]);
+        });
+        it('should attribute app-level scenario errors using pageFilePath', () => {
+            // App-level scenarios have componentName=null. The old approach
+            // parsed the scenario name "Full Page with Library" and got
+            // "Full Page with Library" as the component — which matches nothing.
+            // With metadata, we derive the entity name from pageFilePath.
+            const result = aggregateClientErrorsByComponent({
+                'scenario-1': {
+                    scenarioName: 'Full Page with Library',
+                    errors: ['TypeError: Cannot read property "title"'],
+                },
+            }, [
+                {
+                    name: 'Full Page with Library',
+                    componentName: null,
+                    pageFilePath: 'app/library/page.tsx',
+                },
+            ]);
+            // Should be keyed by the canonical entity name from scenarioEntityName()
+            expect(result['Library']).toEqual([
+                'TypeError: Cannot read property "title"',
+            ]);
+        });
+        it('should fall back to scenario name parsing when no metadata match exists', () => {
+            // If the scenario is not in the metadata list (e.g., metadata not yet loaded),
+            // fall back to the "ComponentName - Variant" convention
+            const result = aggregateClientErrorsByComponent({
+                'scenario-1': {
+                    scenarioName: 'Header - Dark Mode',
+                    errors: ['ReferenceError: theme is not defined'],
+                },
+            }, []);
+            expect(result['Header']).toEqual([
+                'ReferenceError: theme is not defined',
+            ]);
+        });
+        it('should handle non-route file paths via scenarioEntityName', () => {
+            // Non-route files (src/...) are treated as app entry points by
+            // scenarioEntityName → buildRoutePattern returns '/' → 'Home'.
+            // When a url is available, it provides a better entity name.
+            const result = aggregateClientErrorsByComponent({
+                'scenario-1': {
+                    scenarioName: 'LibraryApp - Rich',
+                    errors: ['Error: fetch failed'],
+                },
+            }, [
+                {
+                    name: 'LibraryApp - Rich',
+                    componentName: null,
+                    pageFilePath: 'src/library/LibraryApp.tsx',
+                    url: '/library',
+                },
+            ]);
+            // scenarioEntityName uses url fallback when pageFilePath is a non-route file
+            // pageFilePath 'src/...' → buildRoutePattern → '/' → routeDisplayName → 'Home'
+            // But componentName takes priority, and with url '/library' as final fallback
+            // scenarioEntityName({ pageFilePath: 'src/library/LibraryApp.tsx' }) → 'Home'
+            // because pageFilePath is checked before url
+            expect(result['Home']).toEqual(['Error: fetch failed']);
+        });
+        it('should skip scenarios with no errors', () => {
+            const result = aggregateClientErrorsByComponent({
+                'scenario-1': {
+                    scenarioName: 'DrinkCard - Default',
+                    errors: [],
+                },
+            }, [
+                {
+                    name: 'DrinkCard - Default',
+                    componentName: 'DrinkCard',
+                },
+            ]);
+            expect(result).toEqual({});
+        });
+        it('should aggregate errors from multiple scenarios for same component', () => {
+            const result = aggregateClientErrorsByComponent({
+                'scenario-1': {
+                    scenarioName: 'DrinkCard - Default',
+                    errors: ['Error A'],
+                },
+                'scenario-2': {
+                    scenarioName: 'DrinkCard - Hover',
+                    errors: ['Error B', 'Error C'],
+                },
+            }, [
+                { name: 'DrinkCard - Default', componentName: 'DrinkCard' },
+                { name: 'DrinkCard - Hover', componentName: 'DrinkCard' },
+            ]);
+            expect(result['DrinkCard']).toEqual(['Error A', 'Error B', 'Error C']);
+        });
+        it('should use capitalized display name for page file paths, not lowercase directory', () => {
+            // aggregateClientErrorsByComponent must produce keys matching scenarioEntityName().
+            // scenarioEntityName({ pageFilePath: 'app/library/page.tsx' }) returns 'Library',
+            // so the key must be 'Library' — not 'library' (the raw directory name).
+            // computeAudit checks clientErrors[glossaryEntryName], so a lowercase key
+            // will never match, silently dropping all client errors for page-level scenarios.
+            const result = aggregateClientErrorsByComponent({
+                'sc-1': {
+                    scenarioName: 'Library - Default',
+                    errors: ['TypeError: fetch failed'],
+                },
+            }, [
+                {
+                    name: 'Library - Default',
+                    componentName: null,
+                    pageFilePath: 'app/library/page.tsx',
+                },
+            ]);
+            expect(result).toHaveProperty('Library');
+            expect(result['Library']).toEqual(['TypeError: fetch failed']);
+        });
+        it('should use "Home" for root page app/page.tsx, not "app"', () => {
+            // Root page: scenarioEntityName returns 'Home', not 'app'.
+            // Custom path parsing incorrectly pops the parent dir ('app').
+            const result = aggregateClientErrorsByComponent({
+                'sc-1': {
+                    scenarioName: 'Home - Default',
+                    errors: ['ReferenceError: window is not defined'],
+                },
+            }, [
+                {
+                    name: 'Home - Default',
+                    componentName: null,
+                    pageFilePath: 'app/page.tsx',
+                },
+            ]);
+            expect(result).toHaveProperty('Home');
+            expect(result['Home']).toEqual(['ReferenceError: window is not defined']);
+        });
+    });
+    // ── determineTargetedAnalysisPaths ──────────────────────────────────
+    describe('determineTargetedAnalysisPaths', () => {
+        it('should return unique file paths from unassociated scenarios', () => {
+            const result = determineTargetedAnalysisPaths({
+                unassociatedScenarios: [
+                    { filePath: 'app/components/CreateFromFiltersButton.tsx' },
+                    { filePath: 'app/components/StaleDismissedBanner.tsx' },
+                ],
+                incompleteEntities: [],
+            });
+            expect(result).toEqual([
+                'app/components/CreateFromFiltersButton.tsx',
+                'app/components/StaleDismissedBanner.tsx',
+            ]);
+        });
+        it('should include file paths from incomplete entities', () => {
+            const result = determineTargetedAnalysisPaths({
+                unassociatedScenarios: [{ filePath: 'app/components/TaskCard.tsx' }],
+                incompleteEntities: [{ filePath: 'app/components/Dashboard.tsx' }],
+            });
+            expect(result).toEqual([
+                'app/components/TaskCard.tsx',
+                'app/components/Dashboard.tsx',
+            ]);
+        });
+        it('should deduplicate file paths across both sources', () => {
+            const result = determineTargetedAnalysisPaths({
+                unassociatedScenarios: [{ filePath: 'app/components/TaskCard.tsx' }],
+                incompleteEntities: [{ filePath: 'app/components/TaskCard.tsx' }],
+            });
+            expect(result).toEqual(['app/components/TaskCard.tsx']);
+        });
+        it('should return empty array when no issues', () => {
+            const result = determineTargetedAnalysisPaths({
+                unassociatedScenarios: [],
+                incompleteEntities: [],
+            });
+            expect(result).toEqual([]);
+        });
+        it('should filter out entries with empty file paths', () => {
+            const result = determineTargetedAnalysisPaths({
+                unassociatedScenarios: [{ filePath: '' }],
+                incompleteEntities: [],
+            });
+            expect(result).toEqual([]);
+        });
+        it('should handle incomplete entities with undefined filePath', () => {
+            const result = determineTargetedAnalysisPaths({
+                unassociatedScenarios: [{ filePath: 'app/components/Good.tsx' }],
+                incompleteEntities: [
+                    {
+                    /* no filePath at all */
+                    },
+                    { filePath: undefined },
+                    { filePath: 'app/components/AlsoGood.tsx' },
+                ],
+            });
+            expect(result).toEqual([
+                'app/components/Good.tsx',
+                'app/components/AlsoGood.tsx',
+            ]);
+        });
+    });
+    // ── shouldAutoRecapture ─────────────────────────────────────────────
+    describe('shouldAutoRecapture', () => {
+        it('should return true when fix flag is set and stale scenarios exist', () => {
+            expect(shouldAutoRecapture({
+                fix: true,
+                scenariosNeedingRecapture: [
+                    {
+                        scenarioName: 'Default',
+                        entityName: 'TaskCard',
+                        status: { status: 'edited' },
+                    },
+                ],
+            })).toBe(true);
+        });
+        it('should return false when fix flag is not set', () => {
+            expect(shouldAutoRecapture({
+                fix: false,
+                scenariosNeedingRecapture: [
+                    {
+                        scenarioName: 'Default',
+                        entityName: 'TaskCard',
+                        status: { status: 'edited' },
+                    },
+                ],
+            })).toBe(false);
+        });
+        it('should return false when fix is set but no stale scenarios', () => {
+            expect(shouldAutoRecapture({
+                fix: true,
+                scenariosNeedingRecapture: [],
+            })).toBe(false);
+        });
+        it('should return false when both are falsy', () => {
+            expect(shouldAutoRecapture({
+                fix: false,
+                scenariosNeedingRecapture: [],
+            })).toBe(false);
+        });
+    });
 });
 //# sourceMappingURL=editorAudit.test.js.map