# PR — lsp-base (LSP MVP)

**Branch:** `pr-08-lsp-mvp`

## Briefing

Queremos um **LSP mínimo funcional** que já permita trabalhar PBS no VSCode com:

* erros aparecendo (diagnostics)
* navegação básica (goto definition)
* visão estrutural (document/workspace symbols)

Regras-chave (MVP):

* `didChange` será **full-text**
* rebuild será **coarse** (recompila o projeto inteiro) sempre que qualquer arquivo muda
* sem incremental analysis ainda
* comentários extensivos com exemplos se necessário e em inglês sempre

Este PR não inclui semantic tokens nem completion (virão nos PRs seguintes).

---

## Alvo (Features)

### LSP endpoints

* ✅ `initialize`
* ✅ `textDocument/didOpen`
* ✅ `textDocument/didChange` (FULL)
* ✅ `textDocument/didClose`
* ✅ `textDocument/documentSymbol`
* ✅ `workspace/symbol`
* ✅ `textDocument/definition`
* ✅ `textDocument/publishDiagnostics`

### Modelo de build

* `AnalysisDb` em memória
* `FileDb` (uri → texto)
* `rebuild()` recompila **workspace inteiro** e produz um snapshot

---

## Design (como deve funcionar)

### 1) AnalysisDb: estado e snapshot

**Objetivo:** separar “estado de arquivos” de “resultado de análise”.

Estruturas recomendadas:

```rust
pub struct AnalysisDb {
  pub file_db: FileDb,
  pub revision: u64,
  pub active_rebuild: Option<RebuildHandle>,
  pub last_good: Option<AnalysisSnapshot>,
}

pub struct AnalysisSnapshot {
  pub diagnostics: Vec<Diagnostic>,
  pub symbols: SymbolIndex,          // index por Project/Module (coarse)
  pub node_to_symbol: NodeToSymbol,  // para definition
  pub def_index: DefIndex,           // opcional se você já tiver
  pub ast: AstArena,                 // opcional (mas útil para nodes)
}
```

> Observação: use os tipos reais do seu compiler. O importante é ter um “snapshot” único que o LSP consulta.

### 2) Fluxo de rebuild

* `didOpen/didChange`:

    * atualizar `file_db` com texto atual
    * incrementar `revision`
    * disparar `request_rebuild()` (coalescing)

* `request_rebuild()`:

    * cancela rebuild anterior se houver
    * agenda um rebuild assíncrono (tokio task)
    * no fim, se não estiver cancelado e se `revision` não mudou, grava `last_good` e publica diagnostics

### 3) Diagnostics

* O compiler já deve produzir diagnostics com `Span { file, start, end }` em bytes.
* Para publicar, converter:

    * `Span` → `lsp_types::Range` via `TextIndex` (já existe do refactor)

Regra:

* Diagnóstico sem `Span` (ou span inválido) deve ser **ignorado** ou degradado para range 0..0.

### 4) Definition

Ao receber `textDocument/definition`:

1. converter `Position` → byte offset (com `TextIndex`)
2. encontrar `NodeId` no ponto
3. resolver `NodeId -> SymbolId` via `node_to_symbol`
4. pegar `Symbol.decl_span`
5. converter `decl_span` → `Location`

> Se `NodeId` não existir ou não resolver símbolo: retornar `None`.

### 5) documentSymbol / workspaceSymbol

* `documentSymbol`: filtrar símbolos cujo `decl_span.file` == arquivo da request.
* `workspaceSymbol`: busca textual simples (contains/case-insensitive) nos nomes de símbolos (coarse) e retorna top N.

---

## Tarefas de implementação (checklist técnico)

### Capabilities em `initialize`

Declarar no server:

* `textDocumentSync: Full`
* `definitionProvider: true`
* `documentSymbolProvider: true`
* `workspaceSymbolProvider: true`
* `diagnosticProvider`: use publishDiagnostics (push)

### didOpen

* upsert texto
* request_rebuild

### didChange (Full)

* receber texto completo do doc
* upsert texto
* request_rebuild

### didClose

* remover do file_db (ou marcar fechado)
* publicar diagnostics vazios para o arquivo fechado

### Conversions

* `uri <-> FileId`: FileDb precisa mapear URI para FileId estável.
* `Span -> Range`: usar `TextIndex` do texto atual do arquivo.
* `Position -> byte`: usar `TextIndex`.

### Node lookup

Você precisa de uma função no snapshot (ou util) tipo:

* `fn node_at(file: FileId, byte: u32) -> Option<NodeId>`

MVP aceitável:

* se você ainda não tiver um índice de nodes por span, pode:

    * usar AST arena e fazer busca linear na árvore (aceitável no coarse MVP)

---

## Test Harness (mínimo, mas real)

### Opção A (preferida): tests com `tower-lsp` client in-process

Criar um teste `tests/lsp_mvp.rs`:

