Tooling

Zolo comes with a comprehensive set of development tools.

CLI (zolo)¶

The zolo command is the primary interface for working with Zolo code.

Running Code¶

zolo run hello.zolo       # compile and execute
zolo hello.zolo           # shorthand for 'run'

Compiling¶

zolo compile hello.zolo   # show generated Lua code

This is useful for debugging — you can see exactly what Lua code your Zolo program produces.

Cleaning build artifacts¶

zolo clean                  # remove target/ from the current project
zolo clean --dry-run        # show file count and size without deleting
zolo clean path/to/project  # clean a different project

zolo clean removes only project-local generated artifacts under target/. Published web output under dist/ remains untouched. Immutable npm/JSR package contents live in Zolo's shared package cache and are linked into the project, so a clean rebuild stays fast and can remain offline; this is the same split between cargo clean and Cargo's shared registry cache.

Removing target/ also removes the sealed editor-resolution descriptors the IDE uses to type inline client TypeScript ([client.dependencies] packages and verniz:* modules). The editor never installs or resolves packages on its own, so hovers degrade to any until the next zolo install, zolo dev, or zolo build regenerates the descriptors — zolo clean prints a note when that applies.

Type Checking¶

zolo check hello.zolo     # parse and type check without executing

Testing¶

zolo test tests.zolo                 # run all @test functions
zolo test tests.zolo --filter fib    # only tests matching "fib"
zolo test tests.zolo --list          # list test names

Test output shows pass/fail for each test function:

[PASS] test_addition
[PASS] test_fibonacci
[FAIL] test_broken - assertion failed: expected 5, got 4
Results: 2 passed, 1 failed, 3 total

Formatting¶

zolo fmt hello.zolo          # format file in place
zolo fmt --check hello.zolo  # check formatting without modifying

REPL¶

zolo repl     # start interactive session

Version and Help¶

zolo version   # or zolo -v
zolo help      # or zolo -h

Language Server Protocol (LSP)¶

The Zolo LSP server (zolo-lsp) provides IDE features. It's implemented in Rust using tower-lsp and communicates over stdin/stdout.

Supported Features¶

Semantic Token Types¶

The LSP provides semantic tokens for:

• function — function names (with declaration modifier)
• method — method names
• parameter — function parameters
• variable — local variables
• property — struct fields
• type — type names (structs, enums)
• interface — trait names
• enumMember — enum variants
• decorator — @ annotations
• keyword — language keywords
• string — string literals
• number — numeric literals
• comment — comments

Inlay Hints¶

Two types of inlay hints:

1. Parameter name hints — shown before arguments in function calls:

   add(/*a:*/ 1, /*b:*/ 2)

2. Type hints — shown after let bindings with inferred types:

   let x /*: int*/ = 42

Debug Adapter Protocol (DAP)¶

The zolo-dap crate implements the Debug Adapter Protocol for debugging Zolo programs in VS Code.

Supported Features¶

How It Works¶

1. The DAP compiles Zolo to Lua using compile_to_lua_with_source_map()
2. Source map entries track (lua_line, zolo_line) mappings
3. Breakpoints are translated from Zolo lines to Lua lines
4. The debug session manages stepping, stack frames, and variable scopes

VS Code Launch Configuration¶

Add to .vscode/launch.json:

{
    "type": "zolo",
    "request": "launch",
    "name": "Debug Zolo",
    "program": "${file}"
}

Formatter (zolo fmt)¶

The Zolo formatter is AST-based — it parses the source, then reprints it with consistent style.

Features¶

• 4-space indentation
• Consistent brace placement
• Comment preservation
• Expression formatting
• Declaration alignment

Usage¶

zolo fmt myfile.zolo         # format in place
zolo fmt --check myfile.zolo # check without modifying (exit code 1 if changes needed)

External JavaScript and TypeScript in Verniz¶

Projects that opt in with [client.lint] engine = "oxlint" and [client.format] engine = "oxfmt" gain an embedded, Node-free client quality path:

zolo lint --client                         # safely discover authored JS/TS
zolo lint --client --fix src/client        # apply safe fixes only
zolo lint --client --format json app.ts    # editor/CI protocol
zolo lint --client --format sarif          # code-scanning protocol

zolo fmt --client src/client               # format after parsing every input
zolo fmt --client --check                  # CI check, no writes
zolo fmt --client --diff app.ts            # review the change

Discovery is confined to the current Zolo project and skips dist, public, target/.zolo, package sources, temporary products, node_modules and symlinks. Oxlint warnings/errors carry authored byte offsets and line/column; --deny-warnings or deny_warnings = true controls the exit gate. Oxfmt preserves comments and the file's line-ending style. Neither command changes the TypeScript checker/emitter used by builds, and lint rules never become a bundle requirement.

VS Code Extension¶

The Zolo VS Code extension provides a complete development environment.

Features¶

Commands¶

Configuration¶

Status Bar¶

Shows the LSP connection status:

• Connected / Disconnected / Error
• Click to open the output channel with LSP logs

Zolo Explorer¶

A sidebar panel (activity bar) showing the document outline:

• Functions, structs, enums, traits, variables
• Click any symbol to navigate to its location
• Auto-refreshes on file changes

AST Viewer¶

A webview panel showing the parsed AST as an interactive tree:

• Updates live as you edit
• Shows all AST nodes with their types and spans

Debugging¶

Press F5 to start debugging with the Zolo debug adapter:

• Set breakpoints by clicking the gutter
• Step through code line by line
• View the call stack
• Continue/pause execution

Context Menus¶

Right-click a .zolo file in the explorer → "Run with Zolo"