legacyver 3.0.0 → 3.1.0

package/bin/legacyver.js

@@ -1,8 +1,6 @@
 #!/usr/bin/env node
 'use strict';
 
-require('dotenv').config();
-
 const { program } = require('commander');
 const { readFileSync } = require('fs');
 const { join } = require('path');
@@ -20,16 +18,16 @@ 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('--out <dir>', 'Output directory (default: ./legacyver-docs)')
+  .option('--format <fmt>', 'Output format: markdown | html | json (default: markdown)')
   .option('--model <model>', 'LLM model to use')
-  .option('--provider <provider>', 'LLM provider: groq | ollama', 'groq')
-  .option('--concurrency <n>', 'Concurrent LLM requests (1-10)', '3')
+  .option('--provider <provider>', 'LLM provider: openrouter | groq | gemini | kimi | ollama (default: openrouter)')
+  .option('--concurrency <n>', 'Concurrent LLM requests 1-10 (default: 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('--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')
+  .option('--max-file-size <kb>', 'Skip files larger than this size in KB (default: 500)')
   .action(analyzeCmd);
 
 // init command

package/legacyver-docs/OrderController.md

@@ -1,80 +1,80 @@
-## Overview
-This is the `OrderController` class, responsible for handling CRUD (Create, Read, Update, Delete) operations on orders. It provides a RESTful API interface to interact with the order data.
-
-## Functions
-
-### index
-#### Description
-Returns a paginated list of orders.
-#### Parameters
-| Parameter | Type | Required |
-| --- | --- | --- |
-| `paginate` | int | - |
-| `response` | object | - |
-| `json` | function | - |
-
-#### Return Value
-A `JsonResponse` containing the paginated list of orders.
-
-### store
-#### Description
-Creates a new order and returns its details.
-#### Parameters
-| Parameter | Type | Required |
-| --- | --- | --- |
-| `$request:StoreOrderRequest` | object | Yes |
-
-#### Return Value
-A `JsonResponse` with the created order data and HTTP status code 201.
-
-### show
-#### Description
-Returns a single order by its ID.
-#### Parameters
-| Parameter | Type | Required |
-| --- | --- | --- |
-| `$id:int` | int | Yes |
-
-#### Return Value
-A `JsonResponse` containing the order details.
-
-### update
-#### Description
-Updates an existing order.
-#### Parameters
-| Parameter | Type | Required |
-| --- | --- | --- |
-| `$request:UpdateOrderRequest` | object | Yes |
-| `$id:int` | int | Yes |
-
-#### Return Value
-A `JsonResponse` with the updated order data.
-
-### destroy
-#### Description
-Deletes an existing order.
-#### Parameters
-| Parameter | Type | Required |
-| --- | --- | --- |
-| `$id:int` | int | Yes |
-
-#### Return Value
-A `JsonResponse` with HTTP status code 204.
-
-## Dependencies
-
-* `App\Models\Order`
-* `App\Models\User`
-* `App\Http\Requests\StoreOrderRequest`
-* `App\Http\Requests\UpdateOrderRequest`
-* `App\Services\OrderService`
-* `Illuminate\Http\JsonResponse`
-
-## Usage Example
-```php
-$orderController = new OrderController();
-$orders = $orderController->index(); // returns paginated list of orders
-
-$order = $orderController->store(new StoreOrderRequest(['name' => 'New Order'])); // creates and returns order details
-```
+## Overview
+This is the `OrderController` class, responsible for handling CRUD (Create, Read, Update, Delete) operations on orders. It provides a RESTful API interface to interact with the order data.
+
+## Functions
+
+### index
+#### Description
+Returns a paginated list of orders.
+#### Parameters
+| Parameter | Type | Required |
+| --- | --- | --- |
+| `paginate` | int | - |
+| `response` | object | - |
+| `json` | function | - |
+
+#### Return Value
+A `JsonResponse` containing the paginated list of orders.
+
+### store
+#### Description
+Creates a new order and returns its details.
+#### Parameters
+| Parameter | Type | Required |
+| --- | --- | --- |
+| `$request:StoreOrderRequest` | object | Yes |
+
+#### Return Value
+A `JsonResponse` with the created order data and HTTP status code 201.
+
+### show
+#### Description
+Returns a single order by its ID.
+#### Parameters
+| Parameter | Type | Required |
+| --- | --- | --- |
+| `$id:int` | int | Yes |
+
+#### Return Value
+A `JsonResponse` containing the order details.
+
+### update
+#### Description
+Updates an existing order.
+#### Parameters
+| Parameter | Type | Required |
+| --- | --- | --- |
+| `$request:UpdateOrderRequest` | object | Yes |
+| `$id:int` | int | Yes |
+
+#### Return Value
+A `JsonResponse` with the updated order data.
+
+### destroy
+#### Description
+Deletes an existing order.
+#### Parameters
+| Parameter | Type | Required |
+| --- | --- | --- |
+| `$id:int` | int | Yes |
+
+#### Return Value
+A `JsonResponse` with HTTP status code 204.
+
+## Dependencies
+
+* `App\Models\Order`
+* `App\Models\User`
+* `App\Http\Requests\StoreOrderRequest`
+* `App\Http\Requests\UpdateOrderRequest`
+* `App\Services\OrderService`
+* `Illuminate\Http\JsonResponse`
+
+## Usage Example
+```php
+$orderController = new OrderController();
+$orders = $orderController->index(); // returns paginated list of orders
+
+$order = $orderController->store(new StoreOrderRequest(['name' => 'New Order'])); // creates and returns order details
+```
 Note: The usage example is just a demonstration and should be replaced with actual usage scenarios.

package/legacyver-docs/SUMMARY.md

@@ -1,3 +1,3 @@
-# Summary
-
+# Summary
+
 * [OrderController.php](OrderController.md)

package/legacyver-docs/bin/legacyver.md

@@ -0,0 +1,107 @@
+## Overview
+The `legacyver` CLI tool is an AI-powered tool for auto-generating technical documentation from legacy/undocumented codebases. It provides various commands for analysis, initialization, provider management, caching, login, logout, and pushing documentation to the cloud.
+
+## Functions
+### `analyzeCmd`
+#### Description
+Analyze a directory and generate documentation.
+
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| `target` | string | The directory to analyze. |
+| `--out <dir>` | string | Output directory (default: `./legacyver-docs`). |
+| `--format <fmt>` | string | Output format: `markdown`, `html`, or `json` (default: `markdown`). |
+| `--model <model>` | string | LLM model to use. |
+| `--provider <provider>` | string | LLM provider: `groq` or `ollama` (default: `groq`). |
+| `--concurrency <n>` | number | Concurrent LLM requests (1-10) (default: `3`). |
+| `--dry-run` | boolean | Run AST parsing only, no LLM calls. |
+| `--incremental` | boolean | Only re-analyze changed files. |
+| `--no-confirm` | boolean | Skip cost confirmation prompt. |
+| `--json-summary` | boolean | Output machine-readable JSON summary. |
+| `--max-file-size <kb>` | number | Skip files larger than this size in KB (default: `500`). |
+
+#### Return Value
+None
+
+### `initCmd`
+#### Description
+Interactive setup wizard — saves API key and creates `.legacyverrc`.
+
+#### Parameters
+None
+
+#### Return Value
+None
+
+### `providersCmd`
+#### Description
+List supported LLM providers and available models.
+
+#### Parameters
+None
+
+#### Return Value
+None
+
+### `cacheCmd`
+#### Description
+Manage the incremental analysis cache.
+
+#### Parameters
+None
+
+#### Return Value
+None
+
+### `loginCmd`
+#### Description
+Log in to sync generated docs to the cloud.
+
+#### Parameters
+None
+
+#### Return Value
+None
+
+### `logoutCmd`
+#### Description
+Log out and stop syncing docs to the cloud.
+
+#### Parameters
+None
+
+#### Return Value
+None
+
+### `pushCmd`
+#### Description
+Manually push generated docs to the cloud database.
+
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| `target` | string | The directory to push from. |
+| `--out <dir>` | string | Docs output directory to read from (default: `./legacyver-docs`). |
+
+#### Return Value
+None
+
+## Dependencies
+* `commander`
+* `fs`
+* `path`
+* `dotenv`
+* `../src/cli/commands/analyze`
+* `../src/cli/commands/init`
+* `../src/cli/commands/providers`
+* `../src/cli/commands/cache`
+* `../src/cli/commands/login`
+* `../src/cli/commands/logout`
+* `../src/cli/commands/push`
+
+## Usage Example
+```bash
+legacyver analyze my-project --out docs --format markdown
+```
+This command analyzes the `my-project` directory, generates documentation in Markdown format, and outputs it to the `docs` directory.

package/legacyver-docs/index.md

@@ -1,15 +1,15 @@
-# Controllers — Documentation
-
-**Primary language:** php  
-**Total files:** 1  
-**Analyzed at:** 2026-02-22T03:45:37.186Z  
-
-## Files
-
-- [OrderController.php](OrderController.md)
-
-## Dependency Graph
-
-```mermaid
-graph TD
-```
+# Controllers — Documentation
+
+**Primary language:** php  
+**Total files:** 1  
+**Analyzed at:** 2026-02-22T03:45:37.186Z  
+
+## Files
+
+- [OrderController.php](OrderController.md)
+
+## Dependency Graph
+
+```mermaid
+graph TD
+```

package/legacyver-docs/src/api/auth.md

@@ -0,0 +1,47 @@
+## Overview
+This module provides two functions for managing CLI session tokens: `validateToken` and `revokeToken`. These functions interact with a PostgreSQL database to validate and revoke tokens.
+
+## Functions
+
+### validateToken
+Validates a CLI session token against app.user_sessions.
+
+* **Description**: Returns user info if valid, null if expired/revoked/not found.
+* **Params**:
+	+ `token`: raw token from ~/.legacyver/session.json (string)
+	+ `opts`: optional overrides for testing (object)
+		- `pool`: pg Pool instance (object)
+* **Return Value**: Promise<{userId: string, username: string, email: string} | null>
+
+### revokeToken
+Revoke a CLI session token (logout).
+
+* **Description**: Revoke a CLI session token.
+* **Params**:
+	+ `token`: raw token (string)
+	+ `opts`: optional overrides for testing (object)
+		- `pool`: pg Pool instance (object)
+* **Return Value**: None
+
+## Dependencies
+* `crypto`: crypto module
+* `pg`: pg module
+* `../db/config`: dbConfig module
+
+## Usage Example
+```javascript
+const { validateToken, revokeToken } = require('./auth');
+
+// Validate a token
+const token = 'your_token_here';
+const opts = { pool: your_pool_instance };
+validateToken(token, opts).then((userInfo) => {
+  console.log(userInfo);
+});
+
+// Revoke a token
+const token = 'your_token_here';
+revokeToken(token, opts).then(() => {
+  console.log('Token revoked');
+});
+```

package/legacyver-docs/src/cache/hash.md

@@ -0,0 +1,24 @@
+## Overview
+This module provides a function to compute the SHA-256 hash of a file.
+
+## Functions
+### computeHash
+Computes the SHA-256 hash of a file.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| filePath | string | Path to the file to compute the hash for |
+
+| Return Value | Type | Description |
+| --- | --- | --- |
+| string | The SHA-256 hash as a hex string prefixed with 'sha256:' |
+
+## Dependencies
+* crypto: createHash
+* fs: readFileSync
+
+## Usage Example
+```javascript
+const { computeHash } = require('./hash');
+console.log(computeHash('path/to/file.txt'));
+```

package/legacyver-docs/src/cache/index.md

@@ -0,0 +1,112 @@
+## Overview
+This module provides functions for managing a cache of file hashes in a `.legacyver-cache` directory. It includes functions for loading and saving the cache, separating files into cache hits and misses, removing entries for files that no longer exist on disk, and auto-adding the cache directory to `.gitignore`.
+
+## Functions
+
+### loadCache
+Load cache from `.legacyver-cache/hashes.json`.
+
+* **Params:**
+	+ `cacheDir`: string
+* **Returns:** Object
+	+ map of relativePath -> { hash, docFile, generatedAt }
+
+```javascript
+function loadCache(cacheDir) {
+  const cachePath = path.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}`);
+    return {};
+  }
+}
+```
+
+### saveCache
+Save cache to `.legacyver-cache/hashes.json`.
+
+* **Params:**
+	+ `cacheDir`: string
+	+ `map`: Object
+* **Returns:** None
+
+```javascript
+function saveCache(cacheDir, map) {
+  mkdirSync(cacheDir, { recursive: true });
+  const cachePath = path.join(cacheDir, CACHE_FILE);
+  writeFileSync(cachePath, JSON.stringify(map, null, 2), 'utf8');
+}
+```
+
+### getCacheHits
+Separate files into cache hits and misses.
+
+* **Params:**
+	+ `manifest`: Array of FileManifest[]
+	+ `cacheMap`: Object
+* **Returns:** { hits: Array, misses: Array }
+
+```javascript
+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 };
+}
+```
+
+### purgeDeleted
+Remove entries for files that no longer exist on disk.
+
+* **Params:**
+	+ `cacheMap`: Object (mutated in place)
+	+ `currentPaths`: string[]
+
+```javascript
+function purgeDeleted(cacheMap, currentPaths) {
+  const current = new Set(currentPaths);
+  for (const key of Object.keys(cacheMap)) {
+    if (!current.has(key)) {
+      delete cacheMap[key];
+    }
+  }
+}
+```
+
+### autoAddToGitignore
+Auto-add `.legacyver-cache/` to `.gitignore` if it exists in `projectRoot`.
+
+* **Params:**
+	+ `projectRoot`: string
+* **Patterns:**
+	+ arithmetic (used for appending to `.gitignore`)
+
+```javascript
+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');
+  }
+}
+```
+
+## Dependencies
+
+* `fs`: readFileSync, writeFileSync, mkdirSync, existsSync, appendFileSync
+* `path`: path
+* `../utils/logger`: logger
+
+## Usage Example
+No clear pattern is visible in the code.

package/legacyver-docs/src/cli/commands/analyze.md

@@ -0,0 +1,58 @@
+## Overview
+The `analyzeCommand` function is the main entry point for the `analyze` CLI command. It takes a `target` directory and `flags` object as input, and performs a series of tasks to analyze the files in the target directory.
+
+## Functions
+### analyzeCommand
+#### Description
+Analyzes the files in the target directory using a series of stages, including crawling, incremental caching, AST parsing, dry run estimation, free model policy application, cost gate checking, and LLM engine execution.
+
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| target | string | The target directory to analyze |
+| flags | object | The CLI flags object |
+
+#### Return Value
+No return value
+
+#### Dependencies
+* `loadConfig`
+* `crawl`
+* `parseFiles`
+* `estimateCost`
+* `applyFreeModelPolicy`
+* `createProvider`
+* `validateFragment`
+* `reprompt`
+* `createQueue`
+* `buildChunks`
+
+## Dependencies
+* `path`
+* `loadConfig`
+* `createSpinner`
+* `createProgressBar`
+* `confirmPrompt`
+* `printSummary`
+* `logger`
+* `picocolors`
+* `NoApiKeyError`
+* `crawl`
+* `cache`
+* `parseFiles`
+* `estimateCost`
+* `buildChunks`
+* `applyFreeModelPolicy`
+* `createProvider`
+* `validateFragment`
+* `reprompt`
+* `createQueue`
+* `pushToDatabase`
+* `loadSession`
+
+## Usage Example
+The `analyzeCommand` function can be used by running the `analyze` CLI command with the `--target` option followed by the target directory, and any desired flags. For example:
+```bash
+legacyver analyze --target /path/to/directory --provider groq --model my-model
+```
+This will perform the analysis on the files in the specified directory using the Groq provider and my-model model.

package/legacyver-docs/src/cli/commands/cache.md

@@ -0,0 +1,21 @@
+## Overview
+This module exports a single asynchronous function, `cacheClearCommand`, which clears the cache directory.
+
+## Functions
+### cacheClearCommand
+Clears the cache directory.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| None |  |  |
+
+Return Value:
+No return value.
+
+## Dependencies
+* `fs`: `existsSync`, `rmSync`
+* `path`: `join`
+* `picocolors`: `pc`
+
+## Usage Example
+The function clears the cache directory located at `.legacyver-cache/` in the current working directory. If the directory exists, it is deleted recursively with force. If the directory does not exist, a message indicating that no cache directory was found is logged.

package/legacyver-docs/src/cli/commands/init.md

@@ -0,0 +1,42 @@
+## Overview
+The `initCommand` function is the main entry point for the Legacyver setup wizard, responsible for guiding the user through the setup process and creating a configuration file.
+
+## Functions
+### ask
+#### Description
+Asks a question to the user and returns a promise that resolves with the user's response.
+
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| `rl` | `readline.Interface` | The readline interface to use for asking the question. |
+| `question` | `string` | The question to ask the user. |
+
+#### Return Value
+A promise that resolves with the user's response.
+
+### initCommand
+#### Description
+The main entry point for the Legacyver setup wizard, responsible for guiding the user through the setup process and creating a configuration file.
+
+#### Parameters
+None
+
+#### Return Value
+None
+
+## Dependencies
+* `fs`: `existsSync`, `writeFileSync`
+* `path`: `join`
+* `readline`: `readline.createInterface`
+* `picocolors`: `pc`
+
+## Usage Example
+The `initCommand` function can be used as a standalone command to guide the user through the setup process and create a configuration file. For example:
+```javascript
+const initCommand = require('./init');
+initCommand().then(() => {
+  console.log('Setup complete!');
+});
+```
+Note: This example assumes that the `initCommand` function is exported from the `init.js` file.