ucn

UCN - Universal Code Navigator

Veja o que o código faz antes de tocá-lo.

Se você trabalha com Agentes de IA, adicione UCN como uma Skill ou ferramenta MCP. Uma única ferramenta dá ao agente respostas compactas e vinculadas ao código-fonte para perguntas sobre chamadores, impacto e testes, com incerteza rotulada em vez de adivinhada.

Visão geral conceitual · Imagem estática

Use a CLI diretamente, instale a skill de agente, ou conecte-se via MCP. Um único mecanismo fornece todos os três:

  Terminal              AI Agents           Agent Skills
       │                    │                    │
      CLI                  MCP                 Skill
       └────────────────────┼────────────────────┘
                            │
                     ┌──────┴──────┐
                     │ UCN Engine  │
                     │  commands   │
                     │ tree-sitter │
                     └─────────────┘

UCN usa árvores sintáticas abstratas (ASTs) do tree-sitter para análise estática de código, sem compilar o projeto ou iniciar um servidor de linguagem. A CLI executa sob demanda e reutiliza um índice incremental; o MCP mantém um processo disponível para consultas repetidas. Nenhuma configuração de projeto é necessária, e o cache fica fora do repositório.

Suporta JavaScript, TypeScript, JSX/TSX, Python, Go, Rust, Java, C, C++, C#, e scripts inline em HTML.

Instalação

npm install -g ucn                    # Node.js 20+

No shell

A partir de um diretório de projeto:

ucn repo
ucn show handleRequest --lines
ucn source handleRequest --raw
ucn impact --staged --lines
ucn check --staged

repo mapeia o projeto. show --lines localiza chamadores, source --raw recupera a implementação, e impact e check inspecionam uma alteração em stage. Quando um nome é ambíguo, find retorna um identificador file:line:name que comandos subsequentes aceitam.

--lines retorna registros path:line:text; --raw retorna código-fonte. Ambos se encaixam nos scripts existentes de um agente sem precisar analisar um relatório legível por humanos.

A busca por texto continua útil para comentários, configuração, strings e código fora das linguagens suportadas. usages fornece o inventário de nomes literais quando a tarefa precisa de cada ocorrência, incluindo aquelas que não são chamadas.

Navegação de código e análise de alterações

show reúne a assinatura, o código-fonte, os chamadores, os chamados e o contexto relacionado de um símbolo. Selecione as seções necessárias ou defina um orçamento de saída para manter a resposta focada. trace segue o grafo de chamadas entre arquivos, descendo para chamados ou subindo por chamadores em direção a pontos de entrada. Relacionamentos não verificados permanecem visíveis, e o relatório da árvore informa onde a exploração parou.

impact conecta um símbolo ou diff do Git aos seus chamadores. tests segue caminhos indexados de chamadas e referências para identificar testes estaticamente vinculados, incluindo links a várias etapas de distância. plan pré-visualiza uma renomeação ou mudança de assinatura com localizações de código-fonte e itens de revisão; ele não edita arquivos. Juntos, esses comandos suportam exploração de código, refatoração e revisão de alterações a partir de um terminal ou de um agente de IA.

O que uma resposta estabelece

Para respostas sobre chamadores, o UCN verifica bindings, imports, tipos de receptor e propriedade para distinguir chamadas à definição selecionada de outros usos do seu nome. Chamadas sem evidência suficiente permanecem visíveis como não verificadas, com um motivo. Apenas um nome de método correspondente não estabelece qual implementação é executada; evidências de receptor e propriedade determinam como o candidato é classificado.

No ripgrep em 82313cf9, o helper file_name selecionado tem quatro locais de chamada confirmados e um candidato não verificado. Esta animação contabiliza todas as 29 linhas correspondentes, junto com relações de import e definições de mesmo nome extraídas da saída do UCN.

Descobertas capturadas · Imagem estática · Dados

A linha ACCOUNT reconcilia as ocorrências de nome observadas: chamadas confirmadas, candidatos não verificados, ocorrências que não são chamadas e correspondências atribuídas a outro alvo. CONTRACT descreve o escopo dessa contabilização. Avisos identificam código-fonte que o índice não conseguiu cobrir. Esses detalhes sobrevivem à truncagem de texto para o orçamento de saída de um agente.

