Titicode

Análisis quirúrgico de Pull Requests con la agudeza visual de un Titi Cabeciblanco.

Titicode no es simplemente un revisor basado en inteligencia artificial; es un motor de análisis híbrido que integra validaciones deterministas locales con el razonamiento semántico de los modelos de lenguaje (LLM). Inspirado en el Titi Cabeciblanco, el sistema actúa como un vigía experto, identificando riesgos arquitectónicos y lógicos que pasan desapercibidos para las herramientas convencionales.

Filosofía: Nutrición de Contexto e IA con Lentes

A diferencia de soluciones que envían prompts genéricos, Titicode se encarga de nutrir al LLM. Antes de realizar la inferencia, el motor procesa el entorno del cambio para proporcionar lentes de alta precisión a la IA:

• Detección de Impacto: Identificamos archivos y exports eliminados que no han sido corregidos en las referencias dependientes del proyecto.
• Sandbox Agnóstico: El núcleo del sistema es agnóstico de reglas. La responsabilidad de la validación se delega al equipo de desarrollo, permitiéndoles construir sus propias protecciones en la carpeta .titicode/ del repositorio.
• Análisis Arquitectónico: El sistema evalúa la topología de dependencias para entender la jerarquía y relevancia de cada archivo modificado.

Características Principales

• Zero-Checkout (Worktree): Analiza cualquier rama sin hacer checkout ni modificar tu directorio de trabajo actual. Utiliza git worktree para crear entornos aislados temporales.
• Motor Sandbox: Ejecución de reglas locales (.yml) y scripts de validación complejos (.js) con acceso total al AST del código.
• Validación Estructural con ast-grep: Integración nativa para detectar antipatrones mediante búsqueda estructural de nodos, superando las limitaciones del análisis basado en texto.
• Prompts Personalizados: Capacidad para inyectar guías de estilo y reglas de negocio específicas mediante archivos Markdown en .titicode/prompts/.
• Soporte Multi-Proveedor: Compatibilidad nativa con Google Gemini y modelos a través de OpenRouter.
• Operación Híbrida: Funcionamiento en entornos locales y flujos de trabajo de AWS CodeCommit.

Instalación y Vinculación

Para integrar Titicode globalmente en su entorno de terminal:

1. Instalar dependencias: npm install

2. Compilar el proyecto: npm run build

3. Crear el vínculo simbólico: npm link

Una vez vinculado, puede iniciar el análisis ejecutando: titicode

El Poder del Sandbox (.titicode/)

Titicode otorga control total al equipo sobre qué se valida. Dentro del directorio .titicode/ del proyecto, puede configurar reglas y scripts personalizados:

Guía Completa del Sandbox: ./docs/README.md

