Thrift Support for VS Code and CLI

English | 简体中文

Apache Thrift IDL tooling built on one shared language core, delivered through a VS Code extension for interactive development and a CLI for automation and CI/CD.

Thrift diagnostics and formatting preview

For development details, see DEVELOPMENT.md. For configuration keys, see docs/settings-reference.md. For supported versions and vulnerability reporting, see SECURITY.md.

Choose Your Interface

Interface	Best for	Main capabilities	Install
VS Code extension	Interactive authoring and review	Highlighting, completion, diagnostics, navigation, formatting, rename, refactors, and hierarchy views	Search for Thrift Support in VS Code, or install from VS Marketplace / Open VSX
`thrift-support` CLI	CI/CD, pre-commit checks, scripts, and editor-independent workflows	Whole-file and line-range formatting, diagnostics, AST output, and symbol listing	`npm install --save-dev thrift-support`

Both interfaces reuse @tanzz/thrift-core for Thrift parsing and language behavior. In particular, VS Code Format Selection and CLI format --range share the same formatting-context logic.

🚀 VS Code Extension

Syntax Highlighting

Full Thrift syntax coverage: keywords, data types, strings, comments, numeric literals
Supports all primitive and container types (including uuid)
Smart token coloring for better readability

Code Formatting

Document formatting: format the entire Thrift file with one command
Selection formatting: format only the selected text
Smart alignment: align field types, field names, and comments
Configurable: indentation, line length, and more formatting rules

Go to Definition: jump to type definitions quickly
Include resolution: follow include statements across files
Workspace search: find definitions across the workspace

Editor Semantic Features

Semantic Tokens: AST-based full-document VS Code Semantic Tokens for types, fields, enums, services, methods, constants, and related symbols. Incremental semantic token edits are not implemented.
Call Hierarchy: incoming/outgoing calls for service and interaction methods.
Type Hierarchy: full service extends chains, typedef alias chains, and top-level items for struct/union/enum/exception/interaction. Standard Thrift IDL does not support struct/exception inheritance, so non-standard struct ... extends ... input is not documented as an inheritance relationship.

Code Refactoring

Identifier rename (F2): updates references across files with basic conflict checks
Extract type (typedef): infer type from selection or current field and generate a typedef
Move type to file: move struct/enum/service/typedef into a new .thrift file and auto-insert an include

Advanced Features

Stream: supports experimental stream syntax
Sink: supports experimental sink syntax
Interaction: supports experimental interaction syntax

⚡ Performance

Incremental parsing: only re-parses affected blocks on edit; cache hits respond in <5ms
Smart caching: LRU-K multi-tier cache with memory-pressure eviction, covering AST, diagnostics, definitions, symbols, and more
Concurrent analysis: up to 3 files analysed simultaneously (3× improvement over earlier versions), with debounce/throttle to prevent UI jank
Large-file support: files >10 000 lines are split at top-level block boundaries for formatting, avoiding O(n²) alignment scans
CI performance gate: built-in benchmarks enforce <500ms parse and <500ms format for 1000-line files; failures block CI

See PERFORMANCE.md for tuning tips and CI integration details.

📖 Advanced Feature Docs

See advanced features for details about stream, sink, interaction, and other experimental syntax.

🔐 Trust and Release Posture

MIT licensed, free extension published under the tanzz namespace on Visual Studio Marketplace and Open VSX.
No telemetry or analytics collection is implemented in the current source.
Release automation uses release-please; a published GitHub Release triggers VSIX packaging, Visual Studio Marketplace publishing, Open VSX publishing, and npm CLI publishing.
CI gates cover lint, build, test, coverage, CLI dogfood, package smoke, and performance assertions.
See docs/release-verification.md and SECURITY.md for the current verification and security model.

🖥️ CLI Tool

The standalone npm package thrift-support exposes the shared Thrift engine to CI/CD pipelines, pre-commit hooks, shell scripts, and other editors. See the complete CLI reference for every option.

Install

npm install -g thrift-support
# or install locally in your project
npm install --save-dev thrift-support

Commands

# Check formatting (recommended for CI)
thrift-support format --check src/**/*.thrift

# Format and write back to files
thrift-support format --write src/

# Format only lines 12 through 18 (1-based, inclusive)
thrift-support format --range 12:18 src/example.thrift

# Check or write only that range
thrift-support format --check --range 12:18 src/example.thrift
thrift-support format --write --range 12:18 src/example.thrift

# Read from stdin and output to stdout
echo "struct Foo{1:i32 id}" | thrift-support format --stdin
echo "struct Foo{1:i32 id}" | thrift-support format --stdin --range 1:1

