diffpanel 0.0.1

package/src/schemas.ts

@@ -0,0 +1,167 @@
+import { z } from "zod";
+
+export const reviewScopeSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("worktree"), baseRef: z.string(), baseSha: z.string() }),
+  z.object({ type: z.literal("staged"), baseRef: z.string(), baseSha: z.string() }),
+  z.object({
+    type: z.literal("range"),
+    expression: z.string(),
+    baseRef: z.string(),
+    compareRef: z.string(),
+    baseSha: z.string(),
+    compareSha: z.string(),
+    mergeBase: z.boolean(),
+  }),
+  z.object({
+    type: z.literal("repository"),
+    ref: z.string(),
+    sha: z.string(),
+    maxFiles: z.number().int().positive(),
+  }),
+]);
+
+export const fileStatusSchema = z.enum([
+  "added",
+  "modified",
+  "deleted",
+  "renamed",
+  "copied",
+  "unmerged",
+  "snapshot",
+  "unknown",
+]);
+
+export const reviewItemSchema = z.object({
+  id: z.string().min(1),
+  kind: z.enum(["hunk", "file"]),
+  filePath: z.string().min(1),
+  oldPath: z.string().nullable().default(null),
+  status: fileStatusSchema,
+  ordinal: z.number().int().nonnegative(),
+  oldStart: z.number().int().nonnegative().nullable(),
+  oldLines: z.number().int().nonnegative().nullable(),
+  newStart: z.number().int().nonnegative().nullable(),
+  newLines: z.number().int().nonnegative().nullable(),
+  patch: z.string(),
+  contentHash: z.string().min(1),
+});
+
+export const reviewFileSchema = z.object({
+  id: z.string().min(1),
+  filePath: z.string().min(1),
+  oldPath: z.string().nullable().default(null),
+  status: fileStatusSchema,
+  beforeBlob: z.string().nullable(),
+  afterBlob: z.string().nullable(),
+  additions: z.number().int().nonnegative(),
+  deletions: z.number().int().nonnegative(),
+  language: z.string().nullable(),
+  size: z.number().int().nonnegative(),
+  items: z.array(reviewItemSchema),
+});
+
+export const skippedEntrySchema = z.object({
+  filePath: z.string(),
+  reason: z.string(),
+});
+
+export const reviewManifestSchema = z.object({
+  schemaVersion: z.literal(1),
+  runId: z.string().min(1),
+  repositoryId: z.string().min(1),
+  repositoryRoot: z.string().min(1),
+  repositoryName: z.string().min(1),
+  createdAt: z.string().datetime(),
+  snapshotHash: z.string().min(1),
+  scope: reviewScopeSchema,
+  files: z.array(reviewFileSchema),
+  skipped: z.array(skippedEntrySchema),
+  requirements: z.object({ diagramAssessment: z.literal(true) }).optional(),
+});
+
+export const lineReferenceSchema = z.object({
+  filePath: z.string().min(1),
+  side: z.enum(["before", "after"]),
+  startLine: z.number().int().positive(),
+  endLine: z.number().int().positive(),
+}).refine((value) => value.endLine >= value.startLine, {
+  message: "endLine must be greater than or equal to startLine",
+  path: ["endLine"],
+});
+
+export const keyChangeSchema = z.object({
+  content: z.string().min(1),
+  lineRefs: z.array(lineReferenceSchema).min(1),
+});
+
+export const chapterSchema = z.object({
+  id: z.string().min(1),
+  parentId: z.string().min(1).nullable().default(null),
+  order: z.number().int().positive(),
+  title: z.string().min(1).max(100),
+  summary: z.string().min(1),
+  diagram: z.string().max(20_000).nullable().optional(),
+  diagramItemRefs: z.array(z.string().min(1)).optional(),
+  itemRefs: z.array(z.string().min(1)).default([]),
+  keyChanges: z.array(keyChangeSchema).default([]),
+});
+
+export const focusAreaSchema = z.object({
+  type: z.enum([
+    "security",
+    "breaking-change",
+    "high-complexity",
+    "data-integrity",
+    "new-pattern",
+    "architecture",
+    "performance",
+    "testing-gap",
+  ]),
+  severity: z.enum(["critical", "high", "medium", "info"]),
+  title: z.string().min(1),
+  description: z.string().min(1),
+  locations: z.array(z.string().min(1)).min(1),
+});
+
+export const prologueSchema = z.object({
+  motivation: z.string().nullable(),
+  outcome: z.string().nullable(),
+  diagram: z.string().nullable(),
+  diagramItemRefs: z.array(z.string().min(1)).optional(),
+  keyChanges: z.array(z.object({
+    summary: z.string().min(1),
+    description: z.string().min(1),
+  })).min(1).max(8),
+  focusAreas: z.array(focusAreaSchema).min(1).max(8),
+  complexity: z.object({
+    level: z.enum(["low", "medium", "high", "very-high"]),
+    reasoning: z.string().min(1),
+  }),
+});
+
+export const REVIEW_TITLE_MAX_LENGTH = 80;
+
+export const reviewTitleSchema = z.string().trim().min(1).max(REVIEW_TITLE_MAX_LENGTH);
+
+export const generatedReviewSchema = z.object({
+  schemaVersion: z.literal(1),
+  runId: z.string().min(1),
+  generator: z.string().min(1).optional(),
+  title: reviewTitleSchema.optional(),
+  diagramAssessment: z.object({
+    kind: z.enum(["architectural", "other"]),
+    reasoning: z.string().trim().min(1),
+    overviewOmissionReason: z.string().trim().min(1).optional(),
+    chapterDiagramOmissionReason: z.string().trim().min(1).optional(),
+  }).optional(),
+  chapters: z.array(chapterSchema).min(1),
+  prologue: prologueSchema,
+});
+
+export type ReviewScope = z.infer<typeof reviewScopeSchema>;
+export type ReviewItem = z.infer<typeof reviewItemSchema>;
+export type ReviewFile = z.infer<typeof reviewFileSchema>;
+export type ReviewManifest = z.infer<typeof reviewManifestSchema>;
+export type Chapter = z.infer<typeof chapterSchema>;
+export type GeneratedReview = z.infer<typeof generatedReviewSchema>;
+export type Prologue = z.infer<typeof prologueSchema>;

