CI integration

The CLI is designed for CI: everything goes through analyze → report → check, all of which are non-interactive, exit cleanly, and stream JSON / Markdown / JUnit on stdout.

The recipes below assume @archora/cli is installable from npm. While that's pending, substitute npx @archora/cli with npm run cli -- from a checkout.

GitHub Actions

1. Block PRs that introduce cycles or D-grade

# .github/workflows/archora.yml
name: Architecture
on:
  pull_request:
  push:
    branches: [main]

jobs:
  scope:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - name: Run Archora check
        run: npx @archora/cli check . --fail-on grade:D --fail-on cycles:0

2. Comment a Markdown report on every PR

- name: Generate report
  run: npx @archora/cli report . --format md -o archora.md --quiet
- name: Comment on PR
  uses: marocchino/sticky-pull-request-comment@v2
  with:
    path: archora.md

3. Diff against main

- name: Fetch main
  run: git fetch origin main:main
- name: Baseline scan from main
  run: |
    git worktree add /tmp/main main
    npx @archora/cli analyze /tmp/main --quiet -o baseline.json
- name: Block new cycles
  run: |
    npx @archora/cli check . \
      --fail-on new-cycles:0 \
      --base baseline.json

GitLab CI

archora:
  image: node:20
  script:
    - npm ci
    - npx @archora/cli check . --fail-on grade:D --fail-on cycles:0
    - npx @archora/cli report . --format junit -o archora-junit.xml --quiet
  artifacts:
    when: always
    reports:
      junit: archora-junit.xml

GitLab's "Tests" tab will pick up the JUnit file automatically and surface every cycle / violation as a failed test case.

Local npm script

For day-to-day work without CI, expose the same checks through package.json so contributors can run them before pushing:

{
  "scripts": {
    "scope": "archora check . --fail-on grade:D --fail-on cycles:0",
    "scope:report": "archora report . --format html -o archora-report.html",
    "scope:fix-plan": "archora report . --format fix-plan -o archora-fix-plan.json"
  }
}

Run npm run scope for the gate, npm run scope:report for the human-readable HTML brief, npm run scope:fix-plan for the JSON envelope your tooling can consume. While @archora/cli is pending publish, replace archora with npm run cli -- from a checkout.

Pre-commit (Husky)

# .husky/pre-commit
npx @archora/cli check . --fail-on cycles:0 --quiet

This is intentionally light — only the "no new cycles" rule. Heavier rules belong in CI.

Tips

• Cache node_modules between runs as you would for any Node CLI; the analyzer itself has no cache directory.
• --quiet is recommended in CI to keep logs clean. Errors and rule failures still surface on stderr.
• Long scans (≥ 5000 modules) finish in well under a minute on a 4-core runner. If your job times out, suspect the install step, not the scan.