VS Code and the Language Server

Procedures are written by operators, not only by developers: the tooling that catches errors while they type is part of the product. stellar-lsp is the language server of the configuration repositories, built on the same compiler as stellar check and the CI: what the editor reports is what the CI reports. The VS Code extension is its first client; the web editor is the second.

Installation#

1. Install the language server and the CLI from the repository of Stellar Control:

   cargo install --path tooling/lsp      # stellar-lsp
   cargo install --path tooling/cli      # stellar

2. Install the extension: download stellar-mcs.vsix from the artifacts of the CI (job VS Code extension), then:

   code --install-extension stellar-mcs.vsix

   or Extensions: Install from VSIX… in VS Code. The extension needs VS Code 1.90 or later, and installs the YAML extension of Red Hat with it.

3. Open the configuration repository: the folder with topology.yaml or packages/. The extension activates on a workspace that contains topology.yaml or packages/*/catalogue.yaml.

Features#

Procedures (.proc)#

• Highlighting of the procedure language.
• Live errors and warnings, such as a hazardous telecommand without ask operator, an unknown measure, a unit mismatch or a retry on a step that changes the on-board state.
• Completion by role, from the roles (uses) of the block being written:
  • after psu., the components and measures of the catalogue of the power supply;
  • after send, the telecommands of the platforms of the roles, and after with, their arguments;
  • after is or is not, the enum and boolean values;
  • after do " or run ", the steps and procedures of the library;
  • at the start of a line, the keywords.
• Hover:
  • on a step (defined, inline or called): the maximum duration of an attempt, the retry as written (that of the call wins) or deduced (executor.default_retry when all its telecommands are changes_state: false, else none), its hazardous telecommands;
  • on a procedure: its maximum duration retries included, whether run … retry is allowed, its environments, its signature;
  • on a telecommand or a measure: type, unit, range, limits, description.
• Go to definition of a step, a procedure, a telecommand, a measure or a component, down to its catalogue (or the catalogue it is imported from).

YAML files#

The catalogues (packages/*/catalogue.yaml), library manifests (packages/*/package.yaml), the topology (topology.yaml) and simulations (simulations/*.yaml) get:

• their JSON Schema, through the YAML extension of Red Hat: completion of keys, hover, and structural errors (the same schemas as stellar schema catalogue|library|topology|simulation);
• the errors of the compiler: cross-references, types, units, policies.

Commands#

A dry run needs nats-server on the PATH (or STELLAR_NATS_SERVER). See Simulated Targets.

Settings#

The language server#

stellar-lsp speaks the Language Server Protocol on standard input and output, so any editor with an LSP client can use it.

• Repository root. The repository of a file is the first directory above it that contains topology.yaml or a packages/ directory. Several repositories can be open at once.
• Compilation. It compiles the whole repository with the compiler of the CLI and the CI, the unsaved buffers of the editor over the files on disk, 100 ms after the last change.
• Diagnostics are published file by file — catalogues, topology, procedures and simulations — and cleared once fixed. On the example repository, they arrive within 200 ms of a keystroke, delay included.
• Completion triggers on ., " and space.
• Compilation parameters (executor.default_retry, derived.max_window) come from the global configuration named by STELLAR_CONFIG; defaults without it.
• Logs go to standard error, at warn unless RUST_LOG says otherwise.

For other editors, run stellar-lsp for .proc files and the YAML files above; for instance with Neovim:

vim.lsp.start({
  name = "stellar-lsp",
  cmd = { "stellar-lsp" },
  root_dir = vim.fs.root(0, { "topology.yaml", "packages" }),
})

From source#

cd tooling/vscode
npm ci
npm test                                                  # unit and highlighting tests
STELLAR_CLI=../../target/debug/stellar npm run package    # schemas, bundle, stellar-mcs.vsix

To try it from source, open tooling/vscode in VS Code and run Run Extension (F5) with stellar.server.path pointing to target/debug/stellar-lsp.