✨ feat(vscode): 代码阅读把字典、对象字面量的值展开成键值树

vscode/src/codeReader/translators/zhTemplate.ts

@@ -1,4 +1,4 @@
-import type { Access, ClassFacts, Defines, FactBlock, FunctionFacts, ImportFacts, ImportItem, Markdown, Node, PreviewText, PropertyRow, Segment, SourceSpan, TextBlock, TokenRole, Translator, VariableBlock } from '../contract'
+import type { Access, ClassFacts, Defines, EntryFacts, FactBlock, FunctionFacts, ImportFacts, ImportItem, Markdown, Node, PreviewText, PropertyItem, PropertyRow, Segment, SourceSpan, TextBlock, TokenRole, Translator, VariableBlock } from '../contract'
 import { commonIndent, splitLines } from '../editText'
 
 /** 按所在语法节点区分译法的关键字，例如 Python 的 else：if 后「否则」，for / while 后「未中断时」。 */
@@ -36,8 +36,10 @@ export interface ZhTable {
   /** 翻成文字的运算符：只认父节点在 operatorParents 里的运算符节点（TS 的非空断言 `x!` 不算）。 */
   operators: Record<string, string>
   operatorParents: string[]
-  /** 空字面量（没有具名子节点）整个换成一个词：空数组 / 空列表 / 空字典。 */
+  /** 空字面量（没有具名子节点）整个换成一个词：空数组 / 空列表 / 空字典 / 空对象。 */
   emptyLiterals: Record<string, string>
+  /** 字典 / 对象字面量（语言插件给了 entries 的值）的叫法，按节点类型查：属性表里的值写成「字典 3 项」，各项展开成子行。 */
+  mapLiterals: Record<string, string>
   /** 整段原样照抄、按字符串着色的节点。 */
   stringNodes: string[]
   /** 注释（或 docstring）节点去掉注释符号后的原文，可以多行。 */
@@ -283,17 +285,17 @@ export function createZhTemplateTranslator(table: ZhTable): Translator {
 
   function describe(block: FactBlock, source: string): PropertyRow[] {
     const { header } = block
+    // 值里带语句块主体的回调（useMemo(() => { … })）只翻到主体开始之前，和块头部一致
+    const within = (node: Node, part: SourceSpan): Segment[] => {
+      const span = part.endIndex > header.endIndex ? { ...part, endIndex: header.endIndex, endRow: header.endRow } : part
+      return joinTokens(tokensIn(node, span, source))
+    }
     const phrases: Phrases = {
-      // 值里带语句块主体的回调（useMemo(() => { … })）只翻到主体开始之前，和块头部一致
-      translated: (node) => {
-        const clipped = node.endIndex > header.endIndex
-        const span = {
-          startIndex: node.startIndex,
-          endIndex: clipped ? header.endIndex : node.endIndex,
-          startRow: node.startPosition.row,
-          endRow: clipped ? header.endRow : node.endPosition.row,
-        }
-        return joinTokens(tokensIn(node, span, source))
+      translated: node => within(node, { startIndex: node.startIndex, endIndex: node.endIndex, startRow: node.startPosition.row, endRow: node.endPosition.row }),
+      within,
+      entryCount: (literal, size) => {
+        const name = table.mapLiterals[literal.type]
+        return [hint(name ? `${name} ${size} 项` : `${size} 项`)]
       },
       verbatim: node => verbatim(node, source),
       // 点分模块名逐节照抄，每一节各自能跳到定义，和 VS Code 里一样
@@ -355,10 +357,14 @@ function joinTokens(tokens: Token[]): Segment[] {
 
 // ─── 属性表 ───────────────────────────────────────────────────────────────────
 
-/** 属性表里值的三种来源。 */
+/** 属性表里的值怎么写。 */
 interface Phrases {
   /** 按表翻译，只翻落在块头部里的那一段。 */
   translated: (node: Node) => Segment[]
+  /** 同 translated，只翻 node 落在 span 里的那一段（对象字面量里方法的头部）。 */
+  within: (node: Node, span: SourceSpan) => Segment[]
+  /** 字典 / 对象字面量的项数：「字典 3 项」，叫法按字面量的节点类型查表。 */
+  entryCount: (literal: Node, size: number) => Segment[]
   /** 源码原样照抄、按源码着色（装饰器）。 */
   verbatim: (node: Node) => Segment[]
   /** 导入来源：字符串字面量按字符串着色，模块名按类型着色。 */
@@ -492,13 +498,40 @@ function importRows(facts: ImportFacts, say: Phrases): PropertyRow[] {
   ]
 }
 
-/** 常量 / 变量：每个声明的变量依次是名称 / 访问级别 / 类型（有标注才有）/ 值（变量叫初始值）。 */
+/** 常量 / 变量：每个声明的变量依次是名称 / 访问级别 / 类型（有标注才有）/ 值（变量叫初始值，字典 / 对象字面量见 literalValue）。 */
 function variableRows(block: VariableBlock, say: Phrases): PropertyRow[] {
   const valueLabel = block.kind === 'const' ? '值' : '初始值'
   return block.facts.declarators.flatMap(declarator => [
     { label: '名称', value: say.translated(declarator.name), ...defining(declarator.name) },
     ...accessRows(block.facts.access),
     ...(declarator.type ? [{ label: '类型', value: say.translated(declarator.type) }] : []),
-    { label: valueLabel, value: declarator.value ? say.translated(declarator.value) : [hint('无')] },
+    { label: valueLabel, ...(declarator.value ? literalValue(declarator.value, declarator.entries, say) : { value: [hint('无')] }) },
   ])
 }
+
+/**
+ * 值：字典 / 对象字面量（语言插件给了 entries）写项数，各项展开成下一层子行；
+ * 空字面量和别的值是一行译文（空的译成「空字典」「空对象」）。
+ */
+function literalValue(value: Node, entries: EntryFacts[] | undefined, say: Phrases): { value: Segment[], items?: PropertyItem[] } {
+  if (!entries?.length)
+    return { value: say.translated(value) }
+  return { value: say.entryCount(value, entries.length), items: entries.map(entry => entryItem(entry, say)) }
+}
+
+/**
+ * 字典 / 对象字面量的一项是一个子行，两列：键 | 值。键照源码写法（字符串带引号，计算属性名 `[k]` 照常翻），
+ * `**x`、`...x` 的键写「展开」、值是展开的表达式，方法的值是它的头部。讲的定义是键（对象的属性名）。
+ */
+function entryItem(entry: EntryFacts, say: Phrases): PropertyItem {
+  switch (entry.kind) {
+    case 'pair': {
+      const { value, ...nested } = literalValue(entry.value, entry.entries, say)
+      return { cells: [say.translated(entry.key), value], ...nested, ...defining(entry.key) }
+    }
+    case 'spread':
+      return { cells: [[hint('展开')], say.translated(entry.value)] }
+    case 'method':
+      return { cells: [say.translated(entry.name), say.within(entry.node, entry.header)], ...defining(entry.name) }
+  }
+}