@keboola/validate-ui 0.1.0

package/dist/index.cjs

@@ -0,0 +1,609 @@
+'use strict';
+
+var playwright = require('playwright');
+var fs = require('fs');
+var promises = require('fs/promises');
+var http = require('http');
+var path = require('path');
+var axe = require('axe-core');
+var zod = require('zod');
+var Anthropic = require('@anthropic-ai/sdk');
+var pixelmatch = require('pixelmatch');
+var pngjs = require('pngjs');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var axe__default = /*#__PURE__*/_interopDefault(axe);
+var Anthropic__default = /*#__PURE__*/_interopDefault(Anthropic);
+var pixelmatch__default = /*#__PURE__*/_interopDefault(pixelmatch);
+
+// src/types.ts
+var SEVERITIES = ["critical", "serious", "moderate", "minor"];
+
+// src/prepare-screenshot.ts
+var disableAnimations = async (page) => {
+  await page.addStyleTag({
+    content: `*, *::before, *::after {
+      animation-duration: 0s !important;
+      animation-delay: 0s !important;
+      transition-duration: 0s !important;
+      transition-delay: 0s !important;
+      caret-color: transparent !important;
+    }`
+  });
+};
+var parkMouseOffElements = async (page) => {
+  await page.mouse.move(0, 0);
+};
+var waitForFonts = async (page) => {
+  await page.evaluate(() => document.fonts.ready.then(() => void 0));
+};
+var prepareForScreenshot = async (page) => {
+  await disableAnimations(page);
+  await parkMouseOffElements(page);
+  await waitForFonts(page);
+};
+
+// src/capture.ts
+var DESKTOP_VIEWPORT = { label: "desktop", width: 1280, height: 800 };
+var MOBILE_VIEWPORT = { label: "mobile", width: 390, height: 844 };
+var DEFAULT_VIEWPORTS = [DESKTOP_VIEWPORT, MOBILE_VIEWPORT];
+var DEFAULT_TIMEOUT_MS = 3e4;
+var attachRecorders = (page) => {
+  const consoleEntries = [];
+  const networkEntries = [];
+  page.on("console", (message) => {
+    consoleEntries.push({
+      type: message.type(),
+      text: message.text(),
+      location: message.location().url || void 0
+    });
+  });
+  page.on("pageerror", (error) => {
+    consoleEntries.push({ type: "pageerror", text: error.message });
+  });
+  page.on("requestfailed", (request) => {
+    networkEntries.push({
+      url: request.url(),
+      method: request.method(),
+      status: 0,
+      failure: request.failure()?.errorText
+    });
+  });
+  page.on("response", (response) => {
+    networkEntries.push({
+      url: response.url(),
+      method: response.request().method(),
+      status: response.status()
+    });
+  });
+  return { console: consoleEntries, network: networkEntries };
+};
+var capturePage = async (page, url, viewport, timeoutMs = DEFAULT_TIMEOUT_MS) => {
+  const recorders = attachRecorders(page);
+  await page.setViewportSize({ width: viewport.width, height: viewport.height });
+  await page.goto(url, { waitUntil: "networkidle", timeout: timeoutMs });
+  await prepareForScreenshot(page);
+  const screenshot = await page.screenshot({ fullPage: true });
+  const dom = await page.content();
+  const renderedText = (await page.evaluate(() => document.body.innerText)).trim();
+  return {
+    url,
+    viewport,
+    screenshot,
+    dom,
+    renderedText,
+    console: recorders.console,
+    network: recorders.network
+  };
+};
+var capture = async (url, options = {}) => {
+  const viewports = options.viewports ?? DEFAULT_VIEWPORTS;
+  const browser = options.browser ?? await playwright.chromium.launch();
+  const ownsBrowser = !options.browser;
+  try {
+    const artifacts = [];
+    for (const viewport of viewports) {
+      const context = await browser.newContext({
+        viewport: { width: viewport.width, height: viewport.height }
+      });
+      const page = await context.newPage();
+      try {
+        artifacts.push(await capturePage(page, url, viewport, options.timeoutMs));
+      } finally {
+        await context.close();
+      }
+    }
+    return artifacts;
+  } finally {
+    if (ownsBrowser) await browser.close();
+  }
+};
+var CONTENT_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".woff2": "font/woff2",
+  ".woff": "font/woff"
+};
+var serveStatic = async (rootDir) => {
+  const indexPath = path.join(rootDir, "index.html");
+  const rootResolved = path.resolve(rootDir);
+  const server = http.createServer((request, response) => {
+    const send = (filePath, status = 200) => {
+      response.writeHead(status, {
+        "content-type": CONTENT_TYPES[path.extname(filePath)] ?? "application/octet-stream"
+      });
+      const stream = fs.createReadStream(filePath);
+      stream.on("error", (error) => {
+        console.error(`serveStatic: failed to read ${filePath}:`, error);
+        if (!response.headersSent) response.writeHead(500);
+        response.end();
+      });
+      stream.pipe(response);
+    };
+    const notFound = () => {
+      response.writeHead(404);
+      response.end();
+    };
+    let rawPath;
+    try {
+      rawPath = decodeURIComponent((request.url ?? "/").split("?")[0] ?? "/");
+    } catch {
+      response.writeHead(400);
+      response.end();
+      return;
+    }
+    const relative = path.normalize(rawPath).replace(/^(\.\.[/\\])+/, "");
+    const candidate = path.join(rootDir, relative);
+    const candidateResolved = path.resolve(candidate);
+    if (candidateResolved !== rootResolved && !candidateResolved.startsWith(rootResolved + path.sep)) {
+      notFound();
+      return;
+    }
+    promises.stat(candidate).then((info) => {
+      send(info.isDirectory() ? indexPath : candidate);
+    }).catch(() => {
+      if (path.extname(candidate) === "") {
+        send(indexPath);
+        return;
+      }
+      notFound();
+    });
+  });
+  await new Promise((resolve2) => server.listen(0, "127.0.0.1", resolve2));
+  const address = server.address();
+  if (address === null || typeof address === "string") {
+    throw new Error("serveStatic: failed to bind an ephemeral port");
+  }
+  return {
+    url: `http://127.0.0.1:${address.port}`,
+    close: () => new Promise((resolve2, reject) => {
+      server.close((error) => error ? reject(error) : resolve2());
+    })
+  };
+};
+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) => {
+  const targets = violation.nodes.map((node) => node.target.join(" ")).filter((target) => target.length > 0).join(", ");
+  const wcag = wcagTag(violation.tags);
+  return {
+    message: `${violation.help || violation.description}${targets ? ` (${targets})` : ""}`,
+    severity: toSeverity(violation.impact),
+    ref: [wcag, violation.id].filter(Boolean).join(" \xB7 ")
+  };
+};
+var notAssessed = (message) => ({
+  axis: "a11y",
+  pass: true,
+  findings: [{ message, severity: "minor" }]
+});
+var accessibilityAxis = {
+  name: "a11y",
+  run: async (context) => {
+    const { page } = context;
+    if (!page) return notAssessed("a11y skipped: no live page provided");
+    await page.addScriptTag({ content: axe__default.default.source });
+    const results = await page.evaluate(() => {
+      const injected = window.axe;
+      return injected ? injected.run(document) : null;
+    });
+    if (results === null) {
+      return notAssessed("a11y not assessed: axe-core failed to inject (page CSP?)");
+    }
+    const findings = results.violations.map(toFinding);
+    const pass = !findings.some(
+      (finding) => finding.severity === "critical" || finding.severity === "serious"
+    );
+    return { axis: "a11y", pass, findings };
+  }
+};
+var textFromMessage = (message) => message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+var makeProvider = (backend, clientOptions) => {
+  const client = new Anthropic__default.default(clientOptions);
+  return {
+    backend,
+    judge: async ({ screenshotBase64, prompt, model }) => {
+      const message = await client.messages.create({
+        model,
+        max_tokens: 1024,
+        messages: [
+          {
+            role: "user",
+            content: [
+              {
+                type: "image",
+                source: { type: "base64", media_type: "image/png", data: screenshotBase64 }
+              },
+              { type: "text", text: prompt }
+            ]
+          }
+        ]
+      });
+      return textFromMessage(message);
+    }
+  };
+};
+var nonEmpty = (value) => value !== void 0 && value !== "";
+var resolveVlmProvider = (env = process.env) => {
+  const baseUrl = env.VALIDATE_UI_LLM_BASE_URL ?? env.ANTHROPIC_BASE_URL;
+  const proxyToken = env.VALIDATE_UI_LLM_TOKEN ?? env.KBC_TOKEN ?? env.ANTHROPIC_API_KEY;
+  if (nonEmpty(baseUrl) && nonEmpty(proxyToken)) {
+    return makeProvider("keboola-llm", { baseURL: baseUrl, apiKey: proxyToken });
+  }
+  if (nonEmpty(env.ANTHROPIC_API_KEY)) {
+    return makeProvider("raw-anthropic", { apiKey: env.ANTHROPIC_API_KEY });
+  }
+  return void 0;
+};
+
+// src/axes/brief-conformance.ts
+var JudgeResult = zod.z.object({
+  matchesBrief: zod.z.boolean(),
+  missingStates: zod.z.array(zod.z.string()),
+  reasons: zod.z.array(zod.z.string())
+});
+var MODEL = process.env.VALIDATE_UI_MODEL ?? "claude-sonnet-4-6";
+var DOM_EXCERPT_LIMIT = 12e3;
+var interpretJudgeResult = (result) => {
+  const findings = [];
+  if (!result.matchesBrief) {
+    findings.push({
+      message: `UI does not match the brief: ${result.reasons.join("; ")}`,
+      severity: "serious"
+    });
+  }
+  for (const state of result.missingStates) {
+    findings.push({ message: `missing state: ${state}`, severity: "moderate" });
+  }
+  const pass = result.matchesBrief && result.missingStates.length === 0;
+  return { axis: "brief-conformance", pass, findings };
+};
+var skip = (message) => ({
+  axis: "brief-conformance",
+  pass: true,
+  findings: [{ message, severity: "minor" }]
+});
+var RUBRIC = [
+  "You are judging whether a rendered UI conforms to the brief it was generated from.",
+  "Assess two things:",
+  "1. matchesBrief \u2014 does the screenshot + DOM implement what the brief describes?",
+  "2. missingStates \u2014 which UI states the brief implies are NOT represented.",
+  '   Use short lowercase labels like "empty", "loading", "error".',
+  "Reply with ONLY a JSON object, no prose, matching exactly:",
+  '{ "matchesBrief": boolean, "missingStates": string[], "reasons": string[] }',
+  "reasons: brief explanations for any mismatch (empty array if it matches)."
+].join("\n");
+var briefConformanceAxis = {
+  name: "brief-conformance",
+  run: async (context) => {
+    const brief = context.brief?.trim();
+    if (brief === void 0 || brief === "") {
+      return skip("no brief provided; conformance not assessed");
+    }
+    const provider = resolveVlmProvider();
+    if (provider === void 0) {
+      return skip(
+        "brief-conformance skipped: no VLM backend configured (set VALIDATE_UI_LLM_BASE_URL + VALIDATE_UI_LLM_TOKEN for the Keboola LLM path, or ANTHROPIC_API_KEY for a raw key)"
+      );
+    }
+    const { artifact } = context;
+    const screenshotBase64 = Buffer.from(artifact.screenshot).toString("base64");
+    const domExcerpt = artifact.dom.slice(0, DOM_EXCERPT_LIMIT);
+    const reply = await provider.judge({
+      model: MODEL,
+      screenshotBase64,
+      prompt: `${RUBRIC}
+
+Brief:
+${brief}
+
+DOM excerpt:
+${domExcerpt}`
+    });
+    try {
+      const parsed = JudgeResult.parse(JSON.parse(reply));
+      return interpretJudgeResult(parsed);
+    } catch (error) {
+      console.error("brief-conformance: failed to parse judge response", error);
+      return {
+        axis: "brief-conformance",
+        pass: false,
+        findings: [{ message: "could not parse judge response", severity: "moderate" }]
+      };
+    }
+  }
+};
+
+// src/axes/runtime-health.ts
+var ERROR_MARKERS = [
+  "something went wrong",
+  "vite-error-overlay",
+  "vite-plugin-checker-error-overlay",
+  "react-error-overlay"
+];
+var pageErrorFindings = (console2) => console2.filter((entry) => entry.type === "pageerror").map((entry) => ({
+  message: `Uncaught page error: ${entry.text}`,
+  severity: "critical",
+  detail: entry.location
+}));
+var RESOURCE_LOAD_ECHO = "failed to load resource";
+var isResourceLoadEcho = (entry) => entry.text.toLowerCase().includes(RESOURCE_LOAD_ECHO);
+var consoleErrorFindings = (console2) => {
+  const seen = /* @__PURE__ */ new Set();
+  const findings = [];
+  for (const entry of console2) {
+    if (entry.type !== "error" || isResourceLoadEcho(entry) || seen.has(entry.text)) continue;
+    seen.add(entry.text);
+    findings.push({
+      message: `Console error: ${entry.text}`,
+      severity: "serious",
+      detail: entry.location
+    });
+  }
+  return findings;
+};
+var toNetworkFinding = (entry) => {
+  if (entry.status === 0) {
+    return {
+      message: `Request failed: ${entry.method} ${entry.url}`,
+      severity: "serious",
+      detail: entry.failure,
+      ref: entry.url
+    };
+  }
+  if (entry.status >= 500) {
+    return {
+      message: `Server error ${entry.status}: ${entry.method} ${entry.url}`,
+      severity: "serious",
+      ref: entry.url
+    };
+  }
+  if (entry.status >= 400) {
+    return {
+      message: `Client error ${entry.status}: ${entry.method} ${entry.url}`,
+      severity: "moderate",
+      ref: entry.url
+    };
+  }
+  return null;
+};
+var SEVERITY_RANK = { critical: 3, serious: 2, moderate: 1, minor: 0 };
+var networkFindings = (network) => {
+  const byUrl = /* @__PURE__ */ new Map();
+  for (const entry of network) {
+    const finding = toNetworkFinding(entry);
+    if (finding === null) continue;
+    const existing = byUrl.get(entry.url);
+    if (existing === void 0 || SEVERITY_RANK[finding.severity] > SEVERITY_RANK[existing.severity]) {
+      byUrl.set(entry.url, finding);
+    }
+  }
+  return [...byUrl.values()];
+};
+var errorMarkerFinding = (dom) => {
+  const lower = dom.toLowerCase();
+  const marker = ERROR_MARKERS.find((m) => lower.includes(m));
+  return marker === void 0 ? null : {
+    message: "Error boundary / error overlay rendered instead of the app",
+    severity: "critical",
+    detail: marker
+  };
+};
+var whiteScreenFinding = (renderedText) => renderedText !== void 0 && renderedText.length === 0 ? { message: "White screen: page rendered no visible text", severity: "critical" } : null;
+var runtimeHealthAxis = {
+  name: "runtime-health",
+  run: (context) => {
+    const { artifact } = context;
+    const findings = [
+      ...pageErrorFindings(artifact.console),
+      ...consoleErrorFindings(artifact.console),
+      ...networkFindings(artifact.network)
+    ];
+    const errorMarker = errorMarkerFinding(artifact.dom);
+    if (errorMarker !== null) findings.push(errorMarker);
+    const whiteScreen = whiteScreenFinding(artifact.renderedText);
+    if (whiteScreen !== null) findings.push(whiteScreen);
+    const fatal = ["critical", "serious"];
+    const pass = !findings.some((f) => fatal.includes(f.severity));
+    return Promise.resolve({ axis: "runtime-health", pass, findings });
+  }
+};
+var DRIFT_THRESHOLD = 0.01;
+var RESKIN_THRESHOLD = 5e-3;
+var DEFAULT_ALT_BRAND = "example-customer";
+var pngMismatchRatio = (a, b) => {
+  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) {
+    return { ratio: 1, sizeMismatch: true };
+  }
+  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
+  });
+  return { ratio: mismatched / total, sizeMismatch: false };
+};
+var baselineFinding = (screenshot, baseline) => {
+  const { ratio, sizeMismatch } = pngMismatchRatio(screenshot, baseline);
+  if (sizeMismatch) {
+    return {
+      message: "screenshot dimensions differ from baseline",
+      severity: "moderate"
+    };
+  }
+  if (ratio > DRIFT_THRESHOLD) {
+    return {
+      message: `visual drift ${(ratio * 100).toFixed(1)}% vs baseline`,
+      severity: "moderate",
+      detail: `${(ratio * 100).toFixed(2)}% of pixels changed`
+    };
+  }
+  return null;
+};
+var altBrandFinding = (screenshot, altScreenshot, brand) => {
+  const { ratio } = pngMismatchRatio(screenshot, altScreenshot);
+  if (ratio < RESKIN_THRESHOLD) {
+    return {
+      message: `chrome did not re-skin under alternate brand '${brand}'`,
+      severity: "serious",
+      detail: `${(ratio * 100).toFixed(2)}% of pixels changed`
+    };
+  }
+  return null;
+};
+var overflowFinding = async (page) => {
+  const overflows = await page.evaluate(
+    () => document.documentElement.scrollWidth > document.documentElement.clientWidth
+  );
+  if (overflows) {
+    return { message: "horizontal layout overflow", severity: "moderate" };
+  }
+  return null;
+};
+var visualBrandAxis = {
+  name: "visual-brand",
+  run: async (context) => {
+    const { artifact, baseline, captureUnderBrand, page } = context;
+    const findings = [];
+    if (baseline !== void 0) {
+      const finding = baselineFinding(artifact.screenshot, baseline);
+      if (finding !== null) findings.push(finding);
+    }
+    if (captureUnderBrand !== void 0) {
+      const altArtifact = await captureUnderBrand(DEFAULT_ALT_BRAND);
+      const finding = altBrandFinding(
+        artifact.screenshot,
+        altArtifact.screenshot,
+        DEFAULT_ALT_BRAND
+      );
+      if (finding !== null) findings.push(finding);
+    }
+    if (page !== void 0) {
+      const finding = await overflowFinding(page);
+      if (finding !== null) findings.push(finding);
+    }
+    const pass = !findings.some((f) => f.severity === "critical" || f.severity === "serious");
+    return { axis: "visual-brand", pass, findings };
+  }
+};
+
+// src/axes/index.ts
+var ALL_AXES = [
+  runtimeHealthAxis,
+  accessibilityAxis,
+  visualBrandAxis,
+  briefConformanceAxis
+];
+
+// src/aggregate.ts
+var runAxes = async (axes, context) => {
+  const verdicts = [];
+  for (const axis of axes) {
+    try {
+      verdicts.push(await axis.run(context));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`validate-ui: axis "${axis.name}" threw:`, error);
+      verdicts.push({
+        axis: axis.name,
+        pass: false,
+        findings: [{ message: `Axis crashed: ${message}`, severity: "critical" }]
+      });
+    }
+  }
+  return verdicts;
+};
+var aggregatePass = (verdicts) => verdicts.every((v) => v.pass);
+var withBrandParam = (url, brand) => {
+  const parsed = new URL(url);
+  parsed.searchParams.set("brand", brand);
+  return parsed.toString();
+};
+var validate = async (options) => {
+  const viewport = options.viewport ?? DESKTOP_VIEWPORT;
+  const axes = options.axes ?? ALL_AXES;
+  const browser = options.browser ?? await playwright.chromium.launch();
+  const ownsBrowser = !options.browser;
+  const context = await browser.newContext({
+    viewport: { width: viewport.width, height: viewport.height }
+  });
+  const page = await context.newPage();
+  try {
+    const artifact = await capturePage(page, options.url, viewport, options.timeoutMs);
+    const axisContext = {
+      artifact,
+      page,
+      browser,
+      brief: options.brief,
+      baseline: options.baseline,
+      captureUnderBrand: async (brand) => {
+        const brandContext = await browser.newContext({
+          viewport: { width: viewport.width, height: viewport.height }
+        });
+        const brandPage = await brandContext.newPage();
+        try {
+          return await capturePage(
+            brandPage,
+            withBrandParam(options.url, brand),
+            viewport,
+            options.timeoutMs
+          );
+        } finally {
+          await brandContext.close();
+        }
+      }
+    };
+    const verdicts = await runAxes(axes, axisContext);
+    return { url: options.url, pass: aggregatePass(verdicts), verdicts };
+  } finally {
+    await context.close();
+    if (ownsBrowser) await browser.close();
+  }
+};
+
+exports.ALL_AXES = ALL_AXES;
+exports.DEFAULT_VIEWPORTS = DEFAULT_VIEWPORTS;
+exports.DESKTOP_VIEWPORT = DESKTOP_VIEWPORT;
+exports.MOBILE_VIEWPORT = MOBILE_VIEWPORT;
+exports.SEVERITIES = SEVERITIES;
+exports.accessibilityAxis = accessibilityAxis;
+exports.aggregatePass = aggregatePass;
+exports.briefConformanceAxis = briefConformanceAxis;
+exports.capture = capture;
+exports.capturePage = capturePage;
+exports.prepareForScreenshot = prepareForScreenshot;
+exports.runAxes = runAxes;
+exports.runtimeHealthAxis = runtimeHealthAxis;
+exports.serveStatic = serveStatic;
+exports.validate = validate;
+exports.visualBrandAxis = visualBrandAxis;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map