Sprig for VS Code

Language support for Sprig, an indentation-based, statically typed language for the JVM. Diagnostics as you type, quick fixes, hover, completion, parameter hints, semantic highlighting, navigation, references, rename and formatting come from the Sprig language server, sprig lsp, which runs the same parser and type checker as sprig check. The extension does not implement a second type checker. It also runs programs and tests, shows the generated Java, and highlights Sprig without any compiler.

Extension version 0.3.1 is independent of the compiler version.

Install / 安装

Install Sprig (ColinHouse.sprig-language) from the Extensions view. The Visual Studio Marketplace serves VS Code; Open VSX serves VSCodium and other compatible editors. To build the extension yourself, see Development.

Highlighting, the outline and snippets work immediately, without Java or the compiler. Everything else needs JDK 21+ and the Sprig SDK. Set Sprig: Compiler Path to the SDK's bin/sprig launcher, or put the SDK's bin on PATH. A built Sprig source checkout is found by searching parent directories for bin/sprig after PATH.

The extension asks the compiler (sprig capabilities --json) whether it has a language server, so there is nothing to configure:

{
  "sprig.compilerPath": "/absolute/path/to/Sprig/bin/sprig",
  "sprig.languageServer.enabled": true,
  "sprig.checkOnSave": true,
  "sprig.commandTimeoutSeconds": 120,
  "sprig.testTimeoutSeconds": 600
}

sprig.trace.server (off, messages or verbose) logs the protocol in the Sprig Language Server output.

Windows support (bin/sprig.cmd from a source build or an extracted release ZIP) is a preview. The extension starts the same JVM entry point and classpath directly, so paths never pass through cmd.exe; custom batch wrappers are unsupported. java.exe reads its command line in the Windows ANSI code page, so commands such as Check and Run cannot take a file whose path uses characters outside it. The language server is not affected: document paths travel inside the protocol. Remote SSH and containers need the SDK and JDK on the remote host. Browser-only VS Code and virtual file systems are unsupported.

Editing / 编辑

In both modes, a keyword hover shows its sprig help topic, Go to Symbol in Workspace searches every .spr file, each diagnostic code in Problems links to the diagnostic reference, and the lightbulb offers to explain a code or open its help topic. Snippets: func, funct, class, variant, enum, match, matchr, if, ifnn, for, while, try, import, imports, importj, generic.

The language server reads sprig.toml and sprig.lock like the command line and never resolves or downloads anything. See the language server reference for what it does while code does not compile yet.

Commands / 命令

Open a .spr file. Use the Command Palette, the editor context menu or the Sprig language status item:

The Sprig language status item shows the compiler version, whether the language server runs and, in a project, whether sprig.lock is current, stale or missing.

Without the language server, saving checks the file by default. In a sprig.toml project, Check validates the configured entry graph plus the current file, so an unused module also gets feedback. With the server, open files are checked as they change, and Sprig: Check adds the files of the entry graph that are not open. The extension never resolves or downloads packages on its own: only Resolve Dependencies and New Project run sprig resolve, and only when you choose them.

Commands run the active saved file, with the nearest project root as working directory. Save all dirty Sprig files in that project first. Java/build artifacts are kept in the extension's global storage, outside the source tree; old artifacts are not automatically deleted. Generated files can be inspected, but edits are not fed back into Sprig.

Run supports finite non-interactive programs: stdin is closed, output is displayed on completion, and the default limits are 120 seconds and 8 MB. Cancel the progress notification to stop the compiler and the program it started: the process group on Linux/macOS, the process tree on Windows. For persistent servers or interactive programs, choose Sprig: Run in Terminal. It starts sprig run <saved-file> with the nearest project root as working directory; output and stdin belong to the terminal, with no time or output limit. Use Ctrl+C or close the terminal to stop the program.

Testing view / 测试

Every sprig.toml project with a tests/ directory appears in the Testing view, one entry per tests/**/*.spr file. Running a file uses sprig test <file> --json; running a project uses sprig test --json, both in the project root. Failures show the reason, the compiler diagnostics at their source locations and the program output. Files under tests/compile_fail/ must fail compilation with the codes listed in their sibling .expect.toml. Each run is bounded by sprig.testTimeoutSeconds. VS Code saves dirty files before running tests from the Testing view (testing.saveBeforeTest); Sprig: Run Tests saves the project's Sprig files itself.

