pr 01
This commit is contained in:
@@ -101,346 +101,6 @@ Workspace (Archive.zip) tem crates:
|
||||
|
||||
# PRs (detalhados)
|
||||
|
||||
## PR-00 — Infra: crates de análise + lsp (estrutura do workspace)
|
||||
|
||||
**Branch:** `pr-00-analysis-lsp-foundations`
|
||||
|
||||
### Decisão travada (LSP)
|
||||
|
||||
* **Biblioteca escolhida:** `tower-lsp`
|
||||
* **Motivo:** reduzir boilerplate, acelerar MVP e minimizar vai-e-volta. Cancelamento/incremental será feito **por cima** (tasks async + cancel tokens).
|
||||
|
||||
### Objetivo
|
||||
|
||||
Adicionar crates novas sem mexer no pipeline existente.
|
||||
|
||||
### Entregas obrigatórias
|
||||
|
||||
1. **Novo crate:** `prometeu-analysis/`
|
||||
|
||||
* `Cargo.toml` (library)
|
||||
* `src/lib.rs`
|
||||
2. **Novo crate:** `prometeu-lsp/`
|
||||
|
||||
* `Cargo.toml` (bin)
|
||||
* `src/main.rs`
|
||||
3. Workspace root: ajustar `Cargo.toml` (se existir no root) para incluir members.
|
||||
|
||||
### Dependências (fixas)
|
||||
|
||||
* `prometeu-analysis`: `serde`, `serde_json`
|
||||
* `prometeu-lsp`:
|
||||
|
||||
* `tower-lsp = "0.20"` (ou versão estável atual)
|
||||
* `tokio` (full)
|
||||
* `prometeu-analysis` (path)
|
||||
|
||||
### Esqueleto obrigatório (`prometeu-lsp/src/main.rs`)
|
||||
|
||||
```rust
|
||||
use tower_lsp::{LspService, Server};
|
||||
use tokio::sync::RwLock;
|
||||
use std::sync::Arc;
|
||||
|
||||
#[derive(Default)]
|
||||
struct AnalysisDb {
|
||||
// FileDB, AstArena, SymbolArena, TypeArena, Diagnostics
|
||||
}
|
||||
|
||||
struct Backend {
|
||||
db: Arc<RwLock<AnalysisDb>>,
|
||||
}
|
||||
|
||||
#[tower_lsp::async_trait]
|
||||
impl tower_lsp::LanguageServer for Backend {
|
||||
async fn initialize(&self, _: tower_lsp::lsp_types::InitializeParams)
|
||||
-> tower_lsp::jsonrpc::Result<tower_lsp::lsp_types::InitializeResult> {
|
||||
Ok(tower_lsp::lsp_types::InitializeResult {
|
||||
capabilities: tower_lsp::lsp_types::ServerCapabilities {
|
||||
text_document_sync: Some(tower_lsp::lsp_types::TextDocumentSyncCapability::Kind(
|
||||
tower_lsp::lsp_types::TextDocumentSyncKind::FULL,
|
||||
)),
|
||||
// Declaramos capacidades desde já para evitar churn posterior.
|
||||
definition_provider: Some(true.into()),
|
||||
document_symbol_provider: Some(true.into()),
|
||||
workspace_symbol_provider: Some(true.into()),
|
||||
hover_provider: Some(true.into()),
|
||||
references_provider: Some(true.into()),
|
||||
rename_provider: Some(tower_lsp::lsp_types::OneOf::Left(true)),
|
||||
completion_provider: Some(tower_lsp::lsp_types::CompletionOptions {
|
||||
resolve_provider: Some(false),
|
||||
trigger_characters: Some(vec![".".into(), ":".into()]),
|
||||
..Default::default()
|
||||
}),
|
||||
semantic_tokens_provider: Some(
|
||||
tower_lsp::lsp_types::SemanticTokensServerCapabilities::SemanticTokensOptions(
|
||||
tower_lsp::lsp_types::SemanticTokensOptions {
|
||||
legend: tower_lsp::lsp_types::SemanticTokensLegend {
|
||||
// preenchido no PR-12
|
||||
token_types: vec![],
|
||||
token_modifiers: vec![],
|
||||
},
|
||||
full: Some(tower_lsp::lsp_types::SemanticTokensFullOptions::Bool(true)),
|
||||
range: None,
|
||||
..Default::default()
|
||||
},
|
||||
),
|
||||
),
|
||||
..Default::default()
|
||||
},
|
||||
..Default::default()
|
||||
})
|
||||
}
|
||||
|
||||
async fn initialized(&self, _: tower_lsp::lsp_types::InitializedParams) {}
|
||||
}
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() {
|
||||
let stdin = tokio::io::stdin();
|
||||
let stdout = tokio::io::stdout();
|
||||
let (service, socket) = LspService::new(|_| Backend { db: Arc::new(RwLock::new(AnalysisDb::default())) });
|
||||
Server::new(stdin, stdout, socket).serve(service).await;
|
||||
}
|
||||
```
|
||||
|
||||
### Contrato exato do AnalysisDb (travado)
|
||||
|
||||
> **Regra:** o LSP nunca recalcula segurando `RwLock` por muito tempo. Toda análise pesada roda fora do lock e depois faz swap.
|
||||
|
||||
Criar arquivo: `prometeu-lsp/src/analysis_db.rs`
|
||||
|
||||
```rust
|
||||
use std::sync::Arc;
|
||||
use tokio::sync::RwLock;
|
||||
use tokio_util::sync::CancellationToken;
|
||||
|
||||
use prometeu_analysis::FileDB;
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct AnalysisDb {
|
||||
pub file_db: FileDB,
|
||||
|
||||
// Os campos abaixo serão conectados conforme PR-03/04/05 (podem começar como None)
|
||||
// pub ast: Option<AstArena>,
|
||||
// pub symbols: Option<SymbolArena>,
|
||||
// pub types: Option<TypeArena>,
|
||||
// pub diagnostics: Vec<Diagnostic>,
|
||||
|
||||
/// Incrementa a cada rebuild concluído com sucesso
|
||||
pub revision: u64,
|
||||
|
||||
/// Cancel token do último rebuild em progresso (se houver)
|
||||
pub active_rebuild: Option<CancellationToken>,
|
||||
}
|
||||
|
||||
pub type SharedDb = Arc<RwLock<AnalysisDb>>;
|
||||
```
|
||||
|
||||
No `main.rs`, **substituir** o `AnalysisDb` local pelo import acima (ou manter local e delegar, mas sem duplicar).
|
||||
|
||||
### Modelo de cancelamento e coalescing (travado)
|
||||
|
||||
> Objetivo: quando chegam múltiplos `didChange` em sequência, cancelar o rebuild anterior e rodar apenas o último.
|
||||
|
||||
Adicionar dependência fixa em `prometeu-lsp/Cargo.toml`:
|
||||
|
||||
* `tokio-util`
|
||||
|
||||
Criar arquivo: `prometeu-lsp/src/rebuild.rs`
|
||||
|
||||
```rust
|
||||
use tokio_util::sync::CancellationToken;
|
||||
use crate::analysis_db::SharedDb;
|
||||
|
||||
/// Solicita rebuild do projeto (coarse). Cancela rebuild anterior se em progresso.
|
||||
/// Implementação inicial: apenas cria task e retorna.
|
||||
pub async fn request_rebuild(db: SharedDb) {
|
||||
// 1) lock curto: cancelar token anterior e instalar token novo
|
||||
// 2) spawn task: roda análise fora do lock
|
||||
// 3) lock curto: se token não cancelado, swap estado + revision++
|
||||
}
|
||||
```
|
||||
|
||||
Regras obrigatórias:
|
||||
|
||||
1. `request_rebuild` deve:
|
||||
|
||||
* cancelar `active_rebuild` anterior (se existir)
|
||||
* instalar um token novo
|
||||
* `tokio::spawn` uma task de rebuild
|
||||
2. A task deve checar `token.is_cancelled()` em pontos seguros:
|
||||
|
||||
* antes de começar
|
||||
* após parsing
|
||||
* após resolver
|
||||
* após typecheck
|
||||
3. O lock (`RwLock`) deve ser segurado apenas:
|
||||
|
||||
* para trocar `active_rebuild`
|
||||
* para aplicar o resultado final
|
||||
|
||||
### Critérios de aceite
|
||||
|
||||
* `cargo build -p prometeu-lsp` ok
|
||||
* LSP inicializa em VS Code/Neovim sem crash
|
||||
* Nenhuma feature além do declarado
|
||||
|
||||
---
|
||||
|
||||
## Política fixa de cancelamento e rebuild (tower-lsp)
|
||||
|
||||
### Objetivo
|
||||
|
||||
Garantir que edições rápidas não gerem backlog de análises e evitar race conditions.
|
||||
|
||||
### Decisão travada
|
||||
|
||||
* Usar `tokio_util::sync::CancellationToken`
|
||||
* **Um token por rebuild**
|
||||
* Qualquer `didChange`:
|
||||
|
||||
1. Cancela o rebuild anterior
|
||||
2. Cria novo token
|
||||
3. Agenda nova task de análise
|
||||
|
||||
### Estruturas obrigatórias
|
||||
|
||||
```rust
|
||||
use tokio_util::sync::CancellationToken;
|
||||
|
||||
struct AnalysisController {
|
||||
current: Option<CancellationToken>,
|
||||
}
|
||||
```
|
||||
|
||||
### Regras
|
||||
|
||||
* Nunca segurar `RwLock<AnalysisDb>` durante parsing/resolver/typecheck.
|
||||
* Fluxo correto:
|
||||
|
||||
1. Clonar snapshot dos textos (FileDB)
|
||||
2. Soltar lock
|
||||
3. Rodar análise pesada
|
||||
4. Re-adquirir lock e substituir estado
|
||||
* Tasks devem checar `token.is_cancelled()` entre fases (parse / bind / type).
|
||||
|
||||
### Critérios de aceite
|
||||
|
||||
* Digitar rapidamente não acumula tasks.
|
||||
* Apenas o último estado publica diagnostics.
|
||||
|
||||
---
|
||||
|
||||
## Contrato fechado do AnalysisDb (fonte de verdade do LSP)
|
||||
|
||||
### Objetivo
|
||||
|
||||
Eliminar ambiguidade sobre o que vive no estado compartilhado.
|
||||
|
||||
### Estrutura obrigatória
|
||||
|
||||
```rust
|
||||
#[derive(Default)]
|
||||
pub struct AnalysisDb {
|
||||
pub files: FileDB,
|
||||
pub ast: Option<AstArena>,
|
||||
pub symbols: Option<SymbolArena>,
|
||||
pub types: Option<TypeArena>,
|
||||
pub type_facts: Option<TypeFacts>,
|
||||
pub diagnostics: Vec<Diagnostic>,
|
||||
}
|
||||
```
|
||||
|
||||
### Regras
|
||||
|
||||
* `AnalysisDb` **nunca** armazena estado parcialmente válido.
|
||||
* Se uma fase falhar:
|
||||
|
||||
* `ast/symbols/types` podem ficar `None`
|
||||
* `diagnostics` deve estar preenchido
|
||||
* LSP handlers **não** rodam análise: apenas leem `AnalysisDb`.
|
||||
|
||||
### Leitura segura
|
||||
|
||||
* Todos os handlers (`definition`, `hover`, `references`, etc.) devem:
|
||||
|
||||
* adquirir `db.read()`
|
||||
* lidar com `Option::None` retornando `null` / resposta vazia
|
||||
|
||||
### Escrita segura
|
||||
|
||||
* Apenas a task de rebuild escreve no `AnalysisDb`.
|
||||
* Escrita sempre substitui o estado inteiro (swap lógico).
|
||||
|
||||
### Critérios de aceite
|
||||
|
||||
* Nenhum handler pode panic por `None`.
|
||||
* Rebuild substitui estado de forma atômica (do ponto de vista do LSP).
|
||||
|
||||
---
|
||||
|
||||
|
||||
# Série PR-00.X — Reestruturação de crates (Arena-Driven + LSP-ready)
|
||||
|
||||
> **Objetivo da série PR-00.X:** reorganizar o workspace em crates com fronteiras claras, **sem alterar comportamento**, preparando o terreno para o Prometeu Arena-Driven (compiler/analysis) e um LSP completo depois.
|
||||
>
|
||||
> **Novo layout alvo (travado):**
|
||||
>
|
||||
> * `prometeu-bytecode` (fica)
|
||||
> * `prometeu-abi` (novo nome para o atual `prometeu-core` depurado) = **types + model + protocols** (sem execução)
|
||||
> * `prometeu-vm` (novo) = execução da VM
|
||||
> * `prometeu-kernel` (novo) = OS + FS + syscalls (implementa interface para a VM)
|
||||
> * `prometeu-runtime-desktop` (fica) = host desktop
|
||||
> * `prometeu-compiler` (fica)
|
||||
> * `prometeu` (CLI) (fica)
|
||||
>
|
||||
> **Regra de ouro:** 1 PR = 1 fronteira. Nada de mover tudo de uma vez.
|
||||
>
|
||||
> **Regras para Junie (serie 00.X):**
|
||||
>
|
||||
> 1. **Não mudar lógica**; apenas mover, ajustar imports, e deixar testes verdes.
|
||||
> 2. Se algo exigir mudança de API pública, criar `TODO(PR-00.Y)` e parar.
|
||||
> 3. Sempre manter o workspace compilável a cada PR.
|
||||
|
||||
---
|
||||
## PR-00.4 — Depurar `prometeu-core`: remover execução e virar apenas compat layer
|
||||
|
||||
**Branch:** `pr-00-4-deprecate-prometeu-core`
|
||||
|
||||
### Objetivo
|
||||
|
||||
Eliminar o conteúdo executável restante do `prometeu-core`, deixando-o como reexport/compat por um curto período.
|
||||
|
||||
### Passos
|
||||
|
||||
* `hardware` e `firmware/hub` ficam onde estiverem por enquanto (podem virar PR-00.5/00.6 se necessário)
|
||||
* `prometeu-core` passa a reexportar:
|
||||
|
||||
* `prometeu-abi`
|
||||
* `prometeu-vm`
|
||||
* `prometeu-kernel`
|
||||
|
||||
### Critérios
|
||||
|
||||
* Zero imports internos `crate::virtual_machine` etc. fora da facade.
|
||||
|
||||
---
|
||||
|
||||
## PR-00.6 — Remover `prometeu-core` e migrar consumidores
|
||||
|
||||
**Branch:** `pr-00-6-remove-prometeu-core`
|
||||
|
||||
### Objetivo
|
||||
|
||||
Apagar `prometeu-core` após migração total.
|
||||
|
||||
### Critérios
|
||||
|
||||
* Nenhum crate depende de `prometeu-core`.
|
||||
|
||||
---
|
||||
|
||||
## PR-01 — FileDB + LineIndex (base do LSP e spans)
|
||||
|
||||
**Branch:** `pr-01-filedb`
|
||||
|
||||
Reference in New Issue
Block a user