Lab 05 — Reports & Exit Codes

Aprende a generar reportes estructurados de cada ejecución de Architect y a usar exit codes para integrar con pipelines de CI/CD de forma programática.

Setup

Nivel: Básico

Duración estimada: 15 minutos. Features: reports, exit-code-on-partial.

mkdir -p ~/architect-labs/lab-05 && cd ~/architect-labs/lab-05
git init && mkdir -p src tests reports

src/math_ops.py

def factorial(n):
    if n < 0:
        raise ValueError("Negative numbers not allowed")
    if n == 0:
        return 1
    return n * factorial(n - 1)

tests/test_math.py

from src.math_ops import factorial

def test_factorial_zero():
    assert factorial(0) == 1

def test_factorial_positive():
    assert factorial(5) == 120

.architect.yaml

llm:
  model: openai/gpt-4.1
  api_base: http://localhost:4000/v1
  api_key_env: LITELLM_API_KEY

git add -A && git commit -m "initial"

Ejercicio 1: Generar reporte JSON

architect run "Añade funciones fibonacci(n) y is_prime(n) en src/math_ops.py \
  con tests completos en tests/test_math.py." \
  --config .architect.yaml \
  --confirm-mode yolo \
  --report-file reports/run-001.json

Examina el reporte:

cat reports/run-001.json | python -m json.tool

El reporte contiene:

task — la tarea ejecutada
status — success, partial o failed
duration_seconds — tiempo total
steps — número de pasos del agente
total_cost — coste en USD
files_modified — lista de archivos tocados con diff stats
quality_gates — resultado de verificaciones
errors — errores encontrados

Consejo

El reporte JSON es ideal para integraciones programáticas. Puedes parsearlo con jq, Python, o cualquier herramienta que procese JSON.

Ejercicio 2: Reporte Markdown

architect run "Añade una función gcd(a, b) que calcule el máximo \
  común divisor usando el algoritmo de Euclides." \
  --config .architect.yaml \
  --confirm-mode yolo \
  --report-file reports/run-002.md \
  --report-format markdown

cat reports/run-002.md

El formato Markdown es ideal para:

Pull request descriptions
Release notes automáticas
Documentación de cambios
Revisiones de código

Ejercicio 3: Exit codes para CI/CD

Los exit codes permiten integrar Architect directamente en pipelines:

# Tarea exitosa -> exit code 0
architect run "Añade docstrings a todas las funciones en src/math_ops.py" \
  --config .architect.yaml --confirm-mode yolo
echo "Exit code: $?"
# -> 0

# Tarea con exit-code-on-partial
architect run "Corrige todos los errores de TypeScript en src/" \
  --config .architect.yaml --confirm-mode yolo \
  --exit-code-on-partial 1
echo "Exit code: $?"
# -> 1 si hubo corrección parcial, 0 si fue completa

Importante

El flag --exit-code-on-partial es clave para CI/CD: te permite diferenciar entre éxito completo (exit 0) y corrección parcial (exit 1) para decidir si el pipeline continúa o se detiene.

Ejercicio 4: Usar reportes en un script

Ejemplo de integración de reportes en un script de CI:

#!/bin/bash
# ci-check.sh — Ejemplo de uso de reportes en CI

architect run "Revisa src/math_ops.py y corrige cualquier bug" \
  --config .architect.yaml \
  --confirm-mode yolo \
  --report-file reports/ci-run.json

# Parsear el reporte
STATUS=$(python -c "import json; print(json.load(open('reports/ci-run.json'))['status'])")
FILES=$(python -c "import json; print(len(json.load(open('reports/ci-run.json'))['files_modified']))")

echo "Status: $STATUS"
echo "Files modified: $FILES"

if [ "$STATUS" = "success" ]; then
    echo "All good"
    exit 0
else
    echo "Partial or failed"
    exit 1
fi

Consejo

Combina reportes JSON con herramientas como jq para extraer datos específicos en pipelines más complejos: jq '.files_modified[] | .path' reports/ci-run.json

Resumen

Flag	Descripción
`--report-file PATH`	Genera reporte en la ruta indicada
`--report-format json/markdown`	Formato del reporte
`--exit-code-on-partial N`	Exit code cuando el resultado es parcial
Exit code 0	Éxito completo
Exit code 1	Fallo o parcial (según config)

Siguiente lab

Lab 06: Dry Run & Preview — Previsualiza lo que Architect haría sin ejecutar nada.