AILint

Análisis de calidad de código impulsado por IA para detectar violaciones de mejores prácticas, problemas de seguridad y problemas arquitectónicos en tiempo real.

GitHub
1

Documentación

AILint: Reglas de Restricción para la Generación de Código con IA

Evita que la IA genere código problemático: aplica principios de ingeniería de software.

El Problema: Los asistentes de IA son increíbles generando código funcional, pero a menudo producen código que viola las mejores prácticas, principios de seguridad y patrones arquitectónicos. Esto genera deuda técnica, vulnerabilidades de seguridad y pesadillas de mantenimiento.

La Solución: AILint proporciona un conjunto de reglas deterministas de máquinas de estado que actúan como "guardarraíles" para la generación de código con IA. Al aplicar principios probados de ingeniería de software como restricciones durante el proceso de generación de código, AILint garantiza que el resultado sea de alta calidad, seguro y mantenible.

¿Por qué AILint?

Los asistentes de IA, aunque potentes, presentan con frecuencia errores comunes en la generación de código:

  • Código Fuertemente Acoplado y No Comprobable: Tiende a dependencias hardcodeadas y estructuras monolíticas.
  • Patrones Inseguros: Introduce vulnerabilidades de inyección SQL, criptografía débil y otros fallos de seguridad.
  • Código Ilegible y Complejo: Genera lógica profundamente anidada y convenciones de nombres vagas.
  • Operaciones Ineficientes: Utiliza llamadas bloqueantes en lugar de patrones asíncronos y concurrentes.
  • Prácticas Inconsistentes: Produce mensajes de commit no estándar, mensajes de error poco útiles y nombres genéricos de variables/funciones.

AILint resuelve estos problemas aplicando restricciones durante el proceso de generación de código, no solo después.

Cómo Funciona

Cada regla de AILint es una sofisticada máquina de estados diseñada para guiar el comportamiento de la IA:

  1. Detección: Identifica patrones problemáticos o anti-patrones en las solicitudes de IA o fragmentos de código generados.
  2. Análisis: Evalúa el contexto, la intención y las posibles implicaciones del patrón detectado.
  3. Restricción: Aplica principios arquitectónicos específicos, mejores prácticas de seguridad o estándares de calidad de código como restricciones.
  4. Validación: Garantiza que el resultado de la IA cumpla con estas restricciones, proporcionando retroalimentación si se producen violaciones.
AI Request → Detection → Analysis → Constraint → Validation → High-Quality Code

Reglas Universales

La fortaleza principal de AILint reside en sus reglas universales, que son independientes del lenguaje y aplican principios fundamentales de ingeniería de software. Estas reglas se definen en archivos .mdc dentro del directorio rules/universal/.

Arquitectura y Diseño

  • evitar-clases-dios: Evita que la IA cree clases masivas con múltiples responsabilidades, aplicando el Principio de Responsabilidad Única.
  • composición-sobre-herencia: Guía a la IA para favorecer la composición en diseños flexibles y comprobables sobre jerarquías de herencia rígidas.
  • inyección-de-dependencias: Garantiza que la IA genere código con una inyección de dependencias adecuada, promoviendo la comprobabilidad y el acoplamiento flexible.

Seguridad y Rendimiento

  • seguro-por-defecto: Aplica patrones de seguridad primero, evitando inyección SQL, criptografía débil y otras vulnerabilidades comunes.
  • patrones-promesa: Guía a la IA para usar patrones asíncronos concurrentes, eliminando operaciones bloqueantes y mejorando el rendimiento.

