legacyver 2.1.8 → 3.1.0

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

@@ -0,0 +1,48 @@
+## Overview
+The `pushCommand` function is a CLI command that manually pushes existing generated documentation to the cloud database. It reads markdown files from the output directory and pushes them as documentation pages.
+
+## Functions
+### pushCommand
+#### Description
+Manually push existing generated docs to the cloud database.
+
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| target | string | The directory to read markdown files from (default: current directory) |
+| options | object | Options object (contains `out` property) |
+
+#### Return Value
+No return value
+
+#### Detected Patterns
+* Arithmetic operations are used to calculate the number of markdown files found in the output directory.
+
+### collectMarkdownFiles
+#### Description
+Recursively collect .md files from a directory. Each file becomes a fragment with { relativePath, content }.
+
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| baseDir | string | The base directory to resolve relative paths from |
+| dir | string | The directory to read files from |
+| results | array | The array to store the collected fragments |
+
+#### Return Value
+No return value
+
+## Dependencies
+* `path`
+* `fs`
+* `picocolors`
+* `loadSession` from `../../utils/config`
+* `logger` from `../../utils/logger`
+* `ora`
+* `pushToDatabase` from `../../db/index`
+
+## Usage Example
+No clear pattern is visible in the code, but the function can be used as follows:
+```bash
+legacyver push [target]
+```

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

@@ -0,0 +1,26 @@
+## Overview
+This module exports a function `versionCommand` that prints the version of the package to the console.
+
+## Functions
+### versionCommand
+Prints the version of the package to the console.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| None |  |  |
+
+| Return Value | Type | Description |
+| --- | --- | --- |
+| None |  |  |
+
+## Dependencies
+* `fs: readFileSync`
+* `path: join`
+
+## Usage Example
+The function can be used as follows:
+```javascript
+const version = require('./version');
+version.versionCommand();
+```
+This will print the version of the package to the console.

package/legacyver-docs/src/cli/ui.md

@@ -0,0 +1,112 @@
+## Overview
+This module exports four functions for creating a spinner, progress bar, confirming a prompt, and printing a summary of analysis results.
+
+## Functions
+
+### createSpinner(text)
+Creates a spinner object for displaying a text message.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| text | string | The text to display in the spinner |
+
+| Return Value | Type | Description |
+| --- | --- | --- |
+| object |  | An object with methods for starting, succeeding, failing, warning, stopping, and getting the text |
+
+#### Usage
+```javascript
+const spinner = createSpinner('Analyzing...');
+spinner.start('Starting...');
+spinner.succeed('Done!');
+```
+
+### createProgressBar(total)
+Creates a progress bar object for displaying a progress bar.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| total | number | The total number of items to process |
+
+| Return Value | Type | Description |
+| --- | --- | --- |
+| object |  | An object with methods for starting, incrementing, and stopping the progress bar |
+
+#### Usage
+```javascript
+const progressBar = createProgressBar(100);
+progressBar.start();
+for (let i = 0; i < 100; i++) {
+  progressBar.increment();
+}
+progressBar.stop();
+```
+
+### confirmPrompt(message)
+Asynchronously confirms a prompt with the user.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| message | string | The message to display to the user |
+
+| Return Value | Type | Description |
+| --- | --- | --- |
+| Promise |  | A promise that resolves to a boolean indicating whether the user confirmed |
+
+#### Usage
+```javascript
+confirmPrompt('Are you sure?').then((confirmed) => {
+  if (confirmed) {
+    console.log('Confirmed!');
+  } else {
+    console.log('Not confirmed!');
+  }
+});
+```
+
+### printSummary(stats)
+Prints a summary of analysis results.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| stats | object | The analysis results |
+
+| Return Value | Type | Description |
+| --- | --- | --- |
+| void |  | No return value |
+
+#### Usage
+```javascript
+const stats = { filesAnalyzed: 100, filesCached: 20, filesSkipped: 10 };
+printSummary(stats);
+```
+
+## Dependencies
+
+* `ora`: for creating a spinner
+* `cli-progress`: for creating a progress bar
+* `readline`: for reading input from the user
+* `picocolors`: for coloring console output
+* `../utils/config`: for loading the session configuration
+
+## Usage Example
+```javascript
+const { createSpinner, createProgressBar, confirmPrompt, printSummary } = require('./cli/ui');
+
+const spinner = createSpinner('Analyzing...');
+spinner.start('Starting...');
+confirmPrompt('Are you sure?').then((confirmed) => {
+  if (confirmed) {
+    const progressBar = createProgressBar(100);
+    progressBar.start();
+    for (let i = 0; i < 100; i++) {
+      progressBar.increment();
+    }
+    progressBar.stop();
+    const stats = { filesAnalyzed: 100, filesCached: 20, filesSkipped: 10 };
+    printSummary(stats);
+  } else {
+    console.log('Not confirmed!');
+  }
+});
+```

