diffninja 0.1.1 → 0.3.0

package/dist/review/report-pages.d.ts

@@ -11,12 +11,17 @@
  * allowed by their SHA-256 hashes, so the report HTML is served byte for byte.
  */
 import type { ReviewReport, SuggestedComment } from "./types.js";
+import { type ExplanationCounts, type ExplanationInput } from "./explanation.js";
 /** Most reports one connection keeps; the oldest page closes first. */
 export declare const MAX_REPORT_PAGES = 20;
 /** Most comments one review may carry from the agent: a reviewer's handful, not a lint dump. */
 export declare const MAX_SUGGESTED_COMMENTS = 30;
 /** Longest suggested comment: a sentence or two, the way a reviewer writes one. */
 export declare const MAX_SUGGESTED_CHARS = 280;
+/** Longest goal summary: one short paragraph a maintainer reads before the diff. */
+export declare const MAX_SUMMARY_CHARS = 600;
+/** Longest goal summary by words: the same paragraph, kept short on purpose. */
+export declare const MAX_SUMMARY_WORDS = 80;
 /** CSP naming exactly the inline script and style blocks of one page. */
 export declare function reportPolicy(html: string): string;
 /** A static review published on this connection. */
@@ -43,17 +48,33 @@ export interface RecordedComments {
     readonly reviewId: string;
     readonly suggested: number;
 }
