@analitikisler/ai-tag-debugger 0.13.0 → 0.15.0

package/src/notify.js

@@ -0,0 +1,108 @@
+// Alerts after a saved run: the "since last run" diff, sent to Slack and/or by email.
+// Set in the config:
+//   "notify": { "slack": "https://hooks.slack.com/services/…", "email": "team@example.com" }
+// "slack": true reads the webhook from SLACK_WEBHOOK_URL. Email goes through the SMTP server in
+// SMTP_URL (smtps://user:pass@host:465 or smtp://host:25), from SMTP_FROM (default: the "to" address).
+// Nothing is sent when there is no earlier run or nothing changed.
+import { connect as tlsConnect } from "node:tls";
+import { connect as netConnect } from "node:net";
+import { changesLines } from "./changes.js";
+import { messages } from "./i18n.js";
+
+/** True when there is an earlier run and something was fixed, broke or took a new route since. */
+export const hasChanges = (ch) => Boolean(ch?.previous && (ch.fixed.length || ch.new.length || ch.routes?.length));
+
+const list = (v) => (Array.isArray(v) ? v : v ? [v] : []);
+
+/** The alert's subject and plain-text body. changes carries the run id as `run` (see sinceLastRun). */
+export function alertMessage({ site, changes, lang = "en", reportPath = null }) {
+  const subject = `${site}: ${messages(lang).ui.changesLine(changes)}`;
+  const body = [`${site}`, ...changesLines(changes, lang), ...(reportPath ? ["", reportPath] : [])].join("\n");
+  return { subject, body };
+}
+
+/**
+ * Sends the diff to every channel in `notify`. Never throws: returns { sent: [...], errors: [...] }.
+ * @param {{ notify: any, site: string, changes: any, lang?: string, reportPath?: string,
+ *   env?: Record<string, string | undefined>, fetchImpl?: typeof fetch, smtp?: (url: string, mail: any) => Promise<void> }} opts
+ */
+export async function sendAlerts({ notify, site, changes, lang = "en", reportPath = null, env = process.env, fetchImpl = fetch, smtp = sendSmtp }) {
+  const sent = [];
+  const errors = [];
+  if (!notify || !hasChanges(changes)) return { sent, errors };
+  const { subject, body } = alertMessage({ site, changes, lang, reportPath });
+  const slack = notify.slack === true ? env.SLACK_WEBHOOK_URL : notify.slack;
+  if (slack) {
+    try {
+      const res = await fetchImpl(slack, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ text: body }) });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      sent.push("slack");
+    } catch (err) {
+      errors.push(`Slack: ${err.message}`);
+    }
+  } else if (notify.slack === true) errors.push("Slack: SLACK_WEBHOOK_URL is not set");
+  const to = list(notify.email);
+  if (to.length) {
+    try {
+      if (!env.SMTP_URL) throw new Error("SMTP_URL is not set");
+      await smtp(env.SMTP_URL, { from: env.SMTP_FROM || to[0], to, subject, text: body });
+      sent.push("email");
+    } catch (err) {
+      errors.push(`Email: ${err.message}`);
+    }
+  }
+  return { sent, errors };
+}
+
+/** A minimal SMTP client: smtps:// (TLS from the start) or smtp:// (plain), AUTH LOGIN when the URL has a user. */
+export function sendSmtp(url, { from, to, subject, text }) {
+  const u = new URL(url);
+  const secure = u.protocol === "smtps:";
+  const port = Number(u.port || (secure ? 465 : 25));
+  const socket = secure ? tlsConnect({ host: u.hostname, port, servername: u.hostname }) : netConnect({ host: u.hostname, port });
+  const b64 = (s) => Buffer.from(s).toString("base64");
+  const clean = (s) => String(s).replace(/[\r\n]+/g, " ");
+  const data = [
+    `From: ${clean(from)}`,
+    `To: ${to.map(clean).join(", ")}`,
+    `Subject: =?UTF-8?B?${b64(clean(subject))}?=`,
+    "MIME-Version: 1.0",
+    "Content-Type: text/plain; charset=UTF-8",
+    "Content-Transfer-Encoding: base64",
+    "",
+    b64(text).replace(/.{76}/g, "$&\r\n"),
+    ".",
+  ].join("\r\n");
+  const steps = [
+    null, // greeting
+    `EHLO ${clean(u.hostname)}`,
+    ...(u.username ? ["AUTH LOGIN", b64(decodeURIComponent(u.username)), b64(decodeURIComponent(u.password))] : []),
+    `MAIL FROM:<${clean(from)}>`,
+    ...to.map((t) => `RCPT TO:<${clean(t)}>`),
+    "DATA",
+    data,
+    "QUIT",
+  ];
+  return new Promise((resolve, reject) => {
+    let buf = "";
+    let i = 0;
+    socket.setTimeout(20000, () => socket.destroy(new Error("SMTP timed out")));
+    socket.on("error", reject);
+    socket.on("data", (chunk) => {
+      buf += chunk;
+      // A reply is complete at a line "NNN text" (a dash after the code means more lines follow).
+      const lines = buf.split("\r\n");
+      const last = lines.findLastIndex((l) => /^\d{3} /.test(l));
+      if (last < 0) return;
+      const reply = lines[last];
+      buf = lines.slice(last + 1).join("\r\n");
+      if (!/^[23]/.test(reply)) return socket.destroy(new Error(`SMTP said: ${reply}`));
+      i += 1;
+      if (i < steps.length) socket.write(`${steps[i]}\r\n`);
+      else {
+        socket.end();
+        resolve();
+      }
+    });
+  });
+}

