@decocms/parity 0.11.5 → 0.11.8

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.11.8](https://github.com/decocms/parity/compare/v0.11.7...v0.11.8) (2026-06-17)
+
+### Fixed
+
+* **CI on `main` was broken across the 0.11.x patch series.** Three issues converged: (a) the new `postinstall` script in 0.11.7 used CommonJS `require()` but the package is `"type": "module"`, so every fresh `bun install --frozen-lockfile` (including the CI install step) threw `ReferenceError: require is not defined`. (b) Several lint errors carried over from PRs that used `--admin` to bypass CI (template-literal-as-string, assign-in-while-conditions in the new `plp-pagination` check, `delete attrs[name]` flagged by `noDelete`). (c) The earlier `0.11.4` HTML-compaction code in `discover-selectors`/`recover-step` triggered the same `noDelete` rule.
+* **`postinstall.js` renamed to `postinstall.cjs`** so it runs as CommonJS regardless of the package's `"type"`. `package.json` `files` list and the `postinstall` script invocation updated accordingly.
+* **Lint clean across the repo.** `bun run lint` returns zero errors. Loop patterns rewritten from `while ((m = re.exec(s)))` to `for (;;)` + early-break (biome's `noAssignInExpressions`). Two intentional `delete` calls on cheerio attribs get a scoped `biome-ignore` with the rationale (cheerio serializes `undefined`-valued attrs as empty strings; only `delete` actually removes them).
+
+## [0.11.7](https://github.com/decocms/parity/compare/v0.11.6...v0.11.7) (2026-06-17)
+
+### Fixed
+
+* **First-run UX after `npm install -g`.** Two papercuts:
+  1. **Playwright Chromium wasn't auto-installed.** A fresh global install left users with `browserType.launch: Executable doesn't exist at ...` plus a stack trace on the first `parity run`. Now there's a `postinstall` script that runs `npx playwright install chromium` automatically (one-time, ~140 MB). Skippable via `PARITY_SKIP_PLAYWRIGHT_INSTALL=1` for CI / Docker / monorepos that manage browsers separately. Failures during postinstall (offline, corp proxy) are downgraded to a warning so the global install itself still completes.
+  2. **`launchBrowser` now catches the missing-browser error** and prints a single clear instruction (`npx playwright install chromium`) instead of Playwright's ASCII banner + stack trace. Original error is preserved on `.cause` for debugging.
+
+### Known cosmetic warning
+
+The `@anthropic-ai/claude-agent-sdk` peer-dep on `zod@^4.0.0` clashes with parity's `zod@^3.x`. The warning is harmless — npm nests the two versions and everything works. A migration to zod 4 is tracked separately (lots of schema API differences).
+
+## [0.11.6](https://github.com/decocms/parity/compare/v0.11.5...v0.11.6) (2026-06-17)
+
+### Added
+
+* **New `plp-pagination` check.** Tests that `?page=2` and `?page=3` of every captured PLP return 200 AND show different products than page 1. Catches the classic migration regression: the new site silently ignores `?page=N` and returns the first page on every request (or caps pagination). Live tested against bagaggio TanStack — surfaces a real critical bug (`page=2` shows the same 10 products as `page=1`, 100% overlap). Falls back to scraping the home page for a category link when running standalone (`parity check plp-pagination`).
+* **Cross-side count divergence detection.** When prod and cand both serve a paginated PLP but cand's `?page=2` product count differs from prod's by more than 30%, flag as medium-severity (likely sort-order or index pruning regression).
+
 ## [0.11.5](https://github.com/decocms/parity/compare/v0.11.4...v0.11.5) (2026-06-17)
 
 ### Fixed

package/README.md

@@ -26,11 +26,15 @@ Three use cases drive the design:
 ## Quickstart
 
 ```bash
-# Install
+# Install — auto-installs Playwright Chromium on postinstall (~140 MB, one-time)
 npm install -g @decocms/parity
 # or run without install
 npx @decocms/parity run --prod ... --cand ...
 
+# In CI / behind a corp proxy? Skip the auto-install and do it later:
+# PARITY_SKIP_PLAYWRIGHT_INSTALL=1 npm install -g @decocms/parity
+# npx playwright install chromium
+
 # First-time smoke run (~30s, no LLM needed)
 parity run --prod https://oldsite.com --cand https://newsite.example.dev --preset smoke --open
 

package/dist/cli.js

@@ -1790,11 +1790,29 @@ var VIEWPORT_PRESETS = {
   }
 };
 async function launchBrowser(opts = {}) {
-  return await chromium.launch({
-    headless: opts.headless ?? true,
-    slowMo: opts.slowMo ?? 0,
-    args: ["--disable-blink-features=AutomationControlled"]
-  });
+  try {
+    return await chromium.launch({
+      headless: opts.headless ?? true,
+      slowMo: opts.slowMo ?? 0,
+      args: ["--disable-blink-features=AutomationControlled"]
+    });
+  } catch (err) {
+    const msg = err.message ?? "";
+    if (msg.includes("Executable doesn't exist")) {
+      const friendly = new Error([
+        "Playwright's Chromium binary is not installed yet. Run:",
+        "",
+        "    npx playwright install chromium",
+        "",
+        "(one-time, ~140 MB download). Then re-run parity. This usually happens",
+        "after a fresh `npm install -g @decocms/parity`."
+      ].join(`
+`));
+      friendly.cause = err;
+      throw friendly;
+    }
+    throw err;
+  }
 }
 async function newContext(browser, opts) {
   const baseContext = VIEWPORT_PRESETS[opts.viewport];
@@ -8534,6 +8552,232 @@ function hasReservedSpace($img) {
   return false;
 }
 
+// src/checks/plp-pagination.ts
+async function plpPagination(ctx) {
+  const start = Date.now();
+  const issues = [];
+  let prodPlp = pickPlpUrl(ctx.prodFlows);
+  let candPlp = pickPlpUrl(ctx.candFlows);
+  if (!prodPlp && ctx.prodPages.length > 0) {
+    prodPlp = await discoverPlpFromHome(ctx.prodPages[0].url);
+  }
+  if (!candPlp && ctx.candPages.length > 0) {
+    candPlp = await discoverPlpFromHome(ctx.candPages[0].url);
+  }
+  if (!prodPlp && !candPlp) {
+    return {
+      name: "plp-pagination",
+      status: "skipped",
+      severity: "medium",
+      durationMs: Date.now() - start,
+      summary: "no PLP captured by purchase-journey step 2 AND no home page to discover one from — skipping",
+      issues: []
+    };
+  }
+  const data = {};
+  for (const [side, plp] of [
+    ["prod", prodPlp],
+    ["cand", candPlp]
+  ]) {
+    if (!plp)
+      continue;
+    const page1 = await fetchPlpProducts(plp);
+    const page2 = await fetchPlpProducts(withPage(plp, 2));
+    const page3 = await fetchPlpProducts(withPage(plp, 3));
+    data[`${side}_page_counts`] = {
+      page1: { status: page1.status, products: page1.productPaths.length },
+      page2: { status: page2.status, products: page2.productPaths.length },
+      page3: { status: page3.status, products: page3.productPaths.length }
+    };
+    for (const [n, result] of [
+      [2, page2],
+      [3, page3]
+    ]) {
+      if (result.status !== 200) {
+        issues.push({
+          id: `plp-pagination:${side}:page${n}:status-${result.status}`,
+          severity: "high",
+          category: "functional",
+          check: "plp-pagination",
+          summary: `[${side}] page=${n} returned HTTP ${result.status} (expected 200) — pagination breaks under ?page=${n}`,
+          page: withPage(plp, n)
+        });
+      }
+    }
+    if (page1.productPaths.length > 0 && page2.status === 200) {
+      const overlap = setOverlap(page1.productPaths, page2.productPaths);
+      if (overlap > 0.9) {
+        issues.push({
+          id: `plp-pagination:${side}:page2-identical`,
+          severity: "critical",
+          category: "functional",
+          check: "plp-pagination",
+          summary: `[${side}] page=2 shows the same ${page1.productPaths.length} products as page=1 (${(overlap * 100).toFixed(0)}% overlap) — ?page=N is being ignored`,
+          page: withPage(plp, 2),
+          details: `Page 1 first product: ${page1.productPaths[0] ?? "(none)"}
+Page 2 first product: ${page2.productPaths[0] ?? "(none)"}`
+        });
+      }
+    }
+    if (page2.productPaths.length > 0 && page3.status === 200) {
+      const overlap = setOverlap(page2.productPaths, page3.productPaths);
+      if (overlap > 0.9) {
+        issues.push({
+          id: `plp-pagination:${side}:page3-identical`,
+          severity: "critical",
+          category: "functional",
+          check: "plp-pagination",
+          summary: `[${side}] page=3 shows the same products as page=2 (${(overlap * 100).toFixed(0)}% overlap) — pagination capped or broken`,
+          page: withPage(plp, 3)
+        });
+      }
+    }
+  }
+  if (prodPlp && candPlp) {
+    const prodCounts = data.prod_page_counts;
+    const candCounts = data.cand_page_counts;
+    if (prodCounts && candCounts) {
+      const p = prodCounts.page2.products;
+      const c = candCounts.page2.products;
+      if (p > 0 && Math.abs(p - c) / p > 0.3) {
+        issues.push({
+          id: "plp-pagination:cross-side-count-divergence",
+          severity: "medium",
+          category: "functional",
+          check: "plp-pagination",
+          summary: `page=2 product count diverges: prod=${p}, cand=${c} (Δ ${Math.abs(p - c)}, >30%)`
+        });
+      }
+    }
+  }
+  const status = issues.some((i) => i.severity === "critical") ? "fail" : issues.length > 0 ? "fail" : "pass";
+  return {
+    name: "plp-pagination",
+    status,
+    severity: "high",
+    durationMs: Date.now() - start,
+    summary: issues.length === 0 ? "PLP pagination working on both sides (tested page=2 + page=3)" : `${issues.length} pagination issue(s) — see details`,
+    issues,
+    data
+  };
+}
+async function fetchPlpProducts(url) {
+  try {
+    const res = await fetch(url, {
+      headers: {
+        "User-Agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
+      },
+      signal: AbortSignal.timeout(15000)
+    });
+    if (res.status !== 200) {
+      return { status: res.status, productPaths: [] };
+    }
+    const html = await res.text();
+    const paths = new Set;
+    const re = /href="([^"]+\/p(?:\?[^"]*|\/[^"]+|))"/gi;
+    for (;; ) {
+      const m = re.exec(html);
+      if (!m)
+        break;
+      const path = m[1];
+      if (!path)
+        continue;
+      const normalized = path.split("?")[0].replace(/\/$/, "");
+      paths.add(normalized);
+    }
+    const re2 = /href="([^"]+\/products\/[^"]+)"/gi;
+    for (;; ) {
+      const m = re2.exec(html);
+      if (!m)
+        break;
+      const path = m[1];
+      if (path)
+        paths.add(path.split("?")[0].replace(/\/$/, ""));
+    }
+    return { status: 200, productPaths: Array.from(paths) };
+  } catch (err) {
+    return { status: 0, productPaths: [] };
+  }
+}
+function withPage(url, n) {
+  try {
+    const u = new URL(url);
+    u.searchParams.set("page", String(n));
+    return u.toString();
+  } catch {
+    const sep = url.includes("?") ? "&" : "?";
+    return `${url}${sep}page=${n}`;
+  }
+}
+async function discoverPlpFromHome(homeUrl) {
+  try {
+    const res = await fetch(homeUrl, {
+      headers: {
+        "User-Agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
+      },
+      signal: AbortSignal.timeout(15000)
+    });
+    if (!res.ok)
+      return null;
+    const html = await res.text();
+    const candidates = new Set;
+    const re = /href="([^"]+)"/gi;
+    for (;; ) {
+      const m = re.exec(html);
+      if (!m)
+        break;
+      const href = m[1];
+      if (!href)
+        continue;
+      if (/^https?:\/\//.test(href) || href.startsWith("#") || href === "/" || /\/(p|cart|carrinho|checkout|account|conta|login|wishlist|favoritos)(\/|$|\?)/i.test(href) || /\.(jpg|png|webp|css|js|svg|ico|woff)/i.test(href)) {
+        continue;
+      }
+      const segments = href.split("?")[0].split("/").filter(Boolean);
+      if (segments.length === 0 || segments.length > 3)
+        continue;
+      candidates.add(href.split("?")[0]);
+    }
+    const sorted = Array.from(candidates).sort((a, b) => a.length - b.length);
+    const home = new URL(homeUrl);
+    const pick = sorted[0];
+    if (!pick)
+      return null;
+    return new URL(pick, home).toString();
+  } catch {
+    return null;
+  }
+}
+function pickPlpUrl(flows) {
+  for (const fc of flows) {
+    if (fc.flow !== "purchase-journey")
+      continue;
+    const plpStep = fc.steps?.find((s) => s.name === "navigate-plp" && s.status === "ok");
+    if (plpStep?.url)
+      return plpStep.url;
+    const plpPage = fc.pages.find((p) => {
+      try {
+        const u = new URL(p.url);
+        return u.pathname.split("/").filter(Boolean).length <= 2 && !/\/p$|\/products\//.test(u.pathname);
+      } catch {
+        return false;
+      }
+    });
+    if (plpPage)
+      return plpPage.url;
+  }
+  return null;
+}
+function setOverlap(a, b) {
+  if (a.length === 0 || b.length === 0)
+    return 0;
+  const sa = new Set(a);
+  let common = 0;
+  for (const x of b)
+    if (sa.has(x))
+      common++;
+  return common / Math.max(a.length, b.length);
+}
+
 // src/checks/purchase-journey-flow.ts
 var STEP_LABELS3 = {
   "visit-home": "Visitar home",
@@ -10515,7 +10759,8 @@ var ALL_CHECKS = [
   pdpGalleryRelated,
   footerLinksHealth,
   loginFlow,
-  pictureMissingDims
+  pictureMissingDims,
+  plpPagination
 ];
 var ALL_CHECKS_BY_NAME = {
   "http-status-parity": httpStatusParity,
@@ -10542,7 +10787,8 @@ var ALL_CHECKS_BY_NAME = {
   "pdp-gallery-related": pdpGalleryRelated,
   "footer-links-health": footerLinksHealth,
   "login-flow": loginFlow,
-  "picture-missing-dims": pictureMissingDims
+  "picture-missing-dims": pictureMissingDims,
+  "plp-pagination": plpPagination
 };
 var FLOW_DEPENDENT_CHECKS = new Set([
   "purchase-journey-flow",
@@ -11262,9 +11508,12 @@ function compactHtmlForRecovery(html, maxChars = 12000) {
       if (attrs.class) {
         const tokens = attrs.class.split(/\s+/).filter(Boolean);
         const kept = tokens.filter((t) => isSemanticClassToken(t));
-        attrs.class = kept.join(" ");
-        if (!attrs.class)
+        const joined = kept.join(" ");
+        if (joined) {
+          attrs.class = joined;
+        } else {
           delete attrs.class;
+        }
       }
     });
     const allowed = $("header, nav, main, footer, dialog, [role='dialog'], form, button, a, input, [data-buy-button], [data-checkout], [data-minicart], [data-product-list], [role='button'], [aria-label]").map((_, el) => $.html(el)).get().join(`
@@ -11551,9 +11800,12 @@ function compactHtmlForSelectors(html, maxChars = 30000) {
       if (attrs.class) {
         const tokens = attrs.class.split(/\s+/).filter(Boolean);
         const kept = tokens.filter((t) => isSemanticClass(t));
-        attrs.class = kept.join(" ");
-        if (!attrs.class)
+        const joined2 = kept.join(" ");
+        if (joined2) {
+          attrs.class = joined2;
+        } else {
           delete attrs.class;
+        }
       }
     });
     const sections = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/parity",
-  "version": "0.11.5",
+  "version": "0.11.8",
   "description": "E2E parity validator for site migrations. Compares prod vs cand and reports UI, functional, SEO, visual, and Web Vitals deltas with an LLM-ranked HTML report.",
   "type": "module",
   "license": "MIT",
@@ -32,7 +32,7 @@
   "bin": {
     "parity": "dist/cli.js"
   },
-  "files": ["dist", "README.md", "AGENTS.md", "CHANGELOG.md", "LICENSE"],
+  "files": ["dist", "scripts/postinstall.cjs", "README.md", "AGENTS.md", "CHANGELOG.md", "LICENSE"],
   "scripts": {
     "dev": "bun run --hot src/cli.ts",
     "build": "bun build src/cli.ts --target=node --outfile=dist/cli.js --packages=external && bun run scripts/postbuild.ts",
@@ -44,7 +44,8 @@
     "deadcode": "knip",
     "lint": "biome lint .",
     "fmt": "biome format --write .",
-    "prepublishOnly": "bun run check && bun run build"
+    "prepublishOnly": "bun run check && bun run build",
+    "postinstall": "node scripts/postinstall.cjs"
   },
   "engines": {
     "node": ">=20",

package/scripts/postinstall.cjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Best-effort Playwright Chromium install on first `npm install` of
+ * `@decocms/parity`. Skipped when:
+ *   - `PARITY_SKIP_PLAYWRIGHT_INSTALL=1` is set (CI / Docker / monorepos
+ *     that manage the browser separately).
+ *   - The binary is already present.
+ *
+ * Failures are downgraded to a warning so a `npm install -g` that
+ * happens to be offline / behind a corp proxy doesn't block the whole
+ * install. The runtime path in `engine/browser.ts:launchBrowser` catches
+ * the missing-browser case and tells the user exactly what to run.
+ */
+
+if (process.env.PARITY_SKIP_PLAYWRIGHT_INSTALL === "1") {
+  console.log("[parity] PARITY_SKIP_PLAYWRIGHT_INSTALL=1 set — skipping Chromium install");
+  process.exit(0);
+}
+
+const { spawnSync } = require("node:child_process");
+
+// Probe Playwright to find out if Chromium is already extracted. The cheap
+// way: try to resolve the binary via `npx playwright install --dry-run`.
+// `--dry-run` exits 0 when everything is already installed and non-zero
+// when downloads are needed. We don't actually rely on the exit code; we
+// always attempt `install chromium` (idempotent) and let Playwright print
+// "already up to date" when there's nothing to do.
+try {
+  console.log("[parity] Installing Playwright Chromium (one-time, ~140 MB)…");
+  const result = spawnSync("npx", ["--yes", "playwright", "install", "chromium"], {
+    stdio: "inherit",
+    env: process.env,
+  });
+  if (result.status === 0) {
+    console.log("[parity] Chromium ready.");
+  } else {
+    console.log(
+      "[parity] Chromium install returned a non-zero exit. " +
+        "If `parity run` later fails with 'Executable doesn't exist', " +
+        "run `npx playwright install chromium` manually.",
+    );
+  }
+} catch (err) {
+  const reason = err?.message ?? "unknown error";
+  console.log(
+    `[parity] Playwright install skipped (${reason}). Run \`npx playwright install chromium\` before your first \`parity run\`.`,
+  );
+}