@nextcommerce/campaigns-os 1.43.2 → 1.47.0

package/src/page-kit-sync.mjs

@@ -14,6 +14,7 @@
 // every other file are left as they are. This module is pure: the CLI does
 // the reading, the writing, and the printing.
 import {
+  isAuthoritativeEmptyStoreProfileValue,
   isDemoResidue,
   normalizeStoreProfileValue,
   PAGE_KIT_STORE_PROFILE_FIELDS,
@@ -25,17 +26,23 @@ export const PAGE_KIT_SYNC_FIELDS = Object.freeze([...PAGE_KIT_STORE_PROFILE_FIE
 
 // The field-by-field plan: what the entry holds, what the spec says, and
 // whether a write is owed. `changes` are the fields whose value will move,
-// `unchanged` already match, `not_in_spec` are governed fields the spec does
-// not carry (left as they are; doctor's `target_only` warning still applies),
-// and `not_synced` are fields the target cannot be made authoritative for: an
-// invalid or conflicting spec SDK pin, a spec value of the wrong type or
-// shape (or the demo value itself), or starter demo residue in a field the
-// spec does not carry. Absent, null and blank spec values are "not carried".
+// `unchanged` already match, `not_in_spec` are governed fields left as they
+// are because the spec does not carry them or because its "" was not applied
+// (doctor's `target_only` warning still applies), and `not_synced` are fields
+// the target cannot be made authoritative for: an invalid or conflicting spec
+// SDK pin, a spec value of the wrong type or shape (or the demo value itself),
+// or starter demo residue in a field the spec does not carry. Absent and null
+// spec values are "not carried"; an explicit empty (or whitespace-only) string
+// blanks the starter demo value and otherwise leaves the target as it is.
+// `spec_empty_not_applied` names that last case, the not_in_spec fields the
+// spec sets to "" over a real, non-demo target value, which only a hand edit
+// removes.
 export function planPageKitSync({ spec, entry, waivedGates = [] } = {}) {
   const target = entry && typeof entry === "object" && !Array.isArray(entry) ? entry : {};
   const changes = [];
   const unchanged = [];
   const notInSpec = [];
+  const specEmptyNotApplied = [];
   const notSynced = [];
   // A gate under an ACTIVE named-human waiver recorded a human accepting the
   // target's current values; sync must not silently reverse that decision.
@@ -61,8 +68,15 @@ export function planPageKitSync({ spec, entry, waivedGates = [] } = {}) {
   for (const field of PAGE_KIT_STORE_PROFILE_FIELDS) {
     const raw = spec?.campaign?.[field];
     const current = Object.hasOwn(target, field) ? target[field] : undefined;
-    const carried = raw !== undefined && raw !== null && !(typeof raw === "string" && !raw.trim());
-    if (!carried) {
+    // An explicit empty value blanks only the starter demo value, and confirms
+    // a target that already reads as empty. Any other target value is left as
+    // it is, as for a field the spec does not carry (doctor's target_only
+    // warning): Maps saved "" for every cleared store field before "" meant
+    // empty, so it never wipes a value someone entered.
+    const authoritativeEmpty = isAuthoritativeEmptyStoreProfileValue(field, raw);
+    const targetBlankOrDemo = current === undefined || current === null
+      || (typeof current === "string" && (!normalizeStoreProfileValue(current) || isDemoResidue(field, normalizeStoreProfileValue(current))));
+    if (raw === undefined || raw === null || (authoritativeEmpty && !targetBlankOrDemo)) {
       // Starter demo residue in a field the spec does not carry is the one
       // state sync cannot end: doctor blocks on it without a waiver and there
       // is no spec value to write over it. Say so instead of reporting a
@@ -75,13 +89,16 @@ export function planPageKitSync({ spec, entry, waivedGates = [] } = {}) {
         });
       } else {
         notInSpec.push(field);
+        if (authoritativeEmpty) specEmptyNotApplied.push(field);
       }
       continue;
     }
     // A carried value the target cannot be made authoritative for: the wrong
     // type (doctor's spec_invalid_type), the demo value itself, or a shape a
     // template would put into an href unescaped.
-    const problem = typeof raw !== "string" ? "spec_invalid_type" : storeProfileSpecValueProblem(field, raw);
+    // An explicit empty value reaching here is written as "" over the starter
+    // demo value.
+    const problem = typeof raw !== "string" ? "spec_invalid_type" : authoritativeEmpty ? null : storeProfileSpecValueProblem(field, raw);
     if (problem) {
       notSynced.push({ field, reason: problem, detail: NOT_SYNCED_DETAIL[problem](field, raw) });
       continue;
@@ -91,9 +108,11 @@ export function planPageKitSync({ spec, entry, waivedGates = [] } = {}) {
     const row = { field, before, after, source: `campaign.${field}` };
     // The gate compares normalized forms, so a target that differs only in
     // surrounding whitespace or Unicode normalization already passes; a
-    // rewrite would report a change doctor never saw.
+    // rewrite would report a change doctor never saw. For the same reason an
+    // absent or null target already agrees with an explicit empty value.
     const alreadyMatches = before === after
-      || (typeof before === "string" && normalizeStoreProfileValue(before) === after);
+      || (typeof before === "string" && normalizeStoreProfileValue(before) === after)
+      || (authoritativeEmpty && (before === undefined || before === null));
     if (alreadyMatches) unchanged.push(row);
     else if (storeProfileWaiver) notSynced.push({ field, reason: "waived", detail: waivedDetail(field, storeProfileWaiver, "page_kit.store_profile") });
     else changes.push(row);
@@ -130,7 +149,7 @@ export function planPageKitSync({ spec, entry, waivedGates = [] } = {}) {
     });
   }
 
-  return { changes, unchanged, not_in_spec: notInSpec, not_synced: notSynced };
+  return { changes, unchanged, not_in_spec: notInSpec, spec_empty_not_applied: specEmptyNotApplied, not_synced: notSynced };
 }
 
 // Apply a plan to the parsed campaigns.json document. Mutates ONLY the

package/src/progress-node.mjs

@@ -11,6 +11,8 @@ import {resolveConsent,CANONICAL_REMIT_SCOPE,normalizeConsentScope,announceDefau
 import {boundedResponseText,isLoopbackHostname} from './remit.mjs';
 export const PROGRESS_OBSERVATION = Symbol('canonical progress observation');
 export const PROGRESS_ENDPOINT = '/api/progress';
+// A projection keeps the first PROGRESS_GATE_LIMIT continuation gates (the snapshot schema's gates maxItems).
+export const PROGRESS_GATE_LIMIT = 16;
 const accepted = (value,values,fallback='unknown')=>values.includes(value)?value:fallback;
 const hash = value=>typeof value==='string'&&/^(?:sha256:)?[0-9a-f]{64}$/i.test(value)?`sha256:${value.replace(/^sha256:/i,'').toLowerCase()}`:null;
 const id = value=>typeof value==='string'&&/^[A-Za-z0-9_-]{1,64}$/.test(value)?value:null;
@@ -56,7 +58,7 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
     binding:reportBound&&id(verdict.run_id)&&id(verdict.run_id)===id(report?.stages?.qa?.verdict_run_id)&&build&&qaSource===build&&doctor?.derived?.build_output_fingerprint?.status==='pass'&&hash(verdict.spec_hash)===localHash?'matching':'unconfirmed',
     publish_state:accepted(qaResult?.qa_verdict_publish?.state,['skipped','ok','failed']),
   }:null;
-  const gates=(Array.isArray(continuation?.gates)?continuation.gates:[]).slice(0,16).map(gate=>({id:accepted(gate?.id,PROGRESS_GATE_IDS),state:PROGRESS_GATE_IDS.includes(gate?.id)?accepted(gate?.status,['pass','blocked','waived','not_applicable']):'unknown'}));
+  const gates=(Array.isArray(continuation?.gates)?continuation.gates:[]).slice(0,PROGRESS_GATE_LIMIT).map(gate=>({id:accepted(gate?.id,PROGRESS_GATE_IDS),state:PROGRESS_GATE_IDS.includes(gate?.id)?accepted(gate?.status,['pass','blocked','waived','not_applicable']):'unknown'}));
   const actions=[...new Set((Array.isArray(continuation?.next_actions)?continuation.next_actions:[]).slice(0,64).map(action=>accepted(action?.id,PROGRESS_ACTION_IDS)))];
   const stage=accepted(continuation?.stage,PROGRESS_CONTINUATIONS);
   const preview=typeof packet?.deploy?.preview_url==='string'&&packet.deploy.preview_url?packet.deploy.preview_url:null;

package/src/qa-analytics-parity.mjs

@@ -547,6 +547,10 @@ function valuesEqual(a, b) {
 // flag carried-over-tag regressions for human review.
 // `options.url` is the candidate URL that was captured (the resolved capture
 // target) — stamped on every emitted assertion, pass and fail alike.
+// `options.candidatePage` describes the page the candidate was captured on when
+// the leg picked it automatically (#512): `{ receipt, source, page_type }`.
+// An explicit --analytics-candidate passes none and is treated as the receipt
+// the operator named.
 export function diffAnalyticsParity(baseline, candidate, options = {}) {
   const assertions = [];
   const auditedUrl = (typeof options.url === "string" && options.url.trim()) ? options.url.trim() : null;
@@ -561,13 +565,44 @@ export function diffAnalyticsParity(baseline, candidate, options = {}) {
   const cEff = effectivePurchase(c);
 
   // 1. Purchase present on candidate — the highest-value blocking check.
-  assertions.push(emit({
+  // #512: Purchase fires only on a receipt. When the candidate is known not to
+  // be one (the automatic capture page is the campaign root or a built entry),
+  // a missing Purchase is a page mismatch, not a regression, so it goes to
+  // manual review naming the mismatch. A receipt candidate, or one the
+  // operator named, still blocks.
+  const candidatePage = options.candidatePage && typeof options.candidatePage === "object" ? options.candidatePage : null;
+  if (!cEff.fired && candidatePage?.receipt === false) {
+    const baselineFired = effectivePurchase(b).fired;
+    assertions.push(emit({
+      id: "analytics-parity:purchase-present",
+      status: STATUS.MANUAL_REVIEW,
+      severity: SEVERITY.WARN,
+      expected: "a receipt candidate to check Purchase on; the automatic candidate is not a receipt, so pair receipts with --analytics-candidate",
+      actual: baselineFired
+        ? "baseline fired a Purchase but the automatic candidate is not a receipt page; pass --analytics-candidate <candidate receipt url> to compare receipts"
+        : "neither page fired a Purchase and the automatic candidate is not a receipt page; pass receipt URLs to --analytics-baseline and --analytics-candidate to compare Purchase",
+      evidence: {
+        via: cEff.via,
+        candidate_events: c.eventNames || [],
+        baseline_purchase: bp,
+        page_mismatch: {
+          reason: baselineFired ? "receipt_baseline_non_receipt_candidate" : "candidate_not_receipt",
+          baseline_fired_purchase: baselineFired,
+          candidate_receipt: candidatePage.receipt,
+          candidate_source: candidatePage.source ?? null,
+          candidate_page_type: candidatePage.page_type ?? null,
+        },
+      },
+    }));
+  } else assertions.push(emit({
     id: "analytics-parity:purchase-present",
     status: cEff.fired ? STATUS.PASS : STATUS.FAIL,
     severity: SEVERITY.BLOCKER,
     expected: "candidate fires a Purchase (dl_purchase, or Meta/GA4 pixel if the SDK event is blocked)",
     actual: cEff.fired ? `purchase fired via ${cEff.via}` : "no purchase fire captured on candidate (dataLayer, Meta, or GA4)",
-    evidence: { via: cEff.via, candidate_events: c.eventNames || [], candidate_signals: c.purchaseSignals || {}, baseline_purchase: bp },
+    // An automatic candidate's page is recorded even when it fired, so a pass on
+    // a non-receipt page reads as such.
+    evidence: { via: cEff.via, candidate_events: c.eventNames || [], candidate_signals: c.purchaseSignals || {}, baseline_purchase: bp, ...(candidatePage ? { candidate_page: candidatePage } : {}) },
   }));
 
   if (cEff.fired) {

package/src/qa-binding-evidence.mjs

@@ -1,7 +1,7 @@
 import { parse as parseHtml } from 'parse5';
 import { parse as parseJs } from 'acorn';
 import { createPageSourceLoader, resolveCommercialApiKey } from './qa-commercial-parity.mjs';
-import { HTML_NAMESPACE, baseInEffect, documentBases, frozenBaseUrl, parseFailureDiagnostic, scriptKind } from './built-script-syntax.mjs';
+import { HTML_NAMESPACE, baseInEffect, documentBases, endsUnclosed, frozenBaseUrl, parseFailureDiagnostic, scriptKind } from './built-script-syntax.mjs';
 
 export const BINDING_SCHEMA = 'campaigns-os-page-binding/v0';
 export const BINDING_LIMITS = Object.freeze({ scripts_per_page: 6, scripts_per_run: 24, script_bytes: 262144, timeout_ms: 5000 });
@@ -124,8 +124,10 @@ export async function observeBinding({ source, page, expected, scriptLoader, par
     // Only an HTML-namespace <script> loads `src`. An SVG script runs from
     // href / xlink:href or its inline text, which this static read does not
     // model: it is not fetched and leaves the binding dynamic.
+    // A script the file ends inside never reaches its end tag, so the parser
+    // never prepares it: the browser neither fetches nor runs it (#515).
     if (node.tagName === 'script' && node.namespaceURI !== HTML_NAMESPACE) dynamic = true;
-    else if (node.tagName === 'script') scripts.push({ attrs, base: baseInEffect(bases, node), text: (node.childNodes || []).map(n => n.value || '').join('') });
+    else if (node.tagName === 'script' && !endsUnclosed(node)) scripts.push({ attrs, base: baseInEffect(bases, node), text: (node.childNodes || []).map(n => n.value || '').join('') });
     // parse5 keeps template content separate; it is inert, as is noscript at boot.
     if (node.tagName !== 'noscript') for (const child of node.childNodes || []) walk(child);
   };