package/src/title.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { displayReviewTitle, parseReviewTitle, titleForScope } from "./title.js";
+
+describe("review titles", () => {
+  it("trims and accepts a custom title", () => {
+    expect(parseReviewTitle("  PR 567 retired surfaces  ")).toBe("PR 567 retired surfaces");
+  });
+
+  it("rejects an empty or oversized title", () => {
+    expect(() => parseReviewTitle("   ")).toThrow(/1 to 80/);
+    expect(() => parseReviewTitle("x".repeat(81))).toThrow(/1 to 80/);
+  });
+
+  it("falls back to the git scope label", () => {
+    expect(titleForScope({ type: "worktree", baseRef: "HEAD", baseSha: "abc" })).toBe("Working tree");
+    expect(titleForScope({
+      type: "range",
+      expression: "41a8f8db..c33a9b59",
+      baseRef: "41a8f8db",
+      compareRef: "c33a9b59",
+      baseSha: "abc",
+      compareSha: "def",
+      mergeBase: false,
+    })).toBe("41a8f8db..c33a9b59");
+    expect(displayReviewTitle(null, { type: "staged", baseRef: "HEAD", baseSha: "abc" })).toBe("Staged changes");
+    expect(displayReviewTitle("Account runtime", { type: "staged", baseRef: "HEAD", baseSha: "abc" })).toBe("Account runtime");
+  });
+});

package/src/title.ts