* sobe o backend LSP em memória
* envia:

    * `initialize`
    * `didOpen` com um fixture PBS (2 arquivos)
    * espera `publishDiagnostics` (pode interceptar via `Client` mock)
    * chama `definition` em uma posição de uso e verifica que retorna `Location` do `decl_span`

**Aceite:**

* definition retorna arquivo correto
* range bate com span convertido

### Opção B (mais simples): unit tests nos adaptadores

Se o harness LSP demorar, pelo menos criar:

* `span_to_range_uses_utf16()`
* `position_to_byte_roundtrip()`
* `definition_resolves_to_decl_span()` usando snapshot fake.

---

## Checklist de aceite (obrigatório)

* [ ] `cargo test -q` passa no workspace
* [ ] VSCode: abrir arquivo `.pbs` mostra diagnostics (pelo menos 1 erro sintático)
* [ ] VSCode: `Go to Definition` funciona para símbolo resolvido
* [ ] VSCode: Outline mostra `documentSymbol`
* [ ] Mudanças em um arquivo disparam rebuild e atualizam diagnostics
* [ ] Unicode: diagnostics não ficam “desalinhados” (teste manual com `ação`/emoji)

---

## Fora de escopo (explicitamente)

* semantic tokens
* completion
* references/rename
* hover/signatureHelp
* incremental analysis e cancelation avançada

---

# PR — lsp-hightlight-base (Semantic Tokens — lexer-first)

**Branch:** `pr-12a-lsp-semantic-lexer`

## Briefing

Queremos **highlight no VSCode via LSP**, sem depender de resolver e sem TextMate.

Estratégia:

* Implementar `textDocument/semanticTokens/full`.
* Gerar tokens **lexer-first**: comments/strings/numbers/keywords/identifiers.
* Converter spans (bytes) para LSP positions (UTF-16) usando `TextIndex`.
* comentários extensivos com exemplos se necessário e em inglês sempre

Isso entrega um highlight “bom o suficiente” e muito estável, mesmo com arquivo com erro de parse.

---

## Alvo (Features)

* ✅ `textDocument/semanticTokens/full`
* ✅ `SemanticTokensLegend` consistente
* ✅ tokens derivados do lexer

Opcional (não obrigatório neste PR):

* `semanticTokens/range`
* `semanticTokens/full/delta`

---

## Design

### 1) Legend fixa

Escolher um conjunto pequeno de token types:

* `comment`
* `string`
* `number`
* `keyword`
* `operator` (opcional)
* `variable` (para identifiers genéricos)

> Não inventar muitos tipos agora; fácil expandir depois.

### 2) Fonte de tokens

Implementar uma função no analysis/compiler layer (ou no lsp crate) que, dado:

* `FileId`
* `text: &str`
  retorna `Vec<(Span, TokenType, TokenModifiers)>`.

**Importante:**

* Spans são em bytes.
* Devem ser **não sobrepostos** e preferencialmente em ordem.

### 3) Conversão para formato LSP (deltas)

LSP semantic tokens usa encoding em deltas:

* `deltaLine`, `deltaStartChar`, `length`, `tokenType`, `tokenModifiers`

Algoritmo:

1. Converter `Span.start` e `Span.end` em `(line, utf16_col)`.
2. Calcular `length` em UTF-16 units para o trecho (start..end).
3. Ordenar por `(line, col)`.
4. Emitir deltas.

Regra:

* Se `Span` cruza linhas, **quebrar** em múltiplos tokens por linha (MVP seguro).

### 4) Robustez

* Token inválido (end < start, ou fora do texto) deve ser ignorado.
* Se o arquivo não estiver no `FileDb`, retornar tokens vazios.

---

## Tarefas de implementação

### Server capabilities

No `initialize`, anunciar:

* `semanticTokensProvider` com:

    * `legend`
    * `full: true`
    * `range: false` (por enquanto)

### Handler

Implementar `semantic_tokens_full(params)`:

* pegar `uri`
* buscar texto no `file_db`
* gerar tokens do lexer
* converter com `TextIndex`
* retornar `SemanticTokensResult::Tokens`

### Lexer tokens

Se você já tem lexer com spans:

* mapear tokens para os tipos (keyword/string/comment/number/identifier)
* keywords: pode ser por enum do token ou por tabela

Se o lexer não marca keyword vs ident:

* fallback: parse por string e classifica keywords via `HashSet<&'static str>`.

---

## Testes

### Unit tests (obrigatórios)

1. `semantic_tokens_legend_is_stable()`

* garante que legend não muda sem intenção.

2. `semantic_tokens_are_sorted_and_non_negative()`

* gera tokens em um fixture com 2 linhas
* valida que deltas nunca ficam negativos e que ordem é válida.

3. `semantic_tokens_unicode_length_utf16()`

* texto com `ação🙂`
* valida que `length` corresponde a UTF-16 (emoji conta como 2).

### Teste manual (aceite)

