Add diff summary counts for clear no-diff vs changed visibility in Diff Viewer - PR_11_274

Author: DavidQ

docs/dev/reports/PR_11_274_workspace_v2_diff_viewer_summary_counts_report.md

@@ -0,0 +1,38 @@
+# PR_11_274 Workspace V2 Diff Viewer Summary Counts Report
+
+## Scope
+Workspace V2 Diff Viewer only.
+
+## Files Changed
+- tools/workspace-v2/index.html
+- tools/workspace-v2/index.js
+- tests/runtime/V2DiffViewerSummaryCounts.test.mjs
+- docs/pr/PLAN_PR_11_274_WORKSPACE_V2_DIFF_VIEWER_SUMMARY_COUNTS.md
+- docs/pr/BUILD_PR_11_274_WORKSPACE_V2_DIFF_VIEWER_SUMMARY_COUNTS.md
+- docs/dev/reports/PR_11_274_workspace_v2_diff_viewer_summary_counts_report.md
+
+## Implementation Summary
+- Added a new diff summary line node above raw diff JSON output: `workspaceV2DiffSummary`.
+- Wired summary updates from existing diff result counts (presentation only):
+  - `No differences (added: 0, removed: 0, changed: 0)`
+  - `Differences detected (added: X, removed: Y, changed: Z)`
+- Kept raw JSON diff output unchanged below the summary.
+- Cleared summary text on diff output invalidation/reset paths to prevent stale summaries after selection changes.
+
+## Validation Commands
+1. `node --check tools/workspace-v2/index.js`
+   - PASS
+2. `node --check tests/runtime/V2DiffViewerSummaryCounts.test.mjs`
+   - PASS
+3. `node --check tests/runtime/V2DiffViewerMessaging.test.mjs`
+   - PASS
+4. `node tests/runtime/V2DiffViewerSummaryCounts.test.mjs`
+   - PASS
+   - Results: `tmp/v2-diff-viewer-summary-counts-results.json`
+5. `node tests/runtime/V2DiffViewerMessaging.test.mjs`
+   - PASS
+   - Results: `tmp/v2-diff-viewer-messaging-results.json`
+
+## Full Samples Smoke Decision
+- Skipped full samples smoke test.
+- Reason: change is scoped to Workspace V2 Diff Viewer presentation messaging and covered by targeted runtime tests.

docs/pr/BUILD_PR_11_274_WORKSPACE_V2_DIFF_VIEWER_SUMMARY_COUNTS.md

@@ -0,0 +1,33 @@
+# BUILD_PR_11_274_WORKSPACE_V2_DIFF_VIEWER_SUMMARY_COUNTS
+
+## Purpose
+Implement presentation-only Diff Viewer summary counts in Workspace V2.
+
+## Files
+- tools/workspace-v2/index.html
+- tools/workspace-v2/index.js
+- tests/runtime/V2DiffViewerSummaryCounts.test.mjs
+- docs/dev/reports/PR_11_274_workspace_v2_diff_viewer_summary_counts_report.md
+
+## Implementation
+1. Add `workspaceV2DiffSummary` element above diff JSON output in Workspace V2 Diff Viewer.
+2. Wire the summary node in `index.js`.
+3. Add summary formatting method based on existing diff result object counts:
+   - no diff: `No differences (added: 0, removed: 0, changed: 0)`
+   - diff exists: `Differences detected (added: X, removed: Y, changed: Z)`
+4. Clear summary whenever diff output is invalidated/cleared (selection changes and state resets).
+5. Keep existing diff JSON rendering and diff computation intact.
+
+## Acceptance
+- Summary appears above JSON output.
+- Count values match keys in `added`, `removed`, `changed`.
+- JSON output remains unchanged below summary.
+- Stale summaries are cleared on selection/state change paths.
+- No diff algorithm behavior changes.
+
+## Validation
+- node --check tools/workspace-v2/index.js
+- node --check tests/runtime/V2DiffViewerSummaryCounts.test.mjs
+- node --check tests/runtime/V2DiffViewerMessaging.test.mjs
+- node tests/runtime/V2DiffViewerSummaryCounts.test.mjs
+- node tests/runtime/V2DiffViewerMessaging.test.mjs

docs/pr/PLAN_PR_11_274_WORKSPACE_V2_DIFF_VIEWER_SUMMARY_COUNTS.md

