@lucaford/ai-code-reviewer

v1.0.0

Published

2 days ago

AI-powered code review agent for GitHub Pull Requests using Kimi K2.5 or Claude 3.5 Sonnet

0High
0Medium
0Low

lucaford

github code-review ai claude kimi automation pull-request github-actions code-quality static-analysis

🤖 AI Code Review Agent

Un agente automatizado de code review impulsado por IA que analiza Pull Requests en GitHub y proporciona feedback inteligente sobre bugs, seguridad y mejores prácticas.

⚡ Instalación en 1 comando: Compatible con cualquier lenguaje (Java, Python, Node.js, Go, etc.)
npx @lucaford/ai-code-reviewer install

✨ Características

🔍 Análisis Automático: Se ejecuta automáticamente en cada Pull Request
🧠 Múltiples Proveedores de IA: Soporta Kimi K2.5 (Moonshot AI) y Claude 3.5 Sonnet (Anthropic)
🎯 Revisión Enfocada: Detecta bugs, vulnerabilidades de seguridad y violaciones de mejores prácticas
💬 Comentarios Inline: Publica comentarios directamente en las líneas problemáticas
📊 Resumen Ejecutivo: Genera un resumen del análisis con severidades
⚡ Rápido y Eficiente: Analiza múltiples archivos en paralelo
🎨 Reglas Personalizables: Configura principios SOLID, estándares del equipo y reglas específicas del proyecto

🚀 Instalación Rápida

Método 1: NPM Package (Recomendado) ⚡

La forma más fácil y mantenible de instalar y actualizar:

# Instalar en tu proyecto
cd /path/to/your/project
npx @lucaford/ai-code-reviewer install

El CLI te guiará a través del proceso de instalación. Automáticamente:

✅ Valida requisitos (Git, Node.js)
✅ Copia archivos necesarios
✅ Instala dependencias
✅ Compila TypeScript
✅ Configura el workflow de GitHub Actions

Para actualizar en el futuro:

npx @lucaford/ai-code-reviewer update

Comandos disponibles:

npx @lucaford/ai-code-reviewer install   # Instalar
npx @lucaford/ai-code-reviewer update    # Actualizar
npx @lucaford/ai-code-reviewer version   # Ver versión
npx @lucaford/ai-code-reviewer help      # Ayuda

Método 2: Instalación Remota con Script

Si prefieres un script bash:

# Desde el root de tu proyecto
cd /path/to/your/project
curl -fsSL https://raw.githubusercontent.com/lucaford/ai-code-reviewer/main/remote-install.sh | bash

O con wget:

cd /path/to/your/project
wget -qO- https://raw.githubusercontent.com/lucaford/ai-code-reviewer/main/remote-install.sh | bash

Compatible con cualquier lenguaje: Java, Python, Node.js, Go, Ruby, PHP, C#, Rust, etc.

📖 Documentación completa: Ver INSTALL.md

Método 3: Script Local

Si ya clonaste el repositorio:

# Desde el root de tu proyecto
cd /path/to/your/project
bash /path/to/ai-code-reviewer/install-ai-reviewer.sh

Método 4: Instalación Manual

Si prefieres hacerlo manualmente:

Paso 1: Clonar o copiar el repositorio

git clone <tu-repo>
cd agent-code-review

Paso 2: Instalar dependencias

npm install

Paso 3: Compilar TypeScript

npm run build

Paso 4: Configurar Secrets en GitHub

Ve a tu repositorio en GitHub:

Settings → Secrets and variables → Actions
Agrega el secret correspondiente al proveedor que uses:
- Para Kimi (recomendado): KIMI_API_KEY
- Para Claude: ANTHROPIC_API_KEY

Nota: GITHUB_TOKEN es provisto automáticamente por GitHub Actions.

Paso 5: Obtener API Key

Opción A: Kimi K2.5 (Por defecto - Recomendado)

Ve a platform.moonshot.ai
Crea una cuenta o inicia sesión
Ve a "API Keys" y crea una nueva key
Copia la key y agrégala como secret KIMI_API_KEY en GitHub

Ventajas de Kimi:

Modelo optimizado para código
Ventana de contexto de 128K tokens
Excelente relación precio-rendimiento
Soporte nativo para chino e inglés

Opción B: Claude 3.5 Sonnet (Anthropic)

Ve a console.anthropic.com
Crea una cuenta o inicia sesión
Ve a "API Keys" y crea una nueva key
Copia la key y agrégala como secret ANTHROPIC_API_KEY en GitHub

