Magic Scheme

MORE DETAIL PLEASE REFER GITHUB PAGE.

This extension adds support for Scheme(r6rs standard) to VS Code. With the help of scheme-langserver, we're proud to say that Magic Scheme is much better than many counterparts, which includes even Racket extensions.

NOTE: PLEASE ALWAYS USE LATEST VERSION SCHEME-LANGSERVER.

Zero-config for Linux x64: Magic Scheme can now automatically download and install scheme-langserver on first activation. No manual setup required for most Linux users.

For macOS, Windows, ARM Linux, and NixOS users, please see platform-specific notes below.

You can click this Patreon page or Aifadian to donate monthly, or just donate 10 USD just once time with the following paypal link.

Release

0.0.10 Type inference enabled by default; custom enum values in config wizard (e.g. S7, goldfish). 0.0.9 Interactive config wizard for .vscode/magic-scheme.json; supports arbitrary properties; multi-root workspace aware. 0.0.8 Unified project-level config via .vscode/magic-scheme.json; auto-update for scheme-langserver; removed legacy VS Code settings for LSP parameters. 0.0.7 Compatible with scheme-langserver 2.1.0 (workspace/symbol, improved diagnostics, .sld support); comprehensive syntax highlighting improvements. 0.0.6 Be compatible with new Scheme-langserver[<=2.0.0] ! 0.0.5 OK, at least I removed the annoying surrounding pair with "'" and also, 0.0.4 works now! 0.0.4 Try to notice programmers when LSP is initializing. 0.0.3 Replace grammer configuration. 0.0.2 Fix: comment. 0.0.1 Start!

Features

Magic Scheme does

• Support Scheme LSP through scheme-langserver, which brings jump to definition, auto complete, type inference(early stage) and more. Especially, Magic Scheme can handle local identifiers and partial evaluation technique, which are not provided by many counterparts.
• Support Scheme project with through AKKU, which make you possible to load project depdendencies in REPL or directly run scheme script in terminal.
• Support highlighting of nearly all of the r6rs standard functions and Chez Scheme functions.
• Status bar indicator shows LSP initialization state.
• serverPath and logPath support relative paths and ~ expansion.
• Auto-downloads scheme-langserver on first activation for Linux x64.
• The flag used when running scripts, e.g. --script, can be customized in settings via magicScheme.scheme.scriptFlag.

LSP

Magic Scheme now supports scheme-langserver. The current features are:

• Jump to definition

Especially, I must first recommend you with scheme-langserver's magic local identifier handling. Because in many other counterparts, you can never goto local binding's definition like the a in following:

(let ([a 1])
 a
)

• Auto complete

In further, thorough scheme-langserver, Magic Scheme can auto complete a with a-full-name-identifier in such cases:

(let ([a-full-name-identifier 1])
 a
)

• Find references

• Hover

Scheme-langserver truly responds with results, however, VS Code doesn't always display them.

I'm working on providing more details in this section: stay tuned!

Scheme Project

You can directly run scheme script with project environment after typing Alt+Enter, or you may Ctrl+Shift+P and input command magic-scheme.runSchemeScript; The result shows scheme --script ${currentFile}:

You can directly load scheme project environment in REPL after typing Alt+Shift+Enter, or you may Ctrl+Shift+P and input command magic-scheme.runSchemeREPL; The result shows an REPL and you may import AKKU managed environemnts without further configurations.

Syntax Highlighting

Setting Up & Some Configuration

The followings are mainly focus on x64-based linux operating system. As for other OSs, you may notice the following tips:

1. If you're using nixos, you may directly search scheme-langserver here. it will directly install an executable binary file. And this file is softly linked in bash $PATH as scheme-langserver.
2. If you're using MacOS, Windows or any other related environments, I suppose you're an advanced user and you may refer scheme-langserver's documentation in order to compile scheme-langserver manually.
3. Chez Scheme has Windows and MacOS version, but I've never tested them. So, I mean for Windows, you'd better use WSL/WSL2; for MacOS, it seems not very different from Linux.
4. AKKU is not native on Windows.
5. For nixos, you may be able to directly install all your needs.
6. Any other corner cases, you may refer softwares' documentations.

NixOS Note

NixOS users should install scheme-langserver via nixpkgs (e.g., akkuPackages.scheme-langserver) rather than downloading the generic Linux release binary from GitHub. The generic glibc-linked binary crashes on NixOS with a SIGSEGV. The extension will automatically fall back to scheme-langserver in $PATH or a local ./run file.

Disable Conflict Plugins

I'm so sorry Magic Scheme has some conflicts with Chez-Scheme-VsCode plugin. So, maybe you need to disable it.

Get Scheme-langserver

Automatic Installation (Recommended for Linux x64)

Magic Scheme will automatically download and install scheme-langserver on first activation if:

• You are on Linux x64
• scheme-langserver is not already on your $PATH
• magicScheme.scheme-langserver.autoDownload is enabled (default: true)

The binary is downloaded to VS Code's global storage (~/.config/Code/User/globalStorage/...) and is reused across workspaces.

Note on Settings Sync: The auto-discovered path is written to your workspace settings, not global settings. This prevents machine-specific paths from being synced to other computers via VS Code Settings Sync.

Manual Installation

If automatic installation is not available for your platform, you can manually download the latest executable from the scheme-langserver releases page and set magicScheme.scheme-langserver.serverPath to its path.

