@nextcommerce/campaigns-os 1.33.0

package/src/source-html-manifest.mjs

@@ -0,0 +1,276 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { ADAPTER_WRAPPER_POLICIES, isWrapperPolicy } from "./adapter-decision-contract.mjs";
+import { diagnoseSourceScreenshotRecord } from "./design-source-package.mjs";
+
+export const SOURCE_HTML_MANIFEST_REL_PATH = ".campaigns-os/source-html-manifest.json";
+export const SOURCE_HTML_MANIFEST_SCHEMA = "source-html-manifest/v0";
+
+export const SOURCE_HASH_PATTERN = /^[0-9a-f]{64}$/;
+const FILE_ROLES = new Set(["page", "partial", "layout", "asset", "export_log", "support"]);
+// The per-page keys the Design Source Package reads as source screenshot
+// proof (see design-source-package.mjs visualCandidatesFrom).
+const SCREENSHOT_RECORD_KEYS = Object.freeze(["screenshot_refs", "source_screenshot_refs", "screenshots"]);
+
+export function validateSourceHtmlManifest(manifest) {
+  const errors = [];
+  const warnings = [];
+  const add = (code, message) => errors.push({ code, message });
+  const addWarning = (code, message) => warnings.push({ code, message });
+
+  if (!isObject(manifest)) {
+    add("manifest.type", "Source HTML manifest must be a JSON object.");
+    return { ok: false, errors, warnings };
+  }
+
+  if (manifest.schema_version !== SOURCE_HTML_MANIFEST_SCHEMA) {
+    add("manifest.schema_version", `Expected schema_version "${SOURCE_HTML_MANIFEST_SCHEMA}".`);
+  }
+  if (manifest.generated_at != null && !isNonEmptyString(manifest.generated_at)) {
+    add("manifest.generated_at", "generated_at must be a non-empty string when present.");
+  }
+  if (manifest.generator != null && !isNonEmptyString(manifest.generator)) {
+    add("manifest.generator", "generator must be a non-empty string when present.");
+  }
+  if (manifest.campaign_slug != null && !isNonEmptyString(manifest.campaign_slug)) {
+    add("manifest.campaign_slug", "campaign_slug must be a non-empty string when present.");
+  }
+  if (manifest.root != null && !isNonEmptyString(manifest.root)) {
+    add("manifest.root", "root must be a non-empty string when present.");
+  }
+  // Operator channel for the document-wrapper policy: the same vocabulary the
+  // adapter contract records, declared by whoever hands over the source rather
+  // than only by the build stage. An unrecognized value is a WARNING, not an
+  // error: rejecting the manifest over one optional hint would throw away
+  // pages[], producer_provenance, and files[] and silently drop the run back
+  // to filesystem matching — a far larger loss than the key itself. The key is
+  // treated as unset instead, so the default policy applies.
+  if (manifest.wrapper_policy != null && !isWrapperPolicy(manifest.wrapper_policy)) {
+    addWarning(
+      "manifest.wrapper_policy",
+      `wrapper_policy ${JSON.stringify(manifest.wrapper_policy)} is not one of ${ADAPTER_WRAPPER_POLICIES.join(", ")}; ` +
+        `the key is ignored and the default "strip_document_wrappers" applies. The rest of the manifest is used as written.`,
+    );
+  }
+  if (manifest.producer_provenance != null) {
+    validateProducerProvenance(manifest.producer_provenance, add);
+  }
+  if (manifest.files != null) {
+    if (!Array.isArray(manifest.files)) {
+      add("manifest.files", "files must be an array when present.");
+    } else {
+      manifest.files.forEach((entry, index) => validateManifestFile(entry, index, add));
+    }
+  }
+
+  if (!Array.isArray(manifest.pages)) {
+    add("manifest.pages", "pages must be an array.");
+  } else {
+    manifest.pages.forEach((entry, index) => validateManifestPage(entry, index, add, addWarning));
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+// The manifest lives at SOURCE_HTML_MANIFEST_REL_PATH under the source root by
+// default. An explicit `manifestPath` (the `--design-manifest` flag) reads a
+// manifest from anywhere else instead — a source root nobody can write to
+// still gets its screenshot proof and skip declarations from a file the
+// operator owns. Wherever the manifest lives, its pages[].path and
+// files[].path stay relative to the source root, never to the manifest.
+export function readSourceHtmlManifestFile(sourceRoot, { manifestPath = null } = {}) {
+  const explicit = typeof manifestPath === "string" && manifestPath.trim() ? resolve(manifestPath) : null;
+  const resolvedPath = explicit || resolve(sourceRoot, SOURCE_HTML_MANIFEST_REL_PATH);
+  if (!existsSync(resolvedPath) || !statSync(resolvedPath).isFile()) {
+    return {
+      manifest: null,
+      path: explicit,
+      warning: explicit ? `Design manifest at ${explicit} does not exist or is not a file. Falling back to filesystem matching.` : null,
+      warnings: [],
+      validation: null,
+      explicit: Boolean(explicit),
+    };
+  }
+  return { ...readManifestAt(resolvedPath), explicit: Boolean(explicit) };
+}
+
+function readManifestAt(manifestPath) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    return {
+      manifest: null,
+      path: manifestPath,
+      warning: `Could not parse source-html manifest at ${manifestPath}: ${error.message}. Falling back to filesystem matching.`,
+      warnings: [],
+      validation: null,
+    };
+  }
+
+  const validation = validateSourceHtmlManifest(manifest);
+  if (!validation.ok) {
+    const detail = validation.errors.map((error) => `[${error.code}] ${error.message}`).join("; ");
+    return {
+      manifest: null,
+      path: manifestPath,
+      warning: `Source-html manifest at ${manifestPath} failed ${SOURCE_HTML_MANIFEST_SCHEMA} validation: ${detail}. Falling back to filesystem matching.`,
+      warnings: [],
+      validation,
+    };
+  }
+  // Non-fatal findings: the manifest is used as written and each one names the
+  // key, the value, and what happens instead.
+  const warnings = (validation.warnings || []).map(
+    (entry) => `Source-html manifest at ${manifestPath}: [${entry.code}] ${entry.message}`,
+  );
+  return { manifest, path: manifestPath, warning: null, warnings, validation };
+}
+
+function validateManifestPage(entry, index, add, addWarning = () => {}) {
+  const location = `manifest.pages[${index}]`;
+  if (!isObject(entry)) {
+    add(location, `${location} must be an object.`);
+    return;
+  }
+  if (!isNonEmptyString(entry.page_id)) {
+    add(`${location}.page_id`, `${location}.page_id is required and must be a non-empty string.`);
+  }
+  // A page entry binds either a source HTML file (path) or a declared
+  // out-of-scope skip (skip_reason) — exactly one. Skip-only entries are how
+  // a partial-source build declares template-derived pages per page.
+  const hasPath = isNonEmptyString(entry.path);
+  const hasSkipReason = isNonEmptyString(entry.skip_reason);
+  if (hasPath && hasSkipReason) {
+    add(`${location}.skip_reason`, `${location} declares both path and skip_reason; a page is either bound to a source file or declared out of source scope, not both.`);
+  } else if (!hasPath && !hasSkipReason) {
+    add(`${location}.path`, `${location} requires path (source HTML file) or skip_reason (declared out-of-scope page), and each must be a non-empty string.`);
+  }
+  for (const field of ["page_type", "page_url"]) {
+    if (entry[field] != null && !isNonEmptyString(entry[field])) {
+      add(`${location}.${field}`, `${location}.${field} must be a non-empty string when present.`);
+    }
+  }
+  if (entry.source_hash != null) {
+    if (!isNonEmptyString(entry.source_hash) || !SOURCE_HASH_PATTERN.test(entry.source_hash)) {
+      add(`${location}.source_hash`, `${location}.source_hash must be a 64-character lowercase sha256 hex string when present.`);
+    }
+  }
+  warnOnUnusableScreenshotRecords(entry, location, addWarning);
+}
+
+// Screenshot records are optional proof, so a malformed one is not a reason to
+// reject the manifest and fall the run back to filesystem matching. It is,
+// however, a reason to say something: without this the Design Source Package
+// drops the record and the operator sees a page missing desktop/mobile proof
+// with no hint that a record for it was authored. Same channel as the
+// wrapper_policy warning above, one warning per record naming the page, the
+// record index, the field, and what happens instead. The accept/reject test itself lives with the package builder, so
+// the warning cannot drift from the behaviour it describes.
+function warnOnUnusableScreenshotRecords(entry, location, addWarning) {
+  const pageId = isNonEmptyString(entry.page_id) ? entry.page_id : null;
+  for (const key of SCREENSHOT_RECORD_KEYS) {
+    const records = entry[key];
+    if (!Array.isArray(records)) continue;
+    records.forEach((record, index) => {
+      if (typeof record === "string") return;
+      const rejection = diagnoseSourceScreenshotRecord(record);
+      if (!rejection) return;
+      const recordLocation = `${location}.${key}[${index}]`;
+      addWarning(
+        `${recordLocation}.${rejection.field}`,
+        `${recordLocation}${pageId ? ` (page_id ${JSON.stringify(pageId)})` : ""} is ignored as source screenshot proof: ` +
+          `${rejection.detail}. ${rejection.fix}, or the page counts as having no source proof for that viewport. ` +
+          `The rest of the manifest is used as written.`,
+      );
+    });
+  }
+}
+
+function validateProducerProvenance(provenance, add) {
+  if (!isObject(provenance)) {
+    add("manifest.producer_provenance", "producer_provenance must be an object when present.");
+    return;
+  }
+
+  if (provenance.source_type != null && !isNonEmptyString(provenance.source_type)) {
+    add("manifest.producer_provenance.source_type", "producer_provenance.source_type must be a non-empty string when present.");
+  }
+  if (provenance.screenshot_fallback_used != null && typeof provenance.screenshot_fallback_used !== "boolean") {
+    add("manifest.producer_provenance.screenshot_fallback_used", "producer_provenance.screenshot_fallback_used must be a boolean when present.");
+  }
+  for (const field of ["generator_repo", "generator_version", "export_log", "figma_file_key", "material_fingerprint"]) {
+    if (provenance[field] != null && !isNonEmptyString(provenance[field])) {
+      add(`manifest.producer_provenance.${field}`, `producer_provenance.${field} must be a non-empty string when present.`);
+    }
+  }
+  if (provenance.material_fingerprint != null && !SOURCE_HASH_PATTERN.test(provenance.material_fingerprint)) {
+    add("manifest.producer_provenance.material_fingerprint", "producer_provenance.material_fingerprint must be a 64-character lowercase sha256 hex string when present.");
+  }
+  if (provenance.semantic_section_count != null && (!Number.isInteger(provenance.semantic_section_count) || provenance.semantic_section_count <= 0)) {
+    add("manifest.producer_provenance.semantic_section_count", "producer_provenance.semantic_section_count must be a positive integer when present.");
+  }
+  if (provenance.breakpoint_image_count != null && (!Number.isInteger(provenance.breakpoint_image_count) || provenance.breakpoint_image_count < 0)) {
+    add("manifest.producer_provenance.breakpoint_image_count", "producer_provenance.breakpoint_image_count must be a non-negative integer when present.");
+  }
+  if (provenance.figma_file_keys != null && !Array.isArray(provenance.figma_file_keys)) {
+    add("manifest.producer_provenance.figma_file_keys", "producer_provenance.figma_file_keys must be an array when present.");
+  }
+  if (provenance.section_exports != null) {
+    if (!Array.isArray(provenance.section_exports)) {
+      add("manifest.producer_provenance.section_exports", "producer_provenance.section_exports must be an array when present.");
+    } else {
+      provenance.section_exports.forEach((entry, index) => validateSectionExport(entry, index, add));
+    }
+  }
+}
+
+function validateSectionExport(entry, index, add) {
+  const location = `manifest.producer_provenance.section_exports[${index}]`;
+  if (!isObject(entry)) {
+    add(location, `${location} must be an object.`);
+    return;
+  }
+  for (const field of ["section", "type"]) {
+    if (!isNonEmptyString(entry[field])) {
+      add(`${location}.${field}`, `${location}.${field} is required and must be a non-empty string.`);
+    }
+  }
+  if (entry.node_ids != null && !isObject(entry.node_ids)) {
+    add(`${location}.node_ids`, `${location}.node_ids must be an object when present.`);
+  }
+  for (const field of ["images", "warnings"]) {
+    if (entry[field] != null && !Array.isArray(entry[field])) {
+      add(`${location}.${field}`, `${location}.${field} must be an array when present.`);
+    }
+  }
+}
+
+function validateManifestFile(entry, index, add) {
+  const location = `manifest.files[${index}]`;
+  if (!isObject(entry)) {
+    add(location, `${location} must be an object.`);
+    return;
+  }
+  if (!isNonEmptyString(entry.path)) {
+    add(`${location}.path`, `${location}.path is required and must be a non-empty string.`);
+  }
+  if (!isNonEmptyString(entry.role) || !FILE_ROLES.has(entry.role)) {
+    add(`${location}.role`, `${location}.role is required and must be one of ${[...FILE_ROLES].join(", ")}.`);
+  }
+  if (!isNonEmptyString(entry.sha256) || !SOURCE_HASH_PATTERN.test(entry.sha256)) {
+    add(`${location}.sha256`, `${location}.sha256 is required and must be a 64-character lowercase sha256 hex string.`);
+  }
+  if (entry.bytes != null && (!Number.isInteger(entry.bytes) || entry.bytes < 0)) {
+    add(`${location}.bytes`, `${location}.bytes must be a non-negative integer when present.`);
+  }
+}
+
+function isObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}