package/legacyver-docs/src/crawler/filters.md

@@ -0,0 +1,54 @@
+## Overview
+This module provides functions for detecting the language of a file based on its extension and detecting the primary language of a list of files.
+
+## Functions
+
+### detectLanguage(ext)
+Detects the language of a file based on its extension.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| ext | string | The file extension to detect the language for |
+
+| Return Value | Type | Description |
+| --- | --- | --- |
+| language | string | The detected language, or null if not found |
+
+### detectPrimaryLanguage(files)
+Detects the primary language of a list of files.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| files | array | The list of files to detect the primary language for |
+
+| Return Value | Type | Description |
+| --- | --- | --- |
+| language | string | The primary language detected |
+
+## Dependencies
+* `Object.entries()`
+* `Object.values()`
+* `flat()`
+
+## Usage Example
+```javascript
+const files = [
+  { language: 'javascript' },
+  { language: 'typescript' },
+  { language: 'javascript' },
+];
+
+const primaryLanguage = detectPrimaryLanguage(files);
+console.log(primaryLanguage); // Output: javascript
+```
+
+Based on the provided code, here are the documentation for the missing exported symbols:
+
+## LANGUAGE_EXTENSIONS
+A list of language extensions supported by the module.
+
+## ALL_EXTENSIONS
+A list of all extensions supported by the module.
+
+## DEFAULT_IGNORE_PATTERNS
+A list of default patterns to ignore when processing files.

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

@@ -0,0 +1,54 @@
+## Overview
+This is a JavaScript module that exports a single function, `crawl`, which is the main entrypoint for a file crawler. The `crawl` function takes a target directory and a configuration object as input and returns an object containing a list of files, skipped files, and metadata about the crawled directory.
+
+## Functions
+### crawl
+#### Description
+The `crawl` function is the main entrypoint for the file crawler. It takes a target directory and a configuration object as input and returns an object containing a list of files, skipped files, and metadata about the crawled directory.
+
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| targetDir | string | The target directory to crawl. |
+| config | Object | The configuration object for the crawler. |
+
+#### Return Value
+An object containing the following properties:
+| Name | Type | Description |
+| --- | --- | --- |
+| files | FileManifest[] | A list of files in the crawled directory. |
+| skipped | Object[] | A list of files that were skipped due to size or other reasons. |
+| meta | Object | Metadata about the crawled directory, including the primary language, framework, and total number of files. |
+
+#### Body Logic
+The `crawl` function performs the following steps:
+1. Calculates the maximum file size in bytes based on the configuration object.
+2. Walks the target directory using the `walk` function and builds a manifest of files using the `buildManifest` function.
+3. Applies a size filter to the manifest, skipping files that exceed the maximum size.
+4. Detects the primary language of the files using the `detectPrimaryLanguage` function.
+5. Detects whether the directory is a Laravel project by checking for the presence of the `artisan` and `app` directories.
+6. Returns an object containing the filtered files, skipped files, and metadata about the crawled directory.
+
+## Dependencies
+* `fs`: for the `existsSync` function
+* `path`: for path manipulation
+* `./walk`: for walking the target directory
+* `./manifest`: for building the file manifest
+* `./filters`: for detecting the primary language
+* `../utils/logger`: for logging messages
+
+## Usage Example
+```javascript
+const { crawl } = require('./index');
+
+const targetDir = '/path/to/directory';
+const config = {
+  maxFileSizeKb: 1024,
+};
+
+crawl(targetDir, config).then((result) => {
+  console.log(result.files);
+  console.log(result.skipped);
+  console.log(result.meta);
+});
+```

