✨ feat(vscode): 代码阅读的词可以讲源码里别处的名字（Segment.refers）：FastAPI 路径里的 {user_id} 讲函数的参数，单击参数时跟着高亮，⌘ + 点击跳到参数

vscode/src/codeReader/contract.ts

@@ -275,8 +275,11 @@ export type TokenRole
  * 它在源码里的起始下标（同 SourceSpan 的下标），预览拿它向 VS Code 查定义、跳过去；译词、提示词没有。
  * reference：只有库规则给的段有，这段讲的东西由规则自己查定义（LibraryRule.resolve），不问语言扩展；这样的段必须带 offset。
  * color：这段自己的颜色（暗色、亮色主题各一个），盖过词性的颜色：库规则按库自己的配色上色（FastAPI 的 HTTP 方法用 Swagger UI 的颜色）。
+ * refers：这段讲的是源码里别处的一个名字（那个名字的范围），语言扩展不认得这段自己的位置：写在字符串里的名字
+ * （FastAPI 路径 `"/{user_id}"` 里的 user_id 讲的是函数的参数 user_id）。预览把这段当那个名字：⌘ / Ctrl + 点击跳到它的定义，
+ * 单击高亮它的各处出现，那个名字的某处出现盖住 refers 时这段也跟着高亮。offset 照旧是这段照抄的位置。
  */
-export interface Segment { text: string, role: TokenRole, offset?: number, reference?: RuleReference, color?: ThemeColor }
+export interface Segment { text: string, role: TokenRole, offset?: number, reference?: RuleReference, color?: ThemeColor, refers?: SourceRange }
 
 /** 框的样式，决定框头的图标和框的颜色：'iteration' 是写在表达式里的遍历，图标、颜色同「循环」块。 */
 export type GroupStyle = 'iteration'

vscode/src/codeReader/rules/fastapi.test.ts

