An LSP implementation for tree-sitter query files

Configuration

Configuration can be done via server initialization or via a configuration file named .tsqueryrc.json located in the project workspace directory, or in any of its ancestor directories. Below is an example file:

{
  "$schema": "https://raw.githubusercontent.com/ribru17/ts_query_ls/refs/heads/master/schemas/config.json",
  "parser_install_directories": ["${HOME}/my/parser", "/installation/paths"],
  "parser_aliases": {
    "ecma": "javascript"
  },
  "language_retrieval_patterns": [
    "languages/src/([^/]+)/[^/]+\\.scm$"
  ],
  "valid_captures": {
    "highlights": {
      "variable": "Simple identifiers",
      "variable.parameter": "Parameters of a function"
    }
  },
  "valid_predicates": {
    "eq": {
      "parameters": [
        {
          "type": "capture",
          "arity": "required"
        },
        {
          "type": "any",
          "arity": "required"
        }
      ],
      "description": "Checks for equality between two nodes, or a node and a string.",
      "any": true
    }
  }
}

Configuration options

parser_install_directories

A list of strings representing directories to search for parsers, of the form <lang>.(so|dll|dylib) or tree-sitter-<lang>.wasm.

Supports environment variable expansion of the form ${VAR}.

parser_aliases

A map of parser aliases. E.g., to point queries/ecma/*.scm files to the javascript parser:

{
  "parser_aliases": {
    "ecma": "javascript"
  }
}

language_retrieval_patterns

A list of patterns to aid the LSP in finding a language, given a file path. Patterns must have one capture group which represents the language name. Ordered from highest to lowest precedence. E.g., for zed support:

{
  "language_retrieval_patterns": [
    "languages/src/([^/]+)/[^/]+\\.scm$"
  ]
}

NOTE: The following fallbacks are always provided:

• tree-sitter-([^/]+)/queries/[^/]+\.scm$
• queries/([^/]+)/[^/]+\.scm$

valid_captures

A map from query file name to valid captures. Valid captures are represented as a map from capture name (sans @) to a short (markdown format) description. Note that captures prefixed with an underscore are always permissible.

{
  "valid_captures": {
    "highlights": {
      "variable": "Simple identifiers",
      "variable.parameter": "Parameters of a function"
    }
  }
}

valid_predicates

A map of predicate names (sans # and ?) to parameter specifications.

Parameters can be one or both of two types (a capture or a string), and can be required, optional, or "variadic" (there can be zero-to-many of them). Optional parameters cannot be followed by required parameters, and a variadic parameter may only appear once, as the last parameter.

{
  "valid_predicates": {
    "any-of": {
      "parameters": [
        {
          "type": "capture",
          "arity": "required"
        },
        {
          "type": "string",
          "arity": "required"
        },
        {
          "type": "string",
          "arity": "variadic"
        }
      ],
      "description": "Checks for equality between multiple strings"
    }
  }
}

Predicates are special because they can also accept two other properties: not (boolean, default true), and any (boolean, default false). not means that the predicate supports a not- prefixed version of itself, which acts as its negation, and any means that is supports an any- prefixed version of itself, which holds true if any of the nodes in a quantified capture hold true. If both properties are true, then there will be a predicate of the form #not-any-foo?.

valid_directives

Same as valid_predicates, but for directives (e.g. #foo!).

Example setup (for Neovim):

-- Disable the (slow) builtin query linter
vim.g.query_lint_on = {}

vim.api.nvim_create_autocmd('FileType', {
  pattern = 'query',
  callback = function(ev)
    if vim.bo[ev.buf].buftype == 'nofile' then
      return
    end
    vim.lsp.start {
      name = 'ts_query_ls',
      cmd = { '/path/to/ts_query_ls/target/release/ts_query_ls' },
      root_dir = vim.fs.root(0, { '.tsqueryrc.json', 'queries' }),
      -- OPTIONAL: Override the query omnifunc
      on_attach = function(_, buf)
        vim.bo[buf].omnifunc = 'v:lua.vim.lsp.omnifunc'
      end,
      init_options = {
        parser_install_directories = {
          -- If using nvim-treesitter with lazy.nvim
          vim.fs.joinpath(
            vim.fn.stdpath('data'),
            '/lazy/nvim-treesitter/parser/'
          ),
        },
        parser_aliases = {
          ecma = 'javascript',
        },
        language_retrieval_patterns = {
          'languages/src/([^/]+)/[^/]+\\.scm$',
        },
      },
    }
  end,
})

Standalone tool

Formatter

The language server can be used as a standalone formatter by passing the format argument, e.g. ts_query_ls format ./queries. The command can accept multiple directories to format. It can also run in "check" mode by passing the --check (-c) flag, which will only validate formatting without writing to the files.

# use this command for the full documentation
ts_query_ls format --help

CI Tool

The language server can also be used as standalone CI tool by passing the check argument, e.g:

ts_query_ls check ./queries --config \
'{"parser_install_directories": ["/home/jdoe/Documents/parsers/"]}'

The command can accept a list of directories to search for queries, as well as a flag to pass JSON configuration to the server (needed to detect parser locations). If no configuration flag is passed, the command will attempt to read it from the .tsqueryrc.json configuration file in the current directory. The command also accepts a --format (-f) flag which instructs it to also check formatting for the given directories. Quick fixes can be applied to supported diagnostics by passing the --fix flag. If no directories are specified to be checked, then the command will search for all queries in the current directory.

NOTE: This command performs a superset of the work done by the lint command; it reads the query's language to validate query structure, node names, etc.

# use this command for the full documentation
ts_query_ls check --help

Linter

The server can be used as a general linter which can operate without access to the underlying parser objects. The following command will lint the queries directory, meaning it will scan it for invalid capture names or invalid predicate signatures, as defined by the configuration. Configuration can be passed in via the --config flag, or it will be read from the current directory if no flag is passed. Quick fixes can be applied to supported diagnostics by passing the --fix flag.

ts_query_ls lint ./queries
# Use this command for the full documentation
ts_query_ls lint --help

Profiler

The server can be used to profile individual query patterns to check for patterns which are very slow to compile (often because they are too complex). This can be done via the profile subcommand, which prints each pattern's file path, start line, and the time (in milliseconds) that it took to compile. Alternatively, it can also time the entire query file itself (rather than each pattern inside of it).

ts_query_ls profile ./queries
# Use this command for the full documentation
ts_query_ls profile --help

NOTE: This command will not warm up the cache for you, so it may be best to run more than once.

Checklist

• References for captures
• Renaming captures
• Completions for capture names in a pattern (for predicates)
• Completions for node names
• Fix utility functions, making them robust when it comes to UTF-16 code points
• Go to definition for captures
• Recognition/completion of supertypes (requires tree-sitter 0.25)
• Completions and diagnostics for a supertype's subtypes
  • Requires tree-sitter/tree-sitter#3938
• Completions field names
• Diagnostics for unrecognized nodes
• Diagnostics for referencing undefined capture groups in predicates
• Diagnostics for incorrect syntax
• Diagnostics for impossible patterns
  • Currently not possible without a full (sometimes expensive) run of the query file. This should either be implemented as a user command, or core methods should be exposed to gather pattern information more efficiently
  • For now, this has been made possible due to caching and spawning query scans on a separate, blocking thread. Ideally, in the future, the kinks of query creation will be ironed out so query creation will be quicker, and this logic can be simplified
• Recognize parsers built for WASM
• Document formatting compatible with the nvim-treesitter formatter
• Code cleanup
• Add tests for all* functionality

*All handlers are tested, but core functionality like language loading will be more complicated, and does not yet have test coverage.

Packaging

• homebrew (it's complicated)
• nixpkgs
• mason.nvim
• AUR

And others?

References

Many thanks to @lucario387, and the asm-lsp, jinja-lsp, beancount-language-server, and helix-editor projects for the amazing code that I took inspiration from!