ag-ui-validate 0.1.0

package/src/protocol/event-table.ts

@@ -0,0 +1,316 @@
+// AUTO-GENERATED from @ag-ui/core v0.0.58 — do not edit by hand.
+// Regenerate with: node scripts/generate-event-table.mjs
+// test/protocol-drift.test.ts fails if this file drifts from the installed SDK.
+
+export type FieldKind = "string" | "number" | "boolean" | "object" | "array" | "any"
+
+export type EventCategory =
+  | "lifecycle"
+  | "text"
+  | "toolcall"
+  | "state"
+  | "activity"
+  | "reasoning"
+  | "thinking"
+  | "special"
+
+export interface FieldSpec {
+  kind: FieldKind
+  required: boolean
+  enum?: readonly string[]
+}
+
+export interface EventSpec {
+  category: EventCategory
+  /** Present when the SDK marks the event @deprecated; names the replacement. */
+  deprecated?: string
+  /** Docs section governing this event. */
+  specUrl: string
+  /** Wire fields beyond the base-event fields (type, timestamp, rawEvent). */
+  fields: Readonly<Record<string, FieldSpec>>
+}
+
+/** Version of @ag-ui/core this table was derived from. */
+export const SDK_VERSION = "0.0.58"
+
+/** Canonical wire event types and their schemas, derived from @ag-ui/core. */
+export const EVENT_TABLE: Readonly<Record<string, EventSpec>> = {
+  "TEXT_MESSAGE_START": {
+    category: "text",
+    specUrl: "https://docs.ag-ui.com/concepts/events#textmessagestart",
+    fields: {
+      "messageId": { kind: "string", required: true },
+      "role": { kind: "string", required: false, enum: ["developer","system","assistant","user"] },
+      "name": { kind: "string", required: false },
+    },
+  },
+  "TEXT_MESSAGE_CONTENT": {
+    category: "text",
+    specUrl: "https://docs.ag-ui.com/concepts/events#textmessagecontent",
+    fields: {
+      "messageId": { kind: "string", required: true },
+      "delta": { kind: "string", required: true },
+    },
+  },
+  "TEXT_MESSAGE_END": {
+    category: "text",
+    specUrl: "https://docs.ag-ui.com/concepts/events#textmessageend",
+    fields: {
+      "messageId": { kind: "string", required: true },
+    },
+  },
+  "TEXT_MESSAGE_CHUNK": {
+    category: "text",
+    specUrl: "https://docs.ag-ui.com/concepts/events#textmessagechunk",
+    fields: {
+      "messageId": { kind: "string", required: false },
+      "role": { kind: "string", required: false, enum: ["developer","system","assistant","user"] },
+      "delta": { kind: "string", required: false },
+      "name": { kind: "string", required: false },
+    },
+  },
+  "TOOL_CALL_START": {
+    category: "toolcall",
+    specUrl: "https://docs.ag-ui.com/concepts/events#toolcallstart",
+    fields: {
+      "toolCallId": { kind: "string", required: true },
+      "toolCallName": { kind: "string", required: true },
+      "parentMessageId": { kind: "string", required: false },
+    },
+  },
+  "TOOL_CALL_ARGS": {
+    category: "toolcall",
+    specUrl: "https://docs.ag-ui.com/concepts/events#toolcallargs",
+    fields: {
+      "toolCallId": { kind: "string", required: true },
+      "delta": { kind: "string", required: true },
+    },
+  },
+  "TOOL_CALL_END": {
+    category: "toolcall",
+    specUrl: "https://docs.ag-ui.com/concepts/events#toolcallend",
+    fields: {
+      "toolCallId": { kind: "string", required: true },
+    },
+  },
+  "TOOL_CALL_CHUNK": {
+    category: "toolcall",
+    specUrl: "https://docs.ag-ui.com/concepts/events#toolcallchunk",
+    fields: {
+      "toolCallId": { kind: "string", required: false },
+      "toolCallName": { kind: "string", required: false },
+      "parentMessageId": { kind: "string", required: false },
+      "delta": { kind: "string", required: false },
+    },
+  },
+  "TOOL_CALL_RESULT": {
+    category: "toolcall",
+    specUrl: "https://docs.ag-ui.com/concepts/events#toolcallresult",
+    fields: {
+      "messageId": { kind: "string", required: true },
+      "toolCallId": { kind: "string", required: true },
+      "content": { kind: "string", required: true },
+      "role": { kind: "string", required: false, enum: ["tool"] },
+    },
+  },
+  "THINKING_START": {
+    category: "thinking",
+    deprecated: "REASONING_START",
+    specUrl: "https://docs.ag-ui.com/concepts/events#thinking-events-deprecated",
+    fields: {
+      "title": { kind: "string", required: false },
+    },
+  },
+  "THINKING_END": {
+    category: "thinking",
+    deprecated: "REASONING_END",
+    specUrl: "https://docs.ag-ui.com/concepts/events#thinking-events-deprecated",
+    fields: {
+    },
+  },
+  "THINKING_TEXT_MESSAGE_START": {
+    category: "thinking",
+    deprecated: "REASONING_MESSAGE_START",
+    specUrl: "https://docs.ag-ui.com/concepts/events#thinking-events-deprecated",
+    fields: {
+    },
+  },
+  "THINKING_TEXT_MESSAGE_CONTENT": {
+    category: "thinking",
+    deprecated: "REASONING_MESSAGE_CONTENT",
+    specUrl: "https://docs.ag-ui.com/concepts/events#thinking-events-deprecated",
+    fields: {
+      "delta": { kind: "string", required: true },
+    },
+  },
+  "THINKING_TEXT_MESSAGE_END": {
+    category: "thinking",
+    deprecated: "REASONING_MESSAGE_END",
+    specUrl: "https://docs.ag-ui.com/concepts/events#thinking-events-deprecated",
+    fields: {
+    },
+  },
+  "STATE_SNAPSHOT": {
+    category: "state",
+    specUrl: "https://docs.ag-ui.com/concepts/events#statesnapshot",
+    fields: {
+      "snapshot": { kind: "any", required: true },
+    },
+  },
+  "STATE_DELTA": {
+    category: "state",
+    specUrl: "https://docs.ag-ui.com/concepts/events#statedelta",
+    fields: {
+      "delta": { kind: "array", required: true },
+    },
+  },
+  "MESSAGES_SNAPSHOT": {
+    category: "state",
+    specUrl: "https://docs.ag-ui.com/concepts/events#messagessnapshot",
+    fields: {
+      "messages": { kind: "array", required: true },
+    },
+  },
+  "ACTIVITY_SNAPSHOT": {
+    category: "activity",
+    specUrl: "https://docs.ag-ui.com/concepts/events#activitysnapshot",
+    fields: {
+      "messageId": { kind: "string", required: true },
+      "activityType": { kind: "string", required: true },
+      "content": { kind: "object", required: true },
+      "replace": { kind: "boolean", required: false },
+    },
+  },
+  "ACTIVITY_DELTA": {
+    category: "activity",
+    specUrl: "https://docs.ag-ui.com/concepts/events#activitydelta",
+    fields: {
+      "messageId": { kind: "string", required: true },
+      "activityType": { kind: "string", required: true },
+      "patch": { kind: "array", required: true },
+    },
+  },
+  "RAW": {
+    category: "special",
+    specUrl: "https://docs.ag-ui.com/concepts/events#raw",
+    fields: {
+      "event": { kind: "any", required: true },
+      "source": { kind: "string", required: false },
+    },
+  },
+  "CUSTOM": {
+    category: "special",
+    specUrl: "https://docs.ag-ui.com/concepts/events#custom",
+    fields: {
+      "name": { kind: "string", required: true },
+      "value": { kind: "any", required: true },
+    },
+  },
+  "RUN_STARTED": {
+    category: "lifecycle",
+    specUrl: "https://docs.ag-ui.com/concepts/events#runstarted",
+    fields: {
+      "threadId": { kind: "string", required: true },
+      "runId": { kind: "string", required: true },
+      "parentRunId": { kind: "string", required: false },
+      "input": { kind: "object", required: false },
+    },
+  },
+  "RUN_FINISHED": {
+    category: "lifecycle",
+    specUrl: "https://docs.ag-ui.com/concepts/events#runfinished",
+    fields: {
+      "threadId": { kind: "string", required: true },
+      "runId": { kind: "string", required: true },
+      "result": { kind: "any", required: false },
+      "outcome": { kind: "object", required: false },
+      "usage": { kind: "array", required: false },
+    },
+  },
+  "RUN_ERROR": {
+    category: "lifecycle",
+    specUrl: "https://docs.ag-ui.com/concepts/events#runerror",
+    fields: {
+      "message": { kind: "string", required: true },
+      "code": { kind: "string", required: false },
+      "usage": { kind: "array", required: false },
+    },
+  },
+  "STEP_STARTED": {
+    category: "lifecycle",
+    specUrl: "https://docs.ag-ui.com/concepts/events#stepstarted",
+    fields: {
+      "stepName": { kind: "string", required: true },
+    },
+  },
+  "STEP_FINISHED": {
+    category: "lifecycle",
+    specUrl: "https://docs.ag-ui.com/concepts/events#stepfinished",
+    fields: {
+      "stepName": { kind: "string", required: true },
+    },
+  },
+  "REASONING_START": {
+    category: "reasoning",
+    specUrl: "https://docs.ag-ui.com/concepts/events#reasoningstart",
+    fields: {
+      "messageId": { kind: "string", required: true },
+    },
+  },
+  "REASONING_MESSAGE_START": {
+    category: "reasoning",
+    specUrl: "https://docs.ag-ui.com/concepts/events#reasoningmessagestart",
+    fields: {
+      "messageId": { kind: "string", required: true },
+      "role": { kind: "string", required: true, enum: ["reasoning"] },
+    },
+  },
+  "REASONING_MESSAGE_CONTENT": {
+    category: "reasoning",
+    specUrl: "https://docs.ag-ui.com/concepts/events#reasoningmessagecontent",
+    fields: {
+      "messageId": { kind: "string", required: true },
+      "delta": { kind: "string", required: true },
+    },
+  },
+  "REASONING_MESSAGE_END": {
+    category: "reasoning",
+    specUrl: "https://docs.ag-ui.com/concepts/events#reasoningmessageend",
+    fields: {
+      "messageId": { kind: "string", required: true },
+    },
+  },
+  "REASONING_MESSAGE_CHUNK": {
+    category: "reasoning",
+    specUrl: "https://docs.ag-ui.com/concepts/events#reasoningmessagechunk",
+    fields: {
+      "messageId": { kind: "string", required: false },
+      "delta": { kind: "string", required: false },
+    },
+  },
+  "REASONING_END": {
+    category: "reasoning",
+    specUrl: "https://docs.ag-ui.com/concepts/events#reasoningend",
+    fields: {
+      "messageId": { kind: "string", required: true },
+    },
+  },
+  "REASONING_ENCRYPTED_VALUE": {
+    category: "reasoning",
+    specUrl: "https://docs.ag-ui.com/concepts/events#reasoningencryptedvalue",
+    fields: {
+      "subtype": { kind: "string", required: true, enum: ["tool-call","message"] },
+      "entityId": { kind: "string", required: true },
+      "encryptedValue": { kind: "string", required: true },
+    },
+  },
+}
+
+/** All canonical wire `type` values, in @ag-ui/core enum order. */
+export const EVENT_TYPES: readonly string[] = Object.keys(EVENT_TABLE)
+
+/**
+ * Wire types documented as drafts (https://docs.ag-ui.com/drafts/overview) but
+ * not yet in @ag-ui/core. Not errors: reported at info severity.
+ */
+export const DRAFT_EVENT_TYPES: readonly string[] = ["META"]