Paso 6: Cambiar el proveedor de IA (Opcional)

Por defecto se usa Kimi. Para cambiar a Claude:

Ve a Settings → Secrets and variables → Actions → Variables
Crea una nueva variable llamada AI_PROVIDER con valor claude

O edita .github/workflows/code-review.yml y cambia:

AI_PROVIDER: ${{ vars.AI_PROVIDER || 'kimi' }}

Paso 7: Activar el workflow

El workflow ya está configurado en .github/workflows/code-review.yml y se activará automáticamente cuando:

Se abre un nuevo Pull Request
Se hace push a un PR existente
Se reabre un PR cerrado

🎨 Configurar Reglas Personalizadas (Opcional)

Personaliza las reglas de revisión según las necesidades de tu equipo. Crea un archivo .reviewrc.json en la raíz de tu proyecto:

{
  "language": "Java",
  "framework": "Spring Boot",
  "strictMode": true,
  "focusAreas": [
    {
      "category": "PRINCIPIOS SOLID",
      "rules": [
        "Single Responsibility: Cada clase debe tener una única responsabilidad",
        "Dependency Inversion: Depender de abstracciones, no de implementaciones"
      ]
    },
    {
      "category": "SPRING BOOT BEST PRACTICES",
      "rules": [
        "Inyección de dependencias mediante constructor",
        "Uso apropiado de @Transactional",
        "DTOs separados de entidades JPA"
      ]
    }
  ],
  "customInstructions": "Priorizar arquitectura limpia y código testeable"
}

📖 Documentación completa: Ver RULES.md para guía detallada y ejemplos por tecnología (React, Django, Express, etc.)

🔄 Actualizar a Nueva Versión

Si instalaste usando el método NPM (recomendado), actualizar es muy simple:

cd /path/to/your/project
npx @lucaford/ai-code-reviewer update

El comando update:

✅ Detecta automáticamente la instalación existente (subdirectorio o root)
✅ Hace backup de node_modules por seguridad
✅ Actualiza el código fuente (src/)
✅ Actualiza configuración (package.json, tsconfig.json)
✅ Actualiza el workflow de GitHub Actions
✅ Reinstala dependencias limpias
✅ Recompila TypeScript
✅ Muestra el cambio de versión (v1.0.0 → v1.1.0)

Después de actualizar, solo necesitas:

git add .
git commit -m "Update AI Code Reviewer to v1.1.0"
git push

Verificar versión instalada

# Ver versión del paquete NPM
npx @lucaford/ai-code-reviewer version

# Ver versión en tu proyecto (si está en subdirectorio)
cat .ai-reviewer/package.json | grep version

# Ver versión en tu proyecto (si está en root)
cat package.json | grep version

Actualización manual

Si instalaste con script bash, puedes:

Volver a ejecutar el script de instalación (sobrescribirá archivos)

O migrar al método NPM:

npx @lucaford/ai-code-reviewer install
# Selecciona sobrescribir archivos existentes

📦 Estructura del Proyecto

agent-code-review/
├── .github/
│   └── workflows/
│       └── code-review.yml       # GitHub Action workflow
├── src/
│   ├── index.ts                  # Punto de entrada principal
│   ├── analyzer/
│   │   ├── kimi-client.ts        # Cliente de Kimi API
│   │   ├── claude-client.ts      # Cliente de Claude API
│   │   └── index.ts              # Factory de analyzers
│   ├── github/
│   │   ├── pr-fetcher.ts         # Obtener cambios del PR
│   │   └── comment-poster.ts     # Publicar comentarios
│   ├── prompts/
│   │   └── review-prompts.ts     # Prompts para análisis
│   └── types/
│       └── index.ts               # Definiciones de tipos
├── dist/                          # Código compilado
├── package.json
└── tsconfig.json

🎯 Qué Revisa el Agente

1. Bugs y Errores Potenciales

Errores lógicos
Edge cases no manejados
Null/undefined pointer exceptions
Race conditions
Manejo incorrecto de errores

2. Seguridad

Vulnerabilidades de inyección (SQL, XSS, etc.)
Datos sensibles expuestos (API keys, passwords)
Validación de entrada faltante
Autenticación/autorización débil
Dependencias con vulnerabilidades

3. Mejores Prácticas

Violaciones de principios SOLID
Código duplicado
Funciones muy largas o complejas
Nombres poco descriptivos
Falta de modularidad
Patrones de diseño incorrectos

📝 Ejemplo de Uso

Una vez configurado, el agente trabajará automáticamente:

