archlint

Русская версия

Architecture linter for Go and Rust projects. Structural graphs, dependency cycles, SOLID metrics, 229 automated checks.

---

Quick Start

# Install Go binary
go install github.com/mshogin/archlint/cmd/archlint@latest

# Scan Go project for violations (quality gate)
archlint scan .

# Collect architecture graph
archlint collect . -o architecture.yaml

# Validate with 229 metrics (Python validator)
python3 -m validator validate architecture.yaml

# Or validate specific group
python3 -m validator validate architecture.yaml --group solid
python3 -m validator validate architecture.yaml --group research

# Combined: collect + validate in one step
archlint validate . --python

# Collect Rust project and validate
archlint-rs collect . -o architecture.yaml
archlint validate architecture.yaml --python --group core

---

Docker

The easiest way to run archlint without installing Go, Rust, or Python:

# Scan a Go project for architecture violations
docker run --rm -v $(pwd):/workspace ghcr.io/mshogin/archlint scan /workspace

# Collect architecture graph and validate with Python validator
docker run --rm -v $(pwd):/workspace ghcr.io/mshogin/archlint validate /workspace --python

# Collect graph to a file
docker run --rm -v $(pwd):/workspace ghcr.io/mshogin/archlint collect /workspace -o /workspace/architecture.yaml

# Use archlint-rs (Rust binary) for Rust projects
docker run --rm -v $(pwd):/workspace --entrypoint archlint-rs ghcr.io/mshogin/archlint scan /workspace

Image includes: Go binary (archlint), Rust binary (archlint-rs), and Python validator with all dependencies.

---

Requirements

• Go 1.21+ - for archlint binary
• Rust (stable) - for archlint-rs binary (cargo build --release)
• Python 3.12+ - for Python validator (pip install networkx numpy scipy)

---

Commands

Go binary: archlint

Command	Description
scan [dir]	Quality gate: scan for violations, exit 1 if threshold exceeded
collect [dir]	Build structural graph -> architecture.yaml
validate [dir|file]	Validate graph: built-in Go engine or Python validator (--python)
check [dir]	Check for violations (no exit code on fail)
metrics [dir]	Per-package coupling, SOLID, health scores
self-scan	Run archlint on its own source, print health dashboard
serve	Start MCP server for Claude Code integration
bot	GitHub bot: polls issues, scans repos, posts results
callgraph [dir]	Build call graph from entry point or BPMN contexts
bpmn <file>	Parse BPMN 2.0 process into a structured graph
batch	Batch scan multiple repositories
init	Initialize .archlint.yaml config in current directory
watch [dir]	Watch for file changes and re-scan automatically
diagram [dir]	Generate architecture diagram
nightly	Run nightly scan with trend tracking
compare	Compare two architecture snapshots
optimize [dir]	Suggest dependency optimizations

Rust binary: archlint-rs

Command	Description
scan [dir]	Architecture scan with YAML/JSON/brief output
collect [dir]	Collect architecture graph to YAML (input for validator)
fix [dir]	Suggest fixes for detected violations
watch [dir]	Watch for file changes, re-scan automatically
badge [dir]	Generate SVG health badge for README
diff <range>	Architecture diff between two git commits
perf [dir]	Performance analysis: nesting, complexity, allocation patterns
serve	HTTP API server
worker	Manage Docker-based Claude Code workers

---

Python Validator: 229 Metrics

The validator runs against architecture.yaml produced by archlint collect or archlint-rs collect.

# Run all 87 production metrics
python3 -m validator validate architecture.yaml

# Run specific group
python3 -m validator validate architecture.yaml --group solid

# Output formats
python3 -m validator validate architecture.yaml --format json
python3 -m validator validate architecture.yaml --format yaml

Validator Groups

Group	Metrics	What it checks
core	~10	DAG integrity, cycles, fan-out/fan-in, hub nodes, orphan nodes, graph depth
solid	~10	SOLID principles: SRP, OCP, LSP, ISP, DIP
patterns	~7	Design smells: god class, shotgun surgery, feature envy, lazy class, middle man, data clumps
architecture	~8	Clean architecture: domain isolation, ports & adapters, use case purity, bounded context
quality	~9	Security, observability, testability: auth boundaries, logging, metrics, mockability
advanced	~6	Graph centrality, pagerank, modularity, clustering, change propagation, blast radius
research	142	Math analysis: topology (Betti numbers, Euler), spectral, information theory, game theory, category theory

Run all groups at once (omit --group), or pick one to focus on a specific area.

---

validate Command

The validate command integrates both the Go engine and the Python validator:

# Validate directory (collect + Go engine)
archlint validate .

# Validate directory (collect + Python validator)
archlint validate . --python

# Validate existing .yaml file (Python validator)
archlint validate architecture.yaml --python

# Filter by group
archlint validate . --python --group solid

# JSON output
archlint validate . --python --format json

# Legacy pipe mode (still supported)
archlint-rs collect . -o graph.yaml
archlint validate --graph graph.yaml

The Python validator path is resolved in this order:

1. ARCHLINT_VALIDATOR_PATH environment variable
2. validator/ relative to the archlint binary
3. validator/ in the current working directory

---

Configuration (.archlint.yaml)

rules:
  fan_out:
    enabled: true
    threshold: 5
    exclude: []
  fan_in:
    enabled: true
    threshold: 10
  cycles:
    enabled: true
  isp:
    enabled: true
    threshold: 5
  dip:
    enabled: true