Calidad y Legibilidad del Código

  • preferir-retornos-tempranos: Elimina cadenas if-else profundamente anidadas aplicando cláusulas de guarda y patrones de retorno temprano.
  • commits-convencionales: Garantiza que la IA genere mensajes de commit claros y estructurados siguiendo el estándar Conventional Commits.
  • nombres-descriptivos-de-funciones: Evita nombres de funciones vagos (process, handle) aplicando nombres que revelen la intención y sean específicos del comportamiento.
  • mensajes-de-error-explícitos: Guía a la IA para generar mensajes de error específicos y accionables en lugar de genéricos y poco útiles.
  • nombres-significativos-de-variables: Elimina nombres de variables vagos (data, result) aplicando nombres que revelen la intención y sean específicos del contexto.

Antes vs Después

Observa la mejora drástica en el código generado por IA cuando se aplican las restricciones de AILint.

Sin AILint (lo que la IA genera típicamente):

# Tightly coupled, insecure, unreadable nightmare
class UserService:
    def __init__(self):
        self.db = PostgresDatabase("localhost:5432")  # Hardcoded!
        self.cache = RedisCache("localhost:6379")     # Untestable!
    
    def login(self, username, password):
        # SQL injection vulnerability
        query = f"SELECT * FROM users WHERE username = '{username}'"
        user = self.db.execute(query).fetchone()
        
        # Weak password hashing
        password_hash = hashlib.md5(password.encode()).hexdigest()
        
        if user:
            if user.get('is_active'):
                if user.get('email'):
                    if '@' in user['email']:
                        if user.get('has_permission'):
                            # Logic buried 5 levels deep!
                            return user['email'].lower()

Con AILint (generación restringida):

# Loosely coupled, secure, testable, and readable
class UserService:
    def __init__(self, db, cache, logger):
        # Dependencies injected - fully testable!
        self.db = db
        self.cache = cache
        self.logger = logger
    
    def login(self, username, password):
        # Guard clauses - fail fast, clear flow
        if not username:
            raise ValueError('Username required')
        if not password:
            raise ValueError('Password required')
        
        # Parameterized query - SQL injection impossible
        query = "SELECT * FROM users WHERE username = ?"
        user = self.db.execute(query, (username,)).fetchone()
        
        # Secure password verification with bcrypt
        if user and bcrypt.checkpw(password.encode(), user['password_hash']):
            self.logger.info(f"User {username} logged in successfully")
            return user
        
        raise AuthenticationError('Invalid credentials')

Inicio Rápido

Método de Copiar y Pegar (Uso Inmediato)

Para una aplicación rápida y ad hoc de reglas:

  1. Elige una regla del directorio rules/universal/ (por ejemplo, secure-by-default.mdc).
  2. Copia todo el contenido del archivo .mdc.
  3. Pega el contenido de la regla directamente en el prompt de tu asistente de IA antes de tu solicitud de generación de código.
  4. Genera código – ¡la IA seguirá automáticamente las restricciones!

Ejemplo: Para evitar dependencias hardcodeadas, copia el contenido de dependency-injection.mdc en tu prompt.

Integración MCP (Configuración Profesional)

Para una integración fluida y persistente con herramientas de IA como Claude, Cursor y otras, utiliza el servidor MCP (Model Context Protocol) de AILint. Este proyecto (ailint-mcp) proporciona la implementación del servidor.

npm install -g @ailint/mcp

Consulta el repositorio ailint-mcp para obtener instrucciones detalladas de configuración para varios IDE y clientes de IA.

Estructura del Repositorio

ailint/
├── rules/
│   ├── universal/              # Language-agnostic rules (e.g., SRP, Security, Naming)
│   │   ├── avoid-god-classes.mdc
│   │   ├── composition-over-inheritance.mdc
│   │   ├── conventional-commits.mdc
│   │   ├── dependency-injection.mdc
│   │   ├── descriptive-function-names.mdc
│   │   ├── explicit-error-messages.mdc
│   │   ├── meaningful-variable-names.mdc
│   │   ├── prefer-early-returns.mdc
│   │   ├── promise-patterns.mdc
│   │   └── secure-by-default.mdc
│   ├── language-specific/      # (Future) Rules for specific languages (e.g., Python, JS, Java)
│   └── framework-specific/     # (Future) Rules for specific frameworks (e.g., React, Spring)
├── schemas/                    # (Future) Schemas for rule validation
│   └── rule-schema.json
├── docs/                       # (Future) Documentation on writing rules, philosophy
│   └── writing-rules.md
├── .gitignore
└── README.md                   # This file

