@analitikisler/ai-tag-debugger 0.15.0 → 0.17.0

package/src/gtm.js

@@ -0,0 +1,298 @@
+// Reads a GTM container export (Admin → Export container) to name the tag and trigger
+// behind a hit. Matching is deterministic: no API call and no AI model.
+
+import { canonicalEvent, isConsentCommand } from "./checks.js";
+import { messages } from "./i18n.js";
+
+// GTM's built-in "All Pages" trigger has no entry in the export's trigger list.
+const BUILT_IN_TRIGGERS = { 2147479553: { name: "All Pages", type: "PAGEVIEW" } };
+// The dataLayer events GTM raises for page triggers; the init script records them like any push.
+const PAGE_EVENTS = { PAGEVIEW: "gtm.js", DOM_READY: "gtm.dom", WINDOW_LOADED: "gtm.load" };
+// Triggers GTM evaluates from what happens in the page. Their events reach the dataLayer only
+// while such a trigger is listening, so the dataLayer can confirm one but not rule it out.
+const PAGE_ACTION_EVENTS = {
+  CLICK: "gtm.click", LINK_CLICK: "gtm.linkClick", FORM_SUBMIT: "gtm.formSubmit", FORM_SUBMISSION: "gtm.formSubmit", HISTORY_CHANGE: "gtm.historyChange",
+  ELEMENT_VISIBILITY: "gtm.elementVisibility", TIMER: "gtm.timer", SCROLL_DEPTH: "gtm.scrollDepth", JS_ERROR: "gtm.pageError", YOU_TUBE_VIDEO: "gtm.video",
+};
+// Older exports write the custom event filter's operators in short form.
+const SHORT_OPS = { _eq: "EQUALS", _cn: "CONTAINS", _sw: "STARTS_WITH", _ew: "ENDS_WITH", _re: "MATCH_REGEX", _lt: "LESS", _le: "LESS_OR_EQUALS", _gt: "GREATER", _ge: "GREATER_OR_EQUALS", _css: "CSS_SELECTOR", _um: "URL_MATCHES" };
+const PAGE_VARIABLES = { "Page URL": "URL", "Page Path": "PATH", "Page Hostname": "HOST" };
+const EVENT_PARAMS = ["eventName", "event_name", "event", "eventType", "standardEventName", "customEventName", "eventTypeStandard", "eventTypeCustom"];
+
+/** A tag parameter list as a flat { key: value } map; nested lists and maps are kept as JSON text. */
+function params(list = []) {
+  const out = {};
+  for (const p of list) out[p.key] = p.value ?? (p.list || p.map ? JSON.stringify(p.list ?? p.map) : undefined);
+  return out;
+}
+
+/** Which platform a tag sends to, from its type or, for custom HTML and templates, from its code. */
+function tagPlatform(tag, p) {
+  if (["gaawe", "gaawc", "googtag"].includes(tag.type)) return "ga4";
+  if (["awct", "sp", "gclidw"].includes(tag.type)) return "google_ads";
+  const text = `${tag.type} ${tag.name ?? ""} ${p.html ?? ""}`.toLowerCase();
+  if (/fbq\(|facebook|meta pixel|\bmeta\b/.test(text)) return "meta";
+  if (/ttq\.|tiktok/.test(text)) return "tiktok";
+  return null;
+}
+
+/** The event names a tag sends: its event parameter, a page_view for a GA4 config tag, or the names in fbq/ttq calls. */
+function tagEvents(tag, p) {
+  if (tag.type === "gaawc" || tag.type === "googtag") return ["page_view"];
+  const names = EVENT_PARAMS.map((k) => p[k]).filter((v) => typeof v === "string" && v);
+  for (const m of String(p.html ?? "").matchAll(/(?:fbq|ttq)\s*(?:\(\s*['"](?:track|trackCustom)['"]\s*,|\.track\s*\()\s*['"]([^'"]+)['"]/g)) names.push(m[1]);
+  if (/fbq\s*\(\s*['"]init['"]/.test(p.html ?? "") || /ttq\.page\s*\(/.test(p.html ?? "")) names.push("PageView", "Pageview");
+  return names;
+}
+
+/** The custom event names a trigger fires on, from its "Event name equals …" filter. */
+function triggerEvents(trigger) {
+  return (trigger?.customEventFilter ?? []).map((f) => params(f.parameter).arg1).filter(Boolean);
+}
+
+function describeTrigger(id, byId) {
+  const t = byId.get(String(id)) ?? BUILT_IN_TRIGGERS[id];
+  if (!t) return { id: String(id), name: `#${id}`, type: "unknown" };
+  const events = triggerEvents(t);
+  return { id: String(id), name: t.name, type: t.type, ...(events.length ? { event: events.join(", ") } : {}) };
+}
+
+/**
+ * The tags in a container export with their platform, events and triggers.
+ * @returns {{ id: string, name: string, type: string, platform: string|null, events: string[], paused: boolean, consent: string[], triggers: any[], blocking: any[] }[]}
+ */
+export function containerTags(container) {
+  const v = container?.containerVersion ?? container ?? {};
+  const byId = new Map((v.trigger ?? []).map((t) => [String(t.triggerId), t]));
+  return (v.tag ?? []).map((tag) => {
+    const p = params(tag.parameter);
+    const triggers = (tag.firingTriggerId ?? []).map((id) => describeTrigger(id, byId));
+    let events = tagEvents(tag, p);
+    // An event name taken from a variable such as {{Event}} is whatever the trigger's custom event is.
+    if (events.some((e) => /^\{\{.+\}\}$/.test(e))) events = [...events.filter((e) => !/^\{\{.+\}\}$/.test(e)), ...triggers.flatMap((t) => (t.event ? t.event.split(", ") : []))];
+    const cs = tag.consentSettings;
+    return {
+      id: String(tag.tagId ?? ""),
+      name: tag.name,
+      type: tag.type,
+      platform: tagPlatform(tag, p),
+      events,
+      paused: tag.paused === true,
+      consent: cs?.consentStatus === "NEEDED" ? (cs.consentType?.list ?? []).map((x) => x.value).filter(Boolean) : [],
+      triggers,
+      blocking: (tag.blockingTriggerId ?? []).map((id) => describeTrigger(id, byId)),
+    };
+  });
+}
+
+/** The tags in the container that send an event to a platform. */
+export function tagsForEvent(tags, platform, event) {
+  const want = canonicalEvent(event);
+  return tags.filter((t) => t.platform === platform && t.events.some((e) => canonicalEvent(e) === want));
+}
+
+/** The event name and data a push adds to GTM's data model: an object as it is, a gtag() call as its event and eventModel. */
+function pushModel(value) {
+  if (Array.isArray(value)) return value[0] === "event" && typeof value[1] === "string" ? { event: value[1], data: { event: value[1], eventModel: value[2] ?? {} } } : null;
+  if (value && typeof value === "object") return { event: typeof value.event === "string" ? value.event : undefined, data: value };
+  return null;
+}
+
+/** Merges a push into the running data layer the way GTM's version 2 model does: objects and arrays merge key by key, so a value persists until it is overwritten or cleared with null. */
+function merge(state, push) {
+  for (const [k, v] of Object.entries(push)) {
+    const same = v && typeof v === "object" && state[k] && typeof state[k] === "object" && Array.isArray(v) === Array.isArray(state[k]);
+    if (same) merge(state[k], v);
+    else state[k] = v && typeof v === "object" ? structuredClone(v) : v;
+  }
+  return state;
+}
+
+/** A value from the data layer by dot path, as a Data Layer Variable reads it; version 1 reads the key as it is. */
+function readPath(state, name, version) {
+  if (String(version) === "1") return state[name];
+  return String(name).split(".").reduce((v, k) => (v && typeof v === "object" ? v[k] : undefined), state);
+}
+
+/** A part of the page address at the push, or undefined when it is not a valid address. */
+function urlPart(url, component) {
+  try {
+    const u = new URL(url);
+    return { URL: u.href, PATH: u.pathname, HOST: u.hostname, PROTOCOL: u.protocol.replace(":", ""), PORT: u.port, FRAGMENT: u.hash.replace("#", ""), QUERY: u.search.replace("?", "") }[component];
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The value of one GTM variable at a push: { value, field } when the dataLayer can give it, where `field` is how the
+ * report names it (a Data Layer Variable by its path), or { unknown: name } when only the page could tell.
+ */
+function resolveVariable(name, ctx, variables) {
+  if (name === "_event" || name === "Event") return { value: ctx.event, field: "event" };
+  if (PAGE_VARIABLES[name]) return ctx.url ? { value: urlPart(ctx.url, PAGE_VARIABLES[name]), field: name } : { unknown: name };
+  const v = variables.find((x) => x.name === name);
+  const p = params(v?.parameter);
+  if (v?.type === "v" && p.name) return { value: readPath(ctx.state, p.name, p.dataLayerVersion ?? "2"), field: p.name };
+  if (v?.type === "c") return { value: p.value, field: name };
+  if (v?.type === "u" && ctx.url) return { value: urlPart(ctx.url, p.component ?? "URL"), field: name };
+  return { unknown: name };
+}
+
+/** A condition argument with its {{variables}} filled in; a lone reference keeps the value's type. */
+function resolveArg(text, ctx, variables) {
+  const whole = /^\{\{(.+)\}\}$/.exec(String(text ?? ""));
+  if (whole) return resolveVariable(whole[1], ctx, variables);
+  let unknown = null;
+  const value = String(text ?? "").replace(/\{\{(.+?)\}\}/g, (_, n) => {
+    const r = resolveVariable(n, ctx, variables);
+    if (r.unknown) unknown = r.unknown;
+    return r.value ?? "";
+  });
+  return unknown ? { unknown } : { value, field: String(text ?? "") };
+}
+
+/** GTM's comparison for one condition type: true, false, or "unknown" for the ones only the page can answer. */
+function compare(type, a, b, ignoreCase) {
+  const s = (v) => (ignoreCase ? String(v ?? "").toLowerCase() : String(v ?? ""));
+  const n = (v) => (v === "" || v === null || v === undefined || typeof v === "object" ? NaN : Number(v));
+  switch (type) {
+    case "EQUALS": return s(a) === s(b);
+    case "CONTAINS": return s(a).includes(s(b));
+    case "STARTS_WITH": return s(a).startsWith(s(b));
+    case "ENDS_WITH": return s(a).endsWith(s(b));
+    case "MATCH_REGEX":
+      try {
+        return new RegExp(String(b ?? ""), ignoreCase ? "i" : "").test(String(a ?? ""));
+      } catch {
+        return "unknown";
+      }
+    case "LESS": return n(a) < n(b);
+    case "LESS_OR_EQUALS": return n(a) <= n(b);
+    case "GREATER": return n(a) > n(b);
+    case "GREATER_OR_EQUALS": return n(a) >= n(b);
+    default: return "unknown";
+  }
+}
+
+/** A value as the reason shows it: numbers bare, text quoted, objects as JSON. */
+const show = (v, m) => (v === undefined || v === null ? m.nothing : typeof v === "object" ? JSON.stringify(v) : typeof v === "string" && !/^-?\d+(\.\d+)?$/.test(v) ? `"${v}"` : String(v));
+
+/** One trigger condition at a push: { ok: true | false | "unknown", reason }, with the reason the report shows when it is not met. */
+function condition(c, ctx, variables, trigger, m) {
+  const type = SHORT_OPS[c.type] ?? c.type;
+  const p = params(c.parameter);
+  if (!m.ops[type]) return { ok: "unknown", reason: m.conditionType(trigger, type) };
+  const a = resolveArg(p.arg0, ctx, variables);
+  const b = resolveArg(p.arg1, ctx, variables);
+  const unknown = a.unknown ?? b.unknown;
+  if (unknown) return { ok: "unknown", reason: m.conditionUnknown(trigger, unknown) };
+  const negate = String(p.negate) === "true";
+  let ok = compare(type, a.value, b.value, String(p.ignore_case) === "true");
+  if (ok === "unknown") return { ok, reason: m.conditionType(trigger, type) };
+  if (negate) ok = !ok;
+  return { ok, reason: ok ? "" : m.condition(trigger, a.field, m.ops[type], show(b.value, m), show(a.value, m), negate) };
+}
+
+/**
+ * Whether a GTM trigger fired in a journey, judged from the recorded dataLayer pushes alone.
+ * @param {any} trigger A trigger from the container export.
+ * @param {{ value: any, url?: string }[]} pushes The run's dataLayerLog entries, in order.
+ * @param {any[]} [variables] The export's variable list, for conditions that read Data Layer Variables.
+ * @returns {{ fired: true | false | "unknown", reason: string, matched?: number }} `matched` is the index of the push it fired on.
+ */
+export function evaluateTrigger(trigger, pushes, variables = [], lang = "en") {
+  const m = messages(lang).gtm;
+  const name = trigger?.name ?? "?";
+  const type = trigger?.type ?? "unknown";
+  const custom = type === "CUSTOM_EVENT";
+  const event = PAGE_EVENTS[type] ?? PAGE_ACTION_EVENTS[type];
+  if (!custom && !event) return { fired: "unknown", reason: m.unknownType(name, type) };
+  const state = {};
+  let seen = false;
+  let failed = null;
+  let unknown = null;
+  for (let i = 0; i < pushes.length; i++) {
+    const model = pushModel(pushes[i]?.value);
+    if (!model) continue;
+    merge(state, model.data);
+    const ctx = { event: model.event, state, url: pushes[i].url };
+    // The event conditions decide whether the push concerns this trigger at all; the filter decides whether it fires.
+    const events = custom ? (trigger.customEventFilter ?? []).map((c) => condition(c, ctx, variables, name, m)) : [{ ok: model.event === event }];
+    if (events.some((r) => r.ok === false)) continue;
+    const vague = events.find((r) => r.ok === "unknown");
+    if (vague) {
+      unknown ??= vague;
+      continue;
+    }
+    seen = true;
+    const result = (trigger.filter ?? []).map((c) => condition(c, ctx, variables, name, m)).find((r) => r.ok !== true);
+    if (!result) return { fired: true, reason: m.triggerFired(name, model.event ?? event), matched: i };
+    if (result.ok === "unknown") unknown ??= result;
+    else failed ??= result;
+  }
+  if (unknown) return { fired: "unknown", reason: unknown.reason };
+  if (failed) return { fired: false, reason: failed.reason };
+  if (PAGE_ACTION_EVENTS[type] && !seen) return { fired: "unknown", reason: m.pageTrigger(name, type.toLowerCase().replace(/_/g, " ")) };
+  if (PAGE_EVENTS[type] && !seen) return { fired: false, reason: m.noPageEvent(name, event) };
+  return { fired: false, reason: m.noPush(triggerEvents(trigger).join(", ") || event || name) };
+}
+
+/** The Consent Mode state after the pushes up to and including `upTo`; a type nobody set is not denied. */
+function consentAt(pushes, upTo) {
+  const state = {};
+  for (const e of pushes.slice(0, upTo + 1)) if (isConsentCommand(e, "default") || isConsentCommand(e, "update")) Object.assign(state, e.value[2] ?? {});
+  return state;
+}
+
+/** Why one tag did or did not fire: its pause state, its triggers, its exceptions and its consent needs, in that order. */
+function evaluateTag(tag, byId, pushes, variables, m, lang) {
+  if (tag.paused) return { fired: false, why: m.paused };
+  if (!tag.triggers.length) return { fired: false, why: m.noTrigger };
+  const raw = (t) => byId.get(String(t.id)) ?? (BUILT_IN_TRIGGERS[t.id] ? { ...BUILT_IN_TRIGGERS[t.id], triggerId: t.id } : null);
+  const evaluate = (t) => (raw(t) ? evaluateTrigger(raw(t), pushes, variables, lang) : { fired: "unknown", reason: m.missingTrigger(t.name) });
+  const results = tag.triggers.map(evaluate);
+  const hit = results.find((r) => r.fired === true);
+  if (!hit) {
+    const vague = results.find((r) => r.fired === "unknown");
+    return vague ? { fired: "unknown", why: vague.reason } : { fired: false, why: results.map((r) => r.reason).join("; ") };
+  }
+  // An exception only stops the tag when it fires on the same push as the firing trigger.
+  for (const b of tag.blocking) {
+    const r = evaluate(b);
+    if (r.fired === true && r.matched === hit.matched) return { fired: false, why: m.blocked(b.name) };
+  }
+  const consent = consentAt(pushes, hit.matched);
+  const denied = tag.consent.find((type) => consent[type] === "denied");
+  if (denied) return { fired: false, why: m.consentDenied(denied) };
+  return { fired: true, why: m.fired };
+}
+
+/**
+ * Adds `evaluation: { fired, why }` to each tag in `finding.gtm`, judged from the run's dataLayer pushes:
+ * whether the tag's triggers fired, whether an exception blocked it, and whether consent allowed it.
+ */
+export function explainTags(finding, run, container, lang = "en") {
+  const m = messages(lang).gtm;
+  const v = container?.containerVersion ?? container ?? {};
+  const byId = new Map((v.trigger ?? []).map((t) => [String(t.triggerId), t]));
+  for (const tag of finding.gtm ?? []) tag.evaluation = evaluateTag(tag, byId, run?.dataLayerLog ?? [], v.variable ?? [], m, lang);
+  return finding;
+}
+
+/**
+ * Adds `gtm` to each finding about one platform event: the tags that send it, or an empty list when none does.
+ * With `runs`, each tag also says whether it should have fired in the finding's journey, and why not.
+ */
+export function annotateFindings(findings, container, runs, { lang = "en" } = {}) {
+  if (!container) return findings;
+  const tags = containerTags(container);
+  if (!tags.length) return findings;
+  for (const f of findings) {
+    if (!f.platform || !f.event || f.severity === "ok") continue;
+    f.gtm = tagsForEvent(tags, f.platform, f.event).map(({ name, type, paused, consent, triggers, blocking }) => ({ name, type, paused, consent, triggers, blocking }));
+    const run = runs?.find((r) => r.journeyId === f.journey && r.viewport === f.viewport);
+    if (run) explainTags(f, run, container, lang);
+  }
+  return findings;
+}

package/src/help.js

@@ -13,6 +13,8 @@ Commands:
   run      Audit what a site actually sends, and compare it to a plan
   replay   Re-check saved sites offline, without AI
   mcp      Start the MCP server for Claude, ChatGPT and other chat apps
+  doctor   Check that Node, Chromium, an AI key and the data folder are ready
+  history  Show how a site's saved runs trend: counts, open problems, flapping, journeys
 
 Examples:
   aitd plan --site https://example.com
@@ -40,12 +42,16 @@ Options:
   --lang <code>        Report language: ${Object.keys(LANGUAGES).join(" or ")}
   --headed             Show the browser window
   --fail-on <level>    Exit 1 at this level: broken (default), risk, warning, never
+  --baseline <file>    Known findings to accept; they don't count toward --fail-on
+  --update-baseline    Write the baseline file after the run (creates it)
 
 AI:  --provider <name>   --model <id|cheap>   (default: whichever API key is set)
 
 Advanced:
-  --max-steps <n>   --platforms <list>   --viewport <name>   --data-dir <dir>
-  --scripted   --no-ai   --save-site <dir>   --save-steps <file>   (see the README)`;
+  --max-steps <n>   --platforms <list>   --viewport <name>   --concurrency <n>   --data-dir <dir>
+  --scripted   --no-ai   --save-site <dir>   --save-steps <file>   (see the README)
+  --scripted replays each journey's fixed steps; a journey without any repeats the steps
+  of its last completed run, which every run saves in its folder as steps.json.`;
 
 const PLAN = `Usage: aitd plan --site <url>
        aitd plan list --site <url>
@@ -99,7 +105,31 @@ Advanced:
   --reports <dir>      Where finished audits write reports (default: ~/ai-tag-debugger-reports)
   --public-url <url>   The HTTPS address of your tunnel or host, so audits can link to reports`;
 
-const HELP = { run: RUN, plan: PLAN, replay: REPLAY, mcp: MCP };
+const DOCTOR = `Usage: aitd doctor [--site <url>] [--data-dir <dir>]
+
+Check that this machine can run an audit: the Node version, Playwright's Chromium, whether
+an AI provider key is set, and that the data folder is writable. Exits with code 1 when a
+check an audit needs fails. A missing AI key is only reported: --no-ai and replay work without one.
+
+Options:
+  --site <url>         Also check that the site is an http(s) address whose host resolves (nothing is fetched)
+  --data-dir <dir>     The folder plans and runs are saved in (default: aitd)`;
+
+const HISTORY = `Usage: aitd history --site <url> [--limit <n>] [--json] [--data-dir <dir>]
+
+Show the trend of a site's saved runs: one row per run with its problem counts and score, a
+text sparkline, the problems open longest, the ones that come and go, and the journeys that do
+not finish every time. Reads the runs in aitd/<domain>/runs/ and its history.json; no browser,
+no AI, nothing is changed.
+
+Options:
+  --site <url>         The site (required)
+  --limit <n>          How many of the newest runs to read (default 30)
+  --json               Print the trend, the finding timeline and the journey stability as JSON
+  --lang <code>        Language of the lines: ${Object.keys(LANGUAGES).join(" or ")}
+  --data-dir <dir>     The folder plans and runs are saved in (default: aitd)`;
+
+const HELP = { run: RUN, plan: PLAN, replay: REPLAY, mcp: MCP, doctor: DOCTOR, history: HISTORY };
 
 /** Help text for a command, or the top-level help when the command is unknown or missing. */
 export function helpText(command) {

package/src/history.js

@@ -0,0 +1,302 @@
+// Run history: what the site's saved runs say over time. changes.js compares a run with the one
+// before it; this module reads every run in the window and turns it into views the report, the CLI
+// and the alert can show: a timeline per finding, a trend series for sparklines and the completion
+// rate of every journey. Only a small summary of each run is kept, so thirty runs cost a few KB.
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { groupFindings } from "./checks.js";
+import { LANGUAGES } from "./i18n.js";
+import { PROVIDERS } from "./parsers.js";
+import { listRunIds, runsDir, siteDir } from "./workspace.js";
+
+/** The per-site index of run summaries, next to the plans and runs folders. */
+export const HISTORY_FILE = "history.json";
+export const historyFile = (dataDir, site) => path.join(siteDir(dataDir, site), HISTORY_FILE);
+
+const INDEX_VERSION = 1;
+const PROBLEMS = new Set(["broken", "risk", "warning"]);
+const SEVERITY_RANK = { broken: 0, risk: 1, warning: 2 };
+// Problems are weighed so one broken event outranks a few warnings when runs are compared.
+const WEIGHT = { broken: 3, risk: 2, warning: 1 };
+// "Recently" and the trend direction both look at the last few runs, not just the last one.
+const RECENT = 3;
+
+/**
+ * The identity of a finding across runs: the same line replay.js writes to site.json ("severity check
+ * journey viewport platform event"), so a replay and the history agree on what "the same finding" is.
+ * Kept inline rather than imported because replay.js loads the browser and the audit, and the report
+ * must stay importable without them. test/history.test.js pins the two to the same output.
+ */
+export const findingKey = (f) => [f.severity, f.check, f.journey, f.viewport, f.platform ?? "-", f.event ?? "-"].join(" ");
+
+/** The id's local time as "YYYY-MM-DDTHH:MM"; the seconds suffix of a same-minute id is dropped. */
+export const dateOfId = (id) => {
+  const m = /^(\d{4}-\d{2}-\d{2})_(\d{2})(\d{2})/.exec(id);
+  return m ? `${m[1]}T${m[2]}:${m[3]}` : null;
+};
+
+/**
+ * The summary of one run that history keeps: its journeys, its counts and its problems, a few hundred
+ * bytes instead of a capture. Fields a capture may lack (older shapes, or ones audit.js does not write
+ * yet such as version and ai) come out null, never throw. Findings a baseline accepted are left out,
+ * as the counts and the verdict leave them out, so an accepted problem is not "still open" in the trend.
+ */
+export function runSummary(id, capture = {}, { version = null, ai = null } = {}) {
+  const findings = Array.isArray(capture.findings) ? capture.findings : [];
+  const counts = { broken: 0, risk: 0, warning: 0, info: 0, ok: 0 };
+  for (const f of groupFindings(findings.filter((f) => f.severity in counts))) if (!f.accepted) counts[f.severity] += 1;
+  const seen = new Set();
+  const problems = [];
+  for (const f of findings) {
+    if (!PROBLEMS.has(f.severity) || !f.check || f.accepted === true) continue;
+    const key = findingKey(f);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    problems.push({ key, check: f.check, severity: f.severity, platform: f.platform ?? null, event: f.event ?? null, journey: f.journey ?? null, viewport: f.viewport ?? null });
+  }
+  const journeys = (Array.isArray(capture.runs) ? capture.runs : [])
+    .filter((r) => r && r.journeyId)
+    .map((r) => ({ id: r.journeyId, viewport: r.viewport ?? null, completed: Boolean(r.completed), hits: Array.isArray(r.hits) ? r.hits.length : 0 }));
+  return { id, date: dateOfId(id), version: capture.version ?? version, ai: capture.ai ?? ai, journeys, counts, findings: problems };
+}
+
+const readJson = (file) => readFile(file, "utf8").then(JSON.parse).catch(() => null);
+
+/** The summaries the index holds, by run id; empty when there is no index or it is unreadable. */
+async function readIndex(dataDir, site) {
+  const index = await readJson(historyFile(dataDir, site));
+  const runs = index?.version === INDEX_VERSION && Array.isArray(index.runs) ? index.runs : [];
+  return new Map(runs.filter((r) => r && typeof r.id === "string").map((r) => [r.id, r]));
+}
+
+/**
+ * The site's most recent `limit` runs, oldest first and newest last, each as a runSummary. Runs with a
+ * missing or unreadable capture.json are skipped. A run already in history.json is taken from there;
+ * the others are read from their capture.json, one at a time so only one capture is ever in memory.
+ * Cost without an index: one read and parse per run (a capture is 100 KB to a few MB, roughly 1-10 ms
+ * per 100 KB), then the parsed object is dropped. With the index, one small file.
+ */
+export async function loadHistory(dataDir, site, { limit = 30 } = {}) {
+  const ids = (await listRunIds(dataDir, site)).slice(-Math.max(0, limit));
+  const indexed = await readIndex(dataDir, site);
+  const out = [];
+  for (const id of ids) {
+    const known = indexed.get(id);
+    if (known) {
+      out.push(known);
+      continue;
+    }
+    const capture = await readJson(path.join(runsDir(dataDir, site), id, "capture.json"));
+    if (capture && typeof capture === "object") out.push(runSummary(id, capture));
+  }
+  return out;
+}
+
+/**
+ * Adds one run to the site's history.json (or replaces its entry) so later reports and CLI calls do not
+ * re-read every capture. `run` is { id, capture, version?, ai? } or an existing runSummary. Entries whose
+ * run folder is gone are dropped. Never throws on a missing or corrupt index: it is rebuilt from the run.
+ */
+export async function updateHistoryIndex(dataDir, site, run) {
+  const entry = run.capture ? runSummary(run.id, run.capture, { version: run.version ?? null, ai: run.ai ?? null }) : run;
+  const indexed = await readIndex(dataDir, site);
+  indexed.set(entry.id, entry);
+  const onDisk = new Set(await listRunIds(dataDir, site));
+  const runs = [...indexed.values()].filter((r) => r.id === entry.id || onDisk.has(r.id)).sort((a, b) => (a.id < b.id ? -1 : 1));
+  const file = historyFile(dataDir, site);
+  await writeFile(file, JSON.stringify({ version: INDEX_VERSION, site, updated: new Date().toISOString(), runs }, null, 2));
+  return { file, runs: runs.length };
+}
+
+/** Whether a run gives evidence about a journey: it ran and completed. An incomplete journey proves nothing by absence. */
+const observed = (run) => new Set(run.journeys.filter((j) => j.completed).map((j) => `${j.id}|${j.viewport}`));
+
+/**
+ * One entry per finding seen in the window, oldest open first:
+ * { key, check, severity, platform, event, journey, viewport, firstSeen, lastSeen, seenIn, openNow, openSince,
+ *   flapping, fixedIn }. A run where the finding's journey did not complete says nothing: it is neither "seen"
+ * nor "gone", so a crashed checkout does not count as a fix. flapping: seen, gone, then seen again.
+ * fixedIn: the first run after lastSeen where the journey completed without it; null while open.
+ */
+export function findingTimeline(history) {
+  const entries = new Map();
+  for (const run of history) {
+    for (const f of run.findings) {
+      if (!entries.has(f.key)) entries.set(f.key, { ...f, states: [] });
+    }
+  }
+  for (const run of history) {
+    const present = new Set(run.findings.map((f) => f.key));
+    const ok = observed(run);
+    for (const e of entries.values()) {
+      // A finding from an older capture without a journey has no completion to check: absence means gone.
+      const state = present.has(e.key) ? "seen" : !e.journey || ok.has(`${e.journey}|${e.viewport}`) ? "gone" : null;
+      e.states.push({ id: run.id, state });
+    }
+  }
+  const out = [];
+  for (const e of entries.values()) {
+    const { states, ...rest } = e;
+    const known = states.filter((s) => s.state);
+    const seen = known.filter((s) => s.state === "seen");
+    const firstSeen = seen[0].id;
+    const lastSeen = seen.at(-1).id;
+    const openNow = known.at(-1).state === "seen";
+    // Open since the start of the current unbroken streak, which is firstSeen unless it flapped.
+    let openSince = null;
+    for (let i = known.length - 1; i >= 0 && known[i].state === "seen"; i--) openSince = known[i].id;
+    const between = known.filter((s) => s.id > firstSeen && s.id < lastSeen);
+    const flapping = between.some((s) => s.state === "gone");
+    const fixedIn = openNow ? null : known.find((s) => s.id > lastSeen && s.state === "gone").id;
+    out.push({ ...rest, firstSeen, lastSeen, seenIn: seen.length, openNow, openSince, flapping, fixedIn });
+  }
+  return out.sort(byOpenLongest);
+}
+
+/** Open findings first, the one open longest on top; then the fixed ones, the most recently fixed on top. */
+function byOpenLongest(a, b) {
+  if (a.openNow !== b.openNow) return a.openNow ? -1 : 1;
+  if (a.openNow) return a.openSince < b.openSince ? -1 : a.openSince > b.openSince ? 1 : bySeverity(a, b);
+  return a.fixedIn > b.fixedIn ? -1 : a.fixedIn < b.fixedIn ? 1 : bySeverity(a, b);
+}
+
+const bySeverity = (a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+
+/**
+ * The same problem on several journeys or viewports as one entry with its places, as the report groups
+ * findings. The first entry in timeline order speaks for the group, so its dates are the longest open.
+ */
+function grouped(entries) {
+  const out = new Map();
+  for (const { journey, viewport, ...e } of entries) {
+    const k = [e.severity, e.check, e.platform, e.event].join("|");
+    if (out.has(k)) out.get(k).places.push({ journey, viewport });
+    else out.set(k, { ...e, places: [{ journey, viewport }] });
+  }
+  return [...out.values()];
+}
+
+const score = (c) => c.broken * WEIGHT.broken + c.risk * WEIGHT.risk + c.warning * WEIGHT.warning;
+const mean = (xs) => xs.reduce((a, b) => a + b, 0) / xs.length;
+
+/**
+ * The series for sparklines plus a summary of the window.
+ * series: per run { id, date, broken, risk, warning, score, complete }, oldest first. score is
+ * 3·broken + 2·risk + warning (lower is better); complete is false when a journey did not finish.
+ * direction: the mean score of the last 3 complete runs against the 3 complete runs before them
+ * ("improving" when lower, "worsening" when higher, else "flat"); with fewer than 4 complete runs the
+ * two halves are compared, and with fewer than 2 it is "flat". Incomplete runs are left out because a
+ * journey that stopped early hides findings rather than fixing them.
+ * openLongest: the 5 problems open longest; fixedRecently / newRecently: fixed or first seen in the
+ * last 3 runs; flapping: seen, gone and seen again in the window. Each list has one entry per problem
+ * with its `places` (journey and viewport, as the report groups findings) and its `runsOpen` count.
+ */
+export function trend(history) {
+  const series = history.map((r) => ({ id: r.id, date: r.date, broken: r.counts.broken, risk: r.counts.risk, warning: r.counts.warning, score: score(r.counts), complete: r.journeys.every((j) => j.completed) }));
+  const timeline = findingTimeline(history);
+  const ids = history.map((r) => r.id);
+  const recentIds = new Set(ids.slice(-RECENT));
+  const withAge = (e) => ({ ...e, runsOpen: e.openNow ? ids.length - ids.indexOf(e.openSince) : 0 });
+  return {
+    runs: ids.length,
+    first: ids[0] ?? null,
+    last: ids.at(-1) ?? null,
+    series,
+    direction: direction(series.filter((p) => p.complete).map((p) => p.score)),
+    openLongest: grouped(timeline.filter((e) => e.openNow)).slice(0, 5).map(withAge),
+    fixedRecently: grouped(timeline.filter((e) => e.fixedIn && recentIds.has(e.fixedIn))).map(withAge),
+    newRecently: grouped(timeline.filter((e) => e.openNow && recentIds.has(e.firstSeen))).map(withAge),
+    flapping: grouped(timeline.filter((e) => e.flapping)).map(withAge),
+  };
+}
+
+function direction(scores) {
+  if (scores.length < 2) return "flat";
+  const n = Math.min(RECENT, Math.floor(scores.length / 2));
+  const recent = mean(scores.slice(-n));
+  const earlier = mean(scores.slice(-2 * n, -n));
+  return recent < earlier ? "improving" : recent > earlier ? "worsening" : "flat";
+}
+
+/**
+ * How reliably each journey finishes on this site, least reliable first: per journey and viewport
+ * { id, viewport, runs, completed, completionRate, lastFailure, avgHits }. A journey that keeps
+ * failing says the AI or the script cannot get through the site, not that the tracking is bad.
+ */
+export function journeyStability(history) {
+  const out = new Map();
+  for (const run of history) {
+    for (const j of run.journeys) {
+      const k = `${j.id}|${j.viewport}`;
+      const s = out.get(k) ?? { id: j.id, viewport: j.viewport, runs: 0, completed: 0, lastFailure: null, hits: 0 };
+      s.runs += 1;
+      s.hits += j.hits;
+      if (j.completed) s.completed += 1;
+      else s.lastFailure = run.id;
+      out.set(k, s);
+    }
+  }
+  return [...out.values()]
+    .map(({ hits, ...s }) => ({ ...s, completionRate: s.runs ? s.completed / s.runs : 0, avgHits: s.runs ? Math.round((hits / s.runs) * 10) / 10 : 0 }))
+    .sort((a, b) => a.completionRate - b.completionRate || a.id.localeCompare(b.id) || String(a.viewport).localeCompare(String(b.viewport)));
+}
+
+const day = (id) => (id ? String(id).slice(0, 10) : "");
+const platformLabel = (p) => (p ? PROVIDERS[p] ?? String(p) : "");
+/** "GA4 purchase missing_params" or, for a finding without an event, the check name. */
+const label = (e) => `${platformLabel(e.platform)} ${e.event ?? ""}`.trim().concat(` ${e.check}`).trim();
+/** The strings of ui.history in the report's language; an unknown language falls back to English rather than throwing. */
+const strings = (lang) => (LANGUAGES[lang] ?? LANGUAGES.en).ui.history;
+/** "GA4 purchase missing_params in 4 places": the problem with its place count when it is seen in more than one. */
+export const problemLabel = (e, lang = "en") => `${label(e)}${e.places?.length > 1 ? strings(lang).places(e.places.length) : ""}`;
+
+const SPARK = "▁▂▃▄▅▆▇█";
+
+/**
+ * The trend series as a text sparkline for the CLI and the alert: one character per run, the score
+ * mapped onto eight levels over 0..max, "·" for a run that did not complete (its lower counts are not
+ * a fix). The scale starts at 3 so one warning does not draw a full bar. Empty under two runs.
+ */
+export function sparkline(t) {
+  const series = t?.series ?? [];
+  if (series.length < 2) return "";
+  const max = Math.max(3, ...series.map((p) => p.score));
+  return series.map((p) => (p.complete ? SPARK[Math.min(SPARK.length - 1, Math.round((p.score / max) * (SPARK.length - 1)))] : "·")).join("");
+}
+
+/**
+ * The trend as 2-3 plain lines for the CLI after a run and for the alert: the direction with the counts
+ * now and three runs ago, the findings open longest (up to 3), and the flapping ones when there are any.
+ * Pass the stability list to add a line on journeys that do not always finish.
+ */
+export function historySummaryLines(t, lang = "en", stability = []) {
+  const s = strings(lang);
+  if (!t.runs) return [s.noRuns];
+  if (t.runs === 1) return [s.oneRun(t.last)];
+  const now = t.series.at(-1);
+  const was = t.series.at(-1 - RECENT);
+  const dir = s.direction[t.direction];
+  const lines = [was ? s.headline(t.runs, day(t.first), day(t.last), dir, s.counts(now), s.counts(was), RECENT) : s.headlineShort(t.runs, day(t.first), day(t.last), dir, s.counts(now))];
+  if (t.openLongest.length) lines.push(s.openLongest(t.openLongest.slice(0, 3).map((e) => s.since(problemLabel(e, lang), day(e.openSince), e.runsOpen))));
+  if (t.flapping.length) lines.push(s.flapping(t.flapping.slice(0, 3).map((e) => s.seenIn(problemLabel(e, lang), e.seenIn, t.runs))));
+  const unstable = stability.filter((j) => j.completionRate < 1);
+  if (unstable.length) lines.push(s.unstable(unstable.slice(0, 3).map((j) => `${j.id} (${j.viewport}) ${Math.round(j.completionRate * 100)}%`)));
+  return lines;
+}
+
+/**
+ * The trend as the alert shows it: the direction line with the text sparkline, the flapping line, and
+ * "still open after N runs" only when a problem has just reached a round number of runs (5, 10, 20, …),
+ * so the open-longest list does not repeat in every message and train readers to skip it.
+ */
+export function historyAlertLines(t, lang = "en") {
+  const s = strings(lang);
+  if (!t || t.runs < 2) return [];
+  const lines = [`${historySummaryLines(t, lang)[0]} \`${sparkline(t)}\``];
+  if (t.flapping.length) lines.push(s.flapping(t.flapping.slice(0, 3).map((e) => s.seenIn(problemLabel(e, lang), e.seenIn, t.runs))));
+  // A round number of runs open (5, 10, 20, then every 10) is worth one line; every other week it is noise.
+  const milestone = (n) => [5, 10, 20].includes(n) || (n > 20 && n % 10 === 0);
+  const ages = [...new Set(t.openLongest.filter((e) => milestone(e.runsOpen)).map((e) => e.runsOpen))].sort((a, b) => b - a);
+  for (const n of ages) lines.push(s.stillOpen(n, t.openLongest.filter((e) => e.runsOpen === n).map((e) => problemLabel(e, lang))));
+  return lines;
+}