>_EXECUTIVE SUMMARY
vscode-zsh is the VS Code / VSCodium extension for zshrs — the first-ever Rust rewrite of zsh, a compiled, JIT'd, massively parallel shell. It ships a declarative language contribution (filetype, grammar, editor config), an LSP client that launches zshrs --lsp, and a TextMate grammar that is generated from the zshrs binary's own reflection tables.
Design principle: the grammar owns its own zshrs language id and source.zshrs scope — not a shellscript reskin, not a hand-picked subset. scripts/gen_grammar.sh dumps zshrs --dump-reflection (.builtins, .extensions, .special_vars, .keywords) from the live binary and emits a single source.zshrs grammar carrying the real shell surface. The zshrs world-first extensions get their own scope (support.function.extension.zshrs). Regenerate after a zshrs upgrade and it stays in sync.
~COMPONENTS
| File | Responsibility |
|---|---|
package.json | Extension manifest — contributes.languages (id zshrs, zsh extensions + dotfile filenames, shebang firstLine), contributes.grammars (source.zshrs), contributes.configuration (LSP settings), 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:zshrs and starts a LanguageClient running zshrs --lsp over stdio. Missing binary → one non-fatal warning; highlighting still works. |
syntaxes/zshrs.tmLanguage.json | Generated TextMate grammar — comments, shebang, strings / here-docs, numbers, sigil variables, command substitution, control + declaration keywords, 137 builtins, 113 extensions, 245 special vars, and operators / pipes / redirects. |
scripts/gen_grammar.sh | Regenerates the grammar from zshrs --dump-reflection. Builtins exclude keyword and extension names; names are emitted longest-first so the alternation never matches a prefix of a longer name. |
scripts/tokenize_test.js | Loads the grammar under vscode-textmate + vscode-oniguruma (the engine VS Code itself uses) and asserts the scope of 7 sample tokens. |
$SCOPE MAP
| Token group | TextMate scope | Sample |
|---|---|---|
| Control flow | keyword.control.zshrs | if then fi for while case esac function return |
| Declarations | storage.modifier.zshrs | typeset local export declare readonly integer float |
| Builtins (137) | support.function.builtin.zshrs | bindkey autoload zstyle compadd setopt zle alias |
| Extensions (113) | support.function.extension.zshrs | base64 async await barrier clone arch |
| Special variables (245) | variable.language.zshrs | PATH HOME PWD RANDOM |
| Sigil variables | variable.other.zshrs | $foo ${bar} $1 $? $@ $# $$ |
| Operators / pipes / redirects | keyword.operator.zshrs | | || && ;; > >> << >& =~ |
| Literals & vars | string.* / constant.numeric / variable.* | strings, here-docs, command substitution, sigils, numbers |
#VERIFICATION
The generated grammar is loaded under the exact engine VS Code uses at runtime — vscode-textmate driving vscode-oniguruma — and a sample is tokenized with the resulting scopes asserted. This proves the builtin / extension / special-var alternations compile under oniguruma and classify tokens correctly, with extensions matched ahead of plain builtins so a name such as base64 resolves to support.function.extension.zshrs.
| Sample token | Asserted scope |
|---|---|
typeset | storage.modifier.zshrs |
for | keyword.control.zshrs |
bindkey | support.function.builtin.zshrs |
base64 (extension) | support.function.extension.zshrs |
"^R" (double string) | string.quoted.double.zshrs |
$out (interpolated var) | variable.other.interpolated.zshrs |