✨ feat(vscode): 代码阅读的调用与构造：跨多行写的调用排成「新建 / 调用 名字 · N 个参数」一行，实参摊成参数 / 值表；Python 查被调用名字的定义分新建和调用，查到后刷新

vscode/src/codeReader/contract.ts

@@ -179,6 +179,32 @@ export interface IterationFacts {
   sharedParentheses?: { open: Node, close: Node }
 }
 
+/** 调用里的一个实参，照源码顺序；注释不算。 */
+export type CallArgument
+  = | { kind: 'positional', value: Node } // 按位置传的
+    | { kind: 'keyword', name: Node, value: Node } // 按名字传的：Python 的 name=value
+    | { kind: 'spread', value: Node } // 展开成按位置传的几个：*args、...args；value 是展开的那个表达式
+    | { kind: 'keywordSpread', value: Node } // 展开成按名字传的几个：Python 的 **kwargs
+
+/**
+ * 一次调用（含新建对象）：语言插件从语法树读出结构（LanguageAdapter.call），翻译插件把跨几行写的调用排成
+ * 「新建 / 调用 被调用的名字 · N 个参数」一行，实参摊成一张表。节点都指向源码。
+ */
+export interface CallFacts {
+  /** 被调用的表达式：`user_service.update_user`、`UserDetailResponse`；TypeScript 的 new 不算在里面。 */
+  callee: Node
+  /** callee 里最后那个名字（点分名字的最后一节）：着色、查定义用它；callee 不是名字（`f()()`、`handlers[k]()`）时没有。 */
+  name?: Node
+  /**
+   * 写法本身说明了是不是新建对象时给：TypeScript 的 `new X()` 是，不带 new 的调用不是。
+   * Python 新建对象和调用函数写法一样，不给，翻译插件问 name 的定义是哪种块（SourceDocument.calleeKind）。
+   */
+  construct?: boolean
+  /** 括号连同里面的实参：它跨了几行，这次调用就是跨几行写的。 */
+  argumentList: Node
+  arguments: CallArgument[]
+}
+
 export interface DeclaratorFacts {
   /** 变量名；解构声明是整个模式。 */
   name: Node
@@ -331,6 +357,18 @@ export interface PropertyRow extends Defines {
   columns?: string[]
 }
 
+/** 一张带表头和边框的表：列名，每行几列对齐的格子，同 PropertyRow 给了 columns 的子行。 */
+export interface PreviewTable {
+  columns: string[]
+  items: PropertyItem[]
+}
+
+/** 一行译文的块翻出来的：一行译文（注释块是 Markdown 说明）；跨几行写的调用还有摊开各个实参的表，预览排在这一行下面。 */
+export interface TextTranslation {
+  text: PreviewText
+  table?: PreviewTable
+}
+
 /**
  * 语言插件：语法树 → 代码块树，外加只有它懂、翻译插件翻表达式时要用的信息（叶子的词性、写在表达式里的遍历的结构）。
  * 翻译插件翻一块时从 SourceDocument.language 拿到解析这份源码的语言插件，不直接依赖某个语言插件。
@@ -347,6 +385,8 @@ export interface LanguageAdapter {
   tokenRole: (leaf: Node) => TokenRole
   /** node 是写在表达式里的遍历（推导式、生成器表达式）时给出它的结构，别的节点没有；没有这种写法的语言不填。 */
   iteration?: (node: Node) => IterationFacts | undefined
+  /** node 是一次调用（含新建对象）时给出它的结构，别的节点没有；没给的语言不展开调用，照常一行译文。 */
+  call?: (node: Node) => CallFacts | undefined
   /** 认代码里给定义起的中文名（见「中文名」）；不填就没有中文名。 */
   displayNames?: DisplayNameReader
 }
@@ -384,6 +424,11 @@ export interface SourceDocument {
   language: LanguageAdapter
   /** 写在注释里给代码阅读看的记号（中文名记号，见 DisplayNameFacts.markers）：不是说明文字，翻注释、说明时去掉 */
   markers: SourceRange[]
+  /**
+   * 调用的名字（CallFacts.name）的定义是哪种块：宿主问语言扩展定义在哪，用那个文件的语言插件分块认出来。
+   * 排视图数据是同步的，这里只交出已经查到的；还没查到、查不到、宿主不查（没给）都是 undefined，查到了宿主重排、重发。
+   */
+  calleeKind?: (call: CallFacts) => BlockKind | undefined
 }
 
 /** 筛选属性和值的显示名，筛选栏、块的种类（图标的悬停提示）用它；没给名字的显示 id。 */
@@ -401,8 +446,8 @@ export interface Translator {
   languageIds: string[]
   /** 译文用的语言（BCP 47 的语言部分，例如 'zh'）：库规则按它挑自己的词表。 */
   displayLanguage: string
-  /** 只翻 header 那一段；注释块给去掉注释符号的 Markdown 原文。 */
-  translate: (block: TextBlock, document: SourceDocument) => PreviewText
+  /** 只翻 header 那一段；注释块给去掉注释符号的 Markdown 原文，跨几行写的调用连着摊开实参的表。 */
+  translate: (block: TextBlock, document: SourceDocument) => TextTranslation
   /** 函数、类、枚举、导入、常量、变量块 → 属性表。 */
   describe: (block: FactBlock, document: SourceDocument) => PropertyRow[]
   /** 一个表达式或类型节点整个翻成一行译文，译法同属性表里的值：库规则翻默认值、类型时借它。 */