From 300d8a07b92bdcac769aaa59720d8b2ab3808fec Mon Sep 17 00:00:00 2001 From: cruldra Date: Wed, 7 Oct 2026 08:21:59 +0800 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20feat(vscode):=20=E4=BB=A3=E7=A0=81?= =?UTF-8?q?=E9=98=85=E8=AF=BB=E6=B3=A8=E9=87=8A=E9=87=8C=E4=B8=8D=E5=B8=A6?= =?UTF-8?q?=E8=B7=AF=E5=BE=84=E7=9A=84=E5=BC=95=E7=94=A8=20[Name]=20?= =?UTF-8?q?=E8=83=BD=E7=82=B9=EF=BC=8C=E6=9C=AC=E6=96=87=E4=BB=B6=E5=AE=9A?= =?UTF-8?q?=E4=B9=89=E7=9A=84=E4=BC=98=E5=85=88=E3=80=81=E5=86=8D=E6=89=BE?= =?UTF-8?q?=E5=AF=BC=E5=85=A5=E7=9A=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/superpowers/specs/code-reader/spec.md | 15 +- vscode/src/codeReader/blockView.ts | 11 +- vscode/src/codeReader/docTags.ts | 4 +- .../src/codeReader/editor/documentMessage.ts | 15 +- vscode/src/codeReader/editor/messages.ts | 21 +-- vscode/src/codeReader/editor/previewEditor.ts | 137 ++++++++++++++---- vscode/src/codeReader/symbolLinks.test.ts | 100 +++++++++++++ vscode/src/codeReader/symbolLinks.ts | 118 +++++++++++++++ .../webview-ui/src/codeReader/AskThread.tsx | 4 +- .../webview-ui/src/codeReader/TextPreview.tsx | 2 +- .../src/codeReader/markdown.test.ts | 23 +++ vscode/webview-ui/src/codeReader/markdown.ts | 70 +++++++-- .../src/codeReader/repoLink.test.ts | 58 ++++++-- vscode/webview-ui/src/codeReader/repoLink.ts | 92 +++++++++--- vscode/webview-ui/src/codeReader/types.ts | 21 +-- .../webview-ui/src/codeReader/useRepoLinks.ts | 33 +++-- 16 files changed, 600 insertions(+), 124 deletions(-) create mode 100644 vscode/src/codeReader/symbolLinks.test.ts create mode 100644 vscode/src/codeReader/symbolLinks.ts diff --git a/docs/superpowers/specs/code-reader/spec.md b/docs/superpowers/specs/code-reader/spec.md index 6b5ede3..03f7a63 100644 --- a/docs/superpowers/specs/code-reader/spec.md +++ b/docs/superpowers/specs/code-reader/spec.md @@ -472,9 +472,13 @@ - 中文名的兜底（`languages/typescriptNames.ts`、`pythonNames.ts` 从 `@param` / `Args:` 取参数的中文名）是另一回事，照旧读源码。 - 渲染：webview 用 markdown-it（`html: false`、`linkify: true`），CommonMark 加 GFM 的表格、删除线：段落、强调、行内代码（含双反引号）、代码块（围栏、缩进四格）、列表、链接、标题、引用、表格。段内单个换行是软换行，空行分段。同一段文字只渲染一次（缓存最近 500 段）。 - 安全：源码里的 HTML 当文字显示；链接认 http / https / mailto，带协议的网址和邮箱自动成链接（`sample.py` 这种不带协议的不算），别的写法（`javascript:`、`command:`、`./`、`..`、绝对路径、盘符）照原文显示。http / https / mailto 由 VS Code 的 webview 自己拦下、交给宿主在外部打开，不用另发消息。http / https 图片不渲染（webview 的 CSP 不放行外部图片），`![alt](url)` 显示成 `!` 加链接。仓库内图片按原图比例显示，点了打开原图，没有就写「找不到图片」和路径。 -- 仓库路径链接（`[名字](从仓库根起的路径)`，可带 `#类名` 或 `#类名.成员`）能点，点了打开文件并跳到符号。指到目录的在代码阅读侧栏的树上定位（展开并选中，和侧栏跟着当前文件走是同一个定位；侧栏没露着时亮出来），不切到 VS Code 资源管理器；树上没有（开着筛选时没摆它）时提示「侧栏的树上没有 …」，不退出筛选。 +- 仓库路径链接（`[名字](从仓库根起的路径)`，可带 `#类名` 或 `#类名.成员`）能点，点了打开文件并跳到符号（指到这份文件里的符号时在本预览里滚过去、闪一下，同下面的引用）。指到目录的在代码阅读侧栏的树上定位（展开并选中，和侧栏跟着当前文件走是同一个定位；侧栏没露着时亮出来），不切到 VS Code 资源管理器；树上没有（开着筛选时没摆它）时提示「侧栏的树上没有 …」，不退出筛选。 +- 不带路径的引用（KDoc 的 `[Name]`、`[Class.member]`）能点： + - 认哪些：只在注释的 Markdown 里认（说明正文、参数说明、`@return`、「异常」表、单独成块的注释，连带增删的；问 AI 的回答不认）。方括号里是标识符（ASCII 字母、数字、下划线、`$`，点分开的几段）；中文这类不是标识符的（`[会话进展]`）照原样是文字。反引号里的是代码；紧跟在名字、`]`、`)` 后面的方括号是下标（`items[i]`、`a[0][1]`、`f()[k]`）；后面紧跟 `(…)` 的是完整链接、紧跟 `[` 的是参考式链接，都不算。webview 在 `markdown.ts` 加一条行内规则（排在 markdown-it 的 link 后面，渲染时 `env.symbolLinks` 为真才认），写成地址为 `symbol:名字` 的链接（作者写不出这种地址，`validateLink` 不放行）。 + - 指到哪（扩展端，`symbolLinks.ts` 的 `resolveReference`，按 KDoc 的规矩）：① 本文件定义的：文档符号（`vscode.executeDocumentSymbolProvider`，同仓库链接找符号那一套）顶层名字对上的（类、函数、常量、变量；落在导入语句里的名字不算），`Class.member` 在它底下找成员；② 本文件导入进来的：名字（`Class.member` 的第一段）是某条导入引进来的（预览已有的导入块 facts，`ImportFacts.items`：起了别名的按别名认，问原来那个名字；整模块导入按第一节认，起了别名的问最后一节），在导入语句里这个名字的位置上问语言扩展定义在哪（`vscode.executeDefinitionProvider`，同跳到定义，几处取第一处），`Class.member` 再在目标文件的文档符号里找：定义落在哪个符号里就在它底下找，落在文件开头（导入的是模块）就从顶层找；③ 都没有就找不到。本文件定义了这个名字、却没有这个成员时也算找不到，不再去导入里找。 + - 问答同仓库路径链接（`useRepoLinks`、`RepoLinks`）：画出来后把页面上的仓库路径和引用一起发去问（`checkRepoLinks { paths, symbols }` → `repoLinksChecked { missing, unresolved }`），问到之前是普通链接，找不到的画成坏链接（红色波浪线，悬停「找不到」）；文档换了版本（收到 `document`）再问一次，引用跟着源码变。点了发 `openRepoLink`（不带 `path`，只带 `symbol`）：找到了在预览所在的编辑器组打开目标文件、选中符号的名字（同完整链接的后半段），目标在这份文件里时在本预览里滚过去、闪一下（同跳到定义的闪）；找不到就标坏。 - 样子：正文用界面字体（`--vscode-font-family`、`--vscode-font-size`）、comment 色、行高 20px，一行注释和一行译文一样高；行内代码用编辑器字体、`--vscode-textCodeBlock-background` 底；围栏代码块用编辑器字体和字号、同样的底，长行折行；段落、列表、代码块、表格之间 6px；标题只比正文稍大（h1 1.15em、h2 1.08em，其余同正文，加粗）；链接 `--vscode-textLink-foreground`；引用左边 3px `--vscode-textBlockQuote-border` 竖线、`--vscode-textBlockQuote-background` 底；表格 1px 细线。 -- 「编辑」状态照旧是源码，编辑写回不变；Markdown 里的名字不能点，不参与跳到定义。 +- 「编辑」状态照旧是源码，编辑写回不变；Markdown 里的名字（反引号里的代码）不能点，不参与跳到定义，能点的只有上面的链接和引用。 ### 跳到定义 @@ -1992,11 +1996,13 @@ type BlockView = BlockViewBase & ({ translation: PreviewText, table?: PreviewTab - `{ type: 'askProfiles', options: { id, label }[], selected }`：「问 AI」的 profile 下拉（`id` 是 profile 名，「默认」的 `id` 是 `''`、`label` 是「默认」）。`ready` 后发一次（每次现读 profile 目录），任何一个预览选了都发给所有开着的预览（包括选的那个）。 - `{ type: 'answer', askId, text, activity? }`：`askId` 那个问题的回答长了（`text` 是到现在为止的全文）或换了在做的事。webview 攒着、最多每 80ms 画一次。 - `{ type: 'answerEnd', askId, status: 'done' | 'failed' | 'stopped', text?, error?, entryId? }`：答完了。`done` 带最终回答和存下的那条的 id（历史里不再重复显示它），`failed` 带给人看的原因，`stopped` 是被叫停、没存。 + - `{ type: 'repoLinksChecked', id, missing, unresolved }`：回答第 `id` 次 `checkRepoLinks`，`missing` 是仓库里没有的路径，`unresolved` 是找不到的不带路径的引用。`{ type: 'repoLinkBroken' | 'repoLinkOpened', path?, symbol? }`：点了以后打不开 / 打开了；没有 `path` 的是不带路径的引用。见「注释的 Markdown 排版」。 - webview → 扩展： - `{ type: 'probeDefinition', id, version, offset }`：按住修饰键指到带 `offset` 的名字上时问有没有定义，`id` 每问一次加一；`version` 不是当前文档版本就不答。 - `{ type: 'goToDefinition', version, offset }`：修饰键 + 点击，按「跳到定义」一节跳。这两条都只带下标：扩展端按发出去的文档认出规则标了引用的下标交给规则查（见「规则自己查定义」），其余问语言扩展。 - `{ type: 'findOccurrences', id, version, offset }`：单击带 `offset` 的名字，问它在这份文档里的各处出现；`id` 每问一次加一，`version` 不是当前文档版本就不答。 - `{ type: 'occurrenceNavigation', available }`：眼下能不能用键盘在各处出现之间跳，页面加载后报一次、之后变了才报；扩展端按它设 `superpowers.codeReader.hasOccurrences`。 + - `{ type: 'checkRepoLinks', id, paths, symbols }`：页面上的仓库路径问哪些没有，不带路径的引用问哪些找不到（`id` 每问一次加一）。`{ type: 'openRepoLink', path?, symbol? }`：点了注释里的仓库链接（带 `path`）或不带路径的引用（只带 `symbol`）。见「注释的 Markdown 排版」。 - `{ type: 'ready' }` - `{ type: 'edit', startLine, endLine, text }`：用 `WorkspaceEdit` 把这几行整行替换成 `text`（每行补回原来第一行的缩进）。 - `{ type: 'selectTranslator', id }`：按 `languageId` 记到 `globalState`，重发文档。 @@ -2068,6 +2074,7 @@ vscode/src/codeReader/ rules/children.ts 库规则共用的挑子块的办法（成员连同紧挨在它前面的注释块、成员的说明节点） docTags.ts 说明的原文按 KDoc 拆成正文和块标签（Doc：@param / @return / @throws），翻译插件的 doc 用它（纯函数） rules/docRows.ts 讲说明的几行，中文直译和库规则共用：正文、对不上的参数、参数按名字对说明（paramDocs）、输出后面的 @return、异常表 + symbolLinks.ts 注释里不带路径的引用指到哪：导入引进来的名字（importedNames，readBlockViews 交出）、本文件定义的优先再是导入的（resolveReference，符号和定义由预览去问）（不碰 VS Code） languages/shared.ts 语言插件共用的建树工具；异常类（withExceptions：按整份文件认异常类，类块换成异常块，并类属性、取构造参数） languages/typescript.ts （call：调用的结构，new 是新建；TYPESCRIPT_EXCEPTIONS：认异常类的父类名、类字段、constructor） languages/python.ts （iteration：推导式的结构；call：调用的结构；PYTHON_EXCEPTIONS：自带的异常类、类属性、__init__） @@ -2142,7 +2149,7 @@ vscode/src/codeReader/ editor/occurrences.ts 查名字的各处出现（vscode.executeDocumentHighlights） editor/occurrenceNavigation.ts 跳到下一处 / 上一处高亮：命令、上下文键 index.ts registerCodeReader(context): CodeReaderApi -vscode/webview-ui/code-reader.html + src/codeReader/ 预览界面（React，Vite 第二个入口；块右上角的图标按钮在 BlockTools.tsx，悬停提示在 src/components/ui/tooltip.tsx（和看板共用，页面根上挂一次），块的概念图标（图标名 → 图标组件只在 kindIcons.tsx；内置种类 → 图标名在 contract.ts 的 KIND_ICONS，宿主写进概念列表）在 kindIcons.tsx，属性表在 PropertyGrid.tsx，子行排成表格还是列表在 subRows.ts，着色的词和框在 SegmentText.tsx，中文名换字在 displayNames.ts，Markdown 渲染在 markdown.ts / TextPreview.tsx，筛选栏在 FilterBar.tsx，筛选规则在 filter.ts，编辑时盖住哪些块、点「编辑」退出哪些块在 editing.ts，高亮各处出现的规则在 occurrences.ts、接到页面上在 useOccurrences.ts，问 AI 的问答区在 AskThread.tsx、状态和规则在 qa.ts、贴图拖图的规则在 qaImages.ts、收发在 useQa.ts；代码差异：页面上怎么标（块 id、删掉的块挂哪、只看改动折哪几段、各处改动、上一处 / 下一处跳到哪）在 diffView.ts，筛选栏第二行和新文件横幅在 DiffBar.tsx，卡片里的增删在 DiffText.tsx（Markdown 的增删在 markdown.ts 的 renderMarkdownDiff），总览条在 OverviewRuler.tsx，跳到一处改动在 useChangeNav.ts） +vscode/webview-ui/code-reader.html + src/codeReader/ 预览界面（React，Vite 第二个入口；块右上角的图标按钮在 BlockTools.tsx，悬停提示在 src/components/ui/tooltip.tsx（和看板共用，页面根上挂一次），块的概念图标（图标名 → 图标组件只在 kindIcons.tsx；内置种类 → 图标名在 contract.ts 的 KIND_ICONS，宿主写进概念列表）在 kindIcons.tsx，属性表在 PropertyGrid.tsx，子行排成表格还是列表在 subRows.ts，着色的词和框在 SegmentText.tsx，中文名换字在 displayNames.ts，Markdown 渲染在 markdown.ts / TextPreview.tsx（不带路径的引用的行内规则也在 markdown.ts），仓库链接和引用的点击、问坏没坏在 repoLink.ts / useRepoLinks.ts，筛选栏在 FilterBar.tsx，筛选规则在 filter.ts，编辑时盖住哪些块、点「编辑」退出哪些块在 editing.ts，高亮各处出现的规则在 occurrences.ts、接到页面上在 useOccurrences.ts，问 AI 的问答区在 AskThread.tsx、状态和规则在 qa.ts、贴图拖图的规则在 qaImages.ts、收发在 useQa.ts；代码差异：页面上怎么标（块 id、删掉的块挂哪、只看改动折哪几段、各处改动、上一处 / 下一处跳到哪）在 diffView.ts，筛选栏第二行和新文件横幅在 DiffBar.tsx，卡片里的增删在 DiffText.tsx（Markdown 的增删在 markdown.ts 的 renderMarkdownDiff），总览条在 OverviewRuler.tsx，跳到一处改动在 useChangeNav.ts） ``` ## 测试 @@ -2159,7 +2166,7 @@ vscode/webview-ui/code-reader.html + src/codeReader/ 预览界面（React，Vit - 翻译：上面两张样例表逐字一致；属性名不被翻；每个被翻的词单独成段；节点模板嵌套时正确、槽位里照样翻、没命中模板的节点照抄；属性表里的值和一行译文用同一套表和模板。 - `blockView`：`codeTokens` 拼起来等于 `code`；去缩进正确；函数、类、导入、常量、变量块只带属性表，其余块只带译文。 - 块标签：拆法（`docTags.test.ts`：多行续写、空行结束、`@returns` / `@exception` 同义、JSDoc 的 `{类型}`、`[名字=默认值]`、横杠、标签前后的正文、没有标签时原样、别的标签和围栏代码块里的行留在正文、异常名写成引用）；卡片（`translators/zhTemplate.test.ts` 的「说明里的块标签」）：`fixtures/conversationBrief.py`（luffy 的 `render_conversation_brief`）说明里没有 `@param` / `@return`，输入参数表「说明」列四个参数的原文，输出参数后面跟 `@return`；`fixtures/localRuntimeGate.py`（luffy 的 `gate.py`）「异常」表两行，第一行是完整链接、第二行是不带路径的引用；对不上的 `@param` 排在说明下面、提示色、悬停「没有这个参数」；类的 `@param` 照写成表、异常类的对到构造参数（`*args` 去掉星号对）。React 组件（字段没注释时用 `@param`、`props.x`、讲整个参数的跟在构造参数后面、对不上的、异常表）和事件处理函数（`rules/react.test.ts`）、FastAPI 请求表的说明列和响应后面的 `@return`（`rules/fastapi.test.ts`）、Rust 函数和结构体（`languages/rust.test.ts`）、数据类字段（`rules/dataclass.test.ts`）。 -- 注释的 Markdown：注释块、函数和类「说明」的视图数据是 `{ markdown }`，原文照抄（reST 角色、双反引号、`{@link}`、HTML 都不转换，块标签拆出去），行注释连成的块留得住缩进四格的代码块；渲染时 HTML 当文字、带协议的网址和邮箱成链接、不带协议的文件名不成链接，`javascript:` / `command:` / `./` / `..` / 绝对路径的链接和 http 图片不渲染，仓库内图片按原图比例显示，点了打开原图，没有就写「找不到图片」，仓库路径链接能点、点了打开文件并跳到符号；跳到定义不认 Markdown 里的名字。 +- 注释的 Markdown：注释块、函数和类「说明」的视图数据是 `{ markdown }`，原文照抄（reST 角色、双反引号、`{@link}`、HTML 都不转换，块标签拆出去），行注释连成的块留得住缩进四格的代码块；渲染时 HTML 当文字、带协议的网址和邮箱成链接、不带协议的文件名不成链接，`javascript:` / `command:` / `./` / `..` / 绝对路径的链接和 http 图片不渲染，仓库内图片按原图比例显示，点了打开原图，没有就写「找不到图片」，仓库路径链接能点、点了打开文件并跳到符号；跳到定义不认 Markdown 里的名字。不带路径的引用：行内规则（`webview-ui/.../markdown.test.ts`：`[Name]`、`[A.b]` 是 `symbol:` 链接，`` `[x]` ``、`items[i]`、`[会话进展]`、`[名字](路径)`、`[Agent](javascript:x)` 各自的结果，问 AI 的回答不认、带增删的注释照样认）；问答（`repoLink.test.ts`：`symbol:` 地址只认标识符、点了发不带 `path` 的 `openRepoLink`、和仓库路径一起问、找不到的标坏、打开成功不再标、同样的链接不再问、文档换了版本再问）；扩展端（`symbolLinks.test.ts`：本文件优先于导入且不问语言扩展、本文件的 `Class.member`、类有成员没有就是找不到、导入的名字问定义再在那个类底下找成员、整模块导入从顶层找、找不到；Python / TypeScript 各种导入写法引进来的名字和问定义的位置，`gate.py` 的导入）。 - 行替换：多行块替换后缩进正确。 - 跳到定义：TS / Python 译文和属性表里的名字、点分模块名每一节、模块字符串带下标且指回源码原文，关键字、运算符、说明词不带（前面有中文注释也对得上）；查到的定义 → 不动 / 原地 / 预览 / 普通编辑器 / 挑选框；webview 里按下标找目标块、要展开的祖先块和属性行，滚动位置。闪哪一处（TS、Python 源码走完整的语言插件 + 翻译插件 + 视图数据）：参数 → 它那个子行，导入项 → 它那一项，多变量声明里的一个 → 它的名称行，类的泛型参数 → 「类型参数」那一行，函数名 / 类名 / 单个变量名（含解构模式）→ 整块，循环变量 → 所在的块，翻译插件没填 `defines` → 整块（照样展开属性行）；翻译插件给参数、导入项、声明的变量、泛型参数标的范围指回源码原文；块自己的名字只有函数、类和单变量声明有。 - 高亮各处出现：段的源码范围和出现重叠才亮、边界相接不算、没下标的不亮，讲别处名字的段（`refers`）按那个名字算、自己照抄的位置不算（`occurrences.test.ts` 的 `sourceOf`），点分模块名每一节各按自己的范围认（真实的 Python 译文和属性表：定义处按写入、用到处按读取）；写入 → 强高亮色，读取、按文字 → 普通高亮色，同时碰上按写入；单击名字问、点空白处清、点按钮 / 链接 / 筛选栏不动、名字在按钮里照样问，拖选、双击第二下、带修饰键的点击不动，⌘ / Ctrl + 点击照旧发跳到定义、不问出现处；回答连同名字显示、空回答不亮、换名字时回答到前旧的留着、迟到的回答丢掉、答过「没有」再点照样再问、清掉后才到的回答丢掉、换文档版本或翻译清掉而同版本同翻译重发不清、没有文档时不问。键盘跳（`occurrences.test.ts`、`reveal.test.ts`、`editor/occurrenceNavigation.test.ts`）：回答照源码先后排、点中的那处是当前那一处、「2/5」和「N 处」；往后 / 往前、到头接着跳，找不到的跳过、总数照旧、一处都找不到不动，点中的不在回答里从点中的地方数起；只有当前那一处描框；能不能跳（高亮、焦点、输入框）第一次必报、之后变了才报；页面上找第一处显示着它的地方、要展开的块 / 属性行 / 子行、跳过筛掉 / 编辑 / 盖住的块、Markdown 不算；`package.json` 的两条命令、默认键、`when`、命令面板，扩展和页面的代码里不写键、不拦键，上下文键有一个预览能跳就真、变了才设，命令发给能跳的预览、没有就发给活动的；按键那一刻的位置跳转时回一次、隔太久 / 点过鼠标 / 没按过键不回，跳完守住跳到的位置、过了 `KEY_SCROLL_MS` 或又按键、点鼠标不守。 diff --git a/vscode/src/codeReader/blockView.ts b/vscode/src/codeReader/blockView.ts index e5cc94c..b0e2d2b 100644 --- a/vscode/src/codeReader/blockView.ts +++ b/vscode/src/codeReader/blockView.ts @@ -1,12 +1,14 @@ import type { Tree } from '@vscode/tree-sitter-wasm' import type { BlockAttributes, BlockConcept, BlockKind, CodeBlock, DisplayName, EmbeddedCode, EmbeddedReading, Inline, KindBadge, LanguageAdapter, LibraryRule, LocalSymbol, Markdown, Node, PreviewTable, PreviewText, PropertyRow, RuleCard, RuleContext, Segment, SourceDocument, SourceRange, SourceSpan, StepBlocks, TextBlock, TokenRole, Translator } from './contract' import type { TreeSitterRuntime } from './runtime' +import type { ImportedName } from './symbolLinks' import { blockAttributes } from './attributes' import { KIND_ICONS } from './contract' import { commonIndent, splitLines } from './editText' import { commentSpan } from './languages/shared' import { activeRules, claimBlock, importsIn } from './libraryRules' import { BlockAnchors } from './qa/anchor' +import { importedNames } from './symbolLinks' interface BlockViewBase { /** 在树里的位置，例如 '6.1.0'。 */ @@ -415,12 +417,14 @@ export function toBlockViews( /** * 一份源码的视图数据，和它里面起了中文名的定义（预览找用到它们的各处要用，见 displayNames.ts）、 - * 语言插件自己认得出的名字（LanguageAdapter.symbols，语言扩展查不到定义、各处出现时用）。 + * 语言插件自己认得出的名字（LanguageAdapter.symbols，语言扩展查不到定义、各处出现时用）、 + * 各条导入引进来的名字（注释里不带路径的引用按它找导入的定义，见 symbolLinks.ts）。 */ export interface DocumentViews { blocks: BlockView[] displayNames: DisplayName[] symbols: LocalSymbol[] + imports: ImportedName[] } /** @@ -487,12 +491,13 @@ export async function readBlockViews( ...(commandRule && { commandRule }), ...(parts.size > 0 && { embedded }), } - const blocks = toBlockViews(adapter.toBlocks(tree.rootNode, source, languageId), document, translator, extras.rules, parts) + const codeBlocks = adapter.toBlocks(tree.rootNode, source, languageId) + const blocks = toBlockViews(codeBlocks, document, translator, extras.rules, parts) const symbols = [ ...adapter.symbols?.(tree.rootNode, source, languageId) ?? [], ...[...parts.values()].flatMap(part => part.document.language.symbols?.(part.root, source, part.code.languageId) ?? []), ] - return { blocks, displayNames: names, symbols } + return { blocks, displayNames: names, symbols, imports: importedNames(importsIn(codeBlocks)) } } finally { for (const parsed of trees) diff --git a/vscode/src/codeReader/docTags.ts b/vscode/src/codeReader/docTags.ts index fb0755b..86cb3ba 100644 --- a/vscode/src/codeReader/docTags.ts +++ b/vscode/src/codeReader/docTags.ts @@ -11,8 +11,8 @@ const TAG_LINE = /^\s*@(\w+)(?:\s(.*))?$/ /** 围栏代码块的开头（三个以上的反引号或波浪线，前面最多三个空格）：里面的行照原样留在正文里。 */ const FENCE_OPEN = /^\s{0,3}(`{3,}|~{3,})/ -/** 一个名字或点分的几个名字（`ValueError`、`errors.NotFound`）：写成不带路径的引用。 */ -const NAME_PATH = /^[\p{L}_$][\p{L}\p{N}_$]*(?:\.[\p{L}_$][\p{L}\p{N}_$]*)*$/u +/** 一个标识符或点分的几个（`ValueError`、`errors.NotFound`），同预览认引用的写法：写成不带路径的引用。 */ +const NAME_PATH = /^[A-Z_$][\w$]*(?:\.[A-Z_$][\w$]*)*$/i interface Tag { kind: TagKind diff --git a/vscode/src/codeReader/editor/documentMessage.ts b/vscode/src/codeReader/editor/documentMessage.ts index 6406294..5e56fe1 100644 --- a/vscode/src/codeReader/editor/documentMessage.ts +++ b/vscode/src/codeReader/editor/documentMessage.ts @@ -1,6 +1,7 @@ import type { DisplayName, LocalSymbol, RuleContext, SourceDocument } from '../contract' import type { CodeReaderRegistry } from '../registry' import type { TreeSitterRuntime } from '../runtime' +import type { ImportedName } from '../symbolLinks' import type { DocumentMessage } from './messages' import { fileAttributes, mergeAttributeNames } from '../attributes' import { readBlockViews } from '../blockView' @@ -19,11 +20,15 @@ export interface DocumentSnapshot { entryNames?: readonly string[] } -/** 发给预览的文档，和这份源码里起了中文名的定义（扩展端接着找用到它们的各处）、语言插件自己认得出的名字（LocalSymbol）。 */ +/** + * 发给预览的文档，和这份源码里起了中文名的定义（扩展端接着找用到它们的各处）、语言插件自己认得出的名字（LocalSymbol）、 + * 各条导入引进来的名字（注释里不带路径的引用按它找导入的定义）。 + */ export interface DocumentRead { message: DocumentMessage displayNames: DisplayName[] symbols: LocalSymbol[] + imports: ImportedName[] } /** @@ -55,10 +60,10 @@ export async function documentMessage( } const adapter = registry.languageFor(languageId) if (!adapter) - return { message: { ...message, error: `代码阅读还不支持「${languageId}」这种语言` }, displayNames: [], symbols: [] } + return { message: { ...message, error: `代码阅读还不支持「${languageId}」这种语言` }, displayNames: [], symbols: [], imports: [] } try { const rules = registry.rulesFor(languageId) - const { blocks, displayNames, symbols } = await readBlockViews(runtime, adapter, translator, languageId, source, { + const { blocks, displayNames, symbols, imports } = await readBlockViews(runtime, adapter, translator, languageId, source, { ...(document.fileName && { fileName: document.fileName }), rules: { rules, report, lookup }, calleeKind, @@ -73,9 +78,9 @@ export async function documentMessage( }, }) const names = mergeAttributeNames([translator?.attributeNames, ...ruleAttributeNames(rules, translator?.displayLanguage, report)]) - return { message: { ...message, blocks: markEntryBlocks(blocks, source, document.entryNames ?? []), attributes: fileAttributes(blocks, names) }, displayNames, symbols } + return { message: { ...message, blocks: markEntryBlocks(blocks, source, document.entryNames ?? []), attributes: fileAttributes(blocks, names) }, displayNames, symbols, imports } } catch (err) { - return { message: { ...message, error: err instanceof Error ? err.message : String(err) }, displayNames: [], symbols: [] } + return { message: { ...message, error: err instanceof Error ? err.message : String(err) }, displayNames: [], symbols: [], imports: [] } } } diff --git a/vscode/src/codeReader/editor/messages.ts b/vscode/src/codeReader/editor/messages.ts index 67888bd..32400d6 100644 --- a/vscode/src/codeReader/editor/messages.ts +++ b/vscode/src/codeReader/editor/messages.ts @@ -101,9 +101,9 @@ export interface QaMessage { * displayNames：version 这份文档里显示成中文名的名字，查到一步发一步（先本文件定义的，再别的文件定义的）；不是页面上这个版本的不理 * diff：这份文件相比对比基准改了什么（侧栏开着「未提交的更改」或审查工单时才有，见 DiffBase）：每发一份文档之后算好了补发， * 换了筛选、基准挪了（提交后 HEAD 动了）再发；null 是不比了（回到全部文件） - * repoLinksChecked：id 那次 checkRepoLinks 的回答，missing 是仓库里没有的路径 - * repoLinkBroken：这个仓库链接打不开。没有 symbol 是文件或目录没有；有 symbol 是文件在、这个符号没有 - * repoLinkOpened：这个仓库链接打开了。路径在；带了 symbol 时这个符号也在 + * repoLinksChecked：id 那次 checkRepoLinks 的回答，missing 是仓库里没有的路径，unresolved 是找不到的不带路径的引用 + * repoLinkBroken：这个仓库链接打不开。没有 symbol 是文件或目录没有；有 symbol 是文件在、这个符号没有；没有 path 是不带路径的引用找不到 + * repoLinkOpened：这个仓库链接打开了。路径在；带了 symbol 时这个符号也在；没有 path 是不带路径的引用找到了 * repoImagesChecked：id 那次 checkRepoImages 的回答。src 是预览里能直接用的图片地址；没有 src 是文件不在 */ export type ExtensionToWebview @@ -121,9 +121,9 @@ export type ExtensionToWebview | { type: 'rewriteProgress', anchor: string, question: string, text: string, activity?: string } | { type: 'rewriteEnd', anchor: string, status: 'done' | 'failed' | 'stopped', error?: string } | { type: 'diff', diff: DocumentDiff | null } - | { type: 'repoLinksChecked', id: number, missing: string[] } - | { type: 'repoLinkBroken', path: string, symbol?: string } - | { type: 'repoLinkOpened', path: string, symbol?: string } + | { type: 'repoLinksChecked', id: number, missing: string[], unresolved: string[] } + | { type: 'repoLinkBroken', path?: string, symbol?: string } + | { type: 'repoLinkOpened', path?: string, symbol?: string } | { type: 'repoImagesChecked', id: number, images: { path: string, src?: string }[] } | { type: 'focusPathAsk' } @@ -145,8 +145,9 @@ export type ExtensionToWebview * selectAskProfile：「问 AI」换 profile（id 是 profile 名，「默认」是 ''），扩展端记下后发 askProfiles 给所有预览 * occurrenceNavigation：眼下能不能用键盘在高亮着的名字的各处出现之间跳（有高亮、页面有焦点、焦点不在输入框里），变了才发； * 扩展端按它设 when 子句用的上下文键 - * openRepoLink：点了注释里的仓库路径链接，打开 path（从仓库根算起）。symbol 是类名、函数名或「类名.成员名」，没有就只打开文件或在代码阅读侧栏的树上定位目录 - * checkRepoLinks：预览里这批仓库路径，问哪些文件或目录没有。id 标出是哪一次问 + * openRepoLink：点了注释里的仓库路径链接，打开 path（从仓库根算起）。symbol 是类名、函数名或「类名.成员名」，没有就只打开文件或在代码阅读侧栏的树上定位目录； + * 没有 path 是不带路径的引用（`[Name]`、`[Class.member]`），按这份文件找 symbol（本文件定义的，再是导入的，见 symbolLinks.ts） + * checkRepoLinks：预览里这批仓库路径问哪些文件或目录没有，这批不带路径的引用（symbols）问哪些找不到。id 标出是哪一次问 * checkRepoImages：预览里这批仓库图片，问哪些文件在，在的要预览里能直接用的地址。id 标出是哪一次问 */ export type WebviewToExtension @@ -166,6 +167,6 @@ export type WebviewToExtension | { type: 'deleteQa', anchor: string, entryId: string } | { type: 'selectAskProfile', id: string } | { type: 'occurrenceNavigation', available: boolean } - | { type: 'openRepoLink', path: string, symbol?: string } - | { type: 'checkRepoLinks', id: number, paths: string[] } + | { type: 'openRepoLink', path?: string, symbol?: string } + | { type: 'checkRepoLinks', id: number, paths: string[], symbols: string[] } | { type: 'checkRepoImages', id: number, paths: string[] } diff --git a/vscode/src/codeReader/editor/previewEditor.ts b/vscode/src/codeReader/editor/previewEditor.ts index ca8f72a..2c211fb 100644 --- a/vscode/src/codeReader/editor/previewEditor.ts +++ b/vscode/src/codeReader/editor/previewEditor.ts @@ -1,6 +1,6 @@ import type { CustomTextEditorProvider, Disposable, DocumentSymbol, Event, TextDocument, TextDocumentShowOptions, WebviewPanel } from 'vscode' import type { ClaudeImage } from '../../cc/spawnClaude' -import type { BlockKind, LocalSymbol, RuleLocation, RuleReference, WorkspaceIndex } from '../contract' +import type { BlockKind, LocalSymbol, RuleLocation, RuleReference, SourceRange, WorkspaceIndex } from '../contract' import type { DiffBase } from '../diff/diffBase' import type { OldDocument, SentDocument } from '../diff/previewDiff' import type { WorkspaceEntries } from '../entries/workspaceEntries' @@ -9,6 +9,7 @@ import type { CodeQa } from '../qa/codeQa' import type { CodeReaderRegistry } from '../registry' import type { LookupSources } from '../ruleLookups' import type { TreeSitterRuntime } from '../runtime' +import type { ImportedName, LinkTarget, SymbolNode } from '../symbolLinks' import type { IndexedEntry } from '../workspaceIndex' import type { BlockFilter } from './blockFilter' import type { Definition, FoundLocation } from './definitions' @@ -29,6 +30,7 @@ import { askClaude, askFailure } from '../qa/claudeAsk' import { PATH_ASK_ANCHOR } from '../qa/pathQa' import { askPrompt, followUpPrompt } from '../qa/prompt' import { DocumentLookups } from '../ruleLookups' +import { resolveReference } from '../symbolLinks' import { definitionAction } from './definitionAction' import { definitionKind, findDefinitions, languageDefinitions, pickDefinition, ruleDefinitions } from './definitions' import { DefinitionSources } from './definitionSources' @@ -188,6 +190,8 @@ class Preview { private sent: SentDocument | undefined /** 最近一次发出去的文档里语言插件自己认得出的名字（LanguageAdapter.symbols）：语言扩展查不到定义、各处出现时用 */ private symbols: { version: number, list: LocalSymbol[] } | undefined + /** 最近一次发出去的文档里各条导入引进来的名字：注释里不带路径的引用按它找导入的定义 */ + private imports: ImportedName[] = [] /** 这份文档各版本显示成中文名的名字 */ private readonly names: DocumentNames /** 库规则问的名字的定义查到了什么：查到的变了就重发文档 */ @@ -330,7 +334,7 @@ class Preview { const source = this.document.getText() const session = this.lookups.session() const callees = this.callees.session() - const { message, displayNames, symbols } = await documentMessage({ languageId, version, getText: () => source, fileName: this.document.fileName, entryNames: this.owner.entries.namesOf(this.document.uri) }, this.registry, this.runtime, (text) => { + const { message, displayNames, symbols, imports } = await documentMessage({ languageId, version, getText: () => source, fileName: this.document.fileName, entryNames: this.owner.entries.namesOf(this.document.uri) }, this.registry, this.runtime, (text) => { logger.add({ level: 'warn', source: 'codeReader', message: `${this.document.uri.fsPath}：${text}` }) }, session.lookup, callees.calleeKind) if (request !== this.latest || !this.ready) @@ -339,6 +343,7 @@ class Preview { // 解析失败的文档没有块：问 AI 找不到块，也不拿它比差异 this.sent = message.error === undefined ? { version: message.version, blocks: message.blocks, source } : undefined this.symbols = { version, list: symbols } + this.imports = imports const reveal = this.pendingReveal this.pendingReveal = undefined this.post({ ...message, names: this.names.known(version), ...(reveal && { reveal }) }) @@ -579,7 +584,7 @@ class Preview { await this.openRepoLink(msg.path, msg.symbol) return case 'checkRepoLinks': - await this.checkRepoLinks(msg.id, msg.paths) + await this.checkRepoLinks(msg.id, msg.paths, msg.symbols) return case 'checkRepoImages': await this.checkRepoImages(msg.id, msg.paths) @@ -654,16 +659,25 @@ class Preview { await this.owner.openAt(uri, reveal, () => commands.executeCommand('vscode.openWith', uri, PREVIEW_VIEW_TYPE, options)) } - /** 预览里这批仓库路径，哪些文件或目录不在。 */ - private async checkRepoLinks(id: number, paths: string[]): Promise { + /** 预览里这批仓库路径，哪些文件或目录不在；这批不带路径的引用，哪些找不到。 */ + private async checkRepoLinks(id: number, paths: string[], symbols: string[]): Promise { const root = await repoRootOf(this.document.uri.fsPath) - const missing = (await Promise.all(paths.map(async (rel) => { - if (root === undefined || await resolveRepoEntry(root, rel) === undefined) - return rel - return undefined - }))).filter(rel => rel !== undefined) + const asked = new Map>() + const symbolsOf = (uri: string): Promise => { + const known = asked.get(uri) ?? this.symbolNodes(uri) + asked.set(uri, known) + return known + } + const [missing, unresolved] = await Promise.all([ + Promise.all(paths.map(async (rel) => { + if (root === undefined || await resolveRepoEntry(root, rel) === undefined) + return rel + return undefined + })), + Promise.all(symbols.map(async symbol => await this.resolveSymbolLink(symbol, symbolsOf) ? undefined : symbol)), + ]) if (this.ready) - this.post({ type: 'repoLinksChecked', id, missing }) + this.post({ type: 'repoLinksChecked', id, missing: missing.filter(rel => rel !== undefined), unresolved: unresolved.filter(symbol => symbol !== undefined) }) } /** 仓库根放进这个预览能读的本地目录，图片地址才能加载。真实位置和 git 给的路径不一样时两个都放。 */ @@ -707,18 +721,29 @@ class Preview { /** * 打开注释里的仓库链接：目录在代码阅读侧栏的树上定位，文件用编辑器打开。 - * 带了符号就按文档符号的名字跳过去；文件或符号没有就不打开。 + * 带了符号就按文档符号的名字跳过去；文件或符号没有就不打开。没有路径的是不带路径的引用，按这份文件找（见 resolveSymbolLink）。 */ - private async openRepoLink(rel: string, symbol?: string): Promise { - const root = await repoRootOf(this.document.uri.fsPath) - const target = root === undefined ? undefined : await resolveRepoEntry(root, rel) - if (!target) { - this.markRepoLinkBroken(rel, symbol) - return - } - const uri = Uri.file(target.fsPath) + private async openRepoLink(rel: string | undefined, symbol?: string): Promise { + const link = rel ?? `[${symbol}]` try { - if (target.isDirectory) { + if (rel === undefined) { + const target = symbol === undefined ? undefined : await this.resolveSymbolLink(symbol) + if (!target) { + this.markRepoLinkBroken(undefined, symbol) + return + } + await this.showLinkTarget(target) + this.markRepoLinkOpened(undefined, symbol) + return + } + const root = await repoRootOf(this.document.uri.fsPath) + const entry = root === undefined ? undefined : await resolveRepoEntry(root, rel) + if (!entry) { + this.markRepoLinkBroken(rel, symbol) + return + } + const uri = Uri.file(entry.fsPath) + if (entry.isDirectory) { if (symbol !== undefined) { this.markRepoLinkBroken(rel, symbol) return @@ -738,21 +763,69 @@ class Preview { this.markRepoLinkBroken(rel, symbol) return } - await this.showRepoFile(uri, found.selectionRange) + await this.showLinkTarget(found) this.markRepoLinkOpened(rel, symbol) } catch (err) { const message = err instanceof Error ? err.message : String(err) - logger.add({ level: 'warn', source: 'codeReader', message: `没能打开仓库链接 ${rel}：${message}` }) - void window.showErrorMessage(`代码阅读：没能打开 ${rel}`) + logger.add({ level: 'warn', source: 'codeReader', message: `没能打开仓库链接 ${link}：${message}` }) + void window.showErrorMessage(`代码阅读：没能打开 ${link}`) } } - /** 用文档符号按名字找。先把文件读进来（不显示），没有这个名字就没有，不打开到文件顶上。 */ - private async locateRepoSymbol(uri: Uri, symbol: string): Promise { - const doc = await workspace.openTextDocument(uri) + /** 用文档符号按名字找（`Agent`、`Agent.owner_id`）；没有这个名字就没有，不打开到文件顶上。 */ + private async locateRepoSymbol(uri: Uri, symbol: string): Promise { + const found = findRepoSymbol(await this.symbolNodes(uri.toString()), symbol) + return found && { uri: uri.toString(), selection: found.selection } + } + + /** 一个文件的文档符号（vscode.executeDocumentSymbolProvider）：先把文件读进来（不显示），范围换成那个文件里的下标。 */ + private async symbolNodes(uri: string): Promise { + const doc = await workspace.openTextDocument(Uri.parse(uri)) const symbols = await commands.executeCommand('vscode.executeDocumentSymbolProvider', doc.uri) - return Array.isArray(symbols) ? findRepoSymbol(symbols, symbol) : undefined + const span = (range: Range): SourceRange => ({ startIndex: doc.offsetAt(range.start), endIndex: doc.offsetAt(range.end) }) + const node = (symbol: DocumentSymbol): SymbolNode => ({ + name: symbol.name, + range: span(symbol.range), + selection: span(symbol.selectionRange), + children: (symbol.children ?? []).map(node), + }) + return Array.isArray(symbols) ? symbols.map(node) : [] + } + + /** + * 注释里不带路径的引用（`[Name]`、`[Class.member]`）指到哪：本文件定义的优先，再是导入进来的（见 symbolLinks.ts）。 + * 文档符号同仓库链接找符号那一套（symbols，一批引用一起问时共用一份），导入的名字问语言扩展它的定义（同跳到定义），定义几处取第一处。 + */ + private async resolveSymbolLink(symbol: string, symbols: (uri: string) => Promise = uri => this.symbolNodes(uri)): Promise { + const { document } = this + try { + return await resolveReference(symbol, this.imports, { + uri: document.uri.toString(), + symbols, + definition: async (offset) => { + const [found] = await languageDefinitions(document.uri, document.positionAt(offset)) + if (!found) + return undefined + const doc = await workspace.openTextDocument(found.uri) + return { uri: found.uri.toString(), selection: { startIndex: doc.offsetAt(found.range.start), endIndex: doc.offsetAt(found.range.end) } } + }, + }) + } + catch (err) { + logger.add({ level: 'warn', source: 'codeReader', message: `没能找注释里的引用 [${symbol}]：${err instanceof Error ? err.message : String(err)}` }) + return undefined + } + } + + /** 跳到链接指的符号：在这份文件里就在本预览里滚过去、闪一下；别的文件在预览所在的编辑器组打开、选中符号的名字。 */ + private async showLinkTarget({ uri, selection }: LinkTarget): Promise { + if (uri === this.document.uri.toString()) { + this.reveal({ line: this.document.positionAt(selection.startIndex).line, definition: selection.startIndex }) + return + } + const doc = await workspace.openTextDocument(Uri.parse(uri)) + await this.showRepoFile(doc.uri, new Range(doc.positionAt(selection.startIndex), doc.positionAt(selection.endIndex))) } /** 在预览所在的编辑器组打开文件，并把预览标签固定住，免得被它替掉。图片用默认打开方式，才看得到图。 */ @@ -766,14 +839,14 @@ class Preview { await window.showTextDocument(uri, { viewColumn: this.panel.viewColumn, ...(selection && { selection }) }) } - private markRepoLinkBroken(path: string, symbol?: string): void { + private markRepoLinkBroken(path: string | undefined, symbol?: string): void { if (this.ready) - this.post({ type: 'repoLinkBroken', path, ...(symbol !== undefined && { symbol }) }) + this.post({ type: 'repoLinkBroken', ...(path !== undefined && { path }), ...(symbol !== undefined && { symbol }) }) } - private markRepoLinkOpened(path: string, symbol?: string): void { + private markRepoLinkOpened(path: string | undefined, symbol?: string): void { if (this.ready) - this.post({ type: 'repoLinkOpened', path, ...(symbol !== undefined && { symbol }) }) + this.post({ type: 'repoLinkOpened', ...(path !== undefined && { path }), ...(symbol !== undefined && { symbol }) }) } /** 用写注释的技能重写这一段，只把正文套回原来的定界符，再走块编辑那条写回。 */ diff --git a/vscode/src/codeReader/symbolLinks.test.ts b/vscode/src/codeReader/symbolLinks.test.ts new file mode 100644 index 0000000..8d19c0f --- /dev/null +++ b/vscode/src/codeReader/symbolLinks.test.ts @@ -0,0 +1,100 @@ +import type { ReferenceSources, SymbolNode } from './symbolLinks' +import { describe, expect, it } from 'vitest' +import { createPythonAdapter } from './languages/python' +import { createTypeScriptAdapter } from './languages/typescript' +import { importsIn } from './libraryRules' +import { importedNames, resolveReference, splitReference } from './symbolLinks' +import { readFixture, WASM_DIR, withBlocks } from './testSupport' + +const py = createPythonAdapter(WASM_DIR) +const ts = createTypeScriptAdapter(WASM_DIR) + +function symbol(name: string, start: number, end: number, children: SymbolNode[] = []): SymbolNode { + return { name, range: { startIndex: start, endIndex: end }, selection: { startIndex: start, endIndex: start + name.length }, children } +} + +/** 假的语言扩展：几个文件的文档符号，本文件几处名字的定义；记下问过哪些。 */ +function sources(files: Record, definitions: Record = {}): ReferenceSources & { asked: number[] } { + const asked: number[] = [] + return { + uri: 'file:///here.py', + asked, + symbols: async uri => files[uri] ?? [], + definition: async (offset) => { + asked.push(offset) + const found = definitions[offset] + return found && { uri: found.uri, selection: { startIndex: found.at, endIndex: found.at + found.length } } + }, + } +} + +describe('不带路径的引用：拆名字', () => { + it('拆开 Class.member：名字和成员，单个名字没有成员', () => { + expect(splitReference('Agent.owner_id')).toEqual({ head: 'Agent', members: ['owner_id'] }) + expect(splitReference('USER')).toEqual({ head: 'USER', members: [] }) + }) +}) + +describe('不带路径的引用：指到哪', () => { + const imports = [{ name: 'Agent', offset: 20, range: { startIndex: 20, endIndex: 25 } }] + + it('本文件定义的优先于导入的；不问语言扩展', async () => { + const found = sources({ 'file:///here.py': [symbol('Agent', 100, 200)] }, { 20: { uri: 'file:///models.py', at: 5, length: 5 } }) + expect(await resolveReference('Agent', imports, found)).toEqual({ uri: 'file:///here.py', selection: { startIndex: 100, endIndex: 105 } }) + expect(found.asked).toEqual([]) + }) + + it('本文件的 Class.member 在类底下找成员；类有、成员没有就是找不到，不再去导入里找', async () => { + const here = sources({ 'file:///here.py': [symbol('Agent', 100, 200, [symbol('owner_id', 120, 140)])] }, { 20: { uri: 'file:///models.py', at: 5, length: 5 } }) + expect(await resolveReference('Agent.owner_id', imports, here)).toEqual({ uri: 'file:///here.py', selection: { startIndex: 120, endIndex: 128 } }) + expect(await resolveReference('Agent.missing', imports, here)).toBeUndefined() + expect(here.asked).toEqual([]) + }) + + it('导入语句里的名字不算本文件定义的：问那个名字的定义，Class.member 在定义所在文件的那个类底下找', async () => { + const files = { + 'file:///here.py': [symbol('Agent', 20, 25)], + 'file:///models.py': [symbol('Other', 0, 4, [symbol('owner_id', 1, 3)]), symbol('Agent', 10, 90, [symbol('owner_id', 30, 50)])], + } + const found = sources(files, { 20: { uri: 'file:///models.py', at: 10, length: 5 } }) + expect(await resolveReference('Agent', imports, found)).toEqual({ uri: 'file:///models.py', selection: { startIndex: 10, endIndex: 15 } }) + expect(await resolveReference('Agent.owner_id', imports, found)).toEqual({ uri: 'file:///models.py', selection: { startIndex: 30, endIndex: 38 } }) + expect(found.asked).toEqual([20, 20]) + }) + + it('导入的是整个模块（定义落在文件开头）时成员从顶层找', async () => { + const files = { 'file:///errors.py': [symbol('NotFound', 40, 80)] } + const found = sources(files, { 7: { uri: 'file:///errors.py', at: 0, length: 0 } }) + expect(await resolveReference('errors.NotFound', [{ name: 'errors', offset: 7, range: { startIndex: 7, endIndex: 13 } }], found)) + .toEqual({ uri: 'file:///errors.py', selection: { startIndex: 40, endIndex: 48 } }) + }) + + it('本文件没定义、也没导入，或语言扩展答不上：找不到', async () => { + expect(await resolveReference('Nowhere', imports, sources({}))).toBeUndefined() + expect(await resolveReference('Agent', imports, sources({}))).toBeUndefined() + }) +}) + +describe('导入引进来的名字（取自预览已经读出的导入 facts）', () => { + it('python：from 导入问原名的位置、别名按别名认，整个模块按第一节认、起了别名问最后一节，import * 没有', async () => { + const source = 'from a.b import C, D as E\nimport os.path\nimport x.y as z\nfrom m import *\n' + const names = await withBlocks(py, 'python', source, blocks => importedNames(importsIn(blocks))) + expect(names.map(item => [item.name, source.slice(item.offset, item.offset + 1), source.slice(item.range.startIndex, item.range.endIndex)])).toEqual([ + ['C', 'C', 'C'], + ['E', 'D', 'D as E'], + ['os', 'o', 'os.path'], + ['z', 'y', 'x.y as z'], + ]) + }) + + it('typeScript：具名、默认、命名空间导入', async () => { + const source = 'import d, { b as c } from \'y\'\nimport * as ns from \'z\'\n' + const names = await withBlocks(ts, 'typescript', source, blocks => importedNames(importsIn(blocks))) + expect(names.map(item => [item.name, source.slice(item.offset, item.offset + 1)])).toEqual([['d', 'd'], ['c', 'b'], ['ns', 'n']]) + }) + + it('gate.py 导入的 require_desktop_client、AppException 都在，本文件定义的 LocalRuntimeDisabled 不在', async () => { + const names = await withBlocks(py, 'python', readFixture('localRuntimeGate.py'), blocks => importedNames(importsIn(blocks))) + expect(names.map(item => item.name)).toEqual(['annotations', 'Request', 'get_local_runtime_enabled', 'AppException', 'require_desktop_client']) + }) +}) diff --git a/vscode/src/codeReader/symbolLinks.ts b/vscode/src/codeReader/symbolLinks.ts new file mode 100644 index 0000000..2d75757 --- /dev/null +++ b/vscode/src/codeReader/symbolLinks.ts @@ -0,0 +1,118 @@ +import type { ImportFacts, ImportItem, Node, SourceRange } from './contract' + +/** + * 注释里不带路径的引用（KDoc 的 `[Name]`、`[Class.member]`）指到哪：先找本文件定义的，再找本文件导入进来的，都没有就找不到。 + * 符号、定义问语言扩展，交给调用方（预览）去问；这里只管按什么顺序找、怎么拆名字（不碰 VS Code）。 + */ + +/** 本文件某条导入引进来的一个名字：名字、问定义时问的位置（导入语句里那个名字的下标）、这一项在源码里的范围。 */ +export interface ImportedName { + name: string + offset: number + range: SourceRange +} + +/** 一个文件里的一个文档符号：名字、整个定义的范围（看定义落在哪个符号里）、名字的范围、子符号。下标都是那个文件里的。 */ +export interface SymbolNode { + name: string + range: SourceRange + selection: SourceRange + children: readonly SymbolNode[] +} + +/** 引用指到的地方：文件（uri 字符串）和定义处那个名字的范围。 */ +export interface LinkTarget { + uri: string + selection: SourceRange +} + +/** 解析一个引用要问的：本文件是哪个、它的文档符号，本文件某处名字的定义（几处取第一处），别的文件的文档符号。 */ +export interface ReferenceSources { + uri: string + symbols: (uri: string) => Promise + definition: (offset: number) => Promise +} + +function spanOf(nodes: readonly (Node | undefined)[]): SourceRange { + const present = nodes.filter((node): node is Node => node !== undefined) + return { startIndex: Math.min(...present.map(node => node.startIndex)), endIndex: Math.max(...present.map(node => node.endIndex)) } +} + +/** 一项导入引进来的名字：起了别名的是别名；问定义时问原来那个名字（模块问最后一节，那才是这个模块）。整模块导入（`from m import *`）没有。 */ +function importedName(item: ImportItem): ImportedName | undefined { + switch (item.kind) { + case 'named': + return { name: (item.alias ?? item.name).text, offset: item.name.startIndex, range: spanOf([item.name, item.alias]) } + case 'default': + return { name: item.alias.text, offset: item.alias.startIndex, range: spanOf([item.alias]) } + case 'namespace': + return item.alias && { name: item.alias.text, offset: item.alias.startIndex, range: spanOf([item.alias]) } + case 'module': { + const last = item.module.namedChildren.at(-1) ?? item.module + const name = item.alias?.text ?? item.module.text.split('.')[0] + return { name, offset: item.alias ? last.startIndex : item.module.startIndex, range: spanOf([item.module, item.alias]) } + } + } +} + +/** 本文件各条导入（预览已经读出的 ImportFacts）引进来的名字，照源码顺序。 */ +export function importedNames(imports: readonly ImportFacts[]): ImportedName[] { + return imports.flatMap(facts => facts.items.flatMap(item => importedName(item) ?? [])) +} + +/** 引用拆成名字和成员：`Agent.owner_id` 是 Agent 和 [owner_id]。 */ +export function splitReference(reference: string): { head: string, members: string[] } { + const [head = '', ...members] = reference.split('.') + return { head, members } +} + +function covers(range: SourceRange, offset: number): boolean { + return range.startIndex <= offset && offset < range.endIndex +} + +/** 符号底下按名字一层层找成员：先找直接的子符号，没有再往深处找。 */ +function memberOf(symbols: readonly SymbolNode[], members: readonly string[]): SymbolNode | undefined { + const [first, ...rest] = members + const found = symbols.find(symbol => symbol.name === first) ?? deepFind(symbols, first) + return found && (rest.length > 0 ? memberOf(found.children, rest) : found) +} + +function deepFind(symbols: readonly SymbolNode[], name: string | undefined): SymbolNode | undefined { + for (const symbol of symbols) { + const found = symbol.children.find(child => child.name === name) ?? deepFind(symbol.children, name) + if (found) + return found + } + return undefined +} + +/** 盖住 offset 的最里层的符号；定义落在文件开头（导入的是整个模块）时没有。 */ +function innermost(symbols: readonly SymbolNode[], offset: number): SymbolNode | undefined { + const outer = symbols.find(symbol => covers(symbol.range, offset)) + return outer && (innermost(outer.children, offset) ?? outer) +} + +/** + * 引用指到哪，按 KDoc 的规矩： + * 1. 本文件定义的：顶层的符号（类、函数、常量、变量）名字对上，`Class.member` 再在它底下找成员；导入语句里的名字不算本文件定义的。 + * 2. 本文件导入进来的：名字（`Class.member` 的第一段）是某条导入引进来的，问导入语句里那个名字的定义；`Class.member` 再在定义所在文件的 + * 符号里找：定义落在哪个符号里就在它底下找，落在文件开头（导入的是模块）就从顶层找。 + * 3. 都没有：找不到。本文件定义了这个名字、却没有这个成员时也是找不到，不再去导入里找。 + */ +export async function resolveReference(reference: string, imports: readonly ImportedName[], sources: ReferenceSources): Promise { + const { head, members } = splitReference(reference) + const local = await sources.symbols(sources.uri) + const own = local.find(symbol => symbol.name === head && !imports.some(item => covers(item.range, symbol.selection.startIndex))) + if (own) { + const found = members.length > 0 ? memberOf(own.children, members) : own + return found && { uri: sources.uri, selection: found.selection } + } + const imported = imports.find(item => item.name === head) + const target = imported && await sources.definition(imported.offset) + if (!target || members.length === 0) + return target + const symbols = await sources.symbols(target.uri) + const holder = innermost(symbols, target.selection.startIndex) + const found = memberOf(holder ? holder.children : symbols, members) + return found && { uri: target.uri, selection: found.selection } +} diff --git a/vscode/webview-ui/src/codeReader/AskThread.tsx b/vscode/webview-ui/src/codeReader/AskThread.tsx index 6d3e3cb..06f890c 100644 --- a/vscode/webview-ui/src/codeReader/AskThread.tsx +++ b/vscode/webview-ui/src/codeReader/AskThread.tsx @@ -87,7 +87,7 @@ function HistoryItem({ entry, now, onDelete, onOpenImage }: { entry: QaEntryView {expanded - ?
+ ?
: (