@@ -0,0 +1,20 @@
+import { REVIEW_TITLE_MAX_LENGTH, reviewTitleSchema, type ReviewScope } from "./schemas.js";
+
+export function parseReviewTitle(value: string): string {
+  const result = reviewTitleSchema.safeParse(value);
+  if (!result.success) {
+    throw new Error(`Review title must be 1 to ${REVIEW_TITLE_MAX_LENGTH} characters.`);
+  }
+  return result.data;
+}
+
+export function titleForScope(scope: ReviewScope): string {
+  if (scope.type === "worktree") return "Working tree";
+  if (scope.type === "staged") return "Staged changes";
+  if (scope.type === "range") return scope.expression;
+  return `Repository at ${scope.ref}`;
+}
+
+export function displayReviewTitle(title: string | null | undefined, scope: ReviewScope): string {
+  return title?.trim() || titleForScope(scope);
+}

package/src/validation.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import { validateGeneratedReview } from "./validation.js";
+
+const manifest = {
+  schemaVersion: 1 as const,
+  runId: "run-1",
+  repositoryId: "repo-1",
+  repositoryRoot: "/tmp/repo",
+  repositoryName: "repo",
+  createdAt: "2026-08-08T00:00:00.000Z",
+  snapshotHash: "snapshot",
+  scope: { type: "worktree" as const, baseRef: "HEAD", baseSha: "abc" },
+  files: [{
+    id: "file-1",
+    filePath: "src/a.ts",
+    oldPath: null,
+    status: "modified" as const,
+    beforeBlob: "before",
+    afterBlob: "after",
+    additions: 1,
+    deletions: 1,
+    language: "typescript",
+    size: 20,
+    items: [
+      { id: "item-1", kind: "hunk" as const, filePath: "src/a.ts", oldPath: null, status: "modified" as const, ordinal: 0, oldStart: 1, oldLines: 1, newStart: 1, newLines: 1, patch: "patch", contentHash: "h1" },
+      { id: "item-2", kind: "hunk" as const, filePath: "src/a.ts", oldPath: null, status: "modified" as const, ordinal: 1, oldStart: 5, oldLines: 1, newStart: 5, newLines: 1, patch: "patch", contentHash: "h2" },
+    ],
+  }],
+  skipped: [],
+};
+
+const review = {
+  schemaVersion: 1 as const,
+  runId: "run-1",
+  chapters: [{ id: "chapter-1", order: 1, title: "Explain the change", summary: "The behavior changes coherently.", itemRefs: ["item-1", "item-2"], keyChanges: [] }],
+  prologue: {
+    motivation: null,
+    outcome: null,
+    diagram: null,
+    keyChanges: [{ summary: "Behavior follows the new path", description: "Both related hunks now share one review chapter." }],
+    focusAreas: [{ type: "architecture" as const, severity: "info" as const, title: "Shared control path", description: "The related behavior moved together; confirm the boundary remains appropriate.", locations: ["src/a.ts"] }],
+    complexity: { level: "low" as const, reasoning: "One file with two related hunks." },
+  },
+};
+
+describe("validateGeneratedReview", () => {
+  it("accepts exact item coverage", () => {
+    expect(validateGeneratedReview(manifest, review)).toMatchObject({ valid: true });
+  });
+
+  it("accepts an optional review title", () => {
+    expect(validateGeneratedReview(manifest, { ...review, title: "PR 568 DataFn foundations" })).toMatchObject({ valid: true });
+  });
+
+  it("reports missing and duplicate items", () => {
+    const invalid = structuredClone(review);
+    invalid.chapters[0]!.itemRefs = ["item-1", "item-1"];
+    const result = validateGeneratedReview(manifest, invalid);
+    expect(result.valid).toBe(false);
+    expect(result.missingItemRefs).toEqual(["item-2"]);
+    expect(result.duplicateItemRefs).toEqual(["item-1"]);
+  });
+});
+
+
+describe("diagram evidence", () => {
+  it("accepts supporting refs without counting them as duplicate ownership", () => {
+    const input = { ...review, chapters: [{ ...review.chapters[0], diagram: "flowchart LR\nA-->B", diagramItemRefs: ["item-1"] }] };
+    expect(validateGeneratedReview(manifest, input).valid).toBe(true);
+  });
+  it("requires evidence for new chapter diagrams", () => {
+    expect(validateGeneratedReview(manifest, { ...review, chapters: [{ ...review.chapters[0], diagram: "flowchart LR\nA-->B" }] }).errors).toContain("chapter chapter-1 diagram requires evidence item refs");
+  });
+  it("rejects unknown and duplicate prologue evidence", () => {
+    const input = { ...review, prologue: { ...review.prologue, diagramItemRefs: ["missing", "item-1", "item-1"] } };
+    expect(validateGeneratedReview(manifest, input).errors).toEqual(expect.arrayContaining(["prologue diagram references out-of-scope item missing", "prologue diagram repeats item item-1"]));
+  });
+  it("allows descendant evidence but rejects sibling evidence", () => {
+    const input = { ...review, chapters: [
+      { ...review.chapters[0], id: "parent", itemRefs: [], diagram: "flowchart LR\nA-->B", diagramItemRefs: ["item-1"] },
+      { ...review.chapters[0], id: "child", parentId: "parent", order: 2, itemRefs: ["item-1"] },
+      { ...review.chapters[0], id: "sibling", order: 3, itemRefs: ["item-2"] },
+    ] };
+    expect(validateGeneratedReview(manifest, input).valid).toBe(true);
+    const invalid = { ...input, chapters: input.chapters.map((chapter, index) => index === 0 ? { ...chapter, diagramItemRefs: ["item-2"] } : chapter) };
+    expect(validateGeneratedReview(manifest, invalid).errors).toContain("chapter parent diagram references out-of-scope item item-2");
+  });
+});
+
+describe("required visual assessment for new snapshots", () => {
+  const currentManifest = { ...manifest, requirements: { diagramAssessment: true as const } };
+  const assessment = { kind: "architectural" as const, reasoning: "Ownership and host initialization move across packages." };
+
+  it("keeps historical reviews valid but rejects an absent decision for new captures", () => {
+    expect(validateGeneratedReview(manifest, review).valid).toBe(true);
+    expect(validateGeneratedReview(currentManifest, review).errors).toContain("review requires diagramAssessment for this snapshot");
+  });
+  it("requires an overview and focused diagrams, or explicit omission reasons", () => {
+    const result = validateGeneratedReview(currentManifest, { ...review, diagramAssessment: assessment });
+    expect(result.errors).toContain("provide an overview diagram or overviewOmissionReason");
+    expect(result.errors).toContain("architectural reviews require focused chapter diagrams or chapterDiagramOmissionReason");
+    expect(validateGeneratedReview(currentManifest, { ...review, diagramAssessment: { ...assessment,
+      overviewOmissionReason: "The captured subset does not contain enough dependency evidence for a truthful overview.",
+      chapterDiagramOmissionReason: "These chapters contain declarations only; no flow is established by this snapshot.",
+    } }).valid).toBe(true);
+  });
+  it("requires evidence for new overview diagrams, and rejects contradictory omissions", () => {
+    const input = { ...review, diagramAssessment: { kind: "other", reasoning: "Show a simple transition." },
+      prologue: { ...review.prologue, diagram: "flowchart LR\nA-->B" } };
+    expect(validateGeneratedReview(currentManifest, input).errors).toContain("prologue diagram requires evidence item refs");
+    expect(validateGeneratedReview(currentManifest, { ...input, prologue: { ...input.prologue, diagramItemRefs: ["item-1"] } }).valid).toBe(true);
+    expect(validateGeneratedReview(currentManifest, { ...input, diagramAssessment: { ...input.diagramAssessment, overviewOmissionReason: "omitted" } }).errors).toContain("overview diagram and overviewOmissionReason are mutually exclusive");
+  });
+  it("accepts an evidenced overview and chapter diagram without duplicate ownership", () => {
+    const input = { ...review, diagramAssessment: assessment,
+      prologue: { ...review.prologue, diagram: "flowchart LR\nA-->B", diagramItemRefs: ["item-1"] },
+      chapters: [{ ...review.chapters[0], diagram: "flowchart LR\nB-->C", diagramItemRefs: ["item-2"] }],
+    };
+    expect(validateGeneratedReview(currentManifest, input)).toMatchObject({ valid: true, duplicateItemRefs: [] });
+  });
+});

