ai-context-generator-cli/README.md

# AI Context Generator CLI

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.