@analitikisler/ai-tag-debugger 0.16.0 → 0.17.0

package/src/schema.js

@@ -0,0 +1,190 @@
+// The shape of the config file and the measurement plan, checked as soon as they are read. A typo
+// such as "viewport" or a step action "clik" then fails at once with the field named, instead of
+// deep in a run or by silently doing nothing. Unknown keys are allowed (they only get a warning),
+// so an existing config with an extra harmless key still runs.
+import { z } from "zod";
+import { VIEWPORTS } from "./browser.js";
+import { LANGUAGES } from "./i18n.js";
+import { PROVIDERS as PLATFORMS } from "./parsers.js";
+import { PROVIDERS as AI_PROVIDERS } from "./providers.js";
+
+const text = z.string();
+const flag = z.boolean();
+const names = z.array(z.string());
+
+export const STEP_ACTIONS = ["goto", "click", "fill", "select", "scroll", "wait"];
+
+export const STEP_SCHEMA = z.looseObject({
+  action: z.enum(STEP_ACTIONS),
+  selector: text.optional(),
+  ref: z.int().optional(),
+  text: text.optional(),
+  value: z.union([text, z.number()], { error: "must be a text or a number" }).optional(),
+  url: text.optional(),
+  reason: text.optional(),
+  accepts_consent: flag.optional(),
+  rejects_consent: flag.optional(),
+  optional: flag.optional(),
+});
+
+export const JOURNEY_SCHEMA = z.looseObject({
+  id: text.min(1),
+  goal: text.optional(),
+  start: text.optional(),
+  steps: z.array(STEP_SCHEMA).optional(),
+  incomplete: text.optional(),
+});
+
+export const PLAN_EVENT_SCHEMA = z.looseObject({
+  // The checks lowercase the platform, so "GA4" and "Meta" in a plan keep working as they did.
+  platform: z.string().transform((v) => v.toLowerCase()).pipe(z.enum(Object.keys(PLATFORMS))),
+  name: text.min(1),
+  aliases: names.optional(),
+  required_params: names.optional(),
+  journeys: names.optional(),
+  allow_multiple: flag.optional(),
+  custom: flag.optional(),
+  description: text.nullish(),
+  // Documentation fields the checks ignore: a sentence or an object are both fine.
+  trigger: z.union([text, z.looseObject({ page: text.nullish(), element: text.nullish() })]).nullish(),
+  parameters: z.record(text, z.looseObject({ custom: flag.optional(), description: text.nullish(), example: z.unknown().optional() })).optional(),
+  seen: flag.optional(),
+});
+
+export const PLAN_SCHEMA = z.looseObject({
+  site: text.optional(),
+  consent_mode: flag.optional(),
+  learned: flag.optional(),
+  pages: z.array(z.unknown()).optional(),
+  events: z.array(PLAN_EVENT_SCHEMA),
+  user_properties: z.array(z.union([text, z.looseObject({ name: text.min(1), description: text.nullish(), example: z.unknown().optional() })], { error: 'must be a name or { "name", "description", "example" }' })).optional(),
+});
+
+export const CONFIG_SCHEMA = z.looseObject({
+  site: text.optional(),
+  // Null means "not set" for these, as it always did: the loaders treat null and absent alike.
+  plan: z.union([text, z.looseObject({})], { error: "must be a file path or a plan object" }).nullish(),
+  gtm_container: text.nullish(),
+  viewports: z.array(z.enum(Object.keys(VIEWPORTS))).optional(),
+  journeys: z.array(JOURNEY_SCHEMA).optional(),
+  allowed_hosts: names.optional(),
+  providers: z.union([names, text], { error: 'must be a list of platforms, e.g. ["ga4", "meta"]' }).optional(),
+  detect_providers: flag.optional(),
+  campaign_checks: flag.optional(),
+  block_hits: flag.optional(),
+  consent_scenarios: flag.optional(),
+  keep_bodies: flag.optional(),
+  branding: flag.optional(),
+  // The range itself is checked by parseConcurrency, which gives the exact message for the CLI flag too.
+  concurrency: z.union([z.number(), text], { error: "must be a whole number from 1 to 8" }).optional(),
+  baseline: text.optional(),
+  language: z.enum(Object.keys(LANGUAGES)).nullish(),
+  report: z.looseObject({ name: text.nullish(), logo: text.nullish(), color: text.nullish(), pdf: flag.optional() }).nullish(),
+  provider: z.enum(Object.keys(AI_PROVIDERS)).optional(),
+  model: text.optional(),
+  base_url: text.optional(),
+  notify: z.looseObject({
+    slack: z.union([flag, text], { error: "must be a webhook URL, or true to read SLACK_WEBHOOK_URL" }).optional(),
+    email: z.union([text, names], { error: "must be an address or a list of addresses" }).optional(),
+  }).optional(),
+});
+
+/** Checks a config object. Returns { value, warnings }; throws when a field is wrong. */
+export function validateConfig(config, { file } = {}) {
+  return validate(CONFIG_SCHEMA, config, { what: "config", file });
+}
+
+/**
+ * Checks a measurement plan. Returns { value, warnings }; throws when a field is wrong.
+ * at: the path the plan sits at inside a bigger file, e.g. "plan" for a plan written inline in the config.
+ */
+export function validatePlan(plan, { file, at } = {}) {
+  return validate(PLAN_SCHEMA, plan, { what: "plan", file, at });
+}
+
+function validate(schema, input, { what, file, at }) {
+  const where = file ? ` in ${file}` : "";
+  const result = schema.safeParse(input);
+  if (!result.success) {
+    const lines = result.error.issues.map((issue) => `  ${pathOf(at, issue.path) || what}: ${describe(issue, input)}`);
+    throw new Error(`Invalid ${what}${where}:\n${lines.join("\n")}`);
+  }
+  const unknown = [];
+  unknownKeys(schema, input, [], unknown);
+  const warnings = unknown.map(({ path, suggestion }) => `Unknown key ${quote(pathOf(at, path))}${where} is ignored.${suggestion ? ` Did you mean ${quote(suggestion)}?` : ""}`);
+  return { value: result.data, warnings };
+}
+
+const quote = (s) => `"${s}"`;
+
+/** "journeys[1].steps[0].action" for the path ["journeys", 1, "steps", 0, "action"]. */
+const pathOf = (at, path) => path.reduce((s, key) => (typeof key === "number" ? `${s}[${key}]` : s ? `${s}.${key}` : key), at ?? "");
+
+const valueAt = (input, path) => path.reduce((v, key) => v?.[key], input);
+
+const MAX_SHOWN = 60;
+const show = (value) => {
+  const json = JSON.stringify(value) ?? String(value);
+  return json.length > MAX_SHOWN ? `${json.slice(0, MAX_SHOWN)}…` : json;
+};
+
+const KINDS = { array: "a list", object: "an object", string: "a text", boolean: "true or false", number: "a number", int: "a whole number" };
+
+function describe(issue, input) {
+  const value = valueAt(input, issue.path);
+  if (value === undefined) return "is required";
+  const got = `(got ${show(value)})`;
+  switch (issue.code) {
+    case "invalid_value":
+      return `must be one of ${issue.values.join(", ")} ${got}`;
+    case "invalid_type":
+      return `must be ${KINDS[issue.expected] ?? issue.expected} ${got}`;
+    case "too_small":
+      return issue.origin === "string" ? "must not be empty" : `${issue.message} ${got}`;
+    default:
+      // Unions and custom checks carry their own plain-language message.
+      return `${issue.message} ${got}`;
+  }
+}
+
+// Walks the value next to the schema and lists the keys no schema object knows about. Unions and
+// records are not entered: their keys are free-form, or (an inline plan) checked on their own.
+function unknownKeys(schema, value, path, out) {
+  const s = unwrap(schema);
+  if (s.def.type === "array" && Array.isArray(value)) value.forEach((item, i) => unknownKeys(s.def.element, item, [...path, i], out));
+  if (s.def.type !== "object" || !value || typeof value !== "object" || Array.isArray(value)) return;
+  const known = Object.keys(s.shape);
+  for (const key of Object.keys(value)) {
+    if (known.includes(key)) unknownKeys(s.shape[key], value[key], [...path, key], out);
+    else out.push({ path: [...path, key], suggestion: closest(key, known) });
+  }
+}
+
+function unwrap(schema) {
+  let s = schema;
+  while (["optional", "nullable"].includes(s.def.type)) s = s.def.innerType;
+  return s;
+}
+
+const MAX_DISTANCE = 2;
+
+/** The known key within two edits of the unknown one (a typo or a missing letter), or null. */
+export function closest(key, known) {
+  let best = null;
+  for (const candidate of known) {
+    const d = editDistance(key.toLowerCase(), candidate.toLowerCase());
+    if (d <= MAX_DISTANCE && (best === null || d < best.d)) best = { d, candidate };
+  }
+  return best?.candidate ?? null;
+}
+
+function editDistance(a, b) {
+  if (Math.abs(a.length - b.length) > MAX_DISTANCE) return MAX_DISTANCE + 1;
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j++) row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    prev = row;
+  }
+  return prev[b.length];
+}

