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.

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

pip install -e .

Or install dependencies directly:

pip install -r requirements.txt

Quick Start

Analyze a directory and view the Mermaid diagram:

codemap analyze /path/to/your/project

Generate an HTML file with an interactive viewer:

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

Commands

analyze

Analyze a directory or file and generate a dependency diagram.

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.

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.

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:

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

Generate HTML with live refresh:

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

Serve a diagram on a specific port:

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

Output Examples

Mermaid Flowchart

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

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.