diffninja 0.1.1 → 0.3.0

package/dist/review/explanation.d.ts

@@ -0,0 +1,143 @@
+/**
+ * The reviewing agent's business explanation of a change: what each function
+ * does for the product in plain words, the business processes the change
+ * touches drawn as steps and decisions, and the business rules it adds, changes,
+ * or removes.
+ *
+ * diffninja never writes any of this. It lists the functions a reader meets in
+ * the call flows and around each hunk (`functionsOf`), and the host agent's
+ * model, which read the code, explains them. Everything here is mechanical:
+ * the list is a pure function of the report, and the checks bound shape and
+ * size, require plain one-line prose instead of code names, and make every
+ * reference (a function, a hunk, a next step) point at something that exists.
+ * Nothing here judges whether the explanation is right; the pages show it
+ * attributed to the client that wrote it, as its reading.
+ */
+import type { CallFlowNode, ReviewReport } from "./types.js";
+/** Most functions one review asks the agent to explain; changed code first. */
+export declare const MAX_EXPLAINED_FUNCTIONS = 40;
+/** Most processes one explanation draws: the flows a pull request actually touches. */
+export declare const MAX_PROCESSES = 4;
+/** Most steps one process draws; past this a diagram stops being readable. */
+export declare const MAX_PROCESS_STEPS = 16;
+export declare const MIN_PROCESS_STEPS = 2;
+/** Most business rules one explanation lists. */
+export declare const MAX_RULES = 12;
+/** Most outgoing arrows one step has: a decision's branches, not a switch table. */
+export declare const MAX_STEP_EXITS = 4;
+export declare const MAX_PURPOSE_CHARS = 200;
+export declare const MAX_TITLE_CHARS = 80;
+export declare const MAX_STEP_CHARS = 90;
+export declare const MAX_DETAIL_CHARS = 200;
+export declare const MAX_RULE_CHARS = 200;
+export declare const MAX_BRANCH_CHARS = 24;
+export type ExplanationChange = "unchanged" | "added" | "changed" | "removed";
+export type StepKind = "start" | "action" | "decision" | "end";
+export declare const EXPLANATION_CHANGES: readonly ExplanationChange[];
+export declare const STEP_KINDS: readonly StepKind[];
+/**
+ * One function the agent explains. Its id is readable and deterministic,
+ * `<defining file>#<name>`, so an agent can name it from the code alone.
+ */
+export interface ExplainedFunction {
+    readonly id: string;
+    /** The function's own name, as the code spells it. */
+    readonly name: string;
+    /** The file that defines it. */
+    readonly file: string;
+    /** 1-based definition line at the revision the report read it from. */
+    readonly line: number;
+    /** True when the definition lives in a test file (by path convention). */
+    readonly inTests: boolean;
+}
+export interface StepExit {
+    readonly to: string;
+    /** The branch's condition in a word or two, such as "yes", "paid", or "out of stock". */
+    readonly when?: string;
+}
+export interface ProcessStep {
+    readonly id: string;
+    readonly kind: StepKind;
+    /** What happens, as a person would say it. */
+    readonly text: string;
+    readonly change: ExplanationChange;
+    /** Why, or the rule this step applies. */
+    detail?: string;
+    /** For a changed step: how it worked before this change. */
+    before?: string;
+    /** Function ids from `report.functions` that carry this step out. */
+    functions?: readonly string[];
+    /** Hunk ids from `report.items` that change this step. */
+    hunks?: readonly string[];
+    /** Where the process goes next; omitted on an action or start, it continues to the next step listed. */
+    next?: readonly StepExit[];
+}
+export interface BusinessProcess {
+    readonly title: string;
+    readonly steps: readonly ProcessStep[];
+}
+export interface BusinessRule {
+    readonly text: string;
+    readonly change: ExplanationChange;
+    /** For a changed rule: what the rule was before. */
+    before?: string;
+    hunks?: readonly string[];
+}
+export interface FunctionPurpose {
+    readonly id: string;
+    readonly purpose: string;
+}
+/** The explanation as the agent sends it. */
+export interface ExplanationInput {
+    readonly functions: readonly FunctionPurpose[];
+    readonly processes: readonly BusinessProcess[];
+    readonly rules: readonly BusinessRule[];
+}
+/** The accepted explanation, attributed to the MCP client that wrote it. */
+export interface AgentExplanation extends ExplanationInput {
+    readonly explainedBy: string;
+    readonly explainedAt: string;
+}
+/** The explanation's counts, as finish_review and record_explanation report them. */
+export interface ExplanationCounts {
+    readonly functions: number;
+    readonly processes: number;
+    readonly steps: number;
+    readonly rules: number;
+}
+export declare function functionId(file: string, name: string): string;
+/** The function id a call-flow node's resolved definition has, or undefined when it resolved none. */
+export declare function nodeFunctionId(node: CallFlowNode): string | undefined;
+/**
+ * Every function a reader meets in this report, once, capped at
+ * {@link MAX_EXPLAINED_FUNCTIONS}: the definitions around each hunk in report
+ * order (the changed code, its callers and callees), then the resolved
+ * definitions in the call flows. Calls with no definition in the repository
+ * (library and framework calls) are not listed: there is nothing of the
+ * project's own to explain. Functions outside test files come first, so a cap
+ * cuts test helpers before product code.
+ */
+export declare function functionsOf(report: Pick<ReviewReport, "items" | "callFlows">): ExplainedFunction[];
+/**
+ * Check a whole explanation against the review it explains. It must explain
+ * every function the review lists, each once; draw one to
+ * {@link MAX_PROCESSES} processes whose steps and exits all resolve; and list at
+ * most {@link MAX_RULES} rules, a changed one saying what it was before. The
+ * first problem refuses the whole explanation.
+ */
+export declare function checkExplanation(report: ReviewReport, input: ExplanationInput): void;
+/** Trim every text field and drop empty optional lists, so the pages render exactly what was checked. */
+export declare function normalizeExplanation(input: ExplanationInput, explainedBy: string): AgentExplanation;
+export declare function explanationCounts(input: ExplanationInput): ExplanationCounts;
+/** The agent's purpose for each function id, empty when there is no explanation. */
+export declare function purposesOf(report: Pick<ReviewReport, "agentExplanation">): Map<string, string>;
+/**
+ * Where each step goes, with the implicit exits made explicit: a start or action
+ * step with no `next` continues to the step listed after it. A decision always
+ * lists its own exits, and an end has none.
+ */
+export declare function exitsOf(process: BusinessProcess): Map<string, readonly StepExit[]>;
+/** Greedy word wrap; a word longer than the line gets a line of its own. */
+export declare function wrapWords(text: string, width: number): string[];
+/** At most `maxLines` wrapped lines; the last one ends in an ellipsis when text was cut. */
+export declare function wrapPurpose(text: string, width: number, maxLines: number): string[];

