legacyver 2.1.8 → 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

@@ -0,0 +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
+```
+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
-
-* [components.tsx](components.md)
+# 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 @@
-# src — Documentation
-
-**Primary language:** typescript  
-**Total files:** 1  
-**Analyzed at:** 2026-02-22T03:13:37.724Z  
-
-## Files
-
-- [components.tsx](components.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.

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

@@ -0,0 +1,70 @@
+## Overview
+The `loginCommand` function is an asynchronous command that handles the login process for the Legacyver CLI. It opens a browser to log in with GitHub, waits for the web app to redirect the token back, and saves the session.
+
+## Functions
+### openBrowser
+Opens a URL in the default browser (cross-platform).
+
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| url | string | The URL to open in the browser |
+
+#### Return Value
+None
+
+#### Body
+```javascript
+const { exec } = require('child_process');
+const cmd = process.platform === 'win32' ? `start "" "${url}"`
+  : process.platform === 'darwin' ? `open "${url}"`
+  : `xdg-open "${url}"`;
+exec(cmd);
+```
+This function uses the `child_process` module to execute a command to open the URL in the default browser. The command is platform-dependent, using `start` on Windows, `open` on macOS, and `xdg-open` on Linux.
+
+### loginCommand
+Spawns a temporary local HTTP server, opens the browser for GitHub OAuth, and waits for the web app to redirect the token back.
+
+#### Parameters
+None
+
+#### Return Value
+A Promise that resolves when the login is complete
+
+#### Body
+```javascript
+const session = loadSession();
+if (session.token) {
+  console.log(pc.yellow(`Already logged in as ${session.username} (${session.email}).`));
+  console.log(`Run ${pc.cyan('legacyver logout')} first to switch accounts.`);
+  return;
+}
+
+console.log(pc.bold('\nLegacyver Login\n'));
+console.log(pc.dim('Opening your browser to log in with GitHub...\n'));
+
+const code = crypto.randomBytes(16).toString('hex');
+
+return new Promise((resolve, reject) => {
+  const server = http.createServer((req, res) => {
+    // ...
+  });
+
+  // ...
+});
+```
+This function first checks if the user is already logged in. If not, it generates a random code and starts a local HTTP server. It then opens the browser to the GitHub OAuth page with the code as a query parameter. When the user logs in with GitHub, the web app redirects the token back to the local server, which saves the session and shuts down the server.
+
+## Dependencies
+* `http`
+* `crypto`
+* `picocolors`
+* `../../utils/config` (for `saveSession` and `loadSession`)
+
+## Usage Example
+To use the `loginCommand` function, simply call it as an asynchronous command:
+```javascript
+await loginCommand();
+```
+This will open the browser to log in with GitHub and wait for the web app to redirect the token back. Once the login is complete, the function will resolve and the CLI will continue running.

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

@@ -0,0 +1,26 @@
+## Overview
+This is a JavaScript module that exports a function `logoutCommand` which handles the logout process for a user. It checks if the user is logged in, revokes the token, and clears the local session.
+
+## Functions
+### logoutCommand
+#### Description
+This function handles the logout process for a user.
+
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| None |  | This function does not take any parameters. |
+
+#### Return Value
+None
+
+#### Body
+The function first loads the current session using `loadSession()`. If the session does not have a token, it logs a message indicating that the user is not logged in and returns. If the session has a token, it attempts to revoke the token using `revokeToken(session.token)`. If the token revocation fails, it catches the error and still clears the local session. Finally, it clears the session using `clearSession()` and logs a success message using `pc.green('Logged out.')`.
+
+## Dependencies
+* `picocolors` (as `pc`)
+* `../../utils/config` (for `loadSession` and `clearSession`)
+* `../../api/auth` (for `revokeToken`)
+
+## Usage Example
+No clear usage example is visible in the code.

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

@@ -0,0 +1,23 @@
+## Overview
+This is a command-line interface (CLI) function named `providersCommand` that displays information about supported LLM (Large Language Model) providers and their recommended models.
+
+## Functions
+### providersCommand
+#### Description
+Displays information about supported LLM providers and their recommended models.
+
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| None |  | This function does not take any parameters. |
+
+#### Return Value
+None
+
+## Dependencies
+* `picocolors` (as `pc`)
+* `../../utils/logger` (as `logger`)
+* `../../utils/config` (as `loadConfig` and `loadSession`)
+
+## Usage Example
+This function is designed to be called as a CLI command, and its output will display information about supported LLM providers and their recommended models. The exact output will depend on the environment variables set in the system, such as `GROQ_API_KEY`, `GEMINI_API_KEY`, `MOONSHOT_API_KEY`, and `OPENROUTER_API_KEY`.