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/      # Analizador sintáctico → 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/         # Protocolo de servidor de lenguaje
│   ├── zolo-dap/         # Protocolo del adaptador de depuración
│   ├── 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:

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 → Cliente LSP → 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 → Cliente DAP → 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