# LSP Roadmap — do “base usable” até “LSP completo”

> Este documento é o mapa incremental pós `lsp-base`, `lsp-hightlight-base`, `lsp-completion-base`.
> A ideia é manter o LSP evoluindo sem rework, enquanto SDK/ECS/Packer avançam em paralelo.

---

## Estado atual (após os 3 PRs base)

### ✅ Já temos

* Diagnostics (publishDiagnostics)
* Definition (goto definition)
* DocumentSymbol / WorkspaceSymbol
* Semantic tokens (lexer-first)
* Completion mínimo (keywords/builtins/top-level/module/workspace)

### ❌ Ainda não temos

* references / rename
* hover / signatureHelp
* completion com locals em scope
* semantic tokens semântico (type vs fn vs var)
* incremental analysis real (por arquivo / cancelation)
* debug map pc→span integrado com traps
* code actions / formatting

---

## Próximos PRs recomendados (ordem sugerida)

## PR-09 — References + Rename (seguro)

### Objetivo

Habilitar `references`, `prepareRename`, `rename` com regras de segurança.

### Pré-requisitos

* `RefIndex` completo (SymbolId -> usos em spans)
* `NodeToSymbol` estável
* `TriviaIndex` (comments/strings) para não renomear spans proibidos

### Regras de segurança

* Não renomear símbolo não-resolvido
* Não renomear em comentário/string
* Renomear deve gerar `WorkspaceEdit` apenas para spans válidos

### Testes

* Fixture com 2 arquivos: rename atualiza todas as refs
* Fixture: rename em comentário não altera nada

---

## PR-10 — Hover + SignatureHelp

### Objetivo

* `hover`: mostrar tipo + docstring (docstring opcional)
* `signatureHelp`: para call nodes

### Pré-requisitos

* Type facts básicos: `NodeId -> TypeId`
* Modelo de assinatura: para functions (params, retorno)

### Testes

* Hover em símbolo mostra tipo
* SignatureHelp em chamada mostra params

---

## PR-11b — Completion com locals em scope

### Objetivo

Autocomplete útil para código real:

* locals/params
* shadowing correto

### Pré-requisitos

* Binder/Scope facts:

    * `Position -> ScopeId`
    * `ScopeId -> bindings (name -> SymbolId/TypeId)`

### Testes

* Dentro de bloco, sugere variável local
* Shadowing: sugere a mais interna

---

## PR-12b — Semantic tokens resolver-backed (semântico)

### Objetivo

Melhorar highlight:

* diferenciar `type` vs `function` vs `variable` vs `parameter` vs `module`

### Pré-requisitos

* `NodeAtPosition` confiável
* `NodeToSymbol` confiável
* `SymbolKind` consistente

### Testes

* Identificador de tipo recebe token `type`
* Função recebe token `function`

---

## PR-13 — Formatting + Code Actions (opcional)

### Objetivo

* `textDocument/formatting` (nem que seja formatter simples/estável)
* code actions básicas:

    * organizar imports
    * criar stub de função/struct

### Pré-requisitos

* AST pretty printer (ou formatter incremental)

---

## PR-14 — Incremental analysis + cancelation (de verdade)

### Objetivo

Sair do rebuild coarse:

* recompilar somente arquivo/módulo afetado
* cancelamento real de builds longos
* snapshots por versão

### Pré-requisitos

* Graph de dependências por módulo
* Cache de parse/resolve por arquivo
* `revision` por doc

### Testes

* Editar arquivo A não recompila projeto inteiro
* Cancel: digitar rápido não aplica resultados velhos

---

## PR-15 — Debug map (pc→span) + integração com traps

### Objetivo

Quando a VM gerar trap/runtime error:

* mapear `pc` para `Span`
* mostrar erro com localização exata

### Pré-requisitos

* SourceMap gerado no backend bytecode
* runtime expõe `pc`/contexto

### Testes

* programa que gera trap aponta para linha/col corretos

---

# Backlog adicional (nice to have)

* `workspace/didChangeWatchedFiles` (reagir a mudanças fora do editor)
* `textDocument/codeLens` (ex.: run test / run main)
* `textDocument/inlayHint`
* `workspace/diagnostic` pull-mode (se quiser)
* semanticTokens `range` e `delta` para performance

---

## Interação com SDK/ECS/Packer

### Com os 3 PRs base, você já consegue:

* escrever SDK/ECS em PBS com feedback imediato
* navegar rapidamente pelo código
* manter arquivos grandes com highlight
* usar completion para nomes de APIs

### Enquanto isso, em paralelo:

* packer pode evoluir (não depende do LSP)
* quando packer estabilizar, podemos adicionar code actions/codelens para “build/pack/run” direto no VSCode

---

## Definição de “LSP completo” (para Prometeu view-ready)

Para chamar de "completo" (na sua visão de produto):

* ✅ diagnostics
* ✅ definition
* ✅ symbols
* ✅ highlight semântico
* ✅ completion com scope + members
* ✅ hover + signatureHelp
* ✅ references + rename
* ✅ incremental + cancel
* ✅ debug map integrado com traps

> A ordem acima é incremental por valor percebido e por dependências.