AILint

Análise de qualidade de código com IA para detectar violações de melhores práticas, problemas de segurança e falhas arquiteturais em tempo real.

GitHub
1

Documentação

AILint: Regras de Restrição para Geração de Código com IA

Impeça a IA de gerar código problemático – Aplique princípios de engenharia de software.

O Problema: Assistentes de IA são incríveis em gerar código funcional, mas frequentemente produzem código que viola boas práticas, princípios de segurança e padrões arquiteturais. Isso gera dívida técnica, vulnerabilidades de segurança e pesadelos de manutenção.

A Solução: AILint fornece um conjunto de regras determinísticas de máquina de estados que atuam como "guarda-corpos" para a geração de código com IA. Ao aplicar princípios comprovados de engenharia de software como restrições durante o processo de geração de código, o AILint garante que a saída seja de alta qualidade, segura e mantível.

Por que AILint?

Assistentes de IA, embora poderosos, frequentemente apresentam armadilhas comuns na geração de código:

  • Código Fortemente Acoplado e Não Testável: Padrões padrão com dependências fixas e estruturas monolíticas.
  • Padrões Inseguros: Introduz vulnerabilidades de injeção SQL, criptografia fraca e outras falhas de segurança.
  • Código Ilegível e Complexo: Gera lógica profundamente aninhada e convenções de nomenclatura vagas.
  • Operações Ineficientes: Usa chamadas bloqueantes em vez de padrões assíncronos e concorrentes.
  • Práticas Inconsistentes: Produz mensagens de commit não padronizadas, mensagens de erro pouco úteis e nomes genéricos de variáveis/funções.

AILint resolve esses problemas aplicando restrições durante o processo de geração de código, não apenas depois.

Como Funciona

Cada regra do AILint é uma máquina de estados sofisticada projetada para guiar o comportamento da IA:

  1. Detecção: Identifica padrões problemáticos ou anti-padrões em solicitações de IA ou trechos de código gerados.
  2. Análise: Avalia o contexto, a intenção e as possíveis implicações do padrão detectado.
  3. Restrição: Aplica princípios arquiteturais específicos, boas práticas de segurança ou padrões de qualidade de código como restrições.
  4. Validação: Garante que a saída da IA adere a essas restrições, fornecendo feedback se ocorrerem violações.
AI Request → Detection → Analysis → Constraint → Validation → High-Quality Code

Regras Universais

A força central do AILint está em suas regras universais, que são agnósticas de linguagem e aplicam princípios fundamentais de engenharia de software. Essas regras são definidas em arquivos .mdc dentro do diretório rules/universal/.

Arquitetura e Design

  • avoid-god-classes: Impede a IA de criar classes massivas com múltiplas responsabilidades, aplicando o Princípio da Responsabilidade Única.
  • composition-over-inheritance: Guia a IA a favorecer composição para designs flexíveis e testáveis em vez de hierarquias rígidas de herança.
  • dependency-injection: Garante que a IA gere código com injeção de dependência adequada, promovendo testabilidade e baixo acoplamento.

Segurança e Desempenho

  • secure-by-default: Aplica padrões de segurança em primeiro lugar, prevenindo injeção SQL, criptografia fraca e outras vulnerabilidades comuns.
  • promise-patterns: Guia a IA a usar padrões assíncronos concorrentes, eliminando operações bloqueantes e melhorando o desempenho.

Qualidade e Legibilidade do Código

  • prefer-early-returns: Elimina cadeias if-else profundamente aninhadas aplicando cláusulas de guarda e padrões de retorno antecipado.
  • conventional-commits: Garante que a IA gere mensagens de commit claras e estruturadas seguindo o padrão Conventional Commits.
  • descriptive-function-names: Impede nomes de funções vagos (process, handle) aplicando nomenclatura que revela intenção e é específica do comportamento.
  • explicit-error-messages: Guia a IA a gerar mensagens de erro específicas e acionáveis em vez de genéricas e pouco úteis.
  • meaningful-variable-names: Elimina nomes de variáveis vagos (data, result) aplicando nomenclatura que revela intenção e é específica do contexto.

Antes vs Depois

Veja a melhoria dramática no código gerado por IA quando as restrições do AILint são aplicadas.

Sem AILint (o que a IA normalmente gera):

# 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()

Com AILint (geração restrita):

# 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')

Início Rápido

Método Copiar-Colar (Uso Imediato)

