Void 中 TypeScript/TSX TextMate 语法的来源、维护流程与 Scope 设计演进
Void 中 TypeScript/TSX TextMate 语法的来源、维护流程与 Scope 设计演进
本指南以仓库内 extensions/typescript-basics/syntaxes/Readme.md 为核心,系统讲解 Void 内置 TypeScript / TypeScript React(TSX)语法高亮的来源、升级维护流程、构建期补丁机制,以及维护者针对 scope(语义作用域)命名留下的迁移笔记与设计思考。读完本文,你将理解这一份 TextMate 语法文件是如何从上游项目派生、在每次升级时被自动裁剪与修补、最终通过扩展贡献点接入编辑器渲染管线,并能独立完成一次语法的更新、验证与回归测试。
语法文件的来源与定位
Void(基于 VS Code 体系构建的开源 AI 代码编辑器)将 TypeScript 语法高亮作为一个独立的语言扩展发布,位于 extensions/typescript-basics,核心产物是两份 TextMate grammar 文件:
- TypeScript.tmLanguage.json(scope 为
source.ts,约 231 KB) - TypeScriptReact.tmLanguage.json(scope 为
source.tsx,约 228 KB)
根据 Readme 的明确说明,这两份文件并非本地原创,而是从 TypeScript-TmLanguage 上游项目派生的镜像:分别对应上游的 TypeScript.tmLanguage 与 TypeScriptReact.tmLanguage。在 TypeScript.tmLanguage.json 文件头部的 information_for_contributors 字段中也有同样声明,并记录了生成时所基于的上游提交哈希,方便追溯版本对齐。
因此,对这份语法文件的正确贡献姿势是:先向上游项目提交修复,被上游接纳后再把新版本同步进本仓库,而不是直接改动本地派生文件。这与 Readme 中"欢迎在修复被上游接受后提交更新请求"的说明一致。
升级语法的工作流:更新、补丁与回归测试
Readme 给出了标准的升级路径,结合仓库源码可以还原完整流程。
第一步:拉取上游最新语法
文档中的命令为在 extensions/typescript-basics 目录下执行:
npm run update-grammars
需要说明的是,本扩展自身的 package.json 中实际声明的脚本是单数的 update-grammar(执行 node ./build/update-grammars.mjs);而在仓库根目录的 package.json 中则存在 update-grammars(复数的聚合脚本,执行 node build/npm/update-all-grammars.mjs,用于批量刷新所有语言扩展的语法)。无论从哪个入口执行,最终都会调用扩展下的 update-grammars.mjs 完成实际拉取与转换。
第二步:构建期补丁(patch)
直接拉取的上游语法不会原样落盘,update-grammars.mjs 中通过 patchGrammar 串联了三道补丁,这正是 Readme 末尾关于"library 类型列表是否该保留"这一疑问在工程上的实际答案:
| 补丁函数 | 作用 |
|---|---|
removeDom |
从 support-objects 仓库中剔除 HTMLElement、JSON、Math 等浏览器/DOM 内建类型规则,并移除 support.class.error.、support.class.builtin.、support.function. 前缀的内建支持规则 |
removeNodeTypes |
剔除 Node.js 相关类型(support.variable.object.node、support.class.node.)以及 process、console 等运行时可用的全局对象规则 |
patchJsdoctype |
过滤掉 JSDoc 类型语法(jsdoctype 仓库)中标记为 illegal 的规则 |
也就是说,Readme 中"内置一大串 library 类型会显著增大语法体积、且正确性依赖运行时环境"的顾虑,最终通过在派生时剥离平台相关内建类型来解决:语法只保留语言本体结构,运行时全局由 JavaScript 实际环境决定。同文件的 adaptToJavaScript 函数还会把 TypeScriptReact.tmLanguage 进一步转换为 JavaScript 系列语法(生成 JavaScript.tmLanguage.json 等文件),因此这份 TypeScript 语法的质量同时辐射 JS 语法。
第三步:跑集成测试
Readme 特别强调升级后不要忘记运行集成测试:
./scripts/test-integration.sh
该脚本位于仓库根目录 scripts/test-integration.sh,负责对语法高亮等集成行为做回归验证,防止上游变更破坏现有渲染结果。
Scope 命名迁移笔记与设计思考
Readme 主体是维护者留下的"迁移笔记与待办",这几条笔记直接反映了 TextMate 语法 scope 设计的演进方向,是理解本仓库语法组织方式的关键。
声明与引用的区分
笔记建议:区分"变量/函数声明"与"变量/函数引用",为函数引用引入新的 scope 段 function-call,为声明引入 definition 段;备选方案是统一使用 support.function。从当前 TypeScript.tmLanguage.json 的实际情况看,function-call 片段已在语法中出现多次,且文件中大量使用 entity.name.function.ts 标注函数名、meta.return.type.ts 标注返回类型——这说明"函数名是命名实体、类型位置单独成段"的划分已经落地。
与之呼应的是 package.json 中的 semanticTokenScopes 贡献:它把语义化 token(如 property、variable、function、namespace、variable.defaultLibrary)映射到 TextMate scope(如 variable.other.property.ts、entity.name.function.ts、support.variable.ts)。这意味着编辑器存在两套高亮通道——语法层(TextMate)与语义层(Language Server),而这份映射表正是二者对齐的桥梁。
return.type 重命名为 return-type
笔记指出应把 return.type 改为 return-type,以便与其他语法(例如 Java、C 等)的既有命名习惯保持一致。从当前语法文件看,返回类型 scope 已统一为 meta.return.type.ts 形式,说明该重命名已在历次升级中完成。
entity.name.class 重命名为 entity.name.type.class
同样是为了与其他语法对齐:类型声明统一归入 entity.name.type.* 命名空间。当前 TypeScript.tmLanguage.json 中已使用 entity.name.type.class.ts,而 unbalancedBracketScopes 中列出的 meta.brace.angle、keyword.operator.bitwise.shift 等条目,则是为了在括号匹配时避免把类型参数 <T> 里的尖括号误判为不配对括号——这正是类型语法设计在编辑器底层交互中的延伸。
语法如何接入编辑器:grammars 贡献点
语法文件本身只是 scope 规则,真正接入渲染管线依靠扩展清单中的 contributes.grammars 声明。以 extensions/typescript-basics/package.json 为例:
typescript语言绑定source.ts,typescriptreact绑定source.tsx,语法文件路径指向对应的 tmLanguage JSON;unbalancedBracketScopes列出在括号配对时不应计入配对的 scope(如尖括号、箭头函数、位移运算符);tokenTypes将模板字符串内的表达式、JSDoc 类型实例等标记为other等特殊 token 类型,控制它们不参与括号/缩进等结构化处理;typescriptreact通过embeddedLanguages声明 TSX 标签内的语言嵌套映射(jsx-tags、typescriptreact);- 另外注册了两个 JSDoc 注入语法(
documentation.injection.ts、documentation.injection.js.jsx),通过injectTo注入到source.ts、source.tsx、source.js等语法中,用于在文档注释块内提供高亮与补全,见 jsdoc.ts.injection.tmLanguage.json。
grammars 这个贡献点本身的 schema 定义在核心代码 src/vs/workbench/services/textMate/common/TMGrammars.ts 中,其中 ITMSyntaxExtensionPoint 接口完整描述了 language、scopeName、path、embeddedLanguages、tokenTypes、injectTo、balancedBracketScopes、unbalancedBracketScopes 等字段,任何想为编辑器贡献自定义语法的扩展都可参照此 schema。
配套的语言编辑行为:language-configuration
高亮之外,TypeScript 的编辑体验还由 language-configuration.json 支撑,它与语法文件配合形成完整的语言支持:
- 注释与括号:行注释
//、块注释/* */,以及${ }、{ }、[ ]、( )的括号定义、自动闭合与环绕配对; - 折叠:通过
folding.markers支持// #region/// #endregion折叠标记; - 缩进规则:
increaseIndentPattern/decreaseIndentPattern/unIndentedLinePattern分别处理块开括号的缩进、闭括号的缩进、以及注释行与case/default语句的缩进修正; - 回车行为(onEnterRules):在
/**内回车自动补*续行、在*/前回车自动收尾、在行注释内回车自动补//、在单行if/for/while后回车自动缩进等; - JSDoc 快速注释:输入
/**回车即进入文档注释编辑模式,与注入语法的高亮配合。
测试与验证要点
升级语法后建议按以下顺序自检:
- 运行语法更新脚本,确认两份 TS 语法及派生的 JS 语法文件均已刷新(涉及 update-grammars.mjs 与 extensions/javascript 下的产物);
- 执行 scripts/test-integration.sh 回归集成测试;
- 用编辑器实际打开
.ts、.tsx、.mts、.cts、.tsbuildinfo文件,重点检查泛型尖括号高亮、箭头函数返回类型、JSDoc 块内高亮、#region折叠与缩进行为是否符合预期; - 如需新增代码片段,可参考 typescript.code-snippets 的既有结构(其中已内置
ctor、class、import、get、log等常用片段模板)。
总之,syntaxes/Readme.md 是理解 Void 内 TypeScript 语法体系的"地图":它指明了派生来源、升级流程与 scope 演进方向;而配套的构建脚本、补丁逻辑、扩展清单与核心 schema 代码,则为这条维护路径提供了可执行的完整实现。