@@ -0,0 +1,30 @@
+# PLAN_PR_11_274_WORKSPACE_V2_DIFF_VIEWER_SUMMARY_COUNTS
+
+## Purpose
+Add explicit Diff Viewer summary counts in Workspace V2 so results are understandable without parsing raw JSON.
+
+## Scope
+- tools/workspace-v2/index.html
+- tools/workspace-v2/index.js
+- tests/runtime/V2DiffViewerSummaryCounts.test.mjs
+- tests/runtime/V2DiffViewerMessaging.test.mjs (validation run)
+- docs/report only
+
+## Goals
+- Add summary line above Diff JSON output.
+- Show exact count summary for no-diff and diff-exists outcomes.
+- Keep JSON output unchanged.
+- Clear stale summary on selection/state changes.
+- Preserve existing diff computation behavior.
+
+## Out of Scope
+- No diff algorithm changes.
+- No schema changes.
+- No non-Diff Viewer Workspace V2 behavior changes.
+
+## Validation
+- node --check tools/workspace-v2/index.js
+- node --check tests/runtime/V2DiffViewerSummaryCounts.test.mjs
+- node --check tests/runtime/V2DiffViewerMessaging.test.mjs
+- node tests/runtime/V2DiffViewerSummaryCounts.test.mjs
+- node tests/runtime/V2DiffViewerMessaging.test.mjs

tests/runtime/V2DiffViewerSummaryCounts.test.mjs

