# Zig for Nova

Zig language support – ZLS, LLDB, Tree-Sitter grammar

## Requirements

- [Zig](https://ziglang.org/download/) installed and on `PATH` (or configured in extension preferences)
- [ZLS](https://github.com/zigtools/zls)\* for language intelligence
- [LLDB DAP](https://lldb.llvm.org/use/lldbdap.html)\* for debugging (discovered automatically via `xcrun` or `PATH`; install the Xcode Command Line Tools if absent: `xcode-select --install`)

\* optional but recommended for full experience

## Why

A personal project to learn Zig without leaving Nova and without giving up the comfort of language server and debugging features.

## Features

### Editing

- Syntax highlighting for `.zig` and `.zon`
- Code folding for blocks, declarations, and control-flow expressions
- Document symbols (outline, breadcrumbs, Go to Symbol)
- Diagnostics, completion, hover, go to definition, find references, select all references, formatting (all via ZLS)
- Inline compiler errors from `zig build`

### Tasks

- **Zig Package**: build and run a Zig package in the Nova console
- **Zig Package (macOS Terminal)**: build and run in the external Terminal app for interactive CLIs
- **Zig Debug**: build in Debug mode and launch under the debugger, with configurable console and stop-on-entry
- A clean action on every runnable template that removes `.zig-cache`, `zig-cache`, and `zig-out`

### Debugging

- Breakpoint support in Zig source files
- LLDB-based debug adapter, auto-discovered via `xcrun` or `PATH`

## Configuration

Global settings live under **Nova Preferences > Extensions > Zig**.
Per-workspace overrides live under **Project Settings > Zig** and take precedence.

### Tooling

Paths to the `zig`, `zls`, and `lldb-dap` executables. Leave any blank to discover from `PATH`.

### Language Server

- Enable or disable ZLS
- Allow ZLS to run its build/check on save
- Log ZLS traffic to the Extension Console (for troubleshooting)

## Troubleshooting

### A large part of the file turns red after one error

The parser may report a broad recovery range when it hits an incomplete expression (for example, `MyError.`), and Nova highlights that entire range. Fix the first syntax error shown and the overlay should narrow to the real error locations.

## Development

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
```

Validate the extension bundle:

```sh
/Applications/Nova.app/Contents/SharedSupport/nova extension validate .
```

## 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):

- The Zig logo and the icon/image assets derived from it
  (`extension.png`, `extension@2x.png`, `Images/zig-debug/*.png`,
  `Resources/Zig@32px.af`) are the work of the
  [Zig Software Foundation](https://ziglang.org) and remain licensed
  under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
- The Tree-sitter grammar for Zig is sourced from
  [github.com/tree-sitter-grammars/tree-sitter-zig](https://github.com/tree-sitter-grammars/tree-sitter-zig)
  and is distributed under the MIT License.