ag-ui-validate 0.1.0 → 0.3.0

package/README.md

@@ -15,10 +15,11 @@ spec section.
 2 errors, 0 warnings, 1 info — 3 of 7 AG-UI features exercised
 ```
 
-> **Status: pre-release.** The core validator, the language-neutral fixture
-> corpus, and the transport layer are implemented and tested. The CLI
-> (`npx ag-ui-validate <url|->`), the Vitest matcher, and SARIF/JUnit
-> reporters are in progress.
+> **Status:** the TypeScript implementation is released to npm
+> (`npm install ag-ui-validate`). A native Python port — same rule catalog,
+> same fixture corpus, byte-identical CLI — is fully implemented and tested
+> but not yet published to PyPI as a functional release; see
+> [Python](#python) below.
 
 ## Why
 
@@ -66,6 +67,7 @@ Useful flags (see `--help` for all):
 | Flag | Effect |
 | --- | --- |
 | `--json` / `--sarif` / `--junit` | machine-readable report on stdout (SARIF 2.1.0 for code scanning, JUnit XML for CI) |
+| `--group` | one line per rule with a count — for large streams with repeated findings (totals stay exact) |
 | `--rule AGUI105=error`, `--off AGUI902` | per-rule severity overrides |
 | `--features shared-state,...` | declare exercised features (enables e.g. AGUI305) |
 | `--max-warnings 0` | fail CI on any warning |
@@ -123,7 +125,7 @@ const { diagnostics, summary, features, skipped } = v.report()
 ```
 
 The core is a pure function over an event sequence: zero I/O, zero runtime
-dependencies, isomorphic across Node 20+, browsers, Deno, and Workers.
+dependencies, isomorphic across Node 22+, browsers, Deno, and Workers.
 
 ### Validate a live endpoint
 
