diffninja 0.2.0 → 0.3.1

package/dist/review/connected-html.js

@@ -41,6 +41,16 @@ export function renderConnectedPage(csrf) {
         '<p id="pr-goal-text" class="pr-goal-text"></p>',
         '<p id="pr-goal-by" class="pr-goal-by" hidden></p>',
         "</section>",
+        '<section id="pr-how" class="pr-how" aria-labelledby="pr-how-heading" hidden>',
+        '<details class="pr-how-fold" open>',
+        '<summary class="pr-how-head"><h2 id="pr-how-heading" class="pr-goal-heading">How it works</h2></summary>',
+        '<div class="pr-how-tools">',
+        '<p id="pr-how-by" class="pr-goal-by"></p>',
+        '<button type="button" id="pr-how-open" class="btn btn-quiet btn-sm" data-action="open-how" aria-label="Open how it works beside the diff">Open beside the diff</button>',
+        "</div>",
+        '<iframe id="pr-how-frame" class="pr-how-frame" title="How it works: the business processes and rules this change touches"></iframe>',
+        "</details>",
+        "</section>",
         '<details id="pr-description" class="pr-description" hidden>',
         '<summary>Original PR description</summary>',
         '<p class="note">The author’s own words, as written, including any generated notes. Raw HTML is shown as text, images as links, and nothing here is loaded from another host. It is the author’s claim, not evidence that the changes achieve it.</p>',
@@ -1120,6 +1130,26 @@ function script(csrf) {
     setText(el.prGoalText, goalAbsentReason(snap));
   }
 
+  /**
+   * The agent's business view under the goal: the processes and rules this
+   * change touches, drawn by the server into a same-origin frame that reports
+   * its own height. Shown only once the agent's explanation was accepted for the
+   * revision on screen; the frame reloads only when that revision changes.
+   */
+  function renderHow() {
+    var snap = snapshot();
+    var current = currentAnalysis();
+    var explanation = current && current.explanation && typeof current.explanation === 'object' ? current.explanation : null;
+    var ready = Boolean(snap) && explanation !== null && current.snapshotId === snap.id;
+    show(el.prHow, ready);
+    if (!ready) { if (el.prHowFrame.getAttribute('src')) el.prHowFrame.removeAttribute('src'); return; }
+    var by = typeof explanation.explainedBy === 'string' && explanation.explainedBy.trim() !== '' ? explanation.explainedBy.trim() : 'your review agent';
+    var processes = Array.isArray(explanation.processes) ? explanation.processes.length : 0;
+    setText(el.prHowBy, 'Explained by ' + by + ' from the code: ' + processes + (processes === 1 ? ' process' : ' processes') + ' and ' + (explanation.rules || 0) + ((explanation.rules || 0) === 1 ? ' business rule' : ' business rules') + '. Its reading, not a verdict; the diff below is the ground truth.');
+    var src = '/flow?snapshot=' + encodeURIComponent(current.snapshotId) + '&view=business';
+    if (el.prHowFrame.getAttribute('src') !== src) el.prHowFrame.setAttribute('src', src);
+  }
+
   /** Why no goal is on screen: the analysis is still coming, is of another revision, or recorded none. */
   function goalAbsentReason(snap) {
     if (!analysis || analysisFor !== snap.id) return 'Waiting for the local analysis of this revision\u2026';
@@ -1134,6 +1164,7 @@ function script(csrf) {
   /* ------------------------------------------------------------ analysis -- */
 
   var STATUS_ORDER = ['attention', 'uncertain', 'low', 'passed'];
+  var CHANGE_WORD = { added: 'New', changed: 'Changed', removed: 'Removed' };
 
   function currentAnalysis() {
     var snap = snapshot();
@@ -1267,7 +1298,8 @@ function script(csrf) {
     var verdicts = answeredVerdicts(hunk);
     var facts = Array.isArray(hunk.facts) ? hunk.facts : [];
     var note = typeof hunk.note === 'string' ? hunk.note : '';
-    if (rank === 0 && verdicts.length === 0 && facts.length === 0 && note === '') return null;
+    var business = Array.isArray(hunk.business) ? hunk.business : [];
+    if (rank === 0 && verdicts.length === 0 && facts.length === 0 && note === '' && business.length === 0) return null;
     var why = make('div', 'stop-why' + (rank > 0 ? ' has-rank' : ''));
     if (rank > 0) {
       var badge = make('span', 'why-rank', String(rank));
@@ -1275,6 +1307,19 @@ function script(csrf) {
       why.appendChild(badge);
     }
     var main = make('div', 'why-main');
+    if (business.length > 0) {
+      var steps = make('div', 'tag-row business-row');
+      steps.appendChild(make('span', 'tag-lead', 'In the business'));
+      for (var b = 0; b < business.length; b += 1) {
+        var link = business[b];
+        var change = typeof link.change === 'string' ? link.change : 'unchanged';
+        var step = make('span', 'business-step change-' + change);
+        if (change !== 'unchanged') step.appendChild(make('span', 'business-change', CHANGE_WORD[change] || change));
+        step.appendChild(make('span', 'business-text', (typeof link.process === 'string' ? link.process + ': ' : 'Rule: ') + String(link.text)));
+        steps.appendChild(step);
+      }
+      main.appendChild(steps);
+    }
     if (verdicts.length > 0) {
       var said = make('div', 'tag-row');
       said.appendChild(make('span', 'sr-only', 'Your agent says: '));
@@ -1337,6 +1382,7 @@ function script(csrf) {
     var snap = snapshot();
     // The goal rides on the analysis, so it re-renders wherever the analysis does — every poll included.
     renderGoal();
+    renderHow();
     show(el.analysisSection, Boolean(snap) && !(typeof snap.unavailableReason === 'string' && snap.unavailableReason !== ''));
     el.analysisBody.textContent = '';
     el.analysisActions.textContent = '';
@@ -1726,8 +1772,9 @@ function script(csrf) {
     var src = '/flow?snapshot=' + encodeURIComponent(current.snapshotId) + (path === '' ? '' : '&file=' + encodeURIComponent(path));
     if (el.flowFrame.getAttribute('src') !== src) el.flowFrame.setAttribute('src', src);
     flowSnapshot = current.snapshotId;
-    setText(el.flowTitle, path === '' ? 'Call flows' : 'Call flow: ' + path);
-    el.flowFrame.title = path === '' ? 'Call flows of every changed file' : 'Call flow of ' + path;
+    var explained = Boolean(current.explanation);
+    setText(el.flowTitle, path === '' ? (explained ? 'How it works and call flows' : 'Call flows') : 'Call flow: ' + path);
+    el.flowFrame.title = path === '' ? (explained ? 'How it works, and the call flows of every changed file' : 'Call flows of every changed file') : 'Call flow of ' + path;
     if (el.flowDrawer.hidden) flowReturn = opener || document.activeElement;
     show(el.flowDrawer, true);
     document.body.classList.add('flow-open');
@@ -1751,7 +1798,16 @@ function script(csrf) {
 
   /** The diagram in the drawer opened or closed: the drawer takes the whole window while it is open. */
   function onFlowMessage(event_) {
-    if (event_.origin !== window.location.origin || event_.source !== el.flowFrame.contentWindow) return;
+    if (event_.origin !== window.location.origin) return;
+    // The inline business view reports its height; nothing else it sends is read.
+    if (event_.source === el.prHowFrame.contentWindow) {
+      var sized = event_.data;
+      if (sized && sized.type === 'diffninja-business-height' && typeof sized.height === 'number' && isFinite(sized.height)) {
+        el.prHowFrame.style.height = Math.max(120, Math.min(20000, Math.ceil(sized.height))) + 'px';
+      }
+      return;
+    }
+    if (event_.source !== el.flowFrame.contentWindow) return;
     var data = event_.data;
     if (!data || data.type !== 'diffninja-diagram') return;
     document.body.classList.toggle('flow-full', data.open === true);
@@ -2499,6 +2555,7 @@ function script(csrf) {
     placeAnchor = action === 'preview' || action === 'submit' || action === 'refresh' ? node : null;
     if (action === 'comment') { event_.preventDefault(); addComment(node); return; }
     if (action === 'open-flow') { event_.preventDefault(); openFlow(node.getAttribute('data-path') || '', node); return; }
+    if (action === 'open-how') { event_.preventDefault(); openFlow('', node); return; }
     if (action === 'close-flow') { event_.preventDefault(); closeFlow(); return; }
     if (action === 'add-suggestion') { event_.preventDefault(); addSuggestion(node); return; }
     if (action === 'add-all-suggestions') { event_.preventDefault(); addAllSuggestions(); return; }
@@ -2556,6 +2613,9 @@ function script(csrf) {
     el.prGoal = byId('pr-goal');
     el.prGoalText = byId('pr-goal-text');
     el.prGoalBy = byId('pr-goal-by');
+    el.prHow = byId('pr-how');
+    el.prHowBy = byId('pr-how-by');
+    el.prHowFrame = byId('pr-how-frame');
     el.prDescription = byId('pr-description');
     el.prDescriptionBody = byId('pr-description-body');
     el.lede = byId('lede');
@@ -2682,6 +2742,21 @@ ${BRAND_MARK_STYLES}
 .pr-goal-text { margin: 6px 0 0; font-size: 15.5px; font-weight: 600; line-height: 1.5; overflow-wrap: anywhere; max-width: 90ch; }
 .pr-goal-note { margin: 6px 0 0; font-size: 13px; color: var(--ink-soft); overflow-wrap: anywhere; max-width: 90ch; }
 .pr-goal-by { margin: 6px 0 0; font-size: 12.5px; color: var(--ink-faint); overflow-wrap: anywhere; max-width: 90ch; }
+.pr-how { margin-top: 10px; padding: 14px 16px 10px; border: 1px solid var(--line); border-left: 3px solid var(--ok); border-radius: var(--radius); background: var(--panel); }
+.pr-how-head { cursor: pointer; width: fit-content; }
+.pr-how-head h2 { display: inline; }
+.pr-how-tools { display: flex; align-items: flex-start; justify-content: space-between; gap: 12px; flex-wrap: wrap; }
+.pr-how-tools .pr-goal-by { flex: 1 1 320px; }
+.pr-how-frame { display: block; width: 100%; height: 480px; margin-top: 10px; border: 0; background: transparent; color-scheme: normal; }
+.business-row { align-items: flex-start; }
+.business-step { display: inline-flex; align-items: baseline; gap: 6px; max-width: 100%; padding: 2px 8px; border: 1px solid var(--line); border-radius: 6px; font-size: 12.5px; color: var(--ink); background: var(--panel); overflow-wrap: anywhere; }
+.business-step.change-added { border-color: var(--ok); background: var(--ok-soft); }
+.business-step.change-changed { border-color: var(--warn); background: var(--warn-soft); }
+.business-step.change-removed { border-color: var(--alarm); background: var(--alarm-bg); }
+.business-change { flex: none; font-size: 10px; font-weight: 700; letter-spacing: 0.05em; text-transform: uppercase; color: var(--ink-soft); }
+.change-added .business-change { color: var(--ok); }
+.change-changed .business-change { color: var(--warn); }
+.change-removed .business-change { color: var(--alarm); }
 .pr-description { margin-top: 6px; padding: 12px 16px; border: 1px solid var(--line); border-radius: var(--radius); background: var(--panel); }
 .pr-description > summary { cursor: pointer; font-size: 14px; font-weight: 600; }
 .pr-description > .note { margin-top: 10px; }

package/dist/review/connected.d.ts

@@ -26,10 +26,12 @@ export interface ConnectedOptions {
     readonly analysis?: () => Promise<ConnectedAnalysisView>;
     /**
      * The call-flow page of the analysis of snapshot `snapshotId`, for one changed
-     * file or all of them, for `GET /flow`. Undefined when that snapshot is not
-     * the one analyzed or it has no call flows there.
+     * file or all of them, for `GET /flow`; with `view` "business", the business
+     * view alone (`GET /flow?snapshot=&view=business`), which the page shows under
+     * its goal. Undefined when that snapshot is not the one analyzed or it has
+     * nothing to show there.
      */
-    readonly flow?: (snapshotId: string, file: string | undefined) => Promise<string | undefined>;
+    readonly flow?: (snapshotId: string, file: string | undefined, view: "flow" | "business") => Promise<string | undefined>;
 }
 /** A single ephemeral session; never exposes a general GitHub API proxy. */
 export declare function serveConnected(review?: ConnectedReview, options?: ConnectedOptions): Promise<ConnectedSession>;

package/dist/review/connected.js

@@ -99,9 +99,10 @@ export async function serveConnected(review = new ConnectedReview(), options = {
             const query = new URL(req.url ?? "", origin).searchParams;
             const snapshotId = query.get("snapshot") ?? "";
             const file = query.get("file") ?? undefined;
+            const view = query.get("view") === "business" ? "business" : "flow";
             let html;
             try {
-                html = options.flow === undefined ? undefined : await options.flow(snapshotId, file);
+                html = options.flow === undefined ? undefined : await options.flow(snapshotId, file, view);
             }
             catch {
                 html = undefined;

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