website-xp-phone 2.2.1 → 2.2.11

package/scripts/verify-policy.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * CI drift gate for the checksums pipeline.
+ *
+ * Reads the sidecar `public/documents/drift-report.json` that
+ * write-dist-checksums.mjs emits during the build and fails when the
+ * build observed genuine STABLE-invariant drift relative to the live
+ * deployment baseline:
+ *
+ *   - a non-empty `violations` array (content drift or an artifact that
+ *     could not be verified against the live counterpart), or
+ *   - a corrupt/inconsistent report (`violationCount` disagreeing with
+ *     the `violations` array, reconciled resolutions inside `violations`,
+ *     missing fields) — the gate fails closed on those.
+ *
+ * Rebuild noise that write-dist-checksums.mjs already reconciled against
+ * the live deployment (`rehash-only`, `live-match`) is NOT a failure; it
+ * is printed for observability only.
+ *
+ * The gate runs in CI (where the remote baseline is reachable) rather
+ * than only locally.  On pull requests it runs in advisory mode so that
+ * legitimate content edits under review do not block CI — pass
+ * `--nonblocking` (or set `VERIFY_POLICY_NONBLOCKING=1`) to downgrade
+ * genuine-drift findings to warnings.  A missing or corrupt report is
+ * always a hard failure: an indefinite signal cannot gate anything.
+ */
+
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const projectRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const driftReportPath = resolve(
+  projectRoot,
+  "public",
+  "documents",
+  "drift-report.json",
+);
+
+/** Reconciled resolutions must never appear inside `violations`. */
+const RECONCILED_RESOLUTIONS = new Set(["rehash-only", "live-match"]);
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Decode the drift report.  Unknown shape fails closed.
+ * Returns `{ ok: true, report }` or `{ ok: false, issues }`.
+ */
+export function decodeReport(value) {
+  if (!isRecord(value)) {
+    return { ok: false, issues: ["drift report is not a JSON object"] };
+  }
+
+  const issues = [];
+  const { baselineUrl, generatedAt, violationCount, violations } = value;
+
+  if (typeof baselineUrl !== "string" || baselineUrl.length === 0) {
+    issues.push("baselineUrl is missing or not a non-empty string");
+  }
+  if (typeof generatedAt !== "string" || generatedAt.length === 0) {
+    issues.push("generatedAt is missing or not a non-empty string");
+  }
+  if (
+    typeof violationCount !== "number" ||
+    !Number.isInteger(violationCount) ||
+    violationCount < 0
+  ) {
+    issues.push("violationCount is missing or not a non-negative integer");
+  }
+  if (!Array.isArray(violations)) {
+    issues.push("violations is missing or not an array");
+  }
+  if (issues.length > 0) {
+    return { ok: false, issues };
+  }
+
+  for (const [index, entry] of violations.entries()) {
+    if (!isRecord(entry) || typeof entry.relPath !== "string") {
+      issues.push(`violations[${index}] has no relPath`);
+      continue;
+    }
+    if (typeof entry.resolution !== "string") {
+      issues.push(`violations[${index}] (${entry.relPath}) has no resolution`);
+    }
+  }
+  if (violationCount !== violations.length) {
+    issues.push(
+      `violationCount (${violationCount}) does not match ` +
+        `violations length (${violations.length})`,
+    );
+  }
+
+  return issues.length === 0
+    ? {
+        ok: true,
+        report: { baselineUrl, generatedAt, violationCount, violations },
+      }
+    : { ok: false, issues };
+}
+
+/**
+ * Evaluate a decoded report.  Returns `{ ok, reasons }` where `reasons`
+ * is empty exactly when there is no genuine drift.
+ */
+export function evaluateReport(report) {
+  const reasons = [];
+  for (const entry of report.violations) {
+    if (RECONCILED_RESOLUTIONS.has(entry.resolution)) {
+      reasons.push(
+        `${entry.relPath}: reconciled resolution "${entry.resolution}" ` +
+          `must not appear in violations (generator regression)`,
+      );
+      continue;
+    }
+    const note = entry.note ? ` — ${entry.note}` : "";
+    reasons.push(
+      `${entry.relPath}: ${entry.status ?? "unknown"} ${entry.resolution}${note}`,
+    );
+  }
+  return { ok: reasons.length === 0, reasons };
+}
+
+function observabilityLines(report) {
+  const rehashOnly = Array.isArray(report.rehashOnly) ? report.rehashOnly : [];
+  const liveMatched = Array.isArray(report.liveMatched)
+    ? report.liveMatched
+    : [];
+  return [
+    `rebuild noise reconciled against live: ${rehashOnly.length} rehash-only, ` +
+      `${liveMatched.length} live-match (not drift)`,
+  ];
+}
+
+async function main() {
+  const nonblocking =
+    process.argv.includes("--nonblocking") ||
+    process.env.VERIFY_POLICY_NONBLOCKING === "1";
+
+  let raw;
+  try {
+    raw = await readFile(driftReportPath, "utf8");
+  } catch {
+    process.stderr.write(
+      `Drift policy FAIL — drift report not found at ${driftReportPath}. ` +
+        `The build pipeline (write-dist-checksums.mjs) must run first so ` +
+        `the gate consumes a definite signal.\n`,
+    );
+    process.exit(1);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    process.stderr.write(
+      `Drift policy FAIL — drift report at ${driftReportPath} is not valid ` +
+        `JSON: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    process.exit(1);
+  }
+
+  const decoded = decodeReport(parsed);
+  if (!decoded.ok) {
+    process.stderr.write(
+      `Drift policy FAIL — drift report at ${driftReportPath} failed validation:\n` +
+        decoded.issues.map((issue) => `  ${issue}`).join("\n") +
+        "\n",
+    );
+    process.exit(1);
+  }
+
+  const { report } = decoded;
+  const evaluation = evaluateReport(report);
+  const observability = observabilityLines(report).map((line) => `  ${line}`);
+
+  if (evaluation.ok) {
+    process.stdout.write(
+      `Drift policy PASS — ${report.violationCount} violation(s) vs ${report.baselineUrl}\n` +
+        `${observability.join("\n")}\n` +
+        `Report generated at ${report.generatedAt}\n`,
+    );
+    process.exit(0);
+  }
+
+  const verdict = nonblocking ? "WARN (nonblocking)" : "FAIL";
+  const stream = nonblocking ? process.stdout : process.stderr;
+  stream.write(
+    `Drift policy ${verdict} — ${report.violationCount} genuine drift ` +
+      `artifact(s) vs ${report.baselineUrl}:\n` +
+      evaluation.reasons.map((reason) => `  ${reason}`).join("\n") +
+      "\n" +
+      `${observability.join("\n")}\n` +
+      `Report generated at ${report.generatedAt}\n`,
+  );
+  process.exit(nonblocking ? 0 : 1);
+}
+
+const invokedDirectly =
+  process.argv[1] !== undefined &&
+  pathToFileURL(process.argv[1]).href === import.meta.url;
+
+if (invokedDirectly) {
+  main();
+}

package/scripts/write-dist-checksums.mjs

@@ -18,14 +18,18 @@
  */
 import { createHash } from "node:crypto";
 import {
-    copyFile,
-    mkdir,
-    readdir,
-    readFile,
-    writeFile,
+  copyFile,
+  mkdir,
+  readdir,
+  readFile,
+  writeFile,
 } from "node:fs/promises";
 import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  canonicalizeAssetRefs,
+  isCanonicalizablePath,
+} from "./asset-reference.mjs";
 import { isMutablePath, MUTABLE_PATH_SET } from "./mutable-assets.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -46,30 +50,100 @@ const driftReportPath = resolve(publicRoot, "documents", "drift-report.json");
 
 /** Where the previous deployment's manifest lives. */
 const REMOTE_CHECKSUMS_URL =
-    process.env.CHECKSUMS_URL || "https://akinevz.com/checksums.txt";
+  process.env.CHECKSUMS_URL || "https://akinevz.com/checksums.txt";
+
+/** Directory of the remote manifest; built artifacts are fetched here. */
+const REMOTE_BASE_URL = REMOTE_CHECKSUMS_URL.replace(/checksums\.txt$/, "");
 
 async function walk(dirPath) {
-    const entries = await readdir(dirPath, { withFileTypes: true });
-    const files = [];
-
-    for (const entry of entries) {
-        const fullPath = resolve(dirPath, entry.name);
-        if (entry.isDirectory()) {
-            files.push(...(await walk(fullPath)));
-            continue;
-        }
-
-        if (entry.isFile()) {
-            files.push(fullPath);
-        }
+  const entries = await readdir(dirPath, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = resolve(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await walk(fullPath)));
+      continue;
     }
 
-    return files;
+    if (entry.isFile()) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+async function sha256Text(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+/**
+ * Fetch the previously deployed counterpart of a built artifact.
+ *
+ * Returns null when the remote is unreachable or the file does not exist
+ * there yet — the caller then treats the artifact as unverifiable.
+ */
+async function fetchLiveCounterpart(relPath, cache) {
+  if (cache.has(relPath)) {
+    return cache.get(relPath);
+  }
+
+  let live = null;
+  if (typeof fetch === "function") {
+    try {
+      const response = await fetch(`${REMOTE_BASE_URL}${encodeURI(relPath)}`, {
+        cache: "no-store",
+        headers: { Accept: "text/plain" },
+      });
+      if (response.ok) {
+        live = await response.text();
+      }
+    } catch {
+      live = null;
+    }
+  }
+  cache.set(relPath, live);
+  return live;
 }
 
-async function sha256File(filePath) {
-    const content = await readFile(filePath, "utf8");
-    return createHash("sha256").update(content).digest("hex");
+/**
+ * Decide whether a non-STABLE non-mutable artifact actually drifted.
+ *
+ * Vite rebuilds every HTML entry page whenever any bundle's content hash
+ * changes, so raw byte comparison reports false drift on unchanged pages.
+ * Two false-positive classes are resolved against the live deployment:
+ *
+ *   - "live-match": the artifact is byte-identical to the live file but
+ *     the baseline manifest predates it (baseline staleness).
+ *   - "rehash-only": the page differs only in the content-hashed asset
+ *     references Vite re-injects at build time.
+ *
+ * Anything else — including an unfetchable counterpart — is treated as
+ * real drift, the loud failure mode.
+ */
+function classifyDrift({ relPath, localText, liveText }) {
+  const localCanonical = isCanonicalizablePath(relPath)
+    ? canonicalizeAssetRefs(localText)
+    : localText;
+
+  if (liveText === null) {
+    return {
+      drift: true,
+      resolution: "unverifiable",
+      note: "no counterpart at the baseline URL",
+    };
+  }
+
+  if (localText === liveText) {
+    return { drift: false, resolution: "live-match" };
+  }
+
+  if (localCanonical === canonicalizeAssetRefs(liveText)) {
+    return { drift: false, resolution: "rehash-only" };
+  }
+
+  return { drift: true, resolution: "content-drift" };
 }
 
 /**
@@ -78,142 +152,184 @@ async function sha256File(filePath) {
  * Two or more spaces separate the digest from the path.
  */
 function parseChecksumsText(text) {
-    const entries = new Map();
-
-    for (const line of text.split(/\r?\n/)) {
-        const trimmed = line.trim();
-        if (!trimmed) {
-            continue;
-        }
+  const entries = new Map();
 
-        const [digest, relPath] = trimmed.split(/\s{2,}/);
-        if (!digest || !relPath) {
-            continue;
-        }
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
 
-        entries.set(relPath, digest);
+    const [digest, relPath] = trimmed.split(/\s{2,}/);
+    if (!digest || !relPath) {
+      continue;
     }
 
-    return entries;
+    entries.set(relPath, digest);
+  }
+
+  return entries;
 }
 
 async function readRemoteChecksums() {
-    if (typeof fetch !== "function") {
-        return new Map();
-    }
+  if (typeof fetch !== "function") {
+    return new Map();
+  }
 
-    try {
-        const response = await fetch(REMOTE_CHECKSUMS_URL, {
-            cache: "no-store",
-            headers: { Accept: "text/plain" },
-        });
-        if (!response.ok) {
-            return new Map();
-        }
-        const text = await response.text();
-        return parseChecksumsText(text);
-    } catch {
-        return new Map();
+  try {
+    const response = await fetch(REMOTE_CHECKSUMS_URL, {
+      cache: "no-store",
+      headers: { Accept: "text/plain" },
+    });
+    if (!response.ok) {
+      return new Map();
     }
+    const text = await response.text();
+    return parseChecksumsText(text);
+  } catch {
+    return new Map();
+  }
 }
 
 async function run() {
-    const files = await walk(distRoot);
-    const existing = await readRemoteChecksums();
-    const rows = [];
-    let index = 0;
-    const driftViolations = [];
-
-    for (const filePath of files.sort()) {
-        // Skip the manifest file itself so it doesn't appear in its own diff.
-        if (filePath === distChecksumsPath) {
-            continue;
-        }
-
-        const digest = await sha256File(filePath);
-        const relPath = relative(distRoot, filePath).replace(/\\/g, "/");
-        const previous = existing.get(relPath);
-        const status = !previous
-            ? "NEW"
-            : previous === digest
-                ? "STABLE"
-                : "CHANGED";
-        const mutable = isMutablePath(relPath);
-        index += 1;
-
-        process.stdout.write(
-            `${String(index).padStart(3, "0")}. [${status}] ${relPath}${mutable ? " (mutable)" : ""}\n` +
-            `     prev: ${previous ?? "(none)"}\n` +
-            `     next: ${digest}\n`,
-        );
-
-        // Drift gate: a non-mutable artifact MUST be STABLE relative to the
-        // remote baseline.  A mutable artifact may be STABLE, CHANGED, or NEW.
-        if (!mutable && status !== "STABLE") {
-            driftViolations.push({
-                relPath,
-                status,
-                prev: previous ?? null,
-                next: digest,
-            });
-        }
-
-        rows.push(`${digest}  ${relPath}`);
+  const files = await walk(distRoot);
+  const existing = await readRemoteChecksums();
+  const rows = [];
+  let index = 0;
+  const driftViolations = [];
+  const rehashOnly = [];
+  const liveMatched = [];
+  const liveCounterparts = new Map();
+
+  for (const filePath of files.sort()) {
+    // Skip the manifest file itself so it doesn't appear in its own diff.
+    if (filePath === distChecksumsPath) {
+      continue;
     }
 
-    // Always emit a drift report so verify-policy can consume a definite
-    // signal rather than relying on file presence.
-    const driftReport = JSON.stringify(
-        {
-            baselineUrl: REMOTE_CHECKSUMS_URL,
-            generatedAt: new Date().toISOString(),
-            mutablePaths: [...MUTABLE_PATH_SET],
-            violationCount: driftViolations.length,
-            violations: driftViolations,
-        },
-        null,
-        2,
+    const localText = await readFile(filePath, "utf8");
+    const digest = await sha256Text(localText);
+    const relPath = relative(distRoot, filePath).replace(/\\/g, "/");
+    const previous = existing.get(relPath);
+    const status = !previous
+      ? "NEW"
+      : previous === digest
+        ? "STABLE"
+        : "CHANGED";
+    const mutable = isMutablePath(relPath);
+    index += 1;
+
+    process.stdout.write(
+      `${String(index).padStart(3, "0")}. [${status}] ${relPath}${mutable ? " (mutable)" : ""}\n` +
+        `     prev: ${previous ?? "(none)"}\n` +
+        `     next: ${digest}\n`,
     );
-    await writeFile(driftReportPath, `${driftReport}\n`, "utf8");
-
-    if (driftViolations.length > 0) {
-        const lines = driftViolations.map(
-            (v) => `  ${v.relPath}: ${v.status} (prev=${v.prev ?? "(none)"})`,
-        );
-        process.stderr.write(
-            `Drift gate failed — ${driftViolations.length} non-mutable artifact(s) changed ` +
-            `vs ${REMOTE_CHECKSUMS_URL}:\n${lines.join("\n")}\n`,
-        );
-    }
 
-    const manifest = `${rows.join("\n")}\n`;
+    // Drift gate: a non-mutable artifact MUST be STABLE relative to the
+    // remote baseline.  A mutable artifact may be STABLE, CHANGED, or NEW.
+    //
+    // Rebuild noise is resolved against the live deployment before it is
+    // counted as a violation: Vite re-injects content-hashed asset refs
+    // into every HTML entry page, and the baseline manifest can lag the
+    // live site, so raw byte comparison alone reports false drift.
+    if (!mutable && status !== "STABLE") {
+      const liveText = await fetchLiveCounterpart(relPath, liveCounterparts);
+      const drift = classifyDrift({ relPath, localText, liveText });
 
-    // Write the deployed copy (`dist/checksums.txt`) and the source copy
-    // (`public/checksums.txt`) so the next git commit and the next Render
-    // deploy both carry the new manifest.
-    await mkdir(distRoot, { recursive: true });
-    await mkdir(publicRoot, { recursive: true });
-    await writeFile(distChecksumsPath, manifest, "utf8");
-    await writeFile(publicChecksumsPath, manifest, "utf8");
+      if (drift.drift) {
+        driftViolations.push({
+          relPath,
+          status,
+          prev: previous ?? null,
+          next: digest,
+          resolution: drift.resolution,
+          ...(drift.note ? { note: drift.note } : {}),
+        });
+      } else if (drift.resolution === "rehash-only") {
+        rehashOnly.push(relPath);
+      } else {
+        liveMatched.push(relPath);
+      }
+
+      process.stdout.write(`     drift: ${drift.resolution}\n`);
+    }
 
-    // Belt-and-braces: if Vite ever changes how it copies `public/`, the
-    // `dist/` copy is the authoritative served artifact, so a final copy
-    // keeps the two in sync even if `public/checksums.txt` was deleted
-    // before the build ran.
-    await copyFile(publicChecksumsPath, distChecksumsPath).catch(() => { });
+    rows.push(`${digest}  ${relPath}`);
+  }
 
+  // Always emit a drift report so verify-policy can consume a definite
+  // signal rather than relying on file presence.  `violations` contains
+  // only genuine content drift; rebuild noise that was reconciled against
+  // the live deployment is recorded separately for observability.
+  const driftReport = JSON.stringify(
+    {
+      baselineUrl: REMOTE_CHECKSUMS_URL,
+      generatedAt: new Date().toISOString(),
+      mutablePaths: [...MUTABLE_PATH_SET],
+      violationCount: driftViolations.length,
+      violations: driftViolations,
+      rehashOnlyCount: rehashOnly.length,
+      rehashOnly,
+      liveMatchCount: liveMatched.length,
+      liveMatched,
+    },
+    null,
+    2,
+  );
+  await writeFile(driftReportPath, `${driftReport}\n`, "utf8");
+
+  if (rehashOnly.length > 0) {
     process.stdout.write(
-        `Wrote ${rows.length} checksums to ${distChecksumsPath}\n` +
-        `                and to ${publicChecksumsPath}\n` +
-        `Baseline: ${REMOTE_CHECKSUMS_URL}\n`,
+      `Drift gate: ${rehashOnly.length} rebuilt artifact(s) differ only in ` +
+        `Vite's injected asset hashes (rehash-only, not drift)\n`,
     );
-}
+  }
+  if (liveMatched.length > 0) {
+    process.stdout.write(
+      `Drift gate: ${liveMatched.length} artifact(s) match the live site but ` +
+        `are missing from the baseline manifest (live-match, not drift)\n`,
+    );
+  }
 
