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

package/packages/public-runtime/src/gtm-migration/draft-generator.ts

@@ -0,0 +1,400 @@
+/**
+ * The DISABLED MigrationDraft v1 generator: map a CLASSIFIED GTM migration result
+ * into an inert, always-disabled managed-analytics migration draft plus a complete
+ * unresolved inventory — a pure, deterministic DATA transform with no I/O.
+ *
+ * SECURITY / PRODUCT CONTRACT (a reviewer WILL reject violations):
+ *   - Consumes ONLY the pinned PUBLIC managed-analytics v1 contract
+ *     (`../integration/managed-analytics-api-v1.js`). It never reimplements those
+ *     schemas, never imports a private module, never touches a database, config,
+ *     tenant, or materializer, and never calls a live API.
+ *   - The produced `MigrationDraftV1` is ALWAYS disabled and inert: `status:"draft"`,
+ *     `enabled:false`, `publishes:false`. It carries NO credentials/secrets, NO
+ *     executable code/markup/selectors/loaders, NO wildcard origins, NO legacy UA
+ *     ids, NO GTM container ids, and NO live/publish/activate authority — only an
+ *     approved adapter selection, primitive config values, and redacted finding
+ *     codes, exactly as the pinned contract permits. Every produced draft is run
+ *     THROUGH the pinned `validateMigrationDraftV1` validator; an invalid draft is a
+ *     hard error and is NEVER emitted as valid.
+ *   - Pure and deterministic: no I/O, no `eval`, no globals, no `Date.now` (the
+ *     `generatedAt` timestamp is supplied by the caller). Same input → same draft.
+ *
+ * MAPPING BOUNDARY: only `automatically-portable` objects convert into the draft's
+ * accounting; the confidently-supported GA4 objects among them (GA4 config
+ * `googtag`/`gaawc`, GA4 events `gaawe`) drive the selected managed-analytics
+ * adapter and its primitive configuration. Every object in the other four
+ * disposition classes (`portable-with-review`, `requires-redesign`,
+ * `unsupported-by-design`, `retire`) lands in the unresolved inventory so nothing
+ * is dropped and a human sees exactly what did NOT convert and why.
+ */
+
+import type { GtmContainer } from "./types.js";
+import type { MigrationGraph, GtmObjectKind } from "./graph.js";
+import type { DispositionReport, ObjectDisposition, DispositionClass } from "./dispositions.js";
+import {
+  validateMigrationDraftV1,
+  MANAGED_ANALYTICS_SCHEMA_VERSION,
+  validateManagedAnalyticsSafePayload,
+  type MigrationDraftV1,
+  type AdapterConfigValue,
+  type AdapterDefinition,
+  type OpaquePublicId,
+  type MigrationFindingCode,
+} from "../integration/managed-analytics-api-v1.js";
+import type { ContractResult } from "../integration/result.js";
+import { digestValue } from "../integration/digest.js";
+
+/**
+ * The canonical WS1 shared-catalog adapter id that confidently-supported GA4
+ * objects map to (the Google Measurement destination). WS1 is canonical — this is
+ * exactly the vocabulary WS1's pinned `validateCreateIntegrationInstallRequest`
+ * accepts. A stable opaque handle: no secret, no container id, no execution
+ * authority. Used as the DEFAULT when no adapter catalog is supplied, so the
+ * emitted vocabulary always matches WS1.
+ */
+export const WS1_GOOGLE_MEASUREMENT_ADAPTER_ID: OpaquePublicId = "platform.google-measurement";
+
+/**
+ * The canonical WS1 config field key the google-measurement adapter declares for
+ * its destination id. Used as the DEFAULT config key when no catalog is supplied.
+ */
+export const WS1_GOOGLE_MEASUREMENT_DESTINATION_KEY = "destinationId";
+
+/** The opaque adapter handle used when a container has no supported GA4 concept. */
+export const NO_ADAPTER_SELECTED_ID: OpaquePublicId = "none-selected";
+
+/** The consent purpose GA4 analytics maps to by default (GA4 consent-mode key). */
+const GA4_DEFAULT_CONSENT_PURPOSE = "analytics_storage";
+
+/** GTM tag `type` codes that are a GA4 CONFIG object. */
+const GA4_CONFIG_TYPES = new Set(["googtag", "gaawc"]);
+/** GTM tag `type` code that is a GA4 EVENT object. */
+const GA4_EVENT_TYPE = "gaawe";
+
+/** A literal Google measurement destination id (e.g. `G-ABCDE12345`). Never a secret. */
+const GA4_DESTINATION_ID_VALUE = /^G-[A-Z0-9]{4,}$/;
+
+/** The role a mapped object plays in the produced draft. */
+export type MappedConceptRole = "ga4-config" | "ga4-event" | "native-portable";
+
+/** One `automatically-portable` object accounted for by the draft. */
+export interface MappedConcept {
+  readonly nodeKey: string;
+  readonly kind: GtmObjectKind;
+  readonly id: string | null;
+  readonly name: string | null;
+  readonly type: string | null;
+  readonly reasonCode: string;
+  readonly role: MappedConceptRole;
+  /** Clean semantic event name derived from a GA4 event tag; null when unavailable or templated. */
+  readonly semanticEventName: string | null;
+  /** Consent purposes derived for a GA4 object (empty for non-GA4 native-portable objects). */
+  readonly consentPurposes: string[];
+}
+
+/** One object that did NOT convert — the complete unresolved/unsupported inventory. */
+export interface UnresolvedInventoryItem {
+  readonly nodeKey: string;
+  readonly kind: GtmObjectKind;
+  readonly id: string | null;
+  readonly name: string | null;
+  readonly type: string | null;
+  readonly disposition: DispositionClass;
+  readonly reasonCode: string;
+  readonly explanation: string;
+}
+
+/** Caller-supplied provenance — the timestamp and opaque ids the draft needs (no `Date.now`). */
+export interface DraftProvenanceInput {
+  /** Opaque id for the produced draft (an OpaquePublicId). */
+  readonly draftId: OpaquePublicId;
+  /** ISO-8601 timestamp used for the draft's `createdAt`/`updatedAt` and the digest record. */
+  readonly generatedAt: string;
+  /** CAS token for the draft; defaults to 0. */
+  readonly revision?: number;
+}
+
+/** The provenance/digest record attached to the result. */
+export interface DraftProvenanceRecord {
+  readonly sourceContainerPublicId: string | null;
+  readonly sourceContainerId: string | null;
+  readonly generatedAt: string;
+  readonly objectCounts: {
+    readonly totalObjects: number;
+    readonly mapped: number;
+    readonly unresolved: number;
+    readonly dangling: number;
+    readonly byClass: Record<DispositionClass, number>;
+  };
+  /** Content digest (FNV-1a-128) of the produced draft. */
+  readonly draftDigest: string;
+}
+
+/** The complete result of generating a disabled migration draft. */
+export interface DisabledDraftResult {
+  readonly draft: MigrationDraftV1;
+  readonly mappedConcepts: MappedConcept[];
+  readonly unresolvedInventory: UnresolvedInventoryItem[];
+  readonly provenance: DraftProvenanceRecord;
+  /** The result of running the produced draft through the pinned validator (always `ok` when returned). */
+  readonly validation: ContractResult<MigrationDraftV1>;
+}
+
+export interface GenerateDisabledMigrationDraftArgs {
+  readonly container: GtmContainer;
+  readonly graph: MigrationGraph;
+  readonly disposition: DispositionReport;
+  readonly provenance: DraftProvenanceInput;
+  /**
+   * The shared WS1 adapter catalog, when available. When present, the GA4 mapping
+   * SELECTS the canonical google-measurement adapter FROM it (matched by the
+   * canonical adapter id) and keys the produced config off THAT adapter's declared
+   * config fields — so the draft speaks WS1's exact vocabulary. A catalog that is
+   * present but lacks the adapter is a safe "no adapter selected" outcome (never
+   * invent one). When ABSENT, the canonical WS1 constants are used as the default,
+   * so the emitted vocabulary still matches WS1.
+   */
+  readonly adapterCatalog?: readonly AdapterDefinition[];
+}
+
+/** Select the canonical google-measurement adapter from a WS1 catalog, or undefined. */
+function selectGoogleMeasurementAdapter(
+  catalog: readonly AdapterDefinition[] | undefined,
+): AdapterDefinition | undefined {
+  return catalog?.find((a) => a.adapterId === WS1_GOOGLE_MEASUREMENT_ADAPTER_ID);
+}
+
+/** The config field key an adapter declares for its Google measurement destination id. */
+function destinationKeyFor(adapter: AdapterDefinition): string {
+  const declared =
+    adapter.configuration.find((f) => f.key === WS1_GOOGLE_MEASUREMENT_DESTINATION_KEY) ??
+    adapter.configuration.find((f) => f.kind === "string");
+  return declared?.key ?? WS1_GOOGLE_MEASUREMENT_DESTINATION_KEY;
+}
+
+function normalizeType(type: string | null): string {
+  return typeof type === "string" ? type.trim().toLowerCase() : "";
+}
+
+/** Read a null-prototype-safe own value off a `raw` bag (missing → undefined). */
+function own(raw: Record<string, unknown>, key: string): unknown {
+  return Object.prototype.hasOwnProperty.call(raw, key) ? raw[key] : undefined;
+}
+
+/** The parameter list off an inert GTM record, as `{ key, value }` string pairs. */
+function readParameters(raw: Record<string, unknown>): Array<{ key: string; value: string }> {
+  const params = own(raw, "parameter");
+  if (!Array.isArray(params)) return [];
+  const out: Array<{ key: string; value: string }> = [];
+  for (const p of params) {
+    if (p === null || typeof p !== "object") continue;
+    const key = (p as Record<string, unknown>)["key"];
+    const value = (p as Record<string, unknown>)["value"];
+    if (typeof key === "string" && typeof value === "string") out.push({ key, value });
+  }
+  return out;
+}
+
+/** True only when a value is safe to carry verbatim into the draft (per the pinned validator). */
+function isSafeToCarry(value: string): boolean {
+  return validateManagedAnalyticsSafePayload(value).ok;
+}
+
+/**
+ * Extract a LITERAL Google measurement destination id from a config record, or
+ * null. Scans the record's parameter VALUES for a literal `G-…` destination id
+ * (matched by value shape, independent of GTM's own key names). A templated
+ * `{{...}}` value or any secret/PII/executable-shaped value is deliberately
+ * dropped (never carried) — the reviewed install path resolves the real value
+ * later.
+ */
+function extractDestinationId(raw: Record<string, unknown>): string | null {
+  for (const { value } of readParameters(raw)) {
+    const trimmed = value.trim();
+    if (GA4_DESTINATION_ID_VALUE.test(trimmed) && isSafeToCarry(trimmed)) return trimmed;
+  }
+  return null;
+}
+
+/** Derive a clean semantic event name from a GA4 event tag; null when absent or templated. */
+function deriveSemanticEventName(raw: Record<string, unknown>): string | null {
+  for (const { key, value } of readParameters(raw)) {
+    if (key !== "eventName") continue;
+    const trimmed = value.trim();
+    // Skip dynamic template expressions ({{...}}); keep only a clean literal name.
+    if (trimmed.length === 0 || trimmed.includes("{{") || trimmed.includes("}}")) return null;
+    if (!isSafeToCarry(trimmed)) return null;
+    return trimmed;
+  }
+  return null;
+}
+
+/** Derive GA4 consent purposes: the GA4 default, plus any explicit, safe `consentType` values. */
+function deriveConsentPurposes(raw: Record<string, unknown>): string[] {
+  const purposes = new Set<string>([GA4_DEFAULT_CONSENT_PURPOSE]);
+  const consent = own(raw, "consentSettings");
+  if (consent !== null && typeof consent === "object") {
+    const consentType = (consent as Record<string, unknown>)["consentType"];
+    if (Array.isArray(consentType)) {
+      for (const entry of consentType) {
+        if (typeof entry === "string" && entry.length > 0 && isSafeToCarry(entry)) purposes.add(entry);
+      }
+    }
+  }
+  // Deterministic order: the GA4 default first, then any extras in sorted order.
+  const extras = [...purposes].filter((p) => p !== GA4_DEFAULT_CONSENT_PURPOSE).sort();
+  return [GA4_DEFAULT_CONSENT_PURPOSE, ...extras];
+}
+
+function roleFor(disp: ObjectDisposition): MappedConceptRole {
+  if (disp.kind === "tag" && disp.reasonCode === "ga4-native") {
+    const type = normalizeType(disp.type);
+    if (GA4_CONFIG_TYPES.has(type)) return "ga4-config";
+    if (type === GA4_EVENT_TYPE) return "ga4-event";
+  }
+  return "native-portable";
+}
+
+/**
+ * Generate a DISABLED, inert MigrationDraft v1 from a classified GTM migration.
+ *
+ * Pure and deterministic. Maps only confidently-supported GA4 objects into the
+ * selected managed-analytics adapter + primitive config; everything not
+ * automatically-portable lands in the unresolved inventory. The produced draft is
+ * validated against the pinned schema — an invalid draft throws (never emitted).
+ */
+export function generateDisabledMigrationDraft(
+  args: GenerateDisabledMigrationDraftArgs,
+): DisabledDraftResult {
+  const { container, graph, disposition, provenance } = args;
+
+  // Index graph nodes by key so each classified object can read its inert `raw` bag.
+  const nodeByKey = new Map<string, (typeof graph.nodes)[number]>();
+  for (const node of graph.nodes) nodeByKey.set(node.key, node);
+
+  const mappedConcepts: MappedConcept[] = [];
+  const unresolvedInventory: UnresolvedInventoryItem[] = [];
+
+  for (const obj of disposition.objects) {
+    if (obj.disposition === "automatically-portable") {
+      const role = roleFor(obj);
+      const raw = nodeByKey.get(obj.nodeKey)?.record.raw ?? {};
+      const isGa4 = role === "ga4-config" || role === "ga4-event";
+      mappedConcepts.push({
+        nodeKey: obj.nodeKey,
+        kind: obj.kind,
+        id: obj.id,
+        name: obj.name,
+        type: obj.type,
+        reasonCode: obj.reasonCode,
+        role,
+        semanticEventName: role === "ga4-event" ? deriveSemanticEventName(raw) : null,
+        consentPurposes: isGa4 ? deriveConsentPurposes(raw) : [],
+      });
+    } else {
+      unresolvedInventory.push({
+        nodeKey: obj.nodeKey,
+        kind: obj.kind,
+        id: obj.id,
+        name: obj.name,
+        type: obj.type,
+        disposition: obj.disposition,
+        reasonCode: obj.reasonCode,
+        explanation: obj.explanation,
+      });
+    }
+  }
+
+  // --- Adapter selection + primitive config from the mapped GA4 objects. -------
+  const ga4Configs = mappedConcepts.filter((c) => c.role === "ga4-config");
+  const ga4Events = mappedConcepts.filter((c) => c.role === "ga4-event");
+  const hasGa4 = ga4Configs.length > 0 || ga4Events.length > 0;
+
+  // Select the canonical google-measurement adapter. With a catalog, adopt ITS
+  // exact adapter id + declared destination config key. Without one, fall back to
+  // the canonical WS1 constants so the default vocabulary still matches WS1. A
+  // catalog that is present but lacks the adapter is a safe "no adapter selected"
+  // outcome — never invent one.
+  const catalogAdapter = selectGoogleMeasurementAdapter(args.adapterCatalog);
+  const catalogProvided = args.adapterCatalog !== undefined;
+
+  let proposedAdapterId: OpaquePublicId;
+  let destinationKey: string;
+  if (!hasGa4 || (catalogProvided && catalogAdapter === undefined)) {
+    proposedAdapterId = NO_ADAPTER_SELECTED_ID;
+    destinationKey = WS1_GOOGLE_MEASUREMENT_DESTINATION_KEY;
+  } else if (catalogAdapter !== undefined) {
+    proposedAdapterId = catalogAdapter.adapterId;
+    destinationKey = destinationKeyFor(catalogAdapter);
+  } else {
+    proposedAdapterId = WS1_GOOGLE_MEASUREMENT_ADAPTER_ID;
+    destinationKey = WS1_GOOGLE_MEASUREMENT_DESTINATION_KEY;
+  }
+  const adapterSelected = proposedAdapterId !== NO_ADAPTER_SELECTED_ID;
+
+  const proposedConfiguration: Record<string, AdapterConfigValue> = {};
+  let destinationId: string | null = null;
+  if (adapterSelected) {
+    for (const config of ga4Configs) {
+      const raw = nodeByKey.get(config.nodeKey)?.record.raw ?? {};
+      const found = extractDestinationId(raw);
+      if (found !== null) {
+        destinationId = found;
+        break; // deterministic: first config carrying a literal id wins.
+      }
+    }
+    if (destinationId !== null) proposedConfiguration[destinationKey] = destinationId;
+  }
+
+  // --- Redacted finding codes (no source text; stable, sorted-by-construction). -
+  const findings: MigrationFindingCode[] = [];
+  if (ga4Configs.length > 0) findings.push("ga4-config-detected");
+  if (ga4Events.length > 0) findings.push("ga4-events-detected");
+  findings.push(destinationId !== null ? "ga4-destination-id-configured" : "ga4-destination-id-deferred");
+  if (!hasGa4) findings.push("no-automatically-portable-analytics");
+  if (unresolvedInventory.length > 0) findings.push("unresolved-objects-inventoried");
+
+  const draft: MigrationDraftV1 = {
+    schemaVersion: MANAGED_ANALYTICS_SCHEMA_VERSION,
+    draftId: provenance.draftId,
+    revision: provenance.revision ?? 0,
+    source: "approved-migration",
+    status: "draft",
+    enabled: false,
+    publishes: false,
+    proposedAdapterId,
+    proposedConfiguration,
+    findings,
+    createdAt: provenance.generatedAt,
+    updatedAt: provenance.generatedAt,
+  };
+
+  // --- Validate the produced draft through the PINNED validator. ---------------
+  // A draft that fails the pinned schema is a generator bug: throw loudly, never
+  // emit it as valid.
+  const validation = validateMigrationDraftV1(draft);
+  if (!validation.ok) {
+    throw new Error(
+      `generateDisabledMigrationDraft produced an invalid MigrationDraft v1: ${JSON.stringify(
+        validation.violations,
+      )}`,
+    );
+  }
+
+  const cv = container.containerVersion;
+  const provenanceRecord: DraftProvenanceRecord = {
+    sourceContainerPublicId: cv.publicId,
+    sourceContainerId: cv.containerId,
+    generatedAt: provenance.generatedAt,
+    objectCounts: {
+      totalObjects: disposition.objects.length,
+      mapped: mappedConcepts.length,
+      unresolved: unresolvedInventory.length,
+      dangling: disposition.dangling.length,
+      byClass: disposition.summary.byClass,
+    },
+    draftDigest: digestValue(draft),
+  };
+
+  return { draft, mappedConcepts, unresolvedInventory, provenance: provenanceRecord, validation };
+}