@tokenoftrust/cli 4.9.0 → 4.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "4.9.0",
+  "version": "4.10.0",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/analytics-declaration.mjs

@@ -0,0 +1,299 @@
+// @ts-check
+/**
+ * The tenant `analytics.json` contract, for the surfaces that cannot load the platform's
+ * TypeScript: `tot validate`, the kit's validate-site, `scripts/tenant/validate.mjs` and
+ * materialize-tenant.
+ *
+ * The platform materializes the file with `materializeTenantAnalyticsDeclarations`
+ * (`packages/public-runtime/src/integration/tenant-analytics.ts`), which builds each destination
+ * through the reviewed adapter builder. This module reports the same `{ path, code }` set for any
+ * input; `agency-kit/tools/lib/fixtures/analytics-declarations.json` is run through both, so a
+ * drift on either side fails a test.
+ *
+ * Messages carry no value from the file — never an id, never a key's value — only the field path
+ * and a fixed explanation, so a finding is safe to print, log or forward.
+ *
+ * Pure: callers pass the file's text. `packages/cli/src/analytics-declaration.mjs` is a
+ * byte-identical copy (a test pins it).
+ */
+
+/** The tenant-owned file, at the tenant tree's root. */
+export const ANALYTICS_DECLARATION_FILE = "analytics.json";
+
+/** The current `analytics.json` contract version. */
+export const ANALYTICS_DECLARATION_SCHEMA_VERSION = 1;
+
+/** The stages a destination id may be declared for, in the platform's environment order. */
+export const ANALYTICS_STAGES = Object.freeze(["local", "candidate", "staged", "live"]);
+
+/** The `euUkVisitors` policies; `ask` is the default. */
+export const ANALYTICS_EU_UK_POLICIES = Object.freeze(["ask", "count-only", "full", "none"]);
+
+/**
+ * The first-class platform adapters a tenant may declare. Pinned against the platform's
+ * `PLATFORM_ADAPTERS` by `packages/public-runtime/tests/integration/tenant-analytics.test.ts`.
+ */
+export const ANALYTICS_ADAPTERS = Object.freeze([
+  Object.freeze({
+    adapterId: "platform.google-measurement",
+    maxDestinationsPerStage: 4,
+    idPattern: /^G-[A-Z0-9]{4,20}$/,
+    idLabel: "GA4 measurement id (e.g. G-XXXXXXX)",
+  }),
+  Object.freeze({
+    adapterId: "platform.meta-pixel",
+    maxDestinationsPerStage: 1,
+    idPattern: /^\d{10,20}$/,
+    idLabel: "Meta pixel id (10–20 digits)",
+  }),
+  Object.freeze({
+    adapterId: "platform.amplitude",
+    maxDestinationsPerStage: 1,
+    idPattern: /^(?=[a-f0-9]{32}$)(?=.*[a-f])[a-f0-9]+$/i,
+    idLabel: "Amplitude project API key (32 hexadecimal characters)",
+  }),
+]);
+
+const ANNOTATION_KEYS = ["$schema", "$comment", "$id"];
+const ROOT_KEYS = ["schemaVersion", "destinations", "euUkVisitors"];
+const DESTINATION_KEYS = ["adapter", "ids"];
+
+/**
+ * @typedef {Object} AnalyticsViolation
+ * @property {string} path  the offending field, e.g. `destinations[0].ids.live[1]`
+ * @property {string} code  a stable machine code, e.g. `format`, `unknown_field`
+ */
+
+/**
+ * @typedef {Object} AnalyticsFinding
+ * @property {string} path
+ * @property {string} code
+ * @property {string} message  value-free: the path, the code and a fixed explanation
+ * @property {string} remedy
+ */
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * @param {Record<string, unknown>} obj
+ * @param {readonly string[]} allowed
+ * @param {string} base
+ * @param {AnalyticsViolation[]} out
+ */
+function unknownKeys(obj, allowed, base, out) {
+  for (const key of Object.keys(obj)) {
+    if (allowed.includes(key) || ANNOTATION_KEYS.includes(key)) continue;
+    out.push({ path: base ? `${base}.${key}` : key, code: "unknown_field" });
+  }
+}
+
+/**
+ * The adapter builder's per-stage id rules, with its paths re-anchored under the destination.
+ * @param {Record<string, unknown>} ids
+ * @param {(typeof ANALYTICS_ADAPTERS)[number]} adapter
+ * @param {string} base  `destinations[i]`
+ * @param {AnalyticsViolation[]} out
+ */
+function stageIdViolations(ids, adapter, base, out) {
+  /** @type {Map<string, string[]>} */
+  const valid = new Map();
+  for (const [stage, raw] of Object.entries(ids)) {
+    const at = `${base}.ids.${stage}`;
+    if (!ANALYTICS_STAGES.includes(stage)) {
+      out.push({ path: at, code: "unknown_enum" });
+      continue;
+    }
+    if (!Array.isArray(raw)) {
+      out.push({ path: at, code: "type" });
+      continue;
+    }
+    if (raw.length === 0) {
+      out.push({ path: at, code: "empty" });
+      continue;
+    }
+    if (raw.length > adapter.maxDestinationsPerStage) {
+      out.push({ path: at, code: "too_many_destinations" });
+      continue;
+    }
+    let stageOk = true;
+    raw.forEach((id, index) => {
+      if (typeof id !== "string" || id.length === 0) {
+        out.push({ path: `${at}[${index}]`, code: "type" });
+        stageOk = false;
+        return;
+      }
+      if (!adapter.idPattern.test(id)) {
+        out.push({ path: `${at}[${index}]`, code: "format" });
+        stageOk = false;
+      }
+    });
+    if (!stageOk) continue;
+    if (new Set(raw).size !== raw.length) {
+      out.push({ path: at, code: "duplicate" });
+      continue;
+    }
+    valid.set(stage, /** @type {string[]} */ (raw));
+  }
+  const live = valid.get("live");
+  if (live === undefined) {
+    out.push({ path: `${base}.ids.live`, code: "required" });
+    return;
+  }
+  for (const stage of ANALYTICS_STAGES) {
+    if (stage === "live") continue;
+    (valid.get(stage) ?? []).forEach((id, index) => {
+      if (live.includes(id)) out.push({ path: `${base}.ids.${stage}[${index}]`, code: "non_live_reuses_live_id" });
+    });
+  }
+}
+
+/**
+ * Every violation in an already-parsed `analytics.json` value. `undefined`/`null` (no file) is
+ * the undeclared norm and has none.
+ * @param {unknown} value
+ * @returns {AnalyticsViolation[]}
+ */
+export function analyticsDeclarationViolations(value) {
+  /** @type {AnalyticsViolation[]} */
+  const out = [];
+  if (value === undefined || value === null) return out;
+  if (!isPlainObject(value)) {
+    out.push({ path: "(root)", code: "type" });
+    return out;
+  }
+  unknownKeys(value, ROOT_KEYS, "", out);
+  if ("euUkVisitors" in value && !ANALYTICS_EU_UK_POLICIES.includes(/** @type {string} */ (value.euUkVisitors))) {
+    out.push({ path: "euUkVisitors", code: "unknown_enum" });
+  }
+  if ("schemaVersion" in value && value.schemaVersion !== ANALYTICS_DECLARATION_SCHEMA_VERSION) {
+    out.push({ path: "schemaVersion", code: "unsupported_version" });
+  }
+  const destinations = value.destinations;
+  if (!Array.isArray(destinations)) {
+    out.push({ path: "destinations", code: "type" });
+    return out;
+  }
+  /** @type {Set<string>} */
+  const seenAdapters = new Set();
+  destinations.forEach((destination, index) => {
+    const base = `destinations[${index}]`;
+    if (!isPlainObject(destination)) {
+      out.push({ path: base, code: "type" });
+      return;
+    }
+    unknownKeys(destination, DESTINATION_KEYS, base, out);
+    const adapterId = destination.adapter;
+    if (typeof adapterId !== "string" || adapterId.length === 0) {
+      out.push({ path: `${base}.adapter`, code: "type" });
+      return;
+    }
+    const ids = destination.ids;
+    if (!isPlainObject(ids)) {
+      out.push({ path: `${base}.ids`, code: "type" });
+      return;
+    }
+    if (seenAdapters.has(adapterId)) {
+      out.push({ path: `${base}.adapter`, code: "duplicate" });
+      return;
+    }
+    seenAdapters.add(adapterId);
+    const adapter = ANALYTICS_ADAPTERS.find((a) => a.adapterId === adapterId);
+    if (!adapter) {
+      out.push({ path: `${base}.adapter`, code: "unknown_adapter" });
+      return;
+    }
+    stageIdViolations(ids, adapter, base, out);
+  });
+  return out;
+}
+
+/**
+ * Parse `analytics.json` text. Unparseable text is a `(root)` `invalid_json` violation, never an
+ * absent file: a declaration that cannot be read must refuse, not publish with no analytics.
+ * @param {string} text
+ * @returns {{ ok: true, value: unknown } | { ok: false, violations: AnalyticsViolation[] }}
+ */
+export function parseAnalyticsDeclaration(text) {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return { ok: false, violations: [{ path: "(root)", code: "invalid_json" }] };
+  }
+}
+
+const ADAPTER_IDS = ANALYTICS_ADAPTERS.map((a) => a.adapterId).join(", ");
+const ID_FORMATS = ANALYTICS_ADAPTERS.map((a) => `${a.adapterId}: ${a.idLabel}`).join("; ");
+
+/**
+ * A fixed, value-free explanation and remedy for a violation.
+ * @param {AnalyticsViolation} violation
+ * @returns {{ message: string, remedy: string }}
+ */
+export function analyticsViolationText({ path, code }) {
+  switch (code) {
+    case "invalid_json":
+      return { message: "analytics.json is not valid JSON", remedy: "fix the JSON syntax" };
+    case "type":
+      return {
+        message: "has the wrong type",
+        remedy: 'use { "schemaVersion": 1, "destinations": [{ "adapter": "<adapter id>", "ids": { "live": ["<id>"] } }] }',
+      };
+    case "unknown_field":
+      return { message: "is not an analytics.json field", remedy: "remove it; analytics.json is a closed contract" };
+    case "unknown_enum":
+      return path === "euUkVisitors"
+        ? { message: "is not an EU/UK visitor policy", remedy: `use one of: ${ANALYTICS_EU_UK_POLICIES.join(", ")}` }
+        : { message: "is not a stage", remedy: `use one of: ${ANALYTICS_STAGES.join(", ")}` };
+    case "unsupported_version":
+      return { message: "is not a supported schemaVersion", remedy: `set it to ${ANALYTICS_DECLARATION_SCHEMA_VERSION}` };
+    case "unknown_adapter":
+      return { message: "is not a first-class analytics adapter", remedy: `use one of: ${ADAPTER_IDS}` };
+    case "empty":
+      return { message: "names no destination id", remedy: "name at least one id, or remove the stage" };
+    case "too_many_destinations":
+      return { message: "names more destination ids than this adapter accepts per stage", remedy: "remove the extra ids" };
+    case "format":
+      return { message: "is not a valid destination id for this adapter", remedy: `use the adapter's id format (${ID_FORMATS})` };
+    case "duplicate":
+      return path.endsWith(".adapter")
+        ? { message: "names an adapter an earlier destination already names", remedy: "declare each adapter once, with all of its ids" }
+        : { message: "names the same destination id twice", remedy: "list each id once" };
+    case "required":
+      return { message: "has no valid live destination id", remedy: "declare a valid live id for every destination" };
+    case "non_live_reuses_live_id":
+      return {
+        message: "reuses a live destination id, so non-live traffic would reach the live property",
+        remedy: "use a separate test id, or leave the stage unset",
+      };
+    default:
+      return { message: "is invalid", remedy: "see docs/architecture/analytics-activation.md" };
+  }
+}
+
+/**
+ * Every violation in an `analytics.json` file's text. A file that is present but holds `null` is
+ * a `(root)` `type` violation: only an absent file declares nothing.
+ * @param {string} text
+ * @returns {AnalyticsViolation[]}
+ */
+export function analyticsDeclarationTextViolations(text) {
+  const parsed = parseAnalyticsDeclaration(text);
+  if (!parsed.ok) return [...parsed.violations];
+  if (parsed.value === null) return [{ path: "(root)", code: "type" }];
+  return analyticsDeclarationViolations(parsed.value);
+}
+
+/**
+ * Every finding in an `analytics.json` file's text, each value-free.
+ * @param {string} text
+ * @returns {AnalyticsFinding[]}
+ */
+export function analyticsDeclarationFindings(text) {
+  return analyticsDeclarationTextViolations(text).map((violation) => {
+    const { message, remedy } = analyticsViolationText(violation);
+    return { ...violation, message: `${violation.path}: [${violation.code}] ${message}`, remedy };
+  });
+}

package/src/validate.mjs

@@ -25,6 +25,7 @@ import {
 } from "./tot-repo-mappings.mjs";
 import { isForbiddenPublicPath, publicBinaryFindings } from "./public-binaries.mjs";
 import { pageSlugFindings } from "./page-slugs.mjs";
+import { ANALYTICS_DECLARATION_FILE, analyticsDeclarationFindings } from "./analytics-declaration.mjs";
 import { parseSku, skuCollisions, skuFindings } from "./sku.mjs";
 
 export {
@@ -1351,6 +1352,13 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
+  const analyticsPath = located(ANALYTICS_DECLARATION_FILE);
+  if (existsSync(analyticsPath)) {
+    for (const f of analyticsDeclarationFindings(readFileSync(analyticsPath, "utf8"))) {
+      findings.push(mk(ERROR, "analytics-declaration", ANALYTICS_DECLARATION_FILE, f.message, f.remedy));
+    }
+  }
+
   // 3. content JSON — parse + blocks shape
   for (const name of ["home.json", "chrome.json"]) {
     const p = join(contentDir, name);