void 编辑器 JavaScript 语法高亮:TypeScript TextMate 语法派生的实现原理与更新流程

原创2026-09-09 17:17:462,190 阅读
文章标签:代码编辑器AI 应用代码智能体人工智能桌面应用

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 的机械改写

关联文档明确列出脚本执行的三处核心转换,这也是理解整套派生机制的关键:

  1. fileTypes:.tsx → .js 与 .jsx 上游语法的文件扩展名声明被替换为 JS 生态的文件类型,使语法能正确关联到 .js、.jsx(以及 .mjs、.cjs、.es6)文件。

  2. scopeName:scope.tsx → scope.js 语法文件的顶层作用域名从 TypeScript React 命名改写为 JavaScript 命名。源码中通过 grammar.scopeName = 'source' + replacementScope 实现,对应派生产物中的 "scopeName": "source.js"(JavaScript)与 "scopeName": "source.js.jsx"(JavaScript React)。

  3. 所有规则名称:.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 高亮可以按语言独立演进,无需改动主语法文件。

六、维护建议与注意事项

结合本文梳理的机制,给语法维护者几点实操建议:

  1. 改动一律走上游:对 JavaScript 高亮的任何修复都应提交到 TypeScript-TmLanguage 上游仓库,合入后再用 npm run update-grammar 同步回 void 仓库,避免下游手工改动在下次同步时被覆盖;
  2. 升级后必跑集成测试:语法重命名与规则过滤属于高回归风险操作,务必执行 scripts/test-integration.sh;
  3. 留意脚本命名漂移:文档中的 update-grammars 与当前 package.json 中的 update-grammar 存在单复数差异,执行前先确认实际脚本名;
  4. 检查派生差异:同步后可对比 JavaScript.tmLanguage.json 与 TypeScriptReact.tmLanguage.json 的头部 version 字段,确认上游 commit 一致。

结语

void 编辑器的 JavaScript 语法高亮并非独立实现,而是通过「TypeScript-TmLanguage 上游 + 自动化派生脚本 + 三步命名转换 + 宿主环境规则过滤 + JSDoc 注入」的组合方案,以极低的维护成本获得了与 TypeScript 同步演进的高质量高亮体验。这套机制的核心代码量不足百行,却承载了 JS/TS 两个语言族在编辑器中的语法一致性,是理解「单一事实来源」思想的绝佳范例——从 update-grammars.mjs 出发,你可以沿着这条链路一路读到派生产物与注入语法,完整还原整条语法供应管线。

登录后查看全文
void