ADR-0021: Indexador Sintático e AST Local com Glance

Status Aprovado

Contexto Para que um agente de Inteligência Artificial seja produtivo e preciso no desenvolvimento de código, ele precisa navegar de forma eficiente e estruturada pela base de código do workspace. Abordagens ingênuas baseadas puramente em busca textual simples (como grep bruto) sofrem com falsos positivos, poluição do contexto do modelo e falta de consciência estrutural (por exemplo, incapacidade de diferenciar a definição de uma função de suas chamadas). Por outro lado, o uso exclusivo de buscas semânticas vetoriais em blocos contínuos de texto (text chunking) perde o alinhamento sintático preciso e fragmenta assinaturas de funções ou tipos complexos.

Na base de código em Gleam, as linguagens compilam estaticamente, o que fornece uma excelente oportunidade para usar a estrutura AST (Abstract Syntax Tree) do código-fonte para decompor arquivos de código de forma determinística e enriquecê-los com metadados estruturais.

Decisão Decidimos implementar um indexador sintático e AST local baseado na biblioteca glance (uma biblioteca nativa do Gleam para parsing e análise estática de arquivos .gleam).

A indexação sintática local operará de acordo com o seguinte pipeline lógico: 1. *Análise Estática de Módulo:* O arquivo de código .gleam é lido localmente e passado para o analisador estático do glance. 2. *Mapeamento Estruturado de Símbolos:* O parser decompõe o módulo em seus elementos sintáticos nativos: - **Funções (functions):** Mapeando nome da função, escopo de visibilidade (publicity) e extraindo o bloco exato do corpo da função através de fatiamento de string de forma limpa. - **Imports (imports):** Capturando o nome do módulo importado, alias e tipos ou valores não qualificados importados. - **Constantes (constants):** Identificando constantes globais expostas no módulo. - **Tipos Customizados (custom_types):** Extraindo tipos algébricos (ADTs) com suas respectivas variantes e modificadores de opacidade. - **Aliases de Tipo (type_aliases):** Mapeando aliases de tipos e seus parâmetros. 3. *Fallback Resiliente:* Caso o arquivo .gleam contenha erros de sintaxe ou esteja em um estado transiente inválido de compilação (retornando erro no Glance), o indexador realiza um fallback automático para indexação textual chunked genérica, impedindo a quebra do processo de RAG local. 4. *Vetorização Semântica Isolada:* Cada elemento sintático extraído com sucesso (ex: cada função individual) é encapsulado com seu contexto estrutural e enviado para o worker de vetorização local de forma síncrona. 5. *Gravação no Banco de Grafos:* As representações e vetores são persistidos no modelo de banco de dados gráfico e vetorial local.

Consequências

Positivas - *Acurácia Cirúrgica:* O agente de IA pode localizar o corpo exato de uma função, sem poluição de arquivos adjacentes e sem sofrer com cortes indesejados de chunking. - *Navegação de Dependências:* Facilita a análise de acoplamento e imports no sistema, auxiliando na autodescoberta do ecossistema do monorepo. - *Resiliência a Código Quebrado:* O mecanismo de fallback garante que o sistema de busca continue funcionando mesmo que o usuário ou o agente deixem um arquivo temporariamente sem compilar. - *Estruturação Cross-Platform Nativa:* O processamento ocorre 100% no espaço de usuário do Gleam, sem depender de ferramentas complexas externas do sistema operacional (como Clang ou ferramentas nativas do compilador Rust).

Negativas - *Limitação de Escopo no Fallback:* Durante o estado de fallback de código quebrado, a perda temporária de símbolos AST reduz a precisão da navegação de dependências naquele arquivo específico até que a sintaxe seja corrigida.