@decocms/parity 0.17.8 → 0.17.9

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/CHANGELOG.md CHANGED
@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ### Fixed
11
+
12
+ * **`--fail-on` now gates the exit code on its own (issue #178).** The blocking-issue exit-1 check was gated behind `--ci`, which had no other effect in the codebase — a run with double-digit criticals exited 0 unless the caller also remembered `--ci`, even though `--fail-on` (default `critical`) was already parsed and ready. The check now always runs; `--ci` has been removed as dead weight (`parity audit` never had it and always gated on `--fail-on` alone, which is the pattern `parity run` now follows too).
13
+ * **`--pages`/`--pages-file` scoping documented, and no longer silently disable visual-diff in no-LLM environments (issue #178).** These flags only ever scoped the visual-diff/vitals-extra-pages passes, never the `flows` crawl — now documented in `--help`/`docs/cli.md`, and `parity run` prints a one-line warning when both an explicit page list and a flows crawl are active. Separately, `applySmartDefaults` (issue #71) used to force `noVisualDiff = true` whenever no LLM provider was configured, even when `--pages`/`--pages-file` was explicitly set — making the flag silently inert. Explicit page selection now still gets the prod/cand screenshot + pixelmatch heatmap capture without an LLM verdict.
14
+ * **`banner-aspect-ratio` no longer double-counts carousel boundary clones (issue #178).** Images marked `aria-hidden="true"` or `data-slider-clone` (or nested inside such a wrapper) — the decorative clones a hydration-safe infinite carousel renders at its boundaries — are now excluded from the banner census in `src/diff/dom.ts`, which previously produced false "candidate has N extra banners" findings.
15
+ * **`lazy-section-presence` no longer reports a spurious "missing: render" on every page of a TanStack Start site (issue #178).** The last-path-segment fallback in `extractSectionIds` (used when a lazy-render network entry has no `x-deco-section` header) now ignores known infra/admin route names (`render`, `meta`, `invoke`) that carry no real section-identifying information as a bare fallback id.
16
+ * **Visual-diff LLM prompt now hedges on small-text/count reads (issue #178).** Numeric counts and small text read off a (possibly downscaled) full-page screenshot were occasionally misread by the vision model and reported as confident high-severity regressions. The prompt now caps such claims at `low` severity and requires an explicit hedge in the description; `LLM_PROMPT_VERSION` bumped to invalidate cached verdicts from the old prompt.
17
+ * **`--vitals-pages` noise/scoping trade-off surfaced in `--help`/`docs/cli.md` (issue #178).** `--vitals-pages 0` can dramatically cut unrelated auto-sampled noise (one run went from 53 to 13 `high` findings) but was previously discoverable only by reading source — now called out in both the flag's help text and a `docs/cli.md` callout.
18
+
10
19
  ## [0.17.3](https://github.com/decocms/parity/compare/v0.17.2...v0.17.3) (2026-07-28)
11
20
 
12
21
  ### Fixed
package/README.md CHANGED
@@ -96,6 +96,10 @@ Without any provider, the CLI still runs and outputs raw check results — only
96
96
 
97
97
  Individual flags always override the preset. See `parity run --help` for the full default behavior breakdown.
98
98
 
99
+ ### A note on Web Vitals numbers
100
+
101
+ By default parity measures TTFB/FCP/LCP with the browser's HTTP cache enabled, on a warm connection — a "repeat visit" scenario. Lighthouse and CrUX field data, by contrast, simulate/measure cold first-time visits (cache disabled). Neither is wrong, but they answer different questions, so don't compare parity's default vitals 1:1 against Lighthouse or CrUX. Pass `--bypass-cache` to approximate a cold-visit measurement instead (disables the browser cache via CDP in addition to bypassing CDN/edge caches).
102
+
99
103
  ## CI usage (GitHub Actions)
100
104
 
101
105
  ```yaml
package/dist/cli.js CHANGED
@@ -37789,6 +37789,8 @@ function snapshotDom(html3) {
37789
37789
  const looksLikeBanner = sectionName !== null || widthAttr !== null && widthAttr >= BANNER_WIDTH_THRESHOLD;
37790
37790
  if (!looksLikeBanner)
37791
37791
  return;
37792
+ if ($el.closest('[aria-hidden="true"], [data-slider-clone]').length > 0)
37793
+ return;
37792
37794
  const src = $el.attr("src") ?? "";
37793
37795
  if (!src)
37794
37796
  return;
@@ -38720,6 +38722,13 @@ function missingBrowserError(cause) {
38720
38722
  ].join(`
38721
38723
  `));
38722
38724
  }
38725
+ async function disableHttpCache(page) {
38726
+ try {
38727
+ const cdp = await page.context().newCDPSession(page);
38728
+ await cdp.send("Network.enable");
38729
+ await cdp.send("Network.setCacheDisabled", { cacheDisabled: true });
38730
+ } catch {}
38731
+ }
38723
38732
  async function newContext(browser, opts) {
38724
38733
  const baseContext = VIEWPORT_PRESETS[opts.viewport];
38725
38734
  const ctx = await browser.newContext({
@@ -38729,6 +38738,14 @@ async function newContext(browser, opts) {
38729
38738
  ignoreHTTPSErrors: true,
38730
38739
  extraHTTPHeaders: opts.noCache ? { "Cache-Control": "no-cache", Pragma: "no-cache" } : undefined
38731
38740
  });
38741
+ if (opts.noCache) {
38742
+ const rawNewPage = ctx.newPage.bind(ctx);
38743
+ ctx.newPage = async () => {
38744
+ const page = await rawNewPage();
38745
+ await disableHttpCache(page);
38746
+ return page;
38747
+ };
38748
+ }
38732
38749
  await ctx.addInitScript({
38733
38750
  content: `
38734
38751
  try {
@@ -38767,6 +38784,21 @@ function dlog(side, viewport, msg) {
38767
38784
  process.stderr.write(`[+${elapsed}s ${viewport}/${side}] ${msg}
38768
38785
  `);
38769
38786
  }
38787
+ function clsWindowReducer(state, entry) {
38788
+ if (entry.hadRecentInput)
38789
+ return state;
38790
+ let { sessionValue, sessionStart, sessionLast, clsValue } = state;
38791
+ if (sessionValue && entry.startTime - sessionLast < 1000 && entry.startTime - sessionStart < 5000) {
38792
+ sessionValue += entry.value;
38793
+ } else {
38794
+ sessionValue = entry.value;
38795
+ sessionStart = entry.startTime;
38796
+ }
38797
+ sessionLast = entry.startTime;
38798
+ if (sessionValue > clsValue)
38799
+ clsValue = sessionValue;
38800
+ return { sessionValue, sessionStart, sessionLast, clsValue };
38801
+ }
38770
38802
  var VITALS_INIT_SCRIPT = `
38771
38803
  (function() {
38772
38804
  if (window.__parity_vitals_installed) return;
@@ -38799,15 +38831,14 @@ var VITALS_INIT_SCRIPT = `
38799
38831
  }).observe({ type: 'paint', buffered: true });
38800
38832
  } catch (e) {}
38801
38833
 
38802
- // CLS (cumulative, excluding shifts after recent user input)
38834
+ // CLS
38803
38835
  try {
38804
- let cls = 0;
38836
+ const clsWindowReducer = ${clsWindowReducer.toString()};
38837
+ let clsState = { sessionValue: 0, sessionStart: 0, sessionLast: 0, clsValue: 0 };
38805
38838
  new PerformanceObserver(function(list) {
38806
38839
  for (const entry of list.getEntries()) {
38807
- if (!entry.hadRecentInput) {
38808
- cls += entry.value;
38809
- window.__parity_vitals.cls = cls;
38810
- }
38840
+ clsState = clsWindowReducer(clsState, entry);
38841
+ window.__parity_vitals.cls = clsState.clsValue;
38811
38842
  }
38812
38843
  }).observe({ type: 'layout-shift', buffered: true });
38813
38844
  } catch (e) {}
@@ -38830,6 +38861,68 @@ var VITALS_INIT_SCRIPT = `
38830
38861
  async function installVitalsCollector(ctx) {
38831
38862
  await ctx.addInitScript({ content: VITALS_INIT_SCRIPT });
38832
38863
  }
38864
+ async function captureVitalsSample(context, url, timeoutMs) {
38865
+ const page = await context.newPage();
38866
+ try {
38867
+ await page.goto(url, { waitUntil: "domcontentloaded", timeout: timeoutMs }).catch(() => {
38868
+ return;
38869
+ });
38870
+ await page.waitForLoadState("networkidle", { timeout: Math.min(4000, timeoutMs) }).catch(() => {
38871
+ return;
38872
+ });
38873
+ await page.waitForTimeout(300).catch(() => {
38874
+ return;
38875
+ });
38876
+ return await Promise.race([
38877
+ page.evaluate(() => window.__parity_vitals).catch(() => null),
38878
+ new Promise((resolve) => setTimeout(() => resolve(null), 3000))
38879
+ ]) ?? null;
38880
+ } finally {
38881
+ await page.close().catch(() => {
38882
+ return;
38883
+ });
38884
+ }
38885
+ }
38886
+ var VITALS_METRICS = ["lcp", "cls", "fcp", "ttfb", "inp"];
38887
+ function aggregateVitalsSamples(samples) {
38888
+ const out = {};
38889
+ for (const metric of VITALS_METRICS) {
38890
+ const values = samples.map((s) => s[metric]).filter((v) => v != null);
38891
+ out[metric] = values.length > 0 ? statFor(values) : null;
38892
+ }
38893
+ return out;
38894
+ }
38895
+ function statFor(raw) {
38896
+ const sorted = [...raw].sort((a, b) => a - b);
38897
+ return {
38898
+ median: percentile(sorted, 50),
38899
+ p75: percentile(sorted, 75),
38900
+ min: sorted[0],
38901
+ max: sorted[sorted.length - 1],
38902
+ samples: raw
38903
+ };
38904
+ }
38905
+ function percentile(sorted, p) {
38906
+ if (sorted.length === 1)
38907
+ return sorted[0];
38908
+ const idx = p / 100 * (sorted.length - 1);
38909
+ const lo = Math.floor(idx);
38910
+ const hi = Math.ceil(idx);
38911
+ if (lo === hi)
38912
+ return sorted[lo];
38913
+ const frac = idx - lo;
38914
+ return sorted[lo] + (sorted[hi] - sorted[lo]) * frac;
38915
+ }
38916
+ async function readVitalsSnapshot(page) {
38917
+ return await page.evaluate(() => window.__parity_vitals).catch(() => null) ?? null;
38918
+ }
38919
+ function mergeInpSnapshot(vitals, snapshot) {
38920
+ if (snapshot?.inp == null)
38921
+ return vitals;
38922
+ if (vitals.inp != null && vitals.inp >= snapshot.inp)
38923
+ return vitals;
38924
+ return { ...vitals, inp: snapshot.inp };
38925
+ }
38833
38926
  var CANCELLATION_ERROR_CODES = [
38834
38927
  "net::ERR_ABORTED",
38835
38928
  "net::ERR_NETWORK_CHANGED"
@@ -38907,7 +39000,8 @@ async function responseToEntry(resp) {
38907
39000
  const req = resp.request();
38908
39001
  const headers = resp.headers();
38909
39002
  const timing = req.timing();
38910
- const bytes = await safeBodySize(resp) ?? parseIntOrNull(headers["content-length"]);
39003
+ const contentLength = parseIntOrNull(headers["content-length"]);
39004
+ const bytes = contentLength ?? (isSmallTextResource(req.resourceType()) ? await safeBodySize(resp) : null);
38911
39005
  return {
38912
39006
  url: resp.url(),
38913
39007
  method: req.method(),
@@ -38923,6 +39017,9 @@ async function responseToEntry(resp) {
38923
39017
  decoSection: headers["x-deco-section"] ?? null
38924
39018
  };
38925
39019
  }
39020
+ function isSmallTextResource(resourceType) {
39021
+ return resourceType === "document" || resourceType === "script" || resourceType === "xhr" || resourceType === "fetch";
39022
+ }
38926
39023
  async function safeBodySize(resp) {
38927
39024
  try {
38928
39025
  const buf = await Promise.race([
@@ -39015,7 +39112,8 @@ function isFromHttpCache(resp) {
39015
39112
  async function capturePage(page, opts) {
39016
39113
  const start = Date.now();
39017
39114
  const state = attachCollectors(page);
39018
- const overallBudgetMs = opts.fast ? 25000 : 60000;
39115
+ const extraRunsBudgetMs = Math.max(0, (opts.runs ?? 1) - 1) * 8000;
39116
+ const overallBudgetMs = (opts.fast ? 25000 : 60000) + extraRunsBudgetMs;
39019
39117
  const deadline = start + overallBudgetMs;
39020
39118
  const remaining = () => Math.max(500, deadline - Date.now());
39021
39119
  const buildPartial = () => ({
@@ -39027,6 +39125,8 @@ async function capturePage(page, opts) {
39027
39125
  durationMs: Date.now() - start,
39028
39126
  html: html3,
39029
39127
  vitals: vitals ?? { lcp: null, cls: null, fcp: null, ttfb: null, inp: null },
39128
+ vitalsStats,
39129
+ vitalsFullPage: vitalsFullPage ?? undefined,
39030
39130
  console: state.console,
39031
39131
  network: state.network,
39032
39132
  screenshotPath: opts.screenshotPath,
@@ -39038,7 +39138,16 @@ async function capturePage(page, opts) {
39038
39138
  let finalUrl = opts.url;
39039
39139
  let xRobotsTag = null;
39040
39140
  let vitals = null;
39141
+ let vitalsStats;
39142
+ let vitalsFullPage = null;
39041
39143
  let html3 = "";
39144
+ const readVitals = async () => {
39145
+ dlog(opts.side, opts.viewport, ` capturePage: vitals evaluate (cap=${Math.min(5000, remaining())}ms)`);
39146
+ return await Promise.race([
39147
+ page.evaluate(() => window.__parity_vitals).catch(() => null),
39148
+ new Promise((resolve) => setTimeout(() => resolve(null), Math.min(5000, remaining())))
39149
+ ]) ?? null;
39150
+ };
39042
39151
  let _resolveDisconnect;
39043
39152
  const disconnectPromise = new Promise((r) => {
39044
39153
  _resolveDisconnect = r;
@@ -39074,6 +39183,7 @@ async function capturePage(page, opts) {
39074
39183
  });
39075
39184
  }
39076
39185
  await page.waitForTimeout(Math.min(opts.settleMs ?? 1200, remaining()));
39186
+ vitals = await readVitals();
39077
39187
  } else {
39078
39188
  dlog(opts.side, opts.viewport, ` capturePage: waitForLoadState('load') (cap=${Math.min(12000, remaining())}ms)`);
39079
39189
  await page.waitForLoadState("load", { timeout: Math.min(12000, remaining()) }).catch(() => {
@@ -39087,6 +39197,7 @@ async function capturePage(page, opts) {
39087
39197
  }
39088
39198
  dlog(opts.side, opts.viewport, ` capturePage: settle (cap=${Math.min(opts.settleMs ?? 2000, remaining())}ms)`);
39089
39199
  await page.waitForTimeout(Math.min(opts.settleMs ?? 2000, remaining()));
39200
+ vitals = await readVitals();
39090
39201
  if (opts.scrollToLoad !== false && remaining() > 3000) {
39091
39202
  const scrollBudget = Math.min(45000, remaining());
39092
39203
  dlog(opts.side, opts.viewport, ` capturePage: scrollFullPage start (budget=${scrollBudget}ms, remaining=${remaining()}ms)`);
@@ -39109,6 +39220,7 @@ async function capturePage(page, opts) {
39109
39220
  });
39110
39221
  }
39111
39222
  await page.waitForTimeout(Math.min(800, remaining()));
39223
+ vitalsFullPage = await readVitals();
39112
39224
  }
39113
39225
  }
39114
39226
  } catch (err) {
@@ -39117,11 +39229,9 @@ async function capturePage(page, opts) {
39117
39229
  text: `[navigation-error] ${err.message}`
39118
39230
  });
39119
39231
  }
39120
- dlog(opts.side, opts.viewport, ` capturePage: vitals evaluate (cap=${Math.min(5000, remaining())}ms)`);
39121
- vitals = await Promise.race([
39122
- page.evaluate(() => window.__parity_vitals).catch(() => null),
39123
- new Promise((resolve) => setTimeout(() => resolve(null), Math.min(5000, remaining())))
39124
- ]) ?? null;
39232
+ if (vitals === null) {
39233
+ vitals = await readVitals();
39234
+ }
39125
39235
  if (!opts.skipScreenshot) {
39126
39236
  await Promise.race([
39127
39237
  stabilizeCarousels(page).catch(() => {
@@ -39159,6 +39269,26 @@ async function capturePage(page, opts) {
39159
39269
  ]);
39160
39270
  dlog(opts.side, opts.viewport, ` capturePage: flushCollectors (cap=${Math.min(3000, remaining())}ms)`);
39161
39271
  await flushCollectors(state, Math.min(3000, remaining()));
39272
+ const extraRuns = Math.max(0, (opts.runs ?? 1) - 1);
39273
+ if (extraRuns > 0 && vitals) {
39274
+ dlog(opts.side, opts.viewport, ` capturePage: vitals repeat x${extraRuns} start`);
39275
+ const samples = [vitals];
39276
+ const ctx = page.context();
39277
+ for (let i = 0;i < extraRuns && remaining() > 4000; i++) {
39278
+ const sample = await captureVitalsSample(ctx, opts.url, Math.min(1e4, remaining()));
39279
+ if (sample)
39280
+ samples.push(sample);
39281
+ }
39282
+ vitalsStats = aggregateVitalsSamples(samples);
39283
+ vitals = {
39284
+ lcp: vitalsStats.lcp?.median ?? vitals.lcp,
39285
+ cls: vitalsStats.cls?.median ?? vitals.cls,
39286
+ fcp: vitalsStats.fcp?.median ?? vitals.fcp,
39287
+ ttfb: vitalsStats.ttfb?.median ?? vitals.ttfb,
39288
+ inp: vitalsStats.inp?.median ?? vitals.inp
39289
+ };
39290
+ dlog(opts.side, opts.viewport, ` capturePage: vitals repeat done samples=${samples.length}/${opts.runs}`);
39291
+ }
39162
39292
  dlog(opts.side, opts.viewport, ` capturePage: inner done total=${Date.now() - start}ms`);
39163
39293
  return buildPartial();
39164
39294
  };
@@ -41102,6 +41232,20 @@ var WebVitals = z.object({
41102
41232
  ttfb: z.number().nullable(),
41103
41233
  inp: z.number().nullable()
41104
41234
  });
41235
+ var WebVitalStat = z.object({
41236
+ median: z.number(),
41237
+ p75: z.number(),
41238
+ min: z.number(),
41239
+ max: z.number(),
41240
+ samples: z.array(z.number())
41241
+ });
41242
+ var WebVitalsStats = z.object({
41243
+ lcp: WebVitalStat.nullable(),
41244
+ cls: WebVitalStat.nullable(),
41245
+ fcp: WebVitalStat.nullable(),
41246
+ ttfb: WebVitalStat.nullable(),
41247
+ inp: WebVitalStat.nullable()
41248
+ });
41105
41249
  var ConsoleEntry = z.object({
41106
41250
  type: z.enum(["error", "warning", "log", "info", "debug"]),
41107
41251
  text: z.string(),
@@ -41130,6 +41274,8 @@ var PageCapture = z.object({
41130
41274
  durationMs: z.number(),
41131
41275
  html: z.string(),
41132
41276
  vitals: WebVitals,
41277
+ vitalsStats: WebVitalsStats.optional(),
41278
+ vitalsFullPage: WebVitals.optional(),
41133
41279
  console: z.array(ConsoleEntry),
41134
41280
  network: z.array(NetworkEntry),
41135
41281
  screenshotPath: z.string(),
@@ -41691,7 +41837,8 @@ async function auditCommand(opts) {
41691
41837
  settleMs: 1500,
41692
41838
  timeoutMs: 30000,
41693
41839
  fast: false,
41694
- scrollToLoad: true
41840
+ scrollToLoad: true,
41841
+ runs: opts.runs
41695
41842
  });
41696
41843
  captures.push(cap);
41697
41844
  } catch (err) {
@@ -43221,6 +43368,7 @@ function countFailedImageRequests(entries) {
43221
43368
 
43222
43369
  // src/checks/lazy-sections.ts
43223
43370
  var LAZY_URL_PATTERN = /\/(deco\/render|_loader)\b/;
43371
+ var RESERVED_FALLBACK_SEGMENTS = new Set(["render", "meta", "invoke"]);
43224
43372
  var EAGER_RENDERING_MARKER = /data-deco-async-rendering=["']eager["']|<meta\s+name=["']parity:async-rendering["']\s+content=["']eager["']/i;
43225
43373
  function lazySectionPresence(ctx) {
43226
43374
  const start = Date.now();
@@ -43333,8 +43481,11 @@ function extractSectionIds(entries) {
43333
43481
  try {
43334
43482
  const u = new URL(e.url);
43335
43483
  const seg = u.pathname.split("/").filter(Boolean).pop();
43336
- if (seg)
43337
- out.add(normalizeSectionId(seg));
43484
+ if (seg) {
43485
+ const normalized = normalizeSectionId(seg);
43486
+ if (!RESERVED_FALLBACK_SEGMENTS.has(normalized))
43487
+ out.add(normalized);
43488
+ }
43338
43489
  } catch {}
43339
43490
  }
43340
43491
  }
@@ -45783,7 +45934,7 @@ init_client();
45783
45934
  import { readFileSync as readFileSync4 } from "node:fs";
45784
45935
  import { PNG as PNG2 } from "pngjs";
45785
45936
  var MAX_HEIGHT = 8000;
45786
- var LLM_PROMPT_VERSION = "v3-skeleton";
45937
+ var LLM_PROMPT_VERSION = "v4-text-caution";
45787
45938
  var REPORT_VISUAL_DIFFS_TOOL = {
45788
45939
  name: "report_visual_differences",
45789
45940
  description: "Report semantic visual differences between prod and cand screenshots.",
@@ -45894,6 +46045,27 @@ REGRA DE MODAL/POPUP (importante — não confundir com rota-errada):
45894
46045
  diferente (ex: prod tem modal de login sobre fundo de login, cand mostra a
45895
46046
  home), reporte como \`missing-component\` \`critical\` — é o caso rota-errada.
45896
46047
 
46048
+ REGRA DE LEITURA DE TEXTO/NÚMEROS PEQUENOS (importante — evitar alucinação):
46049
+ - As screenshots enviadas a você podem ser reduzidas de tamanho pelo pipeline de
46050
+ ingestão de imagem antes de chegar até você. Texto pequeno — contagens de
46051
+ produtos ("42 produtos"), preços, números em badges — fica facilmente
46052
+ ilegível ou distorcido nesse processo, e um dígito lido errado (ex: "42"
46053
+ virar "142") pode parecer uma leitura confiante mesmo estando errado.
46054
+ - NÃO reporte uma diferença do tipo \`text-changed\` (ou qualquer diferença de
46055
+ contagem/número) baseada SÓ na sua leitura de um número ou texto pequeno na
46056
+ imagem. Antes de reportar, pergunte-se: "eu teria certeza desse dígito numa
46057
+ imagem menor?" Se não, não é uma diferença confiável pra reportar.
46058
+ - Se ainda assim decidir reportar uma diferença desse tipo (contagem, preço,
46059
+ texto pequeno em geral), o \`severity\` deve ser \`low\` no máximo — NUNCA
46060
+ \`critical\`, \`high\` ou \`medium\` — e o \`description\` DEVE deixar explícito
46061
+ que é uma leitura incerta, por exemplo: "contagem lida da imagem, pode ser
46062
+ leitura incorreta de texto pequeno — confirmar via DOM antes de tratar como
46063
+ regressão".
46064
+ - Essa regra NÃO se aplica a diferenças estruturais óbvias (section inteira
46065
+ faltando, componente com layout diferente, cor/imagem claramente trocada) —
46066
+ só se aplica quando o julgamento depende de ler corretamente dígitos ou
46067
+ texto pequeno.
46068
+
45897
46069
  SEVERIDADE:
45898
46070
  - critical: feature inteira faltando (header sumiu, carrinho não existe, busca quebrada visualmente), página renderizando rota errada
45899
46071
  - high: section importante diferente ou faltando (hero errado, shelf principal vazio, footer cortado)
@@ -46225,6 +46397,28 @@ async function visualRegressionKeyframes(ctx) {
46225
46397
  return b.pctDiff - a.pctDiff;
46226
46398
  });
46227
46399
  const llmTargets = new Set(useLlm ? llmCandidates.slice(0, maxLlmCalls) : []);
46400
+ const llmOutcomes = new Map;
46401
+ await Promise.all(prepared.filter((p) => !p.cacheHit && llmTargets.has(p)).map(async (p) => {
46402
+ try {
46403
+ const diffs = await visualSemanticDiff({
46404
+ prodPath: p.pair.prod.screenshotPath,
46405
+ candPath: p.pair.cand.screenshotPath,
46406
+ heatmapPath: p.heatmapWritten ? p.heatmapPath : undefined,
46407
+ pctDiff: p.pctDiff,
46408
+ pageContext: p.pair.key,
46409
+ viewport: p.pair.viewport,
46410
+ prodSections: p.prodSections,
46411
+ candSections: p.candSections,
46412
+ sectionsOnlyInProd: p.sectionsOnlyInProd,
46413
+ bothHaveCarousel: p.bothHaveCarousel,
46414
+ prodSkeletonCount: p.prodSkeletonCount,
46415
+ candSkeletonCount: p.candSkeletonCount
46416
+ });
46417
+ llmOutcomes.set(p, { differences: diffs ?? [] });
46418
+ } catch (err) {
46419
+ llmOutcomes.set(p, { error: err.message });
46420
+ }
46421
+ }));
46228
46422
  const results = [];
46229
46423
  let pagesFromCache = 0;
46230
46424
  for (const p of prepared) {
@@ -46240,24 +46434,11 @@ async function visualRegressionKeyframes(ctx) {
46240
46434
  } else if (llmTargets.has(p)) {
46241
46435
  llmCallsUsed++;
46242
46436
  llmCalled = true;
46243
- try {
46244
- const diffs = await visualSemanticDiff({
46245
- prodPath: p.pair.prod.screenshotPath,
46246
- candPath: p.pair.cand.screenshotPath,
46247
- heatmapPath: p.heatmapWritten ? p.heatmapPath : undefined,
46248
- pctDiff: p.pctDiff,
46249
- pageContext: p.pair.key,
46250
- viewport: p.pair.viewport,
46251
- prodSections: p.prodSections,
46252
- candSections: p.candSections,
46253
- sectionsOnlyInProd: p.sectionsOnlyInProd,
46254
- bothHaveCarousel: p.bothHaveCarousel,
46255
- prodSkeletonCount: p.prodSkeletonCount,
46256
- candSkeletonCount: p.candSkeletonCount
46257
- });
46258
- differences = diffs ?? [];
46259
- } catch (err) {
46260
- llmError = err.message;
46437
+ const outcome = llmOutcomes.get(p);
46438
+ if (outcome?.error !== undefined) {
46439
+ llmError = outcome.error;
46440
+ } else {
46441
+ differences = outcome?.differences ?? [];
46261
46442
  }
46262
46443
  }
46263
46444
  if (differences.length > 0) {
@@ -50231,6 +50412,9 @@ function isResolutionContext(v) {
50231
50412
  }
50232
50413
 
50233
50414
  // src/engine/flows/shared.ts
50415
+ async function captureInpSnapshot(page, cap) {
50416
+ cap.vitals = mergeInpSnapshot(cap.vitals, await readVitalsSnapshot(page));
50417
+ }
50234
50418
  async function screenshotStable(page, opts) {
50235
50419
  await Promise.race([
50236
50420
  stabilizeCarousels(page).catch(() => {
@@ -52172,6 +52356,7 @@ async function flowPurchaseJourney(ctx) {
52172
52356
  recoveredByLlm: miniRecovered || undefined
52173
52357
  });
52174
52358
  reportEnd(7, "open-minicart", step7Status, Date.now() - t7, step7QuirkNote ?? step7RevealFailureNote);
52359
+ await captureInpSnapshot(page, pdpCap);
52175
52360
  if (isProdCartEmptyQuirk) {
52176
52361
  const quirkNote = "cart-empty-prod-quirk: skipped (depende do cart que prod não persistiu)";
52177
52362
  reportStart(8, "shipping-calc-cart");
@@ -52906,6 +53091,7 @@ async function flowCartInteractions(ctx) {
52906
53091
  reportEnd(4, "read-baseline", "ok", Date.now() - t4);
52907
53092
  reportStart(5, "verify-cart-persistence");
52908
53093
  const t4b = Date.now();
53094
+ await captureInpSnapshot(page, pages[pages.length - 1]);
52909
53095
  await page.reload({ waitUntil: "load" }).catch(() => {
52910
53096
  return;
52911
53097
  });
@@ -53321,6 +53507,7 @@ async function flowCartInteractions(ctx) {
53321
53507
  });
53322
53508
  await screenshotStable(page, { path: screenshotPath(ctx, "cart-9-empty") });
53323
53509
  reportEnd(13, "verify-empty-state", emptyStatus, Date.now() - t9);
53510
+ await captureInpSnapshot(page, pages[pages.length - 1]);
53324
53511
  } finally {
53325
53512
  await page.close().catch(() => {
53326
53513
  return;
@@ -53485,6 +53672,7 @@ async function flowLogin(ctx) {
53485
53672
  });
53486
53673
  await screenshotStable(page, { path: screenshotPath(ctx, "login-3-invalid") });
53487
53674
  reportEnd(3, "submit-invalid", errorShown ? "ok" : "failed", Date.now() - t3);
53675
+ await captureInpSnapshot(page, homeCap);
53488
53676
  reportStart(4, "submit-valid");
53489
53677
  const t4 = Date.now();
53490
53678
  const emailHit2 = await firstVisibleLocator(page, selFor(ctx, "loginEmailInput"));
@@ -54606,6 +54794,7 @@ async function flowSpaNavigation(ctx) {
54606
54794
  const urlChanged = afterUrl !== beforeUrl;
54607
54795
  const markerSurvived = await withCap(page.evaluate(() => window.__parity_nav_marker !== undefined).catch(() => false), 1500, false);
54608
54796
  const navType = classifyNavigationType({ urlChanged, markerSurvived });
54797
+ await captureInpSnapshot(page, cap1);
54609
54798
  const hydrationEntries = consoleDuringNav.filter((e) => e.type === "error" && classify(e) === "hydration");
54610
54799
  const navScreenshot = screenshotPath(ctx, "spa-nav-after-click");
54611
54800
  await screenshotStable(page, { path: navScreenshot });
@@ -59089,9 +59278,18 @@ var PRESETS = {
59089
59278
  only: "e2e,html,console"
59090
59279
  }
59091
59280
  };
59281
+ function pagesFlowsScopeWarning(opts, flows2) {
59282
+ if (!opts.pages && !opts.pagesFile)
59283
+ return null;
59284
+ if (flows2.length === 0)
59285
+ return null;
59286
+ return `--pages/--pages-file only scope the visual-diff/vitals passes — the flows crawl (${flows2.join(",")}) discovers its own pages; use --flows or .parityrc.json *UrlHint overrides to scope that.`;
59287
+ }
59092
59288
  function applySmartDefaults(opts, llmAvailable) {
59093
59289
  if (llmAvailable)
59094
59290
  return opts;
59291
+ if (opts.pages || opts.pagesFile)
59292
+ return opts;
59095
59293
  const merged = { ...opts };
59096
59294
  const COMMANDER_DEFAULTS = {
59097
59295
  visualPages: 5
@@ -59164,6 +59362,16 @@ function applyLlmOptions(opts) {
59164
59362
  }
59165
59363
  return null;
59166
59364
  }
59365
+ function evaluateFailOnGate(allIssues, failOn) {
59366
+ const blocking = allIssues.filter((i) => failOn.includes(i.severity));
59367
+ if (blocking.length === 0)
59368
+ return { exitCode: 0 };
59369
+ return {
59370
+ exitCode: 1,
59371
+ message: `
59372
+ ✖ ${blocking.length} issue(s) bloqueante(s) [${failOn.join(", ")}] — exit 1`
59373
+ };
59374
+ }
59167
59375
  async function runCommand(rawOpts) {
59168
59376
  if (!rawOpts.prod) {
59169
59377
  const target = rawOpts.cand ?? "<url>";
@@ -59224,6 +59432,10 @@ async function runCommand(rawOpts) {
59224
59432
  console.log(chalk17.dim(" no --only/--skip given — running ALL modules; pass --only to scope the run for a lighter/faster result"));
59225
59433
  }
59226
59434
  }
59435
+ const pagesScopeWarning = pagesFlowsScopeWarning(opts, flows2);
59436
+ if (pagesScopeWarning) {
59437
+ console.log(chalk17.dim(` ${pagesScopeWarning}`));
59438
+ }
59227
59439
  if (hasSelection) {
59228
59440
  const needsSitemapPages = selection.modules.some((m) => MODULES[m].needsSitemapPages);
59229
59441
  const needsLlmPass = selection.modules.some((m) => MODULES[m].needsLlm);
@@ -59297,8 +59509,9 @@ async function runCommand(rawOpts) {
59297
59509
  let promotedCount = 0;
59298
59510
  let deprecatedCount = 0;
59299
59511
  const wantsAutoSelectors = opts.autoSelectors !== false && isLlmAvailable();
59512
+ let discoveryBrowser = null;
59300
59513
  if (wantsAutoSelectors) {
59301
- await runSelectorDiscoveryPass({
59514
+ discoveryBrowser = await runSelectorDiscoveryPass({
59302
59515
  url: opts.prod,
59303
59516
  viewport: primaryViewport,
59304
59517
  rc,
@@ -59358,7 +59571,17 @@ async function runCommand(rawOpts) {
59358
59571
  let currentPhase = "launch";
59359
59572
  let shuttingDown = false;
59360
59573
  const partialChecks = [];
59361
- const shutdown = (reason) => {
59574
+ const forceCloseBrowser = async (b, capMs) => {
59575
+ if (!b)
59576
+ return;
59577
+ await Promise.race([
59578
+ b.close().catch(() => {
59579
+ return;
59580
+ }),
59581
+ new Promise((resolve4) => setTimeout(resolve4, capMs))
59582
+ ]);
59583
+ };
59584
+ const shutdown = async (reason) => {
59362
59585
  if (shuttingDown) {
59363
59586
  process.stderr.write(`
59364
59587
  segunda interrupção — forçando saída.
@@ -59399,11 +59622,7 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
59399
59622
  process.stderr.write(` falha escrevendo report parcial: ${err.message}
59400
59623
  `);
59401
59624
  }
59402
- if (browser) {
59403
- browser.close().catch(() => {
59404
- return;
59405
- });
59406
- }
59625
+ await forceCloseBrowser(browser, 3000);
59407
59626
  process.exit(130);
59408
59627
  };
59409
59628
  const onSignal = (sig) => {
@@ -59417,7 +59636,7 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
59417
59636
  }, timeoutMinutes * 60000);
59418
59637
  globalTimeoutTimer.unref?.();
59419
59638
  try {
59420
- browser = await launchBrowser({ headless: true });
59639
+ browser = discoveryBrowser ?? await launchBrowser({ headless: true });
59421
59640
  if (opts.warmup) {
59422
59641
  const warmupSpinner = ora6("Warmup: bustando cache em prod + cand…").start();
59423
59642
  const result = await warmupTargets({
@@ -59435,14 +59654,15 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
59435
59654
  warmupSpinner.fail(`Warmup falhou — 0/${result.attempted} requests ok. Cache pode estar stale. Primeira falha: ${firstReason}`);
59436
59655
  }
59437
59656
  }
59657
+ const traceEnabled = process.env.PARITY_TRACE === "1";
59438
59658
  const runOneSide = async (viewport, side) => {
59439
59659
  const baseUrl = side === "prod" ? opts.prod : opts.cand;
59440
59660
  const harPath = join18(paths.harDir, `${viewport}-${side}.har`);
59441
- const tracePath = join18(paths.tracesDir, `${viewport}-${side}.zip`);
59661
+ const tracePath = traceEnabled ? join18(paths.tracesDir, `${viewport}-${side}.zip`) : null;
59442
59662
  const ctx = await newContext(browser, {
59443
59663
  viewport,
59444
59664
  harPath,
59445
- tracesDir: paths.tracesDir,
59665
+ tracesDir: traceEnabled ? paths.tracesDir : undefined,
59446
59666
  cohortCookieValue: "control",
59447
59667
  noCache: opts.bypassCache
59448
59668
  });
@@ -59503,9 +59723,10 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
59503
59723
  pages.push(p);
59504
59724
  }
59505
59725
  } finally {
59506
- await stopTracing(ctx, tracePath).catch(() => {
59507
- return;
59508
- });
59726
+ if (tracePath)
59727
+ await stopTracing(ctx, tracePath).catch(() => {
59728
+ return;
59729
+ });
59509
59730
  await ctx.close();
59510
59731
  }
59511
59732
  return { captures, pages };
@@ -59550,6 +59771,7 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
59550
59771
  const candIsDevServer = isLocalhost(opts.cand);
59551
59772
  const vitalsPagesDefault = candIsDevServer ? 3 : 10;
59552
59773
  const vitalsPagesLimit = opts.vitalsPages ?? vitalsPagesDefault;
59774
+ const vitalsRuns = Math.max(1, Number.parseInt(opts.runs, 10) || 1);
59553
59775
  if (candIsDevServer && vitalsPagesLimit > 0) {
59554
59776
  console.log(chalk17.dim(` cand=localhost detectado — vitals-pages=${vitalsPagesLimit}, networkidle desabilitado (issue #55)`));
59555
59777
  }
@@ -59608,7 +59830,7 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
59608
59830
  const baseUrl = task.side === "prod" ? opts.prod : opts.cand;
59609
59831
  const fullUrl = new URL(task.path, baseUrl).toString();
59610
59832
  const targetIsDevServer = isLocalhost(baseUrl);
59611
- const PER_TASK_WALLCLOCK_MS = 35000;
59833
+ const PER_TASK_WALLCLOCK_MS = 35000 + Math.max(0, vitalsRuns - 1) * 8000;
59612
59834
  try {
59613
59835
  const ctx = await newContext(browser, {
59614
59836
  viewport: task.viewport,
@@ -59629,7 +59851,8 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
59629
59851
  fast: true,
59630
59852
  scrollToLoad: false,
59631
59853
  skipScreenshot: true,
59632
- noNetworkIdle: targetIsDevServer
59854
+ noNetworkIdle: targetIsDevServer,
59855
+ runs: vitalsRuns
59633
59856
  }),
59634
59857
  new Promise((resolve4) => {
59635
59858
  const t = setTimeout(() => resolve4(null), PER_TASK_WALLCLOCK_MS);
@@ -59871,13 +60094,10 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
59871
60094
  printSummary5(run, paths.reportHtml, { promotedCount, deprecatedCount, platform });
59872
60095
  console.log(`
59873
60096
  ${formatTimingsSummary(runTimings, buildFlowBreakdown(allFlowCaptures))}`);
59874
- if (opts.ci) {
59875
- const blocking = allIssues.filter((i) => failOn.includes(i.severity));
59876
- if (blocking.length > 0) {
59877
- console.log(chalk17.red(`
59878
- ✖ ${blocking.length} issue(s) bloqueante(s) [${failOn.join(", ")}] — exit 1`));
59879
- return 1;
59880
- }
60097
+ const failOnGate = evaluateFailOnGate(allIssues, failOn);
60098
+ if (failOnGate.exitCode === 1) {
60099
+ console.log(chalk17.red(failOnGate.message));
60100
+ return 1;
59881
60101
  }
59882
60102
  if (opts.open) {
59883
60103
  if (browser) {
@@ -60147,7 +60367,6 @@ async function prCommand(opts) {
60147
60367
  cep: "01310-100",
60148
60368
  runs: "1",
60149
60369
  output: opts.output,
60150
- ci: true,
60151
60370
  failOn: "critical,high",
60152
60371
  preset: opts.preset ?? "ci",
60153
60372
  open: false
@@ -60343,7 +60562,7 @@ function extractVitalsSlice(run) {
60343
60562
  if (!p.vitals)
60344
60563
  continue;
60345
60564
  const k = `${p.side}::${p.viewport}::${pathOf4(p.url)}`;
60346
- out[k] = p.vitals;
60565
+ out[k] = p.vitalsFullPage ? { ...p.vitals, fullPage: p.vitalsFullPage } : p.vitals;
60347
60566
  }
60348
60567
  }
60349
60568
  return out;
@@ -60488,7 +60707,7 @@ async function vitalsCommand(opts) {
60488
60707
  await runWithConcurrency3(tasks, concurrency, async (task) => {
60489
60708
  const url = new URL(task.path, task.side === "prod" ? opts.prod : opts.cand).toString();
60490
60709
  try {
60491
- task.capture = await captureVitalsPage(browser, task.viewport, task.side, url, paths.screenshotsDir);
60710
+ task.capture = await captureVitalsPage(browser, task.viewport, task.side, url, paths.screenshotsDir, opts.runs);
60492
60711
  } catch (err) {
60493
60712
  task.error = err.message;
60494
60713
  } finally {
@@ -60591,7 +60810,7 @@ async function vitalsCommand(opts) {
60591
60810
  });
60592
60811
  }
60593
60812
  }
60594
- async function captureVitalsPage(browser, viewport, side, url, screenshotsDir) {
60813
+ async function captureVitalsPage(browser, viewport, side, url, screenshotsDir, runs) {
60595
60814
  const ctx = await newContext(browser, { viewport, cohortCookieValue: "control" });
60596
60815
  await installVitalsCollector(ctx);
60597
60816
  const page = await ctx.newPage();
@@ -60606,7 +60825,8 @@ async function captureVitalsPage(browser, viewport, side, url, screenshotsDir) {
60606
60825
  timeoutMs: 20000,
60607
60826
  scrollToLoad: false,
60608
60827
  skipScreenshot: true,
60609
- fast: true
60828
+ fast: true,
60829
+ runs
60610
60830
  });
60611
60831
  } finally {
60612
60832
  await page.close().catch(() => {
@@ -60716,16 +60936,16 @@ program.command("run").description([
60716
60936
  " flows=purchase-journey, viewports=mobile,desktop, vitals-pages=10,",
60717
60937
  " visual-pages=5 (auto-zeroed when no LLM provider available),",
60718
60938
  " auto-selectors=ON (if LLM), learn=ON, cache=ON, visual-diff=ON,",
60719
- " warmup=OFF, bypass-cache=OFF, ci=OFF."
60939
+ " warmup=OFF, bypass-cache=OFF, fail-on=critical (exit 1 if hit)."
60720
60940
  ].join(`
60721
- `)).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("--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("--ci", "CI mode: stricter exit codes", false).option("--fail-on <severities>", "Comma-separated severities that cause exit 1", "critical").option("--open", "Open the HTML report after the run completes", 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 (default 10)", (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 via 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 this when you want deterministic coverage instead of sampled.').option("--pages-file <path>", "Read paths to compare visually from a text file (one path per line). Lines starting with # are ignored. Overrides --pages when both are present.").option("--no-visual-diff", "Skip the visual diff capture pass entirely").option("--no-cache", "Disable the cross-run visual-diff cache (forces a fresh LLM judgment on every page).").option("--clear-cache", "Wipe the visual-diff verdict cache (parity-output/cache/verdicts.json) before the run.", false).option("--bypass-cache", "Bypass CDN/edge caches: append a cache-busting query param and send Cache-Control: no-cache on every request. Use right after a deploy to avoid false failures from stale CF edge content.", 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("--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("--llm-timeout <seconds>", "Hard timeout for the LLM aggregation call (seconds). The run completes in offline mode if the LLM hangs past this. Default: 60.", (v) => Number(v), 60).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-4-7,explain=claude-opus-4-7. Features: selector-discovery, step-recovery, search-terms, plp-matching, pdp-matching, section-understanding, visual-diff, issue-aggregation, 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("--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.").action(async (opts) => {
60941
+ `)).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("--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("--open", "Open the HTML report after the run completes", 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 via 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 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 path per line). Lines starting with # are ignored. 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", "Disable the cross-run visual-diff cache (forces a fresh LLM judgment on every page).").option("--clear-cache", "Wipe the visual-diff verdict cache (parity-output/cache/verdicts.json) before the run.", 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("--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("--llm-timeout <seconds>", "Hard timeout for the LLM aggregation call (seconds). The run completes in offline mode if the LLM hangs past this. Default: 60.", (v) => Number(v), 60).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-4-7,explain=claude-opus-4-7. Features: selector-discovery, step-recovery, search-terms, plp-matching, pdp-matching, section-understanding, visual-diff, issue-aggregation, 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("--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.").action(async (opts) => {
60722
60942
  if (opts.flow) {
60723
60943
  opts.flows = opts.flow;
60724
60944
  }
60725
60945
  const code = await runCommand(opts);
60726
60946
  process.exit(code);
60727
60947
  });
60728
- program.command("audit").description("Single-site absolute audit. Runs console + vitals + network + images + SEO checks on ONE URL (no prod×cand comparison) and outputs a focused HTML report. Use for pre-launch or post-deploy 'what's broken right now' verification.").requiredOption("--url <url>", "Base URL (e.g. https://miess-tanstack.deco-cx.workers.dev)").option("--viewport <viewport>", "mobile | desktop | tablet", "mobile").option("--pages <list>", "Comma-separated paths to audit (default: /)", "/").option("--output <dir>", "Output directory", "./parity-output").option("--open", "Open the HTML report after the run completes", false).option("--json", "Emit one-line JSON instead of pretty text", false).option("--fail-on <severities>", "Comma-separated severities that cause exit 1 (default: critical,high)", "critical,high").option("--pt", "Tell the LLM to respond in Brazilian Portuguese. Issue #67.").action(async (opts) => {
60948
+ program.command("audit").description("Single-site absolute audit. Runs console + vitals + network + images + SEO checks on ONE URL (no prod×cand comparison) and outputs a focused HTML report. Use for pre-launch or post-deploy 'what's broken right now' verification.").requiredOption("--url <url>", "Base URL (e.g. https://miess-tanstack.deco-cx.workers.dev)").option("--viewport <viewport>", "mobile | desktop | tablet", "mobile").option("--pages <list>", "Comma-separated paths to audit (default: /)", "/").option("--output <dir>", "Output directory", "./parity-output").option("--open", "Open the HTML report after the run completes", false).option("--json", "Emit one-line JSON instead of pretty text", false).option("--fail-on <severities>", "Comma-separated severities that cause exit 1 (default: critical,high)", "critical,high").option("--runs <n>", "Repeat the Web Vitals navigation N times per page and audit against the median (reduces run-to-run jitter false positives). Default 1 (no repeat). Issue #179.", (v) => Number(v), 1).option("--pt", "Tell the LLM to respond in Brazilian Portuguese. Issue #67.").action(async (opts) => {
60729
60949
  if (opts.pt) {
60730
60950
  const { setLlmLanguage: setLlmLanguage2 } = await Promise.resolve().then(() => (init_client(), exports_client));
60731
60951
  setLlmLanguage2("pt");
@@ -60777,7 +60997,7 @@ program.command("pr").description("CI/CD entry point: compare a PR preview URL a
60777
60997
  program.command("cache").description("Cache analysis focused on cand. Crawls N pages (lighter than `vitals`: no screenshots, no vitals, no scroll), groups requests by category, lists MISS-asset opportunities.").requiredOption("--prod <url>", "Production URL (optional reference)").requiredOption("--cand <url>", "Candidate URL (foco)").option("--urls <list-or-file>", "Comma-separated paths or .txt file (1/line). Overrides sitemap.").option("--pages <n>", "Max pages to crawl from sitemap", (v) => Number(v), 30).option("--viewports <list>", "mobile,desktop", "mobile").option("--concurrency <n>", "Parallel workers (1-8)", (v) => Number(v), 6).option("--cand-only", "Skip prod entirely (faster, no comparison)", false).option("--output <dir>", "Output directory", "./parity-output").option("--open", "Open the HTML report when done", false).action(async (opts) => {
60778
60998
  process.exit(await cacheCommand(opts));
60779
60999
  });
60780
- program.command("vitals").description("Crawls multiple pages (via sitemap.xml or --urls) and compares Web Vitals prod vs cand on each. HTML output with the top worst/best expanded.").requiredOption("--prod <url>", "Production URL (base)").requiredOption("--cand <url>", "Candidate URL (base)").option("--urls <list-or-file>", "Comma-separated paths or .txt file (1/line). Overrides sitemap discovery.").option("--limit <n>", "Max pages discovered from sitemap.xml", (v) => Number(v), 20).option("--viewports <list>", "mobile,desktop", "mobile").option("--concurrency <n>", "Parallel workers (1-8)", (v) => Number(v), 4).option("--output <dir>", "Output directory", "./parity-output").option("--open", "Open the HTML report when done", false).action(async (opts) => {
61000
+ program.command("vitals").description("Crawls multiple pages (via sitemap.xml or --urls) and compares Web Vitals prod vs cand on each. HTML output with the top worst/best expanded.").requiredOption("--prod <url>", "Production URL (base)").requiredOption("--cand <url>", "Candidate URL (base)").option("--urls <list-or-file>", "Comma-separated paths or .txt file (1/line). Overrides sitemap discovery.").option("--limit <n>", "Max pages discovered from sitemap.xml", (v) => Number(v), 20).option("--viewports <list>", "mobile,desktop", "mobile").option("--concurrency <n>", "Parallel workers (1-8)", (v) => Number(v), 4).option("--runs <n>", "Repeat each page's vitals navigation N times and compare against the median (reduces run-to-run jitter false positives). Default 1 (no repeat). Issue #179.", (v) => Number(v), 1).option("--output <dir>", "Output directory", "./parity-output").option("--open", "Open the HTML report when done", false).action(async (opts) => {
60781
61001
  process.exit(await vitalsCommand(opts));
60782
61002
  });
60783
61003
  program.command("journey").description("CI-friendly: runs only the purchase journey (home → PLP → PDP → shipping → cart → cart shipping → checkout) and compares prod vs cand step by step.").requiredOption("--prod <url>", "Production URL").requiredOption("--cand <url>", "Candidate URL").option("--viewports <list>", "mobile,desktop", "mobile").option("--cep <cep>", "CEP for shipping calc", "01310-100").option("--output <dir>", "Output directory for runs/<id>/", "./parity-output").option("--junit <file>", "Write JUnit XML to this path").option("--github", "Emit GitHub Actions annotations (::error, ::warning) for failures").option("--json", "Emit a one-line JSON status object to stdout (machine-readable)").option("--no-report", "Skip writing report.html / report.json").option("--no-auto-selectors", "Skip LLM-based selector discovery").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("--pt", "Tell the LLM to respond in Brazilian Portuguese. Issue #67.").action(async (opts) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@decocms/parity",
3
- "version": "0.17.8",
3
+ "version": "0.17.9",
4
4
  "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.",
5
5
  "type": "module",
6
6
  "license": "MIT",