@analitikisler/ai-tag-debugger 0.15.0 → 0.17.0

package/src/audit.js

@@ -8,13 +8,21 @@ import path from "node:path";
 import { failedRun, runJourney } from "./agent.js";
 import { VIEWPORTS } from "./browser.js";
 import { checkRun, groupFindings, planCheck, summarize } from "./checks.js";
-import { explainFindings, renderCsv, renderHtml, renderMarkdown } from "./report.js";
+import { explainFindings, renderCsv, renderHtml, renderMarkdown, verdictHeadline, VERSION } from "./report.js";
+import { computeMetrics } from "./metrics.js";
+import { journeyStability, loadHistory, trend as trendOf, updateHistoryIndex } from "./history.js";
+import { buildSummary, renderJunit } from "./ci-output.js";
 import { LANGUAGES, messages } from "./i18n.js";
+import { loadReportBrand, writePdf } from "./whitelabel.js";
 import { createProvider, alsoSet } from "./providers.js";
 import { filterFindings, JOURNEY_PRESETS, planRun } from "./journeys.js";
 import { resolveProviders } from "./parsers.js";
-import { SAVED_SITE_FILE, writeSavedSite } from "./replay.js";
+import { annotateFindings } from "./gtm.js";
+import { lastSteps, SAVED_SITE_FILE, savedSteps, STEPS_FILE, writeSavedSite } from "./replay.js";
 import { runConsentScenarios } from "./consent.js";
+import { validateConfig, validatePlan } from "./schema.js";
+import { applyBaseline } from "./baseline.js";
+import { parseConcurrency, runPool, taggedLog } from "./pool.js";
 
 export async function readJson(file, baseDir = ".") {
   const full = path.resolve(baseDir, file);
@@ -25,58 +33,106 @@ export async function readJson(file, baseDir = ".") {
   }
 }
 
