dsh-review-graph 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 1.0.2
+
+Fixes reported from real sessions.
+
+* **Generate no longer crashes** when no model is known yet. It failed with
+  `Cannot read properties of null (reading 'provider')` in a session whose selection had never been
+  announced and whose plan had not loaded; the choice is a pure function now and the request says
+  what is missing instead.
+* **"Out of date" means the code moved.** The conversation digest used to count as well, and it moves
+  whenever a session grows — switching pages, loading more history, or a generation recording itself
+  into the conversation — so answers were labelled expired although no code had changed. A moved
+  digest is a note now.
+* **The review pane scrolls to the line it jumped to**, and to the nearest change block when that
+  line survived unchanged and sits outside every hunk.
+* **A step prefers the code that implements it.** A flow diagram used to send the reader to a
+  documentation file whenever the model anchored a behaviour step there.
+* **The model is never printed as `undefined`.** An absent model was dropped by `JSON.stringify` and
+  the card interpolated it anyway; absent values are normalised now, and the label falls back to the
+  model that would answer.
+
+## 1.0.1
+
+Documentation and CI only. Published to validate the package's trusted publishing configuration,
+which npm expires if it is never used.
+
+## 1.0.0
+
+First release: the relationship graph, the review pane, and the optional AI flow diagram.

package/CONTRIBUTING.md

@@ -41,15 +41,32 @@ package does:
 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:
+After that, configure **Trusted publishing** on the package's settings page — publisher *GitHub Actions*,
+repository `huaxiaolong/dsh-review-graph`, workflow file name `publish.yml`, environment name left empty —
+and let `.github/workflows/publish.yml` do the rest. It needs no stored secret and publishes with
+provenance. Two details decide whether it works: the workflow must ask for `id-token: write` (it does), and
+the npm CLI must be 11.5.1 or newer — Node 20's bundled npm is older, so the workflow installs `npm@11`
+first. Pin the major rather than using `npm@latest`: npm 12 requires Node 22.22.2 or newer, and asking for
+it on an older runner fails the install with an engine error before the build even starts.
 
 ```bash
 # bump version in package.json, commit, push
 git tag v<version> && git push origin v<version>
 ```
 
+### Release artifacts and their hashes
+
+Publish the artifact `npm pack` produced — not a tarball assembled by hand. `npm pack` normalises file
+mtimes and entry order, so the same sources produce the same bytes; a `tar -czf` of the same files does
+not, and the registry's `shasum` will not match anything you can reproduce. If a GitHub release carries a
+tarball, attach the one `npm pack` wrote, so the two channels share one hash.
+
+Check the published one with:
+
+```bash
+npm view dsh-review-graph dist.shasum dist.tarball
+```
+
 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/README.en.md

@@ -1,6 +1,6 @@
 # dsh-review-graph
 
