QA Workflow

QA Workflow — Análisis y corrección antes de commit

Cómo ejecutar las herramientas

Las herramientas QA se ejecutan a través de GitHooks usando la configuración de qa/githooks.php. Siempre con --format=json 2>/dev/null para poder parsear la respuesta y extraer los jobs fallidos sin leer bloques ANSI:

# Flow completo (todas las herramientas)
php7.4 githooks flow qa --format=json

# Job individual
php7.4 githooks job phpstan-src --format=json
php7.4 githooks job phpmd-src --format=json
php7.4 githooks job phpcs --format=json
php7.4 githooks job phpcbf --format=json
php7.4 githooks job phpcpd --format=json
php7.4 githooks job parallel-lint --format=json
php7.4 githooks job phpunit --format=json
php7.4 githooks job composer-audit --format=json

# Tests
php7.4 vendor/bin/phpunit --order-by random

NUNCA ejecutar las herramientas directamente (ej: vendor/bin/phpstan). Siempre usar githooks flow o githooks job para que se aplique la configuración del proyecto.

Parsear la respuesta JSON

Para extraer solo los jobs que han fallado y su causa:

php7.4 githooks flow qa --format=json | python3 -c "
import json, sys
d = json.load(sys.stdin)
print(f'{d[\"passed\"]}/{d[\"passed\"]+d[\"failed\"]} passed, {d[\"skipped\"]} skipped')
for j in d['jobs']:
    if not j['success'] and not j.get('skipped'):
        print(f'KO {j[\"name\"]} ({j[\"type\"]}): exitCode={j[\"exitCode\"]}')
        print(j['output'][:400])"

El campo output contiene el stdout del tool (sin ANSI) — suficiente para localizar la violación sin necesidad de re-ejecutar en modo texto.

Pasar argumentos al tool (ej. --filter en phpunit)

githooks job acepta args extra tras el separador POSIX --. No lanzar vendor/bin/phpunit directamente; usar el job con -- para preservar la config del proyecto (--log-junit, --colors, etc.):

# Filtrar un test concreto
php7.4 githooks job "Phpunit" --format=json -- --filter=FooTest

# Por grupo
php7.4 githooks job "Phpunit" --format=json -- --group=slow

# Combinado
php7.4 githooks job "Phpunit" --format=json -- --filter=Bar --stop-on-failure

Todo lo que va después de -- se concatena al comando generado. Vale también para --group, --exclude-group, --stop-on-failure, --testdox, etc. No existe en githooks flow (cada tool del flow tiene flags distintos).

Los nombres de los jobs son los definidos en qa/githooks.php. Son case-sensitive y pueden tener espacios.

Cuándo ejecutar QA

1. Antes de commitear — ejecutar php7.4 githooks flow qa y corregir todo
2. Si un commit falla por un hook pre-commit — corregir y reintentar
3. Después de cada fase de una tarea grande — no acumular deuda

Cómo gestionar las violaciones

Criterio 1: Fácil de corregir → corregir inmediatamente

Si la violación es sensata y se arregla en 1-5 líneas, corregirla en el acto.

Ejemplos:

• Variable con nombre corto ($v → $value)
• Import faltante (Missing class import via use statement)
• Variable no usada (Avoid unused local variables)
• Variable no definida (Avoid using undefined variables)

Criterio 2: Sensata pero requiere refactor → suprimir + documentar

Si la violación es correcta pero corregirla requiere un cambio no trivial (ej: reducir CC de un método, romper acoplamiento de una clase), NO refactorizar en el momento. En su lugar:

1. Añadir @SuppressWarnings en el código:

/**
 * @SuppressWarnings(PHPMD.CyclomaticComplexity)
 */
private function myMethod(): void { ... }

/**
 * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
 */
class MyClass { ... }

/**
 * @SuppressWarnings(PHPMD.BooleanArgumentFlag)
 */
public function __construct(bool $flag) { ... }

2. Documentar en Bugs3.0.0.md o en un apartado de deuda técnica por qué se suprime y qué refactor sería necesario.
3. Informar al usuario.

Criterio 3: Asumible (falso positivo o trade-off aceptado) → suprimir

Si la violación no es un problema real (ej: boolean flag en un value object, acoplamiento en un DI container), suprimirla con @SuppressWarnings e informar al usuario.

Criterio 4: Test que falla → corregir

• Si falla por falta de mantenimiento del test (cambió una signature, un mensaje) → actualizar el test.
• Si falla por un bug en el SUT → corregir el SUT, no el test.
• Nunca marcar un test como @incomplete o @skip. Si crees que ya no aporta valor, preguntar al usuario.

Anotaciones de supresión por herramienta

PHPMD (@SuppressWarnings)

/** @SuppressWarnings(PHPMD.CyclomaticComplexity) */
/** @SuppressWarnings(PHPMD.CouplingBetweenObjects) */
/** @SuppressWarnings(PHPMD.BooleanArgumentFlag) */
/** @SuppressWarnings(PHPMD.ShortVariable) */
/** @SuppressWarnings(PHPMD.UnusedFormalParameter) */
/** @SuppressWarnings(PHPMD.UndefinedVariable) */  // Para falsos positivos de preg_match

Se ponen en el docblock del método o clase afectado.

PHPStan (phpstan-ignore)

/** @phpstan-ignore-next-line */
$result = $something; // PHPStan no puede inferir el tipo aquí

O en qa/phpstan.neon:

parameters:
    ignoreErrors:
        - '#Pattern description#'

PHPCS (phpcs:ignore)

// phpcs:ignore PSR12.Rule.Name -- razón
$code = something_non_psr12();

Checklist pre-commit

• php7.4 githooks flow qa — 8/8 passed
• php7.4 vendor/bin/phpunit --order-by random — 0 fallos
• Si hay violaciones nuevas: corregidas o suprimidas con justificación
• Si se suprimió algo: documentado y usuario informado