@analitikisler/ai-tag-debugger 0.16.0 → 0.18.0

package/src/cli.js

@@ -5,7 +5,9 @@ import { parseArgs } from "node:util";
 import { loadConfig, runAudit } from "./audit.js";
 import { messages } from "./i18n.js";
 import { helpText } from "./help.js";
+import { validatePlan } from "./schema.js";
 import { replaySavedSite, writeSavedSteps } from "./replay.js";
+import { readBaseline, writeBaseline } from "./baseline.js";
 import { savePlan } from "./plan.js";
 import { DEFAULT_DATA_DIR } from "./workspace.js";
 import { commandText, intentToArgs, isSentence, needsWhatToTest, translate } from "./ask.js";
@@ -25,6 +27,7 @@ async function main(args = process.argv.slice(2)) {
       out: { type: "string" },
       journey: { type: "string", multiple: true },
       viewport: { type: "string", multiple: true },
+      concurrency: { type: "string" },
       platforms: { type: "string", multiple: true },
       providers: { type: "string", multiple: true },
       "allow-host": { type: "string", multiple: true },
@@ -36,6 +39,8 @@ async function main(args = process.argv.slice(2)) {
       "base-url": { type: "string" },
       lang: { type: "string" },
       "fail-on": { type: "string", default: "broken" },
+      baseline: { type: "string" },
+      "update-baseline": { type: "boolean", default: false },
       headed: { type: "boolean", default: false },
       "no-branding": { type: "boolean", default: false },
       "keep-bodies": { type: "boolean", default: false },
@@ -53,6 +58,8 @@ async function main(args = process.argv.slice(2)) {
       from: { type: "string" },
       topic: { type: "string" },
       format: { type: "string" },
+      limit: { type: "string" },
+      json: { type: "boolean", default: false },
       force: { type: "boolean", default: false },
       yes: { type: "boolean", short: "y", default: false },
       help: { type: "boolean", short: "h", default: false },
@@ -131,6 +138,18 @@ async function main(args = process.argv.slice(2)) {
     console.log(`✓ Saved plan ${id}: ${plan.events.length} events (${custom} custom) and ${plan.user_properties.length} user properties in ${rel.startsWith("..") ? dir : rel}`);
     return;
   }
+  if (command === "history" && !values.help) {
+    await showHistory(values);
+    return;
+  }
+  if (command === "doctor" && !values.help) {
+    const { doctorChecks } = await import("./doctor.js");
+    const checks = await doctorChecks({ site: values.site, dataDir: values["data-dir"] });
+    for (const c of checks) console.log(`${c.ok ? "✓" : "✗"} ${c.text}`);
+    // Only a check an audit cannot run without fails the command; a missing AI key is advice.
+    if (checks.some((c) => c.hard && !c.ok)) process.exitCode = 1;
+    return;
+  }
   if (values.help || command !== "run" || (!values.config && !values.site && !values.against)) {
     console.log(helpText(command));
     process.exit(values.help ? 0 : 2);
@@ -161,6 +180,8 @@ async function main(args = process.argv.slice(2)) {
     against = await resolvePlan(values.against, { dataDir: values["data-dir"] ?? DEFAULT_DATA_DIR, site: loaded.config.site });
     const plan = await readJson(against.file);
     if (!Array.isArray(plan?.events)) throw new Error(`${against.file} is not a plan: it needs an "events" list.`);
+    // loadConfig checked the config's own plan; the one --against names replaces it and gets the same check.
+    for (const w of validatePlan(plan, { file: against.file }).warnings) console.log(w);
     if (!loaded.config.site) {
       if (!plan.site) throw new Error(`${against.file} has no "site". Add --site <url>.`);
       loaded.config = { ...loaded.config, site: plan.site };
@@ -178,6 +199,17 @@ async function main(args = process.argv.slice(2)) {
   if (maxSteps !== undefined && !(Number.isInteger(maxSteps) && maxSteps > 0)) throw new Error("--max-steps must be a positive whole number.");
   // run --out is a hidden alias kept for one minor version; --data-dir replaces it.
   if (values.out) console.log("Note: run --out will be removed in a later version. Runs are saved in aitd/<domain>/runs/<id>/; use --data-dir <dir> to keep them elsewhere.");
+  const baselineFile = values.baseline ?? loaded.baselineFile ?? null;
+  if (values["update-baseline"] && !baselineFile) throw new Error('--update-baseline needs --baseline <file> or "baseline" in the config.');
+  // A baseline that doesn't exist yet is fine when this run writes it.
+  const baseline = baselineFile
+    ? await readBaseline(baselineFile).catch((err) => {
+        if (values["update-baseline"] && err.code === "ENOENT") return null;
+        throw err;
+      })
+    : null;
+  // A baseline written for another site matches nothing of this one, so say so, but let the run go on.
+  if (baseline?.site && baseline.site !== loaded.config.site) console.log(`Warning: the baseline ${baselineFile} was written for ${baseline.site}, not ${loaded.config.site}. Its entries may not match this site.`);
   const result = await runAudit({
     ...loaded,
     journeys: values.journey,
@@ -185,6 +217,7 @@ async function main(args = process.argv.slice(2)) {
     events: (values.events ?? []).flatMap((e) => e.split(",")).map((e) => e.trim()).filter(Boolean),
     maxSteps,
     viewports: values.viewport,
+    concurrency: values.concurrency,
     providers: platforms.length ? platforms.flatMap((p) => p.split(",")) : undefined,
     scripted: values.scripted,
     ai: !values["no-ai"],
@@ -198,12 +231,27 @@ async function main(args = process.argv.slice(2)) {
     dataDir: values["data-dir"],
     saveSite: values["save-site"],
     against,
+    failOn,
+    baseline,
     log: (msg) => console.log(msg),
   });
 
-  console.log(`\n${messages(result.lang).ui.counts(result.counts)}`);
-  const rel = path.relative(process.cwd(), result.reportPath);
-  console.log(`Report: ${rel.startsWith("..") ? result.reportPath : rel}`);
+  const m = messages(result.lang);
+  console.log(`\n${m.ui.counts(result.counts)}`);
+  if (result.baseline) console.log(`${result.baseline.accepted} accepted (baseline ${baselineFile}), ${result.baseline.partial ? `${result.baseline.partial} ${result.baseline.partial === 1 ? "problem" : "problems"} accepted in some places only (still counted), ` : ""}${result.baseline.stale.length} stale baseline ${result.baseline.stale.length === 1 ? "entry" : "entries"}`);
+  if (result.verdict) console.log(m.ui.cli.verdict(result.verdict.statusText, result.verdict.headline, result.verdict.score));
+  // The trend needs two saved runs; with one there is nothing to say yet.
+  if (result.trend?.runs >= 2) {
+    const { historySummaryLines } = await import("./history.js");
+    for (const line of historySummaryLines(result.trend, result.lang, result.stability ?? []).slice(0, 3)) console.log(line);
+  }
+  const shown = (p) => (path.relative(process.cwd(), p).startsWith("..") ? p : path.relative(process.cwd(), p));
+  console.log(`Report: ${shown(result.reportPath)}`);
+  console.log(`Summary: ${shown(result.summaryPath)} (junit.xml next to it)`);
+  if (values["update-baseline"]) {
+    const n = await writeBaseline(baselineFile, { site: loaded.config.site, findings: result.findings });
+    console.log(`Baseline ${baselineFile} now holds ${n} ${n === 1 ? "finding" : "findings"}. Later runs with --baseline fail only on new ones.`);
+  }
 
   if (!against && !values.out) await offerLearnedPlan(result, loaded.config.site, values);
 
@@ -224,6 +272,39 @@ async function main(args = process.argv.slice(2)) {
   }
 }
 
+// aitd history --site <url>: the trend of the site's saved runs as a small table, the text sparkline and the summary lines.
+async function showHistory(values) {
+  if (!values.site) throw new Error("history needs --site <url>: aitd history --site https://www.example.com");
+  const limit = values.limit ? Number(values.limit) : 30;
+  if (!(Number.isInteger(limit) && limit > 0)) throw new Error("--limit must be a positive whole number.");
+  const lang = values.lang ?? "en";
+  const m = messages(lang);
+  const { domainOf } = await import("./workspace.js");
+  domainOf(values.site);
+  const { findingTimeline, historySummaryLines, journeyStability, loadHistory, sparkline, trend } = await import("./history.js");
+  const history = await loadHistory(values["data-dir"] ?? DEFAULT_DATA_DIR, values.site, { limit });
+  const t = trend(history);
+  const stability = journeyStability(history);
+  if (values.json) {
+    console.log(JSON.stringify({ site: values.site, runs: history.length, trend: t, timeline: findingTimeline(history), stability }, null, 2));
+    return;
+  }
+  if (!history.length) {
+    console.log(m.ui.history.noRuns);
+    return;
+  }
+  const cols = [m.ui.cli.runCol, m.severity.broken, m.severity.risk, m.severity.warning, m.ui.cli.scoreCol, m.ui.cli.completeCol];
+  const rows = t.series.map((p) => [p.id, p.broken, p.risk, p.warning, p.score, p.complete ? m.ui.md.yes : m.ui.md.no].map(String));
+  const widths = cols.map((c, i) => Math.max(c.length, ...rows.map((r) => r[i].length)));
+  const line = (cells) => cells.map((c, i) => (i ? c.padStart(widths[i]) : c.padEnd(widths[i]))).join("  ");
+  console.log(line(cols));
+  for (const r of rows) console.log(line(r));
+  console.log("");
+  const s = m.ui.history;
+  if (t.runs >= 2) console.log(s.sparkline(sparkline(t), s.direction[t.direction], t.runs, t.first.slice(0, 10), t.last.slice(0, 10)));
+  for (const l of historySummaryLines(t, lang, stability)) console.log(l);
+}
+
 // The first run of a site with no plan: offer what it already tracks as its plan.
 async function offerLearnedPlan(result, site, values) {
   const dataDir = values["data-dir"] ?? DEFAULT_DATA_DIR;

package/src/consent.js

@@ -2,6 +2,7 @@
 // (accept all, reject all, analytics only), to show which tags each choice lets through.
 // Runs on its own with every audit when the page shows a consent banner.
 import { AuditSession, CMP_BANNER_SELECTORS } from "./browser.js";
+import { runPool } from "./pool.js";
 
 export const CONSENT_STATES = ["accept", "reject", "analytics"];
 // Tags that are advertising, so an "analytics only" choice should keep them quiet.
@@ -110,6 +111,7 @@ async function runState(config, state, opts) {
 /**
  * Runs every consent scenario on the site's start page. Returns null when the page has no consent
  * banner the tool can answer (the first choice found nothing to click), so the report leaves the section out.
+ * opts.concurrency runs the other choices side by side, each in its own browser; default 1.
  * @returns {Promise<null | { cmp: string, before: object, states: Record<string, { via: string|null, after?: object, error?: string }> }>}
  */
 export async function runConsentScenarios(config, opts = {}) {
@@ -117,8 +119,8 @@ export async function runConsentScenarios(config, opts = {}) {
   const first = await runState(config, "accept", opts);
   if (!first.via) return null;
   log(`\n▶ consent scenarios (${first.via})`);
-  const results = [first];
-  for (const state of CONSENT_STATES.slice(1)) results.push(await runState(config, state, opts));
+  // The first choice shows whether there is a banner to answer at all; the others don't depend on each other.
+  const results = [first, ...(await runPool(CONSENT_STATES.slice(1), opts.concurrency ?? 1, (state) => runState(config, state, opts)))];
   const states = {};
   for (const r of results) {
     states[r.state] = r.error ? { via: null, error: r.error } : { via: r.via, ...(r.after ? { after: r.after } : {}) };

package/src/doctor.js

@@ -0,0 +1,68 @@
+// `aitd doctor`: one line per thing an audit needs, so a broken setup is found before a run starts.
+import { existsSync, readFileSync } from "node:fs";
+import { access, constants, stat } from "node:fs/promises";
+import { lookup } from "node:dns/promises";
+import path from "node:path";
+import { aiStatus } from "./providers.js";
+import { DEFAULT_DATA_DIR } from "./workspace.js";
+
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+
+// The same as minNodeMajor() in scripts/setup.js, which the published package doesn't ship.
+const minNodeMajor = (range) => Number(/(\d+)/.exec(range ?? "")?.[1] ?? 0);
+
+/** The nearest existing directory at or above dir, since the data dir is only created by the first run. */
+function existingAncestor(dir, exists) {
+  let d = dir;
+  while (!exists(d) && path.dirname(d) !== d) d = path.dirname(d);
+  return d;
+}
+
+/**
+ * Runs the checks and returns [{ ok, hard, text }]. A failed hard check means audits can't run;
+ * a soft one is advice. Everything that touches the machine can be injected, so tests need no
+ * browser or network.
+ */
+export async function doctorChecks({ site, dataDir = DEFAULT_DATA_DIR, nodeVersion = process.version, chromiumPath, env = process.env, exists = existsSync, writable = writableDir, resolve = lookup } = {}) {
+  const checks = [];
+  const range = pkg.engines?.node;
+  const nodeOk = Number(/^v?(\d+)/.exec(nodeVersion)?.[1] ?? 0) >= minNodeMajor(range);
+  checks.push({ ok: nodeOk, hard: true, text: nodeOk ? `Node ${nodeVersion} (needs ${range})` : `Node ${nodeVersion} is too old: this needs Node ${range}. Install a newer Node, for example with nvm: nvm install 22` });
+
+  const pw = pkg.dependencies.playwright;
+  chromiumPath ??= (await import("playwright")).chromium.executablePath();
+  const chromiumOk = Boolean(chromiumPath && exists(chromiumPath));
+  checks.push({ ok: chromiumOk, hard: true, text: chromiumOk ? `Playwright ${pw} with Chromium at ${chromiumPath}` : `Playwright ${pw} has no Chromium installed. Run: npx -y playwright@${pw} install chromium` });
+
+  // The same line `aitd` with no arguments prints. No key is not a failure: --no-ai and replay work without one.
+  const ai = aiStatus({}, env);
+  const aiOk = !ai.startsWith("AI: no key set");
+  checks.push({ ok: aiOk, hard: false, text: aiOk ? ai : `${ai}. Optional: --no-ai and replay work without a key` });
+
+  const dir = path.resolve(dataDir);
+  const probe = existingAncestor(dir, exists);
+  const dirOk = await writable(probe).then(() => true, () => false);
+  checks.push({ ok: dirOk, hard: true, text: dirOk ? `Data folder ${dir} is writable${probe === dir ? "" : " (it will be created)"}` : `Data folder ${dir} is not writable (checked ${probe}). Pick another with --data-dir <dir>` });
+
+  if (site !== undefined) checks.push(await siteCheck(site, resolve));
+  return checks;
+}
+
+/** Rejects unless d is a directory the process may write to: a data dir under a file can never be created, whatever the permissions say. */
+async function writableDir(d) {
+  if (!(await stat(d)).isDirectory()) throw new Error(`${d} is not a directory`);
+  await access(d, constants.W_OK);
+}
+
+/** The site is an http(s) address whose host resolves. Nothing is fetched. */
+async function siteCheck(site, resolve) {
+  let u;
+  try {
+    u = new URL(site);
+  } catch {
+    return { ok: false, hard: true, text: `"${site}" is not a full URL. Use the form https://www.example.com` };
+  }
+  if (!["http:", "https:"].includes(u.protocol)) return { ok: false, hard: true, text: `${site} is not an http or https address, so the browser can't open it` };
+  const found = await resolve(u.hostname).then(() => true, () => false);
+  return { ok: found, hard: true, text: found ? `${u.hostname} resolves` : `${u.hostname} does not resolve. Check the address, or your network and DNS` };
+}

package/src/gtm.js

@@ -1,10 +1,22 @@
 // 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 } from "./checks.js";
+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. */
@@ -79,14 +91,208 @@ export function tagsForEvent(tags, platform, event) {
   return tags.filter((t) => t.platform === platform && t.events.some((e) => canonicalEvent(e) === want));
 }
 
-/** Adds `gtm` to each finding about one platform event: the tags that send it, or an empty list when none does. */
-export function annotateFindings(findings, container) {
+/** 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) {