✨ feat(vscode): 代码阅读预览按住 ⌘ / Ctrl 点名字跳到定义

vscode/src/codeReader/translators/zhTemplate.test.ts

@@ -55,6 +55,11 @@ function texts(map: Map<number, Translated>): Record<number, string> {
   return Object.fromEntries([...map].map(([line, { segments }]) => [line, text(segments)]))
 }
 
+/** 只看文字和着色：去掉各段的源码下标（下标另有用例）。 */
+function colors<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value, (key, field: unknown) => key === 'offset' ? undefined : field)) as T
+}
+
 const CJK = /\p{Script=Han}/u
 const CJK_ONLY = /^\p{Script=Han}+$/u
 const WORD_CHAR = /[\p{Script=Han}\w]/u
@@ -105,7 +110,7 @@ describe('typeScript 中文直译', () => {
   it('每个被翻的词单独成段，着色取语法树词性', async () => {
     const env = await translateAll(ts, 'typescript', typescriptZhTranslator, readFixture('envLock.ts.txt'))
     const issue = await translateAll(ts, 'typescript', typescriptZhTranslator, readFixture('issueLock.ts.txt'))
-    expect(env.get(32)?.segments.filter(segment => segment.role !== 'plain')).toEqual([
+    expect(colors(env.get(32)?.segments.filter(segment => segment.role !== 'plain'))).toEqual([
       { text: '公共', role: 'keyword' },
       { text: '接口', role: 'storage' },
       { text: 'EnvLockResult', role: 'type' },
@@ -375,7 +380,7 @@ describe('属性表', () => {
 
   it('属性名是纯文字；值按词性着色，说明词（未标注、N 个、默认）用 hint', async () => {
     const env = await describeAll(ts, 'typescript', typescriptZhTranslator, readFixture('envLock.ts.txt'))
-    const rows = env.get(23) ?? []
+    const rows = colors(env.get(23) ?? [])
     expect(rows.map(row => row.label)).toEqual(['名称', '访问级别', '异步', '输入参数', '输出参数'])
     expect(rows[0].value).toEqual([{ text: 'findEnvFiles', role: 'function' }])
     expect(rows[1].value).toEqual([{ text: '公共', role: 'keyword' }])
@@ -388,8 +393,8 @@ describe('属性表', () => {
       { text: '字符串', role: 'type' },
       { text: '[]>', role: 'plain' },
     ])
-    expect(valueOf(env.get(12), '来源')).toEqual([{ text: '\'node:fs\'', role: 'string' }])
-    expect(env.get(12)?.at(-1)?.items?.[0].cells[0]).toEqual([
+    expect(colors(valueOf(env.get(12), '来源'))).toEqual([{ text: '\'node:fs\'', role: 'string' }])
+    expect(colors(env.get(12)?.at(-1)?.items?.[0].cells[0])).toEqual([
       { text: 'promises', role: 'variable' },
       { text: ' ', role: 'plain' },
       { text: '作为', role: 'keyword' },
@@ -398,8 +403,8 @@ describe('属性表', () => {
     ])
 
     const sample = await describeAll(py, 'python', pythonZhTranslator, readFixture('sample.py'))
-    expect(valueOf(sample.get(3), '来源')).toEqual([{ text: 'os', role: 'type' }])
-    expect(sample.get(39)?.find(row => row.label === '输入参数')?.items).toEqual([
+    expect(colors(valueOf(sample.get(3), '来源'))).toEqual([{ text: 'os', role: 'type' }])
+    expect(colors(sample.get(39)?.find(row => row.label === '输入参数')?.items)).toEqual([
       { cells: [[{ text: 'self', role: 'variable' }], [{ text: '未标注', role: 'hint' }], []] },
       { cells: [[{ text: 'verbose', role: 'variable' }], [{ text: '布尔', role: 'type' }], [{ text: '默认 ', role: 'hint' }, { text: '假', role: 'storage' }]] },
     ])
@@ -464,6 +469,107 @@ describe('属性表', () => {
   })
 })
 
+describe('源码下标（跳到定义用）', () => {
+  /** 带下标的段，按出现顺序写成 [文字, 下标]。 */
+  function linked(segments: Segment[] | undefined): [string, number][] {
+    return (segments ?? []).flatMap(segment => segment.offset === undefined ? [] : [[segment.text, segment.offset] as [string, number]])
+  }
+
+  function itemCells(rows: PropertyRow[] | undefined, label: string): Segment[][] {
+    return rows?.find(row => row.label === label)?.items?.flatMap(item => item.cells) ?? []
+  }
+
+  function propertySegments(rows: PropertyRow[]): Segment[] {
+    return rows.flatMap(row => [...row.value, ...(row.items ?? []).flatMap(item => item.cells.flat())])
+  }
+
+  it('python：点分模块名每一节、导入项、别名各自带下标，点号不带；前面有中文注释也对得上', async () => {
+    const source = [
+      '# 数据库连接',
+      'from luffy_agent.core.db import get_db as conn',
+      'import os.path',
+      'from . import x',
+    ].join('\n')
+    const at = (word: string): number => source.indexOf(word)
+    const rows = await describeAll(py, 'python', pythonZhTranslator, source)
+    expect(text(valueOf(rows.get(2), '来源'))).toBe('luffy_agent.core.db')
+    expect(linked(valueOf(rows.get(2), '来源'))).toEqual([['luffy_agent', at('luffy_agent')], ['core', at('core')], ['db', at('db')]])
+    expect(itemCells(rows.get(2), '导入项').map(linked)).toEqual([[['get_db', at('get_db')], ['conn', at('conn')]]])
+    expect(linked(valueOf(rows.get(3), '来源'))).toEqual([['os', at('os')], ['path', at('path')]])
+    expect(linked(valueOf(rows.get(4), '来源'))).toEqual([])
+    expect(itemCells(rows.get(4), '导入项').map(linked)).toEqual([[['x', at('x')]]])
+  })
+
+  it('python：一行译文里的名字带下标，关键字、运算符、字面量译词不带', async () => {
+    const source = [
+      'def f(user):',
+      '    if not user.active and user is not None:',
+      '        raise HTTPException(status_code=404)',
+    ].join('\n')
+    const at = (word: string, from = 0): number => source.indexOf(word, from)
+    const map = await translateAll(py, 'python', pythonZhTranslator, source)
+    const ifLine = at('if')
+    expect(text(map.get(2)?.segments)).toBe('如果 非 user.active 并且 user 不是 空')
+    expect(linked(map.get(2)?.segments)).toEqual([['user', at('user', ifLine)], ['active', at('active')], ['user', at('user is')]])
+    expect(linked(map.get(3)?.segments)).toEqual([['HTTPException', at('HTTPException')], ['status_code', at('status_code')]])
+  })
+
+  it('typeScript：模块字符串、导入项、函数名称、参数名和类型、返回类型、译文里的名字带下标', async () => {
+    const source = [
+      '// 读取配置',
+      'import { readFile as rf } from \'./fs\'',
+      'export async function load(path: string, opts?: Options): Promise<Result> {',
+      '  if (opts === undefined) return rf(path)',
+      '}',
+    ].join('\n')
+    const at = (word: string): number => source.indexOf(word)
+    const rows = await describeAll(ts, 'typescript', typescriptZhTranslator, source)
+    expect(linked(valueOf(rows.get(2), '来源'))).toEqual([['\'./fs\'', at('\'./fs\'')]])
+    expect(itemCells(rows.get(2), '导入项').map(linked)).toEqual([[['readFile', at('readFile')], ['rf', at('rf }')]]])
+    expect(linked(valueOf(rows.get(3), '名称'))).toEqual([['load', at('load')]])
+    expect(itemCells(rows.get(3), '输入参数').map(linked)).toEqual([
+      [['path', at('path:')]],
+      [],
+      [],
+      [['opts', at('opts?')]],
+      [['Options', at('Options')]],
+      [],
+    ])
+    expect(linked(valueOf(rows.get(3), '输出参数'))).toEqual([['Promise', at('Promise')], ['Result', at('Result')]])
+    const map = await translateAll(ts, 'typescript', typescriptZhTranslator, source)
+    expect(text(map.get(4)?.segments)).toBe('如果 (opts 全等 未定义)')
+    expect(linked(map.get(4)?.segments)).toEqual([['opts', at('opts ===')]])
+  })
+
+  it('样例全文：带下标的只有照抄的名字和字符串，下标处的源码就是这段；变量名、函数名都带，译词、说明词都不带', async () => {
+    const samples: [LanguageAdapter, string, Translator, string][] = [
+      [ts, 'typescript', typescriptZhTranslator, 'envLock.ts.txt'],
+      [ts, 'typescript', typescriptZhTranslator, 'issueLock.ts.txt'],
+      [py, 'python', pythonZhTranslator, 'sample.py'],
+      [py, 'python', pythonZhTranslator, 'routes.py'],
+    ]
+    for (const [adapter, languageId, translator, name] of samples) {
+      const source = readFixture(name)
+      const translated = [...(await translateAll(adapter, languageId, translator, source)).values()].flatMap(block => block.segments)
+      const described = [...(await describeAll(adapter, languageId, translator, source)).values()].flatMap(propertySegments)
+      const segments = [...translated, ...described]
+      expect(linked(segments).length, name).toBeGreaterThan(10)
+      for (const segment of segments) {
+        const where = `${name} 「${segment.text}」`
+        if (segment.role === 'variable' || segment.role === 'function')
+          expect(segment.offset, where).toBeTypeOf('number')
+        if (segment.offset === undefined)
+          continue
+        expect(['variable', 'function', 'type', 'string'], where).toContain(segment.role)
+        if (segment.role === 'string')
+          expect(source[segment.offset], where).toBe(segment.text[0])
+        else
+          expect(source.startsWith(segment.text, segment.offset), where).toBe(true)
+      }
+    }
+  })
+})
+
 describe('中文模板引擎', () => {
   function testTranslator(table: Partial<ZhTable>): Translator {
     return createZhTemplateTranslator({