Void 中 TypeScript/TSX TextMate 语法的来源、维护流程与 Scope 设计演进

原创2026-09-10 13:33:491,635 阅读
文章标签:代码编辑器AI 应用代码智能体人工智能桌面应用

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 文件:

根据 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 快速注释:输入 /** 回车即进入文档注释编辑模式,与注入语法的高亮配合。

测试与验证要点

升级语法后建议按以下顺序自检:

  1. 运行语法更新脚本,确认两份 TS 语法及派生的 JS 语法文件均已刷新(涉及 update-grammars.mjs 与 extensions/javascript 下的产物);
  2. 执行 scripts/test-integration.sh 回归集成测试;
  3. 用编辑器实际打开 .ts、.tsx、.mts、.cts、.tsbuildinfo 文件,重点检查泛型尖括号高亮、箭头函数返回类型、JSDoc 块内高亮、#region 折叠与缩进行为是否符合预期;
  4. 如需新增代码片段,可参考 typescript.code-snippets 的既有结构(其中已内置 ctor、class、import、get、log 等常用片段模板)。

总之,syntaxes/Readme.md 是理解 Void 内 TypeScript 语法体系的"地图":它指明了派生来源、升级流程与 scope 演进方向;而配套的构建脚本、补丁逻辑、扩展清单与核心 schema 代码,则为这条维护路径提供了可执行的完整实现。

登录后查看全文
void