legacyver 2.0.0 → 2.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Legacyver Contributors
+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

package/README.md

@@ -1,14 +1,8 @@
-# Legacyver
+# legacyver
 
-Auto-generate technical documentation for legacy and undocumented codebases using AST parsing + LLMs.
+Generate technical documentation from undocumented or legacy codebases using AST parsing and LLMs.
 
-```bash
-npx legacyver analyze ./src
-```
-
-No documentation written beforehand. No configuration required. One command.
-
----
+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
 
@@ -16,183 +10,144 @@ No documentation written beforehand. No configuration required. One command.
 npm install -g legacyver
 ```
 
-Or use without installing:
-
-```bash
-npx legacyver analyze ./src
-```
-
----
+Requires Node.js >= 18.0.0.
 
 ## Quick Start
 
-**1. Initialize (saves your API key):**
-
 ```bash
+# 1. Run the setup wizard
 legacyver init
-```
-
-**2. Analyze a codebase:**
 
-```bash
+# 2. Generate documentation
 legacyver analyze ./src
+
+# 3. View output
+open legacyver-docs/index.md
 ```
 
-**3. View the output:**
+### Using Ollama (Free, Local)
 
-```
-legacyver-docs/
-  index.md        ← project overview + dependency graph + route map (Laravel)
-  SUMMARY.md      ← GitBook/Docusaurus compatible table of contents
-  src/
-    app.md
-    routes/users.md
-    ...
-```
+No API key required — just have [Ollama](https://ollama.ai) running:
 
----
+```bash
+legacyver analyze ./src --provider ollama
+```
 
-## CLI Commands
+## CLI Reference
 
-### `legacyver analyze <dir>`
+### `legacyver analyze <path>`
 
-Run the full documentation pipeline.
+Main command. Analyzes a codebase and generates documentation.
 
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--out <dir>` | `./legacyver-docs` | Output directory |
-| `--format <fmt>` | `markdown` | Output format: `markdown`, `html`, `json` |
-| `--provider <p>` | `openrouter` | LLM provider: `openrouter`, `ollama` |
-| `--model <id>` | `meta-llama/llama-3.3-70b-instruct:free` | Model ID |
-| `--incremental` | `false` | Skip files unchanged since last run |
-| `--dry-run` | `false` | Estimate cost without calling LLM |
-| `--concurrency <n>` | `3` | Max parallel LLM requests |
-| `--max-file-size <kb>` | `500` | Skip files larger than this |
-| `--no-confirm` | — | Skip cost confirmation prompt |
-| `--verbose` | `false` | Enable debug logging |
+| 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 wizard. Detects existing `.legacyverrc` and warns before overwriting. Saves API key to OS user config.
+Interactive setup wizard. Configures your preferred LLM provider, saves API keys to OS user config, and creates a `.legacyverrc` file.
 
 ### `legacyver providers`
 
-List all supported providers, API key status, and per-model pricing.
+Lists all supported providers with API key status and pricing.
 
 ### `legacyver cache clear`
 
-Delete the `.legacyver-cache/` directory to force full re-analysis on next run.
-
-### `legacyver --version`
+Deletes the `.legacyver-cache/` directory.
 
-Print the installed version.
+## Configuration
 
----
+Legacyver uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) for configuration. It searches for:
 
-## `.legacyverrc` Schema
+- `.legacyverrc` (JSON)
+- `.legacyverrc.json`
+- `.legacyverrc.yaml`
+- `legacyver.config.js`
+- `legacyver.config.mjs`
 
-Create a `.legacyverrc` (JSON or YAML) in your project root:
+### `.legacyverrc` Schema
 
 ```json
 {
-  "provider": "openrouter",
-  "model": "meta-llama/llama-3.3-70b-instruct:free",
+  "provider": "anthropic",
+  "model": null,
   "format": "markdown",
-  "out": "./legacyver-docs",
-  "concurrency": 3,
+  "output": "./legacyver-docs",
+  "concurrency": 5,
   "maxFileSizeKb": 500,
-  "incremental": true
+  "incremental": false,
+  "ignore": ["test/**", "**/*.test.*"],
+  "languages": ["javascript", "typescript", "python", "java", "go"]
 }
 ```
 
