Диаграмма конвейера CI/CD

Структурная карта рабочего процесса сборки · валидации · публикации, который контролирует каждое изменение в экосистеме Apothem. Этот документ устанавливает поверхность визуализации. Рабочие процессы GitHub Actions, которые он описывает, находятся в .github/workflows/ (например, ci.yml и release.yml), а инструментарий релизов — в scripts/release/.

Форма конвейераCopy Anchor Link

%%{ init: { "theme": "neutral" } }%%
%% verified: 2026-04-27 %%
%% provenance: pyproject.toml + scripts/dev/validate_ecosystem.py + scripts/dev/validate_hooks.py %%
%% cross-reference: site/content/docs/developer-guide.mdx (contributor workflow) %%
flowchart LR
    accTitle: CI/CD pipeline shape
    accDescr: Left-to-right flowchart of the apothem CI CD pipeline showing build, test, lint, type-check, security scan, docs build, package, sign, and publish stages with branch protection gates between them.
    subgraph Trigger["Trigger surface"]
        PR["Pull request opened or updated"]
        PUSH["Push to main"]
        TAG["Tag release vX.Y.Z"]
    end
    subgraph Static["Static analysis lane"]
        LINT["Ruff lint + format check"]
        TYPE["Mypy strict"]
        FRONT["Frontmatter validator"]
    end
    subgraph Test["Test lane"]
        PYTEST["pytest tests/hooks"]
        ECO["validate_ecosystem.py"]
        CHAOS["chaos_pass.py (CI quality job)"]
        BENCH["src/apothem/benchmarks/ (unit tests in CI, bench_hooks in metrics job)"]
    end
    subgraph Security["Security lane"]
        SECRETS["Secret scan"]
        SBOM["SBOM generation (tags only)"]
        LICENSE["License audit"]
    end
    subgraph Publish["Publish lane (tags only)"]
        SIGN["Signed-tag verification"]
        ATTEST["Provenance attestation"]
        RELEASE["Release notes from CHANGELOG.md"]
    end
    DOCS["Project website publish"]
    PR --> Static
    PR --> Test
    PR --> Security
    PUSH --> Static
    PUSH --> Test
    PUSH --> Security
    PUSH --> DOCS
    TAG --> Static
    TAG --> Test
    TAG --> Security
    TAG --> Publish
    Static --> GATE{All lanes green?}
    Test --> GATE
    Security --> GATE
    GATE -->|yes| MERGE[Merge / publish]
    GATE -->|no| BLOCK[Block · surface failures · request fix]
    Publish --> MERGE

Роли дорожекCopy Anchor Link

• Дорожка статического анализа — быстрая обратная связь. Ruff покрывает стиль Python и тщательно подобранный набор правил; mypy навязывает дисциплину типов в режиме strict; валидатор фронтматтера контролирует соответствие схеме артефактов для правил, навыков, делегированных исполнителей и команд. markdownlint в эту дорожку не входит: рабочий процесс Markdown Lint запускает его хук pre-commit в CI при изменении файлов Markdown (см. Соглашения по Markdown).
• Дорожка тестов — pytest tests/hooks прогоняет среду выполнения хуков по полной матрице событий; validate_ecosystem.py — основной структурный шлюз для проверки согласованности между артефактами; chaos_pass.py запускается в задании контроля качества CI при push и pull request в main (с фильтром по путям), чтобы выявлять деградацию при ухудшенных входных данных. Драйверы бенчмарков по классам в src/apothem/benchmarks/ выполняются в CI через набор pytest и через задание metrics. Каждый полный запуск pytest в CI собирает tests/unit/test_benchmarks.py, который вызывает все драйверы, кроме bench_install.py. Задание metrics запускает scripts/dev/collect_metrics.py, который выполняет bench_hooks.py --json и записывает результат как hook_e2e_ms. bench_tests.py и bench_install.py замеряют реальные запуски только в рамках make benchmarks. Ни один рабочий процесс не запускает make benchmarks.
• Дорожка безопасности — gitleaks в ci.yml выявляет случайно закоммиченные учётные данные. Аудит лицензий (license-audit.yml) завершается ошибкой, если лицензия зависимости не входит в список разрешённых. Он запускается еженедельно и при изменении файлов зависимостей или лицензий. Шлюз REUSE (reuse.yml) запускается при каждом изменении и завершается ошибкой, если у файла нет строки лицензии или выражение SPDX не разбирается. release.yml генерирует SBOM для каждого релиза с тегом.
• Дорожка публикации — рабочие процессы релиза запускаются push-ами тегов; публикаторов npm и VS Code также можно перезапустить вручную для существующего тега. Проверка подписанного тега подтверждает происхождение релизной ветки; заметки о релизе формируются из CHANGELOG.md в формате Keep-A-Changelog. Сайт проекта публикуется из site/dist/ в цель GitHub Pages при push в main, которые затрагивают его входные данные сборки, либо по ручному запуску.

Конкретная конфигурацияCopy Anchor Link

Фактические файлы рабочего процесса (.github/workflows/ci.yml, .github/workflows/release.yml и т. д.) находятся в репозитории. Эта диаграмма задаёт каноническую форму, которой будет следовать каждая будущая конфигурация.

Авторитетные перекрёстные ссылкиCopy Anchor Link

• pyproject.toml — источник истины для конфигурации Ruff / mypy / pytest.
• scripts/dev/validate_ecosystem.py — основной межартефактный шлюз.
• scripts/dev/validate_hooks.py — структурная валидация, специфичная для хуков.
• scripts/dev/chaos_pass.py — состязательный проход по каждому настроенному хуку.
• src/apothem/benchmarks/ — верификаторы бюджета времени выполнения по классам.
• site/content/docs/developer-guide.mdx — рабочий процесс контрибьютора, ориентированный на оператора.
• CHANGELOG.md — источник заметок о релизе.