prometeu-studio/docs/roadmaps/lsp/LSP - roadmap remain.md

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.