Linter de contratos y reglas de seguridad

Un linter de contratos analiza el archivo del contrato como texto estructurado: no envía una sola petición. Aplica reglas escritas por el equipo (por ejemplo «toda operación declara su seguridad» o «todo parámetro numérico tiene un máximo») y avisa de lo que no las cumple. Es barato, rápido y se corre en cada cambio.

Su límite es que solo ve el contrato. Si el servidor real hace algo distinto de lo escrito, el linter no se entera. Un resultado limpio dice «el contrato cumple las reglas»; no dice «la API cumple el contrato».

El conjunto de reglas vive en el repositorio (aquí, .spectral.yaml). Cada regla tiene una severidad: error (rompe el trabajo de CI), warn (avisa), info o off (apagada, no se evalúa). Apagar una regla es una decisión de gobierno que debe tener dueño y motivo; si nadie la recuerda, un control desaparece sin que nadie lo decida.

Abre el conjunto de reglas del repositorio y busca cuál está apagada.

Solo los resultados con severidad error rompen el trabajo; los warning se acumulan. Un equipo que no distingue unos de otros acaba ignorando ambos. Leer una salida es contar por severidad, no por volumen.

Lee la salida del linter sobre el contrato de pedidos y cuenta las líneas que son errores.

Una regla puede estar bien escrita y aun así dejar pasar lo que no debe. La regla de seguridad del equipo comprueba que cada operación tenga la clave security; no examina lo que dice. En OpenAPI, una operación con security: [] declara una lista vacía: significa «esta operación no exige ninguna credencial» y sustituye a cualquier requisito global.

Cruza el contrato con el conjunto de reglas: busca la operación que se declara sin credencial, con una descripción que sugiere datos que no deberían ser públicos, y que el linter no marca.

La regla no falla: hace exactamente lo que su descripción dice. El problema es lo que se le pidió. Mejorarla significa pedirle más: distinguir una lista vacía de una lista con credenciales y exigir que las operaciones públicas estén en una lista de excepciones con dueño.