Интеграция с CI

CLI спроектирован под CI: всё проходит через analyze → report → check, все три неинтерактивны, чисто завершаются и стримят JSON / Markdown / JUnit в stdout.

Рецепты ниже предполагают, что @archora/cli ставится из npm. Пока это в работе, подменяйте npx @archora/cli на npm run cli -- из чекаута.

GitHub Actions

1. Блокировать PR-ы, добавляющие циклы или 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. Комментировать Markdown-отчёт в каждый 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. Дифф против 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-вкладка «Tests» подхватит JUnit автоматически и покажет каждый цикл / нарушение как failed test case.

Локальный npm скрипт

Для повседневной работы без CI вынесите те же проверки в package.json, чтобы контрибьюторы могли запустить их перед push'ем:

{
  "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"
  }
}

npm run scope — гейт, npm run scope:report — человеко-читаемый HTML-бриф, npm run scope:fix-plan — JSON-конверт для автоматизации. Пока @archora/cli не опубликован, замените archora на npm run cli -- из чекаута.

Pre-commit (Husky)

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

Тут специально только одно правило — «никаких новых циклов». Тяжёлым правилам место в CI.

Советы

• Кэшируйте node_modules между ранами как для любого Node CLI; у самого анализатора нет cache-директории.
• --quiet рекомендуется в CI, чтобы не засорять логи. Ошибки и сработавшие правила всё равно идут в stderr.
• Длинные сканы (≥ 5000 модулей) укладываются заметно быстрее минуты на 4-ядерном раннере. Если job таймаутит — дело почти всегда в шаге установки, не в скане.