@nextcommerce/campaigns-os 1.48.0 → 1.52.0

package/src/sdk-attribute-index.mjs

@@ -210,3 +210,74 @@ export function isKnownCheckoutFieldName(value) {
   return SDK_CHECKOUT_FIELD_NAMES.includes(name)
     || SDK_CHECKOUT_FIELD_PREFIXES.some((prefix) => name.startsWith(prefix) && name.length > prefix.length);
 }
+
+// The Campaign Cart template placeholders, for the raw cart placeholder check
+// (built_output.cart_placeholders). Generated from the SDK renderers at the
+// same tag as the attribute index above, v0.4.38:
+//
+//   src/features/cart/cart-summary/cart-summary.renderer.ts:46-83 (bare vars)
+//   src/features/cart/cart-summary/cart-summary.line-renderer.ts:150-173,
+//     228-240,256-314 ({item.*} and its {line.*} alias, {property.*},
+//     {discount.*})
+//   src/features/cart/package-selector/package-selector.renderer.ts:26
+//     ({package.<any key>})
+//   src/features/cart/bundle-selector/bundle-selector.renderer.ts:37-42
+//     ({bundle.<any key>})
+//   src/features/cart/package-toggle/package-toggle.enhancer.ts:59-65
+//     ({toggle.<any key>})
+//   src/features/cart/quantity-control/quantity-control.renderer.ts:69-70
+//     ({quantity}, {step})
+//   src/features/cart/remove-item/remove-item.renderer.ts:26 ({quantity})
+//   src/features/display/quantity-text/quantity-text.enhancer.ts:124,149
+//     ({qty...} and {singular|plural})
+//
+// Every namespaced renderer replaces any `{<namespace>.<key>}` in its
+// template (item.property.<key> and the package, bundle and toggle keys are
+// open-ended; an unmapped key renders empty), so the namespace alone makes a
+// token known. `{tax}` is not a cart-summary var at this tag. Regenerate the
+// lists whole from the renderers when the index pin advances; never edit them
+// by hand.
+export const SDK_TEMPLATE_PLACEHOLDERS = Object.freeze({
+  cart_summary_vars: Object.freeze([
+    "subtotal",
+    "total",
+    "shipping",
+    "shippingName",
+    "shippingCode",
+    "shippingOriginal",
+    "shippingDiscountAmount",
+    "shippingDiscountPercentage",
+    "totalDiscount",
+    "totalDiscountPercentage",
+    "discounts",
+    "currency",
+    "isCalculating",
+    "isEmpty",
+    "itemCount",
+    "totalQuantity",
+    "isFreeShipping",
+    "hasShippingDiscount",
+    "hasDiscounts",
+  ]),
+  namespaces: Object.freeze(["item", "line", "discount", "property", "package", "bundle", "toggle"]),
+  // Tokens the SDK substitutes in live markup, and the elements that own them.
+  live_tokens: Object.freeze(["quantity", "step", "qty"]),
+  // [data-next-quantity="increase|decrease|set"]: {quantity} and {step}.
+  quantity_control: Object.freeze({ attribute: "data-next-quantity", values: Object.freeze(["increase", "decrease", "set"]), tokens: Object.freeze(["quantity", "step"]) }),
+  // [data-next-remove-item]: {quantity} only.
+  remove_item: Object.freeze({ attribute: "data-next-remove-item", tokens: Object.freeze(["quantity"]) }),
+  // [data-next-quantity-text]: {qty...} and the singular/plural form.
+  // `qty_forms` is the renderer's own {qty} pattern (quantity-text.enhancer.ts:
+  // 124, /\{qty([*+\-]?\d*)\}/): {qty}, {qty*2}, {qty+1}, {qty-1}.
+  quantity_text: Object.freeze({ attribute: "data-next-quantity-text", tokens: Object.freeze(["qty"]), qty_forms: "qty[*+\\-]?\\d*" }),
+  // Item lists whose innerHTML the SDK uses as the row template or replaces
+  // (cart-item-list.enhancer.ts:21-35, order-item-list.enhancer.ts:26-36).
+  item_list_containers: Object.freeze(["data-next-cart-items", "data-next-order-items"]),
+  item_template_selector: "data-item-template-selector",
+  item_template: "data-item-template",
+});
+
+// The SDK versions whose renderer files above were verified unchanged from
+// v0.4.38 (git blob ids equal at v0.4.38, v0.4.39 and v0.4.40). A page whose
+// loader pins another version cannot pass the placeholder check.
+export const SDK_TEMPLATE_PLACEHOLDERS_VERIFIED_PINS = Object.freeze(["0.4.38", "0.4.39", "0.4.40"]);