package/src/providers.js

@@ -8,11 +8,14 @@
 // Tools use one neutral shape: { name, description, schema } where schema is JSON Schema.
 
 export const PROVIDERS = {
-  anthropic: { label: "Anthropic (Claude)", env: "ANTHROPIC_API_KEY", defaultModel: "claude-opus-5-5" },
-  openai: { label: "OpenAI", env: "OPENAI_API_KEY", defaultModel: "gpt-5.5" },
-  gemini: { label: "Google Gemini", env: "GEMINI_API_KEY", defaultModel: "gemini-pro-latest" },
+  // cheapModel is what `--model cheap` picks: a small, inexpensive model for routine CI runs.
+  anthropic: { label: "Anthropic (Claude)", env: "ANTHROPIC_API_KEY", defaultModel: "claude-opus-5-5", cheapModel: "claude-haiku-5-5" },
+  openai: { label: "OpenAI", env: "OPENAI_API_KEY", defaultModel: "gpt-5.5", cheapModel: "gpt-5.5-mini" },
+  gemini: { label: "Google Gemini", env: "GEMINI_API_KEY", defaultModel: "gemini-pro-latest", cheapModel: "gemini-flash-latest" },
   // Vercel AI Gateway: one key, any model as "<provider>/<model>". OpenAI-compatible API.
-  vercel: { label: "Vercel AI Gateway", env: "AI_GATEWAY_API_KEY", defaultModel: "anthropic/claude-opus-5.5" },
+  vercel: { label: "Vercel AI Gateway", env: "AI_GATEWAY_API_KEY", defaultModel: "anthropic/claude-opus-5.5", cheapModel: "anthropic/claude-haiku-5.5" },
+  // Cloudflare Workers AI: open models on Cloudflare's network, billed per use. OpenAI-compatible API.
+  cloudflare: { label: "Cloudflare Workers AI", env: "CLOUDFLARE_API_TOKEN", defaultModel: "@cf/meta/llama-3.3-70b-instruct-fp8-fast", cheapModel: "@cf/meta/llama-3.3-70b-instruct-fp8-fast" },
   // Any API that speaks the OpenAI chat completions protocol. Needs a base URL and a model.
   "openai-compatible": { label: "OpenAI-compatible API", env: "OPENAI_COMPATIBLE_API_KEY", defaultModel: null },
 };
@@ -25,16 +28,17 @@ export function resolveProviderName(name, env = process.env) {
   }
   if (env.OPENAI_COMPATIBLE_BASE_URL) return "openai-compatible";
   if (env.AI_GATEWAY_API_KEY) return "vercel";
+  if (env.CLOUDFLARE_API_TOKEN && env.CLOUDFLARE_ACCOUNT_ID) return "cloudflare";
   if (env.ANTHROPIC_API_KEY) return "anthropic";
   if (env.OPENAI_API_KEY) return "openai";
   if (env.GEMINI_API_KEY || env.GOOGLE_API_KEY) return "gemini";
   return "anthropic";
 }
 
