@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 +1 -0
- package/CHANGELOG.md +8 -0
- package/dist/cli.js +183 -7
- package/package.json +1 -1
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
|
|
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
|
|
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.
|
|
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",
|