Diagramme du pipeline CI/CD

La carte structurelle du flux de travail de build · validation · publication qui contrôle chaque changement de l'écosystème d'Apothem. Ce document installe la surface de visualisation. Les fichiers de flux de travail GitHub Actions qu'il décrit se trouvent dans .github/workflows/ (par exemple ci.yml et release.yml), et l'outillage de publication se trouve dans scripts/release/.

Forme du pipelineCopy 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

Rôles des couloirsCopy Anchor Link

• Couloir d'analyse statique — retour rapide. Ruff couvre le style Python et un ensemble de règles sélectionnées ; mypy impose la discipline de typage en mode strict ; le validateur de frontmatter contrôle la conformité des artefacts au schéma pour les règles, les skills, les travailleurs délégués et les commandes. markdownlint ne fait pas partie de ce couloir : son hook de pre-commit s'exécute dans la CI, via le flux de travail Markdown Lint, lorsque des fichiers Markdown changent (voir Conventions Markdown).
• Couloir de tests — pytest tests/hooks exerce le runtime des hooks contre la matrice complète des événements ; validate_ecosystem.py est le principal portail structurel de la cohérence inter-artefacts ; chaos_pass.py s'exécute dans le job qualité de la CI, sur les push et pull requests vers main (filtrés par chemin), pour détecter la dégradation sous des entrées dégradées. Les pilotes de benchmark par classe sous src/apothem/benchmarks/ s'exécutent en CI via la suite pytest et via le job metrics. Chaque exécution complète de pytest en CI collecte tests/unit/test_benchmarks.py, qui appelle chaque pilote sauf bench_install.py. Le job metrics exécute scripts/dev/collect_metrics.py, qui lance bench_hooks.py --json et consigne le résultat sous le nom hook_e2e_ms. bench_tests.py et bench_install.py ne chronométrent de véritables exécutions que sous make benchmarks. Aucun flux de travail n'exécute make benchmarks.
• Couloir de sécurité — gitleaks dans ci.yml repère les identifiants commités par accident. L'audit de licences (license-audit.yml) échoue lorsqu'une licence de dépendance ne figure pas dans sa liste d'autorisation. Il s'exécute chaque semaine et lorsque les fichiers de dépendances ou de licences changent. La porte REUSE (reuse.yml) s'exécute à chaque modification et échoue lorsqu'un fichier n'a pas de ligne de licence ou qu'une expression SPDX ne s'analyse pas. release.yml génère le SBOM de chaque version étiquetée.
• Couloir de publication — les flux de travail de publication sont déclenchés par les push de tags ; les publieurs npm et VS Code peuvent aussi être relancés manuellement pour une étiquette existante. La vérification de l'étiquette signée confirme la provenance de la branche de publication ; les notes de publication dérivent du format Keep-A-Changelog de CHANGELOG.md. Le site web du projet se publie depuis site/dist/ vers la cible GitHub Pages lors des push sur main qui touchent à ses entrées de compilation, ou sur déclenchement manuel.

Configuration concrèteCopy Anchor Link

Les fichiers de flux de travail réels (.github/workflows/ci.yml, .github/workflows/release.yml, etc.) se trouvent dans le dépôt. Ce diagramme définit la forme canonique que toute configuration future reflète.

Références croisées faisant autoritéCopy Anchor Link

• pyproject.toml — source de vérité de la configuration Ruff / mypy / pytest.
• scripts/dev/validate_ecosystem.py — le principal portail inter-artefacts.
• scripts/dev/validate_hooks.py — validation structurelle spécifique aux hooks.
• scripts/dev/chaos_pass.py — balayage adversarial de chaque hook configuré.
• src/apothem/benchmarks/ — vérificateurs du budget d'exécution par classe.
• site/content/docs/developer-guide.mdx — le flux de travail du contributeur, destiné à l'opérateur.
• CHANGELOG.md — source des notes de publication.