package/src/sheet.js

@@ -4,6 +4,7 @@
 import { readFile, writeFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { PROVIDERS as PLATFORMS } from "./parsers.js";
+import { validatePlan } from "./schema.js";
 
 export const EVENT_COLUMNS = ["event", "platform", "parameter", "required", "example", "trigger", "description"];
 // Optional columns that keep the rest of a plan on a round trip.
@@ -141,7 +142,10 @@ export function rowsToPlan({ events: eventRows = [], user_properties: upRows = n
       user_properties.push({ name: r.name, description: r.description ?? "", example: r.example ?? "" });
     }
   }
-  return { plan: { ...(site ? { site } : {}), consent_mode: true, events, user_properties }, warnings };
+  const plan = { ...(site ? { site } : {}), consent_mode: true, events, user_properties };
+  // The same check every plan gets when it is read, so a bad import fails here, not in a later run.
+  validatePlan(plan);
+  return { plan, warnings };
 }
 
 const toCells = (objs, columns) => [columns, ...objs.map((o) => columns.map((c) => o[c] ?? ""))];
@@ -156,7 +160,7 @@ export const toCsv = (rows) => `${rows.map((r) => r.map(csvCell).join(",")).join
 
 /** Parses CSV text (RFC 4180, comma or semicolon separated) into an array of cell arrays. */
 export function parseCsv(text) {
-  text = text.replace(/^/, "");
+  text = text.replace(/^\uFEFF/, "");
   const firstLine = text.slice(0, text.search(/\r?\n|$/));
   const sep = (firstLine.match(/;/g)?.length ?? 0) > (firstLine.match(/,/g)?.length ?? 0) ? ";" : ",";
   const rows = [];
@@ -200,6 +204,7 @@ async function loadFflate() {
   }
 }
 
+// eslint-disable-next-line no-control-regex -- the characters XML forbids are stripped on purpose.
 const xmlEscape = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g, "");
 const xmlUnescape = (s) => s.replace(/&(lt|gt|quot|apos|amp|#\d+|#x[0-9a-f]+);/gi, (_, e) => {
   const named = { lt: "<", gt: ">", quot: '"', apos: "'", amp: "&" }[e.toLowerCase()];
@@ -284,6 +289,7 @@ export async function readPlanSheet(file, { site } = {}) {
   const ext = path.extname(file).toLowerCase();
   if (!(await exists(file))) throw new Error(`No file at ${file}.`);
   let tabs;
+  let upFile; // Only a CSV import has one, but the warning below names it either way.
   if (ext === ".xlsx") {
     const sheets = await readXlsx(await readFile(file));
     const find = (n) => Object.entries(sheets).find(([k]) => k.trim().toLowerCase() === n)?.[1];
@@ -294,7 +300,7 @@ export async function readPlanSheet(file, { site } = {}) {
     // 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`);
