User Manual    [Previous]   [Next]   

Zed

Umple for Zed

Umple language support for the Zed editor, providing syntax highlighting, diagnostics, code completion, inlay hints, and go-to-definition for .ump files.

Installation

The extension is available on the Zed marketplace. Install it from Zed:

1. Open the command palette (Cmd+Shift+P) and run zed: extensions
2. Search for Umple and click Install

The extension automatically downloads the LSP server and Umple compiler — no manual setup required.

Dev install (from source)

To work on the extension itself, install it as a dev extension:

1. Clone this repo:

   git clone https://github.com/umple/umple.zed.git

2. In Zed, open the command palette (Cmd+Shift+P) and run zed: install dev extension

3. Select the umple.zed directory

Prerequisites

• Rust (via rustup, not Homebrew rust — needed to compile the dev extension)
• Node.js 20+ (for running the LSP server; tested on 20 and 23)
• Java 11+ (optional — needed for diagnostics from the Umple compiler)

Features

• Syntax highlighting via tree-sitter grammar and highlight queries
• Diagnostics from UmpleSync compiler
• Code completion with context-aware keyword suggestions
• Go-to-definition for classes, interfaces, traits, enums, attributes, methods, state machines, states, associations, mixsets, requirements, and use statements
• Find references across all reachable files with state-path disambiguation
• Rename safe symbol rename across all references
• Hover contextual information for symbols
• Inlay hints editor-only inferred type annotations for untyped attributes when Zed renders LSP inlay hints
• Formatting AST-driven indent correction, arrow spacing, declaration assignment spacing, structural comma spacing, blank-line normalization
• Outline view showing classes, methods, state machines, and more
• Cross-file support transitive use statement resolution and cross-file diagnostics
• Auto-indentation for blocks

Formatting is provided by the LSP server. It formats parse-clean Umple structure, parser-visible structural commas, and already split multi-line list indentation, but intentionally does not format embedded target-language method or action bodies. Formatter behavior belongs in umple-lsp/packages/server; this extension should only handle Zed launch/packaging behavior.

How It Works

The extension automatically installs umple-lsp-server from npm and downloads umplesync.jar for compiler diagnostics. The server is launched via Node.js in --stdio mode.

Configuration (optional)

You can adjust certain settings using Settings … / Open Settings (cmd ,) or by editing the settings.json file.

Configuration settings for users

By default lines of Umple code that have errors or warnings are underlined; you can see the error or warning at the bottom of the screen if you click on the underlined text.

However, if you would like such messages from the Umple compiler to appear inline (on the line where each problem occurs), then you can change the Languages & Tools / Diagnostics / Enabled setting to be true. You can also do this by adding the following to the settings.json file.

{
  "diagnostics": {
    "inline": {
      "enabled": true
    }
  }
}

Configuration settings for developers working on the Umple LSP server

For development, you can override the auto-downloaded server with a local build. Add to your Zed settings.json (Cmd+,):

{
  "lsp": {
    "umple-lsp": {
      "settings": {
        "serverPath": "/path/to/umple-lsp"
      }
    }
  }
}

This points to a locally cloned and built umple-lsp repository.

Updating

Marketplace install: Zed updates installed extensions automatically. New versions reach you via the Zed Extensions marketplace.

Dev install (from source): pull the latest changes and Zed will pick them up:

cd umple.zed
git pull

Then restart Zed or reload the extension.

The LSP server itself is downloaded from npm at every extension load (via npm_package_latest_version("umple-lsp-server")), so server-only changes reach you on the next Zed startup without any extension update needed.

Grammar Sync

The tree-sitter grammar and query files are derived from umple-lsp. The following files are auto-synced and should not be edited manually:

• extension.toml [grammars.umple].rev — pinned commit for parser.c
• languages/umple/highlights.scm — copied from umple-lsp/packages/tree-sitter-umple/queries/

How sync usually happens

A GitHub Action in umple/umple-lsp auto-opens (or updates) a PR on this repo whenever grammar or query files change upstream. The PR force-pushes onto a stable branch sync/umple-lsp-master, bumps extension.toml patch version, and includes a body that classifies the change as grammar | highlights | both plus a “safe to merge?” hint. You just merge it.

Manually syncing (rarely needed)

If the auto-PR workflow is broken or you want to sync ahead of an upstream push:

./scripts/sync-grammar.sh --source /path/to/umple-lsp

Checking for drift (CI or local)

./scripts/sync-grammar.sh --source /path/to/umple-lsp --check

This exits with code 1 if any synced file is out of date. The .github/workflows/check-sync.yml workflow in this repo runs this on every push/PR to master to catch drift.

Where to Make Language-Feature Changes

This extension is mainly the Zed wrapper. Core language behavior belongs in umple-lsp:

• Diagnostics, completion, hover, inlay hints, go-to-definition, references, rename, formatting, workspace symbols, code actions, and LSP semantic tokens: umple-lsp/packages/server
• Parser and tree-sitter highlighting: umple-lsp/packages/tree-sitter-umple
• Zed extension loading, npm server download, language registration, and grammar pinning: this repo

Zed’s visible syntax highlighting comes from the synced tree-sitter highlight query at languages/umple/highlights.scm. The LSP server also advertises semantic tokens for clients that use them; those are generated from the upstream highlights.scm and mapped in umple-lsp/packages/server/src/semanticTokens.ts.

When highlighting changes upstream, prefer the sync workflow or run:

./scripts/sync-grammar.sh --source /path/to/umple-lsp --check
./scripts/sync-grammar.sh --source /path/to/umple-lsp

Change this repo directly only when the Zed wrapper behavior changes or when accepting the generated grammar/highlight sync.

Troubleshooting

Extension fails to compile (“failed to compile Rust extension”)

Zed compiles extensions to WebAssembly (wasm32-wasip2), which requires the Rust toolchain from rustup. Homebrew’s rust package only includes the native target and can’t cross-compile to WASM.

# Remove Homebrew rust if installed
brew uninstall rust

brew install rustup
# Or install rustup directly via [rustup](https://rustup.rs/)

LSP server not starting

Check View > Toggle Language Server Logs in Zed for errors. Common issues:

• Node.js not found: Install Node.js 18+ and ensure it’s on your PATH
• npm install failed: Check internet connection, restart Zed to retry

No diagnostics

Diagnostics require Java 11+. Check the LSP logs (View > Toggle Language Server Logs) for errors related to umplesync.

License

MIT

Original markdown source for this page: https://github.com/umple/umple.zed/blob/master/README.md