-const NO_API_KEY = `No AI provider key found. Set one of ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY or AI_GATEWAY_API_KEY for Vercel AI Gateway (or OPENAI_COMPATIBLE_BASE_URL for an OpenAI-compatible API), or pick one with --provider. To run without any AI model, replay saved steps with --no-ai.`;
+const NO_API_KEY = `No AI provider key found. Set one of ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, AI_GATEWAY_API_KEY for Vercel AI Gateway, or CLOUDFLARE_API_TOKEN with CLOUDFLARE_ACCOUNT_ID for Cloudflare Workers AI (or OPENAI_COMPATIBLE_BASE_URL for an OpenAI-compatible API), or pick one with --provider. To run without any AI model, replay saved steps with --no-ai.`;
 
 function hasApiKey(env) {
-  return Boolean(env.OPENAI_COMPATIBLE_BASE_URL || env.AI_GATEWAY_API_KEY || env.ANTHROPIC_API_KEY || env.ANTHROPIC_AUTH_TOKEN || env.OPENAI_API_KEY || env.GEMINI_API_KEY || env.GOOGLE_API_KEY);
+  return Boolean(env.OPENAI_COMPATIBLE_BASE_URL || env.AI_GATEWAY_API_KEY || (env.CLOUDFLARE_API_TOKEN && env.CLOUDFLARE_ACCOUNT_ID) || env.ANTHROPIC_API_KEY || env.ANTHROPIC_AUTH_TOKEN || env.OPENAI_API_KEY || env.GEMINI_API_KEY || env.GOOGLE_API_KEY);
 }
 
 /**
@@ -57,9 +61,9 @@ async function buildProvider(name, opts, env) {
   if (!opts.client && !opts.name && !opts.baseUrl && !hasApiKey(env)) throw Object.assign(new Error(NO_API_KEY), { code: "NO_API_KEY" });
   if (name === "openai-compatible") {
     const baseURL = opts.baseUrl ?? env.OPENAI_COMPATIBLE_BASE_URL;
-    const model = opts.model ?? env.OPENAI_COMPATIBLE_MODEL;
+    const model = compatibleModel(opts.model, env);
     if (!baseURL) throw new Error("openai-compatible needs the API address: --base-url or OPENAI_COMPATIBLE_BASE_URL, e.g. https://api.deepseek.com");
-    if (!model) throw new Error("openai-compatible needs a model id: --model or OPENAI_COMPATIBLE_MODEL.");
+    if (!model) throw new Error("openai-compatible needs a model id: --model or OPENAI_COMPATIBLE_MODEL (\"cheap\" has no meaning here, since the API's models are unknown).");
     // Local servers such as Ollama need no key, but the SDK wants a non-empty one.
     const apiKey = env.OPENAI_COMPATIBLE_API_KEY || "not-needed";
     const client = opts.client ?? new (await import("openai")).default({ baseURL, apiKey });
@@ -67,9 +71,15 @@ async function buildProvider(name, opts, env) {
   }
   if (name === "vercel") {
     const client = opts.client ?? new (await import("openai")).default({ baseURL: VERCEL_GATEWAY, apiKey: env.AI_GATEWAY_API_KEY });
-    return { ...openaiProvider(client, opts.model ?? PROVIDERS.vercel.defaultModel, { compatible: true }), name: "vercel" };
+    return { ...openaiProvider(client, pickModel("vercel", opts.model), { compatible: true }), name: "vercel" };
   }
-  const model = opts.model ?? PROVIDERS[name].defaultModel;
+  if (name === "cloudflare") {
+    const account = env.CLOUDFLARE_ACCOUNT_ID;
+    if (!opts.client && !(account && env.CLOUDFLARE_API_TOKEN)) throw new Error("Cloudflare Workers AI needs CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID.");
+    const client = opts.client ?? new (await import("openai")).default({ baseURL: `${CLOUDFLARE_API}/${account}/ai/v1`, apiKey: env.CLOUDFLARE_API_TOKEN });
+    return { ...openaiProvider(client, pickModel("cloudflare", opts.model), { compatible: true }), name: "cloudflare" };
+  }
+  const model = pickModel(name, opts.model);
   const gateway = gatewayOptions(name, env);
   const provider = await builtInProvider(name, model, gateway, opts.client, env);
   // Shown in the "Using ..." line so a run says whether its calls went through the gateway.
@@ -87,9 +97,22 @@ async function builtInProvider(name, model, gateway, client, env) {
 }
 
 const VERCEL_GATEWAY = "https://ai-gateway.vercel.sh/v1";
+const CLOUDFLARE_API = "https://api.cloudflare.com/client/v4/accounts";
+
+/** An openai-compatible API has no known cheap model, so `cheap` falls back to OPENAI_COMPATIBLE_MODEL. */
+function compatibleModel(model, env) {
+  return (model === "cheap" ? undefined : model) ?? env.OPENAI_COMPATIBLE_MODEL;
+}
+
+/** The model to use: an explicit id, `cheap` for the provider's small CI model, else the default. */
+export function pickModel(name, model) {
+  if (model === "cheap") return PROVIDERS[name]?.cheapModel ?? PROVIDERS[name]?.defaultModel ?? model;
+  return model ?? PROVIDERS[name].defaultModel;
+}
 
 const KEY_PROVIDERS = [
   ["vercel", (env) => env.AI_GATEWAY_API_KEY],
+  ["cloudflare", (env) => env.CLOUDFLARE_API_TOKEN && env.CLOUDFLARE_ACCOUNT_ID],
   ["anthropic", (env) => env.ANTHROPIC_API_KEY || env.ANTHROPIC_AUTH_TOKEN],
   ["openai", (env) => env.OPENAI_API_KEY],
   ["gemini", (env) => env.GEMINI_API_KEY || env.GOOGLE_API_KEY],
@@ -101,9 +124,9 @@ const KEY_PROVIDERS = [
  * "AI: anthropic (claude-opus-5-5) via Cloudflare AI Gateway · also set: gemini (pick with --provider)".
  */
 export function aiStatus(opts = {}, env = process.env) {
-  if (!opts.name && !KEY_PROVIDERS.some(([, has]) => has(env))) return "AI: no key set (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY or AI_GATEWAY_API_KEY)";
+  if (!opts.name && !KEY_PROVIDERS.some(([, has]) => has(env))) return "AI: no key set (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, AI_GATEWAY_API_KEY or CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID)";
   const name = resolveProviderName(opts.name, env);
-  const model = opts.model ?? (name === "openai-compatible" ? env.OPENAI_COMPATIBLE_MODEL : PROVIDERS[name].defaultModel) ?? "no model set";
+  const model = (name === "openai-compatible" ? compatibleModel(opts.model, env) : pickModel(name, opts.model)) ?? "no model set";
   const via = name !== "vercel" && gatewayOptions(name, env).baseURL ? " via Cloudflare AI Gateway" : "";
   return `AI: ${name} (${model})${via}${alsoSet(name, env)}`;
 }

package/src/redact.js

@@ -22,7 +22,7 @@ const SHARED_SECOND_LEVELS = new Set(["com", "co", "org", "net", "gov", "edu", "
 const SHARED_SUFFIXES = ["myshopify.com", "github.io", "vercel.app", "pages.dev", "netlify.app", "herokuapp.com", "web.app", "firebaseapp.com", "appspot.com", "wixsite.com", "blogspot.com", "azurewebsites.net", "cloudfront.net", "workers.dev"];
 
 /** "www.shop.example.com.tr" -> "example.com.tr", "a.shop.myshopify.com" -> "shop.myshopify.com": the part one owner controls. */
-function siteOf(host) {
+export function siteOf(host) {
   const labels = String(host).toLowerCase().replace(/\.$/, "").split(".");
   const name = labels.join(".");
   const shared = SHARED_SUFFIXES.find((s) => name === s || name.endsWith(`.${s}`));

package/src/report.js

@@ -1,9 +1,11 @@
+import { consentTable } from "./consent.js";
 import { OWNERS, ownerOf, verifyLinks } from "./verify.js";
 import { createProvider } from "./providers.js";
 import { groupFindings, hitMatchesEvent, summarize } from "./checks.js";
 import { messages } from "./i18n.js";
 import { parseTrackingRequest, providerOf, PROVIDERS } from "./parsers.js";
 import { decodeGa4Item, isEventParam, paramTip } from "./glossary.js";
+import { buildInventory } from "./inventory.js";
 import { LOGOS } from "./brand.js";
 import { readFileSync } from "node:fs";
 
@@ -152,19 +154,27 @@ const mdCode = (v) => String(v ?? "").replace(/`/g, "'").replace(/\n/g, " ");
 
 const routeList = (ch) => (ch?.routes ?? []).map((r) => `${r.journeyId} (${r.viewport})`).join(", ");
 
-export function renderMarkdown({ title, generatedAt, findings, explained, runs, lang = "en", branding = true, against = null, planCheck = null, changes = null }) {
+export function renderMarkdown({ title, generatedAt, findings, explained, runs, lang = "en", branding = true, against = null, planCheck = null, changes = null, planChanges = null, consentScenarios = null }) {
   const m = messages(lang);
   const rows = attachExplanations(findings, explained);
   const counts = summarize(rows);
-  const lines = [`# ${mdText(title)}`, "", m.ui.generated(generatedAt), "", ...(against ? [mdText(m.ui.checkedAgainst(against)), ""] : []), ...(changes?.routes?.length ? [mdText(m.ui.routeChanged(routeList(changes))), ""] : []), `**${m.ui.counts(counts)}**`, ""];
+  const lines = [`# ${mdText(title)}`, "", m.ui.generated(generatedAt), "", ...(against ? [mdText(m.ui.checkedAgainst(against)), ""] : []), ...(planChanges ? [mdText(m.ui.planChangesLine(planChanges)), "", ...planChangeItems(planChanges).map((i) => `- ${mdText(i)}`), ...(planChangeItems(planChanges).length ? [""] : [])] : []), ...(changes?.routes?.length ? [mdText(m.ui.routeChanged(routeList(changes))), ""] : []), `**${m.ui.counts(counts)}**`, ""];
   if (changes) lines.push(...changesMd(m, changes));
   if (planCheck) lines.push(...planVsSiteMd(m, planCheck));
+  lines.push(...inventoryMd(m, runs));
   const sum = summaryParts(explained?.summary);
   if (sum) {
     lines.push(`## ${m.ui.summary}`, "", sum.text ? mdText(sum.text) : `**${mdText(sum.headline)}**`, "");
     if (sum.points.length) lines.push(...sum.points.map((p) => `- **${m.severity[p.severity]}**: ${mdText(p.text)}`), "");
     if (sum.also_check.length) lines.push(`### ${m.ui.alsoCheck}`, "", ...sum.also_check.map((t) => `- ${mdText(t)}`), "");
   }
+  if (consentScenarios) {
+    const { cols, rows: tagRows } = consentTable(consentScenarios);
+    lines.push(`## ${m.ui.scenarios}`, "", mdText(m.ui.scenariosLead(consentScenarios.cmp)), "");
+    lines.push(`| ${m.ui.scenarioTag} | ${cols.map((c) => m.ui.scenarioCols[c]).join(" | ")} |`, `|${" --- |".repeat(cols.length + 1)}`);
+    for (const r of tagRows) lines.push(`| ${mdText(platformLabel(r.platform))} \`${mdCode(r.event)}\` | ${r.cells.map((c) => (c.count === null ? "–" : c.problem ? `**${c.count}** ⚠` : String(c.count))).join(" | ")} |`);
+    lines.push("");
+  }
   lines.push(`## ${m.ui.findings}`, "");
   for (const f of rows.filter((r) => r.severity !== "ok")) {
     lines.push(`### ${m.severity[f.severity]}: ${mdText(f.detail)}`, "");
@@ -558,10 +568,20 @@ function journeyPanel(m, lang, findings, run, ri, flagged) {
 ${consentCard(m, run)}${body}</article>`;
 }
 
-function journeysTab(m, lang, findings, runs, flagged) {
-  if (!runs.length) return `<p class="empty">${m.ui.noSteps}</p>`;
+/** Consent scenarios: one row per tag, one column per consent choice, hit counts after the choice. */
+function scenariosCard(m, scenarios) {
+  if (!scenarios) return "";
+  const { cols, rows } = consentTable(scenarios);
+  const head = `<tr><th>${m.ui.scenarioTag}</th>${cols.map((c) => `<th>${m.ui.scenarioCols[c]}</th>`).join("")}</tr>`;
+  const body = rows.map((r) => `<tr><td><span class="ptag p-${safeKey(r.platform)}">${escapeHtml(platformLabel(r.platform))}</span> <code>${escapeHtml(r.event)}</code></td>${r.cells.map((c) => (c.count === null ? `<td class="muted xs">–</td>` : `<td class="num${c.problem ? " bad" : ""}">${c.count}</td>`)).join("")}</tr>`).join("");
+  const notRun = cols.filter((c) => c !== "before" && !scenarios.states[c]?.via).map((c) => m.ui.scenarioCols[c]);
+  return `<div class="card jconsent scenarios"><div class="card-h"><div class="card-t">${m.ui.scenarios}</div><div class="card-d">${escapeHtml(m.ui.scenariosLead(scenarios.cmp))}${notRun.length ? ` ${escapeHtml(m.ui.scenarioNotRun)}: ${escapeHtml(notRun.join(", "))}.` : ""}</div></div><div class="card-c tight"><table class="dt"><thead>${head}</thead><tbody>${body}</tbody></table></div></div>`;
+}
+
+function journeysTab(m, lang, findings, runs, flagged, scenarios = null) {
+  if (!runs.length) return `${scenariosCard(m, scenarios)}<p class="empty">${m.ui.noSteps}</p>`;
   const tabs = runs.map((r, ri) => `<a href="#j${ri}">${escapeHtml(r.journeyId)} <span class="muted">· ${escapeHtml(r.viewport)}</span><span class="n">${problemCount(findings, r)}</span></a>`).join("");
-  return `<nav class="jtabs" aria-label="${m.ui.chooseJourney}">${tabs}</nav>\n${runs.map((r, ri) => journeyPanel(m, lang, findings, r, ri, flagged)).join("\n")}`;
+  return `${scenariosCard(m, scenarios)}<nav class="jtabs" aria-label="${m.ui.chooseJourney}">${tabs}</nav>\n${runs.map((r, ri) => journeyPanel(m, lang, findings, r, ri, flagged)).join("\n")}`;
 }
 
 /** Evidence as a table when it is a JSON object (captured parameters), otherwise as text. */
@@ -704,6 +724,12 @@ const coverageLines = (m, pc) => [
 const pcSort = (pc) => [...pc.events].sort((a, b) => BUCKET_ORDER.indexOf(a.bucket) - BUCKET_ORDER.indexOf(b.bucket) || platformRank(a.platform) - platformRank(b.platform));
 const BUCKET_ORDER = ["missing", "missing_params", "wrong_values", "implemented", "unplanned", "not_checked"];
 
+const planChangeItems = (pc) => [
+  ...pc.added.map((c) => `+ ${changeLabel(c)}`),
+  ...pc.removed.map((c) => `− ${changeLabel(c)}`),
+  ...pc.changed.map((c) => `~ ${changeLabel(c)}: ${c.what.join(", ")}`),
+];
+
 /** "Changed since last run": one headline, then what was fixed and what is new. */
 const changeLabel = (c) => `${platformLabel(c.platform ?? "")} ${c.event ?? ""}`.trim() || c.check;
 const changeItems = (m, ch) => [
@@ -761,6 +787,30 @@ function coverageCard(m, plan, runs) {
   return `<div class="card">${head}<div class="card-c"><div class="tscroll"><table class="dt cov"><thead><tr><th>${m.ui.event}</th>${runs.map((r) => `<th>${escapeHtml(r.journeyId)} · ${escapeHtml(r.viewport)}</th>`).join("")}</tr></thead><tbody>${body}</tbody></table></div><p class="muted xs legend">${m.ui.coverageLegend}</p></div></div>`;
 }
 
+const PAGES_SHOWN = 5;
+
+function inventoryMd(m, runs) {
+  const inv = buildInventory(runs);
+  const lines = [`## ${m.ui.inventoryTitle}`, ""];
+  if (!inv.vendors.length) return [...lines, m.ui.noInventory, ""];
+  lines.push(`| ${m.ui.vendorCol} | ${m.ui.partyCol} | ${m.ui.pagesCol} | ${m.ui.cookiesCol} |`, "|---|---|---|---|");
+  for (const v of inv.vendors) lines.push(`| ${mdText(v.vendor)} | ${m.ui.party[v.party]} | ${v.pages.length} | ${mdText(v.cookies.join(", "))} |`);
+  if (inv.otherCookies.length) lines.push("", `${m.ui.otherCookies}: ${mdText(inv.otherCookies.map((c) => c.name).join(", "))}`);
+  lines.push("");
+  return lines;
+}
+
+function inventoryCard(m, runs) {
+  const inv = buildInventory(runs);
+  const head = `<div class="card-h"><div class="card-t">${m.ui.inventoryTitle}</div><div class="card-d">${m.ui.inventoryLead}</div></div>`;
+  if (!inv.vendors.length) return `<div class="card" id="inventory">${head}<div class="card-c"><p class="muted">${m.ui.noInventory}</p></div></div>`;
+  const names = (xs) => xs.map((x) => `<code>${escapeHtml(x)}</code>`).join(" ");
+  const pages = (v) => `${names(v.pages.slice(0, PAGES_SHOWN))}${v.pages.length > PAGES_SHOWN ? ` <span class="muted">${m.ui.morePages(v.pages.length - PAGES_SHOWN)}</span>` : ""}`;
+  const rows = inv.vendors.map((v) => `<tr><td>${escapeHtml(v.vendor)}</td><td>${escapeHtml(m.ui.party[v.party])}</td><td class="xs">${pages(v)}</td><td class="xs">${v.cookies.length ? names(v.cookies) : '<span class="muted">–</span>'}</td></tr>`).join("");
+  const other = inv.otherCookies.length ? `<p class="muted xs legend">${m.ui.otherCookies}: ${inv.otherCookies.map((c) => `${escapeHtml(c.name)} (${escapeHtml(m.ui.party[c.party])})`).join(", ")}</p>` : "";
+  return `<div class="card" id="inventory">${head}<div class="card-c tight"><div class="tscroll"><table class="dt"><thead><tr><th>${m.ui.vendorCol}</th><th>${m.ui.partyCol}</th><th>${m.ui.pagesCol}</th><th>${m.ui.cookiesCol}</th></tr></thead><tbody>${rows}</tbody></table></div></div>${other ? `<div class="card-c">${other}</div>` : ""}</div>`;
+}
+
 function providersCard(m, runs) {
   const provs = checkedProviders(runs);
   const skipped = skippedTotals(runs);
@@ -858,6 +908,7 @@ code{font-size:12px;background:var(--muted-bg);padding:1px 5px;border-radius:4px
 .jconsent{margin-bottom:16px}
 .eyebrow{font:500 12px var(--font-mono);color:var(--accent-fg);text-transform:uppercase;letter-spacing:.06em;margin-bottom:6px}
 .title .meta{margin-top:4px;font-size:12px;color:var(--muted)}
+.title .plan-changes ul{margin:4px 0 0;padding-left:18px}
 .toptabs{position:sticky;top:0;z-index:10;background:var(--page);border-bottom:1px solid var(--border);margin-top:16px}
 .toptabs .wrap{display:flex;gap:4px;overflow-x:auto;scrollbar-width:none}
 .toptabs a{display:inline-flex;align-items:center;gap:6px;padding:12px 10px;color:var(--muted);font-weight:500;white-space:nowrap;border-bottom:2px solid transparent;margin-bottom:-1px}
@@ -1075,7 +1126,7 @@ pre{margin:8px 0 0;font-size:12px;line-height:1.5;background:var(--muted-bg);bor
 @media print{.toptabs,.jtabs,.stepnav,.filter>label,.filter>input,.tabs.seg>label,.sevfilter{display:none}.tabpanel,.jpanel,.sdetail,.tabs.seg>.panel{display:block!important}.jpanel{margin-bottom:32px}.sdetail{margin-bottom:16px;break-inside:avoid-page}details>*{display:block}}
 `;
 
-export function renderHtml({ title, site = null, ai = null, generatedAt, findings, explained, runs, plan = null, lang = "en", branding = true, against = null, planCheck = null, changes = null }) {
+export function renderHtml({ title, site = null, ai = null, generatedAt, findings, explained, runs, plan = null, lang = "en", branding = true, against = null, planCheck = null, changes = null, planChanges = null, consentScenarios = null }) {
   const m = messages(lang);
   const rows = attachExplanations(findings, explained);
   const counts = summarize(rows);
@@ -1096,15 +1147,15 @@ ${navCss(runs)}</style></head><body>
 <div class="topbar"><div class="wrap"><span class="product-logo">${logo("atd-lockup", "AI Tag Debugger", 26, "logo-atd")}</span>${branding ? `<a href="https://analitikisler.com" class="byline" rel="noopener noreferrer"><span>${m.ui.by}</span>${logo("horizontal", "Analitik İşler", 18, "logo-h")}</a>` : ""}</div></div>
 <header class="wrap title">
 <h1 class="site"><span class="k">${m.ui.site}</span><span class="v">${escapeHtml(site ?? title)}</span></h1>
-<div class="meta">${escapeHtml(generatedAt)} · ${escapeHtml(m.ui.headerMeta(runs.length, checkedProviders(runs).length))} · ai-tag-debugger ${VERSION}</div>${against ? `\n<div class="meta">${escapeHtml(m.ui.checkedAgainst(against))}</div>` : ""}${changes?.routes?.length ? `\n<div class="meta"><a href="#changes">${escapeHtml(m.ui.routeChanged(routeList(changes)))}</a></div>` : ""}
+<div class="meta">${escapeHtml(generatedAt)} · ${escapeHtml(m.ui.headerMeta(runs.length, checkedProviders(runs).length))} · ai-tag-debugger ${VERSION}</div>${against ? `\n<div class="meta">${escapeHtml(m.ui.checkedAgainst(against))}</div>` : ""}${planChanges ? `\n<div class="meta plan-changes">${escapeHtml(m.ui.planChangesLine(planChanges))}${planChangeItems(planChanges).length ? `<ul>${planChangeItems(planChanges).map((i) => `<li>${escapeHtml(i)}</li>`).join("")}</ul>` : ""}</div>` : ""}${changes?.routes?.length ? `\n<div class="meta"><a href="#changes">${escapeHtml(m.ui.routeChanged(routeList(changes)))}</a></div>` : ""}
 </header>
 <nav class="toptabs" aria-label="${m.ui.sections}"><div class="wrap">
 <a href="#overview">${m.ui.tabOverview}</a><a href="#findings">${m.ui.findings} <span class="n">${problems}</span></a><a href="#journeys">${m.ui.tabJourneys} <span class="n">${runs.length}</span></a><a href="#scope">${m.ui.tabScope}</a></div></nav>
 <main class="wrap">
 <section class="tabpanel" id="overview" aria-label="${m.ui.tabOverview}">${changes ? changesCard(m, changes) : ""}${planCheck ? planVsSiteCard(m, planCheck) : ""}${overviewTab(m, findings, rows, counts, explained, runs, { ai, plan, lang })}</section>
 <section class="tabpanel" id="findings" aria-label="${m.ui.findings}">${findingsTab(m, runs, rows, Boolean(explained))}</section>
-<section class="tabpanel" id="journeys" aria-label="${m.ui.tabJourneys}">${journeysTab(m, lang, findings, runs, flagged)}</section>
-<section class="tabpanel" id="scope" aria-label="${m.ui.tabScope}"><div class="stack">${coverageCard(m, plan, runs)}${providersCard(m, runs)}</div></section>
+<section class="tabpanel" id="journeys" aria-label="${m.ui.tabJourneys}">${journeysTab(m, lang, findings, runs, flagged, consentScenarios)}</section>
+<section class="tabpanel" id="scope" aria-label="${m.ui.tabScope}"><div class="stack">${coverageCard(m, plan, runs)}${inventoryCard(m, runs)}${providersCard(m, runs)}</div></section>
 </main>
 <footer class="footer">${footer}</footer>
 </body></html>`;

package/src/sheet.js

@@ -84,7 +84,8 @@ export function rowsToPlan({ events: eventRows = [], user_properties: upRows = n
     if (!r.event) throw fail(`${at}: "event" is empty. Give the event name, e.g. purchase.`);
     const platform = (r.platform || "ga4").toLowerCase();
     if (!PLATFORMS[platform]) throw fail(`${at}: "platform" must be one of ${Object.keys(PLATFORMS).join(", ")} (found "${r.platform}").`);
-    const required = (r.required ?? "").toLowerCase();
+    // Google Sheets checkboxes export as TRUE/FALSE.
+    const required = { true: "yes", false: "no" }[(r.required ?? "").toLowerCase()] ?? (r.required ?? "").toLowerCase();
     if (!["yes", "no", ""].includes(required)) throw fail(`${at}: "required" must be yes or no (found "${r.required}").`);
     if (required && !r.parameter) throw fail(`${at}: "required" is set but "parameter" is empty. Name the parameter, or leave "required" empty on the event's own row.`);
     const custom = (r.custom ?? "").toLowerCase().split(",").map((s) => s.trim()).filter(Boolean);
@@ -290,15 +291,17 @@ export async function readPlanSheet(file, { site } = {}) {
     if (!events) throw new Error(`${path.basename(file)} has no tab named "events" (found ${Object.keys(sheets).map((k) => `"${k}"`).join(", ") || "none"}). Rename the tab with the events to "events".`);
     tabs = { events, user_properties: find("user_properties") ?? null };
   } else if (ext === ".csv") {
-    const upFile = path.join(path.dirname(file), "user_properties.csv");
-    const isUp = path.basename(file).toLowerCase() === "user_properties.csv";
-    if (isUp) throw new Error(`Import the events file (events.csv); ${path.basename(file)} beside it is read too.`);
+    // Google Sheets downloads each tab as "<Document> - <tab>.csv"; the sibling file keeps that prefix.
+    const base = path.basename(file);
+    const prefix = base.match(/^(.*?)events\.csv$/i)?.[1] ?? "";
+    const upFile = path.join(path.dirname(file), `${prefix}user_properties.csv`);
+    if (/user_properties\.csv$/i.test(base)) throw new Error(`Import the events file (${base.replace(/user_properties\.csv$/i, "events.csv")}); ${base} beside it is read too.`);
     tabs = { events: parseCsv(await readFile(file, "utf8")), user_properties: (await exists(upFile)) ? parseCsv(await readFile(upFile, "utf8")) : null };
   } else {
     throw new Error(`Import a .xlsx or .csv file (got ${path.basename(file)}).`);
   }
   const result = rowsToPlan(tabs, { site });
-  if (!tabs.user_properties) result.warnings.push(ext === ".csv" ? "No user_properties.csv beside the file, so the plan has no user properties." : 'No "user_properties" tab, so the plan has no user properties.');
+  if (!tabs.user_properties) result.warnings.push(ext === ".csv" ? `No ${path.basename(upFile)} beside the file, so the plan has no user properties.` : 'No "user_properties" tab, so the plan has no user properties.');
   return result;
 }