package/src/source-prep.mjs

@@ -0,0 +1,284 @@
+// Source preparation check (#262): deterministic classification of the common
+// unprepared-source failures the docs name as pre-build preparation steps —
+// unstripped document wrappers, leftover/broken YAML frontmatter, and internal
+// links still pointing at source files instead of CampaignSpec routes. The
+// scope is the certified template families' page-kit ingestion expectations
+// (docs/quickstart.md "Prepare Raw HTML Source", docs/source-adapters.md);
+// this is NOT a general HTML linter. Asset-path rooting stays owned by the
+// 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 { collectDocumentWrapperNames } from "./adapter-decision-contract.mjs";
+
+export const SOURCE_PREP_DOCUMENT_WRAPPER = "source_html.prep.document_wrapper";
+export const SOURCE_PREP_FRONTMATTER_RESIDUE = "source_html.prep.frontmatter_residue";
+export const SOURCE_PREP_INTERNAL_LINK_UNROOTED = "source_html.prep.internal_link_unrooted";
+
+export const SOURCE_PREP_CODES = Object.freeze([
+  SOURCE_PREP_DOCUMENT_WRAPPER,
+  SOURCE_PREP_FRONTMATTER_RESIDUE,
+  SOURCE_PREP_INTERNAL_LINK_UNROOTED,
+]);
+
+// Every code maps to the doc section that names the preparation step it
+// enforces. Keep these pointers in sync with the "Source preparation check"
+// section in docs/source-adapters.md.
+export const SOURCE_PREP_DOC_POINTERS = Object.freeze({
+  [SOURCE_PREP_DOCUMENT_WRAPPER]:
+    'docs/quickstart.md "Prepare Raw HTML Source" and docs/source-adapters.md "Source preparation check"',
+  [SOURCE_PREP_FRONTMATTER_RESIDUE]:
+    'docs/quickstart.md "Prepare Raw HTML Source" and docs/source-adapters.md "Source preparation check"',
+  [SOURCE_PREP_INTERNAL_LINK_UNROOTED]:
+    'docs/quickstart.md "Prepare Raw HTML Source" and docs/source-adapters.md "Source preparation check"',
+});
+
+// Page Kit frontmatter vocabulary used to recognize a leftover frontmatter
+// block embedded below content. A bare `---` pair with none of these keys is
+// left alone — that is content, not frontmatter, and classifying it would be
+// the general-HTML-linting scope this check refuses.
+const FRONTMATTER_KEY_PATTERN = /^(?:page_type|layout|permalink|title|description|next_url|decline_url|styles|scripts|meta)\s*:/;
+
+const FENCE_LINE = /^---\s*$/;
+const ANCHOR_HREF_PATTERN = /<a\b[^>]*?\bhref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi;
+const SKIP_PROTOCOL_PATTERN = /^(?:about|blob|data|javascript|mailto|tel):/i;
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function toPosixPath(value) {
+  return String(value || "").replaceAll("\\", "/");
+}
+
+function safeIsFile(path) {
+  try {
+    return existsSync(path) && statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Splits a page's leading YAML frontmatter (if any) from its body without
+ * parsing YAML. Returns fence state so the caller can classify a fence that
+ * never closes.
+ */
+function scanLeadingFrontmatter(lines) {
+  let index = 0;
+  while (index < lines.length && lines[index].trim() === "") index += 1;
+  if (index >= lines.length || !FENCE_LINE.test(lines[index])) {
+    return { present: false, unterminated: false, bodyStart: 0 };
+  }
+  for (let close = index + 1; close < lines.length; close += 1) {
+    if (FENCE_LINE.test(lines[close])) {
+      return { present: true, unterminated: false, bodyStart: close + 1 };
+    }
+  }
+  return { present: true, unterminated: true, bodyStart: lines.length };
+}
+
+function findEmbeddedFrontmatter(lines, bodyStart) {
+  const hits = [];
+  let open = -1;
+  for (let index = bodyStart; index < lines.length; index += 1) {
+    if (!FENCE_LINE.test(lines[index])) continue;
+    if (open === -1) {
+      open = index;
+      continue;
+    }
+    const block = lines.slice(open + 1, index);
+    if (block.some((line) => FRONTMATTER_KEY_PATTERN.test(line.trim()))) {
+      hits.push({ line: open + 1 });
+      open = -1;
+      continue;
+    }
+    // A fence pair without frontmatter keys is content; the closing fence may
+    // still open a real leftover block that follows it.
+    open = index;
+  }
+  // An opening fence below content whose frontmatter-key-shaped lines run to
+  // EOF without a closing fence is residue too — page-kit would render the
+  // fence and keys literally. A trailing keyless fence stays content.
+  let unterminated = null;
+  if (open !== -1 && lines.slice(open + 1).some((line) => FRONTMATTER_KEY_PATTERN.test(line.trim()))) {
+    unterminated = { line: open + 1 };
+  }
+  return { hits, unterminated };
+}
+
+function cleanHref(raw) {
+  const value = String(raw || "").trim();
+  if (!value || value.startsWith("#")) return null;
+  if (value.startsWith("{{") || value.startsWith("{%")) return null;
+  if (value.startsWith("//")) return null;
+  if (SKIP_PROTOCOL_PATTERN.test(value)) return null;
+  try {
+    const url = new URL(value);
+    if (url.protocol === "http:" || url.protocol === "https:") return null;
+  } catch {
+    // Relative and root-relative hrefs are the expected input.
+  }
+  return value.split("#")[0].split("?")[0].trim();
+}
+
+function collectSourceFileLinks({ content, sourceRoot, pagePath, mappedPaths }) {
+  const hits = [];
+  const seen = new Set();
+  const pageDir = dirname(resolve(sourceRoot, pagePath));
+  for (const match of String(content || "").matchAll(ANCHOR_HREF_PATTERN)) {
+    const cleaned = cleanHref(match[1] ?? match[2] ?? match[3]);
+    if (!cleaned || !/\.html?$/i.test(cleaned)) continue;
+    if (seen.has(cleaned)) continue;
+    const rootRelative = cleaned.startsWith("/");
+    const normalized = cleaned.replace(/^\/+/, "");
+    const candidatePaths = rootRelative
+      ? [resolve(sourceRoot, normalized)]
+      : [resolve(pageDir, cleaned), resolve(sourceRoot, normalized)];
+    const resolvesToSourceFile = candidatePaths.some((candidate) => safeIsFile(candidate));
+    const targetsMappedPage = mappedPaths.has(toPosixPath(normalized));
+    if (!resolvesToSourceFile && !targetsMappedPage) continue;
+    seen.add(cleaned);
+    hits.push(cleaned);
+  }
+  return hits;
+}
+
+function inspectPageContent({ content, sourceRoot, pagePath, mappedPaths }) {
+  const findings = [];
+  const wrappers = collectDocumentWrapperNames(content);
+  if (wrappers.length) {
+    findings.push({ code: SOURCE_PREP_DOCUMENT_WRAPPER, wrappers });
+  }
+
+  const lines = String(content || "").split(/\r?\n/);
+  const leading = scanLeadingFrontmatter(lines);
+  const embedded = findEmbeddedFrontmatter(lines, leading.bodyStart);
+  if (leading.unterminated) {
+    findings.push({ code: SOURCE_PREP_FRONTMATTER_RESIDUE, variant: "unterminated_leading_fence" });
+  }
+  if (embedded.hits.length) {
+    findings.push({
+      code: SOURCE_PREP_FRONTMATTER_RESIDUE,
+      variant: "embedded_block",
+      lines: embedded.hits.map((hit) => hit.line),
+    });
+  }
+  if (embedded.unterminated) {
+    findings.push({
+      code: SOURCE_PREP_FRONTMATTER_RESIDUE,
+      variant: "unterminated_embedded_block",
+      lines: [embedded.unterminated.line],
+    });
+  }
+
+  const sourceFileLinks = collectSourceFileLinks({ content, sourceRoot, pagePath, mappedPaths });
+  if (sourceFileLinks.length) {
+    findings.push({ code: SOURCE_PREP_INTERNAL_LINK_UNROOTED, hrefs: sourceFileLinks });
+  }
+  return findings;
+}
+
+function severityForCode(code, { wrapperPolicy }) {
+  if (code === SOURCE_PREP_DOCUMENT_WRAPPER) {
+    // preserve_document_wrappers is a recorded adapter decision, not silence —
+    // the finding stays visible but stops blocking, mirroring how the
+    // certification gate downgrades under a recorded waiver.
+    return wrapperPolicy === "preserve_document_wrappers" ? "warning" : "error";
+  }
+  if (code === SOURCE_PREP_FRONTMATTER_RESIDUE) return "error";
+  // Internal-link rewrites are sanctioned build-stage work recorded under
+  // cta_rewrite_policy; the adapter gates own the completed-assembly block.
+  return "warning";
+}
+
+function describeFinding(code, pages, { wrapperPolicy }) {
+  const docs = SOURCE_PREP_DOC_POINTERS[code];
+  const sample = pages.slice(0, 4);
+  const more = pages.length > 4 ? `; plus ${pages.length - 4} more page(s)` : "";
+  if (code === SOURCE_PREP_DOCUMENT_WRAPPER) {
+    const listed = sample.map((page) => `${page.path} (${page.wrappers.join(", ")})`).join("; ");
+    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 record wrapper_policy "preserve_document_wrappers" as an explicit adapter decision.${policyNote} See ${docs}.`;
+  }
+  if (code === SOURCE_PREP_FRONTMATTER_RESIDUE) {
+    const listed = sample.map((page) => {
+      const variants = page.variants.map((variant) => {
+        if (variant.variant === "unterminated_leading_fence") return "leading --- fence never closes";
+        if (variant.variant === "unterminated_embedded_block") {
+          return `frontmatter block opened below content at line ${variant.lines.join(", ")} never closes`;
+        }
+        return `frontmatter block embedded below content at line ${variant.lines.join(", ")}`;
+      });
+      return `${page.path} (${variants.join("; ")})`;
+    }).join("; ");
+    return `Mapped source HTML carries leftover or broken YAML frontmatter that page-kit would render literally or misparse: ${listed}${more}. Keep exactly one closed frontmatter block at the very top of the file (or none, when the packet's page_kit.frontmatter projection supplies it). See ${docs}.`;
+  }
+  const listed = sample.map((page) => `${page.path} -> ${page.hrefs.slice(0, 3).join(", ")}`).join("; ");
+  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}.`;
+}
+
+/**
+ * Evaluates the page-kit source-preparation expectations for every mapped
+ * source page. Deterministic: same files in, same findings out. Unreadable or
+ * missing page files are skipped here — source_html.pages.path owns those.
+ *
+ * @returns {{ checked_page_count: number, findings: Array<{code, severity, message, docs, pages}> }}
+ */
+export function evaluateSourcePreparation({ sourceRoot, pages = [], wrapperPolicy = null }) {
+  const mappedPaths = new Set(
+    pages
+      .map((page) => (isNonEmptyString(page?.path) ? toPosixPath(page.path) : null))
+      .filter(Boolean)
+  );
+  const byCode = new Map();
+  let checked = 0;
+
+  for (const page of pages) {
+    if (!isNonEmptyString(page?.path)) continue;
+    const fullPath = resolve(sourceRoot, page.path);
+    if (!safeIsFile(fullPath)) continue;
+    let content;
+    try {
+      content = readFileSync(fullPath, "utf8");
+    } catch {
+      continue;
+    }
+    checked += 1;
+    const pageFindings = inspectPageContent({ content, sourceRoot, pagePath: page.path, mappedPaths });
+    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 entry = pagesForCode.get(page.path);
+      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 || [] });
+    }
+  }
+
+  const findings = [...byCode.entries()]
+    .map(([code, pagesForCode]) => {
+      const pageList = [...pagesForCode.values()];
+      return {
+        code,
+        severity: severityForCode(code, { wrapperPolicy }),
+        message: describeFinding(code, pageList, { wrapperPolicy }),
+        docs: SOURCE_PREP_DOC_POINTERS[code],
+        pages: pageList.map((page) => ({
+          page_id: page.page_id,
+          path: page.path,
+          ...(page.wrappers.length ? { wrappers: page.wrappers } : {}),
+          ...(page.hrefs.length ? { hrefs: page.hrefs } : {}),
+          ...(page.variants.length ? { variants: page.variants } : {}),
+        })),
+      };
+    })
+    .sort((a, b) => SOURCE_PREP_CODES.indexOf(a.code) - SOURCE_PREP_CODES.indexOf(b.code));
+
+  return { checked_page_count: checked, findings };
+}