- TODO: document VSCode extension development practices
- TODO: document Helix Kerolox language setup
- TODO: document licensing and attribution guidelines

# Contributing to the Tree-sitter Grammar

The Kerolox tooling makes use of a custom [tree-sitter](https://github.com/tree-sitter/tree-sitter) grammar for fast incremental parsing.

The tree-sitter grammar lives in the `tree-sitter-kerolox` directory in the repository. The main file of interest is `grammar.js`, which defines the actual Kerolox grammar. The [tree-sitter documentation](https://tree-sitter.github.io/tree-sitter/creating-parsers/index.html) has very useful documentation on how to work with this grammar definition.

Any time the grammar is modified, the tree-sitter parser needs to be regenerated using the [tree-sitter CLI](https://github.com/tree-sitter/tree-sitter/blob/master/crates/cli/README.md). Otherwise, the changes to the grammar won't actually be compiled. To regenerate the parser from the grammar, ensure the CLI is installed, and run this command in the `tree-sitter-kerolox` directory:

```bash
tree-sitter generate --abi 14
```

We use an [ABI version](https://tree-sitter.github.io/tree-sitter/using-parsers/7-abi-versions.html) of 14 because it's known to work with older versions of [Helix](https://helix-editor.com), Marceline's preferred text editor. This is a deliberately overly cautious policy, but we're open to changing it if there's a good reason to.

The generated files should be committed and pushed as normal, since it's conventional for third-party tools to pull and compile pregenerated tree-sitter parsers directly from their upstream repositories.