✨ feat(vscode): 代码阅读的 FastAPI 路由器单独一张「路由器」卡片（前缀、标签、依赖、默认响应，接口表列挂在它上面的接口，函数名 ⌘ + 点击跳到接口卡片）；接口卡片写所属路由器

vscode/src/codeReader/rules/fastapi.ts

@@ -1,4 +1,4 @@
-import type { FunctionBlock, ImportFacts, IndexEntry, Inline, KindIconName, LibraryRule, Node, ParameterFacts, PropertyItem, PropertyRow, RuleCard, RuleContext, Segment, ThemeColor, WorkspaceIndex } from '../contract'
+import type { FunctionBlock, ImportFacts, IndexEntry, Inline, KindIconName, LibraryRule, Node, ParameterFacts, PropertyItem, PropertyRow, RuleCard, RuleContext, Segment, ThemeColor, VariableBlock, WorkspaceIndex } from '../contract'
 import type { Call, LibraryNames } from './pythonTree'
 import { callOf, genericOf, lastName, libraryName, stringContent, syntaxChildren, unwrapType } from './pythonTree'
 import { hint, joined, name, range, word } from './segments'
@@ -15,6 +15,9 @@ const RULE_ID = 'fastapi'
 const KIND = 'fastapi.route'
 const COLOR: ThemeColor = { dark: '#61afef', light: '#1a6fb5' }
 const ICON: KindIconName = 'globe'
+const ROUTER_KIND = 'fastapi.router'
+const ROUTER_COLOR: ThemeColor = { dark: '#7aa2f7', light: '#34548a' }
+const ROUTER_ICON: KindIconName = 'network'
 /** 认路由对象、参数标记、HTTPException 时看从这几个库导入的名字（HTTPException、status 也可以从 starlette 来）。 */
 const NAME_LIBRARIES = ['fastapi', 'starlette']
 