-All fields are optional. CLI flags override file config.
-
-Also supported: `legacyver.config.js`, `legacyver.config.yaml`.
-
----
+CLI flags always take precedence over config file values.
 
 ## Supported Languages
 
-| Language | Extensions | Framework Support |
-|----------|-----------|-------------------|
-| JavaScript | `.js`, `.jsx`, `.mjs` | Express (auto-detected) |
-| TypeScript | `.ts`, `.tsx` | — |
-| Python | `.py` | — |
-| Java | `.java` | — |
-| Go | `.go` | — |
-| PHP | `.php`, `.blade.php` | Laravel (auto-detected) |
-
-**Laravel extras:** When an `artisan` file is detected, Legacyver automatically extracts:
-- Route Map (Method, URI, Controller, Middleware, Route Name)
-- Model Relationships (as Mermaid `erDiagram`)
-- Service Provider Bindings
+| 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 | Env Var | Notes |
-|----------|---------|-------|
-| OpenRouter | `OPENROUTER_API_KEY` | Default. Free models available (`:free` suffix). Get a key at [openrouter.ai/keys](https://openrouter.ai/keys) |
-| Ollama | — | Local/offline. Requires Ollama running: `ollama serve` |
+| 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) |
 
-**Free usage:** The default model `meta-llama/llama-3.3-70b-instruct:free` is free via OpenRouter (rate-limited). Legacyver automatically caps concurrency to 1 for free models.
+## Ignore Rules
 
----
+Legacyver respects a `.legacyverignore` file (same syntax as `.gitignore`) in your project root.
 
-## Ignore Files
+Default ignores include: `node_modules`, `.git`, `dist`, `build`, `__pycache__`, `venv`, `vendor`, minified files, lock files, and more.
 
-Create a `.legacyverignore` in your project root using gitignore syntax:
+## CI/CD Integration
 
-```
-# .legacyverignore
-dist/
-build/
-coverage/
-*.min.js
+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
 ```
 
-See `.legacyverignore.example` for a documented example.
+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
 
-## CI/CD Integration
+Use `--incremental` to skip unchanged files between CI runs:
 
