prompt-helper

# Prompt-Helper Prompt-Helper is a command-line tool for **JavaScript** and **TypeScript** projects designed to streamline the process of generating prompts based on your project's files and configuration settings. It automatically scans your project directory, extracts relevant metadata, and generates meaningful prompts to assist in tasks like generating documentation, summaries, or code comments. > ⚠️ **Limited support for non‑JS/TS files**: The tool’s import‑dependency > analysis and header management rely on parsing `.js`/`.ts` modules. Other file > types (e.g., `.py`, `.go`, `.java`) may be scanned but their dependencies will > not be resolved, and `Depends on:` annotations will not appear. ## Features - **File Header Management:** Automatically checks and adds file headers. ex: `// src/index.ts`. This is useful for ensuring AI understands the context of the code. - **Project Analysis:** Collects information from `package.json`, `tsconfig.json`, and other common configuration files. - **Local Dependency Tracking:** Analyzes imports and dependencies within your JS/TS project. - **Directory Structure Visualization:** Prints a tree-like structure of your project. - **Custom Code Snippets:** Include specific code files or entire directories via `--code` flags. - **Style Injection:** Embed a `style.md` section to enforce code conventions. - **TODO/FIXME Scanning:** Extract inline comments marked for follow-up. - **Code Complexity Metrics:** Adds FTA-based stats like cyclomatic complexity, bugs, and effort. - **Dependency Graph Output:** Include a `dependencyGraph` section and track unused files. - **JSON Output:** Emit a machine-readable JSON alongside the markdown summary. - **Customizable Logs:** Outputs logs to both console and file. ## Installation Install globally or locally using your package manager of choice: ```bash # npm npm install -g prompt-helper npm install prompt-helper # yarn yarn global add prompt-helper yarn add prompt-helper # pnpm pnpm add -g prompt-helper pnpm add prompt-helper ``` If installed locally, run with the runner for your package manager: ```bash npx prompt-helper # npm yarn prompt-helper # yarn pnpm prompt-helper # pnpm ``` ## Commands | Command | Description | |--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| | `prompt-helper` | Scan current directory and generate `promptHelper.md`. | | `-d, --dir <path>` | Specify a different base directory to scan (defaults to current directory). | | `-o, --out <file>` | Specify output filename (defaults to `promptHelper.md`). | | `-s, --style <style.md>` | Include a `style.md` file to inject a **## Style:** section. | | `-c, --code <file/dir>` | Include a specific code file or all files in a directory under a **## Code:** section. Can be used multiple times. | | `-i, --ignore <pattern>` | Glob pattern of files/directories to exclude from `--code` snippets. Can be used multiple times. For recursive matching, use `**` (e.g., `**/*.test.ts`). | | `--todos` | Scan codebase for `TODO:` and `FIXME:` comments. | | `--complexity` | Analyze complexity metrics (Halstead, cyclomatic, bugs, time, effort). | | `--dependency-graph` | Collect and output the full dependency graph and unused file list. | | `--json` | Also write a `promptHelper.json` alongside the markdown summary. | | `--help` | Display help and all available options. | ## Example Usage ```bash # Basic scan prompt-helper # Scan a different folder and output to custom.md prompt-helper --dir ./my-app --out custom.md # Inject style guide prompt-helper --style ./promptHelper/style.md # Include code snippets from src, but ignore test files and a specific utility prompt-helper --code src/entry.ts --code src/utils/ --ignore "**/*.test.ts" --ignore "src/utils/old-util.js" # Ignore a specific directory recursively prompt-helper --code . --ignore "**/node_modules/**" --ignore "**/dist/**" # Include TODO comments and complexity analysis prompt-helper --todos --complexity # Include full dependency graph and export as JSON prompt-helper --dependency-graph --json ``` ## Example Output See [`example.md`](example.md) for a sample output. --- ## Changes ### v1.0.0 - Initial release with basic JS/TS scanning, header management, and dependency tracking. ### v2.0.0 - Major refactor of the codebase to improve maintainability and readability. - Breaking change: `<root>/promptHelperNotes.md` is now `<root>/promptHelper/notes.md`. - Added `--style` and `--code` support; refactored features into separate modules. - Recursive directory support for `--code`; improved error handling for ambiguous paths. - 🚀 Added support for: - `--todos` and `--complexity` metrics - `--dependency-graph` collection and unused file detection - `--json` output for machine-friendly workflows ### v2.1.0 - **Feature:** Added `--ignore <pattern>` CLI option to exclude files or glob patterns from the code snippets collected by `--code`. This allows for more fine-grained control over what code is included in the output. - Dependency: Added `micromatch` for glob pattern matching. --- ## Planned Features - Full test suite with coverage reporting. - Expanded support for non‑JS/TS files (e.g., Python, Go). - ~~Include/exclude globs for fine‑grained control.~~ (Partially addressed with `--ignore`. Further include patterns could be added.) - Plugin system for custom metadata collectors. --- ## Development 1. Clone the repo: ```bash git clone https://github.com/yourusername/prompt-helper.git ``` 2. Install dependencies: ```bash pnpm install ``` 3. Build: ```bash pnpm run build ``` 4. Run locally: ```bash pnpm start ``` --- ## Contributing Contributions are welcome! Please: 1. Fork the repo. 2. Create a branch for your feature or bugfix. 3. Send a pull request. --- ## License This project is licensed under the MIT License. See [LICENSE](LICENSE) for details. --- ## Acknowledgments - Inspired by common project analysis tools. - Built with TypeScript, Node.js, and modern best practices. - This was Vibecoded with ChatGPT.