@@ -0,0 +1,110 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, "..", "..");
+const htmlPath = path.join(repoRoot, "tools", "workspace-v2", "index.html");
+const jsPath = path.join(repoRoot, "tools", "workspace-v2", "index.js");
+const testPath = path.join(repoRoot, "tests", "runtime", "V2DiffViewerSummaryCounts.test.mjs");
+const resultsPath = path.join(repoRoot, "tmp", "v2-diff-viewer-summary-counts-results.json");
+
+function checkSyntax(filePath) {
+  try {
+    execFileSync(process.execPath, ["--check", filePath], {
+      cwd: repoRoot,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    return { ok: true, error: "" };
+  } catch (error) {
+    return { ok: false, error: (error?.stderr || error?.stdout || error?.message || "").toString().trim() };
+  }
+}
+
+function buildDiffSummary(diff) {
+  const addedCount = Object.keys(diff.added).length;
+  const removedCount = Object.keys(diff.removed).length;
+  const changedCount = Object.keys(diff.changed).length;
+  if (addedCount === 0 && removedCount === 0 && changedCount === 0) {
+    return "No differences (added: 0, removed: 0, changed: 0)";
+  }
+  return `Differences detected (added: ${addedCount}, removed: ${removedCount}, changed: ${changedCount})`;
+}
+
+export function run() {
+  const failures = [];
+  const htmlExists = fs.existsSync(htmlPath);
+  const jsExists = fs.existsSync(jsPath);
+  const html = htmlExists ? fs.readFileSync(htmlPath, "utf8") : "";
+  const js = jsExists ? fs.readFileSync(jsPath, "utf8") : "";
+  const jsSyntax = checkSyntax(jsPath);
+  const testSyntax = checkSyntax(testPath);
+
+  if (!htmlExists) failures.push("Missing tools/workspace-v2/index.html.");
+  if (!jsExists) failures.push("Missing tools/workspace-v2/index.js.");
+  if (!jsSyntax.ok) failures.push("tools/workspace-v2/index.js failed syntax check.");
+  if (!testSyntax.ok) failures.push("tests/runtime/V2DiffViewerSummaryCounts.test.mjs failed syntax check.");
+
+  if (!html.includes('id="workspaceV2DiffSummary"')) {
+    failures.push("Missing Diff summary node in Workspace V2 Diff Viewer.");
+  }
+  if (!js.includes("this.diffSummaryNode = document.getElementById(\"workspaceV2DiffSummary\");")) {
+    failures.push("Diff summary node is not wired in JS.");
+  }
+  if (!js.includes("No differences (added: 0, removed: 0, changed: 0)")) {
+    failures.push("Missing no-difference summary text.");
+  }
+  if (!js.includes("Differences detected (added: ${addedCount}, removed: ${removedCount}, changed: ${changedCount})")) {
+    failures.push("Missing diff-exists summary text.");
+  }
+  if (!js.includes("this.diffSummaryNode.textContent = \"\";")) {
+    failures.push("Diff summary clear path missing for stale summary reset.");
+  }
+
+  const noDiffSummary = buildDiffSummary({ added: {}, removed: {}, changed: {} });
+  const withDiffSummary = buildDiffSummary({
+    added: { "a.b": 1, "a.c": 2 },
+    removed: { old: true },
+    changed: { "x.y": { from: 1, to: 2 } }
+  });
+  if (noDiffSummary !== "No differences (added: 0, removed: 0, changed: 0)") {
+    failures.push("No-diff summary formatting mismatch.");
+  }
+  if (withDiffSummary !== "Differences detected (added: 2, removed: 1, changed: 1)") {
+    failures.push("Diff summary count formatting mismatch.");
+  }
+
+  fs.mkdirSync(path.dirname(resultsPath), { recursive: true });
+  fs.writeFileSync(resultsPath, `${JSON.stringify({
+    generatedAt: new Date().toISOString(),
+    failures,
+    checks: {
+      htmlExists,
+      jsExists,
+      jsSyntax,
+      testSyntax
+    },
+    scenarios: {
+      noDiffSummary,
+      withDiffSummary
+    }
+  }, null, 2)}
+`, "utf8");
+
+  console.log(`v2 diff-viewer summary-counts results: ${resultsPath}`);
+  assert.equal(failures.length, 0, `V2 diff-viewer summary-counts failures: ${failures.join(" | ")}`);
+  return { failures };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const summary = run();
+    console.log(JSON.stringify(summary, null, 2));
+  } catch (error) {
+    console.error(error);
+    process.exitCode = 1;
+  }
+}

tools/workspace-v2/index.html

@@ -92,6 +92,7 @@ <h2>Session Diff Viewer</h2>
         <button id="workspaceV2ComputeDiffButton" type="button">Compute Diff</button>
         <p id="workspaceV2DiffEnableState">Select two different sessions to enable Compute Diff.</p>
         <p id="workspaceV2DiffEmptyState">Need at least two valid sessions to compare.</p>
+        <p id="workspaceV2DiffSummary"></p>
         <pre id="workspaceV2DiffOutput">No diff computed.</pre>
       </section>
 

tools/workspace-v2/index.js

@@ -41,6 +41,7 @@ class WorkspaceV2SessionProducer {
     this.computeDiffButton = document.getElementById("workspaceV2ComputeDiffButton");
     this.diffEnableStateNode = document.getElementById("workspaceV2DiffEnableState");
     this.diffEmptyState = document.getElementById("workspaceV2DiffEmptyState");
+    this.diffSummaryNode = document.getElementById("workspaceV2DiffSummary");
     this.diffOutputNode = document.getElementById("workspaceV2DiffOutput");
     this.mergeLeftSelect = document.getElementById("workspaceV2MergeLeftSelect");
     this.mergeRightSelect = document.getElementById("workspaceV2MergeRightSelect");
@@ -566,6 +567,7 @@ class WorkspaceV2SessionProducer {
 
   clearDiffOutputForStateChange(statusMessage, outputMessage) {
     this.diffOutputSelectionKey = "";
+    this.diffSummaryNode.textContent = "";
     this.diffOutputNode.textContent = typeof outputMessage === "string" && outputMessage.trim()
       ? outputMessage
       : "No diff computed.";
@@ -2286,7 +2288,16 @@ class WorkspaceV2SessionProducer {
     return { added, removed, changed };
   }
 
+  setDiffSummaryFromCounts(addedCount, removedCount, changedCount) {
+    if (addedCount === 0 && removedCount === 0 && changedCount === 0) {
+      this.diffSummaryNode.textContent = "No differences (added: 0, removed: 0, changed: 0)";
+      return;
+    }
+    this.diffSummaryNode.textContent = `Differences detected (added: ${addedCount}, removed: ${removedCount}, changed: ${changedCount})`;
+  }
+
   computeSelectedSessionDiff() {
+    this.diffSummaryNode.textContent = "";
     if (!Array.isArray(this.diffCandidates) || this.diffCandidates.length < 2) {
       this.diffOutputSelectionKey = "";
       this.diffOutputNode.textContent = "Create or reopen at least two Workspace V2 sessions before comparing.";
@@ -2334,13 +2345,13 @@ class WorkspaceV2SessionProducer {
       return;
     }
     const diff = this.computeSessionDiff(left.payload, right.payload);
+    const addedCount = Object.keys(diff.added).length;
+    const removedCount = Object.keys(diff.removed).length;
+    const changedCount = Object.keys(diff.changed).length;
     this.diffOutputSelectionKey = this.buildMergeSelectionKey(left.id, right.id);
+    this.setDiffSummaryFromCounts(addedCount, removedCount, changedCount);
     this.diffOutputNode.textContent = JSON.stringify(diff, null, 2);
-    if (
-      Object.keys(diff.added).length === 0 &&
-      Object.keys(diff.removed).length === 0 &&
-      Object.keys(diff.changed).length === 0
-    ) {
+    if (addedCount === 0 && removedCount === 0 && changedCount === 0) {
       this.statusNode.textContent = "No differences. The selected sessions are identical.";
       return;
     }