-run().catch((error) => {
+  if (driftViolations.length > 0) {
+    const lines = driftViolations.map((v) => {
+      const note = v.note ? ` — ${v.note}` : "";
+      return `  ${v.relPath}: ${v.status} ${v.resolution}${note} (prev=${v.prev ?? "(none)"})`;
+    });
     process.stderr.write(
-        `${error instanceof Error ? error.message : String(error)}\n`,
+      `Drift gate failed — ${driftViolations.length} non-mutable artifact(s) changed ` +
+        `vs ${REMOTE_CHECKSUMS_URL}:\n${lines.join("\n")}\n`,
     );
-    process.exit(1);
+  }
+
+  const manifest = `${rows.join("\n")}\n`;
+
+  // Write the deployed copy (`dist/checksums.txt`) and the source copy
+  // (`public/checksums.txt`) so the next git commit and the next Render
+  // deploy both carry the new manifest.
+  await mkdir(distRoot, { recursive: true });
+  await mkdir(publicRoot, { recursive: true });
+  await writeFile(distChecksumsPath, manifest, "utf8");
+  await writeFile(publicChecksumsPath, manifest, "utf8");
+
+  // Belt-and-braces: if Vite ever changes how it copies `public/`, the
+  // `dist/` copy is the authoritative served artifact, so a final copy
+  // keeps the two in sync even if `public/checksums.txt` was deleted
+  // before the build ran.
+  await copyFile(publicChecksumsPath, distChecksumsPath).catch(() => {});
+
+  process.stdout.write(
+    `Wrote ${rows.length} checksums to ${distChecksumsPath}\n` +
+      `                and to ${publicChecksumsPath}\n` +
+      `Baseline: ${REMOTE_CHECKSUMS_URL}\n`,
+  );
+}
+
+run().catch((error) => {
+  process.stderr.write(
+    `${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exit(1);
 });
 
 console.log("https://akinevz.dev/ was here");