openvscode-server 中的 TypeScript 语法高亮:TextMate 语法的来源、更新流程与演进路线
openvscode-server 中的 TypeScript 语法高亮:TextMate 语法的来源、更新流程与演进路线
本篇技术指南围绕 openvscode-server 仓库中 extensions/typescript-basics/syntaxes/Readme.md 展开,系统讲解 TypeScript.tmLanguage.json 与 TypeScriptReact.tmLanguage.json 两份 TextMate 语法的上游来源、一键更新流程、定制化补丁逻辑,以及维护者在迁移笔记中记录的 scope 命名演进方向。读完本文,你将掌握该仓库 TypeScript 语法文件从"上游拉取 → 本地补丁 → 集成测试"的完整闭环,并能理解语法高亮 scope 命名的设计取舍。
一、语法文件全景:一份扩展里的四份语法
typescript-basics 是 openvscode-server 仓库中的基础语言扩展之一,其 syntaxes/ 目录下实际存放着四份与 TypeScript/JavaScript 高亮相关的语法文件:
| 文件 | 作用 |
|---|---|
TypeScript.tmLanguage.json |
source.ts 作用域,负责 .ts / .cts / .mts 文件的着色 |
TypeScriptReact.tmLanguage.json |
source.tsx 作用域,负责 .tsx(TypeScript + JSX)文件的着色 |
jsdoc.ts.injection.tmLanguage.json |
JSDoc 文档注释注入语法,注入目标为 source.ts 与 source.tsx |
jsdoc.js.injection.tmLanguage.json |
JSDoc 注入语法,注入目标为 source.js 与 source.js.jsx |
根据 extensions/typescript-basics/package.json 中的 contributes 声明,typescript 语言通过 extensions 字段关联 .ts、.cts、.mts,并通过 firstLine 正则 ^#!.*\b(deno|bun|ts-node)\b 识别 shebang 行;typescriptreact 关联 .tsx。两份主语法通过 unbalancedBracketScopes 声明了容易造成括号配平失衡的 scope(如 meta.brace.angle、keyword.operator.bitwise.shift 等),并通过 tokenTypes 将模板表达式、JSDoc 类型实例等标记为 other,避免它们被误当作普通标识符参与后续处理。同时,semanticTokenScopes 将语义令牌(property、variable、function、namespace 等)映射到 variable.other.property.ts、entity.name.function.ts 等 TextMate scope,使语义高亮与语法高亮能协同工作。
两份 JSDoc 注入语法则通过 injectionSelector: "L:comment.block.documentation" 将文档注释内的类型标注着色为对应语言的 scope(详见 jsdoc.ts.injection.tmLanguage.json)。
二、上游来源与派生关系:一份语法,全家受益
Readme 开门见山地说明了语法的出身:TypeScript.tmLanguage.json 与 TypeScriptReact.tmLanguage.json 均派生自微软官方维护的 TypeScript-TmLanguage 上游仓库(对应文件为 TypeScript.tmLanguage 与 TypeScriptReact.tmLanguage)。这一点也能在语法文件头部的 information_for_contributors 中得到印证——文件开头就写明"本文件由上游转换而来,若要修复或改进,请向上游仓库提交 PR,被采纳后我们会收到更新请求",并记录了当前对应的上游 commit 哈希(见 TypeScript.tmLanguage.json)。
更有意思的是派生链条并不止于 TypeScript 自身:根据 extensions/javascript/syntaxes/Readme.md,JavaScript 的两份语法 JavaScript.tmLanguage.json 与 JavaScriptReact.tmLanguage.json 同样派生自 TypeScriptReact.tmLanguage,更新脚本会执行一系列改写(fileTypes .tsx → .js/.jsx、scopeName scope.tsx → scope.js、全部规则名 .tsx → .js)。也就是说,一份 TypeScript 上游语法,经过本地补丁与改写,同时滋养了仓库内 TypeScript 与 JavaScript 四个语法文件,这也是整个更新流程设计成"一处运行、多文件落盘"的原因。
三、一键更新到最新版:命令与完整流程
Readme 给出了更新语法的两条明确步骤:
cd extensions/typescript-basics
npm run update-grammars
./scripts/test-integration.sh
第一步中的 npm run update-grammars 由 package.json 中的 scripts.update-grammar 定义,实际执行的是:
node ./build/update-grammars.mjs
build/update-grammars.mjs 的核心只有寥寥数行,却完成了整个同步任务。它引入了 vscode-grammar-updater 的 update 函数,分四路从上游仓库抓取语法:
var tsGrammarRepo = 'microsoft/TypeScript-TmLanguage';
update(tsGrammarRepo, 'TypeScript.tmLanguage', './syntaxes/TypeScript.tmLanguage.json', grammar => patchGrammar(grammar));
update(tsGrammarRepo, 'TypeScriptReact.tmLanguage', './syntaxes/TypeScriptReact.tmLanguage.json', grammar => patchGrammar(grammar));
update(tsGrammarRepo, 'TypeScriptReact.tmLanguage', '../javascript/syntaxes/JavaScript.tmLanguage.json', grammar => adaptToJavaScript(patchGrammar(grammar), '.js'));
update(tsGrammarRepo, 'TypeScriptReact.tmLanguage', '../javascript/syntaxes/JavaScriptReact.tmLanguage.json', grammar => adaptToJavaScript(patchGrammar(grammar), '.js.jsx'));
可以清晰看到两条生成路径:
- 直接路径:上游
TypeScript.tmLanguage→ 本地TypeScript.tmLanguage.json;上游TypeScriptReact.tmLanguage→ 本地TypeScriptReact.tmLanguage.json,两者都仅经过patchGrammar。 - 派生路径:上游
TypeScriptReact.tmLanguage→../javascript/syntaxes/下的两份 JavaScript 语法,经过patchGrammar后再套一层adaptToJavaScript。
3.1 本地定制补丁:为什么不能直接照搬上游
如果只是简单拷贝上游文件,仓库内的 TypeScript 语法会带着一批"多余的"内置对象规则。patchGrammar 由三个子补丁串联而成(build/update-grammars.mjs):
removeDom(移除 DOM 相关内置对象):过滤support-objects仓库中的规则,剔除匹配HTMLElement、ATTRIBUTE_NODE、stopImmediatePropagation、JSON、Math等关键词的 pattern,并移除所有support.class.error.*、support.class.builtin.*、support.function.*前缀的规则。理由正如 Readme 末尾的疑虑:浏览器运行时的内置对象(Math、JSON、DOM 等)不应硬编码在语法里——它们在 Node、Deno、浏览器等不同运行时下存在与否并不一致。removeNodeTypes(移除 Node.js 内置对象):继续裁剪support-objects,移除support.variable.object.node.*、support.class.node.*,以及 capture 中命中support.variable.object.process、support.class.console的规则。patchJsdoctype(修正 JSDoc 类型标注):过滤jsdoctype仓库,删除 name 中包含illegal的 pattern,避免 JSDoc 类型语法中出现"非法"标记。
以当前仓库文件验证:对 TypeScript.tmLanguage.json 检索 support.class.Math、support.class.JSON、support.variable.object.node、support.class.node 均无任何命中,说明这些补丁已在同步产物中生效。
3.2 adaptToJavaScript:从 TSX 语法改写 JS 语法
adaptToJavaScript(grammar, replacementScope)(build/update-grammars.mjs)完成三件事:
- 将语法
name改写为JavaScript (with React support),fileTypes改为.js、.jsx、.es6、.mjs、.cjs; - 将
scopeName改写为source+replacementScope(即.js或.js.jsx); - 递归遍历整棵规则树,把所有规则
name/contentName中的.tsx后缀替换为replacementScope。
这解释了为什么维护者可以在同一仓库里以"零手写"的方式维护 TypeScript 与 JavaScript 两套语法——JavaScript 完全是 TypeScript 语法的"改名换姓"版本,任何上游修复都能自动同步到两处。
四、迁移笔记与待办事项:scope 命名的演进方向
Readme 中部记录了一组"迁移笔记与待办(Migration notes and todos)",它们并非纯粹的遗留琐事,而是当前语法文件高亮精度的设计路线图。我们结合语法文件逐一核对其落地情况。
4.1 区分声明与引用:function-call 与 definition 的引入
第一条待办是"区分变量/函数声明与引用"。维护者提出两种方案:
- 引入新 scope 段
function-call标识函数引用,用definition标识声明; - 备选方案是统一使用
support.function标记所有函数。
对照当前语法文件,function-call 方案已经落地:语法顶层 repository 中出现了独立的 function-call 规则(TypeScript.tmLanguage.json),内部通过 meta.function-call.ts 包裹被调用表达式,并递归引用 #function-call-target、#function-call-optionals、#type-arguments、#paren-expression 等子规则。整套 begin/end 正则还针对带泛型参数的函数调用(fn<T>(x))与紧邻对象字面量的调用(fn<{...}>())做了专门的分支处理,说明这一 scope 已不是简单的标记,而是一套完整的调用表达式识别机制。
至于"为变量声明引入 definition scope 段、并寻找其他语法也在使用的引用 scope"这一半,从当前文件对 definition. 的大量使用(超过百处)来看,声明侧的 scope 体系已相当完善,但"变量引用统一 scope"仍属持续推进中的开放问题。
4.2 return.type → return-type:对齐其他语法的命名
第二条待办是"把 return.type 重命名为 return-type,其他语法已在采用后者"。对当前 TypeScript.tmLanguage.json 检索可见,return-type 已有约 20 处命中,而 return.type(精确形式)不再出现,说明该重命名已基本完成,当前语法统一使用连字符风格的 return-type 来表示函数返回类型。
4.3 entity.name.class → entity.name.type.class
第三条待办是"把 entity.name.class 重命名为 entity.name.type.class,以对齐其他语法"。同样以当前文件验证:entity.name.type.class 已有命中(entity.name.class 的裸形式则不再单独出现),说明这一规范化也已落地。这类重命名的重要性在于:scope 不仅是着色依据,还是所有消费 TextMate scope 的上层功能(主题、符号大纲、括号配对、语义令牌映射等)的契约,跨语法保持一致命名能显著降低主题作者与工具链的适配成本。
4.4 library 类型清单的取舍:仍在悬而未决的讨论
最后一条以问句形式出现的待办最有意思:"我们真的需要把所有 library 类型(Math、Dom……)都列进语法吗?"维护者列出的成本是:语法文件体积显著膨胀、引入大量特殊规则,而且这些内置类型是否真实存在取决于 JavaScript 运行时,硬编码本身就是不准确的。
结合 3.1 节的源码证据,这个疑问已经有了明确的工程答案——更新脚本中的 removeDom 与 removeNodeTypes 正是对这条待办的执行:与其维护一份注定过时的内置类型清单,不如把它们从语法中移除,让类型信息的呈现交给 TypeScript 语言服务与语义高亮(semanticTokenScopes)去完成。这也体现了 TextMate 语法与现代语义高亮之间的分工原则:语法只管词法形状,类型语义交给编译前端。
五、质量保障:改完语法必须跑集成测试
Readme 特别强调:"别忘了运行集成测试 ./scripts/test-integration.sh"(原文档中该命令是相对于仓库根目录执行的)。打开 scripts/test-integration.sh 可以看到,该脚本依次运行 node.js 集成测试、API 测试(folder / workspace 两种形态)、以及多个扩展的测试套件。与语法高亮直接相关的是其中的 Colorize 测试:
npm run test-extension -- -l vscode-colorize-tests
(见 scripts/test-integration.sh)
vscode-colorize-tests 扩展内置了大量着色用例与期望快照:在 extensions/vscode-colorize-tests/test/colorize-fixtures 中有 test.ts 等 TypeScript 夹具,对应的期望结果快照则存放在 test/colorize-results(如 test_ts.json)与 tree-sitter 对照版 test/colorize-tree-sitter-results。更新语法后,任何 scope 回归都会在快照比对中暴露出来——这正是"更新语法 → 跑集成测试"这一纪律存在的意义。
六、总结:一份语法文件的可持续维护之道
回顾整个机制,openvscode-server 对 TypeScript 语法高亮的维护思路可以概括为三条原则:
- 永远以官方上游为单一事实来源,仓库内文件只是"带补丁的镜像",任何修复都应先反馈上游;
- 用脚本而非手工完成同步、裁剪与改写,
update-grammars.mjs一个命令同时维护四份语法文件,把"上游升级带来的回归风险"压缩到最小; - 用快照测试锁死行为,
scripts/test-integration.sh中的 colorize 测试确保 scope 变更不会悄悄破坏既有着色。
对于希望参与 openvscode-server 语言支持工作的开发者,这份 Readme 与 build/update-grammars.mjs 是绝佳的起点:从运行 npm run update-grammars 开始,观察 patchGrammar 对 support-objects 的裁剪,再对照 function-call、return-type、entity.name.type.class 等 scope 的实际落地情况,即可完整理解仓库内 TypeScript/JavaScript 语法高亮从上游到产物的整条链路。