@codeyam/codeyam-cli 0.1.22 → 0.1.23

package/codeyam-cli/src/commands/__tests__/editor.analyzeImportsArgs.test.js

@@ -0,0 +1,47 @@
+/**
+ * Tests that `codeyam editor analyze-imports` correctly parses optional
+ * file path arguments to scope analysis to specific files.
+ *
+ * Without file paths, analyze-imports analyzes all glossary entities.
+ * With file paths, it scopes analysis to only those files.
+ */
+import { parseAnalyzeImportsArgs } from "../editorAnalyzeImportsArgs.js";
+describe('parseAnalyzeImportsArgs', () => {
+    it('should return empty array when no args provided', () => {
+        expect(parseAnalyzeImportsArgs(undefined, [])).toEqual([]);
+        expect(parseAnalyzeImportsArgs('', [])).toEqual([]);
+    });
+    it('should parse a single file path from json arg', () => {
+        // codeyam editor analyze-imports app/components/Foo.tsx
+        expect(parseAnalyzeImportsArgs('app/components/Foo.tsx', [])).toEqual([
+            'app/components/Foo.tsx',
+        ]);
+    });
+    it('should collect extra positional args from argv._', () => {
+        // codeyam editor analyze-imports app/components/Foo.tsx app/components/Bar.tsx
+        // yargs: json="app/components/Foo.tsx", argv._=["editor", "app/components/Bar.tsx"]
+        expect(parseAnalyzeImportsArgs('app/components/Foo.tsx', [
+            'editor',
+            'app/components/Bar.tsx',
+        ])).toEqual(['app/components/Foo.tsx', 'app/components/Bar.tsx']);
+    });
+    it('should filter out "editor" from argv._', () => {
+        expect(parseAnalyzeImportsArgs(undefined, [
+            'editor',
+            'app/components/Foo.tsx',
+            'app/lib/utils.ts',
+        ])).toEqual(['app/components/Foo.tsx', 'app/lib/utils.ts']);
+    });
+    it('should deduplicate file paths', () => {
+        expect(parseAnalyzeImportsArgs('app/components/Foo.tsx', [
+            'editor',
+            'app/components/Foo.tsx',
+            'app/components/Bar.tsx',
+        ])).toEqual(['app/components/Foo.tsx', 'app/components/Bar.tsx']);
+    });
+    it('should handle numeric extras gracefully', () => {
+        // yargs can put numbers in argv._
+        expect(parseAnalyzeImportsArgs('app/components/Foo.tsx', [42, 'editor'])).toEqual(['app/components/Foo.tsx']);
+    });
+});
+//# sourceMappingURL=editor.analyzeImportsArgs.test.js.map

package/codeyam-cli/src/commands/__tests__/editor.analyzeImportsArgs.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor.analyzeImportsArgs.test.js","sourceRoot":"","sources":["../../../../../src/commands/__tests__/editor.analyzeImportsArgs.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAEtE,QAAQ,CAAC,yBAAyB,EAAE,GAAG,EAAE;IACvC,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,CAAC,uBAAuB,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC3D,MAAM,CAAC,uBAAuB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,wDAAwD;QACxD,MAAM,CAAC,uBAAuB,CAAC,wBAAwB,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;YACpE,wBAAwB;SACzB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,+EAA+E;QAC/E,oFAAoF;QACpF,MAAM,CACJ,uBAAuB,CAAC,wBAAwB,EAAE;YAChD,QAAQ;YACR,wBAAwB;SACzB,CAAC,CACH,CAAC,OAAO,CAAC,CAAC,wBAAwB,EAAE,wBAAwB,CAAC,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAChD,MAAM,CACJ,uBAAuB,CAAC,SAAS,EAAE;YACjC,QAAQ;YACR,wBAAwB;YACxB,kBAAkB;SACnB,CAAC,CACH,CAAC,OAAO,CAAC,CAAC,wBAAwB,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CACJ,uBAAuB,CAAC,wBAAwB,EAAE;YAChD,QAAQ;YACR,wBAAwB;YACxB,wBAAwB;SACzB,CAAC,CACH,CAAC,OAAO,CAAC,CAAC,wBAAwB,EAAE,wBAAwB,CAAC,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,kCAAkC;QAClC,MAAM,CACJ,uBAAuB,CAAC,wBAAwB,EAAE,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAClE,CAAC,OAAO,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/codeyam-cli/src/commands/__tests__/editor.auditNoAutoAnalysis.test.js