-```yaml
-# GitHub Actions example
-- name: Generate docs
-  env:
-    OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
-  run: |
-    npx legacyver analyze ./src --no-confirm --incremental --out ./docs
+```bash
+legacyver analyze ./src --incremental --no-confirm
 ```
 
-Legacyver detects non-TTY environments and disables spinners/progress bars automatically (plain log output only).
-
----
+Cache is stored in `.legacyver-cache/` (auto-added to `.gitignore`).
 
 ## How It Works
 
-1. **Crawl** — `fast-glob` walks the directory, respects `.legacyverignore`
-2. **Parse** — Regex/heuristic AST extracts facts: function names, params, complexity scores, imports, exports, call patterns
-3. **PKG** — Assembles a Project Knowledge Graph linking all facts
-4. **LLM** — Sends grounded facts + raw source to LLM; system prompt enforces anti-hallucination contract
-5. **Validate** — Post-generation checks: hallucination detection, completeness check (all exports documented)
-6. **Render** — Writes Markdown/HTML/JSON to output directory
-
-**Design principle:** The LLM is a _writer_, not an analyst. AST extracts facts; LLM only explains them.
-
----
-
-## Contributing
-
-```bash
-git clone https://github.com/user/legacyver
-npm install
-npx vitest run
-```
-
----
+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
 

package/bin/legacyver.js

@@ -1,56 +1,33 @@
 #!/usr/bin/env node
-'use strict';
 
-const { program } = require('commander');
-const { readFileSync } = require('fs');
-const { join } = require('path');
+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 pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
 
-program
-  .name('legacyver')
-  .description('AI-powered CLI tool to auto-generate technical documentation from legacy/undocumented codebases')
-  .version(pkg.version, '-v, --version', 'Output the current version')
-  .option('--verbose', 'Enable verbose debug logging');
+const program = new Command();
 
-// analyze command
-const analyzeCmd = require('../src/cli/commands/analyze');
 program
-  .command('analyze <target>')
-  .description('Analyze a directory and generate documentation')
-  .option('--out <dir>', 'Output directory', './legacyver-docs')
-  .option('--format <fmt>', 'Output format: markdown | html | json', 'markdown')
-  .option('--model <model>', 'LLM model to use')
-  .option('--provider <provider>', 'LLM provider: openrouter | ollama', 'openrouter')
-  .option('--concurrency <n>', 'Concurrent LLM requests (1-10)', '3')
-  .option('--dry-run', 'Run AST parsing only, no LLM calls')
-  .option('--incremental', 'Only re-analyze changed files')
-  .option('--no-confirm', 'Skip cost confirmation prompt')
-  .option('--json-summary', 'Output machine-readable JSON summary')
-  .option('--max-file-size <kb>', 'Skip files larger than this size in KB', '500')
-  .action(analyzeCmd);
-
-// init command
-const initCmd = require('../src/cli/commands/init');
-program
-  .command('init')
-  .description('Interactive setup wizard — saves API key and creates .legacyverrc')
-  .action(initCmd);
-
-// providers command
-const providersCmd = require('../src/cli/commands/providers');
-program
-  .command('providers')
-  .description('List supported LLM providers and available models')
-  .action(providersCmd);
-
-// cache command
-const cacheCmd = require('../src/cli/commands/cache');
-program
-  .command('cache')
-  .description('Manage the incremental analysis cache')
-  .command('clear')
-  .description('Delete the .legacyver-cache/ directory')
-  .action(cacheCmd);
+  .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

@@ -1,49 +1,51 @@
 {
   "name": "legacyver",
-  "version": "2.0.0",
-  "description": "AI-powered CLI tool to auto-generate technical documentation from legacy/undocumented codebases",
+  "version": "2.1.0",
+  "description": "Generate technical documentation from undocumented or legacy codebases using AST parsing and LLMs",
   "main": "src/index.js",
   "bin": {
     "legacyver": "bin/legacyver.js"
   },
-  "type": "commonjs",
   "engines": {
     "node": ">=18.0.0"
   },
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",
-    "lint": "eslint src/ bin/"
+    "lint": "eslint src/ test/"
   },
   "keywords": [
     "documentation",
-    "cli",
+    "legacy",
+    "codebase",
     "ast",
     "llm",
-    "legacy",
-    "code-analysis",
-    "tree-sitter"
+    "tree-sitter",
+    "cli"
   ],
-  "author": "",
   "license": "MIT",
+  "type": "module",
   "dependencies": {
-    "chalk": "^5.3.0",
+    "@anthropic-ai/sdk": "^0.75.0",
+    "@google/generative-ai": "^0.24.1",
+    "chalk": "^5.6.2",
     "cli-progress": "^3.12.0",
-    "commander": "^11.1.0",
-    "conf": "^12.0.0",
+    "commander": "^14.0.3",
+    "conf": "^15.1.0",
     "cosmiconfig": "^9.0.0",
-    "fast-glob": "^3.3.2",
-    "ignore": "^5.3.1",
-    "marked": "^11.1.1",
-    "ora": "^7.0.1",
-    "p-limit": "^4.0.0",
-    "p-retry": "^5.1.2",
-    "picocolors": "^1.0.0",
-    "tiktoken": "^1.0.15",
-    "web-tree-sitter": "^0.22.6"
+    "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": "^8.57.0",
-    "vitest": "^1.2.2"
+    "eslint": "^10.0.0",
+    "vitest": "^4.0.18"
   }
 }

package/src/cache/hash.js

@@ -1,16 +1,17 @@
-'use strict';
+/**
+ * File hash computation for incremental cache.
+ * Uses Node.js crypto SHA-256 to produce deterministic file fingerprints.
+ */
 
-const { createHash } = require('crypto');
-const { readFileSync } = require('fs');
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 
 /**
- * Compute SHA-256 hash of a file.
- * @param {string} filePath
- * @returns {string} hex string prefixed with 'sha256:'
+ * 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
  */
-function computeHash(filePath) {
+export function computeHash(filePath) {
   const content = readFileSync(filePath);
   return 'sha256:' + createHash('sha256').update(content).digest('hex');
 }
-
-module.exports = { computeHash };

package/src/cache/index.js

@@ -1,47 +1,56 @@
-'use strict';
+/**
+ * Incremental cache module.
+ * Persists file hashes to .legacyver-cache/hashes.json so that
+ * unchanged files can skip LLM re-analysis on subsequent runs.
+ */
 
-const { readFileSync, writeFileSync, mkdirSync, existsSync, appendFileSync } = require('fs');
-const path = require('path');
-const logger = require('../utils/logger');
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
 
 const CACHE_FILE = 'hashes.json';
 
 /**
- * Load cache from .legacyver-cache/hashes.json.
- * @param {string} cacheDir
- * @returns {Object} map of relativePath -> { hash, docFile, generatedAt }
+ * 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)
  */
-function loadCache(cacheDir) {
-  const cachePath = path.join(cacheDir, CACHE_FILE);
-  if (!existsSync(cachePath)) return {};
+export function loadCache(cacheDir) {
+  const cachePath = join(cacheDir, CACHE_FILE);
+  if (!existsSync(cachePath)) {
+    return {};
+  }
   try {
-    return JSON.parse(readFileSync(cachePath, 'utf8'));
-  } catch (e) {
-    logger.warn(`Could not read cache: ${e.message}`);
+    const raw = readFileSync(cachePath, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    // Corrupted cache — start fresh
     return {};
   }
 }
 
 /**
- * Save cache to .legacyver-cache/hashes.json.
- * @param {string} cacheDir
- * @param {Object} map
+ * 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
  */
-function saveCache(cacheDir, map) {
+export function saveCache(cacheDir, cacheMap) {
   mkdirSync(cacheDir, { recursive: true });
-  const cachePath = path.join(cacheDir, CACHE_FILE);
-  writeFileSync(cachePath, JSON.stringify(map, null, 2), 'utf8');
+  const cachePath = join(cacheDir, CACHE_FILE);
+  writeFileSync(cachePath, JSON.stringify(cacheMap, null, 2), 'utf-8');
 }
 
 /**
- * Separate files into cache hits and misses.
- * @param {Array} manifest  FileManifest[]
- * @param {Object} cacheMap
- * @returns {{ hits: Array, misses: Array }}
+ * 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[] }}
  */
-function getCacheHits(manifest, cacheMap) {
+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) {
@@ -50,35 +59,48 @@ function getCacheHits(manifest, cacheMap) {
       misses.push(file);
     }
   }
+
   return { hits, misses };
 }
 
 /**
- * Remove entries for files that no longer exist on disk.
- * @param {Object} cacheMap  mutated in place
- * @param {string[]} currentPaths  relative paths currently on disk
+ * 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
  */
-function purgeDeleted(cacheMap, currentPaths) {
-  const current = new Set(currentPaths);
-  for (const key of Object.keys(cacheMap)) {
-    if (!current.has(key)) {
-      delete cacheMap[key];
+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 it exists in projectRoot.
- * @param {string} projectRoot
+ * 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
  */
-function autoAddToGitignore(projectRoot) {
-  const gitignorePath = path.join(projectRoot, '.gitignore');
-  if (!existsSync(gitignorePath)) return;
-  const content = readFileSync(gitignorePath, 'utf8');
-  if (!content.includes('.legacyver-cache')) {
-    appendFileSync(gitignorePath, '\n.legacyver-cache/\n');
-    logger.info('Added .legacyver-cache/ to .gitignore');
+export function addToGitignore(projectRoot) {
+  const gitignorePath = join(projectRoot, '.gitignore');
+  if (!existsSync(gitignorePath)) {
+    return;
   }
-}
 
-module.exports = { loadCache, saveCache, getCacheHits, purgeDeleted, autoAddToGitignore };
+  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');
+}