Platform	Support	Notes
Linux x64	✅ Auto-download	Automatically downloaded on first use.
NixOS	✅ Auto-download	Generic Linux binary; if it fails, install via nix-shell -p akkuPackages.scheme-langserver.
macOS	❌ Manual only	No prebuilt binary. Install via Nix or build from source.
Windows	❌ Manual only	No prebuilt binary. Use WSL2 or build from source.
Linux ARM	❌ Manual only	No prebuilt binary. Build from source.

Get Scheme

Magic Scheme supports r6rs standard scheme. But apparently I can't fully tests all implementations. As myself, I recommend with Chez Scheme, and you may install it as following:

wget https://github.com/cisco/ChezScheme/releases/download/v10.0.0/csv10.0.0.tar.gz
tar -xf csv10.0.0.tar.gz && cd csv10.0.0
# Install dependencies: `libncurses5-dev`
./configure --threads --kernelobj --disable-x11
make && sudo make install

Get AKKU

AKKU is a package manager for Scheme. It grabs hold of code and shakes it vigorously until it behaves properly. Magic Scheme facilitates AKKU to manage scheme projects. To install AKKU, you may follow:

wget https://gitlab.com/-/project/6808260/uploads/094ce726ce3c6cf8c14560f1e31aaea0/akku-1.1.0.amd64-linux.tar.xz
tar -xf akku-1.1.0.amd64-linux.tar.xz && cd akku-1.1.0.amd64-linux
bash install

Automatic Updates

If Magic Scheme automatically downloaded scheme-langserver for you, it will periodically check for newer releases and offer to update.

Setting	Behavior
notify (default)	Status bar shows scheme-langserver X.Y.Z available; click it or use the notification to update
auto	Downloads and installs updates silently in the background, then restarts the language server
off	Never checks for updates

Only applies to auto-downloaded binaries. If you installed scheme-langserver manually (via PATH, Nix, or a local ./run file), Magic Scheme will never touch it.

The check runs at most once every 24 hours and uses GitHub's release redirect (not the API), so it is not affected by GitHub API rate limits.

Project Configuration

Magic Scheme uses .vscode/magic-scheme.json as the sole configuration source for scheme-langserver runtime parameters.

Quick Setup: Configure Magic Scheme Project

The easiest way to configure your project is through the built-in wizard:

1. Open your Scheme project in VS Code.
2. Press Ctrl+Shift+P (or Cmd+Shift+P) and run Configure Magic Scheme Project.
3. A QuickPick panel shows the current settings:

   topEnvironment: R6RS        (default)
   multiThread: enable         (default)
   typeInference: enable       (default)
   logPath: ~/scheme-langserver.log  (default)
   + Add new property...
   ✓ Done
   

4. Click any field to change it:
   • topEnvironment — choose from R6RS, R7RS, or select Custom value... to enter any other environment (e.g. S7, goldfish).
   • multiThread / typeInference — choose enable or disable.
   • logPath — type any path (supports ~ for home directory).
5. Click + Add new property... to add arbitrary scheme-langserver parameters not listed above.
6. Click ✓ Done to save.

The wizard automatically creates .vscode/magic-scheme.json (and .vscode/ if needed) and restarts the language server.

Manual Setup: Edit JSON Directly

You can also edit .vscode/magic-scheme.json by hand. On first activation, Magic Scheme automatically creates this file with default values:

{
  "topEnvironment": "R6RS",
  "multiThread": "enable",
  "typeInference": "enable",
  "logPath": "~/scheme-langserver.log"
}

All fields are optional — omitted fields fall back to the defaults above.

Field	Description	Default
topEnvironment	Scheme top environment: R6RS, R7RS, or any value your scheme-langserver supports (e.g. S7, goldfish)	R6RS
multiThread	Enable/disable multi-threading: enable or disable	enable
typeInference	Enable/disable type inference: enable or disable	enable
logPath	Path to scheme-langserver log file (supports ~ expansion)	~/scheme-langserver.log

When you save changes to this file, Magic Scheme automatically restarts the language server to apply them.

For Developer

Setup (NixOS)

1. For Nixos, after install yo and generator-code, should

export PATH=$PATH:./node_modules/.bin/

Testing

The project has a 3-layer test suite:

Suite	File	Description
Unit	src/test/utils.test.ts, src/test/download.test.ts	Tests pure logic: getOrDefault, quoteWindowsPath, config defaults, download progress, and platform detection.
Mock LSP	src/test/lifecycle.test.ts	Uses a mock Node.js LSP server (src/test/mock-server/server.ts) to test extension activation, completions, and hover without a real scheme-langserver.
E2E	src/test/e2e.test.ts	Tests against a real scheme-langserver binary. Auto-detects the binary from .vscode-test/scheme-langserver, ./run, or $PATH.

Run all tests:

npm run test

Run a specific label:

npx @vscode/test-cli --label unit
npx @vscode/test-cli --label mock-lifecycle
npx @vscode/test-cli --label e2e

Known Issues / Technical Notes

• $/setTrace warning: VS Code's LSP client sends $/setTrace (a standard LSP 3.16+ notification to adjust server trace verbosity). scheme-langserver does not implement this and returns invalid request. This is harmless and does not affect completions, hover, or any other LSP feature.
• NixOS scheme-langserver binary: The generic Linux glibc-linked release binary may crash on NixOS. If this happens, install via nixpkgs (nix-shell -p akkuPackages.scheme-langserver) instead.
• Test sleep(2000): src/test/helper.ts uses a fixed 2-second delay after opening a document to wait for LSP initialization. This is stable but could be improved by listening for State.Running.
• Mock server edge cases: The mock LSP server does not handle stdin end/error events. This is acceptable for current test scenarios.