Arquitetura

Visão Geral¶

Zolo compila o mesmo código-fonte para quatro alvos de execução: a VM de referência, nativo via Cranelift, LLVM e wasm-aot. Todos compartilham o lexer, o parser, o pipeline de desugar e a verificação de tipos.

A documentação arquitetural completa e atualizada fica em docs/architecture/.

Estrutura de Crates¶

zolo-lang/
├── crates/
│   ├── zolo-lang/        # Binário CLI (fachada)
│   ├── zolo-lexer/       # Tokenizador
│   ├── zolo-parser/      # Parser → AST
│   ├── zolo-compiler/    # Transpilador AST → Lua + verificador de tipos
│   ├── zolo-vm/          # VM Lua 5.1 (portado de luaoxide)
│   ├── zolo-native/      # AST → ZoloIR compartilhado + Cranelift
│   ├── zolo-llvm/        # Emissão de LLVM IR a partir do lowering compartilhado
│   ├── zolo-wasm-aot/    # Emissão direta de WebAssembly
│   ├── zolo-ir/          # Representação intermediária compartilhada
│   ├── zolo-runtime/     # ABI, valores, GC e ponte de plugins para AOT
│   ├── zolo-std/         # Biblioteca padrão (runtime Lua)
│   ├── zolo-lsp/         # Language Server Protocol
│   ├── zolo-dap/         # Debug Adapter Protocol
│   ├── zolo-fmt/         # Formatador de código
│   └── … 18 outros crates
├── editors/
│   └── vscode/           # Extensão VS Code
└── examples/             # Arquivos .zolo de exemplo

Veja a tabela completa de crates para responsabilidades e dependências de todos os 32 crates.

Detalhes dos Crates¶

zolo-lexer¶

Tokeniza o código-fonte Zolo em um fluxo de tokens com spans.

Arquivos principais:

token.rs — enum TokenKind com todos os tipos de token
lexer.rs — struct Lexer, iterador sobre tokens
keywords.rs — tabela de lookup de palavras-chave