-[中文](README.md) · English
+[中文](README.md) · English · [![npm](https://img.shields.io/npm/v/dsh-review-graph.svg)](https://www.npmjs.com/package/dsh-review-graph)
 
 **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.
@@ -21,14 +21,14 @@ Three surfaces, in the conversation's middle column:
 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
+# 1) from npm (recommended)
+dsh plugin --profile <profile> add 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
+# 2) from git (no account needed)
+dsh plugin --profile <profile> add https://github.com/huaxiaolong/dsh-review-graph
 
-# 3) from npm
-dsh plugin --profile <profile> add dsh-review-graph
+# 3) from the release tarball (no npm account needed; pins a version)
+dsh plugin --profile <profile> add https://github.com/huaxiaolong/dsh-review-graph/releases/download/v1.0.0/dsh-review-graph-1.0.0.tgz
 ```
 
 Or in the GUI: **Plugins** in the sidebar → **Add plugin** → paste any of the above (package name, git

package/README.md

@@ -1,6 +1,6 @@
 # dsh-review-graph
 
-[English](README.en.md) · 中文
+[English](README.en.md) · 中文 · [![npm](https://img.shields.io/npm/v/dsh-review-graph.svg)](https://www.npmjs.com/package/dsh-review-graph)
 
 一次变更里**哪些文件互相调用、影响面多大、每处改动到底在哪一行**——在会话里直接看懂，不用在编辑器里一个个翻。
 
@@ -20,14 +20,14 @@
 要求：DSH（Host + Web 端），被审查的工作区是 **git 仓库**。
 
 ```bash
-# 1) 从 git（无需任何账号，推荐）
-dsh plugin --profile <profile> add https://github.com/huaxiaolong/dsh-review-graph
+# 1) 从 npm（推荐）
+dsh plugin --profile <profile> add 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
+# 2) 从 git（无需任何账号）
+dsh plugin --profile <profile> add https://github.com/huaxiaolong/dsh-review-graph
 
-# 3) 从 npm
-dsh plugin --profile <profile> add dsh-review-graph
+# 3) 从 Release 里的 tarball（无需 npm 账号，可钉死版本）
+dsh plugin --profile <profile> add https://github.com/huaxiaolong/dsh-review-graph/releases/download/v1.0.0/dsh-review-graph-1.0.0.tgz
 ```
 
 或在 GUI 里：侧栏「**插件**」→ **Add plugin** → 粘贴上面任意一种（包名、git 地址、tarball 地址或本地路径）。

package/client.js

@@ -689,6 +689,7 @@ window.__ModuleLoader__.load({
         aiNoTalk: '（这段会话还没读到可用于推理的消息）',
         aiModel: (name) => `模型：${name}`,
         aiModelUnknown: '模型：未从会话读到，将使用默认 provider',
+        aiNoModel: '还没有确定用哪个模型：请确认对话区已选择模型，或稍后重试（计划加载完成后即可）。',
         aiGenerate: '生成',
         aiGenerating: '正在推理…（会消耗 token）',
         aiRebuild: '重新生成',
@@ -712,6 +713,7 @@ window.__ModuleLoader__.load({
             : `上次失败：${code}`, 
         aiCacheMemory: '本次页面已生成，切页签不丢（刷新后需重新加载）',
         aiStale: '已过期',
+        aiContextMoved: '对话摘要已更新——这份结果是之前的上下文生成的，重新生成会带上新内容。',
         aiStaleHead: 'HEAD 已经变了（分支上有新提交），这是上一次的结果',
         aiStaleContext: '对话摘要变了，这是上一次的结果',
         aiStaleBoth: 'HEAD 与对话摘要都变了，这是上一次的结果',
@@ -824,6 +826,7 @@ window.__ModuleLoader__.load({
         aiNoTalk: '(this session holds no messages to reason from yet)',
         aiModel: (name) => `Model: ${name}`,
         aiModelUnknown: 'Model: not read from this session; the default provider will be used',
+        aiNoModel: 'No model is known yet. Check that the conversation has one selected, or try again in a moment.',
         aiGenerate: 'Generate',
         aiGenerating: 'Thinking… (this spends tokens)',
         aiRebuild: 'Regenerate',
@@ -847,6 +850,7 @@ window.__ModuleLoader__.load({
             : `The last attempt failed: ${code}`,
         aiCacheMemory: 'Generated in this page; a view switch keeps it, a reload does not',
         aiStale: 'Out of date',
+        aiContextMoved: 'The conversation digest has moved on. This answer was generated from the earlier context; regenerating would include the new material.',
         aiStaleHead: 'HEAD moved on (the branch has new commits); this is the previous result',
         aiStaleContext: 'The conversation digest changed; this is the previous result',
         aiStaleBoth: 'HEAD and the conversation digest both moved; this is the previous result',
@@ -1642,6 +1646,10 @@ window.__ModuleLoader__.load({
       const [selected, setSelected] = useState(parsed?.path ?? null);
 
       const highlight = useHighlighter(selected ?? parsed?.path ?? '');
+      /** The scrolling box, the row to reveal, and the hunk to fall back to. */
+      const bodyRef = useRef(null);
+      const targetRowRef = useRef(null);
+      const nearestHunkRef = useRef(null);
       const scope = typeof params.scope === 'string' ? params.scope : 'unstaged';
       const cwd = typeof params.cwd === 'string' ? params.cwd : undefined;
       const seq = Number.isSafeInteger(params.seq) ? params.seq : undefined;
@@ -1684,6 +1692,24 @@ window.__ModuleLoader__.load({
 
       // The change set of the whole source, so the pane walks it file by file
       // instead of being one file's dead end.
+      // A highlight the reader cannot see is not a jump. Scroll the pane itself —
+      // never the page around it — so the target row lands near the middle.
+      useEffect(() => {
+        if (line === undefined) return undefined;
+        const container = bodyRef.current;
+        if (container === null || container === undefined) return undefined;
+        const row = targetRowRef.current ?? nearestHunkRef.current;
+        if (row === null || row === undefined) return undefined;
+        const rowHeight = row.clientHeight ?? 0;
+        const view = container.clientHeight ?? 0;
+        const top = row.offsetTop ?? 0;
+        const next = Math.max(0, top - Math.max(0, (view - rowHeight) / 2));
+        // Assigning scrollTop moves this pane alone; scrollIntoView could also
+        // move the conversation behind it.
+        container.scrollTop = next;
+        return undefined;
+      }, [state.document, line, endLine, selected]);
+
       // The column keeps one tab, so a new file arrives as a new navigation.
       useEffect(() => {
         if (typeof params.path === 'string' && params.path !== '') setSelected(params.path);
@@ -1876,6 +1902,7 @@ window.__ModuleLoader__.load({
                   padding: '2px 8px',
                   ...(hunkIndex === nearest
                     ? {
+                        ref: nearestHunkRef,
                         boxShadow:
                           'inset 3px 0 0 0 var(--dsw-alias-border-focus, rgba(88,166,255,.95))',
                       }
@@ -1897,6 +1924,7 @@ window.__ModuleLoader__.load({
                 'div',
                 {
                   key: `line-${hunkIndex}-${lineIndex}`,
+                  ref: target ? targetRowRef : undefined,
                   style: {
                     display: 'flex',
                     gap: 8,
@@ -1957,7 +1985,11 @@ window.__ModuleLoader__.load({
             );
           }
         }
-        body = h('div', { style: { overflow: 'auto', padding: '6px 0', flex: 1 } }, rows);
+        body = h(
+          'div',
+          { ref: bodyRef, style: { overflow: 'auto', padding: '6px 0', flex: 1 } },
+          rows
+        );
       }
 
       const rail =
@@ -2265,6 +2297,44 @@ window.__ModuleLoader__.load({
      * The view is rendered from a dictionary that a build or a locale can leave
      * incomplete; a missing plural helper must not empty the tab.
      */
+    /**
+     * The model a generation will use.
+     *
+     * The conversation owns the model, the plan's catalogue is the fallback, and
+     * the plan reports the pair it resolved as a last resort. Anything else
+     * returns `null` — so the caller must handle "no model yet" rather than
+     * reading a property off nothing.
+     */
+    /**
+     * The model name to print, never `undefined`.
+     *
+     * A result carries the model that answered it; an older entry may carry none,
+     * in which case the name of the model that would answer now is the honest
+     * thing to show, and the unknown copy is the fallback after that.
+     */
+    function modelNameText(answered, fallback) {
+      if (typeof answered === 'string' && answered !== '') return answered;
+      if (fallback !== null && fallback !== undefined && typeof fallback.model === 'string' && fallback.model !== '') {
+        return `${fallback.provider ?? ''} ${fallback.model}`.trim();
+      }
+      return null;
+    }
+
+    function modelForGeneration(sessionModel, plan) {
+      const session = sessionModel ?? null;
+      if (session !== null && typeof session.model === 'string' && session.model !== '') {
+        return { provider: session.provider ?? null, model: session.model };
+      }
+      const first = plan?.models?.[0];
+      if (first !== undefined && first !== null && typeof first.model === 'string' && first.model !== '') {
+        return { provider: first.provider ?? null, model: first.model };
+      }
+      if (typeof plan?.plan?.model === 'string' && plan.plan.model !== '') {
+        return { provider: plan.plan.provider ?? null, model: plan.plan.model };
+      }
+      return null;
+    }
+
     function copyText(t, key, ...args) {
       const value = t === null || t === undefined ? undefined : t[key];
       if (typeof value === 'function') return value(...args);
@@ -3080,6 +3150,12 @@ window.__ModuleLoader__.load({
        */
       const [zen, setZen] = useState(false);
       const [aiPlan, setAiPlan] = useState(null);
+
+      // The conversation area owns the model; this pane only falls back, and it
+      // may legitimately have none yet (no selection event, plan still loading).
+      // Declared here, before every consumer: a dependency array is evaluated
+      // during render, so a later declaration is a temporal-dead-zone crash.
+      const aiModel = useMemo(() => modelForGeneration(sessionModel, aiPlan), [sessionModel, aiPlan]);
       const [aiDocument, setAiDocument] = useState(null);
       const [aiError, setAiError] = useState(null);
       const [aiBusy, setAiBusy] = useState(false);
@@ -3092,11 +3168,13 @@ window.__ModuleLoader__.load({
       }, [aiFlow, aiDocument]);
       /** The pair a generation will use: the session's own, or a chosen one. */
       /** The conversation area's model; this pane never chooses its own. */
-      let aiModel = null;
+      // derived below, once the session and the plan are both known
       /** Off by default: a record joins the model context on later turns. */
       const [aiRecord, setAiRecord] = useState(false);
       const [aiDebug, setAiDebug] = useState(false);
       const [aiStale, setAiStale] = useState(null);
+      /** The digest moved, the code did not: a note, not an expiry. */
+      const [aiContextMoved, setAiContextMoved] = useState(false);
       /** Reasoning strength, when the provider names its options. */
       const [aiEffort, setAiEffort] = useState('');
       const [selected, setSelected] = useState(null);
@@ -3257,6 +3335,13 @@ window.__ModuleLoader__.load({
               body.instruction = t.aiInstruction;
               if (typeof sessionId === 'string') body.sessionId = sessionId;
             }
+            if (aiModel === null) {
+              // Reading a property off nothing here is what broke Generate in a
+              // real session: say what is missing instead.
+              setAiError(copyText(t, 'aiNoModel'));
+              setAiBusy(false);
+              return;
+            }
             const chosenProvider = aiModel.provider;
             const chosenModel = aiModel.model;
             if (chosenProvider !== undefined) body.provider = chosenProvider;
@@ -3336,7 +3421,10 @@ window.__ModuleLoader__.load({
             // An out-of-date answer is shown, not hidden: the reviewer may be
             // comparing against it, and only they decide whether to regenerate.
             if (value?.last?.document !== undefined && value.last.document !== null) {
-              setAiStale(value.last);
+              // Only the code moving on marks the answer out of date; a changed
+              // conversation digest is shown as a note, not as "expired".
+              setAiStale(value.last.staleReason === null ? null : value.last);
+              setAiContextMoved(value.last.contextMoved === true);
               setAiDocument((current) => current ?? value.last.document);
             }
             const held = flowClientCache.get(aiKey);
@@ -3357,16 +3445,6 @@ window.__ModuleLoader__.load({
         return () => controller.abort();
       }, [mode, root, source, baseRef, commitRef, sessionModel, conversation, aiPlan, aiKey, generateFlow]);
 
-      // The conversation area owns the model. This pane falls back to the first
-      // pair the profile advertises, so a first generation never fails for lack
-      // of one, and never offers a choice of its own.
-      const chosenModel =
-        sessionModel?.model !== undefined
-          ? sessionModel
-          : aiPlan?.models?.[0] !== undefined
-            ? { provider: aiPlan.models[0].provider, model: aiPlan.models[0].model }
-            : {};
-      aiModel = chosenModel.model === undefined ? null : chosenModel;
 
 
       /** Open the review pane at the file and line one AI node was based on. */
@@ -3377,8 +3455,14 @@ window.__ModuleLoader__.load({
             return;
           }
           setOpenError(null);
-          const anchor = (node.anchors ?? [])[0];
-          const path = anchor?.path ?? (node.files ?? [])[0];
+          // A business step belongs in the code that implements it. A model that
+          // anchored a step to a paragraph of documentation gave a target the
+          // reader cannot use, so a source file wins whenever one is offered —
+          // the document stays as the last resort rather than as the destination.
+          const anchors = Array.isArray(node.anchors) ? node.anchors : [];
+          const anchor = anchors.find((candidate) => isSourcePath(candidate?.path)) ?? anchors[0];
+          const files = Array.isArray(node.files) ? node.files : [];
+          const path = anchor?.path ?? files.find((candidate) => isSourcePath(candidate)) ?? files[0];
           const scope =
             scopeSpecFor(source, { base: baseRef, commit: commitRef }) ?? 'unstaged';
           const base = { cwd: root, scope };
@@ -3832,14 +3916,17 @@ window.__ModuleLoader__.load({
                 aiBusy ? t.aiGenerating : aiDocument === null ? t.aiGenerate : t.aiRebuild),
               aiDocument !== null
                 ? h('span', { style: { fontSize: 11, opacity: 0.7 } },
-                    [t.aiModel(aiDocument.model), aiDocument.usage?.outputTokens !== undefined ? `${aiDocument.usage.outputTokens} tok` : null,
+                    [modelNameText(aiDocument.model, aiModel) === null
+                      ? t.aiModelUnknown
+                      : t.aiModel(modelNameText(aiDocument.model, aiModel)),
+                     aiDocument.usage?.outputTokens !== undefined ? `${aiDocument.usage.outputTokens} tok` : null,
                      aiDocument.cached === true ? t.aiCached : null,
                      typeof aiDocument.generatedAt === 'string' ? t.aiGeneratedAt(aiDocument.generatedAt.slice(0, 19).replace('T', ' ')) : null]
                       .filter(Boolean).join(' · '))
                 : h('span', { style: { fontSize: 11, opacity: 0.7 } },
-                    typeof chosenModel.model === 'string'
-                      ? t.aiModel(`${chosenModel.provider ?? ''} ${chosenModel.model}`.trim())
-                      : t.aiModelUnknown),
+                    aiModel === null
+                      ? t.aiModelUnknown
+                      : t.aiModel(`${aiModel.provider ?? ''} ${aiModel.model}`.trim())),
               h(
                 'label',
                 {
@@ -3895,6 +3982,13 @@ window.__ModuleLoader__.load({
                 : null,
             // Saying which cache an answer would come from is the difference
             // between "it worked" and "I cannot tell".
+            aiContextMoved && aiStale === null
+              ? h(
+                  'div',
+                  { style: { fontSize: 11, opacity: 0.7 } },
+                  t.aiContextMoved
+                )
+              : null,
             aiStale !== null
               ? h(
                   'div',
@@ -4657,6 +4751,9 @@ window.__ModuleLoader__.load({
         ReviewGraphView,
         ReviewGraphBody,
         layoutGraph,
+        modelForGeneration,
+        modelNameText,
+        isSourcePath,
         analyze,
         unwrapRemote,
         listSourceFiles,

package/index.js

@@ -1108,14 +1108,13 @@ export function registerFlowRoute(ctx, exec, recorder, options = {}) {
               return [];
             }
           })();
+          // Out of date means the *code* moved on. The conversation digest is a
+          // different thing: it changes whenever the session grows — including
+          // when a generation records itself into the conversation — and telling
+          // someone their answer is stale because they kept talking is wrong.
           const staleReason =
-            stored === undefined || fresh
-              ? null
-              : stored.head !== material.head && stored.contextHash !== contextHash
-                ? 'both'
-                : stored.head !== material.head
-                  ? 'head'
-                  : 'context';
+            stored === undefined || stored.head === material.head ? null : 'head';
+          const contextMoved = stored !== undefined && stored.contextHash !== contextHash;
           return Response.json(
             {
               diskCached: stored !== undefined,
@@ -1132,6 +1131,9 @@ export function registerFlowRoute(ctx, exec, recorder, options = {}) {
                       generatedAt: stored.generatedAt,
                       head: stored.head,
                       staleReason,
+                      // Reported, not treated as staleness: a new generation
+                      // would read this, the previous answer did not.
+                      contextMoved,
                     },
               plan: {
                 scope: material.graph.git?.label ?? spec.kind,
@@ -1188,7 +1190,9 @@ export function registerFlowRoute(ctx, exec, recorder, options = {}) {
             {
               ...stored.document,
               cached: true,
-              model: stored.model,
+              // An entry stored before this was normalised has no model; report
+              // the one this request resolved rather than nothing.
+              model: stored.model ?? model ?? null,
               provider: stored.provider,
               usage: stored.usage,
               generatedAt: stored.generatedAt,
@@ -1286,7 +1290,9 @@ export function registerFlowRoute(ctx, exec, recorder, options = {}) {
         };
         const entry = {
           document,
-          model,
+          // Normalised, both of them: `undefined` is dropped by JSON.stringify,
+          // so the stored document would come back without a model at all.
+          model: model ?? null,
           provider: provider ?? null,
           usage: usageNumbers(collected.usage),
           generatedAt: new Date().toISOString(),
@@ -1323,7 +1329,7 @@ export function registerFlowRoute(ctx, exec, recorder, options = {}) {
           {
             ...document,
             cached: false,
-            model,
+            model: model ?? null,
             provider: entry.provider,
             usage: entry.usage,
             generatedAt: entry.generatedAt,

package/lib/flow.mjs

@@ -241,6 +241,7 @@ export function flowPrompt(input) {
     'Every node MUST list at least one file it is based on in "files", and add an "anchors" entry with that file and the line you mean whenever the material shows one — a node without a file cannot be opened by the reviewer.',
     'An anchor covers a range when the step does: give "line" and "endLine" (inclusive) for a block of lines, and only "line" for one line. Do not collapse a range to its first line.',
     'Anchor lines are lines of the file on the side the diagram shows: the "before" side names original lines, the "after" side names the changed lines.',
+    'Anchor a step to the code that implements it. Do not send the reader to a document, a comment file, or a configuration file for a step about behaviour; name such a file only when the step itself is about that document, and say so in the detail.',
     'If the material does not support a step or an edge, omit it, or mark the node "confidence": "low" — never invent behaviour.',
     'When conversation context is given, use it to name the business intent and the people or systems involved — but the code is the authority on what actually changed; if the two disagree, follow the code.',
     'Do not read the excerpts exhaustively and do not restate them: decide the flows from the file list, the symbols, and the references, then answer.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-review-graph",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "description": "Review a change set as a relationship graph in the middle column, with every node clickable to the exact source line.",
   "exports": {
@@ -24,7 +24,8 @@
     "README.md",
     "docs",
     "CONTRIBUTING.md",
-    "README.en.md"
+    "README.en.md",
+    "CHANGELOG.md"
   ],
   "icon": "./icon.svg",
   "meta": {