Command line / Editors without a plugin
penstock lsp
A language server for BPMN, DMN, CMMN and Camunda Form files, so an editor that speaks the Language Server Protocol shows the Penstock findings without a plugin.
What it is
penstock lsp [--stdio] is a Language Server Protocol 3.17 server built on the same check engine and project model as penstock check. An editor starts it, talks to it over standard input and output, and shows the findings where they are. It is how Zed, Helix, Neovim, Sublime Text, Emacs with eglot, Kate and Eclipse with LSP4E show Penstock. None of them has a Penstock plugin, and none is needed. It is Free.
Stdio is the only transport. --socket, --pipe, --node-ipc and a port are refused. The server makes no network call, executes nothing from the files it reads, and writes only protocol frames to standard output. Started by hand in a terminal it exits with 1; the editor starts it.
JetBrains IDEs and VS Code have their own Penstock plugins, with the full editor; this server is for the editors that have none.
What it does
| Request | Answer |
|---|---|
| Diagnostics | The penstock check findings of the open buffer, never the file on disk, with real ranges: elements by id, decision table rules by number, form components by id, and a parse error at its position. The code is the rule id, a link opens the rule page, and a finding with more than one place carries related places. Typing is debounced by 300 ms, and a stale run is dropped. |
| Hover | The rule under a diagnostic, with why it matters and how to fix it. For any element: its type, id, name, called process, called decision, form, job type and the variables in scope. |
| Go to definition, references | A call activity to its process, a decision reference to the decision, a form reference to the form file, and message, signal and error names to their other uses in the project. |
| Symbols and folding | Processes, sub-processes, lanes, tasks, events, gateways, DMN decisions with inputs and outputs, form components and CMMN plan items, for the document and for the workspace. Every element that has children and spans lines folds. |
| Quick fixes | Mark a process executable, set the history time to live, delete a superfluous label, and open the rule documentation. |
| Completion | FEEL built-ins, keywords and the variables the project knows, in = expressions, conditions and DMN cells; process, decision and form ids where a reference is expected. |
What it does not do
- No formatter. Penstock has none;
penstock fmtrewrites the XML the way the editor saves it. - No rename. Use
penstock refactor rename. - The checks that scan the whole project (code links, variable checks and connections) stay in
penstock check. - Custom bpmnlint rules from
.bpmnlintrcdo not run, because that would execute code from the project.
Limits
A document over 16 MiB is not read, and says so once. A file shows at most 200 findings, and the last note says so. A message over 32 MiB is refused. At most 256 documents are open, and the project index reads at most 3000 files of at most 4 MiB each. A file is read only inside the workspace folders the editor gave, after symbolic links are resolved; a file outside them gets one note and is not checked. A file that is not well formed gets one error at the position of the parse error.
Set it up
Install the command line first (Command line) and check that penstock --version works in the shell your editor starts from. In every setup below the editor runs penstock lsp --stdio. A BPMN, DMN or CMMN file is XML and a .form file is JSON, so each setup maps those file types to the server. An editor's own settings change between versions, so check these against its documentation.
Neovim 0.11
vim.lsp.config('penstock', {
cmd = { 'penstock', 'lsp', '--stdio' },
filetypes = { 'bpmn', 'dmn', 'cmmn', 'camunda-form' },
root_markers = { 'penstock.yaml', '.git' },
})
vim.lsp.enable('penstock')
vim.filetype.add({ extension = { bpmn = 'bpmn', dmn = 'dmn', cmmn = 'cmmn', form = 'camunda-form' } })
Helix
In languages.toml:
[language-server.penstock]
command = "penstock"
args = ["lsp", "--stdio"]
[[language]]
name = "bpmn"
scope = "source.bpmn"
file-types = ["bpmn", "dmn", "cmmn", "form"]
roots = ["penstock.yaml", ".git"]
language-servers = ["penstock"]
grammar = "xml"
Zed
Zed has no Penstock extension. In settings.json:
{
"languages": { "XML": { "language_servers": ["penstock", "..."] } },
"lsp": { "penstock": { "binary": { "path": "penstock", "arguments": ["lsp", "--stdio"] } } },
"file_types": { "XML": ["bpmn", "dmn", "cmmn"], "JSON": ["form"] }
}
Sublime Text
In the settings of the LSP package:
{
"clients": {
"penstock": {
"enabled": true,
"command": ["penstock", "lsp", "--stdio"],
"selector": "text.xml | source.json",
"schemes": ["file"]
}
}
}
Emacs, eglot
(add-to-list 'auto-mode-alist '("\\.\\(bpmn\\|dmn\\|cmmn\\)\\'" . nxml-mode))
(add-to-list 'auto-mode-alist '("\\.form\\'" . json-mode))
(with-eval-after-load 'eglot
(add-to-list 'eglot-server-programs
'((nxml-mode json-mode) . ("penstock" "lsp" "--stdio"))))
Kate
In Settings, LSP Client, User Server Settings:
{ "servers": { "xml": { "command": ["penstock", "lsp", "--stdio"], "highlightingModeRegex": "^XML$" } } }
Eclipse, LSP4E
Eclipse has no Penstock plugin. Under Preferences, Language Servers, choose Add, pick the content types XML and JSON, and set the launch configuration to Program with the command penstock and the arguments lsp --stdio. Then associate *.bpmn, *.dmn, *.cmmn and *.form with them.
OpenIDEA
The OpenIDEA plugin is not released. Its package starts penstock lsp, but there is nothing to install yet, so use one of the editors above.
What you see
- Findings underlined at the element, rule or component they belong to, with the rule id as the code and a link to its page.
- A hover card on an element, with its type and the variables in scope.
- Nothing on the command line: the server prints protocol frames to the editor and nothing else.
Common problems
- No findings appear.
- Check that the editor started the server (most editors have a log of language servers) and that
penstockis on the PATH the editor sees; an editor started from a menu may not have the PATH of your shell. The file must be inside a workspace folder the editor gave. - The file opens as plain XML and nothing is attached to it.
- The editor has to map the file types to the server, as in the setups above. A
.formfile is JSON. - "Only 200 findings are shown".
- A file shows at most 200 findings. Fix the first ones, or run
penstock checkfor the whole list. - A custom bpmnlint rule does not show.
- The server runs no code from the project.
penstock checkruns your custom rules. - Started in a terminal, it exits at once.
- It speaks only over standard input and output to an editor, and exits with 1 in a terminal.