-/** Reads a config file and everything it points to. */
-export async function loadConfig(configFile) {
+/**
+ * Reads a config file and everything it points to. The config and the plan are checked against their
+ * schema first, so a typo fails here with the field named; unknown keys are only warned about, through
+ * log (default: stderr). The result carries validated: true, which tells runAudit not to check again.
+ */
+export async function loadConfig(configFile, { log = console.error } = {}) {
   const configPath = path.resolve(configFile);
   const configDir = path.dirname(configPath);
   const config = await readJson(configPath);
+  const { warnings } = validateConfig(config, { file: configFile });
   const plan = typeof config.plan === "string" ? await readJson(config.plan, configDir) : config.plan;
-  if (plan && !Array.isArray(plan.events)) throw new Error('The "plan" needs an "events" list.');
+  if (plan) warnings.push(...validatePlan(plan, typeof config.plan === "string" ? { file: config.plan } : { file: configFile, at: "plan" }).warnings);
+  for (const w of warnings) log(w);
   const gtmContainer = config.gtm_container ? await readJson(config.gtm_container, configDir) : null;
-  return { config, plan, gtmContainer };
+  const brand = await loadReportBrand(config.report, configDir);
+  // The baseline is only resolved here, not read: --update-baseline may create it on this run.
+  const baselineFile = typeof config.baseline === "string" ? path.resolve(configDir, config.baseline) : null;
+  return { config, plan, gtmContainer, brand, baselineFile, validated: true };
 }
 
 
 /**
- * Writes report.md, report.html, timeline.csv and capture.json, plus plan-check.json with --against.
+ * Writes report.md, report.html, timeline.csv, capture.json and steps.json, plus plan-check.json with --against,
+ * and junit.xml and summary.json for CI. failOn: the --fail-on level, so junit.xml fails the same findings the exit code does.
  * previous: the site's last saved run (see previousRun), null when there is none, or undefined to skip
- * the "Changed since last run" section. Returns { reportPath, changes }.
+ * the "Changed since last run" section. history: { dataDir } when the run is saved in the site's runs folder,
+ * so its history index is updated and the reports get the trend; null for --out and replays.
+ * Returns { reportPath, summaryPath, changes, metrics, verdict, trend, stability }.
  */
-export async function writeReports({ outDir, config, plan, runs, findings, explained, lang, ai = null, against = null, branding = config.branding !== false, previous = undefined, planChanges = null, consentScenarios = null }) {
+export async function writeReports({ outDir, config, plan, runs, findings, explained, lang, ai = null, against = null, branding = config.branding !== false, previous = undefined, planChanges = null, consentScenarios = null, brand = null, failOn = "broken", history = null }) {
   await mkdir(outDir, { recursive: true });
   const site = new URL(config.site).hostname;
   const title = messages(lang).ui.title(site);
   const generatedAt = new Date().toISOString().slice(0, 16).replace("T", " ") + " UTC";
   const check = against ? { plan_id: against.id ?? null, ...planCheck(plan, runs, findings) } : null;
   const changes = previous === undefined ? null : compareRuns(previous, { findings, planCheck: check, runs });
-  const report = { title, site, ai, generatedAt, findings, explained, runs, plan, lang, branding, against: against?.label ?? null, planCheck: check, changes, planChanges, consentScenarios };
+  const metrics = computeMetrics({ plan, runs, findings, consentScenarios });
+  const verdict = verdictHeadline({ findings, runs, metrics, lang });
+  // The capture goes first: the history index summarises it, and the reports then show the trend including this run.
+  await writeFile(path.join(outDir, "capture.json"), JSON.stringify({ version: VERSION, ai, config: { ...config, plan }, ...(against ? { against: { plan_id: against.id, file: against.file } } : {}), runs, findings, explained, metrics, ...(changes ? { changes } : {}), ...(planChanges ? { planChanges } : {}), ...(consentScenarios ? { consentScenarios } : {}) }, null, 2));
+  let trend = null;
+  let stability = null;
+  if (history) {
+    // A history that cannot be read or written costs the trend, never the report.
+    await updateHistoryIndex(history.dataDir, config.site, { id: path.basename(outDir), capture: { runs, findings }, version: VERSION, ai }).catch(() => null);
+    const saved = await loadHistory(history.dataDir, config.site).catch(() => []);
+    trend = trendOf(saved);
+    stability = journeyStability(saved);
+  }
+  const report = { title, site, ai, generatedAt, findings, explained, runs, plan, lang, branding, against: against?.label ?? null, planCheck: check, changes, planChanges, consentScenarios, brand, metrics, trend };
   await writeFile(path.join(outDir, "report.md"), renderMarkdown(report));
   await writeFile(path.join(outDir, "report.html"), renderHtml(report));
   await writeFile(path.join(outDir, "timeline.csv"), renderCsv(report));
   if (check) await writeFile(path.join(outDir, "plan-check.json"), JSON.stringify(check, null, 2));
-  await writeFile(path.join(outDir, "capture.json"), JSON.stringify({ config: { ...config, plan }, ...(against ? { against: { plan_id: against.id, file: against.file } } : {}), runs, findings, explained, ...(changes ? { changes } : {}), ...(planChanges ? { planChanges } : {}), ...(consentScenarios ? { consentScenarios } : {}) }, null, 2));
-  return { reportPath: path.join(outDir, "report.html"), changes };
+  // The steps taken, so the next --scripted run can repeat them without a model (see lastSteps). Typed values are
+  // stored as typed, since a replay has to type them again: journeys should use test data, and the run folder stays out of version control.
+  await writeFile(path.join(outDir, STEPS_FILE), JSON.stringify(savedSteps({ site: config.site, runs }), null, 2));
+  const reportPath = path.join(outDir, "report.html");
+  const summaryPath = path.join(outDir, "summary.json");
+  await writeFile(path.join(outDir, "junit.xml"), renderJunit({ runs, findings, lang, failOn, version: VERSION, site }));
+  await writeFile(summaryPath, JSON.stringify(buildSummary({ runs, findings, counts: summarize(groupFindings(findings)), plan, against, ai, lang, reportPath, outDir, changes, consentScenarios, version: VERSION, site, metrics, trend }), null, 2));
+  if (brand?.pdf) {
+    try {
+      await writePdf(reportPath, path.join(outDir, "report.pdf"));
+    } catch (err) {
+      // The HTML report is the main output; a PDF that can't be made is a warning, not a failed run.
+      console.error(`Could not write report.pdf: ${err.message}`);
+    }
+  }
+  return { reportPath, summaryPath, changes, metrics, verdict, trend, stability };
 }
 
 /**
  * @param {{ config: any, plan?: any, gtmContainer?: any, journeys?: string[], goals?: string[], events?: string[], viewports?: string[],
  *   scripted?: boolean, ai?: boolean, provider?: string, model?: string, baseUrl?: string, maxSteps?: number, lang?: string, headed?: boolean,
- *   outDir?: string, dataDir?: string, branding?: boolean, providers?: string[], saveSite?: string, replaySite?: string, log?: (m: string) => void }} opts
+ *   outDir?: string, dataDir?: string, branding?: boolean, brand?: Awaited<ReturnType<typeof loadReportBrand>>, providers?: string[], saveSite?: string, replaySite?: string, concurrency?: number | string, log?: (m: string) => void }} opts
  *   journeys: config journey ids or ready-made journeys (purchase, add_to_cart, sign_up, lead, search).
  *   goals: extra journeys described in plain language. events: only check these events.
  *   providers: tracking providers to check (default: config "providers", else GA4, Google Ads, Meta, TikTok plus
  *     any other known platform the site sends to).
  *   saveSite: record the site's responses and the steps taken into this folder, for replaySite (see replay.js).
  *   replaySite: answer every request from a folder saved with saveSite, without the network.
+ *   failOn: the --fail-on level (default "broken"), which decides what junit.xml marks as failed.
+ *   concurrency: how many journeys (and consent scenarios) run at once, each in its own browser. Default 1, at most 8.
  *   against: { id, file } of the plan given with --against; opts.plan is then that plan. Used alone, the
  *   journeys come from the plan; with journeys or goals, only the plan events expected on them are checked.
+ *   validated: true when config and plan came through loadConfig, which already checked them against the schema.
+ *   baseline: a baseline read with readBaseline (see baseline.js). The findings it accepts are flagged
+ *     accepted and left out of the counts; the result then has baseline: { accepted, partial, stale }.
  */
 export async function runAudit(opts) {
   const { gtmContainer } = opts;
   let config = opts.config;
   const events = opts.events ?? [];
-  if (!config.site) throw new Error('No site to audit. Pass --site or set "site" in the config.');
   const log = opts.log ?? (() => {});
+  if (!opts.validated) {
+    const checked = [validateConfig(config), ...(opts.plan ? [validatePlan(opts.plan)] : [])];
+    for (const w of checked.flatMap((c) => c.warnings)) log(w);
+  }
+  if (!config.site) throw new Error('No site to audit. Pass --site or set "site" in the config.');
   const lang = opts.lang ?? config.language ?? "en";
   if (!LANGUAGES[lang]) throw new Error(`Language must be one of ${Object.keys(LANGUAGES).join(", ")}.`);
   const useAi = opts.ai !== false;
@@ -92,10 +148,21 @@ export async function runAudit(opts) {
   if (!Array.isArray(viewports)) throw new Error(`"viewports" must be a list, e.g. ["desktop", "mobile"]. Allowed values: ${allowed}.`);
   const unknown = viewports.filter((v) => !Object.hasOwn(VIEWPORTS, v));
   if (unknown.length) throw new Error(`Unknown viewport ${unknown.map((v) => `"${v}"`).join(", ")}. Use: ${allowed}.`);
+  const concurrency = parseConcurrency(opts.concurrency ?? config.concurrency);
   if (!journeys.length) throw new Error(`No journeys to run. A run needs one of:\n  --journey <name>   one of: ${Object.keys(JOURNEY_PRESETS).join(", ")} (or a journey id from your config)\n  --goal "<text>"    describe what to do in your own words\n  --config <file>    a config file with "journeys"\nNot sure what to test? "aitd plan --site ${config.site}" drafts a measurement plan.`);
+  // A journey without fixed steps of its own repeats the steps of the site's last completed run, which every run saves.
+  const replayed = new Map();
   if (opts.scripted) {
-    const unscripted = journeys.filter((j) => !j.steps?.length && !j.incomplete).map((j) => j.id);
-    if (unscripted.length) throw new Error(`Journeys without fixed steps can't be replayed with --scripted: ${unscripted.join(", ")}.`);
+    const unscripted = [];
+    for (const j of journeys.filter((j) => !j.steps?.length && !j.incomplete)) {
+      for (const viewport of viewports) {
+        // A saved-site replay stays offline: it never borrows steps from the runs folder.
+        const last = opts.replaySite ? null : await lastSteps(opts.dataDir, config.site, { journeyId: j.id, viewport }).catch(() => null);
+        if (last) replayed.set(`${j.id}|${viewport}`, last);
+        else if (!unscripted.includes(j.id)) unscripted.push(j.id);
+      }
+    }
+    if (unscripted.length) throw new Error(`Journeys without fixed steps can't be replayed with --scripted: ${unscripted.join(", ")}. Run them once with an AI model first; every completed run saves its steps.`);
   }
 
   if (against) {
@@ -107,33 +174,40 @@ export async function runAudit(opts) {
     }
   }
 
-  const provider = useAi ? await createProvider({ name: opts.provider ?? config.provider, model: opts.model ?? config.model, baseUrl: opts.baseUrl ?? config.base_url }) : null;
+  const provider = useAi ? await createProvider({ name: opts.provider ?? config.provider, model: opts.model ?? config.model, baseUrl: opts.baseUrl ?? config.base_url, log }) : null;
   if (provider) log(`Using ${provider.name} (${provider.model})${provider.via ? ` via ${provider.via}` : ""}${alsoSet(provider.key)}`);
 
   if (opts.saveSite) await mkdir(opts.saveSite, { recursive: true });
   // Repeat runs start from the route the last completed run took. Not with --out or a replay, which have no history to learn from.
   const hints = provider && !opts.outDir && !opts.replaySite ? await routeHints(opts.dataDir, config.site).catch(() => new Map()) : new Map();
-  const runs = [];
-  for (const journey of journeys) {
-    for (const viewport of viewports) {
-      log(`\n▶ ${journey.id} (${viewport})`);
-      const hint = hints.get(`${journey.id}|${viewport}`);
-      const routeHint = hint && hint.goal === journey.goal ? hint.pages : undefined;
-      if (routeHint) log(`  Starting from the route of the last completed run (${routeHint.length} ${routeHint.length === 1 ? "page" : "pages"})`);
-      // runJourney keeps its own errors in the run. This catches the rest, such as a browser that won't close,
-      // so one journey can't cost the report of the others.
-      const run = await runJourney(config, journey, viewport, { scripted: opts.scripted, provider, routeHint, maxSteps: opts.maxSteps, headed: opts.headed, lang, log, saveSite: opts.saveSite, replaySite: opts.replaySite }).catch((err) => failedRun(journey, viewport, err, config.providers));
-      log(`  ${run.completed ? "✓" : "✗"} ${run.note} · ${run.hits.length} tracking hits captured`);
-      runs.push(run);
-    }
-  }
+  // Every journey × viewport pair has its own browser, so they can run side by side. The runs keep the pairs'
+  // order whatever finishes first: the report and the comparison with the last run count on it.
+  const jobs = journeys.flatMap((journey) => viewports.map((viewport) => ({ journey, viewport })));
+  const runs = await runPool(jobs, concurrency, async ({ journey, viewport }) => {
+    // Side by side, each job's lines start with its name, so the interleaved output stays readable.
+    const jobLog = concurrency > 1 ? taggedLog(log, `[${journey.id}/${viewport}]`) : log;
+    jobLog(`\n▶ ${journey.id} (${viewport})`);
+    const hint = hints.get(`${journey.id}|${viewport}`);
+    const routeHint = hint && hint.goal === journey.goal ? hint.pages : undefined;
+    if (routeHint) jobLog(`  Starting from the route of the last completed run (${routeHint.length} ${routeHint.length === 1 ? "page" : "pages"})`);
+    const last = replayed.get(`${journey.id}|${viewport}`);
+    if (last) jobLog(`  Replaying the steps of run ${last.runId}${last.viewport === viewport ? "" : ` (${last.viewport})`}`);
+    const fixed = last ? { ...journey, ...(last.start ? { start: last.start } : {}), steps: last.steps, stepsFrom: last.runId } : journey;
+    // runJourney keeps its own errors in the run. This catches the rest, such as a browser that won't close,
+    // so one journey can't cost the report of the others.
+    const run = await runJourney(config, fixed, viewport, { scripted: opts.scripted, provider, routeHint, maxSteps: opts.maxSteps, headed: opts.headed, lang, log: jobLog, saveSite: opts.saveSite, replaySite: opts.replaySite }).catch((err) => failedRun(journey, viewport, err, config.providers));
+    jobLog(`  ${run.completed ? "✓" : "✗"} ${run.note} · ${run.hits.length} tracking hits captured`);
+    return run;
+  });
 
   // Consent scenarios need the live site, so a replay from a saved site skips them. "consent_scenarios": false turns them off.
   const consentScenarios = opts.replaySite || config.consent_scenarios === false
     ? null
-    : await runConsentScenarios(config, { headed: opts.headed, log }).catch((err) => (log(`  Consent scenarios failed: ${err.message}`), null));
+    : await runConsentScenarios(config, { headed: opts.headed, log, concurrency }).catch((err) => (log(`  Consent scenarios failed: ${err.message}`), null));
 
-  const findings = filterFindings(runs.flatMap((run) => checkRun(plan, run, { lang })), events);
+  const findings = annotateFindings(filterFindings(runs.flatMap((run) => checkRun(plan, run, { lang })), events), gtmContainer, runs, { lang });
+  // Applied before anything reads the findings, so the explanation, the reports, the alerts and the counts all skip accepted ones.
+  const applied = opts.baseline ? applyBaseline(findings, opts.baseline) : null;
   let saveError = null;
   if (opts.saveSite) {
     try {
@@ -155,12 +229,14 @@ export async function runAudit(opts) {
   // Runs saved in the site's runs folder are compared with the one before; a run sent to --out is not.
   const previous = opts.outDir ? undefined : await previousRun(opts.dataDir, config.site);
   const outDir = path.resolve(opts.outDir ?? (await newRunDir(opts.dataDir, config.site)).dir);
-  const { reportPath, changes } = await writeReports({ outDir, config, plan, runs, findings, explained, lang, ai: provider ? { name: provider.name, model: provider.model } : null, against, branding: opts.branding ?? config.branding !== false, previous, planChanges: against ? await previousPlanChanges(opts.dataDir, config.site, against.id, plan).catch(() => null) : null, consentScenarios });
+  const { reportPath, summaryPath, changes, metrics, verdict, trend, stability } = await writeReports({ outDir, config, plan, runs, findings, explained, lang, ai: provider ? { name: provider.name, model: provider.model } : null, against, branding: opts.branding ?? config.branding !== false, previous, planChanges: against ? await previousPlanChanges(opts.dataDir, config.site, against.id, plan).catch(() => null) : null, consentScenarios, brand: opts.brand ?? null, failOn: opts.failOn, history: previous === undefined ? null : { dataDir: opts.dataDir } });
   if (config.notify && changes) {
-    const { sent, errors } = await sendAlerts({ notify: config.notify, site: new URL(config.site).hostname, changes: { run: path.basename(outDir), ...changes }, lang, reportPath });
+    const { sent, errors } = await sendAlerts({ notify: config.notify, site: new URL(config.site).hostname, changes: { run: path.basename(outDir), ...changes }, lang, reportPath, verdict, trend });
     if (sent.length) log(`\nSent the changes since the last run to ${sent.join(" and ")}.`);
     for (const e of errors) log(`\nCould not send an alert. ${e}`);
   }
   const counts = summarize(groupFindings(findings));
-  return { journeys, plan, runs, findings, explained, counts, reportPath, outDir, lang, consentScenarios, ...(against ? { againstId: against.id } : {}), ...(saveError ? { saveError } : {}) };
+  // Accepted counts every finding the baseline matched; a problem accepted in some places only is still counted, and reported as partial.
+  const baseline = applied ? { accepted: applied.accepted, partial: applied.partial, stale: applied.stale } : null;
+  return { journeys, plan, runs, findings, explained, counts, metrics, verdict, trend, stability, reportPath, summaryPath, outDir, lang, consentScenarios, ...(against ? { againstId: against.id } : {}), ...(baseline ? { baseline } : {}), ...(saveError ? { saveError } : {}) };
 }

package/src/baseline.js

@@ -0,0 +1,90 @@
+// A baseline file: findings a team has looked at and accepted. A run with a baseline still
+// lists them in the report, but they don't count toward the exit code, so a deploy fails only
+// on new problems. Only each entry's key is matched; the other fields are there for whoever
+// reads the file.
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * The key a finding is accepted by. It names what went wrong and where, and for missing
+ * parameters which ones, and leaves out everything that differs from run to run: the step a
+ * hit was seen on, timings, counts and the wording of the detail.
+ */
+export function findingKey(f) {
+  return [f.check, f.platform ?? "-", f.event ?? "-", f.journey, f.viewport, f.params?.length ? f.params.join(",") : "-"].join(" ");
+}
+
+/** Reads a baseline file written by writeBaseline. A missing file throws with code ENOENT. */
+export async function readBaseline(file) {
+  let baseline;
+  try {
+    baseline = JSON.parse(await readFile(file, "utf8"));
+  } catch (err) {
+    const wrapped = new Error(`Could not read the baseline ${file}: ${err.message}`);
+    wrapped.code = err.code;
+    throw wrapped;
+  }
+  if (!Array.isArray(baseline?.findings) || baseline.findings.some((b) => typeof b?.key !== "string")) {
+    throw new Error(`${file} is not a baseline: it needs a "findings" list with a "key" on each entry. Write one with --update-baseline.`);
+  }
+  return baseline;
+}
+
+/**
+ * Marks the findings the baseline accepts with accepted: true.
+ * @returns {{ accepted: number, partial: number, stale: string[] }} how many findings were accepted, how many
+ *   problems are accepted in some of their places but not all (the report still counts those, see groupFindings),
+ *   and the baseline keys no finding matched any more.
+ */
+export function applyBaseline(findings, baseline) {
+  const keys = new Set(baseline.findings.map((b) => b.key));
+  const seen = new Set();
+  // Per problem, as groupFindings merges the places: how many of its findings the baseline accepts.
+  const problems = new Map();
+  let accepted = 0;
+  for (const f of findings) {
+    if (f.severity === "ok") continue;
+    const key = findingKey(f);
+    const problem = [f.severity, f.check, f.platform, f.event, f.detail].join("|");
+    const p = problems.get(problem) ?? { total: 0, accepted: 0 };
+    p.total += 1;
+    problems.set(problem, p);
+    if (!keys.has(key)) continue;
+    f.accepted = true;
+    accepted += 1;
+    p.accepted += 1;
+    seen.add(key);
+  }
+  const partial = [...problems.values()].filter((p) => p.accepted && p.accepted < p.total).length;
+  return { accepted, partial, stale: [...keys].filter((k) => !seen.has(k)) };
+}
+
+/**
+ * Writes every current finding except the ok ones as the baseline, creating the file when it
+ * doesn't exist. A note someone wrote on an entry that is still in the file is kept.
+ * @returns {Promise<number>} how many findings the file now holds.
+ */
+export async function writeBaseline(file, { site, findings }) {
+  const notes = new Map();
+  const previous = await readBaseline(file).catch(() => null);
+  for (const b of previous?.findings ?? []) if (b.note) notes.set(b.key, b.note);
+  const entries = new Map();
+  for (const f of findings) {
+    if (f.severity === "ok") continue;
+    const key = findingKey(f);
+    if (entries.has(key)) continue;
+    entries.set(key, {
+      key,
+      check: f.check,
+      severity: f.severity,
+      ...(f.platform ? { platform: f.platform } : {}),
+      ...(f.event ? { event: f.event } : {}),
+      journey: f.journey,
+      viewport: f.viewport,
+      ...(notes.has(key) ? { note: notes.get(key) } : {}),
+    });
+  }
+  await mkdir(path.dirname(path.resolve(file)), { recursive: true });
+  await writeFile(file, `${JSON.stringify({ site, updated: new Date().toISOString(), findings: [...entries.values()] }, null, 2)}\n`);
+  return entries.size;
+}

package/src/browser.js

@@ -351,6 +351,21 @@ function pagePath(href) {
   }
 }
 
+const NAVIGATION_RETRY_MS = 2000;
+
+// Chromium network errors that a second try can get past: the connection dropped, the network changed,
+// a lookup or the server took too long. Blocked, refused-by-proxy, certificate and protocol errors are not here.
+const TRANSIENT_NET_ERRORS = /net::ERR_(CONNECTION_(RESET|CLOSED|ABORTED|REFUSED|TIMED_OUT)|TIMED_OUT|NETWORK_CHANGED|NAME_NOT_RESOLVED|NAME_RESOLUTION_FAILED|DNS_TIMED_OUT|INTERNET_DISCONNECTED|ADDRESS_UNREACHABLE|EMPTY_RESPONSE|SOCKET_NOT_CONNECTED|HTTP2_(PROTOCOL|SERVER_REFUSED_STREAM|PING_FAILED)|NETWORK_IO_SUSPENDED|SPDY_PROTOCOL_ERROR|QUIC_PROTOCOL_ERROR)\b/;
+
+/** The net::ERR_* code or "timeout" from a Playwright navigation error, for the log line. */
+const navigationErrorCode = (err) => String(err?.message ?? err).match(/net::ERR_[A-Z0-9_]+/)?.[0] ?? (err?.name === "TimeoutError" || /Timeout \d+ms exceeded/.test(String(err?.message)) ? "timeout" : "error");
+
+/** True when a failed navigation is worth one more try: a transient network error or a timeout. */
+export function isTransientNavigationError(err) {
+  const code = navigationErrorCode(err);
+  return code === "timeout" || TRANSIENT_NET_ERRORS.test(code);
+}
+
 export class AuditSession {
   /**
    * @param {{ viewport: string, site?: string, allowedHosts?: string[], providers?: string[], keepBodies?: boolean, blockPrivate?: boolean | ((ip: string) => boolean), blockHits?: boolean, headless?: boolean }} opts
@@ -366,9 +381,11 @@ export class AuditSession {
    *   replayHar: answer requests from a .har file saved with recordHar instead of the network; requests it lacks fail.
    *   blockPrivate: refuse loopback, private and link-local addresses (used when the MCP server is reachable over HTTP).
    *     All browser traffic then goes through the egress proxy. A function decides which addresses count as private (for tests).
+   *   log: gets one line when a dropped navigation is tried again. navigationRetryMs: the wait before that (default 2 s).
    */
   constructor(opts) {
     this.opts = { blockHits: true, headless: true, ...opts };
+    this.log = this.opts.log ?? (() => {});
     this.scope = this.opts.site ? hostScope(this.opts.site, this.opts.allowedHosts) : null;
     this.isBlockedAddress = typeof this.opts.blockPrivate === "function" ? this.opts.blockPrivate : isPrivateAddress;
     this.isPrivate = this.opts.blockPrivate ? privateHostChecker(this.isBlockedAddress) : null;
@@ -635,6 +652,24 @@ export class AuditSession {
     return refused;
   }
 
+  /**
+   * Opens a page. When the network dropped the first attempt or it timed out, tries once more after a
+   * short wait, since one lost connection should not cost the journey. A navigation the guard refused
+   * (this.blocked, net::ERR_BLOCKED_BY_CLIENT) is never tried again: it would be refused again.
+   */
+  async navigate(url) {
+    const options = { waitUntil: "domcontentloaded", timeout: 30000 };
+    try {
+      return await this.page.goto(url, options);
+    } catch (err) {
+      if (this.blocked?.step === this.currentStep || !isTransientNavigationError(err)) throw err;
+      const delay = this.opts.navigationRetryMs ?? NAVIGATION_RETRY_MS;
+      this.log(`  Opening ${url} failed (${navigationErrorCode(err)}); trying once more in ${Math.round(delay / 1000)}s`);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      return this.page.goto(url, options);
+    }
+  }
+
   /** Error message when the browser may not be on this URL, or null. */
   checkUrl(url) {
     if (url.startsWith("chrome-error:")) return null; // Chromium's own error page, e.g. after a blocked navigation
@@ -848,7 +883,7 @@ export class AuditSession {
           step.replay = { action: "goto", url: target };
           const refused = await this.checkUrl(target);
           if (refused) return refused;
-          const response = await this.page.goto(target, { waitUntil: "domcontentloaded", timeout: 30000 });
+          const response = await this.navigate(target);
           if (!this.landing) {
             // The first page: the address asked for, each redirect on the way, and where it ended up.
             const chain = [];

package/src/changes.js

@@ -2,6 +2,7 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { messages } from "./i18n.js";
 import { platformLabel } from "./report.js";
+import { ownerOf } from "./verify.js";
 import { PLAN_FILE, listPlanIds, listRunIds, plansDir, runsDir } from "./workspace.js";
 
 const PROBLEMS = new Set(["broken", "risk", "warning"]);
@@ -129,17 +130,22 @@ export async function sinceLastRun(dataDir, site) {
   return { run: latest.id, ...compareRuns(prev, { findings: latest.capture.findings ?? [], planCheck: latest.planCheck, runs: latest.capture.runs }) };
 }
 
-/** The diff as plain lines: a headline, then one line per fixed and new problem. */
+/**
+ * The diff as plain lines: a headline, then one line per fixed and new problem. A fixed item says what
+ * it "was", since its text is the old state; a new one carries its severity (or plan bucket) and owner,
+ * so a lost purchase reads differently from an unplanned event.
+ */
 export function changesLines(ch, lang = "en") {
   const m = messages(lang);
   if (!ch.run) return [m.ui.noSavedRun];
   if (!ch.previous) return [m.ui.noPreviousRun];
   const label = (c) => `${platformLabel(c.platform ?? "")} ${c.event ?? ""}`.trim() || c.check;
   const why = (c, bucket) => (ch.mode === "findings" ? c.detail : m.ui.bucket[bucket]);
+  const tag = (c) => (ch.mode === "findings" ? m.severity[c.severity] ?? "" : m.ui.bucket[c.bucket]);
   return [
     `${m.ui.changesLine(ch)}. ${m.ui.changesLead(ch.previous, ch.mode)} (${ch.run}).`,
-    ...ch.fixed.map((c) => `- ${m.ui.changeFixed}: ${label(c)} (${why(c, c.was)})`),
-    ...ch.new.map((c) => `- ${m.ui.changeNew}: ${label(c)} (${why(c, c.bucket)})`),
+    ...ch.fixed.map((c) => `- ${m.ui.changeFixed}: ${label(c)} (${m.ui.history.fixedWas}: ${why(c, c.was)})`),
+    ...ch.new.map((c) => `- ${m.ui.changeNew}: ${[label(c), tag(c), ch.mode === "findings" ? c.detail : "", c.check ? m.ui.owners[ownerOf(c)] : ""].filter(Boolean).join(" · ")}`),
     ...(ch.routes?.length ? [m.ui.routeChanged(ch.routes.map((r) => `${r.journeyId} (${r.viewport})`).join(", "))] : []),
   ];
 }

package/src/checks.js

@@ -24,6 +24,20 @@ const SEVERITY_ORDER = { broken: 0, risk: 1, warning: 2, info: 3, ok: 4 };
  * @typedef {{ severity: "broken"|"risk"|"warning"|"info"|"ok", check: string, journey: string, viewport: string, platform?: string, event?: string, step?: string, detail: string, evidence?: string }} Finding
  */
 
+/** Hosts of server containers seen in the run's network calls, the site's own or Stape's. */
+export function serverEndpoints(run) {
+  const hosts = new Set();
+  for (const c of run.network ?? []) {
+    let u;
+    try { u = new URL(c.url); } catch { continue; }
+    if (/(^|\.)(google-analytics\.com|analytics\.google\.com|googletagmanager\.com|google\.[a-z.]+|doubleclick\.net)$/.test(u.hostname)) continue;
+    const ga4Server = c.provider === "ga4" && u.pathname.endsWith("/g/collect");
+    const loader = (c.provider === "gtm" || c.provider === "ga4") && /\/(gtm\.js|gtag\/js)$/.test(u.pathname);
+    if (ga4Server || loader) hosts.add(u.hostname);
+  }
+  return [...hosts];
+}
+
 const key = (platform, name) => `${platform}:${name}`;
 
 // Sites name events in their own way: Elevar's dl_add_to_cart, UA-style addToCart, Add To Cart.
@@ -184,6 +198,8 @@ export function checkRun(plan, run, { lang = "en" } = {}) {
         platform: hit.platform,
         event: hit.name,
         step: stepLabel(hit.step),
+        // The parameter names are kept apart from the detail text, so a baseline can match them in any language.
+        params: missing,
         detail: d.missingParams(hit.name, missing),
         evidence: JSON.stringify(hit.params),
       });
@@ -287,7 +303,12 @@ export function checkRun(plan, run, { lang = "en" } = {}) {
     for (const p of byPlatform) findings.push({ ...base, severity: "info", check: "server_side", platform: p.platform, detail: d.serverSide(p.platform, p.server, p.browser, unseenServer) });
   }
   const serverVendors = [...new Set((run.network ?? []).map((c) => c.provider).filter((p) => p === "stape" || p === "elevar"))];
-  if (serverVendors.length || serverHits.length) {
+  // Server containers the browser talked to: GA4 hits on a non-Google host, and GTM or gtag.js
+  // loaded from one (a custom loader, which only a server container serves).
+  const endpoints = serverEndpoints(run);
+  if (endpoints.length && !serverHits.length) findings.push({ ...base, severity: "info", check: "server_endpoint", detail: d.serverEndpoint(endpoints) });
+  const serverSeen = serverVendors.length || serverHits.length || endpoints.length;
+  if (serverSeen) {
     const noId = new Map();
     for (const hit of run.hits) {
       if ((hit.platform === "meta" || hit.platform === "tiktok") && !hit.eventId && !noId.has(key(hit.platform, hit.name))) noId.set(key(hit.platform, hit.name), hit);
@@ -297,6 +318,39 @@ export function checkRun(plan, run, { lang = "en" } = {}) {
     }
   }
 
+  // One event ID on two different events: the platform keeps the first and drops the other as its
+  // duplicate, so a real event is lost (usually an ID set once per page instead of once per event).
+  const byId = new Map();
+  for (const hit of run.hits) {
+    if (!hit.eventId) continue;
+    const k = `${hit.platform}|${hit.eventId}`;
+    byId.set(k, [...(byId.get(k) ?? []), hit]);
+  }
+  for (const [, hits] of byId) {
+    const events = [...new Set(hits.map((h) => `${h.step}|${canonicalEvent(h.name)}`))];
+    if (events.length < 2) continue;
+    const names = [...new Set(hits.map((h) => h.name))];
+    findings.push({ ...base, severity: "warning", check: "event_id_reused", platform: hits[0].platform, event: names.join(", "), step: stepLabel(hits[1].step), detail: d.eventIdReused(platformName(hits[0].platform), hits[0].eventId, names, events.length), evidence: hits.map((h) => h.url).join("\n") });
+  }
+
+  // With a server container, the Conversions API copy is usually built from the GA4 hit, so the
+  // GA4 hit has to carry the same event_id as the Meta pixel event for Meta to deduplicate them.
+  if (serverSeen) {
+    const ga4ToServer = run.hits.filter((h) => h.platform === "ga4" && h.delivery === "server");
+    const reported = new Set();
+    for (const m of run.hits.filter((h) => h.platform === "meta" && h.eventId)) {
+      const g = ga4ToServer.find((h) => h.step === m.step && canonicalEvent(h.name) === canonicalEvent(m.name));
+      if (!g) continue;
+      const gid = g.params?.event_id;
+      const k = key("meta", m.name);
+      if (reported.has(k) || (gid !== undefined && String(gid) === m.eventId)) continue;
+      reported.add(k);
+      findings.push(gid === undefined
+        ? { ...base, severity: "info", check: "event_id_not_forwarded", platform: "meta", event: m.name, step: stepLabel(m.step), detail: d.eventIdNotForwarded(m.name, g.name) }
+        : { ...base, severity: "warning", check: "event_id_mismatch", platform: "meta", event: m.name, step: stepLabel(m.step), detail: d.eventIdMismatch(m.name, m.eventId, g.name, gid), evidence: JSON.stringify({ meta: m.eventId, ga4: gid }) });
+    }
+  }
+
   // Campaign parameters (gclid, fbclid, UTM) on the landing address: they must survive redirects and reach the hits.
   const landing = run.landing;
   const sent = landing ? campaignParamsIn(landing.requested) : {};
@@ -456,9 +510,10 @@ export function checkRun(plan, run, { lang = "en" } = {}) {
   return findings.sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
 }
 
+/** Counts per severity. Findings a baseline accepted are left out, so the counts say what is new. */
 export function summarize(findings) {
   const counts = { broken: 0, risk: 0, warning: 0, info: 0, ok: 0 };
-  for (const f of findings) counts[f.severity] += 1;
+  for (const f of findings) if (!f.accepted) counts[f.severity] += 1;
   return counts;
 }
 
@@ -471,8 +526,12 @@ export function groupFindings(findings) {
   for (const f of findings) {
     const k = f.severity === "ok" ? `ok|${f.journey}|${f.viewport}` : [f.severity, f.check, f.platform, f.event, f.detail].join("|");
     const where = { journey: f.journey, viewport: f.viewport, step: f.step };
-    if (groups.has(k)) groups.get(k).where.push(where);
-    else groups.set(k, { severity: f.severity, check: f.check, platform: f.platform, event: f.event, detail: f.detail, evidence: f.evidence, where: [where] });
+    // A problem counts as accepted only when the baseline accepts it in every place it was seen.
+    if (groups.has(k)) {
+      const group = groups.get(k);
+      group.where.push(where);
+      if (!f.accepted) delete group.accepted;
+    } else groups.set(k, { severity: f.severity, check: f.check, platform: f.platform, event: f.event, detail: f.detail, evidence: f.evidence, ...(f.gtm ? { gtm: f.gtm } : {}), ...(f.accepted ? { accepted: true } : {}), where: [where] });
   }
   return [...groups.values()].sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
 }