aboutsummaryrefslogtreecommitdiff

Zig Extension for Nova — Development Guide

Overview

This repository contains the Zig language extension for Nova. For user documentation, see Zig.novaextension/README.md.

Development

Parser

The Tree-sitter parser is built from the vendored grammar snapshot under vendor/tree-sitter-zig. The pinned upstream commit is recorded in vendor/tree-sitter-zig/VENDORING.md.

Rebuild the parser dylib:

sh ./scripts/build-parser.sh

Bump the vendored snapshot (and rebuild):

sh ./scripts/update-parser.sh # upstream HEAD ./scripts/update-parser.sh <ref> # specific tag, branch, or SHA

Validation

Validate the extension bundle:

sh /Applications/Nova.app/Contents/SharedSupport/nova extension validate Zig.novaextension/

Testing

Manual test cases are documented in TESTING.md. Run the test suite:

sh cd examples/test-suite && zig build test

Architecture

Extension Structure

  • Zig.novaextension/ — Nova extension bundle
    • Scripts/main.js — Extension entry point, task system, ZLS client, debugger
    • extension.json — Manifest with task templates, config schema, language definitions
    • Syntax/ — Syntax definitions and Tree-Sitter integration
    • Commands/ — Custom commands and menu items
  • vendor/tree-sitter-zig/ — Vendored Tree-Sitter grammar
  • examples/ — Example projects for testing and demonstration
  • build/ — Build artifacts (not in use)

Key Components

Language Server Integration — ZLS is launched on activation and provides completions, hover, go-to-definition, and diagnostics via the Nova language client API.

Task System — Four task templates (zigBuildRun, zigTest, zigDebug, zigWatch) wrap zig build subcommands with configurable arguments.

Issue Collection — Compiler diagnostics are parsed into a JSON file and loaded into Nova's issue collection for inline gutter annotations.

Debugger — LLDB-DAP is auto-discovered and used to debug Zig binaries via breakpoints and step controls.

License

The extension's source code is licensed under the BSD 2-Clause License (see LICENSE). Bundled assets and vendored third-party code carry their own licenses, documented in NOTICES.md.