package/src/validation.ts

@@ -0,0 +1,164 @@
+import type { GeneratedReview, ReviewManifest } from "./schemas.js";
+import { generatedReviewSchema, reviewManifestSchema } from "./schemas.js";
+
+export interface ReviewValidationResult {
+  valid: boolean;
+  errors: string[];
+  missingItemRefs: string[];
+  duplicateItemRefs: string[];
+  extraItemRefs: string[];
+}
+
+export function validateGeneratedReview(
+  manifestInput: unknown,
+  reviewInput: unknown,
+): ReviewValidationResult {
+  const manifestResult = reviewManifestSchema.safeParse(manifestInput);
+  const reviewResult = generatedReviewSchema.safeParse(reviewInput);
+  const errors: string[] = [];
+
+  if (!manifestResult.success) {
+    errors.push(...manifestResult.error.issues.map((issue) =>
+      `manifest.${issue.path.join(".")}: ${issue.message}`,
+    ));
+  }
+  if (!reviewResult.success) {
+    errors.push(...reviewResult.error.issues.map((issue) =>
+      `review.${issue.path.join(".")}: ${issue.message}`,
+    ));
+  }
+
+  if (!manifestResult.success || !reviewResult.success) {
+    return {
+      valid: false,
+      errors,
+      missingItemRefs: [],
+      duplicateItemRefs: [],
+      extraItemRefs: [],
+    };
+  }
+
+  const manifest = manifestResult.data;
+  const review = reviewResult.data;
+  const visualAssessment = review.diagramAssessment;
+  const enforceVisuals = !!manifest.requirements?.diagramAssessment || !!visualAssessment;
+  const hasOverview = !!review.prologue.diagram?.trim();
+  const hasChapterDiagrams = review.chapters.some((chapter) => !!chapter.diagram?.trim());
+  if (enforceVisuals) {
+    if (!visualAssessment) errors.push("review requires diagramAssessment for this snapshot");
+    else {
+      if (!hasOverview && !visualAssessment.overviewOmissionReason) errors.push("provide an overview diagram or overviewOmissionReason");
+      if (hasOverview && visualAssessment.overviewOmissionReason) errors.push("overview diagram and overviewOmissionReason are mutually exclusive");
+      if (visualAssessment.kind === "architectural" && !hasChapterDiagrams && !visualAssessment.chapterDiagramOmissionReason) {
+        errors.push("architectural reviews require focused chapter diagrams or chapterDiagramOmissionReason");
+      }
+      if (hasChapterDiagrams && visualAssessment.chapterDiagramOmissionReason) errors.push("chapter diagrams and chapterDiagramOmissionReason are mutually exclusive");
+    }
+    if (hasOverview && !review.prologue.diagramItemRefs?.length) errors.push("prologue diagram requires evidence item refs");
+  }
+  if (manifest.runId !== review.runId) {
+    errors.push(`review.runId ${review.runId} does not match manifest runId ${manifest.runId}`);
+  }
+
+  const chapterIds = new Set<string>();
+  const chapterOrders = new Set<number>();
+  for (const chapter of review.chapters) {
+    if (chapterIds.has(chapter.id)) errors.push(`duplicate chapter id: ${chapter.id}`);
+    if (chapterOrders.has(chapter.order)) errors.push(`duplicate chapter order: ${chapter.order}`);
+    chapterIds.add(chapter.id);
+    chapterOrders.add(chapter.order);
+  }
+  for (const chapter of review.chapters) {
+    if (chapter.parentId === chapter.id) errors.push(`chapter ${chapter.id} cannot be its own parent`);
+    if (chapter.parentId && !chapterIds.has(chapter.parentId)) {
+      errors.push(`chapter ${chapter.id} has unknown parent ${chapter.parentId}`);
+    }
+    const ancestry = new Set([chapter.id]);
+    let parentId = chapter.parentId;
+    while (parentId) {
+      if (ancestry.has(parentId)) {
+        errors.push(`chapter hierarchy contains a cycle at ${parentId}`);
+        break;
+      }
+      ancestry.add(parentId);
+      parentId = review.chapters.find((candidate) => candidate.id === parentId)?.parentId ?? null;
+    }
+    const hasChildren = review.chapters.some((candidate) => candidate.parentId === chapter.id);
+    if (chapter.itemRefs.length === 0 && !hasChildren) {
+      errors.push(`chapter ${chapter.id} has no review items or child chapters`);
+    }
+  }
+
+  const expected = new Set(manifest.files.flatMap((file) => file.items.map((item) => item.id)));
+  const checkDiagramRefs = (label: string, refs: string[] | undefined, allowed: Set<string>): void => {
+    const seen = new Set<string>();
+    for (const ref of refs ?? []) {
+      if (!allowed.has(ref)) errors.push(`${label} diagram references out-of-scope item ${ref}`);
+      if (seen.has(ref)) errors.push(`${label} diagram repeats item ${ref}`);
+      seen.add(ref);
+    }
+  };
+  checkDiagramRefs("prologue", review.prologue.diagramItemRefs, expected);
+  for (const chapter of review.chapters) {
+    const allowed = new Set<string>();
+    const visited = new Set<string>();
+    const collect = (id: string): void => {
+      if (visited.has(id)) return;
+      visited.add(id);
+      for (const candidate of review.chapters) {
+        if (candidate.id === id) for (const ref of candidate.itemRefs) if (expected.has(ref)) allowed.add(ref);
+        if (candidate.parentId === id) collect(candidate.id);
+      }
+    };
+    collect(chapter.id);
+    checkDiagramRefs(`chapter ${chapter.id}`, chapter.diagramItemRefs, allowed);
+    if (chapter.diagram && !chapter.diagramItemRefs?.length) {
+      errors.push(`chapter ${chapter.id} diagram requires evidence item refs`);
+    }
+  }
+  const observed = new Map<string, number>();
+  for (const itemRef of review.chapters.flatMap((chapter) => chapter.itemRefs)) {
+    observed.set(itemRef, (observed.get(itemRef) ?? 0) + 1);
+  }
+
+  const missingItemRefs = [...expected].filter((id) => !observed.has(id)).sort();
+  const duplicateItemRefs = [...observed.entries()]
+    .filter(([, count]) => count > 1)
+    .map(([id]) => id)
+    .sort();
+  const extraItemRefs = [...observed.keys()].filter((id) => !expected.has(id)).sort();
+
+  if (missingItemRefs.length > 0) errors.push(`missing item refs: ${missingItemRefs.join(", ")}`);
+  if (duplicateItemRefs.length > 0) errors.push(`duplicate item refs: ${duplicateItemRefs.join(", ")}`);
+  if (extraItemRefs.length > 0) errors.push(`unknown item refs: ${extraItemRefs.join(", ")}`);
+
+  const files = new Set(manifest.files.map((file) => file.filePath));
+  for (const chapter of review.chapters) {
+    for (const change of chapter.keyChanges) {
+      for (const ref of change.lineRefs) {
+        if (!files.has(ref.filePath)) {
+          errors.push(`chapter ${chapter.id} references unknown file ${ref.filePath}`);
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    missingItemRefs,
+    duplicateItemRefs,
+    extraItemRefs,
+  };
+}
+
+export function assertGeneratedReview(
+  manifest: ReviewManifest,
+  reviewInput: unknown,
+): GeneratedReview {
+  const result = validateGeneratedReview(manifest, reviewInput);
+  if (!result.valid) {
+    throw new Error(`Generated review validation failed:\n${result.errors.join("\n")}`);
+  }
+  return generatedReviewSchema.parse(reviewInput);
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
+}
+