Since installation now installs parsers _and_ queries, caching parsers
doesn't allow skipping the installation step (and caching queries does
not pay off).
This updates
* README
* CONTRIBUTING
* the `:h nvim-treesitter` documentation
to the current state of `main`. It also adds a pull request template for
adding a new language.
Problem: `locals.lua` was neither used nor tested, and providing it goes
against the goal of nvim-treesitter not being a required dependency for
other plugins.
Solution: Remove the module and document that the queries are provided
as-is for limited backward compatibility only.
Problem: Not easy to run all checks and tests locally. Redundant CI
workflows.
Solution: Separate CI into two workflows:
* lint: Lua files (stylua, luals), query files (valid captures,
predicates, directives using tsqueryls), docs
(SUPPORTED_LANGUAGES.md) -- does not need parser installation
* tests: parsers (ABI compatibility), query files (tsqueryls on
Linux/macOS; nvim on Windows), highlight and indent tests (separated
for better readability) -- needs parser installation (but only once)
Switch to https://github.com/nvim-treesitter/highlight-assertions fork
with ABI 15 support.
Run all tests (on Linux and macOS) through `make` (`formatlua`,
`checklua`, `lintquery`, `formatquery`, `checkquery`, `docs`, `tests`),
which downloads and caches all necessary dependencies.
Remove `update-readme` workflow (replaced by lint job on PRs).
Instead, call `require('nvim-treesitter').install( { ... } )` manually.
This gives users full control over how they want to install parsers
(sync, from grammar, limited concurrency) and obviates the need for
calling `setup` for most users.
Problem: Using git for installing parsers can lead to data loss if in a
git commit buffer.
Solution: Only support downloading via curl+tar, which are installed on
all supported platforms (since Windows 10). Curl will also be required
for WASM parsers (and for `vim.net.download()`).
Problem: Tracking parser revision in lockfile and allowing override
through the parsers module complicates the code. In addition, only
revision changes are handled robustly, not changes to other installation
info.
Solution: Track parser revision in the parsers module directly. Reload
parser table on every install or update call. Support modifying parser
table in a `User TSUpdate` autocommand.
Problem: Many parsers require node/npm to evaluate the `grammar.js`
before being able to generate a parser from it.
Solution: Generate from `grammar.json` instead, which is fully resolved.
Drops `node` and `npm` as (optional) requirements for nvim-treesitter.
Note that this requires parsers to commit the generated json iff the
grammar requires evaluation (which is currently the case for all tracked
languages).
Problem: Using `url` for both remote repo and local path complicates the
code.
Solution: Add `path` field that overrides `url` and bypasses
git-specific manipulations, i.e., the contents of the `path` are used
as-is (no git repo needed).
This means `:TSUpdate` will skip such parsers; use `:TSInstall!` instead
after making local changes.
---------
Co-authored-by: Lewis Russell <lewis6991@gmail.com>
