@tokenoftrust/cli 2.0.27 → 2.1.0

package/src/commands/report.mjs

@@ -0,0 +1,308 @@
+/**
+ * `tot report go-live` — the merchant-facing go-live readiness report for one store.
+ *
+ *   tot report go-live --pages <dir> [--style <json>] [--workspace <dir>] [--out <md>]
+ *
+ * It is generated FROM measurements, never authored:
+ *
+ *   --pages <dir>  the page-check results for this store: each page's JSON from the devkit page
+ *                  checks (validate-page.sh and validate-page-browser.mjs, saved one file per run).
+ *                  A site-wide validation run's directory (site-summary.json + browser/) works too.
+ *   --style <json> the style-concept audit's JSON (default: <pages>/style.json when present).
+ *
+ * plus `tot validate` on the store itself, and the store's own records:
+ * `.tot/migration-state.json` (lifecycle, add-ons, commerce-sync and go-live confirmations) and
+ * `.tot/lighthouse-source-baseline.json` (the source site's pre-migration scores).
+ *
+ * Writes <out> (default <pages>/go-live-report.md) and its implementor companion
+ * <out>.internal.md. No network, no credentials: reproducible from the same inputs.
+ * Exit 0 written; 2 usage; 3 refused (no measurements to report on).
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { buildGoLiveReport, buildImplementorReport } from "../go-live-report.mjs";
+import { buildReadinessChecks } from "../readiness-checks.mjs";
+import { validateTenant, ERROR } from "../validate.mjs";
+import { fail } from "../errors.mjs";
+import { tenantDirSegments } from "../tenant-dirs.mjs";
+
+export const TEASER = "Site-wide validation with triage across every page, and the full migration method, are in the Agency Kit.";
+
+export const USAGE = `tot report go-live — the go-live readiness report for your store
+
+  tot report go-live --pages <dir>     report from your page-check results
+      [--style <json>]                 the style-concept audit's JSON (default <pages>/style.json)
+      [--workspace <dir>]              the store checkout (default: this checkout)
+      [--out <md>]                     where to write it (default <pages>/go-live-report.md)
+
+Save each page's JSON from the devkit page checks into <dir> first, e.g.
+  validate-page.sh <base> / > <dir>/home.json
+  validate-page-browser.mjs <base> / --provider cloudflare > <dir>/home.browser.json
+
+${TEASER}`;
+
+/** @param {string} p */
+function readJson(p) {
+  if (!p || !existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** @param {string[]} argv */
+export function parseArgs(argv) {
+  /** @type {Record<string, any>} */
+  const a = { sub: null, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const t = argv[i];
+    if (t === "--help" || t === "-h") { a.help = true; continue; }
+    if (!t.startsWith("--")) {
+      if (a.sub === null) { a.sub = t; continue; }
+      return { ...a, error: `unexpected argument: ${t}` };
+    }
+    const key = t.slice(2);
+    if (!["pages", "style", "workspace", "out", "state", "baseline", "tenant"].includes(key)) {
+      return { ...a, error: `unknown option: ${t}` };
+    }
+    const value = argv[i + 1];
+    if (!value || value.startsWith("--")) return { ...a, error: `missing value for ${t}` };
+    a[key] = value;
+    i += 1;
+  }
+  return a;
+}
+
+/** A gate's verdict as a page result carries it: true, false, or null when not measured. */
+function gateVerdict(gate) {
+  if (gate === true || gate === false) return gate;
+  if (!gate || typeof gate !== "object") return null;
+  if (gate.skipped === true || gate.applicable === false) return null;
+  return gate.pass === true ? true : gate.pass === false ? false : null;
+}
+
+/**
+ * Page-check JSON files → one result per slug. A page checked by both validate-page.sh and
+ * validate-page-browser.mjs appears in two files; their gates merge, so each gate is judged once.
+ * @param {{ file: string, json: any }[]} docs
+ */
+export function pageResultsFromDocs(docs) {
+  /** @type {Map<string, { slug: string, gates: Record<string, boolean|null>, perf: any }>} */
+  const bySlug = new Map();
+  for (const { file, json } of docs) {
+    if (!json || typeof json !== "object" || !json.gates || typeof json.gates !== "object") continue;
+    const slug = typeof json.slug === "string" ? json.slug : basename(file).replace(/\.json$/, "");
+    const entry = bySlug.get(slug) ?? { slug, gates: {}, perf: null };
+    for (const [name, gate] of Object.entries(json.gates)) {
+      const verdict = gateVerdict(gate);
+      const prior = entry.gates[name];
+      // A failure anywhere is a failure; a gate measured anywhere beats one not measured.
+      if (verdict === false || prior === undefined || prior === null) entry.gates[name] = verdict;
+    }
+    if (json.gates.perf && typeof json.gates.perf === "object" && !json.gates.perf.skipped) entry.perf = json.gates.perf;
+    bySlug.set(slug, entry);
+  }
+  return [...bySlug.values()].sort((x, y) => x.slug.localeCompare(y.slug));
+}
+
+/** The Lighthouse facts the report shows, from a page's perf gate. */
+function perfPage(slug, perf) {
+  return {
+    slug,
+    scores: perf.scores ?? {},
+    dimensions: perf.parity?.dimensions ?? {},
+    // Mobile and desktop are separate measurements judged against separate baselines.
+    profiles: Object.fromEntries(
+      Object.entries(perf.profiles ?? {}).map(([name, run]) => [name, {
+        scores: run?.scores ?? {},
+        dimensions: run?.parity?.dimensions ?? {},
+      }]),
+    ),
+    findings: perf.findings ?? [],
+    tolerance: perf.parity?.tolerance,
+    ceiling: perf.parity?.ceiling,
+  };
+}
+
+/** The store's own lint as a readiness check. */
+export function storeConfigCheck(lint) {
+  const errors = (lint?.findings ?? []).filter((f) => f.level === ERROR);
+  return {
+    area: "Store configuration",
+    status: lint ? (errors.length === 0 ? "PASS" : "FAIL") : "UNKNOWN",
+    why: "The store's content, theme and configuration must be valid for the platform to build and serve it.",
+    problem: !lint
+      ? "The store checkout could not be linted."
+      : errors.length === 0
+        ? "tot validate found no errors."
+        : `tot validate found ${errors.length} error(s): ${[...new Set(errors.map((f) => f.rule))].slice(0, 5).join(", ")}.`,
+    fix: "Run tot validate in the store checkout and fix each error it names.",
+  };
+}
+
+/**
+ * Everything the report needs, from a page-results directory. A site-wide run's summary is used as
+ * is; otherwise the checks are derived here from the single-page results.
+ * @param {{ pagesDir: string, stylePath?: string|null, lint?: any }} input
+ */
+export function evidenceFromDir({ pagesDir, stylePath = null, lint = null }) {
+  const summary = readJson(join(pagesDir, "site-summary.json"));
+  const styleJson = readJson(stylePath ?? join(pagesDir, "style.json"));
+  const browserDir = join(pagesDir, "browser");
+  const files = [
+    ...(existsSync(pagesDir) ? readdirSync(pagesDir).map((f) => join(pagesDir, f)) : []),
+    ...(existsSync(browserDir) ? readdirSync(browserDir).map((f) => join(browserDir, f)) : []),
+  ].filter((f) => f.endsWith(".json") && !/(^|\/)(site-summary|style)\.json$/.test(f));
+  const docs = files.map((file) => ({ file, json: readJson(file) }));
+  const results = pageResultsFromDocs(docs);
+  const pages = results.filter((r) => r.perf).map((r) => perfPage(r.slug, r.perf));
+  const style = summary?.style?.gates ?? styleJson?.gates ?? {};
+  const styleFacts = {
+    unsourcedComponents: style.ecommerceStyleGuide?.unsourcedComponents ?? [],
+    styleGuideApproved: (style.styleGuide?.approvedCurrentCount ?? 0) > 0,
+  };
+
+  if (summary) {
+    return {
+      measured: true,
+      generatedAt: summary.generatedAt ?? null,
+      checks: summary.readiness?.checks ?? [],
+      totals: summary.totals ?? {},
+      pages,
+      ...styleFacts,
+    };
+  }
+
+  const checks = results.length === 0 ? [] : [
+    storeConfigCheck(lint),
+    ...buildReadinessChecks({
+      aggregate: { pages: results, totals: { issues: { lowRiskOpen: 0 } } },
+      styleJson,
+      args: { manifest: "(none supplied to the style-concept audit)" },
+    }).filter((c) => c.area !== "Low-risk fix loop"),
+  ];
+  const failing = results.filter((r) => Object.values(r.gates).some((v) => v === false)).length;
+  return {
+    measured: results.length > 0,
+    generatedAt: null,
+    checks,
+    totals: { pages: results.length, passing: results.length - failing, failing, issues: {} },
+    pages,
+    ...styleFacts,
+  };
+}
+
+/** The store's records: lifecycle, add-ons, and the confirmations only a person can record. */
+export function readStoreState(statePath) {
+  const state = readJson(statePath);
+  const track = state?.tracks?.addons?.steps ?? state?.addons ?? [];
+  /** @type {Record<string, string>} */
+  const addOns = {};
+  for (const step of Array.isArray(track) ? track : []) {
+    if (step?.id) addOns[step.id] = step.status ?? "available";
+  }
+  return {
+    addOns,
+    lifecycle: state?.lifecycle ?? "hot-standby",
+    commerceSync: state?.commerceSync ?? {},
+    goLive: state?.goLive ?? {},
+  };
+}
+
+/** Resolve the store checkout the report is about. */
+function resolveStore(args, ctx) {
+  if (args.workspace) return resolve(args.workspace);
+  if (ctx?.mode === "checkout" && ctx.workspacePath) return ctx.workspacePath;
+  if (ctx?.mode === "monorepo" && args.tenant) return join(ctx.repoRoot, ...tenantDirSegments(args.tenant));
+  return null;
+}
+
+/** @param {string} dir */
+function storeTenant(dir) {
+  const config = readJson(join(dir, ".tot", "config.json"));
+  return typeof config?.tenant === "string" && config.tenant ? config.tenant : basename(dir);
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ * @param {{ out?: (s: string) => void, err?: (s: string) => void, now?: () => string }} [io]
+ */
+export function run(argv, ctx, io = {}) {
+  const out = io.out ?? ((s) => process.stdout.write(s));
+  const err = io.err ?? ((s) => process.stderr.write(s));
+  const now = io.now ?? (() => new Date().toISOString());
+  const args = parseArgs(argv);
+  if (args.help || (!args.sub && !args.error)) {
+    out(`${USAGE}\n`);
+    return args.help ? 0 : 2;
+  }
+  if (args.error) {
+    err(`${args.error}\n\n${USAGE}\n`);
+    return 2;
+  }
+  if (args.sub !== "go-live") {
+    err(`unknown report: ${args.sub}\n\n${USAGE}\n`);
+    return 2;
+  }
+  if (!args.pages) {
+    err(`${fail("missing --pages <dir>", "save each page's check JSON into a directory, then pass it as --pages")}\n`);
+    return 2;
+  }
+  const pagesDir = resolve(args.pages);
+  const store = resolveStore(args, ctx);
+  if (!store) {
+    err(`${fail("no store to report on", "run inside your store checkout, or pass --workspace <dir>")}\n`);
+    return 2;
+  }
+  const storeExists = existsSync(store);
+  const tenant = args.tenant ?? (storeExists ? storeTenant(store) : basename(store));
+  const lint = storeExists ? validateTenant(store, { tenantId: tenant, mode: args.workspace ? "workspace" : "monorepo" }) : null;
+  const evidence = evidenceFromDir({ pagesDir, stylePath: args.style ? resolve(args.style) : null, lint });
+  if (!evidence.measured) {
+    err(`${fail(
+      `no page-check results under ${pagesDir}`,
+      "run the page checks first and save their JSON there — a report without them would assert a readiness nobody measured",
+    )}\n`);
+    return 3;
+  }
+
+  const baseline = readJson(args.baseline ? resolve(args.baseline) : join(store, ".tot", "lighthouse-source-baseline.json"));
+  const { addOns, lifecycle, commerceSync, goLive } = readStoreState(
+    args.state ? resolve(args.state) : join(store, ".tot", "migration-state.json"),
+  );
+  const generatedAt = evidence.generatedAt ?? now();
+  const report = buildGoLiveReport({
+    tenant,
+    generatedAt,
+    lifecycle,
+    pages: evidence.pages,
+    checks: evidence.checks,
+    totals: evidence.totals,
+    unsourcedComponents: evidence.unsourcedComponents,
+    styleGuideApproved: evidence.styleGuideApproved,
+    addOns,
+    baselineRoutes: Object.keys(baseline?.results ?? {}).length,
+    baselineCapturedAt: baseline?.capturedAt ?? null,
+    commerceSync,
+    goLive,
+  });
+  const outPath = resolve(args.out ?? join(pagesDir, "go-live-report.md"));
+  mkdirSync(dirname(outPath), { recursive: true });
+  writeFileSync(outPath, report);
+  // The implementor's companion, always written alongside: the merchant document leaves out gate
+  // counts and tooling names, and that detail has to land somewhere.
+  const internalPath = `${outPath.replace(/\.md$/, "")}.internal.md`;
+  writeFileSync(internalPath, buildImplementorReport({
+    tenant,
+    generatedAt,
+    lifecycle,
+    checks: evidence.checks,
+    totals: evidence.totals,
+    pages: evidence.pages,
+    commerceSync,
+  }));
+  err(`wrote ${outPath}\nwrote ${internalPath}\n${TEASER}\n`);
+  return 0;
+}