♻️ refactor(vscode): 代码阅读的翻译插件只经契约拿语言插件的词性和推导式结构

vscode/src/codeReader/contract.ts

@@ -101,8 +101,8 @@ export type IterationClause
     | { kind: 'if', condition: Node }
 
 /**
- * 写在表达式里的遍历（Python 的列表 / 集合 / 字典推导式、生成器表达式）：语言插件从语法树读出结构，翻译插件按自己的语序重排。
- * 节点都指向源码；各节、每一项取的值里还能再套遍历。
+ * 写在表达式里的遍历（Python 的列表 / 集合 / 字典推导式、生成器表达式）：语言插件从语法树读出结构（LanguageAdapter.iteration），
+ * 翻译插件按自己的语序重排。节点都指向源码；各节、每一项取的值里还能再套遍历。
  */
 export interface IterationFacts {
   result: IterationResult
@@ -247,7 +247,10 @@ export interface PropertyRow extends Defines {
   columns?: string[]
 }
 
-/** 语言插件：语法树 → 代码块树。 */
+/**
+ * 语言插件：语法树 → 代码块树，外加只有它懂、翻译插件翻表达式时要用的信息（叶子的词性、写在表达式里的遍历的结构）。
+ * 翻译插件翻一块时从 SourceDocument.language 拿到解析这份源码的语言插件，不直接依赖某个语言插件。
+ */
 export interface LanguageAdapter {
   id: string
   /** 覆盖的 VS Code languageId，例如 ['typescript', 'typescriptreact', 'javascript', 'javascriptreact']。 */
@@ -256,8 +259,16 @@ export interface LanguageAdapter {
   grammarPath: (languageId: string) => string
   /** languageId 是这份源码的 languageId：一个插件覆盖几种方言时按它区分（JavaScript 没有 TypeScript 的抽象类、仅类型导入）。 */
   toBlocks: (root: Node, source: string, languageId: string) => CodeBlock[]
-  /** 源码着色：给语法树叶子节点定词性。 */
+  /** 给语法树叶子节点定词性：源码着色用它，译文里照抄的词也按它着色、按它认出能查定义的名字。 */
   tokenRole: (leaf: Node) => TokenRole
+  /** node 是写在表达式里的遍历（推导式、生成器表达式）时给出它的结构，别的节点没有；没有这种写法的语言不填。 */
+  iteration?: (node: Node) => IterationFacts | undefined
+}
+
+/** 翻译插件翻一块时拿到的这份源码：源码字符串，和解析它的语言插件。 */
+export interface SourceDocument {
+  source: string
+  language: LanguageAdapter
 }
 
 /** 筛选属性和值的显示名，筛选栏、种类标签用它；没给名字的显示 id。 */
@@ -274,9 +285,9 @@ export interface Translator {
   label: string // '中文直译'
   languageIds: string[]
   /** 只翻 header 那一段；注释块给去掉注释符号的 Markdown 原文。 */
-  translate: (block: TextBlock, source: string) => PreviewText
+  translate: (block: TextBlock, document: SourceDocument) => PreviewText
   /** 函数、类、导入、常量、变量块 → 属性表。 */
-  describe: (block: FactBlock, source: string) => PropertyRow[]
+  describe: (block: FactBlock, document: SourceDocument) => PropertyRow[]
   /** 筛选属性和值叫什么，和属性表里的属性名、值用同一套叫法；不给就都显示 id。 */
   attributeNames?: AttributeNames
 }