@keboola/validate-ui 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -1,4 +1,81 @@
 import { Page, Browser } from 'playwright';
+import { z } from 'zod';
+
+/**
+ * Backend/render state of a region. A region that rendered its data is `ok`;
+ * `empty`/`error`/`loading` are non-data states — an old→new transition into one
+ * of them is a degrade, not a value regression (a backend was unavailable, or an
+ * intentional empty state is showing).
+ */
+declare const REGION_STATES: readonly ["ok", "empty", "error", "loading"];
+type RegionState = (typeof REGION_STATES)[number];
+/** One diffable region of a page — a landmark, labelled section, or component. */
+declare const Region: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    state: z.ZodEnum<{
+        ok: "ok";
+        empty: "empty";
+        error: "error";
+        loading: "loading";
+    }>;
+    values: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type Region = z.infer<typeof Region>;
+/**
+ * A page reduced to its diffable regions — the currency both input paths (a live
+ * boot or a recorded JSON file) produce and the differ consumes. Pure JSON, so
+ * it is safe to serialize to disk and re-load; {@link loadSnapshot} validates it.
+ */
+declare const CompareSnapshot: z.ZodObject<{
+    route: z.ZodString;
+    regions: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        state: z.ZodEnum<{
+            ok: "ok";
+            empty: "empty";
+            error: "error";
+            loading: "loading";
+        }>;
+        values: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type CompareSnapshot = z.infer<typeof CompareSnapshot>;
+/** One old-vs-new delta, always attributed to a region. */
+type CompareFinding = Finding & {
+    regionKey: string;
+    kind: 'region-removed' | 'region-degraded' | 'value-missing' | 'region-added';
+    /** Stable signature of the delta — identical across routes for shared chrome. */
+    valueSignature: string;
+    /** Present when a config rule suppressed this delta; it never fails the verdict. */
+    suppressed?: {
+        reason: string;
+    };
+};
+/**
+ * One expected-absent rule. `region` (exact or `*`-glob against {@link Region.key})
+ * alone suppresses a whole `region-removed`; add `value` to suppress a specific
+ * missing value token (optionally scoped to a region). `reason` is required and
+ * surfaced in the report so suppression is auditable, never silent.
+ */
+declare const ExpectedAbsentRule: z.ZodObject<{
+    region: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    reason: z.ZodString;
+}, z.core.$strip>;
+type ExpectedAbsentRule = z.infer<typeof ExpectedAbsentRule>;
+/** Semantic-compare configuration — the allowlist plus extra state markers. */
+declare const CompareConfig: z.ZodObject<{
+    expectedAbsent: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        region: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    emptyStateMarkers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    errorStateMarkers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type CompareConfig = z.infer<typeof CompareConfig>;
 
 /** A named viewport the harness renders and captures at. */
 type Viewport = {
@@ -84,11 +161,15 @@ type AxisContext = {
     baseline?: Uint8Array;
     /** Re-render the same route under a different brand id and capture it. */
     captureUnderBrand?: (brand: string) => Promise<CaptureArtifact>;
+    /** The "old" UI reduced to regions — enables the compare axis when present. */
+    comparison?: CompareSnapshot;
+    /** Allowlist + state markers for the compare axis. */
+    compareConfig?: CompareConfig;
 };
 /**
- * A verdict axis. Each of the four axes (runtime-health, accessibility,
- * visual-brand, brief-conformance) implements this contract in its own file so
- * they can be built independently. `run` must resolve to a {@link Verdict} and
+ * A verdict axis. Each of the axes (runtime-health, accessibility,
+ * visual-brand, brief-conformance, compare) implements this contract in its own
+ * file so they can be built independently. `run` must resolve to a {@link Verdict} and
  * should not throw for expected-missing input — the aggregator converts a throw
  * into a failing verdict, but a clear finding is better.
  */
@@ -157,6 +238,10 @@ type ValidateOptions = {
     /** Reuse a browser instead of launching one. */
     browser?: Browser;
     timeoutMs?: number;
+    /** The "old" UI reduced to regions — enables the compare axis when present. */
+    comparison?: CompareSnapshot;
+    /** Allowlist + state markers for the compare axis. */
+    compareConfig?: CompareConfig;
 };
 /**
  * The closed loop: render `url`, capture ground truth, and run every axis over
@@ -170,6 +255,18 @@ declare const accessibilityAxis: Axis;
 
 declare const briefConformanceAxis: Axis;
 
+/**
+ * A5 · Semantic old-vs-new compare verdict — UT-4572.
+ *
+ * Activates only when `context.comparison` (an "old" {@link CompareSnapshot}) is
+ * supplied; otherwise it degrades to a passing skip, so ordinary single-page runs
+ * are unaffected. Extracts the "new" snapshot from the live `context.page`, then
+ * runs the pure {@link diffSnapshots}: deltas are localized per region, declared
+ * expected-absent deltas are suppressed (not dropped), and a region that degraded
+ * to an empty/error state is reported informationally rather than as value loss.
+ */
+declare const compareAxis: Axis;
+
 /**
  * A2 · Runtime-health verdict — UT-4493.
  *
@@ -191,7 +288,101 @@ declare const runtimeHealthAxis: Axis;
  */
 declare const visualBrandAxis: Axis;
 
-/** The four axes, in report order. */
+/**
+ * The registered axes, in report order. `compare` runs last and only activates
+ * when a comparison snapshot is supplied, so ordinary single-page runs are
+ * unaffected.
+ */
 declare const ALL_AXES: Axis[];
 
-export { ALL_AXES, type AggregateVerdict, type Axis, type AxisContext, type CaptureArtifact, type CaptureOptions, type ConsoleEntry, DEFAULT_VIEWPORTS, DESKTOP_VIEWPORT, type Finding, MOBILE_VIEWPORT, type NetworkEntry, SEVERITIES, type Severity, type StaticServer, type ValidateOptions, type Verdict, type Viewport, accessibilityAxis, aggregatePass, briefConformanceAxis, capture, capturePage, prepareForScreenshot, runAxes, runtimeHealthAxis, serveStatic, validate, visualBrandAxis };
+/**
+ * Semantic old-vs-new diff of two snapshots. Walks regions by key and localizes
+ * every delta to a region: a removed region is `serious` unless allowlisted; a
+ * region that degraded to an empty/error state is reported informationally and
+ * NOT diffed as value loss; surviving regions get a per-region value-multiset
+ * diff with allowlist suppression; new regions are non-regression notes. Pure —
+ * no browser, no I/O.
+ */
+declare const diffSnapshots: (oldSnap: CompareSnapshot, newSnap: CompareSnapshot, config?: CompareConfig) => CompareFinding[];
+/** A compare run passes when no active (non-suppressed) delta is serious/critical. */
+declare const comparePass: (findings: CompareFinding[]) => boolean;
+
+/** One route's compare findings. */
+type RouteFindings = {
+    route: string;
+    findings: CompareFinding[];
+};
+type DedupResult = {
+    /** Findings seen on ≥2 routes, collapsed to one entry tagged with the route count. */
+    sharedChrome: CompareFinding[];
+    /** Per-route findings with the shared-chrome copies removed. */
+    perRoute: RouteFindings[];
+};
+/**
+ * Collapse deltas that recur across routes into a single `shared-chrome` finding.
+ * A value flagged on a shared header/daily-brief element would otherwise be
+ * multiplied across every route (the prototype's `8.4/7.7/-8%/67%` on all 10
+ * pages); here it is reported once, tagged with the routes it spans, and dropped
+ * from each route's own list. Pure — no browser, no I/O.
+ */
+declare const dedupeSharedChrome: (perRoute: RouteFindings[]) => DedupResult;
+
+/**
+ * Reduce the live page to its diffable regions, in the browser. An explicit
+ * `[data-region]` is an authoritative boundary (its subtree is one region);
+ * elsewhere boundaries are the outermost-empty ("leaf") landmarks/sections, so
+ * regions never overlap or double-count values. Each region's key is resolved by
+ * precedence
+ * (`data-region` → `data-testid` → role → `aria-label` → nearest heading), its
+ * state from `data-state`/text markers, and its values as normalized numeric
+ * tokens. Symmetric across old and new so the two sides diff cleanly.
+ */
+declare const extractRegions: (page: Page, config?: CompareConfig) => Promise<Region[]>;
+
+/** How the "old" side is sourced — booted live or loaded from recorded snapshots, never both. */
+type OldSource = {
+    oldBaseUrl: string;
+    oldSnapshotDir?: never;
+} | {
+    oldSnapshotDir: string;
+    oldBaseUrl?: never;
+};
+type CompareRoutesOptions = OldSource & {
+    /** Base URL of the new build, joined with each route. */
+    newBaseUrl: string;
+    routes: string[];
+    config?: CompareConfig;
+    browser?: Browser;
+    viewport?: Viewport;
+    timeoutMs?: number;
+};
+type RouteCompareResult = {
+    route: string;
+    findings: CompareFinding[];
+    pass: boolean;
+};
+type CompareRoutesResult = {
+    routes: RouteCompareResult[];
+    /** Deltas seen on ≥2 routes, reported once (e.g. shared chrome / daily-brief). */
+    sharedChrome: CompareFinding[];
+    pass: boolean;
+};
+/** Recorded old snapshot filename for a route: `/a/b` → `a_b.json`, `/` → `index.json`. */
+declare const routeSnapshotFile: (route: string) => string;
+/**
+ * Multi-route semantic compare. Boots each route on the new side (and the old
+ * side too, unless recorded snapshots are supplied), diffs per route, then
+ * collapses deltas that recur across routes into a single shared-chrome entry so
+ * one shared element is not reported as N regressions. Exactly one of
+ * `oldBaseUrl` / `oldSnapshotDir` must be given.
+ */
+declare const compareRoutes: (options: CompareRoutesOptions) => Promise<CompareRoutesResult>;
+
+/** Reduce a loaded live page to a {@link CompareSnapshot} for the given route. */
+declare const captureSnapshot: (page: Page, route: string, config?: CompareConfig) => Promise<CompareSnapshot>;
+/** Persist a snapshot as pretty JSON so an "old" side can be recorded once and re-diffed. */
+declare const saveSnapshot: (snapshot: CompareSnapshot, path: string) => Promise<void>;
+/** Read and validate a recorded snapshot from disk. */
+declare const loadSnapshot: (path: string) => Promise<CompareSnapshot>;
+
+export { ALL_AXES, type AggregateVerdict, type Axis, type AxisContext, type CaptureArtifact, type CaptureOptions, CompareConfig, type CompareFinding, type CompareRoutesOptions, type CompareRoutesResult, CompareSnapshot, type ConsoleEntry, DEFAULT_VIEWPORTS, DESKTOP_VIEWPORT, type DedupResult, ExpectedAbsentRule, type Finding, MOBILE_VIEWPORT, type NetworkEntry, REGION_STATES, Region, type RegionState, type RouteCompareResult, type RouteFindings, SEVERITIES, type Severity, type StaticServer, type ValidateOptions, type Verdict, type Viewport, accessibilityAxis, aggregatePass, briefConformanceAxis, capture, capturePage, captureSnapshot, compareAxis, comparePass, compareRoutes, dedupeSharedChrome, diffSnapshots, extractRegions, loadSnapshot, prepareForScreenshot, routeSnapshotFile, runAxes, runtimeHealthAxis, saveSnapshot, serveStatic, validate, visualBrandAxis };

package/dist/index.d.ts

@@ -1,4 +1,81 @@
 import { Page, Browser } from 'playwright';
+import { z } from 'zod';
+
+/**
+ * Backend/render state of a region. A region that rendered its data is `ok`;
+ * `empty`/`error`/`loading` are non-data states — an old→new transition into one
+ * of them is a degrade, not a value regression (a backend was unavailable, or an
+ * intentional empty state is showing).
+ */
+declare const REGION_STATES: readonly ["ok", "empty", "error", "loading"];
+type RegionState = (typeof REGION_STATES)[number];
+/** One diffable region of a page — a landmark, labelled section, or component. */
+declare const Region: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    state: z.ZodEnum<{
+        ok: "ok";
+        empty: "empty";
+        error: "error";
+        loading: "loading";
+    }>;
+    values: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type Region = z.infer<typeof Region>;
+/**
+ * A page reduced to its diffable regions — the currency both input paths (a live
+ * boot or a recorded JSON file) produce and the differ consumes. Pure JSON, so
+ * it is safe to serialize to disk and re-load; {@link loadSnapshot} validates it.
+ */
+declare const CompareSnapshot: z.ZodObject<{
+    route: z.ZodString;
+    regions: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        state: z.ZodEnum<{
+            ok: "ok";
+            empty: "empty";
+            error: "error";
+            loading: "loading";
+        }>;
+        values: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type CompareSnapshot = z.infer<typeof CompareSnapshot>;
+/** One old-vs-new delta, always attributed to a region. */
+type CompareFinding = Finding & {
+    regionKey: string;
+    kind: 'region-removed' | 'region-degraded' | 'value-missing' | 'region-added';
+    /** Stable signature of the delta — identical across routes for shared chrome. */
+    valueSignature: string;
+    /** Present when a config rule suppressed this delta; it never fails the verdict. */
+    suppressed?: {
+        reason: string;
+    };
+};
+/**
+ * One expected-absent rule. `region` (exact or `*`-glob against {@link Region.key})
+ * alone suppresses a whole `region-removed`; add `value` to suppress a specific
+ * missing value token (optionally scoped to a region). `reason` is required and
+ * surfaced in the report so suppression is auditable, never silent.
+ */
+declare const ExpectedAbsentRule: z.ZodObject<{
+    region: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    reason: z.ZodString;
+}, z.core.$strip>;
+type ExpectedAbsentRule = z.infer<typeof ExpectedAbsentRule>;
+/** Semantic-compare configuration — the allowlist plus extra state markers. */
+declare const CompareConfig: z.ZodObject<{
+    expectedAbsent: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        region: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    emptyStateMarkers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    errorStateMarkers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type CompareConfig = z.infer<typeof CompareConfig>;
 
 /** A named viewport the harness renders and captures at. */
 type Viewport = {
@@ -84,11 +161,15 @@ type AxisContext = {
     baseline?: Uint8Array;
     /** Re-render the same route under a different brand id and capture it. */
     captureUnderBrand?: (brand: string) => Promise<CaptureArtifact>;
+    /** The "old" UI reduced to regions — enables the compare axis when present. */
+    comparison?: CompareSnapshot;
+    /** Allowlist + state markers for the compare axis. */
+    compareConfig?: CompareConfig;
 };
 /**
- * A verdict axis. Each of the four axes (runtime-health, accessibility,
- * visual-brand, brief-conformance) implements this contract in its own file so
- * they can be built independently. `run` must resolve to a {@link Verdict} and
+ * A verdict axis. Each of the axes (runtime-health, accessibility,
+ * visual-brand, brief-conformance, compare) implements this contract in its own
+ * file so they can be built independently. `run` must resolve to a {@link Verdict} and
  * should not throw for expected-missing input — the aggregator converts a throw
  * into a failing verdict, but a clear finding is better.
  */
@@ -157,6 +238,10 @@ type ValidateOptions = {
     /** Reuse a browser instead of launching one. */
     browser?: Browser;
     timeoutMs?: number;
+    /** The "old" UI reduced to regions — enables the compare axis when present. */
+    comparison?: CompareSnapshot;
+    /** Allowlist + state markers for the compare axis. */
+    compareConfig?: CompareConfig;
 };
 /**
  * The closed loop: render `url`, capture ground truth, and run every axis over
@@ -170,6 +255,18 @@ declare const accessibilityAxis: Axis;
 
 declare const briefConformanceAxis: Axis;
 
+/**
+ * A5 · Semantic old-vs-new compare verdict — UT-4572.
+ *
+ * Activates only when `context.comparison` (an "old" {@link CompareSnapshot}) is
+ * supplied; otherwise it degrades to a passing skip, so ordinary single-page runs
+ * are unaffected. Extracts the "new" snapshot from the live `context.page`, then
+ * runs the pure {@link diffSnapshots}: deltas are localized per region, declared
+ * expected-absent deltas are suppressed (not dropped), and a region that degraded
+ * to an empty/error state is reported informationally rather than as value loss.
+ */
+declare const compareAxis: Axis;
+
 /**
  * A2 · Runtime-health verdict — UT-4493.
  *
@@ -191,7 +288,101 @@ declare const runtimeHealthAxis: Axis;
  */
 declare const visualBrandAxis: Axis;
 
-/** The four axes, in report order. */
+/**
+ * The registered axes, in report order. `compare` runs last and only activates
+ * when a comparison snapshot is supplied, so ordinary single-page runs are
+ * unaffected.
+ */
 declare const ALL_AXES: Axis[];
 
-export { ALL_AXES, type AggregateVerdict, type Axis, type AxisContext, type CaptureArtifact, type CaptureOptions, type ConsoleEntry, DEFAULT_VIEWPORTS, DESKTOP_VIEWPORT, type Finding, MOBILE_VIEWPORT, type NetworkEntry, SEVERITIES, type Severity, type StaticServer, type ValidateOptions, type Verdict, type Viewport, accessibilityAxis, aggregatePass, briefConformanceAxis, capture, capturePage, prepareForScreenshot, runAxes, runtimeHealthAxis, serveStatic, validate, visualBrandAxis };
+/**
+ * Semantic old-vs-new diff of two snapshots. Walks regions by key and localizes
+ * every delta to a region: a removed region is `serious` unless allowlisted; a
+ * region that degraded to an empty/error state is reported informationally and
+ * NOT diffed as value loss; surviving regions get a per-region value-multiset
+ * diff with allowlist suppression; new regions are non-regression notes. Pure —
+ * no browser, no I/O.
+ */
+declare const diffSnapshots: (oldSnap: CompareSnapshot, newSnap: CompareSnapshot, config?: CompareConfig) => CompareFinding[];
+/** A compare run passes when no active (non-suppressed) delta is serious/critical. */
+declare const comparePass: (findings: CompareFinding[]) => boolean;
+
+/** One route's compare findings. */
+type RouteFindings = {
+    route: string;
+    findings: CompareFinding[];
+};
+type DedupResult = {
+    /** Findings seen on ≥2 routes, collapsed to one entry tagged with the route count. */
+    sharedChrome: CompareFinding[];
+    /** Per-route findings with the shared-chrome copies removed. */
+    perRoute: RouteFindings[];
+};
+/**
+ * Collapse deltas that recur across routes into a single `shared-chrome` finding.
+ * A value flagged on a shared header/daily-brief element would otherwise be
+ * multiplied across every route (the prototype's `8.4/7.7/-8%/67%` on all 10
+ * pages); here it is reported once, tagged with the routes it spans, and dropped
+ * from each route's own list. Pure — no browser, no I/O.
+ */
+declare const dedupeSharedChrome: (perRoute: RouteFindings[]) => DedupResult;
+
+/**
+ * Reduce the live page to its diffable regions, in the browser. An explicit
+ * `[data-region]` is an authoritative boundary (its subtree is one region);
+ * elsewhere boundaries are the outermost-empty ("leaf") landmarks/sections, so
+ * regions never overlap or double-count values. Each region's key is resolved by
+ * precedence
+ * (`data-region` → `data-testid` → role → `aria-label` → nearest heading), its
+ * state from `data-state`/text markers, and its values as normalized numeric
+ * tokens. Symmetric across old and new so the two sides diff cleanly.
+ */
+declare const extractRegions: (page: Page, config?: CompareConfig) => Promise<Region[]>;
+
+/** How the "old" side is sourced — booted live or loaded from recorded snapshots, never both. */
+type OldSource = {
+    oldBaseUrl: string;
+    oldSnapshotDir?: never;
+} | {
+    oldSnapshotDir: string;
+    oldBaseUrl?: never;
+};
+type CompareRoutesOptions = OldSource & {
+    /** Base URL of the new build, joined with each route. */
+    newBaseUrl: string;
+    routes: string[];
+    config?: CompareConfig;
+    browser?: Browser;
+    viewport?: Viewport;
+    timeoutMs?: number;
+};
+type RouteCompareResult = {
+    route: string;
+    findings: CompareFinding[];
+    pass: boolean;
+};
+type CompareRoutesResult = {
+    routes: RouteCompareResult[];
+    /** Deltas seen on ≥2 routes, reported once (e.g. shared chrome / daily-brief). */
+    sharedChrome: CompareFinding[];
+    pass: boolean;
+};
+/** Recorded old snapshot filename for a route: `/a/b` → `a_b.json`, `/` → `index.json`. */
+declare const routeSnapshotFile: (route: string) => string;
+/**
+ * Multi-route semantic compare. Boots each route on the new side (and the old
+ * side too, unless recorded snapshots are supplied), diffs per route, then
+ * collapses deltas that recur across routes into a single shared-chrome entry so
+ * one shared element is not reported as N regressions. Exactly one of
+ * `oldBaseUrl` / `oldSnapshotDir` must be given.
+ */
+declare const compareRoutes: (options: CompareRoutesOptions) => Promise<CompareRoutesResult>;
+
+/** Reduce a loaded live page to a {@link CompareSnapshot} for the given route. */
+declare const captureSnapshot: (page: Page, route: string, config?: CompareConfig) => Promise<CompareSnapshot>;
+/** Persist a snapshot as pretty JSON so an "old" side can be recorded once and re-diffed. */
+declare const saveSnapshot: (snapshot: CompareSnapshot, path: string) => Promise<void>;
+/** Read and validate a recorded snapshot from disk. */
+declare const loadSnapshot: (path: string) => Promise<CompareSnapshot>;
+
+export { ALL_AXES, type AggregateVerdict, type Axis, type AxisContext, type CaptureArtifact, type CaptureOptions, CompareConfig, type CompareFinding, type CompareRoutesOptions, type CompareRoutesResult, CompareSnapshot, type ConsoleEntry, DEFAULT_VIEWPORTS, DESKTOP_VIEWPORT, type DedupResult, ExpectedAbsentRule, type Finding, MOBILE_VIEWPORT, type NetworkEntry, REGION_STATES, Region, type RegionState, type RouteCompareResult, type RouteFindings, SEVERITIES, type Severity, type StaticServer, type ValidateOptions, type Verdict, type Viewport, accessibilityAxis, aggregatePass, briefConformanceAxis, capture, capturePage, captureSnapshot, compareAxis, comparePass, compareRoutes, dedupeSharedChrome, diffSnapshots, extractRegions, loadSnapshot, prepareForScreenshot, routeSnapshotFile, runAxes, runtimeHealthAxis, saveSnapshot, serveStatic, validate, visualBrandAxis };