Alguien abre un PR en tu repositorio
GitHub Actions se activa automáticamente
El agente descarga los cambios del PR
La IA (Kimi o Claude) analiza cada archivo modificado
Se publican comentarios inline en el código
Se genera un resumen del review

Ejemplo de Comentario

🚨 Crítico

Posible inyección SQL. La entrada del usuario se concatena 
directamente en la query sin sanitización.

💡 Sugerencia:
Usa prepared statements o un ORM para prevenir inyección SQL:
`db.query('SELECT * FROM users WHERE id = ?', [userId])`

⚙️ Configuración Avanzada

Cambiar el Proveedor de IA

Por defecto se usa Kimi. Puedes cambiarlo de varias formas:

Opción 1: Variable de repositorio (Recomendado)

Settings → Secrets and variables → Actions → Variables
Crea AI_PROVIDER con valor claude o kimi

Opción 2: Variable de entorno en el workflow Edita .github/workflows/code-review.yml:

env:
  AI_PROVIDER: 'claude'  # o 'kimi'

Cambiar el Modelo de IA

Para Kimi: Edita src/analyzer/kimi-client.ts:

constructor(apiKey: string, model: string = 'moonshot-v1-128k') {
  // Otros modelos disponibles: moonshot-v1-32k, moonshot-v1-8k
}

Para Claude: Edita src/analyzer/claude-client.ts:

constructor(apiKey: string, model: string = 'claude-3-5-sonnet-20241022') {
  // claude-3-opus-20240229: Análisis más profundo
  // claude-3-haiku-20240307: Más rápido y económico
}

Personalizar los Prompts

Edita src/prompts/review-prompts.ts para ajustar:

Qué aspectos revisar
Severidad de los problemas
Estilo de los comentarios
Formato de las respuestas

Filtrar Archivos a Analizar

Edita src/github/pr-fetcher.ts para cambiar las extensiones de archivo:

const extensions = [
  '.ts', '.tsx', '.js', '.jsx',  // JavaScript/TypeScript
  '.py',                          // Python
  '.go',                          // Go
  '.java',                        // Java
  // Agrega más según necesites
];

💰 Costos Estimados

Kimi K2.5 (Moonshot AI)

Precios competitivos y excelente relación costo-beneficio:

PR pequeño (1-3 archivos, ~500 líneas): ~¥0.10-0.30 (~$0.014-0.042)
PR mediano (4-10 archivos, ~1000 líneas): ~¥0.30-0.80 (~$0.042-0.112)
PR grande (10+ archivos, ~2000+ líneas): ~¥0.80-2.00 (~$0.112-0.280)

Claude 3.5 Sonnet (Anthropic)

Precios premium para análisis más profundo:

PR pequeño (1-3 archivos, ~500 líneas): ~$0.05-0.15
PR mediano (4-10 archivos, ~1000 líneas): ~$0.15-0.40
PR grande (10+ archivos, ~2000+ líneas): ~$0.40-1.00

Nota: Los precios son aproximados y pueden variar según el contenido específico analizado.

🔧 Scripts NPM

# Compilar TypeScript
npm run build

# Ejecutar localmente (requiere variables de entorno)
npm start

# Limpiar archivos compilados
npm run clean

🐛 Troubleshooting

El workflow no se ejecuta

Verifica que el archivo .github/workflows/code-review.yml existe
Asegúrate que los permisos de GitHub Actions están habilitados en Settings → Actions

Error: "KIMI_API_KEY no está configurado" o "ANTHROPIC_API_KEY no está configurado"

Verifica que agregaste el secret correspondiente a tu proveedor en GitHub
El nombre debe ser exactamente KIMI_API_KEY o ANTHROPIC_API_KEY
Asegúrate que el proveedor configurado coincide con la API key que proporcionaste

Error al publicar comentarios

Verifica que el workflow tiene permisos de pull-requests: write
Asegúrate que GITHUB_TOKEN tiene los permisos necesarios

La IA no encuentra problemas reales

Ajusta los prompts en src/prompts/review-prompts.ts
Para análisis más profundo, considera usar Claude 3 Opus
Proporciona más contexto sobre tu proyecto en los prompts
Verifica que los archivos modificados tienen código real (no solo documentación)

Cambiar entre proveedores

Configura la variable AI_PROVIDER en Settings → Secrets and variables → Actions → Variables
Asegúrate de tener la API key correspondiente configurada como secret

📄 Licencia

ISC

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor abre un issue o PR.

📚 Recursos

Hecho con ❤️ usando Kimi K2.5 y Claude AI