Para aplicação rápida e ad-hoc de regras:

  1. Escolha uma regra do diretório rules/universal/ (ex.: secure-by-default.mdc).
  2. Copie todo o conteúdo do arquivo .mdc.
  3. Cole o conteúdo da regra diretamente no prompt do seu assistente de IA antes da sua solicitação de geração de código.
  4. Gere o código – a IA seguirá automaticamente as restrições!

Exemplo: Para evitar dependências fixas, copie o conteúdo de dependency-injection.mdc para o seu prompt.

Integração MCP (Configuração Profissional)

Para integração contínua e persistente com ferramentas de IA como Claude, Cursor e outras, use o servidor MCP (Model Context Protocol) do AILint. Este projeto (ailint-mcp) fornece a implementação do servidor.

npm install -g @ailint/mcp

Consulte o repositório ailint-mcp para instruções detalhadas de configuração para vários IDEs e clientes de IA.

Estrutura do Repositório

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

Suporte a Linguagens

As regras do AILint são projetadas para serem universais, mas exemplos e adaptações são fornecidos para clareza em diferentes linguagens de programação:

  • Python: Exemplos principais, focando em padrões idiomáticos de Python.
  • JavaScript: Padrões ES6+, async baseado em Promise, práticas modernas de módulos.
  • Java: Padrões empresariais, CompletableFuture, convenções Spring.
  • C#: Padrões .NET, Task.WhenAll, práticas de codificação segura.

Contribuindo

Aceitamos contribuições para expandir o conjunto de regras do AILint e melhorar sua eficácia!

Adicionando Novas Regras

  1. Identifique uma limitação da IA: Aponte um padrão problemático comum que a IA gera (ex.: "IA gera código síncrono quando assíncrono é melhor").
  2. Crie um arquivo de regra: Adicione um novo arquivo .mdc em rules/universal/ (ou um novo diretório de linguagem/framework, se aplicável).
  3. Defina a máquina de estados: Estruture sua regra com triggers, states, transitions e actions conforme demonstrado nos arquivos .mdc existentes.
  4. Inclua exemplos claros: Forneça exemplos de código "ruim" (gerado por IA sem AILint) e "bom" (gerado por IA com AILint).
  5. Envie um Pull Request: Garanta que sua mensagem de commit siga o padrão Conventional Commits.

Melhorando Regras Existentes

  • Adicione adaptações específicas de linguagem ou exemplos mais diversos.
  • Refine descrições de regras, gatilhos ou restrições.
  • Otimize a lógica da máquina de estados para melhor detecção.

Reportando Problemas

  • Relatórios de bugs: Descreva comportamento inesperado da IA ou falhas de regras com exemplos reproduzíveis.
  • Solicitações de recursos: Sugira novas regras ou melhorias no sistema AILint.
  • Documentação: Ajude a melhorar a clareza, exemplos e guias.

Roadmap

  • Fase 3 (Planejada):
    • Análise baseada em AST: Implementar análise de código mais profunda e precisa.
      • Interface de Criação de Regras Personalizadas: Uma interface amigável para definir novas regras.
      • Marketplace de Regras: Uma plataforma para compartilhar e descobrir regras contribuídas pela comunidade.
      • Analíticos e Dashboards de Equipe: Insights sobre tendências de qualidade de código ao longo do tempo.
      • Extensão VS Code: Integração direta no editor VS Code.
  • Melhorias Futuras:
    • Pacotes de regras específicos de linguagem (ex.: Python, JavaScript, Java).
      • Pacotes de regras específicos de framework (ex.: React, Spring, Django).
      • APIs de integração para assistentes populares de codificação com IA.

Filosofia

AILint é construído sobre o princípio de que restrições permitem criatividade. Ao fornecer aos assistentes de IA limites claros e bem definidos baseados em princípios comprovados de engenharia de software, nós os capacitamos a gerar não apenas código funcional, mas código excelente.

Pense nisso como "guarda-corpos que impedem a IA de gerar código problemático" – mantendo a IA no caminho da qualidade, segurança e manutenibilidade.

Licença

Este projeto é licenciado sob a Licença MIT – consulte o arquivo LICENSE para detalhes.

Comunidade

Construído com ❤️ por desenvolvedores cansados de IA gerando código problemático.

"Pare a epidemia de código problemático – uma restrição de IA por vez" – Equipe AILint