tree-sitter-groovy
Tree-sitter grammar for Apache Groovy — the JVM scripting language used in Jenkins pipelines, Gradle build files, and Spock test specifications.
Published as: @dekobon/tree-sitter-groovy on npm,
dekobon-tree-sitter-groovy on crates.io and PyPI,
github.com/dekobon/tree-sitter-groovy as a Go module / Swift package.
The unscoped name belongs to the upstream comparison grammar linked
below; the C library (no naming conflict) still ships as
libtree-sitter-groovy.
This grammar is purpose-built for Groovy (it does not extend the
tree-sitter-java grammar). It synthesises the best ideas from the
two existing community grammars while closing every operator and
statement gap they left open:
amaanq/tree-sitter-groovy— clean precedence table and shebang handling, but mis-shapes Groovy-specific syntax (Elvis?:, safe navigation?., spread operators, regex=~/==~, traits, exclusive ranges, identity===/!==, spaceship<=>, etc.) as Java-shaped parse trees.murtaza64/tree-sitter-groovy— purpose-built for Groovy, broad operator coverage and slashy strings, but has open bugs around empty block comments, multi-catch, multi-assignment, enums, switch-arrow, and apipeline-at-EOF constraint.
The full design is in SPECIFICATION.md.
Status
Fully functional Groovy 2.x--4.x parser with complete operator coverage, GString interpolation, generics, closures, command chains, and six language bindings. See Known limitations for deferred items.
Operator coverage
Every Groovy operator emits a distinct named node so downstream
tooling can identify each by node kind alone — no MISSING-child
inspection, no tree-shape heuristics. This is the contract that
closes
dekobon/big-code-analysis#246
(Elvis short-circuit counting) and
dekobon/big-code-analysis#247
(all Groovy-specific operator gaps).
| Category | Operators |
|---|---|
| Arithmetic | + - * / % ** ++ -- |
| Relational | < <= > >= == != <=> (spaceship) |
| Identity | === !== |
| Regex | =~ (find) ==~ (match) |
| Logical | && || ! ==> (implication) |
| Bitwise | & | ^ ~ << >> >>> |
| Conditional | ? : (ternary) ?: (Elvis) |
| Assignment | = += -= *= /= %= **= <<= >>= >>>= &= ^= |= ?= (Elvis assign) |
| Range | .. ..< <.. <..< |
| Member access | . ?. ??. (safe chain dot) *. (spread-dot) .& (method pointer) .@ (direct field) :: (method reference) |
| Subscript | [] ?[] (safe index) |
| Spread | *args *: (spread-map) |
| Membership | in !in instanceof !instanceof |
| Coercion | as |
Editor support
Tree-sitter queries (queries/groovy/highlights.scm,
folds.scm, indents.scm, injections.scm) are provided for editor
integration. Slashy and dollar-slashy string bodies inject as regex
for nested regex highlighting.
Recognized file extensions: .groovy, .gradle, .gvy, .gy, and
Jenkinsfile.
Filetype detection
The repo ships ftdetect/groovy.lua and ftplugin/groovy.lua for
Neovim. Neovim's built-in filetype detection already maps *.groovy,
*.gradle, and the bare filename Jenkinsfile to filetype groovy;
the shipped ftdetect/groovy.lua fills the gaps by mapping:
*.gvyand*.gy— declared intree-sitter.jsonbut not in Neovim's defaults.*.jenkinsfile— uncommon (the canonical name isJenkinsfile) but declared intree-sitter.jsonand used by some teams as an editor-detection hook.Jenkinsfile.*variants (Jenkinsfile.ci,Jenkinsfile.release, …) — common in repos with multiple pipelines, not handled by Neovim's built-in detection.
The existing ftplugin/groovy.lua then calls vim.treesitter.start().
Highlighting only renders once the parser binary and
queries/groovy/highlights.scm are registered with nvim-treesitter
(or equivalent) — without that, the start() call is a no-op and the
buffer falls back to non-treesitter highlighting.
For files that don't match any of those (e.g. a hand-named
build-pipeline with no extension), opt in with one of:
-
Modeline at the top of the file:
// vim: set filetype=groovy : -
Per-project autocmd in
.nvim.lua(sourced after:cdinto the project via Neovim's'exrc'). Notevim.fn.getcwd()is evaluated when the autocmd is defined, so this snippet belongs in a per-project config, not a globalinit.lua:vim.api.nvim_create_autocmd({ "BufRead", "BufNewFile" }, { pattern = vim.fn.getcwd() .. "/jenkins/*", callback = function() vim.bo.filetype = "groovy" end, })
Other editors follow the same pattern: rely on built-in detection for the common extensions and override per-directory or via a header comment for the rest.
Building
npm install
make build
make test
Bindings
Available bindings: C, Go, Node.js, Python, Rust, Swift. See
bindings/ for binding-specific READMEs and tests.
For Rust consumers:
[dependencies]
dekobon-tree-sitter-groovy = "0.1"
tree-sitter = "0.25"
let mut parser = tree_sitter::Parser::new();
let language = dekobon_tree_sitter_groovy::LANGUAGE;
parser.set_language(&language.into()).expect("Error loading Groovy parser");
let tree = parser.parse(source, None).unwrap();
Known limitations
These are documented in detail in
docs/divergences-from-spec.md.
- Groovy 5 contextual keywords (
val,async,await,defer) are not yet exposed as keyword tokens. They parse as plain identifiers, matching Groovy 2.x--4.x compiler behavior. - Typed local declarations require an initializer --
String xis ambiguous withString(x)(method call). UseString x = ...ordef xinstead. - Leading-operator line continuation --
a\n+ bgreedily joins asa + brather than splitting into two statements. Idiomatic Groovy places continuation operators at the end of the previous line. - A
{afternew T(...)is always an anonymous class body -- Groovy instead calls a closure on the new object when the{starts a later line (outside parentheses and brackets) or cannot be a class body, sonew ArrayList()\n{ list.add(1) }andnew T() { x -> x }get anERRORinside aclass_body. Writenew ArrayList().call { ... }to keep the call. - A
{ ... }straight after a field with no initializer is an instance initializer block --int x { ... }parses with noERROR. A record's compact constructor (public Name { ... }), which is unsupported, takes the same reading. After a field with an initializer a next-line{is that expression's trailing closure, as in Groovy: end the field with;to get an initializer block. sealedandtraitare keywords where a class member can start -- a field namedsealedortraitis anERRORwhen it follows a modifier (private boolean sealed) or opens the member (static trait = 1).boolean sealedandString trait, with no modifier, parse, and so does an enum constant with either name (enum E { trait, sealed }).recordis not affected: it is a keyword only directly before a record header (record Name(), soprivate Record recordandrecord.key()parse.- A member after an enum's trailing comma must start with a
modifier,
defor a keyword -- Groovy up to 4.x takes any member there.A,followed byString xor byE() { }is anERROR(#97). - Parameter modifiers have one order -- annotations, then
final, thendef,varor a type.def String x,final @A xand a varargs parameter with no type (... xs) are anERROR(#98). - A line break does not end a statement -- a newline is whitespace
to the grammar. Most code is unaffected, because the next token
cannot continue the statement. Known cases that read wrongly with no
ERROR: a bare name followed by a literal on the next line is one parenthesis-free call (#90); a field with a modifier and no type followed by a typed method is a typed field and a constructor (#96); and inside brackets,(a)followed by a line that starts with-,+or(is not the cast Groovy reads (#99). - A method with modifiers and no return type is a constructor --
static f() { }in a class body is aconstructor_declaration, andabstract m()is anERROR(#91). - Annotations come before modifiers --
private @Autowired Foo fooandpublic @interface X { }are anERROR(#92).
Contributing
See CONTRIBUTING.md for how to build, test, and
submit changes. AGENTS.md covers project conventions
(commit messages, versioning, validation gates) and
SPECIFICATION.md is the authoritative grammar
design document.
Acknowledgements
We are grateful for the work done in the murtaza64/tree-sitter-groovy and amaanq/tree-sitter-groovy. These projects served as inspiration for some of the approaches in this project
License
Dual-licensed under Apache License 2.0 or MIT.
Metadata
Release files for dekobon-tree-sitter-groovy 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dekobon_tree_sitter_groovy-0.6.0.tar.gz | 539.8 kB | With provenance | Details for dekobon_tree_sitter_groovy-0.6.0.tar.gz |
Built distributions (wheels)
Total release size: 1.5 MB
Release files / dekobon_tree_sitter_groovy-0.6.0.tar.gz
| Download URL | dekobon_tree_sitter_groovy-0.6.0.tar.gz |
|---|---|
| Size | 539.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0ac17d4c135fec942e4149eb0ea619a49609cc9ccd93ad1e99deae19f8070be7
|
|
BLAKE2b-256 checksum How to use checksums |
964a849c0473fae9a440d67420880fd5496dd25be97b6fe68205a8ed6530ed11
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / dekobon_tree_sitter_groovy-0.6.0-cp311-abi3-win_amd64.whl
| Download URL | dekobon_tree_sitter_groovy-0.6.0-cp311-abi3-win_amd64.whl |
|---|---|
| Size | 173.7 kB |
| Tags | CPython 3.11 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
c260705c9532d26df32fd26c84fe4f7957f84fd851c47e27c3c8138ae96a1dd1
|
|
BLAKE2b-256 checksum How to use checksums |
f981fc652903cab2f687741ca81aeacd22835461d348b81e6cc68504635c6716
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / dekobon_tree_sitter_groovy-0.6.0-cp311-abi3-win32.whl
| Download URL | dekobon_tree_sitter_groovy-0.6.0-cp311-abi3-win32.whl |
|---|---|
| Size | 174.1 kB |
| Tags | CPython 3.11 Windows x86-32 abi3 |
|
SHA-256 checksum How to use checksums |
d8c6ecbdc78d460c9406bf265d58d1a7bf379863ce45305fbc7ab3f647255d2c
|
|
BLAKE2b-256 checksum How to use checksums |
cd3da4ffc97c38b940879ce1a2be7640fc605b79625e50e13b3e1c916e502db5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / dekobon_tree_sitter_groovy-0.6.0-cp311-abi3-musllinux_1_2_x86_64.whl
| Download URL | dekobon_tree_sitter_groovy-0.6.0-cp311-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 208.7 kB |
| Tags | CPython 3.11 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
083cd8d038538da76bfb5f8c08a2adc89afb1241330d23f7b0a5f1e1b18ee010
|
|
BLAKE2b-256 checksum How to use checksums |
f3a71625bbb37ba03d3642f7b01fd3414b83c2663663727dfefdcc0c0451e608
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / dekobon_tree_sitter_groovy-0.6.0-cp311-abi3-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | dekobon_tree_sitter_groovy-0.6.0-cp311-abi3-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 210.3 kB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
f816cda14cd14a2d9605cf874d82506d7f321f765d7f34cc37b5d133e5b1236d
|
|
BLAKE2b-256 checksum How to use checksums |
d6a32b19450f685a17e6507079d57ff063c2e324e942469f61ef4815fc201c7a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / dekobon_tree_sitter_groovy-0.6.0-cp311-abi3-macosx_11_0_arm64.whl
| Download URL | dekobon_tree_sitter_groovy-0.6.0-cp311-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 180.0 kB |
| Tags | CPython 3.11 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
e03c32ddfc9daa63a898bd4618e20a9ba3b93669a966e645edcba8db8eac23ec
|
|
BLAKE2b-256 checksum How to use checksums |
3fd3ac3310e149f9b46c6c653ad26c135e49524f9f8c2dbf3fb5480620e2c95e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logSecurity for dekobon-tree-sitter-groovy 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 6 files in this release have been uploaded with provenance metadata.
Attestation for dekobon_tree_sitter_groovy-0.6.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.