# CodeMap

A CLI tool that analyzes Python/JavaScript/Go codebases and automatically generates interactive architecture diagrams using Mermaid.js. It detects module dependencies, data flow patterns, and service boundaries, outputting shareable diagrams that can be embedded in docs or viewed in-browser.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)

## Features

- **Multi-language Support**: Analyze Python, JavaScript/TypeScript, and Go codebases
- **Dependency Detection**: Automatically extracts import statements and build dependency graphs
- **Interactive Diagrams**: Generate Mermaid.js flowcharts with package groupings
- **Multiple Output Formats**: Output as Mermaid syntax, HTML, or Markdown
- **Real-time Monitoring**: Watch directories for changes and regenerate diagrams
- **HTTP Server**: Serve interactive diagrams with auto-refresh

## Installation

```bash
pip install -e .
```

Or install dependencies directly:

```bash
pip install -r requirements.txt
```

## Quick Start

Analyze a directory and view the Mermaid diagram:

```bash
codemap analyze /path/to/your/project
```

Generate an HTML file with an interactive viewer:

```bash
codemap analyze /path/to/your/project --format html --output diagram.html
```

## Commands

### analyze

Analyze a directory or file and generate a dependency diagram.

```bash
codemap analyze [PATH] [OPTIONS]
```

Options:
- `--output, -o FILE`: Output file path
- `--format, -f FORMAT`: Output format (mermaid, html, markdown)
- `--max-depth, -d N`: Maximum dependency depth (default: 3)
- `--include-packages/--no-packages`: Include package groupings (default: True)

### watch

Watch a directory for changes and regenerate diagrams in real-time.

```bash
codemap watch [PATH] [OPTIONS]
```

Options:
- `--output, -o FILE`: Output file path
- `--format, -f FORMAT`: Output format (mermaid, html)
- `--delay SECONDS`: Debounce delay in seconds (default: 1.0)

### serve

Start a local HTTP server with an interactive diagram viewer.

```bash
codemap serve [PATH] [OPTIONS]
```

Options:
- `--port, -p PORT`: Port to serve on (default: 8080)
- `--open/--no-open`: Open browser automatically (default: True)

## Examples

Analyze a Python project:

```bash
codemap analyze ./my-python-project -f mermaid
```

Generate HTML with live refresh:

```bash
codemap watch ./my-python-project -o ./diagram.html -f html
```

Serve a diagram on a specific port:

```bash
codemap serve ./my-python-project --port 3000 --no-open
```

## Output Examples

### Mermaid Flowchart

```mermaid
graph TD
    classDef python fill:#3572A5,stroke:#333,stroke-width:2px,color:white
    classDef javascript fill:#F1E05A,stroke:#333,stroke-width:2px,color:black
    classDef go fill:#00ADD8,stroke:#333,stroke-width:2px,color:white
    
    subgraph src
        main[main]:::python
        utils[utils]:::python
    end
    
    main --> utils
```

### HTML Output

The HTML output includes:
- Interactive Mermaid.js diagram viewer
- Dark theme UI
- Export to PDF functionality
- Download Mermaid source
- Auto-refresh capability (in watch/serve modes)

## Architecture

```
codemap/
├── cli/
│   ├── analyze.py      # Analyze command implementation
│   ├── watch.py        # Watch command implementation
│   ├── serve.py        # Serve command implementation
│   └── app.py          # CLI app setup
├── core/
│   ├── graph_builder.py    # NetworkX-based dependency graph
│   └── mermaid_generator.py # Mermaid diagram generation
├── parsers/
│   ├── base.py         # Base parser interface
│   ├── python_parser.py   # Python AST-based parser
│   ├── javascript_parser.js # JavaScript regex-based parser
│   └── go_parser.go       # Go import parser
├── templates/
│   └── viewer.html     # HTML template for diagrams
└── __init__.py
```

## Configuration

Configuration is handled via CLI flags. No additional config files are required.

## Development

### Running Tests

```bash
pytest tests/ -v
```

### Project Structure

- `codemap/`: Main package
- `tests/`: Test suite
- `pyproject.toml`: Project configuration

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: `pytest tests/ -v`
5. Submit a pull request

## License

MIT License - see LICENSE file for details.