Initial commit: CodeMap v0.1.0 - CLI tool for code analysis and diagram generation

README.md

@@ -1,3 +1,181 @@
-# codemap
+# CodeMap
 
-A CLI tool that analyzes codebases and generates interactive architecture diagrams using Mermaid.js
+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.