CONTRIBUTING.md

Contributing to tree-sitter-scala

First off, thanks for being willing to contribute to making syntax highlighting in Scala better! This document will hopefully help you get set up, understand how to work on the codebase, or link to places to help you understand tree-sitter.

Requirements

• Node.js version 18.0 or greater
• C Compiler

Refer to the tree-sitter documentation for more details and specifics.

If you use nix you can enter a nix-shell (nix-shell .) which will install them for you.

Getting Started

To get started with contributing to the grammar you'll first need to install the project's dependencies:

npm install

The general flow will often start with adding a test case to ./corpus. You can find details on how testing works with tree-sitter here.

Once you've added your test case you'll want to then make the required changes to grammar.js, regenerate and recompile the parser, and run the tests:

npm run build
npm test

Then adjust as necessary. Note that depending on your change you may also have to touch the /src/scanner.c file if you need more advanced features like look-ahead.

Syntax highlighting

Right now the most common use-case for syntax highlight using tree-sitter is nvim-treesitter, which means much of our testing is in relation to it. You can find the syntax highlighting tests in test/highlight/*.scala. You can read more about this type of testing here. These test will be automatically ran with npm run test.

tree-sitter highlight

Another way to test your syntax highlighting locally is to use the tree-sitter highlight command. Note that you'll need to have tree-sitter installed globally for this to work. Once you have it installed you'll want to follow the instructions here to setup a local config that points towards this repo to be used as a parser. Once done you can then do the following:

tree-sitter highlight some/scala/file.scala

And see the syntax highlighting spit out. This is also the format used for testing, so it provides an easy way to get the output we use for testing.

Generation

In order to help not cause conflicts with multiple prs being open at the same time, we don't check in the parser on each pr. Instead, just check in the changes to the grammar.js and the CI will take care of the rest. Each night if changes are detected it will automatically be generated.

Smoke testing

You'll noticed that there is a part of CI that checks parsing against the Scala 2 and Scala 3 repositories to ensure we don't introduce unexpected regressions. The script for this is in script/smoke_test.sh. If you're change is increasing the coverage in either the library or compiler, please do update the expected percentages at the top of the file.

Obtaining an error reproduction

With Neovim

When creating an issue you'll want to ensure to include the ERROR node in it's context. There's a couple ways to do this. If you're using Neovim and utilizing treesitter, you can see the tree with :lua vim.treesitter.show_tree(). You can copy it directly from the open panel.

Manually

A manual way to get this would be to ensure that when you're in the repo you have the latest parser with

npm run build

Then you can copy your Scala code in a file and pass that file into npm run parse:

npm run parse <path/to/your/file.scala>

Then the tree will be printed out for you to copy.