Soporte de Lenguajes

Las reglas de AILint están diseñadas para ser universales, pero se proporcionan ejemplos y adaptaciones para mayor claridad en diferentes lenguajes de programación:

  • Python: Ejemplos principales, centrados en patrones idiomáticos de Python.
  • JavaScript: Patrones ES6+, async basado en Promesas, prácticas modernas de módulos.
  • Java: Patrones empresariales, CompletableFuture, convenciones de Spring.
  • C#: Patrones .NET, Task.WhenAll, prácticas de codificación segura.

Contribuciones

¡Agradecemos contribuciones para ampliar el conjunto de reglas de AILint y mejorar su efectividad!

Añadir Nuevas Reglas

  1. Identifica una limitación de la IA: Señala un patrón problemático común que la IA genera (por ejemplo, "la IA genera código síncrono cuando es mejor asíncrono").
  2. Crea un archivo de regla: Añade un nuevo archivo .mdc en rules/universal/ (o un nuevo directorio de lenguaje/framework si corresponde).
  3. Define la máquina de estados: Estructura tu regla con triggers, states, transitions y actions como se demuestra en los archivos .mdc existentes.
  4. Incluye ejemplos claros: Proporciona ejemplos de código "malo" (generado por IA sin AILint) y "bueno" (generado por IA con AILint).
  5. Envía una Pull Request: Asegúrate de que tu mensaje de commit siga Conventional Commits.

Mejorar Reglas Existentes

  • Añade adaptaciones específicas de lenguaje o ejemplos más diversos.
  • Refina descripciones de reglas, disparadores o restricciones.
  • Optimiza la lógica de la máquina de estados para una mejor detección.

Reportar Problemas

  • Informes de errores: Describe comportamientos inesperados de la IA o fallos de reglas con ejemplos reproducibles.
  • Solicitudes de funciones: Sugiere nuevas reglas o mejoras al sistema AILint.
  • Documentación: Ayuda a mejorar la claridad, ejemplos y guías.

Hoja de Ruta

  • Fase 3 (Planificada):
    • Análisis basado en AST: Implementar un análisis de código más profundo y preciso.
      • Interfaz de Creación de Reglas Personalizadas: Una interfaz amigable para definir nuevas reglas.
      • Mercado de Reglas: Una plataforma para compartir y descubrir reglas contribuidas por la comunidad.
      • Analíticas y Paneles de Equipo: Información sobre tendencias de calidad de código a lo largo del tiempo.
      • Extensión de VS Code: Integración directa en el editor VS Code.
  • Mejoras Futuras:
    • Paquetes de reglas específicos de lenguaje (por ejemplo, Python, JavaScript, Java).
      • Paquetes de reglas específicos de framework (por ejemplo, React, Spring, Django).
      • APIs de integración para asistentes de codificación de IA populares.

Filosofía

AILint se basa en el principio de que las restricciones habilitan la creatividad. Al proporcionar a los asistentes de IA límites claros y bien definidos basados en principios probados de ingeniería de software, les damos el poder de generar no solo código funcional, sino código excelente.

Piénsalo como "guardarraíles que evitan que la IA genere código problemático" – manteniendo a la IA en el camino hacia la calidad, seguridad y mantenibilidad.

Licencia

Este proyecto está licenciado bajo la Licencia MIT – consulta el archivo LICENSE para más detalles.

Comunidad

Construido con ❤️ por desarrolladores cansados de que la IA genere código problemático.

"Detengamos la epidemia de código problemático – una restricción de IA a la vez" – Equipo AILint