okengine 0.1.4

package/src/console/ui/diff/a11y.test.tsx

@@ -0,0 +1,99 @@
+/**
+ * Accessibility gate — axe reports zero violations at WCAG 2.2 AA
+ * (console §7.5 · §9.12).
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import axe from "axe-core";
+import { Window } from "happy-dom";
+import { createRoot, type Root } from "react-dom/client";
+import { act } from "react";
+import { DiffA11yView } from "./DiffA11yView.tsx";
+
+describe("Manifest Diff panel accessibility", () => {
+  let window: Window;
+  let root: Root;
+  let container: HTMLElement;
+
+  beforeEach(() => {
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+      true;
+    window = new Window({ url: "http://console.test/manifest-diff" });
+    Object.defineProperty(globalThis, "window", {
+      value: window,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "document", {
+      value: window.document,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "HTMLElement", {
+      value: window.HTMLElement,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "Node", {
+      value: window.Node,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "navigator", {
+      value: window.navigator,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "getComputedStyle", {
+      value: window.getComputedStyle.bind(window),
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "requestAnimationFrame", {
+      value: (cb: FrameRequestCallback) => window.setTimeout(cb, 0),
+      configurable: true,
+      writable: true,
+    });
+
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+    window.close();
+  });
+
+  test("axe reports zero violations at WCAG 2.2 AA", async () => {
+    await act(async () => {
+      root.render(
+        <DiffA11yView path="/flows/orders.notify/effects/sends" />,
+      );
+    });
+
+    await new Promise((r) => setTimeout(r, 10));
+
+    const results = await axe.run(container, {
+      runOnly: {
+        type: "tag",
+        values: ["wcag2a", "wcag2aa", "wcag22aa"],
+      },
+    });
+
+    if (results.violations.length > 0) {
+      const summary = results.violations
+        .map(
+          (v) =>
+            `${v.id}: ${v.help} (${v.nodes.length} nodes) — ${v.nodes.map((n) => n.html).join("; ")}`,
+        )
+        .join("\n");
+      console.error(summary);
+    }
+
+    expect(results.violations).toEqual([]);
+  });
+});

package/src/console/ui/diff/fixture.ts

@@ -0,0 +1,85 @@
+/**
+ * Manifest Diff fixtures for unit tests and the axe gate (console §9.12).
+ */
+
+import type { DiffListResponse } from "./types.ts";
+
+/** Fixture with all four categories + CI gate distinction. */
+export const DIFF_LIST_FIXTURE: DiffListResponse = {
+  hasBaseline: true,
+  severity: "contract-breaking",
+  blockedCount: 1,
+  acknowledgedCount: 1,
+  changes: [
+    {
+      path: "/flows/reports.export/in",
+      category: "contract-breaking",
+      kind: "changed",
+      summary: "in schema contract broke",
+      flowName: "reports.export",
+      runCountLastWeek: 1200,
+      blastLine: null,
+      weeklyDeltaUsd: null,
+      weeklyBillLine: null,
+      ciGate: "blocked",
+    },
+    {
+      path: "/flows/legacy.import/trigger",
+      category: "contract-breaking",
+      kind: "changed",
+      summary: "trigger changed",
+      flowName: "legacy.import",
+      runCountLastWeek: 40,
+      blastLine: null,
+      weeklyDeltaUsd: null,
+      weeklyBillLine: null,
+      ciGate: "acknowledged",
+    },
+    {
+      path: "/flows/reports.export/gates",
+      category: "permission-widening",
+      kind: "changed",
+      summary: "gate removed: staff",
+      flowName: "reports.export",
+      runCountLastWeek: 1200,
+      blastLine: null,
+      weeklyDeltaUsd: null,
+      weeklyBillLine: null,
+      ciGate: null,
+    },
+    {
+      path: "/flows/orders.notify/effects/sends",
+      category: "effect-widening",
+      kind: "added",
+      summary: "sends added: order-shipped",
+      flowName: "orders.notify",
+      runCountLastWeek: 41_208,
+      blastLine:
+        "this flow ran 41,208 times last week, it sent nothing, and it will now email every caller",
+      weeklyDeltaUsd: 4.1208,
+      weeklyBillLine: "+$4 per week",
+      ciGate: null,
+    },
+    {
+      path: "/flows/health.ping/source",
+      category: "no-impact",
+      kind: "changed",
+      summary: "source changed",
+      flowName: "health.ping",
+      runCountLastWeek: 90_000,
+      blastLine: null,
+      weeklyDeltaUsd: null,
+      weeklyBillLine: null,
+      ciGate: null,
+    },
+  ],
+};
+
+/** Empty baseline fixture. */
+export const DIFF_EMPTY_BASELINE_FIXTURE: DiffListResponse = {
+  hasBaseline: false,
+  severity: null,
+  blockedCount: 0,
+  acknowledgedCount: 0,
+  changes: [],
+};

