dsh-review-graph 0.0.0-stage → 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+User-facing docs live in [README.md](README.md); implementation notes live in
+[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
+
+Thanks for looking. A few things make a PR easy to land here.
+
+## Before you open one
+
+```bash
+npm run verify     # build + all self-checks; must be green
+```
+
+The self-checks do not use the network and do not call a model: the AI half runs against a fake
+adapter, and the client half is rendered with a fake React. That means a mistake like reading a name
+that does not exist fails here instead of blanking a tab in the browser — which is exactly how
+three blank-tab bugs got caught, so please keep that property.
+
+## What is easy to get wrong
+
+* **Never hand-place two things in a container.** Two overlays each anchored to the same corner, or
+  boxes positioned by arithmetic, is how buttons and nodes ended up overlapping. Put them in one
+  flex row, or in a slot on a fixed pitch, so the layout cannot collide.
+* **A cache key is a promise.** If two different questions (another commit, another branch, a
+  changed excerpt) can produce the same key, the answer shown will be wrong rather than stale.
+* **Do not silently truncate.** Sizing input down to suit one model's habits changes every model's
+  answer; send the whole thing and let the caller choose.
+* **Declare the service you use.** A Cordis service is only reachable through the `ctx` that
+  declared it in `inject`, and a dotted name (`remote.workspaceFiles`) must be declared verbatim.
+
+## Commits
+
+Explain *why*, not *what*. The diff already says what changed.
+
+## Releasing
+
+The first version goes out by hand, because npm's trusted-publishing settings page only exists once the
+package does:
+
+```bash
+npm publish --otp=<code from the authenticator>
+```
+
+After that, configure **Trusted publishing** on the package's settings page (repository
+`huaxiaolong/dsh-review-graph`, workflow `publish.yml`) and let `.github/workflows/publish.yml` do the
+rest — it needs no stored secret, and it publishes with provenance:
+
+```bash
+# bump version in package.json, commit, push
+git tag v<version> && git push origin v<version>
+```
+
+Why OIDC rather than an `NPM_TOKEN`: npm is removing direct publish from tokens that bypass 2FA
+(targeted for January 2027), so a stored token would stop working. Trusted publishing replaces it with a
+short-lived credential minted per run.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 huaxiaolong <https://github.com/huaxiaolong>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,122 @@
+# dsh-review-graph
+
+[中文](README.md) · English
+
+**Which files call which, how far a change reaches, and where every edit actually is** — read it inside
+the conversation instead of opening files one by one.
+
+![The change-relationship graph and the review pane: the flow diagram's original and changed sides on the left, syntax-highlighted dual line numbers on the right](docs/screenshot.png)
+
+Three surfaces, in the conversation's middle column:
+
+| What you want to know | What you get |
+|---|---|
+| Reach: who calls whom | **Relationship graph**: only the files this change touches, in lanes by call depth, with thin lines for the calls |
+| Place: where it changed | Click any file → the **review pane** opens the whole change set at that file |
+| Content: what changed | Red/green diff, **dual line numbers** (original and changed), **syntax highlighting** (297 languages), a left marker on the line you jumped to |
+| Intent: which behaviour it belongs to | **Business flows (AI)**: on request, a **flow diagram** of the original and the changed side, each step anchored to a file and a line |
+
+## Install
+
+Requirements: DSH (Host and Web), and the workspace you review is a **git repository**.
+
+```bash
+# 1) from git (no account needed — recommended)
+dsh plugin --profile <profile> add https://github.com/huaxiaolong/dsh-review-graph
+
+# 2) from the release tarball (no npm account needed)
+dsh plugin --profile <profile> add https://github.com/huaxiaolong/dsh-review-graph/releases/latest/download/dsh-review-graph-1.0.0.tgz
+
+# 3) from npm
+dsh plugin --profile <profile> add dsh-review-graph
+```
+
+Or in the GUI: **Plugins** in the sidebar → **Add plugin** → paste any of the above (package name, git
+address, tarball URL, or a local path).
+
+All three install the same code with the same capabilities; npm is one channel, not a requirement.
+
+Restart DSH afterwards (the Host half is regenerated) and reload the page (the client half), then switch
+the middle column to “Relationship graph”.
+
+## Using it
+
+### Relationship graph
+
+* **One file, one box.** A column is one call depth; the leftmost column holds the entries — the files
+  nothing else in this change calls.
+* **Colours:** blue means the file has references to or from other changed files; yellow means it has
+  none in this change (hover a box and it says so).
+* **A single click on a file** opens the whole change set in the right column at that file. Lines run
+  from caller to callee.
+* Top right: **⌃ hides the toolbar** (giving its height to the picture) and **Fit** frames everything
+  again. Bottom right: `-`, `+` and a percentage for zoom.
+* When relationships are dense, only the strongest 600 are drawn with the count of what was left out
+  shown in the corner, plus a **Draw all references** button.
+
+### Review pane (right column)
+
+* The top switches the **change source**: uncommitted, unstaged, staged, a single commit, or a
+  comparison against a branch.
+* The left rail lists every file in that source; `‹ ›` steps to the previous or next one. **The line you
+  jumped to carries a left marker** that does not cover the red/green fills.
+* **Open in file** hands the whole file to DSH’s own preview, which has editor-grade highlighting.
+
+### Business flows (AI) — nothing is generated until you ask
+
+* **Generation starts on the button**, and it calls **the model you selected in the conversation**. Before
+  it runs, the card states exactly what would be sent: how many files, how large the excerpts are,
+  whether the conversation digest is included, and the output limit.
+* The result is a **flow diagram with the original and the changed side by side**; clicking a step jumps
+  to its file and line.
+* **Three cache layers**: re-opening the same material loads the previous answer without spending a
+  token; when the material has moved on, the previous answer is **kept and labelled out of date**, and
+  regenerating is your call.
+* **View what was sent and the raw answer** shows the actual prompt and the model’s reply, for debugging.
+
+## What costs money, and what leaves your machine
+
+* **Only pressing Generate spends tokens.** The graph, the review pane, the diff and the highlighting are
+  all local and never touch the network.
+* A generation sends the **change excerpts, the file and symbol structure, and (optionally) a
+  conversation digest** to the model you chose. **Excerpts are never truncated** — the whole diff goes in.
+  A change set larger than the model’s context window fails with a clear error rather than silently
+  handing you an answer with pieces missing.
+* **The model is chosen in the conversation**, not here: this plugin offers no second model switch. It
+  exposes a reasoning-effort control only when your provider actually publishes the options.
+* Cached answers live in `<DSH_HOME>/storages/review-graph-flows/`, at most 30 of them, mode `0600`.
+  Delete that directory to clear them.
+
+## Limitations
+
+* The graph covers files whose references can be **parsed statically** (JS/TS, Python, Go, Rust, Java and
+  others). Files that cannot be parsed appear as isolated (yellow) boxes.
+* **Deleted files are absent** from the graph: they are no longer in the workspace index.
+* With several entries, the busiest one is placed first and the others sit in the adjacent column.
+* A workspace that is not a git repository says so plainly instead of showing an empty pane.
+
+## When something goes wrong
+
+| Symptom | Cause and what to do |
+|---|---|
+| The pane shows `review graph: xxx is not defined` | A plugin defect; that sentence is the cause. Paste it into an issue. (An error boundary produces it — previously this was a blank tab.) |
+| Generation fails saying the output budget was spent on reasoning | The model used its whole budget thinking. Switch to a model that does not think out loud in the conversation, then generate again. |
+| It says there is no cache right after you generated | Switching commit or branch clears the pane and re-checks; a changed conversation digest counts as out of date. |
+| The graph shows a single file | Only one file changed, or the others have no statically parsable references. |
+
+## Uninstall
+
+```bash
+dsh plugin --profile <profile> remove review-graph
+rm -rf "$DSH_HOME/storages/review-graph-flows"   # optional: the generated cache
+```
+
+## Development, architecture and self-checks
+
+See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) (injection contract, layered design, the defect list, and
+how to run the 358 self-checks).
+
+## License
+
+MIT © 2026 huaxiaolong. The inlined Prism.js is MIT as well; attribution and the way it is regenerated are
+in [vendor/prism/NOTICE.md](vendor/prism/NOTICE.md).

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# dsh-review-graph
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[English](README.en.md) · 中文
+
+一次变更里**哪些文件互相调用、影响面多大、每处改动到底在哪一行**——在会话里直接看懂，不用在编辑器里一个个翻。
+
+![变更关系图与审查面板：左侧是业务流程 AI 的原版/改动后对照流程图，右侧是语法高亮、双列行号的变更审查](docs/screenshot.png)
+
+它把三件事放进会话中间栏：
+
+| 你关心的 | 它给你什么 |
+|---|---|
+| 影响面：谁调用谁 | **变更关系图**：只显示本次改动的文件，按调用深度分列，细线表示调用关系 |
+| 位置：改在哪 | 点任意文件 → 右侧**变更审查**打开整个变更集并定位到该文件 |
+| 内容：改了什么 | 红绿差异、**原始/改动后双列行号**、**语法高亮**（297 种语言）、跳转行左侧标记 |
+| 业务：对应哪块逻辑 | **业务流程 AI**：按需生成改动前/后对照的**流程图**，每一步标注文件与行 |
+
+## 安装
+
+要求：DSH（Host + Web 端），被审查的工作区是 **git 仓库**。
+
+```bash
+# 1) 从 git（无需任何账号，推荐）
+dsh plugin --profile <profile> add https://github.com/huaxiaolong/dsh-review-graph
+
+# 2) 从 Release 里的 tarball（无需 npm 账号）
+dsh plugin --profile <profile> add https://github.com/huaxiaolong/dsh-review-graph/releases/latest/download/dsh-review-graph-1.0.0.tgz
+
+# 3) 从 npm
+dsh plugin --profile <profile> add dsh-review-graph
+```
+
+或在 GUI 里：侧栏「**插件**」→ **Add plugin** → 粘贴上面任意一种（包名、git 地址、tarball 地址或本地路径）。
+
+三种方式装的**是同一份代码**，能力完全相同；npm 只是其中一个渠道。
+
+装完**重启 DSH**（Host 半边生效），刷新页面（Client 半边生效），然后在会话中间栏切到「变更关系图」。
+
+## 用起来
+
+### 变更关系图
+
+* **一个文件一个框**，同一列 = 同一调用深度；最左一列是入口（本次改动里没有任何文件调用它）。
+* **颜色**：蓝色 = 与其他改动文件有引用关系；黄色 = 本次改动里没有任何引用关系（悬停会写明）。
+* **单击文件**：在右侧打开整个变更集并定位到该文件；连线从调用方指向被调用方。
+* 右上：**⌃ 收起工具栏**（把高度让给图）、**适应窗口**（回到全景）；右下：`-` / `+` / 百分比是缩放。
+* 关系太密时只画最强的 600 条，左上角写明隐藏了多少，并给出「显示全部引用」。
+
+### 变更审查（右侧栏）
+
+* 顶部切换**变更来源**：未提交 / 未暂存 / 已暂存 / 单个 commit / 与某个分支对比。
+* 左栏是这次来源里的全部改动文件，`‹ ›` 切上一个/下一个；**跳转过来的那一行左侧有竖条**（不影响红绿底色）。
+* 「在文件中打开」用 DSH 自带的预览看整个文件（那里有编辑器级别的高亮）。
+
+### 业务流程 AI（默认不生成）
+
+* **点「生成」才开始**，调用的是**你在对话区选择的模型**。生成前卡片会写清：将发送几个文件的变更片段、多大、是否带对话摘要、输出上限。
+* 结果是**改动前 / 改动后左右对照的流程图**，点任意节点跳到对应文件与行。
+* **三层缓存**：同一份材料再打开→直接命中、不花 token；材料变了→**保留上一次结果并标「已过期」**，重新生成由你决定。
+* 「查看发送内容与原始回答」能看到实际发出的提示词与模型原文（排查用）。
+
+## 会花钱吗？会外发什么？
+
+* **只有点「生成」才消耗 token**。关系图、审查、diff、语法高亮全部本地完成，不联网。
+* 生成时会把**变更片段 + 文件/符号结构 +（可选）对话摘要**发给你选的模型。**变更片段不截断**——整份差异都会送进去；变更集过大可能超出模型上下文窗口，那会**明确报错**，不会悄悄截断给你一个少内容的答案。
+* **模型只在对话区选**，本插件不提供第二个模型开关（只在 provider 公布档位时暴露推理强度）。
+* 缓存落在 `<DSH_HOME>/storages/review-graph-flows/`，最多 30 份，权限 `0600`；删掉该目录即清空。
+
+## 已知限制
+
+* 关系图只覆盖**能静态解析出引用**的文件类型（JS/TS、Python、Go、Rust、Java 等）；解析不出的文件会作为孤立节点（黄色）出现。
+* **已删除的文件不在图里**（它已不在工作区索引中）。
+* 有多个入口时，最"忙"的那个放最左，其余入口排在相邻列。
+* 工作区不是 git 仓库时会明确提示，而不是给你一个空面板。
+
+## 出问题时
+
+| 现象 | 原因与处理 |
+|---|---|
+| 面板显示 `review graph: xxx is not defined` | 插件缺陷；那句话就是原因，直接贴进 issue（这是错误边界的结果，以前会变成空白页签） |
+| 生成失败并说"占满输出预算" | 模型把额度全用在推理上；去**对话区**换一个不做长推理的模型再生成 |
+| 刚生成过却说"没有缓存" | 切换 commit/分支会清空面板并重新判定；对话摘要变化算「已过期」 |
+| 关系图里只有一个文件 | 本次只改了一个文件，或其余文件静态解析不出引用 |
+
+## 卸载
+
+```bash
+dsh plugin --profile <profile> remove review-graph
+rm -rf "$DSH_HOME/storages/review-graph-flows"   # 可选：连同生成的缓存
+```
+
+## 开发、架构与自检
+
+见 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)（注入契约、分层设计、缺陷清单、358 项自检怎么跑）。
+
+## 许可证
+
+MIT © 2026 huaxiaolong。内联的 Prism.js 同为 MIT，归属与再生成方式见 [vendor/prism/NOTICE.md](vendor/prism/NOTICE.md)。