@tokenoftrust/cli 2.0.28 → 2.1.1

package/src/readiness-checks.mjs

@@ -0,0 +1,254 @@
+/**
+ * Readiness checks for a store, derived from per-page gate results and the style-concept audit.
+ *
+ * One page or every page: the same derivation serves `tot report go-live` for a single store and
+ * the Agency Kit's site-wide validation, so the two never describe a gate differently.
+ *
+ * A page result is `{ gates: { <gate>: true | false | null } }`: true passed, false failed, null
+ * not measured in this run.
+ */
+export function countGate(results, gateName) {
+  return results.reduce(
+    (counts, page) => {
+      const value = page.gates?.[gateName];
+      if (value === true) counts.pass += 1;
+      else if (value === false) counts.fail += 1;
+      else counts.unknown += 1;
+      return counts;
+    },
+    { pass: 0, fail: 0, unknown: 0, total: results.length },
+  );
+}
+
+export function combineStatus(counts, { unknownIsWarn = false } = {}) {
+  if (counts.fail > 0) return "FAIL";
+  if (counts.unknown > 0) return unknownIsWarn ? "WARN" : "UNKNOWN";
+  return "PASS";
+}
+
+export function combineCounts(...countsList) {
+  return countsList.reduce(
+    (out, counts) => ({
+      pass: out.pass + counts.pass,
+      fail: out.fail + counts.fail,
+      unknown: out.unknown + counts.unknown,
+      total: out.total + counts.total,
+    }),
+    { pass: 0, fail: 0, unknown: 0, total: 0 },
+  );
+}
+
+export function gateProblem(label, counts) {
+  if (counts.total === 0) return "No pages were discovered for validation.";
+  if (counts.fail > 0) return `${counts.fail}/${counts.total} ${label} gate checks failed.`;
+  if (counts.unknown > 0) return `${counts.unknown}/${counts.total} ${label} gate checks were not run in this pass.`;
+  return `All ${counts.total} page checks passed.`;
+}
+
+export function styleGuideCheck(styleJson, manifestPath) {
+  const gate = styleJson?.gates?.styleGuide;
+  const manifest = styleJson?.manifest;
+  const manifestPresent = manifest?.present === true;
+  if (!gate) {
+    return {
+      area: "Style guide",
+      status: "UNKNOWN",
+      why: "Business owners need one approved visual reference before the look is rolled across the sitemap.",
+      problem: "The style-guide gate was not produced by this validation run.",
+      fix: "Run the style-concept audit with the store manifest so the guide index and per-theme guide records can be checked.",
+    };
+  }
+  if (!manifestPresent) {
+    return {
+      area: "Style guide",
+      status: "FAIL",
+      why: "The style guide is the approved visual contract for brand, accessibility states, responsive behavior, and reusable page patterns.",
+      problem: `No migration manifest was found at ${manifestPath}, so style-guide readiness cannot be certified.`,
+      fix: "Create the migration manifest with styleGuideIndex and styleGuides records, then validate the preview guide pages.",
+    };
+  }
+  if (!gate.present) {
+    return {
+      area: "Style guide",
+      status: "FAIL",
+      why: "Without a guide, page workers can create inconsistent layouts and business reviewers have no single source of truth.",
+      problem: "No preview-only style-guide index and standalone theme guide records are present.",
+      fix: "Create a preview-only guide index plus one standalone guide per theme; mark them noindex and sitemap-excluded.",
+    };
+  }
+  if (!gate.pass) {
+    const missingGuides = gate.themesMissingStandaloneGuide?.length ?? 0;
+    const missingLinks = gate.indexMissingThemeLinks?.length ?? 0;
+    const guideProblems = gate.problems?.length ?? 0;
+    return {
+      area: "Style guide",
+      status: "FAIL",
+      why: "The approved guide prevents brand drift and gives compliance/business reviewers a concrete preview before broad propagation.",
+      problem: `Index ${gate.indexRoute ?? "missing"} has ${gate.approvedCurrentCount ?? 0} approved current guide(s), ${missingGuides} theme(s) without standalone guides, ${missingLinks} missing index link(s), and ${guideProblems} protection/status problem(s).`,
+      fix: "Link every current/candidate/legacy theme from the index, keep all guide pages preview-only/noindex/out of sitemap, validate them, then approve the current guide.",
+    };
+  }
+  return {
+    area: "Style guide",
+    status: "PASS",
+    why: "The approved guide gives business, design, and engineering reviewers the same reference before remaining pages are restyled.",
+    problem: `Index ${gate.indexRoute} links ${gate.indexLinksToThemeIds?.length ?? 0} theme guide(s); ${gate.approvedCurrentCount ?? 0} current guide is approved.`,
+    fix: "Keep the guide updated when tokens, components, or approved page patterns change.",
+  };
+}
+
+export function styleQualityCheck(styleJson) {
+  const gates = styleJson?.gates;
+  if (!gates) {
+    return {
+      area: "Theme/CSS quality",
+      status: "UNKNOWN",
+      why: "Readable shared CSS makes future page work cheaper and reduces visual drift.",
+      problem: "The style audit did not produce gate output.",
+      fix: "Run the style-concept audit again and inspect its gate output.",
+    };
+  }
+  const failed = [
+    "schema",
+    "storyboard",
+    "theme",
+    "css",
+    "readability",
+    "manifestConventions",
+    "acceptedRisks",
+    "styleConcept",
+    "tokenContrast",
+    "guideCoverage",
+  ].filter((name) => gates[name] && gates[name].pass !== true);
+  return {
+    area: "Theme/CSS quality",
+    status: failed.length > 0 ? "FAIL" : "PASS",
+    why: "A shared, readable tenant theme lets the site be maintained without copying large CSS blobs page by page.",
+    problem:
+      failed.length > 0
+        ? `Failing style gates: ${failed.join(", ")}.`
+        : "Theme record, CSS structure, readability, and style-concept drift gates passed.",
+    fix:
+      failed.length > 0
+        ? "Record storyboard/inspiration policy, extract shared tenant CSS, reduce page-local inline CSS, format source for human review, fix text-token contrast/guide coverage, and update manifest hashes/conformance."
+        : "Re-run after any theme or page restyle change.",
+  };
+}
+
+export function ecommerceStyleGuideCheck(styleJson) {
+  const gate = styleJson?.gates?.ecommerceStyleGuide;
+  if (!gate) {
+    return {
+      area: "Ecommerce style-guide bar",
+      status: "UNKNOWN",
+      why: "High-converting ecommerce themes need mobile ergonomics, accessible states, trust patterns, clear CTAs, and speed budgets before broad propagation.",
+      problem: "The ecommerce style-guide gate was not produced by this validation run.",
+      fix: "Run the style-concept audit with the store manifest.",
+    };
+  }
+  // Components that exist in the guide only as marked placeholders. Named here because they need
+  // MERCHANT evidence, not a code change, and the difference decides who the row is addressed to.
+  // Without naming them the row reads as a theme-CSS task and the real blocker stays invisible
+  // until somebody opens the rendered guide — which is how it was found the first time.
+  const unsourced = gate.unsourcedComponents ?? [];
+  if (!gate.pass) {
+    return {
+      area: "Ecommerce style-guide bar",
+      status: "FAIL",
+      why: "This is the v1.1 hardening checkpoint for accessibility-as-conversion, mobile tap targets, trust/social-proof components, semantic tokens, accessible forms, CTA hierarchy, and performance.",
+      problem:
+        `Required ${gate.requiredVersion ?? "v1.1"} status is ${gate.status ?? "missing"} with ` +
+        `${gate.problemCount ?? 0} theme quality problem(s).` +
+        (unsourced.length > 0
+          ? ` ${unsourced.length} component(s) appear in the style guide ONLY as marked placeholders` +
+            ` and need merchant-supplied evidence: ${unsourced.join(", ")}.`
+          : ""),
+      fix:
+        unsourced.length > 0
+          ? "Source the placeholder components from the merchant (real ratings, badges, guarantees, testimonials, logos) before approving. The claimsPolicy forbids fabricating them, so this is a content-gathering task, not a theme-CSS one. Then update theme CSS/descriptor for any remaining quality problems and mark the bar approved."
+          : "App/content lane should update the theme CSS, descriptor, and style-guide examples, then mark the ecommerce quality bar approved after validation. Do not fabricate ratings, badges, or guarantees.",
+    };
+  }
+  return {
+    area: "Ecommerce style-guide bar",
+    status: "PASS",
+    why: "The theme/style guide has the conversion-critical patterns needed before applying the look across the sitemap.",
+    problem: `${gate.requiredVersion ?? "v1.1"} is approved and current theme quality checks passed.`,
+    fix: "Keep this gate current when CTA, form, trust, token, or motion patterns change.",
+  };
+}
+
+export function buildReadinessChecks({ aggregate, styleJson, args }) {
+  const results = aggregate.pages;
+  const render = countGate(results, "render");
+  const boundary = countGate(results, "boundary");
+  const seo = combineCounts(countGate(results, "seo"), countGate(results, "sitemap"));
+  const secrets = countGate(results, "secrets");
+  const csp = countGate(results, "csp");
+  const mobileUx = combineCounts(countGate(results, "mobile"), countGate(results, "ux"));
+  const a11y = countGate(results, "a11y");
+  const perf = countGate(results, "perf");
+  const lowRisk = aggregate.totals.issues.lowRiskOpen ?? 0;
+
+  return [
+    styleGuideCheck(styleJson, args.manifest),
+    ecommerceStyleGuideCheck(styleJson),
+    styleQualityCheck(styleJson),
+    {
+      area: "Product boundary",
+      status: combineStatus(boundary),
+      why: "The marketing site must not accidentally expose catalog, cart, checkout, saved, search, price, inventory, or offer behavior.",
+      problem: gateProblem("boundary", boundary),
+      fix: "Keep commerce routes reserved/404 for marketing tenants and remove or reclassify product-offer leaks.",
+    },
+    {
+      area: "Route availability",
+      status: combineStatus(render),
+      why: "Business reviewers and crawlers need each launch page to resolve reliably.",
+      problem: gateProblem("render", render),
+      fix: "Fix routing/content-provider errors, then rerun validation for failed slugs.",
+    },
+    {
+      area: "SEO and sitemap",
+      status: combineStatus(seo),
+      why: "Search engines and social previews depend on canonical URLs, descriptions, structured data, and a clean sitemap.",
+      problem: gateProblem("SEO/sitemap", seo),
+      fix: "Restore required head tags, canonical handling, JSON-LD, and sitemap entries while keeping commerce URLs out.",
+    },
+    {
+      area: "Security and CSP",
+      status: combineStatus(combineCounts(secrets, csp), { unknownIsWarn: true }),
+      why: "A clean CSP and zero secrets reduce launch risk and protect the tenant brand.",
+      problem: `${gateProblem("secret", secrets)} ${gateProblem("CSP", csp)}`,
+      fix: "Remove private tokens and fix violating scripts/styles without weakening CSP with unsafe allowances.",
+    },
+    {
+      area: "Accessibility",
+      status: combineStatus(a11y),
+      why: "Accessible pages are easier to use, reduce legal risk, and matter especially for trust/compliance-oriented buyers.",
+      problem: gateProblem("a11y", a11y),
+      fix: "Run browser validation, then fix contrast, semantics, keyboard flow, and reduced-motion issues.",
+    },
+    {
+      area: "Performance",
+      status: combineStatus(perf),
+      why: "Mobile performance affects conversion, perceived trust, and search quality.",
+      problem: gateProblem("performance", perf),
+      fix: "Run browser validation, then reduce main-thread JS, reserve layout space, and optimize blocking resources.",
+    },
+    {
+      area: "Mobile and UX",
+      status: combineStatus(mobileUx),
+      why: "Most reviewers and customers will scan the site on smaller screens before trusting it.",
+      problem: gateProblem("mobile/UX", mobileUx),
+      fix: "Fix viewport, overflow, tap-target, image-alt, landmark, form-label, and mixed-content issues.",
+    },
+    {
+      area: "Low-risk fix loop",
+      status: lowRisk > 0 ? "WARN" : "PASS",
+      why: "Small safe fixes should be drained before asking owners to accept bigger design or performance tradeoffs.",
+      problem: lowRisk > 0 ? `${lowRisk} open low-risk issue(s) remain.` : "No open low-risk issues were reported.",
+      fix: "Assign bounded low-risk issues, append fix-log rows, rerun validation, and repeat until zero remain.",
+    },
+  ];
+}