Highlighting

TextMate scopes cover implemented lexer keywords, functions/declarations, capitalized type names, built-in and generic/nullable types, source fn(A) -> R types and fn(x: A) => expr lambdas, numeric exponents, double-quoted strings and escapes, # comments, variant/match, and operators. Single quotes, Python keywords and Java syntax are not added to Sprig. Colors follow the user's theme. Without semantic tokens, capitalized identifiers are a lexical type-name heuristic. With a compiler that advertises semantic tokens, the language server adds resolved identifier categories, including declaration and readonly modifiers; uppercase variables and lowercase types are classified by their declarations. A syntax or name-resolution error clears semantic tokens and leaves lexical highlighting available. Four spaces and spaces instead of tabs are default editor settings for Sprig.

Trust and diagnostics

Restricted Mode keeps highlighting, the outline, workspace symbols, snippets, keyword completion and navigation to file imports. The language server, compiler queries, checks, runs, formatting, hover details, member completion and tests require a trusted workspace; the server starts when you trust the workspace. Compiler processes receive argument arrays without a shell. Old/canceled checks cannot overwrite a newer result. Compiler response failures appear in the Sprig output; manual commands also show an actionable error notification. If the language server stops repeatedly, the extension falls back to separate compiler commands until Sprig: Restart Language Server; its own log is the Sprig Language Server output.

Limitations

• The language server re-checks the whole program on each change, renames only locals and parameters, and has no workspace symbols or code actions other than quick fixes. Signature help and semantic tokens require a compiler that advertises them; extension 0.3.0 registers them automatically.
• Signature help completes the call being typed, including nested calls and strings with commas; unrelated syntax errors can still prevent an answer. Java overloads are candidates, not ranked by argument types. Missing Java parameter names use arg0, arg1, etc. Sprig generics display written types; built-in functions and native collection/string methods have no signatures yet.
• In a multi-root workspace, one language server serves the window, with the compiler configured for the Sprig file or folder it started from.
• Without the language server, the outline, workspace symbols and Go to Definition are lexical, member completion does not cover locals and parameters, and hover and completion reflect saved files.
• Formatting needs code that parses; otherwise the document is left unchanged.
• No debugger.

Development / 开发

From editors/vscode/:

npm ci
npm test
npm run package

Build the compiler at the repository root first (python3 scripts/build.py). Open this extension directory in VS Code and press F5 to launch a separate Extension Development Host; the launch task compiles TypeScript and bundles out/main.js with esbuild.

npm run test:host
# Reuse an installed VS Code rather than downloading one:
VSCODE_EXECUTABLE_PATH="/Applications/Visual Studio Code.app/Contents/MacOS/Code" npm run test:host
# Real Restricted Mode test (custom launch: official runner disables trust):
SPRIG_TEST_RESTRICTED=1 VSCODE_EXECUTABLE_PATH="/Applications/Visual Studio Code.app/Contents/MacOS/Code" npm run test:host

On Windows, point VSCODE_EXECUTABLE_PATH at Code.exe.

Unit tests use the actual compiler for the CLI adapter, the language server command and protocol, Markdown rendering, queries, formatting, snippets and sprig test results, plus TextMate/Oniguruma tokenization and terminal command checks. Host tests run a real VS Code Extension Host: diagnostics, Run, generated Java, the integrated terminal, symbols, hover, completion, definition, formatting, the Testing view and project commands without the language server; then, with it, diagnostics for unsaved edits, types of locals, member completion, cross-module definition, references, rename, formatting, restart and the fall back; and a separate Restricted Mode run. The host tests use isolated temporary profiles; they do not install into or change your usual VS Code settings. npm run package writes dist/sprig-language-0.3.1.vsix, and python3 scripts/check-editor.py at the repository root also checks its contents. Publishing is described in DEVELOPMENT.md.

License

Apache-2.0. The extension bundles the language client libraries listed, with their licenses, in ThirdPartyNotices.txt.