# v0.2.0 Roadmap — Zerar gap funcional vs CodeGraph

> Status: **planejamento aprovado, execução não iniciada.**
> Meta: nenhum item da auditoria em [docs/competitors/codegraph.md](competitors/codegraph.md) marcado como 🚧/❌ ao final do release.

## Princípio guia

Manter os 4 diferenciais únicos do `ctx` (ranking BM25/PageRank, token budget binary search, dedup de sites, integração com hooks + MCP + RAG + exec) **enquanto** fechamos cada gap funcional do CodeGraph. Não regredir nada da v0.1.0.

## Auditoria sumarizada

| Gap aberto | Estado v0.1.0 | Meta v0.2.0 |
|---|---|---|
| Linguagens core | 7 (TS, Py, Rb, Go, Rust, Java, Groovy) | 18+ (paridade com CodeGraph) |
| Linguagens markup | — | Svelte, Vue, Liquid |
| FTS5 search no grafo | ❌ BM25 in-memory | ✅ persistente em SQLite |
| File watcher | ❌ manual | ✅ FSEvents/inotify + debounce 2s |
| Framework routing | ❌ | ✅ Django, FastAPI, Flask, Rails, Express, NestJS, Spring, Gin, Axum, ASP.NET, Vapor, React Router, SvelteKit (top 13) |
| Dispatch dinâmico | ❌ | ✅ callbacks + interface→impl heurístico |
| Herança | ❌ | ✅ extends/implements resolvidos |
| Path aliases (tsconfig/monorepo) | 🚧 imports simples | ✅ |
| `ctx graph affected` (test impact) | ❌ | ✅ |
| Tools MCP `_explore`/`_context`/`_files`/`_status` | parcial | ✅ |
| Git hooks integration | ❌ | ✅ post-commit re-index opt-in |
| Installers extras (Cursor, Codex, opencode, Hermes) | só Claude Code/Desktop | +4 agentes |
| TUI polish | clap básico | dialoguer/inquire prompts |

## Fases — sequenciadas por (ROI × risco × dependência)

### Fase A — Foundation (baixo risco, alta alavancagem)

**~900 LOC + testes.** Diferenciais imediatos perceptíveis no benchmark.

| Item | LOC | Crates novos |
|---|---|---|
| FTS5 no SQLite store | 150 | nenhum (`rusqlite` já bundled) |
| File watcher + `ctx graph watch` daemon | 400 | `notify`, `notify-debouncer-full` |
| Tools MCP `ctx_explore`, `ctx_context`, `ctx_files`, `ctx_status_graph` | 200 | nenhum |
| `ctx graph affected <file>` (test impact via transitive callers) | 150 | nenhum |

**Critério de saída:** benchmark mostra que `ctx graph` responde queries em < 50ms mesmo após mudança de arquivo (watcher) + `ctx_explore` retorna multi-symbol source em uma chamada.

### Fase B — Escala de linguagens (médio risco, paralelizável)

**~1.500 LOC + testes.** Cobre 90% dos repos do mercado.

| Item | LOC | Crates novos |
|---|---|---|
| C#, C, C++, PHP, Kotlin, Swift extractors | 900 | `tree-sitter-{c_sharp,c,cpp,php,kotlin,swift}` |
| JS puro (separar de TS) + Scala + Dart | 400 | `tree-sitter-{javascript,scala,dart}` |
| Investigar Luau / Pascal: existe crate ou usa WASM runtime? | (decisão) | `wasmtime` se WASM viável |

**Critério de saída:** `ctx graph index` aceita 13+ linguagens sem regressão de performance.

### Fase C — Resolução semântica (alto risco, alto valor)

**~1.600 LOC + testes.** Aqui o `ctx graph` deixa de ser "navegação por nome" e vira "navegação por tipo".

| Item | LOC | Complex |
|---|---|---|
| Path aliases (tsconfig, monorepo workspaces) | 300 | Média |
| Herança: `extends`/`implements` → callers transitivos | 500 | Média |
| Dispatch dinâmico: callbacks JS, React re-render, interface→impl | 800 | **Alta — precisa RFC interno** |

**Critério de saída:** `ctx graph callers IUser` retorna implementações concretas, não só o nome interface.

### Fase D — Framework routing (alto LOC, paralelizável)

**~2.000 LOC + testes.** Diferencial visível em codebases web.

**Top 13 frameworks (todos do CodeGraph):**

| Framework | Linguagem | Pattern |
|---|---|---|
| Django, Flask, FastAPI | Python | `urlpatterns`, `@app.route`, `@app.get` |
| Express, NestJS | JS/TS | `app.get(...)`, `@Controller`/`@Get` |
| Rails | Ruby | `routes.rb` DSL |
| Spring | Java | `@RequestMapping`, `@GetMapping` |
| Gin, chi, gorilla/mux | Go | `r.GET(...)`, `mux.HandleFunc` |
| Axum, actix-web, Rocket | Rust | `Router::route`, `#[get]` |
| ASP.NET | C# | `[HttpGet]`, `MapGet` |
| React Router, SvelteKit | JS/TS | route config + file-based |

~150 LOC × 13 = 2.000 LOC. Cada um vira `src/pipelines/graph/frameworks/<name>.rs` com fixtures dedicados.

**Critério de saída:** `ctx graph node "/users/:id"` em projeto Rails retorna `UsersController#show`.

### Fase E — Distribuição (paralelizável, baixo risco)

**~1.000 LOC + testes.**

| Item | LOC |
|---|---|
| `ClaudeDesktopInstaller` | ✅ já entregue na [Unreleased] |
| `CursorInstaller` | 150 |
| `CodexInstaller` | 150 |
| `OpenCodeInstaller` | 150 |
| `HermesInstaller` | 150 |
| TUI install (`dialoguer` ou `inquire`) | 400 |

**Critério de saída:** `ctx install --agent <qualquer-dos-5>` funciona + smoke real em cada.

## Não-objetivos da v0.2.0

- Reescrever distribuição (já cobrimos com cargo-dist + crates.io)
- Novos pipelines fora de `graph` (catalog/exec/map ficam intactos)
- Session continuity (gap vs Context Mode, planejado para v0.3.0)

## Métricas de sucesso

Antes de cortar v0.2.0:

1. ✅ Tabela em [docs/competitors/codegraph.md](competitors/codegraph.md) tem 0 entradas marcadas 🚧/❌
2. ✅ Suite de testes mantém 100% passing
3. ✅ `ctx graph index` em repo com 100k LOC roda em < 30s (sem regressão)
4. ✅ Benchmark replicável: 7 codebases × 4 runs cada × ctx vs CodeGraph com claude-code headless mostra paridade ou superioridade
5. ✅ Site (jaimejunr.github.io/context-engine) atualizado com nova tabela comparativa

## Estimativa total

- **~8.000 LOC de implementação** + ~4.000 LOC de testes ≈ **12.000 LOC**
- ~30-50 horas de trabalho focado
- Pode ser dividido em 5-8 commits/PRs por fase

## Risco mais alto

**Dispatch dinâmico (Fase C, item 3)** — CodeGraph usa heurísticas em `callback-synthesizer.ts` que demandam design próprio em Rust. Recomendado escrever um mini-RFC antes de codar.

## Como começar

Cada fase abre uma branch tipo `feat/v0.2-fase-a-foundation`. Fases A, B e E podem rodar em paralelo (não compartilham arquivos). C depende de B (resolver precisa de mais linguagens parsed). D depende de B e C parciais.
