thrift-weaver

module
v0.3.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 5, 2026 License: MIT

README

Logo
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 .thrift files
  • thriftlint: a linter for .thrift files
  • thriftls: 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.

Why Use Weaver for Apache Thrift

  • One stack for CLI and editor use.
  • Safe mode: if format is not safe, the tool returns an error.

Usage

Preferred method of installation

Install the extension from a Marketplace:

Manual method for installation

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.

Local Installation

Needs

  • 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 install

Build the CLIs:

go build -o thriftfmt ./cmd/thriftfmt
go build -o thriftlint ./cmd/thriftlint
go build -o thriftls ./cmd/thriftls

Quick Install With go install

go 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@latest

For stable installs, use a version tag, not @latest.

Use thriftfmt

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.thrift

Main 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 (default 100).
  • --range start:end: byte range, half-open.
  • --debug-tokens, --debug-cst: debug dumps.

Exit codes:

  • 0: success.
  • 1: --check found changes.
  • 2: unsafe to format.
  • 3: internal or usage error.

[!WARNING] thriftfmt refuses unsafe formatting and reports errors. It does not guess.

Use thriftlint

Common commands:

thriftlint path/to/file.thrift
thriftlint --stdin --assume-filename foo.thrift < input.thrift
thriftlint --format json path/to/file.thrift

Main flags:

  • --stdin: read source from stdin.
  • --assume-filename: file name used in parser context and diagnostics.
  • --format: text (default) or json.

Exit codes:

  • 0: no lint or parser diagnostics.
  • 1: diagnostics were found.
  • 3: internal or usage error.

Use thriftls

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
  • oneway functions must return void and must not declare throws
  • unqualified local throws types must resolve to exceptions
  • unqualified local service extends targets must resolve to services
  • deprecated field xsd_optional
  • deprecated field xsd_nillable
  • deprecated field xsd_attrs
  • deprecated struct/exception xsd_all
  • required fields inside union
  • negative explicit enum values

Runtime notes:

  • didChange uses 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.

VS Code Extension

The extension lives in editors/vscode.

Build for local development:

npm --prefix editors/vscode ci
npm --prefix editors/vscode run compile

Package a .vsix:

npm --prefix editors/vscode run package

Key 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.

Config Notes

  • Formatter defaults: line width 100, indent 2 spaces, max blank lines 2.
  • Mixed newline files are normalized to the main style (LF or CRLF) with an info message.
  • Invalid UTF-8 input is refused for formatting.

Contributing

Start with the RFC, then code.

Daily commands:

mise run fmt
mise run lint
mise run test
mise run ci

If you change behavior or policy, update RFC 0001 in the same PR.

Repository Map

  • 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.

More Docs

Directories

Path Synopsis
cmd
thriftfmt command
Package main provides the thriftfmt CLI entry point.
 Package main provides the thriftfmt CLI entry point.
thriftlint command
Package main provides the thriftlint CLI entry point.
 Package main provides the thriftlint CLI entry point.
thriftls command
Package main provides the thriftls CLI entry point.
 Package main provides the thriftls CLI entry point.
grammar
tree-sitter-thrift
Package treesitterthrift provides embedded tree-sitter query assets.
 Package treesitterthrift provides embedded tree-sitter query assets.
internal
format
Package format provides formatter core APIs and primitives for Thrift source formatting.
 Package format provides formatter core APIs and primitives for Thrift source formatting.
grammars/thrift
Package thriftwasm embeds the Thrift tree-sitter wasm artifact in the binary.
 Package thriftwasm embeds the Thrift tree-sitter wasm artifact in the binary.
index
Package index provides workspace indexing for cross-file Thrift analysis.
 Package index provides workspace indexing for cross-file Thrift analysis.
lexer
Package lexer provides a lossless token/trivia lexer for Thrift IDL source.
 Package lexer provides a lossless token/trivia lexer for Thrift IDL source.
lint
Package lint provides syntax-tree based lint diagnostics for thrift source files.
 Package lint provides syntax-tree based lint diagnostics for thrift source files.
lsp
Package lsp implements the thriftls LSP server and shared protocol types.
 Package lsp implements the thriftls LSP server and shared protocol types.
syntax
Package syntax builds a CST-oriented parse result by combining the lossless lexer and tree-sitter parser.
 Package syntax builds a CST-oriented parse result by combining the lossless lexer and tree-sitter parser.
syntax/backend
Package backend defines parser backend abstractions for syntax parsing.
 Package backend defines parser backend abstractions for syntax parsing.
syntax/backend/wasm
Package wasm contains the wasm parser backend wiring surface.
 Package wasm contains the wasm parser backend wiring surface.
syntax/treesitter
Package treesitter wraps parser primitives for Thrift syntax parsing.
 Package treesitter wraps parser primitives for Thrift syntax parsing.
testutil
Package testutil provides shared helpers for repository tests.
 Package testutil provides shared helpers for repository tests.
text
Package text defines source offsets, spans, and position/range types.
 Package text defines source offsets, spans, and position/range types.
scripts
check-perf-gate command
Package main enforces the CI performance gate from a perf-report JSON artifact.
 Package main enforces the CI performance gate from a perf-report JSON artifact.
check-vscode-changelog command
Package main enforces when the VS Code changelog must be updated for a change.
 Package main enforces when the VS Code changelog must be updated for a change.
compose-release-notes command
Package main composes the final GitHub release body from release-please notes and repo policy snippets.
 Package main composes the final GitHub release body from release-please notes and repo policy snippets.
evaluate-perf-policy command
Package main evaluates CI perf-gate policy from the current and previous breach states.
 Package main evaluates CI perf-gate policy from the current and previous breach states.
generate-release-manifest command
generate-release-manifest emits the managed-install manifest for thriftls release artifacts.
 generate-release-manifest emits the managed-install manifest for thriftls release artifacts.
generate-sbom command
Package main generates a CycloneDX SBOM for the current Go module graph.
 Package main generates a CycloneDX SBOM for the current Go module graph.
generate-vscode-release-metadata command
generate-vscode-release-metadata emits release metadata for the packaged VS Code extension.
 generate-vscode-release-metadata emits release metadata for the packaged VS Code extension.
notify-released-prs command
Package main comments on pull requests after a release is published.
 Package main comments on pull requests after a release is published.
perf-report command
Package main runs reproducible parse/format and LSP memory stability measurements for Weaver for Apache Thrift.
 Package main runs reproducible parse/format and LSP memory stability measurements for Weaver for Apache Thrift.
update-vscode-changelog command
Package main rolls the VS Code changelog from Unreleased into a versioned release section.
 Package main rolls the VS Code changelog from Unreleased into a versioned release section.
verify-checksums command
Package main verifies sha256 checksums for release artifacts.
 Package main verifies sha256 checksums for release artifacts.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.