◆ arch_guard

CI & hooks

Run arch_guard where it stops problems early: on every pull request, and optionally before each commit. Every option below reads the same arch_guard.yaml and baseline.

Where Use Needs Dart in CI
GitHub pull requests GitHub Action: PR comment, job summary, optional Code Scanning No
GitLab merge requests GitLab CI job with report artifacts Yes
Before each commit pre-commit, lefthook or a plain git hook Yes, locally
Inside dart test expectArchitecture() Yes

On an existing codebase, start with a baseline so CI fails only on new problems. Exit codes are listed on the CLI page.

GitHub Action

# .github/workflows/architecture.yml
name: Architecture
on: [pull_request]

permissions:
  contents: read
  pull-requests: write     # PR comment
  # security-events: write # only with upload-sarif: true

jobs:
  arch_guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: creatorpiyush/arch_guard@v1.21.0
        with:
          path: .                  # project to scan
          args: --scan-dir lib     # any extra CLI flags
          # upload-sarif: true     # show results in the Security tab / PR diff

The action downloads the release binary (checksum-verified, no Dart SDK needed), writes the Markdown report to the job summary, keeps a single PR comment up to date, and fails the job when arch_guard exits non-zero. The comment has a status line, a summary table, the new problems with the rule each one breaks, and the cycle graph in a collapsible Mermaid block.

Input Default Description
path . Project folder to scan, relative to the repository root.
args   Extra CLI flags, e.g. --scan-dir lib --since origin/main.
version the action’s tag Release to run, e.g. v1.21.0. Without a version tag, the latest release. source builds from the action’s checkout and needs Dart on the runner.
comment true Post and update the PR comment. Needs pull-requests: write.
upload-sarif false Upload SARIF to GitHub Code Scanning. Needs security-events: write. Free for public repositories; private ones need GitHub Advanced Security.
output-dir arch_guard_output Report folder, relative to path.
token github.token Token for the PR comment.

Outputs: exit-code, sarif-file, markdown-file.

Prebuilt binaries cover Linux x64/arm64, macOS arm64 and Windows x64. On other runners, install Dart and set version: source.

Large repositories: only changed files

--since reports only problems that touch files changed on the branch, so a PR in a big repository isn’t blamed for old problems elsewhere. The whole project is still analysed (cycles need the full graph).

      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # --since needs the merge base
      - uses: creatorpiyush/arch_guard@v1.21.0
        with:
          args: --since origin/${{ github.base_ref }}

With --since, the PR comment also shows What this change adds: the new layer, module and workspace member dependencies, new packages per layer, and the files whose coupling grew. It is advice for the reviewer and never fails the check:

### What this change adds

_Advice only: this does not affect the result._

**New layer dependencies**

- `presentation` → `data` (2 imports)
  - `lib/ui/cart_page.dart:4` → `lib/data/cart_repo.dart`
  - `lib/ui/checkout_page.dart:7` → `lib/data/cart_repo.dart`

**New packages**

- `domain`: `http`

**Coupling growth**

- `lib/core/service_locator.dart`: fan-in 3 → 9

See What this change adds.

Run only the tests a PR can affect

arch_guard affected lists the test files that the branch’s changes can reach through imports, so a large repository can skip unrelated tests:

      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # affected needs the merge base
      - uses: dart-lang/setup-dart@v1
      - run: dart pub get
      - name: Affected tests
        run: |
          t=$(dart run arch_guard affected --since origin/${{ github.base_ref }})
          if [ -n "$t" ]; then dart test $t; else echo "No affected tests."; fi

Keep the empty check: dart test with no paths runs every test. Flutter projects use flutter test. See Tests affected by a branch.

How long a run takes

A full run, scan included, takes about 0.07 s per 1,000 files. Most of it is reading the files, which the operating system limits. The unused-file check adds about 2 ms per 1,000 files. Measured on generated projects with about 6 imports per file, using the compiled CLI (median of 7 runs):

Files Workspace members Unused-file check alone Full run, check off Full run, check on
1,000 none 1.9 ms 93 ms 93 ms
5,000 none 8.9 ms 382 ms 410 ms
5,050 50 19 ms 408 ms 417 ms
10,000 none 19 ms 709 ms 735 ms
20,000 none 42 ms 1,348 ms 1,439 ms
20,200 200 82 ms 1,502 ms 1,585 ms

Differences of a few percent between runs are noise. dart run arch_guard adds about a second of Dart startup; the GitHub Action and the standalone binaries don’t.

Architecture diagram in the README

GitHub renders Mermaid in any Markdown file. Generate the layer diagram into a file you link from the README, and fail CI when it is out of date:

      - run: |
          dart run arch_guard -f mermaid --group-by layer --no-fail-on-cycle -o build/arch
          cp build/arch/dependency_graph.mmd docs/architecture.md
          git diff --exit-code docs/architecture.md || {
            echo "::error::docs/architecture.md is out of date: run the two commands above and commit it."
            exit 1
          }

Run the same two commands locally to refresh it. Use --group-by module or --group-by package for feature folders or a workspace.

Adopting on an existing codebase (baseline)

Large projects rarely start clean. Record the problems you have today, commit the file, and from then on only new problems fail the run:

arch_guard --update-baseline        # writes arch_guard_baseline.json
git add arch_guard_baseline.json

How later runs compare against the baseline:

Use --baseline path/to/file.json to keep the file somewhere else (paths are relative to the scanned project).

GitLab CI

arch_guard:
  image: dart:stable
  script:
    - dart pub global activate arch_guard
    - dart pub global run arch_guard . -f sarif -f markdown -o reports
  artifacts:
    when: always
    paths: [reports/]

GitLab does not read SARIF natively, so keep the reports as artifacts; reports/arch_guard_report.md can be posted to the merge request from a script.

pre-commit

With pre-commit 2.15 or later:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/creatorpiyush/arch_guard
    rev: v1.21.0
    hooks:
      - id: arch_guard
        # args: [--no-fail-on-cycle]

The arch_guard hook compiles arch_guard from source, so it needs the Dart SDK. Without Dart, install the standalone binary and use id: arch_guard-system instead. It runs the arch_guard on your PATH, so every developer needs it installed.

lefthook

# lefthook.yml
pre-commit:
  commands:
    arch_guard:
      glob: "*.dart"
      run: dart run arch_guard --no-color

(Requires arch_guard as a dev dependency.)

Plain git hook

Save as .git/hooks/pre-commit and make it executable (chmod +x .git/hooks/pre-commit):

#!/bin/sh
dart run arch_guard --no-color || {
  echo "arch_guard found new architecture problems; commit aborted."
  exit 1
}

With a committed baseline, hooks only block commits that introduce new problems.