package/src/console/ui/diff/group.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Manifest Diff grouping / CI gate copy (console §9.12).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { DIFF_LIST_FIXTURE } from "./fixture.ts";
+import {
+  filterChanges,
+  formatCiGate,
+  groupByCategory,
+} from "./group.ts";
+
+describe("groupByCategory", () => {
+  test("keeps the four blast-radius sections in order", () => {
+    const groups = groupByCategory(DIFF_LIST_FIXTURE.changes);
+    expect(groups.map((g) => g.category)).toEqual([
+      "contract-breaking",
+      "permission-widening",
+      "effect-widening",
+      "no-impact",
+    ]);
+  });
+
+  test("does not invent categories — only renders projection output", () => {
+    const only = DIFF_LIST_FIXTURE.changes.filter(
+      (c) => c.category === "effect-widening",
+    );
+    const groups = groupByCategory(only);
+    expect(groups).toHaveLength(1);
+    expect(groups[0]!.category).toBe("effect-widening");
+    expect(groups[0]!.items[0]!.blastLine).toContain("41,208");
+  });
+});
+
+describe("filterChanges", () => {
+  test("filters by path and blast line without reclassifying", () => {
+    const hits = filterChanges(DIFF_LIST_FIXTURE.changes, "email");
+    expect(hits).toHaveLength(1);
+    expect(hits[0]!.category).toBe("effect-widening");
+  });
+
+  test("category facet narrows without changing category labels", () => {
+    const hits = filterChanges(
+      DIFF_LIST_FIXTURE.changes,
+      "",
+      "contract-breaking",
+    );
+    expect(hits.every((c) => c.category === "contract-breaking")).toBe(true);
+  });
+});
+
+describe("formatCiGate", () => {
+  test("undeclared break is blocked; breaking: true is allowed through", () => {
+    expect(formatCiGate("blocked")).toContain("blocked");
+    expect(formatCiGate("acknowledged")).toContain("breaking: true");
+    expect(formatCiGate(null)).toBeNull();
+  });
+});

package/src/console/ui/diff/group.ts

@@ -0,0 +1,97 @@
+/**
+ * Group / filter Manifest Diff rows — render-only, no reclassification.
+ */
+
+import type {
+  DiffCategory,
+  DiffCategoryGroup,
+  DiffChangeRecord,
+} from "./types.ts";
+
+/** Display order — blast radius descending. */
+export const DIFF_CATEGORY_ORDER: readonly DiffCategory[] = [
+  "contract-breaking",
+  "permission-widening",
+  "effect-widening",
+  "no-impact",
+] as const;
+
+/** Human labels for the four categories. */
+export const DIFF_CATEGORY_LABELS: Readonly<Record<DiffCategory, string>> = {
+  "contract-breaking": "Contract breaking",
+  "permission-widening": "Permission widening",
+  "effect-widening": "Effect widening",
+  "no-impact": "No impact",
+};
+
+/**
+ * Filter changes by free-text query and optional category facet.
+ *
+ * @param changes - Projection rows (already classified)
+ * @param q - Free-text filter
+ * @param category - Optional category facet
+ */
+export function filterChanges(
+  changes: readonly DiffChangeRecord[],
+  q: string,
+  category?: DiffCategory,
+): readonly DiffChangeRecord[] {
+  const needle = q.trim().toLowerCase();
+  return changes.filter((c) => {
+    if (category && c.category !== category) return false;
+    if (!needle) return true;
+    return (
+      c.path.toLowerCase().includes(needle) ||
+      c.summary.toLowerCase().includes(needle) ||
+      (c.blastLine?.toLowerCase().includes(needle) ?? false) ||
+      (c.flowName?.toLowerCase().includes(needle) ?? false) ||
+      (c.weeklyBillLine?.toLowerCase().includes(needle) ?? false)
+    );
+  });
+}
+
+/**
+ * Group filtered changes into the four blast-radius sections.
+ * Empty categories are omitted.
+ *
+ * @param changes - Filtered rows
+ */
+export function groupByCategory(
+  changes: readonly DiffChangeRecord[],
+): readonly DiffCategoryGroup[] {
+  const buckets = new Map<DiffCategory, DiffChangeRecord[]>();
+  for (const cat of DIFF_CATEGORY_ORDER) {
+    buckets.set(cat, []);
+  }
+  for (const c of changes) {
+    buckets.get(c.category)?.push(c);
+  }
+  return DIFF_CATEGORY_ORDER.flatMap((category) => {
+    const items = buckets.get(category) ?? [];
+    if (items.length === 0) return [];
+    return [
+      {
+        category,
+        label: DIFF_CATEGORY_LABELS[category],
+        items,
+      },
+    ];
+  });
+}
+
+/**
+ * CI gate label for a contract-breaking row.
+ *
+ * @param ciGate - Gate status from the projection
+ */
+export function formatCiGate(
+  ciGate: DiffChangeRecord["ciGate"],
+): string | null {
+  if (ciGate === "blocked") {
+    return "CI gate: blocked — undeclared break";
+  }
+  if (ciGate === "acknowledged") {
+    return "CI gate: allowed — breaking: true";
+  }
+  return null;
+}

