loqatevars/WORKFLOWS.md

Locate JavaScript files with 'const' or 'process.env' usage in LLM-generated codebases

# Workflows

This document outlines the primary workflows for the `loqatevars` tool.

## 1. Standard Scan Workflow

This is the default workflow for identifying files with `const` or `process.env` usage.

1.  **Execution**: The user runs the `loqatevars scan` command from their terminal, optionally providing a directory path.
    ```bash
    loqatevars scan ./my-project
    ```
2.  **Parsing**: [`cli.js`](cli.js) parses the command-line arguments to determine the target directory and any other options (like files to ignore).
3.  **File Search**: The `findMatchingFiles` function in [`lib/utils.js`](lib/utils.js) is called. It uses `globby` to recursively find all `.js` files in the target directory, excluding those in ignored directories (e.g., `node_modules`).
4.  **Analysis**: For each found file, `findMatchingFiles` reads its content and passes it to `analyzeConstUsage`.
5.  **AST Parsing**: `analyzeConstUsage` uses `acorn` to parse the file content into an Abstract Syntax Tree (AST). It traverses the AST to find `const` declarations (that are not `require` statements) and `process.env` usage.
6.  **Result Aggregation**: If a file contains either, its path is added to a list of matches.
7.  **Output**: The list of matching file paths is returned to [`cli.js`](cli.js), which then prints the array of file paths to the console.

## 2. Detailed Scan Workflow

This workflow provides a more detailed analysis of the scanned files.

1.  **Execution**: The user runs the `loqatevars detailed` command.
    ```bash
    loqatevars detailed ./my-project
    ```
2.  **Parsing**: Same as the standard workflow.
3.  **File Search**: The `findMatchingFilesDetailed` function in [`lib/utils.js`](lib/utils.js) is called.
4.  **Analysis**: The analysis process is the same, but `findMatchingFilesDetailed` collects more information for each match, including the counts of different types of `const` declarations.
5.  **Detailed Result Aggregation**: The function returns an object containing a list of detailed match objects and a summary object with statistics (total files scanned, number of matches, etc.).
6.  **Output**: [`cli.js`](cli.js) formats this detailed information into a human-readable summary and prints it to the console.

## 3. Programmatic Usage Workflow

The tool can also be used as a library in other Node.js projects.

1.  **Import**: A developer imports the desired function into their project:
    ```javascript
    const { findMatchingFiles } = require('loqatevars');
    ```
2.  **Execution**: They call the function with the desired directory and options, using `async/await` to handle the returned Promise.
3.  **Return Value**: The function returns a Promise that resolves with the results, which can then be used by the calling code.