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 demandaPostToolUsehook async trasEdit|Writeen 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 .opencode/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": ".opencode/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) jqpara normalización JSON
Esquemas y referencias
references/unified-schema.md— Schema JSON unificado y jq transformationsreferences/semgrep-rules.yaml— 20 reglas Semgrep por lenguajereferences/language-commands.md— Comandos CLI por lenguaje