@keboola/validate-ui 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -10,6 +10,7 @@ var zod = require('zod');
 var Anthropic = require('@anthropic-ai/sdk');
 var pixelmatch = require('pixelmatch');
 var pngjs = require('pngjs');
+var brandRegistry = require('@keboola/brand-registry');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -341,6 +342,302 @@ ${domExcerpt}`
   }
 };
 
+// src/compare/diff.ts
+var matchesGlob = (pattern, value) => {
+  if (!pattern.includes("*")) return pattern === value;
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`).test(value);
+};
+var multisetMissing = (from, to) => {
+  const remaining = /* @__PURE__ */ new Map();
+  for (const value of to) remaining.set(value, (remaining.get(value) ?? 0) + 1);
+  const missing = [];
+  for (const value of from) {
+    const count = remaining.get(value) ?? 0;
+    if (count > 0) remaining.set(value, count - 1);
+    else missing.push(value);
+  }
+  return missing;
+};
+var signature = (regionKey, tokens) => `${regionKey}::${[...tokens].sort().join("|")}`;
+var regionRemovalRule = (rules, key) => rules.find(
+  (rule) => rule.value === void 0 && rule.region !== void 0 && matchesGlob(rule.region, key)
+);
+var valueRuleMatches = (rule, key, value) => rule.value !== void 0 && matchesGlob(rule.value, value) && (rule.region === void 0 || matchesGlob(rule.region, key));
+var removedFinding = (region, rule) => ({
+  regionKey: region.key,
+  kind: "region-removed",
+  valueSignature: signature(region.key, region.values),
+  message: rule === void 0 ? `region "${region.label}" was removed` : `region "${region.label}" removed as expected`,
+  severity: rule === void 0 ? "serious" : "minor",
+  ...rule !== void 0 && { suppressed: { reason: rule.reason } }
+});
+var degradedFinding = (region) => ({
+  regionKey: region.key,
+  kind: "region-degraded",
+  valueSignature: signature(region.key, [region.state]),
+  message: `region "${region.label}" degraded to ${region.state} state \u2014 not compared as value loss`,
+  severity: "minor"
+});
+var addedFinding = (region) => ({
+  regionKey: region.key,
+  kind: "region-added",
+  valueSignature: signature(region.key, []),
+  message: `region "${region.label}" is new`,
+  severity: "minor"
+});
+var diffRegionValues = (oldRegion, newRegion, rules) => {
+  const missing = multisetMissing(oldRegion.values, newRegion.values);
+  if (missing.length === 0) return [];
+  const active = [];
+  const suppressed = [];
+  const reasons = /* @__PURE__ */ new Set();
+  for (const value of missing) {
+    const rule = rules.find((r) => valueRuleMatches(r, newRegion.key, value));
+    if (rule === void 0) active.push(value);
+    else {
+      suppressed.push(value);
+      reasons.add(rule.reason);
+    }
+  }
+  const findings = [];
+  if (active.length > 0) {
+    findings.push({
+      regionKey: newRegion.key,
+      kind: "value-missing",
+      valueSignature: signature(newRegion.key, active),
+      message: `region "${newRegion.label}" is missing ${active.length} value(s)`,
+      severity: "moderate",
+      detail: active.join(", ")
+    });
+  }
+  if (suppressed.length > 0) {
+    findings.push({
+      regionKey: newRegion.key,
+      kind: "value-missing",
+      valueSignature: signature(newRegion.key, suppressed),
+      message: `region "${newRegion.label}" is missing ${suppressed.length} expected value(s)`,
+      severity: "minor",
+      detail: suppressed.join(", "),
+      suppressed: { reason: [...reasons].join("; ") }
+    });
+  }
+  return findings;
+};
+var diffSnapshots = (oldSnap, newSnap, config = {}) => {
+  const rules = config.expectedAbsent ?? [];
+  const newByKey = new Map(newSnap.regions.map((region) => [region.key, region]));
+  const oldKeys = new Set(oldSnap.regions.map((region) => region.key));
+  const findings = [];
+  for (const oldRegion of oldSnap.regions) {
+    const newRegion = newByKey.get(oldRegion.key);
+    if (newRegion === void 0) {
+      findings.push(removedFinding(oldRegion, regionRemovalRule(rules, oldRegion.key)));
+      continue;
+    }
+    if (oldRegion.state === "ok" && newRegion.state !== "ok") {
+      findings.push(degradedFinding(newRegion));
+      continue;
+    }
+    findings.push(...diffRegionValues(oldRegion, newRegion, rules));
+  }
+  for (const newRegion of newSnap.regions) {
+    if (!oldKeys.has(newRegion.key)) findings.push(addedFinding(newRegion));
+  }
+  return findings;
+};
+var comparePass = (findings) => !findings.some(
+  (f) => f.suppressed === void 0 && (f.severity === "serious" || f.severity === "critical")
+);
+
+// src/compare/regions.ts
+var CANDIDATE_SELECTOR = [
+  "[data-region]",
+  "main",
+  "nav",
+  "header",
+  "aside",
+  "footer",
+  "section[aria-label]",
+  "[role=main]",
+  "[role=navigation]",
+  "[role=banner]",
+  "[role=complementary]",
+  "[role=contentinfo]",
+  "[role=region]"
+].join(",");
+var DEFAULT_EMPTY_MARKERS = [
+  "no data",
+  "no results",
+  "nothing to show",
+  "nothing here",
+  "get started"
+];
+var DEFAULT_ERROR_MARKERS = [
+  "something went wrong",
+  "failed to load",
+  "could not load",
+  "unavailable",
+  "try again"
+];
+var extractRegions = async (page, config = {}) => {
+  const emptyMarkers = [...DEFAULT_EMPTY_MARKERS, ...config.emptyStateMarkers ?? []];
+  const errorMarkers = [...DEFAULT_ERROR_MARKERS, ...config.errorStateMarkers ?? []];
+  return page.evaluate(
+    ({ selector, emptyMarkers: emptyMarkers2, errorMarkers: errorMarkers2 }) => {
+      const STATES = ["ok", "empty", "error", "loading"];
+      const isState = (value) => STATES.includes(value);
+      const slugify = (raw) => raw.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "region";
+      const roleOf = (el) => {
+        const explicit = el.getAttribute("role");
+        if (explicit !== null && explicit !== "") return explicit;
+        const tag = el.tagName.toLowerCase();
+        if (tag === "main") return "main";
+        if (tag === "nav") return "navigation";
+        if (tag === "aside") return "complementary";
+        if (tag === "header" || tag === "footer") {
+          if (el.closest("main,nav,section,article,aside") !== null) return void 0;
+          return tag === "header" ? "banner" : "contentinfo";
+        }
+        return void 0;
+      };
+      const headingOf = (el) => {
+        const heading = el.querySelector("h1,h2,h3,h4,h5,h6");
+        const text = heading?.textContent?.trim();
+        return text !== void 0 && text !== "" ? text : void 0;
+      };
+      const keyOf = (el) => {
+        const region = el.getAttribute("data-region");
+        if (region !== null && region !== "") return slugify(region);
+        const testid = el.getAttribute("data-testid");
+        if (testid !== null && testid !== "") return slugify(testid);
+        const role = roleOf(el);
+        if (role !== void 0) return role;
+        const label = el.getAttribute("aria-label");
+        if (label !== null && label !== "") return slugify(label);
+        const heading = headingOf(el);
+        if (heading !== void 0) return slugify(heading);
+        return slugify(el.tagName);
+      };
+      const labelOf = (el, key) => {
+        const label = el.getAttribute("aria-label");
+        if (label !== null && label.trim() !== "") return label.trim();
+        const heading = headingOf(el);
+        if (heading !== void 0) return heading;
+        const testid = el.getAttribute("data-testid");
+        if (testid !== null && testid !== "") return testid;
+        return key;
+      };
+      const textOf = (el) => (el.innerText || el.textContent || "").trim();
+      const stateOf = (el, text) => {
+        const explicit = (el.getAttribute("data-state") ?? "").toLowerCase();
+        if (isState(explicit)) return explicit;
+        const lower = text.toLowerCase();
+        if (errorMarkers2.some((marker) => lower.includes(marker))) return "error";
+        if (lower.includes("loading")) return "loading";
+        if (emptyMarkers2.some((marker) => lower.includes(marker))) return "empty";
+        return "ok";
+      };
+      const valuesOf = (text) => (text.match(/-?\$?\s?\d[\d,]*(?:\.\d+)?%?/g) ?? []).map((token) => token.replace(/[$\s,]/g, "")).filter((token) => token !== "" && token !== "-");
+      const qualifies = (el) => {
+        const dataRegion = el.getAttribute("data-region");
+        if (dataRegion !== null && dataRegion !== "") {
+          const parent = el.parentElement;
+          return parent === null || parent.closest("[data-region]") === null;
+        }
+        return el.querySelector(selector) === null && el.closest("[data-region]") === null;
+      };
+      const candidates = Array.from(document.querySelectorAll(selector));
+      const regions = candidates.filter(qualifies);
+      const elements = regions.length > 0 ? regions : [document.body];
+      const used = {};
+      const uniqueKey = (key) => {
+        const count = (used[key] ?? 0) + 1;
+        used[key] = count;
+        return count === 1 ? key : `${key}-${count}`;
+      };
+      return elements.map((el) => {
+        const text = textOf(el);
+        const key = uniqueKey(keyOf(el));
+        return {
+          key,
+          label: labelOf(el, key),
+          state: stateOf(el, text),
+          values: valuesOf(text)
+        };
+      });
+    },
+    { selector: CANDIDATE_SELECTOR, emptyMarkers, errorMarkers }
+  );
+};
+var REGION_STATES = ["ok", "empty", "error", "loading"];
+var Region = zod.z.object({
+  /** Stable id: data-region → data-testid → role → aria-label → heading slug. */
+  key: zod.z.string(),
+  /** Human label for the report. */
+  label: zod.z.string(),
+  state: zod.z.enum(REGION_STATES),
+  /** Normalized numeric / currency / percent tokens found in the region. */
+  values: zod.z.array(zod.z.string())
+});
+var CompareSnapshot = zod.z.object({
+  /** Route the snapshot was captured at, e.g. `/financials`. */
+  route: zod.z.string(),
+  regions: zod.z.array(Region)
+}).refine(
+  (snap) => new Set(snap.regions.map((region) => region.key)).size === snap.regions.length,
+  {
+    message: "region keys must be unique"
+  }
+);
+var ExpectedAbsentRule = zod.z.object({
+  region: zod.z.string().optional(),
+  value: zod.z.string().optional(),
+  reason: zod.z.string().min(1)
+}).refine((rule) => rule.region !== void 0 || rule.value !== void 0, {
+  message: "expectedAbsent rule needs at least one of `region` or `value`"
+});
+var CompareConfig = zod.z.object({
+  expectedAbsent: zod.z.array(ExpectedAbsentRule).optional(),
+  emptyStateMarkers: zod.z.array(zod.z.string()).optional(),
+  errorStateMarkers: zod.z.array(zod.z.string()).optional()
+});
+
+// src/compare/snapshot.ts
+var captureSnapshot = async (page, route, config) => ({
+  route,
+  regions: await extractRegions(page, config)
+});
+var saveSnapshot = async (snapshot, path) => {
+  await promises.writeFile(path, JSON.stringify(snapshot, null, 2));
+};
+var loadSnapshot = async (path) => {
+  const raw = await promises.readFile(path, "utf8");
+  return CompareSnapshot.parse(JSON.parse(raw));
+};
+
+// src/axes/compare.ts
+var skip2 = (message) => ({
+  axis: "compare",
+  pass: true,
+  findings: [{ message, severity: "minor" }]
+});
+var compareAxis = {
+  name: "compare",
+  run: async (context) => {
+    const { comparison, compareConfig, page } = context;
+    if (comparison === void 0) {
+      return skip2("no comparison snapshot provided; old-vs-new not assessed");
+    }
+    if (page === void 0) {
+      return skip2("compare needs a live page to extract the new snapshot");
+    }
+    const newSnapshot = await captureSnapshot(page, comparison.route, compareConfig);
+    const findings = diffSnapshots(comparison, newSnapshot, compareConfig);
+    return { axis: "compare", pass: comparePass(findings), findings };
+  }
+};
+
 // src/axes/runtime-health.ts
 var ERROR_MARKERS = [
   "something went wrong",
@@ -479,6 +776,11 @@ var altBrandFinding = (screenshot, altScreenshot, brand) => {
   }
   return null;
 };