* Abrir `.pbs` no VSCode
* Verificar:

    * strings e comentários coloridos
    * keywords coloridas
    * números coloridos
    * identifiers coloridos (mesmo que genérico)

---

## Checklist de aceite

* [ ] `cargo test -q` passa
* [ ] VSCode: arquivos PBS ficam coloridos via LSP (sem TextMate)
* [ ] Unicode não quebra offsets
* [ ] Arquivo com erro de parse ainda tem highlight (lexer-first)

---

## Fora de escopo

* semantic tokens semântico (type vs fn vs var) — virá em `PR-12b`
* `range`/`delta`
* completion

---

# PR — lsp-completion-base (Completion mínimo)

**Branch:** `pr-11a-lsp-completion-min`

## Briefing

Queremos autocomplete **mínimo mas útil** para conseguir escrever SDK/ECS em PBS sem fricção.

Princípio:

* Não depende de scope facts, nem type facts.
* Usa somente:

    * keywords/builtins
    * símbolos top-level do módulo atual
    * exports/imports visíveis no projeto (coarse)

Isso é suficiente para começar a programar e evoluir o LSP depois.

* comentários extensivos com exemplos se necessário e em inglês sempre

---

## Alvo (Features)

* ✅ `textDocument/completion`
* ✅ `completionItem/resolve` (opcional; pode retornar item já completo)

---

## Design

### 1) Buckets e ordenação

Retornar `CompletionList` com itens nesta prioridade:

1. Keywords (`fn`, `let`, `mutate`, `declare`, `struct`, `storage`, `if`, `else`, `for`, `return`, etc.)
2. Builtins/funções globais (ex.: `alloc`, `box`, `unbox`, `range`, etc. — conforme spec do PBS)
3. Símbolos do módulo atual (top-level)
4. Símbolos “workspace visible” (exports/imports), limitado (ex.: top 200)

**Regra de ranking simples:**

* locals (não teremos) > módulo atual > workspace

### 2) Contexto

Para completion mínimo, só precisamos:

* `uri` do documento
* `position` (para pegar prefixo)

Prefixo:

* converter `Position` -> byte
* extrair texto até o cursor e identificar o “token parcial” (regex simples `[A-Za-z_][A-Za-z0-9_]*$`)

### 3) Fonte dos símbolos

Usar o `AnalysisSnapshot` (produzido na PR-08) para expor:

* `fn symbols_in_file(file: FileId) -> Vec<SymbolId>`
* `fn symbols_in_module(project: ProjectId, module: ModuleId) -> Vec<SymbolId>`
* `fn workspace_symbols() -> impl Iterator<Item = (name, kind, decl_span)>`

MVP aceitável:

* `workspace_symbols()` pode ser um vetor “flatten” pré-calculado no snapshot.

### 4) CompletionItem

Mapeamento para `CompletionItemKind`:

* functions -> `FUNCTION`
* types -> `CLASS` (ou `STRUCT` se quiser)
* modules -> `MODULE`
* variables/constants -> `VARIABLE` / `CONSTANT`

Campos:

* `label`: nome
* `detail`: (opcional) `"fn"/"type"/"module"`
* `sortText`: prefixado para impor bucket (ex.: `"1_"`, `"2_"`)
* `filterText`: label

---

## Tarefas de implementação

### Capabilities

No `initialize`:

* `completionProvider: { resolveProvider: false, triggerCharacters: [".", ":"]? }`

> Para completion mínimo, nem precisa trigger chars. Pode deixar default.

### Handler `completion`

* buscar texto e `TextIndex`
* calcular prefixo
* montar lista de candidatos por bucket
* filtrar por prefixo (case-sensitive ou insensitive; escolha e documente)
* limitar tamanho
* retornar `CompletionResponse::List`

### Builtins/keywords

Criar tabelas estáticas em `prometeu-lsp`:

* `static KEYWORDS: &[&str] = ...`
* `static BUILTINS: &[&str] = ...`

---

## Testes

### Unit tests (obrigatórios)

1. `completion_extracts_prefix()`

* valida regex de prefixo

2. `completion_includes_keywords()`

* chama handler com texto vazio e posição 0
* garante que `fn` aparece

3. `completion_filters_by_prefix()`

* prefixo `"ra"` deve sugerir `range` (se builtin)

4. (se possível) `completion_includes_module_symbols()`

* usando snapshot fake ou fixture compilado pela infra da PR-08

### Teste manual (aceite)

* Abrir arquivo PBS e digitar `ra` -> aparece `range`
* Digitar nome de tipo/fn do SDK -> aparece suggestion

---

## Checklist de aceite

* [ ] `cargo test -q` passa
* [ ] VSCode: autocomplete sugere keywords e builtins
* [ ] VSCode: autocomplete sugere símbolos do módulo atual
* [ ] Não trava com rebuild coarse

---

## Fora de escopo

* locals em scope
* members (`obj.`)
* signatureHelp
* hover