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 モードで型の規律を強制します。frontmatter バリデーターは、ルール、スキル、委任されたワーカー、コマンドのアーティファクトスキーマへの準拠を門にかけます。markdownlint はこのレーンには含まれません。Markdown ファイルが変更されたときに、Markdown Lint ワークフローが CI でその pre-commit フックを実行します（Markdown 規約を参照してください）。
• テストレーン —— pytest tests/hooks は、フックランタイムを完全なイベントマトリクスに対して実行します。validate_ecosystem.py は、アーティファクト横断の整合性に対する主要な構造ゲートです。chaos_pass.py は、main へのプッシュおよびプルリクエストに対して、CI の品質ジョブ内で（パスフィルター付きで）実行され、劣化した入力のもとでの品質低下を捕捉します。src/apothem/benchmarks/ 配下のクラス別ベンチマークドライバーは、pytest スイートと metrics ジョブを通じて CI で実行されます。CI での pytest の各フル実行は、bench_install.py を除くすべてのドライバーを呼び出す tests/unit/test_benchmarks.py を収集します。metrics ジョブは scripts/dev/collect_metrics.py を実行します。このスクリプトは bench_hooks.py --json を実行し、結果を hook_e2e_ms として記録します。bench_tests.py と bench_install.py が実際の実行を計測するのは、make benchmarks の下だけです。make benchmarks を実行するワークフローはありません。
• セキュリティレーン —— ci.yml 内の gitleaks が、誤ってコミットされた認証情報を捕捉します。ライセンス監査（license-audit.yml）は、許可リストにない依存関係のライセンスを検出すると失敗します。毎週、および依存関係またはライセンスファイルが変更されたときに実行されます。REUSE ゲート（reuse.yml）はすべての変更で実行され、ファイルにライセンス行がない場合や SPDX 式を解析できない場合に失敗します。release.yml は、タグ付けされたリリースごとに SBOM を生成します。
• 公開レーン —— リリースワークフローはタグのプッシュによって起動されます。npm と VS Code の公開処理は、既存のタグに対して手動ディスパッチで再実行することもできます。署名済みタグの検証は、リリースブランチの来歴を確認します。リリースノートは CHANGELOG.md の Keep-A-Changelog 形式から派生します。プロジェクトのウェブサイトは、そのビルド入力に変更を加えた main へのプッシュ時、または手動ディスパッチ時に、site/dist/ から GitHub Pages のターゲットへ公開されます。

具体的な構成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 —— リリースノートの源。