+var interactiveContrastFindings = (brand) => brandRegistry.checkInteractiveContrast(brand).map((warning) => ({
+  message: `brand '${brand.id}' ${warning.message}`,
+  severity: "moderate",
+  detail: `${warning.foreground} on ${warning.background} (${warning.palette})`
+}));
 var overflowFinding = async (page) => {
   const overflows = await page.evaluate(
     () => document.documentElement.scrollWidth > document.documentElement.clientWidth
@@ -505,6 +807,8 @@ var visualBrandAxis = {
         DEFAULT_ALT_BRAND
       );
       if (finding !== null) findings.push(finding);
+      const altBrand = brandRegistry.brands.find((brand) => brand.id === DEFAULT_ALT_BRAND);
+      if (altBrand !== void 0) findings.push(...interactiveContrastFindings(altBrand));
     }
     if (page !== void 0) {
       const finding = await overflowFinding(page);
@@ -520,7 +824,8 @@ var ALL_AXES = [
   runtimeHealthAxis,
   accessibilityAxis,
   visualBrandAxis,
-  briefConformanceAxis
+  briefConformanceAxis,
+  compareAxis
 ];
 
 // src/aggregate.ts
@@ -564,6 +869,8 @@ var validate = async (options) => {
       browser,
       brief: options.brief,
       baseline: options.baseline,
+      comparison: options.comparison,
+      compareConfig: options.compareConfig,
       captureUnderBrand: async (brand) => {
         const brandContext = await browser.newContext({
           viewport: { width: viewport.width, height: viewport.height }
@@ -589,19 +896,121 @@ var validate = async (options) => {
   }
 };
 
+// src/compare/dedup.ts
+var groupKey = (finding) => `${finding.kind}::${finding.valueSignature}`;
+var dedupeSharedChrome = (perRoute) => {
+  const routesByGroup = /* @__PURE__ */ new Map();
+  for (const { route, findings } of perRoute) {
+    for (const finding of findings) {
+      const key = groupKey(finding);
+      const routes = routesByGroup.get(key) ?? /* @__PURE__ */ new Set();
+      routes.add(route);
+      routesByGroup.set(key, routes);
+    }
+  }
+  const sharedGroups = new Set(
+    [...routesByGroup].filter(([, routes]) => routes.size >= 2).map(([key]) => key)
+  );
+  const sharedChrome = [];
+  const seenShared = /* @__PURE__ */ new Set();
+  const trimmedPerRoute = perRoute.map(({ route, findings }) => ({
+    route,
+    findings: findings.filter((finding) => !sharedGroups.has(groupKey(finding)))
+  }));
+  for (const { findings } of perRoute) {
+    for (const finding of findings) {
+      const key = groupKey(finding);
+      if (!sharedGroups.has(key) || seenShared.has(key)) continue;
+      seenShared.add(key);
+      const routes = [...routesByGroup.get(key) ?? []].sort();
+      sharedChrome.push({
+        ...finding,
+        message: `${finding.message} (shared across ${routes.length} routes: ${routes.join(", ")})`
+      });
+    }
+  }
+  return { sharedChrome, perRoute: trimmedPerRoute };
+};
+var DEFAULT_TIMEOUT_MS2 = 3e4;
+var joinUrl = (base, route) => `${base.replace(/\/$/, "")}/${route.replace(/^\//, "")}`;
+var routeSnapshotFile = (route) => `${route.replace(/^\//, "").replace(/\/+$/, "").replace(/\//g, "_") || "index"}.json`;
+var compareRoutes = async (options) => {
+  if (options.oldBaseUrl === void 0 === (options.oldSnapshotDir === void 0)) {
+    throw new Error("compareRoutes: provide exactly one of oldBaseUrl or oldSnapshotDir");
+  }
+  const viewport = options.viewport ?? DESKTOP_VIEWPORT;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+  const browser = options.browser ?? await playwright.chromium.launch();
+  const ownsBrowser = options.browser === void 0;
+  const { oldBaseUrl, oldSnapshotDir } = options;
+  const snapshotUrl = async (url, route) => {
+    const context = await browser.newContext({
+      viewport: { width: viewport.width, height: viewport.height }
+    });
+    const page = await context.newPage();
+    try {
+      await page.goto(url, { waitUntil: "networkidle", timeout: timeoutMs });
+      await prepareForScreenshot(page);
+      return await captureSnapshot(page, route, options.config);
+    } finally {
+      await context.close();
+    }
+  };
+  const oldSnapshotFor = (route) => {
+    if (oldBaseUrl !== void 0) return snapshotUrl(joinUrl(oldBaseUrl, route), route);
+    if (oldSnapshotDir !== void 0) {
+      return loadSnapshot(path.join(oldSnapshotDir, routeSnapshotFile(route)));
+    }
+    throw new Error("compareRoutes: provide exactly one of oldBaseUrl or oldSnapshotDir");
+  };
+  try {
+    const perRoute = [];
+    for (const route of options.routes) {
+      const oldSnapshot = await oldSnapshotFor(route);
+      const newSnapshot = await snapshotUrl(joinUrl(options.newBaseUrl, route), route);
+      perRoute.push({ route, findings: diffSnapshots(oldSnapshot, newSnapshot, options.config) });
+    }
+    const { sharedChrome, perRoute: trimmed } = dedupeSharedChrome(perRoute);
+    const routes = trimmed.map(({ route, findings }) => ({
+      route,
+      findings,
+      pass: comparePass(findings)
+    }));
+    const pass = comparePass(sharedChrome) && routes.every((route) => route.pass);
+    return { routes, sharedChrome, pass };
+  } finally {
+    if (ownsBrowser) await browser.close();
+  }
+};
+
 exports.ALL_AXES = ALL_AXES;
+exports.CompareConfig = CompareConfig;
+exports.CompareSnapshot = CompareSnapshot;
 exports.DEFAULT_VIEWPORTS = DEFAULT_VIEWPORTS;
 exports.DESKTOP_VIEWPORT = DESKTOP_VIEWPORT;
+exports.ExpectedAbsentRule = ExpectedAbsentRule;
 exports.MOBILE_VIEWPORT = MOBILE_VIEWPORT;
+exports.REGION_STATES = REGION_STATES;
+exports.Region = Region;
 exports.SEVERITIES = SEVERITIES;
 exports.accessibilityAxis = accessibilityAxis;
 exports.aggregatePass = aggregatePass;
 exports.briefConformanceAxis = briefConformanceAxis;
 exports.capture = capture;
 exports.capturePage = capturePage;
+exports.captureSnapshot = captureSnapshot;
+exports.compareAxis = compareAxis;
+exports.comparePass = comparePass;
+exports.compareRoutes = compareRoutes;
+exports.dedupeSharedChrome = dedupeSharedChrome;
+exports.diffSnapshots = diffSnapshots;
+exports.extractRegions = extractRegions;
+exports.loadSnapshot = loadSnapshot;
 exports.prepareForScreenshot = prepareForScreenshot;
+exports.routeSnapshotFile = routeSnapshotFile;
 exports.runAxes = runAxes;
 exports.runtimeHealthAxis = runtimeHealthAxis;
+exports.saveSnapshot = saveSnapshot;
 exports.serveStatic = serveStatic;
 exports.validate = validate;
 exports.visualBrandAxis = visualBrandAxis;