legacyver 2.1.0 → 2.1.2

package/src/cli/commands/analyze.js

@@ -1,240 +1,262 @@
-/**
- * Analyze command — main pipeline orchestrator.
- * Calls Crawler -> Parser -> LLM Engine -> Renderer in sequence.
- * Manages progress bar, aggregates errors, prints final summary.
- */
-
-import { resolve } from 'node:path';
-import { loadConfig, mergeWithFlags } from '../../utils/config.js';
-import { logger } from '../../utils/logger.js';
-import { LegacyverError } from '../../utils/errors.js';
-import { createSpinner, createProgressBar, confirmPrompt, printSummary } from '../ui.js';
-import { applyFlags } from '../flags.js';
-import { crawl } from '../../crawler/index.js';
-import { parseAll } from '../../parser/index.js';
-import { buildPKG } from '../../parser/pkg-builder.js';
-import { resolveCallGraph } from '../../parser/call-graph.js';
-import { createLLMEngine } from '../../llm/index.js';
-import { buildChunks } from '../../llm/chunker.js';
-import { estimateCost } from '../../llm/cost-estimator.js';
-import { createQueue } from '../../llm/queue.js';
-import { render } from '../../renderer/index.js';
-import { loadCache, saveCache, getCacheHits, purgeDeleted, addToGitignore } from '../../cache/index.js';
-
-async function runAnalyze(targetPath, options) {
-  const startTime = Date.now();
-  const errors = [];
-
-  // If dry-run without a path, just show cost estimate info and exit early
-  const effectivePath = targetPath || process.cwd();
-
-  // Load and merge config
-  const fileConfig = await loadConfig(effectivePath);
-  const config = mergeWithFlags(fileConfig, {
-    provider: options.provider,
-    model: options.model,
-    output: options.output,
-    format: options.format,
-    concurrency: options.concurrency ? parseInt(options.concurrency, 10) : undefined,
-    maxFileSizeKb: options.maxFileSize ? parseInt(options.maxFileSize, 10) : undefined,
-    incremental: options.incremental,
-    noConfirm: !options.confirm, // commander inverts --no-confirm
-    dryRun: options.dryRun,
-    ignore: options.ignore,
-    jsonSummary: options.jsonSummary,
-    verbose: options.verbose,
+'use strict';
+
+const path = require('path');
+const { loadConfig } = require('../../utils/config');
+const { createSpinner, createProgressBar, confirmPrompt, printSummary } = require('../ui');
+const logger = require('../../utils/logger');
+const pc = require('picocolors');
+
+const { NoApiKeyError } = require('../../utils/errors');
+
+module.exports = async function analyzeCommand(target, flags) {
+  target = target || '.';
+  // Merge CLI flags into config
+  let config = loadConfig({
+    provider: flags.provider,
+    model: flags.model,
+    format: flags.format,
+    out: flags.out,
+    concurrency: flags.concurrency ? parseInt(flags.concurrency) : undefined,
+    dryRun: flags.dryRun,
+    incremental: flags.incremental,
+    confirm: flags.confirm,
+    verbose: flags.verbose,
+    maxFileSizeKb: flags.maxFileSize ? parseInt(flags.maxFileSize) : undefined,
   });
 
-  const resolvedTarget = resolve(effectivePath);
-  const resolvedOutput = resolve(config.output);
+  if (config.verbose) logger.setLevel('debug');
+
+  const targetDir = path.resolve(target);
+  const outputDir = path.resolve(config.out);
 
-  // Stage 1: Crawl
-  const crawlSpinner = createSpinner('Discovering files...');
-  crawlSpinner.start();
+  // ─── Stage 1: Crawler ────────────────────────────────────────────────────
+  const crawlerSpinner = createSpinner('Crawling files...');
+  crawlerSpinner.start();
 
+  const { crawl } = require('../../crawler/index');
   let manifest;
   try {
-    manifest = await crawl(resolvedTarget, {
-      maxFileSizeKb: config.maxFileSizeKb,
-      ignore: config.ignore,
-    });
-  } catch (err) {
-    crawlSpinner.fail('File discovery failed');
-    throw err;
+    manifest = await crawl(targetDir, config);
+    crawlerSpinner.succeed(`Found ${manifest.files.length} files (${manifest.skipped.length} skipped)`);
+  } catch (e) {
+    crawlerSpinner.fail(`Crawler failed: ${e.message}`);
+    process.exit(1);
   }
 
-  crawlSpinner.succeed(`Found ${manifest.length} files`);
-
-  if (manifest.length === 0) {
-    logger.warn('No files found to analyze. Check your target path and ignore rules.');
-    return;
+  if (manifest.files.length === 0) {
+    console.log(pc.yellow('No source files found. Check your target directory and .legacyverignore.'));
+    process.exit(0);
   }
 
-  // Handle incremental cache
+  // ─── Incremental cache ────────────────────────────────────────────────────
   let cacheMap = {};
-  let filesToAnalyze = manifest;
-  let cachedCount = 0;
+  let cacheHits = [];
+  let cacheMisses = manifest.files;
 
   if (config.incremental) {
-    const cacheDir = resolve(resolvedTarget, '.legacyver-cache');
-    cacheMap = loadCache(cacheDir);
-    cacheMap = purgeDeleted(cacheMap, manifest.map((f) => f.relativePath));
-    const { hits, misses } = getCacheHits(manifest, cacheMap);
-    cachedCount = hits.length;
-    filesToAnalyze = misses;
-    if (cachedCount > 0) {
-      logger.info(`Cache: ${cachedCount} files unchanged, ${misses.length} files to analyze`);
-    }
+    const cache = require('../../cache/index');
+    const cacheDir = path.join(targetDir, '.legacyver-cache');
+    cacheMap = cache.loadCache(cacheDir);
+    const { hits, misses } = cache.getCacheHits(manifest.files, cacheMap);
+    cacheHits = hits;
+    cacheMisses = misses;
+    logger.info(`Cache: ${hits.length} hits, ${misses.length} misses`);
   }
 
-  // Stage 2: Parse
+  const filesToAnalyze = cacheMisses;
+
+  // ─── Stage 2: AST Parser ─────────────────────────────────────────────────
   const parseSpinner = createSpinner('Parsing AST...');
   parseSpinner.start();
 
-  let allFileFacts;
+  const { parseFiles } = require('../../parser/index');
+  let pkg;
   try {
-    allFileFacts = await parseAll(filesToAnalyze, resolvedTarget);
-  } catch (err) {
-    parseSpinner.fail('AST parsing failed');
-    throw err;
+    pkg = await parseFiles(filesToAnalyze, manifest.meta, config);
+    parseSpinner.succeed(`Parsed ${filesToAnalyze.length} files`);
+  } catch (e) {
+    parseSpinner.fail(`Parser failed: ${e.message}`);
+    logger.error(e.stack);
+    process.exit(1);
   }
 
-  // Build call graph and PKG
-  const resolvedFacts = resolveCallGraph(allFileFacts);
-  const pkg = buildPKG(resolvedFacts, resolvedTarget);
-
-  parseSpinner.succeed(`Parsed ${allFileFacts.length} files (${pkg.meta.totalFiles} in PKG)`);
-
-  // Stage 3: LLM Engine
-  const chunks = buildChunks(resolvedFacts, config, resolvedTarget);
-
-  // Cost estimation
-  const costEstimate = estimateCost(chunks, config.provider);
-  logger.info(`Estimated cost: $${costEstimate.estimatedCostUSD.toFixed(4)} (${costEstimate.totalInputTokens} input tokens)`);
-
+  // ─── Dry run ─────────────────────────────────────────────────────────────
   if (config.dryRun) {
+    const { estimateCost } = require('../../llm/cost-estimator');
+    const { buildChunks } = require('../../llm/chunker');
+    const chunks = buildChunks(pkg, config);
+    const est = await estimateCost(chunks, config);
+
     console.log('');
-    console.log(JSON.stringify(costEstimate, null, 2));
-    console.log('');
-    logger.info('Dry run complete. No LLM calls made.');
-    return;
+    console.log(pc.bold('Dry Run Results:'));
+    console.log(`  Files:        ${filesToAnalyze.length}`);
+    console.log(`  Input tokens: ${est.totalInputTokens}`);
+    if (config.model && config.model.endsWith(':free')) {
+      console.log(`  Estimated cost: $0.00 (free model)`);
+    } else {
+      console.log(`  Estimated cost: $${est.estimatedCostUSD.toFixed(4)}`);
+    }
+    process.exit(0);
   }
 
-  // Create engine only when we actually need it (not for dry runs)
-  const engine = createLLMEngine(config);
-
-  // Confirm cost if over $0.10 and not --no-confirm
-  if (costEstimate.estimatedCostUSD > 0.10 && !config.noConfirm) {
-    const confirmed = await confirmPrompt(
-      `Estimated cost is $${costEstimate.estimatedCostUSD.toFixed(4)}. Proceed?`
-    );
-    if (!confirmed) {
-      logger.info('Aborted by user.');
-      process.exit(4);
+  // ─── Free model policy ────────────────────────────────────────────────────
+  const { applyFreeModelPolicy } = require('../../llm/free-model');
+  config = applyFreeModelPolicy(config);
+
+  // ─── Cost gate ────────────────────────────────────────────────────────────
+  const errors = [];
+  let totalTokens = 0;
+  let totalCost = 0;
+
+  if (!config.isFreeModel) {
+    const { estimateCost } = require('../../llm/cost-estimator');
+    const { buildChunks } = require('../../llm/chunker');
+    const chunks = buildChunks(pkg, config);
+    const est = await estimateCost(chunks, config);
+    totalTokens = est.totalInputTokens;
+    totalCost = est.estimatedCostUSD;
+
+    if (est.estimatedCostUSD > 0.10 && config.confirm) {
+      console.log(`\nEstimated cost: ${pc.yellow('$' + est.estimatedCostUSD.toFixed(4))} for ${est.totalInputTokens} tokens`);
+      const ok = await confirmPrompt('Proceed with LLM analysis?');
+      if (!ok) {
+        console.log(pc.yellow('Aborted by user.'));
+        process.exit(0);
+      }
     }
   }
 
-  // Execute LLM calls
-  const progressBar = createProgressBar(chunks.length);
+  // ─── Stage 3: LLM Engine ─────────────────────────────────────────────────
+  const llmSpinner = createSpinner('Generating documentation...');
+  llmSpinner.start();
+
+  const progressBar = createProgressBar(filesToAnalyze.length);
   progressBar.start();
 
-  const queue = createQueue(engine, {
-    concurrency: config.concurrency,
+  const { buildChunks } = require('../../llm/chunker');
+  const { createQueue } = require('../../llm/queue');
+  const { createProvider } = require('../../llm/index');
+  const { validateFragment } = require('../../llm/validator');
+  const { reprompt } = require('../../llm/re-prompter');
+
+  let provider;
+  try {
+    provider = createProvider(config);
+  } catch (e) {
+    if (e.code === 'NO_API_KEY') {
+      const providerName = (config.provider || '').toLowerCase();
+      const isGroq = providerName === 'groq';
+      const isGemini = providerName === 'gemini';
+      const label = isGemini ? 'Google Gemini' : isGroq ? 'Groq' : 'OpenRouter';
+      console.error(pc.red(`\n  No API key found for ${label}.\n`));
+      console.error('  To fix, choose one of:\n');
+      if (isGroq) {
+        console.error(pc.cyan('  1. Run the setup wizard:'));
+        console.error('       legacyver init\n');
+        console.error(pc.cyan('  2. Set an environment variable:'));
+        console.error('       export GROQ_API_KEY=your_key_here\n');
+        console.error('  Get a free Groq key at: https://console.groq.com/keys\n');
+      } else if (isGemini) {
+        console.error(pc.cyan('  1. Run the setup wizard:'));
+        console.error('       legacyver init\n');
+        console.error(pc.cyan('  2. Set an environment variable:'));
+        console.error('       export GEMINI_API_KEY=your_key_here\n');
+        console.error('  Get a free key at: https://aistudio.google.com/apikey\n');
+      } else {
+        console.error(pc.cyan('  1. Run the setup wizard:'));
+        console.error('       legacyver init\n');
+        console.error(pc.cyan('  2. Set an environment variable:'));
+        console.error('       export OPENROUTER_API_KEY=your_key_here\n');
+        console.error(pc.cyan('  3. Use Google Gemini instead (free, 15 req/min):'));
+        console.error('       legacyver analyze --provider gemini\n');
+        console.error(pc.cyan('  4. Use Groq instead (fast & free):'));
+        console.error('       legacyver analyze --provider groq\n');
+        console.error(pc.cyan('  5. Use local Ollama instead (no key needed):'));
+        console.error('       legacyver analyze --provider ollama\n');
+        console.error('  Get a free OpenRouter key at: https://openrouter.ai/keys\n');
+      }
+      process.exit(1);
+    }
+    throw e;
+  }
+  const chunks = buildChunks(pkg, config);
+  let qualityWarnings = 0;
+
+  const docFragments = await createQueue(chunks, provider, config, {
     onProgress: () => progressBar.increment(),
-    onError: (err, chunk) => {
-      errors.push({ file: chunk.relativePath, error: err.message });
-    },
+    onError: (e, chunk) => errors.push(`${chunk.relativePath}: ${e.message}`),
   });
 
-  const docFragments = await queue.processAll(chunks);
   progressBar.stop();
-
-  logger.success(`Generated documentation for ${docFragments.length} files`);
-
-  // Update cache
-  if (config.incremental) {
-    const cacheDir = resolve(resolvedTarget, '.legacyver-cache');
-    for (const file of filesToAnalyze) {
-      cacheMap[file.relativePath] = {
-        hash: file.hash,
-        generatedAt: new Date().toISOString(),
-      };
+  llmSpinner.succeed('Documentation generated');
+
+  // Quality validation
+  for (const frag of docFragments) {
+    const fileFacts = pkg.files[frag.relativePath];
+    const result = validateFragment(frag, fileFacts);
+    frag._qualityWarnings = result.hallucinations.concat(result.missingExports.map(s => `Missing export: ${s}`));
+    qualityWarnings += frag._qualityWarnings.length;
+
+    if (result.missingExports.length > 0) {
+      const pct = result.missingExports.length / (fileFacts && fileFacts.exports ? fileFacts.exports.length : 1);
+      if (pct > 0.3) {
+        const improved = await reprompt(frag, fileFacts, provider, config);
+        if (improved) frag.content = improved.content;
+      }
     }
-    saveCache(cacheDir, cacheMap);
-    addToGitignore(resolvedTarget);
   }
 
-  // Stage 4: Render
+  // Merge cached fragments
+  const allFragments = [...docFragments];
+  // (cached fragments would be loaded here)
+
+  // ─── Stage 4: Renderer ───────────────────────────────────────────────────
   const renderSpinner = createSpinner('Rendering output...');
   renderSpinner.start();
 
+  const { render } = require('../../renderer/index');
   try {
-    await render(docFragments, pkg, {
-      format: config.format,
-      outputDir: resolvedOutput,
-    });
-  } catch (err) {
-    renderSpinner.fail('Rendering failed');
-    throw err;
+    await render(allFragments, pkg, outputDir, config);
+    renderSpinner.succeed(`Output written to ${outputDir}`);
+  } catch (e) {
+    renderSpinner.fail(`Renderer failed: ${e.message}`);
+    errors.push(e.message);
   }
 
-  renderSpinner.succeed(`Output written to ${resolvedOutput}`);
+  // ─── Save cache ───────────────────────────────────────────────────────────
+  if (config.incremental || filesToAnalyze.length > 0) {
+    const cache = require('../../cache/index');
+    const cacheDir = path.join(targetDir, '.legacyver-cache');
+    const updatedMap = { ...cacheMap };
+    for (const file of filesToAnalyze) {
+      updatedMap[file.relativePath] = {
+        hash: file.hash,
+        docFile: path.join(outputDir, file.relativePath.replace(/\.[^.]+$/, '.md')),
+        generatedAt: new Date().toISOString(),
+      };
+    }
+    // Purge deleted
+    const currentPaths = manifest.files.map(f => f.relativePath);
+    cache.purgeDeleted(updatedMap, currentPaths);
+    cache.saveCache(cacheDir, updatedMap);
+    cache.autoAddToGitignore(targetDir);
+  }
 
-  // Summary
-  const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+  // ─── Summary ─────────────────────────────────────────────────────────────
   const stats = {
-    filesAnalyzed: docFragments.length,
-    filesSkipped: manifest.length - filesToAnalyze.length - cachedCount,
-    filesCached: cachedCount,
-    errors: errors.length,
-    inputTokens: costEstimate.totalInputTokens,
-    outputTokens: costEstimate.totalOutputTokens,
-    estimatedCost: costEstimate.estimatedCostUSD,
-    outputDir: resolvedOutput,
-    duration: `${duration}s`,
+    filesAnalyzed: filesToAnalyze.length,
+    filesCached: cacheHits.length,
+    filesSkipped: manifest.skipped.length,
+    tokensUsed: totalTokens || undefined,
+    estimatedCost: totalCost || undefined,
+    qualityWarnings,
+    errors,
+    outputDir,
   };
 
-  if (config.jsonSummary) {
-    console.log(JSON.stringify(stats, null, 2));
+  if (flags.jsonSummary) {
+    console.log(JSON.stringify(stats));
   } else {
     printSummary(stats);
   }
-
-  if (errors.length > 0) {
-    logger.warn(`${errors.length} file(s) had errors during analysis:`);
-    for (const e of errors) {
-      logger.warn(`  ${e.file}: ${e.error}`);
-    }
-  }
-}
-
-export function registerAnalyzeCommand(program) {
-  const cmd = program
-    .command('analyze [path]')
-    .description('Analyze a codebase and generate documentation');
-
-  applyFlags(cmd, [
-    'provider', 'model', 'output', 'format', 'concurrency',
-    'maxFileSize', 'incremental', 'noConfirm', 'dryRun',
-    'ignore', 'jsonSummary',
-  ]);
-
-  cmd.action(async (targetPath, options) => {
-    try {
-      await runAnalyze(targetPath, options);
-    } catch (err) {
-      if (err instanceof LegacyverError) {
-        logger.error(err.message);
-        if (err.suggestion) {
-          logger.info(`Suggestion: ${err.suggestion}`);
-        }
-        process.exit(err.exitCode || 1);
-      }
-      logger.error('Unexpected error:', err.message);
-      if (process.env.DEBUG || options.verbose) {
-        console.error(err.stack);
-      }
-      process.exit(1);
-    }
-  });
-}
+};

package/src/cli/commands/cache.js

@@ -1,35 +1,15 @@
-/**
- * Cache subcommand — cache management utilities.
- * Supports `cache clear` to delete .legacyver-cache/ directory.
- */
-
-import { rmSync, existsSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { logger } from '../../utils/logger.js';
-
-export function registerCacheCommand(program) {
-  const cache = program
-    .command('cache')
-    .description('Manage the incremental analysis cache');
-
-  cache
-    .command('clear')
-    .description('Delete the .legacyver-cache/ directory')
-    .option('--dir <path>', 'Project directory containing the cache', '.')
-    .action((options) => {
-      const cacheDir = resolve(options.dir, '.legacyver-cache');
-
-      if (!existsSync(cacheDir)) {
-        logger.info('No cache directory found. Nothing to clear.');
-        return;
-      }
-
-      try {
-        rmSync(cacheDir, { recursive: true, force: true });
-        logger.success(`Deleted ${cacheDir}`);
-      } catch (err) {
-        logger.error(`Failed to delete cache: ${err.message}`);
-        process.exit(1);
-      }
-    });
-}
+'use strict';
+
+const { existsSync, rmSync } = require('fs');
+const { join } = require('path');
+const pc = require('picocolors');
+
+module.exports = async function cacheClearCommand() {
+  const cacheDir = join(process.cwd(), '.legacyver-cache');
+  if (existsSync(cacheDir)) {
+    rmSync(cacheDir, { recursive: true, force: true });
+    console.log(pc.green('✓ Cache cleared: .legacyver-cache/'));
+  } else {
+    console.log(pc.yellow('No cache directory found (.legacyver-cache/).'));
+  }
+};