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>)
169 lines
4.5 KiB
Markdown
169 lines
4.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
cargo install --path crates/presentation
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
archlens . --since v1.2.0 --output docs/architecture.mmd
|
|
```
|
|
|
|
Compare current state against an existing file:
|
|
|
|
```bash
|
|
archlens diff docs/architecture.mmd --level project
|
|
```
|
|
|
|
## Config
|
|
|
|
Generate a config file:
|
|
|
|
```bash
|
|
archlens init
|
|
```
|
|
|
|
Creates `archlens.toml`:
|
|
|
|
```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
|