https://github.com/albertocavalcante/groovy-parser-go
Lossless Groovy parser in pure Go -- IDE-quality CST with error recovery (no CGO, no tree-sitter)
https://github.com/albertocavalcante/groovy-parser-go
cst go gradle groovy parser syntax-tree
Last synced: about 18 hours ago
JSON representation
Lossless Groovy parser in pure Go -- IDE-quality CST with error recovery (no CGO, no tree-sitter)
- Host: GitHub
- URL: https://github.com/albertocavalcante/groovy-parser-go
- Owner: albertocavalcante
- License: mit
- Created: 2026-02-15T09:11:46.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-05-22T19:31:56.000Z (about 2 months ago)
- Last Synced: 2026-07-04T17:22:09.010Z (8 days ago)
- Topics: cst, go, gradle, groovy, parser, syntax-tree
- Language: Go
- Size: 611 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# groovy-parser-go
[](https://github.com/albertocavalcante/groovy-parser-go/actions/workflows/ci.yml)
[](https://sonarcloud.io/summary/new_code?id=albertocavalcante_groovy-parser-go)
[](https://sonarcloud.io/summary/new_code?id=albertocavalcante_groovy-parser-go)
[](https://pkg.go.dev/github.com/albertocavalcante/groovy-parser-go)
[](https://goreportcard.com/report/github.com/albertocavalcante/groovy-parser-go)
[](LICENSE)
[](go.mod)
A Groovy syntax parser written in pure Go. No CGO, no tree-sitter, no external C dependencies.
The goal is an IDE-quality parser that produces a complete, lossless concrete syntax tree (CST) for any input — including incomplete or invalid Groovy code. It should handle partial files, mid-typing states, and syntax errors gracefully, always returning a usable tree rather than bailing on the first error.
## Motivation
Existing options for parsing Groovy outside the JVM are limited:
- **tree-sitter-groovy** requires CGO bindings, complicating builds and cross-compilation.
- **ANTLR4** can target Go, but the official Groovy grammar is tightly coupled to Java through embedded semantic predicates and custom lexer logic.
- **No standalone pure-Go Groovy parser exists.**
This project aims to fill that gap with a parser that can be used in Go-native tooling — linters, formatters, language servers, static analysis, Gradle file processing — without pulling in C toolchains or JVM dependencies.
## Current Status
**Active development.** The lexer, CST, and parser foundations are implemented with error recovery, fuzz testing, and lossless round-trip verification.
## Design Documents
The [`docs/design/`](docs/design/) directory contains research and design documents that informed the architecture:
- [01-antlr-experiment.md](docs/design/01-antlr-experiment.md) — ANTLR4 experiment plan for building a reference oracle
- [02-handwritten-parser-plan.md](docs/design/02-handwritten-parser-plan.md) — Full architecture plan for the hand-written Pratt/recursive descent parser
- [03-parsing-approaches-deep-dive.md](docs/design/03-parsing-approaches-deep-dive.md) — Comprehensive comparison of nine parsing techniques for Groovy + Go
## Implementation Plan
The [`plan/`](plan/) directory contains the detailed, phased implementation plan:
| Phase | Title | Focus |
|---|---|---|
| [000](plan/000-overview.md) | Master Plan | TDD strategy, dependency graph, DSL strategy, quality gates |
| [001](plan/001-project-setup.md) | Project Setup | Go module, CI, snapshot test framework, source positions |
| [002](plan/002-lexer-foundation.md) | Lexer Foundation | Tokens, trivia, keywords, numbers, operators, single-quoted strings |
| [003](plan/003-cst-tree-builder.md) | CST & Tree Builder | Green/red tree nodes, builder API, walking, pretty-print |
| [004](plan/004-parser-expressions.md) | Expressions | Pratt parser, all binary/unary/ternary ops, method calls, indexing |
| [005](plan/005-parser-statements.md) | Statements | Control flow, blocks, variable declarations, error recovery |
| [006](plan/006-strings-interpolation.md) | Strings & Interpolation | All 6 string types, GString `${}`, lexer mode stack |
| [007](plan/007-closures-collections.md) | Closures & Collections | Closures, trailing closures, lists, maps, ranges |
| [008](plan/008-declarations-types.md) | Declarations | Classes, traits, enums, methods, generics, annotations |
| [009](plan/009-advanced-expressions.md) | Advanced Expressions | Command expressions, slashy strings, safe nav, spread |
| [010](plan/010-error-recovery.md) | Error Recovery | Fuzz testing, mid-typing scenarios, synchronization sets |
| [011](plan/011-corpus-testing.md) | Corpus Testing | Gradle, Jenkins, Spock, Groovy test suite validation |
| [012](plan/012-api-extensibility.md) | API & Performance | Public API, visitor/walker, CLI tool, benchmarks |
Development follows strict TDD — every grammar construct is test-first with snapshot testing, round-trip verification, and error recovery cases.
## Design Principles
- **Always produce a tree.** The parser never panics or bails. Invalid input produces error nodes in the tree, not crashes.
- **Lossless.** Every byte of input is represented in the CST. Round-tripping `tree.Text()` reproduces the original source exactly — same whitespace, same comments, same blank lines.
- **Trivia-preserving.** Whitespace, comments (line, block, Groovydoc), newlines, and shebangs are captured as trivia attached to tokens using the Roslyn leading/trailing trivia model. This enables OpenRewrite-style lossless code transformations: modify a single node and everything around it stays exactly as it was.
- **Pure Go, zero dependencies.** No CGO, no build tags, no external C/C++ dependencies, no third-party Go modules. The only import paths are `github.com/albertocavalcante/groovy-parser-go/...` and the Go standard library. `go build` and done.
- **Go 1.25 baseline.** The module targets Go 1.25 as the minimum version, giving access to generics, fuzz testing, range-over-func iterators, and the `slices`/`maps` packages — without chasing nightly or unstable releases.
- **Syntax only.** No type resolution, no classpath scanning, no semantic analysis. Just the syntax tree.
## Development
Requires [Go 1.25+](https://go.dev/dl/) and [just](https://github.com/casey/just).
```bash
# One-time setup (installs git hooks, syncs tools)
just setup
# Run tests (via gotestsum)
just test
# Run linter (via golangci-lint from tools.go.mod)
just lint
# Full CI gate (format + vet + lint + test)
just check
# See all available recipes
just
```
Dev tools (`gotestsum`, `golangci-lint`) are managed in `tools.go.mod` — a separate module
file that keeps them out of the main dependency tree. No global tool installs needed; Go
downloads them automatically.
## License
[MIT](LICENSE)