package/src/console/ui/diff/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Manifest Diff panel pure modules (console §9.12).
+ */
+
+export type {
+  DiffCategory,
+  DiffCategoryGroup,
+  DiffChangeRecord,
+  DiffCiGate,
+  DiffKind,
+  DiffListResponse,
+} from "./types.ts";
+
+export {
+  DIFF_EMPTY_BASELINE_FIXTURE,
+  DIFF_LIST_FIXTURE,
+} from "./fixture.ts";
+
+export {
+  filterCategory,
+  openDiffPath,
+  parseDiffSearch,
+  serializeDiffSearch,
+  type DiffSearch,
+} from "./search.ts";
+
+export {
+  DIFF_CATEGORY_LABELS,
+  DIFF_CATEGORY_ORDER,
+  filterChanges,
+  formatCiGate,
+  groupByCategory,
+} from "./group.ts";
+
+export {
+  whatChangedSummary,
+  type DiffDeploySummary,
+} from "./summary.ts";

package/src/console/ui/diff/search.test.ts

@@ -0,0 +1,32 @@
+/**
+ * Manifest Diff URL search tests (console §9.12).
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  openDiffPath,
+  parseDiffSearch,
+  serializeDiffSearch,
+} from "./search.ts";
+
+describe("Diff search", () => {
+  test("round-trips path + category", () => {
+    const parsed = parseDiffSearch({
+      path: "/flows/orders.notify/effects/sends",
+      category: "effect-widening",
+      q: "email",
+    });
+    expect(parsed.path).toBe("/flows/orders.notify/effects/sends");
+    expect(parsed.category).toBe("effect-widening");
+    expect(serializeDiffSearch(parsed)).toEqual({
+      q: "email",
+      path: "/flows/orders.notify/effects/sends",
+      category: "effect-widening",
+    });
+  });
+
+  test("openDiffPath focuses a change", () => {
+    const next = openDiffPath({}, "/flows/reports.export/in");
+    expect(next.path).toBe("/flows/reports.export/in");
+  });
+});

package/src/console/ui/diff/search.ts

@@ -0,0 +1,75 @@
+/**
+ * URL search state for the Manifest Diff panel.
+ */
+
+import { z } from "zod";
+import type { DiffCategory } from "./types.ts";
+
+const DiffSearchSchema = z.object({
+  /** Free-text filter over path / summary / blast line. */
+  q: z.string().optional(),
+  /** Focus a Manifest path (AI deep-link). */
+  path: z.string().optional(),
+  /** Optional category facet. */
+  category: z
+    .enum([
+      "contract-breaking",
+      "permission-widening",
+      "effect-widening",
+      "no-impact",
+    ])
+    .optional(),
+});
+
+/** Parsed Manifest Diff URL search. */
+export type DiffSearch = z.infer<typeof DiffSearchSchema>;
+
+/**
+ * Parse Manifest Diff panel search params.
+ *
+ * @param search - Raw router search
+ */
+export function parseDiffSearch(
+  search: Record<string, unknown>,
+): DiffSearch {
+  const parsed = DiffSearchSchema.safeParse(search);
+  return parsed.success ? parsed.data : {};
+}
+
+/**
+ * Serialize Diff search for navigation (omit empties).
+ *
+ * @param search - Search state
+ */
+export function serializeDiffSearch(
+  search: DiffSearch,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (search.q) out.q = search.q;
+  if (search.path) out.path = search.path;
+  if (search.category) out.category = search.category;
+  return out;
+}
+
+/**
+ * Focus a change path in the URL.
+ *
+ * @param search - Current search
+ * @param path - Manifest change path
+ */
+export function openDiffPath(search: DiffSearch, path: string): DiffSearch {
+  return { ...search, path };
+}
+
+/**
+ * Facet to one blast-radius category.
+ *
+ * @param search - Current search
+ * @param category - Category or clear
+ */
+export function filterCategory(
+  search: DiffSearch,
+  category: DiffCategory | undefined,
+): DiffSearch {
+  return { ...search, category };
+}

