@decocms/parity 0.35.28 → 0.35.29

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,6 +50,14 @@ 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
+ * **`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`.
53
61
 
54
62
  ### Fixed
55
63
 
package/dist/cli.js CHANGED
@@ -90645,7 +90645,8 @@ var PageCapture = z2.object({
90645
90645
  xRobotsTag: z2.string().nullable().optional(),
90646
90646
  pairKey: z2.string().optional(),
90647
90647
  pass: z2.enum(["extra", "visual"]).optional(),
90648
- variant: VariantFingerprint.optional()
90648
+ variant: VariantFingerprint.optional(),
90649
+ retried: z2.boolean().optional()
90649
90650
  });
90650
90651
  var StepCapture = z2.object({
90651
90652
  step: z2.number(),
@@ -91022,6 +91023,13 @@ var Run = z2.object({
91022
91023
  failed: z2.number().optional(),
91023
91024
  totalMs: z2.number().optional()
91024
91025
  }).optional(),
91026
+ candPrime: z2.object({
91027
+ attempted: z2.number(),
91028
+ failedUrls: z2.array(z2.string()),
91029
+ totalMs: z2.number(),
91030
+ retried: z2.number(),
91031
+ recovered: z2.number()
91032
+ }).optional(),
91025
91033
  selectionReason: z2.string().optional(),
91026
91034
  moduleVerdicts: z2.array(ModuleVerdict).optional(),
91027
91035
  acceptedFindings: z2.object({
@@ -118593,6 +118601,76 @@ function formatSecs(ms) {
118593
118601
  return `${min}m${sec.toString().padStart(2, "0")}s`;
118594
118602
  }
118595
118603
 
118604
+ // src/engine/cand-prime.ts
118605
+ var PRIME_TIMEOUT_MS = 90000;
118606
+ var PRIME_LOAD_MS = 1e4;
118607
+ function planCandPrime(candBase, paths, alreadyPrimed) {
118608
+ if (!isLocalhost(candBase))
118609
+ return [];
118610
+ const out = [];
118611
+ const seen = new Set(alreadyPrimed);
118612
+ for (const p of paths) {
118613
+ let url;
118614
+ try {
118615
+ url = new URL(p, candBase).toString();
118616
+ } catch {
118617
+ continue;
118618
+ }
118619
+ if (seen.has(url))
118620
+ continue;
118621
+ seen.add(url);
118622
+ out.push(url);
118623
+ }
118624
+ return out;
118625
+ }
118626
+ async function primeSequentially(urls, primed, prime) {
118627
+ const start = Date.now();
118628
+ const failed = [];
118629
+ for (const url of urls) {
118630
+ primed.add(url);
118631
+ const ok = await prime(url).catch(() => false);
118632
+ if (!ok)
118633
+ failed.push(url);
118634
+ }
118635
+ return { attempted: urls.length, failed, totalMs: Date.now() - start };
118636
+ }
118637
+ async function primeCandUrls(browser, urls, primed, ctxOpts) {
118638
+ if (urls.length === 0)
118639
+ return { attempted: 0, failed: [], totalMs: 0 };
118640
+ const ctx = await newContext(browser, { cohortCookieValue: "control", ...ctxOpts });
118641
+ try {
118642
+ return await primeSequentially(urls, primed, async (url) => {
118643
+ const page = await ctx.newPage();
118644
+ try {
118645
+ await page.goto(url, { waitUntil: "domcontentloaded", timeout: PRIME_TIMEOUT_MS });
118646
+ await page.waitForLoadState("load", { timeout: PRIME_LOAD_MS }).catch(() => {
118647
+ return;
118648
+ });
118649
+ return true;
118650
+ } finally {
118651
+ await page.close().catch(() => {
118652
+ return;
118653
+ });
118654
+ }
118655
+ });
118656
+ } finally {
118657
+ await ctx.close().catch(() => {
118658
+ return;
118659
+ });
118660
+ }
118661
+ }
118662
+ function needsRetry(side, candUrl, cap) {
118663
+ if (side !== "cand" || !isLocalhost(candUrl))
118664
+ return false;
118665
+ if (!cap)
118666
+ return true;
118667
+ return cap.status === 0 && !cap.retried;
118668
+ }
118669
+ var COLD_SHARE = 0.25;
118670
+ function isColdCandidate(loads) {
118671
+ return loads.failed >= 2 && loads.failed / loads.total > COLD_SHARE;
118672
+ }
118673
+
118596
118674
  // src/engine/run-context.ts
118597
118675
  function detectRunCaveats(input) {
118598
118676
  const out = [];
@@ -118604,6 +118682,15 @@ function detectRunCaveats(input) {
118604
118682
  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
118683
  });
118606
118684
  }
118685
+ if (input.warmLoads && isColdCandidate(input.warmLoads)) {
118686
+ const { failed, total } = input.warmLoads;
118687
+ out.push({
118688
+ id: "cand-cold",
118689
+ level: "warn",
118690
+ summary: `${failed} of ${total} warm-up/priming loads never answered — the server looked cold or unhealthy`,
118691
+ 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."
118692
+ });
118693
+ }
118607
118694
  if (isLocalhost(input.prodUrl)) {
118608
118695
  out.push({
118609
118696
  id: "prod-dev-server",
@@ -119327,6 +119414,65 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119327
119414
  } else if (warmPlan.skippedReason === "bypass-cache") {
119328
119415
  console.log(chalk34.dim(" vitals warm-up: off (--bypass-cache measures cold on purpose)"));
119329
119416
  }
119417
+ const primeEnabled = opts.primeCand !== false && isLocalhost(opts.cand);
119418
+ const primed = new Set;
119419
+ const primeAcc = { attempted: 0, failed: [], totalMs: 0 };
119420
+ const candRetry = { retried: 0, recovered: 0 };
119421
+ const retrying = new Set;
119422
+ const warmLoadsNow = () => ({
119423
+ total: primeAcc.attempted + (vitalsWarm?.stats.loads ?? 0),
119424
+ failed: primeAcc.failed.length + (vitalsWarm?.stats.failed ?? 0)
119425
+ });
119426
+ let coldWarned = false;
119427
+ const warnIfCold = () => {
119428
+ const loads = warmLoadsNow();
119429
+ if (coldWarned || !isColdCandidate(loads))
119430
+ return;
119431
+ coldWarned = true;
119432
+ 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.`));
119433
+ };
119434
+ const primeCand = async (candPaths) => {
119435
+ if (!primeEnabled || !browser)
119436
+ return;
119437
+ const urls = planCandPrime(opts.cand, candPaths, primed);
119438
+ if (urls.length === 0)
119439
+ return;
119440
+ console.log(chalk34.dim(` priming cand: ${urls.length} URL(s), one at a time (--no-prime-cand to skip)`));
119441
+ const r = await primeCandUrls(browser, urls, primed, {
119442
+ viewport: viewports[0],
119443
+ cookies: pins.cand.cookies,
119444
+ headers: pins.cand.headers
119445
+ });
119446
+ primeAcc.attempted += r.attempted;
119447
+ primeAcc.failed.push(...r.failed);
119448
+ primeAcc.totalMs += r.totalMs;
119449
+ phaseStart += r.totalMs;
119450
+ warnIfCold();
119451
+ };
119452
+ const retryColdCand = async (pass, passTasks, runTask) => {
119453
+ const capOf = (t) => {
119454
+ const url = new URL(t.path, opts.cand).toString();
119455
+ return allPageCaptures.find((c) => c.pass === pass && c.side === "cand" && c.viewport === t.viewport && c.url === url);
119456
+ };
119457
+ for (const t of passTasks.filter((x) => needsRetry(x.side, opts.cand, capOf(x)))) {
119458
+ const old = capOf(t);
119459
+ const before = allPageCaptures.length;
119460
+ retrying.add(t);
119461
+ candRetry.retried++;
119462
+ await runTask(t);
119463
+ if (allPageCaptures.length === before)
119464
+ continue;
119465
+ const fresh = allPageCaptures[allPageCaptures.length - 1];
119466
+ if (fresh.status > 0)
119467
+ candRetry.recovered++;
119468
+ if (old) {
119469
+ allPageCaptures.splice(allPageCaptures.indexOf(old), 1);
119470
+ const fi = allFlowCaptures.findIndex((f) => f.pages.length === 1 && f.pages[0] === old);
119471
+ if (fi >= 0)
119472
+ allFlowCaptures.splice(fi, 1);
119473
+ }
119474
+ }
119475
+ };
119330
119476
  const timeoutMinutes = Math.max(1, Math.floor(opts.timeout ?? 30));
119331
119477
  const globalTimeoutTimer = setTimeout(() => {
119332
119478
  shutdown(`timeout ${timeoutMinutes}min`);
@@ -119452,8 +119598,10 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119452
119598
  }
119453
119599
  };
119454
119600
  const maxViewportConcurrency = Math.max(1, opts.maxViewportConcurrency ?? 2);
119601
+ await primeCand(["/"]);
119455
119602
  await runWithConcurrency2(viewports, maxViewportConcurrency, runOneViewport);
119456
119603
  stampPhase("collect");
119604
+ warnIfCold();
119457
119605
  spinner.succeed("Coleta concluída");
119458
119606
  if (isLlmAvailable()) {
119459
119607
  const prodPdp = findPdpCapture(allFlowCaptures, "prod");
@@ -119528,7 +119676,8 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119528
119676
  }
119529
119677
  }
119530
119678
  let done = 0;
119531
- await runWithConcurrency2(tasks, 4, async (task) => {
119679
+ await primeCand(extraPaths);
119680
+ const runTask = async (task) => {
119532
119681
  const baseUrl = task.side === "prod" ? opts.prod : opts.cand;
119533
119682
  const fullUrl = new URL(task.path, baseUrl).toString();
119534
119683
  const targetIsDevServer = isLocalhost(baseUrl);
@@ -119572,6 +119721,8 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119572
119721
  return;
119573
119722
  }
119574
119723
  cap.pass = "extra";
119724
+ if (retrying.has(task))
119725
+ cap.retried = true;
119575
119726
  allPageCaptures.push(cap);
119576
119727
  allFlowCaptures.push({
119577
119728
  flow: "homepage",
@@ -119593,7 +119744,9 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119593
119744
  vitalsHb.bump();
119594
119745
  extraSpinner.text = `[vitals extras] ${done}/${tasks.length} (último: ${task.path})`;
119595
119746
  }
119596
- });
119747
+ };
119748
+ await runWithConcurrency2(tasks, 4, runTask);
119749
+ await retryColdCand("extra", tasks, runTask);
119597
119750
  vitalsHb.stop();
119598
119751
  extraSpinner.succeed(`+${extraPaths.length} página(s) com vitals`);
119599
119752
  } else {
@@ -119605,6 +119758,7 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119605
119758
  extraSpinner.warn(`vitals extras pulado: ${err.message}`);
119606
119759
  } finally {
119607
119760
  stampPhase("vitals-pages");
119761
+ warnIfCold();
119608
119762
  }
119609
119763
  }
119610
119764
  const explicitPaths = resolveExplicitPages(opts.pagesFile, opts.pages);
@@ -119638,7 +119792,8 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119638
119792
  } else {
119639
119793
  visualSpinner.text = `Visual diff: capturando ${tasks.length} screenshot(s) (${visualPaths.length} páginas × ${viewports.length} viewport(s) × 2 sides)…`;
119640
119794
  let done = 0;
119641
- await runWithConcurrency2(tasks, 4, async (task) => {
119795
+ await primeCand(visualPaths.map((p) => p.cand));
119796
+ const runTask = async (task) => {
119642
119797
  const baseUrl = task.side === "prod" ? opts.prod : opts.cand;
119643
119798
  const fullUrl = new URL(task.path, baseUrl).toString();
119644
119799
  const safePath = task.path.replace(/[/?&=]+/g, "_") || "_root";
@@ -119667,6 +119822,8 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119667
119822
  pairKey: task.pairKey
119668
119823
  });
119669
119824
  cap.pass = "visual";
119825
+ if (retrying.has(task))
119826
+ cap.retried = true;
119670
119827
  allPageCaptures.push(cap);
119671
119828
  if (existsSync31(screenshotPath)) {
119672
119829
  visualProbes.set(screenshotPath, await probeFullPage(page, screenshotPath, task.side === "prod" ? screenshotPath.replace(/\.png$/, "-repeat.png") : null));
@@ -119684,7 +119841,9 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119684
119841
  visualHb.bump();
119685
119842
  visualSpinner.text = `[visual] ${done}/${tasks.length} (último: ${task.path})`;
119686
119843
  }
119687
- });
119844
+ };
119845
+ await runWithConcurrency2(tasks, 4, runTask);
119846
+ await retryColdCand("visual", tasks, runTask);
119688
119847
  visualHb.stop();
119689
119848
  visualSpinner.succeed(`Visual diff: ${tasks.length} screenshot(s) capturado(s)`);
119690
119849
  }
@@ -119699,6 +119858,14 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119699
119858
  const w = vitalsWarm.stats;
119700
119859
  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
119860
  }
119861
+ warnIfCold();
119862
+ if (primeAcc.attempted > 0) {
119863
+ const f = primeAcc.failed.map((u) => new URL(u).pathname);
119864
+ 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 ? "…" : ""}` : ""}`));
119865
+ }
119866
+ if (candRetry.retried > 0) {
119867
+ console.log(chalk34.dim(` cand retry: ${candRetry.retried} capture(s) retried after not answering, ${candRetry.recovered} recovered`));
119868
+ }
119702
119869
  if (goldenRec && goldenPlan) {
119703
119870
  const merged = mergeGoldenContext(goldenRec, goldenPlan, {
119704
119871
  pages: allPageCaptures,
@@ -119832,6 +119999,8 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119832
119999
  const visualDiff = visualCheck?.data?.visualDiff;
119833
120000
  const seoCheck = checks.find((c) => c.name === "seo-deep-audit");
119834
120001
  const seo = seoCheck?.data?.seo;
120002
+ if (primeAcc.totalMs > 0)
120003
+ timings.push("prime-cand", primeAcc.totalMs);
119835
120004
  const runTimings = timings.finalize();
119836
120005
  const run = {
119837
120006
  schemaVersion: "0.1",
@@ -119855,6 +120024,12 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119855
120024
  baseline: baselineSection,
119856
120025
  timings: runTimings,
119857
120026
  vitalsWarmup: vitalsWarm ? { enabled: true, loadsPerPage: vitalsWarm.loads, ...vitalsWarm.stats } : { enabled: false, skippedReason: warmPlan.skippedReason },
120027
+ candPrime: primeAcc.attempted > 0 || candRetry.retried > 0 ? {
120028
+ attempted: primeAcc.attempted,
120029
+ failedUrls: primeAcc.failed,
120030
+ totalMs: primeAcc.totalMs,
120031
+ ...candRetry
120032
+ } : undefined,
119858
120033
  selectionReason: opts.why,
119859
120034
  moduleVerdicts: moduleVerdicts.length > 0 ? moduleVerdicts : undefined,
119860
120035
  acceptedFindings: acceptance.accepted > 0 || acceptance.stale.length > 0 ? {
@@ -119870,7 +120045,8 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
119870
120045
  verdict,
119871
120046
  llmEnabled: llmStillAvailable,
119872
120047
  candIsProduction: opts.candIsProduction,
119873
- prodPinned: !isEmptyPin(pins.prod)
120048
+ prodPinned: !isEmptyPin(pins.prod),
120049
+ warmLoads: warmLoadsNow()
119874
120050
  })),
119875
120051
  pinned: isEmptyPin(pins.prod) && isEmptyPin(pins.cand) ? undefined : { prod: pinNames(pins.prod), cand: pinNames(pins.cand) },
119876
120052
  pagePairs,
@@ -125231,7 +125407,7 @@ program.command("run").description([
125231
125407
  " visual-pages=5, auto-selectors=ON (if LLM), learn=ON, visual-diff=ON,",
125232
125408
  " warmup=OFF, vitals warm=ON, bypass-cache=OFF, fail-on=critical (exit 1 if hit)."
125233
125409
  ].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) => {
125410
+ `)).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
125411
  if (opts.flow) {
125236
125412
  opts.flows = opts.flow;
125237
125413
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@decocms/parity",
3
- "version": "0.35.28",
3
+ "version": "0.35.29",
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",