Cómo dominar nuestro CI Pipeline

Seguro que te ha pasado: envías un pull request y esperas una eternidad para que el CI termine, solo para descubrir que falló por un error de formato básico. Es frustrante perder tiempo en esperas innecesarias cuando podrías estar programando.

Para evitar esto, nuestro CI Pipeline utiliza un sistema de scoping inteligente. Si solo cambias la documentación o el código nativo, el sistema omite las tareas pesadas para que recibas feedback rápido en tus cambios.

Requisitos previos

• Tener instalado pnpm.
• Acceso al repositorio para ejecutar los comandos locales.

Inicio rápido

Para validar tus cambios antes de subirlos y ahorrar tiempo en el CI, sigue estos pasos:

1. Ejecuta pnpm check para validar tipos de TypeScript, lint y formato.
2. Corre pnpm test para asegurar que los tests de Vitest pasen correctamente.
3. Si estás trabajando en la documentación, usa pnpm check:docs.
4. Verifica el contenido del paquete final con pnpm release:check.

Job Overview

El pipeline se ejecuta en cada push a main y en cada pull request. Aquí tienes lo que hace cada job:

Job	Purpose	When it runs
docs-scope	Detect docs-only changes	Always
changed-scope	Detect which areas changed (node/macos/android)	Non-docs PRs
check	TypeScript types, lint, format	Non-docs changes
check-docs	Markdown lint + broken link check	Docs changed
code-analysis	LOC threshold check (1000 lines)	PRs only
secrets	Detect leaked secrets	Always
build-artifacts	Build dist once, share with other jobs	Non-docs, node changes
release-check	Validate npm pack contents	After build
checks	Node/Bun tests + protocol check	Non-docs, node changes
checks-windows	Windows-specific tests	Non-docs, node changes
macos	Swift lint/build/test + TS tests	PRs with macos changes
android	Gradle build + tests	Non-docs, android changes

Fail-Fast Order

Los jobs están ordenados para que las verificaciones baratas fallen antes de que se ejecuten las costosas:

1. Validaciones iniciales: docs-scope, code-analysis y check corren en paralelo (~1-2 min).
2. Construcción: build-artifacts se ejecuta solo si los anteriores pasan.
3. Tests de plataforma: Se lanzan checks y checks-windows.
4. Tests nativos: Se ejecutan macos y android (bloqueados por el build).

Code Analysis

El job code-analysis ejecuta el script scripts/analyze_code_files.py en los PRs para mantener la calidad del código bajo estas reglas:

• Límite de líneas (LOC): Los archivos que superen las 1000 líneas harán que el build falle.
• Solo cambios (Delta): El sistema solo revisa los archivos que modificaste en tu PR, no todo el proyecto.

Cuando activas el flag --strict, cualquier violación bloquea todos los jobs siguientes. Esto permite detectar archivos demasiado grandes antes de gastar recursos en tests pesados. El sistema ignora directorios como node_modules, dist, vendor, .git, coverage, Swabble, skills y .pi.

Solución de problemas

• Fallo por límite de líneas: Si el job code-analysis falla, revisa si tu archivo superó las 1000 líneas. Te recomiendo dividir el código en módulos más pequeños.
• Jobs bloqueados: Si usas el flag --strict y hay una violación de calidad, los jobs posteriores no se ejecutarán hasta que lo soluciones.

Si necesitas ayuda con un error específico, consulta al AI Setup Assistant.

Próximos pasos

• Guía de tests locales.
• Estándares de código nativo.