This commit is contained in:
282
README.md
282
README.md
@@ -1,3 +1,281 @@
|
||||
# ai-context-generator-cli
|
||||
# AI Context Generator CLI
|
||||
|
||||
A CLI tool that generates comprehensive context files for AI coding assistants by analyzing project structure, dependencies, and coding patterns. Supports JSON/YAML output with templates for Cursor, Copilot, and generic AI assistants.
|
||||
A CLI tool that generates comprehensive context files for AI coding assistants by analyzing project structure, dependencies, and coding patterns. Outputs structured JSON/YAML context files optimized for different AI tools.
|
||||
|
||||
## Features
|
||||
|
||||
- **Automatic Project Detection**: Detects project type (Node.js, Python, Go, Rust, Java, etc.) and frameworks (React, Django, FastAPI, etc.)
|
||||
- **Dependency Analysis**: Extracts dependencies from package.json, requirements.txt, go.mod, Cargo.toml, and more
|
||||
- **Convention Extraction**: Analyzes coding patterns, naming conventions, import styles, and testing frameworks
|
||||
- **Multi-format Output**: Generates context files in JSON or YAML format
|
||||
- **AI-specific Templates**: Predefined templates for Cursor, Copilot, and generic AI assistants
|
||||
- **Configurable**: Customize analysis scope and output via `.ai-context-config.json`
|
||||
- **Ignore Pattern Support**: Respects `.gitignore` and custom ignore rules
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 16+
|
||||
- npm or yarn
|
||||
|
||||
### Install from Source
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/ai-context-generator-cli.git
|
||||
cd ai-context-generator-cli
|
||||
npm install
|
||||
npm run build
|
||||
npm link
|
||||
```
|
||||
|
||||
### Install Globally
|
||||
|
||||
```bash
|
||||
npm install -g ai-context-generator-cli
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Analyze current directory and generate context
|
||||
ai-context
|
||||
|
||||
# Analyze specific directory
|
||||
ai-context --dir /path/to/project
|
||||
|
||||
# Save to specific output file
|
||||
ai-context --output my-context
|
||||
|
||||
# Generate YAML instead of JSON
|
||||
ai-context --format yaml
|
||||
```
|
||||
|
||||
### Command Options
|
||||
|
||||
| Option | Short | Description | Default |
|
||||
|--------|-------|-------------|---------|
|
||||
| `--dir` | `-d` | Project directory to analyze | Current directory |
|
||||
| `--output` | `-o` | Output file path | `ai-context` |
|
||||
| `--format` | `-f` | Output format: `json` or `yaml` | `json` |
|
||||
| `--template` | `-t` | Template: `default`, `cursor`, `copilot`, `generic` | `default` |
|
||||
| `--config` | `-c` | Config file path | Auto-detected |
|
||||
| `--verbose` | `-v` | Enable verbose output | `false` |
|
||||
| `--no-conventions` | | Skip convention analysis | `false` |
|
||||
| `--include-dev` | | Include dev dependencies | `false` |
|
||||
| `--no-gitignore` | | Do not respect .gitignore | `false` |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Generate context with all analysis
|
||||
ai-context --dir ./my-project --verbose
|
||||
|
||||
# Generate YAML output for documentation
|
||||
ai-context --format yaml --output project-context
|
||||
|
||||
# Use Cursor-optimized template
|
||||
ai-context --template cursor --output cursor-context
|
||||
|
||||
# Quick analysis without conventions
|
||||
ai-context --no-conventions
|
||||
|
||||
# Include development dependencies
|
||||
ai-context --include-dev
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Create a `.ai-context-config.json` file in your project root:
|
||||
|
||||
```json
|
||||
{
|
||||
"includes": [
|
||||
"**/*.ts",
|
||||
"**/*.js",
|
||||
"**/*.py",
|
||||
"**/*.go",
|
||||
"**/*.rs"
|
||||
],
|
||||
"excludes": [
|
||||
"node_modules/**",
|
||||
"dist/**",
|
||||
".git/**"
|
||||
],
|
||||
"outputFormat": "json",
|
||||
"template": "default",
|
||||
"outputFile": "ai-context.json",
|
||||
"analyzeConventions": true,
|
||||
"includeDevDependencies": false,
|
||||
"respectGitignore": true
|
||||
}
|
||||
```
|
||||
|
||||
### Configuration Options
|
||||
|
||||
| Option | Type | Description | Default |
|
||||
|--------|------|-------------|---------|
|
||||
| `includes` | `string[]` | File patterns to include | All common source files |
|
||||
| `excludes` | `string[]` | File patterns to exclude | Common ignore patterns |
|
||||
| `outputFormat` | `json | yaml` | Output format | `json` |
|
||||
| `template` | `string` | Template name | `default` |
|
||||
| `outputFile` | `string` | Output filename | `ai-context.json` |
|
||||
| `analyzeConventions` | `boolean` | Extract coding conventions | `true` |
|
||||
| `includeDevDependencies` | `boolean` | Include dev dependencies | `false` |
|
||||
| `respectGitignore` | `boolean` | Respect .gitignore | `true` |
|
||||
|
||||
## Templates
|
||||
|
||||
### Default Template
|
||||
Generates structured JSON/YAML with full project analysis.
|
||||
|
||||
### Cursor Template
|
||||
Optimized for Cursor AI, focusing on:
|
||||
- Key dependencies
|
||||
- Coding conventions
|
||||
- File structure overview
|
||||
|
||||
### Copilot Template
|
||||
Tailored for GitHub Copilot, featuring:
|
||||
- Concise project summary
|
||||
- Dependency overview
|
||||
- Style guidelines
|
||||
|
||||
### Generic Template
|
||||
Simple format suitable for any AI assistant:
|
||||
- Project information
|
||||
- Dependency list
|
||||
- Conventions summary
|
||||
|
||||
## Output Structure
|
||||
|
||||
### JSON Output
|
||||
|
||||
```json
|
||||
{
|
||||
"projectInfo": {
|
||||
"projectType": {
|
||||
"primaryLanguage": "TypeScript",
|
||||
"languages": ["TypeScript", "JavaScript"],
|
||||
"frameworks": ["React", "Next.js"],
|
||||
"buildTools": ["npm"]
|
||||
},
|
||||
"dependencies": {
|
||||
"direct": [...],
|
||||
"dev": [...],
|
||||
"total": 50
|
||||
},
|
||||
"conventions": {
|
||||
"namingConvention": {
|
||||
"files": "kebab-case",
|
||||
"variables": "camelCase",
|
||||
"functions": "camelCase",
|
||||
"classes": "PascalCase"
|
||||
},
|
||||
"importStyle": {
|
||||
"style": "ESM",
|
||||
"aliasPrefix": "@/"
|
||||
},
|
||||
"testingFramework": "Jest",
|
||||
"codeStyle": {
|
||||
"indentSize": 2,
|
||||
"indentType": "spaces",
|
||||
"lineEndings": "LF",
|
||||
"quoteStyle": "single"
|
||||
}
|
||||
},
|
||||
"fileCount": 150,
|
||||
"analysisDate": "2024-01-15T10:30:00.000Z"
|
||||
},
|
||||
"files": [...],
|
||||
"config": {...},
|
||||
"generatedAt": "2024-01-15T10:30:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Supported Languages
|
||||
|
||||
| Language | Detected By | Dependency Files |
|
||||
|----------|-------------|------------------|
|
||||
| TypeScript | `.ts`, `.tsx`, `tsconfig.json` | `package.json` |
|
||||
| JavaScript | `.js`, `.jsx`, `package.json` | `package.json` |
|
||||
| Python | `.py`, `requirements.txt` | `requirements.txt`, `pyproject.toml`, `Pipfile` |
|
||||
| Go | `.go`, `go.mod` | `go.mod` |
|
||||
| Rust | `.rs`, `Cargo.toml` | `Cargo.toml` |
|
||||
| Java | `.java`, `pom.xml` | `pom.xml`, `build.gradle` |
|
||||
| C/C++ | `.c`, `.cpp`, `CMakeLists.txt` | `CMakeLists.txt` |
|
||||
| Ruby | `.rb`, `Gemfile` | `Gemfile` |
|
||||
| PHP | `.php`, `composer.json` | `composer.json` |
|
||||
|
||||
## Supported Frameworks
|
||||
|
||||
- **Frontend**: React, Vue, Next.js, NestJS
|
||||
- **Backend**: Express, Django, FastAPI, Flask, Gin, Echo
|
||||
- **Testing**: Jest, Mocha, Pytest, Go testing, JUnit
|
||||
|
||||
## Programmatic Usage
|
||||
|
||||
```typescript
|
||||
import { ContextGenerator } from 'ai-context-generator-cli';
|
||||
|
||||
const generator = new ContextGenerator();
|
||||
|
||||
// Generate context
|
||||
const projectInfo = await generator.generate('/path/to/project');
|
||||
|
||||
// Generate JSON output
|
||||
const jsonOutput = await generator.generateJson('/path/to/project');
|
||||
|
||||
// Generate YAML output
|
||||
const yamlOutput = await generator.generateYaml('/path/to/project');
|
||||
|
||||
// Save to file
|
||||
await generator.saveContext('/path/to/project', 'output', 'json');
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors
|
||||
|
||||
| Error | Solution |
|
||||
|-------|----------|
|
||||
| `No package.json found` | Check if running in project root or use `--dir` flag |
|
||||
| `Invalid config file format` | Validate JSON syntax and required fields |
|
||||
| `Permission denied on output file` | Check write permissions in target directory |
|
||||
| `Directory not found` | Verify the directory path exists |
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Run tests
|
||||
npm test
|
||||
|
||||
# Build
|
||||
npm run build
|
||||
|
||||
# Run locally
|
||||
npm run dev -- --dir ./my-project
|
||||
|
||||
# Lint
|
||||
npm run lint
|
||||
|
||||
# Lint with fix
|
||||
npm run lint:fix
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
||||
4. Push to the branch (`git push origin feature/amazing-feature`)
|
||||
5. Open a Pull Request
|
||||
|
||||
## License
|
||||
|
||||
MIT License - see [LICENSE](LICENSE) for details.
|
||||
|
||||
Reference in New Issue
Block a user