morpharch 1.2.5

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. 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.
• Advanced Mouse Interaction -- Zoom, pan, node dragging, and interactive timeline scrubbing.
• Dynamic UI -- Resizable sidebars and detail panels via mouse dragging.
• Blast Radius Analysis -- Visualize the potential impact of changes to a module across the entire architecture.
• 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:

curl -fsSL https://raw.githubusercontent.com/onplt/morpharch/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/onplt/morpharch/main/install.ps1 | iex

Package Managers

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 Interaction

Keyboard Shortcuts

Mouse Interaction

• Graph Interaction:
  • Scroll Wheel: Zoom in and out toward the cursor position.
  • Click & Drag (Background): Pan the graph view.
  • Click & Drag (Node): Move and pin a module node manually.
• UI Management:
  • Click & Drag (Borders): Resize the Packages sidebar and Insights panel.
• Navigation:
  • Click (Timeline): Scrub to a specific point in history.
  • Click (Lists): Select and inspect a module from the sidebar or Spots table.

Architecture Health Scoring

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

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.

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