# Run diagnostics (syntax + semantic rules)
thrift-support lint src/**/*.thrift
thrift-support lint --severity error --json src/**/*.thrift

# Parse and output AST (JSON)
thrift-support parse --stdin < myfile.thrift

# List defined symbols
thrift-support symbols --json src/my.thrift

--range changes only the selected lines; indentation context is derived from the preceding lines. This matches the extension's Format Selection behavior because both paths call the shared core implementation.

Configuration

Create a .thriftrc.json in your project root; the CLI searches upward automatically:

{
    "format": {
        "indentSize": 4,
        "trailingComma": "add",
        "alignTypes": true,
        "maxLineLength": 100
    },
    "lint": {
        "severity": "error"
    }
}

Exit Codes

Code	Meaning
0	Success
1	Lint errors (or `--check` found unformatted files)
2	Usage error
3	Internal error

📦 Install the VS Code Extension

Open VS Code
Open the Extensions view (Ctrl+Shift+X)
Search for "Thrift Support"
Click Install

🧭 Project Structure

For a fuller agent-readable directory map and validation matrix, see docs/PROJECT_MAP.md.

packages/core/src/: pure Thrift parsing, formatting, diagnostics, cache, and shared utilities
packages/vscode/src/: VS Code extension entrypoint, providers, commands, and configuration bridge
packages/cli/src/: CLI argument parsing, config loading, and format/lint/symbols commands
syntaxes/: TextMate syntax grammar
tests/src/: canonical Mocha test suite
tests/cli/: CLI integration and unit tests
tests/perf/: performance benchmarks
tests/debug/: manual reproduction and debug scripts
test-files/ / tests/src/**/test-files/: fixtures
language-configuration.json: VS Code bracket, comment, and language configuration

🔧 VS Code Extension Usage

Formatting

Format Document: Ctrl+Shift+I (Windows/Linux) or Cmd+Shift+I (macOS)
Format Selection: select text, then Ctrl+K Ctrl+F (Windows/Linux) or Cmd+K Cmd+F (macOS)
Command Palette:
- Thrift: Format Document
- Thrift: Format Selection

Selection formatting and CLI format --range use the same core formatting-context implementation; use the editor command interactively and the CLI form in automation.

Go to Definition: F12 or Ctrl+Click
Peek Definition: Alt+F12

Semantic Tokens, Call Hierarchy, and Type Hierarchy

Semantic tokens are generated from the AST for the whole document. They cover struct/union/exception, enum/member, service/interaction, method, field, typedef, const, namespace, and type-reference tokens; provideDocumentSemanticTokensEdits is not implemented.
Call hierarchy shows service/interaction method calls and override relationships.
Type hierarchy shows complete service extends parent chains, direct child services, and typedef alias parent chains.
struct, union, exception, enum, and interaction appear as top-level type items, but no inheritance semantics are claimed beyond service extends and typedef aliasing.

Diagnostics

Syntax pairing and unclosed checks (syntax.unmatchedCloser / syntax.unclosed)
Type checks: unknown types and typedef base (type.unknown / typedef.unknownBase)
Container inner type checks: validate inner types of list/map/set
Enum constraints: values must be non-negative integers (enum.negativeValue / enum.valueNotInteger)
Default value type checks: including base types and UUID string format (value.typeMismatch)
Service constraints:
- oneway must return void and must not declare throws (service.oneway.returnNotVoid / service.oneway.hasThrows)
- throws must reference known exception types (service.throws.unknown / service.throws.notException)
- extends must target a service type (service.extends.unknown / service.extends.notService)
Robust default value extraction improvements:
- Ignore '=' inside field annotations so it won’t be treated as the start of a default value
- set default values accept either [] or {} with bracket-aware element checks

Note: Diagnostics update in real-time during editing and on save. You can review them in VS Code’s “Problems” panel.

Code Refactoring

Identifier rename (F2): cross-file reference updates with basic conflict checks
Extract type (typedef): infer type from selection/current field and generate a typedef
Move type to file: move struct/enum/service/typedef into a new .thrift file and auto-insert an include

Rename and Refactor

Rename symbol: select an identifier and press F2, or use Rename Symbol from the context menu
Command Palette:
- Thrift: Extract type (typedef)
- Thrift: Move type to file...
- Thrift: Show Performance Report
- Thrift: Clear Performance Data
- Thrift: Show Memory Report
- Thrift: Force Garbage Collection
Quick Fix/Refactor lightbulb: refactoring code actions appear where applicable

