@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.0

package/packages/public-runtime/src/gtm-migration/graph.ts

@@ -0,0 +1,468 @@
+/**
+ * Normalized GTM migration graph — a pure, NON-EXECUTING transformation of an
+ * already-parsed, inert GTM container into a node/edge graph with complete
+ * object accounting.
+ *
+ * SECURITY CONTRACT (inherited — a reviewer WILL reject violations):
+ *   - Pure DATA transformation. Nothing here executes, evaluates, interprets, or
+ *     compiles any part of the export. Variable references are recovered by STRING
+ *     SCANNING `{{Name}}` tokens (see references.ts), never by evaluation.
+ *   - Pure and deterministic: no I/O, no globals mutated, stable node/edge order.
+ *   - Null-prototype safety: id/name lookup indexes are `Map`s (never object
+ *     literals), so attacker-controlled ids/names cannot collide with prototype
+ *     keys (`__proto__`, `constructor`, …).
+ *   - Bounded: `{{...}}` token scanning is capped per-string and in total, and the
+ *     edge count is capped — on breach the build STOPS WITH ACCOUNTING rather than
+ *     growing unboundedly.
+ *   - Nothing is silently dropped: a reference to a missing id/name is recorded in
+ *     `danglingReferences`, and `nodeCount` is asserted to equal the sum of the 10
+ *     input collections.
+ */
+
+import type { GtmContainer, GtmContainerVersion, GtmInertRecord } from "./types.js";
+import {
+  extractVariableTokensReport,
+  isBuiltInVariableRef,
+  readParentFolderId,
+  readTemplateId,
+  readTemplateTrailingId,
+  readTemplateTypeRef,
+  readTriggerIds,
+  resolveBuiltInTrigger,
+  type BuiltInTriggerInfo,
+} from "./references.js";
+
+/** The 10 GTM object collections, one graph-node kind each. */
+export type GtmObjectKind =
+  | "tag"
+  | "trigger"
+  | "variable"
+  | "builtInVariable"
+  | "customTemplate"
+  | "folder"
+  | "zone"
+  | "client"
+  | "gtagConfig"
+  | "transformation";
+
+/** The dependency-edge kinds resolved across the container. */
+export type GtmEdgeKind = "fires" | "blocks" | "references" | "parentFolder" | "usesTemplate";
+
+/**
+ * Marks a SYNTHETIC built-in node — a GTM reserved built-in that a container
+ * references but never materializes as a collection record (a reserved built-in
+ * trigger like "All Pages", or an underscore-prefixed built-in variable like
+ * `_event`). Absent on every record-backed node.
+ */
+export interface GraphNodeBuiltIn {
+  /** Which built-in family this synthetic node stands in for. */
+  readonly of: "trigger" | "variable";
+  /** Human label (e.g. "All Pages", "Initialization", or the `_event` name). */
+  readonly label: string;
+  /** True when the exact built-in is recognized (vs a generic reserved-range id). */
+  readonly known: boolean;
+}
+
+/** One graph node — one per input record, or a synthetic built-in (see `builtIn`). */
+export interface GraphNode {
+  /** Stable, unique key: `${kind}:${id ?? '#'+index}` (record) or `builtIn*:...` (synthetic). */
+  readonly key: string;
+  readonly kind: GtmObjectKind;
+  readonly id: string | null;
+  readonly name: string | null;
+  readonly type: string | null;
+  /** The complete inert record this node was built from (empty for synthetic built-ins). */
+  readonly record: GtmInertRecord;
+  /** Present only on synthetic built-in nodes; absent on record-backed nodes. */
+  readonly builtIn?: GraphNodeBuiltIn;
+}
+
+/** One resolved dependency edge between two node keys. */
+export interface GraphEdge {
+  /** Source node key. */
+  readonly from: string;
+  /** Target node key. */
+  readonly to: string;
+  readonly kind: GtmEdgeKind;
+  /** The raw reference token that produced the edge (an id, or `{{Name}}`). */
+  readonly via?: string;
+}
+
+/** A reference whose target id/name has no node — recorded, never silently dropped. */
+export interface DanglingReference {
+  /** Source node key that made the reference. */
+  readonly from: string;
+  readonly kind: GtmEdgeKind;
+  /** The unresolved id or variable name. */
+  readonly ref: string;
+}
+
+/** Complete object accounting — the reviewer checks nothing is dropped. */
+export interface GraphAccounting {
+  readonly nodeCount: number;
+  readonly perKind: Record<GtmObjectKind, number>;
+  /**
+   * Number of SYNTHETIC built-in nodes (reserved built-in triggers +
+   * underscore-prefixed built-in variables) resolved on demand — included in
+   * `nodeCount` and `perKind`, but NOT backed by an input record. The record-node
+   * invariant (`nodeCount - syntheticNodeCount === sum of the 10 collections`)
+   * still holds.
+   */
+  readonly syntheticNodeCount: number;
+  readonly edgeCount: number;
+  readonly perEdgeKind: Record<GtmEdgeKind, number>;
+  readonly danglingCount: number;
+  /** Distinct built-in variable names that were referenced (deduped, stable order). */
+  readonly builtInVariablesReferenced: string[];
+  /** True when any bound engaged (distinct-token / total token cap, or the edge cap). */
+  readonly tokensCapped: boolean;
+  /**
+   * True when the PER-STRING `{{...}}` match cap engaged on at least one
+   * scanned string (a single string carried more matches than
+   * `maxTokensPerString` allows to be consumed). Additive to `tokensCapped`
+   * — a real cap can engage here even when `tokensCapped` stays false (e.g. a
+   * single string spamming one repeated token: distinct-token count stays
+   * low, but the per-string match cap still bounds the work).
+   */
+  readonly perStringTokensCapped: boolean;
+}
+
+/** The normalized migration graph. */
+export interface MigrationGraph {
+  readonly nodes: GraphNode[];
+  readonly edges: GraphEdge[];
+  readonly danglingReferences: DanglingReference[];
+  readonly accounting: GraphAccounting;
+}
+
+/** Caps that keep graph construction bounded on adversarial input. */
+export interface GraphBounds {
+  /** Max `{{...}}` tokens recovered from a single record's `raw` bag. */
+  maxTokensPerString: number;
+  /** Max `{{...}}` tokens recovered across the whole container. */
+  maxTotalTokens: number;
+  /** Max edges; on breach the build stops adding edges (flagged in accounting). */
+  maxEdges: number;
+}
+
+export const DEFAULT_GRAPH_BOUNDS: GraphBounds = {
+  maxTokensPerString: 500,
+  maxTotalTokens: 100_000,
+  maxEdges: 500_000,
+};
+
+/** Merge a partial override over the defaults, ignoring non-finite/non-positive caps. */
+export function resolveGraphBounds(partial?: Partial<GraphBounds>): GraphBounds {
+  const out: GraphBounds = { ...DEFAULT_GRAPH_BOUNDS };
+  if (partial) {
+    for (const key of Object.keys(DEFAULT_GRAPH_BOUNDS) as (keyof GraphBounds)[]) {
+      const v = partial[key];
+      if (typeof v === "number" && Number.isFinite(v) && v > 0) out[key] = v;
+    }
+  }
+  return out;
+}
+
+/** Fixed kind order — drives deterministic node ordering and the `perKind` map. */
+const KIND_ORDER: readonly GtmObjectKind[] = [
+  "tag",
+  "trigger",
+  "variable",
+  "builtInVariable",
+  "customTemplate",
+  "folder",
+  "zone",
+  "client",
+  "gtagConfig",
+  "transformation",
+];
+
+/** Fixed edge-kind order — drives deterministic per-node edge emission. */
+const EDGE_KIND_ORDER: readonly GtmEdgeKind[] = [
+  "fires",
+  "blocks",
+  "references",
+  "parentFolder",
+  "usesTemplate",
+];
+
+function collectionFor(cv: GtmContainerVersion, kind: GtmObjectKind): readonly GtmInertRecord[] {
+  return cv[kind];
+}
+
+function nodeKey(kind: GtmObjectKind, id: string | null, index: number): string {
+  return `${kind}:${id ?? `#${index}`}`;
+}
+
+/**
+ * Build the normalized migration graph from an inert container.
+ *
+ * Pure and deterministic. NEVER executes any part of the input.
+ */
+export function buildMigrationGraph(
+  container: GtmContainer,
+  bounds?: Partial<GraphBounds>,
+): MigrationGraph {
+  const b = resolveGraphBounds(bounds);
+  const cv = container.containerVersion;
+
+  // --- 1. Nodes: exactly one per record across all 10 collections. -----------
+  const nodes: GraphNode[] = [];
+  const perKind = Object.create(null) as Record<GtmObjectKind, number>;
+
+  // Per-kind indexes. Maps (NOT object literals) so attacker-controlled ids/names
+  // can never collide with prototype keys.
+  const idIndex = new Map<GtmObjectKind, Map<string, GraphNode>>();
+  const nameIndex = new Map<GtmObjectKind, Map<string, GraphNode>>();
+  // customTemplate resolves by its advertised templateId (== a tag/variable `cvt_*` type).
+  const templateIdIndex = new Map<string, GraphNode>();
+
+  for (const kind of KIND_ORDER) {
+    idIndex.set(kind, new Map<string, GraphNode>());
+    nameIndex.set(kind, new Map<string, GraphNode>());
+    const records = collectionFor(cv, kind);
+    perKind[kind] = records.length;
+    for (let i = 0; i < records.length; i += 1) {
+      const record = records[i];
+      if (record === undefined) continue; // defensive; arrays are dense
+      const node: GraphNode = {
+        key: nodeKey(kind, record.id, i),
+        kind,
+        id: record.id,
+        name: record.name,
+        type: record.type,
+        record,
+      };
+      nodes.push(node);
+      // First writer wins on duplicate id/name — deterministic and stable.
+      if (record.id !== null && !idIndex.get(kind)!.has(record.id)) {
+        idIndex.get(kind)!.set(record.id, node);
+      }
+      if (record.name !== null && !nameIndex.get(kind)!.has(record.name)) {
+        nameIndex.get(kind)!.set(record.name, node);
+      }
+      if (kind === "customTemplate") {
+        const tid = readTemplateId(record);
+        if (tid !== null && !templateIdIndex.has(tid)) templateIdIndex.set(tid, node);
+      }
+    }
+  }
+
+  // Assert-by-construction: one node per input record across the 10 collections.
+  const expectedNodeCount = KIND_ORDER.reduce((sum, kind) => sum + collectionFor(cv, kind).length, 0);
+  if (nodes.length !== expectedNodeCount) {
+    throw new Error(
+      `buildMigrationGraph invariant violated: nodeCount ${nodes.length} !== sum of collections ${expectedNodeCount}`,
+    );
+  }
+
+  // --- 2. Edges + dangling references, deterministically per node. -----------
+  const edges: GraphEdge[] = [];
+  const danglingReferences: DanglingReference[] = [];
+  const perEdgeKind = Object.create(null) as Record<GtmEdgeKind, number>;
+  for (const ek of EDGE_KIND_ORDER) perEdgeKind[ek] = 0;
+
+  const builtInSeen = new Set<string>();
+  const builtInVariablesReferenced: string[] = [];
+  let totalTokens = 0;
+  let tokensCapped = false;
+  let perStringTokensCapped = false;
+  let edgesFull = false;
+
+  const triggerIds = idIndex.get("trigger")!;
+  const folderIds = idIndex.get("folder")!;
+  const variableNames = nameIndex.get("variable")!;
+  const builtInNames = nameIndex.get("builtInVariable")!;
+
+  // --- Synthetic built-in nodes (reserved triggers + `_`-prefixed variables). --
+  // GTM references built-ins it never materializes as records; resolve each to a
+  // stable synthetic node (created once, on first reference) instead of dangling.
+  // Only RECORD nodes were built above, so iterate that fixed prefix — appended
+  // synthetic nodes must never be walked as edge SOURCES.
+  const recordNodeCount = nodes.length;
+  const EMPTY_RAW: Record<string, unknown> = Object.freeze(Object.create(null));
+  let syntheticNodeCount = 0;
+  const builtInTriggerNodes = new Map<string, GraphNode>();
+  const builtInVariableNodes = new Map<string, GraphNode>();
+
+  const getOrCreateBuiltInTrigger = (id: string, info: BuiltInTriggerInfo): GraphNode => {
+    const key = `builtInTrigger:${id}`;
+    const existing = builtInTriggerNodes.get(key);
+    if (existing) return existing;
+    const node: GraphNode = {
+      key,
+      kind: "trigger",
+      id,
+      name: info.label,
+      type: null,
+      record: { id, name: info.label, type: null, raw: EMPTY_RAW },
+      builtIn: { of: "trigger", label: info.label, known: info.known },
+    };
+    builtInTriggerNodes.set(key, node);
+    nodes.push(node);
+    perKind["trigger"] += 1;
+    syntheticNodeCount += 1;
+    return node;
+  };
+
+  const getOrCreateBuiltInVariable = (name: string): GraphNode => {
+    const key = `builtInVariable:${name}`;
+    const existing = builtInVariableNodes.get(key);
+    if (existing) return existing;
+    const node: GraphNode = {
+      key,
+      kind: "builtInVariable",
+      id: null,
+      name,
+      type: null,
+      record: { id: null, name, type: null, raw: EMPTY_RAW },
+      builtIn: { of: "variable", label: name, known: true },
+    };
+    builtInVariableNodes.set(key, node);
+    nodes.push(node);
+    perKind["builtInVariable"] += 1;
+    syntheticNodeCount += 1;
+    return node;
+  };
+
+  /** Resolve a firing/blocking trigger id to a real OR synthetic built-in node. */
+  const resolveTriggerTarget = (id: string): GraphNode | null => {
+    const real = triggerIds.get(id);
+    if (real) return real;
+    const info = resolveBuiltInTrigger(id);
+    return info ? getOrCreateBuiltInTrigger(id, info) : null;
+  };
+
+  /** Append an edge, respecting the edge cap. Returns false once the cap is hit. */
+  const pushEdge = (from: string, to: string, kind: GtmEdgeKind, via: string): boolean => {
+    if (edges.length >= b.maxEdges) {
+      if (!edgesFull) {
+        edgesFull = true;
+        tokensCapped = true; // a graph bound engaged — surfaced in accounting
+      }
+      return false;
+    }
+    edges.push({ from, to, kind, via });
+    perEdgeKind[kind] += 1;
+    return true;
+  };
+
+  const pushDangling = (from: string, kind: GtmEdgeKind, ref: string): void => {
+    danglingReferences.push({ from, kind, ref });
+  };
+
+  for (let ni = 0; ni < recordNodeCount; ni += 1) {
+    const node = nodes[ni]!;
+    if (edgesFull) break;
+    const raw = node.record.raw;
+
+    // 2a. fires: tag → trigger (raw.firingTriggerId[]) — reserved ids → built-in.
+    for (const tid of readTriggerIds(raw, "firingTriggerId")) {
+      const target = resolveTriggerTarget(tid);
+      if (target) {
+        if (!pushEdge(node.key, target.key, "fires", tid)) break;
+      } else {
+        pushDangling(node.key, "fires", tid);
+      }
+    }
+    if (edgesFull) break;
+
+    // 2b. blocks: tag → trigger (raw.blockingTriggerId[]) — reserved ids → built-in.
+    for (const tid of readTriggerIds(raw, "blockingTriggerId")) {
+      const target = resolveTriggerTarget(tid);
+      if (target) {
+        if (!pushEdge(node.key, target.key, "blocks", tid)) break;
+      } else {
+        pushDangling(node.key, "blocks", tid);
+      }
+    }
+    if (edgesFull) break;
+
+    // 2c. references: any object → variable / builtInVariable, from {{Name}} tokens.
+    // Per-record cap, plus a running total-token budget across the container.
+    let perRecordCap = b.maxTokensPerString;
+    if (totalTokens >= b.maxTotalTokens) {
+      tokensCapped = true;
+      perRecordCap = 0;
+    } else {
+      const remaining = b.maxTotalTokens - totalTokens;
+      if (remaining < perRecordCap) perRecordCap = remaining;
+    }
+    if (perRecordCap > 0) {
+      const { tokens, perStringCapped } = extractVariableTokensReport(raw, perRecordCap);
+      totalTokens += tokens.length;
+      if (tokens.length >= perRecordCap) tokensCapped = true;
+      if (perStringCapped) perStringTokensCapped = true;
+      // De-dupe reference edges per (from → target) within this record.
+      const linked = new Set<string>();
+      for (const name of tokens) {
+        const via = `{{${name}}}`;
+        const variableNode = variableNames.get(name);
+        const builtInNode = builtInNames.get(name);
+        // Underscore-prefixed names are GTM built-in variables the container never
+        // materializes (e.g. `_event`) — resolve to a synthetic node, not dangling.
+        const target =
+          variableNode ?? builtInNode ?? (isBuiltInVariableRef(name) ? getOrCreateBuiltInVariable(name) : undefined);
+        if (target) {
+          if (target !== variableNode && !builtInSeen.has(name)) {
+            builtInSeen.add(name);
+            builtInVariablesReferenced.push(name);
+          }
+          if (!linked.has(target.key)) {
+            linked.add(target.key);
+            if (!pushEdge(node.key, target.key, "references", via)) break;
+          }
+        } else {
+          pushDangling(node.key, "references", name);
+        }
+      }
+    }
+    if (edgesFull) break;
+
+    // 2d. parentFolder: any object → folder (raw.parentFolderId)
+    const parentFolderId = readParentFolderId(raw);
+    if (parentFolderId !== null) {
+      const target = folderIds.get(parentFolderId);
+      if (target) {
+        if (!pushEdge(node.key, target.key, "parentFolder", parentFolderId)) break;
+      } else {
+        pushDangling(node.key, "parentFolder", parentFolderId);
+      }
+    }
+    if (edgesFull) break;
+
+    // 2e. usesTemplate: tag / variable → customTemplate when its type is a cvt_* type.
+    // A real GTM tag/variable's `type` is the FULL `cvt_<containerId>_<n>` token, while
+    // the customTemplate it points at usually advertises just the bare `<n>` as its
+    // `templateId` — so resolve by the full token first, then by its trailing `<n>`
+    // segment (see `readTemplateTrailingId`). Either match is a valid, non-dangling link.
+    if (node.kind === "tag" || node.kind === "variable") {
+      const templateRef = readTemplateTypeRef(node.record);
+      if (templateRef !== null) {
+        const trailingId = readTemplateTrailingId(templateRef);
+        const target =
+          templateIdIndex.get(templateRef) ??
+          (trailingId !== null ? templateIdIndex.get(trailingId) : undefined);
+        if (target) {
+          if (!pushEdge(node.key, target.key, "usesTemplate", templateRef)) break;
+        } else {
+          pushDangling(node.key, "usesTemplate", templateRef);
+        }
+      }
+    }
+  }
+
+  const accounting: GraphAccounting = {
+    nodeCount: nodes.length,
+    perKind,
+    syntheticNodeCount,
+    edgeCount: edges.length,
+    perEdgeKind,
+    danglingCount: danglingReferences.length,
+    builtInVariablesReferenced,
+    tokensCapped,
+    perStringTokensCapped,
+  };
+
+  return { nodes, edges, danglingReferences, accounting };
+}