Um resultado vazio, portanto, significa algo específico sobre o código inspecionado. Ele não pode estabelecer que reflexão, código gerado, registro em tempo de execução ou consumidores externos nunca alcançam um símbolo. deadcode fornece candidatos para investigar; a exclusão ainda precisa de corroboração. Uma pré-visualização de refatoração ainda precisa do compilador e dos testes.

Precisão e validação

Os portões de release comparam as respostas do UCN com compiladores independentes e servidores de linguagem em um painel de dez repositórios com codebases de produção fixados. A avaliação local de 6 de setembro de 2026 registrou estes resultados amostrais de chamadores:

| Repositório | Commit fixado | Oracle | Símbolos amostrados | Precisão confirmada | Recall no escopo | |---|---:|---:|---:|---:| | preact-signals | e0ce9fdf | ts-morph | 27 | 100% | 100% | | httpx | b5addb64 | Pyright | 50 | 100% | 100% | | cobra | ad460ea8 | gopls | 50 | 100% | 100% | | viper | 528f7416 | gopls | 50 | 100% | 100% | | ripgrep | 82313cf9 | rust-analyzer | 41 | 100% | 100% | | clap | d3e59a9a | rust-analyzer | 50 | 100% | 100% | | javapoet | b9017a95 | JDT LS | 50 | 100% | 100% | | newtonsoft-json | 4f73e743 | Roslyn | 50 | 100% | 100% | | cjson | c859b25d | clangd | 50 | 100% | 100% | | fmt | e424e3f2 | clangd | 50 | 100% | 100% |

Essa avaliação relatou zero arestas oracle no escopo ausentes tanto em respostas de chamadores quanto de chamados, e 8.000 comparações entre comandos com zero divergências. A auditoria padrão de código morto encontrou zero resultados falsos-positivos de código morto entre 13 afirmações pontuadas; 13 afirmações adicionais não puderam ser fixadas pelo oracle e não foram pontuadas. Todos os dez repositórios passaram nos orçamentos de desempenho, com p95 de consulta em estado estável de 4,5 a 76,2 ms. Esses tempos excluem inicialização de processo e indexação; builds a frio e carregamento de cache são medidos separadamente.

As amostras são determinísticas e estratificadas por atividade de referência. Precisão confirmada se aplica a afirmações pontuadas; recall conta arestas oracle no escopo encontradas na faixa confirmada ou não verificada. Candidatos não verificados, abstenções do oracle e descobertas não pontuadas permanecem separados. Essas medições não estabelecem conhecimento completo de tempo de execução ou desempenho idêntico em todas as máquinas.

O painel agendado cobre 24 repositórios fixados: os dez acima mais zod, express, hono, zustand, fastify, rich, click, attrs, grpc-go, chi, cursive, itertools, gson e jsoup. Um braço rotativo de repositórios novos verifica codebases fora desse painel fixado.

O manifesto do repositório registra os commits completos. O workflow Publish controla os releases, e o workflow Eval executa as verificações em agendamento e sob demanda. Suas páginas de execução fornecem resultados de CI e artefatos de avaliação. Reproduza as verificações localmente com as dependências do oracle instaladas:

npm run verify
npm run trust:gate

Comandos

deps --cycles agrupa dependências circulares e distingue imports ansiosos de arestas adiadas ou somente de tipo. Limites de enumeração são divulgados. repo relata cobertura de código-fonte, bem como estrutura do projeto; seu ranking HOT rápido tem um orçamento de refinamento divulgado, e repo --sections=stats --hot solicita o ranking exato.

endpoints --bridge corresponde rotas de servidor e solicitações de cliente reconhecidas por seus extratores de framework. plan lida com relacionamentos de código como imports, overrides e métodos de interface ou trait quando a propriedade é resolvida; relacionamentos ambíguos permanecem como itens de revisão.

Execute ucn --help para flags, ou use a referência de comandos.

Saída do shell

