ag-ui-validate 0.1.0

package/dist/types-oH_QTnn2.d.cts

@@ -0,0 +1,148 @@
+//#region src/rules/catalog.d.ts
+type Severity = "error" | "warning" | "info";
+type SeverityOrOff = Severity | "off";
+interface RuleDefinition {
+  /** e.g. "AGUI203" */
+  id: string;
+  severity: Severity;
+  title: string;
+  /** Human template with {placeholder} slots filled per diagnostic. */
+  messageTemplate: string;
+  /** Governing spec section. Mandatory: rules that cannot cite one don't ship. */
+  specUrl: string;
+  /** Exact sentence from the spec section, where one exists. */
+  specQuote?: string;
+  since: string;
+  /** Canonical AG-UI feature this rule relates to, if any. */
+  feature?: string;
+  /** True when the rule only fires if opts.features declares `feature`. */
+  requiresFeature?: boolean;
+  /** Cross-reference into docs/spec-questions.md for downgraded/ambiguous rules. */
+  specQuestion?: string;
+  /** Where the rule is evaluated. Transport rules are skipped (and the skip
+   * reported) when validating recorded input with no transport in play. */
+  checkedIn: "core" | "transport";
+}
+interface Catalog {
+  catalogVersion: string;
+  spec: string;
+  rules: readonly RuleDefinition[];
+}
+/** Validates catalog data and returns it typed. Throws on structural problems. */
+declare function validateCatalog(data: unknown): Catalog;
+declare const CATALOG: Catalog;
+declare const RULES: ReadonlyMap<string, RuleDefinition>;
+/** Fills a rule's messageTemplate. Unknown placeholders are left intact. */
+declare function formatMessage(rule: RuleDefinition, params: Record<string, unknown>): string;
+//#endregion
+//#region src/types.d.ts
+/** A single conformance finding. */
+interface Diagnostic {
+  /** Rule ID, e.g. "AGUI203". */
+  rule: string;
+  severity: Severity;
+  /** Human-readable, includes the offending id/value. */
+  message: string;
+  /**
+   * 0-based position in the stream of the event this diagnostic is about.
+   * Stream-level diagnostics (e.g. AGUI902) use -1.
+   */
+  eventIndex: number;
+  /** The event's declared type, if parseable. */
+  eventType?: string;
+  /** RFC 6901 JSON pointer into the event, e.g. "/toolCallId". */
+  pointer?: string;
+  /** e.g. the unterminated TOOL_CALL_START this refers back to. */
+  relatedEventIndex?: number;
+  /** Link to the governing spec section. Always populated. */
+  specUrl: string;
+}
+/** The seven canonical AG-UI features (from the AG-UI Dojo). */
+type CanonicalFeature = "agentic-chat" | "backend-tool-rendering" | "human-in-the-loop" | "agentic-generative-ui" | "tool-based-generative-ui" | "shared-state" | "predictive-state-updates";
+declare const CANONICAL_FEATURES: readonly CanonicalFeature[];
+/**
+ * Feature-matrix status. Capability discovery (getCapabilities()) is
+ * out-of-band and invisible to a passive stream observer, so this matrix is
+ * inferred from observed events; features whose exercise cannot be
+ * distinguished passively are "not-inferable". See docs/spec-questions.md SQ-13.
+ */
+type FeatureStatus = "exercised" | "not-exercised" | "not-inferable";
+type FeatureMatrix = Record<CanonicalFeature, FeatureStatus>;
+interface Summary {
+  errors: number;
+  warnings: number;
+  info: number;
+}
+interface SkippedRule {
+  rule: string;
+  reason: string;
+}
+interface Report {
+  diagnostics: Diagnostic[];
+  summary: Summary;
+  features: FeatureMatrix;
+  /**
+   * Rules that were not evaluated in this mode and why — e.g. transport rules
+   * when validating recorded input. Skips are reported, never silent.
+   */
+  skipped: SkippedRule[];
+  eventCount: number;
+  /**
+   * Unexpected internal validator errors. The validator never throws on any
+   * input; if a check itself crashes, the message lands here instead.
+   */
+  internalErrors: string[];
+}
+type ValidationLayer = "core" | "transport";
+interface ValidatorOptions {
+  /** Pins the rule set to a spec version. Only "0.x" exists today. */
+  spec?: "0.x";
+  /**
+   * Declared features. Enables feature-conditional rules (e.g. AGUI305 fires
+   * only when "shared-state" is declared).
+   */
+  features?: string[];
+  /** Per-rule severity overrides; "off" disables a rule. */
+  severityOverrides?: Record<string, SeverityOrOff>;
+  /**
+   * Which rule layers are being evaluated. "core" is always on. Wrapping
+   * layers that check transport rules (via emitExternal) declare "transport"
+   * so those rules stop being reported as skipped. Default: ["core"].
+   */
+  layers?: ValidationLayer[];
+}
+interface Validator {
+  /**
+   * Feed one event — a parsed object, or a raw JSON string (malformed JSON is
+   * a diagnostic, not an exception). Returns diagnostics detectable at this
+   * event, in stream order. Never throws.
+   */
+  feed(event: unknown): Diagnostic[];
+  /**
+   * End-of-stream checks (unterminated tool calls, missing RUN_FINISHED, …).
+   * Idempotent: second and later calls return []. Never throws.
+   */
+  finalize(): Diagnostic[];
+  /** Cumulative report over everything fed so far. Never throws. */
+  report(): Report;
+  /**
+   * For wrapping layers (transport, CLI): report a layer-checked rule through
+   * the same catalog formatting, severity overrides, and summary as core
+   * diagnostics. Returns the diagnostic, or null when the rule is unknown
+   * (recorded in internalErrors) or overridden off. Never throws.
+   */
+  emitExternal(rule: string, params?: Record<string, unknown>, extra?: {
+    eventIndex?: number;
+    pointer?: string;
+    relatedEventIndex?: number;
+  }): Diagnostic | null;
+  /**
+   * For wrapping layers: declare that a rule was NOT evaluated and why (e.g.
+   * timing rules on recorded input). The entry appears in report().skipped,
+   * replacing any layer-computed entry for the same rule. Never throws.
+   */
+  markSkipped(rule: string, reason: string): void;
+}
+//#endregion
+export { SeverityOrOff as _, FeatureStatus as a, Summary as c, ValidatorOptions as d, CATALOG as f, Severity as g, RuleDefinition as h, FeatureMatrix as i, ValidationLayer as l, RULES as m, CanonicalFeature as n, Report as o, Catalog as p, Diagnostic as r, SkippedRule as s, CANONICAL_FEATURES as t, Validator as u, formatMessage as v, validateCatalog as y };
+//# sourceMappingURL=types-oH_QTnn2.d.cts.map

