integrated 14 into specs
This commit is contained in:
@@ -0,0 +1,537 @@
|
||||
# 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
|
||||
@@ -0,0 +1,219 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,564 @@
|
||||
# Prometeu Packer (prometeu-packer) — Specification (Draft)
|
||||
|
||||
> **Status:** Draft / Community-facing
|
||||
>
|
||||
> This document specifies the **Prometeu Packer**, the tooling responsible for **asset management** and producing two build artifacts:
|
||||
>
|
||||
> * `build/assets.pa` — the ROM payload containing packed asset bytes
|
||||
> * `build/asset_table.json` — a machine-readable descriptor of the packed assets
|
||||
>
|
||||
> The Packer is deliberately **agnostic of cartridge building**. A separate **Cartridge Builder** (outside the Packer) consumes `build/asset_table.json` to generate the final `cartridge/manifest.json`, copy `assets.pa` to the cartridge directory, and zip the cartridge into a distributable format.
|
||||
|
||||
---
|
||||
|
||||
## 1. Goals and Non-Goals
|
||||
|
||||
### 1.1 Goals
|
||||
|
||||
1. **Be the guardian of sanity** in a constantly mutating `assets/` workspace.
|
||||
|
||||
* Users may be disorganized.
|
||||
* The directory may contain WIP, junk, unused files, duplicates, outdated exports.
|
||||
* The Packer must help users identify and fix mistakes.
|
||||
|
||||
2. Provide a robust, deterministic, **tooling-grade** asset pipeline.
|
||||
|
||||
* Stable asset identity.
|
||||
* Deterministic packing order.
|
||||
* Reproducible output bytes.
|
||||
|
||||
3. Support both **raw (direct) assets** and **virtual assets**.
|
||||
|
||||
* Raw assets: the payload in ROM is exactly the source bytes.
|
||||
* Virtual assets: the payload is derived from multiple inputs via a build pipeline (e.g., PNG + palettes → `TILES` payload).
|
||||
|
||||
4. Produce an output descriptor (`build/asset_table.json`) suitable for:
|
||||
|
||||
* a Cartridge Builder to generate the runtime manifest
|
||||
* CI checks
|
||||
* a future IDE / GUI tooling
|
||||
|
||||
5. Provide an extensive **diagnostics chain** (doctor) with structured error codes and suggested fixes.
|
||||
|
||||
### 1.2 Non-Goals
|
||||
|
||||
* The Packer **does not**:
|
||||
|
||||
* generate `cartridge/manifest.json`
|
||||
* decide preload slots
|
||||
* copy files into `cartridge/`
|
||||
* compile PBS bytecode
|
||||
* zip cartridges
|
||||
|
||||
These responsibilities belong to a separate **Cartridge Builder**.
|
||||
|
||||
---
|
||||
|
||||
## 2. Repository / Project Layout (Golden Pipeline)
|
||||
|
||||
The Prometeu project uses the following canonical structure:
|
||||
|
||||
* `src/` — PBS scripts
|
||||
* `assets/` — mutable asset workspace (WIP allowed)
|
||||
* `build/` — generated artifacts and caches
|
||||
* `cartridge/` — final cartridge directory (produced by Cartridge Builder)
|
||||
* `prometeu.json` — project description (dependencies, version, etc.)
|
||||
* `sdk/` — SDK/tooling and libraries
|
||||
|
||||
The Packer owns the asset workspace metadata under:
|
||||
|
||||
* `assets/.prometeu/` — Packer control directory (registry, cache, quarantine)
|
||||
|
||||
---
|
||||
|
||||
## 3. Crate Topology
|
||||
|
||||
### 3.1 Crates
|
||||
|
||||
* **`prometeu-packer`**
|
||||
|
||||
* **lib**: `prometeu_packer_core`
|
||||
* **bin**: `prometeu-packer`
|
||||
|
||||
* a thin CLI wrapper delegating to `prometeu_packer_core::run()`
|
||||
|
||||
* **`prometeu` dispatcher**
|
||||
|
||||
* provides a wrapper command **`prometeup`** (or integrated subcommand)
|
||||
* delegates to `prometeu-packer` for packer operations
|
||||
|
||||
### 3.2 Design Principle
|
||||
|
||||
Treat the Packer like the compiler: core library + CLI wrapper.
|
||||
|
||||
* The core library enables future integrations (IDE, GUI, watch mode) without shelling out.
|
||||
* CLI is a stable interface for users and CI.
|
||||
|
||||
---
|
||||
|
||||
## 4. Mental Model: A “Git-like” Asset Workspace
|
||||
|
||||
The Packer treats `assets/` like a **dirty working tree**.
|
||||
|
||||
* `assets/` can contain *anything*.
|
||||
* Only the assets registered in the Packer registry are considered part of the build.
|
||||
|
||||
This is analogous to Git:
|
||||
|
||||
* working tree (chaos) vs index (truth)
|
||||
|
||||
The **source of truth** for “what counts” is the registry:
|
||||
|
||||
* `assets/.prometeu/index.json`
|
||||
|
||||
---
|
||||
|
||||
## 5. Core Concepts
|
||||
|
||||
### 5.1 Managed Asset
|
||||
|
||||
A **managed asset** is an entry in `assets/.prometeu/index.json` pointing to an **asset root directory** that contains an anchor file:
|
||||
|
||||
* `asset.json` (the asset specification)
|
||||
|
||||
Everything else is free-form.
|
||||
|
||||
### 5.2 Asset Identity
|
||||
|
||||
Each asset has stable identity:
|
||||
|
||||
* `asset_id: u32` — stable within the project (used by runtime/tooling)
|
||||
* `asset_uuid: string` — globally unique stable identifier (useful for IDE and future migrations)
|
||||
|
||||
Names and paths may change, but identity remains.
|
||||
|
||||
### 5.3 Asset Types (Bank Targets)
|
||||
|
||||
Assets ultimately target a **bank type** in the runtime:
|
||||
|
||||
* `TILES`
|
||||
* `SOUNDS`
|
||||
* (future) `SPRITESHEET`, `MAP`, `FONT`, `RAW_BLOB`, etc.
|
||||
|
||||
The Packer does **not** define bank memory semantics. It defines the *ROM payload* and its metadata.
|
||||
|
||||
### 5.4 Raw vs Virtual Assets
|
||||
|
||||
* **Raw assets**: ROM payload equals the source bytes.
|
||||
* **Virtual assets**: ROM payload is derived from input(s) via deterministic build steps.
|
||||
|
||||
Examples:
|
||||
|
||||
* PNG + palette files → `TILES` payload (indexed pixels + packed palettes)
|
||||
* WAV → PCM16LE payload
|
||||
* Multiple PNGs → atlas spritesheet
|
||||
|
||||
---
|
||||
|
||||
## 6. Directory Structure and Control Files
|
||||
|
||||
### 6.1 Workspace
|
||||
|
||||
`assets/` is a mutable workspace:
|
||||
|
||||
* users may create nested organization trees
|
||||
* junk files are allowed
|
||||
|
||||
### 6.2 Control Directory
|
||||
|
||||
The Packer stores its truth + tools state in:
|
||||
|
||||
```
|
||||
assets/
|
||||
.prometeu/
|
||||
index.json
|
||||
cache/
|
||||
fingerprints.json
|
||||
build-cache.json
|
||||
quarantine/
|
||||
...
|
||||
```
|
||||
|
||||
* `index.json` — registry of managed assets
|
||||
* `cache/` — fingerprints and incremental build cache
|
||||
* `quarantine/` — optional area to move detected junk (only by explicit user action)
|
||||
|
||||
---
|
||||
|
||||
## 7. Asset Specification: `asset.json`
|
||||
|
||||
`asset.json` describes:
|
||||
|
||||
1. **the output ROM payload** expected by runtime
|
||||
2. **the build pipeline** (for virtual assets)
|
||||
3. **metadata** needed by runtime/builder
|
||||
|
||||
This spec is modular: **each asset format** (e.g. `TILES/indexed_v1`) has its own dedicated specification document.
|
||||
|
||||
### 7.1 Common Fields (All Assets)
|
||||
|
||||
* `schema_version`
|
||||
* `name`
|
||||
* `type` (bank type)
|
||||
* `codec` (e.g. `RAW`; future: compression)
|
||||
* `inputs` (for virtual assets)
|
||||
* `output` (format + required metadata)
|
||||
* `build` (optional pipeline configuration)
|
||||
|
||||
### 7.2 Virtual Asset Pipeline Declaration
|
||||
|
||||
Virtual assets must be declared in a way that is:
|
||||
|
||||
* deterministic
|
||||
* fully materialized (no silent inference)
|
||||
* explicit about defaults (defaults may exist, but must be written into `asset.json` or build outputs)
|
||||
|
||||
---
|
||||
|
||||
## 8. Build Artifacts Produced by the Packer
|
||||
|
||||
### 8.1 `build/assets.pa`
|
||||
|
||||
**`assets.pa`** is the ROM asset payload used by the runtime.
|
||||
|
||||
**Definition:** a contiguous binary blob where each managed asset contributes a payload region.
|
||||
|
||||
#### Key Properties
|
||||
|
||||
* Deterministic asset order (by `asset_id`)
|
||||
* Offsets are recorded in `build/asset_table.json`
|
||||
* Alignment rules (configurable by packer, default: no alignment unless required by a format)
|
||||
|
||||
**Note:** `assets.pa` is intentionally simple.
|
||||
|
||||
* No internal header is required.
|
||||
* The authoritative structure comes from the descriptor (`asset_table.json`).
|
||||
|
||||
Future versions may introduce chunk tables, but v1 keeps ROM simple.
|
||||
|
||||
### 8.2 `build/asset_table.json`
|
||||
|
||||
**`asset_table.json`** is the canonical descriptor output of the Packer.
|
||||
|
||||
It contains:
|
||||
|
||||
* `assets_pa` file info (size, hash)
|
||||
* `asset_table[]` entries describing each payload slice
|
||||
* optional diagnostics/warnings
|
||||
|
||||
#### Asset Table Entry
|
||||
|
||||
An entry describes a ROM slice and its runtime meaning:
|
||||
|
||||
* `asset_id` — stable u32
|
||||
* `asset_uuid` — stable UUID string
|
||||
* `asset_name` — stable user-facing name
|
||||
* `bank_type` — e.g. `TILES`, `SOUNDS`
|
||||
* `offset` — byte offset in `assets.pa`
|
||||
* `size` — bytes stored in ROM
|
||||
* `decoded_size` — bytes after decode (equal to `size` when `codec=RAW`)
|
||||
* `codec` — `RAW` (future: compression)
|
||||
* `metadata` — format-specific metadata needed by runtime/builder
|
||||
|
||||
Additional tooling fields:
|
||||
|
||||
* `source_root` — path to asset dir
|
||||
* `inputs` — resolved input paths
|
||||
* `source_hashes` — stable fingerprints of inputs
|
||||
|
||||
`asset_table.json` is machine-readable and designed for:
|
||||
|
||||
* cartridge builder consumption
|
||||
* IDE visualization
|
||||
* debugging
|
||||
|
||||
---
|
||||
|
||||
## 9. Determinism Rules
|
||||
|
||||
1. Asset packing order MUST be deterministic.
|
||||
|
||||
* Default: increasing `asset_id`
|
||||
|
||||
2. All derived outputs MUST be deterministic.
|
||||
|
||||
* No random seeds unless explicitly declared
|
||||
* Any seed must be written to output metadata
|
||||
|
||||
3. Default values MUST be materialized.
|
||||
|
||||
* If the packer infers something, it must be written into `asset.json` (via `--fix`) or recorded in build outputs.
|
||||
|
||||
---
|
||||
|
||||
## 10. Diagnostics and the “Sanity Guardian” Chain
|
||||
|
||||
The Packer provides structured diagnostics:
|
||||
|
||||
* `code` — stable diagnostic code
|
||||
* `severity` — `error | warning | info`
|
||||
* `path` — affected file
|
||||
* `message` — human friendly
|
||||
* `help` — extended context
|
||||
* `fixes[]` — suggested automated or manual fixes
|
||||
|
||||
### 10.1 Diagnostic Classes
|
||||
|
||||
1. **Registered Errors** (break build)
|
||||
|
||||
* registry entry missing anchor file
|
||||
* `asset.json` invalid
|
||||
* missing inputs
|
||||
* format/metadata mismatch
|
||||
|
||||
2. **Workspace Warnings** (does not break build)
|
||||
|
||||
* orphaned `asset.json` (not registered)
|
||||
* unused large files
|
||||
* duplicate inputs by hash
|
||||
|
||||
3. **Policy Hints** (optional)
|
||||
|
||||
* naming conventions
|
||||
* missing preview
|
||||
|
||||
### 10.2 `doctor` Modes
|
||||
|
||||
* `doctor` (default) — validate registry only (fast)
|
||||
* `doctor --workspace` — deep scan workspace (slow)
|
||||
|
||||
---
|
||||
|
||||
## 11. Incremental Build, Cache, and Fingerprints
|
||||
|
||||
The Packer maintains fingerprints of inputs:
|
||||
|
||||
* size
|
||||
* mtime
|
||||
* strong hash (sha256)
|
||||
|
||||
Stored in:
|
||||
|
||||
* `assets/.prometeu/cache/fingerprints.json`
|
||||
|
||||
This enables:
|
||||
|
||||
* detecting changes
|
||||
* rebuild only what changed
|
||||
* producing stable reports
|
||||
|
||||
The cache must never compromise determinism.
|
||||
|
||||
---
|
||||
|
||||
## 12. Quarantine and Garbage Collection
|
||||
|
||||
### 12.1 Quarantine
|
||||
|
||||
The Packer can optionally move suspected junk to:
|
||||
|
||||
* `assets/.prometeu/quarantine/`
|
||||
|
||||
Rules:
|
||||
|
||||
* Quarantine is **never automatic** without user consent.
|
||||
* Packer must explain exactly what will be moved.
|
||||
|
||||
### 12.2 Garbage Collection (`gc`)
|
||||
|
||||
The Packer can report unused files:
|
||||
|
||||
* files not referenced by any registered asset
|
||||
* orphaned asset dirs
|
||||
|
||||
Actions:
|
||||
|
||||
* list candidates
|
||||
* optionally move to quarantine
|
||||
* never delete without explicit user request
|
||||
|
||||
---
|
||||
|
||||
## 13. CLI Commands (Comprehensive)
|
||||
|
||||
> The CLI is a stable interface; all commands are implemented by calling `prometeu_packer_core`.
|
||||
|
||||
### 13.1 `prometeu packer init`
|
||||
|
||||
Creates the control directory and initial registry:
|
||||
|
||||
* creates `assets/.prometeu/index.json`
|
||||
* creates caches directory
|
||||
|
||||
### 13.2 `prometeu packer add <path> [--name <name>] [--type <TILES|SOUNDS|...>]`
|
||||
|
||||
Registers a new managed asset.
|
||||
|
||||
* does not require moving files
|
||||
* can create an asset root directory if desired
|
||||
* generates `asset.json` with explicit defaults
|
||||
* allocates `asset_id` and `asset_uuid`
|
||||
|
||||
Variants:
|
||||
|
||||
* `add --dir` creates a dedicated asset root dir
|
||||
* `add --in-place` anchors next to the file
|
||||
|
||||
### 13.3 `prometeu packer adopt`
|
||||
|
||||
Scans workspace for unregistered `asset.json` anchors and offers to register them.
|
||||
|
||||
* default: dry-run list
|
||||
* `--apply` registers them
|
||||
|
||||
### 13.4 `prometeu packer forget <name|id|uuid>`
|
||||
|
||||
Removes an asset from the registry without deleting files.
|
||||
|
||||
Useful for WIP and cleanup.
|
||||
|
||||
### 13.5 `prometeu packer rm <name|id|uuid> [--delete]`
|
||||
|
||||
Removes the asset from the registry.
|
||||
|
||||
* default: no deletion
|
||||
* `--delete` can remove the asset root dir (dangerous; must confirm in UI tooling, or require a force flag in CLI)
|
||||
|
||||
### 13.6 `prometeu packer list`
|
||||
|
||||
Lists managed assets:
|
||||
|
||||
* id, uuid, name
|
||||
* type
|
||||
* status (ok/error)
|
||||
|
||||
### 13.7 `prometeu packer show <name|id|uuid>`
|
||||
|
||||
Shows detailed information:
|
||||
|
||||
* resolved inputs
|
||||
* metadata
|
||||
* fingerprints
|
||||
* last build summary
|
||||
|
||||
### 13.8 `prometeu packer doctor [--workspace] [--strict] [--fix]`
|
||||
|
||||
Runs diagnostics:
|
||||
|
||||
* `--workspace` deep scan
|
||||
* `--strict` warnings become errors
|
||||
* `--fix` applies safe automatic fixes (materialize defaults, normalize paths)
|
||||
|
||||
### 13.9 `prometeu packer build [--out build/assets.pa] [--table build/asset_table.json]`
|
||||
|
||||
Builds:
|
||||
|
||||
* `build/assets.pa`
|
||||
* `build/asset_table.json`
|
||||
|
||||
Key behaviors:
|
||||
|
||||
* validates registry before packing
|
||||
* packs assets deterministically
|
||||
* for virtual assets, runs build pipelines
|
||||
* records all offsets and metadata
|
||||
|
||||
### 13.10 `prometeu packer watch`
|
||||
|
||||
Watches registered inputs and registry changes.
|
||||
|
||||
* emits events (future)
|
||||
* rebuilds incrementally
|
||||
|
||||
`watch` is optional in v0 but recommended.
|
||||
|
||||
### 13.11 `prometeu packer gc [--workspace] [--quarantine]`
|
||||
|
||||
Reports unused files.
|
||||
|
||||
* default: report only
|
||||
* `--quarantine` moves candidates to quarantine
|
||||
|
||||
### 13.12 `prometeu packer quarantine <path> [--restore]`
|
||||
|
||||
Moves or restores files into/from quarantine.
|
||||
|
||||
---
|
||||
|
||||
## 14. Virtual Assets (Deep Explanation)
|
||||
|
||||
Virtual assets are a major capability.
|
||||
|
||||
### 14.1 Why Virtual Assets
|
||||
|
||||
* Most runtime formats should be derived from human-friendly authoring formats.
|
||||
* Example:
|
||||
|
||||
* author uses `source.png` and palette files
|
||||
* runtime expects indexed pixels + packed RGB565 palettes
|
||||
|
||||
### 14.2 Virtual Asset Contract
|
||||
|
||||
* Inputs are explicit.
|
||||
* Build steps are deterministic.
|
||||
* Outputs match a well-defined runtime payload format.
|
||||
|
||||
### 14.3 Examples of Future Virtual Assets
|
||||
|
||||
* `TILES/indexed_v1`: PNG + palette files → indexed pixels + packed palettes
|
||||
* `SOUNDS/pcm16le_v1`: WAV → PCM16LE
|
||||
* `SPRITESHEET/atlas_v1`: multiple PNG frames → atlas + metadata
|
||||
|
||||
Each `output.format` must have its own dedicated spec.
|
||||
|
||||
---
|
||||
|
||||
## 15. Integration with Cartridge Builder
|
||||
|
||||
The Cartridge Builder should:
|
||||
|
||||
1. Compile PBS into bytecode (e.g. `program.pbc` / `program.pbx`)
|
||||
2. Call `prometeu packer build`
|
||||
3. Consume `build/asset_table.json` and produce `cartridge/manifest.json`
|
||||
4. Copy artifacts into `cartridge/`
|
||||
5. Zip the cartridge into a distributable format (`.crt` / `.rom` / `.pro`)
|
||||
|
||||
The packer never touches `cartridge/`.
|
||||
|
||||
---
|
||||
|
||||
## 16. Compatibility and Versioning
|
||||
|
||||
* `assets/.prometeu/index.json` has `schema_version`
|
||||
* `asset.json` has `schema_version`
|
||||
* `build/asset_table.json` has `schema_version`
|
||||
|
||||
The Packer must be able to migrate older schema versions or emit actionable diagnostics.
|
||||
|
||||
---
|
||||
|
||||
## 17. Security and Trust Model
|
||||
|
||||
* The Packer is offline tooling.
|
||||
* It must never execute untrusted scripts.
|
||||
* It should treat external inputs as untrusted data.
|
||||
|
||||
---
|
||||
|
||||
## 18. Implementation Notes (Non-Normative)
|
||||
|
||||
* Rust implementation with a core crate + CLI wrapper.
|
||||
* Prefer structured JSON serde models.
|
||||
* Use stable diagnostic codes.
|
||||
* Keep the build deterministic.
|
||||
|
||||
---
|
||||
|
||||
## Appendix A — Glossary
|
||||
|
||||
* **ROM (`assets.pa`)**: packed asset payload used by runtime
|
||||
* **Descriptor (`asset_table.json`)**: mapping from logical assets to ROM slices
|
||||
* **Managed asset**: registered asset with stable identity and anchor file
|
||||
* **Virtual asset**: derived asset built from multiple inputs
|
||||
* **Quarantine**: safe area for suspected junk
|
||||
* **Doctor**: diagnostic command to keep sanity
|
||||
Reference in New Issue
Block a user