1. Reglas Estáticas (rules/*.yml): Utiliza la potencia de ast-grep para definir patrones estructurales prohibidos.
2. Sensores de Dominio (rules-scripts/*.js): Scripts en Node.js con una API rica para análisis profundo de archivos y reporte de violaciones complejas.
3. Prompts Custom (prompts/*.md): Archivos que definen el contexto adicional, personalidad y estándares de equipo que el LLM debe considerar.

Zero-Checkout: Análisis con Git Worktree y Doble Índice

Titicode implementa un enfoque Zero-Checkout utilizando git worktree para crear entornos aislados temporales y un sistema de doble indexación para garantizar la precisión del análisis.

Sistema de Índices (Target vs Source)

Para detectar roturas de contrato de forma precisa, el sistema gestiona dos representaciones del proyecto:

1. Target Index (target-index.json): Representa el estado actual de la rama destino (ej: main). Se genera creando un worktree temporal de la rama base.
2. Source Index (source-index.json): Representa el estado final de la rama de cambios (el PR). Se genera basándose en el entorno aislado del análisis.

Recomendación: Estos archivos se guardan en .titicode/graph/. Se recomienda añadir esta carpeta a tu .gitignore para no trackear los índices generados localmente.

Validación por Commit Hash

Cada índice incluye metadatos con el hash del commit. Si el sistema detecta que el commit local de una rama no coincide con el guardado en el índice, regenerará automáticamente el grafo para asegurar que el análisis de impacto se basa en código real y actualizado.

Beneficios

• Consistencia: Las refactorizaciones coordinadas dentro de un mismo PR no se marcan como errores si el estado final en la rama source es consistente.
• Rendimiento: El uso de archivos físicos como caché evita regenerar el grafo completo si los commits no han cambiado.
• Precisión: Al indexar la rama base en un entorno separado, se detectan cambios estructurales incluso si no has hecho checkout a esa rama recientemente.

Fallback Seguro

Si por alguna razón no se puede crear el worktree (ej: permisos del sistema), Titicode continúa usando el directorio actual del proyecto, mostrando una advertencia pero permitiendo que el análisis continúe.

El Pipeline de Análisis

El proceso de revisión se ejecuta en etapas de enriquecimiento progresivo:

1. Inicialización y Worktree: Se crea el entorno aislado y se prepara el estado del análisis.
2. Ejecución del Sandbox: Se procesan las reglas locales para detectar errores estructurales inmediatos.
3. Análisis de Referencias Rotas: Identificación de inconsistencias provocadas por la eliminación de entidades.
4. Evaluación Topológica: Cálculo de la relevancia del archivo dentro de la red de dependencias del proyecto.
5. Inferencia Optimizada: Construcción de un prompt que incluye los hallazgos del sandbox y las alertas de impacto, permitiendo que el LLM sea extremadamente preciso.
6. Limpieza: Se elimina el worktree temporal y se liberan recursos.

Documentación Técnica

Para una guía detallada de todos los componentes, consulte el Índice de Documentación.

• Arquitectura y Pipeline: ./docs/ARCHITECTURE.md
• Configuración y Secretos: ./docs/CONFIGURATION.md
• Reglas Personalizadas: ./docs/CUSTOM_RULES.md
• Sensores de Dominio: ./docs/DOMAIN_SENSORS.md

Análisis de Impacto y Rotura de Contratos

El sistema utiliza el índice de símbolos y el grafo de dependencias para identificar riesgos colaterales en cada cambio:

1. Detección de Breaking Changes: Se comparan los símbolos exportados de la rama base contra la rama de cambios. Si un símbolo desaparece o cambia su firma, se marca como una rotura de contrato.
2. Identificación de Afectados: Utilizando el grafo de dependencias, el motor localiza todos los archivos que importan los símbolos modificados o eliminados.
3. Notificación al Modelo: Esta información se inyecta en el prompt del LLM, permitiéndole advertir sobre errores de compilación en archivos que no forman parte directa del Pull Request.
4. Código Muerto: Se analizan los nuevos exports para verificar si tienen referencias activas en el resto del proyecto.

Consideraciones para Despliegue en AWS Lambda

Para futuras implementaciones en entornos serverless como AWS Lambda, se deben considerar los siguientes cambios en la estrategia de manejo de repositorio:

1. El uso de git worktree deja de ser necesario ya que cada ejecución de la función ocurre en un contenedor efímero y aislado.
2. Debido a que solo el directorio /tmp es escribible en Lambda, el repositorio debe inicializarse directamente en dicha ubicación.
3. Se recomienda sustituir la creación de worktrees por un clonado superficial (shallow clone) utilizando git clone --depth 1 o git fetch --depth 1 para minimizar el consumo de almacenamiento y tiempo de red.
4. El control de la versión a analizar se realizará mediante un checkout directo sobre el clon fresco en /tmp, garantizando que el entorno este limpio para cada ejecución.

---

Titicode: Vigilancia experta de su código, un commit a la vez.

Próximos Pasos (Roadmap)

• Soporte para AWS Lambda: Implementar la ejecución serverless para facilitar la integración en pipelines de CI/CD sin servidores dedicados.
• Integración con Gestión de Proyectos:
  • Lectura de tickets en Jira y páginas de Notion.
  • Capacidad de contrastar el código del PR contra los criterios de aceptación de la Historia de Usuario (HU).
• Soporte Multi-lenguaje Extendido: Añadir gramáticas de tree-sitter para Java y Dart (Flutter).