Configuration Options

Configure these options in VS Code settings:

{
  "thrift.format.trailingComma": "preserve", // "preserve" | "add" | "remove"
  "thrift.format.alignTypes": true,
  "thrift.format.alignNames": true,
  "thrift.format.alignAssignments": true,
  "thrift.format.alignStructDefaults": false,
  "thrift.format.alignAnnotations": true,
  "thrift.format.alignComments": true,
  "thrift.format.indentSize": 4,
  "thrift.format.maxLineLength": 100,
  "thrift.format.collectionStyle": "preserve" // "preserve" | "multiline" | "auto"
}

alignAssignments: master switch for struct field = and enum = / value alignment. If it is not set explicitly, each alignment family keeps its own default behavior.
alignStructDefaults: controls struct default-value = alignment only. It is independent from alignAssignments.

📐 Language Spec Alignment (IDL 0.24)

Apache Thrift IDL 0.24 lists uuid as a built-in base type; this extension treats uuid as a primitive everywhere it would otherwise resolve user-defined types.
Alignment touches the following components:
- Diagnostics: uuid is recognized as a primitive type
- Definition Provider: uuid is excluded from user-defined symbol navigation
- Syntax Highlighting: uuid is included in the primitive type regex
Reference: Apache Thrift IDL — https://thrift.apache.org/docs/idl

📝 Formatting Example

Before

struct User{
1:required string name
2:optional i32 age,
3: string email // user email
}

After

struct User {
    1:   required string name,
    2:   optional i32    age,
    3:   string          email  // user email
}

🐛 Issues

Check TROUBLESHOOTING.md for common solutions first.

If the problem persists:

Create an issue in the GitHub repository
Include details:
- VS Code version
- Extension version
- Steps to reproduce
- Expected behavior
- Actual behavior
Provide a minimal reproducible example when possible

🤝 Contributing

We welcome contributions!

How to Contribute

Report bugs and propose features
Suggest new features and improvements
Open pull requests with clear descriptions
Help improve documentation

Development

Development prerequisites, build/test steps, and CI/CD details have been moved to DEVELOPMENT.md.

Pull Requests

Create a feature branch: git checkout -b feature/your-feature
Commit changes: git commit -m "Add your feature"
Push branch: git push origin feature/your-feature
Open a Pull Request

📄 License

MIT License.

🔄 Changelog

See the complete changelog:

Local: CHANGELOG.md
GitHub: https://github.com/tzzs/vsce-thrift-support/blob/master/CHANGELOG.md

📚 Developer Docs

Document	Description
docs/README.md	Documentation index and freshness signals
docs/PROJECT_MAP.md	Directory ownership, generated outputs, and validation matrix
DEVELOPMENT.md	Environment setup, build, test, and release workflow
ARCHITECTURE.md	Cache system, incremental parse/format, concurrency details
PERFORMANCE.md	Tuning tips, CI integration, memory management
TROUBLESHOOTING.md	Common issues and solutions

🔗 Links

GitHub Repository: https://github.com/tzzs/vsce-thrift-support
Issues: https://github.com/tzzs/vsce-thrift-support/issues
Discussions: https://github.com/tzzs/vsce-thrift-support/discussions
CI Status: https://github.com/tzzs/vsce-thrift-support/actions/workflows/ci.yml
Publish Status: https://github.com/tzzs/vsce-thrift-support/actions/workflows/publish.yml
Changelog: https://github.com/tzzs/vsce-thrift-support/blob/master/CHANGELOG.md
Apache Thrift IDL: https://thrift.apache.org/docs/idl
Thrift Type system: https://thrift.apache.org/docs/types

Thrift Support

tanzz

Thrift Support for VS Code and CLI

Choose Your Interface

🚀 VS Code Extension

Syntax Highlighting

Code Formatting

Code Navigation

Editor Semantic Features

Code Refactoring

Advanced Features

⚡ Performance

📖 Advanced Feature Docs

🔐 Trust and Release Posture

🖥️ CLI Tool

Install

Commands

Configuration

Exit Codes

📦 Install the VS Code Extension

🧭 Project Structure

🔧 VS Code Extension Usage

Formatting

Code Navigation

Semantic Tokens, Call Hierarchy, and Type Hierarchy

Diagnostics

Code Refactoring

Rename and Refactor

Configuration Options

📐 Language Spec Alignment (IDL 0.24)

📝 Formatting Example

Before

After

🐛 Issues

🤝 Contributing

How to Contribute

Development

Pull Requests

📄 License

🔄 Changelog

📚 Developer Docs

🔗 Links