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 | Specify a different base directory to scan (defaults to current directory). |
| -o, --out | Specify output filename (defaults to promptHelper.md). |
| -s, --style | Include a style.md file to inject a ## Style: section. |
| -c, --code | Include a specific code file or all files in a directory under a ## Code: section. Can be used multiple times. |
| -i, --ignore | 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 for a sample output.

---

Changes

$3

- Initial release with basic JS/TS scanning, header management, and dependency
tracking.

$3

- Major refactor of the codebase to improve maintainability and readability.
- Breaking change: /promptHelperNotes.md is now
/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

$3

- Feature: Added --ignore 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 for
details.

---

Acknowledgments

- Inspired by common project analysis tools.
- Built with TypeScript, Node.js, and modern best practices.
- This was Vibecoded with ChatGPT.