@@ -63,12 +66,17 @@ type Place = 'path' | 'query' | 'header' | 'cookie' | 'body' | 'dependency'
 
 /** 一种显示语言的用词。 */
 interface Words {
+  /** 接口卡片、路由器卡片的种类名 */
   kind: string
-  labels: Record<'name' | 'doc' | 'tags' | 'async' | 'decorators' | 'dependencies' | 'request' | 'responses', string>
+  routerKind: string
+  labels: Record<'name' | 'doc' | 'router' | 'tags' | 'async' | 'decorators' | 'dependencies' | 'request' | 'responses' | 'prefix' | 'defaultResponses' | 'routes', string>
   yes: string
   no: string
+  count: (n: number) => string
   requestHeads: string[]
   responseHeads: string[]
+  /** 路由器卡片的接口表：方法 | 路径 | 函数 | 说明 */
+  routeHeads: string[]
   items: Record<'url' | 'method' | 'path' | 'query' | 'header' | 'cookie' | 'body', string>
   /** 成功那一行没写 response_description 时的说明 */
   success: string
@@ -86,11 +94,27 @@ interface Words {
 
 const ZH: Words = {
   kind: '接口',
-  labels: { name: '名称', doc: '说明', tags: '标签', async: '异步', decorators: '装饰器', dependencies: '依赖', request: '请求', responses: '响应' },
+  routerKind: '路由器',
+  labels: {
+    name: '名称',
+    doc: '说明',
+    router: '路由器',
+    tags: '标签',
+    async: '异步',
+    decorators: '装饰器',
+    dependencies: '依赖',
+    request: '请求',
+    responses: '响应',
+    prefix: '前缀',
+    defaultResponses: '默认响应',
+    routes: '接口',
+  },
   yes: '是',
   no: '否',
+  count: n => `${n} 个`,
   requestHeads: ['项', '值'],
   responseHeads: ['状态码', '内容', '说明'],
+  routeHeads: ['方法', '路径', '函数', '说明'],
   items: { url: 'URL', method: '方法', path: '路径参数', query: '查询参数', header: '请求头', cookie: 'Cookie', body: '请求体' },
   success: '成功',
   validation: '参数校验失败',
@@ -225,6 +249,8 @@ function listItems(node: Node | undefined): Node[] {
 
 /** 路由对象：同一文件模块顶层 `X = APIRouter(...)` / `X = FastAPI(...)` 赋值出来的，和它给挂在上面的接口叠的东西。 */
 interface Router {
+  /** 赋值目标：路由对象的名字 */
+  target: Node
   prefix?: Node
   tags: Node[]
   dependencies: Node[]
@@ -242,6 +268,7 @@ function routersOf(root: Node, env: Env): Map<string, Router> {
     if (target?.type !== 'identifier' || !call || (kind !== 'APIRouter' && kind !== 'FastAPI'))
       continue
     routers.set(target.text, {
+      target,
       prefix: kind === 'APIRouter' ? call.keywords.get('prefix') : undefined,
       tags: listItems(call.keywords.get('tags')),
       dependencies: listItems(call.keywords.get('dependencies')),
@@ -272,6 +299,40 @@ function routeOf(decorator: Node, routers: ReadonlyMap<string, Router>): Route |
   return { decorator, router, method: method.toUpperCase(), call, path: call.positional[0] ?? call.keywords.get('path') }
 }
 
+/** 路由器卡片接口表里的一个接口：挂在这个路由对象上的函数（模块顶层的）。 */
+interface RouteOn {
+  route: Route
+  definition: Node
+  name: Node
+}
+
+/** 这份文件模块顶层挂在 router 上的接口，照源码顺序；一个函数几个路由装饰器时同接口卡片，取第一个。 */
+function routesOn(root: Node, routers: ReadonlyMap<string, Router>, router: Router): RouteOn[] {
+  return syntaxChildren(root).flatMap((statement) => {
+    const definition = statement.type === 'decorated_definition' ? statement.childForFieldName('definition') : null
+    const name = definition?.type === 'function_definition' ? definition.childForFieldName('name') : null
+    if (!definition || !name)
+      return []
+    const route = syntaxChildren(statement).filter(child => child.type === 'decorator').map(decorator => routeOf(decorator, routers)).find(found => found !== undefined)
+    return route?.router === router ? [{ route, definition, name }] : []
+  })
+}
+
+/** 函数的参数名 → 定义处那个名字（`*args` 这种不算），路径里 `{参数}` 讲的是它。 */
+function parametersOf(definition: Node): Map<string, Node> {
+  const names = syntaxChildren(definition.childForFieldName('parameters')).map(param =>
+    param.type === 'identifier' ? param : param.type === 'typed_parameter' ? syntaxChildren(param)[0] : param.childForFieldName('name'))
+  return new Map(names.flatMap(param => param?.type === 'identifier' ? [[param.text, param] as const] : []))
+}
+
+/** 函数 docstring 的第一行（翻译插件取的说明原文），没有 docstring 时没有。 */
+function docFirstLine(definition: Node, env: Env): string | undefined {
+  const [first] = syntaxChildren(definition.childForFieldName('body'))
+  const [doc] = first?.type === 'expression_statement' ? syntaxChildren(first) : []
+  const markdown = doc?.type === 'string' ? env.context.doc(doc)?.markdown : undefined
+  return markdown?.split('\n').map(line => line.trim()).find(line => line !== '')
+}
+
 /**
  * 路径里的一段：`{参数}` 按变量着色，其余按字符串，都带源码下标；花括号里的名字讲的是函数的同名参数（params），
  * 标上 refers，高亮参数的各处出现时它也跟着亮、⌘ + 点击跳到参数。写的不是字符串时交给翻译插件翻。
@@ -544,6 +605,25 @@ function addRaises(body: Node | null | undefined, statuses: Statuses, env: Env):
   }
 }
 
+/** 响应那一行：值是各状态码用 ` / ` 连起来，下面一张表格「状态码 | 内容 | 说明」（同一行里的内容「、」隔开，消息「；」隔开）。 */
+function responsesRow(label: string, statuses: Statuses, env: Env): PropertyRow {
+  const { words } = env
+  const rows = statuses.rows()
+  return {
+    label,
+    value: [hint(rows.map(row => textOf(row.code)).join(' / '))],
+    columns: words.responseHeads,
+    items: rows.map(row => ({
+      cells: [row.code, joined(row.contents, hint(words.listSeparator)), joined(row.notes, { text: words.messageSeparator, role: 'comment' })],
+    })),
+  }
+}
+
+/** HTTP 方法：大写，按 Swagger UI 的配色（没有配色的按关键字着色）。 */
+function methodText(method: string): Inline[] {
+  return [{ text: method, role: 'keyword', ...(METHOD_COLORS[method] && { color: METHOD_COLORS[method] }) }]
+}
+
 /** 请求表的一行：项 | 值。 */
 function requestItem(label: string, value: Inline[]): PropertyItem {
   return { cells: [[hint(label)], value] }
@@ -565,7 +645,7 @@ function routeCard(block: FunctionBlock, route: Route, env: Env): RuleCard {
   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] }) }]),
+    requestItem(words.items.method, methodText(route.method)),
     ...(['path', 'query', 'header', 'cookie'] as const).flatMap(place => at(place).length > 0 ? [requestItem(words.items[place], paramsText(at(place), env))] : []),
     ...(body.length > 0 ? [requestItem(words.items.body, body.length === 1 && body[0].type ? context.translate(body[0].type) : paramsText(body, env))] : []),
   ]
@@ -587,7 +667,6 @@ function routeCard(block: FunctionBlock, route: Route, env: Env): RuleCard {
   addRaises(definition?.childForFieldName('body'), statuses, env)
   if (placed.some(item => item.place !== 'dependency'))
     statuses.add(numericStatus('422'), [hint(words.validation)], [hint(words.automatic)])
-  const responses = statuses.rows()
 
   const doc = facts.doc && context.doc(facts.doc)
   const tags = [...router.tags, ...listItems(call.keywords.get('tags'))].map(tag => tagText(tag, env))
@@ -602,6 +681,7 @@ function routeCard(block: FunctionBlock, route: Route, env: Env): RuleCard {
   const rows: PropertyRow[] = [
     ...(facts.name ? [{ label: labels.name, value: [name(facts.name, 'function')] }] : []),
     ...(doc ? [{ label: labels.doc, value: doc }] : []),
+    { label: labels.router, value: [name(router.target, 'variable')] },
     ...(tags.length > 0 ? [{ label: labels.tags, value: joined(tags, separator) }] : []),
     { label: labels.async, value: [word(facts.async ? words.yes : words.no)] },
     ...(decorators.length > 0 ? [{ label: labels.decorators, value: joined(decorators.map(other => context.translate(other)), { text: '\n', role: 'plain' }) }] : []),
@@ -612,14 +692,7 @@ function routeCard(block: FunctionBlock, route: Route, env: Env): RuleCard {
       columns: words.requestHeads,
       items: request,
     },
-    {
-      label: labels.responses,
-      value: [hint(responses.map(row => textOf(row.code)).join(' / '))],
-      columns: words.responseHeads,
-      items: responses.map(row => ({
-        cells: [row.code, joined(row.contents, separator), joined(row.notes, { text: words.messageSeparator, role: 'comment' })],
-      })),
-    },
+    responsesRow(labels.responses, statuses, env),
   ]
   return {
     kind: KIND,
@@ -631,20 +704,78 @@ function routeCard(block: FunctionBlock, route: Route, env: Env): RuleCard {
   }
 }
 
+/**
+ * 路由器卡片：名称 / 说明 / 前缀 / 标签 / 依赖 / 默认响应（有才显示），接口表列这份文件里挂在它上面的全部接口：
+ * 方法 | 路径（前缀 + 装饰器里的路径，`{参数}` 讲那个函数的参数）| 函数（⌘ + 点击跳到那张接口卡片）| 说明（docstring 第一行）。
+ */
+function routerCard(block: VariableBlock, router: Router, routes: readonly RouteOn[], env: Env): RuleCard {
+  const { context, words } = env
+  const { labels } = words
+  const separator = hint(words.listSeparator)
+  const doc = block.facts.doc && context.doc(block.facts.doc)
+  const tags = router.tags.map(tag => tagText(tag, env))
+  const dependencies = listedDependencies(router.dependencies, env)
+  const statuses = new Statuses()
+  addResponses(router.responses, statuses, env)
+  const rows: PropertyRow[] = [
+    { label: labels.name, value: [name(router.target, 'variable')] },
+    ...(doc ? [{ label: labels.doc, value: doc }] : []),
+    ...(router.prefix ? [{ label: labels.prefix, value: pathSegments(router.prefix, new Map(), env) }] : []),
+    ...(tags.length > 0 ? [{ label: labels.tags, value: joined(tags, separator) }] : []),
+    ...(dependencies.length > 0 ? [{ label: labels.dependencies, value: joined(dependencies, separator) }] : []),
+    ...(statuses.rows().length > 0 ? [responsesRow(labels.defaultResponses, statuses, env)] : []),
+    {
+      label: labels.routes,
+      value: [hint(words.count(routes.length))],
+      ...(routes.length > 0 && {
+        columns: words.routeHeads,
+        items: routes.map(({ route, definition, name: fn }) => {
+          const params = parametersOf(definition)
+          const doc = docFirstLine(definition, env)
+          return {
+            cells: [
+              methodText(route.method),
+              [...pathSegments(router.prefix, params, env), ...pathSegments(route.path, params, env)],
+              [name(fn, 'function')],
+              doc ? [{ text: doc, role: 'comment' }] : [],
+            ],
+          }
+        }),
+      }),
+    },
+  ]
+  return {
+    kind: ROUTER_KIND,
+    badge: { label: words.routerKind, color: ROUTER_COLOR, icon: ROUTER_ICON },
+    rows,
+    defines: range(router.target),
+    absorbs: [],
+  }
+}
+
 export const fastapiRule: LibraryRule = {
   id: RULE_ID,
   label: 'FastAPI 接口',
   languageIds: ['python'],
   libraries: ['fastapi'],
   claim: (block, context) => {
-    if (block.kind !== 'function' || block.facts.decorators.length === 0)
-      return undefined
     const env: Env = { context, words: WORDS[context.displayLanguage ?? ''] ?? ZH, names: namesOf(context.imports) }
-    const routers = routersOf(block.node.tree.rootNode, env)
-    for (const decorator of block.facts.decorators) {
-      const route = routeOf(decorator, routers)
-      if (route)
-        return routeCard(block, route, env)
+    const root = block.node.tree.rootNode
+    if (block.kind === 'function' && block.facts.decorators.length > 0) {
+      const routers = routersOf(root, env)
+      for (const decorator of block.facts.decorators) {
+        const route = routeOf(decorator, routers)
+        if (route)
+          return routeCard(block, route, env)
+      }
+    }
+    // 路由对象只认模块顶层的赋值（routersOf），按赋值目标的位置认出是不是这一块
+    if ((block.kind === 'const' || block.kind === 'variable') && block.facts.declarators.length === 1) {
+      const routers = routersOf(root, env)
+      const target = block.facts.declarators[0].name
+      const router = routers.get(target.text)
+      if (router?.target.startIndex === target.startIndex)
+        return routerCard(block, router, routesOn(root, routers, router), env)
     }
     return undefined
   },