package/dist/review/explanation.js

@@ -0,0 +1,310 @@
+/**
+ * The reviewing agent's business explanation of a change: what each function
+ * does for the product in plain words, the business processes the change
+ * touches drawn as steps and decisions, and the business rules it adds, changes,
+ * or removes.
+ *
+ * diffninja never writes any of this. It lists the functions a reader meets in
+ * the call flows and around each hunk (`functionsOf`), and the host agent's
+ * model, which read the code, explains them. Everything here is mechanical:
+ * the list is a pure function of the report, and the checks bound shape and
+ * size, require plain one-line prose instead of code names, and make every
+ * reference (a function, a hunk, a next step) point at something that exists.
+ * Nothing here judges whether the explanation is right; the pages show it
+ * attributed to the client that wrote it, as its reading.
+ */
+import { testLikeFile } from "./file-role.js";
+/** Most functions one review asks the agent to explain; changed code first. */
+export const MAX_EXPLAINED_FUNCTIONS = 40;
+/** Most processes one explanation draws: the flows a pull request actually touches. */
+export const MAX_PROCESSES = 4;
+/** Most steps one process draws; past this a diagram stops being readable. */
+export const MAX_PROCESS_STEPS = 16;
+export const MIN_PROCESS_STEPS = 2;
+/** Most business rules one explanation lists. */
+export const MAX_RULES = 12;
+/** Most outgoing arrows one step has: a decision's branches, not a switch table. */
+export const MAX_STEP_EXITS = 4;
+export const MAX_PURPOSE_CHARS = 200;
+export const MAX_TITLE_CHARS = 80;
+export const MAX_STEP_CHARS = 90;
+export const MAX_DETAIL_CHARS = 200;
+export const MAX_RULE_CHARS = 200;
+export const MAX_BRANCH_CHARS = 24;
+export const EXPLANATION_CHANGES = ["unchanged", "added", "changed", "removed"];
+export const STEP_KINDS = ["start", "action", "decision", "end"];
+/** A function's name without its receiver: `self.save` and `Order.save` are the same `save`. */
+function shortName(name) {
+    const bare = name.replace(/^(?:before|after):/, "");
+    const segments = bare.split(/[.:#]+/).filter((segment) => segment !== "");
+    return segments.length === 0 ? bare : segments[segments.length - 1];
+}
+export function functionId(file, name) {
+    return `${file}#${shortName(name)}`;
+}
+/** The function id a call-flow node's resolved definition has, or undefined when it resolved none. */
+export function nodeFunctionId(node) {
+    return node.source === undefined ? undefined : functionId(node.source.file, node.key);
+}
+/**
+ * Every function a reader meets in this report, once, capped at
+ * {@link MAX_EXPLAINED_FUNCTIONS}: the definitions around each hunk in report
+ * order (the changed code, its callers and callees), then the resolved
+ * definitions in the call flows. Calls with no definition in the repository
+ * (library and framework calls) are not listed: there is nothing of the
+ * project's own to explain. Functions outside test files come first, so a cap
+ * cuts test helpers before product code.
+ */
+export function functionsOf(report) {
+    const found = new Map();
+    const add = (file, name, line) => {
+        const id = functionId(file, name);
+        if (found.has(id) || shortName(name) === "")
+            return;
+        found.set(id, { id, name: shortName(name), file, line, inTests: testLikeFile(file) });
+    };
+    for (const item of report.items) {
+        for (const node of item.contextNodes ?? [])
+            add(node.file, node.key, node.line);
+    }
+    const walk = (node) => {
+        if (node.source !== undefined)
+            add(node.source.file, node.key, node.source.line);
+        node.children.forEach(walk);
+    };
+    for (const entry of report.callFlows)
+        entry.trees.forEach(walk);
+    const all = [...found.values()];
+    return [...all.filter((fn) => !fn.inTests), ...all.filter((fn) => fn.inTests)].slice(0, MAX_EXPLAINED_FUNCTIONS);
+}
+const CONTROL_CHARACTERS = /[^\P{Cc}]/u;
+/** Markdown or HTML a person would not type into one line of plain explanation. */
+const SCAFFOLDING = /^\s*(?:#{1,6}\s|>|[-*+]\s|\d+[.)]\s|\|)|(?:\*\*|__|```|~~~|<\/?[a-z][^>]*>|!?\[[^\]]*\]\()/i;
+/** Code a reader would have to decode: a call, a backtick span, a snake_case name, or a source path. */
+const CODE_LIKE = [
+    { pattern: /`/, what: "a code span" },
+    // Glued to its parenthesis, as code writes it; prose puts a space before one.
+    { pattern: /[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*\(/, what: "a function call" },
+    { pattern: /\b[a-z][a-z0-9]*_[a-z0-9_]*[a-z0-9]\b/, what: "a snake_case name" },
+    // A path needs a directory, so product names such as Node.js stay prose.
+    { pattern: /\b[\w.-]+\/[\w./-]*\.(?:py|pyi|ts|tsx|js|jsx|mjs|cjs|go|rb|java|kt|kts|rs|cs|php|swift|scala|c|cc|cpp|h|hpp|m|ex|exs|lua|pl|sol|zig|hs|ml)\b/, what: "a source file path" },
+];
+/** Why one field is not plain prose, or undefined when it is. */
+function proseProblem(text, max) {
+    if (text.trim() === "")
+        return "is empty";
+    if (CONTROL_CHARACTERS.test(text))
+        return "must be one line of plain text, with no line breaks, tabs, or control characters";
+    if (text.trim().length > max)
+        return `is longer than ${max} characters`;
+    if (SCAFFOLDING.test(text))
+        return "uses Markdown or HTML formatting; write plain prose";
+    for (const { pattern, what } of CODE_LIKE) {
+        const match = pattern.exec(text);
+        if (match !== null)
+            return `reads like code (${what}: "${match[0]}"); say what it does for the business or the user in plain words, not the code's names`;
+    }
+    return undefined;
+}
+function checkProse(where, text, max, required) {
+    if (text === undefined) {
+        if (required)
+            throw new Error(`${where} is missing.`);
+        return;
+    }
+    const problem = proseProblem(text, max);
+    if (problem !== undefined)
+        throw new Error(`${where} ${problem}.`);
+}
+function checkHunks(where, hunks, items) {
+    hunks?.forEach((id, index) => {
+        if (!items.has(id))
+            throw new Error(`${where}.hunks[${index}] names a hunk this review does not have; use an items[].id.`);
+    });
+}
+function checkChange(where, change, before) {
+    if (!EXPLANATION_CHANGES.some((known) => known === change)) {
+        throw new Error(`${where}.change must be one of ${EXPLANATION_CHANGES.join(", ")}.`);
+    }
+    if (before !== undefined && change !== "changed")
+        throw new Error(`${where}.before is only for a changed ${where.includes("rules") ? "rule" : "step"}.`);
+}
+function checkProcess(process, at, functions, items) {
+    const where = `processes[${at}]`;
+    checkProse(`${where}.title`, process.title, MAX_TITLE_CHARS, true);
+    const steps = process.steps;
+    if (steps.length < MIN_PROCESS_STEPS || steps.length > MAX_PROCESS_STEPS) {
+        throw new Error(`${where} has ${steps.length} steps; draw ${MIN_PROCESS_STEPS} to ${MAX_PROCESS_STEPS}.`);
+    }
+    const ids = new Set();
+    steps.forEach((step, index) => {
+        if (ids.has(step.id))
+            throw new Error(`${where}.steps[${index}] repeats the step id ${step.id}.`);
+        ids.add(step.id);
+    });
+    steps.forEach((step, index) => {
+        const at = `${where}.steps[${index}]`;
+        if (!STEP_KINDS.includes(step.kind))
+            throw new Error(`${at}.kind must be one of ${STEP_KINDS.join(", ")}.`);
+        checkProse(`${at}.text`, step.text, MAX_STEP_CHARS, true);
+        checkProse(`${at}.detail`, step.detail, MAX_DETAIL_CHARS, false);
+        checkChange(at, step.change, step.before);
+        checkProse(`${at}.before`, step.before, MAX_DETAIL_CHARS, false);
+        step.functions?.forEach((id, fn) => {
+            if (!functions.has(id))
+                throw new Error(`${at}.functions[${fn}] is not a function this review lists; use an id from functions.`);
+        });
+        checkHunks(at, step.hunks, items);
+        const exits = step.next ?? [];
+        if (exits.length > MAX_STEP_EXITS)
+            throw new Error(`${at} has ${exits.length} exits; a step has at most ${MAX_STEP_EXITS}.`);
+        const targets = new Set();
+        exits.forEach((exit, index) => {
+            if (!ids.has(exit.to))
+                throw new Error(`${at}.next[${index}] goes to ${exit.to}, which is not a step of this process.`);
+            if (targets.has(exit.to))
+                throw new Error(`${at}.next[${index}] repeats an exit to ${exit.to}.`);
+            targets.add(exit.to);
+            checkProse(`${at}.next[${index}].when`, exit.when, MAX_BRANCH_CHARS, step.kind === "decision");
+        });
+        if (step.kind === "decision" && exits.length < 2)
+            throw new Error(`${at} is a decision, so it needs at least two next steps, each with when.`);
+        if (step.kind === "end" && exits.length > 0)
+            throw new Error(`${at} is an end, so it has no next steps.`);
+    });
+}
+/**
+ * Check a whole explanation against the review it explains. It must explain
+ * every function the review lists, each once; draw one to
+ * {@link MAX_PROCESSES} processes whose steps and exits all resolve; and list at
+ * most {@link MAX_RULES} rules, a changed one saying what it was before. The
+ * first problem refuses the whole explanation.
+ */
+export function checkExplanation(report, input) {
+    const listedFunctions = report.functions ?? [];
+    const listed = new Map(listedFunctions.map((fn) => [fn.id, fn]));
+    const items = new Set(report.items.map((item) => item.id));
+    const explained = new Set();
+    input.functions.forEach((entry, index) => {
+        if (!listed.has(entry.id))
+            throw new Error(`explanation.functions[${index}] names ${JSON.stringify(entry.id)}, which is not in this review's functions list.`);
+        if (explained.has(entry.id))
+            throw new Error(`explanation.functions[${index}] explains ${entry.id} a second time.`);
+        explained.add(entry.id);
+        checkProse(`explanation.functions[${index}].purpose`, entry.purpose, MAX_PURPOSE_CHARS, true);
+    });
+    const missing = listedFunctions.filter((fn) => !explained.has(fn.id));
+    if (missing.length > 0) {
+        throw new Error(`explanation.functions leaves out ${missing.length} of ${listedFunctions.length} functions, starting with ${missing[0].id}; explain every function the review lists, in one plain sentence each.`);
+    }
+    if (input.processes.length < 1 || input.processes.length > MAX_PROCESSES) {
+        throw new Error(`explanation.processes has ${input.processes.length} processes; draw 1 to ${MAX_PROCESSES}: the business flows this change touches.`);
+    }
+    const functions = new Set(listed.keys());
+    input.processes.forEach((process, index) => checkProcess(process, index, functions, items));
+    if (input.rules.length > MAX_RULES)
+        throw new Error(`explanation.rules has ${input.rules.length} rules; list at most ${MAX_RULES}.`);
+    input.rules.forEach((rule, index) => {
+        const where = `explanation.rules[${index}]`;
+        checkProse(`${where}.text`, rule.text, MAX_RULE_CHARS, true);
+        checkChange(where, rule.change, rule.before);
+        if (rule.change === "changed")
+            checkProse(`${where}.before`, rule.before, MAX_RULE_CHARS, true);
+        checkHunks(where, rule.hunks, items);
+    });
+}
+/** Trim every text field and drop empty optional lists, so the pages render exactly what was checked. */
+export function normalizeExplanation(input, explainedBy) {
+    const processes = input.processes.map((process) => ({
+        title: process.title.trim(),
+        steps: process.steps.map(normalizeStep),
+    }));
+    const rules = input.rules.map((rule) => {
+        const kept = { text: rule.text.trim(), change: rule.change };
+        if (rule.before !== undefined)
+            kept.before = rule.before.trim();
+        if (rule.hunks !== undefined && rule.hunks.length > 0)
+            kept.hunks = [...rule.hunks];
+        return kept;
+    });
+    return {
+        functions: input.functions.map(({ id, purpose }) => ({ id, purpose: purpose.trim() })),
+        processes,
+        rules,
+        explainedBy,
+        explainedAt: new Date().toISOString(),
+    };
+}
+function normalizeStep(step) {
+    const kept = { id: step.id, kind: step.kind, text: step.text.trim(), change: step.change };
+    if (step.detail !== undefined)
+        kept.detail = step.detail.trim();
+    if (step.before !== undefined)
+        kept.before = step.before.trim();
+    if (step.functions !== undefined && step.functions.length > 0)
+        kept.functions = [...step.functions];
+    if (step.hunks !== undefined && step.hunks.length > 0)
+        kept.hunks = [...step.hunks];
+    if (step.next !== undefined && step.next.length > 0) {
+        kept.next = step.next.map((exit) => (exit.when === undefined ? { to: exit.to } : { to: exit.to, when: exit.when.trim() }));
+    }
+    return kept;
+}
+export function explanationCounts(input) {
+    return {
+        functions: input.functions.length,
+        processes: input.processes.length,
+        steps: input.processes.reduce((total, process) => total + process.steps.length, 0),
+        rules: input.rules.length,
+    };
+}
+/** The agent's purpose for each function id, empty when there is no explanation. */
+export function purposesOf(report) {
+    return new Map((report.agentExplanation?.functions ?? []).map((entry) => [entry.id, entry.purpose]));
+}
+/**
+ * Where each step goes, with the implicit exits made explicit: a start or action
+ * step with no `next` continues to the step listed after it. A decision always
+ * lists its own exits, and an end has none.
+ */
+export function exitsOf(process) {
+    const exits = new Map();
+    process.steps.forEach((step, index) => {
+        const following = process.steps[index + 1];
+        if (step.next !== undefined && step.next.length > 0)
+            exits.set(step.id, step.next);
+        else if (step.kind !== "end" && step.kind !== "decision" && following !== undefined)
+            exits.set(step.id, [{ to: following.id }]);
+        else
+            exits.set(step.id, []);
+    });
+    return exits;
+}
+/** Greedy word wrap; a word longer than the line gets a line of its own. */
+export function wrapWords(text, width) {
+    const lines = [];
+    let line = "";
+    for (const word of text.split(/\s+/).filter((part) => part !== "")) {
+        if (line === "")
+            line = word;
+        else if (line.length + 1 + word.length <= width)
+            line = `${line} ${word}`;
+        else {
+            lines.push(line);
+            line = word;
+        }
+    }
+    if (line !== "")
+        lines.push(line);
+    return lines.length === 0 ? [""] : lines;
+}
+/** At most `maxLines` wrapped lines; the last one ends in an ellipsis when text was cut. */
+export function wrapPurpose(text, width, maxLines) {
+    const lines = wrapWords(text, Math.max(8, width));
+    if (lines.length <= maxLines)
+        return lines;
+    const kept = lines.slice(0, maxLines);
+    const last = kept[maxLines - 1];
+    kept[maxLines - 1] = last.length + 1 > width ? `${last.slice(0, Math.max(1, width - 1))}\u2026` : `${last}\u2026`;
+    return kept;
+}

package/dist/review/html.d.ts

@@ -25,6 +25,13 @@ import type { ReviewReport } from "./types.js";
  * request body or report field is HTML-escaped.
  */
 export declare function renderReview(report: ReviewReport): string;
+/**
+ * The business view alone, for the pull request page to frame under its goal:
+ * the processes, the rules, and the glossary, with no links into a diff (the
+ * page around it has its own). Server-rendered; its one script only reports
+ * the document's height to the framing page.
+ */
+export declare function renderBusinessPage(report: ReviewReport): string;
 /**
  * The call flows of one review as a page of their own, for the connected pull
  * request page to show beside its diff: every changed file with call flows, or

package/dist/review/html.js

@@ -2,6 +2,7 @@ import { verdictOf } from "./questions.js";
 import { factQuestionsFor } from "./change-facts.js";
 import { renderCallFlows, CALL_FLOW_STYLES, CALL_FLOW_SCRIPT } from "./call-flow-html.js";
 import { renderBrief, BRIEF_STYLES } from "./evidence-html.js";
+import { renderBusinessView, BUSINESS_STYLES } from "./process-html.js";
 import { BRAND_MARK, BRAND_MARK_STYLES } from "./brand.js";
 import { PALETTE_STYLES } from "./palette.js";
 import { escapeHtml } from "./escape-html.js";
@@ -52,17 +53,19 @@ export function renderReview(report) {
         '<meta name="viewport" content="width=device-width, initial-scale=1">',
         '<meta name="color-scheme" content="light dark">',
         `<title>${escapeHtml(`diffninja review: ${report.title || "untitled diff"}`)}</title>`,
-        `<style>${STYLES}\n${BRIEF_STYLES}\n${CALL_FLOW_STYLES}</style>`,
+        `<style>${STYLES}\n${BRIEF_STYLES}\n${CALL_FLOW_STYLES}\n${BUSINESS_STYLES}\n${BUSINESS_VIEW_STYLES}</style>`,
         "</head>",
-        `<body data-default-view="${report.evidence === undefined ? "call-flow" : "brief"}">`,
+        `<body data-default-view="${defaultView(report)}">`,
         '<div class="wrap">',
         renderHeader(report),
         renderAgentOrder(report),
         '<nav class="view-switch" aria-label="Report view">',
+        '<a href="#view-business" data-view="business">How it works</a>',
         '<a href="#view-brief" data-view="brief">Outcome</a>',
         '<a href="#view-call-flow" data-view="call-flow">Call flow</a>',
         '<a href="#view-diff" data-view="diff">Diff</a>',
         "</nav>",
+        `<section class="business" id="view-business" aria-labelledby="view-business-title">${renderBusinessSection(report)}</section>`,
         `<section class="brief" id="view-brief" aria-label="Expected outcome and reading agenda">${renderBrief(report)}</section>`,
         '<section id="view-call-flow" aria-label="Call flow">',
         renderCallFlows(report),
@@ -78,6 +81,87 @@ export function renderReview(report) {
         "",
     ].join("\n");
 }
+/**
+ * The page opens on the business view once the reviewing agent explained the
+ * change: that is the first thing a reader who does not know this code needs.
+ * Without one it opens on the agenda, or on the call flow when there is none.
+ */
+function defaultView(report) {
+    if (report.agentExplanation !== undefined)
+        return "business";
+    return report.evidence === undefined ? "call-flow" : "brief";
+}
+/** Link target of a hunk on this page: its card in the diff, by rank. */
+function hunkHref(report) {
+    const ranks = new Map(report.items.map((item, index) => [item.id, index + 1]));
+    return (itemId) => {
+        const rank = ranks.get(itemId);
+        return rank === undefined ? undefined : `#item-${rank}`;
+    };
+}
+function renderBusinessSection(report) {
+    return [
+        '<h2 class="business-title" id="view-business-title">How it works</h2>',
+        '<p class="business-lede">What this change does to the product, as processes, rules, and plain descriptions of the code it touches. The reviewing agent wrote it from the code; the diff stays the ground truth.</p>',
+        renderBusinessView(report, { hunkHref: hunkHref(report) }),
+    ].join("\n");
+}
+const BUSINESS_VIEW_STYLES = `
+.business { padding-top: 14px; }
+.business-title { font-size: 20px; }
+.business-lede { margin-top: 4px; color: var(--ink-soft); font-size: 14px; max-width: 90ch; }
+.flow-section-title { margin: 22px 0 0; font-size: 18px; }
+`;
+/**
+ * Posts the document's height to the page that frames it, so the pull request
+ * page can size its inline "How it works" frame to fit. Only the same origin
+ * receives it, and it carries a number, nothing from the report.
+ */
+const BUSINESS_FRAME_SCRIPT = `
+(function () {
+  'use strict';
+  function post() {
+    if (window.parent === window) return;
+    window.parent.postMessage({ type: 'diffninja-business-height', height: Math.ceil(document.documentElement.scrollHeight) }, window.location.origin);
+  }
+  window.addEventListener('load', post);
+  if (typeof ResizeObserver !== 'undefined') new ResizeObserver(post).observe(document.body);
+  document.addEventListener('toggle', post, true);
+  post();
+}());
+`;
+/**
+ * The business view alone, for the pull request page to frame under its goal:
+ * the processes, the rules, and the glossary, with no links into a diff (the
+ * page around it has its own). Server-rendered; its one script only reports
+ * the document's height to the framing page.
+ */
+export function renderBusinessPage(report) {
+    return [
+        "<!doctype html>",
+        '<html lang="en">',
+        "<head>",
+        '<meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        '<meta name="color-scheme" content="light dark">',
+        "<title>How it works</title>",
+        `<style>${STYLES}\n${PALETTE_STYLES}\n${BUSINESS_STYLES}\n${EMBEDDED_BUSINESS_STYLES}</style>`,
+        "</head>",
+        "<body>",
+        '<main class="business-embed" aria-label="How it works">',
+        renderBusinessView(report, { attribution: false, glossary: false, stepsOpen: false }),
+        "</main>",
+        `<script>${BUSINESS_FRAME_SCRIPT}</script>`,
+        "</body>",
+        "</html>",
+        "",
+    ].join("\n");
+}
+const EMBEDDED_BUSINESS_STYLES = `
+body { background: transparent; font-family: var(--sans); }
+.business-embed { padding: 0 2px 4px; }
+.business-embed .bp { margin-top: 0; }
+`;
 /** Trims the report's call-flow view to live inside the pull request page's drawer. */
 const EMBEDDED_FLOW_STYLES = `
 body { background: var(--bg); font-family: var(--sans); }
@@ -102,10 +186,19 @@ export function renderCallFlowPage(report, file) {
         '<meta name="viewport" content="width=device-width, initial-scale=1">',
         '<meta name="color-scheme" content="light dark">',
         `<title>${escapeHtml(file === undefined ? "Call flows" : `Call flow: ${file}`)}</title>`,
-        `<style>${STYLES}\n${CALL_FLOW_STYLES}\n${PALETTE_STYLES}\n${EMBEDDED_FLOW_STYLES}</style>`,
+        `<style>${STYLES}\n${CALL_FLOW_STYLES}\n${PALETTE_STYLES}\n${BUSINESS_STYLES}\n${BUSINESS_VIEW_STYLES}\n${EMBEDDED_FLOW_STYLES}</style>`,
         "</head>",
         "<body>",
+        report.agentExplanation === undefined
+            ? ""
+            : [
+                '<section class="flow-embed business" aria-labelledby="flow-business-title">',
+                `<h2 class="business-title" id="flow-business-title">${file === undefined ? "How it works" : "How this file fits the process"}</h2>`,
+                renderBusinessView(report, { file, glossary: false }),
+                "</section>",
+            ].join("\n"),
         `<section id="view-call-flow" class="flow-embed${file === undefined ? "" : " flow-single"}" aria-label="Call flow">`,
+        report.agentExplanation === undefined ? "" : '<h2 class="flow-section-title">Call flow</h2>',
         renderCallFlows(scoped),
         "</section>",
         `<script>document.documentElement.classList.add('js');\n${CALL_FLOW_SCRIPT}</script>`,
@@ -491,10 +584,11 @@ const SCRIPT = `
   'use strict';
   document.documentElement.classList.add('js');
   var briefView = document.getElementById('view-brief');
+  var businessView = document.getElementById('view-business');
   var diffView = document.getElementById('view-diff');
   var flowView = document.getElementById('view-call-flow');
   var viewLinks = Array.prototype.slice.call(document.querySelectorAll('[data-view]'));
-  var VIEWS = { brief: briefView, 'call-flow': flowView, diff: diffView };
+  var VIEWS = { business: businessView, brief: briefView, 'call-flow': flowView, diff: diffView };
   function showView(name) {
     for (var key in VIEWS) {
       if (VIEWS[key]) VIEWS[key].hidden = key !== name;