@decocms/parity 0.35.28 → 0.35.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -163,6 +163,7 @@ Hard caps already in place:
163
163
  - **A page that was never captured (status 0) is not a status divergence.** `http-status-parity` files one inconclusive `http-status:not-captured:<page>` finding, the run gets a `cand-pages-not-captured` (or `prod-…`) caveat listing the paths, and the check is `warn`. A real 404/500 stays critical. Re-run against a warm server before reading the score.
164
164
  - **`[hydration]` console errors are React's own hydration messages only.** A section that threw and was caught by an error boundary is `[section-crash]` (same severity); its `file:line` positions come from the candidate's build at capture time and may be stale against the working tree.
165
165
  - **`Issue.page` is the `path::viewport` key**, never a URL; the URL is in `details`.
166
+ - **A local dev candidate (`--cand http://localhost:…`) is cold on its first request to each route.** A run started right after the server came up, or after adding routes, can time out on pages the server would answer in milliseconds once requested. `parity run` primes the candidate's pages one at a time and retries a never-answered capture once; if it still prints "warm-up/priming loads never answered" or a `cand-cold` caveat, the server was not ready: request the routes yourself (or wait) and re-run, and do not read the "status divergente: cand=0" findings as defects. Flows' own PLP/PDP navigations are not primed. `--no-prime-cand` turns priming off.
166
167
  - **`parity run` doesn't apply schema changes from old runs** — if you change `src/types/schema.ts`, old `report.json` files won't parse. Delete `parity-output/` or re-run.
167
168
 
168
169
  ## Files agents should and should not write
package/CHANGELOG.md CHANGED
@@ -50,8 +50,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
50
50
  selection, empty golden, `--pages` outside the golden) exits 2 before any browser work. Recordings
51
51
  now also carry the detected `platform` (optional; older recordings still load). See
52
52
  `docs/cli.md`.
53
-
54
- ### Fixed
53
+ * **`parity run` primes a local dev candidate** (`--cand` on localhost) before each capture pass:
54
+ every distinct candidate URL is requested once, sequentially, in a real page (90s cap, nothing
55
+ measured), so a dev server's first-request compile no longer happens under 4 concurrent
56
+ captures. A capture that still never answered (status 0) is retried once, sequentially, after
57
+ the pass (`PageCapture.retried`). When most warm-up/priming loads fail, the run warns at once and
58
+ adds a `cand-cold` run caveat. The priming cost is its own `prime-cand` timing line;
59
+ `report.json.candPrime` is new and additive. `--no-prime-cand` turns priming off. Remote
60
+ candidates and prod behave as before. See `docs/cli.md`.
61
+
62
+ ### Fixed
63
+
64
+ * **The compared / passed counts agree across checks again.** Three changes that each assumed
65
+ the others were already in: a pair a not-captured guard (`withCapturedPairs`) withholds now
66
+ lands in the check's `inconclusive` count (a check that does not count stays uncounted);
67
+ `visual-regression-keyframes` counts a height-differs page as compared-and-not-passed and every
68
+ other `failed` page as inconclusive, even when a live `visual:sections` finding names it, so the
69
+ check agrees with the "N not compared" split line; and the page-height severity scale moved
70
+ into `TOLERANCES.visual` (`heightLowMaxPx`, `heightLowMaxPct`, `heightHighMinPct`). No tolerance
71
+ value changed.
55
72
 
56
73
  * **A candidate page that was never captured is no longer a status divergence.**
57
74
  A capture that recorded no HTTP answer (status 0: timeout, refused connection)
package/dist/cli.js CHANGED
@@ -76786,6 +76786,24 @@ var TOLERANCES = {
76786
76786
  unit: "px",
76787
76787
  basis: "assumed",
76788
76788
  note: "Minimum connected-component size to count as a hotspot; drops 1-2px anti-aliasing specks. About a small icon."
76789
+ },
76790
+ heightLowMaxPx: {
76791
+ value: 50,
76792
+ unit: "px",
76793
+ basis: "assumed",
76794
+ note: "A page-height difference under this and under heightLowMaxPct is `low` (margin / rounding)."
76795
+ },
76796
+ heightLowMaxPct: {
76797
+ value: 2,
76798
+ unit: "% of prod height",
76799
+ basis: "assumed",
76800
+ note: "Paired with heightLowMaxPx so a short page is not 'low' at 49 px."
76801
+ },
76802
+ heightHighMinPct: {
76803
+ value: 10,
76804
+ unit: "% of prod height",
76805
+ basis: "assumed",
76806
+ note: "A page-height difference at or above this is `high`: a block of content is missing or extra."
76789
76807
  }
76790
76808
  },
76791
76809
  geometry: {
@@ -79374,11 +79392,11 @@ function withCapturedPairs(check) {
79374
79392
  summary: `${uncapturedSummary(pair.key, sides)} — not compared by ${result.name}`,
79375
79393
  details: "The capture recorded no HTTP answer (status 0), so this check had nothing to judge on that side. Not a finding about the page: re-run it against a warm server."
79376
79394
  }));
79377
- return {
79395
+ return addWithheld({
79378
79396
  ...result,
79379
79397
  status: result.status === "pass" ? "warn" : result.status,
79380
79398
  issues: [...result.issues, ...issues]
79381
- };
79399
+ }, missing.length);
79382
79400
  };
79383
79401
  Object.defineProperty(guarded, "name", { value: check.name });
79384
79402
  return guarded;
@@ -89738,32 +89756,12 @@ function everyRegionImperceptible(heatmapPath, prod, cand, diffDir, prefix, view
89738
89756
  });
