@nextcommerce/campaigns-os 1.33.0

package/src/campaign-identity.mjs

@@ -0,0 +1,405 @@
+// Cross-page campaign identity (#301).
+//
+// Every page of a built campaign tells the Campaign Cart SDK which campaign it
+// belongs to through three signals, and the SDK reads each of them per page
+// with no cross-page reconciliation:
+//
+//   API key      <meta name="next-api-key"> beats window.nextConfig.apiKey
+//                (inline, or in the config.js the page loads). Selects the
+//                campaign whose packages, prices and orders the page acts on.
+//   next-funnel  <meta name="next-funnel">. Attributed onto the order.
+//   setAttribution({ funnel })  A script call that overrides the funnel tag.
+//
+// The failure this module gates is a page borrowed from another funnel: a
+// copied upsell or receipt page that still carries the other campaign's API
+// key, funnel tag, or setAttribution call. Nothing else notices. The SDK binds
+// each page happily, the build succeeds, the page renders, and the order is
+// created against (or attributed to) the wrong campaign. It has shipped twice
+// and been written up as advice both times; advice is not a gate.
+//
+// Hence a static blocker over built output that asserts CONSISTENCY only:
+//
+//   - every API key observed anywhere in the campaign is the same key;
+//   - every next-funnel meta is the same value, and once any page carries one,
+//     every page that declares a next-page-type (so the SDK is bootstrapped on
+//     it) carries one too;
+//   - every setAttribution({ funnel }) agrees with the next-funnel of the page
+//     that calls it.
+//
+// Presence is deliberately NOT asserted. Whether a checkout page must call
+// setAttribution is a separate question (the SDK reads ?funnel=, then the
+// remembered funnel, then the tag, and the platform fills the campaign name
+// when the tag is absent), and a campaign whose pages carry no key at all is a
+// different defect with its own check.
+//
+// Not waivable. The two values in a finding cannot both be right, so there is
+// no bounded human decision to record — the fix is a one-line edit, and the
+// message names the two files and the two values so it is exactly that.
+//
+// Pure: callers read the built HTML and the local scripts each page loads and
+// hand them in. Nothing here touches the filesystem, so the packet doctor path
+// and the built-site-only path (`doctor --built`) drive the same evaluator.
+
+export const CAMPAIGN_IDENTITY = "built_output.campaign_identity";
+
+// Finding kinds, each with its own issue code under the gate id.
+export const CAMPAIGN_IDENTITY_KINDS = Object.freeze({
+  api_key_drift: `${CAMPAIGN_IDENTITY}.api_key_drift`,
+  funnel_drift: `${CAMPAIGN_IDENTITY}.funnel_drift`,
+  funnel_missing: `${CAMPAIGN_IDENTITY}.funnel_missing`,
+  attribution_drift: `${CAMPAIGN_IDENTITY}.attribution_drift`,
+});
+
+const HTML_COMMENT = /<!--[\s\S]*?-->/g;
+const INLINE_SCRIPT = /<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi;
+const SET_ATTRIBUTION_FUNNEL = /setAttribution\s*\(\s*\{[^}]*?\bfunnel\s*:\s*(["'`])([^"'`]*)\1/g;
+
+// A page that is a parked copy rather than a served page: `checkout-backup-2`,
+// `upsell-old`, `old-receipt`. The issue names `*-backup-*` and `*-old-*`; the
+// segment-anchored form also catches the marker at either end of a segment so
+// `upsell-old/` and `old-upsell/` are both skipped, while `bold-claims/` and
+// `holdout/` are not. Skipped pages are reported, never silently dropped.
+const PARKED_SEGMENT = /(^|-)(backup|old)(-|$)/i;
+
+export function isParkedPage(routeOrFile) {
+  const value = String(routeOrFile || "").replace(/\\/g, "/").replace(/\/index\.html?$/i, "").replace(/\.html?$/i, "");
+  return value.split("/").some((segment) => PARKED_SEGMENT.test(segment));
+}
+
+function metaContent(html, name) {
+  const tag = new RegExp(`<meta\\b(?=[^>]*\\bname=["']${name}["'])([^>]*)>`, "i").exec(html);
+  if (!tag) return null;
+  const content = /\bcontent=["']([^"']*)["']/i.exec(tag[1]);
+  return content ? content[1].trim() : "";
+}
+
+function hasSrcAttribute(attrs) {
+  return /(?:^|\s)src\s*=/i.test(attrs || "");
+}
+
+/**
+ * The `src` of every external `<script>` on a page, in document order, with
+ * HTML comments stripped first so a commented-out loader is not followed.
+ * The caller resolves and reads them (that needs the filesystem) and hands
+ * them back as `page.scripts[]`.
+ */
+export function externalScriptSources(html) {
+  const source = String(html || "").replace(HTML_COMMENT, "");
+  return [...source.matchAll(/<script\b[^>]*\bsrc=["']([^"']+)["'][^>]*>/gi)].map((match) => match[1]);
+}
+
+/**
+ * Inline `<script>` bodies of a page, in document order. External scripts are
+ * the caller's to resolve (they need the filesystem); they arrive as
+ * `page.scripts[]`.
+ */
+export function inlineScriptBodies(html) {
+  const source = String(html || "").replace(HTML_COMMENT, "");
+  const bodies = [];
+  for (const match of source.matchAll(INLINE_SCRIPT)) {
+    if (hasSrcAttribute(match[1])) continue;
+    if (match[2].trim()) bodies.push(match[2]);
+  }
+  return bodies;
+}
+
+// Walk a JS object literal from its opening brace and return the string value
+// of a given key at depth 1, skipping strings, template literals and comments
+// so a commented-out `apiKey: "your-api-key"` or a nested
+// `googleMaps: { apiKey: "" }` (both present in the starter config.js) cannot
+// be read as the campaign key. Returns null when the key is absent or its
+// value is not a plain string literal (a computed value is not something a
+// static check can compare).
+function depthOneStringValue(js, openIndex, key) {
+  let depth = 0;
+  let i = openIndex;
+  const n = js.length;
+  // Sticky, so a test at position i reads from i without slicing the source.
+  const keyPattern = new RegExp(`(?:${key}|["']${key}["'])\\s*:\\s*(["'\`])((?:\\\\.|(?!\\1)[^\\\\])*)\\1`, "y");
+  const identifier = /[A-Za-z0-9_$]*/y;
+  const tryKey = (at) => {
+    keyPattern.lastIndex = at;
+    const hit = keyPattern.exec(js);
+    return hit ? hit[2] : null;
+  };
+  while (i < n) {
+    const ch = js[i];
+    const next = js[i + 1];
+    if (ch === "/" && next === "/") {
+      const end = js.indexOf("\n", i);
+      i = end === -1 ? n : end + 1;
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      const end = js.indexOf("*/", i + 2);
+      i = end === -1 ? n : end + 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      // At depth 1 a string may be the quoted key itself; test before skipping.
+      if (depth === 1) {
+        const value = tryKey(i);
+        if (value != null) return value;
+      }
+      i += 1;
+      while (i < n && js[i] !== ch) {
+        if (js[i] === "\\") i += 1;
+        i += 1;
+      }
+      i += 1;
+      continue;
+    }
+    if (ch === "{") {
+      depth += 1;
+      i += 1;
+      continue;
+    }
+    if (ch === "}") {
+      depth -= 1;
+      if (depth <= 0) return null;
+      i += 1;
+      continue;
+    }
+    if (/[A-Za-z_$]/.test(ch)) {
+      // An identifier: test it as the key once (at depth 1, and only when it
+      // starts a word) and then step past the whole identifier in one jump
+      // rather than re-testing at every character inside it.
+      if (depth === 1 && (i === 0 || !/[A-Za-z0-9_$.]/.test(js[i - 1]))) {
+        const value = tryKey(i);
+        if (value != null) return value;
+      }
+      identifier.lastIndex = i;
+      identifier.exec(js);
+      i = Math.max(identifier.lastIndex, i + 1);
+      continue;
+    }
+    i += 1;
+  }
+  return null;
+}
+
+/**
+ * Every campaign API key a script text declares, with the spelling it used.
+ *
+ *   window.nextConfig = { apiKey: "…" }      -> "nextConfig.apiKey"
+ *   window.nextConfig.apiKey = "…"           -> "nextConfig.apiKey"
+ *   nextCampaign.config({ apiKey: "…" })     -> "nextCampaign.config apiKey" (legacy)
+ */
+export function collectScriptApiKeys(js) {
+  const source = String(js || "");
+  const keys = [];
+  for (const match of source.matchAll(/\bnextConfig\s*=\s*\{/g)) {
+    const value = depthOneStringValue(source, match.index + match[0].length - 1, "apiKey");
+    if (value != null) keys.push({ source: "nextConfig.apiKey", value: value.trim() });
+  }
+  for (const match of source.matchAll(/\bnextConfig\s*\.\s*apiKey\s*=\s*(["'`])((?:\\.|(?!\1)[^\\])*)\1/g)) {
+    keys.push({ source: "nextConfig.apiKey", value: match[2].trim() });
+  }
+  for (const match of source.matchAll(/\bnextCampaign\s*\.\s*config\s*\(\s*\{/g)) {
+    const value = depthOneStringValue(source, match.index + match[0].length - 1, "apiKey");
+    if (value != null) keys.push({ source: "nextCampaign.config apiKey", value: value.trim() });
+  }
+  return keys;
+}
+
+export function collectSetAttributionFunnels(js) {
+  return [...String(js || "").matchAll(SET_ATTRIBUTION_FUNNEL)].map((match) => match[2].trim());
+}
+
+/**
+ * The identity signals one built page carries.
+ *
+ * @param {{ page_id: string, file?: string|null, content: string,
+ *   scripts?: Array<{ src: string, file?: string|null, content: string }> }} page
+ */
+export function collectPageIdentity(page) {
+  const html = String(page?.content || "");
+  const stripped = html.replace(HTML_COMMENT, "");
+  // Normalized once: an empty content="" is "no meta", here and on the record.
+  const apiKeyMeta = metaContent(stripped, "next-api-key") || null;
+  const apiKeys = [];
+  if (apiKeyMeta) apiKeys.push({ source: 'meta name="next-api-key"', where: page.file || page.page_id, value: apiKeyMeta });
+  const attributions = [];
+
+  for (const body of inlineScriptBodies(html)) {
+    for (const key of collectScriptApiKeys(body)) apiKeys.push({ ...key, source: `inline ${key.source}`, where: page.file || page.page_id });
+    for (const funnel of collectSetAttributionFunnels(body)) attributions.push({ where: page.file || page.page_id, value: funnel });
+  }
+  for (const script of Array.isArray(page?.scripts) ? page.scripts : []) {
+    const where = script.file || script.src;
+    for (const key of collectScriptApiKeys(script.content)) apiKeys.push({ ...key, source: `${script.src} ${key.source}`, where });
+    for (const funnel of collectSetAttributionFunnels(script.content)) attributions.push({ where, value: funnel });
+  }
+
+  return {
+    page_id: page.page_id,
+    file: page.file || null,
+    api_key_meta: apiKeyMeta,
+    api_keys: apiKeys,
+    funnel: metaContent(stripped, "next-funnel"),
+    page_type: metaContent(stripped, "next-page-type"),
+    attributions,
+  };
+}
+
+function quote(value) {
+  return value == null ? "(none)" : `"${value}"`;
+}
+
+function gateBase(subject) {
+  return {
+    id: CAMPAIGN_IDENTITY,
+    scope: CAMPAIGN_IDENTITY,
+    waivable: false,
+    subject: subject && typeof subject === "object" ? subject : {},
+    waiver: null,
+  };
+}
+
+/**
+ * Evaluate cross-page campaign identity over built pages.
+ *
+ * @param {{ subject: object, pages: Array<{ page_id: string, route?: string|null,
+ *   file?: string|null, content: string,
+ *   scripts?: Array<{ src: string, file?: string|null, content: string }> }> }} input
+ */
+export function evaluateCampaignIdentity({ subject, pages = [] } = {}) {
+  const all = Array.isArray(pages) ? pages : [];
+  const skipped = all
+    .filter((page) => isParkedPage(page.route ?? page.file ?? page.page_id))
+    .map((page) => page.file || page.page_id);
+  const scanned = all.filter((page) => !isParkedPage(page.route ?? page.file ?? page.page_id));
+
+  if (scanned.length === 0) {
+    return {
+      ...gateBase(subject),
+      status: "not_applicable",
+      code: `${CAMPAIGN_IDENTITY}.not_applicable`,
+      reason: "No built page was available to scan; campaign identity becomes mandatory once pages are built.",
+      findings: [],
+      pages_scanned: 0,
+      pages_skipped: skipped,
+      identity: null,
+      required_actions: [],
+    };
+  }
+
+  const identities = scanned.map(collectPageIdentity);
+  const findings = [];
+
+  // 1. API key: every observed key, from every source on every page, is one
+  //    value. Meta and config are compared together on purpose: a page whose
+  //    meta names one campaign while its config.js names another is drift
+  //    inside a single page, and the SDK's precedence rule only hides it.
+  const keyObservations = identities.flatMap((identity) => identity.api_keys.map((key) => ({ page_id: identity.page_id, ...key })));
+  const firstKey = keyObservations[0] || null;
+  for (const observation of keyObservations.slice(1)) {
+    if (observation.value === firstKey.value) continue;
+    findings.push({
+      kind: "api_key_drift",
+      code: CAMPAIGN_IDENTITY_KINDS.api_key_drift,
+      a: { page_id: firstKey.page_id, file: firstKey.where, source: firstKey.source, value: firstKey.value },
+      b: { page_id: observation.page_id, file: observation.where, source: observation.source, value: observation.value },
+      message: `API key differs across pages: ${firstKey.where} has ${quote(firstKey.value)} (${firstKey.source}) but ${observation.where} has ${quote(observation.value)} (${observation.source}). One of these pages was borrowed from another campaign; make both name the same key.`,
+    });
+    break; // one finding per kind names the first pair; the rest follow from the same edit
+  }
+
+  // 2. next-funnel: one value across pages, and present wherever the SDK is
+  //    bootstrapped (a page that declares next-page-type is SDK-bound).
+  const funnelPages = identities.filter((identity) => identity.funnel);
+  const firstFunnel = funnelPages[0] || null;
+  for (const identity of funnelPages.slice(1)) {
+    if (identity.funnel === firstFunnel.funnel) continue;
+    findings.push({
+      kind: "funnel_drift",
+      code: CAMPAIGN_IDENTITY_KINDS.funnel_drift,
+      a: { page_id: firstFunnel.page_id, file: firstFunnel.file || firstFunnel.page_id, value: firstFunnel.funnel },
+      b: { page_id: identity.page_id, file: identity.file || identity.page_id, value: identity.funnel },
+      message: `next-funnel differs across pages: ${firstFunnel.file || firstFunnel.page_id} has ${quote(firstFunnel.funnel)} but ${identity.file || identity.page_id} has ${quote(identity.funnel)}. Orders from the second page attribute to the other funnel; set the same <meta name="next-funnel"> on both.`,
+    });
+    break;
+  }
+  //    "Missing" is judged against the campaign, not in the abstract: a
+  //    campaign that tags no page at all is consistent (the platform fills the
+  //    campaign name when the tag is absent), and blocking it would be the
+  //    presence assertion this check deliberately does not make. Once ANY
+  //    page carries the tag, an SDK-bound page without it attributes its
+  //    orders differently from the rest, which is drift.
+  //    One finding, like the other kinds: the repair is the same edit on every
+  //    untagged page, and a run should not be dominated by it repeated N times.
+  if (firstFunnel) {
+    for (const identity of identities) {
+      if (identity.funnel || !identity.page_type) continue;
+      findings.push({
+        kind: "funnel_missing",
+        code: CAMPAIGN_IDENTITY_KINDS.funnel_missing,
+        a: { page_id: identity.page_id, file: identity.file || identity.page_id, value: null },
+        b: { page_id: firstFunnel.page_id, file: firstFunnel.file || firstFunnel.page_id, value: firstFunnel.funnel },
+        message: `${identity.file || identity.page_id} declares next-page-type=${quote(identity.page_type)} but no <meta name="next-funnel">, while ${firstFunnel.file || firstFunnel.page_id} carries ${quote(firstFunnel.funnel)}. Orders from the untagged page attribute differently from the rest; add the same next-funnel meta.`,
+      });
+      break;
+    }
+  }
+
+  // 3. setAttribution({ funnel }) agrees with the page's own tag. A page with
+  //    no tag of its own is held to the campaign's tag (the one every other
+  //    page agrees on) so a borrowed script on an untagged page still fails.
+  for (const identity of identities) {
+    const expected = identity.funnel || (firstFunnel ? firstFunnel.funnel : null);
+    if (!expected) continue;
+    const expectedWhere = identity.funnel ? identity.file || identity.page_id : firstFunnel.file || firstFunnel.page_id;
+    for (const attribution of identity.attributions) {
+      if (attribution.value === expected) continue;
+      findings.push({
+        kind: "attribution_drift",
+        code: CAMPAIGN_IDENTITY_KINDS.attribution_drift,
+        a: { page_id: identity.page_id, file: expectedWhere, value: expected },
+        b: { page_id: identity.page_id, file: attribution.where, value: attribution.value },
+        message: `setAttribution({ funnel: ${quote(attribution.value)} }) in ${attribution.where} disagrees with next-funnel ${quote(expected)} in ${expectedWhere}. The call overrides the tag, so orders attribute to ${quote(attribution.value)}; change the call to ${quote(expected)} or remove it.`,
+      });
+    }
+  }
+
+  const identity = {
+    api_key: firstKey ? firstKey.value : null,
+    api_key_source: firstKey ? firstKey.source : null,
+    funnel: firstFunnel ? firstFunnel.funnel : null,
+  };
+
+  if (findings.length === 0) {
+    return {
+      ...gateBase(subject),
+      status: "pass",
+      code: `${CAMPAIGN_IDENTITY}.pass`,
+      reason: `All ${scanned.length} built page(s) agree on campaign identity (API key ${identity.api_key ? "present" : "not declared"}, next-funnel ${quote(identity.funnel)}).`,
+      findings: [],
+      pages_scanned: scanned.length,
+      pages_skipped: skipped,
+      identity,
+      required_actions: [],
+    };
+  }
+
+  return {
+    ...gateBase(subject),
+    status: "blocked",
+    code: CAMPAIGN_IDENTITY,
+    // Short on purpose; the per-edit prose is findings[].message, which is
+    // what each doctor error carries. A reason that concatenates them is
+    // truncated by every single-line renderer.
+    reason: `${findings.length} campaign identity drift finding(s) across ${scanned.length} built page(s) (${[...new Set(findings.map((finding) => finding.kind))].join(", ")}); see findings[] for the two files and two values of each.`,
+    findings,
+    pages_scanned: scanned.length,
+    pages_skipped: skipped,
+    identity,
+    required_actions: [
+      {
+        id: "repair_identity",
+        kind: "edit",
+        command: null,
+        description: `Make every page name the same campaign: ${findings.map((finding) => `${finding.b?.file || finding.a.file} (${finding.kind.replace(/_/g, " ")})`).join("; ")}. Not waivable: two campaign identities on one funnel cannot both be intended.`,
+      },
+    ],
+  };
+}

package/src/campaign-workspace.mjs

@@ -0,0 +1,127 @@
+// Campaign workspace: where a Build Packet's sidecars live, resolved once.
+//
+// Two roots matter. The TARGET REPO (`packet.assembly.target_repo` resolved
+// against the packet's directory, else that directory) carries the build
+// sidecars under `.campaign-runtime/` and the local QA verdicts under
+// `qa-output/`; the packet's own directory (`baseDir`) carries what is written
+// beside the packet (run records, the committed QA verdict sidecar). They
+// coincide for a packet at the target root and diverge for `prepare-build
+// --out` elsewhere — exactly when a stage spelling the rule for itself drifts.
+// A leaf: node built-ins and the sidecar leaves only.
+
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { DOCTOR_SIDECAR_REL_PATH } from "./doctor-sidecar.mjs";
+import { absentOrMalformed, sameFile } from "./fs-identity.mjs";
+
+export const BUILD_CONTEXT_REL_PATH = ".campaign-runtime/build-context.json";
+export const ASSEMBLY_REPORT_REL_PATH = ".campaign-runtime/assembly-report.json";
+export const QA_OUTPUT_REL_PATH = "qa-output";
+
+// The target repo a packet builds into.
+export function targetRepoFor(packetPath, packet) {
+  const packetDir = dirname(resolve(packetPath));
+  const declared = packet?.assembly?.target_repo;
+  return typeof declared === "string" && declared.trim() ? resolve(packetDir, declared) : packetDir;
+}
+
+// The default location of every build sidecar a target repo carries.
+export function campaignSidecarPaths(targetRepo) {
+  return {
+    contextPath: join(targetRepo, BUILD_CONTEXT_REL_PATH),
+    reportPath: join(targetRepo, ASSEMBLY_REPORT_REL_PATH),
+    doctorOutPath: join(targetRepo, DOCTOR_SIDECAR_REL_PATH),
+    qaOutputDir: join(targetRepo, QA_OUTPUT_REL_PATH),
+  };
+}
+
+// The report a printed remediation must name, or null. `checkpoint waive`,
+// `theme waive` and `polish capture` all default to the packet-inferred
+// <target repo>/.campaign-runtime/assembly-report.json, so a command printed
+// for a report that came from anywhere else (--report, or a Build Context
+// binding) has to carry `--report <path>` or it acts on a different report —
+// possibly one that does not exist. Quiet in the common case: null when the
+// report IS that default, so the printed command stays short; the path when
+// it is not, or when the target repo is unknown and the default cannot be
+// ruled out. Doctor's report and the QA runner's both print through this.
+export function explicitReportPath(reportPath, targetRepo) {
+  if (typeof reportPath !== "string" || !reportPath) return null;
+  const inferred = typeof targetRepo === "string" && targetRepo ? campaignSidecarPaths(targetRepo).reportPath : null;
+  return reportPath !== inferred ? reportPath : null;
+}
+
+// Best-effort read of the Build Context for the report binding only: a
+// missing or malformed context binds nothing. A caller that must refuse a
+// malformed context reads it again strictly. Any other read failure (a
+// permission error, a directory where the file should be) is not absence:
+// binding the default report over it would record a stage outcome into a
+// report the campaign is not bound to, so it reaches the caller.
+function readContextForBinding(contextPath) {
+  if (!contextPath) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(contextPath, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch (error) {
+    if (absentOrMalformed(error)) return null;
+    throw error;
+  }
+}
+
+// The one resolver. `contextPath` / `reportPath` / `doctorOutPath` are the
+// operator's explicit choices, resolved by the caller from whichever flag it
+// owns: a string is used as given, `null` switches that sidecar off (no
+// context to bind from; `reportPath: null`), `undefined` derives the default.
+//
+// `followContextPointer` is required on purpose. The Build Context records
+// where prepare-build wrote the report (`--report-out`), relative to the
+// target repo. A stage that follows it acts on the report the campaign is
+// bound to; one that does not acts on the default sidecar. Both are
+// legitimate (doctor's stage write-back must not restate its outcome into a
+// report it did not inspect), but a stage that never said which is how the QA
+// stage came to be recorded into a report `next` never reads. Say it.
+//
+// A context binds a report for the packet it names: prepare-build writes
+// `packet_path` beside `report_path`, and when two packets of one campaign
+// share a target repo the default context belongs to whichever ran last, so
+// a pointer from a context naming another packet is not followed. A context
+// naming no packet binds by location, as it always did.
+export function resolveCampaignWorkspace(packetPath, {
+  packet = undefined,
+  contextPath = undefined,
+  reportPath = undefined,
+  doctorOutPath = undefined,
+  followContextPointer,
+} = {}) {
+  if (typeof followContextPointer !== "boolean") {
+    throw new TypeError("resolveCampaignWorkspace requires followContextPointer: true (act on the report the Build Context binds) or false (act on the default sidecar).");
+  }
+  const absolutePacketPath = resolve(packetPath);
+  const loadedPacket = packet === undefined ? JSON.parse(readFileSync(absolutePacketPath, "utf8")) : packet;
+  const baseDir = dirname(absolutePacketPath);
+  const targetRepo = targetRepoFor(absolutePacketPath, loadedPacket);
+  const defaults = campaignSidecarPaths(targetRepo);
+  const resolvedContextPath = contextPath === undefined ? defaults.contextPath : contextPath;
+  const context = followContextPointer ? readContextForBinding(resolvedContextPath) : null;
+  const recorded = typeof context?.report_path === "string" && context.report_path.trim() ? context.report_path.trim() : null;
+  const named = typeof context?.packet_path === "string" && context.packet_path.trim() ? context.packet_path.trim() : null;
+  // Both sides must be on disk: a pointer naming a packet that is not there
+  // cannot be shown to name this one.
+  const bound = recorded && (!named || sameFile(resolve(targetRepo, named), absolutePacketPath, { requireExisting: true }));
+
+  const resolvedReportPath = reportPath !== undefined
+    ? reportPath
+    : bound
+      ? resolve(targetRepo, recorded)
+      : defaults.reportPath;
+  return {
+    packet: loadedPacket,
+    packetPath: absolutePacketPath,
+    baseDir,
+    targetRepo,
+    contextPath: resolvedContextPath,
+    reportPath: resolvedReportPath,
+    defaultReportPath: defaults.reportPath,
+    doctorOutPath: doctorOutPath === undefined ? defaults.doctorOutPath : doctorOutPath,
+    qaOutputDir: defaults.qaOutputDir,
+  };
+}