package/dist/types-oH_QTnn2.d.ts

@@ -0,0 +1,148 @@
+//#region src/rules/catalog.d.ts
+type Severity = "error" | "warning" | "info";
+type SeverityOrOff = Severity | "off";
+interface RuleDefinition {
+  /** e.g. "AGUI203" */
+  id: string;
+  severity: Severity;
+  title: string;
+  /** Human template with {placeholder} slots filled per diagnostic. */
+  messageTemplate: string;
+  /** Governing spec section. Mandatory: rules that cannot cite one don't ship. */
+  specUrl: string;
+  /** Exact sentence from the spec section, where one exists. */
+  specQuote?: string;
+  since: string;
+  /** Canonical AG-UI feature this rule relates to, if any. */
+  feature?: string;
+  /** True when the rule only fires if opts.features declares `feature`. */
+  requiresFeature?: boolean;
+  /** Cross-reference into docs/spec-questions.md for downgraded/ambiguous rules. */
+  specQuestion?: string;
+  /** Where the rule is evaluated. Transport rules are skipped (and the skip
+   * reported) when validating recorded input with no transport in play. */
+  checkedIn: "core" | "transport";
+}
+interface Catalog {
+  catalogVersion: string;
+  spec: string;
+  rules: readonly RuleDefinition[];
+}
+/** Validates catalog data and returns it typed. Throws on structural problems. */
+declare function validateCatalog(data: unknown): Catalog;
+declare const CATALOG: Catalog;
+declare const RULES: ReadonlyMap<string, RuleDefinition>;
+/** Fills a rule's messageTemplate. Unknown placeholders are left intact. */
+declare function formatMessage(rule: RuleDefinition, params: Record<string, unknown>): string;
+//#endregion
+//#region src/types.d.ts
+/** A single conformance finding. */
+interface Diagnostic {
+  /** Rule ID, e.g. "AGUI203". */
+  rule: string;
+  severity: Severity;
+  /** Human-readable, includes the offending id/value. */
+  message: string;
+  /**
+   * 0-based position in the stream of the event this diagnostic is about.
+   * Stream-level diagnostics (e.g. AGUI902) use -1.
+   */
+  eventIndex: number;
+  /** The event's declared type, if parseable. */
+  eventType?: string;
+  /** RFC 6901 JSON pointer into the event, e.g. "/toolCallId". */
+  pointer?: string;
+  /** e.g. the unterminated TOOL_CALL_START this refers back to. */
+  relatedEventIndex?: number;
+  /** Link to the governing spec section. Always populated. */
+  specUrl: string;
+}
+/** The seven canonical AG-UI features (from the AG-UI Dojo). */
+type CanonicalFeature = "agentic-chat" | "backend-tool-rendering" | "human-in-the-loop" | "agentic-generative-ui" | "tool-based-generative-ui" | "shared-state" | "predictive-state-updates";
+declare const CANONICAL_FEATURES: readonly CanonicalFeature[];
+/**
+ * Feature-matrix status. Capability discovery (getCapabilities()) is
+ * out-of-band and invisible to a passive stream observer, so this matrix is
+ * inferred from observed events; features whose exercise cannot be
+ * distinguished passively are "not-inferable". See docs/spec-questions.md SQ-13.
+ */
+type FeatureStatus = "exercised" | "not-exercised" | "not-inferable";
+type FeatureMatrix = Record<CanonicalFeature, FeatureStatus>;
+interface Summary {
+  errors: number;
+  warnings: number;
+  info: number;
+}
+interface SkippedRule {
+  rule: string;
+  reason: string;
+}
+interface Report {
+  diagnostics: Diagnostic[];
+  summary: Summary;
+  features: FeatureMatrix;
+  /**
+   * Rules that were not evaluated in this mode and why — e.g. transport rules
+   * when validating recorded input. Skips are reported, never silent.
+   */
+  skipped: SkippedRule[];
+  eventCount: number;
+  /**
+   * Unexpected internal validator errors. The validator never throws on any
+   * input; if a check itself crashes, the message lands here instead.
+   */
+  internalErrors: string[];
+}
+type ValidationLayer = "core" | "transport";
+interface ValidatorOptions {
+  /** Pins the rule set to a spec version. Only "0.x" exists today. */
+  spec?: "0.x";
+  /**
+   * Declared features. Enables feature-conditional rules (e.g. AGUI305 fires
+   * only when "shared-state" is declared).
+   */
+  features?: string[];
+  /** Per-rule severity overrides; "off" disables a rule. */
+  severityOverrides?: Record<string, SeverityOrOff>;
+  /**
+   * Which rule layers are being evaluated. "core" is always on. Wrapping
+   * layers that check transport rules (via emitExternal) declare "transport"
+   * so those rules stop being reported as skipped. Default: ["core"].
+   */
+  layers?: ValidationLayer[];
+}
+interface Validator {
+  /**
+   * Feed one event — a parsed object, or a raw JSON string (malformed JSON is
+   * a diagnostic, not an exception). Returns diagnostics detectable at this
+   * event, in stream order. Never throws.
+   */
+  feed(event: unknown): Diagnostic[];
+  /**
+   * End-of-stream checks (unterminated tool calls, missing RUN_FINISHED, …).
+   * Idempotent: second and later calls return []. Never throws.
+   */
+  finalize(): Diagnostic[];
+  /** Cumulative report over everything fed so far. Never throws. */
+  report(): Report;
+  /**
+   * For wrapping layers (transport, CLI): report a layer-checked rule through
+   * the same catalog formatting, severity overrides, and summary as core
+   * diagnostics. Returns the diagnostic, or null when the rule is unknown
+   * (recorded in internalErrors) or overridden off. Never throws.
+   */
+  emitExternal(rule: string, params?: Record<string, unknown>, extra?: {
+    eventIndex?: number;
+    pointer?: string;
+    relatedEventIndex?: number;
+  }): Diagnostic | null;
+  /**
+   * For wrapping layers: declare that a rule was NOT evaluated and why (e.g.
+   * timing rules on recorded input). The entry appears in report().skipped,
+   * replacing any layer-computed entry for the same rule. Never throws.
+   */
+  markSkipped(rule: string, reason: string): void;
+}
+//#endregion
+export { SeverityOrOff as _, FeatureStatus as a, Summary as c, ValidatorOptions as d, CATALOG as f, Severity as g, RuleDefinition as h, FeatureMatrix as i, ValidationLayer as l, RULES as m, CanonicalFeature as n, Report as o, Catalog as p, Diagnostic as r, SkippedRule as s, CANONICAL_FEATURES as t, Validator as u, formatMessage as v, validateCatalog as y };
+//# sourceMappingURL=types-oH_QTnn2.d.ts.map

package/dist/vitest.d.ts

@@ -0,0 +1,28 @@
+//#region src/rules/catalog.d.ts
+type Severity = "error" | "warning" | "info";
+type SeverityOrOff = Severity | "off";
+//#endregion
+//#region src/vitest/matcher.d.ts
+interface ToBeValidAGUIOptions {
+  /** Declared features (enables feature-conditional rules, e.g. AGUI305). */
+  features?: string[];
+  /** Per-rule severity overrides; "off" disables a rule. */
+  severityOverrides?: Record<string, SeverityOrOff>;
+  /** Fail when warning-severity findings exceed this budget. */
+  maxWarnings?: number;
+}
+interface MatcherResult {
+  pass: boolean;
+  message: () => string;
+}
+declare function toBeValidAGUI(received: unknown, options?: ToBeValidAGUIOptions): MatcherResult;
+//#endregion
+//#region src/vitest/index.d.ts
+declare module "vitest" {
+  interface Matchers<T = any> {
+    toBeValidAGUI(options?: ToBeValidAGUIOptions): T;
+  }
+}
+//#endregion
+export { type MatcherResult, type ToBeValidAGUIOptions, toBeValidAGUI };
+//# sourceMappingURL=vitest.d.ts.map