Weaver for Apache Thrift
Linter, Formatter, LSP Server and a VS Code Extension
Weaver for Apache Thrift helps you write and format Apache Thrift IDL files.
Note
Weaver for Apache Thrift is an independent project for Apache Thrift tooling. Apache Thrift is a trademark of The Apache Software Foundation. Repository names, module paths, and extension identifiers currently use thrift-weaver.
It has three parts:
thriftfmt: a safe formatter for.thriftfilesthriftlint: a linter for.thriftfilesthriftls: an LSP server for editors.- a VS Code extension with syntax highlighting and LSP support.
It is made for daily editor use. It keeps comments. It stays stable. It can handle broken or half-written files while you type.
All three binaries are pure Go (CGO_ENABLED=0) and embed the Apache Thrift grammar wasm artifact. No external .wasm file is required at runtime.
Important
Read RFC 0001 before code changes. If behavior or policy changes, update the RFC in the same PR.
- One stack for CLI and editor use.
- Safe mode: if format is not safe, the tool returns an error.
Install the extension from a Marketplace:
Download the VSIX from the latest GitHub release. Open the Command Palette and select "Extensions: Install from VSIX...", then open the file you just downloaded.
- Go (pinned in
mise.toml). - Node.js and npm (for the VS Code extension).
git clone https://github.com/kpumuk/thrift-weaver.git
cd thrift-weaver
mise trust
mise install
mise exec lefthook -- lefthook installBuild the CLIs:
go build -o thriftfmt ./cmd/thriftfmt
go build -o thriftlint ./cmd/thriftlint
go build -o thriftls ./cmd/thriftlsgo install github.com/kpumuk/thrift-weaver/cmd/thriftfmt@latest
go install github.com/kpumuk/thrift-weaver/cmd/thriftlint@latest
go install github.com/kpumuk/thrift-weaver/cmd/thriftls@latestFor stable installs, use a version tag, not @latest.
Common commands:
thriftfmt path/to/file.thrift
thriftfmt --write path/to/file.thrift
thriftfmt --check path/to/file.thrift
thriftfmt --stdin --assume-filename foo.thrift < input.thrift
thriftfmt --range 120:240 path/to/file.thriftMain flags:
--write,-w: write in place.--check: non-zero exit when the file would change.--stdin: read source from stdin.--stdout: force stdout output.--assume-filename: file name used in parser context and errors.--line-width: preferred max line width (default100).--range start:end: byte range, half-open.--debug-tokens,--debug-cst: debug dumps.
Exit codes:
0: success.1:--checkfound changes.2: unsafe to format.3: internal or usage error.
Warning
thriftfmt refuses unsafe formatting and reports errors. It does not guess.
Common commands:
thriftlint path/to/file.thrift
thriftlint --stdin --assume-filename foo.thrift < input.thrift
thriftlint --format json path/to/file.thriftMain flags:
--stdin: read source from stdin.--assume-filename: file name used in parser context and diagnostics.--format:text(default) orjson.
Exit codes:
0: no lint or parser diagnostics.1: diagnostics were found.3: internal or usage error.
thriftls is a stdio LSP server. Your editor starts it.
Current features:
- Live text sync.
- Errors as you type.
- Full-file lint diagnostics on open/save and debounced full-file lint on change.
- Document formatting and range formatting.
- Document symbols.
- Folding ranges.
- Selection ranges.
- Semantic tokens (
textDocument/semanticTokens/full).
Current built-in lint rules:
- explicit field IDs required
- explicit field IDs unique within the same containing field list
- field names unique within the same containing field list
- unqualified local type references must resolve, including typedef base types and container inner types
onewayfunctions must returnvoidand must not declarethrows- unqualified local
throwstypes must resolve to exceptions - unqualified local
service extendstargets must resolve to services - deprecated field
xsd_optional - deprecated field
xsd_nillable - deprecated field
xsd_attrs - deprecated struct/exception
xsd_all requiredfields insideunion- negative explicit enum values
Runtime notes:
didChangeuses incremental reparsing when edit eligibility checks pass; otherwise it falls back to a full reparse for that version.- Lint on change is currently full-file only. Changed-range lint is experimental and not enabled in the normative path.
- Semantic lint currently resolves only unqualified names declared in the current document. Dotted include-qualified references are skipped until cross-file indexing exists.
- There is no parser backend toggle. The supported runtime path is the embedded wasm parser.
The extension lives in editors/vscode.
Build for local development:
npm --prefix editors/vscode ci
npm --prefix editors/vscode run compilePackage a .vsix:
npm --prefix editors/vscode run packageKey settings:
thrift.server.path.thrift.server.args.thrift.format.lineWidth.thrift.trace.server.thrift.managedInstall.enabled.thrift.managedInstall.manifestUrl.thrift.managedInstall.allowInsecureHttp.
Managed install is on by default. If it fails and thrift.server.path is set, the extension uses that path.
- Formatter defaults: line width
100, indent2spaces, max blank lines2. - Mixed newline files are normalized to the main style (
LForCRLF) with an info message. - Invalid UTF-8 input is refused for formatting.
Start with the RFC, then code.
Daily commands:
mise run fmt
mise run lint
mise run test
mise run ciIf you change behavior or policy, update RFC 0001 in the same PR.
cmd/: CLI entry points (thriftfmt,thriftlint,thriftls).internal/: core engine packages (text,lexer,syntax,format,lsp).grammar/tree-sitter-thrift/: Apache Thrift grammar and generated parser assets.editors/vscode/: VS Code extension client.testdata/: formatter fixtures, LSP scenarios, and corpus files.docs/: RFCs, architecture notes, user guide, and release policy.