diffninja 0.1.1 → 0.3.0

package/dist/review/call-flow-html.js

@@ -1,6 +1,7 @@
 import { CALL_FLOW_MAX_CHILDREN, CALL_FLOW_MAX_CROSS_FILE_CHILDREN, CALL_FLOW_MAX_DEPTH, CALL_FLOW_MAX_NODES, CALL_FLOW_MAX_ROOTS, } from "./call-flow.js";
 import { CALL_FLOW_DEFAULT_DEPTH, CALL_FLOW_DEPTHS, CALL_FLOW_MODES, CALL_FLOW_NAV_SOURCE, } from "./call-flow-nav.js";
 import { escapeHtml } from "./escape-html.js";
+import { nodeFunctionId, purposesOf, wrapPurpose } from "./explanation.js";
 /**
  * Call-flow navigation for a review report: Tree, Graph and Sequence views of
  * the syntactic call trees that touch each changed file.
@@ -24,13 +25,16 @@ import { escapeHtml } from "./escape-html.js";
  * removed, or contains a change, and plain dimmed text for an unchanged call.
  */
 export function renderCallFlows(report) {
-    const files = collectFiles(report.callFlows, report.items);
+    const purposes = purposesOf(report);
+    const files = collectFiles(report.callFlows, report.items, purposes);
     if (files.length === 0) {
         return `<p class="cf-note cf-absence">${escapeHtml(AVAILABILITY_NOTE[report.callFlowAvailability])}</p>`;
     }
+    const plumbing = purposes.size === 0 ? 0 : files.reduce((total, view) => total + countPlumbing(view.trees, purposes), 0);
     return [
         '<div class="cf">',
         renderSummary(files, new Set(report.items.map(item => item.file)).size),
+        renderPlumbingToggle(plumbing, report.agentExplanation?.explainedBy),
         renderControls(),
         renderJump(files),
         '<nav class="cf-crumbs" id="cf-crumbs" aria-label="Visited call trail" hidden></nav>',
@@ -100,6 +104,47 @@ const GRAPH_CHAR = 7.4;
 const GRAPH_LOC_CHAR = 6.2;
 const GRAPH_MIN_WIDTH = 132;
 const GRAPH_MAX_WIDTH = 300;
+/** The agent's purpose leads an explained box: up to three lines of 12px sans text. */
+const GRAPH_PURPOSE_LINES = 3;
+const GRAPH_PURPOSE_HEIGHT = 16;
+const GRAPH_PURPOSE_CHAR = 7.2;
+/** The agent's purpose for the function a node resolved to, if it wrote one. */
+function purposeOf(node, purposes) {
+    const id = nodeFunctionId(node);
+    return id === undefined ? undefined : purposes.get(id);
+}
+/**
+ * Whether a node and everything below it is plumbing: no call in the subtree
+ * resolved to a function the agent explained. Library and framework calls are
+ * the usual case; hiding them leaves the calls the product itself makes.
+ */
+function isPlumbing(node, purposes) {
+    return purposeOf(node, purposes) === undefined && node.children.every((child) => isPlumbing(child, purposes));
+}
+/** Plumbing subtrees that the toggle hides, counted at their topmost node. */
+function countPlumbing(trees, purposes) {
+    let total = 0;
+    for (const tree of trees)
+        total += isPlumbing(tree, purposes) ? 1 : countPlumbing(tree.children, purposes);
+    return total;
+}
+/**
+ * A native checkbox, so hiding plumbing needs no script: while it is unchecked
+ * the stylesheet hides every plumbing call in Tree and Sequence. The Diagram
+ * keeps every box, because hiding one would leave its edges pointing at nothing.
+ */
+function renderPlumbingToggle(plumbing, explainedBy) {
+    if (explainedBy === undefined)
+        return "";
+    return [
+        '<div class="cf-business">',
+        `<p class="cf-business-note">Each call shows what it does for the product first, as ${escapeHtml(explainedBy)} explained it, and its code name under it.</p>`,
+        plumbing === 0
+            ? ""
+            : `<label class="cf-plumbing-toggle"><input type="checkbox" class="cf-show-plumbing"> Show ${escapeHtml(plural(plumbing, "library or framework call"))} with no product code below</label>`,
+        "</div>",
+    ].join("");
+}
 /** Most severe hunk per file, and the earliest hunk of that severity. */
 function hunkRanks(items) {
     const ranks = new Map();
@@ -113,7 +158,7 @@ function hunkRanks(items) {
     return ranks;
 }
 /** One diagram section per changed file with structured call paths. */
-function collectFiles(callFlows, items) {
+function collectFiles(callFlows, items, purposes) {
     const ranks = hunkRanks(items);
     const views = [];
     const seen = new Set();
@@ -129,6 +174,7 @@ function collectFiles(callFlows, items) {
             rank: hunk.rank,
             trees,
             truncated: entry.truncated === true,
+            purposes,
         });
     }
     // Most severe file first; ties keep report order.
@@ -289,7 +335,7 @@ function lazyMode(mode, at, section) {
 }
 function renderTreeMode(view, at) {
     const trees = view.trees
-        .map((tree, root) => renderTreeNode(tree, [root], at, view.file))
+        .map((tree, root) => renderTreeNode(tree, [root], at, view.file, view.purposes))
         .join("\n");
     return modeSection("tree", at, `<ul class="cf-tree">${trees}</ul>`);
 }
@@ -341,11 +387,12 @@ function nodeAttrs(node, path, at) {
         node.file === undefined ? "" : ` data-cf-nodefile="${escapeHtml(node.file)}"`,
     ].join("");
 }
-function renderTreeNode(node, path, at, changedFile) {
+function renderTreeNode(node, path, at, changedFile, purposes) {
     const id = path.join("-");
     const status = node.status;
     const inFile = node.file === changedFile;
     const loc = locationText(node);
+    const purpose = purposeOf(node, purposes);
     // The label is the zoom target. It stays a plain span without JavaScript (a
     // dead button would be worse) and the script upgrades it into a real button.
     const zoom = `<span class="cf-label mono" data-cf-zoom data-cf-file="${at}" data-cf-path="${id}"` +
@@ -356,7 +403,9 @@ function renderTreeNode(node, path, at, changedFile) {
         loc === ""
             ? '<span class="cf-loc cf-loc-none">no source location</span>'
             : `<span class="cf-loc mono">${escapeHtml(loc)}</span>`,
-        node.description ? `<span class="cf-desc">${escapeHtml(node.description)}</span>` : "",
+        purpose !== undefined
+            ? `<span class="cf-purpose">${escapeHtml(purpose)}</span>`
+            : node.description ? `<span class="cf-desc">${escapeHtml(node.description)}</span>` : "",
         // An anchor, not a button: it reaches the disclosure below without the script.
         `<a class="cf-src-link" href="#cf-f${at}-src-${id}" data-cf-source` +
             ` data-cf-file="${at}" data-cf-path="${id}">${node.source ? "source" : "details"}</a>`,
@@ -366,13 +415,17 @@ function renderTreeNode(node, path, at, changedFile) {
     const classes = ["cf-node", `cf-st-${status}`];
     if (inFile)
         classes.push("cf-infile");
+    if (purpose !== undefined)
+        classes.push("cf-explained");
+    else if (purposes.size > 0 && isPlumbing(node, purposes))
+        classes.push("cf-plumbing");
     const kids = node.children;
     const source = renderSource(node, id, at);
     if (kids.length === 0) {
         return `<li class="${classes.join(" ")} cf-leaf"${nodeAttrs(node, id, at)}><span class="cf-row">${row}</span>${source}</li>`;
     }
     const children = kids
-        .map((child, childAt) => renderTreeNode(child, path.concat([childAt]), at, changedFile))
+        .map((child, childAt) => renderTreeNode(child, path.concat([childAt]), at, changedFile, purposes))
         .join("\n");
     return [
         `<li class="${classes.join(" ")}"${nodeAttrs(node, id, at)}>`,
@@ -412,7 +465,7 @@ function locationText(node) {
 function renderGraphMode(view, at) {
     const figures = view.trees
         .map((tree, root) => {
-        const layout = layoutTree(tree, [root]);
+        const layout = layoutTree(tree, [root], view.purposes);
         const edges = layout.edges
             .map((edge, index) => renderGraphEdge(edge, index + 1, layout.edges.length, at))
             .join("");
@@ -446,26 +499,29 @@ function renderGraphMode(view, at) {
  * The enhanced viewport frames these coordinates without shrinking text.
  * Without JavaScript the native-size diagram scrolls inside its container.
  */
-function layoutTree(root, rootPath) {
+function layoutTree(root, rootPath, purposes) {
     const levels = [];
     const boxes = [];
     const edges = [];
     const walk = (node, path, parent) => {
         const loc = locationText(node);
-        const description = node.description ?? "";
+        const purpose = purposeOf(node, purposes);
+        const description = purpose === undefined ? node.description ?? "" : "";
         const labelChars = Math.max(1, node.label.length + (node.status === "same" ? 0 : 2));
-        const width = Math.ceil(Math.min(GRAPH_MAX_WIDTH, Math.max(GRAPH_MIN_WIDTH, 48 +
+        const width = purpose !== undefined ? GRAPH_MAX_WIDTH : Math.ceil(Math.min(GRAPH_MAX_WIDTH, Math.max(GRAPH_MIN_WIDTH, 48 +
             Math.max(labelChars * GRAPH_CHAR, loc.length * GRAPH_LOC_CHAR, description.length * GRAPH_LOC_CHAR))));
+        const purposeLines = purpose === undefined ? [] : wrapPurpose(purpose, Math.floor((width - 48) / GRAPH_PURPOSE_CHAR), GRAPH_PURPOSE_LINES);
         const box = {
             node,
             path,
             x: 0,
             y: 0,
             width,
-            height: description === "" ? GRAPH_NODE_HEIGHT : GRAPH_NODE_HEIGHT + GRAPH_DESC_HEIGHT,
+            height: GRAPH_NODE_HEIGHT + (description === "" ? 0 : GRAPH_DESC_HEIGHT) + purposeLines.length * GRAPH_PURPOSE_HEIGHT,
             labelChars: Math.floor((width - 48) / GRAPH_CHAR),
             locChars: Math.floor((width - 24) / GRAPH_LOC_CHAR),
             descChars: Math.floor((width - 24) / GRAPH_LOC_CHAR),
+            purposeLines,
         };
         const depth = path.length - 1;
         const level = levels[depth];
@@ -526,12 +582,14 @@ function renderGraphNode(box, at, changedFile) {
     const status = node.status;
     const loc = locationText(node);
     const source = node.source;
-    const description = node.description ?? "";
+    // The agent's purpose replaces the docstring line: one explanation per box.
+    const description = box.purposeLines.length > 0 ? "" : node.description ?? "";
     const desc = description === "" ? "" : clip(description, box.descChars);
     const inFile = node.file === changedFile;
     const action = `href="#cf-f${at}-src-${path}" data-cf-source`;
     const title = [
         node.label,
+        box.purposeLines.join(" "),
         loc === "" ? "no source location" : loc,
         STATUS_WORD[status],
         description,
@@ -541,17 +599,23 @@ function renderGraphNode(box, at, changedFile) {
         .join(" · ");
     const mark = STATUS_MARK[status];
     const label = clip(mark ? `${mark} ${node.label}` : node.label, box.labelChars);
+    // An explained box leads with what the call does; its code name and place follow.
+    const lead = box.purposeLines.length * GRAPH_PURPOSE_HEIGHT;
+    const purposeLines = box.purposeLines
+        .map((line, index) => `<text class="cf-gpurpose" x="${box.x + 12}" y="${box.y + 19 + index * GRAPH_PURPOSE_HEIGHT}">${escapeHtml(line)}</text>`)
+        .join("");
     return [
-        `<a class="cf-gnode cf-st-${status}${inFile ? " cf-infile" : ""}" ${action} data-cf-file="${at}" data-cf-path="${path}">`,
+        `<a class="cf-gnode cf-st-${status}${inFile ? " cf-infile" : ""}${lead > 0 ? " cf-explained" : ""}" ${action} data-cf-file="${at}" data-cf-path="${path}">`,
         `<title>${escapeHtml(title)}</title>`,
         `<rect x="${box.x}" y="${box.y}" width="${box.width}" height="${box.height}" rx="7"></rect>`,
-        `<text class="cf-glabel" x="${box.x + 12}" y="${loc === "" && desc === "" ? box.y + 25 : box.y + 17}">${escapeHtml(label)}</text>`,
+        purposeLines,
+        `<text class="cf-glabel" x="${box.x + 12}" y="${lead + (loc === "" && desc === "" ? box.y + 25 : box.y + 17)}">${escapeHtml(label)}</text>`,
         loc === ""
             ? ""
-            : `<text class="cf-gloc" x="${box.x + 12}" y="${box.y + 31}">${escapeHtml(clip(loc, box.locChars))}</text>`,
+            : `<text class="cf-gloc" x="${box.x + 12}" y="${lead + box.y + 31}">${escapeHtml(clip(loc, box.locChars))}</text>`,
         desc === ""
             ? ""
-            : `<text class="cf-gdesc" x="${box.x + 12}" y="${loc === "" ? box.y + 31 : box.y + 44}">${escapeHtml(desc)}</text>`,
+            : `<text class="cf-gdesc" x="${box.x + 12}" y="${lead + (loc === "" ? box.y + 31 : box.y + 44)}">${escapeHtml(desc)}</text>`,
         "</a>",
         `<a class="cf-gzoom" href="#cf-f${at}-t-${path}" data-cf-zoom data-cf-file="${at}" data-cf-path="${path}" aria-label="Zoom into ${escapeHtml(node.label)}">`,
         `<circle cx="${box.x + box.width - 13}" cy="${box.y + 13}" r="10"></circle>`,
@@ -570,9 +634,15 @@ function clip(text, maxChars) {
 function renderSequenceMode(view, at) {
     const paths = [];
     view.trees.forEach((tree, root) => collectPaths(tree, [root], [], paths));
+    // With an explanation, a path of plumbing alone says nothing about the product.
+    if (view.purposes.size > 0) {
+        const explained = paths.filter((chain) => chain.some((step) => purposeOf(step.node, view.purposes) !== undefined));
+        if (explained.length > 0)
+            paths.splice(0, paths.length, ...explained);
+    }
     const shown = Math.min(paths.length, SEQUENCE_LIMIT);
     const note = `<p class="cf-note cf-omitted"${paths.length <= SEQUENCE_LIMIT ? " hidden" : ""}>Showing ${shown} of ${paths.length} call paths; focus a branch to narrow.</p>`;
-    return modeSection("sequence", at, `<p class="cf-note">Static call paths, not execution order.</p><ol class="cf-paths" data-cf-path-limit="${SEQUENCE_LIMIT}">${paths.map((chain) => renderPath(chain, at)).join("\n")}</ol>${note}`);
+    return modeSection("sequence", at, `<p class="cf-note">Static call paths, not execution order.</p><ol class="cf-paths" data-cf-path-limit="${SEQUENCE_LIMIT}">${paths.map((chain) => renderPath(chain, at, view.purposes)).join("\n")}</ol>${note}`);
 }
 function collectPaths(node, path, chain, out) {
     const next = chain.concat([{ node, path }]);
@@ -583,18 +653,19 @@ function collectPaths(node, path, chain, out) {
     }
     kids.forEach((child, childAt) => collectPaths(child, path.concat([childAt]), next, out));
 }
-function renderPath(chain, at) {
+function renderPath(chain, at, purposes) {
     const leaf = chain[chain.length - 1];
     const chips = chain
-        .map((step) => renderChip(step, at))
+        .map((step) => renderChip(step, at, purposes))
         .join('<span class="cf-arrow" aria-hidden="true">→</span>');
     return `<li class="cf-path" data-cf-file="${at}" data-cf-path="${leaf.path.join("-")}">${chips}</li>`;
 }
 /** A chip is the step's zoom target plus, when the backend resolved it, its own
  *  source link: without the script both are plain anchors that reach the tree. */
-function renderChip(step, at) {
+function renderChip(step, at, purposes) {
     const path = step.path.join("-");
     const node = step.node;
+    const purpose = purposeOf(node, purposes);
     const status = node.status;
     const loc = locationText(node);
     const title = loc === "" ? "" : ` title="${escapeHtml(loc)}"`;
@@ -605,7 +676,9 @@ function renderChip(step, at) {
         `<span class="cf-chip-label mono">${escapeHtml(node.label)}</span>`,
         loc === "" ? "" : `<span class="cf-chip-loc mono">${escapeHtml(loc)}</span>`,
         "</a>",
-        node.description ? `<span class="cf-desc">${escapeHtml(node.description)}</span>` : "",
+        purpose !== undefined
+            ? `<span class="cf-purpose">${escapeHtml(purpose)}</span>`
+            : node.description ? `<span class="cf-desc">${escapeHtml(node.description)}</span>` : "",
         `<a class="cf-src-link" href="#cf-f${at}-src-${path}" data-cf-source` +
             ` data-cf-file="${at}" data-cf-path="${path}">${node.source ? "source" : "details"}</a>`,
         "</span>",
@@ -957,6 +1030,17 @@ export const CALL_FLOW_STYLES = `
 .cf-arrow { color: var(--ink-soft); font-size: 12px; }
 /* One description line per call, only when the backend attached one. */
 .cf-desc { font-size: 11.5px; color: var(--ink-soft); font-style: italic; overflow-wrap: anywhere; }
+.cf-business { display: flex; flex-direction: column; gap: 6px; margin: 4px 0 10px; }
+.cf-business-note { font-size: 13px; color: var(--ink-soft); }
+.cf-plumbing-toggle { display: inline-flex; align-items: center; gap: 7px; font-size: 13px; color: var(--ink-soft); cursor: pointer; width: fit-content; }
+.cf:has(.cf-show-plumbing:not(:checked)) .cf-node.cf-plumbing { display: none; }
+.cf-purpose { font-family: var(--sans); font-size: 13.5px; font-weight: 550; color: var(--ink); overflow-wrap: anywhere; }
+.cf-row > .cf-purpose { flex: 1 0 100%; order: -1; padding-left: 26px; }
+.cf-fold > .cf-row > .cf-purpose { padding-left: 16px; }
+.cf-node.cf-explained > .cf-row .cf-label, .cf-node.cf-explained > .cf-fold > .cf-row .cf-label { font-size: 11.5px; }
+.cf-chip .cf-purpose { font-size: 12.5px; max-width: 34ch; }
+.cf-gpurpose { font-family: var(--sans); font-size: 12px; font-weight: 600; fill: var(--ink); }
+.cf-diagram-nav-name.cf-diagram-nav-purpose { font-family: var(--sans); white-space: normal; }
 .cf-row > .cf-desc { flex: 1 0 100%; order: 5; padding-left: 26px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 .cf-row > .cf-src-link { order: 4; }
 .cf-depth { align-items: center; gap: 4px; }
@@ -1610,6 +1694,16 @@ export const CALL_FLOW_SCRIPT = `
         count.className = 'cf-diagram-nav-count';
         var calls = frames[i].querySelectorAll('a.cf-gnode').length;
         count.textContent = (dot > 0 && label.slice(0, 4) !== 'new ' ? label.slice(0, dot) + ', ' : '') + calls + (calls === 1 ? ' call' : ' calls');
+        // An explained entry point leads with what it does for the product; its name moves under it.
+        var lead = frames[i].querySelector('a.cf-gnode');
+        var said = lead ? lead.querySelectorAll('.cf-gpurpose') : [];
+        if (said.length > 0) {
+          var words = [];
+          for (var w = 0; w < said.length; w++) words.push(said[w].textContent);
+          count.textContent = name.textContent + ' \u00b7 ' + count.textContent;
+          name.textContent = words.join(' ');
+          name.classList.add('cf-diagram-nav-purpose');
+        }
         button.appendChild(name);
         button.appendChild(count);
         item.appendChild(button);

package/dist/review/connected-analysis.d.ts

@@ -11,7 +11,8 @@
  * MCP client that recorded it.
  */
 import { type QuestionKind, type Verdict } from "./questions.js";
-import type { ReviewReport, ReviewStatus, SuggestedComment } from "./types.js";
+import type { AgentSummary, ReviewReport, ReviewStatus, SuggestedComment } from "./types.js";
+import type { ExplanationChange } from "./explanation.js";
 /** Most agenda entries the page lists; the full report has the rest. */
 export declare const CONNECTED_AGENDA_LIMIT = 5;
 export interface ConnectedFact {
@@ -45,6 +46,22 @@ export interface ConnectedHunk {
     /** One fixed sentence when the hunk was not read: a metadata unit or an unread file type. */
     note?: string;
     readonly questions: readonly ConnectedQuestion[];
+    /** The process steps and rules the reviewing agent tied to this hunk, in its words. */
+    business?: readonly ConnectedBusinessLink[];
+}
+/** One step or rule of the agent's explanation that names a hunk. */
+export interface ConnectedBusinessLink {
+    /** The process title for a step; absent for a business rule. */
+    readonly process?: string;
+    readonly text: string;
+    readonly change: ExplanationChange;
+}
+/** What the page needs to show the business view under the goal; the drawing itself is served by `/flow?view=business`. */
+export interface ConnectedExplanation {
+    readonly explainedBy: string;
+    readonly processes: readonly string[];
+    readonly rules: number;
+    readonly functions: number;
 }
 /** Whether the analysis had a local clone's definitions and call flows. */
 export interface ConnectedScope {
@@ -70,13 +87,23 @@ export interface ConnectedAnalysis {
         readonly total: number;
         readonly answered: number;
     };
-    /** Line comments the reviewing agent suggested, for the human to add to their review or not. */
     /** Changed files that have call-flow diagrams, for the page's "Call flow" buttons; empty for a patch-only analysis. */
     readonly callFlowFiles: readonly string[];
+    /** Line comments the reviewing agent suggested, for the human to add to their review or not. */
     suggestions?: {
         readonly suggestedBy: string;
         readonly comments: readonly SuggestedComment[];
     };
+    /**
+     * The reviewing agent's own short paragraph on what the pull request does and
+     * why, attributed to the client that wrote it. Absent when no finish_review
+     * accepted one, which the page must say instead of showing a goal of its own:
+     * diffninja generates no summary, and this one is the agent's reading of the
+     * author's stated intent, not a claim that the changes achieve it.
+     */
+    summary?: AgentSummary;
+    /** Present once the reviewing agent's business explanation was accepted for this report. */
+    explanation?: ConnectedExplanation;
 }
 export type ConnectedOrder = {
     readonly source: "agent";

package/dist/review/connected-analysis.js

@@ -106,6 +106,17 @@ export function connectedAnalysisOf(report, snapshotId, reviewId, reportUrl, sco
         list.push(view);
         questionsByUnit.set(owner, list);
     }
+    const business = new Map();
+    const link = (hunks, entry) => {
+        for (const id of new Set(hunks ?? []))
+            business.set(id, [...(business.get(id) ?? []), entry]);
+    };
+    for (const process of report.agentExplanation?.processes ?? []) {
+        for (const step of process.steps)
+            link(step.hunks, { process: process.title, text: step.text, change: step.change });
+    }
+    for (const rule of report.agentExplanation?.rules ?? [])
+        link(rule.hunks, { text: rule.text, change: rule.change });
     const counts = { attention: 0, uncertain: 0, low: 0, passed: 0 };
     const hunks = report.items.map((item) => {
         counts[item.status] += 1;
@@ -136,6 +147,9 @@ export function connectedAnalysisOf(report, snapshotId, reviewId, reportUrl, sco
         const note = noteOf(item);
         if (note !== undefined)
             hunk.note = note;
+        const links = business.get(item.id);
+        if (links !== undefined)
+            hunk.business = links;
         return hunk;
     });
     const answered = report.questions.filter((question) => question.answer !== undefined).length;
@@ -159,5 +173,19 @@ export function connectedAnalysisOf(report, snapshotId, reviewId, reportUrl, sco
     if (report.agentComments !== undefined) {
         analysis.suggestions = { suggestedBy: report.agentComments.suggestedBy, comments: report.agentComments.comments };
     }
+    // Only finish_review stores a summary, so this is present exactly when the
+    // agent's whole reading was accepted for this snapshot's report; it is copied
+    // verbatim, attributed, and never synthesized here.
+    if (report.agentSummary !== undefined)
+        analysis.summary = report.agentSummary;
+    const explanation = report.agentExplanation;
+    if (explanation !== undefined) {
+        analysis.explanation = {
+            explainedBy: explanation.explainedBy,
+            processes: explanation.processes.map((process) => process.title),
+            rules: explanation.rules.length,
+            functions: explanation.functions.length,
+        };
+    }
     return analysis;
 }