docs: automated weekly documentation synchronization

CHANGELOG.md

@@ -58,13 +58,23 @@ Resultado prático: `ctx graph callers show` em projeto Rails/Grails retorna as
 
 - `docs/v0.2-roadmap.md` documenta as 5 fases do plano completo para zerar gap vs CodeGraph (~12k LOC total). Esta release entrega: Fase B parcial (linguagens prioritárias) + Fase D parcial (3 frameworks centrais) + Fase E parcial (Claude Desktop).
 
+#### Astro Starlight Documentation & Landing Page
+
+- Novo site de documentação e landing page de alta performance construído com Astro Starlight sob `site/`.
+- Pipeline de deploy automático para GitHub Pages configurado via GitHub Actions em `.github/workflows/deploy-site.yml`.
+- Forçado uso do registro público do npm no setup do site (workaround para ~/.npmrc corporativo).
+
 ### Changed
 
+- **Rebranding do Projeto:** Renomeado o crate de `context-mode` para `ctx-engine` e referências do repositório GitHub para `context-engine`.
 - `SUPPORTED_EXTS` do scanner expandido para `.rs/.java/.js/.jsx`
 - `GRAPH_EXTS` expandido para `.groovy/.gradle/.js/.jsx/.mjs/.cjs`
 - `ext_to_lang` retorna `rust`/`java`/`javascript` para extensões correspondentes
 - `AgentName` enum tem variante `ClaudeDesktop` (CLI: `--agent claude-desktop`)
 - `installer_for()` despacha para `ClaudeDesktopInstaller`
+- Atualizada infraestrutura de CI/CD para usar runners `ubuntu-22.04` (antes `ubuntu-20.04`).
+- Atualizado `cargo-dist` de `0.28.0` para `0.32.0` no workflow de release.
+- Tolerância adicionada ao commitlint para commits sem tag corporativa e correção de lints Clippy (`collapsible_match`).
 
 ### Performance
 

Cargo.toml

@@ -61,6 +61,13 @@ serial_test = "3"
 [build-dependencies]
 cc = "1.0"
 
+[profile.dev]
+debug = "line-tables-only"
+split-debuginfo = "unpacked"
+
+[profile.dev.package."*"]
+debug = false
+
 [profile.release]
 opt-level = 3
 lto = true
@@ -70,6 +77,7 @@ codegen-units = 1
 [profile.dist]
 inherits = "release"
 lto = "thin"
+strip = true
 
 # Config for 'dist'
 [workspace.metadata.dist]

README.md