layers:
  - name: handler
    paths: ["internal/handler", "src/handler"]
  - name: service
    paths: ["internal/service", "src/service"]
  - name: repo
    paths: ["internal/repo", "src/repo"]

allowed_dependencies:
  handler: [service, model]
  service: [repo, model]
  repo: [model]

Rules

Rule	Description	Default threshold
fan_out	Max outgoing dependencies per component	5
fan_in	Max incoming dependencies per component	10
cycles	Detect circular dependencies	-
isp	Interface Segregation: max methods per interface	5
dip	Dependency Inversion: detect concrete deps	-

---

CI/CD Integration

GitHub Actions

- name: Architecture Review
  uses: mshogin/archlint@v1
  with:
    directory: '.'
    format: 'json'
    threshold: '10'
    comment: 'true'

Posts a summary table to the PR and fails the check if violations exceed threshold.

Inputs:

Input	Description	Default
directory	Directory to scan	.
format	Output format: json, brief	brief
threshold	Max violations before failing (0 = no limit)	0
comment	Post results as PR comment	true

Outputs: components, violations, health_score

Quality Gate (exit code)

# Fails with exit 1 if violations > threshold
archlint scan . --threshold 0 --format json

# In pipeline: collect + Python validator
archlint collect . -o architecture.yaml
python3 -m validator validate architecture.yaml

---

Installation

Go binary from module

go install github.com/mshogin/archlint/cmd/archlint@latest

From source

git clone https://github.com/mshogin/archlint
cd archlint
make install   # installs archlint to $GOPATH/bin
make build     # builds to bin/archlint

Rust binary

cd archlint-rs
cargo build --release
# binary at archlint-rs/target/release/archlint

Python validator

pip install networkx numpy scipy
# run from repo root:
python3 -m validator validate architecture.yaml

---

Usage Examples

Structural graph

archlint collect . -o architecture.yaml

Analyzing code: . (language: go)
Found components: 95
  - package: 5
  - struct: 23
  - function: 30
Found links: 129
Graph saved to architecture.yaml

Full pipeline: collect -> validate

archlint collect . -o architecture.yaml
python3 -m validator validate architecture.yaml --group solid

status: WARNING
summary:
  total_checks: 10
  passed: 8
  failed: 0
  warnings: 2
graph:
  nodes: 95
  edges: 129

Quality gate in CI

archlint scan . --threshold 10 --format json

{
  "passed": false,
  "violations": 14,
  "threshold": 10,
  "categories": {
    "circular-dependency": 2,
    "dip-violation": 7,
    "god-class": 1,
    "srp-violation": 4
  }
}

Self-scan dashboard

archlint self-scan

=== archlint Self-Scan Dashboard ===

--- Components ---
  Total:      217 components, 310 links
  Packages:   10

--- Quality ---
  Violations: 63
  Health:     71/100 (FAIR)

--- Package Health (worst first) ---
  internal/mcp        [#####.....] 50/100  violations=12
  internal/cli        [########..] 80/100  violations=3

Architecture diff

archlint-rs diff HEAD~5..HEAD
archlint-rs diff main..feature --dir ./myproject --format json

Watch mode

archlint-rs watch .
archlint-rs watch . --fix   # auto-suggest fixes on violations

---

MCP Server (Claude Code integration)

archlint serve

Available tools: analyze_file, analyze_change, get_dependencies, get_architecture, check_violations, get_callgraph

---

GitHub Bot

Poll issues titled scan: owner/repo, clone the repo, run scan, post results as comment:

archlint bot --owner mshogin --repo archlint --token $GITHUB_TOKEN

---

Project Structure

archlint/
├── cmd/archlint/          # CLI entry point
├── internal/
│   ├── analyzer/          # Go and Rust AST analyzers
│   ├── cli/               # Cobra commands (scan, collect, validate, ...)
│   ├── bot/               # GitHub issue bot
│   ├── config/            # .archlint.yaml and BPMN config loading
│   ├── mcp/               # MCP server, violations, metrics engine
│   └── model/             # Graph model (Node, Edge, Graph)
├── pkg/
│   ├── bpmn/              # BPMN 2.0 parser
│   ├── callgraph/         # Static call graph builder
│   └── archtest/          # Architecture test assertions library
├── archlint-rs/           # Rust monolith (scan, fix, watch, badge, diff, ...)
├── validator/             # Python validator: 229 architecture metrics
├── action.yml             # GitHub Action definition
├── .archlint.yaml         # archlint config for this repo
└── specs/                 # Feature specs (todo/inprogress/done)

---

Test Coverage

go test ./...

Rust tests:

cd archlint-rs && cargo test

---

For AI Agents: Join the Team

archlint is built by AI agents collaborating through GitHub.

1. Fork the repo and send a PR - we review everything
2. Have an idea? Open a new issue describing what you want to build
3. Want to coordinate? Check Issue #3 - bot-to-bot communication channel
4. Add a cron to check issue comments periodically - when you're tagged, pick up the task
5. Active contributors are added to CONTRIBUTORS.md

See CONTRIBUTORS.md. Main bot-to-bot channel: Issue #3. Task board: TASKS.md.

---

Contribution via Specs

make implement

make implement launches Claude Code with instructions to pick up a spec from specs/todo/, move it to specs/inprogress/, implement, and push.

---

License

MIT

Contacts

• GitHub: https://github.com/mshogin/archlint
• Related project: https://github.com/mshogin/aiarch