@analitikisler/ai-tag-debugger 0.17.0 → 0.18.0

package/src/metrics.js

@@ -210,7 +210,10 @@ export function platformParity({ runs = [] } = {}) {
       const platforms = Object.fromEntries([...byPlatform].map(([platform, hits]) => {
         const valued = hits.find((h) => paramOf(h, "value") !== undefined) ?? hits.find((h) => paramOf(h, "currency") !== undefined) ?? hits[0];
         const value = paramOf(valued, "value");
-        return [platform, { names: uniq(hits.map((h) => h.name)), count: hits.length, value: value === undefined ? null : Number(value), currency: paramOf(valued, "currency") ?? null }];
+        // A value that is not a number (a template left unresolved, a product name) stays as the text the
+        // tag sent, so the report shows what the platform received instead of NaN. Only numbers are compared.
+        const n = Number(value);
+        return [platform, { names: uniq(hits.map((h) => h.name)), count: hits.length, value: value === undefined ? null : Number.isFinite(n) ? n : String(value), currency: paramOf(valued, "currency") ?? null }];
       }));
       if (byPlatform.size < 2) {
         const [[platform, p]] = Object.entries(platforms);
@@ -220,8 +223,11 @@ export function platformParity({ runs = [] } = {}) {
       const list = Object.values(platforms);
       const mismatch = [];
       if (uniq(list.map((p) => p.count)).length > 1) mismatch.push("count");
-      const values = list.map((p) => p.value).filter((v) => v !== null && Number.isFinite(v));
-      if (values.length > 1 && Math.max(...values) - Math.min(...values) > 0.005) mismatch.push("value");
+      // Numbers compare within rounding; once a side sent text, the platforms agree only on the same text.
+      const sent = list.map((p) => p.value).filter((v) => v !== null);
+      const numbers = sent.filter((v) => Number.isFinite(v));
+      const differs = numbers.length === sent.length ? Math.max(...numbers) - Math.min(...numbers) > 0.005 : uniq(sent.map(String)).length > 1;
+      if (sent.length > 1 && differs) mismatch.push("value");
       const currencies = uniq(list.map((p) => p.currency).filter(Boolean).map((c) => c.toUpperCase()));
       if (currencies.length > 1) mismatch.push("currency");
       // A value one platform has and the other lacks is a mismatch too: the platforms will not agree on revenue.

package/src/plan-html.js

@@ -1,24 +1,67 @@
-import { CSS, VERSION, escapeHtml, logo, platformLabel } from "./report.js";
+import { VERSION } from "./report-shared.js";
+import { TOKENS, COMPONENTS, PRODUCT } from "./html/css.js";
+import { chip, escapeHtml, logo, plat, platformLabel, sprite } from "./html/lib.js";
 import { LOGOS } from "./brand.js";
 
 const e = escapeHtml;
 const text = (v) => (v === undefined || v === null || v === "" ? `<span class="muted">–</span>` : e(v));
 
+// Only what the plan page needs on top of the report's tokens and components: the top bar (a trimmed copy of the
+// report shell's, which this page does not load, with no rail or verdict), the page column, and the event list. Colours come from tokens, so dark mode
+// follows both selectors in TOKENS and nothing here names a colour.
 const PLAN_CSS = `
-.pl-event{padding:16px 20px}
+.top{display:flex;align-items:center;gap:var(--s3);height:var(--top);padding:0 var(--s4);background:var(--card);border-bottom:1px solid var(--border);white-space:nowrap}
+.top .brand{display:inline-flex;align-items:center;flex:none}
+.top .l-mark{display:none}
+.top-site{display:flex;align-items:baseline;gap:var(--s2);min-width:0;overflow:hidden}
+.top-site b{font-weight:600;overflow:hidden;text-overflow:ellipsis}
+.top-end{margin-left:auto;display:flex;align-items:center;gap:var(--s2)}
+.byline{display:inline-flex;align-items:center;gap:var(--s2);font-size:12px;color:var(--muted)}
+.logo{display:inline-flex}
+.logo .l-dark{display:none}
+html[data-theme="dark"] .logo .l-light{display:none}
+html[data-theme="dark"] .logo .l-dark{display:inline}
+@media (prefers-color-scheme:dark){html:not([data-theme="light"]) .logo .l-light{display:none}html:not([data-theme="light"]) .logo .l-dark{display:inline}}
+.eyebrow{font:600 11px/1.4 var(--font-sans);text-transform:uppercase;letter-spacing:.06em;color:var(--muted)}
+.plan{max-width:1100px;margin:0 auto;padding:var(--s5) var(--s6) var(--s7)}
+.plan-title{display:grid;gap:var(--s2);margin-bottom:var(--s5)}
+.plan-title .chips{margin-top:var(--s1)}
+.plan .card+.card{margin-top:var(--s4)}
+.pl-card-h{padding:var(--s3) var(--s4);border-bottom:1px solid var(--border)}
+.pl-card-d{margin-top:2px;font-size:12.5px;color:var(--muted)}
+.pl-empty{padding:var(--s3) var(--s4)}
+.pl-event{padding:var(--s4)}
 .pl-event+.pl-event{border-top:1px solid var(--border)}
-.pl-head{display:flex;flex-wrap:wrap;align-items:center;gap:8px}
+.pl-head{display:flex;flex-wrap:wrap;align-items:center;gap:var(--s2)}
 .pl-head code{font-size:14px}
 .pl-desc{margin:6px 0 10px}
 .pl-trigger{font-size:12px;color:var(--muted);margin-bottom:10px}
 .pl-trigger b{font-weight:500;color:var(--fg)}
-.flag{display:inline-flex;align-items:center;font:500 12px/1 var(--font-sans);padding:4px 8px;border-radius:4px;background:var(--muted-bg);color:var(--muted)}
-.flag.on{background:var(--accent-bg);color:var(--accent-fg)}
-.flag.req{background:var(--warn-bg);color:var(--warn)}
-table.dt td,table.dt th{vertical-align:top}
+.chip .plat{display:inline-flex;align-items:center;gap:5px}
+.chip.on{--k:var(--accent);--k-fg:var(--accent-fg);background:var(--accent-bg)}
+.chip.req{--k:var(--sev-warning);--k-fg:var(--sev-warning-fg);background:var(--sev-warning-bg)}
+.pl-card-body{padding:var(--s4)}
+.tbl td,.tbl th{vertical-align:top}
+/* a narrow table scrolls inside its .tscroll instead of breaking names mid-word */
+.plan .tbl{min-width:480px}
+.plan .tbl td:first-child code{white-space:nowrap}
+.footer{display:flex;align-items:center;gap:var(--s4);padding:var(--s4);border-top:1px solid var(--border);background:var(--card)}
+.footer a{color:var(--fg)}
+.logo-link{display:inline-flex}
+.f-links{display:flex;flex-wrap:wrap;gap:var(--s2) var(--s4)}
+.footer .f-meta{margin-left:auto}
+@media (max-width:719.98px){
+  :root{--top:44px}
+  .top{gap:var(--s2);padding:0 var(--s3)}
+  .top .l-lockup,.top-site .eyebrow,.byline{display:none}
+  .top .l-mark{display:block}
+  .plan{padding:var(--s4) var(--s4) var(--s6)}
+  .footer{flex-wrap:wrap}
+}
+@media print{.top{display:none}.plan{padding:0}}
 `;
 
-const flag = (label, cls = "") => `<span class="flag ${cls}">${e(label)}</span>`;
+const flag = (label, cls = "") => `<span class="chip ${cls}">${e(label)}</span>`;
 
 function paramsTable(event) {
   const params = Object.entries(event.parameters ?? {});
@@ -27,13 +70,14 @@ function paramsTable(event) {
   const rows = params
     .map(([name, p]) => `<tr><td><code>${e(name)}</code>${p?.custom ? ` ${flag("custom")}` : ""}</td><td>${required.has(name) ? flag("required", "req") : `<span class="muted">optional</span>`}</td><td class="mono">${text(p?.example)}</td><td>${text(p?.description)}</td></tr>`)
     .join("");
-  return `<div class="tscroll"><table class="dt"><thead><tr><th>Parameter</th><th>Required</th><th>Example</th><th>Description</th></tr></thead><tbody>${rows}</tbody></table></div>`;
+  return `<div class="tscroll"><table class="tbl"><thead><tr><th>Parameter</th><th>Required</th><th>Example</th><th>Description</th></tr></thead><tbody>${rows}</tbody></table></div>`;
 }
 
 function eventCard(event) {
   const trigger = event.trigger ?? {};
+  const platform = event.platform ?? "ga4";
   return `<div class="pl-event">
-<div class="pl-head"><span class="ptag">${e(platformLabel(event.platform ?? "ga4"))}</span><code>${e(event.name)}</code>${flag(event.custom ? "custom event" : "standard event", event.custom ? "on" : "")}</div>
+<div class="pl-head">${chip("plat", platform, plat(platform, 13, platformLabel(platform)))}<code>${e(event.name)}</code>${flag(event.custom ? "custom event" : "standard event", event.custom ? "on" : "")}</div>
 <p class="pl-desc">${text(event.description)}</p>
 <p class="pl-trigger"><b>Trigger</b> · page: ${text(trigger.page)} · element: ${text(trigger.element)}</p>
 ${paramsTable(event)}
@@ -42,12 +86,12 @@ ${paramsTable(event)}
 
 function userPropertiesCard(props) {
   const body = props.length
-    ? `<div class="tscroll"><table class="dt"><thead><tr><th>Name</th><th>Example</th><th>Description</th></tr></thead><tbody>${props
+    ? `<div class="pl-card-body"><div class="tscroll"><table class="tbl"><thead><tr><th>Name</th><th>Example</th><th>Description</th></tr></thead><tbody>${props
         .map((p) => (typeof p === "string" ? { name: p } : p))
         .map((p) => `<tr><td><code>${e(p.name)}</code></td><td class="mono">${text(p.example)}</td><td>${text(p.description)}</td></tr>`)
-        .join("")}</tbody></table></div>`
-    : `<p class="muted xs">No user properties.</p>`;
-  return `<section class="card"><div class="card-h"><div class="card-t">User properties</div></div><div class="card-c">${body}</div></section>`;
+        .join("")}</tbody></table></div></div>`
+    : `<p class="pl-empty muted xs">No user properties.</p>`;
+  return `<section class="card"><div class="pl-card-h"><h2>User properties</h2></div>${body}</section>`;
 }
 
 /** A single self-contained, readable page for a measurement plan. Respects branding false like the report. */
@@ -58,19 +102,21 @@ export function renderPlanHtml(plan, { id = "", generatedAt = "", branding = tru
   const meta = [id && `Plan ${id}`, generatedAt, `${events.length} events (${custom} custom)`, `ai-tag-debugger ${VERSION}`].filter(Boolean).join(" · ");
   const consent = plan.consent_mode ? flag("Consent mode on", "on") : flag("Consent mode off");
   const footer = branding
-    ? `<div class="wrap"><a href="https://analitikisler.com" class="logo-link" aria-label="analitikisler.com" rel="noopener noreferrer">${logo("stacked", "Analitik İşler", 56, "logo-s")}</a><div><div class="f-links"><a href="https://analitikisler.com" rel="noopener noreferrer">analitikisler.com</a><a href="https://github.com/analitikisler/ai-tag-debugger" rel="noopener noreferrer">GitHub</a></div></div><div class="f-meta">v${VERSION}</div></div>`
-    : `<div class="wrap plain"><div class="f-meta">AI Tag Debugger</div><div class="f-meta">v${VERSION}</div></div>`;
+    ? `<a href="https://analitikisler.com" class="logo-link" aria-label="analitikisler.com" rel="noopener noreferrer">${logo("stacked", "Analitik İşler", 40, "logo-s")}</a><div class="f-links xs"><a href="https://analitikisler.com" rel="noopener noreferrer">analitikisler.com</a><a href="https://github.com/analitikisler/ai-tag-debugger" rel="noopener noreferrer">GitHub</a></div><p class="f-meta xs muted">v${VERSION}</p>`
+    : `<p class="xs">AI Tag Debugger</p><p class="f-meta xs muted">v${VERSION}</p>`;
+  const body = `<header class="top"><span class="brand">${logo("atd-lockup", "AI Tag Debugger", 22, "l-lockup")}<img class="l-mark" src="${LOGOS["atd-icon"]}" alt="AI Tag Debugger" height="24"></span><span class="top-site"><span class="eyebrow">Measurement plan</span>${plan.site ? `<b>${e(plan.site)}</b>` : ""}</span><div class="top-end">${branding ? `<a href="https://analitikisler.com" class="byline" rel="noopener noreferrer"><span>by</span>${logo("horizontal", "Analitik İşler", 16, "logo-h")}</a>` : ""}</div></header>
+<main class="plan">
+<div class="plan-title"><div class="eyebrow">Measurement plan</div><h1>${e(title)}</h1><div class="muted xs">${e(meta)}</div><div class="chips">${consent}</div></div>
+<section class="card"><div class="pl-card-h"><h2>Events</h2><p class="pl-card-d">What should be tracked, where it fires and which parameters it carries.</p></div>${events.length ? events.map(eventCard).join("") : `<p class="pl-empty muted xs">No events.</p>`}</section>
+${userPropertiesCard(plan.user_properties ?? [])}
+</main>
+<footer class="footer">${footer}</footer>`;
   return `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light dark">
 <title>${e(title)}</title><link rel="icon" type="image/png" href="${LOGOS.favicon}">
-<style>${CSS}${PLAN_CSS}</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>by</span>${logo("horizontal", "Analitik İşler", 18, "logo-h")}</a>` : ""}</div></div>
-<header class="wrap title"><div class="eyebrow">Measurement plan</div><h1>${e(title)}</h1><div class="meta">${e(meta)}</div></header>
-<main class="wrap" style="padding-top:24px;padding-bottom:64px"><div class="stack">
-<div>${consent}</div>
-<section class="card"><div class="card-h"><div class="card-t">Events</div><div class="card-d">What should be tracked, where it fires and which parameters it carries.</div></div><div class="card-c tight">${events.length ? events.map(eventCard).join("") : `<p class="muted xs" style="padding:12px">No events.</p>`}</div></section>
-${userPropertiesCard(plan.user_properties ?? [])}
-</div></main>
-<footer class="footer">${footer}</footer>
+<style>${TOKENS}\n${COMPONENTS}\n${PRODUCT}\n${PLAN_CSS}</style></head><body>
+${sprite(body)}
+${body}
 </body></html>`;
 }

package/src/report-shared.js

@@ -0,0 +1,123 @@
+// What the Markdown and the HTML renderers share: the version, escaping, the grouped findings, platform names and
+// order, the plan-check lines and the verdict sentence. src/report.js and src/html/*.js both import from here and
+// this module imports neither, so the two renderers never import each other.
+import { readFileSync } from "node:fs";
+import { groupFindings } from "./checks.js";
+import { messages } from "./i18n.js";
+import { PROVIDERS } from "./parsers.js";
+
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+const SEVERITIES = ["broken", "risk", "warning", "info"];
+
+/** The summary as { headline, points, also_check }. Older plain-text summaries become a headline-only paragraph. */
+function summaryParts(summary) {
+  if (!summary) return null;
+  if (typeof summary === "string") return { text: summary, points: [], also_check: [] };
+  return {
+    headline: String(summary.headline ?? ""),
+    points: (Array.isArray(summary.points) ? summary.points : []).filter((p) => p && p.text).map((p) => ({ severity: SEVERITIES.includes(p.severity) ? p.severity : "info", text: String(p.text) })),
+    also_check: (Array.isArray(summary.also_check) ? summary.also_check : []).map(String).filter(Boolean),
+  };
+}
+
+/** Fix steps of an explanation; older explanations had one "fix" string. */
+const fixSteps = (e) => (Array.isArray(e?.fix_steps) && e.fix_steps.length ? e.fix_steps.map(String) : e?.fix ? [String(e.fix)] : []);
+
+export const escapeHtml = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+
+function attachExplanations(findings, explained) {
+  const byIndex = new Map((explained?.explanations ?? []).map((e) => [e.finding, e]));
+  // A finding a baseline accepted carries `accepted: true`; the grouped card is accepted when every place it covers is.
+  const key = (f) => [f.severity, f.check, f.platform, f.event, f.detail].join("|");
+  const accepted = new Map();
+  for (const f of findings) if (f.severity !== "ok") accepted.set(key(f), (accepted.get(key(f)) ?? true) && f.accepted === true);
+  return groupFindings(findings).map((f, i) => ({ ...f, explanation: byIndex.get(i), ...(accepted.get(key(f)) ? { accepted: true } : {}) }));
+}
+
+const SEVERITY_RANK = { broken: 0, risk: 1, warning: 2 };
+
+const seconds = (run, t) => `+${((t - run.startedAt) / 1000).toFixed(1)}s`;
+const isConsentEntry = (value) => Array.isArray(value) && value[0] === "consent";
+
+const routeList = (ch) => (ch?.routes ?? []).map((r) => `${r.journeyId} (${r.viewport})`).join(", ");
+
+const isProblem = (f) => f.severity in SEVERITY_RANK;
+const placeKey = (w) => `${w.journey}|${w.viewport}`;
+const uniqPlaces = (where) => [...new Map(where.map((w) => [placeKey(w), w])).values()];
+/** The problem the verdict is about: the one that costs the score most, else the most severe and widespread. */
+function mdLead(rows, metrics) {
+  const top = metrics.score?.deductions?.[0];
+  const problems = rows.filter(isProblem);
+  return (top && problems.find((f) => f.check === top.check && f.severity === top.severity && (f.platform ?? null) === top.platform && (f.event ?? null) === top.event)) ?? problems[0] ?? null;
+}
+
+/** " on mobile" when the lead problem is on one viewport of several, " on checkout" for one journey of several, " on every journey" when it is everywhere. */
+function mdScope(m, runs, lead) {
+  if (!lead) return "";
+  const places = uniqPlaces(lead.where);
+  if (runs.length > 1 && places.length === runs.length) return m.ui.md.everywhere;
+  const viewports = new Set(places.map((w) => w.viewport));
+  const journeys = new Set(places.map((w) => w.journey));
+  if (viewports.size === 1 && new Set(runs.map((r) => r.viewport)).size > 1) return m.ui.md.onViewport(String([...viewports][0]));
+  if (journeys.size === 1 && new Set(runs.map((r) => r.journeyId)).size > 1) return m.ui.md.onJourney(String([...journeys][0]));
+  return "";
+}
+
+/**
+ * The verdict sentence for the title, with no model, keyed the same way as metrics.verdict.headline. It names
+ * the lead problem and where it is ("purchase tracking is broken on mobile"): the counts sit next to the
+ * headline on every surface, so the count-based sentences in `verdict.headline` are left to the HTML verdict block.
+ */
+function mdHeadline(m, runs, rows, metrics) {
+  const v = metrics.verdict;
+  const lead = mdLead(rows, metrics);
+  const what = lead ? (lead.event ? m.ui.md.tracking(String(lead.event)) : m.ui.md.setup(String(lead.check).replace(/_/g, " "))) : "";
+  const scope = mdScope(m, runs, lead);
+  const incomplete = runs.find((r) => !r.completed);
+  const ctx = { key: v.headline, what, scope, journey: incomplete ? String(incomplete.journeyId) : "", events: metrics.coverage?.checkable ?? 0, journeys: runs.length, counts: v.counts, lead };
+  const fallback = m.ui.md.headline[v.headline] ?? m.ui.md.headline.attention_nothing_tested;
+  if (v.headline === "fail_incomplete") return fallback(ctx.journey);
+  if (v.headline === "pass") return fallback(ctx.events, ctx.journeys);
+  if (v.headline === "attention_no_hits" || v.headline === "attention_nothing_tested") return fallback();
+  return fallback(what, scope);
+}
+
+/**
+ * The verdict as the CLI, the alert subject and the Markdown title say it: { status, statusText, headline,
+ * score }, in the report's language and with no Markdown in it. `metrics` is computeMetrics' result.
+ */
+export function verdictHeadline({ findings = [], runs = [], metrics, lang = "en" }) {
+  const m = messages(lang);
+  const rows = groupFindings(findings).sort((a, b) => SEVERITY_ORDER_MD[a.severity] - SEVERITY_ORDER_MD[b.severity] || b.where.length - a.where.length);
+  return { status: metrics.verdict.status, statusText: m.verdict.status[metrics.verdict.status], headline: mdHeadline(m, runs, rows, metrics), score: metrics.score?.score ?? null };
+}
+
+const SEVERITY_ORDER_MD = { broken: 0, risk: 1, warning: 2, info: 3, ok: 4 };
+
+const PLATFORM_ORDER = ["ga4", "google_ads", "meta", "tiktok", "x", "linkedin", "microsoft_ads", "pinterest", "snapchat", "criteo", "klaviyo", "adobe", "matomo", "piwik_pro", "clarity", "hotjar"];
+export const platformLabel = (p) => PROVIDERS[p] ?? String(p).replace(/[_-]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+const platformRank = (p) => (PLATFORM_ORDER.includes(p) ? PLATFORM_ORDER.indexOf(p) : PLATFORM_ORDER.length);
+
+// Platform keys go into class names, ids and attribute selectors.
+const safeKey = (k) => String(k ?? "").toLowerCase().replace(/[^a-z0-9_-]/g, "") || "other";
+const sortPlatforms = (keys) => [...keys].sort((a, b) => platformRank(a) - platformRank(b) || platformLabel(a).localeCompare(platformLabel(b)));
+const changeLabel = (c) => `${platformLabel(c.platform ?? "")} ${c.event ?? ""}`.trim() || c.check;
+const coverageLines = (m, pc) => [
+  m.ui.coverageLine(pc.coverage),
+  ...sortPlatforms(Object.keys(pc.coverage.platforms)).map((p) => `${platformLabel(p)}: ${m.ui.coverageLine(pc.coverage.platforms[p])}`),
+];
+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(", ")}`),
+];
+
+export {
+  SEVERITIES, summaryParts, fixSteps, attachExplanations, SEVERITY_RANK, SEVERITY_ORDER_MD, seconds, isConsentEntry, routeList,
+  isProblem, placeKey, uniqPlaces, mdHeadline, PLATFORM_ORDER, platformRank, safeKey, sortPlatforms, changeLabel,
+  coverageLines, pcSort, BUCKET_ORDER, planChangeItems,
+};