Rohy VI for VS Code
Rohy VI (Virtual Intelligence) is rohy in the editor. Today it checks and formats
rohy correlation rule files while you edit them.
How a file is checked
The status bar, beside a rule file, says which of two checks is in use:
✓ rohy: rohyctl is in use. The buffer is checked as you type, by rohyctl validate.
That is the same function the application loads rules with, so a file with no problems here
is a file that loads. Errors and warnings appear where they are, with their codes.
ⓘ rohy: schema only: no rohyctl could be run. VS Code checks the file
against the rule schema (schemas/rohy-rule.schema.json, generated by tools/genschema), and
hover and completion work. The schema describes the shape of a rule. It cannot express anything
that depends on the algorithm, so a file with no problems may still not load. The tooltip says
why rohyctl is not in use.
You do not need to install rohyctl. The extension carries one for Windows, Linux and macOS, on
x64 and arm64, built from the same commit as the extension. The extension uses, in order:
- the
rohyctl named by rohy.rohyctlPath, when that is set;
- its own;
- the first
rohyctl on PATH, on a machine it carries none for (32-bit, for instance).
rohy: Show Log (or a click on the status bar item) says which rohyctl is in use and where it
came from.
Format Document lays a rule out in the house style with rohyctl format. That is the layout
the built-in library uses, and the one rohyctl format --check holds a CI job to. It needs
rohyctl. A file that does not parse is left as it is, and you are told why. VS Code may ask
once which JSON formatter to use for these files.
Which files
rohy-data/rules/*.json: the application's rules folder. rules-state.json sits there too,
and is not a rule; it is left alone.
backend/rules/builtin/*.json: the built-in library, in a checkout of rohy itself.
- Anything matched by
rohy.ruleFiles.
Settings
| Setting |
Default |
|
rohy.rohyctlPath |
empty |
The absolute path of a rohyctl to use instead of the extension's own, for instance one built from another version of rohy. Empty means the extension's own, or, on a machine it carries none for, the first rohyctl on PATH. A path that is wrong is reported, never replaced by another rohyctl. |
rohy.ruleFiles |
[] |
More glob patterns for rule files. A pattern with no root matches anywhere: rules/*.json means any rules folder. These files are checked and formatted by rohyctl; the schema's hover and completion cover only the default folders, because VS Code reads that list from the manifest. |
Safety
- An opened folder cannot choose the program that runs.
rohy.rohyctlPath is read only from
your user settings, never from a folder's. The extension's own rohyctl sits inside the
installed extension, where an opened folder cannot reach. PATH is searched by the extension itself, in
absolute entries only, so a rohyctl.exe placed inside a repository is never picked up from
the current directory. On Windows only rohyctl.exe is taken, never a .cmd or .bat.
- The text goes on stdin, never on the command line, and there is no shell. Nothing typed in
a rule can become an argument.
- Every run is bounded: 10 seconds, 8 MiB of output, and cancelled when the text changes
again. The output is checked field by field. A report the extension cannot read is reported
as an error, never shown as a file with no problems.
rohyctl never opens a case. It reads the text it is given and nothing else.
This is why the extension declares full support for folders you have not trusted: it behaves
the same in them.
Versions
The extension has its own version, independent of rohy's. Its first release is 0.1.0.
Its own rohyctl is built from the same commit and reports rohy's version
(rohyctl version, also in the log). It checks rules the way that rohy does. To check them the way
another rohy does, point rohy.rohyctlPath at that rohy's rohyctl.
It works with any rohyctl whose validate --json report is in shape 1 (output_version). A
rohyctl that reports another shape is refused, with a message naming both shapes, and is never
read as a file with no problems. The schema it falls back to is copied in when the extension is
packaged, so in that mode it checks the rule format of the rohy it was built from.
Building and testing
There are no dependencies. The tests use Node's own runner and need Node 22 or later:
cd tools/rohy-vi
npm test
rohyctl validate --json is the contract between the two halves. The rules in
test/fixtures/rules and the reports in test/fixtures/reports are read by both test suites:
the Go test (cmd/rohyctl/validatejson_test.go) pins what rohyctl prints for each rule, and
these tests place those exact reports on those rules. To change the output on purpose:
go test ./cmd/rohyctl/ -run TestValidateJSONMatchesTheExtensionFixtures -update-extension-fixtures
Then check the diff, and that npm test still passes.
Packaging and publishing
From the repository root, build-extension.ps1 (Windows) or build-extension.sh (Linux, macOS)
builds the installable package, rohy-vi-<version>.vsix, in this folder. Both run
scripts/package.js (also npm run package here), so they do the same thing. It needs Go and
Node 22 or later.
The one package carries rohyctl for win32-x64, win32-arm64, linux-x64, linux-arm64,
darwin-x64 and darwin-arm64, in bin/<platform>-<arch>/; the extension runs the one for its
machine. The Linux builds are static, so they run on Alpine too. It stops at the first failure:
- The extension's version, and rohy's in
build/config.yml, must be plain x.y.z. The
Marketplace takes no pre-release labels.
go run ./tools/genschema -check must pass. The schema-only check uses the bundled schema,
so a stale schema would check rules against an old format.
npm test must pass.
Then it:
- cross-builds each
rohyctl with no cgo, stamped with rohy's version, the commit (-dirty if
the checkout has changes, with a warning) and the commit's time;
- runs the one built for this machine, to confirm it starts and reports that stamp;
- packages the folder with a pinned
@vscode/vsce (fetched by npx; it is not a dependency of
the extension), with the README's relative links pointed at this folder on GitHub;
- confirms the package holds every
rohyctl, and prints the package's SHA-256.
bin/ is emptied before the builds and removed at the end, so the package holds exactly the
binaries built that run.
.\build-extension.ps1 # from the repository root
code --install-extension tools\rohy-vi\rohy-vi-0.1.0.vsix # try it locally first
The script never publishes, so it never handles the publisher's token. It prints the command to
run:
npx @vscode/vsce@4.1.0 publish --packagePath rohy-vi-0.1.0.vsix
Publish all the platforms of a version together. A machine whose platform has no package for a
version cannot install that version.
Raise version in package.json before each release; the Marketplace refuses a version it
already has.
Checked by hand
The tests drive the extension through a fake VS Code API. They cover which files are checked,
when, and which answer is kept. What only a real VS Code can show is checked by hand, after
installing the package:
- With no
rohyctl on PATH, open a rule in rohy-data/rules/. The status bar reads ✓ rohy,
and rohy: Show Log names the extension's own bin/<platform>-<arch>/rohyctl. On Linux and macOS this also
proves its execute permission was restored. Type "algorithm": "x": the squiggle lands on
"x" within a moment, with the code unknown_algorithm.
- Open
rules-state.json in the same folder: no status bar item, and no problems.
- Run Format Document on a rule with tabs: it is laid out in the house style.
- Set
rohy.rohyctlPath to a path that does not exist: a warning names the setting, and the
status bar reads schema only.
- Add
"rohy.rohyctlPath": "C:\\evil.exe" to a folder's .vscode/settings.json: it is ignored.
- On a Mac with Apple silicon, step 1 also proves macOS runs the packaged
rohyctl.