diff --git a/.agents/notes/implemented/architecture/2026-11-09-cua-ax-traversal-defaults.i18n.yaml b/.agents/notes/implemented/architecture/2026-11-09-cua-ax-traversal-defaults.i18n.yaml new file mode 100644 index 0000000000..0e2260eefc --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-11-09-cua-ax-traversal-defaults.i18n.yaml @@ -0,0 +1,19 @@ +# Bilingual-pair consistency record for 2026-11-09-cua-ax-traversal-defaults.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-11-09-cua-ax-traversal-defaults.md +/agent-note-ax-traversal-defaults-and-per-read-limits: + en: 71a088b589135b94 + zh: 40a0accb1f6d100b +/agent-note-ax-traversal-defaults-and-per-read-limits/problem: + en: 18405553f792f64c + zh: 1b6891403539c2f8 +/agent-note-ax-traversal-defaults-and-per-read-limits/decision: + en: 89cb2b1f33b0551c + zh: b57839093a735c2a +/agent-note-ax-traversal-defaults-and-per-read-limits/alternatives-considered: + en: c15d84e0bbb18b39 + zh: 4799291d7a66fa04 +/agent-note-ax-traversal-defaults-and-per-read-limits/consequences: + en: 687f4ba2af13e847 + zh: ae5777022619b71d diff --git a/.agents/notes/implemented/architecture/2026-11-09-cua-ax-traversal-defaults.md b/.agents/notes/implemented/architecture/2026-11-09-cua-ax-traversal-defaults.md new file mode 100644 index 0000000000..37a04b4aa7 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-11-09-cua-ax-traversal-defaults.md @@ -0,0 +1,21 @@ +# Agent Note: AX traversal defaults and per-read limits + +Status: implemented + +English | [中文](2026-11-09-cua-ax-traversal-defaults.zh.md) + +## Problem + +A shallow read can omit a control in a deeply nested window. Increasing the profile settings to reach it also increases the work and possible output of subsequent reads. + +## Decision + +For an accessibility tree read, the Host takes each of `maxElements` and `maxDepth` from the request when present and from the provider configuration otherwise. A caller can raise or lower either value for one read. The native provider enforces its traversal ceilings. On macOS, Paste menu discovery always uses the configured values because the paste operation has no traversal options. + +## Alternatives considered + +**Cap each read at the configured values.** With a profile tuned for small reads, recovering a truncated branch would require changing the profile even when the provider can handle a larger request. Per-read overrides let the caller inspect that window and return to the usual limits on the next read. + +## Consequences + +Lowering a profile default reduces the budget for ordinary reads. An explicit larger request can take longer and produce more text. The native operation deadline and response size limit still apply. The [macOS configuration table](../../../../packages/experimental/cua-macos/README.md#use-this-package) lists the defaults. diff --git a/.agents/notes/implemented/architecture/2026-11-09-cua-ax-traversal-defaults.zh.md b/.agents/notes/implemented/architecture/2026-11-09-cua-ax-traversal-defaults.zh.md new file mode 100644 index 0000000000..536a6908eb --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-11-09-cua-ax-traversal-defaults.zh.md @@ -0,0 +1,21 @@ +# Agent Note: AX 树遍历的默认值和单次读取上限 + +Status: implemented + +[English](2026-11-09-cua-ax-traversal-defaults.md) | 中文 + +## 问题 + +读取深度较小时,控件可能位于窗口中被截断的分支里。为了找到这个控件而调高配置值,会让以后的读取也可能访问更多节点、返回更多文本。 + +## 决策 + +读取辅助功能树时,Host 分别处理 `maxElements` 和 `maxDepth`。调用方显式传入的值只对本次读取生效,可以高于或低于配置值。省略的参数使用平台配置。原生实现在遍历时执行自身的硬上限。macOS 的粘贴操作没有遍历参数,查找粘贴菜单时始终使用配置值。 + +## 考虑过的替代方案 + +**把配置值作为每次读取的硬上限。** 如果日常读取使用较小的配置值,即使平台支持读取更大的树,调用方也必须先修改配置才能看到被截断的分支。允许单次覆盖后,调用方可以单独扩大这次读取的范围,下次读取继续使用原有配置。 + +## 影响 + +调低配置值可以缩小常规读取的范围。显式请求更大的树可能耗时更长,也可能返回更多文本。原生调用仍受超时和响应大小限制。默认值见 [macOS 配置表](../../../../packages/experimental/cua-macos/README.zh.md#use-this-package)。 diff --git a/.agents/notes/implemented/feature/2026-10-09-forge-panel.i18n.yaml b/.agents/notes/implemented/feature/2026-10-09-forge-panel.i18n.yaml index f779b7be73..83daa37ac0 100644 --- a/.agents/notes/implemented/feature/2026-10-09-forge-panel.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-10-09-forge-panel.i18n.yaml @@ -9,8 +9,8 @@ en: 344bcc7e9825bbc8 zh: c1d0f4b54f5b3786 /agent-note-change-request-panel-and-worktree-sessions/decision: - en: 66bde24e7c601eb6 - zh: 5091591f3dc1ac85 + en: 4695a1e4f8aa7a25 + zh: e17be0e36ea3eaa3 /agent-note-change-request-panel-and-worktree-sessions/deferred: en: 32ef8af85f4d2f66 zh: b82b67f94346399e diff --git a/.agents/notes/implemented/feature/2026-10-09-forge-panel.md b/.agents/notes/implemented/feature/2026-10-09-forge-panel.md index 2b852ad824..32b6fb4edc 100644 --- a/.agents/notes/implemented/feature/2026-10-09-forge-panel.md +++ b/.agents/notes/implemented/feature/2026-10-09-forge-panel.md @@ -28,7 +28,7 @@ The panel does not move a Session between existing worktrees. Removing a change The panel also shows the changes behind a Session's work in a changes view, a resource tab type of this package. The Remote parses every diff on the Host into files and hunks, so the browser draws them without a patch parser, and bounds each read with `maxDiffBytes` and `maxUntrackedFiles`. Local changes come from `git diff` using the Session's permissions and execution world, in a scope the user picks: the branch against its fork point by default, or the uncommitted, unstaged, or staged changes; untracked files are read through the Session's filesystem and shown as new files. A change request's changes come from its code host at the head of the binding's latest status, through two provider reads the forge seam gained, `diff` and `fileText`. The Host keeps the patch it read last for each change request, keyed by the head commit and base branch and bounded by `maxCachedDiffBytes`, so reopening, refreshing, and navigating at the same head download nothing again; a host or provider that refuses an answer over its size limit reports the forge failure `too-large`, and the view then offers the change request's web page instead of a retry. Unchanged lines between hunks expand from the file's new side, which is the working tree, the index, or the head commit, and only while that text still matches the hunks. Each inspection also sizes the branch's changes for a local changes card, shown while no open change request carries the checked-out branch; its Create change request sends the Session a user message, so the Agent creates the change request with its own tools and the binding follows from `gh pr create` as for any other. -Review comments capture the file, side, range, complete hunk, and reviewed head when the user selects code. Agent references enter the existing composer quote mechanism, so the user controls batching and the sent message records exactly what the model receives. GitHub writes belong to the optional forge provider operation: preflight checks the current head, the write addresses that commit, and an ambiguous outcome blocks another write until the user reconciles it. Review drafts and inline records belong to a browser tab occurrence, not to the Session log or a GitHub pending review. Switching Sessions retains that occurrence; closing it discards the local state and rejects late write completions. Published GitHub comments remain external records. +Review comments capture the file, side, range, complete hunk, and reviewed head when the user selects code. Agent references enter the existing composer quote mechanism, so the user controls batching and the sent message records exactly what the model receives. GitHub writes belong to the optional forge provider operation: preflight checks the current head, the write addresses that commit, and an ambiguous outcome blocks another write until the user reconciles it. Inline records of Agent references and published comments, and the review summary, belong to a browser tab occurrence, not to the Session log; a pull request comment kept for a later review goes to the code host's pending review, as [the pending review decision](2026-11-05-forge-pending-review-drafts.md) records. Switching Sessions retains that occurrence; closing it discards the local state and rejects late write completions. Published GitHub comments remain external records. ## Deferred diff --git a/.agents/notes/implemented/feature/2026-10-09-forge-panel.zh.md b/.agents/notes/implemented/feature/2026-10-09-forge-panel.zh.md index 660bd81d38..6e8438080c 100644 --- a/.agents/notes/implemented/feature/2026-10-09-forge-panel.zh.md +++ b/.agents/notes/implemented/feature/2026-10-09-forge-panel.zh.md @@ -28,7 +28,7 @@ Session 所在的 worktree 可能在 Session 之外被删除。每次检查都 面板还通过变更视图展示 Session 工作背后的变更;变更视图是本包的一个资源标签页类型。Remote 在宿主上把每个 diff 解析成文件与 hunk,因此浏览器无需补丁解析器即可绘制,每次读取都受 `maxDiffBytes` 与 `maxUntrackedFiles` 约束。本地变更来自使用 Session 权限与执行环境的 `git diff`,范围由用户选择:默认是分支相对于分叉点的变更,也可以是未提交、未暂存或已暂存的变更;未跟踪文件经 Session 的文件系统读取,显示为新文件。变更请求的变更来自代码托管平台,取自绑定最新状态中的 head,经 forge seam 新增的两个提供方读取操作 `diff` 与 `fileText` 获得。Host 为每个变更请求保留最近读到的补丁,按 head 提交与目标分支区分,总量受 `maxCachedDiffBytes` 约束,因此在同一 head 下重新打开、刷新与导航都不会再次下载;托管平台或提供方因结果超过其大小上限而拒绝时报告 forge 失败 `too-large`,视图随之提供变更请求的网页而不是重试。hunk 之间未变更的行从文件的新版本展开,即工作树、暂存区或 head 提交,并且只在该文本仍与 hunk 吻合时展开。每次检查还会为变更卡片统计分支的变更规模;没有打开中的变更请求以当前检出分支为源分支时才显示该卡片。卡片上的“创建变更请求”向 Session 发送一条用户消息,由 Agent 用自己的工具创建变更请求,绑定像其他变更请求一样来自 `gh pr create`。 -评审评论在用户选择代码时固定文件、侧、行范围、完整 hunk 与所评审的 head。Agent 引用进入既有输入框引用机制,由用户决定批量发送,发送后的消息记录模型实际收到的内容。GitHub 写入属于 forge 提供方的可选操作:预检核对当前 head,写入明确指向该提交;结果不明时阻止再次写入,直到用户核对。评审草稿与行内记录归浏览器页签实例所有,不进入 Session 日志,也不创建 GitHub 待提交评审。切换 Session 保留该实例;关闭时丢弃本地状态并拒绝迟到的写入结果。已发布的 GitHub 评论仍保留在外部平台。 +评审评论在用户选择代码时固定文件、侧、行范围、完整 hunk 与所评审的 head。Agent 引用进入既有输入框引用机制,由用户决定批量发送,发送后的消息记录模型实际收到的内容。GitHub 写入属于 forge 提供方的可选操作:预检核对当前 head,写入明确指向该提交;结果不明时阻止再次写入,直到用户核对。Agent 引用与已发布评论的行内记录以及评审总结归浏览器页签实例所有,不进入 Session 日志;留待之后一起提交的 PR 评论写入代码托管平台的待提交评审,见[待提交评审决策](2026-11-05-forge-pending-review-drafts.zh.md)。切换 Session 保留该实例;关闭时丢弃本地状态并拒绝迟到的写入结果。已发布的 GitHub 评论仍保留在外部平台。 ## Deferred diff --git a/.agents/notes/implemented/feature/2026-11-05-forge-pending-review-drafts.i18n.yaml b/.agents/notes/implemented/feature/2026-11-05-forge-pending-review-drafts.i18n.yaml new file mode 100644 index 0000000000..eb6f1712fb --- /dev/null +++ b/.agents/notes/implemented/feature/2026-11-05-forge-pending-review-drafts.i18n.yaml @@ -0,0 +1,19 @@ +# Bilingual-pair consistency record for 2026-11-05-forge-pending-review-drafts.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-11-05-forge-pending-review-drafts.md +/agent-note-pull-request-comment-drafts-in-the-code-host-s-pending-review: + en: 25b4da2d12f15b82 + zh: 6d9fec68e8bb0baa +/agent-note-pull-request-comment-drafts-in-the-code-host-s-pending-review/problem: + en: 2674866671bd0d4b + zh: e60d41a24d20d7bf +/agent-note-pull-request-comment-drafts-in-the-code-host-s-pending-review/decision: + en: 3df55965423b6d33 + zh: 2e8f0fbb4f7a311f +/agent-note-pull-request-comment-drafts-in-the-code-host-s-pending-review/alternatives-considered: + en: ef67e05cb9442f05 + zh: d4433ddd090a9cec +/agent-note-pull-request-comment-drafts-in-the-code-host-s-pending-review/consequences: + en: 198f6cf5a2bc2230 + zh: 92eb0a349356f100 diff --git a/.agents/notes/implemented/feature/2026-11-05-forge-pending-review-drafts.md b/.agents/notes/implemented/feature/2026-11-05-forge-pending-review-drafts.md new file mode 100644 index 0000000000..d0c4cf0d89 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-11-05-forge-pending-review-drafts.md @@ -0,0 +1,31 @@ +# Agent Note: Pull request comment drafts in the code host's pending review + +Status: implemented + +English | [中文](2026-11-05-forge-pending-review-drafts.zh.md) + +## Problem + +The [forge panel](2026-10-09-forge-panel.md) kept a pull request's comment drafts in a browser tab occurrence, published them as one review, and recorded what it published. Once the changes view shows the code host's review threads and lets the user reply to them, browser drafts leave four gaps. A reply cannot join a later review, because the drafts and the threads live in different places. A review the user started on the GitHub page, or in another browser, does not appear, and GitHub refuses a review submitted while the user has one. Drafts are lost with the tab and invisible on another device. And GitHub keeps one pending review per user and pull request, so two stores of one review would disagree. + +## Decision + +A pull request comment that the user keeps for a later review goes to the user's pending review on the code host through the provider's optional `writeReview`. The first such comment or reply starts the pending review at the head the user saw; later ones join it. The changes view reads the pending review with the threads, shows its comments as threads tagged Pending, and Submit review submits or discards that review with the summary and decision. Replies, resolving and unresolving, and editing and deleting the user's own comments use the same write, which re-checks the head and is never retried. + +The browser keeps what the code host does not hold: the review summary and decision until submission, the records of Agent references and published comments, and the outgoing direct write whose outcome needs confirmation. Comments on local changes never had a host destination; they go to the main input as before. Comment drafts an earlier panel kept in the browser stay readable: they show beside their code as browser drafts, can move into the pending review, and keep Submit review disabled while a pending review exists; without one, Submit review publishes them as one review as before. + +GitHub measurements on a private test repository decided three rules. While the user has a pending review, GitHub refuses a directly created review and a single comment (HTTP 422, "can only have one pending review per pull request"), so the view offers neither; a reply sent without the review's id still joins the review, so the view offers no reply at once and the provider refuses one. GitHub refuses Approve and Request changes on the user's own pull request, so the dialog offers only Comment there. + +## Alternatives considered + +**Keeping drafts in the browser tab.** It needs no host write until submission, but replies cannot join the same review, a review started elsewhere blocks submission without explanation, and the drafts do not follow the user to another device. + +**Keeping both stores.** Mirroring browser drafts into the pending review or the reverse gives one review two owners whose contents can diverge, and every edit would need reconciliation of two writes. + +**Recording drafts in the Session log.** The log records what reaches the model; review drafts are host state the model never sees, and other Sessions on the same pull request would not see them. + +**Retrying a write after an unknown outcome.** A lost response does not show whether GitHub applied the mutation. A submission of the pending review is kept as the write to reconcile, as a direct submission is, and blocks another submission until the user checks GitHub; a reply, resolution, or comment change reads the threads again and asks the user to check them before trying again. + +## Consequences + +A comment kept for later is visible on the GitHub page to its author before submission, and is lost only when the user discards the review. Each comment, reply, or thread change costs one GraphQL query for the head check and one mutation. Resolving a thread does not change the pull request's update time, so every write from the panel drops the panel's kept threads; another view of the same pull request shows the change at its next status or after `reviewRefreshMs`. A provider without `writeReview` reports no write permissions, so its threads stay read-only and its pull request comments are published at once or added to the input. Comment drafts from an earlier panel remain until the user moves, publishes, or deletes them, or closes their tab. diff --git a/.agents/notes/implemented/feature/2026-11-05-forge-pending-review-drafts.zh.md b/.agents/notes/implemented/feature/2026-11-05-forge-pending-review-drafts.zh.md new file mode 100644 index 0000000000..0dc9c99e2a --- /dev/null +++ b/.agents/notes/implemented/feature/2026-11-05-forge-pending-review-drafts.zh.md @@ -0,0 +1,31 @@ +# Agent Note: PR 评论草稿保存在代码托管平台的待提交评审中 + +Status: implemented + +[English](2026-11-05-forge-pending-review-drafts.md) | 中文 + +## Problem + +[forge 面板](2026-10-09-forge-panel.zh.md)原先把 PR 的评论草稿保存在浏览器页签实例中,作为一次评审发布,并记录已发布的内容。变更视图显示代码托管平台的评审讨论并允许用户回复之后,浏览器草稿留下四个缺口。回复无法加入之后的评审,因为草稿与讨论保存在不同的地方。用户在 GitHub 页面或另一个浏览器中开始的评审不会显示,而用户已有待提交评审时,GitHub 会拒绝直接提交的评审。草稿随页签丢失,在其他设备上也看不到。GitHub 每个用户在每个 PR 上只保留一个待提交评审,两处保存同一个评审会出现不一致。 + +## Decision + +用户留待之后一起提交的 PR 评论,通过提供方的可选能力 `writeReview` 写入代码托管平台上该用户的待提交评审。第一条这样的评论或回复在用户看到的 head 上开始待提交评审,之后的评论或回复加入其中。变更视图随讨论一起读取待提交评审,把其中的评论显示为带“待提交”标签的讨论;“提交评审”带着总结和评审决定提交或丢弃这个评审。回复、解决与取消解决、编辑与删除用户自己的评论也使用同一写操作;写操作会重新检查 head,且从不重试。 + +浏览器只保存代码托管平台不保存的内容:提交前的评审总结与评审决定、Agent 引用与已发布评论的记录,以及结果有待确认的直接写入。本地变更上的评论本来就没有托管平台上的去处,仍像以前一样进入主输入框。早期面板保存在浏览器中的评论草稿仍可读取:它们作为浏览器草稿显示在对应代码旁,可以加入待提交评审;存在待提交评审时,它们会让“提交评审”保持不可用;没有待提交评审时,“提交评审”像以前一样把它们作为一次评审发布。 + +在一个私有测试仓库上对 GitHub 的实测确定了三条规则。用户已有待提交评审时,GitHub 拒绝直接创建的评审和单条评论(HTTP 422,“每个 PR 只能有一个待提交评审”),因此视图两者都不提供;不带评审 id 发送的回复仍会加入该评审,因此视图不提供立即回复,提供方也拒绝这种回复。GitHub 拒绝用户批准或请求更改自己的 PR,因此在这种 PR 上,弹窗只提供“评论”。 + +## Alternatives considered + +**把草稿保存在浏览器页签中。** 提交之前不需要写入托管平台,但回复无法加入同一个评审,在别处开始的评审会无说明地阻止提交,草稿也无法随用户换到另一台设备。 + +**两处同时保存。** 把浏览器草稿同步到待提交评审,或反过来同步,会让一个评审有两个所有者,内容可能分歧,每次编辑都要核对两次写入。 + +**把草稿记录在 Session 日志中。** 日志记录的是到达模型的内容;评审草稿是模型永远看不到的托管平台状态,同一 PR 上的其他 Session 也看不到它们。 + +**结果不明时自动重试写操作。** 响应丢失并不能说明 GitHub 是否执行了 mutation。提交待提交评审时,与直接提交一样,这次提交会作为待核对的写入保留下来,在用户到 GitHub 核对之前阻止再次提交;回复、解决讨论或修改评论时,视图重新读取讨论,并请用户核对后再重试。 + +## Consequences + +留待之后提交的评论,在提交前其作者就能在 GitHub 页面上看到,只有用户丢弃评审时才会丢失。每条评论、回复或讨论状态的修改,都消耗一次用于检查 head 的 GraphQL 查询和一个 mutation。解决讨论不会改变 PR 的更新时间,因此面板发出的每个写操作都会丢弃面板保留的讨论;同一 PR 的其他视图在收到下一次状态时,或在 `reviewRefreshMs` 之后显示这一变化。未实现 `writeReview` 的提供方不报告任何写入权限,因此它的讨论保持只读,它的 PR 评论只能立即发布或添加到输入框。早期面板留下的评论草稿会一直保留,直到用户把它们加入评审、发布、删除,或关闭所在页签。 diff --git a/apps/web/tests/expected/forge-panel/discard-review.expected.md b/apps/web/tests/expected/forge-panel/discard-review.expected.md new file mode 100644 index 0000000000..a31563daba --- /dev/null +++ b/apps/web/tests/expected/forge-panel/discard-review.expected.md @@ -0,0 +1,19 @@ +- dialog "提交评审": + - heading "提交评审" [level=2] + - button "关闭" + - text: 待提交评论(1) + - group "丢弃评审": + - text: 丢弃待提交的评审及其中的 1 条评论?此操作无法撤销 + - button "取消" + - button "丢弃评审" + - textbox "评审总结…" + - status + - radio "评论" [checked] + - text: 评论 + - radio "批准" + - text: 批准 + - radio "请求更改" + - text: 请求更改 + - button "丢弃评审" [disabled] + - button "取消" + - button "提交评审" [disabled] diff --git a/apps/web/tests/expected/forge-panel/review-record.expected.md b/apps/web/tests/expected/forge-panel/review-record.expected.md index 3e678d6071..aef059b24e 100644 --- a/apps/web/tests/expected/forge-panel/review-record.expected.md +++ b/apps/web/tests/expected/forge-panel/review-record.expected.md @@ -1,4 +1,8 @@ -- region "评论 R2–4": - - text: 你的评论 R2–4 已发布到 GitHub 请核对边界条件 +- region "R2–4": + - text: R2–4 · 在 aaaaaaa 上 lin 1 个月前 + - button "lin 的评论操作" + - paragraph: 请核对边界条件 + - button "回复…" - button "添加到输入框" - - button "在 GitHub 查看" + - button "在 GitHub 中查看" + - button "解决讨论" diff --git a/apps/web/tests/expected/forge-panel/review-summary-required.expected.md b/apps/web/tests/expected/forge-panel/review-summary-required.expected.md index 3e384b28e1..2a56eddd38 100644 --- a/apps/web/tests/expected/forge-panel/review-summary-required.expected.md +++ b/apps/web/tests/expected/forge-panel/review-summary-required.expected.md @@ -10,5 +10,6 @@ - text: 批准 - radio "请求更改" [checked] - text: 请求更改 + - button "丢弃评审" - button "取消" - button "提交评审" [disabled] diff --git a/apps/web/tests/expected/forge-panel/review-thread-list.expected.md b/apps/web/tests/expected/forge-panel/review-thread-list.expected.md new file mode 100644 index 0000000000..bdfb2dc803 --- /dev/null +++ b/apps/web/tests/expected/forge-panel/review-thread-list.expected.md @@ -0,0 +1,15 @@ +- complementary "讨论列表,共 5 个": + - text: 讨论 5 + - button "关闭讨论列表" + - radiogroup "筛选讨论": + - radio "未解决 4" + - radio "已解决 1" + - radio "全部 5" [checked] + - heading "docs/panel.md" [level=3] + - button "文件级讨论 Add a screenshot." + - heading "src/panel.ts" [level=3] + - button "R2 · 1 条回复 Why two?" + - button "L15 The old fifteen was a number." + - button "R15 Settled. 已解决" + - button "原在 R9 · 在 fffffff 上 This line moved. 已过期" + - button "在 GitHub 中查看" diff --git a/apps/web/tests/expected/forge-panel/review-thread-message.expected.md b/apps/web/tests/expected/forge-panel/review-thread-message.expected.md new file mode 100644 index 0000000000..0ea820a2af --- /dev/null +++ b/apps/web/tests/expected/forge-panel/review-thread-message.expected.md @@ -0,0 +1,19 @@ +> ## Review Thread 1 +> File: src/panel.ts +> Side: R +> Lines: 2 +> Commit: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +> State: unresolved +> Source: https://github.com/octo/demo/pull/7#discussion_on-line_0 +> Diff hunk: +> ```diff +> @@ -1,5 +1,5 @@ +> export const n1 = 1 +> -export const n2 = 2 +> +export const n2 = 'two' +> ``` +> Comments: +> @lin (2026-10-09T00:00:00Z): +> > Why **two**? +> @octo (2026-10-09T00:00:00Z): +> > It reads better. diff --git a/apps/web/tests/expected/forge-panel/review-thread-reply.expected.md b/apps/web/tests/expected/forge-panel/review-thread-reply.expected.md new file mode 100644 index 0000000000..0a6b4b489c --- /dev/null +++ b/apps/web/tests/expected/forge-panel/review-thread-reply.expected.md @@ -0,0 +1,16 @@ +- region "R2": + - text: R2 · 在 aaaaaaa 上 lin 2 小时前 + - button "lin 的评论操作" + - paragraph: + - text: Why + - strong: two + - text: "?" + - text: octo 2 小时前 作者 + - paragraph: It reads better. + - textbox "回复…": 已改为字符串 + - button "取消" + - button "回复" + - button "回复选项" + - button "添加到输入框" + - button "在 GitHub 中查看" + - button "解决讨论" diff --git a/apps/web/tests/expected/forge-panel/review-threads.expected.md b/apps/web/tests/expected/forge-panel/review-threads.expected.md new file mode 100644 index 0000000000..ff5dc738a5 --- /dev/null +++ b/apps/web/tests/expected/forge-panel/review-threads.expected.md @@ -0,0 +1,91 @@ +- button "收起 panel.ts" [expanded] +- text: src/panel.ts +- button "panel.ts 有 3 条未解决的讨论,跳到下一条": 3 条未解决 +- text: +2 −2 +- checkbox "将 panel.ts 标记为已审阅" +- button "panel.ts 的更多操作" +- button "选择第 L1 行": "1" +- text: export const n1 = 1 +- button "选择第 R1 行": "1" +- text: export const n1 = 1 +- button "选择第 L2 行": "2" +- text: export const n2 = 2 +- button "选择第 R2 行": "2" +- text: export const n2 = 'two' +- region "R2": + - text: R2 · 在 aaaaaaa 上 lin 2 小时前 + - button "lin 的评论操作" + - paragraph: + - text: Why + - strong: two + - text: "?" + - text: octo 2 小时前 作者 + - paragraph: It reads better. + - button "回复…" + - button "添加到输入框" + - button "在 GitHub 中查看" + - button "解决讨论" +- button "选择第 L3 行": "3" +- text: export const n3 = 3 +- button "选择第 R3 行": "3" +- text: export const n3 = 3 +- button "选择第 L4 行": "4" +- text: export const n4 = 4 +- button "选择第 R4 行": "4" +- text: export const n4 = 4 +- button "选择第 L5 行": "5" +- text: export const n5 = 5 +- button "选择第 R5 行": "5" +- text: export const n5 = 5 +- button "6 行未变更" +- button "选择第 L12 行": "12" +- text: export const n12 = 12 +- button "选择第 R12 行": "12" +- text: export const n12 = 12 +- button "选择第 L13 行": "13" +- text: export const n13 = 13 +- button "选择第 R13 行": "13" +- text: export const n13 = 13 +- button "选择第 L14 行": "14" +- text: export const n14 = 14 +- button "选择第 R14 行": "14" +- text: export const n14 = 14 +- button "选择第 L15 行": "15" +- text: export const n15 = 15 +- button "选择第 R15 行": "15" +- text: export const n15 = 'fifteen' +- region "L15": + - text: L15 · 在 aaaaaaa 上 lin 2 小时前 + - button "lin 的评论操作" + - paragraph: The old fifteen was a number. + - button "回复…" + - button "添加到输入框" + - button "在 GitHub 中查看" + - button "解决讨论" +- text: 已解决的讨论 · lin +- button "展开" +- button "选择第 L16 行": "16" +- text: export const n16 = 16 +- button "选择第 R16 行": "16" +- text: export const n16 = 16 +- button "选择第 L17 行": "17" +- text: export const n17 = 17 +- button "选择第 R17 行": "17" +- text: export const n17 = 17 +- button "选择第 L18 行": "18" +- text: export const n18 = 18 +- button "选择第 R18 行": "18" +- text: export const n18 = 18 +- button "其余未变更的行" +- text: 1 条讨论已过期:所在代码已被后续提交修改 +- button "收起" [expanded] +- region "原在 R9": + - text: 原在 R9 · 在 fffffff 上 已过期 + - button "查看当时的文件" + - text: "@@ -1,5 +1,5 @@ export const n1 = 1 -export const n2 = 2 +export const n2 = 'two' lin 2 小时前" + - button "lin 的评论操作" + - paragraph: This line moved. + - button "回复…" + - button "添加到输入框" + - button "在 GitHub 中查看" + - button "解决讨论" diff --git a/apps/web/tests/expected/forge-panel/submit-review.expected.md b/apps/web/tests/expected/forge-panel/submit-review.expected.md index 0687f7ba99..8affefb880 100644 --- a/apps/web/tests/expected/forge-panel/submit-review.expected.md +++ b/apps/web/tests/expected/forge-panel/submit-review.expected.md @@ -10,5 +10,6 @@ - text: 批准 - radio "请求更改" [checked] - text: 请求更改 + - button "丢弃评审" - button "取消" - button "提交评审" diff --git a/apps/web/tests/forge-panel.e2e.ts b/apps/web/tests/forge-panel.e2e.ts index 6f6990b494..60642f1499 100644 --- a/apps/web/tests/forge-panel.e2e.ts +++ b/apps/web/tests/forge-panel.e2e.ts @@ -1,5 +1,6 @@ /** Worktree Sessions and the change request panel through the real optional bundle, a Git checkout, and a scripted GitHub CLI. */ import { execFile } from 'node:child_process' +import { existsSync } from 'node:fs' import { access, chmod, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' import { homedir, tmpdir } from 'node:os' import { basename, join } from 'node:path' @@ -49,8 +50,14 @@ const run = promisify(execFile) * `pr-N.diff`, or, when `pr-N.refused` exists, fails with that JSON error body * and the matching diagnostic as GitHub's HTTP 406 refusal. The raw contents API * serves `contents.json`, keyed by `path@commit`, and the commit listing of pull - * request 7 serves `commits.json`, oldest first. Every invocation is appended to - * `calls.jsonl`. + * request 7 serves `commits.json`, oldest first. The review thread read serves + * `threads.json` as its one page of threads, with the viewer `lin`, who may write + * to the repository and did not open either pull request, or no threads without it. Review mutations, which arrive as + * JSON on stdin, change what later reads report through `state.json`: replies, + * which join the pending review whenever one exists, resolution, comment edits and + * deletions, and the pending review of `lin` with its new threads, which a + * submission publishes. Each mutation is appended to + * `mutations.jsonl`, and every invocation to `calls.jsonl`. */ const GH = `#!/usr/bin/env node import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs' @@ -131,6 +138,56 @@ if (args[0] === 'auth' && args[1] === 'status') { process.stdout.write('github.com\\n Logged in to github.com account octo\\n') process.exit(0) } +const review = () => ({ pending: null, published: [], replies: {}, resolved: {}, bodies: {}, deleted: [], ...state.review }) +/** The signed-in reviewer, who did not open the pull requests. */ +const VIEWER = 'lin' +/** One review comment node by \`login\`, which the viewer may change when it is the viewer's own. */ +const commentNode = (id, body, login, pending) => ({ id, state: pending ? 'PENDING' : 'SUBMITTED', createdAt: '2026-10-09T01:00:00Z', + url: pending ? null : 'https://github.com/octo/demo/pull/7#discussion_' + id, body, + viewerCanUpdate: login === VIEWER, viewerCanDelete: login === VIEWER, author: { __typename: 'User', login, avatarUrl: null } }) +if (args[0] === 'api' && args[1] === 'graphql' && args.includes('--input')) { + const { query, variables } = JSON.parse(readFileSync(0, 'utf8')) + const field = query.match(/\\{\\s*(\\w+)\\(input:/)[1] + appendFileSync(join(here, 'mutations.jsonl'), JSON.stringify({ field, variables }) + '\\n') + const current = review() + const draft = thread => ({ id: 'new-' + (current.published.length + (current.pending?.threads.length ?? 0) + 1), + path: thread.path, side: thread.side, line: thread.line, startLine: thread.startLine ?? null, body: thread.body }) + let payload + if (field === 'addPullRequestReview') { + current.pending = { id: 'review-1', commit: variables.commit, threads: [] } + for (const thread of variables.threads ?? []) current.pending.threads.push(draft(thread)) + payload = { pullRequestReview: { id: 'review-1' } } + } else if (field === 'addPullRequestReviewThread') { + current.pending.threads.push(draft(variables)) + payload = { thread: { id: current.pending.threads.at(-1).id } } + } else if (field === 'addPullRequestReviewThreadReply') { + const replies = current.replies[variables.thread] ??= [] + // As on GitHub, a reply joins the pending review whenever one exists. + replies.push({ id: variables.thread + '-reply-' + replies.length, body: variables.body, pending: variables.review !== null || current.pending !== null }) + payload = { comment: { id: replies.at(-1).id } } + } else if (field === 'resolveReviewThread' || field === 'unresolveReviewThread') { + current.resolved[variables.thread] = field === 'resolveReviewThread' + payload = { thread: { id: variables.thread } } + } else if (field === 'updatePullRequestReviewComment') { + current.bodies[variables.comment] = variables.body + payload = { pullRequestReviewComment: { id: variables.comment } } + } else if (field === 'deletePullRequestReviewComment') { + current.deleted.push(variables.comment) + payload = { clientMutationId: null } + } else if (field === 'submitPullRequestReview' || field === 'deletePullRequestReview') { + if (field === 'submitPullRequestReview') current.published.push(...current.pending.threads) + for (const replies of Object.values(current.replies)) { + for (const reply of replies) if (reply.pending && field === 'deletePullRequestReview') current.deleted.push(reply.id) + for (const reply of replies) reply.pending = false + } + current.pending = null + payload = { pullRequestReview: { id: variables.review } } + } + state.review = current + save() + process.stdout.write(JSON.stringify({ data: { [field]: payload } })) + process.exit(0) +} if (args[0] === 'api' && args[1] === 'graphql') { const query = args.find(arg => arg.startsWith('query=')).slice('query='.length) const check = (name, conclusion, completedAt, databaseId = 101) => ({ @@ -171,6 +228,41 @@ if (args[0] === 'api' && args[1] === 'graphql') { } } } } })) process.exit(0) } + if (query.includes('viewer { login }')) { + const number = Number(args.find(arg => arg.startsWith('number=')).slice('number='.length)) + const current = review() + const page = nodes => ({ pageInfo: { hasNextPage: false, endCursor: null }, nodes }) + const written = (thread, pending) => ({ + id: thread.id, isOutdated: false, isResolved: false, path: thread.path, diffSide: thread.side, startDiffSide: thread.startLine === null ? null : thread.side, + line: thread.line, startLine: thread.startLine, originalLine: thread.line, originalStartLine: thread.startLine, subjectType: 'LINE', + viewerCanReply: true, viewerCanResolve: true, viewerCanUnresolve: false, + root: { nodes: [{ diffHunk: '@@ -1,5 +1,5 @@', commit: { oid: pulls[number].headRefOid }, originalCommit: { oid: pulls[number].headRefOid } }] }, + comments: page([commentNode(thread.id + '-0', thread.body, VIEWER, pending)]), + }) + const stored = existsSync(join(here, 'threads.json')) ? JSON.parse(readFileSync(join(here, 'threads.json'), 'utf8')) : [] + const threads = [...stored, ...current.published.map(thread => written(thread, false)), + ...(current.pending?.threads ?? []).map(thread => written(thread, true))].map((thread) => { + const replies = (current.replies[thread.id] ?? []).map(reply => commentNode(reply.id, reply.body, VIEWER, reply.pending)) + const comments = [...thread.comments.nodes, ...replies].filter(comment => !current.deleted.includes(comment.id)) + .map(comment => ({ ...comment, body: current.bodies[comment.id] ?? comment.body })) + return { ...thread, isResolved: current.resolved[thread.id] ?? thread.isResolved, comments: page(comments) } + }).filter(thread => thread.comments.nodes.length > 0) + const pendingComments = threads.flatMap(thread => thread.comments.nodes).filter(comment => comment.state === 'PENDING').length + process.stdout.write(JSON.stringify({ data: { viewer: { login: VIEWER }, repository: { isArchived: false, viewerPermission: 'WRITE', + pullRequest: { id: 'pull-' + number, headRefOid: pulls[number].headRefOid, locked: false, + reviews: { nodes: current.pending === null ? [] : [{ id: current.pending.id, viewerDidAuthor: true, comments: { totalCount: pendingComments } }] }, + reviewThreads: page(threads) } } } })) + process.exit(0) + } + if (query.includes('reviews(states: PENDING')) { + const number = Number(args.find(arg => arg.startsWith('number=')).slice('number='.length)) + const pending = review().pending + // Every thread and comment the double serves belongs to the pull request it was read from. + const target = args.some(arg => arg.startsWith('target=')) ? { target: { pullRequest: { id: 'pull-' + number } } } : {} + process.stdout.write(JSON.stringify({ data: { repository: { pullRequest: { id: 'pull-' + number, headRefOid: pulls[number].headRefOid, + reviews: { nodes: pending === null ? [] : [{ id: pending.id, viewerDidAuthor: true }] } } }, ...target } })) + process.exit(0) + } if (query.includes('pullRequest(number: $number)')) { const number = Number(args.find(arg => arg.startsWith('number=')).slice('number='.length)) process.stdout.write(JSON.stringify({ data: { repository: { pullRequest: { headRefOid: pulls[number].headRefOid, baseRefOid: BASE } } } })) @@ -1021,7 +1113,10 @@ it.skipIf(MODE === 'record')('shows the local changes of the Session by scope an expect(narrowComment.x + narrowComment.width).toBeLessThanOrEqual(390) await page.setViewportSize({ width: 1680, height: 1000 }) await panelFile.getByRole('button', { name: '开始评审', exact: true }).click() - await panelFile.locator('[data-forge-review-thread="pending"]').getByText('请核对边界条件', { exact: true }).waitFor() + // The comment starts the pending review on GitHub, and the threads read again show it there. + const pendingThread = panelFile.locator('[data-forge-thread="new-1"]') + await pendingThread.getByText('请核对边界条件', { exact: true }).waitFor({ timeout: 20_000 }) + await pendingThread.getByText('待提交', { exact: true }).waitFor() await page.setViewportSize({ width: 1680, height: 500 }) const changesScroll = view.locator('[data-forge-changes-scroll]') await changesScroll.evaluate((element) => { element.scrollTop = element.scrollHeight }) @@ -1052,11 +1147,16 @@ it.skipIf(MODE === 'record')('shows the local changes of the Session by scope an await captureStableAria(page, '[role="dialog"][aria-label="提交评审"]', scaffold.workspaceCwd), MODE) await reviewDialog.getByRole('button', { name: '提交评审', exact: true }).click() await page.getByRole('alert').filter({ hasText: '已提交评审' }).waitFor() - await panelFile.locator('[data-forge-review-thread="published"]').getByText('请核对边界条件', { exact: true }).waitFor() - await compareOrRefreshGolden(join(EXPECTED, 'review-record.expected.md'), await captureStableAria(page, '[data-forge-review-thread="published"]', scaffold.workspaceCwd), MODE) - const published: unknown = JSON.parse((await readFile(join(root, 'reviews.jsonl'), 'utf8')).trim()) - expect(published).toEqual({ endpoint: 'repos/octo/demo/pulls/7/reviews', body: { commit_id: HEAD7, event: 'REQUEST_CHANGES', body: '需要补充边界检查', - comments: [{ path: 'src/panel.ts', side: 'RIGHT', line: 4, start_line: 2, start_side: 'RIGHT', body: '请核对边界条件' }] } }) + await expect.poll(() => pendingThread.getByText('待提交', { exact: true }).count(), { timeout: 20_000 }).toBe(0) + await compareOrRefreshGolden(join(EXPECTED, 'review-record.expected.md'), + await captureStableAria(page, '[data-forge-thread="new-1"]', scaffold.workspaceCwd), MODE) + const mutations = (await readFile(join(root, 'mutations.jsonl'), 'utf8')).trim().split('\n').map((line): unknown => JSON.parse(line)) + expect(mutations).toEqual([ + { field: 'addPullRequestReview', variables: { pull: 'pull-7', commit: HEAD7, + threads: [{ path: 'src/panel.ts', body: '请核对边界条件', line: 4, side: 'RIGHT', startLine: 2, startSide: 'RIGHT' }] } }, + { field: 'submitPullRequestReview', variables: { review: 'review-1', event: 'REQUEST_CHANGES', body: '需要补充边界检查' } }, + ]) + expect(existsSync(join(root, 'reviews.jsonl'))).toBe(false) await page.getByRole('button', { name: '退出全屏', exact: true }).click() await panelFile.getByRole('button', { name: '6 行未变更', exact: true }).click() await panelFile.getByText('export const n6 = 6', { exact: true }).first().waitFor({ timeout: 20_000 }) @@ -1080,7 +1180,7 @@ it.skipIf(MODE === 'record')('shows the local changes of the Session by scope an expect(await panelFile.evaluate((element, original) => element === original, originalFile)).toBe(true) await expect.poll(() => docsFile.getAttribute('data-expanded')).toBe(null) await expect.poll(() => scrollport.evaluate(element => element.scrollTop)).toBe(position) - expect(await panelFile.locator('[data-forge-review-thread="published"]').count()).toBe(1) + expect(await panelFile.locator('[data-forge-thread="new-1"]').count()).toBe(1) await page.setViewportSize({ width: 1680, height: 1000 }) await page.locator('[data-dockkit-tab]').filter({ hasText: '#7 的变更' }).locator('[data-dockkit-tab-close]').click() await expect.poll(() => view.count()).toBe(0) @@ -1719,7 +1819,7 @@ it.skipIf(MODE === 'record').each([120, 4000])('types a review comment beside %i expect(await file.getByRole('button', { name: '开始评审', exact: true }).isDisabled()).toBe(true) await input.fill('检查边界条件') await file.getByRole('button', { name: '开始评审', exact: true }).click() - await file.locator('[data-forge-review-thread="pending"]').getByText('检查边界条件', { exact: true }).waitFor() + await file.locator('[data-forge-thread]').getByText('检查边界条件', { exact: true }).waitFor({ timeout: 20_000 }) expect(tripwire.pageErrors).toEqual([]) }) @@ -1856,6 +1956,170 @@ it.skipIf(MODE === 'record')('keeps local viewed marks across reloads, clears a expect(tripwire.pageErrors).toEqual([]) }) +/** + * One review thread node of pull request 7 as the GraphQL thread read returns it, its comments by `lin`, the viewer, then + * `octo`, the pull request's author; the viewer may reply, resolve, and change their own comments. + */ +function threadNode( + id: string, fields: Record, bodies: readonly string[], commit: string = HEAD7, +): Record { + return { + id, isOutdated: false, isResolved: false, path: 'src/panel.ts', diffSide: 'RIGHT', startDiffSide: null, line: null, startLine: null, + originalLine: null, originalStartLine: null, subjectType: 'LINE', viewerCanReply: true, viewerCanResolve: true, viewerCanUnresolve: true, ...fields, + root: { nodes: [{ diffHunk: '@@ -1,5 +1,5 @@\n export const n1 = 1\n-export const n2 = 2\n+export const n2 = \'two\'', + commit: { oid: commit }, originalCommit: { oid: commit } }] }, + comments: { pageInfo: { hasNextPage: false, endCursor: null }, nodes: bodies.map((body, index) => ({ + id: `${id}-${index}`, state: 'SUBMITTED', createdAt: '2026-10-09T00:00:00Z', url: `${PULL}#discussion_${id}_${index}`, body, + viewerCanUpdate: index === 0, viewerCanDelete: index === 0, author: { __typename: 'User', login: index === 0 ? 'lin' : 'octo', avatarUrl: null }, + })) }, + } +} + +/** Threads of pull request 7: on new line 2, on old line 15, resolved on new line 15, outdated, and on the whole of `docs/panel.md`. */ +const THREADS = [ + threadNode('on-line', { line: 2, originalLine: 2 }, ['Why **two**?', 'It reads better.']), + threadNode('old-side', { diffSide: 'LEFT', line: 15, originalLine: 15 }, ['The old fifteen was a number.']), + threadNode('resolved', { isResolved: true, line: 15, originalLine: 15 }, ['Settled.']), + threadNode('outdated', { isOutdated: true, originalLine: 9 }, ['This line moved.'], 'f'.repeat(40)), + threadNode('whole-file', { path: 'docs/panel.md', subjectType: 'FILE' }, ['Add a screenshot.']), +] + +it.skipIf(MODE === 'record')('overlays the review threads of a change request and opens them from the thread list', async () => { + const { scaffold, page, root, tripwire } = await launchPanel('web-e2e-forge-review-threads', 'follow-up') + await writeFile(join(root, 'threads.json'), JSON.stringify(THREADS)) + // Comments were written two hours before the browser's clock, so their relative times stay fixed. + await page.clock.setFixedTime(Date.parse('2026-10-09T02:00:00Z')) + const { view, sessionId } = await openReview(page, scaffold) + const panel = view.locator('[data-forge-diff-file="src/panel.ts"]') + const onLine = panel.locator('[data-forge-thread="on-line"]') + await onLine.getByText('two', { exact: true }).waitFor({ timeout: 20_000 }) + // The thread follows the row of its last line, under the new side. + expect(await onLine.evaluate(card => card.previousElementSibling?.querySelector('[data-new-line]')?.textContent)).toBe('export const n2 = \'two\'') + expect(await panel.locator('[data-forge-thread="old-side"]').evaluate(card => card.previousElementSibling?.querySelector('[data-old-line]')?.textContent)) + .toBe('export const n15 = 15') + await panel.locator('[data-forge-thread="resolved"]').getByText('已解决的讨论 · lin', { exact: true }).waitFor() + await panel.locator('[data-forge-outdated-threads]').getByText('1 条讨论已过期:所在代码已被后续提交修改', { exact: true }).waitFor() + await view.locator('[data-forge-diff-file="docs/panel.md"] [data-forge-thread="whole-file"]').getByText('文件级讨论', { exact: true }).waitFor() + const count = panel.getByRole('button', { name: 'panel.ts 有 3 条未解决的讨论,跳到下一条', exact: true }) + await count.waitFor() + await view.getByRole('navigation').getByTitle('3 条未解决的讨论', { exact: true }).waitFor() + await compareOrRefreshGolden(join(EXPECTED, 'review-threads.expected.md'), + await captureStableAria(page, '[data-forge-diff-file="src/panel.ts"]', scaffold.workspaceCwd), MODE) + + // The count steps through the file's unresolved threads in display order: R2, L15, then the outdated one. + const centered = async (id: string): Promise => await panel.locator(`[data-forge-thread="${id}"]`).evaluate((card) => { + const viewport = card.closest('[data-forge-changes-scroll]')!.getBoundingClientRect() + const box = card.getBoundingClientRect() + return box.top + box.height / 2 > viewport.top && box.top + box.height / 2 < viewport.bottom + }) + for (const id of ['on-line', 'old-side', 'outdated']) { + await count.click() + await expect.poll(() => centered(id)).toBe(true) + } + expect(await view.locator('[data-forge-thread-list]').count()).toBe(0) + + await view.getByRole('button', { name: '讨论列表,共 5 个', exact: true }).click() + const list = view.getByRole('complementary', { name: '讨论列表,共 5 个' }) + await expect.poll(() => list.getByRole('radio', { checked: true }).allTextContents()).toEqual(['未解决4']) + await expect.poll(() => list.locator('[data-forge-thread-item]').evaluateAll(items => items.map(item => item.getAttribute('data-forge-thread-item')))) + .toEqual(['whole-file', 'on-line', 'old-side', 'outdated']) + await list.getByRole('radio', { name: /^已解决/ }).click() + await list.locator('[data-forge-thread-item="resolved"]').click() + // Opening a resolved thread unfolds it inside its file, and the docked list stays. + await panel.locator('[data-forge-thread="resolved"]').getByText('Settled.', { exact: true }).waitFor() + await list.getByRole('radio', { name: /^全部/ }).click() + await expect.poll(() => list.locator('[data-forge-thread-item]').count()).toBe(5) + await compareOrRefreshGolden(join(EXPECTED, 'review-thread-list.expected.md'), + await captureStableAria(page, '[data-forge-thread-list]', scaffold.workspaceCwd), MODE) + // A view narrower than 480px gives the list the files' whole width and closes it before opening a thread. + await view.evaluate((element) => { element.style.width = '420px'; element.style.flex = 'none' }) + await expect.poll(() => list.evaluate(element => [getComputedStyle(element).position, element.getBoundingClientRect().width])) + .toEqual(['absolute', 420]) + await list.locator('[data-forge-thread-item="on-line"]').click() + await list.waitFor({ state: 'detached' }) + await view.evaluate((element) => { element.style.width = ''; element.style.flex = '' }) + + await onLine.getByRole('button', { name: '添加到输入框', exact: true }).click() + await page.locator('[data-composer-input]').first().getByText('panel.ts R2', { exact: true }).first().waitFor() + const sent = scaffold.whenTurnSettled() + await page.locator('[data-composer-input]').first().press('Enter') + await sent + await page.getByText(FOLLOW_UP_REPLY, { exact: true }).waitFor() + // The quoted thread reaches the model only inside the ordinary logged user message. + const quotes = (await readPersistedEvents(scaffold, sessionId)).flatMap(event => event.type === 'user/message' + ? event.data.content.flatMap(block => block.type === 'text' && block.text.includes('## Review Thread') ? [block.text] : []) : []) + expect(quotes).toHaveLength(1) + await compareOrRefreshGolden(join(EXPECTED, 'review-thread-message.expected.md'), quotes.join('').trimEnd(), MODE) + const calls = (await readFile(join(root, 'calls.jsonl'), 'utf8')).split('\n').filter(line => line.length > 0).map(line => JSON.parse(line) as string[]) + const reads = calls.filter(args => args.some(arg => arg.startsWith('query=') && arg.includes('viewer { login }'))) + expect(reads.length).toBeGreaterThan(0) + expect(reads[0]).toEqual(expect.arrayContaining(['owner=octo', 'name=demo', 'number=7', 'first=100'])) + expect(tripwire.pageErrors).toEqual([]) +}) + +it.skipIf(MODE === 'record')('replies to, edits, deletes, and resolves review threads, and discards a pending review started from a reply', async () => { + const { scaffold, page, root, tripwire } = await launchPanel('web-e2e-forge-review-writes') + await writeFile(join(root, 'threads.json'), JSON.stringify(THREADS)) + await page.clock.setFixedTime(Date.parse('2026-10-09T02:00:00Z')) + const { view } = await openReview(page, scaffold) + const panel = view.locator('[data-forge-diff-file="src/panel.ts"]') + const onLine = panel.locator('[data-forge-thread="on-line"]') + await onLine.getByText('two', { exact: true }).waitFor({ timeout: 20_000 }) + + await onLine.getByRole('button', { name: '回复…', exact: true }).click() + await onLine.getByRole('textbox', { name: '回复…', exact: true }).fill('已改为字符串') + await compareOrRefreshGolden(join(EXPECTED, 'review-thread-reply.expected.md'), + await captureStableAria(page, '[data-forge-thread="on-line"]', scaffold.workspaceCwd), MODE) + await onLine.getByRole('button', { name: '回复', exact: true }).click() + await onLine.getByText('已改为字符串', { exact: true }).waitFor({ timeout: 20_000 }) + + await onLine.getByRole('button', { name: 'lin 的评论操作', exact: true }).first().click() + await page.getByRole('menuitem', { name: '编辑', exact: true }).click() + await onLine.getByRole('textbox', { name: '编辑评论', exact: true }).fill('Why a **word**?') + await onLine.getByRole('button', { name: '保存', exact: true }).click() + await onLine.getByText('word', { exact: true }).waitFor({ timeout: 20_000 }) + + await onLine.getByRole('button', { name: 'lin 的评论操作', exact: true }).last().click() + await page.getByRole('menuitem', { name: '删除', exact: true }).click() + await onLine.getByRole('group', { name: '删除这条评论?', exact: true }).getByRole('button', { name: '删除', exact: true }).click() + await expect.poll(() => onLine.getByText('已改为字符串', { exact: true }).count(), { timeout: 20_000 }).toBe(0) + + await onLine.getByRole('button', { name: '解决讨论', exact: true }).click() + await onLine.getByText('已解决的讨论 · lin', { exact: true }).waitFor({ timeout: 20_000 }) + + const oldSide = panel.locator('[data-forge-thread="old-side"]') + await oldSide.getByRole('button', { name: '回复…', exact: true }).click() + await oldSide.getByRole('textbox', { name: '回复…', exact: true }).fill('稍后一起提交') + await oldSide.getByRole('button', { name: '回复选项', exact: true }).click() + await page.getByRole('menuitem', { name: '开始评审', exact: true }).click() + await oldSide.getByText('待提交', { exact: true }).waitFor({ timeout: 20_000 }) + await view.getByRole('button', { name: '提交评审 (1)', exact: true }).click() + const dialog = page.getByRole('dialog', { name: '提交评审', exact: true }) + await dialog.getByRole('button', { name: '丢弃评审', exact: true }).click() + await compareOrRefreshGolden(join(EXPECTED, 'discard-review.expected.md'), + await captureStableAria(page, '[role="dialog"][aria-label="提交评审"]', scaffold.workspaceCwd), MODE) + await dialog.getByRole('group', { name: '丢弃评审', exact: true }).getByRole('button', { name: '丢弃评审', exact: true }).click() + await page.getByRole('alert').filter({ hasText: '已丢弃评审' }).waitFor() + await expect.poll(() => oldSide.getByText('稍后一起提交', { exact: true }).count(), { timeout: 20_000 }).toBe(0) + await view.getByRole('button', { name: '提交评审', exact: true }).waitFor() + + const mutations = (await readFile(join(root, 'mutations.jsonl'), 'utf8')).trim().split('\n').map((line): unknown => JSON.parse(line)) + expect(mutations).toEqual([ + { field: 'addPullRequestReviewThreadReply', variables: { thread: 'on-line', body: '已改为字符串', review: null } }, + { field: 'updatePullRequestReviewComment', variables: { comment: 'on-line-0', body: 'Why a **word**?' } }, + { field: 'deletePullRequestReviewComment', variables: { comment: 'on-line-reply-0' } }, + { field: 'resolveReviewThread', variables: { thread: 'on-line' } }, + { field: 'addPullRequestReview', variables: { pull: 'pull-7', commit: HEAD7, threads: null } }, + { field: 'addPullRequestReviewThreadReply', variables: { thread: 'old-side', body: '稍后一起提交', review: 'review-1' } }, + { field: 'deletePullRequestReview', variables: { review: 'review-1' } }, + ]) + // Every write checked the head of pull request 7 first. + const calls = (await readFile(join(root, 'calls.jsonl'), 'utf8')).split('\n').filter(line => line.length > 0).map(line => JSON.parse(line) as string[]) + expect(calls.filter(args => args.some(arg => arg.startsWith('query=') && arg.includes('reviews(states: PENDING') && !arg.includes('viewer { login }')))) + .toHaveLength(mutations.length - 1) + expect(tripwire.pageErrors).toEqual([]) +}) + it.skipIf(MODE === 'record')('keeps a narrow file header\'s viewed mark and menu inside its card and its name under the pointer', async () => { const { scaffold, page, project, tripwire } = await launchPanel('web-e2e-forge-narrow-header', 'normal', { branch: 'feat' }) const from = 'src/original-review-module-with-a-long-name.ts' diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 19b1bb2f25..8ff3224180 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -1121,6 +1121,13 @@ export interface Config { * `testPaths` and before the built-in rules. */ interfacePaths?: string[] + /** Most UTF-8 bytes, as JSON, of change request review threads kept in memory for later reads at the same head commit and update time. */ + maxCachedReviewBytes?: number + /** + * Age in milliseconds at which review threads kept in memory are read from the code host again; a GitHub pull + * request's update time does not change when a thread is resolved. + */ + reviewRefreshMs?: number } ``` @@ -1156,7 +1163,7 @@ export interface Config { - `inject`: `computerUse` · `tools` · `systemPrompt` · `subprocess` · `agents` - `refs`: [`CuaConfig`](../packages/experimental/cua/src/index.ts) -- `source`: [`packages/experimental/cua-macos/src/index.ts:33`](../packages/experimental/cua-macos/src/index.ts) +- `source`: [`packages/experimental/cua-macos/src/index.ts:34`](../packages/experimental/cua-macos/src/index.ts) ```ts config-catalog /** Native preparation, source-build signing, operation bounds, and profile-local application grants. */ @@ -1186,7 +1193,7 @@ export type SourceSigning = 'ad-hoc' | { ## `@deepseek-ai/dsh-experimental-forge` -- `source`: [`packages/experimental/forge/src/types.ts:279`](../packages/experimental/forge/src/types.ts) +- `source`: [`packages/experimental/forge/src/types.ts:432`](../packages/experimental/forge/src/types.ts) ```ts config-catalog /** Poll cadence and fetch deadline for watched change requests. */ @@ -1220,9 +1227,12 @@ export interface Config { hosts?: string[] /** Deadline in milliseconds for one `gh` invocation. */ timeoutMs?: number - /** Maximum captured bytes per `gh` output stream and combined JSON bytes of one complete check read. */ + /** Maximum captured bytes per `gh` output stream and combined JSON bytes of one complete check read or review read. */ maxOutputBytes?: number - /** Most review threads counted per pull request in one status read; a pull request with more reports a lower bound. */ + /** + * Most review threads counted per pull request in one status read, which reports a lower bound past it, and read in + * one review read, which reports itself truncated past it. + */ maxReviewThreads?: number /** Most commits one pull request commit listing returns; GitHub lists at most 250 commits of a pull request. */ maxCommits?: number diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index 833ddbce39..704d37d959 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -1123,6 +1123,13 @@ export interface Config { * `testPaths` and before the built-in rules. */ interfacePaths?: string[] + /** Most UTF-8 bytes, as JSON, of change request review threads kept in memory for later reads at the same head commit and update time. */ + maxCachedReviewBytes?: number + /** + * Age in milliseconds at which review threads kept in memory are read from the code host again; a GitHub pull + * request's update time does not change when a thread is resolved. + */ + reviewRefreshMs?: number } ``` @@ -1158,7 +1165,7 @@ export interface Config { - `inject`: `computerUse` · `tools` · `systemPrompt` · `subprocess` · `agents` - `refs`: [`CuaConfig`](../packages/experimental/cua/src/index.ts) -- `source`: [`packages/experimental/cua-macos/src/index.ts:33`](../packages/experimental/cua-macos/src/index.ts) +- `source`: [`packages/experimental/cua-macos/src/index.ts:34`](../packages/experimental/cua-macos/src/index.ts) ```ts config-catalog /** Native preparation, source-build signing, operation bounds, and profile-local application grants. */ @@ -1188,7 +1195,7 @@ export type SourceSigning = 'ad-hoc' | { ## `@deepseek-ai/dsh-experimental-forge` -- `source`: [`packages/experimental/forge/src/types.ts:279`](../packages/experimental/forge/src/types.ts) +- `source`: [`packages/experimental/forge/src/types.ts:432`](../packages/experimental/forge/src/types.ts) ```ts config-catalog /** Poll cadence and fetch deadline for watched change requests. */ @@ -1222,9 +1229,12 @@ export interface Config { hosts?: string[] /** Deadline in milliseconds for one `gh` invocation. */ timeoutMs?: number - /** Maximum captured bytes per `gh` output stream and combined JSON bytes of one complete check read. */ + /** Maximum captured bytes per `gh` output stream and combined JSON bytes of one complete check read or review read. */ maxOutputBytes?: number - /** Most review threads counted per pull request in one status read; a pull request with more reports a lower bound. */ + /** + * Most review threads counted per pull request in one status read, which reports a lower bound past it, and read in + * one review read, which reports itself truncated past it. + */ maxReviewThreads?: number /** Most commits one pull request commit listing returns; GitHub lists at most 250 commits of a pull request. */ maxCommits?: number diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index cb4129be82..cdc25843df 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -47,7 +47,7 @@ Application listeners are outside this package matrix. Desktop Host subscribes t | `deepseek-account/signed-out` | `emit` | [`packages/credentials/deepseek-account/src/index.ts:29`](../packages/credentials/deepseek-account/src/index.ts) | [`deepseek-account`](../packages/credentials/deepseek-account) (`emit`) | [`deepseek-account`](../packages/credentials/deepseek-account) | | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `workspace-controller` | | `feedback/committed` | `parallel` | [`packages/feedback/message-feedback/src/index.ts:58`](../packages/feedback/message-feedback/src/index.ts) | [`message-feedback`](../packages/feedback/message-feedback) (`parallel`) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | -| `forge/providers-changed` | `parallel` | [`packages/experimental/forge/src/index.ts:27`](../packages/experimental/forge/src/index.ts) | `forge` (`parallel`) | `forge-session` | +| `forge/providers-changed` | `parallel` | [`packages/experimental/forge/src/index.ts:28`](../packages/experimental/forge/src/index.ts) | `forge` (`parallel`) | `forge-session` | | `fs/delete-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:83`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`workspace-changes`](../packages/deliverables/workspace-changes) | | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:75`](../packages/fs/fs/src/index.ts) | `liveshare` (`waterfall`), [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`workspace-changes`](../packages/deliverables/workspace-changes) | | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:93`](../packages/fs/fs/src/index.ts) | `liveshare` (`emit`), [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem), `workspace-files` | diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md index f367889fa4..73677d93b1 100644 --- a/docs/event-producer-consumer.zh.md +++ b/docs/event-producer-consumer.zh.md @@ -49,7 +49,7 @@ | `deepseek-account/signed-out` | `emit` | [`packages/credentials/deepseek-account/src/index.ts:29`](../packages/credentials/deepseek-account/src/index.ts) | [`deepseek-account`](../packages/credentials/deepseek-account) (`emit`) | [`deepseek-account`](../packages/credentials/deepseek-account) | | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `workspace-controller` | | `feedback/committed` | `parallel` | [`packages/feedback/message-feedback/src/index.ts:58`](../packages/feedback/message-feedback/src/index.ts) | [`message-feedback`](../packages/feedback/message-feedback) (`parallel`) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | -| `forge/providers-changed` | `parallel` | [`packages/experimental/forge/src/index.ts:27`](../packages/experimental/forge/src/index.ts) | `forge` (`parallel`) | `forge-session` | +| `forge/providers-changed` | `parallel` | [`packages/experimental/forge/src/index.ts:28`](../packages/experimental/forge/src/index.ts) | `forge` (`parallel`) | `forge-session` | | `fs/delete-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:83`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`workspace-changes`](../packages/deliverables/workspace-changes) | | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:75`](../packages/fs/fs/src/index.ts) | `liveshare` (`waterfall`), [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`workspace-changes`](../packages/deliverables/workspace-changes) | | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:93`](../packages/fs/fs/src/index.ts) | `liveshare` (`emit`), [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem), `workspace-files` | diff --git a/docs/subsystems/forge.i18n.yaml b/docs/subsystems/forge.i18n.yaml index 97ebf7bece..408ac912e6 100644 --- a/docs/subsystems/forge.i18n.yaml +++ b/docs/subsystems/forge.i18n.yaml @@ -12,11 +12,14 @@ en: 26ccfa2e342e3e67 zh: fe6cc2a622757c48 /forges/change-request-actions: - en: 87d2c81d9514267f - zh: 1daf31c5b0127a1c + en: ae735fbdbdf2d870 + zh: 9903fcc571104ad8 +/forges/review-threads: + en: af729af6e59e915f + zh: 62ddae4cfcd4431f /forges/session-bindings: en: 13dfd36f2166bba0 zh: a369434f52f04d57 /forges/panel: - en: e52a5c57abc4d30e - zh: 509a40f421cc3d33 + en: 4020149c26661a2d + zh: 56842b057d4f662e diff --git a/docs/subsystems/forge.md b/docs/subsystems/forge.md index 208c6a5d9f..3fc9cde00c 100644 --- a/docs/subsystems/forge.md +++ b/docs/subsystems/forge.md @@ -47,6 +47,18 @@ interface ForgeProvider { readonly forge: string /** Publish a comment or completed review. Omission declares that this provider cannot write reviews. */ submitReview?(ref: ChangeRequestRef, request: ForgeReviewRequest, signal: AbortSignal): Promise + /** + * Read the review threads of a change request at head commit `headSha`. The threads are returned only when the + * read names `headSha` as the head; once the head is another commit, the read resolves to a `stale` failure. + * Omission declares that this provider cannot read reviews. + */ + readReview?(ref: ChangeRequestRef, headSha: string, signal: AbortSignal): Promise + /** + * Write to the review threads or the pending review of a change request while its head is `write.headSha`; once the + * head is another commit, the write resolves to `stale` without writing. A write is never retried. Omission declares + * that this provider cannot write reviews, and its `readReview` then reports no viewer permission. + */ + writeReview?(ref: ChangeRequestRef, write: ForgeReviewWrite, signal: AbortSignal): Promise /** Map a Git remote URL to its repository, or undefined when this provider does not serve it. */ repositoryFromRemote(url: string): ForgeRepository | undefined /** Map a change request web URL to its reference, or undefined when this provider does not serve it. */ @@ -244,9 +256,9 @@ interface ForgeFailure { * `not-found`: the host does not expose it; `unauthenticated`: credentials are missing or rejected; * `too-large`: the host or the provider refuses an answer over its size limit, so reading again fails * the same way; `stale`: the head is no longer the commit the read named, so reading again at the head of - * a later status can succeed; `unavailable`: any other failure. + * a later status can succeed; `unsupported`: the provider does not offer the read; `unavailable`: any other failure. */ - readonly code: 'not-found' | 'unauthenticated' | 'too-large' | 'stale' | 'unavailable' + readonly code: 'not-found' | 'unauthenticated' | 'too-large' | 'stale' | 'unsupported' | 'unavailable' /** Human-readable cause. */ readonly message: string } @@ -303,7 +315,7 @@ interface ForgeActionFailure { } ``` -`ctx.forge.submitReview` delegates an explicit comment or completed review to the provider. A provider that omits this capability returns unsupported. Consumers retain pending drafts and reconcile unknown write outcomes before resubmitting. +`ctx.forge.submitReview` delegates an explicit comment or completed review to the provider. A provider that omits this capability returns unsupported. Consumers reconcile unknown write outcomes before resubmitting; comments kept for a later review go to the code host's pending review through `ctx.forge.writeReview`. ```ts type-equiv /** One inline comment addressed to the old or new side of a pull request diff. */ @@ -323,17 +335,188 @@ type ForgeReviewRequest = { readonly headSha: string } & ( | { readonly kind: 'comment'; readonly comment: ForgeLineComment } - | { readonly kind: 'review'; readonly event: 'comment' | 'approve' | 'request-changes'; readonly body: string; readonly comments: readonly ForgeLineComment[] } + | { readonly kind: 'review'; readonly event: ForgeReviewEvent; readonly body: string; readonly comments: readonly ForgeLineComment[] } ) ``` ```ts type-equiv -/** Result of a review write; unknown outcomes must be checked on the host before another submission. */ +/** Result of a review submission; unknown outcomes must be checked on the host before another submission. */ type ForgeReviewResult = | { readonly ok: true; readonly url: string } | { readonly ok: false; readonly code: 'unsupported' | 'stale' | 'failed' | 'unknown'; readonly message: string } ``` +## Review threads + +`ctx.forge.readReview(ref, headSha, signal)` reads the review threads of a change request at one head commit. The provider returns `ForgeReviewData` only when the read names `headSha` as the head; otherwise it returns `stale`, which polls a watched change request again at once, as a stale diff read does. For a provider without `readReview` the service returns `unsupported`, so consumers show no threads instead of a failure. A line thread has two positions: `original` on the commit it was written on, and `current` on the head of the read, which is null once the host no longer places the thread on that commit. A consumer that shows the head's diff places a thread at `current` and shows the others with their `diffHunk`; reading the file at `original.commit` through `fileText` shows the whole file the thread was written on. The [GitHub provider README](../../packages/experimental/forge-github/README.md#use-this-package) owns how GitHub's fields map onto these positions. + +```ts type-equiv +/** Opaque host identity of one review thread. */ +type ForgeThreadId = Branded<'ForgeThreadId'> +``` + +```ts type-equiv +/** Opaque host identity of one review comment. */ +type ForgeCommentId = Branded<'ForgeCommentId'> +``` + +```ts type-equiv +/** Consecutive lines on one side of a diff whose new side is one commit. */ +interface ForgeAnchor { + /** + * Full object name of the commit the diff's new side shows: new-side (`R`) lines number this commit's file, and + * old-side (`L`) lines number the file at the diff's base. + */ + readonly commit: string + /** First line, inclusive. */ + readonly startLine: number + /** Last line, inclusive. */ + readonly endLine: number +} +``` + +```ts type-equiv +/** Account that wrote a review comment. */ +interface ForgeCommentAuthor { + /** Login as the host spells it. */ + readonly login: string + /** Avatar image URL, or null when the host reports none. */ + readonly avatarUrl: string | null + /** Whether the account is an app or bot rather than a person. */ + readonly bot: boolean +} +``` + +```ts type-equiv +/** One comment of a review thread. */ +interface ForgeReviewComment { + /** Host identity of the comment. */ + readonly id: ForgeCommentId + /** Author, or null when the account no longer exists. */ + readonly author: ForgeCommentAuthor | null + /** Markdown source as the author wrote it; it may contain raw HTML, which readers must not render as HTML. */ + readonly body: string + /** ISO 8601 time the comment was created. */ + readonly createdAt: string + /** Whether the comment belongs to the signed-in user's review that is not submitted yet, which only that user sees. */ + readonly pending: boolean + /** Web page of the comment, or null when the host reports none. */ + readonly url: string | null + /** Whether the signed-in user can replace the comment's text through `writeReview`; false for a provider without it. */ + readonly viewerCanEdit: boolean + /** Whether the signed-in user can delete the comment through `writeReview`; false for a provider without it. */ + readonly viewerCanDelete: boolean +} +``` + +```ts type-equiv +/** + * One review thread on a file of a change request. A line thread has two positions: `original` on the commit it was + * written on, and `current` on the head commit of the read. `current` is null once the host no longer places the + * thread on the head commit, as after later commits changed its lines. + */ +interface ForgeReviewThread { + /** Host identity of the thread. */ + readonly id: ForgeThreadId + /** Repository-relative path the thread is on. */ + readonly path: string + /** Old (`L`) or new (`R`) side of the diff the lines number. */ + readonly side: 'L' | 'R' + /** Whether the thread is on lines or on the whole file. */ + readonly subject: 'line' | 'file' + /** Lines in the diff that ends at the head commit of the read, whose `commit` is that head; null for an outdated or file thread. */ + readonly current: ForgeAnchor | null + /** Lines in the diff that ended at the commit the thread was written on; null for a file thread. */ + readonly original: ForgeAnchor | null + /** Diff hunk the host recorded when the thread was written, ending at its last line; null when it recorded none. */ + readonly diffHunk: string | null + /** Whether the thread is marked resolved. */ + readonly resolved: boolean + /** Whether the signed-in user can reply to the thread through `writeReview`; false for a provider without it. */ + readonly viewerCanReply: boolean + /** + * Whether the signed-in user can mark the thread resolved, or unresolved when `resolved`, through `writeReview`; false + * for a provider without it. + */ + readonly viewerCanResolve: boolean + /** Comments oldest first; the first starts the thread. */ + readonly comments: readonly ForgeReviewComment[] +} +``` + +```ts type-equiv +/** Review threads of a change request read at one head commit. */ +interface ForgeReviewData { + /** Head commit the threads were read at; `current` positions number its files. */ + readonly headSha: string + /** Login of the signed-in user the provider read as, or null when the host does not name one. */ + readonly viewer: string | null + /** Threads in host order, at most the provider's limit. */ + readonly threads: readonly ForgeReviewThread[] + /** Whether the change request has more threads than `threads` holds. */ + readonly truncated: boolean + /** The signed-in user's pending review, or null without one. */ + readonly pendingReview: ForgePendingReview | null + /** + * Whether the signed-in user can add comments to a pending review and submit or discard it through `writeReview`; + * false for a provider without it. + */ + readonly viewerCanReview: boolean +} +``` + +`ctx.forge.writeReview(ref, write, signal)` writes to the review threads and the signed-in user's pending review: a reply, at once or with `pending` inside the pending review; resolving or unresolving a thread; editing or deleting a comment; a line comment at the head added to the pending review; and submitting or discarding the pending review. A pending reply or comment starts a pending review when the user has none. Every write carries the head commit the user saw; the provider checks it first and returns `stale` without writing once the head moved, which polls a watched change request as a stale read does, and the service polls a watched change request at once after any other result. Writes are never retried, and an `unknown` result must be checked on the host before the write is tried again. For a provider without `writeReview` the service returns `unsupported`. `ForgeReviewData` carries the pending review and the user's permissions for each thread, comment, and the pending review, which a provider without `writeReview` reports as absent, so consumers offer only the writes that can succeed. The [GitHub provider README](../../packages/experimental/forge-github/README.md#use-this-package) owns the GraphQL mutations and how their outcomes map onto these results. + +```ts type-equiv +/** Opaque host identity of one review. */ +type ForgeReviewId = Branded<'ForgeReviewId'> +``` + +```ts type-equiv +/** The signed-in user's review of a change request that is not submitted yet, which only that user sees. */ +interface ForgePendingReview { + /** Host identity of the review. */ + readonly id: ForgeReviewId + /** Comments the review holds. */ + readonly comments: number +} +``` + +```ts type-equiv +/** Decision a submitted review records. */ +type ForgeReviewEvent = 'comment' | 'approve' | 'request-changes' +``` + +```ts type-equiv +/** + * One write to the review threads and the pending review of a change request. `pending` replies and `add-pending` + * comments join the signed-in user's pending review, which is started when the user has none. A host that adds every + * reply to an existing pending review, as GitHub does, refuses a reply with `pending: false` while one exists. + */ +type ForgeReviewWrite = { + /** Head commit the user saw; providers check it before writing and refuse with `stale` once the head is another commit. */ + readonly headSha: string +} & ( + | { readonly kind: 'reply'; readonly thread: ForgeThreadId; readonly body: string; readonly pending: boolean } + | { readonly kind: 'resolve'; readonly thread: ForgeThreadId; readonly resolved: boolean } + | { readonly kind: 'edit-comment'; readonly comment: ForgeCommentId; readonly body: string } + /** Deleting the only comment of a thread deletes the thread. */ + | { readonly kind: 'delete-comment'; readonly comment: ForgeCommentId } + /** A comment on lines of `headSha`. */ + | { readonly kind: 'add-pending'; readonly comment: ForgeLineComment } + | { readonly kind: 'submit-pending'; readonly review: ForgeReviewId; readonly event: ForgeReviewEvent; readonly body: string } + /** Delete the pending review with every comment it holds. */ + | { readonly kind: 'discard-pending'; readonly review: ForgeReviewId } +) +``` + +```ts type-equiv +/** Result of a review write; an `unknown` outcome must be checked on the host before the write is tried again. */ +type ForgeReviewWriteResult = + | { readonly ok: true } + | { readonly ok: false; readonly code: 'unsupported' | 'stale' | 'failed' | 'unknown'; readonly message: string } +``` + ## Session bindings `ctx.forgeSession` derives each Session's bindings from its own log: `gh pr create` results bind the URLs they print, `gh pr view`, `gh pr edit`, and `gh pr checkout` calls bind the change request they act on, and `git push` results trigger head-branch discovery through `ctx.forge`; the panel also reports the branch its checkout tracks for the same discovery. Track, dismiss, and discovery actions are `plugin:forge-session/binding` records, which stay outside the model-visible conversation. The `forgeChangeRequests` projection's client view, which the Session summary carries, lists the bindings without their status. The [Session binding README](../../packages/experimental/forge-session/README.md#use-this-package) owns the recognition and discovery rules. @@ -623,6 +806,10 @@ type ForgeChangeRequestStatesFrame = The changes view reads through the same Remote. `localDiff` reads one `ForgeLocalScope` of the Session's checkout, and `changeRequestDiff` reads a bound change request at the head of its latest status through the provider's `diff`, which returns a patch only for that head commit, or the `ForgeCommitRange` it names through the provider's `compare`; both return files that the Host parsed into `ForgeDiffFile` hunks, each with its review layer and change digest. `localCommits` and `changeRequestCommits` list the commits a range can name, the latter as null when the provider does not read commits. `localText` and `changeRequestText` read the new side of one file, which supplies the unchanged lines between hunks. Each inspection also sizes the `branch` scope as `ForgePanelState.local` for the panel's local changes card, always against the automatic fork point. A `branch` scope whose `base` names a ref compares with the merge base of HEAD and that branch instead; `diffBases` lists the branches the view offers, with the automatic fork point. When the head moved past the latest status, the provider returns `stale` and `ctx.forge.diff` polls the change request at once, once per head commit; `changeRequestDiff` rejects with `forgePanel/stale-head` and caches nothing, and the changes view keeps loading until a later status arrives, then reads again at that status's head. Review comments therefore always address the commit whose lines the view shows. +`changeRequestReview(session, url, headSha, fresh)` reads the threads of a bound change request at the head of the diff the view shows and refuses another head with `forgePanel/stale-head`, `forgePanel/review-unsupported` for a provider without review reads, and `forgePanel/review-failed` otherwise. It keeps one read per change request in memory, keyed by head commit and the status's update time and bounded by `maxCachedReviewBytes`, and reads again once the kept read is `reviewRefreshMs` old or when `fresh` asks for it, as the first read after the reader refreshes the view does: on GitHub a new comment or reply changes a pull request's update time, but resolving a thread does not. The changes view asks again at every status it receives while visible, and overlays the threads on the files the [panel README](../../packages/experimental/client-ui-forge/README.md#use-this-package) describes. + +`changeRequestReviewWrite(session, url, write)` passes one `ForgeReviewWrite` for a bound change request to `ctx.forge.writeReview` after checking its head commit, ids, text, and line range, and returns the `ForgeReviewWriteResult`. Once the provider answers, whatever the answer, it drops the kept threads of that change request and every read that started before, so the next `changeRequestReview` reads the host; `submitReview` drops them as well. The changes view sends one write at a time and reads the threads again after each write that may have changed them. + ```ts type-equiv /** * Consecutive commits a changes view shows instead of its whole comparison, named by full object names in the order @@ -923,6 +1110,30 @@ async fetchChecks(ref: ChangeRequestRef, signal: AbortSignal): Promise +/** + * Read the review threads of a change request at one head commit. A + * `stale` failure polls a watched change request again as {@link ForgeService.diff} does. + * @param ref - change request served by a registered provider. + * @param headSha - head commit the threads must be read at, usually the head of the displayed diff. + * @param signal - cancellation of the read. + * @returns the threads read at `headSha`, or why the host did not provide them; `unsupported` when the provider cannot read reviews. + * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts. + */ +async readReview(ref: ChangeRequestRef, headSha: string, signal: AbortSignal): Promise + +/** + * Write to the review threads or the pending review of a change request while its head is still `write.headSha`, then + * poll the change request at once when it is watched, unless the provider cannot write reviews. A `stale` result polls + * it as a stale read does. + * @param ref - change request served by a registered provider. + * @param write - the write and the head commit the user saw. + * @param signal - cancellation of the write. + * @returns whether the host took the write; `unsupported` when the provider cannot write reviews, and `unknown` when the + * outcome must be checked on the host before the write is tried again. + * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts. + */ +async writeReview(ref: ChangeRequestRef, write: ForgeReviewWrite, signal: AbortSignal): Promise + /** * List the commits of a change request at its current head. * @param ref - change request served by a registered provider. @@ -1194,7 +1405,28 @@ Serves the forge panel. Following a Session inspects the checkout of its current @Remote async changeRequestText(session: Session, url: string, commit: string, path: string, signal: AbortSignal): Promise /** - * Publish a line comment or completed review for a visible Session binding. + * Read the review threads of a change request of a Session at the head commit of its displayed diff. Threads read + * at the same head commit and update time are reused from memory, for any Session, until they are + * `reviewRefreshMs` old, `maxCachedReviewBytes` evicts them, or a review write through this panel drops them; a read + * again after that age, or a `fresh` read, shows threads resolved elsewhere since, which do not change a GitHub pull + * request's update time. + * @param session - Session the change request is bound to. + * @param url - binding URL of the change request. + * @param headSha - head commit of the displayed diff. + * @param fresh - whether to read from the host even when threads at this head and update time are kept, as after the + * reader refreshes the view; the result replaces the kept threads. + * @param signal - request cancellation. + * @returns the threads at `headSha`, with `current` positions numbering the files of that diff. + * @throws `forgePanel/not-bound` unless the URL is a visible binding of the Session that a provider serves; + * `forgePanel/stale-head` when the latest status or the host names another head, which a host answer polls again; + * `forgePanel/review-unsupported` when the provider cannot read reviews; `forgePanel/review-failed` before the + * status was read and when the host does not provide the threads otherwise. + */ +@Remote async changeRequestReview(session: Session, url: string, headSha: string, fresh: boolean, signal: AbortSignal): Promise + +/** + * Publish a line comment or completed review for a visible Session binding. The threads kept for the change request + * are dropped once the host answers, so the next read shows the comments. * @param session - Session retaining the change request. * @param url - visible binding URL. * @param request - reviewed head, ranges, plain text, and explicit review decision. @@ -1203,6 +1435,21 @@ Serves the forge panel. Following a Session inspects the checkout of its current */ @Remote async submitReview(session: Session, url: string, request: ForgeReviewRequest, signal: AbortSignal): Promise +/** + * Write to the review threads or the pending review of a change request of a Session while its head is still the + * head the user saw. The threads kept for the change request are dropped once the host answers, so the next read + * shows the write, which a resolve does not show through a GitHub pull request's update time. + * @param session - Session the change request is bound to. + * @param url - binding URL of the change request. + * @param write - the write and the head commit of the threads the user saw. + * @param signal - request cancellation. + * @returns whether the host took the write; `stale` once the head moved, which polls the change request again, and + * `unknown` when the outcome must be checked on the host before the write is tried again. + * @throws `forgePanel/not-bound` unless the URL is a visible binding of the Session that a provider serves; an error + * for a write without text, a head that is not a commit object name, or an invalid line range. + */ +@Remote async changeRequestReviewWrite( session: Session, url: string, write: ForgeReviewWrite, signal: AbortSignal, ): Promise + /** * Mark a draft change request of a Session ready for review; the change * request is polled again once the host answers. diff --git a/docs/subsystems/forge.zh.md b/docs/subsystems/forge.zh.md index 0d6fba5c35..d127005c08 100644 --- a/docs/subsystems/forge.zh.md +++ b/docs/subsystems/forge.zh.md @@ -47,6 +47,18 @@ interface ForgeProvider { readonly forge: string /** Publish a comment or completed review. Omission declares that this provider cannot write reviews. */ submitReview?(ref: ChangeRequestRef, request: ForgeReviewRequest, signal: AbortSignal): Promise + /** + * Read the review threads of a change request at head commit `headSha`. The threads are returned only when the + * read names `headSha` as the head; once the head is another commit, the read resolves to a `stale` failure. + * Omission declares that this provider cannot read reviews. + */ + readReview?(ref: ChangeRequestRef, headSha: string, signal: AbortSignal): Promise + /** + * Write to the review threads or the pending review of a change request while its head is `write.headSha`; once the + * head is another commit, the write resolves to `stale` without writing. A write is never retried. Omission declares + * that this provider cannot write reviews, and its `readReview` then reports no viewer permission. + */ + writeReview?(ref: ChangeRequestRef, write: ForgeReviewWrite, signal: AbortSignal): Promise /** Map a Git remote URL to its repository, or undefined when this provider does not serve it. */ repositoryFromRemote(url: string): ForgeRepository | undefined /** Map a change request web URL to its reference, or undefined when this provider does not serve it. */ @@ -244,9 +256,9 @@ interface ForgeFailure { * `not-found`: the host does not expose it; `unauthenticated`: credentials are missing or rejected; * `too-large`: the host or the provider refuses an answer over its size limit, so reading again fails * the same way; `stale`: the head is no longer the commit the read named, so reading again at the head of - * a later status can succeed; `unavailable`: any other failure. + * a later status can succeed; `unsupported`: the provider does not offer the read; `unavailable`: any other failure. */ - readonly code: 'not-found' | 'unauthenticated' | 'too-large' | 'stale' | 'unavailable' + readonly code: 'not-found' | 'unauthenticated' | 'too-large' | 'stale' | 'unsupported' | 'unavailable' /** Human-readable cause. */ readonly message: string } @@ -303,7 +315,7 @@ interface ForgeActionFailure { } ``` -`ctx.forge.submitReview` 将明确指定的评论或完整评审交给 provider;未实现此能力的 provider 返回不支持。消费者保存待提交草稿,并在再次提交前核对结果不明的写操作。 +`ctx.forge.submitReview` 将明确指定的评论或完整评审交给 provider;未实现此能力的 provider 返回不支持。消费者在再次提交前核对结果不明的写操作;留待之后一起提交的评论通过 `ctx.forge.writeReview` 写入代码托管平台的待提交评审。 ```ts type-equiv /** One inline comment addressed to the old or new side of a pull request diff. */ @@ -323,17 +335,188 @@ type ForgeReviewRequest = { readonly headSha: string } & ( | { readonly kind: 'comment'; readonly comment: ForgeLineComment } - | { readonly kind: 'review'; readonly event: 'comment' | 'approve' | 'request-changes'; readonly body: string; readonly comments: readonly ForgeLineComment[] } + | { readonly kind: 'review'; readonly event: ForgeReviewEvent; readonly body: string; readonly comments: readonly ForgeLineComment[] } ) ``` ```ts type-equiv -/** Result of a review write; unknown outcomes must be checked on the host before another submission. */ +/** Result of a review submission; unknown outcomes must be checked on the host before another submission. */ type ForgeReviewResult = | { readonly ok: true; readonly url: string } | { readonly ok: false; readonly code: 'unsupported' | 'stale' | 'failed' | 'unknown'; readonly message: string } ``` +## 评审讨论 + +`ctx.forge.readReview(ref, headSha, signal)` 读取变更请求在某个 head 提交处的评审讨论。只有当读取时的 head 就是 `headSha` 时,提供方才返回 `ForgeReviewData`;否则返回 `stale`,并像 diff 读取遇到 `stale` 时一样,立即重新轮询被关注的变更请求。提供方没有实现 `readReview` 时,服务返回 `unsupported`,使用方据此不显示讨论,也不报错。行级讨论有两套位置:`original` 是写下讨论时所在提交上的行,`current` 是本次读取的 head 上的行;托管平台不再把讨论放在该提交上时,`current` 为 null。显示 head diff 的使用方把讨论放在 `current` 位置,其余讨论用 `diffHunk` 展示;用 `fileText` 读取 `original.commit` 上的文件,可以看到写下讨论时的完整文件。GitHub 各字段如何映射到这两套位置,由 [GitHub 提供方 README](../../packages/experimental/forge-github/README.zh.md#use-this-package) 说明。 + +```ts type-equiv +/** Opaque host identity of one review thread. */ +type ForgeThreadId = Branded<'ForgeThreadId'> +``` + +```ts type-equiv +/** Opaque host identity of one review comment. */ +type ForgeCommentId = Branded<'ForgeCommentId'> +``` + +```ts type-equiv +/** Consecutive lines on one side of a diff whose new side is one commit. */ +interface ForgeAnchor { + /** + * Full object name of the commit the diff's new side shows: new-side (`R`) lines number this commit's file, and + * old-side (`L`) lines number the file at the diff's base. + */ + readonly commit: string + /** First line, inclusive. */ + readonly startLine: number + /** Last line, inclusive. */ + readonly endLine: number +} +``` + +```ts type-equiv +/** Account that wrote a review comment. */ +interface ForgeCommentAuthor { + /** Login as the host spells it. */ + readonly login: string + /** Avatar image URL, or null when the host reports none. */ + readonly avatarUrl: string | null + /** Whether the account is an app or bot rather than a person. */ + readonly bot: boolean +} +``` + +```ts type-equiv +/** One comment of a review thread. */ +interface ForgeReviewComment { + /** Host identity of the comment. */ + readonly id: ForgeCommentId + /** Author, or null when the account no longer exists. */ + readonly author: ForgeCommentAuthor | null + /** Markdown source as the author wrote it; it may contain raw HTML, which readers must not render as HTML. */ + readonly body: string + /** ISO 8601 time the comment was created. */ + readonly createdAt: string + /** Whether the comment belongs to the signed-in user's review that is not submitted yet, which only that user sees. */ + readonly pending: boolean + /** Web page of the comment, or null when the host reports none. */ + readonly url: string | null + /** Whether the signed-in user can replace the comment's text through `writeReview`; false for a provider without it. */ + readonly viewerCanEdit: boolean + /** Whether the signed-in user can delete the comment through `writeReview`; false for a provider without it. */ + readonly viewerCanDelete: boolean +} +``` + +```ts type-equiv +/** + * One review thread on a file of a change request. A line thread has two positions: `original` on the commit it was + * written on, and `current` on the head commit of the read. `current` is null once the host no longer places the + * thread on the head commit, as after later commits changed its lines. + */ +interface ForgeReviewThread { + /** Host identity of the thread. */ + readonly id: ForgeThreadId + /** Repository-relative path the thread is on. */ + readonly path: string + /** Old (`L`) or new (`R`) side of the diff the lines number. */ + readonly side: 'L' | 'R' + /** Whether the thread is on lines or on the whole file. */ + readonly subject: 'line' | 'file' + /** Lines in the diff that ends at the head commit of the read, whose `commit` is that head; null for an outdated or file thread. */ + readonly current: ForgeAnchor | null + /** Lines in the diff that ended at the commit the thread was written on; null for a file thread. */ + readonly original: ForgeAnchor | null + /** Diff hunk the host recorded when the thread was written, ending at its last line; null when it recorded none. */ + readonly diffHunk: string | null + /** Whether the thread is marked resolved. */ + readonly resolved: boolean + /** Whether the signed-in user can reply to the thread through `writeReview`; false for a provider without it. */ + readonly viewerCanReply: boolean + /** + * Whether the signed-in user can mark the thread resolved, or unresolved when `resolved`, through `writeReview`; false + * for a provider without it. + */ + readonly viewerCanResolve: boolean + /** Comments oldest first; the first starts the thread. */ + readonly comments: readonly ForgeReviewComment[] +} +``` + +```ts type-equiv +/** Review threads of a change request read at one head commit. */ +interface ForgeReviewData { + /** Head commit the threads were read at; `current` positions number its files. */ + readonly headSha: string + /** Login of the signed-in user the provider read as, or null when the host does not name one. */ + readonly viewer: string | null + /** Threads in host order, at most the provider's limit. */ + readonly threads: readonly ForgeReviewThread[] + /** Whether the change request has more threads than `threads` holds. */ + readonly truncated: boolean + /** The signed-in user's pending review, or null without one. */ + readonly pendingReview: ForgePendingReview | null + /** + * Whether the signed-in user can add comments to a pending review and submit or discard it through `writeReview`; + * false for a provider without it. + */ + readonly viewerCanReview: boolean +} +``` + +`ctx.forge.writeReview(ref, write, signal)` 写入评审讨论和当前登录用户的待提交评审:回复讨论,立即发布,或在 `pending` 时加入待提交评审;把讨论标记为已解决或取消解决;编辑或删除评论;在 head 上添加一条行内评论到待提交评审;以及提交或丢弃待提交评审。用户还没有待提交评审时,待提交的回复或评论会先开始一个评审。每个写操作都带有用户看到的 head 提交;提供方先检查它,head 已变化时不写入,直接返回 `stale`,并像读取遇到 `stale` 时那样重新轮询被关注的变更请求;其他结果之后,服务都会立即重新轮询被关注的变更请求。写操作从不重试;结果为 `unknown` 时,必须先在托管平台上核对,再重试。提供方没有实现 `writeReview` 时,服务返回 `unsupported`。`ForgeReviewData` 带有待提交评审,以及用户对每个讨论、每条评论和待提交评审的权限;未实现 `writeReview` 的提供方把这些权限报告为没有,使用方据此只提供能够成功的写操作。GraphQL mutation 以及它们的结果如何对应到这些返回值,由 [GitHub 提供方 README](../../packages/experimental/forge-github/README.zh.md#use-this-package) 说明。 + +```ts type-equiv +/** Opaque host identity of one review. */ +type ForgeReviewId = Branded<'ForgeReviewId'> +``` + +```ts type-equiv +/** The signed-in user's review of a change request that is not submitted yet, which only that user sees. */ +interface ForgePendingReview { + /** Host identity of the review. */ + readonly id: ForgeReviewId + /** Comments the review holds. */ + readonly comments: number +} +``` + +```ts type-equiv +/** Decision a submitted review records. */ +type ForgeReviewEvent = 'comment' | 'approve' | 'request-changes' +``` + +```ts type-equiv +/** + * One write to the review threads and the pending review of a change request. `pending` replies and `add-pending` + * comments join the signed-in user's pending review, which is started when the user has none. A host that adds every + * reply to an existing pending review, as GitHub does, refuses a reply with `pending: false` while one exists. + */ +type ForgeReviewWrite = { + /** Head commit the user saw; providers check it before writing and refuse with `stale` once the head is another commit. */ + readonly headSha: string +} & ( + | { readonly kind: 'reply'; readonly thread: ForgeThreadId; readonly body: string; readonly pending: boolean } + | { readonly kind: 'resolve'; readonly thread: ForgeThreadId; readonly resolved: boolean } + | { readonly kind: 'edit-comment'; readonly comment: ForgeCommentId; readonly body: string } + /** Deleting the only comment of a thread deletes the thread. */ + | { readonly kind: 'delete-comment'; readonly comment: ForgeCommentId } + /** A comment on lines of `headSha`. */ + | { readonly kind: 'add-pending'; readonly comment: ForgeLineComment } + | { readonly kind: 'submit-pending'; readonly review: ForgeReviewId; readonly event: ForgeReviewEvent; readonly body: string } + /** Delete the pending review with every comment it holds. */ + | { readonly kind: 'discard-pending'; readonly review: ForgeReviewId } +) +``` + +```ts type-equiv +/** Result of a review write; an `unknown` outcome must be checked on the host before the write is tried again. */ +type ForgeReviewWriteResult = + | { readonly ok: true } + | { readonly ok: false; readonly code: 'unsupported' | 'stale' | 'failed' | 'unknown'; readonly message: string } +``` + ## Session 绑定 `ctx.forgeSession` 从每个 Session 自己的日志派生其绑定:`gh pr create` 的结果绑定其输出的 URL,`gh pr view`、`gh pr edit` 与 `gh pr checkout` 调用绑定它们所操作的变更请求,`git push` 的结果通过 `ctx.forge` 触发按 head 分支的发现;面板也会报告其检出所跟踪的分支,触发同样的发现。track、dismiss 与发现操作都是 `plugin:forge-session/binding` 插件记录,位于模型可见对话之外。`forgeChangeRequests` 投影的客户端视图随 Session 摘要下发,列出绑定但不含其状态。识别与发现规则见 [Session 绑定 README](../../packages/experimental/forge-session/README.zh.md#use-this-package)。 @@ -623,6 +806,10 @@ type ForgeChangeRequestStatesFrame = 变更视图经同一个 Remote 读取。`localDiff` 读取 Session 检出的某个 `ForgeLocalScope`;`changeRequestDiff` 经提供方的 `diff` 读取已绑定变更请求在其最新状态 head 处的变更(提供方只返回描述该 head 提交的补丁),或经提供方的 `compare` 读取它指定的 `ForgeCommitRange`;两者返回的文件都已在宿主上解析为 `ForgeDiffFile` 的 hunk,并带有分层与改动摘要。`localCommits` 与 `changeRequestCommits` 列出范围可以指定的提交,提供方不读取提交时后者返回 null。`localText` 与 `changeRequestText` 读取一个文件的新版本,用来补出 hunk 之间未变更的行。每次检查还会把 `branch` 范围的规模统计为 `ForgePanelState.local`,供面板的变更卡片使用,始终以自动分叉点为准。`base` 指定了引用的 `branch` 范围改为与 HEAD 和该分支的合并基准比较;`diffBases` 列出视图可选的分支以及自动分叉点。head 已越过最新状态时,提供方返回 `stale`,`ctx.forge.diff` 立即重新轮询该变更请求(每个 head 提交一次);`changeRequestDiff` 以 `forgePanel/stale-head` 拒绝且不缓存任何内容,变更视图保持加载,直到更新的状态到达后按该状态的 head 重新读取。因此评审评论始终指向视图所显示行的那个提交。 +`changeRequestReview(session, url, headSha, fresh)` 在视图所显示 diff 的 head 处读取已绑定变更请求的讨论;head 不同时以 `forgePanel/stale-head` 拒绝,提供方不支持读取讨论时返回 `forgePanel/review-unsupported`,其他失败返回 `forgePanel/review-failed`。每个变更请求在内存里保留一次读取结果,以 head 提交和状态的更新时间为键、受 `maxCachedReviewBytes` 约束,保留时间达到 `reviewRefreshMs` 后,或 `fresh` 要求时(读者刷新视图后的第一次读取就是这样)重新读取:在 GitHub 上,新评论和回复会改变 PR 的更新时间,解决讨论则不会。变更视图可见时,每收到一次状态就重新请求一次,并按[面板 README](../../packages/experimental/client-ui-forge/README.zh.md#use-this-package) 所述把讨论叠加到文件上。 + +`changeRequestReviewWrite(session, url, write)` 检查已绑定变更请求的一个 `ForgeReviewWrite` 的 head 提交、id、文字和行范围后,交给 `ctx.forge.writeReview`,并返回 `ForgeReviewWriteResult`。提供方给出答复后,无论结果如何,都会丢弃该变更请求保留的讨论,以及在此之前开始的所有读取,使下一次 `changeRequestReview` 从托管平台读取;`submitReview` 同样如此。变更视图一次只发送一个写操作,每个可能改变讨论的写操作之后都会重新读取讨论。 + ```ts type-equiv /** * Consecutive commits a changes view shows instead of its whole comparison, named by full object names in the order @@ -923,6 +1110,30 @@ async fetchChecks(ref: ChangeRequestRef, signal: AbortSignal): Promise +/** + * Read the review threads of a change request at one head commit. A + * `stale` failure polls a watched change request again as {@link ForgeService.diff} does. + * @param ref - change request served by a registered provider. + * @param headSha - head commit the threads must be read at, usually the head of the displayed diff. + * @param signal - cancellation of the read. + * @returns the threads read at `headSha`, or why the host did not provide them; `unsupported` when the provider cannot read reviews. + * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts. + */ +async readReview(ref: ChangeRequestRef, headSha: string, signal: AbortSignal): Promise + +/** + * Write to the review threads or the pending review of a change request while its head is still `write.headSha`, then + * poll the change request at once when it is watched, unless the provider cannot write reviews. A `stale` result polls + * it as a stale read does. + * @param ref - change request served by a registered provider. + * @param write - the write and the head commit the user saw. + * @param signal - cancellation of the write. + * @returns whether the host took the write; `unsupported` when the provider cannot write reviews, and `unknown` when the + * outcome must be checked on the host before the write is tried again. + * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts. + */ +async writeReview(ref: ChangeRequestRef, write: ForgeReviewWrite, signal: AbortSignal): Promise + /** * List the commits of a change request at its current head. * @param ref - change request served by a registered provider. @@ -1194,7 +1405,28 @@ Serves the forge panel. Following a Session inspects the checkout of its current @Remote async changeRequestText(session: Session, url: string, commit: string, path: string, signal: AbortSignal): Promise /** - * Publish a line comment or completed review for a visible Session binding. + * Read the review threads of a change request of a Session at the head commit of its displayed diff. Threads read + * at the same head commit and update time are reused from memory, for any Session, until they are + * `reviewRefreshMs` old, `maxCachedReviewBytes` evicts them, or a review write through this panel drops them; a read + * again after that age, or a `fresh` read, shows threads resolved elsewhere since, which do not change a GitHub pull + * request's update time. + * @param session - Session the change request is bound to. + * @param url - binding URL of the change request. + * @param headSha - head commit of the displayed diff. + * @param fresh - whether to read from the host even when threads at this head and update time are kept, as after the + * reader refreshes the view; the result replaces the kept threads. + * @param signal - request cancellation. + * @returns the threads at `headSha`, with `current` positions numbering the files of that diff. + * @throws `forgePanel/not-bound` unless the URL is a visible binding of the Session that a provider serves; + * `forgePanel/stale-head` when the latest status or the host names another head, which a host answer polls again; + * `forgePanel/review-unsupported` when the provider cannot read reviews; `forgePanel/review-failed` before the + * status was read and when the host does not provide the threads otherwise. + */ +@Remote async changeRequestReview(session: Session, url: string, headSha: string, fresh: boolean, signal: AbortSignal): Promise + +/** + * Publish a line comment or completed review for a visible Session binding. The threads kept for the change request + * are dropped once the host answers, so the next read shows the comments. * @param session - Session retaining the change request. * @param url - visible binding URL. * @param request - reviewed head, ranges, plain text, and explicit review decision. @@ -1203,6 +1435,21 @@ Serves the forge panel. Following a Session inspects the checkout of its current */ @Remote async submitReview(session: Session, url: string, request: ForgeReviewRequest, signal: AbortSignal): Promise +/** + * Write to the review threads or the pending review of a change request of a Session while its head is still the + * head the user saw. The threads kept for the change request are dropped once the host answers, so the next read + * shows the write, which a resolve does not show through a GitHub pull request's update time. + * @param session - Session the change request is bound to. + * @param url - binding URL of the change request. + * @param write - the write and the head commit of the threads the user saw. + * @param signal - request cancellation. + * @returns whether the host took the write; `stale` once the head moved, which polls the change request again, and + * `unknown` when the outcome must be checked on the host before the write is tried again. + * @throws `forgePanel/not-bound` unless the URL is a visible binding of the Session that a provider serves; an error + * for a write without text, a head that is not a commit object name, or an invalid line range. + */ +@Remote async changeRequestReviewWrite( session: Session, url: string, write: ForgeReviewWrite, signal: AbortSignal, ): Promise + /** * Mark a draft change request of a Session ready for review; the change * request is polled again once the host answers. diff --git a/docs/upgrade-guide/v0.2.2-rc.1/cua-ax-read-limits/guide.i18n.yaml b/docs/upgrade-guide/v0.2.2-rc.1/cua-ax-read-limits/guide.i18n.yaml new file mode 100644 index 0000000000..aa355c3d62 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-rc.1/cua-ax-read-limits/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/cua-ax-read-limits/guide.md +/: + en: a8ca814cf60ea12e + zh: f068d1ee13e80594 +/macos-ax-tree-read-limits: + en: a7eed0c191ff2b32 + zh: 15291798ba91329b +/macos-ax-tree-read-limits/change: + en: e4281d86095b950f + zh: 684ddf2957443ace +/macos-ax-tree-read-limits/migration: + en: 97a3885f5d1cb907 + zh: 19313c56eff68835 diff --git a/docs/upgrade-guide/v0.2.2-rc.1/cua-ax-read-limits/guide.md b/docs/upgrade-guide/v0.2.2-rc.1/cua-ax-read-limits/guide.md new file mode 100644 index 0000000000..8eab347bb2 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-rc.1/cua-ax-read-limits/guide.md @@ -0,0 +1,20 @@ +--- +kind: upgrade-guide +description: "macOS reads more AX nodes by default and accepts per-read overrides of configured traversal budgets." +--- + +# macOS AX tree read limits + +English | [中文](guide.zh.md) + +## Change + +The default macOS node count rises from 2000 to 5000 and the default depth from 25 to 50. Reading a large window can take longer and emit more text to the model. + +Configured `maxElements` and `maxDepth` now supply defaults independently for omitted arguments. Callers can request larger or smaller values for one read. Paste menu discovery continues to use the configured limits. + +## Migration + +1. To keep the previous budgets for ordinary reads, find the `@deepseek-ai/dsh-experimental-cua-macos` entry in your `cordis.yml` or profile patch. Set `maxElements: 2000` and `maxDepth: 25` in its existing `config`. +2. Restart the profile and confirm both defaults in the Computer Use model instructions. +3. If a script depends on specific traversal budgets, pass them explicitly to `getAccessibilityTree()`. An override applies only to that call. diff --git a/docs/upgrade-guide/v0.2.2-rc.1/cua-ax-read-limits/guide.zh.md b/docs/upgrade-guide/v0.2.2-rc.1/cua-ax-read-limits/guide.zh.md new file mode 100644 index 0000000000..e6f392c7aa --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-rc.1/cua-ax-read-limits/guide.zh.md @@ -0,0 +1,20 @@ +--- +kind: upgrade-guide +description: "macOS 默认读取更多 AX 节点,调用方可为单次读取覆盖配置值。" +--- + +# macOS AX 树读取范围 + +[English](guide.md) | 中文 + +## 变更 + +macOS 的默认节点数从 2000 增至 5000,默认深度从 25 增至 50。窗口中有更多节点可访问时,读取可能耗时更长,输出到模型的文本也可能增加。 + +`maxElements` 和 `maxDepth` 分别决定省略对应参数时的读取范围。调用方可以为一次读取指定高于或低于配置的值。查找粘贴菜单始终使用配置值。 + +## 迁移 + +1. 如需沿用原先的常规读取范围,在 `cordis.yml` 或配置补丁中找到 `@deepseek-ai/dsh-experimental-cua-macos`,在现有的 `config` 下设置 `maxElements: 2000` 和 `maxDepth: 25`。 +2. 重启配置,确认 Computer Use 模型说明中的两个默认值与配置一致。 +3. 如果脚本依赖特定的遍历范围,在 `getAccessibilityTree()` 的调用处显式传入这两个参数。一次调用的覆盖值不会影响后续读取。 diff --git a/docs/upgrade-guide/v0.2.2-rc.1/cua-native-platform/guide.i18n.yaml b/docs/upgrade-guide/v0.2.2-rc.1/cua-native-platform/guide.i18n.yaml index a017e7f82b..6dfabdc004 100644 --- a/docs/upgrade-guide/v0.2.2-rc.1/cua-native-platform/guide.i18n.yaml +++ b/docs/upgrade-guide/v0.2.2-rc.1/cua-native-platform/guide.i18n.yaml @@ -12,5 +12,5 @@ en: e5d1027faa55adba zh: 4b88ad6a70977fb3 /native-cua-application-and-window-api/migration: - en: a63e88dce467d6ee - zh: fc25bb283ca0eaff + en: 106eab81fd078fec + zh: 6fb30738af8bc621 diff --git a/docs/upgrade-guide/v0.2.2-rc.1/cua-native-platform/guide.md b/docs/upgrade-guide/v0.2.2-rc.1/cua-native-platform/guide.md index 2675699a71..2f4eea3c91 100644 --- a/docs/upgrade-guide/v0.2.2-rc.1/cua-native-platform/guide.md +++ b/docs/upgrade-guide/v0.2.2-rc.1/cua-native-platform/guide.md @@ -16,7 +16,7 @@ Providers supply startup capabilities alongside their platform guidance. The nat ## Migration 1. After `cua.getApp(selector)`, select the target from `app.getWindows()` with `app.getWindow(windowId)`. Use `window.getScreenshot()`, `window.click()`, `window.scroll()`, and `window.drag()`. Replace `hover` with `window.mouseMove()`. On macOS, `window.click(id)` sends mouse events at the element center. Switch to `invoke(id)` for the default accessibility action, or `performAction(id, "AXShowMenu")` to request an advertised menu action. -2. Replace `getAXState()` with `getAccessibilityTree()`. Replace `getAXStateAndScreenshot()` with separate tree and screenshot reads. Selection reads the initial tree silently for a window, and for an app when `appLevelAccessibility` is true. Read the tree explicitly to display it. +2. Replace `getAXState()` with `getAccessibilityTree()`. Replace `getAXStateAndScreenshot()` with separate tree and screenshot reads. Selection reads the initial tree silently for a window, and for an app when `appLevelAccessibility` is true. Read the tree explicitly to display it. See [macOS AX read limits](../cua-ax-read-limits/guide.md) for changes to traversal defaults and configuration. 3. Pass the opaque string ID from the latest tree wherever you passed a numeric element index. In raw requests use `elementId` with `snapshotId`. Replace `performSecondaryAction` with `listActions(id)` and `performAction(id, exactName, argument?)`, or use `invoke(id)` for the default action. `setValue` accepts the provider’s supported JSON values. On macOS, `performAction(id, 'AXRaise')` performs the advertised raise action. Call `app.activate()` first when the application must become active. 4. Replace a packed chord such as `pressKey('shift+Tab')` with `pressKey('Tab', ['shift'])`. Check `(await cua.getCapabilities()).methods` before using `sendKeyEvent`. On macOS, call it inside one `run_code` to hold a key across tool calls. To request one repeat, send another down for a non-modifier key held by that execution. Returning, throwing or pausing releases any remaining keys. If your script handles unknown macOS key names as `NATIVE_ERROR`, handle `INVALID_ARGUMENT` instead. Correct the key name before retrying. 5. Read `dispatched` from action results, then observe the application to verify the outcome. `invoke` returns `dispatched: false` when the element has no default action. Remove reads of the old `verified` field and of `pid` on selected objects or window records. Use `listApps()` or running `findApps()` matches when you need a PID. diff --git a/docs/upgrade-guide/v0.2.2-rc.1/cua-native-platform/guide.zh.md b/docs/upgrade-guide/v0.2.2-rc.1/cua-native-platform/guide.zh.md index b4551f624b..77e65e7ba4 100644 --- a/docs/upgrade-guide/v0.2.2-rc.1/cua-native-platform/guide.zh.md +++ b/docs/upgrade-guide/v0.2.2-rc.1/cua-native-platform/guide.zh.md @@ -16,7 +16,7 @@ CUA 脚本在指定窗口上截图和操作鼠标。App 和 Window 对象共享 ## 迁移 1. 调用 `cua.getApp(selector)` 后,从 `app.getWindows()` 返回的列表选定目标,再调用 `app.getWindow(windowId)`。在窗口上调用 `getScreenshot()`、`click()`、`scroll()` 和 `drag()`,将原有的 `hover` 调用改为 `window.mouseMove()`。在 macOS 上,`window.click(id)` 在元素中心发送鼠标事件。需要执行默认辅助功能动作时,改用 `invoke(id)`。需要打开控件菜单且控件声明了 `AXShowMenu` 时,调用 `performAction(id, "AXShowMenu")`。 -2. 将 `getAXState()` 改为 `getAccessibilityTree()`,将 `getAXStateAndScreenshot()` 拆成读取树和截图两次调用。选择窗口时会静默读取初始树。选择应用时,只有 `appLevelAccessibility` 为真才读取。要显示树,请显式读取。 +2. 将 `getAXState()` 改为 `getAccessibilityTree()`,将 `getAXStateAndScreenshot()` 拆成读取树和截图两次调用。选择窗口时会静默读取初始树。选择应用时,只有 `appLevelAccessibility` 为真才读取。要显示树,请显式读取。[读取上限的迁移说明](../cua-ax-read-limits/guide.zh.md)列出了 macOS 默认值和配置含义的变化。 3. 将数字元素索引改为从最新树中取得的字符串 ID。直接发送请求时使用 `elementId` 和 `snapshotId`。原先调用 `performSecondaryAction` 的地方,先用 `listActions(id)` 取得完整动作名,再调用 `performAction(id, exactName, argument?)`。要执行默认动作,可调用 `invoke(id)`。`setValue` 接受提供方支持的 JSON 值。 在 macOS 上,`performAction(id, 'AXRaise')` 只执行元素声明的抬起窗口动作。需要把应用切到前台时先调用 `app.activate()`。 4. 将 `pressKey('shift+Tab')` 之类的组合键写法改为 `pressKey('Tab', ['shift'])`。调用 `sendKeyEvent` 前检查 `(await cua.getCapabilities()).methods`。在 macOS 上,同一次 `run_code` 中可调用此方法跨工具调用保持按键。如果需要一次重复按下,可在这次执行中对已按住的普通键再发一次 `down`。执行返回、异常退出或用户暂停时会释放仍按着的键。如果脚本用 `NATIVE_ERROR` 识别 macOS 上的未知键名,请改为处理 `INVALID_ARGUMENT`,并在重试前修正键名。 5. 从动作结果读取 `dispatched`,再观察应用确认效果。元素没有默认动作时,`invoke` 返回 `dispatched: false`。移除读取旧字段 `verified` 的代码,以及对已选对象和窗口记录中 `pid` 的读取。需要 PID 时,使用 `listApps()` 或 `findApps()` 返回的运行中应用记录。 diff --git a/docs/upgrade-guide/v0.2.2-rc.1/forge-review-reads/guide.i18n.yaml b/docs/upgrade-guide/v0.2.2-rc.1/forge-review-reads/guide.i18n.yaml new file mode 100644 index 0000000000..8377a14f8a --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-rc.1/forge-review-reads/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/forge-review-reads/guide.md +/: + en: 53dbdc67362a5851 + zh: 9c7b2c4dd31cf666 +/forge-failures-report-unsupported-reads: + en: 3e5488f3008886b7 + zh: 8123e954c41d559c +/forge-failures-report-unsupported-reads/change: + en: 77712ff12908e838 + zh: 00714f77f3b7ae80 +/forge-failures-report-unsupported-reads/migration: + en: 698a34a7e09be2be + zh: a32a64dc130f496f diff --git a/docs/upgrade-guide/v0.2.2-rc.1/forge-review-reads/guide.md b/docs/upgrade-guide/v0.2.2-rc.1/forge-review-reads/guide.md new file mode 100644 index 0000000000..d6c6aa2962 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-rc.1/forge-review-reads/guide.md @@ -0,0 +1,19 @@ +--- +kind: upgrade-guide +description: "ForgeFailure gains the unsupported code, which ctx.forge.readReview returns for a provider without review reads." +--- + +# Forge failures report unsupported reads + +English | [中文](guide.zh.md) + +## Change + +`ForgeFailure['code']` gains `unsupported`. `ctx.forge.readReview(ref, headSha, signal)`, new beside the optional `ForgeProvider.readReview`, returns it when the provider of the change request does not read review threads. Other reads keep their codes: a provider without `fetchChecks` still makes `ctx.forge.fetchChecks` return `unavailable`. + +This affects code that switches exhaustively over `ForgeFailure['code']`, such as a `Record` lookup or a `switch` that ends in `assertNever`. All types come from `@deepseek-ai/dsh-experimental-forge`. Providers need no change: `readReview` is optional. + +## Migration + +1. Handle `unsupported` wherever code switches exhaustively over `ForgeFailure['code']`; treat it as a capability the provider lacks, not as a failed read to retry. +2. Run your type check; it succeeds when no `ForgeFailure` code is unhandled. diff --git a/docs/upgrade-guide/v0.2.2-rc.1/forge-review-reads/guide.zh.md b/docs/upgrade-guide/v0.2.2-rc.1/forge-review-reads/guide.zh.md new file mode 100644 index 0000000000..75f8a1057e --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-rc.1/forge-review-reads/guide.zh.md @@ -0,0 +1,19 @@ +--- +kind: upgrade-guide +description: "ForgeFailure 新增 unsupported 代码;提供方不支持读取评审讨论时,ctx.forge.readReview 返回它。" +--- + +# Forge 失败代码报告不支持的读取 + +[English](guide.md) | 中文 + +## 变更 + +`ForgeFailure['code']` 新增 `unsupported`。新增的 `ctx.forge.readReview(ref, headSha, signal)` 对应可选的 `ForgeProvider.readReview`;变更请求的提供方不支持读取评审讨论时,它返回 `unsupported`。其他读取的代码不变:提供方未实现 `fetchChecks` 时,`ctx.forge.fetchChecks` 仍返回 `unavailable`。 + +受影响的是对 `ForgeFailure['code']` 做穷举的代码,例如 `Record` 查表,或以 `assertNever` 结尾的 `switch`。所有类型都来自 `@deepseek-ai/dsh-experimental-forge`。提供方无需修改:`readReview` 是可选方法。 + +## 迁移 + +1. 在所有对 `ForgeFailure['code']` 做穷举的地方处理 `unsupported`,把它当作提供方缺少的能力,而不是需要重试的读取失败。 +2. 运行类型检查;没有未处理的 `ForgeFailure` 代码时即通过。 diff --git a/packages/client/ui-theme/tests/stylesheet-scan.client.spec.ts b/packages/client/ui-theme/tests/stylesheet-scan.client.spec.ts new file mode 100644 index 0000000000..e65cb1a16a --- /dev/null +++ b/packages/client/ui-theme/tests/stylesheet-scan.client.spec.ts @@ -0,0 +1,32 @@ +/** Tests for the package-tree scan helpers that the stylesheet contracts range over. */ +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterEach, expect, it } from 'vitest' +import { packageFiles } from './stylesheet-scan.ts' + +const roots: string[] = [] + +afterEach(() => { + for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }) +}) + +it('skips dot directories holding transient roots', () => { + const root = mkdtempSync(join(tmpdir(), 'dsh-stylesheet-scan-')) + roots.push(root) + mkdirSync(join(root, 'pkg', 'nested'), { recursive: true }) + writeFileSync(join(root, 'pkg', 'package.json'), '{}') + writeFileSync(join(root, 'pkg', 'nested', 'package.json'), '{}') + mkdirSync(join(root, '.typert-worker-failure-probe')) + writeFileSync(join(root, '.typert-worker-failure-probe', 'package.json'), '{}') + + // The helper reports `/`-separated paths on every platform, so the Windows + // temporary root's separators must not reach the expectation. Traversal + // reports the nested manifest before its parent, and directory order is not + // guaranteed, so both sides are compared sorted. + const normalized = root.replaceAll('\\', '/') + expect(packageFiles(name => name === 'package.json', root).sort()).toEqual([ + `${normalized}/pkg/nested/package.json`, + `${normalized}/pkg/package.json`, + ]) +}) diff --git a/packages/client/ui-theme/tests/stylesheet-scan.ts b/packages/client/ui-theme/tests/stylesheet-scan.ts index 91311945bf..ce796bc62c 100644 --- a/packages/client/ui-theme/tests/stylesheet-scan.ts +++ b/packages/client/ui-theme/tests/stylesheet-scan.ts @@ -73,22 +73,28 @@ export function varReferences(value: string): string[] { /** * Every file shipped as package source whose name the predicate accepts, - * excluding build output and installed dependencies. + * excluding build output, installed dependencies, and dot directories. + * Dot directories hold VCS metadata and per-test temporary roots rather than + * shipped source, and their owner can remove one while a scan reads it. * @param accepts - filename predicate. - * @returns absolute paths under packages/, `/`-separated on every platform so + * @param root - tree to walk, the packages directory by default. + * @returns absolute paths under `root`, `/`-separated on every platform so * specs can match repo-relative suffixes verbatim. */ -export function packageFiles(accepts: (name: string) => boolean): string[] { +export function packageFiles(accepts: (name: string) => boolean, root: string = PACKAGES_DIR): string[] { const found: string[] = [] const walk = (dir: string): void => { for (const entry of readdirSync(dir, { withFileTypes: true })) { const path = join(dir, entry.name) if (entry.isDirectory()) { - if (entry.name !== 'node_modules' && entry.name !== 'lib' && entry.name !== 'dist') walk(path) + // Dot directories hold VCS metadata and the temporary roots each spec + // creates inside the package tree, never shipped package source; a + // concurrent owner can remove one while a scan reads it. + if (!entry.name.startsWith('.') && entry.name !== 'node_modules' && entry.name !== 'lib' && entry.name !== 'dist') walk(path) } else if (accepts(entry.name)) found.push(path.replaceAll('\\', '/')) } } - walk(PACKAGES_DIR) + walk(root) return found } diff --git a/packages/experimental/client-ui-forge/README.i18n.yaml b/packages/experimental/client-ui-forge/README.i18n.yaml index 851fed865d..3affdf7c58 100644 --- a/packages/experimental/client-ui-forge/README.i18n.yaml +++ b/packages/experimental/client-ui-forge/README.i18n.yaml @@ -15,23 +15,23 @@ en: d152484eb41ac6b4 zh: 2f8a621b991260a1 /deepseek-ai-dsh-experimental-client-ui-forge/use-this-package: - en: c7e1b7d87ccccd2e - zh: 42d864b918a6175c + en: 78e5f4f2b3faeb7a + zh: 6d0e381fc385d6c7 /deepseek-ai-dsh-experimental-client-ui-forge/understand-the-implementation: - en: eaf062b1439ed8b3 - zh: d7c6a68779774825 + en: 0feae5f8c5ef559f + zh: 5334adff35e3bebd /deepseek-ai-dsh-experimental-client-ui-forge/further-exploration: en: fa4d8c579ffc49ff zh: 5856ed7469e4585b /deepseek-ai-dsh-experimental-client-ui-forge/model-experience: - en: 10101427d1e0589b - zh: c981cec12f64eb75 + en: 795766e162ebf4df + zh: 893de3302798330a /deepseek-ai-dsh-experimental-client-ui-forge/model-experience/kv-cache-effect: en: 2bc25a99e17789c4 zh: 4bec723fbf249d28 /deepseek-ai-dsh-experimental-client-ui-forge/known-limitations-and-deferred-work: - en: 4124d453778daf7b - zh: 33cab3137381942e + en: da0e90e368524e68 + zh: 1763d9c607926013 /deepseek-ai-dsh-experimental-client-ui-forge/known-limitations-and-deferred-work/dev-note: en: e67f633dc6fe7773 zh: 3bb0c20c93f16f98 diff --git a/packages/experimental/client-ui-forge/README.md b/packages/experimental/client-ui-forge/README.md index c4e36aaba3..8c24bf2687 100644 --- a/packages/experimental/client-ui-forge/README.md +++ b/packages/experimental/client-ui-forge/README.md @@ -41,14 +41,15 @@ Panel text follows the application language: Chinese, English, Japanese, Spanish - **Changes view** — The Changes row of an expanded change request card and the local changes card open a right-sidebar tab that lists the changed files. The local tab is named Local changes and shows Branch by default: the working tree and untracked files against the fork point. Its header names the checked-out branch, or the abbreviated commit on a detached HEAD, and the base branch, which opens a searchable menu: first Default, the base commit of the worktree the Session created, else the merge base of HEAD with the default branch of the code host remote, then remote-tracking and then local branches, each most recently committed first, without the checked-out branch and, outside a created worktree, without the remote-tracking branch Default already names. Typing filters the listed rows at once and lists the branches whose names contain the text, ignoring case, after a short pause; Enter chooses the first row. Choosing another branch compares with the merge base of HEAD and that branch. The tab keeps the choice while other scopes show; closing the tab or reloading the application returns it to Default. When the chosen branch is gone, its name is struck through, and when it shares no history with HEAD, the view says so as well; both offer Use the default base branch instead of Retry. A narrow view hides the note that uncommitted changes count, then the checked-out branch. Uncommitted compares them with HEAD, Unstaged with the index, and Staged compares the index with HEAD. A change request view shows the host's diff at its head and says how many commits the checked-out branch has beyond that head when it is the change request's head branch. The toolbar jumps to a file, totals the changed lines, refreshes, and switches between two columns and one and between wrapped and cut long lines. Visited changes tabs stay mounted across tab and Session switches, hiding the sidebar, and docking changes, preserving file folds, revealed large files, expanded context, layout, and scroll position while the diff is unchanged. Hidden changes views release their panel subscription and defer diff reads; returning reads again only when the latest head or local summary differs. A refresh that replaces the diff discards expanded context, and changed content may move the reading position. Temporary menus close when the view is hidden. Closing the tab or reloading the application discards this progress. Each file is a separate card, with a tinted header that stays at the top while its lines scroll. Files are named before their directories, which use smaller subdued type and shorten first; hovering one shows its complete path, and both paths for a renamed file. Each file shows badges for a new, deleted, or renamed file, the last naming the old file name, or the old path when only the directory changed, and, in the Branch scope, an untracked one, and a menu that copies its path and opens the whole file in the sidebar for local changes or its page at the head in the browser for a change request. When the header is narrow, the path, the badges, and Changed since viewed shorten, so the line counts, Viewed, and the menu stay whole. Unchanged lines between hunks collapse into rows that expand from the file's new side: the working tree, the index for Staged, or the head commit through the code host; a file that changed after the diff was read stays collapsed until the view reads again. A binary file and an untracked file over `maxDiffBytes` show a note instead of their lines, a file whose hunks draw more than 1,000 lines starts as one collapsed strip that names its changed lines and draws them when opened, and a file below files that change more than 5,000 lines starts collapsed. The view reads again on Refresh and the page refresh shortcut, on each navigation, when the change request's head moves, and when the Branch scope's summary changes; a change request's view first waits for the status that names its head, unless no provider serves it or that poll failed. When the head moved past the latest status, the view keeps loading and reads again at the head of a status later than the one the read started with, at once when that status arrived during the read. While a read replaces changes already shown, the Refresh icon turns. A change request whose diff the code host or its provider refuses over a size limit, such as a GitHub diff whose output exceeds the provider's `maxOutputBytes`, says its changes are too large to show here and offers View in browser; another failed read offers Retry and, for a change request, View in browser. A change request's diff is downloaded once per head commit and base branch while it stays cached, so reopening, refreshing, and navigating at the same head read nothing from the host. - **Review layers, test files, viewed files, and commits** — Above the file tree, the lens keeps All files or the files of one layer, Interface, Implementation, or Tests, each with its count; where no tree shows, the toolbar offers the lens as a menu. The repository decides first: a file whose root `.gitattributes` sets `dsh-review-layer=test`, `interface`, or `implementation` is in that layer, and one it marks `linguist-generated` is in Tests. Next come the optional `testPaths` and `interfacePaths` globs, which add to the built-in rules and are empty by default. The built-in rules then follow common conventions: test directories and files of Jest, Vitest, `go test`, pytest, RSpec, XCTest, and .NET, snapshots, locale catalogs, and lockfiles are Tests; package manifests, type declarations, headers, stubs, and interface definitions such as Protocol Buffers, GraphQL, and OpenAPI are Interface. Every other file is in Implementation. For example, `*_test.go dsh-review-layer=test` or `api/**/*.yaml dsh-review-layer=interface` in `.gitattributes` records a repository's own convention. Hide test files leaves Tests out of the file tree and the diff without listing them, and disables the Tests lens. Viewed on a file header marks that change of the file viewed and collapses it; the toolbar shows how many of the shown files are viewed, and `V` marks or clears the file being read: the file holding the focus or the text cursor, else the file at the top of the view. A file whose change differs from the change it was marked at shows Changed since viewed and expands again. Marks are kept in this browser per Session, source, path, and change digest, so they survive closing the tab and reloading, and the tabs of one Session share them: a mark in one tab appears in the others and keeps their marks. A change of the file mode alone, such as `chmod +x`, also counts as a new change. All commits beside Submit review, and beside the base branch in the Branch scope, lists the commits oldest first, read once until the head, the local branch or base, or a refresh changes them; a click shows one commit and a Shift click the commits from the last one clicked, which must follow each other as first parents: a run that leaves that line, such as one across a merged branch, keeps the menu open and says why; the view then shows those commits' changes, reads unchanged lines at the last of them, and offers Add to input but no GitHub comment or review. Branch commits exclude uncommitted and untracked files. Another base or scope returns to all commits, and chosen commits that are gone or no longer one run offer Show all commits. +- **Review threads** — A change request view overlays the review threads its code host read at the shown head. A thread on lines follows the row of its last line, on the side it was written on, or the collapsed unchanged lines that hold it; it shows the place it was written, each comment's avatar, author, time, and Markdown with raw HTML left out, and tags for the change request's author, bots, and comments still pending in the signed-in user's review. A resolved thread folds into one row that unfolds on request. Threads on a whole file open the file, and threads later commits made outdated gather after its lines in a section that shows the end of the hunk they were written on and offers View file at that commit, which reads the file at the commit they were written on with their lines marked. Chosen commits show only new-side threads whose lines number the last chosen commit. The file tree and each file header count unresolved threads. Each click on the count in a header goes to the file's next unresolved thread in the order the file shows them, threads the chosen commits do not hold last, and from the last back to the first; the Threads toolbar button opens the thread list, which groups the threads by file in file tree order and orders each file's threads the same way, shows the Unresolved, Resolved, or All threads, Unresolved first, and opens each thread at its place, choosing all commits for one the chosen commits do not hold. The list docks beside the files in a view at least 1,040px wide, floats over them in a narrower one and closes before it opens a thread there, and takes their whole width below 480px. The list names a truncated read. A thread offers Add to input, which quotes the whole thread, View on GitHub, and the writes the signed-in user may make. Without a pending review, its reply field replies at once, and its menu starts a pending review with the reply; with one, the field adds the reply to it, as GitHub adds every reply of the user to the pending review. Resolve thread and Unresolve thread change its state, and the menu of the user's own comment edits or deletes it after asking, saying when deleting the only comment deletes the thread. A resolved thread stays open while the user writes a reply or an edit in it. A write the code host refuses keeps the text and says why; a write whose outcome is unknown reads the threads again and asks the user to check them before trying again. Every write reads the threads again, since resolving a thread does not change a GitHub pull request's update time. Threads are read again at each status while the view shows, and from the code host after Refresh even while the panel keeps an earlier read; a failed read keeps the last threads and offers Retry, and a provider that does not read reviews shows none. The checks row initially shows the polling preview. While it is incomplete, the card uses the host’s aggregate outcome without a failure count and labels the loaded check count as partial. Opening the list loads the remaining pages for that PR through `changeRequestChecks`; its deadline is independent of polling. A failed read keeps the preview and offers Retry. Closing the list, changing the head, or unmounting cancels the read; late results are ignored. Reopening reads current details. The Remote requires a visible Session binding and rejects a response for a different head commit. The diff follows the file tree’s depth-first order: directories before files, with each group sorted by displayed name in case-sensitive UTF-16 code-unit order. Compacted directory chains are compared as one complete name. Filtering or folding the tree does not reorder the diff. Click the diff content to focus it. Left and Right move to the previous and next file in diff order and expand it; navigation stops at the first and last file. Up and Down keep their normal scrolling behavior. After manual scrolling, file navigation starts from the file at the top of the viewport. Text editing, non-collapsed text selections, modified keys, menus, and file-tree controls keep their own keyboard behavior. -`gitCommand`, `gitTimeoutMs`, `graceMs`, `maxOutputBytes`, `readinessTimeoutMs`, `maxBranches`, `worktreePrefix`, `maxDiffBytes`, `maxUntrackedFiles`, `maxCachedDiffBytes`, `maxCommits`, `testPaths`, and `interfacePaths` are listed in the [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-experimental-client-ui-forge). +`gitCommand`, `gitTimeoutMs`, `graceMs`, `maxOutputBytes`, `readinessTimeoutMs`, `maxBranches`, `worktreePrefix`, `maxDiffBytes`, `maxUntrackedFiles`, `maxCachedDiffBytes`, `maxCachedReviewBytes`, `reviewRefreshMs`, `maxCommits`, `testPaths`, and `interfacePaths` are listed in the [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-experimental-client-ui-forge). -All files opens a searchable directory tree with the selected file scrolled to its middle. Single-child directories share a row, and renamed files also match their old path. A wide changes pane shows the same tree beside the diff; its File tree toolbar button cycles through left, right, and hidden, starting on the left. Its accessible name describes the next action, and focus stays on the button when it moves or hides the tree. The search, folds, selection, and width survive moving or hiding the tree and switching tabs or Sessions. Drag the divider or use its arrow keys to resize the tree. Files and folders reserve the same disclosure column so each child is indented from its parent. Local changes and each PR retain separate tabs. Select code text or use line numbers to select a range within one displayed hunk and side; text selection and copying stay on the starting side. The plus button opens the plain-text comment editor. With a mouse, hovering a line also shows a plus beside its line number, which stays clickable, on the hovered side in two columns and on the line's own side in one column; pressing it selects that line, dragging extends the range on that side, and releasing opens the editor. It accepts newlines and IME composition; only its action buttons submit the comment. Drag its lower edge to adjust the height. Add to input inserts a removable quote into the main composer that shows the file name, side and lines, and comment, and on hover the file path; multiple quotes are sent together only when the user sends that composer. The GitHub split button starts or adds to a pending review; its menu publishes a single comment immediately. Comments remain beside their code after quoting, queueing, or publishing. Pending comments are edited or removed there. Request changes requires a review summary; the dialog explains this beside the summary field and announces the requirement when the decision changes. Submit review in the PR title bar opens a centered dialog showing only the pending count, summary, and Comment, Approve, or Request changes. Added and deleted files show only their populated line-number column. Pending reviews and comment records are stored in this browser per Session and tab, including the original PR head commit. Switching Sessions or hiding the pane retains them; closing the tab clears its comments, summary, and decision, and reopening starts an empty review. Published GitHub comments and references already added to the main composer are unaffected. Records whose code changed remain visible below their file, or after the diff when the file is absent. A changed head requires fresh line selections. While the tab remains open, an uncertain write stays blocked across reloads until the user checks GitHub and explicitly permits another submission. +All files opens a searchable directory tree with the selected file scrolled to its middle. Single-child directories share a row, and renamed files also match their old path. A wide changes pane shows the same tree beside the diff; its File tree toolbar button cycles through left, right, and hidden, starting on the left. Its accessible name describes the next action, and focus stays on the button when it moves or hides the tree. The search, folds, selection, and width survive moving or hiding the tree and switching tabs or Sessions. Drag the divider or use its arrow keys to resize the tree. Files and folders reserve the same disclosure column so each child is indented from its parent. Local changes and each PR retain separate tabs. Select code text or use line numbers to select a range within one displayed hunk and side; text selection and copying stay on the starting side. The plus button opens the plain-text comment editor. With a mouse, hovering a line also shows a plus beside its line number, which stays clickable, on the hovered side in two columns and on the line's own side in one column; pressing it selects that line, dragging extends the range on that side, and releasing opens the editor. It accepts newlines and IME composition; only its action buttons submit the comment. Drag its lower edge to adjust the height. Add to input inserts a removable quote into the main composer that shows the file name, side and lines, and comment, and on hover the file path; multiple quotes are sent together only when the user sends that composer. Once the review threads are read and the user may review, the GitHub split button starts the user's pending review on GitHub with the comment, or adds the comment to it; the comment then shows as a thread tagged Pending, which only the user sees until the review is submitted. Its menu publishes a single comment immediately, which GitHub refuses while the user has a pending review, so the menu is then absent. Agent references and published comments remain beside their code. Request changes requires a review summary; the dialog explains this beside the summary field and announces the requirement when the decision changes. Submit review in the PR title bar opens a centered dialog showing only the pending count, summary, and Comment, Approve, or Request changes. With a pending review, it submits that review, keeping a submission whose outcome is unknown blocked until the user checks GitHub, as a direct submission is, and Discard review deletes the review and its comments after a confirmation; without one, it publishes the summary as one review. On the user's own pull request, which GitHub lets its author only comment on, Approve and Request changes are unavailable. Added and deleted files show only their populated line-number column. The summary, decision, and records of Agent references and published comments are stored in this browser per Session and tab, including the original PR head commit. Switching Sessions or hiding the pane retains them; closing the tab clears them, and reopening starts an empty summary. The pending review, published GitHub comments, and references already added to the main composer are unaffected. Comment drafts an earlier version kept in this browser stay beside their code tagged Browser draft and can be edited, deleted, or added to the pending review; they keep Submit review disabled while a pending review exists, and without one Submit review publishes them with the summary. Records whose code changed remain visible below their file, or after the diff when the file is absent. A changed head requires fresh line selections. While the tab remains open, an uncertain write stays blocked across reloads until the user checks GitHub and explicitly permits another submission. ----- @@ -69,11 +70,11 @@ Restoration records `restoring` before mutation and `restored` only after succes Each inspection also decides whether the worktree is missing: the Session's directory lies inside the created worktree, `ctx.fs.lstat` finds no directory there, and `show-ref` in the source repository tells whether the branch still exists. -`localDiff` takes the fork point from the created worktree's `baseCommit` when the Session works in it, else, for each remote in the code host order, from `symbolic-ref --quiet --short refs/remotes//HEAD` and `merge-base HEAD`; without one the `branch` scope refuses with `forgePanel/no-fork-point`. A `branch` scope that names a base ref under `refs/heads/` or `refs/remotes/` instead takes `merge-base HEAD` with it once `show-ref --verify` finds the ref, refusing with `forgePanel/base-missing` when the ref does not exist and with `forgePanel/no-fork-point` when HEAD shares no history with it; another ref name is refused before Git runs. It runs `diff --no-ext-diff --no-textconv --submodule=short --ignore-submodules=dirty --no-color -M` with fixed `a/` and `b/` prefixes and `core.quotePath=false` against the fork point, against HEAD (the empty tree before the first commit), against the index, or with `--cached` against HEAD. Before patches and statistics, Git configuration is read to apply command-local clean/process filter overrides. A failed or truncated configuration read stops the comparison: `localDiff` reports `forgePanel/filter-config-failed`, with a retry after correcting Git configuration or the output limit; failed statistics leave the local changes card hidden. Filter enumeration uses `maxDiffBytes` for patches and `maxOutputBytes` for statistics. Untracked files, at most `maxUntrackedFiles` with the rest counted as omitted, come from `ls-files --others --exclude-standard -z` and are read through `ctx.fs` as new files, binary when their first 8,000 bytes hold a NUL byte or they are not UTF-8. A patch, file list, or file over `maxDiffBytes` refuses with `forgePanel/diff-too-large`, and a directory outside a checkout with `forgePanel/not-a-checkout`. The Host parses patches with jsdiff into files and hunks, so the browser receives no raw patch. It gives each file a digest of its paths, status, hunks, and `old mode` and `new mode` lines, plus the blob names of a binary change or the content of an untracked binary file, and a layer from the `dsh-review-layer` and `linguist-generated` lines of the root `.gitattributes`, later lines overriding earlier ones and a value other than a layer name leaving the layer unspecified, with patterns matched by Git's wildmatch rules in [`src/wildmatch.ts`](src/wildmatch.ts) and negated patterns skipped as Git skips them, then from picomatch matches, with dot files included, of `testPaths`, `interfacePaths`, and the built-in rules in [`src/layers.ts`](src/layers.ts), with `.gitattributes` read from the index for Staged, the working tree for the other local scopes, the last chosen commit for chosen commits, and the head or last chosen commit through `fileText` for a change request, where a missing file reads as none. `localCommits` lists the commits between the fork point and HEAD with `log --no-show-signature --topo-order --reverse`, the newest `maxCommits` of them, so the list ends with HEAD's commit. A Branch scope with chosen commits compares the first one's first parent, or the empty tree for a root commit, with the last, refusing commits that are not full object names, not listed, or out of order with `forgePanel/commits-missing`, and a chosen commit whose first parent is not the commit listed before it with `forgePanel/commits-not-linear`; `localText` reads that last commit through `show`. `localText` reads the new side of one file, from the index through `show :` for Staged and through `ctx.fs` otherwise, and refuses a path that leaves the checkout. `changeRequestDiff` and `changeRequestText` act only on a visible binding a provider serves, else they refuse with `forgePanel/not-bound`; they read the head commit of the binding's latest status through the provider's `diff` and `fileText`, a patch together with its `.gitattributes`, where a failed patch read cancels the attributes read and both reads end before the result, the patch's failure passing on before the attributes failure, refuse a `too-large` failure with `forgePanel/diff-too-large`, a `stale` failure, meaning the head moved past that status, with `forgePanel/stale-head`, and refuse with `forgePanel/diff-failed` before a status was read or when the host refuses otherwise. A `stale` diff polls the change request at once, once per head commit, and is not cached, so no patch is ever kept under a head it does not describe. The Host keeps the patches `changeRequestDiff` read with their attributes, one per change request at its head commit and base branch, and drops the least recently read once they exceed `maxCachedDiffBytes`; a later read at the same head and base answers from memory for any Session, and a failed read is not kept. `changeRequestCommits` returns the provider's `commits` list, or null when the provider does not read commits; `changeRequestDiff` with chosen commits finds them in that list, refuses them as the Branch scope does, and reads `compare` from the first one's parent to the last, uncached. The commits the checkout has beyond the head come from `symbolic-ref`, `cat-file -e`, and `rev-list --count`, and are null when the checked-out branch is not the head branch, the head commit is absent, or Git fails. +`localDiff` takes the fork point from the created worktree's `baseCommit` when the Session works in it, else, for each remote in the code host order, from `symbolic-ref --quiet --short refs/remotes//HEAD` and `merge-base HEAD`; without one the `branch` scope refuses with `forgePanel/no-fork-point`. A `branch` scope that names a base ref under `refs/heads/` or `refs/remotes/` instead takes `merge-base HEAD` with it once `show-ref --verify` finds the ref, refusing with `forgePanel/base-missing` when the ref does not exist and with `forgePanel/no-fork-point` when HEAD shares no history with it; another ref name is refused before Git runs. It runs `diff --no-ext-diff --no-textconv --submodule=short --ignore-submodules=dirty --no-color -M` with fixed `a/` and `b/` prefixes and `core.quotePath=false` against the fork point, against HEAD (the empty tree before the first commit), against the index, or with `--cached` against HEAD. Before patches and statistics, Git configuration is read to apply command-local clean/process filter overrides. A failed or truncated configuration read stops the comparison: `localDiff` reports `forgePanel/filter-config-failed`, with a retry after correcting Git configuration or the output limit; failed statistics leave the local changes card hidden. Filter enumeration uses `maxDiffBytes` for patches and `maxOutputBytes` for statistics. Untracked files, at most `maxUntrackedFiles` with the rest counted as omitted, come from `ls-files --others --exclude-standard -z` and are read through `ctx.fs` as new files, binary when their first 8,000 bytes hold a NUL byte or they are not UTF-8. A patch, file list, or file over `maxDiffBytes` refuses with `forgePanel/diff-too-large`, and a directory outside a checkout with `forgePanel/not-a-checkout`. The Host parses patches with jsdiff into files and hunks, so the browser receives no raw patch. It gives each file a digest of its paths, status, hunks, and `old mode` and `new mode` lines, plus the blob names of a binary change or the content of an untracked binary file, and a layer from the `dsh-review-layer` and `linguist-generated` lines of the root `.gitattributes`, later lines overriding earlier ones and a value other than a layer name leaving the layer unspecified, with patterns matched by Git's wildmatch rules in [`src/wildmatch.ts`](src/wildmatch.ts) and negated patterns skipped as Git skips them, then from picomatch matches, with dot files included, of `testPaths`, `interfacePaths`, and the built-in rules in [`src/layers.ts`](src/layers.ts), with `.gitattributes` read from the index for Staged, the working tree for the other local scopes, the last chosen commit for chosen commits, and the head or last chosen commit through `fileText` for a change request, where a missing file reads as none. `localCommits` lists the commits between the fork point and HEAD with `log --no-show-signature --topo-order --reverse`, the newest `maxCommits` of them, so the list ends with HEAD's commit. A Branch scope with chosen commits compares the first one's first parent, or the empty tree for a root commit, with the last, refusing commits that are not full object names, not listed, or out of order with `forgePanel/commits-missing`, and a chosen commit whose first parent is not the commit listed before it with `forgePanel/commits-not-linear`; `localText` reads that last commit through `show`. `localText` reads the new side of one file, from the index through `show :` for Staged and through `ctx.fs` otherwise, and refuses a path that leaves the checkout. `changeRequestDiff` and `changeRequestText` act only on a visible binding a provider serves, else they refuse with `forgePanel/not-bound`; they read the head commit of the binding's latest status through the provider's `diff` and `fileText`, a patch together with its `.gitattributes`, where a failed patch read cancels the attributes read and both reads end before the result, the patch's failure passing on before the attributes failure, refuse a `too-large` failure with `forgePanel/diff-too-large`, a `stale` failure, meaning the head moved past that status, with `forgePanel/stale-head`, and refuse with `forgePanel/diff-failed` before a status was read or when the host refuses otherwise. A `stale` diff polls the change request at once, once per head commit, and is not cached, so no patch is ever kept under a head it does not describe. The Host keeps the patches `changeRequestDiff` read with their attributes, one per change request at its head commit and base branch, and drops the least recently read once they exceed `maxCachedDiffBytes`; a later read at the same head and base answers from memory for any Session, and a failed read is not kept. `changeRequestCommits` returns the provider's `commits` list, or null when the provider does not read commits; `changeRequestDiff` with chosen commits finds them in that list, refuses them as the Branch scope does, and reads `compare` from the first one's parent to the last, uncached. The commits the checkout has beyond the head come from `symbolic-ref`, `cat-file -e`, and `rev-list --count`, and are null when the checked-out branch is not the head branch, the head commit is absent, or Git fails. `changeRequestReview` acts on the same visible bindings, refuses a head other than the latest status's with `forgePanel/stale-head` before reading, and reads the provider's `readReview`, mapping `stale` to `forgePanel/stale-head`, `unsupported` to `forgePanel/review-unsupported`, and other failures to `forgePanel/review-failed`. It keeps one read per change request, keyed by head commit and update time, drops the least recently read once the kept reads exceed `maxCachedReviewBytes` as JSON, and reads again once a kept read is `reviewRefreshMs` old or the reader refreshes the view, since resolving a GitHub thread leaves the update time unchanged. `changeRequestStates` streams, for the Session list, the last known number, title, state, draft flag, checks rollup, review decision, and mergeability of every change request that a listed Session the caller may read binds: a `baseline` frame, then `changed` frames. One run serves every stream. Cancellation is observed before initialization and between frames; the last stream and plugin disposal await initialization and accepted writes, then close the run’s storage domain. A later run waits for that closure before reopening the domain and reading its stored states. Binding updates received during listing override its initial snapshot. It lists Sessions through `sessionQuery` without loading them, takes the visible bindings of a loaded Session from `ctx.forgeSession` and of another from its cached `forgeChangeRequests` summary, follows binding changes of loaded Sessions, and subscribes to each bound change request through `ctx.forge.watch`; closed requests use the idle polling cadence, and merged requests remain subscribed for explicit refresh. It stores every changed state in the `forge_panel_change_requests` storage domain under the SHA-256 digest of its URL and drops unbound stored states only when every listed Session has known bindings; a failed write is logged and the state stays in memory. The stream fails when the Host lacks the Session query, projection cache, storage, or Session store service. -The browser entry mounts the Remote, then the UI. One stream per Session feeds the tab, the header button, the New Session option, and the creation card; it opens with the first subscriber, closes with the last, reopens after a transport reset, and keeps the last state while the Session scope is retained. Releasing that scope closes the stream and removes its cached state. The New Session option fills `conversation.hero.options` and the worktree card `conversation.input.dock`. The worktree card shows a running creation, with Cancel calling `stopCreation` while a message waits for it, or the failed or stopped attempt a message waits after, with Retry calling `retryWorktree` and Continue without a worktree calling `cancelWorktree`. The tab shortens paths with the Host home from the Remote's Host facts, read again after each transport reset. The tab reports its visibility to the header button's pressed state. The header button collapses a docked tab or closes its floating tab. The toast lives in a `shell.overlay` entry so it outlives the tab. One stream of change request states feeds the Session row icons in `sidebar.session.row.trailing` and the hover card section in `sidebar.session.row.hover` while any of them is mounted; both take a Session's worktree and bindings from its Session list summary values. The change request card takes a change request, its snapshot, and optional actions, so another surface can reuse it. The changes view is the `forge-changes` resource tab type: its addresses, `dsh-resource://forge-changes//local` and `dsh-resource://forge-changes//change/`, name the source, and a navigation may name a file to scroll to. The tab type enables `keepMounted`, retaining visited bodies and their owning Session references until their tab records end. Its keyed panel hook subscribes only for the visible body; other panel surfaces may keep the shared Session stream open. Its body keeps the scope, base branch, chosen commits, lens, test file switch, and layout choices of each tab in a slot store, keeps viewed marks per Session in `localStorage` under `dsh.forge-viewed.v1.`, at most 20 sources per Session and 50 Sessions, reads through the Remote, and passes each file section values that keep their identity across its renders, including the tab's visibility, so a render redraws only the sections whose values changed and a visibility change redraws every section. An expanded file draws its lines, highlighted with the shared code highlighter in the same render, once its section first comes within 1200px of the scrollport, keeps them drawn after that, and until then holds a 22px row per drawn line; a chip title shows its name with the changes icon. +The browser entry mounts the Remote, then the UI. One stream per Session feeds the tab, the header button, the New Session option, and the creation card; it opens with the first subscriber, closes with the last, reopens after a transport reset, and keeps the last state while the Session scope is retained. Releasing that scope closes the stream and removes its cached state. The New Session option fills `conversation.hero.options` and the worktree card `conversation.input.dock`. The worktree card shows a running creation, with Cancel calling `stopCreation` while a message waits for it, or the failed or stopped attempt a message waits after, with Retry calling `retryWorktree` and Continue without a worktree calling `cancelWorktree`. The tab shortens paths with the Host home from the Remote's Host facts, read again after each transport reset. The tab reports its visibility to the header button's pressed state. The header button collapses a docked tab or closes its floating tab. The toast lives in a `shell.overlay` entry so it outlives the tab. One stream of change request states feeds the Session row icons in `sidebar.session.row.trailing` and the hover card section in `sidebar.session.row.hover` while any of them is mounted; both take a Session's worktree and bindings from its Session list summary values. The change request card takes a change request, its snapshot, and optional actions, so another surface can reuse it. The changes view is the `forge-changes` resource tab type: its addresses, `dsh-resource://forge-changes//local` and `dsh-resource://forge-changes//change/`, name the source, and a navigation may name a file to scroll to. The tab type enables `keepMounted`, retaining visited bodies and their owning Session references until their tab records end. Its keyed panel hook subscribes only for the visible body; other panel surfaces may keep the shared Session stream open. Its body keeps the scope, base branch, chosen commits, lens, test file switch, and layout choices of each tab in a slot store, keeps viewed marks per Session in `localStorage` under `dsh.forge-viewed.v1.`, at most 20 sources per Session and 50 Sessions, reads through the Remote, and passes each file section values that keep their identity across its renders, including the tab's visibility, so a render redraws only the sections whose values changed and a visibility change redraws every section. An expanded file draws its lines, highlighted with the shared code highlighter in the same render, once its section first comes within 1200px of the scrollport or a jump to one of its review threads targets it, keeps them drawn after that, and until then holds a 22px row per drawn line; a chip title shows its name with the changes icon. | Source | Responsibility | |---|---| @@ -96,6 +97,11 @@ The browser entry mounts the Remote, then the UI. One stream per Session feeds t | [`src/client/ReviewControls.tsx`](src/client/ReviewControls.tsx) | Lens, test file switch, and viewed progress | | [`src/client/CommitMenu.tsx`](src/client/CommitMenu.tsx) | Commit picker | | [`src/client/viewed-files.ts`](src/client/viewed-files.ts) | Viewed marks kept in the browser | +| [`src/client/ReviewThreads.tsx`](src/client/ReviewThreads.tsx) | Review thread cards and the outdated section | +| [`src/client/ThreadList.tsx`](src/client/ThreadList.tsx) | Thread list | +| [`src/client/review-threads.ts`](src/client/review-threads.ts) | Thread places, list filters, hunk excerpts, and thread quotes | +| [`src/client/thread-state.ts`](src/client/thread-state.ts) | Thread reads and their places in the shown changes | +| [`src/review-cache.ts`](src/review-cache.ts) | Review threads kept in memory | | [`src/client/FileLabel.tsx`](src/client/FileLabel.tsx) | Changed file label: name, then directory | | [`src/client/WorktreeToggle.tsx`](src/client/WorktreeToggle.tsx) | New Session worktree option | | [`src/client/WorktreeProgress.tsx`](src/client/WorktreeProgress.tsx) | Worktree creation and removed-worktree card | @@ -118,7 +124,7 @@ The browser entry mounts the Remote, then the UI. One stream per Session feeds t ## Model Experience -Indirectly, through the working-directory service and the Session's conversation: the notice about a Session's new worktree joins the first request's messages, Continue in the project queues the same kind of notice for the next request, and Create change request sends a user message that asks the Agent for a change request. Add to input contributes a frozen `## User Comment N` quote containing File, Side, Lines, Source, the diff hunk, and Comment; PR quotes also name the reviewed commit, local Branch quotes the base the view compared with, and quotes from chosen commits name them. These quotes enter the normal logged user message only when the composer is sent. Inspection, status, restoring, the Session list, and GitHub review submission add no model context. +Indirectly, through the working-directory service and the Session's conversation: the notice about a Session's new worktree joins the first request's messages, Continue in the project queues the same kind of notice for the next request, and Create change request sends a user message that asks the Agent for a change request. Add to input contributes a frozen `## User Comment N` quote containing File, Side, Lines, Source, the diff hunk, and Comment; PR quotes also name the reviewed commit, local Branch quotes the base the view compared with, and quotes from chosen commits name them. These quotes enter the normal logged user message only when the composer is sent. Inspection, status, restoring, the Session list, and GitHub review submission add no model context. Add to input on a review thread contributes a frozen `## Review Thread N` quote with File, Side, Lines, the commit those lines number, State, Source, the recorded diff hunk, and every comment's author, time, and body quoted line by line. #### KV Cache effect @@ -143,6 +149,7 @@ None for a new worktree, as its notice belongs to the first request of the Sessi - **Undrawn files** — until the reader scrolls near an expanded file, it holds 22 px per drawn line, which leaves out side-by-side pairing, wrapped lines, unchanged-line rows, and review cards, so the scroll range shifts a little as files draw; its saved review comments also appear only once it draws. - **Find in page over long diffs** — an expanded file draws its lines only once the reader scrolls near it, so the browser's find in page does not match lines of files further down until they are drawn; a page-wide search of the diff needs a find control of the view's own. - **Viewed files on the code host** — viewed marks of a change request stay in this browser and are not read from or written to GitHub's viewed state (`markFileAsViewed`) until the provider's review operations exist; another browser or device starts without them. +- **Review thread writes** — a write through one changes view shows in other open views of the change request at their next status, or after `reviewRefreshMs` for a resolve, which does not change the pull request's update time. GitHub keeps one pending review per user and pull request. A comment draft an earlier version kept in the browser can join the pending review only while its file and lines still match the shown diff; otherwise it can only be edited or deleted. A comment on chosen commits can only be added to the input. Minimized comments show like others, and avatars load from the code host's image server in the browser. - **Review layers** — the built-in rules cover common conventions only, so a repository records others in `.gitattributes`; a path cannot show Rust's inline `#[cfg(test)]` modules or which declarations a language exports, and the Interface layer keeps whole files, so finding changed exports needs a language analyzer that a later lens extension point can supply. `linguist-generated` is read only from the root `.gitattributes`, without nested `.gitattributes` files or attribute macros. - **Chosen commits** — a change request lists at most `maxCommits` commits of the provider, the oldest 250 for GitHub, while the Branch scope lists its newest `maxCommits`; a run must follow first parents, so commits of a merged branch can be shown one at a time but not together with the branch's own; a commit range is read from the host on every view; comments on chosen commits can only be added to the input, as a GitHub review addresses the head. - **Review page** — deferred: a left-navigation page that lists the user's change requests from the selected provider; the [decision note](../../../.agents/notes/implemented/feature/2026-10-09-forge-panel.md) records where it attaches. diff --git a/packages/experimental/client-ui-forge/README.zh.md b/packages/experimental/client-ui-forge/README.zh.md index ebe5c653ef..6960bca568 100644 --- a/packages/experimental/client-ui-forge/README.zh.md +++ b/packages/experimental/client-ui-forge/README.zh.md @@ -41,14 +41,15 @@ kind: "package-reference" - **变更视图**——展开的变更请求卡片上的“变更”一行与本地变更卡片会打开一个右侧边栏标签页,列出所有变更的文件。本地标签页名为“本地变更”,默认显示“分支”:工作树与未跟踪文件相对于分叉点的变更。它的标题栏写出当前检出的分支(分离 HEAD 时为缩写提交)与基准分支;点击基准分支打开可搜索的菜单:最前面是“默认”,即 Session 创建的 worktree 的基准提交,否则是 HEAD 与代码托管远端默认分支的合并基准;其后依次是远程跟踪分支与本地分支,各按最近提交排序,不含当前检出的分支,不在所创建的 worktree 中时也不含“默认”已经指向的远程跟踪分支。输入文字会立即筛选已列出的行,短暂停顿后列出名称包含该文字(不区分大小写)的分支;按 Enter 选择第一行。选择其他分支后,与 HEAD 和该分支的合并基准比较。标签页切换到其他范围时仍保留这个选择;关闭标签页或重新加载应用后回到“默认”。所选分支已不存在时,它的名称显示删除线;它与 HEAD 没有共同历史时,视图同样给出说明;两种情况都提供“使用默认基准分支”而不是“重试”。视图较窄时,先隐藏“包含未提交的修改”,再隐藏当前分支。“未提交”与 HEAD 比较,“未暂存”与暂存区比较,“已暂存”比较暂存区与 HEAD。变更请求的视图显示托管平台在其 head 处的 diff;当前检出分支就是该变更请求的源分支时,还会说明本地分支比该 head 多出几个提交。工具栏可以跳到某个文件、汇总变更行数、刷新,并在左右对比与单栏对比、自动换行与截断长行之间切换。访问过的变更标签页会在切换标签页与 Session、隐藏侧边栏及调整停靠位置时保持挂载,在 diff 未改变时保留文件折叠、大文件展开、上下文展开、布局与滚动位置。隐藏的变更视图释放面板订阅并推迟 diff 读取;返回时仅在最新 head 或本地摘要不同时重新读取。刷新替换 diff 后会丢弃展开的上下文,内容变化也可能移动阅读位置。视图隐藏时关闭临时菜单。关闭标签页或重新加载应用后不保留这些进度。每个文件是一张独立的卡片,带浅色底的标题在滚动时停在顶部。文件名在前,目录在后,用更小的浅色字显示,空间不够时目录先缩短;悬停时显示完整路径,重命名的文件显示新旧两条路径。每个文件带有新文件、已删除、重命名的标记(重命名标记写出原文件名,只换了目录时写出原路径),“分支”范围下的未跟踪文件还标“未提交”;文件菜单可以复制路径,本地变更可在侧边栏打开整个文件,变更请求可在浏览器中查看该文件在 head 处的页面。标题变窄时,路径、标记和“有新改动”会缩短,行数、“已审阅”和文件菜单始终完整显示。hunk 之间未变更的行折叠成一行,点击后从文件的新版本展开:工作树、“已暂存”时为暂存区,或经托管平台读取的 head 提交;读取 diff 之后文件又有修改时不会展开,直到视图重新读取。二进制文件与超过 `maxDiffBytes` 的未跟踪文件只显示一条说明;hunk 超过 1,000 行的文件先显示为一条写出变更行数的折叠条,点击后才绘制;前面的文件累计变更超过 5,000 行后,其后的文件默认收起。刷新与页面刷新快捷键、每次导航、变更请求的 head 变化,以及“分支”范围的摘要变化时,视图都会重新读取;变更请求的视图会先等到给出 head 的状态再读取,除非没有提供方服务它或那次轮询失败。head 已越过最新状态时,视图保持加载,等到比读取开始时更新的状态后按其 head 重新读取;该状态在读取期间已到达时立即重读。重新读取已显示的变更时,刷新图标会旋转。托管平台或其提供方因超过大小上限拒绝给出 diff 的变更请求(例如 GitHub 上输出超过提供方 `maxOutputBytes` 的 diff)显示“变更太大,无法在这里显示”并提供“在浏览器中查看”;其他读取失败提供“重试”,变更请求还提供“在浏览器中查看”。变更请求的 diff 在缓存期间对每个 head 提交与目标分支只下载一次,因此在同一 head 下重新打开、刷新与导航都不会再从托管平台读取。 - **分层、测试文件、已审阅与提交**——文件树上方的分层透镜保留全部文件,或“接口”“实现”“测试”中一层的文件,并显示各自的数量;不显示文件树时,工具栏以菜单提供透镜。仓库的声明优先:根目录 `.gitattributes` 把文件设为 `dsh-review-layer=test`、`interface` 或 `implementation` 时,文件属于对应的层;标为 `linguist-generated` 的文件属于“测试”。其次是可选的 `testPaths` 与 `interfacePaths`,它们追加在内置规则之前,默认为空。最后是按常见约定写的内置规则:Jest、Vitest、`go test`、pytest、RSpec、XCTest 与 .NET 的测试目录和文件、快照、本地化目录与 lockfile 属于“测试”;包清单、类型声明、头文件、类型存根与 Protocol Buffers、GraphQL、OpenAPI 等接口定义属于“接口”。其余文件属于“实现”。例如在 `.gitattributes` 中写 `*_test.go dsh-review-layer=test` 或 `api/**/*.yaml dsh-review-layer=interface`,即可记录仓库自己的约定。“隐藏测试文件”让文件树与 diff 都不显示“测试”层,也不列出被隐藏的文件,同时停用“测试”透镜。文件标题上的“已审阅”把该文件的这次改动标为已审阅并折叠它;工具栏显示已显示文件中已审阅的数量,按 `V` 标记或取消当前阅读的文件:焦点或文本光标所在的文件,否则是视图顶部的文件。改动与标记时不同的文件显示“有新改动”并重新展开。标记按 Session、变更来源、路径与改动摘要保存在本浏览器中,关闭标签页或重新加载后仍在;同一 Session 的多个标签页共用这些标记:在一个标签页中标记,其他标签页随之更新,且不会覆盖它们的标记。只改文件模式(例如 `chmod +x`)也算新改动。“提交评审”左侧,以及“分支”范围中基准分支右侧的“全部提交”按从旧到新列出提交,读取一次后保留到 head、本地分支或基准变化或刷新为止;单击只看一个提交,按住 Shift 单击看从上次单击的提交到这个提交的连续多个提交,这些提交必须依次是后一个的第一父提交:离开这条链的范围(例如跨越已合并分支的范围)会让菜单保持打开并说明原因;此时视图显示这些提交的改动,在最后一个提交读取未变更的行,提供“添加到输入框”,但不提供 GitHub 评论或评审。“分支”的提交不含未提交与未跟踪的文件。换基准分支或范围后回到全部提交;所选提交已不存在或不再是一条链时提供“查看全部提交”。 +- **评审讨论**——变更请求视图会叠加代码托管平台在所显示 head 处读到的评审讨论。行级讨论显示在它最后一行所在的行之后,位于写下时所在的那一侧;若该行折叠在未变更的行中,则显示在折叠行之后。讨论标明写下时的位置,每条评论显示头像、作者、时间和 Markdown 正文(不显示原始 HTML),并用标签标出变更请求作者、机器人账号,以及当前登录用户尚未提交的评审中的评论。已解决的讨论折叠成一行,可以展开。针对整个文件的讨论显示在文件开头;被后续提交改到而过期的讨论集中在文件的行之后,显示写下时那段 hunk 的末尾,并提供“查看当时的文件”,读取写下讨论时那个提交上的文件并标出相应的行。选择了部分提交时,只显示行号对应最后一个所选提交的新版本侧讨论。文件树和每个文件标题都显示未解决讨论数。每点击一次文件标题上的计数,就按文件中的显示顺序跳到该文件的下一条未解决讨论(所选提交中没有的讨论排在最后),到最后一条后回到第一条;工具栏的“讨论”按钮打开讨论列表。列表按文件树顺序分组,组内讨论的顺序与文件中相同,可显示未解决、已解决或全部讨论,默认显示未解决的讨论;点击讨论会跳到它的位置,若所选提交中没有该讨论,会先切换到全部提交。视图宽度不小于 1,040px 时列表停靠在文件旁;更窄时浮在文件之上,并在跳到讨论前先关闭;窄于 480px 时占满文件区的宽度。读取被截断时,列表会注明。讨论上提供“添加到输入框”(把整个讨论作为引用插入)、“在 GitHub 中查看”,以及当前登录用户可以执行的写操作。没有待提交评审时,回复框立即回复,其下拉菜单可以带着这条回复开始待提交评审;有待提交评审时,回复框把回复加入其中,因为 GitHub 会把用户的每条回复都加入待提交评审。“解决讨论”和“取消解决”切换讨论状态;用户自己评论的菜单可以编辑或删除该评论,删除前会先确认,删除讨论中唯一的评论会一并删除讨论,确认时会说明这一点。用户正在讨论中写回复或编辑评论时,即使讨论已被解决,也保持展开。代码托管平台拒绝写操作时保留输入的文字并说明原因;结果不明时会重新读取讨论,并请用户核对后再重试。每次写操作后都会重新读取讨论,因为解决讨论不会改变 GitHub pull request 的更新时间。视图显示期间,每收到一次状态就重新读取讨论;点击刷新后,即使面板还保留着之前的读取结果,也会从代码托管平台重新读取;读取失败时保留上次的讨论并提供重试,提供方不支持读取讨论时不显示讨论。 检查行先显示轮询预览。不完整时,卡片使用托管平台的总体状态而不显示失败总数,并注明已加载的检查数量尚不完整。打开列表后,经 `changeRequestChecks` 单独读取该 PR 的后续页,时限独立于轮询。读取失败时保留预览并提供重试。关闭列表、head 变化或组件卸载会取消读取,忽略迟到结果;重新打开会读取当前详情。Remote 要求 URL 是该 Session 可见的绑定,并拒绝 head 提交不一致的响应。 diff 按文件树的深度优先顺序排列:同层目录在前、文件在后,各组按显示名称以区分大小写的 UTF-16 码元顺序排序。压缩目录链作为一个完整名称参与比较。筛选或折叠文件树不会改变 diff 的顺序。点击 diff 内容区可将焦点移入。左右方向键按 diff 顺序跳到上一个、下一个文件并展开它;到达首尾时停留。上下方向键保留原有滚动行为。手动滚动后,文件跳转从视口顶部的文件继续。文本编辑、非折叠文本选区、组合键、菜单与文件树控件保留各自的键盘行为。 -`gitCommand`、`gitTimeoutMs`、`graceMs`、`maxOutputBytes`、`readinessTimeoutMs`、`maxBranches`、`worktreePrefix`、`maxDiffBytes`、`maxUntrackedFiles`、`maxCachedDiffBytes`、`maxCommits`、`testPaths` 与 `interfacePaths` 列在[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-experimental-client-ui-forge)中。 +`gitCommand`、`gitTimeoutMs`、`graceMs`、`maxOutputBytes`、`readinessTimeoutMs`、`maxBranches`、`worktreePrefix`、`maxDiffBytes`、`maxUntrackedFiles`、`maxCachedDiffBytes`、`maxCachedReviewBytes`、`reviewRefreshMs`、`maxCommits`、`testPaths` 与 `interfacePaths` 列在[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-experimental-client-ui-forge)中。 -“全部文件”打开可搜索的目录树,并把选中文件滚动到中间;只有一个子目录的路径会合并显示,重命名文件也可以按旧路径搜索。较宽的变更面板会在 diff 旁显示同一棵树,工具栏的“文件树”按钮按“左侧 → 右侧 → 隐藏”循环切换,默认显示在左侧。按钮的无障碍名称说明下一步操作,移动或隐藏文件树时焦点仍留在按钮上。移动或隐藏文件树,以及切换标签页与 Session 时保留搜索、折叠状态、选中文件和宽度。拖动分隔线,或聚焦分隔线后使用方向键,可以调整文件树宽度。文件与文件夹预留相同的展开箭头列,子项相对父目录向内缩进。本地变更与每个 PR 保留独立标签页。划选代码文字或通过行号选择同一已显示 hunk、同一侧的连续行,文字划选与复制都限定在起始侧。点击“+”打开纯文本评论框。使用鼠标时,悬停在某一行上也会在其行号旁显示“+”,行号仍可点击:两栏时显示在悬停的一侧,单栏时显示在该行所属的一侧;按下即选中这一行,拖动可在同一侧扩展范围,松开即打开评论框。评论框支持换行和输入法组合输入,只有点击操作按钮才提交。可拖动底边调整高度。“添加到输入框”将评论作为可移除的引用加入主输入框,引用显示文件名、侧与行号以及评论,悬停时显示文件路径;多条引用只会在用户发送主输入框时一起发送。GitHub 分段按钮用于开始或加入待提交评审,下拉菜单可以立即发布单条评论。评论在引用、暂存或发布后保留在对应代码旁,暂存评论可在那里编辑或删除。“请求更改”需要填写评审总结,弹窗在总结输入框旁说明此要求,并在切换评审决定时播报。PR 标题栏中的“提交评审”打开居中弹窗,只显示待提交数量、总结以及“评论”“批准”“请求更改”选项。新建和删除文件只显示有内容的一侧行号。待提交评审与评论记录按 Session 和页签保存在当前浏览器,包括最初评审的 head。切换 Session 或隐藏面板时保留;关闭页签会清空该页签的评论、总结与评审决定,重新打开从空评审开始。已发布到 GitHub 的评论与已加入主输入框的引用不受影响。head 变化后需要重新选择评论行。代码变化后的记录保留在文件末尾;文件已不在 diff 中时,记录显示在 diff 之后。页签保持打开时,结果不明的提交在重新加载后仍会阻止重复发送,直到用户检查 GitHub 并明确允许再次提交。 +“全部文件”打开可搜索的目录树,并把选中文件滚动到中间;只有一个子目录的路径会合并显示,重命名文件也可以按旧路径搜索。较宽的变更面板会在 diff 旁显示同一棵树,工具栏的“文件树”按钮按“左侧 → 右侧 → 隐藏”循环切换,默认显示在左侧。按钮的无障碍名称说明下一步操作,移动或隐藏文件树时焦点仍留在按钮上。移动或隐藏文件树,以及切换标签页与 Session 时保留搜索、折叠状态、选中文件和宽度。拖动分隔线,或聚焦分隔线后使用方向键,可以调整文件树宽度。文件与文件夹预留相同的展开箭头列,子项相对父目录向内缩进。本地变更与每个 PR 保留独立标签页。划选代码文字或通过行号选择同一已显示 hunk、同一侧的连续行,文字划选与复制都限定在起始侧。点击“+”打开纯文本评论框。使用鼠标时,悬停在某一行上也会在其行号旁显示“+”,行号仍可点击:两栏时显示在悬停的一侧,单栏时显示在该行所属的一侧;按下即选中这一行,拖动可在同一侧扩展范围,松开即打开评论框。评论框支持换行和输入法组合输入,只有点击操作按钮才提交。可拖动底边调整高度。“添加到输入框”将评论作为可移除的引用加入主输入框,引用显示文件名、侧与行号以及评论,悬停时显示文件路径;多条引用只会在用户发送主输入框时一起发送。读到评审讨论且用户可以评审时,GitHub 分段按钮会用这条评论在 GitHub 上开始用户的待提交评审,或把评论加入其中;评论随后显示为带“待提交”标签的讨论,提交评审之前只有用户自己能看到。下拉菜单可以立即发布单条评论;用户有待提交评审时 GitHub 会拒绝单条评论,因此这时没有该菜单。Agent 引用和已发布的评论保留在对应代码旁。“请求更改”需要填写评审总结,弹窗在总结输入框旁说明此要求,并在切换评审决定时播报。PR 标题栏中的“提交评审”打开居中弹窗,只显示待提交数量、总结以及“评论”“批准”“请求更改”选项。有待提交评审时提交该评审,结果不明的提交与直接提交一样,在用户到 GitHub 核对之前阻止再次提交;“丢弃评审”在确认后删除该评审及其中的评论;没有待提交评审时,把总结作为一次评审发布。在用户自己的 PR 上,GitHub 只允许作者评论,因此“批准”和“请求更改”不可用。新建和删除文件只显示有内容的一侧行号。总结、评审决定,以及 Agent 引用与已发布评论的记录按 Session 和页签保存在当前浏览器,包括最初评审的 head。切换 Session 或隐藏面板时保留;关闭页签会清空它们,重新打开从空总结开始。待提交评审、已发布到 GitHub 的评论与已加入主输入框的引用不受影响。早期版本保存在此浏览器中的评论草稿保留在对应代码旁,带“浏览器草稿”标签,可以编辑、删除或加入待提交评审;存在待提交评审时,它们会让“提交评审”保持不可用;没有待提交评审时,“提交评审”把它们连同总结一起发布。head 变化后需要重新选择评论行。代码变化后的记录保留在文件末尾;文件已不在 diff 中时,记录显示在 diff 之后。页签保持打开时,结果不明的提交在重新加载后仍会阻止重复发送,直到用户检查 GitHub 并明确允许再次提交。 ----- @@ -69,11 +70,11 @@ worktree 请求是一条 `plugin:client-ui-forge/worktree` 记录,由 `forgeWo 每次检查还会判断 worktree 是否缺失:Session 的目录位于所创建的 worktree 内,`ctx.fs.lstat` 在那里找不到目录,再由源仓库中的 `show-ref` 判断分支是否还在。 -Session 在所创建的 worktree 中工作时,`localDiff` 以它的 `baseCommit` 为分叉点;否则按代码托管远端的顺序,对每个远端依次运行 `symbolic-ref --quiet --short refs/remotes//HEAD` 与 `merge-base HEAD` 找出分叉点;找不到时 `branch` 范围以 `forgePanel/no-fork-point` 拒绝。`branch` 范围指定了 `refs/heads/` 或 `refs/remotes/` 下的基准引用时,`show-ref --verify` 找到该引用后改用 `merge-base HEAD` 与它的结果;引用不存在时以 `forgePanel/base-missing` 拒绝,HEAD 与它没有共同历史时以 `forgePanel/no-fork-point` 拒绝;其他引用名在运行 Git 之前即被拒绝。它以固定的 `a/`、`b/` 前缀和 `core.quotePath=false` 运行 `diff --no-ext-diff --no-textconv --submodule=short --ignore-submodules=dirty --no-color -M`,分别与分叉点、HEAD(第一次提交之前为空树)、暂存区比较,或带 `--cached` 与 HEAD 比较。读取补丁与统计前会查询 Git 配置,应用命令级 clean/process filter 覆盖。配置读取失败或被截断时停止比较:`localDiff` 报告 `forgePanel/filter-config-failed`,修正 Git 配置或读取上限后可重试;统计失败时本地变更卡片保持隐藏。过滤器枚举在读取补丁时使用 `maxDiffBytes` 上限,统计时使用 `maxOutputBytes` 上限。未跟踪文件由 `ls-files --others --exclude-standard -z` 列出,最多 `maxUntrackedFiles` 个,其余计为未列出;它们经 `ctx.fs` 读取并作为新文件加入,前 8,000 字节含 NUL 字节或不是 UTF-8 时视为二进制。补丁、文件列表或文件超过 `maxDiffBytes` 时以 `forgePanel/diff-too-large` 拒绝,目录不在检出中时以 `forgePanel/not-a-checkout` 拒绝。宿主用 jsdiff 把补丁解析为文件与 hunk,浏览器不会收到原始补丁。Host 为每个文件计算由路径、状态、hunk 以及 `old mode` 与 `new mode` 行组成的摘要(二进制改动加上 blob 名,未跟踪的二进制文件加上内容),并先按根目录 `.gitattributes` 中的 `dsh-review-layer` 与 `linguist-generated` 行确定分层(后面的行覆盖前面的行,不是层名的值视为未指定;模式按 [`src/wildmatch.ts`](src/wildmatch.ts) 中 Git 的 wildmatch 规则匹配,取反模式与 Git 一样跳过),再用 picomatch(包含点文件)依次匹配 `testPaths`、`interfacePaths` 与 [`src/layers.ts`](src/layers.ts) 中的内置规则。`.gitattributes` 的读取来源:“已暂存”读暂存区,其他本地范围读工作树,所选提交读最后一个提交,变更请求经 `fileText` 读 head 或最后一个所选提交,文件不存在时按没有处理。`localCommits` 用 `log --no-show-signature --topo-order --reverse` 列出分叉点到 HEAD 之间最新的 `maxCommits` 个提交,因此列表以 HEAD 的提交结尾。带所选提交的“分支”范围比较第一个提交的第一个父提交(根提交用空树)与最后一个提交;不是完整对象名、不在列表中或顺序颠倒的提交以 `forgePanel/commits-missing` 拒绝,第一父提交不是列表中前一个提交的所选提交以 `forgePanel/commits-not-linear` 拒绝;`localText` 经 `show` 读取那个最后的提交。`localText` 读取一个文件的新版本:“已暂存”经 `show :` 从暂存区读取,其余经 `ctx.fs` 读取;离开检出的路径会被拒绝。`changeRequestDiff` 与 `changeRequestText` 只作用于该 Session 中由提供方服务的可见绑定,否则以 `forgePanel/not-bound` 拒绝;它们经提供方的 `diff` 与 `fileText` 读取绑定最新状态中的 head 提交,补丁与它的 `.gitattributes` 同时读取,补丁读取失败时取消 `.gitattributes` 的读取,两者都结束后才给出结果,补丁的失败优先于 `.gitattributes` 的失败,`too-large` 失败以 `forgePanel/diff-too-large` 拒绝,`stale` 失败(head 已越过该状态)以 `forgePanel/stale-head` 拒绝,尚未读到状态或托管平台以其他原因拒绝时以 `forgePanel/diff-failed` 拒绝。`stale` 的 diff 会立即重新轮询该变更请求(每个 head 提交一次)且不缓存,因此不会有补丁被存放在它不描述的 head 下。Host 保留 `changeRequestDiff` 读到的补丁及其属性,每个变更请求一份,按 head 提交与目标分支区分,总量超过 `maxCachedDiffBytes` 时丢弃最久未读的;之后在同一 head 与目标分支下的读取不论来自哪个 Session 都从内存返回,读取失败的结果不保留。`changeRequestCommits` 返回提供方 `commits` 的列表,提供方不读取提交时返回 null;带所选提交的 `changeRequestDiff` 在该列表中找到它们,按与“分支”范围相同的规则拒绝,并从第一个提交的父提交到最后一个提交读取 `compare`,不缓存。本地分支比 head 多出的提交数由 `symbolic-ref`、`cat-file -e` 与 `rev-list --count` 得出;当前检出分支不是源分支、本地没有 head 提交或 Git 失败时为 null。 +Session 在所创建的 worktree 中工作时,`localDiff` 以它的 `baseCommit` 为分叉点;否则按代码托管远端的顺序,对每个远端依次运行 `symbolic-ref --quiet --short refs/remotes//HEAD` 与 `merge-base HEAD` 找出分叉点;找不到时 `branch` 范围以 `forgePanel/no-fork-point` 拒绝。`branch` 范围指定了 `refs/heads/` 或 `refs/remotes/` 下的基准引用时,`show-ref --verify` 找到该引用后改用 `merge-base HEAD` 与它的结果;引用不存在时以 `forgePanel/base-missing` 拒绝,HEAD 与它没有共同历史时以 `forgePanel/no-fork-point` 拒绝;其他引用名在运行 Git 之前即被拒绝。它以固定的 `a/`、`b/` 前缀和 `core.quotePath=false` 运行 `diff --no-ext-diff --no-textconv --submodule=short --ignore-submodules=dirty --no-color -M`,分别与分叉点、HEAD(第一次提交之前为空树)、暂存区比较,或带 `--cached` 与 HEAD 比较。读取补丁与统计前会查询 Git 配置,应用命令级 clean/process filter 覆盖。配置读取失败或被截断时停止比较:`localDiff` 报告 `forgePanel/filter-config-failed`,修正 Git 配置或读取上限后可重试;统计失败时本地变更卡片保持隐藏。过滤器枚举在读取补丁时使用 `maxDiffBytes` 上限,统计时使用 `maxOutputBytes` 上限。未跟踪文件由 `ls-files --others --exclude-standard -z` 列出,最多 `maxUntrackedFiles` 个,其余计为未列出;它们经 `ctx.fs` 读取并作为新文件加入,前 8,000 字节含 NUL 字节或不是 UTF-8 时视为二进制。补丁、文件列表或文件超过 `maxDiffBytes` 时以 `forgePanel/diff-too-large` 拒绝,目录不在检出中时以 `forgePanel/not-a-checkout` 拒绝。宿主用 jsdiff 把补丁解析为文件与 hunk,浏览器不会收到原始补丁。Host 为每个文件计算由路径、状态、hunk 以及 `old mode` 与 `new mode` 行组成的摘要(二进制改动加上 blob 名,未跟踪的二进制文件加上内容),并先按根目录 `.gitattributes` 中的 `dsh-review-layer` 与 `linguist-generated` 行确定分层(后面的行覆盖前面的行,不是层名的值视为未指定;模式按 [`src/wildmatch.ts`](src/wildmatch.ts) 中 Git 的 wildmatch 规则匹配,取反模式与 Git 一样跳过),再用 picomatch(包含点文件)依次匹配 `testPaths`、`interfacePaths` 与 [`src/layers.ts`](src/layers.ts) 中的内置规则。`.gitattributes` 的读取来源:“已暂存”读暂存区,其他本地范围读工作树,所选提交读最后一个提交,变更请求经 `fileText` 读 head 或最后一个所选提交,文件不存在时按没有处理。`localCommits` 用 `log --no-show-signature --topo-order --reverse` 列出分叉点到 HEAD 之间最新的 `maxCommits` 个提交,因此列表以 HEAD 的提交结尾。带所选提交的“分支”范围比较第一个提交的第一个父提交(根提交用空树)与最后一个提交;不是完整对象名、不在列表中或顺序颠倒的提交以 `forgePanel/commits-missing` 拒绝,第一父提交不是列表中前一个提交的所选提交以 `forgePanel/commits-not-linear` 拒绝;`localText` 经 `show` 读取那个最后的提交。`localText` 读取一个文件的新版本:“已暂存”经 `show :` 从暂存区读取,其余经 `ctx.fs` 读取;离开检出的路径会被拒绝。`changeRequestDiff` 与 `changeRequestText` 只作用于该 Session 中由提供方服务的可见绑定,否则以 `forgePanel/not-bound` 拒绝;它们经提供方的 `diff` 与 `fileText` 读取绑定最新状态中的 head 提交,补丁与它的 `.gitattributes` 同时读取,补丁读取失败时取消 `.gitattributes` 的读取,两者都结束后才给出结果,补丁的失败优先于 `.gitattributes` 的失败,`too-large` 失败以 `forgePanel/diff-too-large` 拒绝,`stale` 失败(head 已越过该状态)以 `forgePanel/stale-head` 拒绝,尚未读到状态或托管平台以其他原因拒绝时以 `forgePanel/diff-failed` 拒绝。`stale` 的 diff 会立即重新轮询该变更请求(每个 head 提交一次)且不缓存,因此不会有补丁被存放在它不描述的 head 下。Host 保留 `changeRequestDiff` 读到的补丁及其属性,每个变更请求一份,按 head 提交与目标分支区分,总量超过 `maxCachedDiffBytes` 时丢弃最久未读的;之后在同一 head 与目标分支下的读取不论来自哪个 Session 都从内存返回,读取失败的结果不保留。`changeRequestCommits` 返回提供方 `commits` 的列表,提供方不读取提交时返回 null;带所选提交的 `changeRequestDiff` 在该列表中找到它们,按与“分支”范围相同的规则拒绝,并从第一个提交的父提交到最后一个提交读取 `compare`,不缓存。本地分支比 head 多出的提交数由 `symbolic-ref`、`cat-file -e` 与 `rev-list --count` 得出;当前检出分支不是源分支、本地没有 head 提交或 Git 失败时为 null。`changeRequestReview` 同样只作用于可见的绑定;head 与最新状态的 head 不同时,读取前就以 `forgePanel/stale-head` 拒绝;随后调用提供方的 `readReview`,把 `stale` 映射为 `forgePanel/stale-head`、`unsupported` 映射为 `forgePanel/review-unsupported`、其余失败映射为 `forgePanel/review-failed`。每个变更请求保留一次读取结果,以 head 提交和更新时间为键;保留的结果按 JSON 计超过 `maxCachedReviewBytes` 时,最久未读的先被丢弃;保留时间达到 `reviewRefreshMs` 后,或读者刷新视图时,重新读取,因为解决 GitHub 讨论不会改变更新时间。 `changeRequestStates` 为会话列表推送调用方可读的、已列出的 Session 所绑定的每个变更请求的最近编号、标题、状态、草稿标记、检查汇总、评审结论与可合并性:先是一个 `baseline` 帧,之后是 `changed` 帧。所有流共用一次运行。初始化之前和帧之间均响应取消;最后一条流结束及插件卸载会等待初始化与已接受的写入完成,再关闭本次运行的存储域。后续运行会等待该域关闭后重新打开,并读取已存状态。列举期间收到的绑定更新优先于初始快照。它经 `sessionQuery` 列出 Session 而不加载它们,已加载 Session 的可见绑定取自 `ctx.forgeSession`,其他 Session 的取自缓存的 `forgeChangeRequests` 摘要;它跟随已加载 Session 的绑定变化,并经 `ctx.forge.watch` 订阅每个已绑定的变更请求;已关闭的按空闲间隔轮询,已合并的保留订阅以接收显式刷新结果。每个变化了的状态以其 URL 的 SHA-256 摘要为键存入 `forge_panel_change_requests` 存储域,仅在所有已列出 Session 的绑定均已知时删除无人绑定的已存状态;写入失败时记录日志,状态仍保留在内存中。宿主缺少 Session 查询、投影缓存、存储或 Session 存储服务时,流以失败结束。 -浏览器入口先挂载 Remote,再挂载界面。每个 Session 一条流,同时供给标签页、标题栏按钮、新会话选项与创建卡片;第一个订阅方出现时打开,最后一个离开时关闭,传输重置后重新打开,在 Session scope 保留期间保存最后的状态。释放该 scope 时关闭流并移除缓存状态。新会话选项填入 `conversation.hero.options`,worktree 卡片填入 `conversation.input.dock`。worktree 卡片显示正在进行的创建,有消息在等待时“取消”调用 `stopCreation`;或显示消息等待时失败或被停止的那次尝试,“重试”调用 `retryWorktree`,“不使用工作树”调用 `cancelWorktree`。标签页用 Remote 宿主信息中的宿主主目录缩短路径,每次传输重置后重新读取。标签页把自己是否可见报告给标题栏按钮的按下状态。标题栏按钮收起停靠的标签页,或关闭其浮动标签页。toast 位于 `shell.overlay` 条目中,因此比标签页存在得更久。只要 `sidebar.session.row.trailing` 中的会话行图标或 `sidebar.session.row.hover` 中的悬浮卡片部分有一个已挂载,就由同一条变更请求状态流供给它们;两者都从会话列表的摘要值中读取 Session 的 worktree 与绑定。变更请求卡片接收变更请求、它的快照与可选操作,其他界面可以复用。变更视图是 `forge-changes` 资源标签页类型:它的地址 `dsh-resource://forge-changes//local` 与 `dsh-resource://forge-changes//change/` 指明来源,导航参数可以指定要滚动到的文件。标签页类型启用 `keepMounted`,将访问过的正文及其所属 Session 引用保留至标签页记录结束。它的 keyed panel hook 仅为可见正文订阅;其他面板界面仍可能保持共享 Session 流开启。它的正文用 slot store 按标签页保存范围、基准分支、所选提交、透镜、测试文件开关与布局选择,按 Session 把已审阅标记保存在 `localStorage` 的 `dsh.forge-viewed.v1.` 下(每个 Session 最多 20 个来源,最多 50 个 Session),经 Remote 读取,并且传给每个文件段的值(包括标签页可见性)在多次渲染之间保持同一标识,所以一次渲染只重绘值有变化的文件段,可见性变化时重绘全部文件段。展开的文件在它的段第一次进入滚动区域 1200px 范围内时才绘制各行,并在同一次渲染中用共享的代码高亮器高亮,此后一直保留;在此之前按每个绘制行 22px 占位;标签页标题显示变更图标与视图名称。 +浏览器入口先挂载 Remote,再挂载界面。每个 Session 一条流,同时供给标签页、标题栏按钮、新会话选项与创建卡片;第一个订阅方出现时打开,最后一个离开时关闭,传输重置后重新打开,在 Session scope 保留期间保存最后的状态。释放该 scope 时关闭流并移除缓存状态。新会话选项填入 `conversation.hero.options`,worktree 卡片填入 `conversation.input.dock`。worktree 卡片显示正在进行的创建,有消息在等待时“取消”调用 `stopCreation`;或显示消息等待时失败或被停止的那次尝试,“重试”调用 `retryWorktree`,“不使用工作树”调用 `cancelWorktree`。标签页用 Remote 宿主信息中的宿主主目录缩短路径,每次传输重置后重新读取。标签页把自己是否可见报告给标题栏按钮的按下状态。标题栏按钮收起停靠的标签页,或关闭其浮动标签页。toast 位于 `shell.overlay` 条目中,因此比标签页存在得更久。只要 `sidebar.session.row.trailing` 中的会话行图标或 `sidebar.session.row.hover` 中的悬浮卡片部分有一个已挂载,就由同一条变更请求状态流供给它们;两者都从会话列表的摘要值中读取 Session 的 worktree 与绑定。变更请求卡片接收变更请求、它的快照与可选操作,其他界面可以复用。变更视图是 `forge-changes` 资源标签页类型:它的地址 `dsh-resource://forge-changes//local` 与 `dsh-resource://forge-changes//change/` 指明来源,导航参数可以指定要滚动到的文件。标签页类型启用 `keepMounted`,将访问过的正文及其所属 Session 引用保留至标签页记录结束。它的 keyed panel hook 仅为可见正文订阅;其他面板界面仍可能保持共享 Session 流开启。它的正文用 slot store 按标签页保存范围、基准分支、所选提交、透镜、测试文件开关与布局选择,按 Session 把已审阅标记保存在 `localStorage` 的 `dsh.forge-viewed.v1.` 下(每个 Session 最多 20 个来源,最多 50 个 Session),经 Remote 读取,并且传给每个文件段的值(包括标签页可见性)在多次渲染之间保持同一标识,所以一次渲染只重绘值有变化的文件段,可见性变化时重绘全部文件段。展开的文件在它的段第一次进入滚动区域 1200px 范围内,或跳转到它的某个评审讨论时,才绘制各行,并在同一次渲染中用共享的代码高亮器高亮,此后一直保留;在此之前按每个绘制行 22px 占位;标签页标题显示变更图标与视图名称。 | 源码 | 职责 | |---|---| @@ -96,6 +97,11 @@ Session 在所创建的 worktree 中工作时,`localDiff` 以它的 `baseCommi | [`src/client/ReviewControls.tsx`](src/client/ReviewControls.tsx) | 分层透镜、测试文件开关与已审阅进度 | | [`src/client/CommitMenu.tsx`](src/client/CommitMenu.tsx) | 提交选择器 | | [`src/client/viewed-files.ts`](src/client/viewed-files.ts) | 保存在浏览器中的已审阅标记 | +| [`src/client/ReviewThreads.tsx`](src/client/ReviewThreads.tsx) | 评审讨论卡片与已过期区域 | +| [`src/client/ThreadList.tsx`](src/client/ThreadList.tsx) | 讨论列表 | +| [`src/client/review-threads.ts`](src/client/review-threads.ts) | 讨论位置、列表筛选、hunk 摘录与讨论引用 | +| [`src/client/thread-state.ts`](src/client/thread-state.ts) | 读取讨论并确定它们在所显示变更中的位置 | +| [`src/review-cache.ts`](src/review-cache.ts) | 保存在内存中的评审讨论 | | [`src/client/FileLabel.tsx`](src/client/FileLabel.tsx) | 变更文件的标签:文件名在前,目录在后 | | [`src/client/WorktreeToggle.tsx`](src/client/WorktreeToggle.tsx) | 新会话的工作树选项 | | [`src/client/WorktreeProgress.tsx`](src/client/WorktreeProgress.tsx) | worktree 创建卡片与 worktree 缺失卡片 | @@ -118,7 +124,7 @@ Session 在所创建的 worktree 中工作时,`localDiff` 以它的 `baseCommi ## 模型体验 -间接影响,经由工作目录服务与 Session 的对话:关于 Session 新 worktree 的通知会加入第一次请求的消息,“在项目目录继续”会为下一次请求排入同类通知,“创建变更请求”会发送一条请 Agent 创建变更请求的用户消息。“添加到输入框”提供以 `## User Comment N` 开头的冻结引用,包含 File、Side、Lines、Source、diff hunk 与 Comment;PR 引用还包含评审的提交,本地“分支”引用还包含视图比较的基准,来自所选提交的引用还会注明这些提交。只有发送主输入框后,这些引用才进入正常记录的用户消息。检查、状态、恢复、会话列表与 GitHub 评审提交不会增加模型上下文。 +间接影响,经由工作目录服务与 Session 的对话:关于 Session 新 worktree 的通知会加入第一次请求的消息,“在项目目录继续”会为下一次请求排入同类通知,“创建变更请求”会发送一条请 Agent 创建变更请求的用户消息。“添加到输入框”提供以 `## User Comment N` 开头的冻结引用,包含 File、Side、Lines、Source、diff hunk 与 Comment;PR 引用还包含评审的提交,本地“分支”引用还包含视图比较的基准,来自所选提交的引用还会注明这些提交。只有发送主输入框后,这些引用才进入正常记录的用户消息。检查、状态、恢复、会话列表与 GitHub 评审提交不会增加模型上下文。对评审讨论使用“添加到输入框”时,会加入一段固定的 `## Review Thread N` 引用,包含 File、Side、Lines、这些行号所在的提交、State、Source、记录下的 diff hunk,以及逐行引用的每条评论的作者、时间和正文。 #### KV Cache 影响 @@ -143,6 +149,7 @@ Session 在所创建的 worktree 中工作时,`localDiff` 以它的 `baseCommi - **尚未绘制的文件**——读者滚动到展开的文件附近之前,它按每个绘制行 22 px 占位,没有计入左右对比的配对、自动换行、未变更行按钮和评审卡片,所以文件绘制时滚动范围会略有变化;它已保存的评审评论也要等它绘制后才显示。 - **长 diff 中的页内查找**——展开的文件要等读者滚动到附近才绘制各行,所以浏览器的页内查找在更靠后的文件绘制之前匹配不到它们的行;要在整个 diff 中查找,需要视图自己的查找控件。 - **代码托管平台上的已审阅状态**——变更请求的已审阅标记只保存在本浏览器中,在提供方评审接口完成之前,不读取也不写入 GitHub 的已审阅状态(`markFileAsViewed`);换浏览器或设备后没有这些标记。 +- **评审讨论的写入**——在一个变更视图中的写操作,会在该变更请求的其他已打开视图收到下一次状态时显示;解决讨论不会改变 pull request 的更新时间,要等到 `reviewRefreshMs` 之后才显示。GitHub 每个用户在每个 pull request 上只保留一个待提交评审。早期版本保存在浏览器中的评论草稿,只有其文件和行仍与所显示的 diff 一致时才能加入待提交评审,否则只能编辑或删除。对所选提交的评论只能添加到输入框。被折叠隐藏的评论与其他评论显示方式相同;头像由浏览器从代码托管平台的图片服务器加载。 - **分层**——内置规则只覆盖常见约定,其他约定由仓库写在 `.gitattributes` 中;按路径无法识别 Rust 的内联 `#[cfg(test)]` 模块,也无法判断一种语言导出了哪些声明,“接口”层保留整个文件,找出变更的导出需要语言分析器,可由之后的透镜扩展点提供。`linguist-generated` 只读取根目录的 `.gitattributes`,不读子目录中的 `.gitattributes`,也不展开属性宏。 - **所选提交**——变更请求最多列出提供方的 `maxCommits` 个提交(GitHub 为最早的 250 个),“分支”范围则列出最新的 `maxCommits` 个;范围必须沿第一父提交相连,因此已合并分支的提交只能逐个查看,不能与本分支的提交一起查看;每次查看提交范围都从托管平台读取;所选提交上的评论只能添加到输入框,因为 GitHub 评审针对 head。 - **代码审查页**——待办:在左侧导航中新增一个页面,列出用户在所选提供方上的变更请求;[决策笔记](../../../.agents/notes/implemented/feature/2026-10-09-forge-panel.zh.md)记录了它的接入位置。 diff --git a/packages/experimental/client-ui-forge/src/client/ChangeRequestCard.tsx b/packages/experimental/client-ui-forge/src/client/ChangeRequestCard.tsx index 5a90b9e6b3..a5f1abbab2 100644 --- a/packages/experimental/client-ui-forge/src/client/ChangeRequestCard.tsx +++ b/packages/experimental/client-ui-forge/src/client/ChangeRequestCard.tsx @@ -76,6 +76,7 @@ const FAILURE: Record = { 'unauthenticated': 'change.failure.unauthenticated', 'too-large': 'change.failure.unavailable', 'stale': 'change.failure.unavailable', + 'unsupported': 'change.failure.unavailable', 'unavailable': 'change.failure.unavailable', } diff --git a/packages/experimental/client-ui-forge/src/client/ChangedFiles.module.css b/packages/experimental/client-ui-forge/src/client/ChangedFiles.module.css index 4a57098d20..2006c2b546 100644 --- a/packages/experimental/client-ui-forge/src/client/ChangedFiles.module.css +++ b/packages/experimental/client-ui-forge/src/client/ChangedFiles.module.css @@ -5,6 +5,8 @@ .row { box-sizing: border-box; display: flex; align-items: center; gap: 6px; width: 100%; min-width: 0; min-height: 30px; padding: 4px 6px; border: 0; border-radius: var(--dsw-radius-sm); background: transparent; color: inherit; font: inherit; text-align: start; cursor: pointer; } .row svg { flex: none; } .name { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +/* Unresolved host review threads of a file, in the thread count chip treatment of the file header. */ +.threads { flex: none; min-width: 16px; padding: 0 5px; box-sizing: border-box; border-radius: var(--dsw-radius-xs); background: color-mix(in srgb, var(--dsw-alias-state-business-primary) 12%, transparent); color: var(--dsw-alias-state-business-primary); font-size: 11px; line-height: 16px; text-align: center; } .selected { background: var(--dsw-alias-interactive-bg-hover); } .chevron { display: inline-flex; flex: 0 0 12px; } .collapsed { transform: rotate(-90deg); } diff --git a/packages/experimental/client-ui-forge/src/client/ChangedFiles.tsx b/packages/experimental/client-ui-forge/src/client/ChangedFiles.tsx index 995bae454d..eb24d62b51 100644 --- a/packages/experimental/client-ui-forge/src/client/ChangedFiles.tsx +++ b/packages/experimental/client-ui-forge/src/client/ChangedFiles.tsx @@ -25,6 +25,8 @@ export interface ChangedFilesProps extends PropsLocale { readonly jump: (path: string) => void /** A menu row participates in the shared menu's keyboard walk. */ readonly menu?: boolean + /** Unresolved host review threads by file path; files without any are absent. */ + readonly threadCounts?: ReadonlyMap } function Rows({ nodes, depth, props }: { @@ -32,10 +34,11 @@ function Rows({ nodes, depth, props }: { readonly depth: number readonly props: ChangedFilesProps }): ReactNode { - const { state, toggle, jump, menu, t } = props + const { state, toggle, jump, menu, threadCounts, t } = props return nodes.map((node) => { const directory = node.kind === 'directory' const expanded = directory && (state.query.trim() !== '' || state.collapsed[node.path] !== true) + const threads = node.kind === 'file' ? threadCounts?.get(node.path) ?? 0 : 0 const label = node.kind === 'file' && node.file.previousPath !== null ? t('diff.renamedPath', { from: node.file.previousPath, path: node.path }) : node.path return
@@ -54,6 +57,7 @@ function Rows({ nodes, depth, props }: { {directory ? : } {node.name} + {threads > 0 && {threads}} {node.kind === 'file' && } diff --git a/packages/experimental/client-ui-forge/src/client/ChangesTab.module.css b/packages/experimental/client-ui-forge/src/client/ChangesTab.module.css index 8f9ea2c8e6..9183d560e4 100644 --- a/packages/experimental/client-ui-forge/src/client/ChangesTab.module.css +++ b/packages/experimental/client-ui-forge/src/client/ChangesTab.module.css @@ -333,6 +333,7 @@ } .body { + position: relative; display: flex; flex: 1; min-height: 0; @@ -865,3 +866,69 @@ .code[data-single-side]:not([data-wrap]) .line { grid-template-columns: var(--forge-number-width) 1.4em max-content; } .reviewFile { padding: 12px 0; } .reviewFile > h3 { margin: 0 10px; font-size: 12px; font-weight: 500; overflow-wrap: anywhere; } + +/* The unresolved thread count of a file opens the thread list at the file. */ +.threadCount { + flex: none; + height: 20px; + padding: 0 6px; + border: 0; + border-radius: var(--dsw-radius-xs); + background: color-mix(in srgb, var(--dsw-alias-state-business-primary) 12%, transparent); + color: var(--dsw-alias-state-business-primary); + font: inherit; + font-size: 11px; + line-height: 20px; + white-space: nowrap; + cursor: pointer; +} + +/* Drawn inside the button, since the file title clips what overflows it. */ +.threadCount:focus-visible { + outline: var(--dsw-focus-ring-width) solid var(--dsw-focus-ring-color, var(--dsw-alias-state-business-primary)); + outline-offset: -1px; +} + +@media (hover: hover) { + .threadCount:hover { background: color-mix(in srgb, var(--dsw-alias-state-business-primary) 20%, transparent); } +} + +/* A view narrower than 480px shows the count alone. */ +.threadCountNumber { display: none; } + +@container forge-changes (max-width: 479px) { + .threadCountText { display: none; } + .threadCountNumber { display: inline; } +} + +/* Opens the thread list; pressed while the list shows. */ +.threadsToggle { + display: inline-flex; + flex: none; + align-items: center; + gap: 6px; + height: 28px; + padding: 0 8px; + border: 0; + border-radius: var(--dsw-radius-sm); + background: transparent; + color: var(--dsw-alias-label-primary); + font: inherit; + white-space: nowrap; + cursor: pointer; +} + +.threadsToggle[aria-pressed='true'] { background: var(--dsw-alias-interactive-bg-hover); } + +@media (hover: hover) { + .threadsToggle:hover { background: var(--dsw-alias-interactive-bg-hover); } +} + +.threadsTotal { + padding: 0 5px; + border-radius: var(--dsw-radius-xs); + background: var(--forge-fill); + color: var(--dsw-alias-label-secondary); + font-size: 11px; + line-height: 16px; +} diff --git a/packages/experimental/client-ui-forge/src/client/ChangesTab.tsx b/packages/experimental/client-ui-forge/src/client/ChangesTab.tsx index dd01665747..babc227996 100644 --- a/packages/experimental/client-ui-forge/src/client/ChangesTab.tsx +++ b/packages/experimental/client-ui-forge/src/client/ChangesTab.tsx @@ -25,12 +25,16 @@ import { import type { HostObservable, InjectFace, PropsLocale, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots' import type { SidebarRightTabInfo } from '@deepseek-ai/dsh-client-ui-sidebar-right/client' import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol' +import { assertNever } from '@deepseek-ai/dsh-util-values' import { fileAddressFor, pathPartsOf } from '@deepseek-ai/dsh-util-workspace-path' import type { ForgeBaseBranch, ForgeBaseBranches, ForgeChangeRequestDiff, ForgeCommitRange, ForgeDiffFile, ForgeLocalCommits, ForgeLocalDiff, ForgeLocalScope, ForgePanelChangeRequest, ForgePanelState, } from '../types.ts' -import type { ForgeCommitList, ForgeReviewRequest, ForgeReviewResult } from '@deepseek-ai/dsh-experimental-forge/types' +import type { + ForgeCommitList, ForgeReviewData, ForgeReviewRequest, ForgeReviewResult, ForgeReviewThread, ForgeReviewWrite, ForgeReviewWriteResult, + ForgeThreadId, +} from '@deepseek-ai/dsh-experimental-forge/types' import { sameReviewSource, type ReviewQueue } from './review-queue.ts' import { ReviewThread, useFileReview } from './ReviewThread.tsx' import type { ReviewActions } from './ReviewComposer.tsx' @@ -51,6 +55,10 @@ import { drawnLines, matchesHunks, textLines } from './diff-rows.ts' import { ChangeRequestGlyph } from './glyphs.tsx' import type { ForgePanelKey, NS } from './locales.ts' import { RefreshGlyph } from './RefreshGlyph.tsx' +import type { FileThreads, ThreadActions, ThreadFocus, ThreadWrite } from './ReviewThreads.tsx' +import { inFileOrder, type ThreadFilter } from './review-threads.ts' +import { usePlacedThreads, useThreadRead, type PlacedThread } from './thread-state.ts' +import { ThreadList } from './ThreadList.tsx' import type { PanelSnapshot } from './source.ts' import { numberOf, openChangeRequestOf, TONE_LABEL, toneOf } from './status.ts' import css from './ChangesTab.module.css' @@ -60,6 +68,12 @@ type Translate = PropsLocale['t'] /** Kind of a local scope. */ type ScopeKind = ForgeLocalScope['kind'] +/** A file the view scrolls to once, and the thread card it centers there with whether that card takes the focus. */ +interface Wanted { + readonly path: string + readonly center: { readonly id: ForgeThreadId; readonly focus: boolean } | null +} + /** Business face of the changes tab body. */ export interface ChangesTabInjected { /** Append a frozen comment to the main input without submitting it. */ @@ -90,6 +104,14 @@ export interface ChangesTabInjected { readonly viewedFiles: ViewedFiles /** Read one file of a change request at a commit. */ readonly changeRequestText: (url: string, commit: string, path: string) => Promise> + /** Read the review threads of a change request at the head of its latest status; `signal` aborts the read. */ + readonly changeRequestReview: ( + url: string, headSha: string, fresh: boolean, signal: AbortSignal, + ) => Promise> + /** Write to the review threads or the pending review of a change request; never retries a write. */ + readonly changeRequestReviewWrite: (url: string, write: ForgeReviewWrite) => Promise> + /** Quote a whole review thread of the change request at `url` in the main input without submitting it. */ + readonly addThreadToInput: (thread: ForgeReviewThread, url: string, range: string | null) => boolean /** Open a URL outside the app. */ readonly openLink: (url: string) => void /** Copy a path to the clipboard and report the outcome. */ @@ -134,6 +156,12 @@ type ChangesData = readonly fileUrls: Readonly> } +/** Why the code host did not take a review write, and whether it may have applied it. */ +interface WriteRefusal { + readonly message: string + readonly unknown: boolean +} + /** Unchanged lines read for one loaded diff: each file's new side and its expanded gaps. */ interface Expansion { readonly data: ChangesData | null @@ -427,8 +455,8 @@ function OrphanReviews({ path, actions, t }: PropsLocale & { */ export function ChangesTab({ useTabInfo, sessionId, useStore, actions, usePanel, reconnect, localDiff, diffBases, localText, localCommits, changeRequestDiff, - changeRequestText, changeRequestCommits, viewedFiles, - openLink, copyPath, createChangeRequest, addReviewToInput, reviewQueue, submitReview, report, t, + changeRequestText, changeRequestCommits, changeRequestReview, changeRequestReviewWrite, viewedFiles, + openLink, copyPath, createChangeRequest, addReviewToInput, addThreadToInput, reviewQueue, submitReview, report, t, }: ChangesTabProps): ReactNode { const { tab } = useTabInfo() const { navigation, signal } = tab @@ -476,8 +504,49 @@ export function ChangesTab({ setReviewBusy(false) } } + // Every write that may have changed the threads reads them again; writes run one at a time, so a write that starts a + // pending review settles before the next write looks for one. + const [reviewRevision, setReviewRevision] = useState(0) + const writing = useRef>(Promise.resolve()) + /** + * Send one write after the earlier ones. + * @returns undefined once the host took it, else its message and whether its outcome is unknown. + */ + const sendWrite = (url: string, write: ForgeReviewWrite): Promise => { + const run = async (): Promise => { + const response = await changeRequestReviewWrite(url, write) + if (!response.ok) { + if (response.error.code === 'forgePanel/not-bound') { + return { message: t('thread.writeFailed', { message: response.error.message }), unknown: false } + } + setReviewRevision(value => value + 1) + return { message: t('thread.writeUnknown'), unknown: true } + } + const result = response.value + if (result.ok) { + setReviewRevision(value => value + 1) + return undefined + } + switch (result.code) { + case 'unsupported': return { message: t('thread.writeUnsupported'), unknown: false } + case 'failed': + setReviewRevision(value => value + 1) + return { message: t('thread.writeFailed', { message: result.message }), unknown: false } + case 'stale': return { message: t('thread.writeStale'), unknown: false } + case 'unknown': + setReviewRevision(value => value + 1) + return { message: t('thread.writeUnknown'), unknown: true } + /* v8 ignore next -- closed ForgeReviewWriteResult code union exhaustiveness guard */ + default: return assertNever(result.code, 'ForgeReviewWriteResult.code') + } + } + const next = writing.current.then(run, run) + writing.current = next + return next + } + const writeReview = async (url: string, write: ForgeReviewWrite): Promise => (await sendWrite(url, write))?.message const choices = useStore(store => store.byTab[tab.id]) - const [wanted, setWanted] = useState(null) + const [wanted, setWanted] = useState(null) const [treeState, setTreeState] = useState({ query: '', collapsed: {}, selected: null }) const [treePosition, setTreePosition] = useState('left') const [treeWidth, setTreeWidth] = useState(0) @@ -491,7 +560,7 @@ export function ChangesTab({ if (path === undefined) return setTreeState(value => ({ ...value, selected: path })) setChosen(value => ({ ...value, [path]: true })) - setWanted(path) + setWanted({ path, center: null }) }, [choices, navigation.revision, navigation.params, actions, tab.id]) // The tab's choices end with its record. useEffect(() => { @@ -564,6 +633,23 @@ export function ChangesTab({ return () => { controller.abort() } }, [tab.visible, read, refused, waiting, source, localScope, changeCommits, dataKey, localDiff, changeRequestDiff]) const data = loaded !== null && loaded.key === dataKey ? loaded.data : null + // Threads show only while they were read at the head of the latest status and, for the whole change request, at + // the head the shown diff was read at, so their positions number the shown files. + const prHead = entry?.snapshot?.headSha ?? null + const prAuthor = entry?.snapshot?.author ?? null + const threadRead = useThreadRead({ visible: tab.visible, url: source.kind === 'change' ? source.url : null, head: prHead, + updatedAt: entry?.snapshot?.updatedAt ?? null, statusAt, attempt, revision: reviewRevision, read: changeRequestReview }) + const review = data?.kind === 'change' && threadRead.review !== null && threadRead.review.headSha === prHead + && (data.commits !== null || data.headSha === prHead) ? threadRead.review : null + const placed = usePlacedThreads(review, data?.kind === 'change' ? { head: prHead ?? '', end: data.headSha, commits: data.commits } : null) + const [threadList, setThreadList] = useState<{ + readonly open: boolean + readonly filter: ThreadFilter + /** Whether the reader just opened the list and it has not taken the focus yet. */ + readonly claim: boolean + }>({ open: false, filter: 'unresolved', claim: false }) + const threadsToggle = useRef(null) + const [focus, setFocus] = useState(null) const allFiles = useMemo(() => filesInTreeOrder(changedFileTree(data?.files ?? [])), [data]) const files = useMemo(() => allFiles.filter(file => shownBy(file, lens, hideTests)), [allFiles, lens, hideTests]) const lensCounts = useMemo(() => Object.fromEntries(LENSES.map(item => [item, @@ -597,14 +683,25 @@ export function ChangesTab({ useLayoutEffect(() => { if (!tab.visible || wanted === null || data === null) return // A file the lens or the test switch hides is shown before the view scrolls to it. - const hidden = allFiles.find(file => file.path === wanted && !shownBy(file, lens, hideTests)) + const hidden = allFiles.find(file => file.path === wanted.path && !shownBy(file, lens, hideTests)) if (hidden !== undefined) { if (lens !== 'all') actions.lensed(tab.id, 'all') if (hideTests && hidden.layer === 'test') actions.toggledTests(tab.id) return } // The browser's scroll anchoring keeps the section in place while the sections above it draw their lines. - sections.current.get(wanted)?.scrollIntoView({ block: 'start' }) + const section = sections.current.get(wanted.path) + section?.scrollIntoView({ block: 'start' }) + // A thread the reader opened from the thread list or a file's unresolved count centers inside its file, which the jump + // expanded and revealed; the jump ends here, so a later jump to the file stops at its header. + const { center } = wanted + if (center !== null) { + /* v8 ignore next 4 -- a centered thread's file is drawn and its card unfolded, so both are found. */ + const card = [...section?.querySelectorAll('[data-forge-thread]') ?? []] + .find(element => element.dataset.forgeThread === center.id) + card?.scrollIntoView({ block: 'center' }) + if (center.focus) card?.focus({ preventScroll: true }) + } if (scrollport.current !== null) jumpPosition.current = { data, top: scrollport.current.scrollTop } setWanted(null) }, [tab.visible, wanted, data, allFiles, lens, hideTests, actions, tab.id]) @@ -665,16 +762,68 @@ export function ChangesTab({ return list } - // A review addresses the head commit, so it is submitted from the view of the whole change request. + // A review addresses the head commit, so it is submitted from the view of the whole change request. A pending review on + // the code host is submitted or discarded there; without one, the summary and any comment drafts kept in the browser + // are published as one review. + const pendingReview = review?.pendingReview ?? null + // Logins compare without case, as GitHub's do. + const ownChangeRequest = review?.viewer != null && prAuthor !== null && review.viewer.toLowerCase() === prAuthor.toLowerCase() + const finishWrite = async (send: () => Promise, done: ForgePanelKey): Promise => { + if (reviewRunning.current) return + reviewRunning.current = true + setReviewBusy(true) + setReviewError(null) + try { + const failure = await send() + if (failure !== undefined) { + setReviewError(failure) + return + } + report(done) + setReviewOpen(false) + } finally { + reviewRunning.current = false + setReviewBusy(false) + } + } const reviewForm = tab.visible && data !== null && reviewOpen && data.kind === 'change' && data.commits === null && { setReviewOpen(false) }} + url={data.url} headSha={data.headSha} pending={pendingReview} own={ownChangeRequest} busy={reviewBusy} error={reviewError} + close={() => { setReviewOpen(false) }} check={() => { openLink(data.url) }} reconcile={() => { queue.finish(false); setReviewError(null) }} submit={() => { const latest = queue.getSnapshot() - void publishReview(data.url, { kind: 'review', headSha: data.headSha, event: latest.event, - body: latest.body, comments: latest.comments.map(item => item.comment) }, url => queue.finish(true, url)) + if (pendingReview === null) { + void publishReview(data.url, { kind: 'review', headSha: data.headSha, event: latest.event, + body: latest.body, comments: latest.comments.map(item => item.comment) }, url => queue.finish(true, url)) + return + } + // The submission is kept as the write to reconcile until the host answers, so an unknown outcome blocks another + // submission, which would otherwise publish a second review once the pending review no longer reads. + void finishWrite(async () => { + if (!queue.begin({ kind: 'review', headSha: data.headSha, event: latest.event, body: latest.body, comments: [] })) { + return t('review.saveFailed') + } + const refusal = await sendWrite(data.url, { kind: 'submit-pending', headSha: data.headSha, review: pendingReview.id, + event: latest.event, body: latest.body }) + if (refusal === undefined) { + if (!queue.finish(true)) report('review.saveFailed') + return undefined + } + if (!refusal.unknown) queue.finish(false) + return refusal.message + }, 'review.submitted') + }} + discard={pendingReview === null ? undefined : () => { + void finishWrite(() => writeReview(data.url, { kind: 'discard-pending', headSha: data.headSha, review: pendingReview.id }), 'review.discarded') }} t={t} /> + /** Add a comment to the pending review on the code host at the head the comment was selected on. */ + const addPending = (selection: ReviewSelection): Promise => { + if (selection.source.kind !== 'change') return Promise.resolve(t('review.stale')) + const { path, side, startLine, endLine, body } = selection.comment + return writeReview(selection.source.url, { kind: 'add-pending', headSha: selection.source.headSha, comment: { path, side, startLine, endLine, body } }) + } + const recordActions: ReviewActions = { source: shownSource ?? (source.kind === 'local' ? { kind: 'local', scope, base: null, baseRef: baseRefOf(localScope), commits: commitsOf(localScope) } @@ -686,10 +835,57 @@ export function ChangesTab({ .filter(path => !data?.files.some(file => file.path === path)) const orphanRecords = absentPaths.map(path => ) - const jump = (path: string): void => { + // Thread groups keep their identity across renders that change neither the threads nor what their cards share, so + // only the sections whose threads changed redraw. + const url = data?.kind === 'change' ? data.url : null + const threadActions = useMemo((): ThreadActions | null => review === null || url === null ? null : { + author: prAuthor, + addToInput: (thread, range) => addThreadToInput(thread, url, range), + openLink, + readText: (commit, path) => changeRequestText(url, commit, path), + inputFailed: () => { live.current.report('thread.inputFailed') }, + focused: focus, + writes: { + write: (write: ThreadWrite) => live.current.writeReview(url, { ...write, headSha: review.headSha }), + reviewStarted: review.pendingReview !== null, + canReview: review.viewerCanReview, + }, + }, [review, url, prAuthor, addThreadToInput, openLink, changeRequestText, focus]) + const fileThreads = useMemo(() => new Map(threadActions === null ? [] + : [...placed.files].map(([path, group]) => [path, { ...group, actions: threadActions }])), [placed.files, threadActions]) + /** Show a file's next unresolved thread in display order after the one last shown, or its first. */ + const nextThread = (path: string): void => { + const order = inFileOrder(placed.entries.filter(({ thread }) => thread.path === path && !thread.resolved), + allFiles.find(file => file.path === path)) + const next = order[(order.findIndex(({ thread }) => thread.id === focus?.id) + 1) % order.length] + /* v8 ignore next -- the count that calls this shows only while the file has an unresolved thread. */ + if (next !== undefined) openThread(next, false) + } + /** Close the thread list at the reader's request and return the focus to its toggle. */ + const closeThreadList = (): void => { + setThreadList(value => ({ ...value, open: false })) + threadsToggle.current?.focus() + } + /** + * Show a thread: all commits for a thread the chosen ones do not hold, whose diff holds the file of every thread with a + * position at the head, then its file, with the thread unfolded and centered; `focusCard` moves the focus to it. A + * thread on a file the shown changes lack opens on the host. + */ + const openThread = ({ thread, place }: PlacedThread, focusCard: boolean): void => { + if (place.kind === 'elsewhere') actions.committed(tab.id, null) + else if (!allFiles.some(file => file.path === thread.path)) { + const url = thread.comments[0]?.url ?? null + if (url !== null) openLink(url) + return + } + setFocus(value => ({ id: thread.id, revision: (value?.revision ?? 0) + 1 })) + setRevealed(value => new Set([...value, thread.path])) + jump(thread.path, { id: thread.id, focus: focusCard }) + } + const jump = (path: string, center: Wanted['center'] = null): void => { setTreeState(value => ({ ...value, selected: path })) setChosen(value => ({ ...value, [path]: true })) - setWanted(path) + setWanted({ path, center }) } /** * The file being read: the file last jumped to while the scroll stays there, else the first file whose section still @@ -738,7 +934,7 @@ export function ChangesTab({ const section = sections.current.get(file.path) const viewport = scrollport.current if (viewed && section !== undefined && viewport !== null - && section.getBoundingClientRect().top < viewport.getBoundingClientRect().top) setWanted(file.path) + && section.getBoundingClientRect().top < viewport.getBoundingClientRect().top) setWanted({ path: file.path, center: null }) // A new mark collapses the file through its default; clearing a mark expands it. setChosen(({ [file.path]: _choice, ...value }) => viewed ? value : { ...value, [file.path]: true }) } @@ -765,8 +961,11 @@ export function ChangesTab({ // during render rather than in an effect because the file menus read their actions while this same render draws them; // an effect would hand them the previous diff's links. A render React discards leaves values derived from the same // props and state, which the retried render assigns again. - const live = useRef({ data, expandedByDefault, expand, markViewed, fileActions, publishReview, report, t }) - live.current = { data, expandedByDefault, expand, markViewed, fileActions, publishReview, report, t } + const callbacks = { + data, expandedByDefault, expand, markViewed, fileActions, publishReview, writeReview, addPending, report, nextThread, t, + } + const live = useRef(callbacks) + live.current = callbacks const handlers = useMemo((): DiffFileHandlers => ({ toggle: (file) => { const byDefault = live.current.expandedByDefault(file) @@ -792,26 +991,31 @@ export function ChangesTab({ if (element === null) sections.current.delete(path) else sections.current.set(path, element) }, + nextThread: (path) => { live.current.nextThread(path) }, reach, }), [reach]) - const reviewStarted = reviewState.comments.length > 0 + const reviewStarted = pendingReview !== null const publishingBlocked = reviewState.uncertain !== null - // Comments on a commit range or on local changes go to the input only; a whole change request also takes GitHub comments. - const publishable = data?.kind === 'change' && data.commits === null + // Comments on a commit range or on local changes go to the input only; a whole change request also takes GitHub comments: + // into its pending review once the threads say the user may review, and on their own while the user has no pending + // review, since GitHub refuses a single comment beside one. + const whole = data?.kind === 'change' && data.commits === null + const queueable = whole && review?.viewerCanReview === true + const single = whole && pendingReview === null const fileReview = useMemo((): ReviewActions | undefined => shownSource === null ? undefined : { source: shownSource, addToInput: addReviewToInput, records: queue, openLink, reviewStarted, onQuoted: (selection) => { if (!queue.recordAgent(selection)) live.current.report('review.saveFailed') }, publishingBlocked, - ...publishable ? { - queue: selection => queue.add(selection), - publish: selection => selection.source.kind === 'change' + ...queueable ? { queue: (selection: ReviewSelection) => live.current.addPending(selection) } : {}, + ...single ? { + publish: (selection: ReviewSelection) => selection.source.kind === 'change' ? live.current.publishReview(selection.source.url, { kind: 'comment', headSha: selection.source.headSha, comment: selection.comment }, url => queue.published(selection, url)) : Promise.resolve(live.current.t('review.stale')), } : {}, - }, [shownSource, addReviewToInput, queue, openLink, reviewStarted, publishingBlocked, publishable]) + }, [shownSource, addReviewToInput, queue, openLink, reviewStarted, publishingBlocked, queueable, single]) let body: ReactNode if (data === null) { @@ -868,6 +1072,8 @@ export function ChangesTab({ wrap={wrap} badge={badgeOf(file, data, t)} tooltip={pathTooltipOf(file, t)} + threads={fileThreads.get(path)} + drawNow={wanted !== null && wanted.center !== null && wanted.path === path} viewed={viewedStateOf(marks, path, file.digest)} handlers={handlers} t={t} @@ -883,6 +1089,7 @@ export function ChangesTab({ filter: (query) => { setTreeState(value => ({ ...value, query })) }, toggle: (path) => { setTreeState(value => ({ ...value, collapsed: { ...value.collapsed, [path]: value.collapsed[path] !== true } })) }, jump, + ...review === null ? {} : { threadCounts: placed.unresolved }, } // The toolbar collapses every file while any is expanded, as the files on screen show, and expands every file otherwise. const anyExpanded = files.some(isExpanded) @@ -908,7 +1115,8 @@ export function ChangesTab({ ? { actions.based(tab.id, next) }} commitMenu={commitMenu} createChangeRequest={createChangeRequest} t={t} /> - : { setReviewOpen(true) }} t={t} />} {!reviewOpen && reviewState.error !== null && {t(reviewState.error === 'load' ? 'review.loadFailed' : 'review.saveFailed')}} {!reviewOpen && reviewState.uncertain !== null && !reviewBusy && source.kind === 'change' &&
@@ -931,6 +1139,14 @@ export function ChangesTab({
) diff --git a/packages/experimental/client-ui-forge/src/client/DiffFile.tsx b/packages/experimental/client-ui-forge/src/client/DiffFile.tsx index 10a039cc6d..e07bb2f722 100644 --- a/packages/experimental/client-ui-forge/src/client/DiffFile.tsx +++ b/packages/experimental/client-ui-forge/src/client/DiffFile.tsx @@ -20,6 +20,8 @@ import { drawnLines, segmentsOf, splitRows, type DiffRow, type SplitCell, type S import { codeSideAt, readCodeSelection } from './code-selection.ts' import { reviewMatches, selectReviewLines, type ReviewSelection } from './review.ts' import { ReviewThread, useFileReview } from './ReviewThread.tsx' +import { OutdatedThreads, ThreadCard, type FileThreads, type LineThread, type ThreadActions } from './ReviewThreads.tsx' +import { gapOf } from './review-threads.ts' import type { FileReviewState } from './review-queue.ts' import { ReviewComposer, type ReviewActions } from './ReviewComposer.tsx' import reviewCss from './ReviewComposer.module.css' @@ -59,6 +61,8 @@ export interface DiffFileHandlers { readonly actions: (file: ForgeDiffFile) => readonly DiffFileAction[] /** Receive a file's section element, which scrolling to the file targets, or null once it unmounts. */ readonly section: (path: string, element: HTMLElement | null) => void + /** Show a file's next unresolved host thread in display order after the last one shown, or its first. */ + readonly nextThread: (path: string) => void /** Tells each expanded section when it comes within reach of the scrollport, which draws its lines. */ readonly reach: SectionReach } @@ -91,6 +95,10 @@ export interface DiffFileProps { readonly tooltip: string /** Whether the reader marked this change viewed, or marked an earlier change of the file. */ readonly viewed: ViewedState + /** Review threads of the file from the code host, or undefined while none are read; the view keeps their identity. */ + readonly threads?: FileThreads | undefined + /** Whether the section draws its lines at once, as the target of a thread jump, whose card must exist to be centered. */ + readonly drawNow?: boolean | undefined /** Actions shared by every section of the view. */ readonly handlers: DiffFileHandlers /** Forge panel copy. */ @@ -158,8 +166,8 @@ function pairKind(pair: SplitRow): 'context' | 'change' { } /** The hunks of one file with their collapsed and expanded unchanged lines. */ -function Lines({ file, text, open, handlers, split, wrap, review, visible, comments, t }: Pick & { readonly comments: FileReviewState }): ReactNode { +function Lines({ file, text, open, handlers, split, wrap, review, visible, comments, threads, t }: Pick & { readonly comments: FileReviewState }): ReactNode { const lines = typeof text === 'object' ? text : undefined const columns = split && file.additions > 0 && file.deletions > 0 const singleSide = file.status === 'added' ? 'R' : file.status === 'deleted' ? 'L' : null @@ -327,6 +335,17 @@ function Lines({ file, text, open, handlers, split, wrap, review, visible, comme remaining.delete(thread) } } + // A host thread follows the row of its last line, or the collapsed unchanged lines that hold it. + const unplaced = new Set(threads === undefined ? [] : threads.lines.map(item => ({ ...item, actions: threads.actions }))) + const threadCard = (item: LineThread & { readonly actions: ThreadActions }, columns: boolean): ReactNode => + + const appendThreads = (old: number | null, next: number | null): void => { + for (const item of unplaced) { + if ((item.place.side === 'L' ? old : next) !== item.place.endLine) continue + rows.push(threadCard(item, columns)) + unplaced.delete(item) + } + } const endsAt = (old: number | null, next: number | null): boolean => selection !== null && (selection.comment.side === 'L' ? old : next) === selection.comment.endLine for (const [at, segment] of prepared.entries()) { @@ -336,6 +355,11 @@ function Lines({ file, text, open, handlers, split, wrap, review, visible, comme {segment.count === null ? t('diff.unchangedRest') : t('diff.unchanged', { count: segment.count.toLocaleString('en-US') })} ) + for (const item of unplaced) { + if (gapOf(file, item.place.side, item.place.endLine) !== segment.index) continue + rows.push(threadCard(item, columns)) + unplaced.delete(item) + } } else if (columns) { for (const [index, pair] of splitRows(segment.rows).entries()) { rows.push(
) } + for (const item of unplaced) rows.push(threadCard(item, false)) if (!inserted) rows.push(editor) return
0 && (!large || revealed) } -function Body(props: DiffFileProps): ReactNode { - const { file, large, revealed, handlers, review, t } = props +/** The file's lines or the note that replaces them, with its saved comments; host threads on lines follow when no lines show. */ +function Content(props: DiffFileProps): ReactNode { + const { file, large, revealed, handlers, review, threads, t } = props const comments = useFileReview(review, file.path) const records = review === undefined ? null : comments.threads.map(thread => ) - if (file.binary) return <>

{t('diff.binary')}

{records} - if (file.oversized) return <>

{t('diff.fileTooLarge')}

{records} - if (file.hunks.length === 0) return records + const lineThreads = threads?.lines.map(item => ) + if (file.binary) return <>

{t('diff.binary')}

{records}{lineThreads} + if (file.oversized) return <>

{t('diff.fileTooLarge')}

{records}{lineThreads} + if (file.hunks.length === 0) return <>{records}{lineThreads} if (large && !revealed) { // A large file starts as one collapsed strip, drawn and opened like the collapsed unchanged lines. return ( <>{records} + {records}{lineThreads} ) } return } +/** Host threads on the whole file, the lines, then the host threads that later commits made outdated. */ +function Body(props: DiffFileProps): ReactNode { + const { threads, t } = props + return <> + {threads?.file.map(thread => )} + + {threads !== undefined && } + +} + /** File actions live only while their owning tab is visible. */ function FileMenu({ name, file, handlers, t }: { readonly name: string @@ -458,17 +498,19 @@ function FileMenu({ name, file, handlers, t }: { } /** - * Render one file of a diff. Until the section first comes within reach of the scrollport, an expanded file that - * draws lines shows a box of about their height instead. + * Render one file of a diff. Until the section first comes within reach of the scrollport or a thread jump targets it, + * an expanded file that draws lines shows a box of about their height instead. * @param props - the file, its section and gap state, layout choices, shared actions, and copy. * @returns the file section. */ function DiffFileSection(props: DiffFileProps): ReactNode { - const { file, expanded, large, revealed, badge, tooltip, viewed, handlers, t } = props + const { file, expanded, large, revealed, badge, tooltip, viewed, threads, handlers, t } = props const name = file.path.slice(file.path.lastIndexOf('/') + 1) const element = useRef(null) const [reached, setReached] = useState(false) - const waiting = expanded && !reached && drawsLines(file, large, revealed) + // A thread jump draws the section for good, so it does not fall back to the box once the jump ends. + if (props.drawNow === true && !reached) setReached(true) + const waiting = expanded && !reached && props.drawNow !== true && drawsLines(file, large, revealed) useEffect(() => { /* v8 ignore next -- React attaches the section before it runs effects */ if (!waiting || element.current === null) return @@ -500,6 +542,15 @@ function DiffFileSection(props: DiffFileProps): ReactNode { {viewed === 'changed' && ( {t('viewed.changed')} )} + {threads !== undefined && threads.unresolved > 0 && ( + + + + )} {badge !== '' && {badge}} diff --git a/packages/experimental/client-ui-forge/src/client/ReviewComposer.tsx b/packages/experimental/client-ui-forge/src/client/ReviewComposer.tsx index 94407dfee8..82e482c35f 100644 --- a/packages/experimental/client-ui-forge/src/client/ReviewComposer.tsx +++ b/packages/experimental/client-ui-forge/src/client/ReviewComposer.tsx @@ -15,7 +15,7 @@ export interface ReviewActions { readonly source: ReviewSource /** Browser records shared by the changes tab. */ readonly records?: ReviewQueue - /** Whether another comment already started a pending review. */ + /** Whether the signed-in user has a pending review on the code host that the next comment joins. */ readonly reviewStarted?: boolean /** Open the confirmed publication URL. */ readonly openLink?: (url: string) => void @@ -27,26 +27,32 @@ export interface ReviewActions { readonly onQuoted?: (selection: ReviewSelection) => void /** Publish one comment; an error string preserves the editor. */ readonly publish?: (selection: ReviewSelection) => Promise - /** Keep one comment for the final review; false preserves the editor. */ - readonly queue?: (selection: ReviewSelection) => boolean + /** Add one comment to the pending review on the code host, starting one when needed; an error string preserves the editor. */ + readonly queue?: (selection: ReviewSelection) => Promise } -function GitHubAction({ disabled, busy, started, queue, publish, t }: PropsLocale & { +/** + * Render a primary action with an optional second action in its menu. + * @param props - the main action, the optional menu action, the menu's name, and availability. + * @returns the split button. + */ +export function SplitAction({ disabled, label, run, menuLabel, menu, other }: { readonly disabled: boolean - readonly busy: boolean - readonly started: boolean - readonly queue: () => void - readonly publish: (() => void) | undefined + readonly label: string + readonly run: () => void + /** Accessible name of the menu button. */ + readonly menuLabel: string + /** Label of the action in the menu, or undefined without one. */ + readonly other: string | undefined + readonly menu: () => void }): ReactNode { const [open, setOpen] = useState(false) return
- - {publish !== undefined && { setOpen(false) }} + + {other !== undefined && { setOpen(false) }} anchor={}> - { setOpen(false); publish() }}>{t('review.publish')} + aria-label={menuLabel} onClick={() => { setOpen(value => !value) }}>}> + { setOpen(false); menu() }}>{other} }
} @@ -73,13 +79,14 @@ export function ReviewComposer({ selection, actions, close, visible = true, spli useEffect(() => { input.current?.focus() }, []) const comment = (): ReviewSelection => ({ ...selection, comment: { ...selection.comment, body: body.current } }) const range = reviewRange(selection.comment) - const publish = async (): Promise => { - if (running.current || actions.publish === undefined) return + /** Send the comment to the code host, closing the form once it is taken and keeping its text otherwise. */ + const send = async (destination: ((selection: ReviewSelection) => Promise) | undefined): Promise => { + if (running.current || destination === undefined) return running.current = true setBusy(true) setError(null) try { - const failure = await actions.publish(comment()) + const failure = await destination(comment()) if (failure === undefined) close() else setError(failure) } catch (_error) { @@ -108,14 +115,12 @@ export function ReviewComposer({ selection, actions, close, visible = true, spli if (actions.addToInput(selected)) { actions.onQuoted?.(selected); close() } else setError(t('review.inputFailed')) }}>{t('review.addToInput')} - {visible && actions.queue !== undefined && { - if (actions.queue?.(comment()) === true) close() - else setError(t('review.saveFailed')) - }} publish={actions.publish === undefined ? undefined : () => { void publish() }} t={t} />} + {visible && actions.queue !== undefined && { void send(actions.queue) }} menuLabel={t('review.githubActions')} + other={actions.publish === undefined ? undefined : t('review.publish')} menu={() => { void send(actions.publish) }} />} {actions.queue === undefined && actions.publish !== undefined && } + disabled={busy || actions.publishingBlocked === true || empty} onClick={() => { void send(actions.publish) }}>{t('review.publish')}}
diff --git a/packages/experimental/client-ui-forge/src/client/ReviewControls.module.css b/packages/experimental/client-ui-forge/src/client/ReviewControls.module.css index a08dc8e88e..655cf83171 100644 --- a/packages/experimental/client-ui-forge/src/client/ReviewControls.module.css +++ b/packages/experimental/client-ui-forge/src/client/ReviewControls.module.css @@ -1,6 +1,7 @@ -/* Review controls of the changes toolbar. The lens draws the segmented track and raised indicator of the shared - segmented control at the toolbar's 28px control height and 12px text, with each segment's file count after its label. */ -.lens { +/* Review controls of the changes toolbar. The segmented radio group of the lens and the thread list's filter draws the + track and raised indicator of the shared segmented control at the toolbar's 28px control height and 12px text, with + each segment's count after its label. */ +.segmented { box-sizing: border-box; display: grid; grid-auto-columns: minmax(0, 1fr); diff --git a/packages/experimental/client-ui-forge/src/client/ReviewControls.tsx b/packages/experimental/client-ui-forge/src/client/ReviewControls.tsx index 735c0148c4..b6765c158a 100644 --- a/packages/experimental/client-ui-forge/src/client/ReviewControls.tsx +++ b/packages/experimental/client-ui-forge/src/client/ReviewControls.tsx @@ -1,7 +1,7 @@ /** * Review controls of the changes toolbar: the lens that keeps the files of one review layer, as a full-width * radio group above the file tree or as a menu where no tree shows; the switch that hides test files; and the - * share of shown files the reader marked viewed. + * share of shown files the reader marked viewed. The thread list shares the segmented radio group. */ import { useRef, useState, type KeyboardEvent, type ReactNode } from 'react' @@ -33,17 +33,35 @@ export interface LensProps extends PropsLocale { readonly choose: (lens: ChangesLens) => void } +/** One segment of a {@link SegmentedChoice}. */ +export interface Segment { + /** Value the segment chooses. */ + readonly value: Value + /** Localized label. */ + readonly label: string + /** Count shown after the label, or null for none. */ + readonly count: number | null + /** Localized hover text of a disabled segment, or null for an enabled one. */ + readonly disabledTip: string | null +} + /** - * Render the lens as a radio group whose segments share its width; arrow keys, Home, and End move between enabled lenses. - * @param props - the lens, its counts, whether test files hide, the choose action, and copy. + * Render a radio group whose segments share its width, each with a count after its label; arrow keys, Home, and End + * move between enabled segments. + * @param props - the segments, the chosen value, the choose action, and the group's localized accessible name. * @returns the radio group. */ -export function LensControl({ lens, counts, hideTests, choose, t }: LensProps): ReactNode { +export function SegmentedChoice({ segments, value, choose, label }: { + readonly segments: readonly Segment[] + readonly value: Value + readonly choose: (value: Value) => void + readonly label: string +}): ReactNode { const group = useRef(null) - const enabled = LENSES.filter(item => item !== 'test' || !hideTests) + const enabled = segments.filter(segment => segment.disabledTip === null).map(segment => segment.value) const move = (event: KeyboardEvent): void => { - const at = enabled.indexOf(lens) - let next: ChangesLens | undefined + const at = enabled.indexOf(value) + let next: Value | undefined switch (event.key) { case 'ArrowLeft': case 'ArrowUp': next = enabled[(at + enabled.length - 1) % enabled.length]; break case 'ArrowRight': case 'ArrowDown': next = enabled[(at + 1) % enabled.length]; break @@ -53,28 +71,40 @@ export function LensControl({ lens, counts, hideTests, choose, t }: LensProps): } event.preventDefault() event.stopPropagation() - /* v8 ignore next -- at most the test lens is disabled, so every key lands on an enabled lens */ + /* v8 ignore next -- every caller keeps a segment enabled, so every key lands on one */ if (next === undefined) return choose(next) - group.current?.querySelector(`[data-forge-lens="${next}"]`)?.focus() + group.current?.querySelector(`[data-segment="${next}"]`)?.focus() } return ( -
- {LENSES.map((item) => { - const disabled = item === 'test' && hideTests +
+ {segments.map((segment) => { const button = ( - ) - return disabled ? {button} : button + return segment.disabledTip === null ? button : {button} })}
) } +/** + * Render the lens as a radio group whose segments share its width. + * @param props - the lens, its counts, whether test files hide, the choose action, and copy. + * @returns the radio group. + */ +export function LensControl({ lens, counts, hideTests, choose, t }: LensProps): ReactNode { + // A disabled lens shows no count, since hidden test files are not counted. + return item === 'test' && hideTests + ? { value: item, label: t(LENS_LABEL[item]), count: null, disabledTip: t('lens.testHidden') } + : { value: item, label: t(LENS_LABEL[item]), count: counts[item], disabledTip: null })} /> +} + /** * Render the lens as a menu button, for a toolbar without the file tree beside it. * @param props - the lens, its counts, whether test files hide, the choose action, copy, and whether the owning tab is visible. diff --git a/packages/experimental/client-ui-forge/src/client/ReviewThread.tsx b/packages/experimental/client-ui-forge/src/client/ReviewThread.tsx index f626c2dc47..7abb3a7f67 100644 --- a/packages/experimental/client-ui-forge/src/client/ReviewThread.tsx +++ b/packages/experimental/client-ui-forge/src/client/ReviewThread.tsx @@ -1,4 +1,4 @@ -/** Inline comment records and editing of a pending review at its captured code location. */ +/** Inline comment records and the editing of comment drafts kept in the browser at their captured code location. */ import { useCallback, useState, useSyncExternalStore, type ReactNode } from 'react' import { Button, Tag } from '@deepseek-ai/dsh-client-ui-primitives' @@ -24,7 +24,8 @@ export function useFileReview(actions: ReviewActions | undefined, path: string): } /** - * Render a saved comment at its line, with pending edits kept in the browser queue. + * Render a saved comment at its line. A comment draft kept in the browser can be edited, deleted, or moved into the + * pending review on the code host. * @param props - record, edit availability, source actions, and localized copy. * @returns one compact inline comment card. */ @@ -38,11 +39,27 @@ export function ReviewThread({ thread, actions, locked, outdated, split, t }: Pr const [editing, setEditing] = useState(false) const [body, setBody] = useState(thread.selection.comment.body) const [error, setError] = useState(null) + const [moving, setMoving] = useState(false) const comment = thread.selection.comment const quoted = editing && thread.kind === 'pending' ? { ...thread.selection, comment: { ...comment, body } } : thread.selection const range = reviewRange(comment) - const status = thread.kind === 'pending' ? 'review.pending' : thread.kind === 'published' ? 'review.published' : 'review.quoted' + const status = thread.kind === 'pending' ? 'review.browserDraft' : thread.kind === 'published' ? 'review.published' : 'review.quoted' const save = (): boolean => actions.records?.editThread(thread.key, body) === true + const queue = actions.queue + /** Add the draft to the pending review on the code host, then delete it from the browser. */ + const move = async (add: NonNullable): Promise => { + setMoving(true) + setError(null) + try { + const failure = await add(thread.selection) + if (failure !== undefined) setError(failure) + else if (actions.records?.editThread(thread.key, null) !== true) setError(t('review.saveFailed')) + } catch (_error) { + setError(t('review.unknown')) + } finally { + setMoving(false) + } + } return
@@ -65,13 +82,15 @@ export function ReviewThread({ thread, actions, locked, outdated, split, t }: Pr }}>{t('review.addToInput')} {thread.kind === 'pending' && <> {editing - ? - : } - } + + {queue !== undefined && !editing && !outdated && } } {thread.kind === 'published' && actions.openLink !== undefined && }
diff --git a/packages/experimental/client-ui-forge/src/client/ReviewThreads.module.css b/packages/experimental/client-ui-forge/src/client/ReviewThreads.module.css new file mode 100644 index 0000000000..e4363071da --- /dev/null +++ b/packages/experimental/client-ui-forge/src/client/ReviewThreads.module.css @@ -0,0 +1,325 @@ +/* Review thread cards share the inline review form's card material; comment rows follow the conversation's 13px detail size. */ +.card, +.folded { + box-sizing: border-box; + width: calc(100% - 20px); + max-width: 720px; + margin: 10px; + border: 0.5px solid var(--dsw-alias-border-l3); + border-radius: var(--dsw-radius-md); + background: var(--dsw-alias-bg-layer-1); + color: var(--dsw-alias-label-primary); + font: var(--dsw-font-xs-13); + font-family: Inter, var(--dsw-font-family); + white-space: normal; +} + +.card { padding: 10px 12px; } + +/* A card a jump from a covering thread list focused; a pointer jump shows no ring. */ +.card:focus { outline: none; } + +.card:focus-visible { + outline: var(--dsw-focus-ring-width) solid var(--dsw-focus-ring-color, var(--dsw-alias-state-business-primary)); + outline-offset: -1px; +} + +.card[data-split][data-side="R"], +.folded[data-split][data-side="R"] { + margin-inline-start: clamp(10px, calc(100% - 740px), calc(50% + 10px)); +} + +.card[data-resolved] { + /* An elevated surface: the excerpt and the file at that commit scroll inside it, so the thumb takes the l2 pair, + which inherits down to them (see ui-theme styles/scrollbar.css for the rebinding contract). */ + --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2); + --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2); + background: var(--dsw-alias-bg-layer-2); +} + +.folded { + display: flex; + align-items: center; + gap: 6px; + min-height: 32px; + padding: 4px 12px; + color: var(--dsw-alias-label-secondary); +} + +.folded > svg { flex: none; color: var(--dsw-alias-state-success-primary); } + +.foldedText { + min-width: 0; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.header { + display: flex; + flex-wrap: wrap; + align-items: center; + gap: 6px; + margin-bottom: 8px; +} + +.place { + min-width: 0; + color: var(--dsw-alias-label-secondary); + font-size: 12px; + overflow-wrap: anywhere; +} + +.spacer { flex: 1; } + +/* Text actions inside a card: no fill, accent ink, the same height as the tags beside them. */ +.link { + display: inline-flex; + flex: none; + align-items: center; + gap: 2px; + padding: 0; + border: 0; + background: transparent; + color: var(--dsw-alias-state-business-primary); + font: inherit; + font-size: 12px; + cursor: pointer; +} + +.link:disabled { color: var(--dsw-alias-label-dimmed); cursor: default; } + +.link:focus-visible { + border-radius: var(--dsw-radius-xs); + outline: var(--dsw-focus-ring-width) solid var(--dsw-focus-ring-color, var(--dsw-alias-state-business-primary)); + outline-offset: 2px; +} + +@media (hover: hover) { + .link:not(:disabled):hover { text-decoration: underline; } +} + +.turned { transform: rotate(-90deg); } + +.comments { + display: flex; + flex-direction: column; + gap: 12px; +} + +.comment { + display: flex; + gap: 8px; + min-width: 0; +} + +.avatar { + display: inline-flex; + flex: none; + align-items: center; + justify-content: center; + overflow: hidden; + border-radius: 50%; + corner-shape: round; + background: var(--dsw-alias-interactive-bg-hover); + color: var(--dsw-alias-label-secondary); + font-weight: 500; + line-height: 1; + user-select: none; +} + +.avatar img { + display: block; + width: 100%; + height: 100%; + border-radius: 50%; + corner-shape: round; + object-fit: cover; +} + +.commentMain { + flex: 1; + min-width: 0; +} + +.commentHeader { + display: flex; + flex-wrap: wrap; + align-items: center; + gap: 6px; + min-height: 20px; +} + +.login { font-weight: 500; overflow-wrap: anywhere; } + +.time { color: var(--dsw-alias-label-tertiary); font-size: 12px; } + +.body { + min-width: 0; + margin-top: 2px; + overflow-wrap: anywhere; +} + +.actions { + display: flex; + flex-wrap: wrap; + gap: 4px; + margin: 10px -8px -4px; +} + +/* A reply or a comment edit uses the inline review form's field; its actions sit under it like the form's. */ +.form { margin-top: 10px; } + +.formActions { + display: flex; + flex-wrap: wrap; + align-items: center; + justify-content: flex-end; + gap: 8px; + margin-top: 8px; +} + +/* The collapsed reply field, a field-shaped button that opens the reply form. */ +.replyPrompt { + display: block; + box-sizing: border-box; + width: 100%; + min-height: 32px; + margin-top: 10px; + padding: 6px 12px; + border: 0.5px solid var(--dsw-alias-border-l4); + border-radius: var(--dsw-radius-md); + background: var(--dsw-alias-bg-layer-3); + color: var(--dsw-alias-label-dimmed); + font: inherit; + text-align: start; + cursor: text; +} + +.replyPrompt:focus-visible { + outline: var(--dsw-focus-ring-width) solid var(--dsw-focus-ring-color, var(--dsw-alias-state-business-primary)); + outline-offset: 2px; +} + +.menuAnchor { display: inline-flex; flex: none; } + +/* The comment menu's icon button keeps the 20px row height of the header it ends. */ +.icon { + display: inline-flex; + align-items: center; + justify-content: center; + width: 20px; + height: 20px; + padding: 0; + border: 0; + border-radius: var(--dsw-radius-xs); + background: transparent; + color: var(--dsw-alias-label-secondary); + cursor: pointer; +} + +.icon[aria-expanded="true"] { background: var(--dsw-alias-interactive-bg-hover); color: var(--dsw-alias-label-primary); } + +.icon:focus-visible { + outline: var(--dsw-focus-ring-width) solid var(--dsw-focus-ring-color, var(--dsw-alias-state-business-primary)); + outline-offset: 1px; +} + +@media (hover: hover) { + .icon:hover { background: var(--dsw-alias-interactive-bg-hover); color: var(--dsw-alias-label-primary); } +} + +/* Confirming a deletion replaces nothing: the comment stays readable above the question. */ +.confirm { + display: flex; + flex-wrap: wrap; + align-items: center; + gap: 8px; + margin-top: 8px; +} + +.confirmText { flex: 1 1 auto; min-width: 0; color: var(--dsw-alias-label-secondary); overflow-wrap: anywhere; } + +.confirmError, +.actionError { flex-basis: 100%; margin-top: 0; } + +.actionError { padding-inline: 8px; } + +/* The end of the recorded hunk, drawn like the diff rows it came from. */ +.excerpt, +.original { + margin-bottom: 10px; + overflow-x: auto; + border: 0.5px solid var(--dsw-alias-border-l2); + border-radius: var(--dsw-radius-sm); + font: var(--dsw-font-markdown-code-block); +} + +.excerptLine, +.originalLine { + min-height: 20px; + padding: 0 10px; + line-height: 20px; + white-space: pre; +} + +.excerptHeader { color: var(--dsw-alias-label-tertiary); } + +.added { background: var(--dsw-alias-file-diff-added-bg); } + +.deleted { background: var(--dsw-alias-file-diff-deleted-bg); } + +.original { + max-height: 320px; + overflow: auto; +} + +.originalLine { + display: grid; + grid-template-columns: max-content minmax(0, 1fr); + gap: 12px; +} + +.originalNumber { + min-width: 3ch; + color: var(--dsw-alias-label-tertiary); + text-align: right; + user-select: none; +} + +.marked { background: var(--dsw-alias-interactive-bg-hover); } + +.originalNote { + padding: 8px 10px; + color: var(--dsw-alias-label-secondary); + font-family: Inter, var(--dsw-font-family); +} + +/* Outdated threads of one file, after its lines. */ +.outdated { + border-top: 0.5px solid var(--dsw-alias-border-l3); + padding-bottom: 2px; +} + +.outdatedHeader { + display: flex; + align-items: center; + gap: 6px; + min-height: 32px; + padding: 0 12px; + color: var(--dsw-alias-label-secondary); + font: var(--dsw-font-xs-13); + font-family: Inter, var(--dsw-font-family); +} + +/* A changes view narrower than 480px gives the code more width; the query names no container, since CSS Modules rename + a container name per file, and the nearest inline-size container is the changes view. */ +@container (max-width: 479px) { + .card, + .folded, + .card[data-split][data-side="R"], + .folded[data-split][data-side="R"] { + width: calc(100% - 12px); + margin: 6px; + } +} diff --git a/packages/experimental/client-ui-forge/src/client/ReviewThreads.tsx b/packages/experimental/client-ui-forge/src/client/ReviewThreads.tsx new file mode 100644 index 0000000000..658356b09e --- /dev/null +++ b/packages/experimental/client-ui-forge/src/client/ReviewThreads.tsx @@ -0,0 +1,445 @@ +/** + * Review threads of a change request inside the changes view: a thread card at its lines or at the top of its file, a + * resolved thread folded into one row, and the outdated threads of a file in a section after its lines. A card offers + * the writes the signed-in user may make: a reply, published at once or added to the pending review, resolving or + * unresolving the thread, and editing or deleting the user's own comments. + */ + +import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react' +import clsx from 'clsx' +import { + Button, IconCheckOutlineRegular, IconChevronDownOutlineRegular, IconEllipsisOutlineRegular, IconRightUpOutlineRegular, MarkdownText, + Menu, Tag, Tooltip, type MarkdownLabels, +} from '@deepseek-ai/dsh-client-ui-primitives' +import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots' +import type { ForgeReviewComment, ForgeReviewThread, ForgeReviewWrite, ForgeThreadId } from '@deepseek-ai/dsh-experimental-forge/types' +import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol' +import { formatAgo } from './format.ts' +import { anchorRange, hunkExcerpt, type ThreadPlace } from './review-threads.ts' +import { SplitAction } from './ReviewComposer.tsx' +import type { NS } from './locales.ts' +import css from './ReviewThreads.module.css' +import composerCss from './ReviewComposer.module.css' + +type Translate = PropsLocale['t'] + +/** Each member of a union without its `headSha`. */ +type WithoutHead = T extends unknown ? Omit : never + +/** A write to one thread or its comments, without the head commit the changes view adds. */ +export type ThreadWrite = WithoutHead> + +/** Writes the signed-in user can make to the threads of one changes view. */ +export interface ThreadWrites { + /** Send a write; resolves to the message to show, or undefined once the code host took it. */ + readonly write: (write: ThreadWrite) => Promise + /** Whether the user has a pending review, which every reply then joins. */ + readonly reviewStarted: boolean + /** Whether the user can add a reply to a pending review, starting one when needed. */ + readonly canReview: boolean +} + +/** Reads, actions, and identities every thread card of one changes view shares. */ +export interface ThreadActions { + /** Login of the change request's author, or null when the host hides it. */ + readonly author: string | null + /** Quote the whole thread in the main input without sending it; false when the input refused it. */ + readonly addToInput: (thread: ForgeReviewThread, range: string | null) => boolean + /** Open a URL outside the app. */ + readonly openLink: (url: string) => void + /** Read a file of the change request's repository at a commit. */ + readonly readText: (commit: string, path: string) => Promise> + /** Report that the input refused a thread. */ + readonly inputFailed: () => void + /** The latest jump to a thread, which unfolds that thread and its section until the reader folds them again; null before any. */ + readonly focused: ThreadFocus | null + /** Writes the user can make, or null when the code host takes none from this view. */ + readonly writes: ThreadWrites | null +} + +/** One jump to a thread; each jump has its own revision, so a jump to the same thread unfolds it again. */ +export interface ThreadFocus { + readonly id: ForgeThreadId + readonly revision: number +} + +/** A host thread shown on lines of one side. */ +export interface LineThread { + readonly thread: ForgeReviewThread + readonly place: Extract +} + +/** Host threads of one file and the actions their cards share. */ +export interface FileThreads { + /** Threads on lines, which follow the row of their last line. */ + readonly lines: readonly LineThread[] + /** Threads on the whole file, shown above its lines. */ + readonly file: readonly ForgeReviewThread[] + /** Threads no longer on the head's lines, shown after them. */ + readonly outdated: readonly ForgeReviewThread[] + /** Unresolved threads of the file in every place, including threads the chosen commits do not show. */ + readonly unresolved: number + /** Reads, actions, and identities shared by the cards. */ + readonly actions: ThreadActions +} + +/** The commit a thread was written on, abbreviated, or null for a file thread. */ +function writtenOn(thread: ForgeReviewThread): string | null { + return thread.original === null ? null : thread.original.commit.slice(0, 7) +} + +/** + * Build the Markdown chrome copy of comment bodies. + * @param t - forge panel copy. + * @returns labels for code fences and footnotes. + */ +export function useMarkdownLabels(t: Translate): MarkdownLabels { + return useMemo(() => ({ + code: { copyLabel: t('thread.copy'), copiedLabel: t('thread.copied'), + toolbarLabels: { codeLabel: t('thread.codeBlock'), wrapLabel: t('thread.wrap'), unwrapLabel: t('thread.unwrap') } }, + footnotes: t('thread.footnotes'), + }), [t]) +} + +/** + * Render an author's avatar, or the first letter of the login when the image is missing or fails. + * @param props - the comment's author and the avatar size. + * @returns the round avatar. + */ +export function Avatar({ author, size = 20 }: { readonly author: ForgeReviewComment['author']; readonly size?: number }): ReactNode { + const [failed, setFailed] = useState(false) + const login = author?.login ?? '?' + return +} + +/** Run one write at a time for a card section, keeping its error until the next attempt. */ +function useWriting(t: Translate): { + readonly busy: boolean + readonly error: string | null + readonly run: (send: () => Promise) => Promise +} { + const [busy, setBusy] = useState(false) + const [error, setError] = useState(null) + const running = useRef(false) + const run = async (send: () => Promise): Promise => { + if (running.current) return false + running.current = true + setBusy(true) + setError(null) + try { + const failure = await send() + setError(failure ?? null) + return failure === undefined + } catch (_error) { + setError(t('thread.writeUnknown')) + return false + } finally { + running.current = false + setBusy(false) + } + } + return { busy, error, run } +} + +/** A plain-text field with Cancel and the actions that send it, for a reply or a comment edit. */ +function TextForm({ label, initial, busy, error, cancel, children }: { + readonly label: string + readonly initial: string + readonly busy: boolean + readonly error: string | null + readonly cancel: { readonly label: string; readonly run: () => void } + /** The sending actions, given the current text and whether it is blank. */ + readonly children: (text: string, blank: boolean) => ReactNode +}): ReactNode { + const [text, setText] = useState(initial) + return
+