<p align="center">
<img src="assets/logo.svg" alt="morpharch animated logo" width="600">
</p>
<p align="center">
<strong>Monorepo architecture health visualizer with animated TUI.</strong>
</p>
<p align="center">
<a href="https://crates.io/crates/morpharch"><img src="https://img.shields.io/crates/v/morpharch" alt="Crates.io"></a>
<a href="https://docs.rs/morpharch"><img src="https://img.shields.io/docsrs/morpharch" alt="docs.rs"></a>
<a href="https://github.com/onplt/morpharch/actions/workflows/ci.yml"><img src="https://github.com/onplt/morpharch/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://github.com/onplt/morpharch#license"><img src="https://img.shields.io/crates/l/morpharch" alt="License"></a>
</p>
MorphArch scans monorepo Git history, builds per-commit dependency graphs using
tree-sitter AST parsing, calculates architectural health scores, and renders the
results as an animated force-directed graph in your terminal.
It supports Nx, Turborepo, pnpm workspaces, and Cargo workspaces out of the
box, with language-level import extraction for Rust, TypeScript, JavaScript, Python, and Go.
<p align="center">
<img src="website/static/img/demo.gif" alt="MorphArch TUI Demo" width="800">
</p>
---
## Features
- **Git history scanning** -- walk commit history with gix, extract file trees,
and detect workspace configurations automatically.
- **Tree-sitter AST parsing** -- extract real import/dependency edges from
source files in Rust, TypeScript (inc. JSX/TSX), JavaScript, Python, and Go.
- **Absolute Health scoring** -- quantify architectural integrity on a 0--100
scale using cycle detection (Kosaraju SCC), boundary violation analysis, and
context-aware coupling density metrics. Fully configurable via `morpharch.toml`.
- **Animated TUI** -- Verlet physics force-directed graph layout rendered with
ratatui and crossterm, featuring a timeline slider, k9s-inspired insight
dashboard, and Catppuccin Mocha color theme.
- **Incremental scanning** -- subtree-cached tree walks (`O(changed_dirs)`)
and an LRU blob import cache (50K entries) deliver 5--20x speedups on
subsequent runs.
- **Parallel parsing** -- rayon-powered data-parallel import extraction across
all workspace packages.
- **Mouse interaction** -- click and drag graph nodes to rearrange the layout
in real time.
- **Search filtering** -- press `/` in the TUI to filter nodes by name.
- **SQLite persistence** -- all scan data is stored in
`~/.morpharch/morpharch.db` for instant replay and historical analysis.
- **Cross-platform** -- runs on Linux, macOS, and Windows.
---
## Installation
### Quick Install
**Linux / macOS:**
```bash
**Windows (PowerShell):**
```powershell
### Package Managers
| **crates.io** | `cargo install morpharch` |
| **cargo-binstall** | `cargo binstall morpharch` |
| **Homebrew** | `brew install onplt/morpharch` |
| **npm** | `npm install -g morpharch` |
| **Scoop** (Windows) | `scoop bucket add morpharch https://github.com/onplt/scoop-morpharch` then `scoop install morpharch` |
| **AUR** (Arch) | `yay -S morpharch-bin` |
| **DEB** (Debian/Ubuntu) | Download `.deb` from [Releases](https://github.com/onplt/morpharch/releases) |
| **RPM** (Fedora/RHEL) | Download `.rpm` from [Releases](https://github.com/onplt/morpharch/releases) |
| **Docker** | `docker run --rm -v .:/repo ghcr.io/onplt/morpharch scan .` |
### From Source
```bash
git clone https://github.com/onplt/morpharch.git
cd morpharch
cargo build --release
# Binary is at target/release/morpharch
```
---
## Quick Start
```bash
# Scan a monorepo and build the database
morpharch scan /path/to/monorepo
# Scan and launch the animated TUI
morpharch watch /path/to/monorepo
# Analyze architecture for the current HEAD commit
morpharch analyze
# View the health trend over recent commits
morpharch list-drift
```
---
## Usage
### `morpharch scan <path>`
Scan a Git repository: walk commit history, build per-commit dependency graphs,
calculate health scores, and persist everything to the SQLite database.
```bash
# Scan the current directory (all commits)
morpharch scan .
# Scan a specific repo, limit to last 100 commits
morpharch scan /path/to/repo -n 100
```
| `-n, --max-commits <N>` | Maximum commits to scan. `0` (default) means unlimited. |
### `morpharch watch <path>`
Perform a scan and then launch the animated TUI. The TUI displays a
force-directed graph of the dependency structure, a timeline slider for
navigating commit history, and a mission-control style dashboard with
real-time architectural insights.
| `-n, --max-commits <N>` | Maximum commits to scan. `0` (default) means unlimited. |
| `-s, --max-snapshots <N>` | Maximum graph snapshots loaded into the TUI timeline. Default: `200`. |
### `morpharch analyze [commit]`
Display a detailed architectural report for a specific commit, including
health sub-metrics, boundary violations, circular dependencies, and AI-driven
improvement recommendations.
---
## TUI Keyboard Shortcuts
| `j` / `Down` | Navigate to the next (older) commit |
| `k` / `Up` | Navigate to the previous (newer) commit |
| `p` / `Space` | Play / pause auto-play through the timeline |
| `r` | Reheat the graph (re-energize Verlet temperature) |
| `/` | Enter search mode to filter nodes by name |
| `Esc` | Exit search mode, or quit the TUI |
| `q` | Quit the TUI |
---
## Architecture Health Scoring
MorphArch assigns each commit a system health score between **0 and 100**. Higher scores indicate a cleaner, more maintainable architecture.
| **90-100** | **Clean** | Excellent structural integrity. Modular and cohesive. |
| **70-89** | **Healthy** | Minor architectural debt, but no fatal flaws. |
| **40-69** | **Warning** | Significant debt detected. Prone to ripple effects. |
| **0-39** | **Critical** | Spagetti code. High structural risk; immediate refactoring required. |
The score uses a **6-component scale-aware algorithm** that calculates "Architectural Debt" and subtracts it from a base of 100. It dynamically scales its expectations based on the size of your repository, forgiving necessary complexity while harshly penalizing true anti-patterns.
- **Cycle Debt (30%):** Circular paths between packages that break modularity. Detected via Strongly Connected Components (Kosaraju's algorithm).
- **Layering Debt (25%):** Back-edges in the topological ordering of the dependency graph (boundary violations).
- **Hub/God Module Debt (15%):** Penalizes "God modules" that have both abnormally high incoming (Fan-in) and outgoing (Fan-out) dependencies, ignoring natural entry points (`main`, `index`, `app`).
- **Coupling Debt (12%):** Weighted coupling intensity based on the exact count of import statements between modules.
- **Cognitive Debt (10%):** Evaluates graph Shannon entropy. Penalizes structures where the sheer density of connections makes the system impossible for a human to reason about.
- **Instability Debt (8%):** Based on Martin's Abstractness/Instability metrics. Flags fragile modules that depend on everything but are depended upon by nothing.
All weights, thresholds, and exemptions above are fully configurable via `morpharch.toml`.
---
## Configuration
MorphArch works out of the box with zero configuration. To customize the scoring engine, place a `morpharch.toml` file at the root of your repository.
```toml
# Paths to exclude from scanning
[ignore]
paths = ["tests/**", "benches/**", "vendor/**"]
# Relative weights (normalized internally — no need to sum to 100)
[scoring.weights]
cycle = 35
layering = 25
hub = 20
coupling = 10
cognitive = 5
instability = 5
# Thresholds for debt detection
[scoring.thresholds]
hub_exemption_ratio = 0.3 # fan_out/(fan_in+1) below this = shared core
entry_point_max_fan_in = 2 # max fan-in to qualify as entry point
brittle_instability_ratio = 0.8 # I > this = flagged as brittle
# Architectural boundary rules
[[scoring.boundaries]]
from = "runtime/"
deny = ["cli/"]
# Module-level exemptions
[scoring.exemptions]
hub_exempt = ["deno_core"]
instability_exempt = []
entry_point_stems = ["main", "index", "app", "lib", "mod"]
```
All fields are optional. Omitted values use sensible defaults. See [`morpharch.example.toml`](morpharch.example.toml) for a fully commented reference.
---
## Contributing
1. Fork the repository and create a feature branch.
2. Ensure all tests pass: `cargo test`
3. Run clippy: `cargo clippy -- -D warnings`
4. Run fmt: `cargo fmt --all`
---
## License
Apache License, Version 2.0 or MIT License.