# Zig Extension for Nova — Development Guide

## Overview

This repository contains the Zig language extension for Nova. For user documentation, see [Zig.novaextension/README.md](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](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`](LICENSE)). Bundled assets and vendored third-party code carry their own licenses, documented in [`NOTICES.md`](NOTICES.md).