package/src/console/ui/diff/summary.ts

@@ -0,0 +1,74 @@
+/**
+ * Deploy summary for Overview "what changed" (console §9.12 · §9.16).
+ *
+ * Reads the Manifest Diff projection — never recomputes `diffManifest`.
+ */
+
+import { DIFF_CATEGORY_LABELS } from "./group.ts";
+import type { DiffListResponse } from "./types.ts";
+
+/** Linked summary of the most recent deploy's Manifest Diff. */
+export interface DiffDeploySummary {
+  readonly hasBaseline: boolean;
+  readonly severity: DiffListResponse["severity"];
+  readonly changeCount: number;
+  readonly blockedCount: number;
+  readonly acknowledgedCount: number;
+  /** One-line plain-language summary. */
+  readonly line: string;
+  /** Deep-link into the Diff panel. */
+  readonly href: string;
+}
+
+/**
+ * Summarise the latest Manifest Diff projection for Overview.
+ *
+ * @param diff - `console.diff.list` response
+ */
+export function whatChangedSummary(diff: DiffListResponse): DiffDeploySummary {
+  const href = "/diff";
+  if (!diff.hasBaseline) {
+    return {
+      hasBaseline: false,
+      severity: null,
+      changeCount: 0,
+      blockedCount: 0,
+      acknowledgedCount: 0,
+      line: "No prior deploy baseline — Manifest Diff has nothing to compare yet",
+      href,
+    };
+  }
+
+  const changeCount = diff.changes.length;
+  if (changeCount === 0) {
+    return {
+      hasBaseline: true,
+      severity: null,
+      changeCount: 0,
+      blockedCount: 0,
+      acknowledgedCount: 0,
+      line: "Last deploy changed nothing in the Manifest",
+      href,
+    };
+  }
+
+  const severityLabel =
+    diff.severity != null ? DIFF_CATEGORY_LABELS[diff.severity] : "changes";
+  const top = diff.changes[0]!;
+  const gateNote =
+    diff.blockedCount > 0
+      ? ` · ${diff.blockedCount} blocked by CI`
+      : diff.acknowledgedCount > 0
+        ? ` · ${diff.acknowledgedCount} acknowledged break${diff.acknowledgedCount === 1 ? "" : "s"}`
+        : "";
+
+  return {
+    hasBaseline: true,
+    severity: diff.severity,
+    changeCount,
+    blockedCount: diff.blockedCount,
+    acknowledgedCount: diff.acknowledgedCount,
+    line: `${changeCount} Manifest change${changeCount === 1 ? "" : "s"} (${severityLabel}): ${top.summary}${gateNote}`,
+    href,
+  };
+}

package/src/console/ui/diff/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Manifest Diff panel view types (console §9.12).
+ */
+
+/** Four blast-radius categories — mirrored from `diffManifest`, never recomputed. */
+export type DiffCategory =
+  | "contract-breaking"
+  | "permission-widening"
+  | "effect-widening"
+  | "no-impact";
+
+/** How a path changed. */
+export type DiffKind = "added" | "removed" | "changed";
+
+/** CI gate status for contract-breaking changes. */
+export type DiffCiGate = "blocked" | "acknowledged";
+
+/** One enriched change row from `console.diff.list`. */
+export interface DiffChangeRecord {
+  readonly path: string;
+  readonly category: DiffCategory;
+  readonly kind: DiffKind;
+  readonly summary: string;
+  readonly before?: unknown;
+  readonly after?: unknown;
+  readonly flowName: string | null;
+  readonly runCountLastWeek: number;
+  readonly blastLine: string | null;
+  readonly weeklyDeltaUsd: number | null;
+  readonly weeklyBillLine: string | null;
+  readonly ciGate: DiffCiGate | null;
+}
+
+/** `console.diff.list` response. */
+export interface DiffListResponse {
+  readonly hasBaseline: boolean;
+  readonly severity: DiffCategory | null;
+  readonly blockedCount: number;
+  readonly acknowledgedCount: number;
+  readonly changes: readonly DiffChangeRecord[];
+}
+
+/** Grouped section for the four categories. */
+export interface DiffCategoryGroup {
+  readonly category: DiffCategory;
+  readonly label: string;
+  readonly items: readonly DiffChangeRecord[];
+}