+    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 {
@@ -313,8 +319,8 @@ export async function writePlanSheet(plan, dir, { format = "xlsx" } = {}) {
   const tabs = { events: toCells(events, eventColumns), user_properties: toCells(user_properties, USER_PROPERTY_COLUMNS) };
   if (format === "csv") {
     const files = [path.join(dir, "events.csv"), path.join(dir, "user_properties.csv")];
-    await writeFile(files[0], `${toCsv(tabs.events)}`);
-    await writeFile(files[1], `${toCsv(tabs.user_properties)}`);
+    await writeFile(files[0], `\uFEFF${toCsv(tabs.events)}`);
+    await writeFile(files[1], `\uFEFF${toCsv(tabs.user_properties)}`);
     return files;
   }
   if (format !== "xlsx") throw new Error(`--format must be xlsx or csv (found "${format}").`);

package/src/whitelabel.js

@@ -43,16 +43,45 @@ const rgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
 const toHex = (c) => `#${c.map((v) => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, "0")).join("")}`;
 const mix = (hex, other, amount) => toHex(rgb(hex).map((v, i) => v + (other[i] - v) * amount));
 
-/** CSS that recolors the report's accent. The light theme gets a darker text color and a pale tint; the dark theme a lighter one. */
+// WCAG relative luminance and contrast ratio, so the link colour is checked instead of guessed.
+const luminance = (hex) => {
+  const [r, g, b] = rgb(hex).map((v) => v / 255).map((v) => (v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4));
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+export const contrast = (a, b) => {
+  const [h, l] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (h + 0.05) / (l + 0.05);
+};
+const MIN_TEXT_CONTRAST = 4.5;
+// The card surfaces of visual-system.md §1, which the link colour must read on.
+const LIGHT_CARD = "#ffffff";
+const DARK_CARD = "#141927";
+
+/** The colour mixed step by step towards `toward` until it reads at 4.5:1 on `surface`; the input when it already does. */
+function readable(hex, toward, surface) {
+  let c = hex;
+  for (let i = 0; i < 20 && contrast(c, surface) < MIN_TEXT_CONTRAST; i++) c = mix(c, toward, 0.1);
+  return c;
+}
+
+/**
+ * CSS that recolors the report's accent: the active tab rule, focus rings, links and the step plates (visual-system.md §9).
+ * The light theme gets a link colour darkened until it reads on a white card, the dark theme one lightened until it
+ * reads on the dark card, so a pale brand colour never gives unreadable links. The dark set is written under both dark
+ * selectors the report uses, so a forced light theme on a dark OS keeps the light accent.
+ */
 export function brandCss(color) {
   if (!color) return "";
   const black = [0, 0, 0], white = [255, 255, 255];
-  const light = `--accent:${color};--accent-fg:${mix(color, black, 0.2)};--accent-bg:${mix(color, white, 0.9)}`;
-  const dark = `--accent:${mix(color, white, 0.2)};--accent-fg:${mix(color, white, 0.5)};--accent-bg:${mix(color, [10, 14, 26], 0.75)}`;
-  return `:root{${light}}@media (prefers-color-scheme:dark){:root{${dark}}}`;
+  const light = `--accent:${color};--accent-fg:${readable(mix(color, black, 0.2), black, LIGHT_CARD)};--accent-bg:${mix(color, white, 0.9)}`;
+  const dark = `--accent:${mix(color, white, 0.2)};--accent-fg:${readable(mix(color, white, 0.5), white, DARK_CARD)};--accent-bg:${mix(color, [10, 14, 26], 0.75)}`;
+  return `:root{${light}}@media (prefers-color-scheme:dark){:root:not([data-theme="light"]){${dark}}}:root[data-theme="dark"]{${dark}}`;
 }
 
-/** Prints an HTML report to a PDF with Chromium. The print styles open every tab, so the PDF holds the whole report. */
+// A forwarded PDF loses its file name, so every page carries the document title and the page number (Chromium fills the spans).
+const PDF_FOOTER = '<div style="width:100%;font:9px system-ui,sans-serif;color:#4b5567;padding:0 10mm;display:flex;justify-content:space-between"><span class="title"></span><span><span class="pageNumber"></span> / <span class="totalPages"></span></span></div>';
+
+/** Prints an HTML report to a PDF with Chromium. The print styles stack every tab and open every details, so the PDF holds the whole report. */
 export async function writePdf(htmlPath, pdfPath) {
   const launch = { headless: true, env: browserEnv() };
   let browser;
@@ -69,7 +98,7 @@ export async function writePdf(htmlPath, pdfPath) {
     const page = await context.newPage();
     await page.goto(new URL(`file://${path.resolve(htmlPath)}`).href);
     await page.emulateMedia({ media: "print", colorScheme: "light" });
-    await page.pdf({ path: pdfPath, format: "A4", printBackground: true, margin: { top: "14mm", bottom: "14mm", left: "10mm", right: "10mm" } });
+    await page.pdf({ path: pdfPath, format: "A4", printBackground: true, displayHeaderFooter: true, headerTemplate: "<span></span>", footerTemplate: PDF_FOOTER, margin: { top: "14mm", bottom: "16mm", left: "10mm", right: "10mm" } });
   } finally {
     await browser.close();
   }