89739
89757
  return explainHotspots(all.hotspots, prod.side, cand.side, artifactPaths(diffDir, prefix, viewport), prod.boxTree, cand.boxTree).every(isImperceptible);
89740
89758
  }
89741
- var HEIGHT_DIFF_TOLERANCE = {
89742
- lowMaxPx: {
89743
- value: 50,
89744
- unit: "px",
89745
- basis: "assumed",
89746
- note: "under this and under lowMaxPct: margin / rounding"
89747
- },
89748
- lowMaxPct: {
89749
- value: 2,
89750
- unit: "% of prod height",
89751
- basis: "assumed",
89752
- note: "paired with lowMaxPx so a short page is not 'low' at 49 px"
89753
- },
89754
- highMinPct: {
89755
- value: 10,
89756
- unit: "% of prod height",
89757
- basis: "assumed",
89758
- note: "at or above: a block of content is missing or extra"
89759
- }
89760
- };
89761
89759
  function heightDiffSeverity(prodH, candH) {
89762
89760
  const delta = Math.abs(candH - prodH);
89763
89761
  const pct = prodH > 0 ? delta / prodH * 100 : 100;
89764
- if (pct >= HEIGHT_DIFF_TOLERANCE.highMinPct.value)
89762
+ if (pct >= TOLERANCES.visual.heightHighMinPct.value)
89765
89763
  return "high";
89766
- if (delta < HEIGHT_DIFF_TOLERANCE.lowMaxPx.value && pct < HEIGHT_DIFF_TOLERANCE.lowMaxPct.value) {
89764
+ if (delta < TOLERANCES.visual.heightLowMaxPx.value && pct < TOLERANCES.visual.heightLowMaxPct.value) {
89767
89765
  return "low";
89768
89766
  }
89769
89767
  return "medium";
@@ -90056,6 +90054,9 @@ Usually missing from registerSections() in src/setup.ts, or the CMS is not resol
90056
90054
  summary: "Visual pass ran but no page pair was captured on both sides — nothing was compared"
90057
90055
  });
90058
90056
  }