package/src/sdk-markup.mjs

@@ -86,7 +86,7 @@ export const SDK_MARKUP_CODES = Object.freeze({
 
 // Attributes whose value names a <template> by id. The SDK reads the template
 // they point at, so that template is SDK-owned wherever it sits.
-const TEMPLATE_ID_ATTRIBUTES = /^data-(?:next-)?[a-z0-9-]*template-id$/;
+export const TEMPLATE_ID_ATTRIBUTES = /^data-(?:next-)?[a-z0-9-]*template-id$/;
 
 // Containers whose DIRECT <template> child the SDK clones (each does a
 // `:scope > template` lookup at v0.4.38: cart-summary and its
@@ -98,7 +98,7 @@ const TEMPLATE_ID_ATTRIBUTES = /^data-(?:next-)?[a-z0-9-]*template-id$/;
 // package-toggle).
 // Only the direct child: a vendor template nested deeper inside SDK chrome is
 // never read, so it may use any syntax.
-const TEMPLATE_CONTAINER_ATTRIBUTES = [
+export const TEMPLATE_CONTAINER_ATTRIBUTES = [
   "data-next-cart-summary",
   "data-summary-lines",
   "data-next-discounts",

package/src/sdk-storage-compatibility.mjs

@@ -1,6 +1,7 @@
 // Read-only source evidence. SDK migration names come exclusively from the supplied manifest.
 import { parse as parseJs } from 'acorn';
 import { parse as parseHtml } from 'parse5';
+import { parseDocument, isSeq, isScalar, LineCounter } from 'yaml';
 import { execFileSync } from 'node:child_process';
 import { readFileSync, lstatSync, realpathSync, statSync } from 'node:fs';
 import { resolve, relative, dirname, posix, sep } from 'node:path';
@@ -261,6 +262,35 @@ export function analyzeStorageJavaScript(source, { path = '<source>', lineOffset
   visit(ast, null);
   return findings;
 }
+// Page Kit's campaign_asset filter serves src/<slug>/assets/<path>, <slug> being
+// the campaign folder the template sits in. A layout's {% for script in scripts %}
+// loop loads each page's frontmatter `scripts:` entries through the same filter.
+const CAMPAIGN_ASSET_SRC = /^\{\{-?\s*(?:'([^']*)'|"([^"]*)"|([A-Za-z_]\w*))\s*\|\s*campaign_asset\s*-?\}\}$/;
+function campaignAssetRoot(path) {
+  const match = /^((?:.*\/)?src\/[^/]+)\//.exec(path);
+  return match ? `${match[1]}/assets` : null;
+}
+function loopsOverPageScripts(text, name) {
+  return new RegExp(`\\{%-?\\s*for\\s+${name}\\s+in\\s+(?:page\\.)?scripts\\b`).test(text);
+}
+// Each local-or-remote entry of a page's frontmatter `scripts:` list with the
+// file line it is declared on, or an error naming why the list cannot be read.
+function frontmatterScripts(text) {
+  const block = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+  if (!block) return { scripts: [] };
+  const lineCounter = new LineCounter();
+  const document = parseDocument(block[1], { lineCounter });
+  if (document.errors.length) {
+    const { line } = lineCounter.linePos(document.errors[0].pos[0]);
+    return { error: `Frontmatter is not valid YAML (${document.errors[0].code}); review the scripts this page loads.`, line: line + 1 };
+  }
+  const scripts = document.get('scripts', true);
+  if (scripts === undefined || scripts === null || (isScalar(scripts) && scripts.value === null)) return { scripts: [] };
+  if (!isSeq(scripts) || !scripts.items.every(item => isScalar(item) && typeof item.value === 'string'))
+    return { error: 'Frontmatter scripts is not a list of paths; review the scripts this page loads.', line: lineCounter.linePos(scripts.range?.[0] ?? 0).line + 1 };
+  // linePos is 1-based within the YAML block, which starts on the file's line 2.
+  return { scripts: scripts.items.map(item => ({ value: item.value, line: lineCounter.linePos(item.range[0]).line + 1 })) };
+}
 export function scanSdkStorageCompatibility({ cwd = process.cwd(), targetSdkVersion, manifestPath, scope, exclude = [] }) {
   version(targetSdkVersion);
   if (!Array.isArray(scope) || !scope.length)
@@ -320,20 +350,50 @@ export function scanSdkStorageCompatibility({ cwd = process.cwd(), targetSdkVers
       for (const child of node.childNodes ?? []) findBase(child);
     }
     findBase(document);
+    const assetRoot = campaignAssetRoot(path);
+    const requireSelected = (sourcePath, line) => {
+      if (!selected.includes(sourcePath))
+        unknown(path, 'shared-script-outside-scope', sourcePath, line);
+    };
+    // Page Kit serves campaign_asset paths from the assets folder only; an entry
+    // that normalizes outside it is not a file the page loads from there.
+    const requireAsset = (asset, line) => {
+      const sourcePath = posix.normalize(`${assetRoot}/${asset.split(/[?#]/)[0]}`);
+      if (sourcePath.startsWith(`${assetRoot}/`)) requireSelected(sourcePath, line);
+      else unknown(path, 'shared-script-outside-scope', `${asset} resolves outside ${assetRoot}`, line);
+    };
+    if (assetRoot) {
+      const frontmatter = frontmatterScripts(text);
+      if (frontmatter.error)
+        unknown(path, 'shared-script-outside-scope', frontmatter.error, frontmatter.line);
+      for (const { value, line } of frontmatter.scripts ?? []) {
+        if (/^(?:[a-z]+:)?\/\//i.test(value) || value.startsWith('data:')) continue;
+        requireAsset(value, line);
+      }
+    }
     function html(node) {
       if (node.tagName === 'script') {
         const attrs = Object.fromEntries((node.attrs ?? []).map(a => [a.name, a.value]));
         const type = (attrs.type ?? '').trim().toLowerCase();
         if (!type || ['module', 'text/javascript', 'application/javascript', 'text/ecmascript', 'application/ecmascript'].includes(type)) {
-          if (attrs.src) {
+          const campaignAsset = attrs.src ? CAMPAIGN_ASSET_SRC.exec(attrs.src.trim()) : null;
+          if (campaignAsset) {
+            const line = node.sourceCodeLocation?.startLine ?? 1;
+            const literal = campaignAsset[1] ?? campaignAsset[2];
+            if (assetRoot && literal !== undefined)
+              requireAsset(literal, line);
+            else if (!assetRoot || !loopsOverPageScripts(text, campaignAsset[3]))
+              unknown(path, 'shared-script-outside-scope', attrs.src, line);
+            // A frontmatter scripts loop: each page's own entries are checked above.
+          }
+          else if (attrs.src) {
             if (baseHref !== null && !attrs.src.startsWith('/') && !/^[a-z]+:/i.test(attrs.src)) {
               unknown(path, 'html-base-script-resolution', `Relative script ${attrs.src} resolves against base ${baseHref}; include/review the actual dependency.`, node.sourceCodeLocation?.startLine ?? 1);
             }
             if (!/^(?:[a-z]+:)?\/\//i.test(attrs.src) && !attrs.src.startsWith('data:')) {
               const localSource = attrs.src.split(/[?#]/)[0];
               const sourcePath = posix.normalize(localSource.startsWith('/') ? localSource.slice(1) : posix.join(posix.dirname(path), localSource));
-              if (!selected.includes(sourcePath))
-                unknown(path, 'shared-script-outside-scope', sourcePath, node.sourceCodeLocation?.startLine ?? 1);
+              requireSelected(sourcePath, node.sourceCodeLocation?.startLine ?? 1);
             }
           }
           else if (node.sourceCodeLocation?.startTag) {

package/src/source-prep.mjs

@@ -8,7 +8,7 @@
 // source asset crawl (source_asset.* codes) so the two checks never disagree
 // about the same reference.
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { collectDocumentWrapperNames } from "./adapter-decision-contract.mjs";
 
 export const SOURCE_PREP_DOCUMENT_WRAPPER = "source_html.prep.document_wrapper";
@@ -201,7 +201,7 @@ function describeFinding(code, pages, { wrapperPolicy }) {
     const policyNote = wrapperPolicy === "preserve_document_wrappers"
       ? " The adapter contract records wrapper_policy \"preserve_document_wrappers\", so this is reported without blocking."
       : "";
-    return `Mapped source HTML is a full browser document, not page-kit-ready source: ${listed}${more}. Strip <!doctype>, <html>, <head>, and <body> so the campaign layout can wrap the page, or, for a standalone page meant to stay whole, record wrapper_policy "preserve_document_wrappers" as an explicit adapter decision: re-run start or prepare-build with --wrapper-policy preserve_document_wrappers, or set "wrapper_policy" in the source-html manifest.${policyNote} See ${docs}.`;
+    return `Mapped source HTML (the converted page-kit page once it exists at page_kit.output_path, else the design) is a full browser document, not page-kit-ready source: ${listed}${more}. Strip <!doctype>, <html>, <head>, and <body> so the campaign layout can wrap the page, or, for a standalone page meant to stay whole, record wrapper_policy "preserve_document_wrappers" as an explicit adapter decision: re-run start or prepare-build with --wrapper-policy preserve_document_wrappers, or set "wrapper_policy" in the source-html manifest.${policyNote} See ${docs}.`;
   }
   if (code === SOURCE_PREP_FRONTMATTER_RESIDUE) {
     const listed = sample.map((page) => {
@@ -220,6 +220,26 @@ function describeFinding(code, pages, { wrapperPolicy }) {
   return `Mapped source HTML still links to source files instead of CampaignSpec routes: ${listed}${more}. Replace internal links and CTA destinations with CampaignSpec-derived routes, usually via campaign_link; source filenames like checkout.html are not built campaign URLs. See ${docs}.`;
 }
 
+// The converted page-kit page for a mapped design (page_kit.output_path under
+// the target repo), when it has been written.
+function convertedPageContent(targetRoot, page) {
+  const outputPath = page?.page_kit?.output_path;
+  if (!isNonEmptyString(targetRoot) || !isNonEmptyString(outputPath)) return null;
+  // output_path is repo-relative. One that is absolute or climbs out of the
+  // target repo is not a converted page of this campaign, so it reads like a
+  // missing one and the design is checked instead.
+  const root = resolve(targetRoot);
+  const fullPath = resolve(root, outputPath);
+  const rel = relative(root, fullPath);
+  if (isAbsolute(outputPath) || rel === "" || rel.startsWith("..") || isAbsolute(rel)) return null;
+  if (!safeIsFile(fullPath)) return null;
+  try {
+    return { path: toPosixPath(outputPath), content: readFileSync(fullPath, "utf8") };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Evaluates the page-kit source-preparation expectations for every mapped
  * source page. Deterministic: same files in, same findings out. Unreadable or
@@ -227,7 +247,7 @@ function describeFinding(code, pages, { wrapperPolicy }) {
  *
  * @returns {{ checked_page_count: number, findings: Array<{code, severity, message, docs, pages}> }}
  */
-export function evaluateSourcePreparation({ sourceRoot, pages = [], wrapperPolicy = null }) {
+export function evaluateSourcePreparation({ sourceRoot, pages = [], wrapperPolicy = null, targetRoot = null }) {
   const mappedPaths = new Set(
     pages
       .map((page) => (isNonEmptyString(page?.path) ? toPosixPath(page.path) : null))
@@ -247,14 +267,24 @@ export function evaluateSourcePreparation({ sourceRoot, pages = [], wrapperPolic
       continue;
     }
     checked += 1;
-    const pageFindings = inspectPageContent({ content, sourceRoot, pagePath: page.path, mappedPaths });
+    let pageFindings = inspectPageContent({ content, sourceRoot, pagePath: page.path, mappedPaths });
+    // Wrappers are stripped when the design is converted into the page-kit
+    // page at page_kit.output_path, the file page-kit builds. Once that page
+    // exists, it is the one checked; the design keeps its wrappers.
+    const converted = convertedPageContent(targetRoot, page);
+    if (converted) {
+      pageFindings = pageFindings.filter((finding) => finding.code !== SOURCE_PREP_DOCUMENT_WRAPPER);
+      const wrappers = collectDocumentWrapperNames(converted.content);
+      if (wrappers.length) pageFindings.push({ code: SOURCE_PREP_DOCUMENT_WRAPPER, wrappers, path: converted.path });
+    }
     for (const finding of pageFindings) {
       if (!byCode.has(finding.code)) byCode.set(finding.code, new Map());
       const pagesForCode = byCode.get(finding.code);
-      if (!pagesForCode.has(page.path)) {
-        pagesForCode.set(page.path, { page_id: page.page_id || null, path: page.path, wrappers: [], hrefs: [], variants: [] });
+      const findingPath = finding.path || page.path;
+      if (!pagesForCode.has(findingPath)) {
+        pagesForCode.set(findingPath, { page_id: page.page_id || null, path: findingPath, wrappers: [], hrefs: [], variants: [] });
       }
-      const entry = pagesForCode.get(page.path);
+      const entry = pagesForCode.get(findingPath);
       if (finding.wrappers) entry.wrappers.push(...finding.wrappers);
       if (finding.hrefs) entry.hrefs.push(...finding.hrefs);
       if (finding.variant) entry.variants.push({ variant: finding.variant, lines: finding.lines || [] });