@analitikisler/ai-tag-debugger 0.21.0 → 0.22.1

package/src/mcp.js

@@ -33,6 +33,8 @@ import { decodeGcd, DEFAULT_PROVIDERS, googleConsent, isCollectionEndpoint, pars
 import { hitParams } from "./hit-params.js";
 import { CAMPAIGN_PARAMS, campaignParamsIn, withCampaignParams } from "./campaign.js";
 import { cmpFacts } from "./cmp.js";
+import { containerRows, loadSources } from "./containers.js";
+import { isWidgetHit, siteIds } from "./frames.js";
 import { consentMatrixMarkdown, consentTable, runConsentScenarios } from "./consent.js";
 import { expectEvents, filterFindings, JOURNEY_PRESETS, onlyEvents, presetFor, withPresetEvents } from "./journeys.js";
 
@@ -90,25 +92,36 @@ const consentText = (c) => Object.entries(c).map(([k, v]) => `${k}=${v}`).join("
 /** The Google protocol fields of a hit, short: values for the ids and consent strings, bare names for the 1-flags. */
 const protocolText = (p) => Object.entries(p).map(([k, v]) => (["_fv", "_ss", "_nsi"].includes(k) && v === "1" ? k : `${k}=${v}`)).join(" ");
 
-function describeHit(h, steps, index) {
+/** Where an iframe's hit came from, and whether the plan checks will count it (see src/frames.js). */
+function frameNote(h, ids) {
+  if (!h.frame) return "";
+  if (h.frame.party === "site") return ` (from an iframe on the site: ${h.frame.origin})`;
+  return isWidgetHit(h, ids)
+    ? ` (from an embedded widget at ${h.frame.origin}, to an account the site's tags don't use: left out of the plan checks, kept for consent and personal data)`
+    : ` (from a third-party iframe at ${h.frame.origin}, to the site's own account)`;
+}
+
+function describeHit(h, steps, index, ids = new Set()) {
   const entries = Object.entries(h.params ?? {}).filter(([k]) => !["v", "tid", "gtm", "_p", "cid", "sid", "_s", "sct", "seg", "dl", "dr", "dt", "ul", "sr", "_et", "en"].includes(k));
   const params = [
     ...entries.filter(([k]) => !WHOLE_FIELDS.has(k)).slice(0, 12).map(([k, v]) => cut(`${k}=${show(v)}`, VALUE_LIMIT)),
     ...entries.filter(([k]) => WHOLE_FIELDS.has(k)).map(([k, v]) => `${k}=${show(v)}`),
   ].join(", ");
   const late = h.late ? ` (arrived ${(h.late.ms / 1000).toFixed(1)} s late, after the step that loaded its page: "${steps[h.step]?.label ?? `step ${h.step}`}")` : "";
-  return `- [h${index}] ${h.platform} ${h.name}${h.consent ? ` [consent ${consentText(h.consent)}]` : ""}${h.protocol ? ` {${protocolText(h.protocol)}}` : ""}${params ? `: ${params}` : ""}${late}`;
+  return `- [h${index}] ${h.platform} ${h.name}${h.consent ? ` [consent ${consentText(h.consent)}]` : ""}${h.protocol ? ` {${protocolText(h.protocol)}}` : ""}${params ? `: ${params}` : ""}${late}${frameNote(h, ids)}`;
 }
 
 /** A consent command in full, as key=value; any other push as JSON, cut, with its page address fields whole. */
 function describePush(p) {
+  // Pushes to a dataLayer of another name (a container's l=) say which.
+  const layer = `${p.frame ? `[iframe ${p.frame.origin}] ` : ""}${p.layer ? `[${p.layer}] ` : ""}`;
   if (isConsentCommand(p, "default") || isConsentCommand(p, "update")) {
     const signals = p.value[2] && typeof p.value[2] === "object" ? Object.entries(p.value[2]).map(([k, v]) => `${k}=${show(v)}`).join(" ") : show(p.value[2]);
-    return `- consent ${p.value[1]}: ${signals}`;
+    return `- ${layer}consent ${p.value[1]}: ${signals}`;
   }
   const json = JSON.stringify(p.value) ?? String(p.value);
   const whole = json.length > PUSH_LIMIT ? wholeFieldsIn(p.value) : [];
-  return `- ${cut(json, PUSH_LIMIT)}${whole.length ? ` (${whole.map(([k, v]) => `${k}=${v}`).join(", ")})` : ""}`;
+  return `- ${layer}${cut(json, PUSH_LIMIT)}${whole.length ? ` (${whole.map(([k, v]) => `${k}=${v}`).join(", ")})` : ""}`;
 }
 
 /** A call to a tracking endpoint that carries no event the tool reads, such as a Consent Mode ping, with its consent. */
@@ -150,9 +163,17 @@ function cookieLines(session, step) {
   return lines;
 }
 
+/** One container load in words: its ID, what inserted it, its dataLayer and where it came from. */
+function describeLoad(l) {
+  const c = messages("en").ui.containers;
+  const extra = [l.layer !== "dataLayer" && `dataLayer ${l.layer}`, l.served === "site" && `served from ${l.host}`, l.environment && c.environment(l.environment), l.frame && c.iframe(l.frame.origin, l.frame.party)].filter(Boolean);
+  return `  ${l.id} (${c.script[l.script]}): ${c.kinds[l.kind](l.by)}${extra.length ? `; ${extra.join(", ")}` : ""}`;
+}
+
 export function stepCapture(audit, step) {
   const { session } = audit;
   const hits = session.hits.filter((h) => h.step === step);
+  const ids = siteIds(session);
   const pushes = session.dataLayerLog.filter((e) => e.step === step);
   // Hits that arrived during this step for a page an earlier step loaded are listed there, and noted here.
   const lateHere = session.hits.filter((h) => h.late?.during === step);
@@ -163,11 +184,13 @@ export function stepCapture(audit, step) {
     ...(problem?.kind === "crash" ? [`WARNING: the page crashed in the browser (the ${problem.vendor} error screen)${problem.refusedScripts ? `; ${problem.refusedScripts} of its own scripts came back as HTML pages, which bot protection or a mismatched deployment does` : ""}. Its tags may never have run.`] : []),
     `Step ${step}: "${session.steps[step]?.label ?? ""}". Read a hit's full parameters with get_hit (audit_id, step ${step}, its [h] number).`,
     `Tracking hits sent by this step: ${hits.length}`,
-    ...hits.map((h, i) => describeHit(h, session.steps, i)),
+    ...hits.map((h, i) => describeHit(h, session.steps, i, ids)),
   ];
   if (lateHere.length) lines.push(`Arrived during this step but belong to the step that loaded their page: ${lateHere.map((h) => `${h.platform} ${h.name} (step "${session.steps[h.step]?.label ?? h.step}")`).join(", ")}`);
   if (pings.length) lines.push("Other calls to analytics and ad endpoints, not read as events (Consent Mode pings, resends, remarketing):", ...pings.map(describeCall));
   if (pushes.length) lines.push("dataLayer pushes:", ...pushes.map(describePush));
+  const loads = loadSources({ containerLoads: (session.containerLoads ?? []).filter((l) => l.step === step), dataLayerLog: session.dataLayerLog });
+  if (loads.length) lines.push("Google containers loaded:", ...loads.map(describeLoad));
   lines.push(...cookieLines(session, step));
   const tag = session.steps[step]?.tagConsent;
   if (tag) {
@@ -214,6 +237,32 @@ export function hitDetail(audit, step, index) {
  * hits it sent with their consent, its consent commands and other tracking calls, the Google tag's consent when it
  * changed, and the cookies and ids that changed.
  */
+/** A container load or row as compact JSON: the ID, its source, and the dataLayer, host and environment when they are not the usual ones. */
+function containerJson(l) {
+  return {
+    id: l.id, source: l.kind, ...(l.by ? { by: l.by } : {}),
+    ...(l.layer !== "dataLayer" ? { data_layer: l.layer } : {}),
+    ...(l.served === "site" ? { served_from: l.host } : {}),
+    ...(l.environment ? { gtm_environment: l.environment } : {}),
+    ...(l.frame ? { iframe: { origin: l.frame.origin, party: l.frame.party } } : {}),
+    ...(l.pages ? { pages: l.pages } : {}),
+  };
+}
+
+/** The Google containers of the runs and how each reached the page, as lines for a tool result; [] when none loaded. */
+export function containerLines(runs) {
+  const rows = containerRows(runs);
+  if (!rows.length) return [];
+  const c = messages("en").ui.containers;
+  return [
+    "Google containers (how each reached the page):",
+    ...rows.map((r) => {
+      const extra = [r.layer !== "dataLayer" && `dataLayer ${r.layer}`, r.served === "site" && `served from ${r.host}`, r.environment && c.environment(r.environment), r.frame && c.iframe(r.frame.origin, r.frame.party), `${r.pages.length} ${r.pages.length === 1 ? "page" : "pages"}`].filter(Boolean);
+      return `  ${r.id} (${c.script[r.script]}): ${c.kinds[r.kind](r.by)}; ${extra.join(", ")}`;
+    }),
+  ];
+}
+
 export function timelineOf(run) {
   let lastIds = null;
   return (run.steps ?? []).map((st) => {
@@ -224,12 +273,17 @@ export function timelineOf(run) {
     const names = (kind) => [...new Set(changes.filter((c) => c.change === kind).map((c) => c.name))];
     const entry = { step: st.index, action: st.label, ...(st.pagePath ? { page: st.pagePath } : {}) };
     if (st.error) entry.error = st.error;
-    if (hits.length) entry.hits = hits.map((h) => ({ platform: h.platform, event: h.name, ...(h.consent ? { consent: h.consent } : {}), ...(h.late ? { late_ms: h.late.ms } : {}) }));
+    if (hits.length) entry.hits = hits.map((h) => ({ platform: h.platform, event: h.name, ...(h.consent ? { consent: h.consent } : {}), ...(h.late ? { late_ms: h.late.ms } : {}), ...(h.frame ? { iframe: h.frame.origin } : {}) }));
+    // An embedded widget's own hits, kept apart from the site's (see src/frames.js).
+    const widget = (run.widgetHits ?? []).filter((h) => h.step === st.index);
+    if (widget.length) entry.widget_hits = widget.map((h) => ({ widget: h.frame.origin, platform: h.platform, event: h.name, ...(h.id ? { id: h.id } : {}), ...(h.consent ? { consent: h.consent } : {}) }));
     if (others.length) entry.other_tracking_calls = others.length;
     if (commands.length) entry.consent_commands = commands.map((e) => ({ [e.value[1]]: e.value[2] }));
     if (st.tagConsent) entry.tag_consent = Object.fromEntries(Object.entries(st.tagConsent.entries).map(([k, e]) => [k, e.update ?? e.default ?? null]));
     const cookies = Object.fromEntries(["added", "changed", "removed"].map((k) => [k, names(k)]).filter(([, list]) => list.length));
     if (Object.keys(cookies).length) entry.cookies = cookies;
+    const loads = loadSources({ containerLoads: (run.containerLoads ?? []).filter((l) => l.step === st.index), dataLayerLog: run.dataLayerLog });
+    if (loads.length) entry.containers = loads.map(containerJson);
     if (st.identity && JSON.stringify(st.identity) !== JSON.stringify(lastIds)) entry.ids = st.identity;
     if (st.identity) lastIds = st.identity;
     return entry;
@@ -466,15 +520,33 @@ export function buildServer(opts) {
     },
   );
 
+  server.registerTool(
+    "get_containers",
+    {
+      title: "List the Google containers loaded so far",
+      description:
+        "Returns every GTM container (gtm.js) and Google tag (gtag/js) this audit's pages loaded so far, and how each reached the page: a script tag in the HTML, the inline snippet, another script (named by its address, such as a consent platform), a Custom HTML tag or a Google tag in another GTM container, a container loading another itself (a Zone or a tag template), a gtag('config') command, an event's send_to with no config, or a destination of the Google tag. Also the dataLayer each reads, whether it was served from the site's own domain, the GTM environment when one is named, and the step it loaded at. Duplicates, GTM environments and split dataLayers are flagged by finish_audit.",
+      inputSchema: { audit_id: z.string() },
+      annotations: { readOnlyHint: true },
+    },
+    async ({ audit_id }) => {
+      const { session } = getAudit(audit_id);
+      const loads = loadSources({ containerLoads: session.containerLoads ?? [], dataLayerLog: session.dataLayerLog });
+      if (!loads.length) return text("No GTM container or Google tag script has loaded on this audit's pages yet.");
+      const lines = loads.map((l) => `Step ${l.step} ("${session.steps[l.step]?.label ?? ""}"), ${l.page ?? "?"}:\n${describeLoad(l)}`);
+      return text(`${loads.length} container ${loads.length === 1 ? "load" : "loads"}:\n${lines.join("\n")}\n\nAs JSON: ${JSON.stringify(loads.map((l) => ({ step: l.step, page: l.page, ...containerJson(l) })))}`);
+    },
+  );
+
   server.registerTool(
     "get_report",
     {
       title: "Read a report this server wrote",
       description:
-        "Returns a report finish_audit or run_audit wrote, so it can be read without access to the computer running this server. part markdown (default): report.md, the verdict, findings, consent and journeys in about 120 lines. summary: summary.json, the counts, journeys and findings as JSON. timeline: one JSON entry per step of each journey (hits with their consent, consent commands, the Google tag's consent, cookies and ids).",
+        "Returns a report finish_audit or run_audit wrote, so it can be read without access to the computer running this server. part markdown (default): report.md, the verdict, findings, consent and journeys in about 120 lines. summary: summary.json, the counts, journeys and findings as JSON. timeline: one JSON entry per step of each journey (hits with their consent, consent commands, the Google tag's consent, cookies and ids, the Google containers loaded). containers: every GTM container and Google tag the journeys loaded as JSON, with how each reached the page (source html, inline, script, custom_html, google_tag, nested, config, send_to or destination, and by: the container or script that loaded it), its dataLayer, host, GTM environment and pages.",
       inputSchema: {
         report: z.string().describe("The report name finish_audit or run_audit gave."),
-        part: z.enum(["markdown", "summary", "timeline"]).optional().describe("Default markdown."),
+        part: z.enum(["markdown", "summary", "timeline", "containers"]).optional().describe("Default markdown."),
       },
       annotations: { readOnlyHint: true },
     },
@@ -485,6 +557,7 @@ export function buildServer(opts) {
         if (part === "markdown") return text(await readFile(path.join(dir, "report.md"), "utf8"));
         if (part === "summary") return text(await readFile(path.join(dir, "summary.json"), "utf8"));
         const capture = JSON.parse(await readFile(path.join(dir, "capture.json"), "utf8"));
+        if (part === "containers") return text(JSON.stringify(containerRows(capture.runs ?? []).map(containerJson)));
         return text(JSON.stringify((capture.runs ?? []).map((r) => ({ journey: r.journeyId, viewport: r.viewport, steps: timelineOf(r) }))));
       } catch (err) {
         return fail(`Could not read the report: ${err.message}`);
@@ -594,13 +667,14 @@ export function buildServer(opts) {
         `${run.hits.length} tracking hits, ${run.dataLayerLog.length} dataLayer pushes and ${run.network.length} analytics or ad network calls captured over ${run.steps.length} steps.`,
         skippedLine(run),
         ...((platform) => (platform ? [`Consent platform: ${platform.vendor}. ${platform.facts.join(" ")}`] : []))(cmpFacts(messages("en"), [run])),
+        ...containerLines([run]),
         opts.allowFiles
           ? `Full report with the event timeline: ${reportPath}`
           : opts.reportsUrl
             ? `Full report with the event timeline: ${opts.reportsUrl}/${path.basename(outDir)}/report.html`
             : "",
         "",
-        `To read the report here: get_report with report "${path.basename(outDir)}" (markdown, summary or timeline).`,
+        `To read the report here: get_report with report "${path.basename(outDir)}" (markdown, summary, timeline or containers).`,
         "Explain each problem to the user with its likely cause and fix.",
       ];
       return {
@@ -746,8 +820,9 @@ export function buildServer(opts) {
             ...(result.baseline ? [`${result.baseline.accepted} accepted from the baseline${result.baseline.partial ? `, ${result.baseline.partial} accepted in some places only (still counted)` : ""}, ${result.baseline.stale.length} stale baseline entries`] : []),
             ...result.runs.map((r) => `${r.journeyId} (${r.viewport}): ${r.completed ? "completed" : "not completed"}, ${r.note}`),
             ...grouped.map((f) => `- ${m.severity[f.severity]}${f.accepted ? ` (${m.ui.accepted})` : ""}: ${f.detail}`),
+            ...containerLines(result.runs),
             `Report: ${result.reportPath}`,
-            `To read the report here: get_report with report "${path.basename(result.outDir)}" (markdown, summary or timeline).`,
+            `To read the report here: get_report with report "${path.basename(result.outDir)}" (markdown, summary, timeline or containers).`,
           ].join("\n"),
         );
       },

package/src/report.js

@@ -5,6 +5,7 @@ import { createProvider } from "./providers.js";
 import { canonicalEvent, groupFindings, summarize } from "./checks.js";
 import { messages } from "./i18n.js";
 import { buildInventory } from "./inventory.js";
+import { containerRows } from "./containers.js";
 import { computeMetrics } from "./metrics.js";
 import { historySummaryLines, sparkline } from "./history.js";
 import { cardIds } from "./html/lib.js";
@@ -396,6 +397,21 @@ function mdInventory(m, runs) {
   return lines;
 }
 
+/** The Google containers and how each reached the page, one row per container and source. Omitted when none loaded. */
+function mdContainers(m, runs) {
+  const rows = containerRows(runs);
+  if (!rows.length) return [];
+  const c = m.ui.containers;
+  const lines = [`## ${m.ui.containersTitle}`, "", `| ${m.ui.containerCol} | ${m.ui.sourceCol} | ${m.ui.layerCol} | ${m.ui.servedCol} | ${m.ui.pagesCol} |`, "|---|---|---|---|---|"];
+  for (const r of rows.slice(0, MD_INVENTORY_ROWS)) {
+    const served = r.served === "google" ? c.served.google : `${c.served.site} (${r.host})`;
+    lines.push(`| ${mdText(r.id)} (${c.script[r.script]}) | ${mdText(c.kinds[r.kind](r.by))}${r.frame ? `, ${mdText(c.iframe(r.frame.origin, r.frame.party))}` : ""}${r.environment ? `, ${mdText(c.environment(r.environment))}` : ""} | ${mdText(r.layer)} | ${mdText(served)} | ${r.pages.length} |`);
+  }
+  if (rows.length > MD_INVENTORY_ROWS) lines.push("", m.ui.md.moreIn(rows.length - MD_INVENTORY_ROWS, "report.html"));
+  lines.push("");
+  return lines;
+}
+
 /** The trend in up to five lines: the text sparkline with the direction, then the open-longest and flapping lines. */
 function mdTrend(m, trend, lang) {
   if (!trend || trend.runs < 2) return [];
@@ -447,6 +463,7 @@ export function renderMarkdown({ title, site = null, generatedAt, findings, expl
   lines.push(...mdJourneys(m, runs, rows));
   lines.push(...mdNotChecked(m, runs, rows, plan, consentScenarios));
   lines.push(...mdInventory(m, runs));
+  lines.push(...mdContainers(m, runs));
   // A report with its own name or logo carries no Analitik İşler credit; the ai tag debugger one stays.
   if (brand?.name || brand?.logo) lines.push("---", "", `_${brand.name ? `${brand.name} · ` : ""}${m.ui.generatedBy}_`, "");
   else if (branding) lines.push("---", "", `_${m.ui.generatedBy} · [analitikisler.com](https://analitikisler.com)_`, "");