morpharch 1.1.2

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.

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.
• 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

From crates.io

cargo install morpharch

From source

git clone https://github.com/onplt/morpharch.git
cd morpharch
cargo build --release
# Binary is at target/release/morpharch

Quick Start

# 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.

# Scan the current directory (all commits)
morpharch scan .

# Scan a specific repo, limit to last 100 commits
morpharch scan /path/to/repo -n 100

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.

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

Architecture Health

MorphArch assigns each commit a health score between 0 and 100. Higher scores indicate cleaner, more maintainable architecture.

The score is calculated by subtracting "Architectural Debt" from a base of 100:

• Cyclic dependencies (-25 pts) -- circular paths between packages that break modularity, detected via SCC analysis.
• Boundary violations (-15 pts) -- dependencies that violate layer constraints (e.g., shared libs depending on application code).
• Coupling density (-5 pts per unit > 3.5) -- penalizes excessive inter-package connections beyond a healthy threshold. Large projects like Deno are given grace for necessary complexity.

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.