Gabriel Kaszewski
fdd85011a4
P1 correctness: - filter test files by default (--include-tests to opt in) - per-module diagrams show cross-module dependency arrows - qualified type names (Module::TypeName) fix false edges from duplicate names P2 output richness: - method parameter types and return types in class diagrams (Rust + Python) - Python pyproject.toml project analyzer (--level project for monorepos) P3 unique value: - boundary rules in archlens.toml ([rules] allow/deny, --strict enforcement) P4 nice to have: - dependency weight labels on module arrows (--no-weights to disable) - --watch mode with 500ms debounce - D2 renderer adapter (--format d2) - interactive self-contained HTML viewer (--format html) - git-aware incremental analysis (--since <ref>)
4.5 KiB
4.5 KiB
archlens
Generate architecture diagrams from source code. Runs on CI to keep docs fresh.
Supports Rust, Python and C# (planned). Produces Mermaid, D2, ASCII, or interactive HTML output.
Install
cargo install --path crates/presentation
Usage
# Module-level dependency graph (default)
archlens .
# Project-level (crate/package dependencies from manifests)
archlens . --level project
# Type-level class diagram
archlens . --level type
# Write to file
archlens . --output docs/architecture.mmd
# Split by module (one file per module + overview)
archlens . --level type --split-by-module --output docs/arch/
# D2 format
archlens . --format d2 --output docs/architecture.d2
# Interactive HTML viewer
archlens . --format html --output docs/architecture.html
# ASCII output to terminal
archlens . --format ascii
# Scope to a subtree
archlens . --scope src/domain
# Exclude directories
archlens . --exclude tests/ --exclude generated/
# Exclude test files from diagrams (default: excluded)
archlens . --include-tests
# Show/hide dependency weights on module arrows (default: shown)
archlens . --level module --no-weights
# Watch for changes and regenerate automatically
archlens . --watch
# Analyse only files changed since a git ref (useful in CI)
archlens . --since HEAD~1
# Verbose logging
archlens . -v # info
archlens . -vv # debug
CI Integration
Check if committed diagrams are up to date:
archlens . --level project --check --output docs/architecture.mmd
Exit code 1 if the diagram has changed. Use --strict to also fail on parse warnings or boundary rule violations.
Only re-analyse files changed since the last release tag:
archlens . --since v1.2.0 --output docs/architecture.mmd
Compare current state against an existing file:
archlens diff docs/architecture.mmd --level project
Config
Generate a config file:
archlens init
Creates archlens.toml:
[analysis]
exclude = ["tests/", "vendor/", "generated/"]
level = "module"
[modules]
# "src/infra" = "Infrastructure"
[output]
format = "mermaid"
# path = "docs/architecture.mmd"
split_by_module = false
[rules]
# Allowed dependency directions — unlisted directions are violations
# allow = ["Application --> Domain", "Adapters --> Domain"]
# Explicitly forbidden directions — always checked
# deny = ["Domain --> Adapters", "Domain --> Application"]
Violations are printed to stderr. Pass --strict to exit with code 1 on any violation.
Diagram Levels
| Level | What it shows | Source |
|---|---|---|
project |
Crate/package dependencies | Cargo.toml or pyproject.toml |
module |
Module-level dependency graph with coupling weights | Imports + manifest deps |
type |
Class diagram with fields, methods, signatures, relationships | Source code (tree-sitter) |
Output Formats
| Format | Flag | Extension | Notes |
|---|---|---|---|
| Mermaid | --format mermaid |
.mmd |
Default. Renders in GitHub, GitLab, Obsidian |
| D2 | --format d2 |
.d2 |
Better layout control, renders to SVG |
| ASCII | --format ascii |
.txt |
Terminal-friendly |
| HTML | --format html |
.html |
Self-contained interactive viewer, clickable nodes |
Supported Languages
| Language | Types | Inheritance | Composition | Imports | Method signatures |
|---|---|---|---|---|---|
| Rust | struct, enum, trait | impl Trait for Type |
struct fields | use, mod |
params + return type |
| Python | class | class Foo(Bar) |
__init__ params, type annotations |
import, from ... import |
typed params + return annotation |
| C# | planned | - | - | - | - |
Architecture
Built with hexagonal architecture (ports and adapters) + DDD.
crates/
domain/ # Core model, zero external deps
application/ # Use cases, orchestration
adapters/
tree-sitter/ # Source code parsing (Rust, Python)
cargo-workspace/ # Cargo.toml dependency extraction
python-project/ # pyproject.toml dependency extraction
walkdir/ # File discovery
mermaid/ # Mermaid diagram output
d2/ # D2 diagram output
ascii/ # Terminal output
html-viewer/ # Interactive HTML output
file-writer/ # Write to disk
stdout-writer/ # Write to stdout
toml-config/ # Config file parsing
presentation/ # CLI (clap), composition root
License
MIT