void 编辑器 JavaScript 语法高亮:TypeScript TextMate 语法派生的实现原理与更新流程
void 编辑器 JavaScript 语法高亮:TypeScript TextMate 语法派生的实现原理与更新流程
导读
本文围绕 extensions/javascript/syntaxes/Readme.md 的核心内容,深入讲解 void 编辑器(开源 AI 代码编辑器)中 JavaScript 语法高亮(TextMate Grammar)如何从 TypeScript 语法派生而来,包括完整的更新命令、三步转换规则(fileTypes / scopeName / 规则命名),并结合 update-grammars.mjs 源码剖析底层实现。读完本文,你将掌握这套「单一上游语法源、自动化派生下游语法」的维护机制,能够独立完成语法文件的同步升级与集成测试。
一、背景:为什么 JavaScript 语法要「派生」自 TypeScript
在主流编辑器的语言服务实践中,JavaScript 与 TypeScript 共享同一套语法体系——JS 是 TS 的类型子集。因此,与其维护两份独立的 TextMate 语法文件并忍受二者逐步漂移,void 仓库选择了「单一上游、自动派生」的策略:
- 上游唯一事实来源:语法以
TypeScriptReact.tmLanguage(以及TypeScript.tmLanguage)为准,二者来自 Microsoft 官方维护的 TypeScript-TmLanguage 项目; - JavaScript 为下游产物:
JavaScript.tmLanguage.json与JavaScriptReact.tmLanguage.json由脚本从 TypeScript 语法自动转换生成,不手工维护; - 规则命名体现语言归属:派生产物中所有作用域(scope)名称的后缀从
.tsx改写为.js(或.js.jsx),保证高亮主题、语义着色规则能按语言精确匹配。
这一点在 JavaScript.tmLanguage.json 文件头部有直接证据:文件开头的 information_for_contributors 字段明确写着「This file has been converted from TypeScriptReact.tmLanguage」,并提示所有修复应向上游仓库提交 PR,上游合入后再同步回本仓库。
二、一次完整的语法升级:操作步骤
按 extensions/javascript/syntaxes/Readme.md 的指引,将语法升级到最新版本分为两步:
2.1 运行语法更新脚本
cd extensions/typescript-basics
npm run update-grammars
脚本会从上游 microsoft/TypeScript-TmLanguage 拉取最新语法,并同步生成以下四份文件:
| 生成文件 | 相对仓库根目录路径 | 派生来源 |
|---|---|---|
| TypeScript 语法 | extensions/typescript-basics/syntaxes/TypeScript.tmLanguage.json | 上游 TypeScript.tmLanguage |
| TypeScript React 语法 | extensions/typescript-basics/syntaxes/TypeScriptReact.tmLanguage.json | 上游 TypeScriptReact.tmLanguage |
| JavaScript 语法 | extensions/javascript/syntaxes/JavaScript.tmLanguage.json | 上游 TypeScriptReact.tmLanguage 转换而来 |
| JavaScript React 语法 | extensions/javascript/syntaxes/JavaScriptReact.tmLanguage.json | 上游 TypeScriptReact.tmLanguage 转换而来 |
注意一处命令名差异:关联文档中写作
npm run update-grammars(复数),而当前仓库 extensions/typescript-basics/package.json 中scripts段实际定义的是"update-grammar": "node ./build/update-grammars.mjs"(单数)。在 void 仓库当前版本下,应执行npm run update-grammar;若脚本名与文档不一致,以 package.json 中的实际定义为准。
2.2 运行集成测试验证
./scripts/test-integration.sh
语法文件属于编辑器「集成面」组件,直接影响高亮、括号匹配与代码片段行为,因此升级后必须跑仓库根目录下的 scripts/test-integration.sh 集成测试,确认没有引入回归。
三、三步转换规则:从 .tsx 到 .js 的机械改写
关联文档明确列出脚本执行的三处核心转换,这也是理解整套派生机制的关键:
-
fileTypes:
.tsx→.js与.jsx上游语法的文件扩展名声明被替换为 JS 生态的文件类型,使语法能正确关联到.js、.jsx(以及.mjs、.cjs、.es6)文件。 -
scopeName:
scope.tsx→scope.js语法文件的顶层作用域名从 TypeScript React 命名改写为 JavaScript 命名。源码中通过grammar.scopeName = 'source' + replacementScope实现,对应派生产物中的"scopeName": "source.js"(JavaScript)与"scopeName": "source.js.jsx"(JavaScript React)。 -
所有规则名称:
.tsx→.js语法仓库中成百上千条 rule 的name与contentName字段统一把.tsx后缀替换为目标后缀。由于这是对整个 grammar 对象的递归遍历,任何嵌套在 pattern 内部的规则名都不会遗漏。
需要强调的是:这是一次深度的、全量的重命名,而不是对顶层几个字段的简单替换。正因为规则命名完整保留了 keyword.、string.、comment.、meta. 等 TextMate 作用域层级,VSCode 风格的主题与 void 编辑器的语义着色才能无缝复用这套 JavaScript 高亮。
四、源码级原理:update-grammars.mjs 的实现细节
转换逻辑全部集中在 extensions/typescript-basics/build/update-grammars.mjs,下面拆解其关键实现。
4.1 上游拉取与四路输出
脚本基于 vscode-grammar-updater 包提供的 update 函数,从 microsoft/TypeScript-TmLanguage 仓库拉取语法:
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 两份文件只做 patchGrammar(通用修补),而 JavaScript 两份文件在 patchGrammar 之后再套一层 adaptToJavaScript,这正是派生流程的落点。
4.2 adaptToJavaScript:三步转换的代码落地
function adaptToJavaScript(grammar, replacementScope) {
grammar.name = 'JavaScript (with React support)';
grammar.fileTypes = ['.js', '.jsx', '.es6', '.mjs', '.cjs'];
grammar.scopeName = 'source' + replacementScope;
// fixScopeNames 递归遍历所有 rule 的 name / contentName,
// 把其中的 .tsx 后缀替换为 replacementScope(.js 或 .js.jsx)
}
- 文件扩展名:派生语法支持
.js、.jsx、.es6、.mjs、.cjs五种文件类型,覆盖现代 JavaScript 工程的模块格式(ESM 的.mjs、CommonJS 的.cjs); - 作用域命名:
replacementScope参数区分两份产物——.js用于纯 JavaScript,.js.jsx用于带 JSX 的 JavaScript React 语法; - 规则重命名:
fixScopeNames对 grammar 对象做深度递归,凡name或contentName为字符串的字段都执行.tsx → .js的替换,保证整个作用域树命名一致。
4.3 上游语法同步前的通用修补(patchGrammar)
在派生之前,脚本还会对上游语法做三类修补,避免将 DOM / Node.js 的宿主环境类型错误地带入语言层:
removeDom:过滤HTMLElement、ATTRIBUTE_NODE、stopImmediatePropagation、JSON、Math等浏览器 DOM / 内建对象匹配规则,以及support.class.error.、support.class.builtin.、support.function.前缀的规则;removeNodeTypes:剔除support.variable.object.node、support.class.node.、support.variable.object.process、support.class.console等 Node.js 环境类型;patchJsdoctype:移除 JSDoc 类型中illegal相关的非法规则。
这些修补让高亮语法保持「纯语言」属性,宿主环境(浏览器 / Node.js)的类型则由语言服务层(semantic token)另行补充,属于职责分离的经典设计。
4.4 产物中的对应证据
打开 extensions/javascript/syntaxes/JavaScript.tmLanguage.json 即可验证上述流程的结果:
- 顶层
"name": "JavaScript (with React support)"、"scopeName": "source.js"; repository中包含shebang、statements、declaration、control-statement、expression、string、comment等完整的 JavaScript 语句级规则,且匹配#declaration、#var-expr、#function-declaration等递归引用;shebang规则match: "\\A(#!).*(?=$)"支持 Unix 脚本首行#!/usr/bin/env node的注释高亮。
五、配套语法:JS 专属的 JSDoc 注入语法
除主语法外,仓库还维护了一份为 JavaScript 定制的作用域注入语法:extensions/typescript-basics/syntaxes/jsdoc.js.injection.tmLanguage.json。
在 extensions/typescript-basics/package.json 的 contributes.grammars 中,它被声明为:
{
"scopeName": "documentation.injection.js.jsx",
"path": "./syntaxes/jsdoc.js.injection.tmLanguage.json",
"injectTo": ["source.js", "source.js.jsx"]
}
即把 JSDoc 注释规则注入到 source.js 与 source.js.jsx 两个作用域中;对应地,TypeScript 侧也有 jsdoc.ts.injection.tmLanguage.json(injectTo 为 source.ts / source.tsx)。这种「注入式」设计使 JSDoc 高亮可以按语言独立演进,无需改动主语法文件。
六、维护建议与注意事项
结合本文梳理的机制,给语法维护者几点实操建议:
- 改动一律走上游:对 JavaScript 高亮的任何修复都应提交到 TypeScript-TmLanguage 上游仓库,合入后再用
npm run update-grammar同步回 void 仓库,避免下游手工改动在下次同步时被覆盖; - 升级后必跑集成测试:语法重命名与规则过滤属于高回归风险操作,务必执行 scripts/test-integration.sh;
- 留意脚本命名漂移:文档中的
update-grammars与当前 package.json 中的update-grammar存在单复数差异,执行前先确认实际脚本名; - 检查派生差异:同步后可对比
JavaScript.tmLanguage.json与TypeScriptReact.tmLanguage.json的头部version字段,确认上游 commit 一致。
结语
void 编辑器的 JavaScript 语法高亮并非独立实现,而是通过「TypeScript-TmLanguage 上游 + 自动化派生脚本 + 三步命名转换 + 宿主环境规则过滤 + JSDoc 注入」的组合方案,以极低的维护成本获得了与 TypeScript 同步演进的高质量高亮体验。这套机制的核心代码量不足百行,却承载了 JS/TS 两个语言族在编辑器中的语法一致性,是理解「单一事实来源」思想的绝佳范例——从 update-grammars.mjs 出发,你可以沿着这条链路一路读到派生产物与注入语法,完整还原整条语法供应管线。