@decocms/parity 0.26.13 → 0.26.15

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.
Files changed (2) hide show
  1. package/dist/cli.js +187 -14
  2. package/package.json +1 -1
package/dist/cli.js CHANGED
@@ -41598,6 +41598,12 @@ var ModuleVerdict = z.object({
41598
41598
  checksRun: z.number(),
41599
41599
  pagesAnalyzed: z.number()
41600
41600
  });
41601
+ var RunCaveat = z.object({
41602
+ id: z.string(),
41603
+ level: z.enum(["warn", "info"]),
41604
+ summary: z.string(),
41605
+ detail: z.string()
41606
+ });
41601
41607
  var Run = z.object({
41602
41608
  schemaVersion: z.literal("0.1"),
41603
41609
  id: z.string(),
@@ -41631,6 +41637,7 @@ var Run = z.object({
41631
41637
  }).optional(),
41632
41638
  partial: z.boolean().optional(),
41633
41639
  partialReason: z.string().optional(),
41640
+ caveats: z.array(RunCaveat).optional(),
41634
41641
  timings: z.object({
41635
41642
  totalMs: z.number(),
41636
41643
  phases: z.array(z.object({ phase: z.string(), durationMs: z.number() }))
@@ -41716,8 +41723,13 @@ var ParityRc = z.object({
41716
41723
  addToCartConfirmMs: z.number().optional(),
41717
41724
  cartRevealTimeoutMs: z.number().optional()
41718
41725
  });
41726
+ var ExpectedDivergence = z.object({
41727
+ match: z.string(),
41728
+ note: z.string()
41729
+ });
41719
41730
  var ParityIgnore = z.object({
41720
41731
  ignoreSelectorsVisual: z.array(z.string()).default([]),
41732
+ expectedDivergences: z.array(ExpectedDivergence).optional(),
41721
41733
  ignoreRequestPatterns: z.array(z.string()).default([]),
41722
41734
  ignoreConsolePatterns: z.array(z.string()).default([]),
41723
41735
  ignoreMetaKeys: z.array(z.string()).default([]),
@@ -50529,6 +50541,10 @@ async function ssrNoJs(ctx) {
50529
50541
  }
50530
50542
  const prodHome = pickHome5(ctx.prodPages);
50531
50543
  const prodText = prodHome ? await fetchSsrText(prodHome.finalUrl) : null;
50544
+ const candIsDevServer = isLocalhost(candHome.finalUrl);
50545
+ const devServerNote = candIsDevServer ? `
50546
+
50547
+ ⚠ Medido contra um dev server, onde várias frameworks renderizam client-side por padrão. Reconfirme num build de produção antes de tratar isto como defeito.` : "";
50532
50548
  if (candText.length < 200) {
50533
50549
  issues.push({
50534
50550
  id: "ssr:blank",
@@ -50536,7 +50552,8 @@ async function ssrNoJs(ctx) {
50536
50552
  category: "functional",
50537
50553
  check: "ssr-no-js",
50538
50554
  summary: `SSR do candidato rende só ${candText.length} chars de texto — página em branco sem JS (CLS alto, SEO/acessibilidade quebrados)`,
50539
- details: "Todo o conteúdo carrega client-side. Marque seções above-the-fold com `export const neverDefer = true` ou adicione LoadingFallback."
50555
+ details: `Todo o conteúdo carrega client-side. Marque seções above-the-fold com \`export const neverDefer = true\` ou adicione LoadingFallback.${devServerNote}`,
50556
+ ...candIsDevServer ? { inconclusive: true } : {}
50540
50557
  });
50541
50558
  } else if (prodText !== null && prodText.length > 0 && candText.length < prodText.length * 0.3) {
50542
50559
  issues.push({
@@ -50544,10 +50561,11 @@ async function ssrNoJs(ctx) {
50544
50561
  severity: "high",
50545
50562
  category: "functional",
50546
50563
  check: "ssr-no-js",
50547
- summary: `SSR do candidato tem <30% do texto do prod (${candText.length} vs ${prodText.length} chars) — maioria do conteúdo é client-only`
50564
+ summary: `SSR do candidato tem <30% do texto do prod (${candText.length} vs ${prodText.length} chars) — maioria do conteúdo é client-only`,
50565
+ ...candIsDevServer ? { inconclusive: true, details: devServerNote.trim() } : {}
50548
50566
  });
50549
50567
  }
50550
- const status = issues.some((i) => i.severity === "critical") ? "fail" : issues.length > 0 ? "warn" : "pass";
50568
+ const status = issues.some((i) => i.severity === "critical" && !i.inconclusive) ? "fail" : issues.length > 0 ? "warn" : "pass";
50551
50569
  return {
50552
50570
  name: "ssr-no-js",
50553
50571
  status,
@@ -53240,6 +53258,35 @@ async function visualSemanticDiff(input) {
53240
53258
  }));
53241
53259
  }
53242
53260
 
53261
+ // src/diff/expected-divergence.ts
53262
+ function matchExpectedDivergence(haystacks, expected) {
53263
+ if (expected.length === 0)
53264
+ return null;
53265
+ const text3 = haystacks.filter((h) => Boolean(h)).join(" ").toLowerCase();
53266
+ if (!text3)
53267
+ return null;
53268
+ for (const e of expected) {
53269
+ const needle = e.match.trim().toLowerCase();
53270
+ if (!needle)
53271
+ continue;
53272
+ if (text3.includes(needle))
53273
+ return e;
53274
+ }
53275
+ return null;
53276
+ }
53277
+ function partitionExpectedSections(sections, expected) {
53278
+ const reportable = [];
53279
+ const accepted = [];
53280
+ for (const section of sections) {
53281
+ const hit = matchExpectedDivergence([section], expected);
53282
+ if (hit)
53283
+ accepted.push({ section, note: hit.note });
53284
+ else
53285
+ reportable.push(section);
53286
+ }
53287
+ return { reportable, accepted };
53288
+ }
53289
+
53243
53290
  // src/checks/lib/parity-cache.ts
53244
53291
  import { createHash as createHash2 } from "node:crypto";
53245
53292
  import { existsSync as existsSync7, mkdirSync as mkdirSync7, readFileSync as readFileSync10, writeFileSync as writeFileSync9 } from "node:fs";
@@ -53388,6 +53435,7 @@ async function visualRegressionKeyframes(ctx) {
53388
53435
  const diffDir = join12(ctx.outDir, "screenshots");
53389
53436
  if (!existsSync8(diffDir))
53390
53437
  mkdirSync8(diffDir, { recursive: true });
53438
+ const expectedDivergences = ctx.ignore.expectedDivergences ?? [];
53391
53439
  const useLlm = isLlmAvailable();
53392
53440
  const maxLlmCalls = getMaxLlmCalls();
53393
53441
  let llmCallsUsed = 0;
@@ -53560,16 +53608,30 @@ async function visualRegressionKeyframes(ctx) {
53560
53608
  llmError,
53561
53609
  cachedAt
53562
53610
  });
53563
- if (p.sectionsOnlyInProd.length > 0) {
53611
+ const sectionSplit = partitionExpectedSections(p.sectionsOnlyInProd, expectedDivergences);
53612
+ if (sectionSplit.accepted.length > 0) {
53613
+ issues.push({
53614
+ id: `visual:sections-expected:${p.pair.key}`,
53615
+ severity: "low",
53616
+ category: "visual",
53617
+ page: p.pair.key,
53618
+ check: "visual-regression-keyframes",
53619
+ inconclusive: true,
53620
+ summary: `${sectionSplit.accepted.length} section(s) ausente(s) em cand por decisão: ${sectionSplit.accepted.map((a) => a.section).join(", ")}`,
53621
+ details: sectionSplit.accepted.map((a) => `- ${a.section}: ${a.note}`).join(`
53622
+ `)
53623
+ });
53624
+ }
53625
+ if (sectionSplit.reportable.length > 0) {
53564
53626
  issues.push({
53565
53627
  id: `visual:sections:${p.pair.key}`,
53566
53628
  severity: "high",
53567
53629
  category: "visual",
53568
53630
  page: p.pair.key,
53569
53631
  check: "visual-regression-keyframes",
53570
- summary: `${p.sectionsOnlyInProd.length} section(s) ausente(s) em cand: ${p.sectionsOnlyInProd.join(", ")}`,
53632
+ summary: `${sectionSplit.reportable.length} section(s) ausente(s) em cand: ${sectionSplit.reportable.join(", ")}`,
53571
53633
  details: `Sections detectadas no DOM de prod via data-section, mas ausentes em cand:
53572
- ${p.sectionsOnlyInProd.map((s) => `- ${s}`).join(`
53634
+ ${sectionSplit.reportable.map((s) => `- ${s}`).join(`
53573
53635
  `)}
53574
53636
 
53575
53637
  Provavelmente faltam em registerSections() em src/setup.ts, ou o CMS não está resolvendo essas keys em cand.`,
@@ -53581,16 +53643,20 @@ Provavelmente faltam em registerSections() em src/setup.ts, ou o CMS não está
53581
53643
  });
53582
53644
  }
53583
53645
  for (const [i, d] of differences.entries()) {
53646
+ const accepted = matchExpectedDivergence([d.description, d.region], expectedDivergences);
53584
53647
  issues.push({
53585
53648
  id: `visual:semantic:${p.pair.key}:${i}`,
53586
- severity: severityForDiff(d),
53649
+ severity: accepted ? "low" : severityForDiff(d),
53587
53650
  category: "visual",
53588
53651
  page: p.pair.key,
53589
53652
  check: "visual-regression-keyframes",
53590
- summary: `[${d.region}] ${d.description}`,
53653
+ ...accepted ? { inconclusive: true } : {},
53654
+ summary: `[${d.region}] ${d.description}${accepted ? " (divergência esperada)" : ""}`,
53591
53655
  details: `Tipo: ${d.type}
53592
53656
  Região: ${d.region}
53593
- Severidade: ${d.severity}`,
53657
+ Severidade: ${d.severity}${accepted ? `
53658
+
53659
+ Decisão registrada: ${accepted.note}` : ""}`,
53594
53660
  evidence: [
53595
53661
  { kind: "screenshot", path: p.pair.prod.screenshotPath, label: "prod" },
53596
53662
  { kind: "screenshot", path: p.pair.cand.screenshotPath, label: "cand" },
@@ -55884,6 +55950,7 @@ function renderHtmlReport(run, runDir) {
55884
55950
  </div>
55885
55951
  </header>
55886
55952
  ${run.partial ? `<div style="background:#7c2d12;color:#fed7aa;padding:12px 24px;border-bottom:2px solid #ea580c;font-weight:600">⚠ Partial run — interrupted${run.partialReason ? ` (${escapeHtml(run.partialReason)})` : ""}. Verdict, top-issues, and some sections may be incomplete.</div>` : ""}
55953
+ ${renderCaveats(run)}
55887
55954
  ${countHiddenLlmTabs(run) > 0 ? `<div class="llm-disabled-banner">LLM disabled — ${countHiddenLlmTabs(run)} tab${countHiddenLlmTabs(run) !== 1 ? "s" : ""} hidden (Visual Diff, LLM Prompt). Set <code>ANTHROPIC_API_KEY</code> or log in to the local <code>claude</code> CLI and re-run for semantic analysis.</div>` : ""}
55888
55955
  ${renderTimingsBar(run)}
55889
55956
  <main class="app-main">
@@ -55983,6 +56050,19 @@ function renderTimingsBar(run) {
55983
56050
  <div style="display:flex;flex-direction:column;gap:4px">${rows}</div>
55984
56051
  </div>`;
55985
56052
  }
56053
+ function renderCaveats(run) {
56054
+ const caveats = run.caveats ?? [];
56055
+ if (caveats.length === 0)
56056
+ return "";
56057
+ const rows = caveats.map((c) => {
56058
+ const warn = c.level === "warn";
56059
+ return `<li style="margin:4px 0"><b style="color:${warn ? "#fca5a5" : "#93c5fd"}">${warn ? "⚠" : "ℹ"} ${escapeHtml(c.summary)}</b> <span style="opacity:.85">— ${escapeHtml(c.detail)}</span></li>`;
56060
+ }).join("");
56061
+ return `<div style="background:#1c1917;color:#e7e5e4;padding:12px 24px;border-bottom:1px solid #44403c;font-size:13px">
56062
+ <div style="font-weight:600;margin-bottom:4px">Como ler este run</div>
56063
+ <ul style="margin:0;padding-left:18px;list-style:none">${rows}</ul>
56064
+ </div>`;
56065
+ }
55986
56066
 
55987
56067
  // src/commands/cache.ts
55988
56068
  async function cacheCommand(opts) {
@@ -65512,6 +65592,84 @@ function formatSecs(ms) {
65512
65592
  return `${min}m${sec.toString().padStart(2, "0")}s`;
65513
65593
  }
65514
65594
 
65595
+ // src/engine/run-context.ts
65596
+ function detectRunCaveats(input) {
65597
+ const out = [];
65598
+ if (isLocalhost(input.candUrl)) {
65599
+ out.push({
65600
+ id: "cand-dev-server",
65601
+ level: "warn",
65602
+ summary: "Candidato medido num dev server",
65603
+ 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."
65604
+ });
65605
+ }
65606
+ if (isLocalhost(input.prodUrl)) {
65607
+ out.push({
65608
+ id: "prod-dev-server",
65609
+ level: "warn",
65610
+ summary: "Referência (prod) medida num dev server",
65611
+ detail: "O lado de referência também é local, então a comparação mede duas máquinas de desenvolvimento — útil para regressão relativa, não para números absolutos."
65612
+ });
65613
+ }
65614
+ const mismatched = pairedPathMismatches(input.prodPages, input.candPages);
65615
+ if (mismatched.length > 0) {
65616
+ out.push({
65617
+ id: "paths-differ",
65618
+ level: "warn",
65619
+ summary: `${mismatched.length} página(s) comparadas em caminhos diferentes`,
65620
+ detail: `Os dois lados não estão no mesmo conteúdo (${mismatched.slice(0, 3).join(", ")}${mismatched.length > 3 ? "…" : ""}). O módulo visual vai apontar diferenças que são de produto, não de migração — leia estrutura e hierarquia, não conteúdo.`
65621
+ });
65622
+ }
65623
+ if (!input.llmEnabled) {
65624
+ out.push({
65625
+ id: "llm-disabled",
65626
+ level: "info",
65627
+ summary: "Sem provedor de LLM — módulos visuais não rodaram",
65628
+ detail: "Visual diff e ranking de issues dependem de LLM. Sem provedor configurado eles são pulados, então a ausência de achados visuais não significa paridade visual."
65629
+ });
65630
+ }
65631
+ const skipped = input.verdict?.checksSkipped ?? 0;
65632
+ if (skipped > 0) {
65633
+ out.push({
65634
+ id: "checks-skipped",
65635
+ level: "info",
65636
+ summary: `${skipped} de ${input.verdict?.checksRun ?? "?"} checks pulados`,
65637
+ detail: "Um check pulado não é um check que passou. Veja `checks[]` no report.json para quais e por quê."
65638
+ });
65639
+ }
65640
+ if (input.partial) {
65641
+ out.push({
65642
+ id: "partial-run",
65643
+ level: "warn",
65644
+ summary: "Run interrompido — veredito parcial",
65645
+ detail: input.partialReason ? `Parou em: ${input.partialReason}. O que não rodou não conta como aprovado.` : "O que não rodou não conta como aprovado."
65646
+ });
65647
+ }
65648
+ return out;
65649
+ }
65650
+ function pairedPathMismatches(prodPages, candPages) {
65651
+ const out = [];
65652
+ for (const cand of candPages) {
65653
+ if (!cand.pairKey)
65654
+ continue;
65655
+ const prod = prodPages.find((p) => p.pairKey === cand.pairKey);
65656
+ if (!prod)
65657
+ continue;
65658
+ const prodPath = pathOf5(prod.url);
65659
+ const candPath = pathOf5(cand.url);
65660
+ if (prodPath && candPath && prodPath !== candPath)
65661
+ out.push(`${prodPath} → ${candPath}`);
65662
+ }
65663
+ return [...new Set(out)];
65664
+ }
65665
+ function pathOf5(raw) {
65666
+ try {
65667
+ return new URL(raw).pathname;
65668
+ } catch {
65669
+ return null;
65670
+ }
65671
+ }
65672
+
65515
65673
  // src/util/timing.ts
65516
65674
  async function withTiming(fn) {
65517
65675
  const start = performance.now();
@@ -65921,6 +66079,9 @@ function pagesFlowsScopeWarning(opts, flows2) {
65921
66079
  return null;
65922
66080
  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.`;
65923
66081
  }
66082
+ function caveatsOrUndefined(caveats) {
66083
+ return caveats.length > 0 ? caveats : undefined;
66084
+ }
65924
66085
  function applySmartDefaults(opts, llmAvailable) {
65925
66086
  if (llmAvailable)
65926
66087
  return opts;
@@ -66741,7 +66902,15 @@ ${formatTimingsSummary(partialTimings, buildFlowBreakdown(allFlowCaptures))}
66741
66902
  baseline: baselineSection,
66742
66903
  timings: runTimings,
66743
66904
  selectionReason: opts.why,
66744
- moduleVerdicts: moduleVerdicts.length > 0 ? moduleVerdicts : undefined
66905
+ moduleVerdicts: moduleVerdicts.length > 0 ? moduleVerdicts : undefined,
66906
+ caveats: caveatsOrUndefined(detectRunCaveats({
66907
+ prodUrl: opts.prod,
66908
+ candUrl: opts.cand,
66909
+ prodPages: checkCtx.prodPages,
66910
+ candPages: checkCtx.candPages,
66911
+ verdict: verdict2,
66912
+ llmEnabled: llmStillAvailable
66913
+ }))
66745
66914
  };
66746
66915
  const reportStart = performance.now();
66747
66916
  writeRunReportJson(paths.runDir, run);
@@ -66997,6 +67166,10 @@ function printSummary6(run, htmlPath, meta) {
66997
67166
  console.log(` ${emoji} parity ${verdict2.status.toUpperCase()} · score ${score}/100${scoreDelta}`);
66998
67167
  console.log(` checks: ${chalk20.green(verdict2.checksPassed)} pass · ${chalk20.red(verdict2.checksFailed)} fail · ${chalk20.dim(`${verdict2.checksSkipped} skipped`)}`);
66999
67168
  console.log(` issues: ${chalk20.red(verdict2.critical)} critical · ${chalk20.yellow(verdict2.high)} high · ${verdict2.medium} medium · ${chalk20.dim(`${verdict2.low} low`)}`);
67169
+ for (const c of run.caveats ?? []) {
67170
+ const mark = c.level === "warn" ? chalk20.yellow("⚠") : chalk20.dim("ℹ");
67171
+ console.log(` ${mark} ${c.summary}`);
67172
+ }
67000
67173
  if (run.moduleVerdicts && run.moduleVerdicts.length > 0) {
67001
67174
  const perModule = run.moduleVerdicts.map((mv) => {
67002
67175
  const colored = mv.status === "pass" ? chalk20.green(mv.score) : mv.status === "warn" ? chalk20.yellow(mv.score) : chalk20.red(mv.score);
@@ -67240,7 +67413,7 @@ function extractVitalsSlice(run) {
67240
67413
  for (const p of fc.pages) {
67241
67414
  if (!p.vitals)
67242
67415
  continue;
67243
- const k = `${p.side}::${p.viewport}::${pathOf5(p.url)}`;
67416
+ const k = `${p.side}::${p.viewport}::${pathOf6(p.url)}`;
67244
67417
  out[k] = p.vitalsFullPage ? { ...p.vitals, fullPage: p.vitalsFullPage } : p.vitals;
67245
67418
  }
67246
67419
  }
@@ -67285,8 +67458,8 @@ function extractSideBySideSlice(run) {
67285
67458
  for (const p of fc.pages) {
67286
67459
  if (p.side !== "prod")
67287
67460
  continue;
67288
- const candPath = pathOf5(p.url);
67289
- const cand = fc.pages.find((q) => q.side === "cand" && pathOf5(q.url) === candPath && q.viewport === p.viewport);
67461
+ const candPath = pathOf6(p.url);
67462
+ const cand = fc.pages.find((q) => q.side === "cand" && pathOf6(q.url) === candPath && q.viewport === p.viewport);
67290
67463
  if (!cand)
67291
67464
  continue;
67292
67465
  pairs.push({
@@ -67299,7 +67472,7 @@ function extractSideBySideSlice(run) {
67299
67472
  }
67300
67473
  return pairs;
67301
67474
  }
67302
- function pathOf5(url) {
67475
+ function pathOf6(url) {
67303
67476
  try {
67304
67477
  return new URL(url).pathname || "/";
67305
67478
  } catch {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@decocms/parity",
3
- "version": "0.26.13",
3
+ "version": "0.26.15",
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",