thrift-weaver

module

v0.0.3 Latest Latest Go to latest Published: Feb 27, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/kpumuk/thrift-weaver

Links

Open Source Insights

README ¶

Thrift Weaver for VSCode

thrift-weaver helps you write and format Thrift IDL files.

It has three parts:

thriftfmt: a safe formatter 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.

[!IMPORTANT] Read RFC 0001 before code changes. If behavior or policy changes, update the RFC in the same PR.

Why Use `thrift-weaver`

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:

Visual Studio 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).
A C toolchain (tree-sitter uses cgo).
Node.js and npm (for the VS Code extension).

Setup From Source (recommended)

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 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/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 `thriftls`

thriftls is a stdio LSP server. Your editor starts it.

Current features:

Live text sync.
Errors as you type.
Document formatting and range formatting.
Document symbols.
Folding ranges.
Selection ranges.
Semantic tokens (textDocument/semanticTokens/full).

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.

[!CAUTION] tree-sitter uses cgo. Build and go install need a working C toolchain on your system.

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, thriftls).
internal/: core engine packages (text, lexer, syntax, format, lsp).
grammar/tree-sitter-thrift/: 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 ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
thriftfmt command Package main provides the thriftfmt CLI entry point.	Package main provides the thriftfmt 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 exposes the generated tree-sitter grammar and queries for Thrift IDL.	Package treesitterthrift exposes the generated tree-sitter grammar and queries for Thrift IDL.
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.
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.
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/treesitter Package treesitter wraps go-tree-sitter parser primitives for Thrift syntax parsing.	Package treesitter wraps go-tree-sitter 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
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-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.
perf-report command Package main runs reproducible parse/format and LSP memory stability measurements for Thrift Weaver.	Package main runs reproducible parse/format and LSP memory stability measurements for Thrift Weaver.