@@ -3,11 +3,12 @@ import * as path from 'path';
 /**
  * Structural test: handleAudit must NOT call runAnalysisForEntities.
  *
- * Previously, handleAudit auto-ran targeted analysis for incomplete entities,
- * which was slow (analyzer startup + AST scan) and contradicted the design
- * intent (comment at line ~6255 says "We do NOT run handleAnalyzeImports here").
+ * Previously, handleAudit auto-ran full analysis for incomplete entities,
+ * which was slow (analyzer startup + AST scan for all glossary entries).
  *
- * This test ensures the auto-analysis doesn't creep back in.
+ * Targeted analysis (with filePaths for 1-3 specific files) is acceptable,
+ * but a full scan (without filePaths) must never be used here.
+ * This test ensures the full auto-analysis doesn't creep back in.
  */
 describe('handleAudit - no auto-analysis', () => {
     it('should not call runAnalysisForEntities inside handleAudit', () => {
@@ -43,7 +44,7 @@ describe('handleAudit - no auto-analysis', () => {
         expect(handleAuditBody).toContain('incompleteEntities');
         expect(handleAuditBody).toContain('formatIncompleteEntityGuidance');
     });
-    it('should not call handleAnalyzeImports inside handleAudit', () => {
+    it('should only call handleAnalyzeImports with filePaths (targeted, not full scan)', () => {
         const editorTsPath = path.join(__dirname, '..', 'editor.ts');
         const source = fs.readFileSync(editorTsPath, 'utf8');
         const handleAuditStart = source.indexOf('async function handleAudit');
@@ -54,10 +55,17 @@ describe('handleAudit - no auto-analysis', () => {
             ? handleAuditStart + 1 + nextFnMatch.index
             : source.length;
         const handleAuditBody = source.slice(handleAuditStart, handleAuditEnd);
-        // handleAnalyzeImports calls runAnalysisForEntities internally —
-        // it takes minutes on large projects and contradicts the audit's
-        // read-only design intent.
-        expect(handleAuditBody).not.toContain('handleAnalyzeImports');
+        // Targeted handleAnalyzeImports (with filePaths) is OK — it only
+        // analyzes 1-3 specific files. A full scan (without filePaths) takes
+        // minutes on large projects and must never be used here.
+        const calls = [...handleAuditBody.matchAll(/handleAnalyzeImports\s*\(/g)];
+        for (const call of calls) {
+            const afterCall = handleAuditBody.slice(call.index + call[0].length);
+            // Each call must include filePaths in its arguments
+            const closingParen = afterCall.indexOf(')');
+            const callArgs = afterCall.slice(0, closingParen);
+            expect(callArgs).toContain('filePaths');
+        }
     });
 });
 //# sourceMappingURL=editor.auditNoAutoAnalysis.test.js.map

package/codeyam-cli/src/commands/__tests__/editor.auditNoAutoAnalysis.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"editor.auditNoAutoAnalysis.test.js","sourceRoot":"","sources":["../../../../../src/commands/__tests__/editor.auditNoAutoAnalysis.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"editor.auditNoAutoAnalysis.test.js","sourceRoot":"","sources":["../../../../../src/commands/__tests__/editor.auditNoAutoAnalysis.test.ts"],"names":[],"mappings":"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"}

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

@@ -1978,7 +1978,7 @@ function printMigrateStep8(root) {
     printComponentCaptureInstructions();
     console.log();
     console.log(chalk.bold('Verify:'));
-    checkbox('Run `codeyam editor analyze-imports` to populate import graph');
+    checkbox('Run `codeyam editor analyze-imports` to populate import graph (or `codeyam editor analyze-imports path/to/file.tsx ...` for specific files)');
     checkbox('Run library function tests: `npx jest --testPathPattern="<relevant>" --maxWorkers=2`');
     checkbox('Run `codeyam editor audit` to check completeness');
     checkbox('Check for client errors: `codeyam editor client-errors`');
@@ -2356,10 +2356,14 @@ async function handleAnalyzeImports(options = {}) {
         glossaryEntries = sanitizeGlossaryEntries(parsed);
     }
     catch {
+        if (options.silent)
+            return;
         console.error(chalk.red('Error: Could not parse .codeyam/glossary.json.'));
         process.exit(1);
     }
     if (glossaryEntries.length === 0) {
+        if (options.silent)
+            return;
         console.error(chalk.red('Error: glossary.json is empty.'));
         process.exit(1);
     }
@@ -2428,6 +2432,15 @@ async function handleAnalyzeImports(options = {}) {
     catch {
         // Non-fatal — fall back to analyzing all files
     }
+    // If specific file paths were requested, scope analysis to only those files.
+    // The full filePaths set is still used for the import graph below.
+    if (options.filePaths && options.filePaths.length > 0) {
+        const requested = new Set(options.filePaths);
+        targetFilePaths = targetFilePaths.filter((fp) => requested.has(fp));
+        if (targetFilePaths.length === 0 && !options.silent) {
+            console.log(chalk.dim('Requested file(s) already analyzed or not in glossary — skipping analysis.'));
+        }
+    }
     // Run data-structure-only analysis for entities that need it.
     // Don't pass entityNames — entities may not exist yet (fresh clone).
     // The analyzer will discover and create them from file paths.
@@ -2444,6 +2457,10 @@ async function handleAnalyzeImports(options = {}) {
         catch (err) {
             progress.fail('Analysis failed');
             const msg = err instanceof Error ? err.message : String(err);
+            if (options.silent) {
+                // Internal caller — don't kill the process, let the caller handle it
+                return;
+            }
             console.error(chalk.red(`Error: ${msg}`));
             process.exit(1);
         }
@@ -3454,7 +3471,15 @@ function printAuditGateFailures(data) {
         for (const m of missingGlossary) {
             issues.push(`    → ${m.name} (${m.filePath})`);
         }
-        issues.push(`      Fix: Run \`codeyam editor analyze-imports\` to add these files to the glossary`);
+        const missingPaths = missingGlossary
+            .map((m) => m.filePath)
+            .filter(Boolean);
+        if (missingPaths.length > 0) {
+            issues.push(`      Fix: Run \`codeyam editor analyze-imports ${missingPaths.join(' ')}\``);
+        }
+        else {
+            issues.push(`      Fix: Run \`codeyam editor analyze-imports\` to add these files to the glossary`);
+        }
     }
     if (s.incompleteEntities > 0) {
         // Check for persistent analysis failures
@@ -3498,8 +3523,16 @@ function printAuditGateFailures(data) {
         }
     }
     if (s.unassociatedScenarios > 0) {
-        issues.push(`${s.unassociatedScenarios} component(s) have scenarios with no entity link — run \`codeyam editor analyze-imports\` then re-run audit`);
         const unassociated = data.unassociatedScenarios || [];
+        const unassocPaths = unassociated
+            .map((u) => u.filePath)
+            .filter(Boolean);
+        if (unassocPaths.length > 0) {
+            issues.push(`${s.unassociatedScenarios} component(s) have scenarios with no entity link — run \`codeyam editor analyze-imports ${unassocPaths.join(' ')}\` then re-run audit`);
+        }
+        else {
+            issues.push(`${s.unassociatedScenarios} component(s) have scenarios with no entity link — run \`codeyam editor analyze-imports\` then re-run audit`);
+        }
         for (const u of unassociated) {
             issues.push(`    → ${u.name} (${u.filePath}) — ${u.scenarioCount} scenario${u.scenarioCount !== 1 ? 's' : ''}`);
         }
@@ -3554,16 +3587,16 @@ function printAuditGateFailures(data) {
  * which glossary components have registered scenarios and which functions
  * have test files. Exits with code 1 if anything is missing.
  */
-async function handleAudit() {
+async function handleAudit(options) {
     let data = await fetchAuditResult();
     if (!data) {
         console.error(chalk.red('Error: Could not reach the CodeYam server. Is it running?'));
         process.exit(1);
     }
-    // Lightweight auto-fix: backfill entity_sha on scenarios that were
-    // registered before entity records existed. This is fast (DB-only).
-    // Import analysis is NOT triggered here — it scans all files and takes
-    // minutes on large projects. Users should run it separately if needed.
+    // Two-phase auto-fix for entity associations:
+    // Phase 1: DB-only backfill — fast, matches existing entities to scenarios.
+    // Phase 2: If backfill fails, targeted analyze-imports for only the
+    // specific unresolved files (1-3 files, not the full glossary scan).
     const incompleteBeforeFix = data.incompleteEntities || [];
     const unassociatedBeforeFix = data.unassociatedScenarios || [];
     let autoRemediationFailed = false;
@@ -3595,14 +3628,58 @@ async function handleAudit() {
             console.error(chalk.red('Error: Could not reach the CodeYam server after backfill.'));
             process.exit(1);
         }
-        // If issues persist after backfill, flag it so we show clear guidance
+        // If issues persist after DB-only backfill, run targeted analyze-imports
+        // for ONLY the specific files that need entities. This is fast (1-3 files)
+        // unlike full analyze-imports which scans all glossary entries.
+        const incompleteAfterBackfill = data.incompleteEntities || [];
+        const unassociatedAfterBackfill = data.unassociatedScenarios || [];
+        if (incompleteAfterBackfill.length > 0 ||
+            unassociatedAfterBackfill.length > 0) {
+            const { determineTargetedAnalysisPaths } = await import('../utils/editorAudit.js');
+            const targetPaths = determineTargetedAnalysisPaths({
+                unassociatedScenarios: unassociatedAfterBackfill,
+                incompleteEntities: incompleteAfterBackfill,
+            });
+            if (targetPaths.length > 0) {
+                console.log(chalk.dim(`Running targeted analysis for ${targetPaths.length} file${targetPaths.length !== 1 ? 's' : ''}...`));
+                try {
+                    await handleAnalyzeImports({
+                        silent: true,
+                        filePaths: targetPaths,
+                    });
+                    // Retry backfill after analysis created entities
+                    const entities = await loadEntities({});
+                    if (entities && entities.length > 0) {
+                        const { getDatabase: getDb } = await import('../../../packages/database/index.js');
+                        const freshDb = getDb();
+                        await backfillEntityShaOnScenarios(freshDb, entities.map((e) => ({
+                            sha: e.sha,
+                            name: e.name,
+                            filePath: e.filePath || '',
+                            isDefaultExport: e.metadata?.notExported === false &&
+                                e.metadata?.namedExport === false,
+                        })));
+                    }
+                    // Re-fetch audit results after targeted analysis
+                    data = await fetchAuditResult({ skipTests: true });
+                    if (!data) {
+                        console.error(chalk.red('Error: Could not reach the CodeYam server after analysis.'));
+                        process.exit(1);
+                    }
+                }
+                catch {
+                    // Targeted analysis failed — fall through to show remaining issues
+                }
+            }
+        }
+        // Check if issues persist after all remediation attempts
         const incompleteAfterFix = data.incompleteEntities || [];
         const unassociatedAfterFix = data.unassociatedScenarios || [];
         if (incompleteAfterFix.length > 0 || unassociatedAfterFix.length > 0) {
             autoRemediationFailed = true;
         }
     }
-    const { components, functions, summary } = data;
+    let { components, functions, summary } = data;
     console.log();
     console.log(chalk.bold.cyan('━━━ Editor Audit ━━━'));
     console.log();
@@ -3701,7 +3778,15 @@ async function handleAudit() {
         for (const m of missingFromGlossary) {
             console.log(`  ${chalk.red('✗')} ${m.name} ${chalk.dim(`(${m.filePath})`)} — ${m.scenarioCount} scenario${m.scenarioCount !== 1 ? 's' : ''} but not in glossary`);
         }
-        console.log(chalk.yellow('    Add these to .codeyam/glossary.json and run `codeyam editor analyze-imports`'));
+        const mgPaths = missingFromGlossary
+            .map((m) => m.filePath)
+            .filter(Boolean);
+        if (mgPaths.length > 0) {
+            console.log(chalk.yellow(`    Add these to .codeyam/glossary.json and run \`codeyam editor analyze-imports ${mgPaths.join(' ')}\``));
+        }
+        else {
+            console.log(chalk.yellow('    Add these to .codeyam/glossary.json and run `codeyam editor analyze-imports`'));
+        }
         console.log();
     }
     // Incomplete entities (scenarios without analyses) — report with guidance.
@@ -3756,12 +3841,18 @@ async function handleAudit() {
                 console.log(chalk.dim(`      … and ${u.scenarioNames.length - 3} more`));
             }
         }
+        const uaPaths = unassociatedScenarios
+            .map((u) => u.filePath)
+            .filter(Boolean);
+        const uaCmd = uaPaths.length > 0
+            ? `codeyam editor analyze-imports ${uaPaths.join(' ')}`
+            : 'codeyam editor analyze-imports';
         if (autoRemediationFailed) {
             console.log(chalk.yellow('    analyze-imports ran automatically but could not resolve these.'));
-            console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to see the full error output.'));
+            console.log(chalk.yellow(`    Run \`${uaCmd}\` to see the full error output.`));
         }
         else {
-            console.log(chalk.yellow('    Run `codeyam editor analyze-imports` to create entity records, then re-run audit to backfill.'));
+            console.log(chalk.yellow(`    Run \`${uaCmd}\` to create entity records, then re-run audit to backfill.`));
         }
         const unassocErrorReportPath = path.join(getProjectRoot(), '.codeyam', 'analysis-errors.txt');
         if (fs.existsSync(unassocErrorReportPath)) {
@@ -3794,7 +3885,26 @@ async function handleAudit() {
                 : `${s.status.status}`;
             console.log(`  ${chalk.red('✗')} ${s.scenarioName} ${chalk.dim(`(${s.entityName} — ${reason})`)}`);
         }
-        console.log(chalk.yellow('    Run: codeyam editor recapture-stale'));
+        if (options?.fix) {
+            // --fix: auto-recapture stale scenarios instead of just reporting them
+            const { shouldAutoRecapture } = await import('../utils/editorAudit.js');
+            if (shouldAutoRecapture({ fix: true, scenariosNeedingRecapture })) {
+                console.log(chalk.cyan('    --fix: auto-recapturing stale scenarios...'));
+                console.log();
+                await handleRecaptureStale();
+                // Re-fetch audit results so the summary and exit code reflect
+                // the post-fix state, not the pre-fix state.
+                const refreshed = await fetchAuditResult({ skipTests: true });
+                if (refreshed) {
+                    data = refreshed;
+                    ({ components, functions, summary } = data);
+                }
+            }
+        }
+        else {
+            console.log(chalk.yellow('    Run: codeyam editor recapture-stale'));
+            console.log(chalk.dim('    Or: codeyam editor audit --fix (to auto-recapture)'));
+        }
         console.log();
     }
     // Duplicate glossary names (warning, not a failure)
@@ -4796,6 +4906,11 @@ const editorCommand = {
             alias: 'p',
             describe: 'Port to run the web server on',
             default: 3111,
+        })
+            .option('fix', {
+            type: 'boolean',
+            describe: 'For audit: also recapture stale scenarios after displaying results',
+            default: false,
         });
         if (IS_INTERNAL_BUILD) {
             builder = builder
@@ -4923,9 +5038,11 @@ const editorCommand = {
             fs.writeFileSync(trackingPath, JSON.stringify({ step: state.step, taskCreated: true }, null, 2), 'utf8');
             return;
         }
-        // Subcommand: codeyam editor analyze-imports
+        // Subcommand: codeyam editor analyze-imports [file1.tsx file2.tsx ...]
         if (argv.step === 'analyze-imports') {
-            await handleAnalyzeImports();
+            const { parseAnalyzeImportsArgs } = await import('./editorAnalyzeImportsArgs.js');
+            const requestedPaths = parseAnalyzeImportsArgs(argv.json, argv._);
+            await handleAnalyzeImports(requestedPaths.length > 0 ? { filePaths: requestedPaths } : {});
             return;
         }
         // Subcommand: codeyam editor manual-entity <JSON|@file>
@@ -4938,9 +5055,9 @@ const editorCommand = {
             await handleDependents(argv.json || '');
             return;
         }
-        // Subcommand: codeyam editor audit
+        // Subcommand: codeyam editor audit [--fix]
         if (argv.step === 'audit') {
-            await handleAudit();
+            await handleAudit({ fix: argv.fix || false });
             return;
         }
         // Subcommand: codeyam editor scenarios