90057
+ const measured = (r) => r.verdict !== "failed" || r.notComparedKind === "height-differs";
90058
+ const notMeasured = results.filter((r) => !measured(r)).map((r) => r.pageKey);
90059
+ const notMeasuredSet = new Set(notMeasured);
90059
90060
  const summary = {
90060
90061
  results,
90061
90062
  pagesChecked: results.length,
@@ -90076,9 +90077,9 @@ Usually missing from registerSections() in src/setup.ts, or the CMS is not resol
90076
90077
  issues,
90077
90078
  ...unitCounts({
90078
90079
  unit: "page-pair",
90079
- judged: results.filter((r) => r.verdict !== "failed").map((r) => r.pageKey),
90080
- unjudged: results.filter((r) => r.verdict === "failed").map((r) => r.pageKey),
90081
- issues,
90080
+ judged: results.filter(measured).map((r) => r.pageKey),
90081
+ unjudged: notMeasured,
90082
+ issues: issues.filter((i) => i.inconclusive || i.accepted || !i.page || !notMeasuredSet.has(i.page)),
90082
90083
  informational: (i) => i.id.startsWith("visual:heatmap:") || i.id.startsWith("visual:sections-expected:")
90083
90084
  }),
90084
90085
  data: { visualDiff: summary }
@@ -90645,7 +90646,8 @@ var PageCapture = z2.object({
90645
90646
  xRobotsTag: z2.string().nullable().optional(),
90646
90647
  pairKey: z2.string().optional(),
90647
90648
  pass: z2.enum(["extra", "visual"]).optional(),
90648
- variant: VariantFingerprint.optional()
90649
+ variant: VariantFingerprint.optional(),
90650
+ retried: z2.boolean().optional()
90649
90651
  });
90650
90652
  var StepCapture = z2.object({
90651
90653
  step: z2.number(),
@@ -91022,6 +91024,13 @@ var Run = z2.object({
91022
91024
  failed: z2.number().optional(),
91023
91025
  totalMs: z2.number().optional()
91024
91026
  }).optional(),
91027
+ candPrime: z2.object({
91028
+ attempted: z2.number(),
91029
+ failedUrls: z2.array(z2.string()),
91030
+ totalMs: z2.number(),
91031
+ retried: z2.number(),
91032
+ recovered: z2.number()
91033
+ }).optional(),
91025
91034
  selectionReason: z2.string().optional(),
91026
91035
  moduleVerdicts: z2.array(ModuleVerdict).optional(),
91027
91036
  acceptedFindings: z2.object({
@@ -118593,6 +118602,76 @@ function formatSecs(ms) {
118593
118602
  return `${min}m${sec.toString().padStart(2, "0")}s`;
118594
118603
  }
118595
118604
 
118605
+ // src/engine/cand-prime.ts
118606
+ var PRIME_TIMEOUT_MS = 90000;
118607
+ var PRIME_LOAD_MS = 1e4;
118608
+ function planCandPrime(candBase, paths, alreadyPrimed) {
118609
+ if (!isLocalhost(candBase))
118610
+ return [];
118611
+ const out = [];
118612
+ const seen = new Set(alreadyPrimed);
118613
+ for (const p of paths) {
118614
+ let url;
118615
+ try {
118616
+ url = new URL(p, candBase).toString();
118617
+ } catch {
118618
+ continue;
118619
+ }
118620
+ if (seen.has(url))
118621
+ continue;
118622
+ seen.add(url);
118623
+ out.push(url);
118624
+ }
118625
+ return out;
118626
+ }
118627
+ async function primeSequentially(urls, primed, prime) {
118628
+ const start = Date.now();
118629
+ const failed = [];
118630
+ for (const url of urls) {
118631
+ primed.add(url);
118632
+ const ok = await prime(url).catch(() => false);
118633
+ if (!ok)
118634
+ failed.push(url);
118635
+ }
118636
+ return { attempted: urls.length, failed, totalMs: Date.now() - start };
118637
+ }
118638
+ async function primeCandUrls(browser, urls, primed, ctxOpts) {
118639
+ if (urls.length === 0)
118640
+ return { attempted: 0, failed: [], totalMs: 0 };
118641
+ const ctx = await newContext(browser, { cohortCookieValue: "control", ...ctxOpts });
118642
+ try {
118643
+ return await primeSequentially(urls, primed, async (url) => {
118644
+ const page = await ctx.newPage();
118645
+ try {
118646
+ await page.goto(url, { waitUntil: "domcontentloaded", timeout: PRIME_TIMEOUT_MS });
118647
+ await page.waitForLoadState("load", { timeout: PRIME_LOAD_MS }).catch(() => {
118648
+ return;
118649
+ });
118650
+ return true;
118651
+ } finally {
118652
+ await page.close().catch(() => {
118653
+ return;
118654
+ });
118655
+ }
118656
+ });
118657
+ } finally {
118658
+ await ctx.close().catch(() => {
118659
+ return;
118660
+ });
118661
+ }
118662
+ }
118663
+ function needsRetry(side, candUrl, cap) {
118664
+ if (side !== "cand" || !isLocalhost(candUrl))
118665
+ return false;
118666
+ if (!cap)
118667
+ return true;
118668
+ return cap.status === 0 && !cap.retried;
118669
+ }
118670
+ var COLD_SHARE = 0.25;
118671
+ function isColdCandidate(loads) {
118672
+ return loads.failed >= 2 && loads.failed / loads.total > COLD_SHARE;
118673
+ }
118674
+
118596
118675
  // src/engine/run-context.ts
118597
118676
  function detectRunCaveats(input) {
118598
118677
  const out = [];
@@ -118604,6 +118683,15 @@ function detectRunCaveats(input) {
118604
118683
  detail: "Vitals, cache e bundle de um dev server não são representativos: sem minificação, sem cache de edge, HMR aberto. Reconfirme num build de produção antes de tratar qualquer número de performance como resultado."
118605
118684
  });
118606
118685
  }
118686
+ if (input.warmLoads && isColdCandidate(input.warmLoads)) {
118687
+ const { failed, total } = input.warmLoads;
118688
+ out.push({
118689
+ id: "cand-cold",
118690
+ level: "warn",
118691
+ summary: `${failed} of ${total} warm-up/priming loads never answered — the server looked cold or unhealthy`,
118692
+ detail: "Pages that did not answer are missing from this run or were measured cold, so counts, vitals and status findings of the affected routes are not a fair comparison. Wait for the candidate to finish starting, or request each route once, then re-run."
118693
+ });
118694
+ }
118607
118695
  if (isLocalhost(input.prodUrl)) {
118608
118696
  out.push({
118609
118697
  id: "prod-dev-server",
@@ -119327,6 +119415,65 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119327
119415
  } else if (warmPlan.skippedReason === "bypass-cache") {
119328
119416
  console.log(chalk34.dim(" vitals warm-up: off (--bypass-cache measures cold on purpose)"));
119329
119417
  }
119418
+ const primeEnabled = opts.primeCand !== false && isLocalhost(opts.cand);
119419
+ const primed = new Set;
119420
+ const primeAcc = { attempted: 0, failed: [], totalMs: 0 };
119421
+ const candRetry = { retried: 0, recovered: 0 };
119422
+ const retrying = new Set;
119423
+ const warmLoadsNow = () => ({
119424
+ total: primeAcc.attempted + (vitalsWarm?.stats.loads ?? 0),
119425
+ failed: primeAcc.failed.length + (vitalsWarm?.stats.failed ?? 0)
119426
+ });
119427
+ let coldWarned = false;
119428
+ const warnIfCold = () => {
119429
+ const loads = warmLoadsNow();
119430
+ if (coldWarned || !isColdCandidate(loads))
119431
+ return;
119432
+ coldWarned = true;
119433
+ console.log(chalk34.yellow(` ! ${loads.failed} of ${loads.total} warm-up/priming loads never answered — the server looks cold or unhealthy. Captures that follow will likely time out. Wait for it to finish starting, or request each route once, then re-run.`));
119434
+ };
119435
+ const primeCand = async (candPaths) => {
119436
+ if (!primeEnabled || !browser)
119437
+ return;
119438
+ const urls = planCandPrime(opts.cand, candPaths, primed);
119439
+ if (urls.length === 0)
119440
+ return;
119441
+ console.log(chalk34.dim(` priming cand: ${urls.length} URL(s), one at a time (--no-prime-cand to skip)`));
119442
+ const r = await primeCandUrls(browser, urls, primed, {
119443
+ viewport: viewports[0],
119444
+ cookies: pins.cand.cookies,
119445
+ headers: pins.cand.headers
119446
+ });
119447
+ primeAcc.attempted += r.attempted;
119448
+ primeAcc.failed.push(...r.failed);
119449
+ primeAcc.totalMs += r.totalMs;
119450
+ phaseStart += r.totalMs;
119451
+ warnIfCold();
119452
+ };
119453
+ const retryColdCand = async (pass, passTasks, runTask) => {
119454
+ const capOf = (t) => {
119455
+ const url = new URL(t.path, opts.cand).toString();
119456
+ return allPageCaptures.find((c) => c.pass === pass && c.side === "cand" && c.viewport === t.viewport && c.url === url);
119457
+ };
119458
+ for (const t of passTasks.filter((x) => needsRetry(x.side, opts.cand, capOf(x)))) {
119459
+ const old = capOf(t);
119460
+ const before = allPageCaptures.length;
119461
+ retrying.add(t);
119462
+ candRetry.retried++;
119463
+ await runTask(t);
119464
+ if (allPageCaptures.length === before)
119465
+ continue;
119466
+ const fresh = allPageCaptures[allPageCaptures.length - 1];
119467
+ if (fresh.status > 0)
119468
+ candRetry.recovered++;
119469
+ if (old) {
119470
+ allPageCaptures.splice(allPageCaptures.indexOf(old), 1);
119471
+ const fi = allFlowCaptures.findIndex((f) => f.pages.length === 1 && f.pages[0] === old);
119472
+ if (fi >= 0)
119473
+ allFlowCaptures.splice(fi, 1);
119474
+ }
119475
+ }
119476
+ };
119330
119477
  const timeoutMinutes = Math.max(1, Math.floor(opts.timeout ?? 30));
119331
119478
  const globalTimeoutTimer = setTimeout(() => {
119332
119479
  shutdown(`timeout ${timeoutMinutes}min`);
@@ -119452,8 +119599,10 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119452
119599
  }
119453
119600
  };
119454
119601
  const maxViewportConcurrency = Math.max(1, opts.maxViewportConcurrency ?? 2);
119602
+ await primeCand(["/"]);
119455
119603
  await runWithConcurrency2(viewports, maxViewportConcurrency, runOneViewport);
119456
119604
  stampPhase("collect");
119605
+ warnIfCold();
119457
119606
  spinner.succeed("Coleta concluída");
119458
119607
  if (isLlmAvailable()) {
119459
119608
  const prodPdp = findPdpCapture(allFlowCaptures, "prod");
@@ -119528,7 +119677,8 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119528
119677
  }
119529
119678
  }
119530
119679
  let done = 0;
119531
- await runWithConcurrency2(tasks, 4, async (task) => {
119680
+ await primeCand(extraPaths);
119681
+ const runTask = async (task) => {
119532
119682
  const baseUrl = task.side === "prod" ? opts.prod : opts.cand;
119533
119683
  const fullUrl = new URL(task.path, baseUrl).toString();
119534
119684
  const targetIsDevServer = isLocalhost(baseUrl);
@@ -119572,6 +119722,8 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119572
119722
  return;
119573
119723
  }
119574
119724
  cap.pass = "extra";
119725
+ if (retrying.has(task))
119726
+ cap.retried = true;
119575
119727
  allPageCaptures.push(cap);
119576
119728
  allFlowCaptures.push({
119577
119729
  flow: "homepage",
@@ -119593,7 +119745,9 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119593
119745
  vitalsHb.bump();
119594
119746
  extraSpinner.text = `[vitals extras] ${done}/${tasks.length} (último: ${task.path})`;
119595
119747
  }
119596
- });
119748
+ };
119749
+ await runWithConcurrency2(tasks, 4, runTask);
119750
+ await retryColdCand("extra", tasks, runTask);
119597
119751
  vitalsHb.stop();
119598
119752
  extraSpinner.succeed(`+${extraPaths.length} página(s) com vitals`);
119599
119753
  } else {
@@ -119605,6 +119759,7 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119605
119759
  extraSpinner.warn(`vitals extras pulado: ${err.message}`);
119606
119760
  } finally {
119607
119761
  stampPhase("vitals-pages");
119762
+ warnIfCold();
119608
119763
  }
119609
119764
  }
119610
119765
  const explicitPaths = resolveExplicitPages(opts.pagesFile, opts.pages);
@@ -119638,7 +119793,8 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119638
119793
  } else {
119639
119794
  visualSpinner.text = `Visual diff: capturando ${tasks.length} screenshot(s) (${visualPaths.length} páginas × ${viewports.length} viewport(s) × 2 sides)…`;
119640
119795
  let done = 0;
119641
- await runWithConcurrency2(tasks, 4, async (task) => {
119796
+ await primeCand(visualPaths.map((p) => p.cand));
119797
+ const runTask = async (task) => {
119642
119798
  const baseUrl = task.side === "prod" ? opts.prod : opts.cand;
119643
119799
  const fullUrl = new URL(task.path, baseUrl).toString();
119644
119800
  const safePath = task.path.replace(/[/?&=]+/g, "_") || "_root";
@@ -119667,6 +119823,8 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119667
119823
  pairKey: task.pairKey
119668
119824
  });
119669
119825
  cap.pass = "visual";
119826
+ if (retrying.has(task))
119827
+ cap.retried = true;
119670
119828
  allPageCaptures.push(cap);
119671
119829
  if (existsSync31(screenshotPath)) {
119672
119830
  visualProbes.set(screenshotPath, await probeFullPage(page, screenshotPath, task.side === "prod" ? screenshotPath.replace(/\.png$/, "-repeat.png") : null));
@@ -119684,7 +119842,9 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119684
119842
  visualHb.bump();
119685
119843
  visualSpinner.text = `[visual] ${done}/${tasks.length} (último: ${task.path})`;
119686
119844
  }
119687
- });
119845
+ };
119846
+ await runWithConcurrency2(tasks, 4, runTask);
119847
+ await retryColdCand("visual", tasks, runTask);
119688
119848
  visualHb.stop();
119689
119849
  visualSpinner.succeed(`Visual diff: ${tasks.length} screenshot(s) capturado(s)`);
119690
119850
  }