Trata: Interpolação de strings ("text {expr} more"), templates com tag (tag"..."), todos os operadores, comentários (// e /* */).

zolo-parser¶

Parser de descida recursiva que produz uma AST.

Arquivos principais:

ast.rs — Definições completas de tipos de AST (Program, Item, Expr, Stmt, Pattern, TypeExpr)
parser.rs — struct Parser com análise de expressões estilo Pratt
error.rs — Erros de análise com spans de código-fonte

Trata: Precedência de operadores, todos os tipos de expressão, correspondência de padrão, decoradores, genéricos.

zolo-compiler¶

Executa o front-end compartilhado e, no caminho da VM, transpila a AST Zolo para código-fonte Lua 5.1. Os backends AOT usam o lowering compartilhado de zolo-native para produzir ZoloIR.

Arquivos principais:

lowering.rs — LuaEmitter que percorre a AST e emite código Lua
compiler.rs — compile_to_lua() e compile_to_lua_with_source_map() de alto nível
typeck.rs — Inferência e verificação básica de tipos

Traduções principais do caminho da VM:

Zolo	Lua
`let x = 10`	`local x = 10`
`fn f(a, b) { a + b }`	`local function f(a, b) return a + b end`
`\|x\| x * 2`	`function(x) return x * 2 end`
`a \|> f(b)`	`f(a, b)`
`a &. f()`	`(function(x) f(x); return x end)(a)`
`a?.b`	`(a ~= nil and a.b or nil)`
`a ?? b`	`(function() local __t = a; if __t ~= nil then return __t else return b end end)()`
`arr[i]`	`arr[i + 1]` (indexado em 0 → indexado em 1)
`struct S { x }`	Função construtora + metatabela
`enum E { A(x) }`	`{__tag="A", x}`
`match`	Cadeia de `if/elseif` com desestruturação
`@memoize fn f()`	Wrapper de cache em torno da função
`@deprecated fn f()`	Wrapper de aviso único
`@builder struct S`	Métodos builder gerados após a struct

Modos de compilação:

Run — pular funções @test
Test — incluir funções @test e emitir executor de testes

Mapas de fonte: O emissor rastreia pares (lua_line, zolo_line) para depuração.

zolo-vm¶

Uma VM Lua 5.1 portada de luaoxide, implementada inteiramente em Rust.

Componentes principais:

Execução de bytecode (38 opcodes Lua 5.1)
VM baseada em pilha com gerenciamento de frames
Coletor de lixo tri-color mark-sweep
Tabelas híbridas array+hash
Internamento de strings
Biblioteca padrão (base, string, table, math, io, os, debug, coroutine)

zolo-std¶

Biblioteca padrão do caminho da VM escrita em Lua, injetada como prelúdio antes do código do usuário. Os backends AOT também usam zolo-runtime para a ABI e os serviços de runtime nativos.

Fornece: string.*, Array.*, Map.*, Set.*, Option.*, Result.*, Iter.*, BigInt.*, assert_eq, assert_ne.

zolo-lsp¶

Implementação do Language Server Protocol usando tower-lsp.

Módulos:

server.rs — Servidor LSP principal, registra capacidades, despacha requisições
hover.rs — Informações de hover para símbolos
completion.rs — Sugestões de autocompletar
definition.rs — Ir para definição
symbols.rs — Esboço de símbolos do documento
semantic_tokens.rs — Tokens de realce semântico
signature_help.rs — Informações de parâmetro de assinatura de função
inlay_hints.rs — Dicas de tipo e nome de parâmetro
document.rs — Gerenciamento de estado do documento com DashMap

zolo-dap¶

Implementação do Debug Adapter Protocol sobre stdin/stdout.

Módulos:

protocol.rs — Tipos de mensagem DAP (Request, Response, Event)
transport.rs — I/O JSON com framing Content-Length
session.rs — Tratamento de sessão de depuração (lançamento, pontos de parada, stepping)

zolo-fmt¶

Formatador de código baseado em AST.

Arquivo principal:

printer.rs — Percorre a AST e imprime código Zolo formatado

Extensão VS Code¶

Extensão TypeScript para VS Code.

Arquivos principais:

extension.ts — Ponto de entrada da extensão, cliente LSP, registro de comandos
explorer.ts — Barra lateral Zolo Explorer (TreeDataProvider)
astViewer.ts — Painel webview do Visualizador de AST
debugProvider.ts — Fábrica de adaptador de depuração
package.json — Manifesto da extensão (contribuições, ativação, comandos)

Fluxo de Dados¶

Executando um Arquivo na VM¶

zolo run hello.zolo
    → ler arquivo
    → tokenizar
    → analisar AST
    → verificar tipos
    → baixar para Lua (com prelúdio adicionado)
    → compilar Lua para bytecode (via VM)
    → executar bytecode

Gerando um artefato AOT¶

zolo build hello.zolo --emit native|llvm|wasm
    → tokenizar, analisar, dessugar e verificar tipos
    → baixar AST para ZoloIR compartilhado
    → native: Cranelift → objeto → link com zolo-runtime
    → llvm: LLVM IR → clang/lld → link com zolo-runtime
    → wasm: lowering wasm + encoder zolo-wasm-emit → módulo .wasm

Requisição LSP¶

VS Code → LSP Client → stdin → zolo-lsp
    → analisar documento (a cada edição)
    → responder à requisição (hover/completion/etc.)
    → stdout → LSP Client → VS Code

Sessão de Depuração¶

VS Code → DAP Client → stdin → zolo-dap
    → compilar código-fonte para Lua (com mapa de fonte)
    → definir pontos de parada (mapeados via mapa de fonte)
    → step/continue (rastrear linha atual)
    → responder com frames de pilha / variáveis
    → stdout → DAP Client → VS Code