package/legacyver-docs/src/crawler/manifest.md

@@ -0,0 +1,22 @@
+## Overview
+The `buildManifest` function generates a list of file manifests from a list of absolute file paths.
+
+## Functions
+### buildManifest
+Build a FileManifest[] from a list of absolute paths.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| absPaths | string[] | List of absolute file paths. |
+| targetDir | string | Target directory for relative path calculation. |
+
+Returns: `import('./index').FileManifest[]`
+
+## Dependencies
+* `crypto: createHash`
+* `fs: statSync, readFileSync`
+* `path: path`
+* `./filters: detectLanguage`
+
+## Usage Example
+The `buildManifest` function takes a list of absolute file paths and a target directory, and returns a list of file manifests. Each file manifest contains the relative path, absolute path, language, size in bytes, and SHA-256 hash of the file. If a file is unreadable, its hash is set to `null`.

package/legacyver-docs/src/crawler/walk.md

@@ -0,0 +1,29 @@
+## Overview
+The `walk` function is used to walk a directory and return all matching source file paths. It takes a target directory and a configuration object as input.
+
+## Functions
+### walk
+* Description: Walk a directory and return all matching source file paths.
+* Parameters:
+	+ `targetDir`: The target directory to walk.
+	+ `config`: The configuration object.
+* Return Value: An array of absolute paths.
+
+## Dependencies
+* `fast-glob`: `fg`
+* `ignore`: `ignore`
+* `fs`: `readFileSync`, `existsSync`
+* `path`: `path`
+* `./filters`: `DEFAULT_IGNORE_PATTERNS`, `ALL_EXTENSIONS`
+
+## Usage Example
+The `walk` function can be used as follows:
+```javascript
+const walk = require('./walk');
+const targetDir = '/path/to/directory';
+const config = {};
+
+const paths = await walk(targetDir, config);
+console.log(paths);
+```
+Note: The usage example is not directly extracted from the code, but rather inferred based on the function's purpose and parameters.

package/legacyver-docs/src/db/config.md

@@ -0,0 +1,13 @@
+## Overview
+This module exports a PostgreSQL connection configuration for the Legacyver hackathon database, using SSL with a self-signed certificate.
+
+## Functions
+### None
+
+## Dependencies
+* `module.exports`
+
+## Usage Example
+None, as this module only exports a configuration object.
+
+Note: This module does not contain any functions, only a configuration object that is exported. The usage example is not applicable in this case.

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

