Avouch es una herramienta de línea de comandos, ligera y de código abierto, que realiza análisis estático sobre código Python limitado a los archivos modificados respecto al último commit de Git. Su objetivo es revisar únicamente el código que el desarrollador está a punto de enviar, evitando arrastrar problemas heredados de archivos no tocados en la changeset. Para ello consulta a Git qué archivos cambiará el próximo commit —ya sea vía git diff HEAD --name-only o git ls-files --others --exclude-standard para los no rastreados— y los analiza con el módulo estándar ast, sin recurrir a expresiones regulares ni a dependencias externas de red.
La herramienta funciona como un binario efímero: tres llamadas a Git como subprocesos más ast y tomllib, ambos de la biblioteca estándar. Necesita Python 3.10 o superior (las reglas usan ast.Match y la configuración, tomllib) y el ejecutable git en el PATH. No requiere demonio en segundo plano, listas de rutas mantenidas a mano ni configuración por invocación. La instalación se realiza con pip install avouch, tras lo cual basta con ejecutar avouch desde la raíz del repositorio para obtener un informe en terminal.
El informe agrupa los hallazgos por archivo y por regla con códigos del tipo SCR002 (except desnudo) o SCR014 (demasiados parámetros), indica la severidad y muestra la región de código señalada con un caret bajo el identificador infractor. La salida soporta colores ANSI cuando la salida estándar es un TTY, pero en modo pipe emite texto plano, lo que facilita integraciones con tee, logs o CI. Cuando no hay hallazgos, imprime All clean.
Avouch ofrece un modo --json que vuelca un documento JSON estable, versionado y determinista para integrarlo en pipelines de automatización, y un modo --quiet que ejecuta el análisis sin emitir informe y solo comunica el resultado mediante el código de salida (0 limpio, 1 con hallazgos, 2 error de la herramienta). Estos códigos están pensados para actuar como check opcional en hooks de Git o en sistemas de integración continua, sin imponer un bloqueo agresivo: la herramienta revisa, no bloquea.
Los archivos que parecen generados (patrones como generated.py, *_generated.py, codegen.py, autogen.py) se ignoran automáticamente. Adicionalmente, --changed ofrece una vista compacta de líneas añadidas y borradas frente a HEAD; --staged revisa solo los archivos preparados para el siguiente commit; --all-files analiza todo el repositorio; y --not-git permite usar la herramienta sin un repositorio Git, recorriendo los .py del directorio actual. El propio binario incluye documentación accesible con avouch --docs, que en un terminal interactivo abre un navegador con secciones de ayuda, navegación y salida limpia cuando se redirige. El proyecto se distribuye bajo licencia open source y puede ejecutarse como paso de revisión en GitHub Actions.