ProjectMap

Multi-Language Codebase Visualizer and Static Analyzer — Acting as Google Maps for Software Codebases.

ProjectMap statically parses codebases without executing code to build interactive 2D dependency graphs, terminal tree structures, cyclomatic complexity scores, circular import warnings, and markdown documentation.

---

Key Capabilities

• Multi-Language Parser Engine: Native static AST analysis for Python, JavaScript, TypeScript, React (JSX/TSX), HTML, and CSS.
• Interactive 2D Web Visualizer: Zoomable, filterable network graph powered by Vis.js with real-time physics controls.
• Code Health Metrics:
  • Cyclomatic Complexity: McCabe branching complexity scoring for functions and classes.
  • Dead Code & Orphan File Detection: Identifies unimported/unused files and modules across the codebase (modules not imported or referenced by any other file).
  • Circular Dependency Warning Engine: Graph cycle detection using NetworkX to spot circular imports (File A <-> File B).
• VS Code Deep Linking: Clicking any component or function in the web inspector opens that exact file and line number directly in VS Code (vscode://file/...).
• Real-Time Live Watcher: Monitors codebase changes on save and rebuilds visual maps instantly (projectmap watch .).
• 1-Click PNG Exporter: Export high-resolution PNG graph diagrams directly from the browser viewer.

---

Supported Languages & Ecosystems

Language / Framework	Extension	Features Extracted
Python	.py	Classes, Methods, Functions, AST Imports, Docstrings
JavaScript / Node.js	.js, .mjs, .cjs	ES6 Imports, CommonJS require(), Exports, Functions
TypeScript	.ts, .tsx	Type declarations, Interfaces, Classes, Imports
React	.jsx, .tsx	React Components, Hook calls, JSX Render Hierarchies
HTML & CSS	.html, .css	Script tags, Stylesheet links, @import rules

---

Architecture & Project Structure

ProjectMap/
├── src/
│   └── projectmap/
│       ├── __init__.py           # Package version & metadata
│       ├── cli.py                # Command-line Interface entry point
│       ├── config.py             # Custom configuration loader (.projectmap.json)
│       ├── models.py             # Language-agnostic Data Models (Nodes & Edges)
│       ├── watcher.py            # Real-time filesystem watcher (watchdog)
│       ├── parser/               # Multi-language static parsers
│       │   ├── __init__.py
│       │   ├── ast_visitor.py    # Python AST Visitor
│       │   ├── js_parser.py     # JS, TS & React JSX parser
│       │   ├── html_parser.py   # HTML & CSS parser
│       │   └── project_analyzer.py # Directory walker & file router
│       ├── graph/                # Relationship Graph Construction
│       │   ├── __init__.py
│       │   └── builder.py        # NetworkX dependency graph builder
│       ├── exporters/            # Output Exporters
│       │   ├── __init__.py
│       │   ├── console_exporter.py # Rich terminal tree & health warnings
│       │   ├── markdown_exporter.py # Mermaid.js diagram generator
│       │   └── html_exporter.py  # Standalone Web Map exporter
│       └── templates/            # Web UI Templates
│           └── viewer.html       # Glassmorphic Vis.js web visualizer
├── tests/                        # Unit Test Suite
│   └── test_parser.py
├── output/                       # Auto-generated Artifacts (HTML & Markdown maps)
├── .gitignore                    # Version control exclusions
├── pyproject.toml                # Standard PEP 517 build configuration
├── requirements.txt              # Project dependencies
└── README.md                     # Documentation

Note on output/ Directory: The output/ folder is automatically created when you run projectmap analyze .. It stores the generated projectmap.html web visualizer and PROJECTMAP.md markdown summary.

---

Installation

Prerequisites

• Python 3.8 or higher
• pip package manager

Option 1: Install as an Editable Package (Recommended)

Cloning the repository and installing in editable mode allows you to execute projectmap from any directory on your computer:

git clone https://github.com/abinjoyal/ProjectMap.git
cd ProjectMap
pip install -e .

Option 2: Install Dependencies Directly

pip install -r requirements.txt

---

Usage Commands

1. Analyze Current Directory

Generates terminal summary report, interactive output/projectmap.html, and output/PROJECTMAP.md:

# Using installed CLI executable
projectmap analyze .

# OR directly via Python module (without installing CLI executable):
python -m src.projectmap.cli analyze .

2. Analyze External Project

Analyze any Python, React, or Web codebase on your system by supplying its directory path:

projectmap analyze "/path/to/external/project"

3. Real-Time Live Watcher Mode

Watch a directory for file saves and update the HTML map live in real time:

projectmap watch .

4. Custom Output Paths

Specify custom destinations for HTML and Markdown outputs:

projectmap analyze . --html "custom/path/map.html" --md "custom/path/MAP.md"

---

Quick Open

After analyzing a project, the interactive map is saved as output/projectmap.html. Open it directly from PowerShell:

Start-Process "output\projectmap.html"

(You can also double‑click the file in Explorer or use open/xdg-open on other platforms.)

Running Unit Tests

Run the automated test suite to verify parsers, graph engines, and health metrics:

python -m unittest discover -s tests

---

Configuration (.projectmap.json)

ProjectMap supports custom configuration via .projectmap.json in your project root:

{
  "ignore_dirs": [
    "venv",
    ".venv",
    "__pycache__",
    "node_modules",
    "dist",
    "build",
    "output"
  ],
  "complexity_threshold": 10,
  "html_output": "output/projectmap.html",
  "md_output": "output/PROJECTMAP.md"
}

---

License

This project is licensed under the MIT License - see the LICENSE file for details.