@keboola/validate-ui 0.4.0 → 0.5.0

package/AGENTS.md

@@ -0,0 +1,13 @@
+# @keboola/validate-ui — agent guide
+
+Closed-loop validator for generated UI. Static gates check code; this checks the
+rendered result. Reach for it after generating/scaffolding a module, before a PR.
+
+- **Run it:** `validate-ui --url <url> --brief "<the brief>"` (or `--serve <distDir> --route <path>`). Exit 0 = all axes pass. `--json` for machine output.
+- **Programmatic:** `validate({ url, brief })` → `AggregateVerdict`. Building a pipeline? `capture()` for artifacts, `runAxes(axes, ctx)` to run a subset.
+- **Five axes** live one-per-file in `src/axes/` (`runtime-health`, `a11y`, `visual-brand`, `brief-conformance`, `compare`), each implementing the `Axis` contract in `src/types.ts`. Add an axis: implement `{ name, run }`, register it in `src/axes/index.ts`.
+- **Contract boundary:** everything an axis needs is on `AxisContext` (`artifact`, live `page`, `brief`, `baseline`, `captureUnderBrand`, `comparison`, `compareConfig`). Don't reach outside it.
+- **Compare (old-vs-new)** is semantic, not a value multiset — `src/compare/`. Both sides reduce to a serializable `CompareSnapshot` (regions with key/state/values) via `extractRegions`; the pure `diffSnapshots` localizes every delta to a region, suppresses declared `expectedAbsent` deltas (recorded, not dropped), and reports an empty/error `region-degraded` instead of value loss. Multi-route: `validate-ui compare --new <url> (--old <url> | --old-snapshots <dir>) --routes a,b,c [--config f.json]` — `dedupeSharedChrome` collapses a delta seen on ≥2 routes into one finding so shared chrome isn't multiplied. The `compare` axis only activates when `context.comparison` is set, so single-page runs are unaffected.
+- **Do not** depend on `@keboola/e2e-testing` (private) — the screenshot-prep helper is reimplemented in `src/prepare-screenshot.ts`.
+- **Want one pass/fail number + a gate exit code**, not raw findings? Use `@keboola/ui-gen-bench` — `ui-gen-bench eval --serve <dir> --route <path> --brief "…"` boots via this validator, scores the verdict, and exits 0/1. That's the per-generation gate; this package is the validator underneath it.
+- **VLM backend** for `brief-conformance` is chosen in `src/axes/vlm-provider.ts`: Keboola LLM proxy (base URL `VALIDATE_UI_LLM_BASE_URL` → `ANTHROPIC_BASE_URL`; token `VALIDATE_UI_LLM_TOKEN` → `KBC_TOKEN` → `ANTHROPIC_API_KEY` — so kai-agent's SDK-native `ANTHROPIC_BASE_URL` + `ANTHROPIC_API_KEY` pair works, preferred) → raw `ANTHROPIC_API_KEY` (no proxy base URL) → skip. Route new VLM calls through `resolveVlmProvider()`, never `new Anthropic()` directly.

package/dist/cli.cjs

@@ -456,10 +456,85 @@ var compareRoutes = async (options) => {
     if (ownsBrowser) await browser.close();
   }
 };
+
+// src/axes/clipped-text.ts
+var CLIP_TOLERANCE_PX = 2;
+var MAX_REPORTED = 10;
+var findClippedElements = ({
+  tolerance,
+  max
+}) => {
+  const describe = (el) => {
+    const tag = el.tagName.toLowerCase();
+    const label = el.getAttribute("aria-label");
+    if (label) return `${tag}[aria-label="${label}"]`;
+    if (el.id) return `${tag}#${el.id}`;
+    const name = el.getAttribute("name");
+    if (name) return `${tag}[name="${name}"]`;
+    const cls = typeof el.className === "string" && el.className.trim() ? `.${el.className.trim().split(/\s+/).slice(0, 2).join(".")}` : "";
+    return `${tag}${cls}`;
+  };
+  const results = [];
+  const reported = /* @__PURE__ */ new Set();
+  const hasReportedAncestor = (el) => {
+    let parent = el.parentElement;
+    while (parent) {
+      if (reported.has(parent)) return true;
+      parent = parent.parentElement;
+    }
+    return false;
+  };
+  for (const el of document.querySelectorAll("*")) {
+    if (results.length >= max) break;
+    if (hasReportedAncestor(el)) continue;
+    const style = window.getComputedStyle(el);
+    if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") {
+      continue;
+    }
+    if (el.clientWidth <= 1 || el.clientHeight <= 1) continue;
+    const overflowX = style.overflowX;
+    const isFormValue = el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement;
+    const isSingleLineInput = el instanceof HTMLInputElement;
+    if (!isSingleLineInput && overflowX !== "hidden" && overflowX !== "clip") continue;
+    if (!isSingleLineInput && style.textOverflow === "ellipsis") continue;
+    const overflowBy = el.scrollWidth - el.clientWidth;
+    if (overflowBy <= tolerance) continue;
+    const text = isFormValue ? el.value : (el.textContent ?? "").trim();
+    if (!text) continue;
+    reported.add(el);
+    results.push({
+      selector: describe(el),
+      text: text.length > 40 ? `${text.slice(0, 40)}\u2026` : text,
+      visibleWidth: Math.round(el.clientWidth),
+      contentWidth: Math.round(el.scrollWidth),
+      isInput: isFormValue
+    });
+  }
+  return results;
+};
+var toFinding = (clipped) => ({
+  message: `Content is cut off with no way to reveal it (${clipped.selector})`,
+  severity: "serious",
+  detail: `${clipped.isInput ? "Input value" : "Text"} "${clipped.text}" needs ${clipped.contentWidth}px but has ${clipped.visibleWidth}px. Widen the element, or make the truncation explicit with \`text-overflow: ellipsis\`.`
+});
+var clippedTextFindings = async (page) => {
+  try {
+    const clipped = await page.evaluate(findClippedElements, {
+      tolerance: CLIP_TOLERANCE_PX,
+      max: MAX_REPORTED
+    });
+    return clipped.map(toFinding);
+  } catch (error) {
+    console.error("clipped-text: could not inspect the page", error);
+    return [];
+  }
+};
+
+// src/axes/accessibility.ts
 var IMPACTS = ["critical", "serious", "moderate", "minor"];
 var toSeverity = (impact) => impact && IMPACTS.includes(impact) ? impact : "minor";
 var wcagTag = (tags) => tags.find((tag) => tag.startsWith("wcag")) ?? tags[0];
