# CodeSnap - Codebase Summarization CLI

A CLI tool that analyzes codebases and generates concise, human-readable summaries including file structure, key functions/classes, dependencies, and architectural patterns. Useful for onboarding, understanding legacy code, and providing context to AI assistants.

## Features

- **Multi-language Support**: Python, JavaScript, TypeScript, Go, Rust, Java, C/C++, Ruby, PHP
- **Dependency Analysis**: Build import/dependency graphs using NetworkX
- **Complexity Scoring**: Calculate cyclomatic complexity with ratings (low/medium/high/critical)
- **Multiple Output Formats**: JSON, Markdown, and LLM-optimized output
- **Tree-sitter Parsing**: Accurate code parsing for extraction
- **Configuration**: YAML-based configuration with environment variable overrides

## Installation

### From PyPI (Recommended)

```bash
pip install codesnap
```

### From Source

```bash
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/codesnap.git
cd codesnap
pip install -e .
```

### Development Installation

```bash
pip install -e ".[dev]"
```

## Usage

### Basic Analysis

Analyze a directory and generate a summary:

```bash
codesnap analyze /path/to/project
```

### Output Formats

#### Markdown (Default)

```bash
codesnap analyze /path/to/project --output markdown
```

Generates a human-readable report with:
- Language breakdown
- File structure (tree view)
- Key functions and classes
- Dependencies
- Complexity metrics

#### JSON

```bash
codesnap analyze /path/to/project --output json
```

Generates structured JSON output suitable for programmatic processing.

#### LLM-Optimized

```bash
codesnap analyze /path/to/project --output llm --max-tokens 4000
```

Optimized output for AI assistants with token limiting.

### Dependency Analysis

Show dependency graph for a codebase:

```bash
codesnap deps /path/to/project
```

Shows:
- Graph statistics
- Circular dependencies
- Most depended-on files
- Most dependent files

### Complexity Analysis

Calculate complexity metrics:

```bash
codesnap complexity /path/to/project
```

Shows complexity ratings (low/medium/high/critical) for each file.

### List Supported Languages

```bash
codesnap languages
```

Shows all supported programming languages and file extensions.

## Configuration

Create a `.codesnaprc` file in your project root:

```yaml
max_files: 1000
max_tokens: 8000

include_patterns:
  - "**/*.py"
  - "**/*.js"
  - "**/*.ts"

exclude_patterns:
  - "**/node_modules/**"
  - "**/.git/**"
  - "**/venv/**"

complexity:
  low: 10
  medium: 20
  high: 50
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `CODSNAP_MAX_FILES` | Maximum files to analyze | 1000 |
| `CODSNAP_MAX_TOKENS` | Maximum output tokens | 8000 |
| `CODSNAP_GRCACHE` | Tree-sitter grammar cache | `~/.cache/codesnap/grammars` |

## Output Formats

### JSON Schema

```json
{
  "timestamp": "2024-01-01T00:00:00Z",
  "version": "0.1.0",
  "directory": "/path/to/project",
  "file_count": 10,
  "language_breakdown": {
    "python": 5,
    "javascript": 3,
    "typescript": 2
  },
  "files": [
    {
      "path": "/path/to/project/main.py",
      "language": "python",
      "functions": [...],
      "classes": [...]
    }
  ],
  "dependencies": {
    "main.py": ["utils.py", "config.py"]
  },
  "metrics": {
    "total_functions": 25,
    "total_classes": 5,
    "cycles_found": 0
  }
}
```

## Examples

### Analyze a Python Project

```bash
codesnap analyze ./my-python-app --output markdown
```

### Analyze with Token Limit for LLM

```bash
codesnap analyze ./large-project --output llm --max-tokens 4000 > summary.txt
```

### Find Circular Dependencies

```bash
codesnap deps ./project
```

### Quick Complexity Check

```bash
codesnap complexity ./project --format markdown
```

## Supported Languages

- Python (.py, .pyw, .pyi)
- JavaScript (.js, .mjs, .cjs)
- TypeScript (.ts, .tsx)
- Go (.go)
- Rust (.rs)
- Java (.java)
- C/C++ (.c, .cpp, .cc, .h, .hpp)
- Ruby (.rb)
- PHP (.php)

## 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 file for details.