SDIF for VS Code

VS Code extension client providing rich language support for the
Semantic Data Interchange Format (SDIF).

Features · Highlighting Architecture · Language Server · Development · Ecosystem

Compact Less repeated structure. Fewer wasted tokens.

Semantic Tables, relations, metadata and intent.

Canonical Stable output for hashing, signing and comparison.

Auditable Designed to be read, reviewed and trusted.

---

Features

• Registers .sdif, .sdif.ai, and .sdif.canon files as SDIF documents.
• Automatically launches the external Rust sdif-lsp language server over stdio when available.
• Uses LSP semantic tokens for structural and editorial highlighting.
• Provides a minimal TextMate fallback for comments, directives, quoted strings, and narrative delimiters while the language server starts or when it is disabled.

---

Highlighting Architecture

vscode-sdif is not the direct source of truth for SDIF highlighting.

The highlighting chain resolves as follows:

sdif-spec
  -> tree-sitter-sdif/queries/highlights.scm
  -> sdif-lsp semantic tokens
  -> vscode-sdif client

tree-sitter-sdif/queries/highlights.scm is the single structural highlighting source. The bundled TextMate grammar in this extension is deliberately minimal and non-normative; it exists only as a startup/offline fallback and does not duplicate alias, relation, table, rule, or grouped-relation highlighting.

The Rust sdif-rs parser remains the normative source for diagnostics and semantic parsing. sdif-lsp uses sdif-rs for diagnostics, hover, and completions, and uses tree-sitter-sdif captures to produce editor highlighting semantic tokens.

---

Language Server

vscode-sdif orchestrates the Rust sdif-lsp language server. By default, it automatically searches for the server binary using the following sequence:

1. Explicit Path: If sdif.server.path is configured, the extension will attempt to execute that binary directly.
2. Bundled Binary: The extension checks for a pre-compiled, platform-specific binary in the extension's folder (under bin/ or server/ matching the user's OS and architecture, e.g., bin/linux-x64/sdif-lsp or bin/win32-x64/sdif-lsp.exe).
3. Workspace Build: If you are developing SDIF, it checks for sibling development builds (../sdif-lsp/target/release/sdif-lsp or ../sdif-lsp/target/debug/sdif-lsp).
4. System PATH: As a fallback, it will try the command configured under sdif.server.command (which defaults to "sdif-lsp") on the system PATH.

Version Compatibility

At startup, the client runs sdif-lsp --version to verify that the language server matches the version expected by the extension (as declared in the compatibility contract). If a mismatch or compatibility error occurs, VS Code will display a warning notification but will still attempt to run the language server.

Settings Configuration

You can configure the server path and args in your VS Code settings:

{
  "sdif.server.path": "",
  "sdif.server.command": "sdif-lsp",
  "sdif.server.args": [],
  "sdif.server.enabled": true
}

---

Development

Set up a local development workspace, compile the extension, and run testing:

npm install
npm run compile
npm test
npm run package

---

Boundaries

• Platform-specific language server binaries are bundled/distributed internally under bin/ or server/ without requiring external system package installation.
• No automatic download of language server binaries from the internet is performed.
• Formatting is intentionally out of scope for v1.0.
• VS Code does not load tree-sitter directly; highlighting integration is mediated by sdif-lsp semantic tokens.

---

Ecosystem

This GitHub organization hosts the official SDIF ecosystem: the core format, reference tooling, benchmarks, examples, libraries, and editor extensions.

PYTHON CLIENT & CLI sdif-py Specification, parser, canonicalizer, and CLI. The normative reference implementation. Explore sdif-py →	SPECIFICATION (SSOT) sdif-spec Official format specification, canonicalization rules, and portable conformance test suite. View specification →	BENCHMARKS sdif-benchmarks Reproducible benchmark datasets and reports comparing SDIF with JSON, YAML, XML, and CSV. View benchmarks →
RUST IMPLEMENTATION sdif-rs Pure Rust parser implementation with a span-annotated AST designed for editor tooling. Explore sdif-rs →	LANGUAGE SERVER (LSP) sdif-lsp LSP language server binary (tower-lsp) providing real-time diagnostics and IDE features. View sdif-lsp →	EDITOR INTEGRATION vscode-sdif VS Code extension client providing syntax highlighting, diagnostics, and LSP configuration. Open extension →
GRAMMAR FOUNDATION tree-sitter-sdif Tree-sitter grammar foundation for syntax highlighting and incremental parsing. Open grammar →	DOCUMENTATION sdif-format.github.io Official documentation website containing specification guides, tutorials, and examples. Read docs →	ORGANIZATION META .github Organization profile, assets, and shared community configuration files. View profile →

Repository map

Repository	Purpose
sdif-py	Core Python parser, validator, canonicalizer, and CLI
sdif-spec	Official format specification and conformance test suite (SSOT)
sdif-benchmarks	Benchmark datasets, reports, and comparison tooling
sdif-rs	Rust parser crate with span-annotated AST
sdif-lsp	LSP language server binary
tree-sitter-sdif	Tree-sitter grammar foundation for syntax highlighting
vscode-sdif	VS Code extension client for SDIF
sdif-format.github.io	Public documentation website (Docusaurus)
.github	Organization profile, assets, and shared GitHub community files

License

MIT. See LICENSE.