>_EXECUTIVE SUMMARY
vscode-arb is the VS Code / VSCodium extension for arb — a Tcl/Tk-flavored declarative language for visualizing and modifying Unix pipelines, on the fusevm bytecode VM + Cranelift JIT. It ships a declarative language contribution (filetype, grammar, editor config), an LSP client that launches arb --lsp, a debug adapter that launches arb --dap, and a TextMate grammar (source.arb) covering the arb surface: widgets, query verbs, input sources, directives, widget paths, and -flags.
Design principle: mirror the proven vscode-stryke runtime wiring. The LSP transport is omitted so the client spawns bare arb --lsp and never appends --stdio (the arg-rejection / “connection got disposed” failure mode learned from vscode-stryke). The binary is resolved to an absolute path through $PATH plus common install dirs (~/.cargo/bin, /opt/homebrew/bin, …), so it works even when the editor is launched from the macOS Dock and doesn’t inherit the shell $PATH.
~COMPONENTS
| File | Responsibility |
|---|---|
package.json | Extension manifest — contributes.languages (id arb, *.arb), contributes.grammars (source.arb), contributes.configuration (LSP settings), contributes.commands (run / debug), contributes.debuggers (type arb), and the vscode-languageclient dependency. |
language-configuration.json | Line comment #, brackets, auto-closing / surrounding pairs, word pattern, and brace-based indentationRules. |
extension.js | Activates on onLanguage:arb. Starts a LanguageClient running arb --lsp over stdio, registers the run command (terminal arb <file>), and registers a DebugAdapterDescriptorFactory launching arb --dap. Missing binary → one non-fatal warning; highlighting still works. |
lib/resolveBinary.js | Pure (vscode-free) resolver that turns the arb.path setting into an absolute, executable path — searching $PATH then the GUI-missed fallback dirs. Unit-tested in CI. |
syntaxes/arb.tmLanguage.json | TextMate grammar — comments, shebang, single/double strings, /.../ regex, numbers / durations / sizes, widgets, query verbs, input sources, directives, keywords, widget paths, flags, and operators. |
scripts/tokenize_test.js | Loads the grammar under vscode-textmate + vscode-oniguruma (the engine VS Code itself uses) and asserts the scope of 16 sample tokens. |
$SCOPE MAP
| Token group | TextMate scope | Sample |
|---|---|---|
| Widgets | support.class.widget.arb | text table gauge bars spark tail select |
| Query verbs | support.function.arb | field where map tally sort_by group_by percentile |
| Input sources | support.constant.source.arb | in in.json in.csv in.logfmt in.yaml |
| Directives | keyword.other.directive.arb | source bind grid out timeout expect |
| Control flow | keyword.control.arb | if elif else for while match return |
| Declarations | storage.type.arb | fn var let import save |
| Widget paths | variable.other.widget-path.arb | .codes .errors .ps.sel |
| Flags | variable.parameter.flag.arb | -label -max -cols -color |
| Operators | keyword.operator.arb | |> <- => .. |
| Literals | string.* / constant.numeric / string.regexp | strings, numbers, durations, /.../ regex |
#VERIFICATION
The grammar is loaded under the exact engine VS Code uses at runtime — vscode-textmate driving vscode-oniguruma — and a sample spec is tokenized with the resulting scopes asserted. This proves the grammar compiles under oniguruma and classifies arb tokens correctly, including the tricky cases: a /.../ regex literal distinguished from division, a dotted widget path such as .codes, a query verb in pipe position, and a -flag.
| Sample token | Asserted scope |
|---|---|
gauge | support.class.widget.arb |
in.logfmt | support.constant.source.arb |
/^5/ | string.regexp.arb |
.codes | variable.other.widget-path.arb |
tally | support.function.arb |
source / -max | keyword.other.directive.arb / variable.parameter.flag.arb |