✨ feat(vscode): 代码阅读把推导式换成按读的顺序重排的遍历小框

vscode/src/codeReader/contract.ts

@@ -92,6 +92,33 @@ export type EntryFacts
     | { kind: 'spread', value: Node } // **other、...other：value 是展开的那个表达式
     | { kind: 'method', name: Node, node: Node, header: SourceSpan } // 对象字面量里的方法、getter、setter：node 是整个方法，header 同 BlockShape.header，只到主体开始之前
 
+/** 写在表达式里的遍历得到什么：逐个产出的生成器，或一次建好的列表、集合、字典。 */
+export type IterationResult = 'generator' | 'list' | 'set' | 'dict'
+
+/** 遍历的一节，照源码顺序：从来源里逐个取出变量（async：异步地取），或只留下满足条件的。 */
+export type IterationClause
+  = | { kind: 'for', variables: Node, source: Node, async: boolean }
+    | { kind: 'if', condition: Node }
+
+/**
+ * 写在表达式里的遍历（Python 的列表 / 集合 / 字典推导式、生成器表达式）：语言插件从语法树读出结构，翻译插件按自己的语序重排。
+ * 节点都指向源码；各节、每一项取的值里还能再套遍历。
+ */
+export interface IterationFacts {
+  result: IterationResult
+  /** 至少一节，第一节是 for。 */
+  clauses: IterationClause[]
+  /** 每一项取的值。 */
+  value: Node
+  /** 结果是字典时每一项的键。 */
+  key?: Node
+  /**
+   * 遍历自己的一对括号同时是外面调用的括号时（Python `f(x for x in y)` 只写一对括号）是这对括号：
+   * 它们属于外面的调用，照常写在遍历外面；别的写法里遍历自己的括号、方括号、花括号不写出来。
+   */
+  sharedParentheses?: { open: Node, close: Node }
+}
+
 export interface DeclaratorFacts {
   /** 变量名；解构声明是整个模式。 */
   name: Node
@@ -170,6 +197,23 @@ export type TokenRole
  */
 export interface Segment { text: string, role: TokenRole, offset?: number }
 
+/** 框的样式，决定框头的图标和框的颜色：'iteration' 是写在表达式里的遍历，图标、颜色同「循环」块。 */
+export type GroupStyle = 'iteration'
+
+/**
+ * 框起来的一组词：译文里自成一体的一段（写在表达式里的遍历），预览把它画成嵌在前后文字里的一个小框，框头是图标和 label。
+ * 框里的词照样带源码下标，还能再套框。
+ */
+export interface SegmentGroup {
+  style: GroupStyle
+  /** 框头的文字（遍历的结果：生成器 / 列表 …），翻译插件给。 */
+  label: string
+  segments: Inline[]
+}
+
+/** 译文里的一段：着色的词，或框起来的一组词。 */
+export type Inline = Segment | SegmentGroup
+
 /**
  * 一段 Markdown 说明文字：注释、JSDoc、docstring 去掉注释符号、引号和共同缩进后的原文，不做别的转换
  * （reStructuredText 的 `:func:`、JSDoc 的 `@param` 都照抄）。预览按 Markdown 渲染成注释色的段落、列表、代码块，源码里的 HTML 当文字显示。
@@ -177,7 +221,7 @@ export interface Segment { text: string, role: TokenRole, offset?: number }
 export interface Markdown { markdown: string }
 
 /** 预览里显示的一段文字：着色的词（一行译文、属性值），或整段 Markdown 说明（注释块、函数和类的说明）。 */
-export type PreviewText = Segment[] | Markdown
+export type PreviewText = Inline[] | Markdown
 
 /**
  * 属性表里的一行或一个子行讲的是哪个定义：定义出来的那个名字的节点（取自 facts，例如参数名、导入项的名称和别名、
@@ -187,7 +231,7 @@ export interface Defines { defines?: SourceRange }
 
 /** 属性表里展开的一个子行：几列对齐的格子，例如参数的名称 / 类型 / 默认值、字典一项的键 / 值。 */
 export interface PropertyItem extends Defines {
-  cells: Segment[][]
+  cells: Inline[][]
   /** 展开在这个子行下面的下一层子行（字典 / 对象的值又是字典 / 对象时，它的各项）；一层层可以一直往下套。 */
   items?: PropertyItem[]
 }