@@ -4,12 +4,12 @@
 [![Docs](https://img.shields.io/badge/docs-jaimejunr.github.io%2Fcontext--engine-blue)](https://jaimejunr.github.io/context-engine/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Rust](https://img.shields.io/badge/rust-1.70+-orange.svg)](https://rustup.rs/)
-[![Tests](https://img.shields.io/badge/tests-271%20passing-green.svg)](#desenvolvimento)
+[![Tests](https://img.shields.io/badge/tests-282%20passing-green.svg)](#desenvolvimento)
 [![Release](https://img.shields.io/github/v/release/JaimeJunr/context-engine)](https://github.com/JaimeJunr/context-engine/releases)
 
 > **Maintainers e AI agents:** leia [`CLAUDE.md`](CLAUDE.md) antes de fazer qualquer mudança.
 
-CLI Rust que dá ao seu agente de codificação **mapas curados de repositório**, **busca semântica em docs**, **compressão de output**, **grafo de chamadas em 7 linguagens** e **integração via MCP/hooks** — tudo em um único binário 100% local.
+CLI Rust que dá ao seu agente de codificação **mapas curados de repositório**, **busca semântica em docs**, **compressão de output**, **grafo de chamadas em 8 linguagens** e **integração via MCP/hooks** — tudo em um único binário 100% local.
 
 🌐 **Site oficial:** **<https://jaimejunr.github.io/context-engine/>**
 
@@ -80,8 +80,8 @@ O único CLI que cobre **4 eixos competitivos** em um binário Rust único, 100%
 | 100% local (sem API externa) | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Single binary Rust nativo | ✅ | ✅ | ❌ (TS) | ❌ (TS) | ❌ (TS) |
 | Cobertura de comandos exec | **17 famílias** | 100+ comandos | n/a | parcial | n/a |
-| Linguagens (grafo) | **7** (TS, Py, Rb, Go, Rust, Java, Groovy) | n/a | 19+ | n/a | 5 (AST) |
-| Multi-agente installer | 1 (Claude Code) | 13 | 5 | 15 | parcial |
+| Linguagens (grafo) | **8** (TS, JS, Py, Rb, Go, Rust, Java, Groovy) | n/a | 19+ | n/a | 5 (AST) |
+| Multi-agente installer | 2 (Claude Code, Claude Desktop) | 13 | 5 | 15 | parcial |
 | Stars (referência) | — | 53k | 22k | 15.5k | 25.5k |
 
 **Onde ganhamos clarissimamente:**
@@ -93,9 +93,9 @@ O único CLI que cobre **4 eixos competitivos** em um binário Rust único, 100%
 
 **Onde estamos atrás (assumido, com plano):**
 - Cobertura de comandos do `exec` (17 famílias vs 100+ do RTK) — ver [análise](docs/competitors/rtk.md) e roadmap.
-- Multi-agente installer (só Claude Code hoje; trait `AgentInstaller` pronto para Cursor/Codex/opencode).
-- Linguagens no grafo (7 vs 19+ do CodeGraph — falta C#, PHP, Swift, Kotlin, Scala, Dart, Svelte, Vue, Lua).
-- Dispatch dinâmico / herança / framework routing (URL → handler) — CodeGraph faz, nós não.
+- Multi-agente installer (Claude Code e Claude Desktop; trait `AgentInstaller` pronto para Cursor/Codex/opencode).
+- Linguagens no grafo (8 vs 19+ do CodeGraph — falta C#, PHP, Swift, Kotlin, Scala, Dart, Svelte, Vue, Lua).
+- Dispatch dinâmico / herança — CodeGraph faz, nós não. (Framework-aware routing inicial entregue para NestJS, Rails, Grails).
 - Live file watcher — re-indexamos sob demanda, não automaticamente.
 
 ### Cobertura `ctx exec` (17 famílias)
@@ -122,7 +122,7 @@ O único CLI que cobre **4 eixos competitivos** em um binário Rust único, 100%
 - **`ctx map`** — repo map curado: extrai assinaturas via Tree-Sitter, ranqueia com BM25 + Personalized PageRank, respeita `.gitignore`, output em texto/JSON dentro de orçamento de tokens.
 - **`ctx catalog`** — RAG local: indexa documentação, gera embeddings via endpoint OpenAI-compatible (Ollama, etc), busca por intenção.
 - **`ctx exec`** — proxy universal: aplica filtros de compressão por família (git, cargo, npm, docker, kubectl, aws, gh, gradle, maven, pytest, etc), persiste métricas.
-- **`ctx graph`** — grafo de símbolos resolvido (callers/callees/trace/impact/node) em 7 linguagens. **Resultados ranqueados** por relevância à query e respeitam token budget.
+- **`ctx graph`** — grafo de símbolos resolvido (callers/callees/trace/impact/node) em 8 linguagens. **Resultados ranqueados** por relevância à query e respeitam token budget.
 - **`ctx install --agent claude-code`** — configura hook PreToolUse (auto-rewrite de `git status` → `ctx exec git status`) **e** MCP server (`ctx_exec`, `ctx_search`, `ctx_map`, `ctx_list`) num único comando idempotente.
 - **`ctx mcp serve`** — MCP server stdio expondo 4 tools com schema JSON gerado via `rmcp` + `schemars`.
 - **Arquitetura modular** com 3 camadas (`pipelines/`, `integrations/`, `shared/`) preparada para crescer sem virar mono-arquivo.
@@ -252,7 +252,7 @@ ignore_extra = ["**/fixtures/**"]
 ## Desenvolvimento
 
 ```bash
-cargo test --locked --all-features                       # 214 testes
+cargo test --locked --all-features                       # 282 testes
 cargo clippy --all-targets --all-features -- -D warnings # lint estrito
 cargo fmt -- --check                                     # formatação
 cargo run -- map --help                                  # ajuda dos subcomandos

docs/INDEX.md

@@ -50,6 +50,11 @@ Comprime output de comandos shell mantendo essencial, economizando tokens.
 - **[Configuration](exec/configuration.md)** — Customização
 - **[Metrics](exec/metrics.md)** — Rastreamento de economia
 
+### [`ctx graph`](graph/README.md) — Grafo de Chamadas Semântico
+Mapeamento e navegação de fluxo e símbolos (callers, callees, trace, impact).
+
+- **[Overview](graph/README.md)** — Como funciona, subcomandos e framework routing
+
 ---
 
 ## 🏗️ Arquitetura & Extensão
@@ -103,6 +108,8 @@ docs/
 │   ├── filtering-pipeline.md
 │   ├── configuration.md
 │   └── metrics.md
+├── graph/                         ← Subcomando `ctx graph`
+│   └── README.md
 ├── architecture/                  ← Design interno
 │   ├── README.md
 │   ├── pipelines.md
@@ -127,6 +134,7 @@ docs/
 | **Usar `ctx map`** | [map/README.md](map/README.md) | [map/how-it-works.md](map/how-it-works.md) |
 | **Usar `ctx search`** | [search/README.md](search/README.md) | [search/overview.md](search/overview.md) |
 | **Usar `ctx exec`** | [exec/overview.md](exec/overview.md) | [exec/configuration.md](exec/configuration.md) |
+| **Usar `ctx graph`** | [graph/README.md](graph/README.md) | [graph/README.md](graph/README.md) |
 | **Entender projeto** | [guides/vision.md](guides/vision.md) | [architecture/README.md](architecture/README.md) |
 | **Implementar feature** | [architecture/design-patterns.md](architecture/design-patterns.md) | Código + testes |
 | **Adicionar linguagem** | [architecture/extending.md](architecture/extending.md) | `src/pipelines/map/extractors/<lang>.rs` |

docs/architecture/modules.md

@@ -24,22 +24,31 @@ src/
 │   │   ├── searcher.rs        Busca vetorial
 │   │   └── reranker.rs        Re-ranking contextual
 │   │
-│   └── exec/                  Compressão de output de comandos
-│       ├── mod.rs             API pública (run_proxy)
-│       ├── pipeline.rs        8 estágios de filtragem
-│       ├── registry.rs        Dispatch comando → filtro
-│       ├── filters/           Filtros por família (git, cargo, docker…)
-│       └── metrics.rs         Telemetria de economia
+│   ├── exec/                  Compressão de output de comandos
+│   │   ├── mod.rs             API pública (run_proxy)
+│   │   ├── pipeline.rs        8 estágios de filtragem
+│   │   ├── registry.rs        Dispatch comando → filtro
+│   │   ├── filters/           Filtros por família (git, cargo, docker…)
+│   │   └── metrics.rs         Telemetria de economia
+│   │
+│   └── graph/                 Grafo de símbolos e chamadas semânticas (novo)
+│       ├── mod.rs             Indexação paralela & API pública
+│       ├── extractor.rs       Extração via Tree-Sitter (8 linguagens)
+│       ├── store.rs           Persistência SQLite
+│       ├── query.rs           Navegação por BFS (callers, trace, impact)
+│       ├── types.rs           Símbolos e call sites
+│       └── frameworks/        Framework-aware routing (Rails, Grails, NestJS)
 │
 ├── integrations/              INTERFACES EXTERNAS
-│   ├── agents/                Hooks Claude Code (e futuros Cursor, Codex…)
+│   ├── agents/                Instaladores para agentes (Claude Code/Desktop...)
 │   │   ├── mod.rs             Trait AgentInstaller
 │   │   ├── claude_code.rs     Impl Claude Code (hook + mcpServer)
+│   │   ├── claude_desktop.rs  Impl Claude Desktop (mcpServer)
 │   │   ├── hook_handlers.rs   Handler de `ctx __hook`
 │   │   └── settings_merge.rs  Helpers JSON (idempotente)
 │   └── mcp/                   MCP server expondo pipelines como tools
-│       ├── mod.rs             Entry point: serve() + tool_names()
-│       └── server.rs          CtxServer + 4 tools (ctx_exec, ctx_search, ctx_map, ctx_list)
+│       ├── mod.rs             Entry point: serve()
+│       └── server.rs          CtxServer + 10 tools (exec, search, map, list, graph_index e navigation)
 │
 └── shared/                    UTILITÁRIOS CROSS-CUTTING
     ├── cache.rs               SQLite cache em ~/.cache/context_engine/
@@ -65,9 +74,9 @@ A separação permite, no futuro, virar Cargo workspace (`ctx-shared`, `ctx-pipe
 |---------|-------------|
 | RRF (fusão BM25 + vetorial) | `pipelines/catalog/rrf.rs` |
 | Query expansion | `pipelines/catalog/query_expansion.rs` |
-| Call graph (callers/callees) | `pipelines/map/graph.rs` |
+| Grafo de chamadas (novas linguagens/frameworks) | `pipelines/graph/` |
 | Cursor/Codex/opencode installers | `integrations/agents/<nome>.rs` |
-| MCP server | `integrations/mcp/` ✅ entregue |
+| MCP server | `integrations/mcp/` ✅ entregue (10 tools) |
 | Session continuity | `integrations/session/` |
 | Telemetria | `shared/telemetry.rs` |
 

docs/graph/README.md

@@ -0,0 +1,96 @@
+# 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 (PageRank/BM25)
+```
+
+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 e salvas em um banco de dados SQLite unificado localizado em `~/.cache/context_engine/graph.db`.
+4. **Ranking & BM25**: Para as buscas, as queries textuais são resolvidas usando um algoritmo de relevância híbrido baseado em **BM25** (no nome dos símbolos) combinado com métricas de conectividade do grafo (PageRank e contagem de call sites).
+5. **Token Budget**: Os resultados passam por um algoritmo de busca binária para limitar e ajustar perfeitamente o tamanho do output em número de tokens de acordo com o contexto disponível do LLM.
+
+---
+
+## 🛠️ Subcomandos Disponíveis
+
+### 1. `ctx graph index`
+Indexa (ou re-indexa de forma incremental) os diretórios especificados.
+
+```bash
+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.
+
+```bash
+ctx graph callers handle_request
+```
+
+### 3. `ctx graph callees`
+Encontra todas as chamadas (`callees`) feitas por um símbolo específico.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+ctx graph impact migrate_db
+```
+
+### 6. `ctx graph node`
+Detalha as propriedades e o local exato onde um símbolo está definido no grafo.
+
+```bash
+ctx graph node "route::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` ranqueia os resultados usando a query textual com BM25 + PageRank para garantir que os símbolos mais relevantes para a tarefa do agente apareçam primeiro.
+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:** As buscas respeitam a flag `--max-tokens` do seu agente através de busca binária robusta no output final do grafo.
+4.  **100% Local e Rápido:** Construído em Rust e usando o poder do SQLite e Tree-Sitter, indexa projetos gigantescos em segundos com threads paralelas via `rayon`.

docs/guides/agent-integration.md

@@ -14,12 +14,15 @@ Resultado prático: o agente roda `git status` normalmente; o hook reescreve par
 | Agente | Status | Escopo padrão |
 |--------|--------|---------------|
 | Claude Code | ✅ disponível | `~/.claude/settings.json` |
+| Claude Desktop | ✅ disponível | `~/*.../claude_desktop_config.json` |
 | Cursor | 🚧 próxima entrega | — |
 | Codex CLI | 🚧 próxima entrega | — |
 | opencode | 🚧 próxima entrega | — |
 
 ## Uso
 
+### Claude Code
+
 ```bash
 # Instala no escopo de usuário (~/.claude/settings.json) — afeta todos os projetos
 ctx install --agent claude-code
@@ -34,6 +37,16 @@ ctx uninstall --agent claude-code
 ctx uninstall --agent claude-code --project
 ```
 
+### Claude Desktop
+
+```bash
+# Instala no aplicativo Claude Desktop
+ctx install --agent claude-desktop
+
+# Remove do aplicativo Claude Desktop
+ctx uninstall --agent claude-desktop
+```
+
 Reinicie sessões abertas do agente para o hook entrar em vigor.
 
 ## O que é escrito no `settings.json`
@@ -68,14 +81,20 @@ O campo `_installer: "ctx"` é o **marcador de propriedade**: o `uninstall` remo
 
 ## Tools MCP expostas
 
-Quando o agente cliente conecta via MCP, vê estas 4 tools:
+Quando o agente cliente conecta via MCP, vê estas **10 tools**:
 
 | Tool | Função |
 |---|---|
 | `ctx_exec` | Executa comando shell com filtro de compressão (mesma cobertura do hook PreToolUse) |
 | `ctx_search` | Busca semântica em acervo do catalog (`collection`, `query`, `top_k`) |
 | `ctx_map` | Gera repo map curado (`title`, `dirs`, `max_tokens`…) |
 | `ctx_list` | Lista acervos catalogados disponíveis |
+| `ctx_graph_index` | Indexa diretórios populando o grafo de símbolos |
+| `ctx_callers` | Busca chamadores de um símbolo com relevância e budget de tokens |
+| `ctx_callees` | Busca símbolos chamados a partir de um identificador qualificado |
+| `ctx_trace` | Retorna a cadeia de callers até `depth` níveis |
+| `ctx_impact` | Lista código impactado por mudanças (callers diretos e indiretos) |
+| `ctx_node` | Localiza as definições de um símbolo no grafo |
 
 Schemas de input são gerados automaticamente via `schemars` (validados no cliente antes da chamada).