Diagrama de la canalización de CI/CD

El mapa estructural del flujo de trabajo de compilación · validación · publicación que controla cada cambio en el ecosistema de Apothem. Este documento instala la superficie de visualización. Los archivos del flujo de trabajo de GitHub Actions que describe están en .github/workflows/ (por ejemplo, ci.yml y release.yml), y el utillaje de lanzamiento está en scripts/release/.

Forma de la canalizaciónCopy 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

Roles de los carrilesCopy Anchor Link

• Carril de análisis estático — retroalimentación rápida. Ruff cubre el estilo de Python y un conjunto de reglas curado; mypy aplica disciplina de tipos en modo strict; el validador de frontmatter controla el cumplimiento del esquema de artefactos para reglas, skills, trabajadores delegados y comandos. markdownlint no forma parte de este carril: su hook de pre-commit se ejecuta en CI a través del flujo de trabajo Markdown Lint cuando cambian archivos Markdown (consulta Convenciones de Markdown).
• Carril de pruebas — pytest tests/hooks ejercita el tiempo de ejecución de hooks con la matriz completa de eventos; validate_ecosystem.py es la puerta estructural principal para la coherencia entre artefactos; chaos_pass.py se ejecuta en el trabajo de calidad de CI en los push y las pull requests a main (filtrado por ruta) para detectar la degradación ante entradas degradadas. Los drivers de benchmark por clase bajo src/apothem/benchmarks/ se ejecutan en CI a través de la suite de pytest y del trabajo metrics. Cada ejecución completa de pytest en CI recoge tests/unit/test_benchmarks.py, que llama a todos los drivers salvo bench_install.py. El trabajo metrics ejecuta scripts/dev/collect_metrics.py, que ejecuta bench_hooks.py --json y registra el resultado como hook_e2e_ms. bench_tests.py y bench_install.py solo miden ejecuciones reales con make benchmarks. Ningún flujo de trabajo ejecuta make benchmarks.
• Carril de seguridad — gitleaks en ci.yml detecta credenciales confirmadas por accidente. La auditoría de licencias (license-audit.yml) falla si la licencia de una dependencia no está en su lista permitida. Se ejecuta semanalmente y cuando cambian los archivos de dependencias o de licencias. La puerta REUSE (reuse.yml) se ejecuta en cada cambio y falla cuando un archivo no tiene línea de licencia o una expresión SPDX no se puede analizar. release.yml genera el SBOM de cada versión etiquetada.
• Carril de publicación — los flujos de trabajo de lanzamiento se activan con los push de etiquetas; los publicadores de npm y de VS Code también pueden volver a ejecutarse mediante despacho manual para una etiqueta existente. La verificación de etiquetas firmadas confirma la procedencia de la rama de lanzamiento; las notas de lanzamiento derivan del formato Keep-A-Changelog de CHANGELOG.md. El sitio web del proyecto se publica desde site/dist/ en el destino de GitHub Pages en los push a main que modifiquen sus entradas de compilación, o mediante despacho manual.

Configuración concretaCopy Anchor Link

Los archivos de flujo de trabajo reales (.github/workflows/ci.yml, .github/workflows/release.yml, etc.) están en el repositorio. Este diagrama define la forma canónica que reflejará toda configuración futura.

Referencias cruzadas autoritativasCopy Anchor Link

• pyproject.toml — fuente de verdad de la configuración de Ruff / mypy / pytest.
• scripts/dev/validate_ecosystem.py — la principal puerta entre artefactos.
• scripts/dev/validate_hooks.py — validación estructural específica de hooks.
• scripts/dev/chaos_pass.py — barrido adversarial de cada hook configurado.
• src/apothem/benchmarks/ — verificadores del presupuesto de runtime por clase.
• site/content/docs/developer-guide.mdx — el flujo de trabajo del contribuyente orientado al operador.
• CHANGELOG.md — fuente de las notas de lanzamiento.