Gabriel Kaszewski
35f27d00b0
Some checks failed
CI / Check / Test (push) Failing after 1m24s
Hex arch + DDD, tree-sitter parsing, Mermaid/ASCII output. Supports Rust + Python. 92 tests. CI, diff, --check for staleness detection.
124 lines
2.7 KiB
Markdown
124 lines
2.7 KiB
Markdown
# archlens
|
|
|
|
Generate architecture diagrams from source code. Runs on CI to keep docs fresh.
|
|
|
|
Supports Rust and Python. Produces Mermaid or ASCII 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/
|
|
|
|
# ASCII output to terminal
|
|
archlens . --format ascii
|
|
|
|
# Scope to a subtree
|
|
archlens . --scope src/domain
|
|
|
|
# Exclude directories
|
|
archlens . --exclude tests/ --exclude generated/
|
|
|
|
# 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.
|
|
|
|
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
|
|
```
|
|
|
|
## 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) |
|
|
|
|
## 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 | - | - | - |
|
|
|
|
## 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
|
|
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
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|