@@ -169,12 +171,71 @@ import { formatReportSummary, toSarif, toJUnit } from "ag-ui-validate/report"
 }
 ```
 
+## Python
+
+A native Python port ships in [py/](py/) — the same rule catalog, the same
+fixture corpus, and a CLI with byte-identical flags, error messages, and
+JSON/SARIF/JUnit output to the TypeScript one above. It's fully implemented
+and tested, and checked against the TypeScript implementation on every PR
+by Parity CI (see [docs/TESTING.md](docs/TESTING.md) for how, and
+[docs/PYTHON-PORT-PLAN.md](docs/PYTHON-PORT-PLAN.md) for the port's full
+milestone history). **Not yet published to PyPI as a functional release**
+— only a name-reservation placeholder (`0.0.1`) is live today.
+Install from source until a real release ships:
+
+```bash
+git clone https://github.com/langport-dev/ag-ui-validate
+cd ag-ui-validate/py
+pip install -e ".[dev]"   # or ".[transport]" for just the endpoint-validating extras
+```
+
+### CLI
+
+```bash
+ag-ui-validate http://localhost:8000/agui   # live endpoint (POSTs a RunAgentInput)
+ag-ui-validate run.jsonl                    # recorded stream (NDJSON/JSONL or SSE capture)
+cat run.jsonl | ag-ui-validate -            # stdin
+```
+
+Same exit codes and the same flags as the [CLI](#cli) above (see
+`ag-ui-validate --help`) — the Python argument parser is a direct,
+hand-rolled port of the TypeScript one rather than `argparse`/`click`,
+specifically to keep both CLIs' invocation and error messages
+byte-for-byte identical.
+
+### Test your agent in pytest
+
+```python
+from ag_ui_validate.pytest_plugin import assert_valid_agui
+
+def test_my_agent_stream(captured_events):
+    assert_valid_agui(captured_events, features=["shared-state"], max_warnings=0)
+```
+
+`assert_valid_agui` accepts a list of events (dicts or JSON strings) or a
+whole JSONL capture as one string, and raises `AssertionError` with every
+finding's rule ID and spec link on failure. It registers automatically as a
+pytest plugin on install — no `conftest.py` setup needed. An async
+counterpart validates a live endpoint directly from a test:
+
+```python
+from ag_ui_validate.pytest_plugin import assert_valid_agui_endpoint
+
+async def test_my_live_agent():
+    await assert_valid_agui_endpoint("http://localhost:8000/agui", max_warnings=0)
+```
+
+`assert_valid_agui` has zero runtime dependencies; only the
+endpoint-validating helpers (`assert_valid_agui_endpoint`,
+`validate_agui_endpoint`) pull in `httpx`
+(`pip install ag-ui-validate[transport]`).
+
 ## The rule catalog
 
 40 rules, maintained as **data** in
-[src/rules/catalog.json](src/rules/catalog.json) so other implementations
-(Python, Go, …) can share them. Every rule has its own page — spec grounding,
-severity, and a violating example from the corpus — in the
+[spec/catalog.json](spec/catalog.json), shared by both implementations in
+this repo ([TypeScript](.) and [Python](py/)) rather than duplicated.
+Every rule has its own page — spec grounding,
 **[rule index](docs/rules/README.md)** (generated from the catalog,
 drift-checked in CI):
 
@@ -194,7 +255,7 @@ drift-tested against the installed SDK on every run.
 
 ## The fixture corpus
 
-[fixtures/](fixtures/README.md) is a language-neutral conformance corpus:
+[spec/fixtures/](spec/fixtures/README.md) is a language-neutral conformance corpus:
 7 valid streams (one per canonical AG-UI feature — the false-positive guards)
 and 40 invalid fixtures (one per rule) with exact expected diagnostics. Any
 validator implementation that consumes the shared catalog can be tested
@@ -218,12 +279,18 @@ Component-by-component instructions live in
 rules are tracked in [docs/spec-questions.md](docs/spec-questions.md).
 
 Adding a rule: add the catalog entry (with its `specUrl`), add the fixture
-stream + intended findings to `scripts/build-fixtures.mjs`, and run
+stream + intended findings to `js/scripts/build-fixtures.mjs`, and run
 `npm run fixtures:build` — the meta-tests fail until both exist. Rule
 *proposals* belong upstream as issues on
 [`ag-ui-protocol/ag-ui`](https://github.com/ag-ui-protocol/ag-ui) first; this
 project does not invent rules the spec doesn't support.
 
+Releasing: merge the pending changesets (`npx changeset version`) via a PR,
+then publish a GitHub release tagged `vX.Y.Z` (matching `package.json`) — the
+[Publish workflow](.github/workflows/publish.yml) typechecks, builds, tests,
+and publishes to npm with provenance via trusted publishing. The workflow
+fails fast if the tag and `package.json` disagree.
+
 ## License
 
 MIT — maintained by [Faraz](https://langport.dev).

package/dist/{catalog-Ci9dqc1a.cjs → catalog-AB5vuZ8j.cjs}

@@ -1,4 +1,4 @@
-//#region src/rules/catalog.json
+//#region ../spec/catalog.json
 var catalog_default = {
 	$comment: "AG-UI conformance rule catalog. Data, not code: a Python/Go implementation shares these rules. Severities follow the working agreement that behaviour the spec does not clearly govern is at most 'info' — entries with 'specQuestion' were downgraded accordingly; see docs/spec-questions.md.",
 	catalogVersion: "0.1.0",
@@ -342,7 +342,7 @@ var catalog_default = {
 			"id": "AGUI503",
 			"severity": "error",
 			"title": "Unknown event type",
-			"messageTemplate": "Unknown event type '{type}' (not in @ag-ui/core v{sdkVersion}, and not RAW or CUSTOM)",
+			"messageTemplate": "Unknown event type '{type}' (not in the installed AG-UI SDK v{sdkVersion}, and not RAW or CUSTOM)",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#event-types-overview",
 			"specQuote": "Events in the protocol are categorized by their purpose.",
 			"since": "0.x",
@@ -492,4 +492,4 @@ Object.defineProperty(exports, "validateCatalog", {
 	}
 });
 
-//# sourceMappingURL=catalog-Ci9dqc1a.cjs.map
+//# sourceMappingURL=catalog-AB5vuZ8j.cjs.map

package/dist/catalog-AB5vuZ8j.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-AB5vuZ8j.cjs","names":["catalogJson"],"sources":["../spec/catalog.json","../js/src/rules/catalog.ts"],"sourcesContent":["","// Typed loader for the rule catalog. The catalog itself is data\n// (catalog.json) so other implementations can share it; this module gives it\n// types and validates its invariants once at load time.\n//\n// Note the asymmetry: the validator never throws on stream input, but a\n// malformed catalog is a programming error in this package, so the loader\n// throws loudly at import time.\n\nimport catalogJson from \"../../../spec/catalog.json\"\n\nexport type Severity = \"error\" | \"warning\" | \"info\"\nexport type SeverityOrOff = Severity | \"off\"\n\nconst SEVERITIES: readonly string[] = [\"error\", \"warning\", \"info\"]\nconst LAYERS: readonly string[] = [\"core\", \"transport\"]\n\nexport interface RuleDefinition {\n  /** e.g. \"AGUI203\" */\n  id: string\n  severity: Severity\n  title: string\n  /** Human template with {placeholder} slots filled per diagnostic. */\n  messageTemplate: string\n  /** Governing spec section. Mandatory: rules that cannot cite one don't ship. */\n  specUrl: string\n  /** Exact sentence from the spec section, where one exists. */\n  specQuote?: string\n  since: string\n  /** Canonical AG-UI feature this rule relates to, if any. */\n  feature?: string\n  /** True when the rule only fires if opts.features declares `feature`. */\n  requiresFeature?: boolean\n  /** Cross-reference into docs/spec-questions.md for downgraded/ambiguous rules. */\n  specQuestion?: string\n  /** Where the rule is evaluated. Transport rules are skipped (and the skip\n   * reported) when validating recorded input with no transport in play. */\n  checkedIn: \"core\" | \"transport\"\n}\n\nexport interface Catalog {\n  catalogVersion: string\n  spec: string\n  rules: readonly RuleDefinition[]\n}\n\n/** Validates catalog data and returns it typed. Throws on structural problems. */\nexport function validateCatalog(data: unknown): Catalog {\n  const problems: string[] = []\n  const cat = data as Catalog\n  if (typeof cat !== \"object\" || cat === null || !Array.isArray(cat.rules)) {\n    throw new Error(\"rule catalog: expected an object with a rules array\")\n  }\n  const seen = new Set<string>()\n  for (const rule of cat.rules) {\n    const where = rule?.id ?? \"<missing id>\"\n    if (!/^AGUI\\d{3}$/.test(rule.id ?? \"\")) problems.push(`${where}: id must match AGUI###`)\n    if (seen.has(rule.id)) problems.push(`${where}: duplicate id`)\n    seen.add(rule.id)\n    if (!SEVERITIES.includes(rule.severity)) problems.push(`${where}: bad severity '${rule.severity}'`)\n    if (!rule.title) problems.push(`${where}: missing title`)\n    if (!rule.messageTemplate) problems.push(`${where}: missing messageTemplate`)\n    if (!rule.specUrl?.startsWith(\"https://\")) problems.push(`${where}: specUrl must be an https URL`)\n    if (!rule.since) problems.push(`${where}: missing since`)\n    if (!LAYERS.includes(rule.checkedIn)) problems.push(`${where}: bad checkedIn '${rule.checkedIn}'`)\n    if (rule.requiresFeature && !rule.feature) problems.push(`${where}: requiresFeature without feature`)\n  }\n  if (problems.length > 0) {\n    throw new Error(`rule catalog is invalid:\\n  ${problems.join(\"\\n  \")}`)\n  }\n  return cat\n}\n\nexport const CATALOG: Catalog = validateCatalog(catalogJson)\n\nexport const RULES: ReadonlyMap<string, RuleDefinition> = new Map(\n  CATALOG.rules.map((r) => [r.id, r]),\n)\n\n/** Fills a rule's messageTemplate. Unknown placeholders are left intact. */\nexport function formatMessage(rule: RuleDefinition, params: Record<string, unknown>): string {\n  return rule.messageTemplate.replace(/\\{(\\w+)\\}/g, (whole, key: string) =>\n    key in params ? String(params[key]) : whole,\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACaA,MAAM,aAAgC;CAAC;CAAS;CAAW;AAAM;AACjE,MAAM,SAA4B,CAAC,QAAQ,WAAW;;AAgCtD,SAAgB,gBAAgB,MAAwB;CACtD,MAAM,WAAqB,CAAC;CAC5B,MAAM,MAAM;CACZ,IAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,CAAC,MAAM,QAAQ,IAAI,KAAK,GACrE,MAAM,IAAI,MAAM,qDAAqD;CAEvE,MAAM,uBAAO,IAAI,IAAY;CAC7B,KAAK,MAAM,QAAQ,IAAI,OAAO;EAC5B,MAAM,QAAQ,MAAM,MAAM;EAC1B,IAAI,CAAC,cAAc,KAAK,KAAK,MAAM,EAAE,GAAG,SAAS,KAAK,GAAG,MAAM,wBAAwB;EACvF,IAAI,KAAK,IAAI,KAAK,EAAE,GAAG,SAAS,KAAK,GAAG,MAAM,eAAe;EAC7D,KAAK,IAAI,KAAK,EAAE;EAChB,IAAI,CAAC,WAAW,SAAS,KAAK,QAAQ,GAAG,SAAS,KAAK,GAAG,MAAM,kBAAkB,KAAK,SAAS,EAAE;EAClG,IAAI,CAAC,KAAK,OAAO,SAAS,KAAK,GAAG,MAAM,gBAAgB;EACxD,IAAI,CAAC,KAAK,iBAAiB,SAAS,KAAK,GAAG,MAAM,0BAA0B;EAC5E,IAAI,CAAC,KAAK,SAAS,WAAW,UAAU,GAAG,SAAS,KAAK,GAAG,MAAM,+BAA+B;EACjG,IAAI,CAAC,KAAK,OAAO,SAAS,KAAK,GAAG,MAAM,gBAAgB;EACxD,IAAI,CAAC,OAAO,SAAS,KAAK,SAAS,GAAG,SAAS,KAAK,GAAG,MAAM,mBAAmB,KAAK,UAAU,EAAE;EACjG,IAAI,KAAK,mBAAmB,CAAC,KAAK,SAAS,SAAS,KAAK,GAAG,MAAM,kCAAkC;CACtG;CACA,IAAI,SAAS,SAAS,GACpB,MAAM,IAAI,MAAM,+BAA+B,SAAS,KAAK,MAAM,GAAG;CAExE,OAAO;AACT;AAEA,MAAa,UAAmB,gBAAgBA,eAAW;AAE3D,MAAa,QAA6C,IAAI,IAC5D,QAAQ,MAAM,KAAK,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,CACpC;;AAGA,SAAgB,cAAc,MAAsB,QAAyC;CAC3F,OAAO,KAAK,gBAAgB,QAAQ,eAAe,OAAO,QACxD,OAAO,SAAS,OAAO,OAAO,IAAI,IAAI,KACxC;AACF"}

