[RAG] Indexar assinaturas de código (code_structure) em vez de corpo completo das funções

[felipefernandes]

Contexto

Inspirado na estratégia code_structure do Th0th, que extrai apenas assinaturas, interfaces e hierarquias — gerando 70-90% de redução de tokens no contexto.

Hoje o CodeChunker da Iara indexa o código-fonte completo de cada função e classe:

# iara/memory/indexer.py — CodeVisitor._process_node()
chunk_content = ast.get_source_segment(self.content, node)  # ← corpo COMPLETO

Para uma função de 80 linhas, o chunk tem 80 linhas. Para o objetivo de fornecer contexto ao LLM durante o review, isso é frequentemente excessivo — o LLM precisa entender o que a função faz e como é chamada, não necessariamente cada linha da implementação.

Problema

Chunks grandes têm três consequências negativas:

1. Menos chunks cabem no prompt — com limite de tokens, 3 chunks de 80 linhas ocupam o espaço de 15 chunks de 15 linhas
2. Ruído na busca vetorial — embeddings de funções longas capturam menos o "significado" central da função
3. Contexto diluído no LLM — o modelo processa muito código de implementação quando o que importa é a interface

Solução Proposta

Criar dois modos de chunking configuráveis via .iara.json:

Modo full (atual, padrão mantido para compatibilidade)

chunk_content = ast.get_source_segment(self.content, node)

Modo signature (novo — inspirado em code_structure do Th0th)

def _extract_signature(self, node, content: str) -> str:
    """
    Extrai assinatura + docstring + primeiras linhas de uma função/classe.
    Para Python, usa o AST para precisão.
    
    Resultado para uma função de 80 linhas → ~8 linhas:
    
    def review_code(diff: str, api_key: str, config: dict) -> str:
        '''Execute code review trying configured model or fallback.
        
        Args:
            diff: The unified diff string of the PR
            api_key: Provider API key
            config: Loaded .iara.json configuration
        Returns:
            Review text as a string
        '''
        # [... 80 lines of implementation omitted ...]
    """
    lines = content.splitlines()
    
    # Captura: decorator(es) + def/class + docstring
    start = node.lineno - 1
    
    # Encontra o fim da docstring (ou primeira linha de código)
    body_start = self._find_body_start(node)
    
    signature_lines = lines[start:body_start]
    signature_lines.append("    # [...implementation omitted...]")
    
    return "\n".join(signature_lines)

Configuração no .iara.json

{
  "memory": {
    "chunk_mode": "signature"  // "full" | "signature" — default: "signature"
  }
}

Impacto Esperado

Modo	Tamanho médio do chunk	Chunks recuperáveis no mesmo prompt	Precisão da busca vetorial
full (atual)	~80 linhas	3 chunks	Boa
signature (novo)	~8 linhas	15-20 chunks	Melhor (embedding mais focado)

Com signature mode:

• O sistema pode retornar contexto de 5x mais funções no mesmo espaço de tokens
• O LLM entende o "contrato" da função (interface) sem precisar processar a implementação
• Se precisar de detalhes da implementação, o diff já os contém

Critérios de Aceite

• _extract_signature() implementado no CodeVisitor
• chunk_mode: "signature" | "full" configurável via .iara.json
• Default: "signature" (mais eficiente — mudança deliberada de comportamento)
• Metadados do chunk incluem chunk_mode para rastreabilidade
• Compatibilidade: re-indexação necessária ao trocar de modo (detectar e alertar)
• Testes unitários para _extract_signature() com funções com e sem docstring, classes, métodos

Considerações

⚠️ Breaking change no índice: Mudar de full para signature exige re-indexação do codebase. O sistema deve detectar a diferença de modo e alertar o usuário com iara memory index --force.

Referências

• Th0th — code_structure: 70-90% de redução
• iara/memory/indexer.py — CodeVisitor._process_node(), _chunk_python()
• Issue relacionada: [[RAG] Chunking inteligente via AST para JavaScript/TypeScript e C# #45] Chunking inteligente para JS/TS e C# (pode usar o mesmo chunk_mode)

Complexidade Estimada

🟡 Média-Alta — mudança na estratégia central de indexação, requer atenção com compatibilidade de índices existentes e testes abrangentes