Arquitectura

Visión General¶

Zolo compila el mismo código fuente para cuatro objetivos de ejecución: la VM de referencia, nativo mediante Cranelift, LLVM y wasm-aot. Todos comparten el lexer, el parser, el pipeline de desugar y la verificación de tipos.

La documentación arquitectónica completa y actualizada está en docs/architecture/.

Estructura de Crates¶

zolo-lang/
├── crates/
│   ├── zolo-lang/        # Binario 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 compartido + Cranelift
│   ├── zolo-llvm/        # Emisión de LLVM IR desde el lowering compartido
│   ├── zolo-wasm-aot/    # Emisión directa de WebAssembly
│   ├── zolo-ir/          # Representación intermedia compartida
│   ├── zolo-runtime/     # ABI, valores, GC y puente de plugins para AOT
│   ├── zolo-std/         # Biblioteca estándar (runtime Lua)
│   ├── zolo-lsp/         # Language Server Protocol
│   ├── zolo-dap/         # Debug Adapter Protocol
│   ├── zolo-fmt/         # Formateador de código
│   └── … otros 18 crates
├── editors/
│   └── vscode/           # Extensión VS Code
└── examples/             # Archivos .zolo de ejemplo

Consulta la tabla completa de crates para conocer las responsabilidades y dependencias de los 32 crates.

Detalles de los Crates¶

zolo-lexer¶

Tokeniza el código fuente de Zolo en un flujo de tokens con spans.

Archivos principales:

token.rs — enum TokenKind con todos los tipos de token
lexer.rs — struct Lexer, iterador sobre tokens
keywords.rs — tabla de búsqueda de palabras clave

Gestiona: Interpolación de cadenas ("text {expr} more"), plantillas con etiqueta (tag"..."), todos los operadores, comentarios (// y /* */).

zolo-parser¶

Parser de descenso recursivo que produce un AST.

Archivos principales:

ast.rs — Definiciones completas de tipos de AST (Program, Item, Expr, Stmt, Pattern, TypeExpr)
parser.rs — struct Parser con análisis de expresiones estilo Pratt
error.rs — Errores de análisis con spans del código fuente

Gestiona: Precedencia de operadores, todos los tipos de expresión, coincidencia de patrones, decoradores, genéricos.

zolo-compiler¶

Ejecuta el front-end compartido y, en el camino de la VM, transpila el AST de Zolo a código fuente Lua 5.1. Los backends AOT usan el lowering compartido de zolo-native para producir ZoloIR.

Archivos principales:

lowering.rs — LuaEmitter que recorre el AST y emite código Lua
compiler.rs — compile_to_lua() y compile_to_lua_with_source_map() de alto nivel
typeck.rs — Inferencia y verificación básica de tipos

Traducciones principales del camino de la 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 en 0 → indexado en 1)
`struct S { x }`	Función constructora + metatabla
`enum E { A(x) }`	`{__tag="A", x}`
`match`	Cadena de `if/elseif` con desestructuración
`@memoize fn f()`	Envoltorio de caché alrededor de la función
`@deprecated fn f()`	Envoltorio de advertencia única
`@builder struct S`	Métodos builder generados después del struct

Modos de compilación:

Run — omitir funciones @test
Test — incluir funciones @test y emitir ejecutor de pruebas

Mapas de fuente: El emisor rastrea pares (lua_line, zolo_line) para depuración.

zolo-vm¶

Una VM Lua 5.1 portada de luaoxide, implementada completamente en Rust.

Componentes principales:

Ejecución de bytecode (38 opcodes Lua 5.1)
VM basada en pila con gestión de frames
Recolector de basura tri-color mark-sweep
Tablas híbridas array+hash
Internamiento de cadenas
Biblioteca estándar (base, string, table, math, io, os, debug, coroutine)

zolo-std¶

Biblioteca estándar del camino de la VM escrita en Lua, inyectada como preludio antes del código del usuario. Los backends AOT también usan zolo-runtime para la ABI y los servicios de runtime nativos.

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

zolo-lsp¶

Implementación del Language Server Protocol usando tower-lsp.

Módulos:

server.rs — Servidor LSP principal, registra capacidades, despacha solicitudes
hover.rs — Información de hover para símbolos
completion.rs — Sugerencias de autocompletar
definition.rs — Ir a definición
symbols.rs — Esquema de símbolos del documento
semantic_tokens.rs — Tokens de resaltado semántico
signature_help.rs — Información de parámetros de firma de función
inlay_hints.rs — Sugerencias de tipo y nombre de parámetro
document.rs — Gestión de estado del documento con DashMap

zolo-dap¶

Implementación del Debug Adapter Protocol sobre stdin/stdout.

Módulos:

protocol.rs — Tipos de mensaje DAP (Request, Response, Event)
transport.rs — I/O JSON con framing Content-Length
session.rs — Gestión de sesión de depuración (lanzamiento, puntos de interrupción, stepping)

zolo-fmt¶

Formateador de código basado en AST.

Archivo principal:

printer.rs — Recorre el AST e imprime código Zolo formateado

Extensión VS Code¶

Extensión TypeScript para VS Code.

Archivos principales:

extension.ts — Punto de entrada de la extensión, cliente LSP, registro de comandos
explorer.ts — Barra lateral Zolo Explorer (TreeDataProvider)
astViewer.ts — Panel webview del Visor de AST
debugProvider.ts — Fábrica de adaptador de depuración
package.json — Manifiesto de la extensión (contribuciones, activación, comandos)

Flujo de Datos¶

Ejecutando un Archivo en la VM¶

zolo run hello.zolo
    → leer archivo
    → tokenizar
    → analizar AST
    → verificar tipos
    → bajar a Lua (con preludio añadido)
    → compilar Lua a bytecode (vía VM)
    → ejecutar bytecode

Generando un artefacto AOT¶

zolo build hello.zolo --emit native|llvm|wasm
    → tokenizar, analizar, desazucarar y verificar tipos
    → bajar el AST a ZoloIR compartido
    → native: Cranelift → objeto → enlace con zolo-runtime
    → llvm: LLVM IR → clang/lld → enlace con zolo-runtime
    → wasm: lowering wasm + encoder zolo-wasm-emit → módulo .wasm

Solicitud LSP¶

VS Code → LSP Client → stdin → zolo-lsp
    → analizar documento (en cada edición)
    → responder a la solicitud (hover/completion/etc.)
    → stdout → LSP Client → VS Code

Sesión de Depuración¶

VS Code → DAP Client → stdin → zolo-dap
    → compilar código fuente a Lua (con mapa de fuente)
    → establecer puntos de interrupción (mapeados vía mapa de fuente)
    → step/continue (rastrear línea actual)
    → responder con frames de pila / variables
    → stdout → DAP Client → VS Code