package/dist/{catalog-BglXBNbL.js → catalog-DqTI4VLt.js}

@@ -1,4 +1,4 @@
-//#region src/rules/catalog.json
+//#region ../spec/catalog.json
 var catalog_default = {
 	$comment: "AG-UI conformance rule catalog. Data, not code: a Python/Go implementation shares these rules. Severities follow the working agreement that behaviour the spec does not clearly govern is at most 'info' — entries with 'specQuestion' were downgraded accordingly; see docs/spec-questions.md.",
 	catalogVersion: "0.1.0",
@@ -342,7 +342,7 @@ var catalog_default = {
 			"id": "AGUI503",
 			"severity": "error",
 			"title": "Unknown event type",
-			"messageTemplate": "Unknown event type '{type}' (not in @ag-ui/core v{sdkVersion}, and not RAW or CUSTOM)",
+			"messageTemplate": "Unknown event type '{type}' (not in the installed AG-UI SDK v{sdkVersion}, and not RAW or CUSTOM)",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#event-types-overview",
 			"specQuote": "Events in the protocol are categorized by their purpose.",
 			"since": "0.x",
@@ -469,4 +469,4 @@ function formatMessage(rule, params) {
 //#endregion
 export { validateCatalog as i, RULES as n, formatMessage as r, CATALOG as t };
 
-//# sourceMappingURL=catalog-BglXBNbL.js.map
+//# sourceMappingURL=catalog-DqTI4VLt.js.map

package/dist/catalog-DqTI4VLt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-DqTI4VLt.js","names":["catalogJson"],"sources":["../spec/catalog.json","../js/src/rules/catalog.ts"],"sourcesContent":["","// Typed loader for the rule catalog. The catalog itself is data\n// (catalog.json) so other implementations can share it; this module gives it\n// types and validates its invariants once at load time.\n//\n// Note the asymmetry: the validator never throws on stream input, but a\n// malformed catalog is a programming error in this package, so the loader\n// throws loudly at import time.\n\nimport catalogJson from \"../../../spec/catalog.json\"\n\nexport type Severity = \"error\" | \"warning\" | \"info\"\nexport type SeverityOrOff = Severity | \"off\"\n\nconst SEVERITIES: readonly string[] = [\"error\", \"warning\", \"info\"]\nconst LAYERS: readonly string[] = [\"core\", \"transport\"]\n\nexport interface RuleDefinition {\n  /** e.g. \"AGUI203\" */\n  id: string\n  severity: Severity\n  title: string\n  /** Human template with {placeholder} slots filled per diagnostic. */\n  messageTemplate: string\n  /** Governing spec section. Mandatory: rules that cannot cite one don't ship. */\n  specUrl: string\n  /** Exact sentence from the spec section, where one exists. */\n  specQuote?: string\n  since: string\n  /** Canonical AG-UI feature this rule relates to, if any. */\n  feature?: string\n  /** True when the rule only fires if opts.features declares `feature`. */\n  requiresFeature?: boolean\n  /** Cross-reference into docs/spec-questions.md for downgraded/ambiguous rules. */\n  specQuestion?: string\n  /** Where the rule is evaluated. Transport rules are skipped (and the skip\n   * reported) when validating recorded input with no transport in play. */\n  checkedIn: \"core\" | \"transport\"\n}\n\nexport interface Catalog {\n  catalogVersion: string\n  spec: string\n  rules: readonly RuleDefinition[]\n}\n\n/** Validates catalog data and returns it typed. Throws on structural problems. */\nexport function validateCatalog(data: unknown): Catalog {\n  const problems: string[] = []\n  const cat = data as Catalog\n  if (typeof cat !== \"object\" || cat === null || !Array.isArray(cat.rules)) {\n    throw new Error(\"rule catalog: expected an object with a rules array\")\n  }\n  const seen = new Set<string>()\n  for (const rule of cat.rules) {\n    const where = rule?.id ?? \"<missing id>\"\n    if (!/^AGUI\\d{3}$/.test(rule.id ?? \"\")) problems.push(`${where}: id must match AGUI###`)\n    if (seen.has(rule.id)) problems.push(`${where}: duplicate id`)\n    seen.add(rule.id)\n    if (!SEVERITIES.includes(rule.severity)) problems.push(`${where}: bad severity '${rule.severity}'`)\n    if (!rule.title) problems.push(`${where}: missing title`)\n    if (!rule.messageTemplate) problems.push(`${where}: missing messageTemplate`)\n    if (!rule.specUrl?.startsWith(\"https://\")) problems.push(`${where}: specUrl must be an https URL`)\n    if (!rule.since) problems.push(`${where}: missing since`)\n    if (!LAYERS.includes(rule.checkedIn)) problems.push(`${where}: bad checkedIn '${rule.checkedIn}'`)\n    if (rule.requiresFeature && !rule.feature) problems.push(`${where}: requiresFeature without feature`)\n  }\n  if (problems.length > 0) {\n    throw new Error(`rule catalog is invalid:\\n  ${problems.join(\"\\n  \")}`)\n  }\n  return cat\n}\n\nexport const CATALOG: Catalog = validateCatalog(catalogJson)\n\nexport const RULES: ReadonlyMap<string, RuleDefinition> = new Map(\n  CATALOG.rules.map((r) => [r.id, r]),\n)\n\n/** Fills a rule's messageTemplate. Unknown placeholders are left intact. */\nexport function formatMessage(rule: RuleDefinition, params: Record<string, unknown>): string {\n  return rule.messageTemplate.replace(/\\{(\\w+)\\}/g, (whole, key: string) =>\n    key in params ? String(params[key]) : whole,\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACaA,MAAM,aAAgC;CAAC;CAAS;CAAW;AAAM;AACjE,MAAM,SAA4B,CAAC,QAAQ,WAAW;;AAgCtD,SAAgB,gBAAgB,MAAwB;CACtD,MAAM,WAAqB,CAAC;CAC5B,MAAM,MAAM;CACZ,IAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,CAAC,MAAM,QAAQ,IAAI,KAAK,GACrE,MAAM,IAAI,MAAM,qDAAqD;CAEvE,MAAM,uBAAO,IAAI,IAAY;CAC7B,KAAK,MAAM,QAAQ,IAAI,OAAO;EAC5B,MAAM,QAAQ,MAAM,MAAM;EAC1B,IAAI,CAAC,cAAc,KAAK,KAAK,MAAM,EAAE,GAAG,SAAS,KAAK,GAAG,MAAM,wBAAwB;EACvF,IAAI,KAAK,IAAI,KAAK,EAAE,GAAG,SAAS,KAAK,GAAG,MAAM,eAAe;EAC7D,KAAK,IAAI,KAAK,EAAE;EAChB,IAAI,CAAC,WAAW,SAAS,KAAK,QAAQ,GAAG,SAAS,KAAK,GAAG,MAAM,kBAAkB,KAAK,SAAS,EAAE;EAClG,IAAI,CAAC,KAAK,OAAO,SAAS,KAAK,GAAG,MAAM,gBAAgB;EACxD,IAAI,CAAC,KAAK,iBAAiB,SAAS,KAAK,GAAG,MAAM,0BAA0B;EAC5E,IAAI,CAAC,KAAK,SAAS,WAAW,UAAU,GAAG,SAAS,KAAK,GAAG,MAAM,+BAA+B;EACjG,IAAI,CAAC,KAAK,OAAO,SAAS,KAAK,GAAG,MAAM,gBAAgB;EACxD,IAAI,CAAC,OAAO,SAAS,KAAK,SAAS,GAAG,SAAS,KAAK,GAAG,MAAM,mBAAmB,KAAK,UAAU,EAAE;EACjG,IAAI,KAAK,mBAAmB,CAAC,KAAK,SAAS,SAAS,KAAK,GAAG,MAAM,kCAAkC;CACtG;CACA,IAAI,SAAS,SAAS,GACpB,MAAM,IAAI,MAAM,+BAA+B,SAAS,KAAK,MAAM,GAAG;CAExE,OAAO;AACT;AAEA,MAAa,UAAmB,gBAAgBA,eAAW;AAE3D,MAAa,QAA6C,IAAI,IAC5D,QAAQ,MAAM,KAAK,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,CACpC;;AAGA,SAAgB,cAAc,MAAsB,QAAyC;CAC3F,OAAO,KAAK,gBAAgB,QAAQ,eAAe,OAAO,QACxD,OAAO,SAAS,OAAO,OAAO,IAAI,IAAI,KACxC;AACF"}

package/dist/cli.js

@@ -16,6 +16,7 @@ Output (default: human-readable):
   --json-file <path>              additionally write the JSON report to a file
   --sarif-file <path>             additionally write a SARIF log to a file
   --junit-file <path>             additionally write JUnit XML to a file
+  --group                         one line per rule with a count (large streams)
   --no-color                      disable ANSI colors
 
 Rules:
@@ -50,6 +51,10 @@ const FLAGS = {
 		takesValue: false,
 		apply: (c) => (c.color = false, null)
 	},
+	"--group": {
+		takesValue: false,
+		apply: (c) => (c.group = true, null)
+	},
 	"--json": {
 		takesValue: false,
 		apply: (c) => setFormat(c, "json")
@@ -142,6 +147,7 @@ function parseCliArgs(argv) {
 		color: null,
 		headers: {},
 		severityOverrides: {},
+		group: false,
 		help: false,
 		version: false
 	};
@@ -182,6 +188,10 @@ function parseCliArgs(argv) {
 			error
 		};
 	}
+	if (config.group && config.format !== "pretty") return {
+		ok: false,
+		error: "--group only applies to the default pretty output, not --json/--sarif/--junit"
+	};
 	if (targets.length > 1) return {
 		ok: false,
 		error: `expected exactly one target, got ${targets.length}`
@@ -202,58 +212,7 @@ function decideExitCode(summary, maxWarnings) {
 	return 0;
 }
 //#endregion
-//#region src/report/pretty.ts
-const SYMBOL = {
-	error: "✖",
-	warning: "⚠",
-	info: "ℹ"
-};
-const SGR = {
-	error: "31",
-	warning: "33",
-	info: "36"
-};
-function paint(code, s, on) {
-	return on ? `\x1b[${code}m${s}\x1b[0m` : s;
-}
-function formatDiagnosticLine(d, opts) {
-	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, noun) {
-	return `${n} ${noun}${n === 1 ? "" : "s"}`;
-}
-function formatReportSummary(report, opts) {
-	const { errors, warnings, info } = report.summary;
-	const lines = [];
-	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");
-}
-//#endregion
-//#region src/report/json.ts
-function toJsonReport(report, opts) {
-	const doc = {
-		tool: opts.tool,
-		...report
-	};
-	if (opts.target !== void 0) doc.target = opts.target;
-	return doc;
-}
-//#endregion
-//#region src/rules/catalog.json
+//#region ../spec/catalog.json
 var catalog_default = {
 	$comment: "AG-UI conformance rule catalog. Data, not code: a Python/Go implementation shares these rules. Severities follow the working agreement that behaviour the spec does not clearly govern is at most 'info' — entries with 'specQuestion' were downgraded accordingly; see docs/spec-questions.md.",
 	catalogVersion: "0.1.0",
@@ -597,7 +556,7 @@ var catalog_default = {
 			"id": "AGUI503",
 			"severity": "error",
 			"title": "Unknown event type",
-			"messageTemplate": "Unknown event type '{type}' (not in @ag-ui/core v{sdkVersion}, and not RAW or CUSTOM)",
+			"messageTemplate": "Unknown event type '{type}' (not in the installed AG-UI SDK v{sdkVersion}, and not RAW or CUSTOM)",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#event-types-overview",
 			"specQuote": "Events in the protocol are categorized by their purpose.",
 			"since": "0.x",
@@ -722,6 +681,98 @@ function formatMessage(rule, params) {
 	return rule.messageTemplate.replace(/\{(\w+)\}/g, (whole, key) => key in params ? String(params[key]) : whole);
 }
 //#endregion
+//#region src/report/pretty.ts
+const SYMBOL = {
+	error: "✖",
+	warning: "⚠",
+	info: "ℹ"
+};
+const SGR = {
+	error: "31",
+	warning: "33",
+	info: "36"
+};
+function paint(code, s, on) {
+	return on ? `\x1b[${code}m${s}\x1b[0m` : s;
+}
+function formatDiagnosticLine(d, opts) {
+	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, noun) {
+	return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+const SEVERITY_RANK = {
+	error: 0,
+	warning: 1,
+	info: 2
+};
+const SAMPLE_INDEXES = 3;
+/**
+* One line per rule instead of one per occurrence — for large streams where
+* the same violation repeats. Totals stay honest in the summary; this only
+* changes what is listed.
+*/
+function formatGroupedDiagnostics(diagnostics, opts) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const d of diagnostics) {
+		const list = groups.get(d.rule);
+		if (list === void 0) groups.set(d.rule, [d]);
+		else list.push(d);
+	}
+	const sorted = [...groups.values()].sort((a, b) => {
+		const bySeverity = SEVERITY_RANK[a[0].severity] - SEVERITY_RANK[b[0].severity];
+		return bySeverity !== 0 ? bySeverity : a[0].rule.localeCompare(b[0].rule);
+	});
+	const lines = [];
+	for (const group of sorted) {
+		const first = group[0];
+		const title = RULES.get(first.rule)?.title ?? first.message;
+		const indexes = group.map((d) => d.eventIndex).filter((i) => i >= 0);
+		let where;
+		if (indexes.length === 0) where = "stream-level";
+		else {
+			const sample = indexes.slice(0, SAMPLE_INDEXES).join(", ");
+			const rest = indexes.length - SAMPLE_INDEXES;
+			where = `events ${sample}${rest > 0 ? ` (+${rest} more)` : ""}`;
+		}
+		const head = paint(SGR[first.severity], `${SYMBOL[first.severity]} ${first.rule}`, opts.color);
+		const meta = paint("2", `${first.severity.padEnd(7)} ×${group.length}`, opts.color);
+		const cite = paint("2", `  ↳ ${first.specUrl}`, opts.color);
+		lines.push(`${head}  ${meta}  ${title} — ${where}`, cite);
+	}
+	return lines.join("\n");
+}
+function formatReportSummary(report, opts) {
+	const { errors, warnings, info } = report.summary;
+	const lines = [];
+	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");
+}
+//#endregion
+//#region src/report/json.ts
+function toJsonReport(report, opts) {
+	const doc = {
+		tool: opts.tool,
+		...report
+	};
+	if (opts.target !== void 0) doc.target = opts.target;
+	return doc;
+}
+//#endregion
 //#region src/report/sarif.ts
 const LEVEL = {
 	error: "error",
@@ -2707,7 +2758,7 @@ async function main() {
 	const color = config.color ?? (process.stdout.isTTY === true && process.env.NO_COLOR === void 0);
 	const pretty = config.format === "pretty";
 	let printed = 0;
-	const onDiagnostic = pretty ? (d) => {
+	const onDiagnostic = pretty && !config.group ? (d) => {
 		printed += 1;
 		process.stdout.write(`${formatDiagnosticLine(d, { color })}\n`);
 	} : void 0;
@@ -2755,7 +2806,8 @@ async function main() {
 	if (config.sarifFile !== void 0) writeFileSync(config.sarifFile, `${JSON.stringify(toSarif(report, sarifOptions), null, 2)}\n`);
 	if (config.junitFile !== void 0) writeFileSync(config.junitFile, toJUnit(report, { name: targetLabel }));
 	if (pretty) {
-		if (printed > 0) process.stdout.write("\n");
+		if (config.group && report.diagnostics.length > 0) process.stdout.write(`${formatGroupedDiagnostics(report.diagnostics, { color })}\n\n`);
+		else if (printed > 0) process.stdout.write("\n");
 		process.stdout.write(`${formatReportSummary(report, { color })}\n`);
 	} else if (config.format === "json") {
 		const doc = toJsonReport(report, {