package/src/protocol/jsonpatch.ts

@@ -0,0 +1,220 @@
+// Minimal RFC 6902 (JSON Patch) + RFC 6901 (JSON Pointer) implementation.
+// Hand-rolled so the core keeps zero runtime dependencies. Immutable: the
+// input document is never mutated; ops apply atomically (all or none).
+
+export type PatchResult =
+  | { ok: true; result: unknown }
+  | { ok: false; error: string; opIndex: number }
+
+export interface PatchShapeProblem {
+  /** Human-readable problem. */
+  error: string
+  /** Index of the offending op, or -1 when the document itself is not an array. */
+  opIndex: number
+  /** RFC 6901 pointer into the patch document, e.g. "/0/op". */
+  pointer: string
+}
+
+const OPS = ["add", "remove", "replace", "move", "copy", "test"] as const
+type OpName = (typeof OPS)[number]
+
+/** RFC 6901: "" → whole document; "/a/b" → ["a", "b"]. Returns null when invalid. */
+export function parsePointer(pointer: unknown): string[] | null {
+  if (typeof pointer !== "string") return null
+  if (pointer === "") return []
+  if (!pointer.startsWith("/")) return null
+  return pointer
+    .slice(1)
+    .split("/")
+    .map((t) => t.replace(/~1/g, "/").replace(/~0/g, "~"))
+}
+
+/** Structural validation of a patch document, without applying it. */
+export function validatePatchShape(patch: unknown): PatchShapeProblem | null {
+  if (!Array.isArray(patch)) {
+    return { error: "patch document must be an array of operations", opIndex: -1, pointer: "" }
+  }
+  for (let i = 0; i < patch.length; i++) {
+    const op = patch[i]
+    if (typeof op !== "object" || op === null || Array.isArray(op)) {
+      return { error: `operation ${i} is not an object`, opIndex: i, pointer: `/${i}` }
+    }
+    const o = op as Record<string, unknown>
+    if (!OPS.includes(o.op as OpName)) {
+      return { error: `operation ${i} has invalid op '${String(o.op)}'`, opIndex: i, pointer: `/${i}/op` }
+    }
+    if (parsePointer(o.path) === null) {
+      return { error: `operation ${i} (${String(o.op)}) has invalid path`, opIndex: i, pointer: `/${i}/path` }
+    }
+    if ((o.op === "add" || o.op === "replace" || o.op === "test") && !("value" in o)) {
+      return { error: `operation ${i} (${String(o.op)}) is missing value`, opIndex: i, pointer: `/${i}` }
+    }
+    if ((o.op === "move" || o.op === "copy") && parsePointer(o.from) === null) {
+      return { error: `operation ${i} (${String(o.op)}) is missing or has invalid from`, opIndex: i, pointer: `/${i}` }
+    }
+  }
+  return null
+}
+
+function clone(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(clone)
+  if (typeof value === "object" && value !== null) {
+    const out: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(value)) out[k] = clone(v)
+    return out
+  }
+  return value
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => deepEqual(v, b[i]))
+  }
+  if (typeof a === "object" && a !== null && typeof b === "object" && b !== null && !Array.isArray(a) && !Array.isArray(b)) {
+    const ka = Object.keys(a)
+    const kb = Object.keys(b as object)
+    return ka.length === kb.length && ka.every((k) => deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]))
+  }
+  return false
+}
+
+function arrayIndex(token: string, length: number, allowAppend: boolean): number | null {
+  if (allowAppend && token === "-") return length
+  if (!/^(0|[1-9]\d*)$/.test(token)) return null
+  const i = Number(token)
+  return i > length ? null : i
+}
+
+interface Located {
+  parent: Record<string, unknown> | unknown[] | null // null → the document root itself
+  key: string | number
+  exists: boolean
+  value: unknown
+}
+
+function locate(doc: unknown, tokens: string[], forAdd: boolean): Located | string {
+  if (tokens.length === 0) return { parent: null, key: "", exists: true, value: doc }
+  let current = doc
+  for (let i = 0; i < tokens.length - 1; i++) {
+    const token = tokens[i]!
+    if (Array.isArray(current)) {
+      const idx = arrayIndex(token, current.length, false)
+      if (idx === null || idx >= current.length) return `path segment '/${token}' does not exist`
+      current = current[idx]
+    } else if (typeof current === "object" && current !== null) {
+      const obj = current as Record<string, unknown>
+      if (!(token in obj)) return `path segment '/${token}' does not exist`
+      current = obj[token]
+    } else {
+      return `path segment '/${token}' is not an object or array`
+    }
+  }
+  const last = tokens[tokens.length - 1]!
+  if (Array.isArray(current)) {
+    const idx = arrayIndex(last, current.length, forAdd)
+    if (idx === null) return `'${last}' is not a valid index for an array of length ${current.length}`
+    return { parent: current, key: idx, exists: idx < current.length, value: current[idx] }
+  }
+  if (typeof current === "object" && current !== null) {
+    const obj = current as Record<string, unknown>
+    return { parent: obj, key: last, exists: last in obj, value: obj[last] }
+  }
+  return `target of '/${last}' is not an object or array`
+}
+
+/** Applies an RFC 6902 patch. Validates shape first; never throws. */
+export function applyPatch(doc: unknown, patch: unknown): PatchResult {
+  const shape = validatePatchShape(patch)
+  if (shape !== null) return { ok: false, error: shape.error, opIndex: shape.opIndex }
+
+  let result = clone(doc)
+  const ops = patch as Record<string, unknown>[]
+
+  const getAt = (pointer: string): { ok: true; value: unknown } | { ok: false; error: string } => {
+    const loc = locate(result, parsePointer(pointer)!, false)
+    if (typeof loc === "string") return { ok: false, error: `${pointer}: ${loc}` }
+    if (!loc.exists) return { ok: false, error: `${pointer} does not exist` }
+    return { ok: true, value: loc.value }
+  }
+
+  const setAt = (pointer: string, value: unknown, mustExist: boolean): string | null => {
+    const tokens = parsePointer(pointer)!
+    if (tokens.length === 0) {
+      result = value
+      return null
+    }
+    const loc = locate(result, tokens, !mustExist)
+    if (typeof loc === "string") return `${pointer}: ${loc}`
+    if (mustExist && !loc.exists) return `${pointer} does not exist`
+    if (Array.isArray(loc.parent)) {
+      if (mustExist) loc.parent[loc.key as number] = value
+      else loc.parent.splice(loc.key as number, 0, value)
+    } else {
+      loc.parent![loc.key as string] = value
+    }
+    return null
+  }
+
+  const removeAt = (pointer: string): { ok: true; removed: unknown } | { ok: false; error: string } => {
+    const tokens = parsePointer(pointer)!
+    if (tokens.length === 0) return { ok: false, error: "cannot remove the whole document" }
+    const loc = locate(result, tokens, false)
+    if (typeof loc === "string") return { ok: false, error: `${pointer}: ${loc}` }
+    if (!loc.exists) return { ok: false, error: `${pointer} does not exist` }
+    if (Array.isArray(loc.parent)) loc.parent.splice(loc.key as number, 1)
+    else delete loc.parent![loc.key as string]
+    return { ok: true, removed: loc.value }
+  }
+
+  for (let i = 0; i < ops.length; i++) {
+    const op = ops[i]!
+    const path = op.path as string
+    let error: string | null = null
+
+    switch (op.op as OpName) {
+      case "add":
+        error = setAt(path, clone(op.value), false)
+        break
+      case "replace":
+        error = setAt(path, clone(op.value), true)
+        break
+      case "remove": {
+        const r = removeAt(path)
+        if (!r.ok) error = r.error
+        break
+      }
+      case "move": {
+        const from = op.from as string
+        if (path.startsWith(`${from}/`)) {
+          error = `cannot move ${from} into its own child ${path}`
+          break
+        }
+        const r = removeAt(from)
+        if (!r.ok) { error = r.error; break }
+        error = setAt(path, r.removed, false)
+        break
+      }
+      case "copy": {
+        const r = getAt(op.from as string)
+        if (!r.ok) { error = r.error; break }
+        error = setAt(path, clone(r.value), false)
+        break
+      }
+      case "test": {
+        const r = getAt(path)
+        if (!r.ok) error = r.error
+        else if (!deepEqual(r.value, op.value)) error = `test failed at ${path}`
+        break
+      }
+    }
+
+    if (error !== null) return { ok: false, error, opIndex: i }
+  }
+  return { ok: true, result }
+}
+
+/** RFC 6901 token escaping, for building diagnostic pointers. */
+export function escapePointerToken(token: string): string {
+  return token.replace(/~/g, "~0").replace(/\//g, "~1")
+}

package/src/report/index.ts

@@ -0,0 +1,10 @@
+// ag-ui-validate/report: pure reporters over a core Report. No I/O — callers
+// decide where the strings go.
+export { formatDiagnosticLine, formatReportSummary } from "./pretty.js"
+export type { PrettyOptions } from "./pretty.js"
+export { toJsonReport } from "./json.js"
+export type { JsonReportDocument, JsonReportOptions } from "./json.js"
+export { toSarif } from "./sarif.js"
+export type { SarifLevel, SarifLog, SarifOptions, SarifResult } from "./sarif.js"
+export { toJUnit } from "./junit.js"
+export type { JUnitOptions } from "./junit.js"

package/src/report/json.ts

@@ -0,0 +1,20 @@
+// Machine-readable report: the core Report plus tool identification, so a
+// stored document is self-describing.
+import type { Report } from "../types.js"
+
+export interface JsonReportOptions {
+  tool: { name: string; version: string }
+  /** What was validated: URL, file path, or "stdin". */
+  target?: string
+}
+
+export interface JsonReportDocument extends Report {
+  tool: { name: string; version: string }
+  target?: string
+}
+
+export function toJsonReport(report: Report, opts: JsonReportOptions): JsonReportDocument {
+  const doc: JsonReportDocument = { tool: opts.tool, ...report }
+  if (opts.target !== undefined) doc.target = opts.target
+  return doc
+}

package/src/report/junit.ts

@@ -0,0 +1,56 @@
+// JUnit XML output for CI systems. One testcase per finding: errors are
+// <failure>, warnings and info are <skipped> (visible but not build-breaking —
+// the exit code, not the XML, decides pass/fail). A clean report is a single
+// passing testcase so the suite is never empty.
+import type { Report } from "../types.js"
+
+export interface JUnitOptions {
+  /** Suite name — typically the validated target. */
+  name: string
+}
+
+function esc(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;")
+}
+
+export function toJUnit(report: Report, opts: JUnitOptions): string {
+  const lines: string[] = ['<?xml version="1.0" encoding="UTF-8"?>']
+  const suite = esc(opts.name)
+
+  if (report.diagnostics.length === 0) {
+    lines.push('<testsuites name="ag-ui-validate" tests="1" failures="0" errors="0" skipped="0">')
+    lines.push(`  <testsuite name="${suite}" tests="1" failures="0" errors="0" skipped="0">`)
+    lines.push(
+      `    <testcase name="AG-UI conformance: no violations across ${report.eventCount} events" classname="${suite}"/>`,
+    )
+    lines.push("  </testsuite>")
+    lines.push("</testsuites>")
+    return `${lines.join("\n")}\n`
+  }
+
+  const failures = report.diagnostics.filter((d) => d.severity === "error").length
+  const skipped = report.diagnostics.length - failures
+  const counts = `tests="${report.diagnostics.length}" failures="${failures}" errors="0" skipped="${skipped}"`
+  lines.push(`<testsuites name="ag-ui-validate" ${counts}>`)
+  lines.push(`  <testsuite name="${suite}" ${counts}>`)
+  for (const d of report.diagnostics) {
+    const where = d.eventIndex >= 0 ? `event ${d.eventIndex}` : "stream"
+    const name = esc(`${d.rule} (${where})`)
+    lines.push(`    <testcase name="${name}" classname="${suite}">`)
+    const body = `${esc(d.message)}\n${esc(d.specUrl)}`
+    if (d.severity === "error") {
+      lines.push(`      <failure message="${esc(d.message)}">${body}</failure>`)
+    } else {
+      lines.push(`      <skipped message="${esc(`${d.severity}: ${d.message}`)}">${body}</skipped>`)
+    }
+    lines.push("    </testcase>")
+  }
+  lines.push("  </testsuite>")
+  lines.push("</testsuites>")
+  return `${lines.join("\n")}\n`
+}

package/src/report/pretty.ts

@@ -0,0 +1,59 @@
+// Human-readable output. Pure string formatting — the CLI decides where it
+// goes and whether a TTY wants color.
+import type { Diagnostic, Report, Severity } from "../types.js"
+
+export interface PrettyOptions {
+  color: boolean
+}
+
+const SYMBOL: Record<Severity, string> = { error: "✖", warning: "⚠", info: "ℹ" }
+const SGR: Record<Severity, string> = { error: "31", warning: "33", info: "36" }
+
+function paint(code: string, s: string, on: boolean): string {
+  return on ? `\x1b[${code}m${s}\x1b[0m` : s
+}
+
+export function formatDiagnosticLine(d: Diagnostic, opts: PrettyOptions): string {
+  const where = d.eventIndex >= 0 ? `event ${d.eventIndex}` : "—"
+  const head = paint(SGR[d.severity], `${SYMBOL[d.severity]} ${d.rule}`, opts.color)
+  const meta = paint("2", `${d.severity.padEnd(7)} ${where.padEnd(10)}`, opts.color)
+  const cite = paint("2", `  ↳ ${d.specUrl}`, opts.color)
+  return `${head}  ${meta} ${d.message}\n${cite}`
+}
+
+function count(n: number, noun: string): string {
+  return `${n} ${noun}${n === 1 ? "" : "s"}`
+}
+
+export function formatReportSummary(report: Report, opts: PrettyOptions): string {
+  const { errors, warnings, info } = report.summary
+  const lines: string[] = []
+
+  if (errors + warnings + info === 0) {
+    lines.push(
+      paint("32", `✔ no conformance violations across ${count(report.eventCount, "event")}`, opts.color),
+    )
+  } else {
+    lines.push(
+      `${count(errors, "error")}, ${count(warnings, "warning")}, ${info} info across ${count(report.eventCount, "event")}`,
+    )
+  }
+
+  const features = Object.entries(report.features)
+  const exercised = features.filter(([, s]) => s === "exercised").map(([f]) => f)
+  const suffix = exercised.length > 0 ? `: ${exercised.join(", ")}` : ""
+  lines.push(`${exercised.length} of ${features.length} AG-UI features exercised${suffix}`)
+
+  if (report.skipped.length > 0) {
+    lines.push(`${count(report.skipped.length, "rule")} not evaluated:`)
+    for (const s of report.skipped) {
+      lines.push(paint("2", `  – ${s.rule}: ${s.reason}`, opts.color))
+    }
+  }
+
+  for (const e of report.internalErrors) {
+    lines.push(paint("31", `! internal validator error: ${e}`, opts.color))
+  }
+
+  return lines.join("\n")
+}