ai-delivery-workflow 0.2.2 → 0.4.0

package/lib/prototype-page-review.mjs

@@ -0,0 +1,384 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { stringify as stringifyYaml } from "./yaml-runtime.mjs";
+import { readYamlMapping, resolveContainedPath } from "./artifact-files.mjs";
+
+const receiptRootRelative = path.join(".workflow", "delivery", "reviews", "prototype-pages");
+const receiptIdPattern = /^PAGE-REVIEW-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const safeIdentityPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const pageIdPattern = /^P[0-9]{2,}(?:-[0-9]{2,})?$/;
+const sceneIdPattern = /^RS[0-9]{4,}$/;
+const sha256Pattern = /^[a-f0-9]{64}$/;
+const evidenceDomains = Object.freeze([
+  "page",
+  "review_scenes",
+  "triggers",
+  "routes",
+  "ui_mapping",
+  "page_sources",
+  "shared_components",
+  "visual_standard",
+]);
+const receiptFields = Object.freeze([
+  "actor",
+  "artifact_type",
+  "comment",
+  "decided_at",
+  "decision",
+  "evidence_checksums",
+  "iteration_id",
+  "page_checksum",
+  "page_id",
+  "prototype_id",
+  "prototype_revision_checksum",
+  "prototype_revision_id",
+  "rationale",
+  "receipt_checksum",
+  "receipt_id",
+  "scene_checksums",
+  "schema_version",
+  "terminal_id",
+]);
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.keys(value).sort().map((key) => [key, stableValue(value[key])]),
+  );
+}
+
+function digest(value) {
+  return crypto.createHash("sha256").update(JSON.stringify(stableValue(value))).digest("hex");
+}
+
+function receiptChecksum(receipt) {
+  const { receipt_checksum: ignored, ...unsigned } = receipt;
+  return digest(unsigned);
+}
+
+function mapping(value) {
+  return value && typeof value === "object" && !Array.isArray(value);
+}
+
+function requireSafeIdentity(value, label) {
+  if (typeof value !== "string" || !safeIdentityPattern.test(value)) {
+    throw new Error(`${label} is invalid.`);
+  }
+}
+
+function requireChecksum(value, label) {
+  if (typeof value !== "string" || !sha256Pattern.test(value)) {
+    throw new Error(`${label} is invalid.`);
+  }
+}
+
+function validatePrototypePageReviewReceipt(receipt, options = {}) {
+  if (!mapping(receipt) || receipt.schema_version !== 1
+      || receipt.artifact_type !== "prototype-page-review-receipt"
+      || !receiptIdPattern.test(String(receipt.receipt_id || ""))) {
+    throw new Error("Prototype Page review receipt identity is invalid.");
+  }
+  if (Object.keys(receipt).sort().join("\0") !== receiptFields.join("\0")) {
+    throw new Error("Prototype Page review receipt fields are invalid.");
+  }
+  requireSafeIdentity(receipt.prototype_id, "Prototype identity");
+  requireSafeIdentity(receipt.prototype_revision_id, "Prototype revision identity");
+  requireSafeIdentity(receipt.iteration_id, "Iteration identity");
+  requireSafeIdentity(receipt.terminal_id, "Terminal identity");
+  if (!pageIdPattern.test(String(receipt.page_id || ""))) {
+    throw new Error("Prototype Page review receipt Page identity is invalid.");
+  }
+  requireChecksum(receipt.prototype_revision_checksum, "Prototype revision checksum");
+  requireChecksum(receipt.page_checksum, "Page checksum");
+  if (!mapping(receipt.scene_checksums)) {
+    throw new Error("Prototype Page review receipt Scene checksums are invalid.");
+  }
+  for (const [sceneId, checksum] of Object.entries(receipt.scene_checksums)) {
+    if (!sceneIdPattern.test(sceneId)) {
+      throw new Error("Prototype Page review receipt Scene identity is invalid.");
+    }
+    requireChecksum(checksum, `Review Scene ${sceneId} checksum`);
+  }
+  if (!mapping(receipt.evidence_checksums)
+      || Object.keys(receipt.evidence_checksums).sort().join("\0") !== [...evidenceDomains].sort().join("\0")) {
+    throw new Error("Prototype Page review receipt evidence domains are invalid.");
+  }
+  for (const domain of evidenceDomains) {
+    requireChecksum(receipt.evidence_checksums[domain], `Page evidence ${domain} checksum`);
+  }
+  if (!new Set(["approved", "changes-requested"]).has(receipt.decision)) {
+    throw new Error("Prototype Page review receipt decision is invalid.");
+  }
+  if (!/^human:[A-Za-z0-9._@/-]+$/.test(String(receipt.actor || ""))) {
+    throw new Error("Prototype Page review receipt actor is invalid.");
+  }
+  if (!new Set(["string", "object"]).has(typeof receipt.rationale)
+      || (receipt.rationale !== null && typeof receipt.rationale !== "string")
+      || (receipt.comment !== null && typeof receipt.comment !== "string")) {
+    throw new Error("Prototype Page review receipt rationale or comment is invalid.");
+  }
+  if (receipt.decision === "changes-requested" && !String(receipt.rationale || "").trim()) {
+    throw new Error("Prototype Page review receipt rationale is required.");
+  }
+  if (!Number.isFinite(Date.parse(receipt.decided_at || ""))) {
+    throw new Error("Prototype Page review receipt decision time is invalid.");
+  }
+  if (receipt.receipt_checksum !== receiptChecksum(receipt)) {
+    throw new Error("Prototype Page review receipt checksum is invalid.");
+  }
+  if (options.file) {
+    const file = path.resolve(options.file);
+    const receiptRoot = path.resolve(options.receiptRoot);
+    const relative = path.relative(receiptRoot, file);
+    const segments = relative.split(path.sep);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)
+        || segments.length !== 2
+        || segments[0] !== receipt.prototype_revision_id
+        || !new RegExp(`^${receipt.receipt_id}\\.ya?ml$`, "i").test(path.basename(file))) {
+      throw new Error("Prototype Page review receipt file path does not match its identities.");
+    }
+  }
+  return receipt;
+}
+
+function active(rows) {
+  return rows.filter((row) => row.lifecycle_status === "active");
+}
+
+export function buildPrototypePageReviewEvidence(revision, rows) {
+  const routeById = new Map(rows.routes.map((route) => [route.route_id, route]));
+  const triggerById = new Map(
+    rows.trigger_conditions.map((trigger) => [trigger.trigger_condition_id, trigger]),
+  );
+  const activeMappings = active(rows.ui_mapping);
+  const affectedPagesByUnit = new Map();
+  for (const relation of rows.review_unit_pages) {
+    const pageIds = affectedPagesByUnit.get(relation.review_unit_id) || [];
+    pageIds.push(relation.page_id);
+    affectedPagesByUnit.set(relation.review_unit_id, pageIds);
+  }
+  const activeUnits = active(rows.review_units).map((unit) => ({
+    ...unit,
+    affected_page_ids: [...(affectedPagesByUnit.get(unit.review_unit_id) || [])].sort(),
+  }));
+  const sceneEvidence = new Map();
+  for (const scene of active(rows.review_scenes)) {
+    const mappings = activeMappings.filter((mapping) => mapping.review_scene_id === scene.review_scene_id);
+    const routes = mappings.flatMap((mapping) => [
+      routeById.get(mapping.prototype_route_id),
+      routeById.get(mapping.production_route_id),
+    ]).filter(Boolean);
+    const units = activeUnits.filter((unit) => unit.unit_kind === "review-scene"
+      && unit.target_id === scene.review_scene_id);
+    const shared = activeUnits.filter((unit) => unit.unit_kind === "shared-component"
+      && unit.affected_page_ids.includes(scene.page_id));
+    sceneEvidence.set(scene.review_scene_id, digest({
+      scene,
+      trigger: triggerById.get(scene.trigger_condition_id),
+      routes,
+      mappings,
+      units,
+      shared_components: shared,
+      visual_standard: revision.visual_standard.checksum,
+    }));
+  }
+
+  const pages = new Map();
+  for (const page of active(rows.pages)) {
+    const scenes = active(rows.review_scenes).filter((scene) => scene.page_id === page.page_id);
+    const sceneIds = new Set(scenes.map((scene) => scene.review_scene_id));
+    const mappings = activeMappings.filter((mapping) => mapping.page_id === page.page_id);
+    const routeIds = new Set(mappings.flatMap((mapping) => [
+      mapping.prototype_route_id, mapping.production_route_id,
+    ]));
+    const pageUnits = activeUnits.filter((unit) => unit.unit_kind === "page"
+      && unit.target_id === page.page_id);
+    const shared = activeUnits.filter((unit) => unit.unit_kind === "shared-component"
+      && unit.affected_page_ids.includes(page.page_id));
+    const evidenceChecksums = {
+      page: digest(page),
+      review_scenes: digest(scenes),
+      triggers: digest(scenes.map((scene) => triggerById.get(scene.trigger_condition_id))),
+      routes: digest(active(rows.routes).filter((route) => routeIds.has(route.route_id))),
+      ui_mapping: digest(mappings),
+      page_sources: digest(pageUnits),
+      shared_components: digest(shared),
+      visual_standard: revision.visual_standard.checksum,
+    };
+    const sceneChecksums = Object.fromEntries(
+      [...sceneIds].sort().map((sceneId) => [sceneId, sceneEvidence.get(sceneId)]),
+    );
+    pages.set(page.page_id, {
+      evidence_checksums: evidenceChecksums,
+      scene_checksums: sceneChecksums,
+      page_checksum: digest({ evidence_checksums: evidenceChecksums, scene_checksums: sceneChecksums }),
+      changed_domains: ["initial-review"],
+      review_status: "pending-review",
+    });
+  }
+  return { pages, scenes: sceneEvidence };
+}
+
+export function createPrototypePageReviewReceipt(target, page, input, now = () => new Date().toISOString()) {
+  const decision = String(input.decision || "").toLowerCase().replaceAll("_", "-");
+  if (!new Set(["approved", "changes-requested"]).has(decision)) {
+    throw new Error("Page review decision must be approved or changes-requested.");
+  }
+  const actor = String(input.actor || "");
+  if (!/^human:[A-Za-z0-9._@/-]+$/.test(actor)) {
+    throw new Error("Page review actor must use a human:<identity> value.");
+  }
+  const rationale = String(input.rationale || "").trim();
+  if (decision === "changes-requested" && !rationale) {
+    throw new Error("Page changes-requested decisions require a rationale.");
+  }
+  if (input.target_checksum !== target.targetChecksum || input.page_checksum !== page.page_checksum) {
+    throw new Error("Page review target or Page checksum is stale.");
+  }
+  if (input.terminal_id !== page.terminal_id) {
+    throw new Error("Page review Logical Terminal does not match its Page.");
+  }
+  const decidedAt = now();
+  if (!Number.isFinite(Date.parse(decidedAt))) throw new Error("Page review decision time is invalid.");
+  const receipt = {
+    schema_version: 1,
+    receipt_id: `PAGE-REVIEW-${crypto.randomUUID()}`,
+    artifact_type: "prototype-page-review-receipt",
+    prototype_id: target.prototypeId,
+    prototype_revision_id: target.targetId,
+    prototype_revision_checksum: target.targetChecksum,
+    iteration_id: target.iterationId,
+    terminal_id: page.terminal_id,
+    page_id: page.page_id,
+    page_checksum: page.page_checksum,
+    scene_checksums: page.scene_checksums,
+    evidence_checksums: page.evidence_checksums,
+    decision,
+    actor,
+    rationale: rationale || null,
+    comment: String(input.comment || "").trim() || null,
+    decided_at: decidedAt,
+  };
+  receipt.receipt_checksum = receiptChecksum(receipt);
+  return receipt;
+}
+
+export function prototypePageReviewReceiptWrite(projectRoot, receipt) {
+  validatePrototypePageReviewReceipt(receipt);
+  const receiptRoot = path.join(path.resolve(projectRoot), receiptRootRelative);
+  const directory = resolveContainedPath(
+    receiptRoot,
+    receipt.prototype_revision_id,
+    "Prototype Page review receipt revision directory",
+  );
+  const file = resolveContainedPath(directory, `${receipt.receipt_id}.yaml`, "Prototype Page review receipt");
+  if (fs.existsSync(file)) throw new Error(`Prototype Page review receipt already exists: ${receipt.receipt_id}.`);
+  return { file, content: stringifyYaml(receipt, { lineWidth: 0 }) };
+}
+
+function listReceiptFiles(directory) {
+  if (!fs.existsSync(directory)) return [];
+  if (!fs.statSync(directory).isDirectory()) throw new Error("Prototype Page review receipt root must be a directory.");
+  const files = [];
+  const visit = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const absolute = path.join(current, entry.name);
+      if (entry.isSymbolicLink()) throw new Error("Prototype Page review receipts must not contain symbolic links.");
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile() && /\.ya?ml$/i.test(entry.name)) files.push(absolute);
+    }
+  };
+  visit(directory);
+  return files.sort();
+}
+
+export function readPrototypePageReviewReceipts(projectRoot) {
+  const receiptRoot = path.join(path.resolve(projectRoot), receiptRootRelative);
+  return listReceiptFiles(receiptRoot).map((file) => {
+    const receipt = readYamlMapping(file, "Prototype Page review receipt");
+    try {
+      return validatePrototypePageReviewReceipt(receipt, { file, receiptRoot });
+    } catch {
+      throw new Error(`Prototype Page review receipt is invalid or tampered: ${path.basename(file)}.`);
+    }
+  });
+}
+
+function receiptOrder(left, right) {
+  return String(left.decided_at).localeCompare(String(right.decided_at))
+    || String(left.receipt_id).localeCompare(String(right.receipt_id));
+}
+
+function changedDomains(page, receipt) {
+  const changed = Object.keys(page.evidence_checksums)
+    .filter((key) => page.evidence_checksums[key] !== receipt.evidence_checksums?.[key]);
+  if (JSON.stringify(page.scene_checksums) !== JSON.stringify(receipt.scene_checksums)
+      && !changed.includes("review_scenes")) changed.push("review_scenes");
+  return changed.length ? changed.sort() : ["receipt-binding"];
+}
+
+function receiptMatchesPage(target, page, receipt, revisionChecksum) {
+  return receipt.iteration_id === target.iterationId
+    && receipt.terminal_id === page.terminal_id
+    && receipt.page_checksum === page.page_checksum
+    && digest(receipt.scene_checksums) === digest(page.scene_checksums)
+    && digest(receipt.evidence_checksums) === digest(page.evidence_checksums)
+    && receipt.prototype_revision_checksum === revisionChecksum;
+}
+
+export function applyPrototypePageReviewReceipts(target, receipts) {
+  const pages = target.pages.map((page) => {
+    const candidates = receipts.filter((receipt) => receipt.prototype_id === target.prototypeId
+      && receipt.page_id === page.page_id).sort(receiptOrder);
+    const current = candidates.filter((receipt) => receipt.prototype_revision_id === target.targetId).at(-1);
+    if (current) {
+      if (!receiptMatchesPage(target, page, current, target.targetChecksum)) {
+        return { ...page, review_status: "stale", changed_domains: changedDomains(page, current) };
+      }
+      return {
+        ...page,
+        review_status: current.decision === "approved" ? "approved" : "changes-requested",
+        changed_domains: [],
+        latest_review: current,
+      };
+    }
+    const ancestorRevisions = Array.isArray(target.ancestorRevisions)
+      ? target.ancestorRevisions
+      : [];
+    const priorBinding = ancestorRevisions
+      .map((ancestor) => ({
+        ancestor,
+        receipt: candidates
+          .filter((receipt) => receipt.prototype_revision_id === ancestor.prototype_revision_id)
+          .at(-1),
+      }))
+      .find((binding) => binding.receipt);
+    const prior = priorBinding?.receipt;
+    if (!prior) return page;
+    if (receiptMatchesPage(
+      target,
+      page,
+      prior,
+      priorBinding.ancestor.prototype_revision_checksum,
+    )) {
+      return {
+        ...page,
+        review_status: prior.decision === "approved" ? "approved" : "changes-requested",
+        changed_domains: [],
+        ...(prior.decision === "approved"
+          ? { inherited_from_revision: prior.prototype_revision_id }
+          : {}),
+        latest_review: prior,
+      };
+    }
+    return { ...page, review_status: "stale", changed_domains: changedDomains(page, prior), latest_review: prior };
+  });
+  const statusByPage = new Map(pages.map((page) => [page.page_id, page.review_status]));
+  const scenes = target.reviewScenes.map((scene) => ({
+    ...scene,
+    review_status: statusByPage.get(scene.page_id) || "pending-review",
+  }));
+  return { pages, reviewScenes: scenes };
+}