legacyver 2.1.0 → 2.1.2

package/.opencode/skills/openspec-verify-change/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: openspec-verify-change
+description: Verify implementation matches change artifacts. Use when the user wants to validate that implementation is complete, correct, and coherent before archiving.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+Verify that an implementation matches the change artifacts (specs, tasks, design).
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have implementation tasks (tasks artifact exists).
+   Include the schema used for each change if available.
+   Mark changes with incomplete tasks as "(In Progress)".
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifacts exist for this change
+
+3. **Get the change directory and load artifacts**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns the change directory and context files. Read all available artifacts from `contextFiles`.
+
+4. **Initialize verification report structure**
+
+   Create a report structure with three dimensions:
+   - **Completeness**: Track tasks and spec coverage
+   - **Correctness**: Track requirement implementation and scenario coverage
+   - **Coherence**: Track design adherence and pattern consistency
+
+   Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
+
+5. **Verify Completeness**
+
+   **Task Completion**:
+   - If tasks.md exists in contextFiles, read it
+   - Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete)
+   - Count complete vs total tasks
+   - If incomplete tasks exist:
+     - Add CRITICAL issue for each incomplete task
+     - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
+
+   **Spec Coverage**:
+   - If delta specs exist in `openspec/changes/<name>/specs/`:
+     - Extract all requirements (marked with "### Requirement:")
+     - For each requirement:
+       - Search codebase for keywords related to the requirement
+       - Assess if implementation likely exists
+     - If requirements appear unimplemented:
+       - Add CRITICAL issue: "Requirement not found: <requirement name>"
+       - Recommendation: "Implement requirement X: <description>"
+
+6. **Verify Correctness**
+
+   **Requirement Implementation Mapping**:
+   - For each requirement from delta specs:
+     - Search codebase for implementation evidence
+     - If found, note file paths and line ranges
+     - Assess if implementation matches requirement intent
+     - If divergence detected:
+       - Add WARNING: "Implementation may diverge from spec: <details>"
+       - Recommendation: "Review <file>:<lines> against requirement X"
+
+   **Scenario Coverage**:
+   - For each scenario in delta specs (marked with "#### Scenario:"):
+     - Check if conditions are handled in code
+     - Check if tests exist covering the scenario
+     - If scenario appears uncovered:
+       - Add WARNING: "Scenario not covered: <scenario name>"
+       - Recommendation: "Add test or implementation for scenario: <description>"
+
+7. **Verify Coherence**
+
+   **Design Adherence**:
+   - If design.md exists in contextFiles:
+     - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
+     - Verify implementation follows those decisions
+     - If contradiction detected:
+       - Add WARNING: "Design decision not followed: <decision>"
+       - Recommendation: "Update implementation or revise design.md to match reality"
+   - If no design.md: Skip design adherence check, note "No design.md to verify against"
+
+   **Code Pattern Consistency**:
+   - Review new code for consistency with project patterns
+   - Check file naming, directory structure, coding style
+   - If significant deviations found:
+     - Add SUGGESTION: "Code pattern deviation: <details>"
+     - Recommendation: "Consider following project pattern: <example>"
+
+8. **Generate Verification Report**
+
+   **Summary Scorecard**:
+   ```
+   ## Verification Report: <change-name>
+
+   ### Summary
+   | Dimension    | Status           |
+   |--------------|------------------|
+   | Completeness | X/Y tasks, N reqs|
+   | Correctness  | M/N reqs covered |
+   | Coherence    | Followed/Issues  |
+   ```
+
+   **Issues by Priority**:
+
+   1. **CRITICAL** (Must fix before archive):
+      - Incomplete tasks
+      - Missing requirement implementations
+      - Each with specific, actionable recommendation
+
+   2. **WARNING** (Should fix):
+      - Spec/design divergences
+      - Missing scenario coverage
+      - Each with specific recommendation
+
+   3. **SUGGESTION** (Nice to fix):
+      - Pattern inconsistencies
+      - Minor improvements
+      - Each with specific recommendation
+
+   **Final Assessment**:
+   - If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
+   - If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
+   - If all clear: "All checks passed. Ready for archive."
+
+**Verification Heuristics**
+
+- **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
+- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
+- **Coherence**: Look for glaring inconsistencies, don't nitpick style
+- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
+- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
+
+**Graceful Degradation**
+
+- If only tasks.md exists: verify task completion only, skip spec/design checks
+- If tasks + specs exist: verify completeness and correctness, skip design
+- If full artifacts: verify all three dimensions
+- Always note which checks were skipped and why
+
+**Output Format**
+
+Use clear markdown with:
+- Table for summary scorecard
+- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
+- Code references in format: `file.ts:123`
+- Specific, actionable recommendations
+- No vague suggestions like "consider reviewing"

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 legacyver contributors
+Copyright (c) 2024 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,8 +1,14 @@
-# legacyver
+# Legacyver
 
