@a9n-shoji/rvw 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -5,6 +5,21 @@
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-08-31
+
+### Added
+
+- Markdown、comment、WalkthroughのMermaid図をviewportサイズのreview workspaceへ展開し、Fit・zoom・
+  scroll、resizableなcomment rail、code referenceのpeekとreview画面へのnavigationを利用できる機能
+- WalkthroughのMermaid bindingをflowchartとclassDiagramに加え、sequenceDiagramのparticipant / actor、
+  stateDiagram-v2のstate、erDiagramのentity、architecture-betaのserviceへ拡張
+
+### Changed
+
+- Walkthroughのcode referenceを保存済みの最新PR headへ遅延解決し、fileが不変ならexact range、変更時は
+  sourceとdestinationで一意な未変更rangeだけを対応付け。安全に特定できない場合はimmutableなsource commitへ
+  fallbackし、rename / copyも一意な直接successorだけを追跡
+
 ## [0.3.1] - 2026-08-28
 
 ### Added

package/README.md

@@ -16,7 +16,7 @@ Agentが実装
     ↓
 Git commit / GitHub Pull Request
     ↓
-Agentが任意でcommit固定のWalkthroughを提示
+Agentが任意でsource anchor付きWalkthroughを提示
     ↓
 rvwで意図・説明・変更・repository全体を読む
     ↓
@@ -118,7 +118,7 @@ viewerはこの流れのために次を提供します。
 
 ## Agentの説明を人間の順序で検証する
 
