ctx-gen
Version:
AI-Enhanced Documentation Generator for Code Understanding
235 lines (168 loc) • 10.3 kB
Markdown
<div align="center">
<h1>CtxGen</h1>
<p><strong>AI-Enhanced Documentation Generator for Code Understanding</strong></p>
[](https://nodejs.org/)
[](https://openai.com/)
[](https://www.typescriptlang.org/)
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/ctx-gen)
</div>
<hr>
<p align="center">
<a href="#features"><strong>Features</strong></a> •
<a href="#installation"><strong>Installation</strong></a> •
<a href="#usage"><strong>Usage</strong></a> •
<a href="#cli-options"><strong>CLI Options</strong></a> •
<a href="#output"><strong>Output</strong></a> •
<a href="#using-with-llms"><strong>Using with LLMs</strong></a> •
<a href="#contributing"><strong>Contributing</strong></a>
</p>
<hr>
## Overview
**Context-Gen** is a command-line tool that generates AI-enhanced documentation specifically designed to provide Large Language Models (LLMs) with comprehensive context about your codebase. Unlike traditional documentation tools, Ctx-Gen focuses on creating machine-optimized outputs that help AI models understand code structure, logic, and relationships. This enables more effective AI-driven workflows such as code review, generation, debugging, and refactoring.
The generated documentation is auto-ignored by Git, ensuring it remains a development-only resource. By leveraging AI-powered analysis, Ctx-Gen extracts deep insights from your code and presents them in formats that are easily consumable by LLMs, such as markdown, JSON, and visual diagrams.
> **Note**: Ctx-Gen is intended for development purposes only, to assist AI models in understanding codebases. It is not designed for producing polished, user-facing documentation.
<hr>
## Features
Ctx-Gen provides a robust set of features to maximize codebase comprehension for AI systems:
🔹 **AI-Powered Analysis**: Parses code structure, logic flows, and component relationships with AI-driven insights powered by GPT-4o-mini
🔹 **Intent Inference**: Infers and documents the purpose behind functions, classes, and modules
🔹 **Detailed Summaries**: Generates concise, context-rich descriptions for files, functions, classes, and modules
🔹 **Function Insights**: Documents inputs, outputs, side effects, and usage examples
🔹 **Framework Detection**: Automatically identifies frameworks and libraries used in your project
🔹 **Architecture Pattern Recognition**: Detects common architectural patterns like MVC, DDD, Clean Architecture
🔹 **Enhanced Language Support**: Supports 40+ programming languages with specialized analysis
🔹 **Advanced Visual Diagrams**: Creates call graphs, data flow diagrams, sequence diagrams, class diagrams, and dependency maps
🔹 **Multi-Language Support**: Works with TypeScript, JavaScript, Python, Java, and many more languages
🔹 **Machine-Readable Outputs**: Produces JSON and XML files alongside markdown for direct AI consumption
🔹 **Codebase Metadata**: Includes information on languages, frameworks, and architectural patterns
🔹 **Concurrent Processing**: Processes multiple files in parallel for improved performance
🔹 **Gitignore Integration**: Automatically respects .gitignore patterns when analyzing files
🔹 **Code Quality Integration**: Leverages linters and static analysis tools for additional insights
🔹 **Auto Git-Ignored**: Automatically excludes generated documentation from version control
<hr>
## Installation
### Global Installation
```bash
npm install -g ctx-gen
# or with yarn
yarn global add ctx-gen
# or with pnpm
pnpm add -g ctx-gen
```
### Project-Specific Installation
```bash
npm install ctx-gen --save-dev
# or with yarn
yarn add -D ctx-gen
# or with pnpm
pnpm add -D ctx-gen
```
> **Requirements**: Node.js (version 14 or higher)
<hr>
## Usage
Ctx-Gen provides two primary commands, with all configuration passed via command-line arguments:
### Generate Full Documentation
```bash
ctx-gen full [options]
```
### Update Existing Documentation
```bash
ctx-gen update [options]
```
### CLI Options
All configuration is handled via command-line options. Below is a list of available options:
| Option | Description | Default |
|--------|-------------|---------|
| `--docs-dir <path>` | Output directory for documentation | `docs` |
| `--cache-file <path>` | Path to the cache file | `.doc_cache.json` |
| `--exclude <paths>` | Comma-separated list of paths to exclude | `.git,node_modules,dist` |
| `--languages <langs>` | Comma-separated list of languages to analyze | `typescript,javascript` |
| `--diagrams <types>` | Comma-separated list of diagram types to generate | `call-graph,data-flow,module-deps,class-diagram` |
| `--machine-formats` | Generate JSON/XML outputs for AI consumption | `false` |
| `--include-examples` | Include usage examples in documentation | `false` |
| `--no-ai` | Disable AI-powered features | - |
| `--openai-key <key>` | OpenAI API key for AI features | - |
| `--auto-ignore` | Auto-add `docsDir` to `.gitignore` | `true` |
| `--respect-gitignore` | Respect patterns in .gitignore when analyzing files | `true` |
| `--concurrent-ai <number>` | Maximum number of concurrent AI analyses | `3` |
### Examples
```bash
# Generate full documentation with default options
ctx-gen full
# Update documentation with custom output directory and languages
ctx-gen update --docs-dir custom_docs --languages typescript,python
# Generate documentation with machine-readable formats and examples
ctx-gen full --machine-formats --include-examples
# Generate documentation focusing on specific diagram types
ctx-gen full --diagrams class-diagram,module-deps
# Generate documentation with higher concurrency for large projects
ctx-gen full --concurrent-ai 8
# Disable AI features and specify excluded paths
ctx-gen full --no-ai --exclude .git,node_modules,build
# Ignore .gitignore patterns when analyzing files
ctx-gen full --no-respect-gitignore
```
> **Note**: To enable AI features, set the `OPENAI_API_KEY` environment variable or use the `--openai-key` option.
<hr>
## Output
Ctx-Gen generates a structured set of documentation files in the specified `docsDir` (default: `docs/`), which is automatically excluded from Git:
```
docs/
├── index.md # Project overview with navigation links
├── modules/ # Module and file documentation
│ ├── module1.md # Details for each module
│ └── module2.md
├── diagrams/ # Visual representations
│ ├── call_graph.mmd # Function call relationships
│ ├── data_flow.mmd # Data movement diagrams
│ ├── class_diagram.mmd # Class relationships and structure
│ ├── sequence.mmd # Sequence diagrams for key interactions
│ └── module_deps.mmd # Module dependency graphs
├── metadata.json # Codebase metadata (languages, frameworks, etc.)
├── analysis.json # Code quality and analysis insights
└── search.json # Searchable index for AI consumption
```
### Metadata
The `metadata.json` and `metadata.md` files contain rich information about your project:
- Language distribution with percentage breakdown
- Detected frameworks and their versions
- Identified architecture patterns
- Dependencies and dev dependencies
### Class Diagrams
The `class_diagram.mmd` file visualizes:
- Classes with their properties and methods
- Inheritance relationships
- Implementation relationships
- Component associations
<hr>
## Using with LLMs
Ctx-Gen is specifically designed to provide LLMs with the context they need to understand and interact with your codebase effectively. The generated documentation serves as a rich, structured input that LLMs can use to perform a variety of tasks, including:
- **Code Review**: LLMs can analyze the documentation to identify potential issues, suggest improvements, or ensure adherence to best practices.
- **Code Generation**: By understanding the existing structure and logic, LLMs can generate new code that integrates seamlessly with your project.
- **Debugging**: The detailed insights into function behaviors, data flows, and dependencies help LLMs pinpoint errors or suggest fixes.
- **Refactoring**: LLMs can use the documentation to propose refactoring strategies that improve code quality without breaking functionality.
### How It Works
1. **Generate Documentation**: Run `ctx-gen full` to create a comprehensive set of documentation files, including markdown, JSON, and diagrams.
2. **Feed to LLM**: Provide the generated files (e.g., `metadata.json`, `search.json`, or specific module documentation) as input to your LLM of choice.
3. **Query the LLM**: Ask the LLM to perform tasks like reviewing a specific function, suggesting improvements, or generating new code based on the provided context.
### Example Use Case
Suppose you want an LLM to review the `processData` function for potential optimizations:
1. Run `ctx-gen full --include-examples` to generate documentation with examples.
2. Provide the LLM with the `modules/utils/data.md` file, which contains the detailed documentation for `processData`.
3. Ask the LLM: "Review the `processData` function and suggest any optimizations or improvements."
The LLM can then analyze the function's intent, inputs, outputs, and usage examples to provide meaningful feedback.
<hr>
## Contributing
Contributions are welcome! Please see our [Contribution Guidelines](CONTRIBUTING.md) for more details.
### Development Setup
1. Clone the repository
2. Install dependencies with `pnpm install`
3. Build the project with `pnpm build`
4. Run tests with `pnpm test`
### Report Issues
Please report bugs and suggest features via the [GitHub Issues](https://github.com/maxmcneal/ctx-gen/issues) page.
<hr>
<div align="center">
<p><sub>© 2025 Max McNeal • Built for AI-assisted development</sub></p>
</div>