-Generate technical documentation from undocumented or legacy codebases using AST parsing and LLMs.
+Auto-generate technical documentation for legacy and undocumented codebases using AST parsing + 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.
+```bash
+npx legacyver analyze ./src
+```
+
+No documentation written beforehand. No configuration required. One command.
+
+---
 
 ## Install
 
@@ -10,144 +16,183 @@ Legacyver crawls your source code, extracts structural facts with AST parsers (T
 npm install -g legacyver
 ```
 
-Requires Node.js >= 18.0.0.
+Or use without installing:
+
+```bash
+npx legacyver analyze ./src
+```
+
+---
 
 ## Quick Start
 
+**1. Initialize (saves your API key):**
+
 ```bash
-# 1. Run the setup wizard
 legacyver init
+```
 
-# 2. Generate documentation
-legacyver analyze ./src
+**2. Analyze a codebase:**
 
-# 3. View output
-open legacyver-docs/index.md
+```bash
+legacyver analyze ./src
 ```
 
-### Using Ollama (Free, Local)
-
-No API key required — just have [Ollama](https://ollama.ai) running:
+**3. View the output:**
 
-```bash
-legacyver analyze ./src --provider ollama
+```
+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
+    ...
 ```
 
-## CLI Reference
+---
 
-### `legacyver analyze <path>`
+## CLI Commands
 
-Main command. Analyzes a codebase and generates documentation.
+### `legacyver analyze <dir>`
 
-| 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` |
+Run the full documentation pipeline.
+
+| 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 |
 
 ### `legacyver init`
 
-Interactive setup wizard. Configures your preferred LLM provider, saves API keys to OS user config, and creates a `.legacyverrc` file.
+Interactive wizard. Detects existing `.legacyverrc` and warns before overwriting. Saves API key to OS user config.
 
 ### `legacyver providers`
 
-Lists all supported providers with API key status and pricing.
+List all supported providers, API key status, and per-model pricing.
 
 ### `legacyver cache clear`
 
-Deletes the `.legacyver-cache/` directory.
+Delete the `.legacyver-cache/` directory to force full re-analysis on next run.
+
+### `legacyver --version`
 
-## Configuration
+Print the installed version.
 
-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
 
-### `.legacyverrc` Schema
+Create a `.legacyverrc` (JSON or YAML) in your project root:
 
 ```json
 {
-  "provider": "anthropic",
-  "model": null,
+  "provider": "openrouter",
+  "model": "meta-llama/llama-3.3-70b-instruct:free",
   "format": "markdown",
-  "output": "./legacyver-docs",
-  "concurrency": 5,
+  "out": "./legacyver-docs",
+  "concurrency": 3,
   "maxFileSizeKb": 500,
-  "incremental": false,
-  "ignore": ["test/**", "**/*.test.*"],
-  "languages": ["javascript", "typescript", "python", "java", "go"]
+  "incremental": true
 }
 ```
 
-CLI flags always take precedence over config file values.
+All fields are optional. CLI flags override file config.
+
+Also supported: `legacyver.config.js`, `legacyver.config.yaml`.
+
+---
 
 ## 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 |
+| 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) |
 
-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.
+**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
 
-## 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) |
+## Supported LLM Providers
 
-## Ignore Rules
+| 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` |
 
-Legacyver respects a `.legacyverignore` file (same syntax as `.gitignore`) in your project root.
+**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.
 
-Default ignores include: `node_modules`, `.git`, `dist`, `build`, `__pycache__`, `venv`, `vendor`, minified files, lock files, and more.
+---
 
-## CI/CD Integration
+## Ignore Files
 
-Legacyver auto-detects non-interactive environments (no TTY) and disables spinners/prompts. For CI pipelines:
+Create a `.legacyverignore` in your project root using gitignore syntax:
 
-```bash
-legacyver analyze ./src --provider openai --no-confirm --json-summary
+```
+# .legacyverignore
+dist/
+build/
+coverage/
+*.min.js
 ```
 
-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).
+See `.legacyverignore.example` for a documented example.
 
-### Incremental Builds
+---
 
-Use `--incremental` to skip unchanged files between CI runs:
+## CI/CD Integration
 
-```bash
-legacyver analyze ./src --incremental --no-confirm
+```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
 ```
 
-Cache is stored in `.legacyver-cache/` (auto-added to `.gitignore`).
+Legacyver detects non-TTY environments and disables spinners/progress bars automatically (plain log output only).
+
+---
 
 ## 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
+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
+```
+
+---
 
 ## License
 

package/bin/legacyver.js

@@ -1,33 +1,56 @@
 #!/usr/bin/env node
+'use strict';
 
-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 { program } = require('commander');
+const { readFileSync } = require('fs');
+const { join } = require('path');
 
-const require = createRequire(import.meta.url);
-const pkg = require('../package.json');
-
-const program = new Command();
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
 
 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);
+  .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');
+
+// 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);
 
 program.parse(process.argv);

package/legacyver-docs/SUMMARY.md

@@ -0,0 +1,3 @@
+# Summary
+
+* [components.tsx](components.md)

package/legacyver-docs/components.md

@@ -0,0 +1,57 @@
+## Overview
+This file contains React components and a utility function for formatting currency amounts.
+
+## Functions
+
+### formatCurrency
+
+#### Description
+Formats a given amount as a string in a specified currency.
+
+#### Params Table
+
+| Name | Type |
+| --- | --- |
+| `amount` | `number` |
+| `currency` | `string`, defaults to `'USD'` |
+
+#### Return Value
+A formatted string representing the currency amount.
+
+```typescript
+export function formatCurrency(amount: number, currency: string = 'USD'): string {
+  return new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(amount);
+}
+```
+
+## Dependencies
+
+* `react`
+* `intl`
+
+## Overview
+This file appears to contain UI components, with buttons and cards used for user representation.
+
+## Functions
+
+### Button
+#### Description
+A button component that can trigger an action.
+#### Params Table
+| Param | Type | Required |
+| --- | --- | --- |
+| - | - | No |
+#### Return Value
+N/A
+
+### UserCard
+#### Description
+A card component representing a user.
+#### Params Table
+| Param | Type | Required |
+| --- | --- | --- |
+| - | - | Yes |
+
+## Dependencies
+* `@ui-component/library` (UI components library)
+* `@utils/typography` (Typography utilities)

package/legacyver-docs/index.md

@@ -0,0 +1,15 @@
+# src — Documentation
+
+**Primary language:** typescript  
+**Total files:** 1  
+**Analyzed at:** 2026-02-21T07:52:12.371Z  
+
+## Files
+
+- [components.tsx](components.md)
+
+## Dependency Graph
+
+```mermaid
+graph TD
+```

package/nul

@@ -0,0 +1,2 @@
+dir: cannot access '/b': No such file or directory
+dir: cannot access '/s': No such file or directory