@analitikisler/ai-tag-debugger 0.16.0 → 0.18.0

package/src/audit.js

@@ -8,15 +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 { annotateFindings } from "./gtm.js";
-import { SAVED_SITE_FILE, writeSavedSite } from "./replay.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);
@@ -27,38 +33,67 @@ 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;
   const brand = await loadReportBrand(config.report, configDir);
-  return { config, plan, gtmContainer, brand };
+  // 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, brand = 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, brand };
+  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));
+  // 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"));
@@ -67,28 +102,37 @@ export async function writeReports({ outDir, config, plan, runs, findings, expla
       console.error(`Could not write report.pdf: ${err.message}`);
     }
   }
-  return { reportPath, changes };
+  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, brand?: Awaited<ReturnType<typeof loadReportBrand>>, 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;
@@ -104,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) {
@@ -119,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 = annotateFindings(filterFindings(runs.flatMap((run) => checkRun(plan, run, { lang })), events), gtmContainer);
+  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 {
@@ -167,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, brand: opts.brand ?? null });
+  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

@@ -198,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),
       });
@@ -508,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;
 }
 
@@ -523,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, ...(f.gtm ? { gtm: f.gtm } : {}), 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]);
 }

package/src/ci-output.js

@@ -0,0 +1,104 @@
+// Machine-readable outputs for CI: junit.xml, which GitHub Actions, GitLab and Jenkins show as test
+// results, and summary.json, a small file a script can read without parsing capture.json.
+import path from "node:path";
+import { groupFindings, summarize } from "./checks.js";
+import { messages } from "./i18n.js";
+import { platformLabel } from "./report.js";
+
+// The same order the CLI uses for --fail-on: a finding fails when its severity is at or above the level.
+const LEVELS = ["broken", "risk", "warning", "info"];
+
+/** Whether a finding counts as a failure under --fail-on. Accepted (baselined) findings never do. */
+export function failsAt(finding, failOn = "broken") {
+  if (failOn === "never" || finding.accepted === true) return false;
+  const level = LEVELS.indexOf(finding.severity);
+  return level !== -1 && level <= LEVELS.indexOf(failOn);
+}
+
+/** How long a run took in seconds, from its start to its last step or hit; 0 when the run has no timing. */
+export function runSeconds(run) {
+  if (typeof run?.startedAt !== "number") return 0;
+  const last = Math.max(...[...(run.steps ?? []), ...(run.hits ?? [])].map((x) => x?.t ?? 0));
+  return last > run.startedAt ? Math.round((last - run.startedAt) / 10) / 100 : 0;
+}
+
+/** The one-line name of a finding: platform and event when it has them, then the message. */
+export function findingTitle(f) {
+  const what = [f.platform ? platformLabel(f.platform) : "", f.event ?? ""].filter(Boolean).join(" ");
+  const line = what ? `${what}: ${f.detail}` : f.detail ?? f.check;
+  return line.length > 120 ? `${line.slice(0, 119).trimEnd()}…` : line;
+}
+
+const escapeXml = (s) => String(s ?? "").replace(/[<>&"']/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", '"': "&quot;", "'": "&apos;" })[c]);
+// Control characters are not allowed in XML 1.0 at all, so they are dropped rather than escaped.
+// eslint-disable-next-line no-control-regex
+const xmlText = (s) => escapeXml(String(s ?? "").replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, ""));
+const attrs = (o) => Object.entries(o).map(([k, v]) => ` ${k}="${xmlText(v)}"`).join("");
+
+const belongsTo = (f, run) => f.journey === run.journeyId && f.viewport === run.viewport;
+
+// A case is { xml, failed }: a failure carries the detail in its body, a pass keeps it in system-out.
+const testcase = ({ classname, name, time = 0, failed, type, text, message = name }) => ({
+  failed,
+  xml: `<testcase${attrs({ classname, name, time })}>${failed ? `<failure${attrs({ message, type })}>${xmlText(text)}</failure>` : text ? `<system-out>${xmlText(text)}</system-out>` : ""}</testcase>`,
+});
+
+const findingCase = (f, failOn) => testcase({ classname: f.check, name: findingTitle(f), failed: failsAt(f, failOn), type: f.severity, text: f.detail });
+
+function suite(name, cases, seconds) {
+  const failures = cases.filter((c) => c.failed).length;
+  return { failures, tests: cases.length, xml: `  <testsuite${attrs({ name, tests: cases.length, failures, errors: 0, skipped: 0, time: seconds })}>\n${cases.map((c) => `    ${c.xml}`).join("\n")}\n  </testsuite>` };
+}
+
+/**
+ * JUnit XML: one suite per journey and viewport, one case per finding, plus a "journey completed" case
+ * that fails when the journey did not reach its goal. Findings not tied to a run go in a suite of their own.
+ */
+export function renderJunit({ runs = [], findings = [], lang = "en", failOn = "broken", version = "", site = "" }) {
+  const m = messages(lang).ui;
+  const suites = runs.map((run) => {
+    // With --fail-on never the CLI exits 0 whatever happened, so the JUnit file must not fail the job on its own.
+    const journey = testcase({ classname: "journey", name: m.junitJourney, time: runSeconds(run), failed: failOn !== "never" && run.completed === false, type: "incomplete", text: run.note, message: run.note ?? "" });
+    return suite(`${run.journeyId} (${run.viewport})`, [journey, ...findings.filter((f) => belongsTo(f, run)).map((f) => findingCase(f, failOn))], runSeconds(run));
+  });
+  const loose = findings.filter((f) => !runs.some((run) => belongsTo(f, run)));
+  if (loose.length) suites.push(suite(m.junitSite, loose.map((f) => findingCase(f, failOn)), 0));
+  const totals = { tests: suites.reduce((n, s) => n + s.tests, 0), failures: suites.reduce((n, s) => n + s.failures, 0), time: runs.reduce((n, r) => n + runSeconds(r), 0) };
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuites${attrs({ name: `ai-tag-debugger ${site}`.trim(), ...(version ? { version } : {}), ...totals })}>\n${suites.map((s) => s.xml).join("\n")}\n</testsuites>\n`;
+}
+
+/** The run in one small object: counts, journeys, findings and where the other files are. */
+export function buildSummary({ runs = [], findings = [], counts, plan = null, against = null, ai = null, lang = "en", reportPath, outDir, changes = null, version = "", site = "", metrics = null, trend = null }) {
+  // Only the run folder's name and file names relative to it: a summary uploaded as a CI artifact must not carry the runner's paths.
+  const dir = outDir ?? (reportPath ? path.dirname(reportPath) : ".");
+  const file = (name) => name;
+  return {
+    version,
+    site,
+    generatedAt: new Date().toISOString(),
+    lang,
+    ai: ai ? { name: ai.name, model: ai.model } : null,
+    plan: { id: against?.id ?? null, events: (plan?.events ?? []).map((e) => `${String(e.platform ?? "").toLowerCase()}:${e.name}`) },
+    journeys: runs.map((r) => ({ id: r.journeyId, viewport: r.viewport, completed: r.completed !== false, note: r.note ?? "", steps: r.steps?.length ?? 0, hits: r.hits?.length ?? 0 })),
+    counts: counts ?? summarize(groupFindings(findings)),
+    // The deterministic verdict (see src/metrics.js): its status, the headline key, and the data quality score.
+    verdict: metrics ? { status: metrics.verdict.status, headline: metrics.verdict.headline } : null,
+    score: metrics?.score?.score ?? null,
+    trend: trend ? { direction: trend.direction, runs: trend.runs } : null,
+    findings: findings.map((f) => ({
+      check: f.check,
+      severity: f.severity,
+      platform: f.platform ?? null,
+      event: f.event ?? null,
+      journey: f.journey ?? null,
+      viewport: f.viewport ?? null,
+      title: findingTitle(f),
+      message: f.detail ?? "",
+      ...(f.platform && f.event ? { key: `${f.platform}:${f.event}` } : {}),
+      ...(f.accepted === true ? { accepted: true } : {}),
+    })),
+    changes: changes ? { fixed: changes.fixed ?? [], new: changes.new ?? [] } : null,
+    run: path.basename(dir),
+    files: { html: file("report.html"), md: file("report.md"), csv: file("timeline.csv"), capture: file("capture.json"), ...(against ? { planCheck: file("plan-check.json") } : {}), junit: file("junit.xml"), summary: file("summary.json") },
+  };
+}