archcheck

KO | EN

gitlite — search

#hacktoberfest #android #machine-learning #rust #deep-learning #linux #macos #cli #vue #pytorch #security #mcp #openai #open-source

(★ 21)

Architecture testing and dependency rules for C++ projects

archcheck Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# archcheck

[![CI](https://github.com/blurman-ai/archcheck/actions/workflows/ci.yml/badge.svg)](https://github.com/blurman-ai/archcheck/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/blurman-ai/archcheck)](https://github.com/blurman-ai/archcheck/releases/latest)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://raw.githubusercontent.com/blurman-ai/archcheck/master/LICENSE)

Architecture rules and drift checks for C++ CI.

![archcheck --diff reporting copy-paste introduced by a pull request](https://raw.githubusercontent.com/blurman-ai/archcheck/master/docs/assets/archcheck-diff-demo.gif)

*A PR copies a function — `archcheck --diff` names the clone and its source, `file:line` both
ways. Output recorded verbatim from the [live demo repo](https://github.com/blurman-ai/archcheck-demo).*

## Why

C++ projects degrade over time:

- layers stop being layers
- modules start depending on everything
- include graph turns into spaghetti

Code review doesn’t catch this.
Linters don’t check architecture.
AI-assisted coding makes external structural checks more important: agents can
struggle to preserve constraints across long contexts (*constraint decay*,
[Dente et al., EURECOM, 2026](docs/research/constraint_decay.md)). The prompt
degrades with context; CI doesn’t.

**archcheck keeps the hard CI gate narrow, and reports the rest as explicit advisories.**

---

## What it does (today, v0.1)

- Scans `.h` / `.cpp` sources with a fast preprocessor pass — no `compile_commands.json` required
- Builds the include-dependency graph and detects cycles, deep chains, and god-headers
- Runs five default intrinsic rules sourced from C++ Core Guidelines and Lakos:
  - **SF.9** — no cycles in the include graph (**gating** in plain check mode)
  - **SF.7** — no `using namespace` in headers (**advisory**)
  - **SF.8** — every header has `#pragma once` or include guard (**advisory**)
  - **Lakos.GodHeader** — fan-in ≤ 50 incoming includes (**advisory** in check mode)
  - **Lakos.ChainLength** — include-chain depth ≤ 10 (**advisory**)
- Checks local `#include` resolution: **CASE_MISMATCH_INCLUDE** — a quoted include that resolves only when filesystem case is ignored (`#include "core/Board.hpp"` for `core/board.hpp`), a real build break on case-sensitive Linux (**gating**); **UNRESOLVED_LOCAL_INCLUDE** — a quoted local include that resolves nowhere (**advisory**; `--fail-on-unresolved-local` makes it gate). Angle-bracket / system includes are never flagged
- Reports findings as `file:line: [rule] message`; exit `1` means a gated finding, not merely "anything was reported"
- Tracks architectural drift between graph baselines: `DRIFT.1`, `DRIFT.2`, and `DRIFT.4.CYCLE` gate; `DRIFT.3`, `DRIFT.4.NEW`, `DRIFT.4.SDP`, and pre-existing findings are advisory
- Runs the canonical PR workflow with `--diff <revspec>`: new/grown cycles and new god-headers gate, while added edges, chain/NCCD growth, SATD, test co-evolution, local complexity, flag-argument drift, and new clone drift are advisory

The current signal model:

| Layer | Examples | Exit behavior |
|-------|----------|---------------|
| Core gate | SF.9 cycles, CASE_MISMATCH_INCLUDE, DRIFT.1/2/4.CYCLE, `--diff` new/grown cycles and new god-headers | exit `1` |
| Structural advisories | SF.7/SF.8, Lakos chain/god-header in check mode, added edges, NCCD/chain growth | reported, exit `0` |
| PR hygiene advisories | SATD, test co-evolution, local complexity, flag arguments, new clones | reported, exit `0` |
| History analytics | `--history` god-file growth and defect-attractor signals | report-only, exit `0` |

---

## Live demo

See the new-clone advisory fire on real pull requests:
**[blurman-ai/archcheck-demo](https://github.com/blurman-ai/archcheck-demo)** — 14 PRs on a real C
codebase (monit). Five introduce copy-paste (exact, whole-file, renamed, and edited near-misses —
a copied function with a line inserted or a token changed) and fire `DRIFT.NEW_CLONE`; five are
look-alikes that stay silent (a move, a below-threshold dup, a touched pre-existing clone, a
formatting-only change). Each firing PR gets a markdown comment (`archcheck --diff --format=md`)
with clickable links to the introduced code and its clone source.

**Granularity:** a copied function is reported, and so is a block copied *into* an existing
function — the scanner descends into function bodies, so nested copy-paste is compared as its own
unit ([#190](backlog/wip/190_crit_subfunction_clone_pass.md)). The floor is `min_tokens` (30): a
copy shorter than that is not reported at any nesting depth.

---

## Findings on real code

Include cycles archcheck flagged on well-known C++ projects, each pinned to an exact commit and
verified in both directions with `file:line` — see [docs/findings/](docs/findings/):

- **folly** — `Future.h` ⇄ `Promise.h` (trailing-include idiom, a real cycle by Lakos's definition).
- **RocksDB** — the public `db.h` ⇄ an `EXPERIMENTAL` `multi_scan.h`; the back-edge is a removable forward-declaration.
- **Windows Terminal** — `Utils.h` ⇄ `SettingContainer.h`, where the include is dead (`SettingContainer` never used in `Utils.h`).

Each write-up quotes both include lines, gives the reproduce command, and states the honest
counter-argument a maintainer might make.

---

## Case studies

### Gambit

`archcheck` was used on [Gambit](https://github.com/abhi-saurav-saroya/Gambit), a public
C++17/SFML chess project whose author had invited code review. The architecture gate was
quiet (no include cycles); the useful findings were a Linux portability issue from
case-mismatched local includes and duplicated sliding-piece move generation for bishop,
rook, and queen. The fixes were submitted as PRs, reviewed and tested locally by the
author, and merged — see [docs/case-studies/gambit.md](docs/case-studies/gambit.md).

---

## Install

Prebuilt Linux x86_64 binaries ship with every [release](https://github.com/blurman-ai/archcheck/releases/latest)
(two variants: dynamic for recent glibc, fully static for anything else — Debian 10,
RHEL 8, Astra 1.7). Each asset has a `.sha256` next to it.

```bash
V=0.1.5   # pin a version
curl -fsSLO "https://github.com/blurman-ai/archcheck/releases/download/v${V}/archcheck-${V}-linux-x86_64-static.tar.gz"
curl -fsSLO "https://github.com/blurman-ai/archcheck/releases/download/v${V}/archcheck-${V}-linux-x86_64-static.tar.gz.sha256"
sha256sum -c "archcheck-${V}-linux-x86_64-static.tar.gz.sha256"
tar -xzf "archcheck-${V}-linux-x86_64-static.tar.gz"
sudo install -m 0755 archcheck /usr/local/bin/archcheck
archcheck --version
```

For CI installation (pinned + checksummed, GitHub Actions snippets) see
[docs/ci_usage.md](docs/ci_usage.md). Prebuilt **Windows x64 and macOS arm64 binaries are
planned for the next phase** (see [docs/ROADMAP.md](docs/ROADMAP.md)); until then, other
platforms build from source — `cmake -B build -G Ninja && cmake --build build`
(C++20 compiler + CMake 3.18+; see [CONTRIBUTING.md](CONTRIBUTING.md)).

### Docker

A container image is published to GHCR on every release, based on `alpine` (not `scratch`)
because `--diff` fork/execs `git` at runtime — see [Dockerfile](Dockerfile) for the reasoning.

```bash
# Whole-tree check
docker run --rm -v "$PWD:/work" ghcr.io/blurman-ai/archcheck:0.1.5 .

# --diff needs the git history, so mount the full checkout (.git included)
docker run --rm -v "$PWD:/work" ghcr.io/blurman-ai/archcheck:0.1.5 --diff origin/main..HEAD .
```

`safe.directory` is pre-configured system-wide in the image, so a bind-mounted repo owned by a
different host uid works without extra flags.

---

## Quick start

```bash
# Default check on current directory — zero config, no flags
archcheck

# Check a specific path
archcheck path/to/src

# JSON output for CI integration. Check-mode JSON includes top-level
# "gate": "ok|fail" and per-finding "disposition": "gating|advisory".
archcheck --format json src/

# PR check — the canonical CI workflow. Exit 1 only on gated regressions
# (new/grown cycles, new god-headers); structural and hygiene drift are
# reported as advisory and never fail the run.
archcheck --diff origin/main..HEAD .
archcheck --diff --format=json origin/main..HEAD .   # machine-readable

# Freeze legacy violations, fail only on new ones
archcheck --save-baseline archcheck-baseline.json src/
archcheck --baseline      archcheck-baseline.json src/

# Alternative to --diff when you want to pin a reviewed graph snapshot in a
# file (instead of comparing two git refs): snapshot once, gate drift in CI
archcheck --save-graph-baseline graph.json src/
archcheck --drift-baseline      graph.json src/

# Validate .archcheck.yml and apply threshold overrides
archcheck --config .archcheck.yml src/

# Advisory reports (report-only, never gate)
archcheck --duplication src/
archcheck --history src/

# Quick previews: scanner stats / include-graph stats
archcheck --scan src/
archcheck --graph src/
```

**Embedding in CI?** Start with [docs/ci_usage.md](docs/ci_usage.md): both scenarios
(full repo scan and diff on PR), ready-made workflow snippets, the exit-code contract.
Common critiques (macros and `#ifdef`, C++20 modules, "isn't this a linter",
heuristic precision) are answered in [docs/faq.md](docs/faq.md).
A ready-to-copy GitHub Actions job for the PR workflow (sticky PR comment +
step summary) lives in
[`.github/workflows/example_archcheck_pr.yml`](.github/workflows/example_archcheck_pr.yml).

### Default thresholds

These thresholds apply automatically without a config file. Override any via the `thresholds:` block in `.archcheck.yml`:

| Threshold | Default value | Rule / subsystem |
|-----------|---------------|------------------|
| include chain length | `10` | `Lakos.ChainLength` |
| god-header fan-in | `50` | `Lakos.GodHeader` |
| project source extensions | `.c .C .cc .cpp .cxx .h .hh .hpp .hxx .ipp .tpp .inl .inc` | scan |
| header extensions | `.h .hh .hpp .hxx .ipp .tpp .inl .inc` | scan |

### Example output

```text
$ archcheck fixtures/sf9_no_cycles/fail_simple
a.h: [SF.9] cycle: a.h → c.h → b.h → a.h

1 violation(s) (SF.9: 1)
$ echo $?
1
```

---

## Key Features

- **Zero config** — runs with no arguments, ships sensible defaults; no `compile_commands.json` needed
- **CI-first** — deterministic output; non-zero exit only for gated findings
- **Baseline-friendly** — freeze legacy, fail on new (`--baseline`, `--save-baseline`)
- **Drift detection** — track architecture across revisions (`--drift-baseline`, `--diff`)
- **Sourced** — every default rule cites a published authority (Core Guidelines, Lakos)

---

## Output formats

- `text` (default) — human-readable, line-oriented
- `json` — stable schema for CI integration

---

## What it is NOT

- Not a linter (clang-tidy's job)
- Not a bug finder (PVS-Studio, Coverity, cppcheck)
- Not a formatter (clang-format)
- Not an include optimizer (IWYU)
- Not a GUI, not a web dashboard, not an IDE extension — CLI and CI only

archcheck is not a clang-tidy replacement. Its hygiene signals are diff-scoped,
advisory-first regression hints for CI, not broad style or semantic linting.

---

## Planned (v0.2+)

The original pitch promised module-mapping with YAML-declared dependency rules. This is real, just deferred — see [docs/architecture-spec.md](docs/architecture-spec.md) and the ADR trail in `backlog/completed/`.

- **YAML module-rule enforcement** — the `.archcheck.yml` v1 schema (`modules:` + `rules:` with `layers` / `independence` / `forbidden`, see [docs/config_format.md](docs/config_format.md)) is already parsed, validated and auto-discovered, and `thresholds:` overrides already apply; *enforcement* of module rules lands v0.2
- **`archcheck init`** scaffolding command — v0.2
- **`--with-clang`** semantic backend (libclang) — unlocks SF.21 and the remaining SF.* rules — v0.2
- **SARIF** output — when semantic rules ship
- **Color TTY output** — once a track decision lands

The defaults that ship today were chosen precisely so a YAML config is not required for useful CI feedback on day one.

---

## Status

v0.1 in active development. Shipped: five default rules, baselines, graph drift gate
(`DRIFT.1/2/4.CYCLE` gating + `DRIFT.3/4.NEW/4.SDP` advisory), PR diff mode,
check/diff JSON, advisory duplication and history reports. Module-rule enforcement
from YAML is the **v0.2** headline by design ([ADR-001](docs/decisions/001-config-rules-deferred-to-v0.2.md)
— zero-config first); SARIF and the semantic backend are also v0.2. Current release-readiness
status lives in [backlog/TASK_TRACKER.md](backlog/TASK_TRACKER.md).

---

## Secondary goal

Side experiment: test whether a useful, reliable, moderately complex CLI tool can be built end-to-end purely through agent conversation — no hand-written code.

---

## License

Apache License 2.0

---

## Principle

If it cannot be validated with tests — it should not exist.

archcheck

archcheck Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

archcheck

archcheck Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README