-外部Agentは`rvw-walkthrough` SkillとCLIを使い、実装説明を一つのcommitへ固定してrvwへ提示できます。
+外部Agentは`rvw-walkthrough` SkillとCLIを使い、実装説明を一つのsource commitをanchorとしてrvwへ提示できます。
 
 ```bash
 rvw walkthrough publish --stdin --json
@@ -128,7 +128,14 @@ rvw walkthrough publish --stdin --json
 構成されます。参照は意味のある複数行range、単行、またはfile全体を指せます。rvwは登録時にcommit、
 path、指定された行範囲を検証します。publishしてもbrowserは開かれず、
 active tabやscroll位置も変わりません。人間がviewerのWalkthroughを開き、必要なreferenceを選んだ
-時だけ、exact sourceがdocument tabへ開き、行指定があれば範囲全体が強調されます。通常clickは左ペイン、
+時だけ、`sourceOid`のanchorから最新PR headへcode位置を保守的に解決します。追跡できれば最新code、
+変更や曖昧さがあれば参照時点のcodeを明示して開きます。行指定はfile全体が同一、または選択範囲が
+source/latest双方で一意な場合だけ解決し、範囲全体を強調します。元pathが消えたrenameはcopy候補も含めて後継が1件のときだけ追従します。
+変更表示は選択中の比較がlatestで終わる場合だけtop barのPR比較範囲を使い、historical範囲では別revisionへ
+lineを誤適用せずlatest全文を表示します。fallbackでは、同じfileまたは明確なrename先があればline保証なしで
+最新fileも開けます。このactionも比較終端がlatestと一致するときだけ変更表示を使い、historical範囲ではlatest全文を
+開きます。解決後にPR headが進んだ場合、または同じWalkthrough IDのreference座標が変わった場合はstaleとし、
+解決時／現在のSHAと表示中のanchorを示します。staleな判断とlatest file actionを隠して明示的な再解決だけを提供します。通常clickは左ペイン、
 `Cmd` / `Ctrl`を押しながら選べば右ペインへ開きます。説明tabは残るため、
 複数のclaimと実装を任意の順序・任意のタイミングで往復できます。
 
@@ -197,7 +204,7 @@ rvw Skillを使って、https://github.com/owner/repository/pull/123 をreview
 
 Walkthroughを作る場合は、説明したい対象と必要な作成指示をセッションへ伝えて`rvw-walkthrough` Skillを使います。
 Skillは明示された指示を優先し、未指定の作成判断だけを既定guideで補って、reviewerが変更または実装対象の
-mental modelを作るための最初の読解経路を構成します。文書の見出しや説明順序は固定せず、commit固定の
+mental modelを作るための最初の読解経路を構成します。文書の見出しや説明順序は固定せず、source anchorを持つ
 reference付きartifactとして検証してpublishします。Walkthrough全体へのコメントから説明を改善する場合は、
 現在内容を取得して同じURIを更新し、重複した「改訂版」を追加しません。
 

package/dist/cli.mjs

@@ -19895,7 +19895,7 @@ import path5 from "node:path";
 import { TextDecoder as TextDecoder2 } from "node:util";
 
 // src/shared/constants.ts
-var APP_VERSION = "0.3.1";
+var APP_VERSION = "0.3.2";
 var PROTOCOL_VERSION = 4;
 var VIEWER_ID_HEADER = "x-rvw-viewer-id";
 var VIEWER_OPEN_LEASE_HEADER = "x-rvw-viewer-open-lease";
@@ -20396,6 +20396,10 @@ var GitClient = class {
     );
     return parseCommitLog(output);
   }
+  async firstParent(cwd, oid) {
+    const parents = await runText("git", ["show", "-s", "--format=%P", oid], { cwd });
+    return parents.split(" ").filter(Boolean)[0] ?? null;
+  }
   async tree(cwd, oid) {
     const result = await runProcess("git", ["ls-tree", "-r", "-z", "--long", oid], { cwd });
     return parseLsTree(result.stdout);
@@ -20408,6 +20412,23 @@ var GitClient = class {
     );
     return parseNameStatus(result.stdout);
   }
+  async changedFilesWithCopies(cwd, oldOid, newOid) {
+    const result = await runProcess(
+      "git",
+      [
+        "diff",
+        "--name-status",
+        "-z",
+        "--find-renames",
+        "--find-copies",
+        "--find-copies-harder",
+        oldOid,
+        newOid
+      ],
+      { cwd }
+    );
+    return parseNameStatus(result.stdout);
+  }
   async readDocument(cwd, sourceOid, filePath) {
     assertGitPath(filePath);
     const result = await runProcess("git", ["ls-tree", "-z", "--long", sourceOid, "--", filePath], {
@@ -28071,11 +28092,22 @@ function selectedLineText(value, startLine, endLine) {
 function lines(text5) {
   return normalizeLf(text5).split("\n");
 }
+function countLineRangeOccurrences(documentLines, selected) {
+  let occurrences = 0;
+  for (let index2 = 0; index2 <= documentLines.length - selected.length; index2 += 1) {
+    if (selected.every((line, offset) => documentLines[index2 + offset] === line)) {
+      occurrences += 1;
+    }
+  }
+  return occurrences;
+}
 function mapUnchangedLineRange(sourceText, destinationText, startLine, endLine) {
   if (startLine < 1 || endLine < startLine) return null;
   const sourceLines = lines(sourceText);
   if (endLine > sourceLines.length) return null;
   if (sourceText === destinationText) return { startLine, endLine };
+  const selected = sourceLines.slice(startLine - 1, endLine);
+  if (countLineRangeOccurrences(sourceLines, selected) !== 1) return null;
   const mapping = /* @__PURE__ */ new Map();
   let sourceIndex = 1;
   let destinationIndex = 1;
@@ -28101,14 +28133,8 @@ function mapUnchangedLineRange(sourceText, destinationText, startLine, endLine)
   for (let line = startLine; line <= endLine; line += 1) {
     if (mapping.get(line) !== mappedStart + line - startLine) return null;
   }
-  const selected = sourceLines.slice(startLine - 1, endLine);
-  let occurrences = 0;
   const destinationLines = lines(destinationText);
-  for (let index2 = 0; index2 <= destinationLines.length - selected.length; index2 += 1) {
-    if (selected.every((line, offset) => destinationLines[index2 + offset] === line))
-      occurrences += 1;
-    if (occurrences > 1) return null;
-  }
+  if (countLineRangeOccurrences(destinationLines, selected) !== 1) return null;
   return { startLine: mappedStart, endLine: mappedEnd };
 }
 function findUniqueQuotedLineRange(quotedText, destinationText) {
@@ -28136,6 +28162,11 @@ function placeMutableDocumentComment(anchor, currentText) {
   return range ? { outdated: false, range } : { outdated: true, range: null };
 }
 
+// src/domain/walkthrough-reference.ts
+function walkthroughReferenceFingerprint(sourceOid, reference) {
+  return JSON.stringify([sourceOid, reference.path, reference.startLine, reference.endLine]);
+}
+
 // src/domain/source-excerpt.ts
 var SOURCE_EXCERPT_CONTEXT_LINES = 20;
 var MAX_SOURCE_EXCERPT_LINES = 200;
@@ -41105,7 +41136,8 @@ var codeReferenceIdPattern = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
 var walkthroughDiagramNodePattern = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
 var mermaidIdentifierPattern = /[A-Za-z][A-Za-z0-9_-]{0,63}/g;
 var mermaidEdgePattern = /[<|o*x]*[-.=~]{2,}[|o*x>]*/g;
-var mermaidKeywords = /* @__PURE__ */ new Set([
+var mermaidClassShorthandPattern = /:::[A-Za-z][A-Za-z0-9_-]*(?:,[A-Za-z][A-Za-z0-9_-]*)*/g;
+var flowchartAndClassKeywords = /* @__PURE__ */ new Set([
   "class",
   "classDef",
   "classDiagram",
@@ -41117,12 +41149,19 @@ var mermaidKeywords = /* @__PURE__ */ new Set([
   "style",
   "subgraph"
 ]);
-function mermaidIdentifiers(value) {
-  return [...value.matchAll(mermaidIdentifierPattern)].map(([identifier]) => identifier).filter((identifier) => !mermaidKeywords.has(identifier));
+var noMermaidKeywords = /* @__PURE__ */ new Set();
+function mermaidIdentifiers(value, excludedKeywords) {
+  return [...value.matchAll(mermaidIdentifierPattern)].map(([identifier]) => identifier).filter((identifier) => !excludedKeywords.has(identifier));
 }
-function mermaidLineWithoutLabels(value) {
+function mermaidLineWithoutComment(value) {
   const commentIndex = value.indexOf("%%");
-  const uncommented = commentIndex === -1 ? value : value.slice(0, commentIndex);
+  return commentIndex === -1 ? value : value.slice(0, commentIndex);
+}
+function mermaidLineWithoutClassShorthand(value) {
+  return value.replace(mermaidClassShorthandPattern, "");
+}
+function mermaidLineWithoutLabels(value) {
+  const uncommented = mermaidLineWithoutComment(value);
   const withoutQuotedLabels = uncommented.replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'/g, " ").replace(/\|[^|]*\|/g, " ").replace(/--\s+[^-\n]+\s+-->/g, " -->").replace(/-\.\s+[^.\n]+\s+\.->/g, " -.->").replace(/==\s+[^=\n]+\s+==>/g, " ==>");
   let result = "";
   const closingDelimiters = [];
@@ -41147,33 +41186,105 @@ function mermaidLineWithoutLabels(value) {
   }
   return result;
 }
-function addMermaidEdgeEndpoints(line, nodeIds) {
-  const edges = [...line.matchAll(mermaidEdgePattern)];
+function addMermaidEdgeEndpoints(line, nodeIds, excludedKeywords) {
+  const endpointLine = mermaidLineWithoutClassShorthand(line);
+  const edges = [...endpointLine.matchAll(mermaidEdgePattern)];
   for (let index2 = 0; index2 < edges.length; index2 += 1) {
     const edge = edges[index2];
     const edgeStart = edge.index;
     const edgeEnd = edgeStart + edge[0].length;
     const leftStart = index2 === 0 ? 0 : edges[index2 - 1].index + edges[index2 - 1][0].length;
-    const rightEnd = index2 + 1 === edges.length ? line.length : edges[index2 + 1].index;
-    const left = line.slice(leftStart, edgeStart);
-    const right = line.slice(edgeEnd, rightEnd);
-    const leftIdentifiers = mermaidIdentifiers(left);
-    const rightIdentifiers = mermaidIdentifiers(right);
+    const rightEnd = index2 + 1 === edges.length ? endpointLine.length : edges[index2 + 1].index;
+    const left = endpointLine.slice(leftStart, edgeStart);
+    const right = endpointLine.slice(edgeEnd, rightEnd);
+    const leftIdentifiers = mermaidIdentifiers(left, excludedKeywords);
+    const rightIdentifiers = mermaidIdentifiers(right, excludedKeywords);
     const leftEndpoints = left.includes("&") ? leftIdentifiers : leftIdentifiers.slice(-1);
     const rightEndpoints = right.includes("&") ? rightIdentifiers : rightIdentifiers.slice(0, 1);
     for (const identifier of [...leftEndpoints, ...rightEndpoints]) nodeIds.add(identifier);
   }
 }
+function addSequenceMessageParticipants(line, nodeIds) {
+  const message = line.match(
+    /^([A-Za-z][A-Za-z0-9_-]{0,63})\s*<*[-=]+[)>x]+\s*[+-]?([A-Za-z][A-Za-z0-9_-]{0,63})\b/
+  );
+  if (!message) return;
+  nodeIds.add(message[1]);
+  nodeIds.add(message[2]);
+}
+var erCardinalitySource = [
+  "one\\s+or\\s+zero",
+  "one\\s+or\\s+(?:more|many)",
+  "zero\\s+or\\s+(?:one|more|many)",
+  "only\\s+one",
+  "many\\([01]\\)",
+  "[01]\\+",
+  "many",
+  "one",
+  "\\d+(?:\\.\\d+)?"
+].join("|");
+var erTextualRelationshipPattern = new RegExp(
+  `^([A-Za-z][A-Za-z0-9_-]{0,63})\\s+(?:${erCardinalitySource})\\s+(?:to|optionally\\s+to)\\s+(?:${erCardinalitySource})\\s+([A-Za-z][A-Za-z0-9_-]{0,63})\\b`,
+  "i"
+);
+function addErRelationshipEntities(line, nodeIds) {
+  const relationship = line.match(
+    /^([A-Za-z][A-Za-z0-9_-]{0,63})\s+[|o}{]+[.-]{2}[|o}{]+\s+([A-Za-z][A-Za-z0-9_-]{0,63})\b/
+  ) ?? line.match(erTextualRelationshipPattern);
+  if (!relationship) return;
+  nodeIds.add(relationship[1]);
+  nodeIds.add(relationship[2]);
+}
 function addMermaidDiagramNodes(source, nodeIds) {
   const lines2 = source.split("\n");
   const header = lines2.map((line) => mermaidLineWithoutLabels(line).trim()).find((line) => line.length > 0);
-  const diagramType = header?.match(/^(flowchart|graph|classDiagram)\b/)?.[1];
+  const diagramType = header?.match(
+    /^(flowchart|graph|classDiagram|sequenceDiagram|stateDiagram-v2|erDiagram|architecture-beta)\b/
+  )?.[1];
   if (!diagramType) return;
   for (const rawLine of lines2) {
-    for (const statement of mermaidLineWithoutLabels(rawLine).split(";")) {
+    const diagramLine = diagramType === "erDiagram" || diagramType === "sequenceDiagram" ? mermaidLineWithoutComment(rawLine) : mermaidLineWithoutLabels(rawLine);
+    for (const statement of diagramLine.split(";")) {
       const line = statement.trim();
-      if (!line || /^(flowchart|graph|classDiagram)\b/.test(line)) continue;
-      addMermaidEdgeEndpoints(line, nodeIds);
+      if (!line || /^(flowchart|graph|classDiagram|sequenceDiagram|stateDiagram-v2|erDiagram|architecture-beta)\b/.test(
+        line
+      )) {
+        continue;
+      }
+      if (diagramType === "sequenceDiagram") {
+        const participant = line.match(
+          /^(?:participant|actor)\s+([A-Za-z][A-Za-z0-9_-]{0,63})(?:\s*@\s*\{|\s+as\b|\s*$)/
+        )?.[1];
+        if (participant) nodeIds.add(participant);
+        else addSequenceMessageParticipants(line, nodeIds);
+        continue;
+      }
+      if (diagramType === "architecture-beta") {
+        const service = line.match(/^service\s+([A-Za-z][A-Za-z0-9_-]{0,63})(?:\s|\(|$)/)?.[1];
+        if (service) nodeIds.add(service);
+        continue;
+      }
+      if (diagramType === "stateDiagram-v2") {
+        addMermaidEdgeEndpoints(line, nodeIds, noMermaidKeywords);
+        const alias = line.match(/^state\s+.+?\s+as\s+([A-Za-z][A-Za-z0-9_-]{0,63})\b/)?.[1];
+        const declaration = alias ? void 0 : line.match(/^state\s+([A-Za-z][A-Za-z0-9_-]{0,63})(?:\s|\{|$)/)?.[1];
+        const describedState = line.match(/^([A-Za-z][A-Za-z0-9_-]{0,63})\s*:/)?.[1];
+        const standaloneState = line.match(/^([A-Za-z][A-Za-z0-9_-]{0,63})$/)?.[1];
+        for (const identifier of [alias, declaration, describedState, standaloneState]) {
+          if (identifier) nodeIds.add(identifier);
+        }
+        continue;
+      }
+      if (diagramType === "erDiagram") {
+        const entityLine = mermaidLineWithoutClassShorthand(line);
+        addErRelationshipEntities(entityLine, nodeIds);
+        const entity = entityLine.match(
+          /^([A-Za-z][A-Za-z0-9_-]{0,63})(?:\s*\[[^\]\n]+\])?\s*(?:\{|$)/
+        )?.[1];
+        if (entity) nodeIds.add(entity);
+        continue;
+      }
+      addMermaidEdgeEndpoints(line, nodeIds, flowchartAndClassKeywords);
       if (diagramType === "classDiagram") {
         const declaration = line.match(/^class\s+([A-Za-z][A-Za-z0-9_-]{0,63})\b/)?.[1];
         const memberOwner = line.match(/^([A-Za-z][A-Za-z0-9_-]{0,63})\s*:/)?.[1];
@@ -42091,6 +42202,133 @@ var RvwService = class {
     }
     return walkthrough;
   }
+  async walkthroughReferenceFallbackTarget(pullRequest, sourceOid, filePath) {
+    const diffBaseOid = await this.git.firstParent(pullRequest.localRepositoryPath, sourceOid);
+    if (!diffBaseOid) {
+      return {
+        sourceOid,
+        path: filePath,
+        diffBaseOid: null,
+        oldPath: filePath,
+        newPath: filePath,
+        hasDiff: false
+      };
+    }
+    const change = (await this.git.changedFiles(pullRequest.localRepositoryPath, diffBaseOid, sourceOid)).find((candidate) => candidate.newPath === filePath);
+    return {
+      sourceOid,
+      path: filePath,
+      diffBaseOid,
+      oldPath: change?.oldPath ?? filePath,
+      newPath: change?.newPath ?? filePath,
+      hasDiff: change !== void 0
+    };
+  }
+  async resolveWalkthroughReference(pullRequestId, walkthroughId, referenceId) {
+    const pullRequest = this.getPullRequest(pullRequestId);
+    const walkthrough = this.getWalkthrough(pullRequestId, walkthroughId);
+    const reference = walkthrough.references.find((candidate) => candidate.id === referenceId);
+    if (!reference) {
+      throw new RvwError("NOT_FOUND", "Walkthrough\u306Ecode reference\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093\u3002", {
+        status: 404
+      });
+    }
+    const referenceFingerprint = walkthroughReferenceFingerprint(walkthrough.sourceOid, reference);
+    const sourceDocument = await this.getDocument({
+      kind: "repository-file",
+      pullRequestId,
+      sourceOid: walkthrough.sourceOid,
+      path: reference.path
+    });
+    const latestHeadOid = pullRequest.latestHeadOid;
+    let latestPath = reference.path;
+    let latestDocument;
+    if (walkthrough.sourceOid === latestHeadOid) {
+      latestDocument = sourceDocument;
+    } else {
+      latestDocument = await this.getDocument({
+        kind: "repository-file",
+        pullRequestId,
+        sourceOid: latestHeadOid,
+        path: reference.path
+      });
+      if (latestDocument.availability === "missing") {
+        const successorPaths = [
+          ...new Set(
+            (await this.git.changedFilesWithCopies(
+              pullRequest.localRepositoryPath,
+              walkthrough.sourceOid,
+              latestHeadOid
+            )).filter(
+              (candidate) => (candidate.status.startsWith("R") || candidate.status.startsWith("C")) && candidate.oldPath === reference.path && candidate.newPath !== null
+            ).map((candidate) => candidate.newPath)
+          )
+        ];
+        latestPath = successorPaths.length === 1 ? successorPaths[0] : null;
+        latestDocument = latestPath === null ? null : await this.getDocument({
+          kind: "repository-file",
+          pullRequestId,
+          sourceOid: latestHeadOid,
+          path: latestPath
+        });
+      }
+    }
+    const latestFileExists = latestDocument !== null && latestDocument.availability !== "missing";
+    const latestFileDisplayable = latestDocument?.availability === "available";
+    const mappedRange = reference.startLine === null || reference.endLine === null ? latestFileDisplayable ? null : void 0 : sourceDocument.availability === "available" && latestDocument?.availability === "available" ? mapUnchangedLineRange(
+      sourceDocument.text ?? "",
+      latestDocument.text ?? "",
+      reference.startLine,
+      reference.endLine
+    ) : null;
+    const resolvedToLatest = latestFileDisplayable && (reference.startLine === null || reference.endLine === null || mappedRange !== null);
+    if (resolvedToLatest && latestPath !== null && latestDocument !== null) {
+      return {
+        outcome: "latest",
+        anchorSourceOid: walkthrough.sourceOid,
+        latestHeadOid,
+        referenceFingerprint,
+        target: {
+          sourceOid: latestHeadOid,
+          path: latestPath,
+          diffBaseOid: null,
+          oldPath: latestPath,
+          newPath: latestPath,
+          hasDiff: false,
+          startLine: mappedRange?.startLine ?? reference.startLine,
+          endLine: mappedRange?.endLine ?? reference.endLine
+        },
+        latestFile: null,
+        document: latestDocument
+      };
+    }
+    const targetFile = await this.walkthroughReferenceFallbackTarget(
+      pullRequest,
+      walkthrough.sourceOid,
+      reference.path
+    );
+    const latestFile = latestFileExists && latestPath !== null ? {
+      sourceOid: latestHeadOid,
+      path: latestPath,
+      diffBaseOid: null,
+      oldPath: latestPath,
+      newPath: latestPath,
+      hasDiff: false
+    } : null;
+    return {
+      outcome: "source-fallback",
+      anchorSourceOid: walkthrough.sourceOid,
+      latestHeadOid,
+      referenceFingerprint,
+      target: {
+        ...targetFile,
+        startLine: reference.startLine,
+        endLine: reference.endLine
+      },
+      latestFile,
+      document: sourceDocument
+    };
+  }
   getWalkthroughByUri(uri) {
     const walkthrough = this.database.getWalkthrough(parseWalkthroughUri(uri));
     if (!walkthrough) {
@@ -42139,7 +42377,7 @@ var RvwService = class {
       if (!markdown.mermaidNodeIds.has(nodeId)) {
         throw new RvwError(
           "INVALID_INPUT",
-          `Mermaid node\u304C\u672C\u6587\u306Eflowchart\u307E\u305F\u306FclassDiagram\u306B\u898B\u3064\u304B\u308A\u307E\u305B\u3093: ${nodeId}`
+          `Mermaid binding\u5BFE\u8C61\u304C\u672C\u6587\u306E\u5BFE\u5FDCdiagram\u306B\u898B\u3064\u304B\u308A\u307E\u305B\u3093: ${nodeId}`
         );
       }
     }
@@ -46840,6 +47078,17 @@ function createApp(service, options) {
       walkthroughs: service.listWalkthroughs(context.req.param("id"))
     })
   );
+  app.get(
+    "/api/pull-requests/:id/walkthroughs/:walkthroughId/references/:referenceId/resolve",
+    async (context) => context.json({
+      ok: true,
+      resolution: await service.resolveWalkthroughReference(
+        context.req.param("id"),
+        context.req.param("walkthroughId"),
+        context.req.param("referenceId")
+      )
+    })
+  );
   app.get(
     "/api/pull-requests/:id/walkthroughs/:walkthroughId",
     (context) => context.json({