@@ -119699,6 +119859,14 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119699
119859
  const w = vitalsWarm.stats;
119700
119860
  console.log(chalk34.dim(` vitals warm-up: ${w.pages} page(s), ${w.loads} load(s)${w.failed ? `, ${w.failed} failed` : ""}, +${(w.totalMs / 1000).toFixed(1)}s summed across captures`));
119701
119861
  }
119862
+ warnIfCold();
119863
+ if (primeAcc.attempted > 0) {
119864
+ const f = primeAcc.failed.map((u) => new URL(u).pathname);
119865
+ console.log(chalk34.dim(` cand priming: ${primeAcc.attempted} URL(s), ${(primeAcc.totalMs / 1000).toFixed(1)}s${f.length ? `, ${f.length} never answered: ${f.slice(0, 5).join(", ")}${f.length > 5 ? "…" : ""}` : ""}`));
119866
+ }
119867
+ if (candRetry.retried > 0) {
119868
+ console.log(chalk34.dim(` cand retry: ${candRetry.retried} capture(s) retried after not answering, ${candRetry.recovered} recovered`));
119869
+ }
119702
119870
  if (goldenRec && goldenPlan) {
119703
119871
  const merged = mergeGoldenContext(goldenRec, goldenPlan, {
119704
119872
  pages: allPageCaptures,
@@ -119832,6 +120000,8 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119832
120000
  const visualDiff = visualCheck?.data?.visualDiff;
119833
120001
  const seoCheck = checks.find((c) => c.name === "seo-deep-audit");
119834
120002
  const seo = seoCheck?.data?.seo;
120003
+ if (primeAcc.totalMs > 0)
120004
+ timings.push("prime-cand", primeAcc.totalMs);
119835
120005
  const runTimings = timings.finalize();
119836
120006
  const run = {
119837
120007
  schemaVersion: "0.1",
@@ -119855,6 +120025,12 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119855
120025
  baseline: baselineSection,
119856
120026
  timings: runTimings,
119857
120027
  vitalsWarmup: vitalsWarm ? { enabled: true, loadsPerPage: vitalsWarm.loads, ...vitalsWarm.stats } : { enabled: false, skippedReason: warmPlan.skippedReason },
120028
+ candPrime: primeAcc.attempted > 0 || candRetry.retried > 0 ? {
120029
+ attempted: primeAcc.attempted,
120030
+ failedUrls: primeAcc.failed,
120031
+ totalMs: primeAcc.totalMs,
120032
+ ...candRetry
120033
+ } : undefined,
119858
120034
  selectionReason: opts.why,
119859
120035
  moduleVerdicts: moduleVerdicts.length > 0 ? moduleVerdicts : undefined,
119860
120036
  acceptedFindings: acceptance.accepted > 0 || acceptance.stale.length > 0 ? {
@@ -119870,7 +120046,8 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119870
120046
  verdict,
119871
120047
  llmEnabled: llmStillAvailable,
119872
120048
  candIsProduction: opts.candIsProduction,
119873
- prodPinned: !isEmptyPin(pins.prod)
120049
+ prodPinned: !isEmptyPin(pins.prod),
120050
+ warmLoads: warmLoadsNow()
119874
120051
  })),
119875
120052
  pinned: isEmptyPin(pins.prod) && isEmptyPin(pins.cand) ? undefined : { prod: pinNames(pins.prod), cand: pinNames(pins.cand) },
119876
120053
  pagePairs,
@@ -125231,7 +125408,7 @@ program.command("run").description([
125231
125408
  " visual-pages=5, auto-selectors=ON (if LLM), learn=ON, visual-diff=ON,",
125232
125409
  " warmup=OFF, vitals warm=ON, bypass-cache=OFF, fail-on=critical (exit 1 if hit)."
125233
125410
  ].join(`
125234
- `)).option("--prod <url>", "Production URL (source of truth, e.g. Fresh site). Omit for a single site — the run will point you to `parity e2e` (issue #141).").requiredOption("--cand <url>", "Candidate URL (migrated site, e.g. TanStack)").option("--preset <name>", "Bundle of defaults: smoke (fast, ~30s, no LLM) | full (deep audit) | ci (CI-tuned)").option("--flows <list>", "Comma-separated flows: homepage,plp,pdp,purchase-journey", "purchase-journey").option("--viewports <list>", "Comma-separated viewports: mobile,desktop", "mobile,desktop").option("--cep <cep>", "CEP for shipping calculation", "01310-100").option("--prod-cookie <name=value>", "Cookie set on every prod browser context and plain request; repeatable. Pins prod to one A/B variant (e.g. a Fresh-vs-TanStack bucket cookie) so the run does not compare whichever build each fresh context drew. Values are redacted in logs and report.json.", collectCookie, []).option("--cand-cookie <name=value>", "Same as --prod-cookie, for the candidate side", collectCookie, []).option("--prod-header <Name: value>", "Request header sent on every prod request (all origins — no credentials); repeatable. The header twin of --prod-cookie. Values are redacted in logs and report.json.", collectHeader, []).option("--cand-header <Name: value>", "Same as --prod-header, for the candidate side", collectHeader, []).option("--add-to-cart-timeout <ms>", "How long (ms) the add-to-cart step polls for a success signal before failing. Default 3000. Raise/lower to match your site's success-toast lifetime (issue #143).", (v) => Number(v)).option("--runs <n>", "Repeat each measurement N times (median)", "1").option("--baseline <name>", "Compare against a saved baseline").option("--output <dir>", "Output directory", "./parity-output").option("--fail-on <severities>", "Comma-separated severities that cause exit 1 (default: critical)", "critical").option("--html", "Also write report.html (off by default: render it later with `parity report <runId>`)", false).option("--open", "Write report.html and open it after the run completes (implies --html)", false).option("--no-auto-selectors", "Disable LLM-based selector discovery (uses defaults instead)").option("--refresh-selectors", "Bypass selector cache and re-run discovery", false).option("--no-learn", "Don't write to learned-selectors.json (read-only mode)").option("--vitals-pages <n>", "Extra pages from sitemap to crawl for Vitals coverage, beyond what --flows/--pages already cover (default 10). These are auto-sampled and can add significant unrelated noise to findings — pass 0 to scope the run to only the pages you explicitly requested.", (v) => Number(v), 10).option("--max-viewport-concurrency <n>", "How many viewports run concurrently during collect (default 2: mobile+desktop together). Set to 1 if you hit OOM with many viewports.", (v) => Number(v), 2).option("--visual-pages <n>", "Pages to compare visually with the heatmap engine — pixel diff + box-tree diff, no LLM (home + sampled PLPs/PDPs from sitemap, default 5)", (v) => Number(v), 5).option("--pages <list>", 'Comma-separated paths to compare visually (overrides sitemap discovery). E.g. "/,/account,/p/some-product". Use "prod->cand" for a page that lives at DIFFERENT paths on each side (partial migration), e.g. "/encimera-gc60/p->/ar-condicionado-12k/p". Use this when you want deterministic coverage instead of sampled. Scopes the visual-diff + vitals-extra-pages passes ONLY — the flows crawl (--flows, default purchase-journey) discovers its own target pages independently and ignores this flag. To scope which page(s) a flow visits, use --flows to pick a lighter flow and/or set the matching *UrlHint (e.g. plpUrlHint) in .parityrc.json. Issue #178.').option("--pages-file <path>", `Read paths to compare visually from a text file (one entry per line). Lines starting with # are ignored. Accepts the same "prod->cand" pair syntax as --pages. Overrides --pages when both are present. Same visual-diff/vitals-only scope as --pages — see that flag's help. Issue #178.`).option("--no-visual-diff", "Skip the visual diff capture pass entirely").option("--no-cache", "Deprecated, no effect (the visual verdict cache is gone).").option("--clear-cache", "Deprecated, no effect (the visual verdict cache is gone).", false).option("--bypass-cache", "Bypass CDN/edge caches AND the browser's own HTTP cache (CDP cache-disable), forcing a cold-visit fetch. Use right after a deploy to avoid false failures from stale CF edge content, or to approximate Lighthouse/CrUX-comparable TTFB/FCP/LCP numbers — without this flag, parity's vitals are a warm-connection/cache-enabled ('repeat visit') measurement, not a cold first-visit one, so they aren't directly comparable 1:1 to Lighthouse.", false).option("--warmup", "Before measurement, hit each target URL once (per viewport) with a cache-buster so the Worker serves a fresh response. Recommended after deploys.", false).option("--no-warm", "Don't warm each side's URL before measuring vitals. By default every vitals-measured page is loaded once on BOTH sides first, in a throwaway page (same device + cookies), so a cold edge/loader cache on whichever side hit the route first isn't reported as a Web Vitals or CLS regression. Ignored under --bypass-cache, which measures cold on purpose. Distinct from --warmup (a cache-busted homepage hit after a deploy).").option("--accept-prod-quirks", "Demote prod-side cart-empty journey failures (VTEX session quirk) from failed to skipped. The cart-reveal-mode-divergence check still emits critical if prod/cand markup intents differ, so this flag never masks a real regression. See issue #12.", false).option("--cand-is-production", "Cand is the final production domain, not a staging host. Disables staging detection (cand on another host with noindex everywhere), so noindex/nofollow on cand is critical and third-party origins missing on cand are high again.", false).option("--record <dir>", "Save the exact input the checks ran on (captures with full page HTML, resolved config, visual probes, screenshots, and the fetches the checks made) into <dir>, which must be new or empty. Contains full HTML and screenshots of both sites: do not commit it.").option("--golden <dir>", "Use the PROD half of a `--record` recording as the reference and capture only cand (--prod becomes optional). Pages come from the recording, prod-origin fetches by the checks are served from it, and a prod request it never saw is reported as stale (exit 2). Never written to. See docs/cli.md.").option("--llm-timeout <seconds>", "Deprecated, no effect: topIssues is ranked deterministically now, there is no LLM aggregation call to time out.").option("--keep-runs <n>", "After the run, delete all but the n newest runs of this prod/cand host pair under --output (other host pairs, runs without a readable report.json and baseline-referenced runs are never touched). 0 keeps everything. Default: 10.", (v) => Number(v), 10).option("--timeout <minutes>", "Hard wall-clock cap for the whole run (minutes). On expiry, parity writes a partial report and exits 130. Default: 30. Issue #56.", (v) => Number(v), 30).option("--flow <name>", "Alias for --flows when running a single flow (e.g. --flow cart). Issue #53.").option("--json <path|->", "Emit JSON-Lines (one line per check) to the given file path, or '-' for stdout. Schema versioned via leading metadata line. Issue #53.").option("--pt", "Tell the LLM to respond in Brazilian Portuguese. Only affects LLM-generated content (issues, explain, prompts) — the static HTML report stays in English. Issue #67.").option("--llm <provider>", "Force LLM provider: anthropic | openrouter | claude-code | none. Default: auto-detect (anthropic key → openrouter key → local claude CLI → none). Issue #66.").option("--llm-model <overrides>", "Per-feature model override, e.g. visual-diff=claude-opus-5,explain=claude-opus-5. Features: selector-discovery, step-recovery, search-terms, plp-matching, pdp-matching, section-understanding, visual-diff, explain, component-detection. Issue #66.").option("--llm-tier-default <tier>", "Override the default tier (haiku | sonnet | opus) for every feature that doesn't have a per-feature override. Issue #66.").option("--llm-model-default <model>", "Force every LLM call to use this exact model ID, ignoring per-feature defaults. Issue #66.").option("--llm-premium", "Bump the reasoning-heavy features (explain/visual-diff) to opus. Defaults are sonnet-first for cost/latency (opus blew the 60s timeout on most runs); opt into opus for hard fixes. Issue #256.").option("--no-interactive", "Disable the interactive selector prompt that auto-fires in a TTY without an LLM provider. Use in scripts and CI where stdin is technically a TTY but you don't want to pause. Issue #72.").option("--only <modules>", "Scope the run to these modules and/or single checks (comma-separated). Module names: e2e, seo, visual, vitals, cache, console, html, network. Single-check granularity via `check:<name>`, e.g. `--only e2e,check:cache-coverage`. Run `parity list modules` for the full check/flow mapping. Default: all modules. M3 module selection.").option("--skip <modules>", "Subtract these modules and/or single checks (comma-separated, same syntax as --only) from whatever base set was chosen (all modules, or --only's set if both are given). M3 module selection.").option("--why <text>", "Free-text reason for this run's scope, stored in report.json as `selectionReason`. Purely informational. M3 module selection.").option("--profile <type>", "Site profile: commerce | content. Scopes modules/flows/CEP. `content` (blog/custom site with no storefront) drops the e2e purchase journey, scopes flows to the homepage, and skips CEP. Auto-detected from the platform when omitted. Issues #254/#255.").action(async (opts) => {
125411
+ `)).option("--prod <url>", "Production URL (source of truth, e.g. Fresh site). Omit for a single site — the run will point you to `parity e2e` (issue #141).").requiredOption("--cand <url>", "Candidate URL (migrated site, e.g. TanStack)").option("--preset <name>", "Bundle of defaults: smoke (fast, ~30s, no LLM) | full (deep audit) | ci (CI-tuned)").option("--flows <list>", "Comma-separated flows: homepage,plp,pdp,purchase-journey", "purchase-journey").option("--viewports <list>", "Comma-separated viewports: mobile,desktop", "mobile,desktop").option("--cep <cep>", "CEP for shipping calculation", "01310-100").option("--prod-cookie <name=value>", "Cookie set on every prod browser context and plain request; repeatable. Pins prod to one A/B variant (e.g. a Fresh-vs-TanStack bucket cookie) so the run does not compare whichever build each fresh context drew. Values are redacted in logs and report.json.", collectCookie, []).option("--cand-cookie <name=value>", "Same as --prod-cookie, for the candidate side", collectCookie, []).option("--prod-header <Name: value>", "Request header sent on every prod request (all origins — no credentials); repeatable. The header twin of --prod-cookie. Values are redacted in logs and report.json.", collectHeader, []).option("--cand-header <Name: value>", "Same as --prod-header, for the candidate side", collectHeader, []).option("--add-to-cart-timeout <ms>", "How long (ms) the add-to-cart step polls for a success signal before failing. Default 3000. Raise/lower to match your site's success-toast lifetime (issue #143).", (v) => Number(v)).option("--runs <n>", "Repeat each measurement N times (median)", "1").option("--baseline <name>", "Compare against a saved baseline").option("--output <dir>", "Output directory", "./parity-output").option("--fail-on <severities>", "Comma-separated severities that cause exit 1 (default: critical)", "critical").option("--html", "Also write report.html (off by default: render it later with `parity report <runId>`)", false).option("--open", "Write report.html and open it after the run completes (implies --html)", false).option("--no-auto-selectors", "Disable LLM-based selector discovery (uses defaults instead)").option("--refresh-selectors", "Bypass selector cache and re-run discovery", false).option("--no-learn", "Don't write to learned-selectors.json (read-only mode)").option("--vitals-pages <n>", "Extra pages from sitemap to crawl for Vitals coverage, beyond what --flows/--pages already cover (default 10). These are auto-sampled and can add significant unrelated noise to findings — pass 0 to scope the run to only the pages you explicitly requested.", (v) => Number(v), 10).option("--max-viewport-concurrency <n>", "How many viewports run concurrently during collect (default 2: mobile+desktop together). Set to 1 if you hit OOM with many viewports.", (v) => Number(v), 2).option("--visual-pages <n>", "Pages to compare visually with the heatmap engine — pixel diff + box-tree diff, no LLM (home + sampled PLPs/PDPs from sitemap, default 5)", (v) => Number(v), 5).option("--pages <list>", 'Comma-separated paths to compare visually (overrides sitemap discovery). E.g. "/,/account,/p/some-product". Use "prod->cand" for a page that lives at DIFFERENT paths on each side (partial migration), e.g. "/encimera-gc60/p->/ar-condicionado-12k/p". Use this when you want deterministic coverage instead of sampled. Scopes the visual-diff + vitals-extra-pages passes ONLY — the flows crawl (--flows, default purchase-journey) discovers its own target pages independently and ignores this flag. To scope which page(s) a flow visits, use --flows to pick a lighter flow and/or set the matching *UrlHint (e.g. plpUrlHint) in .parityrc.json. Issue #178.').option("--pages-file <path>", `Read paths to compare visually from a text file (one entry per line). Lines starting with # are ignored. Accepts the same "prod->cand" pair syntax as --pages. Overrides --pages when both are present. Same visual-diff/vitals-only scope as --pages — see that flag's help. Issue #178.`).option("--no-visual-diff", "Skip the visual diff capture pass entirely").option("--no-cache", "Deprecated, no effect (the visual verdict cache is gone).").option("--clear-cache", "Deprecated, no effect (the visual verdict cache is gone).", false).option("--bypass-cache", "Bypass CDN/edge caches AND the browser's own HTTP cache (CDP cache-disable), forcing a cold-visit fetch. Use right after a deploy to avoid false failures from stale CF edge content, or to approximate Lighthouse/CrUX-comparable TTFB/FCP/LCP numbers — without this flag, parity's vitals are a warm-connection/cache-enabled ('repeat visit') measurement, not a cold first-visit one, so they aren't directly comparable 1:1 to Lighthouse.", false).option("--warmup", "Before measurement, hit each target URL once (per viewport) with a cache-buster so the Worker serves a fresh response. Recommended after deploys.", false).option("--no-warm", "Don't warm each side's URL before measuring vitals. By default every vitals-measured page is loaded once on BOTH sides first, in a throwaway page (same device + cookies), so a cold edge/loader cache on whichever side hit the route first isn't reported as a Web Vitals or CLS regression. Ignored under --bypass-cache, which measures cold on purpose. Distinct from --warmup (a cache-busted homepage hit after a deploy).").option("--no-prime-cand", "Don't request each candidate URL once (sequentially, in a real page) before the capture passes. Applies only when --cand is a local dev server (localhost), which compiles each route on its first request and times out when several first requests overlap; ignored for any other candidate. Separate from --no-warm: priming is cand-only, measures nothing, and still runs under --bypass-cache.").option("--accept-prod-quirks", "Demote prod-side cart-empty journey failures (VTEX session quirk) from failed to skipped. The cart-reveal-mode-divergence check still emits critical if prod/cand markup intents differ, so this flag never masks a real regression. See issue #12.", false).option("--cand-is-production", "Cand is the final production domain, not a staging host. Disables staging detection (cand on another host with noindex everywhere), so noindex/nofollow on cand is critical and third-party origins missing on cand are high again.", false).option("--record <dir>", "Save the exact input the checks ran on (captures with full page HTML, resolved config, visual probes, screenshots, and the fetches the checks made) into <dir>, which must be new or empty. Contains full HTML and screenshots of both sites: do not commit it.").option("--golden <dir>", "Use the PROD half of a `--record` recording as the reference and capture only cand (--prod becomes optional). Pages come from the recording, prod-origin fetches by the checks are served from it, and a prod request it never saw is reported as stale (exit 2). Never written to. See docs/cli.md.").option("--llm-timeout <seconds>", "Deprecated, no effect: topIssues is ranked deterministically now, there is no LLM aggregation call to time out.").option("--keep-runs <n>", "After the run, delete all but the n newest runs of this prod/cand host pair under --output (other host pairs, runs without a readable report.json and baseline-referenced runs are never touched). 0 keeps everything. Default: 10.", (v) => Number(v), 10).option("--timeout <minutes>", "Hard wall-clock cap for the whole run (minutes). On expiry, parity writes a partial report and exits 130. Default: 30. Issue #56.", (v) => Number(v), 30).option("--flow <name>", "Alias for --flows when running a single flow (e.g. --flow cart). Issue #53.").option("--json <path|->", "Emit JSON-Lines (one line per check) to the given file path, or '-' for stdout. Schema versioned via leading metadata line. Issue #53.").option("--pt", "Tell the LLM to respond in Brazilian Portuguese. Only affects LLM-generated content (issues, explain, prompts) — the static HTML report stays in English. Issue #67.").option("--llm <provider>", "Force LLM provider: anthropic | openrouter | claude-code | none. Default: auto-detect (anthropic key → openrouter key → local claude CLI → none). Issue #66.").option("--llm-model <overrides>", "Per-feature model override, e.g. visual-diff=claude-opus-5,explain=claude-opus-5. Features: selector-discovery, step-recovery, search-terms, plp-matching, pdp-matching, section-understanding, visual-diff, explain, component-detection. Issue #66.").option("--llm-tier-default <tier>", "Override the default tier (haiku | sonnet | opus) for every feature that doesn't have a per-feature override. Issue #66.").option("--llm-model-default <model>", "Force every LLM call to use this exact model ID, ignoring per-feature defaults. Issue #66.").option("--llm-premium", "Bump the reasoning-heavy features (explain/visual-diff) to opus. Defaults are sonnet-first for cost/latency (opus blew the 60s timeout on most runs); opt into opus for hard fixes. Issue #256.").option("--no-interactive", "Disable the interactive selector prompt that auto-fires in a TTY without an LLM provider. Use in scripts and CI where stdin is technically a TTY but you don't want to pause. Issue #72.").option("--only <modules>", "Scope the run to these modules and/or single checks (comma-separated). Module names: e2e, seo, visual, vitals, cache, console, html, network. Single-check granularity via `check:<name>`, e.g. `--only e2e,check:cache-coverage`. Run `parity list modules` for the full check/flow mapping. Default: all modules. M3 module selection.").option("--skip <modules>", "Subtract these modules and/or single checks (comma-separated, same syntax as --only) from whatever base set was chosen (all modules, or --only's set if both are given). M3 module selection.").option("--why <text>", "Free-text reason for this run's scope, stored in report.json as `selectionReason`. Purely informational. M3 module selection.").option("--profile <type>", "Site profile: commerce | content. Scopes modules/flows/CEP. `content` (blog/custom site with no storefront) drops the e2e purchase journey, scopes flows to the homepage, and skips CEP. Auto-detected from the platform when omitted. Issues #254/#255.").action(async (opts) => {
125235
125412
  if (opts.flow) {
125236
125413
  opts.flows = opts.flow;
125237
125414
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@decocms/parity",
3
- "version": "0.35.28",
3
+ "version": "0.35.30",
4
4
  "description": "E2E parity validator for site migrations. Compares prod vs cand and reports UI, functional, SEO, visual, and Web Vitals deltas with a ranked HTML report.",
5
5
  "type": "module",
6
6
  "license": "MIT",