legacyver 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 legacyver contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# legacyver
+
+Generate technical documentation from undocumented or legacy codebases using AST parsing and LLMs.
+
+Legacyver crawls your source code, extracts structural facts with AST parsers (Tree-sitter + regex fallback), sends them to an LLM with anti-hallucination constraints, and outputs clean Markdown, HTML, or JSON documentation.
+
+## Install
+
+```bash
+npm install -g legacyver
+```
+
+Requires Node.js >= 18.0.0.
+
+## Quick Start
+
+```bash
+# 1. Run the setup wizard
+legacyver init
+
+# 2. Generate documentation
+legacyver analyze ./src
+
+# 3. View output
+open legacyver-docs/index.md
+```
+
+### Using Ollama (Free, Local)
+
+No API key required — just have [Ollama](https://ollama.ai) running:
+
+```bash
+legacyver analyze ./src --provider ollama
+```
+
+## CLI Reference
+
+### `legacyver analyze <path>`
+
+Main command. Analyzes a codebase and generates documentation.
+
+| Flag | Description | Default |
+|---|---|---|
+| `-p, --provider <name>` | LLM provider (`anthropic`, `openai`, `google`, `groq`, `ollama`) | `anthropic` |
+| `-m, --model <name>` | Model name (overrides provider default) | Provider default |
+| `-o, --output <dir>` | Output directory | `./legacyver-docs` |
+| `-f, --format <type>` | Output format: `markdown`, `html`, `json` | `markdown` |
+| `-c, --concurrency <n>` | Concurrent LLM requests | `5` |
+| `--max-file-size <kb>` | Skip files larger than this (KB) | `500` |
+| `--incremental` | Only re-analyze changed files | `false` |
+| `--no-confirm` | Skip cost confirmation prompt | `false` |
+| `--dry-run` | Show cost estimate, no LLM calls | `false` |
+| `--ignore <patterns...>` | Additional glob patterns to ignore | `[]` |
+| `--json-summary` | Output JSON summary to stdout | `false` |
+| `--verbose` | Enable debug output | `false` |
+
+### `legacyver init`
+
+Interactive setup wizard. Configures your preferred LLM provider, saves API keys to OS user config, and creates a `.legacyverrc` file.
+
+### `legacyver providers`
+
+Lists all supported providers with API key status and pricing.
+
+### `legacyver cache clear`
+
+Deletes the `.legacyver-cache/` directory.
+
+## Configuration
+
+Legacyver uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) for configuration. It searches for:
+
+- `.legacyverrc` (JSON)
+- `.legacyverrc.json`
+- `.legacyverrc.yaml`
+- `legacyver.config.js`
+- `legacyver.config.mjs`
+
+### `.legacyverrc` Schema
+
+```json
+{
+  "provider": "anthropic",
+  "model": null,
+  "format": "markdown",
+  "output": "./legacyver-docs",
+  "concurrency": 5,
+  "maxFileSizeKb": 500,
+  "incremental": false,
+  "ignore": ["test/**", "**/*.test.*"],
+  "languages": ["javascript", "typescript", "python", "java", "go"]
+}
+```
+
+CLI flags always take precedence over config file values.
+
+## Supported Languages
+
+| Language | Extensions | Parser |
+|---|---|---|
+| JavaScript | `.js`, `.jsx`, `.mjs` | Tree-sitter (WASM) or regex fallback |
+| TypeScript | `.ts`, `.tsx` | Tree-sitter (WASM) or regex fallback |
+| Python | `.py` | Tree-sitter (WASM) or regex fallback |
+| Java | `.java` | Tree-sitter (WASM) or regex fallback |
+| Go | `.go` | Tree-sitter (WASM) or regex fallback |
+
+When Tree-sitter WASM grammars are not available, legacyver automatically falls back to a generic regex-based parser that extracts function signatures, class definitions, and imports.
+
+## Supported LLM Providers
+
+| Provider | Default Model | Input Cost/1k tokens | Output Cost/1k tokens | API Key Env Var |
+|---|---|---|---|---|
+| Anthropic | `claude-haiku-3-5` | $0.00025 | $0.00125 | `ANTHROPIC_API_KEY` |
+| OpenAI | `gpt-4o-mini` | $0.00015 | $0.00060 | `OPENAI_API_KEY` |
+| Google | `gemini-1.5-flash` | $0.000075 | $0.00030 | `GOOGLE_API_KEY` |
+| Groq | `llama-3.1-70b-versatile` | $0.00059 | $0.00079 | `GROQ_API_KEY` |
+| Ollama | `llama3.2` | Free | Free | None (local) |
+
+## Ignore Rules
+
+Legacyver respects a `.legacyverignore` file (same syntax as `.gitignore`) in your project root.
+
+Default ignores include: `node_modules`, `.git`, `dist`, `build`, `__pycache__`, `venv`, `vendor`, minified files, lock files, and more.
+
+## CI/CD Integration
+
+Legacyver auto-detects non-interactive environments (no TTY) and disables spinners/prompts. For CI pipelines:
+
+```bash
+legacyver analyze ./src --provider openai --no-confirm --json-summary
+```
+
+The `--json-summary` flag outputs a machine-readable summary to stdout. The `--no-confirm` flag is required in non-interactive mode (otherwise legacyver exits with code 4).
+
+### Incremental Builds
+
+Use `--incremental` to skip unchanged files between CI runs:
+
+```bash
+legacyver analyze ./src --incremental --no-confirm
+```
+
+Cache is stored in `.legacyver-cache/` (auto-added to `.gitignore`).
+
+## How It Works
+
+1. **Crawler** discovers source files using fast-glob, respecting ignore rules
+2. **AST Parser** extracts structural facts (functions, classes, imports, exports, call graph) using Tree-sitter or regex fallback
+3. **LLM Engine** sends facts + source code to the LLM with anti-hallucination constraints — the LLM can only describe what's actually in the code
+4. **Renderer** assembles the output as Markdown (with Mermaid diagrams), self-contained HTML (with search), or structured JSON
+
+## License
+
+MIT