Registros e código vão para stdout; contabilização e notas vão para stderr. Registros não verificados carregam um motivo separado por tabulação. Uma listagem vazia sai com 1, um erro sai com 2, e uma listagem bem-sucedida sai com 0. --lines suporta find, show, usages, search e impact; show --lines lista chamadores por padrão. Use --json quando o script precisar de campos estruturados ou um resultado em árvore.

Listagens não têm limite padrão de linhas. Limites explícitos divulgam o que omitem, e um orçamento de caracteres do modo shell falha antes de escrever saída parcial. source --raw extrai funções e classes completas, a menos que um limite explícito de linhas seja solicitado; qualquer truncagem resultante é relatada em stderr.

Erros comuns de comandos em modo texto também saem com 2. JSON mantém saída 0 para resultados vazios bem-sucedidos e saída 1 para erros de comando (meta.ok: false mais error). check sem alvo sai com 1 quando TRUST é BLOCKED, 0 para outras verificações concluídas, e 2 se não puder ser executado.

Fora de --lines, find, texto search, deadcode, api e repo --sections=files têm como padrão um máximo de 500 resultados. Use --limit=N para solicitar mais; usages lista todos os locais, a menos que um limite seja dado. Consultas amplas de find selecionam candidatos por totais aproximados de uso antes de calcular a atividade de chamadores fixada por definição, e divulgam essa seleção quando limitada.

Arquivos chamados *.min.js, *.bundle.js e *.map são relatados como fontes ignoradas e tornam a completude parcial. --include-bundled (MCP include_bundled=true) indexa os bundles de JavaScript respeitando exclusões do usuário; ele ignora o cache compartilhado. Source maps permanecem divulgados, mas não indexados.

Configuração de IA

Uma ferramenta, 18 comandos, respostas compactas vinculadas ao código-fonte que mantêm seus metadados de confiança mesmo quando truncadas.

MCP

# Claude Code
claude mcp add ucn -- npx -y ucn --mcp

# OpenAI Codex CLI
codex mcp add ucn -- npx -y ucn --mcp

# VS Code Copilot
code --add-mcp '{"name":"ucn","command":"npx","args":["-y","ucn","--mcp"]}'

{
  "mcpServers": {
    "ucn": {
      "command": "npx",
      "args": ["-y", "ucn", "--mcp"]
    }
  }
}

{
  "servers": {
    "ucn": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ucn", "--mcp"]
    }
  }
}

Skill de Agente (sem necessidade de servidor)

macOS / Linux:

# Claude Code
mkdir -p ~/.claude/skills
cp -r "$(npm root -g)/ucn/.claude/skills/ucn" ~/.claude/skills/

# OpenAI Codex CLI
mkdir -p ~/.agents/skills
cp -r "$(npm root -g)/ucn/.claude/skills/ucn" ~/.agents/skills/

Windows PowerShell:

$npmRoot = npm root -g
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills"
Copy-Item -Recurse "$npmRoot\ucn\.claude\skills\ucn" "$env:USERPROFILE\.claude\skills\"

New-Item -ItemType Directory -Force "$env:USERPROFILE\.agents\skills"
Copy-Item -Recurse "$npmRoot\ucn\.claude\skills\ucn" "$env:USERPROFILE\.agents\skills\"

A skill ensina um agente a se orientar, fixar símbolos, escolher o menor comando útil, interpretar os níveis de evidência e se recuperar de respostas incompletas. É orientação sobre o mesmo mecanismo, não uma segunda implementação.

Escopo

O UCN analisa código-fonte indexado em um projeto. Ele não executa o programa nem indexa dependências instaladas, como node_modules e site-packages. repo --sections=health --deep relata cobertura de código-fonte e limites conhecidos de análise.

C e C++ podem usar compile_commands.json para caminhos de include e contexto de cabeçalho, mas o UCN não executa o pré-processador nem reproduz a visão específica de build de um compilador. Geradores de código-fonte C# e assemblies externos também estão fora do índice. HTML tem cobertura de regressão, mas sem oracle de compilador/LSP no repositório.

A CLI, o MCP e a skill compartilham as mesmas regras de resolução e evidência. Mudar o transporte não muda o que o mecanismo sabe sobre o código.

MIT