✨ feat(vscode): 代码阅读的解析与模板直译核心

vscode/src/codeReader/contract.ts

@@ -0,0 +1,54 @@
+import type { Node } from '@vscode/tree-sitter-wasm'
+import type { Disposable } from 'vscode'
+
+export type { Node }
+
+export type BlockKind
+  = | 'import' | 'function' | 'class' | 'type' | 'field' | 'const' | 'variable'
+    | 'if' | 'else' | 'loop' | 'try' | 'catch' | 'finally' | 'return' | 'statement' | 'comment'
+
+/** 源码里的一段，行号从 0 开始；下标是源码字符串下标（web-tree-sitter 的 startIndex / endIndex），end 为开区间。 */
+export interface SourceSpan { startIndex: number, endIndex: number, startRow: number, endRow: number }
+
+export interface CodeBlock {
+  kind: BlockKind
+  /** 这一块对应的语法树节点（整条语句）。 */
+  node: Node
+  /** 块自己显示 / 编辑的那一段：复合语句只到主体开始之前，其余是整条语句。 */
+  header: SourceSpan
+  children: CodeBlock[]
+}
+
+/** 着色用的词性，源码着色和译文着色共用。 */
+export type TokenRole
+  = | 'keyword' // 流程关键字：import from export if else for return try catch await …
+    | 'storage' // 声明关键字与字面量关键字：const function async class interface new true false null …
+    | 'operator' // 被翻成文字的运算符：全等 与 或 非
+    | 'variable' | 'function' | 'type' | 'string' | 'number' | 'literal' | 'comment' | 'plain'
+
+export interface Segment { text: string, role: TokenRole }
+
+/** 语言插件：语法树 → 代码块树。 */
+export interface LanguageAdapter {
+  id: string
+  /** 覆盖的 VS Code languageId，例如 ['typescript', 'typescriptreact', 'javascript', 'javascriptreact']。 */
+  languageIds: string[]
+  /** 该 languageId 用的语法包 .wasm 的绝对路径（宿主负责加载，保证和解析器运行时是同一份）。 */
+  grammarPath: (languageId: string) => string
+  toBlocks: (root: Node, source: string) => CodeBlock[]
+  /** 源码着色：给语法树叶子节点定词性。 */
+  tokenRole: (leaf: Node) => TokenRole
+}
+
+/** 翻译插件：代码块 → 译文。 */
+export interface Translator {
+  id: string // 'typescript.zh-template'
+  label: string // '中文直译'
+  languageIds: string[]
+  translate: (block: CodeBlock, source: string) => Segment[]
+}
+
+export interface CodeReaderApi {
+  registerLanguage: (adapter: LanguageAdapter) => Disposable
+  registerTranslator: (translator: Translator) => Disposable
+}