ag-ui-validate 0.1.0 → 0.2.0

package/README.md

@@ -66,6 +66,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 |
@@ -224,6 +225,12 @@ stream + intended findings to `scripts/build-fixtures.mjs`, and run
 [`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/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,57 +212,6 @@ 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
 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.",
@@ -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, {