README
¶
archfit
Architecture fitness checker for Go, TypeScript, and Python repositories.
archfit makes selected architecture rules executable. It reads dependency facts
from a repository, compares them with .archfit.yaml, and reports findings that
humans, CI, or AI coding agents can act on.
Use it when you want fast feedback on architecture drift: boundary leaks, layer violations, import cycles, new cross-module dependencies, or coupling risk.
What you get
- Deterministic gates for dependencies, public APIs, layers, cycles, and configured thresholds.
- Architecture metrics for modularity, coupling risk, coverage, change locality, and other drift signals.
- Baselines so accepted current debt does not hide new findings.
- SARIF, Markdown, JSON, and text output for local work, CI, and code scanning.
- Structured
agent_tasksrepair blocks for AI-agent feedback loops. - Optional LLM enrichment for coupling-label drafts, kept off the CI gate.
Quick start
Install the CLI:
go install github.com/alexei-led/archfit/cmd/archfit@v0.1.0
Or run the Docker image:
docker run --rm -v "$(pwd):/repo" ghcr.io/alexei-led/archfit:latest \
check --config /repo/.archfit.yaml --full
Run the first check in a repository:
archfit doctor
archfit init --root . --output .archfit.yaml
$EDITOR .archfit.yaml
archfit check --config .archfit.yaml --full
Accept current findings as a baseline when they represent known debt:
archfit baseline --full --config .archfit.yaml
Need Docker, CI, optional analyzers, or language-specific setup? Start with the guide.
Core commands
| Command | Use |
|---|---|
archfit doctor |
Check local analyzer/tool availability. |
archfit init |
Generate a starter .archfit.yaml. |
archfit check |
Run architecture gates and metrics. |
archfit scan |
Produce a full Markdown audit report. |
archfit baseline |
Save accepted current findings. |
archfit enrich |
Draft off-gate LLM coupling-label refinements. |
archfit explain <id> |
Explain one finding by fingerprint prefix. |
archfit install |
Check or install optional language tools. |
See the commands guide for formats, exit codes, and examples.
Model
archfit operationalizes the parts of Vlad Khononov's Balanced Coupling model
that can be checked from code, configuration, and git history. It uses the
model's strength, distance, and volatility vocabulary, plus explicitness, to
explain why a relationship is balanced or risky.
It does not replace architecture review. It makes repeatable evidence cheap to collect and safe to run in CI. For the books, posts, and mapping from theory to signals, see Concepts and Metrics.
Documentation
- Guide — documentation map.
- Install — Go install, Docker, and optional tools.
- Quick start — first useful run.
- Configuration —
.archfit.yamlbasics. - CI — pull-request and pipeline setup.
- Agent feedback —
agent_tasks, SARIF, andchange_locality. - LLM enrichment — human-reviewed label drafts.
- Contributing — local development and release notes.
License
Apache-2.0. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
archfit
command
enrich: the off-gate LLM workflow that drafts coupling-strength label refinements for human review.
|
enrich: the off-gate LLM workflow that drafts coupling-strength label refinements for human review. |
|
internal
|
|
|
agenttask
Package agenttask assembles the structured repair-task block (spec §13) from gate findings.
|
Package agenttask assembles the structured repair-task block (spec §13) from gate findings. |
|
baseline
Package baseline handles loading and saving the archfit baseline file, which tracks accepted findings and metric snapshots across runs.
|
Package baseline handles loading and saving the archfit baseline file, which tracks accepted findings and metric snapshots across runs. |
|
classify
Package classify assigns Balanced Coupling classifications to graph edges: strength, distance, volatility, and explicitness.
|
Package classify assigns Balanced Coupling classifications to graph edges: strength, distance, volatility, and explicitness. |
|
config
Package config defines the Config struct, its view projections, and the Load function that parses and validates an archfit.yaml configuration file.
|
Package config defines the Config struct, its view projections, and the Load function that parses and validates an archfit.yaml configuration file. |
|
engine
Package engine implements the pipeline orchestrator that runs extractors, classify, rules, status, metrics, and renderers in sequence.
|
Package engine implements the pipeline orchestrator that runs extractors, classify, rules, status, metrics, and renderers in sequence. |
|
extract/astgrep
Package astgrep implements the ports.PatternProvider port for ast-grep.
|
Package astgrep implements the ports.PatternProvider port for ast-grep. |
|
extract/clones
Package clones provides a clone-detection runner that identifies duplicated code blocks across files.
|
Package clones provides a clone-detection runner that identifies duplicated code blocks across files. |
|
extract/complexity
Package complexity provides a cyclomatic-complexity runner that collects per-function CCN values via the external lizard tool.
|
Package complexity provides a cyclomatic-complexity runner that collects per-function CCN values via the external lizard tool. |
|
extract/gitnexus
Package gitnexus provides an optional, opt-in dependant-count provider backed by the gitnexus CLI's knowledge graph.
|
Package gitnexus provides an optional, opt-in dependant-count provider backed by the gitnexus CLI's knowledge graph. |
|
extract/golang
Package golang implements the Go import extractor using golang.org/x/tools/go/packages.
|
Package golang implements the Go import extractor using golang.org/x/tools/go/packages. |
|
extract/loc
Package loc counts source-file line counts for the structural_weight metric.
|
Package loc counts source-file line counts for the structural_weight metric. |
|
extract/py
Package py implements the Python import extractor using grimp.
|
Package py implements the Python import extractor using grimp. |
|
extract/scip
Package scip implements the ports.SymbolResolver port using SCIP indexers.
|
Package scip implements the ports.SymbolResolver port using SCIP indexers. |
|
extract/ts
Package ts implements the TypeScript import extractor using dependency-cruiser.
|
Package ts implements the TypeScript import extractor using dependency-cruiser. |
|
facts
Package facts assembles per-module structural facts from already-collected data (symbol graph, file LOC, co-change history, optional gitnexus impact).
|
Package facts assembles per-module structural facts from already-collected data (symbol graph, file LOC, co-change history, optional gitnexus impact). |
|
fitness
Package fitness detects architecture-intent ENFORCEMENT signals in a repository.
|
Package fitness detects architecture-intent ENFORCEMENT signals in a repository. |
|
history/git
Package git provides functions for reading git history: changed files between refs, the HEAD ref, repo root, and a churn stats stub.
|
Package git provides functions for reading git history: changed files between refs, the HEAD ref, repo root, and a churn stats stub. |
|
initcfg
Package initcfg discovers project structure and renders a starter .archfit.yaml.
|
Package initcfg discovers project structure and renders a starter .archfit.yaml. |
|
labels
Package labels loads and validates pinned coupling-strength labels — the human-reviewed output of `archfit enrich`.
|
Package labels loads and validates pinned coupling-strength labels — the human-reviewed output of `archfit enrich`. |
|
llm
Package llm is the thin off-gate LLM provider layer for archfit's enrich and explain commands.
|
Package llm is the thin off-gate LLM provider layer for archfit's enrich and explain commands. |
|
metrics
Package metrics defines the Metric interface, the generic Calculator[In] adapter, and the New() registry.
|
Package metrics defines the Metric interface, the generic Calculator[In] adapter, and the New() registry. |
|
metrics/boundary
Package boundary implements the five boundary-health metrics: encapsulation, unbalanced_edge, cycle, coverage, and change_locality.
|
Package boundary implements the five boundary-health metrics: encapsulation, unbalanced_edge, cycle, coverage, and change_locality. |
|
metrics/internal/modgraph
Package modgraph provides the shared module-level graph and history helpers used by the modularity metrics: collapsing nodes/files to module units, aggregating churn, and computing SCC-condensed blast radius.
|
Package modgraph provides the shared module-level graph and history helpers used by the modularity metrics: collapsing nodes/files to module units, aggregating churn, and computing SCC-condensed blast radius. |
|
metrics/internal/result
Package result provides shared scoring helpers for the metrics layer: band names, confidence constants, mode constants, and the utility functions that map scores to bands, apply confidence caps, compute deltas, and build indeterminate (n/a) count results.
|
Package result provides shared scoring helpers for the metrics layer: band names, confidence constants, mode constants, and the utility functions that map scores to bands, apply confidence caps, compute deltas, and build indeterminate (n/a) count results. |
|
metrics/intramodule
Package intramodule holds the intra-module quality metrics — signals about the internals of a module (function complexity, architecture-enforcement presence) rather than its coupling to other modules.
|
Package intramodule holds the intra-module quality metrics — signals about the internals of a module (function complexity, architecture-enforcement presence) rather than its coupling to other modules. |
|
metrics/metricstest
Package metricstest provides shared test helpers for metric family packages.
|
Package metricstest provides shared test helpers for metric family packages. |
|
metrics/modularity
Package modularity implements the modularity metrics (blast_radius, change_amplification, hidden_coupling, structural_weight) and the functional_candidates metric.
|
Package modularity implements the modularity metrics (blast_radius, change_amplification, hidden_coupling, structural_weight) and the functional_candidates metric. |
|
metrics/risk
Package risk implements the risk_hub architecture metric, which surfaces modules whose cross-module symbol-surface breadth and explicit config volatility identify the highest-risk coupling hubs.
|
Package risk implements the risk_hub architecture metric, which surfaces modules whose cross-module symbol-surface breadth and explicit config volatility identify the highest-risk coupling hubs. |
|
model/clone
Package clone holds the neutral value types for clone-detection results so that core-ring packages (e.g.
|
Package clone holds the neutral value types for clone-detection results so that core-ring packages (e.g. |
|
model/coupling
Package coupling defines the Balanced Coupling classification types: Strength, Distance, Volatility, Explicitness, and the Classification index.
|
Package coupling defines the Balanced Coupling classification types: Strength, Distance, Volatility, Explicitness, and the Classification index. |
|
model/diagnostic
Package diagnostic defines the top-level output contract: Diagnostic, MetricResult, Verdict, and the supporting summary and coverage types.
|
Package diagnostic defines the top-level output contract: Diagnostic, MetricResult, Verdict, and the supporting summary and coverage types. |
|
model/finding
Package finding defines the Finding type and its sealed constructor.
|
Package finding defines the Finding type and its sealed constructor. |
|
model/graph
Package graph defines the sealed graph types: Node, Edge, and the Build constructor that deduplicates, sorts, and freezes extractor output into a deterministic, immutable Graph.
|
Package graph defines the sealed graph types: Node, Edge, and the Build constructor that deduplicates, sorts, and freezes extractor output into a deterministic, immutable Graph. |
|
model/pattern
Package pattern defines the shared structural match result type produced by pattern-search ports (PatternProvider) and consumed by rules as evidence.
|
Package pattern defines the shared structural match result type produced by pattern-search ports (PatternProvider) and consumed by rules as evidence. |
|
model/signal
Package signal defines the carrier types that flow between signal producers (fitness scanner, git history, complexity tool) and the metrics layer: the per-family metric inputs (CommonInput, HistoryInput, SymbolInput, SizeInput, ComplexityInput, FitnessInput, DuplicationInput), the CollectedSignals bag the engine assembles and projects per family, and the RunSignals bundle the cmd layer produces.
|
Package signal defines the carrier types that flow between signal producers (fitness scanner, git history, complexity tool) and the metrics layer: the per-family metric inputs (CommonInput, HistoryInput, SymbolInput, SizeInput, ComplexityInput, FitnessInput, DuplicationInput), the CollectedSignals bag the engine assembles and projects per family, and the RunSignals bundle the cmd layer produces. |
|
model/symbol
Package symbol defines the domain type for per-symbol metadata extracted from a SCIP (or equivalent) index.
|
Package symbol defines the domain type for per-symbol metadata extracted from a SCIP (or equivalent) index. |
|
output/console
Package console renders a Diagnostic as clean, LLM-friendly plain text: labelled sections of aligned key/value lines, no box-drawing tables.
|
Package console renders a Diagnostic as clean, LLM-friendly plain text: labelled sections of aligned key/value lines, no box-drawing tables. |
|
output/jsonout
Package jsonout implements the JSON renderer for diagnostic output.
|
Package jsonout implements the JSON renderer for diagnostic output. |
|
output/markdown
Package markdown renders a Diagnostic as clean, LLM-friendly Markdown: `##` sections and `-` lists, no box-drawing tables (which do not align in raw text).
|
Package markdown renders a Diagnostic as clean, LLM-friendly Markdown: `##` sections and `-` lists, no box-drawing tables (which do not align in raw text). |
|
output/sarif
Package sarif renders a Diagnostic as a SARIF 2.1.0 log (spec §12) so CI systems (GitHub code scanning et al.) can surface findings inline on PRs — the agent/CI half of the feedback loop.
|
Package sarif renders a Diagnostic as a SARIF 2.1.0 log (spec §12) so CI systems (GitHub code scanning et al.) can surface findings inline on PRs — the agent/CI half of the feedback loop. |
|
ownership
Package ownership resolves module owners from CODEOWNERS files or git-author history, producing a module→owner map that fills gaps in config-authored ownership metadata.
|
Package ownership resolves module owners from CODEOWNERS files or git-author history, producing a module→owner map that fills gaps in config-authored ownership metadata. |
|
ports
Package ports defines the hexagonal port interfaces that separate the engine orchestrator from its adapters.
|
Package ports defines the hexagonal port interfaces that separate the engine orchestrator from its adapters. |
|
rules
Package rules defines the Rule interface and the built-in rule implementations: forbidden_dependency, public_api_only, forbidden_layer_direction, internal_api_access, new_cross_module_dependency, and cycle.
|
Package rules defines the Rule interface and the built-in rule implementations: forbidden_dependency, public_api_only, forbidden_layer_direction, internal_api_access, new_cross_module_dependency, and cycle. |
|
scope
Package scope resolves the analysis scope: the repo root, changed files (delta mode), and the mode (full vs delta) for a run.
|
Package scope resolves the analysis scope: the repo root, changed files (delta mode), and the mode (full vs delta) for a run. |
|
staleness
Package staleness detects map-quality advisory findings: uncovered paths, dead module rules, and stale reviewed_at timestamps.
|
Package staleness detects map-quality advisory findings: uncovered paths, dead module rules, and stale reviewed_at timestamps. |
|
status
Package status assigns status labels (new, baseline, excepted, expired_exception, fixed) to findings by comparing against a baseline and exception set.
|
Package status assigns status labels (new, baseline, excepted, expired_exception, fixed) to findings by comparing against a baseline and exception set. |
|
toolrun
Package toolrun defines the Runner interface and its concrete implementation.
|
Package toolrun defines the Runner interface and its concrete implementation. |
Click to show internal directories.
Click to hide internal directories.