Skip to content

README.md

Latest commit

 

History

History
97 lines (67 loc) · 4.96 KB

README.md

File metadata and controls

97 lines (67 loc) · 4.96 KB

Subcomando ctx graph — Grafo de Chamadas Semântico

O subcomando ctx graph oferece ferramentas para análise estática e navegação estrutural do fluxo do código. Ele constrói um grafo de símbolos, chamadas e imports a partir das árvores de sintaxe das linguagens suportadas e armazena os dados em um banco de dados SQLite local.

Diferente do grep tradicional, o ctx graph entende a semântica do código, permitindo responder a perguntas como "quem chama este método?", "o que esta função invoca?", ou "quais rotas HTTP batem neste handler?".

🚀 Como funciona

O pipeline do ctx graph é dividido em cinco etapas fundamentais:

[Código Fonte] ──> Extractor (Tree-Sitter) ──> Framework Router ──> SQLite Store ──> Query & Ranking ──> Token Budget
  1. Scanner & Extractor: O scanner descobre os arquivos no projeto (respeitando as regras de .gitignore). Cada arquivo é analisado usando Tree-Sitter para extrair declarações de símbolos (classes, métodos, funções, etc.), chamadas (call sites), e imports de módulos.
  2. Framework Routing: Detecta definições de rotas HTTP para frameworks conhecidos e injeta símbolos sintéticos do tipo route::METODO /path vinculados às suas respectivas funções handler.
  3. Persistência: As informações extraídas são limpas de forma idempotente por arquivo (clear_file + insert) e salvas em SQLite em ~/.cache/context_engine/graph.db. Não há file watcher — re-indexe com ctx graph index após mudanças.
  4. Ranking: Resultados de callers/callees/trace são ordenados por score heurístico (src/pipelines/graph/query.rs::score_node): boost se termos da --query aparecem no nome/qualified, log₂ do número de call sites (centralidade), e peso leve por kind (function/method > struct > variable). Não usa BM25 nem PageRank do pipeline map.
  5. Token Budget: Com --max-tokens, os nós já ranqueados são incluídos em ordem até estourar o limite (estimativa 1 token ≈ 4 chars) — corte linear, não binary search.

🛠️ Subcomandos Disponíveis

1. ctx graph index

Indexa os diretórios especificados (re-indexação idempotente por arquivo; varre todos os arquivos elegíveis a cada execução).

ctx graph index --dirs src
  • Extensões Suportadas (8 linguagens): .rs, .go, .java, .ts, .tsx, .js, .jsx, .mjs, .cjs, .py, .rb, .rake, .groovy, .gradle.

2. ctx graph callers

Encontra todos os chamadores (callers) diretos de um símbolo específico.

ctx graph callers handle_request

3. ctx graph callees

Encontra todas as chamadas (callees) feitas por um símbolo específico.

ctx graph callees execute_pipeline

4. ctx graph trace

Mostra a cadeia e fluxo completo de chamadas ligadas a um símbolo até uma determinada profundidade.

ctx graph trace handle_request --depth 3

5. ctx graph impact

Realiza uma análise de impacto transitiva. Retorna os chamadores indiretos e tudo o que pode ser impactado pela alteração do símbolo fornecido.

ctx graph impact migrate_db

6. ctx graph node

Detalha as propriedades e o local exato onde um símbolo está definido no grafo.

# Busca por nome do símbolo (ex.: rota sintética ou handler)
ctx graph node "GET /users/:id"

🌐 Framework-Aware Routing

Uma das funcionalidades mais poderosas do ctx graph é o suporte nativo a rotas de frameworks. Ele detecta os caminhos declarados de URLs HTTP e injeta-os no grafo conectando o endpoint sintético à action/função controladora real.

Frameworks Cobertos:

  • Ruby on Rails (config/routes.rb):
    • Mapeia chamadas do DSL como resources :users, resource, get '/login', to: 'session#new', além de namespaces.
    • Conecta automaticamente route::GET /users/:id à action UsersController#show.
  • Grails (UrlMappings.groovy):
    • Mapeia blocos "/path"(controller: 'x', action: 'y') e recursos dinâmicos.
    • Normaliza parâmetros de variáveis (ex: $id → :id).
  • NestJS (Classes *.ts):
    • Analisa os decorators @Controller('prefix') e os decorators de verbo @Get(':id'), @Post(), @Patch(), etc.
    • Injeta a rota mapeando o handler qualificado como ClassName::method.

💎 Diferenciais Exclusivos vs CodeGraph e RTK

  1. Resultados Ranqueados: O CodeGraph retorna listas cruas de callers/callees. O ctx graph ordena por relevância heurística à --query (termos no nome + popularidade por sites + kind).
  2. Deduplicação Inteligente de Call Sites: Se um método é chamado 10 vezes pelo mesmo chamador, o ctx graph agrupa os call sites em uma única entrada reduzida, economizando tokens preciosos.
  3. Token Budget Integration: --max-tokens corta o output nos símbolos top-ranked já ordenados (corte linear).
  4. 100% Local e Rápido: Construído em Rust com SQLite e Tree-Sitter; indexação paralela via rayon.