type-guardian: una CLI para auditar tipos inseguros en pull requests
Una herramienta open source que combina la Compiler API de TypeScript y la salida estructurada de OpenAI para detectar patrones de tipos inseguros en diffs de Git.
Gate of AI ha publicado el código de type-guardian, una herramienta de línea de comandos diseñada para revisar pull requests en repositorios TypeScript. El objetivo es detectar patrones que debilitan los contratos de tipos sin provocar necesariamente un error de compilación inmediato, como el uso excesivo de any, aserciones peligrosas a través de unknown o supresiones de diagnósticos con @ts-ignore.
La arquitectura de la herramienta sigue un enfoque en capas para mantener la separación entre lo determinista y lo contextual. Primero, extrae el alcance del cambio mediante la comparación del diff de Git contra el merge-base. A continuación, ejecuta reglas locales basadas en el AST (Abstract Syntax Tree) para identificar patrones de política concretos y recopila los diagnósticos previos a la emisión desde el tsconfig.json usando la TypeScript Compiler API. Solo en una tercera fase, si está habilitada, se envía un subconjunto del código a OpenAI para obtener hallazgos contextuales en JSON validado.
Este diseño busca que el compilador siga siendo la autoridad final para los errores de sintaxis y semántica, mientras que las reglas locales cubren las políticas de estilo y seguridad que el compilador ignora. El modelo de IA solo actúa como consultor para explicar límites potencialmente peligrosos, sin modificar el código ni sustituir al compilador como puerta de entrada al merge. Para los equipos que operan bajo requisitos de gobernanza estrictos, el tutorial destaca la importancia de configurar límites, como el número máximo de caracteres o archivos enviados a la API externa, evitando que credenciales o datos sensibles salgan del entorno de desarrollo.
La implementación depende de la API de respuestas de OpenAI y de Zod para la validación. El autor recomienda configurar strict, noUncheckedIndexedAccess y exactOptionalPropertyTypes en el tsconfig.json para que la propia herramienta cumpla con los estándares que exige. El proyecto incluye scripts para ejecutar la revisión localmente o integrarla en pipelines de CI/CD, inyectando las claves API a través de los mecanismos de secretos de la plataforma continua.
Para los equipos que gestionan infraestructura de software con TypeScript, esta herramienta ofrece una capa de auditoría automática que reduce la carga cognitiva en los code reviews. No sustituye a un revisor humano, pero ayuda a estandarizar la detección de malas prácticas tipográficas antes de que lleguen al código base.