package/bin/legacyver.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'node:module';
+import { Command } from 'commander';
+import { registerAnalyzeCommand } from '../src/cli/commands/analyze.js';
+import { registerInitCommand } from '../src/cli/commands/init.js';
+import { registerProvidersCommand } from '../src/cli/commands/providers.js';
+import { registerCacheCommand } from '../src/cli/commands/cache.js';
+import { setVerbose } from '../src/utils/logger.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+const program = new Command();
+
+program
+  .name('legacyver')
+  .description('Generate technical documentation from undocumented or legacy codebases')
+  .version(pkg.version)
+  .option('--verbose', 'Enable verbose debug output', false)
+  .hook('preAction', (thisCommand) => {
+    const opts = thisCommand.opts();
+    if (opts.verbose) {
+      setVerbose(true);
+    }
+  });
+
+registerAnalyzeCommand(program);
+registerInitCommand(program);
+registerProvidersCommand(program);
+registerCacheCommand(program);
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "legacyver",
+  "version": "1.0.0",
+  "description": "Generate technical documentation from undocumented or legacy codebases using AST parsing and LLMs",
+  "main": "src/index.js",
+  "bin": {
+    "legacyver": "bin/legacyver.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/ test/"
+  },
+  "keywords": [
+    "documentation",
+    "legacy",
+    "codebase",
+    "ast",
+    "llm",
+    "tree-sitter",
+    "cli"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.75.0",
+    "@google/generative-ai": "^0.24.1",
+    "chalk": "^5.6.2",
+    "cli-progress": "^3.12.0",
+    "commander": "^14.0.3",
+    "conf": "^15.1.0",
+    "cosmiconfig": "^9.0.0",
+    "fast-glob": "^3.3.3",
+    "groq-sdk": "^0.37.0",
+    "ignore": "^7.0.5",
+    "marked": "^17.0.3",
+    "openai": "^6.22.0",
+    "ora": "^9.3.0",
+    "p-limit": "^7.3.0",
+    "p-retry": "^7.1.1",
+    "picocolors": "^1.1.1",
+    "web-tree-sitter": "^0.26.5"
+  },
+  "devDependencies": {
+    "eslint": "^10.0.0",
+    "vitest": "^4.0.18"
+  }
+}