-/** Everything the reviewing agent owes a review before its pages are handed out. */
+export interface RecordedExplanation {
+    readonly reviewId: string;
+    readonly explained: ExplanationCounts;
+}
+/**
+ * Everything the reviewing agent owes a review before its pages are handed out.
+ * `summary` is the agent's own plain-English paragraph on what the pull request
+ * does and why, taken from the pull request's own title and description; a
+ * connected review must send it, a static report need not.
+ */
 export interface FinishInput {
     readonly answers: readonly AnswerInput[];
     readonly order: readonly string[];
     readonly comments: readonly SuggestedComment[];
+    readonly summary?: string;
+    /** The business explanation: every listed function's purpose, the processes, and the rules. */
+    readonly explanation?: ExplanationInput;
 }
 export interface FinishedReview {
     readonly reviewId: string;
     readonly answered: number;
     readonly ordered: number;
     readonly suggested: number;
+    /** Characters of the goal summary kept, or 0 when none was sent. */
+    readonly summarized: number;
+    /** What the business explanation holds, or absent when none was sent. */
+    explained?: ExplanationCounts;
     readonly reportUrl: string;
 }
 export declare class ReportPages {
@@ -69,11 +90,17 @@ export declare class ReportPages {
     publish(report: ReviewReport): Promise<PublishedReview>;
     /**
      * Accept the reviewing agent's whole reading of a review at once: an answer
-     * to every question, the reading order of every hunk, and the line comments
-     * it suggests (an empty list says it has none). Everything is checked before
+     * to every question, the reading order of every hunk, the line comments it
+     * suggests (an empty list says it has none), and, for a connected pull
+     * request, one short paragraph on the goal. Everything is checked before
      * anything is kept, so one gap or bad entry refuses the call and changes
      * nothing. Only a finished review's page addresses are handed out: an agent
      * cannot give the human a page it has not finished reading.
+     *
+     * `summary` is checked here like any other field, so a bad paragraph refuses
+     * the answers and the order with it; whether a connected review *owes* one is
+     * the caller's decision (see mcp.ts), because only it knows which reviews are
+     * pull request reviews.
      */
     finish(reviewId: string, input: FinishInput, by: string): FinishedReview;
     /** Whether finish_review accepted this review, so its addresses may be handed out again. */
@@ -100,6 +127,13 @@ export declare class ReportPages {
      * call and keeps the previous set; an empty list clears it.
      */
     suggestComments(reviewId: string, comments: readonly SuggestedComment[], suggestedBy: string): RecordedComments;
+    /**
+     * Replace the business explanation of a review: a purpose for every function
+     * the review lists, the processes the change touches, and its business rules.
+     * The whole explanation is checked first; any problem refuses the call and
+     * keeps the previous one.
+     */
+    recordExplanation(reviewId: string, explanation: ExplanationInput, explainedBy: string): RecordedExplanation;
     private review;
     private rerender;
     private origin;

package/dist/review/report-pages.js

@@ -13,13 +13,26 @@
 import { createHash, randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import { z } from "zod";
+import { checkExplanation, explanationCounts, normalizeExplanation } from "./explanation.js";
 /** Most reports one connection keeps; the oldest page closes first. */
 export const MAX_REPORT_PAGES = 20;
 /** Most comments one review may carry from the agent: a reviewer's handful, not a lint dump. */
 export const MAX_SUGGESTED_COMMENTS = 30;
 /** Longest suggested comment: a sentence or two, the way a reviewer writes one. */
 export const MAX_SUGGESTED_CHARS = 280;
+/** Longest goal summary: one short paragraph a maintainer reads before the diff. */
+export const MAX_SUMMARY_CHARS = 600;
+/** Longest goal summary by words: the same paragraph, kept short on purpose. */
+export const MAX_SUMMARY_WORDS = 80;
 const CONTROL_CHARACTERS = /[^\P{Cc}]/u;
+/**
+ * Report scaffolding a person would not write as a goal summary. The summary is
+ * one paragraph with no line breaks, so a heading, quote, or list marker can
+ * only open it; bold, code spans, links, tables, and tags are caught anywhere.
+ * Ordinary prose stays untouched: a sentence that ends in a number ("a fixed
+ * 10.") or a hyphen inside a phrase is not scaffolding.
+ */
+const SUMMARY_SCAFFOLDING = /^\s*(?:#{1,6}\s|>|```|~~~|[-*+]\s|\d+[.)]\s|\|)|(?:\*\*|__|\||```|~~~|`|<\/?[a-z][^>]*>|!?\[[^\]]*\]\()/i;
 /** Report scaffolding a person would not write in a review comment: "Finding 1:", "Attention -", "**Error**", "## Bug". */
 const REPORT_LABEL = /^\s*(?:#|>|[-*+]\s|\d+[.)]\s|\*\*|\[)|^\s*(?:findings?|issues?|attention|errors?|warnings?|bugs?|problems?|severity|critical|major|minor|high|medium|low|concerns?|risks?|suggestions?|observations?|summary)\b\s*#?\d*\s*[:\-\u2013\u2014.]|\*\*/i;
 const INLINE_BLOCK = /<(script|style)>([\s\S]*?)<\/\1>/g;
@@ -109,6 +122,29 @@ function applyComments(report, comments, suggestedBy) {
         suggestedAt: new Date().toISOString(),
     };
 }
+/**
+ * The goal paragraph the agent sent, trimmed and validated, or undefined when it
+ * sent none. The bounds are mechanical — one non-empty paragraph of plain prose
+ * within {@link MAX_SUMMARY_CHARS} characters and {@link MAX_SUMMARY_WORDS}
+ * words, with no control characters and no Markdown scaffolding. Nothing here
+ * judges the writing itself, and a bad paragraph refuses the whole call.
+ */
+function checkSummary(summary) {
+    if (summary === undefined)
+        return undefined;
+    const text = summary.trim();
+    if (text === "")
+        throw new Error("summary is empty; write one short paragraph on what the pull request does and why, from its own title and description.");
+    if (CONTROL_CHARACTERS.test(text))
+        throw new Error("summary must be one paragraph of plain text: no line breaks, tabs, or other control characters.");
+    if (text.length > MAX_SUMMARY_CHARS)
+        throw new Error(`summary is longer than ${MAX_SUMMARY_CHARS} characters; write one short paragraph.`);
+    if (text.split(/\s+/).length > MAX_SUMMARY_WORDS)
+        throw new Error(`summary is longer than ${MAX_SUMMARY_WORDS} words; write one short paragraph.`);
+    if (SUMMARY_SCAFFOLDING.test(text))
+        throw new Error("summary uses Markdown or HTML formatting (a heading, list, bold, code, quote, link, table, or tag); write plain prose.");
+    return text;
+}
 /** Map key of one commentable line. */
 function anchorKey(path, side, line) {
     return JSON.stringify([path, side, line]);
@@ -179,11 +215,17 @@ export class ReportPages {
     }
     /**
      * Accept the reviewing agent's whole reading of a review at once: an answer
-     * to every question, the reading order of every hunk, and the line comments
-     * it suggests (an empty list says it has none). Everything is checked before
+     * to every question, the reading order of every hunk, the line comments it
+     * suggests (an empty list says it has none), and, for a connected pull
+     * request, one short paragraph on the goal. Everything is checked before
      * anything is kept, so one gap or bad entry refuses the call and changes
      * nothing. Only a finished review's page addresses are handed out: an agent
      * cannot give the human a page it has not finished reading.
+     *
+     * `summary` is checked here like any other field, so a bad paragraph refuses
+     * the answers and the order with it; whether a connected review *owes* one is
+     * the caller's decision (see mcp.ts), because only it knows which reviews are
+     * pull request reviews.
      */
     finish(reviewId, input, by) {
         const { token, page, report } = this.review(reviewId);
@@ -195,18 +237,29 @@ export class ReportPages {
         }
         checkOrder(report, input.order);
         checkComments(report, input.comments);
+        const summary = checkSummary(input.summary);
+        if (input.explanation !== undefined)
+            checkExplanation(report, input.explanation);
         applyAnswers(report, input.answers, by);
         applyOrder(report, input.order, by);
         applyComments(report, input.comments, by);
+        if (summary !== undefined)
+            report.agentSummary = { text: summary, summarizedBy: by };
+        if (input.explanation !== undefined)
+            report.agentExplanation = normalizeExplanation(input.explanation, by);
         page.finished = true;
         this.rerender(page, report);
-        return {
+        const finished = {
             reviewId,
             answered: input.answers.length,
             ordered: input.order.length,
             suggested: input.comments.length,
+            summarized: summary?.length ?? 0,
             reportUrl: `${this.origin}/report/${token}`,
         };
+        if (input.explanation !== undefined)
+            finished.explained = explanationCounts(input.explanation);
+        return finished;
     }
     /** Whether finish_review accepted this review, so its addresses may be handed out again. */
     isFinished(reviewId) {
@@ -253,6 +306,19 @@ export class ReportPages {
         this.rerender(page, report);
         return { reviewId, suggested: comments.length };
     }
+    /**
+     * Replace the business explanation of a review: a purpose for every function
+     * the review lists, the processes the change touches, and its business rules.
+     * The whole explanation is checked first; any problem refuses the call and
+     * keeps the previous one.
+     */
+    recordExplanation(reviewId, explanation, explainedBy) {
+        const { page, report } = this.review(reviewId);
+        checkExplanation(report, explanation);
+        report.agentExplanation = normalizeExplanation(explanation, explainedBy);
+        this.rerender(page, report);
+        return { reviewId, explained: explanationCounts(explanation) };
+    }
     review(reviewId) {
         const token = this.tokens.get(reviewId);
         const page = token === undefined ? undefined : this.pages.get(token);

package/dist/review/service.js

@@ -12,6 +12,7 @@ import { checkReferences } from "./reference-check.js";
 import { moduleResolver } from "./module-resolution.js";
 import { reviewQuestions } from "./questions.js";
 import { readProjectContext } from "./history.js";
+import { functionsOf } from "./explanation.js";
 /** Context width may differ, but source-enriched patches must describe the same changed lines. */
 function changedLineIdentity(units) {
     const changes = [];
@@ -191,7 +192,8 @@ export async function reviewDiff(input, options = {}) {
         pr: options.pr,
         evidence: { ...evidence, intent: crossCheckIntent(options.pr, units, evidence.agenda, evidence.findings) },
         ...result, callFlow, callFlows, callFlowAvailability, warnings: [...warnings, ...result.warnings],
-        questions: reviewQuestions(result.items, options.pr, project) };
+        questions: reviewQuestions(result.items, options.pr, project),
+        functions: functionsOf({ items: result.items, callFlows }) };
     if (project !== undefined)
         report.project = project;
     return report;

package/dist/review/types.d.ts

@@ -2,6 +2,7 @@ import type { PullRequestIntent, ReviewEvidence } from "./evidence-types.js";
 import type { ChangeFacts } from "./change-facts.js";
 import type { ReviewQuestion } from "./questions.js";
 import type { HunkHistory, ProjectContext } from "./history.js";
+import type { AgentExplanation, ExplainedFunction } from "./explanation.js";
 export type ReviewStatus = "attention" | "uncertain" | "low" | "passed";
 /**
  * Structural status for a call-flow node. The engine only knows `same`,
@@ -143,6 +144,18 @@ export interface AgentComments {
     suggestedBy: string;
     suggestedAt: string;
 }
+/**
+ * The reviewing agent's own plain-English description of what the pull request
+ * does and why, written for the human before they read the diff. It is the
+ * agent's reading, never diffninja's and never a claim that the changes achieve
+ * the goal: the page shows it attributed, as a description.
+ */
+export interface AgentSummary {
+    /** One short paragraph: the goal, why it matters, and the limits a reviewer should know. */
+    text: string;
+    /** The MCP client that wrote it, as it names itself. */
+    summarizedBy: string;
+}
 export interface ReviewReport {
     title: string;
     source: string;
@@ -165,6 +178,27 @@ export interface ReviewReport {
     agentOrder?: AgentOrder;
     /** Line comments the reviewing agent suggested; nothing is posted until the human submits them. */
     agentComments?: AgentComments;
+    /**
+     * The reviewing agent's own paragraph on the pull request's goal, written
+     * from the author's title and description. Only finish_review's accepted
+     * reading stores it, so an unfinished report never carries one, and it is the
+     * agent's reading rather than a verified claim.
+     */
+    agentSummary?: AgentSummary;
+    /**
+     * Every function a reader meets in this report (around the hunks and in the
+     * call flows), each with a stable `<file>#<name>` id, for the reviewing agent
+     * to explain in business terms. Empty for a patch, which resolves none;
+     * absent only on a report assembled by hand, which counts as empty.
+     */
+    functions?: ExplainedFunction[];
+    /**
+     * The reviewing agent's business explanation: a plain purpose for every
+     * listed function, the processes the change touches as steps and decisions,
+     * and the business rules it adds, changes, or removes. Attributed to the
+     * client that wrote it; never generated by diffninja.
+     */
+    agentExplanation?: AgentExplanation;
     /**
      * Local repository context for a git-range review: prior reverts, contributor
      * guidelines, and sibling-file conventions. Absent for a patch.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffninja",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Local, deterministic PR review for coding agents over MCP: call flows, change facts, and a human review workspace",
   "type": "module",
   "exports": {
@@ -61,6 +61,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "incur": "^0.4.26",
+    "marked": "^18.0.14",
     "picocolors": "^1.1.1",
     "smol-toml": "^1.9.0",
     "tree-sitter": "^0.25.1",