✨ feat(vscode): 代码阅读函数、导入、常量、变量块预览改成属性表

vscode/src/codeReader/contract.ts

@@ -10,8 +10,61 @@ export type BlockKind
 /** 源码里的一段，行号从 0 开始；下标是源码字符串下标（web-tree-sitter 的 startIndex / endIndex），end 为开区间。 */
 export interface SourceSpan { startIndex: number, endIndex: number, startRow: number, endRow: number }
 
-export interface CodeBlock {
-  kind: BlockKind
+/** 访问级别。 */
+export type Access = 'public' | 'private' | 'protected'
+
+/** 函数的一个参数；节点都指向源码。 */
+export interface ParameterFacts {
+  /** 参数名；解构参数是整个模式，`...rest`、`*args`、`**kwargs` 带着前缀。 */
+  name: Node
+  /** TypeScript 的可省略参数 `x?`。 */
+  optional: boolean
+  type?: Node
+  default?: Node
+}
+
+export interface FunctionFacts {
+  /** 匿名函数（`export default function () {}`）没有。 */
+  name?: Node
+  /** 嵌套在函数体、条件等语句块里的函数没有。 */
+  access?: Access
+  async: boolean
+  decorators: Node[]
+  parameters: ParameterFacts[]
+  returnType?: Node
+}
+
+/** 导入的一项。 */
+export type ImportItem
+  = | { kind: 'named', name: Node, alias?: Node } // import { a as b }、from m import a as b
+    | { kind: 'default', alias: Node } // import x from 'm'
+    | { kind: 'namespace', alias?: Node } // import * as x、from m import *
+    | { kind: 'module', module: Node, alias?: Node } // import a.b as c、import x = require('m')
+
+export interface ImportFacts {
+  /** 来源模块，节点就是源码里的写法：TypeScript 是字符串字面量，Python 是点分模块名；Python 的 `import a, b` 有多个。 */
+  sources: Node[]
+  /** 只导入类型（TypeScript 的 `import type`）；没有这个概念的语言不填。 */
+  typeOnly?: boolean
+  /** 副作用导入（`import './x'`）没有。 */
+  items: ImportItem[]
+}
+
+export interface DeclaratorFacts {
+  /** 变量名；解构声明是整个模式。 */
+  name: Node
+  type?: Node
+  value?: Node
+}
+
+export interface VariableFacts {
+  /** 只有模块顶层（Python 还有类主体）的声明有。 */
+  access?: Access
+  /** 一条语句声明几个变量（`let a = 1, b = 2`）就有几项。 */
+  declarators: DeclaratorFacts[]
+}
+
+export interface BlockShape {
   /** 这一块对应的语法树节点（整条语句）。 */
   node: Node
   /** 块自己显示 / 编辑的那一段：复合语句只到主体开始之前，其余是整条语句。 */
@@ -19,15 +72,39 @@ export interface CodeBlock {
   children: CodeBlock[]
 }
 
+/** 预览成属性表的块：语言插件从语法树读出结构化信息（facts），翻译插件把它排成属性表。 */
+export interface FunctionBlock extends BlockShape { kind: 'function', facts: FunctionFacts }
+export interface ImportBlock extends BlockShape { kind: 'import', facts: ImportFacts }
+export interface VariableBlock extends BlockShape { kind: 'const' | 'variable', facts: VariableFacts }
+export type FactBlock = FunctionBlock | ImportBlock | VariableBlock
+
+export type TextKind = Exclude<BlockKind, FactBlock['kind']>
+
+/** 预览成一行译文的块。 */
+export interface TextBlock extends BlockShape { kind: TextKind }
+
+export type CodeBlock = TextBlock | FactBlock
+
 /** 着色用的词性，源码着色和译文着色共用。 */
 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' // 被翻成文字的运算符：全等 并且 或者 非
+    | 'hint' // 属性表里的说明词：未标注 无 N 个 默认导出 …
     | 'variable' | 'function' | 'type' | 'string' | 'number' | 'literal' | 'comment' | 'plain'
 
 export interface Segment { text: string, role: TokenRole }
 
+/** 属性表里展开的一个子行：几列对齐的格子，例如参数的名称 / 类型 / 默认值。 */
+export interface PropertyItem { cells: Segment[][] }
+
+/** 属性表的一行：左列属性名，右列着色的值；items 是展开在这一行下面的子行（输入参数、导入项）。 */
+export interface PropertyRow {
+  label: string
+  value: Segment[]
+  items?: PropertyItem[]
+}
+
 /** 语言插件：语法树 → 代码块树。 */
 export interface LanguageAdapter {
   id: string
@@ -40,12 +117,15 @@ export interface LanguageAdapter {
   tokenRole: (leaf: Node) => TokenRole
 }
 
-/** 翻译插件：代码块 → 译文。 */
+/** 翻译插件：代码块 → 一行译文或属性表。 */
 export interface Translator {
   id: string // 'typescript.zh-template'
   label: string // '中文直译'
   languageIds: string[]
-  translate: (block: CodeBlock, source: string) => Segment[]
+  /** 只翻 header 那一段。 */
+  translate: (block: TextBlock, source: string) => Segment[]
+  /** 函数、导入、常量、变量块 → 属性表。 */
+  describe: (block: FactBlock, source: string) => PropertyRow[]
 }
 
 export interface CodeReaderApi {