feat: implement all P1/P2/P3/P4 improvements from issue backlog
Some checks failed
CI / Check / Test (push) Failing after 1m33s
Architecture Docs / Generate diagrams (push) Successful in 3m21s

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>)
This commit is contained in:
2026-06-17 09:50:50 +02:00
parent 27197062eb
commit fdd85011a4
42 changed files with 2767 additions and 92 deletions

View File

@@ -2,7 +2,7 @@
Generate architecture diagrams from source code. Runs on CI to keep docs fresh.
Supports Rust and Python. Produces Mermaid or ASCII output.
Supports Rust, Python and C# (planned). Produces Mermaid, D2, ASCII, or interactive HTML output.
## Install
@@ -28,6 +28,12 @@ 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
@@ -37,6 +43,18 @@ 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
@@ -50,7 +68,13 @@ 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.
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:
@@ -80,23 +104,41 @@ level = "module"
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` |
| `module` | Module-level dependency graph | Imports + manifest deps |
| `type` | Class diagram with fields, methods, relationships | Source code (tree-sitter) |
| `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 |
|----------|-------|-------------|-------------|---------|
| Rust | struct, enum, trait | `impl Trait for Type` | struct fields | `use`, `mod` |
| Python | class | `class Foo(Bar)` | `__init__` params, type annotations | `import`, `from ... import` |
| C# | planned | - | - | - |
| 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
@@ -104,18 +146,21 @@ Built with hexagonal architecture (ports and adapters) + DDD.
```
crates/
domain/ # Core model, zero external deps
application/ # Use cases, orchestration
domain/ # Core model, zero external deps
application/ # Use cases, orchestration
adapters/
tree-sitter/ # Source code parsing (Rust, Python)
cargo-workspace/ # Cargo.toml dependency extraction
walkdir/ # File discovery
mermaid/ # Mermaid diagram output
ascii/ # Terminal output
file-writer/ # Write to disk
stdout-writer/ # Write to stdout
toml-config/ # Config file parsing
presentation/ # CLI (clap), composition root
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