feat: implement all P1/P2/P3/P4 improvements from issue backlog
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:
87
README.md
87
README.md
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user