@@ -0,0 +1,86 @@
+  ## Overview
+This module provides a set of functions for interacting with a PostgreSQL database, specifically for managing repositories and documentation. It uses a lazy singleton pool to connect to the database.
+
+## Functions
+
+### getPool
+#### Description
+Lazy singleton pool — created on first use, ended after push.
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| None |  |  |
+#### Return Value
+`Pool` instance
+
+### getOrCreateRepo
+#### Description
+Find or create a repository for the given user + project path.
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| pool | `Pool` | Database connection pool |
+| userId | `string` | User ID (BIGINT as string) |
+| projectPath | `string` | Absolute path of the analyzed directory |
+#### Return Value
+`Promise<string>` repository ID (UUID)
+
+### getOrCreateDocumentation
+#### Description
+Find or create a documentation record for a repository.
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| pool | `Pool` | Database connection pool |
+| repositoryId | `string` | Repository ID (UUID) |
+| repoName | `string` | Repository name |
+#### Return Value
+`Promise<string>` documentation ID (UUID)
+
+### upsertPages
+#### Description
+Upsert documentation pages.
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| pool | `Pool` | Database connection pool |
+| documentationId | `string` | Documentation ID (UUID) |
+| fragments | `Array<{relativePath: string, content: string}>` | Array of fragments to upsert |
+#### Return Value
+`Promise<number>` count of upserted pages
+
+### pushToDatabase
+#### Description
+Top-level push function. Called from analyze command.
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| fragments | `Array<{relativePath: string, content: string}>` | Array of fragments to push |
+| projectPath | `string` | Absolute path of the analyzed directory |
+| [opts] | `object` | Optional overrides for testing |
+| [opts.pool] | `object` | PG Pool instance (skips singleton pool) |
+| [opts.session] | `object` | Session object (skips loadSession) |
+| [opts.user] | `object` | User object (skips validateToken) — { userId, username, email } |
+#### Return Value
+`Promise<{skipped: boolean, pushed?: number}>`
+
+## Dependencies
+
+* `pg: Pool`
+* `path: path`
+* `./config: dbConfig`
+* `../utils/config: loadSession`
+* `../api/auth: validateToken`
+* `../utils/logger: logger`
+
+## Usage Example
+```javascript
+const pool = getPool();
+const repoId = await getOrCreateRepo(pool, '1234567890', '/path/to/project');
+const docId = await getOrCreateDocumentation(pool, repoId, 'my-repo');
+const pushed = await upsertPages(pool, docId, [
+  { relativePath: 'file1.md', content: 'Hello world!' },
+  { relativePath: 'file2.md', content: 'Foo bar!' },
+]);
+console.log(pushed); // 2
+```

package/legacyver-docs/src/llm/chunker.md

@@ -0,0 +1,28 @@
+## Overview
+The `buildChunks` function builds LLM request chunks from a given package (`pkg`) and configuration (`config`). It processes each file in the package, truncating the source if necessary to fit within a token count limit.
+
+## Functions
+### buildChunks
+#### Description
+Builds LLM request chunks from a given package (`pkg`) and configuration (`config`).
+
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| `pkg` | `Object` | The package to process. |
+| `config` | `Object` | The configuration to use. |
+
+#### Return Value
+`Array<{relativePath, systemPrompt, userMessage, tokenCount}>`
+
+#### Detected Patterns
+* Arithmetic operations are used to calculate the token count and budget characters.
+
+## Dependencies
+* `fs: readFileSync`
+* `./prompts: SYSTEM_PROMPT, buildUserMessage`
+* `./cost-estimator: countTokens`
+* `../utils/logger: logger`
+
+## Usage Example
+Based on the code, it appears that the function is designed to be used in a loop, processing each file in the package. The `buildChunks` function returns an array of objects, each containing the relative path, system prompt, user message, and token count for a given file.

package/legacyver-docs/src/llm/cost-estimator.md