-var toFinding = (violation) => {
+var toFinding2 = (violation) => {
   const targets = violation.nodes.map((node) => node.target.join(" ")).filter((target) => target.length > 0).join(", ");
   const wcag = wcagTag(violation.tags);
   return {
@@ -486,7 +561,7 @@ var accessibilityAxis = {
     if (results === null) {
       return notAssessed("a11y not assessed: axe-core failed to inject (page CSP?)");
     }
-    const findings = results.violations.map(toFinding);
+    const findings = [...results.violations.map(toFinding2), ...await clippedTextFindings(page)];
     const pass = !findings.some(
       (finding) => finding.severity === "critical" || finding.severity === "serious"
     );
@@ -728,8 +803,10 @@ var runtimeHealthAxis = {
 };
 var DRIFT_THRESHOLD = 0.01;
 var RESKIN_THRESHOLD = 5e-3;
+var DRIFT_PIXEL_THRESHOLD = 0.1;
+var RESKIN_PIXEL_THRESHOLD = 0.02;
 var DEFAULT_ALT_BRAND = "example-customer";
-var pngMismatchRatio = (a, b) => {
+var pngMismatchRatio = (a, b, pixelThreshold = DRIFT_PIXEL_THRESHOLD) => {
   const imgA = pngjs.PNG.sync.read(Buffer.from(a));
   const imgB = pngjs.PNG.sync.read(Buffer.from(b));
   if (imgA.width !== imgB.width || imgA.height !== imgB.height) {
@@ -738,7 +815,7 @@ var pngMismatchRatio = (a, b) => {
   const total = imgA.width * imgA.height;
   if (total === 0) return { ratio: 0, sizeMismatch: false };
   const mismatched = pixelmatch__default.default(imgA.data, imgB.data, void 0, imgA.width, imgA.height, {
-    threshold: 0.1
+    threshold: pixelThreshold
   });
   return { ratio: mismatched / total, sizeMismatch: false };
 };
@@ -759,8 +836,16 @@ var baselineFinding = (screenshot, baseline) => {
   }
   return null;
 };
-var altBrandFinding = (screenshot, altScreenshot, brand) => {
-  const { ratio } = pngMismatchRatio(screenshot, altScreenshot);
+var altBrandWasApplied = (altDom, brand) => altDom.includes(`data-brand="${brand}"`);
+var altBrandFinding = (screenshot, altScreenshot, brand, altDom) => {
+  if (!altBrandWasApplied(altDom, brand)) {
+    return {
+      message: `alt-brand re-skin not assessed: the app did not apply '${brand}' from ?brand=`,
+      severity: "minor",
+      detail: "Brand is usually build configuration rather than a runtime switch. To have this axis assess re-skinning, register the alternate brand and resolve the active id from the `brand` query parameter."
+    };
+  }
+  const { ratio } = pngMismatchRatio(screenshot, altScreenshot, RESKIN_PIXEL_THRESHOLD);
   if (ratio < RESKIN_THRESHOLD) {
     return {
       message: `chrome did not re-skin under alternate brand '${brand}'`,
@@ -798,7 +883,8 @@ var visualBrandAxis = {
       const finding = altBrandFinding(
         artifact.screenshot,
         altArtifact.screenshot,
-        DEFAULT_ALT_BRAND
+        DEFAULT_ALT_BRAND,
+        altArtifact.dom
       );
       if (finding !== null) findings.push(finding);
       const altBrand = brandRegistry.brands.find((brand) => brand.id === DEFAULT_ALT_BRAND);