# 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