@@ -0,0 +1,62 @@
+## Overview
+This module provides functions for estimating the cost of using Large Language Models (LLMs) based on the input text and model pricing data. It uses the tiktoken library to estimate token counts and fetches model pricing data from the OpenRouter API.
+
+## Functions
+
+### countTokens(text)
+Counts the number of tokens in the given text.
+
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| text | string | The text to count tokens for |
+
+#### Return Value
+The number of tokens in the text.
+
+#### Description
+This function uses the tiktoken library to encode the text and return the length of the encoded string. If the tiktoken library is not available, it falls back to a rough approximation of 1 token per 4 characters.
+
+### fetchModelPricing()
+Fetches the model pricing data from the OpenRouter API or returns a cached version if it is still valid.
+
+#### Return Value
+A promise resolving to an object with model pricing data.
+
+#### Description
+This function checks if the model pricing cache is still valid (within the last hour). If it is, it returns the cached data. Otherwise, it fetches the data from the OpenRouter API, parses the response, and caches the result.
+
+### estimateCost(chunks, config)
+Estimates the cost of a list of LLM request chunks.
+
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| chunks | Array | The list of LLM request chunks |
+| config | Object | The configuration object with a `model` property |
+
+#### Return Value
+A promise resolving to an object with the estimated cost data.
+
+#### Description
+This function uses the `fetchModelPricing` function to get the model pricing data for the specified model. It then calculates the total input tokens by summing the tokens in each chunk's system prompt and user message. It also calculates the total output tokens based on an average of 400 tokens per chunk. The estimated cost is then calculated by multiplying the total input tokens by the input price and the total output tokens by the output price.
+
+## Dependencies
+* `fs`: `readFileSync`
+* `path`: `path`
+* `../utils/logger`: `logger`
+* `tiktoken`: `get_encoding`
+
+## Usage Example
+```javascript
+const chunks = [
+  { systemPrompt: 'Hello, world!', userMessage: 'How are you?' },
+  { systemPrompt: 'What is your name?', userMessage: 'John' },
+];
+
+const config = { model: 'meta-llama/llama-3.3-70b-instruct:free' };
+
+estimateCost(chunks, config).then((cost) => {
+  console.log(cost);
+});
+```

package/legacyver-docs/src/llm/free-model.md

@@ -0,0 +1,40 @@
+## Overview
+The `applyFreeModelPolicy` function applies free model policies to a given configuration object. It checks if the model ID ends with `:free` and adjusts the configuration accordingly.
+
+## Functions
+### applyFreeModelPolicy
+#### Description
+Applies free model policies to a given configuration object.
+
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| config | Object | The configuration object to apply free model policies to |
+
+#### Return Value
+The mutated configuration object
+
+#### Complex Logic
+The function checks if the provider is one of Ollama, Groq, Gemini, or Kimi, and if so, sets `isFreeModel` and `skipCostEstimation` to `true`. It then checks the provider-specific rate limits and caps concurrency accordingly. If the model ID does not end with `:free`, it sets `isFreeModel` to `false`. Otherwise, it sets `isFreeModel` to `true` and caps concurrency to 2.
+
+#### Detected Patterns
+* Arithmetic operations (e.g. `parseInt`, `parseInt(config.concurrency) || 1`)
+* Conditional statements (e.g. `if (provider === 'ollama' || provider === 'groq' || provider === 'gemini' || provider === 'kimi')`)
+* String manipulation (e.g. `provider.toLowerCase()`, `model.endsWith(':free')`)
+
+## Dependencies
+* `../utils/logger`
+* `picocolors`
+
+## Usage Example
+```javascript
+const config = {
+  provider: 'groq',
+  model: 'meta-llama/llama-3.3-70b-instruct:free',
+  concurrency: 5
+};
+
+const updatedConfig = applyFreeModelPolicy(config);
+console.log(updatedConfig);
+```
+Note: This example is a simplified representation of the usage and may not cover all possible scenarios.

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

@@ -0,0 +1,29 @@
+## Overview
+This module exports a `createProvider` function that returns an instance of a provider based on the provided configuration.
+
+## Functions
+### createProvider
+#### Description
+Returns an instance of a provider based on the provided configuration.
+
+#### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| config | Object | The configuration object |
+
+#### Return Value
+An instance of `OpenRouterProvider`, `OllamaProvider`, `GroqProvider`, `GeminiProvider`, or `KimiProvider`
+
+## Dependencies
+* `./providers/openrouter: OpenRouterProvider`
+* `./providers/ollama: OllamaProvider`
+* `./providers/groq: GroqProvider`
+* `./providers/gemini: GeminiProvider`
+* `./providers/kimi: KimiProvider`
+
+## Usage Example
+Based on the code, it appears that the `createProvider` function can be used as follows:
+```javascript
+const provider = createProvider({ provider: 'openrouter' });
+```
+This would return an instance of `OpenRouterProvider` with the provided configuration.