package/packages/public-runtime/src/gtm-migration/index.ts

@@ -0,0 +1,95 @@
+/**
+ * @tot/public-runtime — GTM container-export migration: the SAFE, non-executing
+ * parser + inert typed model + complete object accounting.
+ *
+ * This subtree turns an untrusted GTM (Google Tag Manager) container export into
+ * inert typed DATA and a normalized reference/dependency graph. It NEVER executes,
+ * evaluates, or interprets any part of the export (see `parse.ts` for the full
+ * security contract). It does NOT classify tags into dispositions or render any UI
+ * — those are separate downstream units that consume this module's output.
+ */
+
+export { parseGtmExport, DEFAULT_BOUNDS } from "./parse.js";
+export { enforceBounds, resolveBounds } from "./bounds.js";
+export type { ParseBounds, GtmViolation } from "./bounds.js";
+export type {
+  GtmContainer,
+  GtmContainerVersion,
+  GtmInertRecord,
+  GtmParseAccounting,
+  GtmParseResult,
+} from "./types.js";
+
+// Reference-extraction helpers (pure, non-executing, string-scanning only).
+export {
+  extractVariableTokens,
+  extractVariableTokensReport,
+  readTriggerIds,
+  readParentFolderId,
+  isCustomTemplateType,
+  readTemplateTypeRef,
+  readTemplateTrailingId,
+  readTemplateId,
+  resolveBuiltInTrigger,
+  isBuiltInVariableRef,
+  GTM_RESERVED_TRIGGER_MIN,
+  GTM_RESERVED_TRIGGER_MAX,
+} from "./references.js";
+export type { ExtractVariableTokensResult, BuiltInTriggerInfo } from "./references.js";
+
+// Normalized migration graph: nodes + resolved edges + complete accounting.
+export { buildMigrationGraph, resolveGraphBounds, DEFAULT_GRAPH_BOUNDS } from "./graph.js";
+export type {
+  GtmObjectKind,
+  GtmEdgeKind,
+  GraphNode,
+  GraphNodeBuiltIn,
+  GraphEdge,
+  DanglingReference,
+  GraphAccounting,
+  MigrationGraph,
+  GraphBounds,
+} from "./graph.js";
+
+// Migration disposition (classification) engine: one disposition per object +
+// dangling reference, with complete accounting.
+export { classifyMigration } from "./dispositions.js";
+export type {
+  DispositionClass,
+  ObjectDisposition,
+  DanglingDisposition,
+  DispositionReport,
+} from "./dispositions.js";
+
+// The extensible disposition ruleset (GTM-type → disposition knowledge). Exported
+// so the report UI can render the reason legend and the classification rubric.
+export {
+  classifyNode,
+  isCodeBearing,
+  verdict,
+  dispositionForReason,
+  REASON_CATALOG,
+  TAG_TYPE_RULES,
+  VARIABLE_TYPE_RULES,
+  TRIGGER_TYPE_RULES,
+  KIND_RULES,
+} from "./disposition-rules.js";
+export type { ReasonCode, DispositionVerdict, NodeRuleContext } from "./disposition-rules.js";
+
+// The disabled MigrationDraft v1 generator: map a classified migration into an
+// inert, always-disabled managed-analytics draft + complete unresolved inventory.
+export {
+  generateDisabledMigrationDraft,
+  WS1_GOOGLE_MEASUREMENT_ADAPTER_ID,
+  WS1_GOOGLE_MEASUREMENT_DESTINATION_KEY,
+  NO_ADAPTER_SELECTED_ID,
+} from "./draft-generator.js";
+export type {
+  GenerateDisabledMigrationDraftArgs,
+  DisabledDraftResult,
+  MappedConcept,
+  MappedConceptRole,
+  UnresolvedInventoryItem,
+  DraftProvenanceInput,
+  DraftProvenanceRecord,
+} from "./draft-generator.js";