archlint

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

Architecture linter for Go (also scans external Rust/TS codebases). Structural graphs, dependency cycles, SOLID metrics, agent-ready quality gate (MCP).

archlint is a pure-Go tool. Go is the primary target; it can also scan external Rust and TypeScript projects to build their structural graph.

For AI agents: archlint exposes an MCP server (severity + remediation + human-in-the-loop per violation) — see docs/mcp-setup.md and docs/agent-gate.md.

---

Quick Start

Pure-Go workflow — no Python required:

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

# 2. Scan for violations (quality gate)
archlint scan .

# 3. Collect the architecture graph (Go; also scans external Rust/TS)
archlint collect . -o architecture.yaml

# 4. Install the repo-local pre-commit gate
make setup-hooks

For AI agents, start the MCP server instead:

archlint serve   # MCP server for Claude Code / Cursor — see docs/mcp-setup.md

---

Local dev gate (pre-commit)

Repo-local architecture gate that travels with the repo (not a global hook):

make setup-hooks   # sets core.hooksPath -> .githooks (committed pre-commit)

After this, every commit runs make gate (~1.7s): a delta-ERROR check that blocks new ERROR-class violations (cycles / layer / ISP / dead-code) vs .archlint-baseline.json. Existing baseline debt does not block. Bypass in exceptional cases with git commit --no-verify.

---

Docker

The easiest way to run archlint without installing Go:

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

# Validate the graph with the built-in Go engine
docker run --rm -v $(pwd):/workspace ghcr.io/mshogin/archlint validate /workspace

# Collect graph to a file (Go; also scans external Rust/TS)
docker run --rm -v $(pwd):/workspace ghcr.io/mshogin/archlint collect /workspace -o /workspace/architecture.yaml

Image includes: the Go binary (archlint) and, optionally, the research validator.

---

Requirements

• Go 1.21+ - for the archlint binary (the only requirement for the production path)
• Python 3.12+ - OPTIONAL, only for the legacy/research validator (pip install networkx numpy scipy)

---

Commands

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 with the built-in Go engine
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 agent integration (Claude Code / Cursor) — see docs/mcp-setup.md
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

---

validate Command

The validate command runs the built-in Go engine against a directory or a previously collected graph:

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

# Validate an existing .yaml file
archlint validate architecture.yaml

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

The --python flag is now a NO-OP. The production validate path runs entirely on the built-in Go engine. The Python validator is documented separately under Legacy / Research validator.

---

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 (pure Go, no extra deps)
archlint scan . --threshold 0 --format json

---

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

---

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
archlint validate architecture.yaml

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 diff HEAD~5..HEAD
archlint diff main..feature --dir ./myproject --format json

Watch mode

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

---

MCP Server (agent integration)

Start the MCP server so AI agents (Claude Code / Cursor) can call archlint as a quality gate — each violation carries severity, remediation, and a human-in-the-loop hook.

archlint serve

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

See docs/mcp-setup.md and docs/agent-gate.md for setup.

---

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 AST analyzer (+ external Rust/TS scanners)
│   ├── 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
├── validator/             # Legacy/research Python validator (optional, see below)
├── action.yml             # GitHub Action definition
├── .archlint.yaml         # archlint config for this repo
└── specs/                 # Feature specs (todo/inprogress/done)

---

Test Coverage

go 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.

---

Add Your Project

Want archlint to monitor your project's architecture?

1. Create an issue with your repo URL
2. We'll review and add your project to monitoring
3. Architecture metrics will be published at archlint.ru/projects/your-org/your-repo

---

Legacy / Research validator (optional)

The production path is pure Go: archlint scan (gate) and archlint validate (built-in Go engine). The Python validator below is research mathematics (topology, spectral analysis, information / game / category theory), not a production gate. It is optional and not part of the shipped binary — the archlint validate --python flag is now a NO-OP.

Use it only if you want to explore the research metrics against a graph produced by archlint collect.

pip install networkx numpy scipy

# Collect the graph with archlint, then run the validator directly
archlint collect . -o architecture.yaml
python3 -m validator validate architecture.yaml

# Focus on a specific group
python3 -m validator validate architecture.yaml --group solid
python3 -m validator validate architecture.yaml --group research

# 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

The 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

---

License

MIT

Contacts

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