@@ -95,9 +95,12 @@ describe('fastapi 库规则：接口卡片', () => {
     const rows = properties(await route(ROUTES, 'update_user', known({ Forbidden: '403' })))
     const request = rows.find(row => row.label === '请求')
     const [url, method] = request?.items ?? []
-    expect(flatSegments(url.cells[1]).map(piece => [piece.text, piece.role])).toEqual([['/users', 'string'], ['/', 'string'], ['{user_id}', 'variable']])
+    expect(flatSegments(url.cells[1]).map(piece => [piece.text, piece.role])).toEqual([['/users', 'string'], ['/', 'string'], ['{', 'variable'], ['user_id', 'variable'], ['}', 'variable']])
     for (const piece of flatSegments(url.cells[1]))
       expect(ROUTES.slice(piece.offset, (piece.offset ?? 0) + piece.text.length)).toBe(piece.text)
+    // 路径里的 user_id 讲的是 update_user 的参数 user_id：高亮参数的各处出现时跟着亮，⌘ + 点击跳到参数
+    const param = ROUTES.indexOf('user_id: Int4Path', ROUTES.indexOf('def update_user'))
+    expect(flatSegments(url.cells[1]).find(piece => piece.text === 'user_id')?.refers).toEqual({ startIndex: param, endIndex: param + 'user_id'.length })
     expect(method.cells[1]).toEqual([{ text: 'PUT', role: 'keyword', color: { dark: '#fca130', light: '#b35f00' } }])
     const [ok, forbidden, validation] = rows.find(row => row.label === '响应')?.items ?? []
     expect(ok.cells[0]).toEqual([{ text: '200', role: 'number', color: { dark: '#2ea043', light: '#1a7f37' } }])

vscode/src/codeReader/rules/fastapi.ts

@@ -266,8 +266,11 @@ function routeOf(decorator: Node, routers: ReadonlyMap<string, Router>): Route |
   return { decorator, router, method: method.toUpperCase(), call, path: call.positional[0] ?? call.keywords.get('path') }
 }
 
-/** 路径里的一段：`{参数}` 按变量着色，其余按字符串，带源码下标；写的不是字符串时交给翻译插件翻。 */
-function pathSegments(node: Node | undefined, env: Env): Inline[] {
+/**
+ * 路径里的一段：`{参数}` 按变量着色，其余按字符串，都带源码下标；花括号里的名字讲的是函数的同名参数（params），
+ * 标上 refers，高亮参数的各处出现时它也跟着亮、⌘ + 点击跳到参数。写的不是字符串时交给翻译插件翻。
+ */
+function pathSegments(node: Node | undefined, params: ReadonlyMap<string, Node>, env: Env): Inline[] {
   if (!node)
     return []
   const content = stringContent(node)
@@ -276,7 +279,22 @@ function pathSegments(node: Node | undefined, env: Env): Inline[] {
   const segments: Segment[] = []
   let at = content.node?.startIndex ?? node.startIndex
   for (const part of content.text.split(/(\{[^}]*\})/).filter(Boolean)) {
-    segments.push({ text: part, role: part.startsWith('{') ? 'variable' : 'string', offset: at })
+    if (!part.startsWith('{')) {
+      segments.push({ text: part, role: 'string', offset: at })
+    }
+    else {
+      // `{file_path:path}`：冒号前面是参数名，后面是转换器
+      const colon = part.indexOf(':')
+      const key = part.slice(1, colon < 0 ? -1 : colon)
+      const rest = part.slice(1 + key.length, -1)
+      const param = params.get(key.trim())
+      const pieces: Segment[] = [
+        { text: '{', role: 'variable', offset: at },
+        { text: key, role: 'variable', offset: at + 1, ...(param && { refers: range(param) }) },
+        { text: `${rest}}`, role: 'variable', offset: at + 1 + key.length },
+      ]
+      segments.push(...pieces.filter(piece => piece.text !== ''))
+    }
     at += part.length
   }
   return segments
@@ -537,7 +555,8 @@ function routeCard(block: FunctionBlock, route: Route, env: Env): RuleCard {
   const at = (place: Place): Placed[] => placed.filter(item => item.place === place)
   const body = at('body')
 
-  const url = [...pathSegments(router.prefix, env), ...pathSegments(route.path, env)]
+  const params = new Map(facts.parameters.flatMap(({ name: param }) => param.type === 'identifier' ? [[param.text, param] as const] : []))
+  const url = [...pathSegments(router.prefix, params, env), ...pathSegments(route.path, params, env)]
   const request: PropertyItem[] = [
     requestItem(words.items.url, url),
     requestItem(words.items.method, [{ text: route.method, role: 'keyword', ...(METHOD_COLORS[route.method] && { color: METHOD_COLORS[route.method] }) }]),

vscode/webview-ui/src/codeReader/SegmentText.test.tsx

@@ -19,4 +19,15 @@ describe('着色的词', () => {
     )
     expect(html).toBe('<span class="cr-role-keyword cr-colored" style="--color-dark:#fca130;--color-light:#b35f00">PUT</span><span class="cr-role-string"> /users</span>')
   })
+
+  it('讲别处名字的段（refers）：data-offset 记那个名字的下标，⌘ + 点击、单击高亮都按它', () => {
+    const html = renderToStaticMarkup(
+      <SegmentText segments={[
+        { text: '/users/', role: 'string', offset: 20 },
+        { text: 'user_id', role: 'variable', offset: 28, refers: { startIndex: 90, endIndex: 97 } },
+      ]}
+      />,
+    )
+    expect(html).toBe('<span class="cr-role-string" data-offset="20">/users/</span><span class="cr-role-variable" data-offset="90">user_id</span>')
+  })
 })

vscode/webview-ui/src/codeReader/SegmentText.tsx

@@ -4,12 +4,12 @@ import type { GroupStyle, Inline, SegmentGroup } from './types'
 import { useContext } from 'react'
 import { DisplayNameContext, shownName } from './displayNames'
 import { KIND_ICON_COMPONENTS, KIND_ICONS } from './kindIcons'
-import { isCurrent, segmentOccurrence } from './occurrences'
+import { isCurrent, segmentOccurrence, sourceOf } from './occurrences'
 import { HighlightContext } from './useOccurrences'
 
 /**
- * 按词性给每一段上色，颜色在 codeReader.css 的 .cr-role-* 里按主题切换，带自己颜色（color）的段用它（.cr-colored）；带源码下标的名字记在 data-offset 上，
- * 跳到定义、高亮各处出现用；是眼下高亮着的名字的一处出现时 data-occurrence 标出底色，是当前那一处（点中的、用键盘跳到的）时
+ * 按词性给每一段上色，颜色在 codeReader.css 的 .cr-role-* 里按主题切换，带自己颜色（color）的段用它（.cr-colored）；带源码下标的名字记在 data-offset 上
+ * （讲别处名字的段记那个名字的下标，见 sourceOf），跳到定义、高亮各处出现用；是眼下高亮着的名字的一处出现时 data-occurrence 标出底色，是当前那一处（点中的、用键盘跳到的）时
  * 再标 data-current。起了中文名的名字显示中文名（data-name），悬停看原名，定义处本身在后面淡淡写原名；下标照旧，跳到定义、高亮照常。
  * 框起来的一组词画成小框，框里的词同样处理。
  */
@@ -27,7 +27,7 @@ export function SegmentText({ segments }: { segments: Inline[] }): ReactElement
             key={index}
             className={piece.color ? `cr-role-${piece.role} cr-colored` : `cr-role-${piece.role}`}
             style={piece.color && { '--color-dark': piece.color.dark, '--color-light': piece.color.light } as CSSProperties}
-            data-offset={piece.offset}
+            data-offset={sourceOf(piece)?.start}
             data-occurrence={highlight && segmentOccurrence(piece, highlight.occurrences)}
             data-current={highlight && isCurrent(piece, highlight) ? '' : undefined}
             data-name={shown?.name}

vscode/webview-ui/src/codeReader/occurrences.test.ts

@@ -6,7 +6,7 @@ import { createPythonAdapter } from '../../../src/codeReader/languages/python'
 import { WASM_DIR, withBlocks } from '../../../src/codeReader/testSupport'
 import { pythonZhTranslator } from '../../../src/codeReader/translators/pythonZh'
 import { DefinitionLinks } from './definitionLinks'
-import { clickAction, isCurrent, KEY_SCROLL_MS, KEY_TO_COMMAND_MS, KeyScroll, occurrenceCount, OccurrenceHighlight, OccurrenceNavigation, occurrenceStyle, segmentOccurrence, stepIndex } from './occurrences'
+import { clickAction, isCurrent, KEY_SCROLL_MS, KEY_TO_COMMAND_MS, KeyScroll, occurrenceCount, OccurrenceHighlight, OccurrenceNavigation, occurrenceStyle, segmentOccurrence, sourceOf, stepIndex } from './occurrences'
 
 function name(text: string, offset: number): Segment {
   return { text, role: 'variable', offset }
@@ -54,6 +54,16 @@ describe('occurrences：哪些段画高亮', () => {
     expect(segmentOccurrence(name('a', 0), [at(0, 1, 'read'), at(0, 1, 'write')])).toBe('strong')
   })
 
+  it('讲别处名字的段（refers，写在字符串里的参数名）按那个名字算：那个名字的出现盖住它就画、能是当前那一处，自己照抄的位置不算', () => {
+    const param: Segment = { text: 'user_id', role: 'variable', offset: 40, refers: { startIndex: 100, endIndex: 107 } }
+    expect(sourceOf(param)).toEqual({ start: 100, end: 107 })
+    expect(segmentOccurrence(param, [at(100, 107, 'write')])).toBe('strong')
+    expect(segmentOccurrence(param, [at(40, 47)])).toBeUndefined()
+    expect(isCurrent(param, { name: 'user_id', occurrences: [at(100, 107)], current: 0 })).toBe(true)
+    expect(sourceOf(name('x', 3))).toEqual({ start: 3, end: 4 })
+    expect(sourceOf({ text: '常量', role: 'storage' })).toBeUndefined()
+  })
+
   it('真实的 Python 译文和属性表：定义处按写入、用到的地方按读取画；点分模块名每一节各按自己的范围认', async () => {
     const source = [
       'import luffy_agent.core.db',

vscode/webview-ui/src/codeReader/occurrences.ts

@@ -8,7 +8,7 @@ export function occurrenceStyle(kind: Occurrence['kind']): OccurrenceStyle {
 }
 
 /**
- * 一段文字画不画高亮、画哪种：它照抄自源码，在源码里占 [offset, offset + 字数)，和哪处出现重叠就画，
+ * 一段文字画不画高亮、画哪种：它讲的名字（sourceOf）和哪处出现重叠就画，
  * 同时碰上写入和读取的按写入画。没有下标的（译词、提示词、编辑状态的源码）不画。
  */
 export function segmentOccurrence(segment: Segment, occurrences: readonly Occurrence[]): OccurrenceStyle | undefined {
@@ -23,10 +23,20 @@ export function segmentOccurrence(segment: Segment, occurrences: readonly Occurr
   return style
 }
 
-/** 段照抄自源码、在源码里占的 [offset, offset + 字数) 和这处出现重叠；没有下标的段不算。 */
+/**
+ * 段讲的是源码里哪个名字，[start, end)：讲别处名字的段（refers，写在字符串里的参数名）是那个名字，照抄自源码的段是它自己占的
+ * [offset, offset + 字数)；没有下标的段（译词、提示词）没有。跳到定义、单击高亮、各处出现画在哪都按它。
+ */
+export function sourceOf(segment: Segment): { start: number, end: number } | undefined {
+  if (segment.refers)
+    return { start: segment.refers.startIndex, end: segment.refers.endIndex }
+  return segment.offset === undefined ? undefined : { start: segment.offset, end: segment.offset + segment.text.length }
+}
+
+/** 段讲的名字（sourceOf）和这处出现重叠；没有下标的段不算。 */
 export function overlaps(segment: Segment, occurrence: Occurrence): boolean {
-  const { offset } = segment
-  return offset !== undefined && occurrence.start < offset + segment.text.length && offset < occurrence.end
+  const source = sourceOf(segment)
+  return source !== undefined && occurrence.start < source.end && source.start < occurrence.end
 }
 
 /** 文字里（连框里）有段和这处出现重叠。 */

vscode/webview-ui/src/codeReader/types.ts

@@ -17,9 +17,10 @@ export type TokenRole
 /**
  * offset：照抄自源码里的名字、字符串时它在源码里的起始下标，⌘ / Ctrl 悬停、点击时拿它查定义；译词、提示词没有。
  * reference：库规则自己查定义的名字（Celery 的任务名）才有；webview 不看它，照样只报 offset，扩展端按 offset 认出来交给规则查。
- * color：这段自己的颜色（库规则按库自己的配色给的，例如 HTTP 方法），盖过词性的颜色，按主题挑暗色、亮色
+ * color：这段自己的颜色（库规则按库自己的配色给的，例如 HTTP 方法），盖过词性的颜色，按主题挑暗色、亮色。
+ * refers：这段讲的是源码里别处的一个名字（写在字符串里的名字讲的参数）：跳到定义、高亮各处出现都当它是那个名字，见 sourceOf
  */
-export interface Segment { text: string, role: TokenRole, offset?: number, reference?: RuleReference, color?: ThemeColor }
+export interface Segment { text: string, role: TokenRole, offset?: number, reference?: RuleReference, color?: ThemeColor, refers?: SourceRange }
 
 /** 规则自己查得到定义的一个名字：哪个规则、规则自己认的键 */
 export interface RuleReference { rule: string, key: string }