package/src/cache/hash.js

@@ -0,0 +1,17 @@
+/**
+ * File hash computation for incremental cache.
+ * Uses Node.js crypto SHA-256 to produce deterministic file fingerprints.
+ */
+
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+
+/**
+ * Compute SHA-256 hash of a file's contents.
+ * @param {string} filePath - Absolute path to file
+ * @returns {string} Hex-encoded SHA-256 hash with "sha256:" prefix
+ */
+export function computeHash(filePath) {
+  const content = readFileSync(filePath);
+  return 'sha256:' + createHash('sha256').update(content).digest('hex');
+}

package/src/cache/index.js

@@ -0,0 +1,106 @@
+/**
+ * Incremental cache module.
+ * Persists file hashes to .legacyver-cache/hashes.json so that
+ * unchanged files can skip LLM re-analysis on subsequent runs.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const CACHE_FILE = 'hashes.json';
+
+/**
+ * Load the cache map from disk.
+ * @param {string} cacheDir - Path to .legacyver-cache directory
+ * @returns {Record<string, { hash: string, generatedAt: string }>} Cache map (empty object if no cache)
+ */
+export function loadCache(cacheDir) {
+  const cachePath = join(cacheDir, CACHE_FILE);
+  if (!existsSync(cachePath)) {
+    return {};
+  }
+  try {
+    const raw = readFileSync(cachePath, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    // Corrupted cache — start fresh
+    return {};
+  }
+}
+
+/**
+ * Save the cache map to disk.
+ * Creates the cache directory if it doesn't exist.
+ * @param {string} cacheDir - Path to .legacyver-cache directory
+ * @param {Record<string, { hash: string, generatedAt: string }>} cacheMap - Cache map to persist
+ */
+export function saveCache(cacheDir, cacheMap) {
+  mkdirSync(cacheDir, { recursive: true });
+  const cachePath = join(cacheDir, CACHE_FILE);
+  writeFileSync(cachePath, JSON.stringify(cacheMap, null, 2), 'utf-8');
+}
+
+/**
+ * Separate manifest entries into cache hits and misses.
+ * A hit means the file hash matches the cached hash — no re-analysis needed.
+ * @param {import('../crawler/manifest.js').FileManifest[]} manifest - Current file manifest
+ * @param {Record<string, { hash: string }>} cacheMap - Loaded cache map
+ * @returns {{ hits: import('../crawler/manifest.js').FileManifest[], misses: import('../crawler/manifest.js').FileManifest[] }}
+ */
+export function getCacheHits(manifest, cacheMap) {
+  const hits = [];
+  const misses = [];
+
+  for (const file of manifest) {
+    const cached = cacheMap[file.relativePath];
+    if (cached && cached.hash === file.hash) {
+      hits.push(file);
+    } else {
+      misses.push(file);
+    }
+  }
+
+  return { hits, misses };
+}
+
+/**
+ * Remove cache entries for files that no longer exist on disk.
+ * @param {Record<string, { hash: string }>} cacheMap - Current cache map
+ * @param {string[]} currentPaths - Relative paths of files currently on disk
+ * @returns {Record<string, { hash: string }>} Cleaned cache map
+ */
+export function purgeDeleted(cacheMap, currentPaths) {
+  const pathSet = new Set(currentPaths);
+  const cleaned = {};
+  for (const [key, value] of Object.entries(cacheMap)) {
+    if (pathSet.has(key)) {
+      cleaned[key] = value;
+    }
+  }
+  return cleaned;
+}
+
+/**
+ * Auto-add .legacyver-cache/ to .gitignore if .gitignore exists
+ * and doesn't already contain the entry.
+ * @param {string} projectRoot - Root directory of the project being analyzed
+ */
+export function addToGitignore(projectRoot) {
+  const gitignorePath = join(projectRoot, '.gitignore');
+  if (!existsSync(gitignorePath)) {
+    return;
+  }
+
+  const content = readFileSync(gitignorePath, 'utf-8');
+  const entry = '.legacyver-cache/';
+
+  // Check if already present (exact line match)
+  const lines = content.split('\n');
+  if (lines.some((line) => line.trim() === entry || line.trim() === '.legacyver-cache')) {
+    return;
+  }
+
+  // Append entry with a newline separator
+  const separator = content.endsWith('\n') ? '' : '\n';
+  writeFileSync(gitignorePath, content + separator + entry + '\n', 'utf-8');
+}

package/src/cli/commands/analyze.js

@@ -0,0 +1,240 @@
+/**
+ * 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,
+  });
+
+  const resolvedTarget = resolve(effectivePath);
+  const resolvedOutput = resolve(config.output);
+
+  // Stage 1: Crawl
+  const crawlSpinner = createSpinner('Discovering files...');
+  crawlSpinner.start();
+
+  let manifest;
+  try {
+    manifest = await crawl(resolvedTarget, {
+      maxFileSizeKb: config.maxFileSizeKb,
+      ignore: config.ignore,
+    });
+  } catch (err) {
+    crawlSpinner.fail('File discovery failed');
+    throw err;
+  }
+
+  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;
+  }
+
+  // Handle incremental cache
+  let cacheMap = {};
+  let filesToAnalyze = manifest;
+  let cachedCount = 0;
+
+  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`);
+    }
+  }
+
+  // Stage 2: Parse
+  const parseSpinner = createSpinner('Parsing AST...');
+  parseSpinner.start();
+
+  let allFileFacts;
+  try {
+    allFileFacts = await parseAll(filesToAnalyze, resolvedTarget);
+  } catch (err) {
+    parseSpinner.fail('AST parsing failed');
+    throw err;
+  }
+
+  // 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)`);
+
+  if (config.dryRun) {
+    console.log('');
+    console.log(JSON.stringify(costEstimate, null, 2));
+    console.log('');
+    logger.info('Dry run complete. No LLM calls made.');
+    return;
+  }
+
+  // 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);
+    }
+  }
+
+  // Execute LLM calls
+  const progressBar = createProgressBar(chunks.length);
+  progressBar.start();
+
+  const queue = createQueue(engine, {
+    concurrency: config.concurrency,
+    onProgress: () => progressBar.increment(),
+    onError: (err, chunk) => {
+      errors.push({ file: chunk.relativePath, error: err.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(),
+      };
+    }
+    saveCache(cacheDir, cacheMap);
+    addToGitignore(resolvedTarget);
+  }
+
+  // Stage 4: Render
+  const renderSpinner = createSpinner('Rendering output...');
+  renderSpinner.start();
+
+  try {
+    await render(docFragments, pkg, {
+      format: config.format,
+      outputDir: resolvedOutput,
+    });
+  } catch (err) {
+    renderSpinner.fail('Rendering failed');
+    throw err;
+  }
+
+  renderSpinner.succeed(`Output written to ${resolvedOutput}`);
+
+  // Summary
+  const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+  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`,
+  };
+
+  if (config.jsonSummary) {
+    console.log(JSON.stringify(stats, null, 2));
+  } 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

@@ -0,0 +1,35 @@
+/**
+ * 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);
+      }
+    });
+}