# 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.

This extension is not endorsed by, affiliated with, or associated with the [Zig Software Foundation](https://ziglang.org/zsf/) or the Zig core team in any way. It is maintained by an independent person, for fun.

## 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.