22. Editor Integration

Most of the time you author .arch files in an editor, not from a CLI. This chapter is about what the editor extensions actually do — what completions you get, what hover shows, what code actions appear, where the inline preview lives, and how to set things up if you’re using an editor that isn’t on the first-class list.

Two extensions are first-class:

• VS Code — search for “Archlang” in the marketplace.
• JetBrains (IDEA, WebStorm, GoLand, PyCharm, RubyMine, Rider, CLion) — search for “Archlang” in the JetBrains plugin marketplace.

Both bundle the same language server (@archlang/lsp). Feature parity is the goal; the two are kept in step.

What the LSP gives you

Once the extension is installed and you open a .arch file, the language server activates. From that moment on:

Completion

Type micro and the completion list shows service (and any other registered kinds matching that prefix). After the kind keyword, completion suggests fresh stable IDs and module-name conventions. Inside a body, completion knows what fields the type provides and what required blanks remain unfilled — for a service instance, you’ll see team, labels.domain, and widget.* props at the top of the list.

Inside process steps, completion is path-aware: type Customer > Payments. and you get the list of interfaces (and facets, which you can dot-into further) declared on Payments. The LSP knows the entire workspace — completion across files in your package and across imported packages works the same way.

Hover

Hover any identifier. The LSP renders:

• For a module reference: the module’s kind, team, description (rendered with markdown + [[refs]] + @labels), and a list of its interfaces.
• For an interface reference: the interface’s kind, description, and any subscribes: wiring.
• For a kind keyword: the kind’s defining type, its required blanks, and the chain up to the base kind.
• For a stable ID: the named declaration and its location.

The exact same renderer the viewer uses for descriptions also runs in the hover. What you see in the editor matches what you see in the diagram.

Diagnostics

Every save runs the full validator. Errors and warnings underline in the source and appear in the Problems panel. Diagnostic codes (USE_TYPE_NOT_EXPORTED, DEP_CYCLE, WIDGETS_FILE_NOT_FOUND, etc.) are stable across releases — you can filter or escalate specific ones in your project’s settings.

Go-to-definition and find-references

Right-click any identifier and jump to where it’s declared. Find-references shows everywhere it’s used — every process step invoking a given interface, every module declaring it, every description that cross-references it.

This works across files in the package and across imported packages. Imported types resolve to their declaration in the source package (the LSP follows the use chain).

Rename refactoring

Rename a module and every reference updates: process steps that named it, descriptions that linked to it, view include/exclude patterns that matched it. Renames preserve the stable ID, so the diff engine still sees one renamed module rather than a delete-plus-add (Chapter 14).

Renames work for interfaces (within their enclosing module’s path), processes, views, and types.

Code actions

The LSP exposes lightbulb code actions for common edits. The exact set evolves between releases; representative actions include fulfilling a required blank with a default value, dropping an inherited declaration, and converting between dotted and block label forms. Hover the lightbulb in any context to see what’s available.

Semantic tokens

Syntax highlighting in .arch files isn’t lexical — the LSP provides semantic tokens. Kind keywords, stable IDs, qualified names, descriptions, and label paths each get their own token type, which means your color theme can distinguish them. The highlighting is identical in VS Code and JetBrains because both consume the same LSP.

Inline diagram preview

Both extensions ship an inline preview pane. Open the command palette and run Archlang: Preview Diagram (or use the keybinding). A side panel renders the current package’s diagram and updates on every save — the same diff loop as Chapter 2’s worked example. The pane uses the same renderer as the hosted and embedded viewers.

Preview pane controls:

• Toggle between the package’s default view and any declared view in the file.
• Zoom and pan; the LOD rules from Chapter 20 apply.
• Hover a node to see its full body in a side popover.
• Click a node to jump back to its declaration in the editor.

Inlay hints

When a module instance is filling in a required blank, the editor shows the type that originally declared the blank as a faint hint next to the value:

service Payments {
    team: Payments        ⋯ (required cascade on type service)
}

Inlay hints can be toggled off if they’re noisy. They’re useful while you’re learning the metamodel; they fade into the background once you know it.

Setup notes per editor

VS Code

The extension activates automatically on .arch and package.archspace files. The first activation downloads the bundled language server binary (it ships inside the extension, so no separate install).

Settings worth knowing:

Setting	Default	Effect
archlang.format.onSave	true	Run the formatter on every save
archlang.preview.enabled	true	Allow the inline preview pane to open
archlang.stdlib.path	(toolchain default)	Point at a custom stdlib if you’re working on the toolchain itself

JetBrains

Install from the plugin marketplace. The plugin registers a file type for .arch and starts the bundled language server lazily on first file open.

JetBrains-specific niceties:

• The Structure tool window shows modules, interfaces, and processes as a tree.
• The Project tool window’s “Show in Archlang Viewer” right-click action opens the inline preview for any .arch file or package directory.
• Find Usages and Refactor → Rename are wired to the corresponding LSP requests.

Other editors

The language server is the standard LSP protocol over stdio:

@archlang/lsp                    # if installed via npm
archlang-lsp                     # if installed via @archlang/cli (the binary ships with both)

Hand your editor’s LSP client this command and an arch languageId. Specifically:

• Neovim with nvim-lspconfig: register a server pointing at archlang-lsp for the arch filetype.
• Emacs with lsp-mode: add (arch-mode . "archlang-lsp") to lsp-language-id-configuration.
• Helix: add a [language] block in languages.toml pointing at archlang-lsp.
• Sublime Text with LSP package: register a new language server with the same command.

Browser editors that want the LSP without a backend can use @archlang/lsp/browser’s startBrowserServer(vfs) entry point, which runs the server as a web worker with an in-memory virtual file system. The hosted demo at archlang.dev/demo uses exactly this.

What the LSP doesn’t do

• Doesn’t render diagrams itself. The preview pane delegates to the viewer’s renderer; the LSP only provides the resolved model and updates.
• Doesn’t execute processes. Archlang is a description language; processes are documentation, not orchestration. The LSP describes flow; it doesn’t run it.
• Doesn’t fetch packages over the network. Dependencies are resolved against local filesystem paths declared in package.archspace. If you want a registry, that’s the next layer up.

Summary

• VS Code and JetBrains extensions are first-class; both bundle the same language server.
• The LSP provides completion, hover, diagnostics, go-to-definition, find-references, rename, code actions, semantic tokens, inlay hints, and an inline preview pane.
• Other editors connect via the standard LSP protocol over stdio (archlang-lsp) or as a browser worker (@archlang/lsp/browser).
• Diagnostic codes are stable across releases; tooling keys off them for filtering and CI gating.

What’s next

Chapter 23: Embedding Diagrams → — put architecture diagrams into your own pages, dashboards, and review tools.