¿Qué es la puerta de commit?

La puerta de commit es una característica opcional en AI Diff Review que revisa automáticamente tus cambios de código antes de hacer commit. Basada en los resultados del análisis, puede recomendar bloquear un commit si detecta problemas de alto riesgo. Esto actúa como una red de seguridad automatizada, capturando problemas antes de que entren en tu repositorio.

La puerta está diseñada para ser inteligente y matizada—no bloquea cada problema menor, sino que se enfoca en cambios verdaderamente problemáticos que podrían causar vulnerabilidades de seguridad, pérdida de datos o rupturas graves de funcionalidad.

Cómo funciona la puerta de commit

Sistema de puntuación ponderada

La puerta de commit utiliza un sistema de puntuación ponderada sofisticado para evaluar la severidad de los hallazgos. Diferentes tipos de problemas contribuyen con diferentes cantidades al puntaje total:

  • Preocupaciones de seguridad: CRÍTICO=5, ADVERTENCIA=3, INFO=2
  • Problemas críticos: CRÍTICO=4, ADVERTENCIA=3, INFO=2
  • Notas de rendimiento: ADVERTENCIA=1.5, INFO=0.5
  • Sugerencias: ADVERTENCIA=1, INFO=0.5
  • Calidad del código: ADVERTENCIA=1, INFO=0.5
  • Recomendaciones de pruebas: ADVERTENCIA=0.5, INFO=0.25

Esta ponderación asegura que los problemas de seguridad y los problemas críticos tengan más impacto en la decisión que las sugerencias menores o las recomendaciones de estilo.

Niveles de severidad

La puerta de commit ofrece tres niveles de severidad que determinan qué tan estricto es el comportamiento de bloqueo:

Nivel INFO

Bloquea commits cuando el puntaje ponderado total alcanza 4.0 o más. Esta es la configuración más indulgente, adecuada para equipos que quieren capturar solo los problemas más graves.

Nivel ADVERTENCIA

Bloquea commits cuando el puntaje ponderado total alcanza 6.0 o más. Esto proporciona un enfoque equilibrado, capturando problemas significativos mientras permite que pasen problemas menores.

Nivel CRÍTICO

Bloquea commits cuando el puntaje ponderado total alcanza 8.0 o más, O cuando se encuentra cualquier elemento CRÍTICO en las categorías Preocupaciones de seguridad o Problemas críticos. Esta es la configuración más estricta, asegurando que los problemas graves nunca lleguen al repositorio.

Condiciones de bloqueo duro

Ciertas condiciones siempre activan una recomendación de bloqueo, independientemente del puntaje total:

  • Cualquier elemento de severidad CRÍTICO en Preocupaciones de seguridad
  • Problemas de seguridad de alto riesgo tales como:
    • Fugas de secretos o credenciales expuestas
    • Vulnerabilidades de inyección SQL
    • Riesgos de ejecución de código remoto (RCE)
    • Problemas de bypass de autenticación
    • Vulnerabilidades de escalada de privilegios

Estas condiciones de bloqueo duro aseguran que las vulnerabilidades de seguridad graves nunca se comiteen accidentalmente, incluso si el puntaje general es bajo.

Recomendaciones explícitas de IA

Además del sistema de puntuación ponderada, el modelo de IA puede recomendar explícitamente bloquear un commit estableciendo should_block_commit=true en su respuesta. Cuando esto sucede, el plugin recomendará bloquear el commit y proporcionará el razonamiento de la IA en el campo block_reason.

Esto permite que la IA tome decisiones matizadas basadas en contexto que podrían no ser capturadas por el sistema de puntuación solo. Por ejemplo, la IA podría detectar un patrón de problemas que, aunque individualmente menores, colectivamente representan un problema significativo.

Toma de decisiones con intervención humana

La puerta de commit no te impide automáticamente hacer commit—proporciona una recomendación y te da la última palabra. Cuando intentas hacer commit con la puerta habilitada, verás un diálogo de decisión que muestra:

  • La recomendación de la puerta (BLOQUEAR o PROCEDER)
  • Puntaje total y umbral
  • Conteo de hallazgos por severidad
  • Resumen de hallazgos clave
  • Problemas contribuyentes principales

Esta transparencia te ayuda a entender por qué un commit fue marcado y tomar una decisión informada. Si decides proceder a pesar de una recomendación BLOQUEAR, puedes proporcionar una razón que se agregará a tu mensaje de commit.

Configurar la puerta de commit

Habilitar la puerta

Para habilitar la puerta de commit, ve a Configuración → Herramientas → AI Diff Review y marca "Habilitar revisión pre-commit". Luego puedes seleccionar tu nivel de severidad de puerta preferido.

Elegir el nivel correcto

El nivel de severidad correcto depende de las necesidades de tu equipo:

  • INFO: Bueno para equipos que recién comienzan con revisión automatizada o aquellos con desarrolladores muy experimentados
  • ADVERTENCIA: Opción equilibrada para la mayoría de los equipos, capturando problemas significativos sin ser demasiado restrictivo
  • CRÍTICO: Mejor para proyectos sensibles a la seguridad o equipos que quieren protección máxima

Conciencia del alcance del diff

La puerta de commit es consciente de la configuración del alcance del diff. Por defecto, solo los hallazgos vinculados a líneas modificadas (o dentro de una pequeña ventana de proximidad) contribuyen a la puntuación. Los elementos INFO globales o no dirigidos típicamente se ignoran para fines de puerta, asegurando que la puerta se enfoque en problemas realmente introducidos por tus cambios.

Mejores prácticas

Comenzar conservador

Si eres nuevo en puertas de commit, comienza con el nivel INFO y aumenta gradualmente la rigurosidad a medida que tu equipo se sienta cómodo con el proceso. Esto ayuda a evitar la frustración de un bloqueo demasiado agresivo.

Revisar commits bloqueados

Cuando un commit es bloqueado, tómate tiempo para revisar los hallazgos. Incluso si decides proceder, entender por qué fue marcado te ayuda a aprender y mejorar la calidad de tu código.

Usar la anulación razonablemente

La capacidad de anular una recomendación de bloqueo es importante para la flexibilidad, pero úsala con consideración. Si anulas frecuentemente los bloqueos, considera si tu nivel de puerta es demasiado estricto o si hay patrones en tu código que necesitan abordarse.

Comunicación del equipo

Asegúrate de que tu equipo entienda cómo funciona la puerta de commit y por qué ciertos commits son bloqueados. Esto ayuda a construir confianza en el sistema y asegura que todos estén alineados en los estándares de calidad del código.

Conclusión

La puerta de commit es una herramienta poderosa para mantener la calidad y seguridad del código, pero es más efectiva cuando se configura apropiadamente para las necesidades de tu equipo. Al entender cómo funciona la puntuación ponderada y elegir el nivel de severidad correcto, puedes crear una red de seguridad efectiva que capture problemas sin convertirse en un cuello de botella.

Recuerda, la puerta está ahí para ayudar, no para obstaculizar. Úsala como una herramienta para mejorar la calidad del código mientras mantienes la productividad del desarrollador. Con la configuración adecuada y el apoyo del equipo, la puerta de commit se convierte en una parte invaluable de tu flujo de trabajo de desarrollo.

¿Listo para configurar tu puerta de commit? Instala AI Diff Review y comienza a proteger tu base de código hoy.