gonzalezpazmonica/ast-quality-gate

AST Quality Gate — Verificación de Calidad Multi-Lenguaje

Sistema de quality gates para verificar código generado por IA en los 16 language packs de pm-workspace. Detecta los 5 patrones de error más comunes en código LLM-generado y 7 criterios universales adicionales.

Cuándo usar

• Post-implementación SDD: verificar código antes de PR
• Pre-commit hook: bloquear patrones críticos
• /ast-quality-gate {fichero-o-directorio} — bajo demanda
• PostToolUse hook async tras Edit|Write en SDD sessions

Arquitectura de 3 Capas

Capa 1: Herramienta nativa del lenguaje (máxima precisión)
  → eslint/ruff/golangci-lint/cargo clippy/dotnet build/phpstan/...
  → Output: JSON nativo normalizado

Capa 2: Semgrep (cobertura universal de patrones LLM)
  → rules/llm-antipatterns.yaml (8+ lenguajes simultáneos)
  → Output: semgrep JSON normalizado

Capa 3: LSP Claude Code (semántica real-time)
  → 11 lenguajes (dic 2025)
  → tipo nulo, símbolo no resuelto, import no usado

12 Quality Gates

| Gate | Patrón | Severidad | |------|--------|-----------| | QG-01 | Async/concurrencia sin manejo de errores | error | | QG-02 | N+1 queries / acceso DB en loop | error | | QG-03 | Null/nil/None dereference sin check | error | | QG-04 | Magic numbers/strings sin nombre | warning | | QG-05 | Exception handling vacío o excesivamente amplio | error | | QG-06 | Complejidad ciclomática > 15 | warning | | QG-07 | Función/método > 50 líneas | warning | | QG-08 | Duplicación de código > 15% | warning | | QG-09 | Credenciales/secrets hardcodeados | error | | QG-10 | Logging excesivo en producción | warning | | QG-11 | Código muerto / imports no usados | info | | QG-12 | Lógica nueva sin tests | error |

Pipeline de Ejecución

Paso 1: Detectar lenguaje

scripts/ast-quality-gate.sh detecta por extensión/fichero de proyecto (16 lenguajes).

Paso 2: Ejecutar herramienta nativa

Ver comandos por lenguaje en references/language-commands.md.

Paso 3: Ejecutar Semgrep (patrones LLM)

semgrep --config .claude/skills/ast-quality-gate/references/semgrep-rules.yaml \
        --json --no-git-ignore "$TARGET"

Paso 4: Normalizar a JSON unificado

Ver references/unified-schema.md para el schema completo. Output en output/quality-gates/YYYYMMDD-HHMMSS-{lenguaje}.json

Paso 5: Calcular score y veredicto

score = 100 - (errores × 10) - (warnings × 3) - (infos × 1)  [min 0]

| Score | Grade | Veredicto | |-------|-------|-----------| | 90-100 | A | PASS: listo para PR | | 75-89 | B | PASS_WITH_WARNINGS: PR con advisory | | 60-74 | C | REVIEW: requiere revisión human | | 40-59 | D | FAIL: corregir antes de PR | | 0-39 | F | BLOCK: bloquear commit |

Integración SDD

PostToolUse hook (async)

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "command": ".claude/hooks/ast-quality-gate-hook.sh",
      "async": true
    }]
  }
}

Umbral de bloqueo

Gates QG-01, QG-03, QG-05, QG-09, QG-12 son bloqueantes (exit 1). Gates QG-02, QG-04, QG-06, QG-07, QG-08, QG-10, QG-11 son advisory.

Uso manual

bash scripts/ast-quality-gate.sh src/               # completo
bash scripts/ast-quality-gate.sh src/ --semgrep-only # solo Semgrep
bash scripts/ast-quality-gate.sh src/ --native-only  # solo nativo
bash scripts/ast-quality-gate.sh src/ --advisory     # sin bloqueo

Prerequisitos

• semgrep ≥ 1.60.0 (pip install semgrep)
• Herramienta nativa del lenguaje instalada (ver references/language-commands.md)
• jq para normalización JSON

Esquemas y referencias

• references/unified-schema.md — Schema JSON unificado y jq transformations
• references/semgrep-rules.yaml — 20 reglas Semgrep por lenguaje
• references/language-commands.md — Comandos CLI por lenguaje