ai-delivery-workflow 0.2.2 → 0.4.0

package/lib/prototype-review-target.mjs

@@ -0,0 +1,334 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  readYamlMapping as readYaml,
+  requireSha256 as requireChecksum,
+  resolveContainedPath as safePath,
+  sha256File,
+} from "./artifact-files.mjs";
+import {
+  COMPONENT_CANDIDATE_LIFECYCLE_TRANSITIONS,
+  parsePrototypeCatalogCsv,
+  prototypeRevisionCatalogContracts,
+  validatePrototypeRevision,
+} from "./prototype-revision.mjs";
+import {
+  applyPrototypePageReviewReceipts,
+  buildPrototypePageReviewEvidence,
+  readPrototypePageReviewReceipts,
+} from "./prototype-page-review.mjs";
+import { validateVisualStandard } from "./visual-standard.mjs";
+
+function aggregateChecksum(files) {
+  const digest = crypto.createHash("sha256");
+  for (const file of [...files].sort()) {
+    digest.update(path.basename(file));
+    digest.update("\0");
+    digest.update(fs.readFileSync(file));
+    digest.update("\0");
+  }
+  return digest.digest("hex");
+}
+
+function readCatalog(bundleRoot, revision, name) {
+  const entry = revision.catalogs[name];
+  const file = safePath(bundleRoot, entry.ref, `Prototype ${name} catalog`);
+  const parsed = parsePrototypeCatalogCsv(fs.readFileSync(file, "utf8"), `Prototype ${name} catalog`);
+  if (parsed.header !== prototypeRevisionCatalogContracts[name]) {
+    throw new Error(`Prototype ${name} catalog header is invalid.`);
+  }
+  return parsed.rows;
+}
+
+function readVisualStandard(bundleRoot, revision) {
+  const ref = String(revision.visual_standard.ref);
+  const checksum = requireChecksum(
+    revision.visual_standard.checksum,
+    "Prototype Revision Visual Standard",
+  );
+  const file = safePath(bundleRoot, ref, "Prototype Revision Visual Standard");
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile() || sha256File(file) !== checksum) {
+    throw new Error("Prototype Revision Visual Standard checksum mismatch.");
+  }
+  return { ref, checksum, content: readYaml(file, "Prototype Revision Visual Standard") };
+}
+
+function componentGovernance(rows, validation) {
+  const componentBindings = rows.component_bindings.map((binding) => ({ ...binding }));
+  const pageById = new Map(rows.pages.map((page) => [page.page_id, page]));
+  const bindingsForComponent = (componentId) => componentBindings
+    .filter((binding) => binding.component_id === componentId);
+  const bindingsForContract = (dataContractId) => componentBindings
+    .filter((binding) => binding.data_contract_id === dataContractId);
+  const componentRows = rows.components.map((component) => {
+    const bindings = bindingsForComponent(component.component_id);
+    return {
+      ...component,
+      binding_count: bindings.length,
+      terminal_ids: [...new Set(bindings.map((binding) => binding.terminal_id))].sort(),
+    };
+  });
+  const dataContractRows = rows.data_contracts.map((contract) => {
+    const bindings = bindingsForContract(contract.data_contract_id);
+    return {
+      ...contract,
+      binding_count: bindings.length,
+      terminal_ids: [...new Set(bindings.map((binding) => binding.terminal_id))].sort(),
+    };
+  });
+  const componentCandidates = rows.component_candidates.map((candidate) => {
+    const bindings = bindingsForComponent(candidate.component_id);
+    const sourcePage = pageById.get(candidate.source_page_id);
+    const terminalIds = [...new Set([
+      ...(sourcePage ? [sourcePage.terminal_id] : []),
+      ...bindings.map((binding) => binding.terminal_id),
+    ])].sort();
+    return {
+      ...candidate,
+      source_terminal_id: sourcePage?.terminal_id || null,
+      binding_count: bindings.length,
+      binding_statuses: [...new Set(bindings.map((binding) => binding.status))].sort(),
+      terminal_ids: terminalIds,
+      allowed_lifecycle_transitions: [
+        ...(COMPONENT_CANDIDATE_LIFECYCLE_TRANSITIONS[candidate.lifecycle] || []),
+      ],
+    };
+  });
+  const implementationBindings = rows.implementation_bindings.map((binding) => ({ ...binding }));
+  const checks = [
+    ["component-registrations", componentRows.length, "Component Registration identities, lifecycle, and declared variants are valid."],
+    ["component-candidates", componentCandidates.length, "Component Candidate lifecycle, source scope, and eligible next transitions are valid."],
+    ["data-contracts", dataContractRows.length, "Data Contract identities and registered references are valid."],
+    ["component-bindings", componentBindings.length, "Component Binding Page, Scene, Terminal, and variant references are valid."],
+    ["implementation-mappings", implementationBindings.length, "Implementation Mapping entries are unique and match their registered Component and Data Contract."],
+  ].map(([check_id, count, message]) => ({
+    check_id,
+    status: validation.valid ? "passed" : "failed",
+    count,
+    message,
+  }));
+  return {
+    schema_version: "workflow-manager.component-governance.v1",
+    components: componentRows,
+    component_candidates: componentCandidates,
+    data_contracts: dataContractRows,
+    component_bindings: componentBindings,
+    implementation_bindings: implementationBindings,
+    validation: { status: validation.valid ? "passed" : "failed", checks },
+  };
+}
+
+function revisionCatalog(bundleRoot, revision, validation) {
+  const rows = Object.fromEntries(
+    Object.keys(prototypeRevisionCatalogContracts)
+      .map((name) => [name, readCatalog(bundleRoot, revision, name)]),
+  );
+  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 pageMapping = new Map();
+  const sceneMapping = new Map();
+  for (const mapping of rows.ui_mapping.filter((item) => item.lifecycle_status === "active")) {
+    if (mapping.target_kind === "page") pageMapping.set(mapping.page_id, mapping);
+    else if (mapping.target_kind === "review-scene") {
+      sceneMapping.set(mapping.review_scene_id, mapping);
+    }
+  }
+  const reviewEvidence = buildPrototypePageReviewEvidence(revision, rows);
+  const terminals = rows.terminals.filter((terminal) => terminal.lifecycle_status === "active");
+  const catalogSummary = Object.fromEntries([
+    "components",
+    "data_contracts",
+    "component_candidates",
+    "component_bindings",
+    "implementation_bindings",
+    "source_inspection_snapshots",
+  ].map((name) => [name, rows[name].length]));
+  const pages = rows.pages
+    .filter((page) => page.lifecycle_status === "active")
+    .map((page) => {
+      const mapping = pageMapping.get(page.page_id);
+      return {
+        ...page,
+        ...reviewEvidence.pages.get(page.page_id),
+        prototype_route: routeById.get(mapping.prototype_route_id).path,
+        production_route: routeById.get(mapping.production_route_id).path,
+        direct_review_path: `/review/page/${encodeURIComponent(page.page_id)}`,
+      };
+    });
+  const reviewScenes = rows.review_scenes
+    .filter((scene) => scene.lifecycle_status === "active")
+    .map((scene) => {
+      const mapping = sceneMapping.get(scene.review_scene_id);
+      const prototypeRoute = routeById.get(mapping.prototype_route_id);
+      const productionRoute = routeById.get(mapping.production_route_id);
+      return {
+        ...scene,
+        review_status: reviewEvidence.pages.get(scene.page_id).review_status,
+        scene_checksum: reviewEvidence.scenes.get(scene.review_scene_id),
+        prototype_route: prototypeRoute.path,
+        production_route: productionRoute.path,
+        direct_review_path: `/review/scene/${encodeURIComponent(scene.review_scene_id)}`,
+        trigger: triggerById.get(scene.trigger_condition_id),
+      };
+    });
+  const routeGraph = reviewScenes.map((scene) => ({
+    terminal_id: scene.terminal_id,
+    page_id: scene.page_id,
+    review_scene_id: scene.review_scene_id,
+    trigger_condition_id: scene.trigger_condition_id,
+    prototype_path: scene.prototype_route,
+    production_path: scene.production_route,
+  }));
+  const pageById = new Map(pages.map((page) => [page.page_id, page]));
+  const sceneById = new Map(reviewScenes.map((scene) => [scene.review_scene_id, scene]));
+  const sourceInspectionSnapshots = rows.source_inspection_snapshots
+    .filter((snapshot) => snapshot.lifecycle_status === "active")
+    .map((snapshot) => {
+      const page = pageById.get(snapshot.page_id);
+      const scene = snapshot.review_scene_id ? sceneById.get(snapshot.review_scene_id) : null;
+      return {
+        ...snapshot,
+        page_name: page?.page_name || null,
+        display_label: page?.display_label || null,
+        scene_name: scene?.scene_name || null,
+        scene_type: scene?.scene_type || null,
+        scene_review_status: scene?.review_status || null,
+      };
+    });
+  return {
+    terminals,
+    catalogSummary,
+    pages,
+    reviewScenes,
+    routeGraph,
+    sourceInspectionSnapshots,
+    componentGovernance: componentGovernance(rows, validation),
+    visualStandard: readVisualStandard(bundleRoot, revision),
+  };
+}
+
+export function buildPrototypeReviewTarget(projectRoot, options = {}) {
+  const root = path.resolve(projectRoot);
+  const experienceRelative = String(options.experience || "");
+  const experienceRoot = safePath(root, experienceRelative, "Experience directory");
+  if (!fs.existsSync(experienceRoot) || !fs.statSync(experienceRoot).isDirectory()) {
+    throw new Error("Experience directory is missing.");
+  }
+  const requestedRevision = String(options.revision || "").trim();
+  if (requestedRevision) {
+    validatePrototypeRevision(root, {
+      experience: experienceRelative,
+      revision: requestedRevision,
+    });
+  }
+  const confirmationFile = path.join(experienceRoot, "visual-system-confirmation.yaml");
+  const confirmation = readYaml(confirmationFile, "Visual Standard confirmation");
+  let visualApproved = confirmation.status === "valid"
+    && confirmation.decision === "approved"
+    && confirmation.human_approval?.decision === "approved";
+  if (visualApproved) {
+    try {
+      validateVisualStandard(root, { experience: experienceRelative, now: options.now });
+    } catch (error) {
+      if (/approval expired/i.test(error.message)) visualApproved = false;
+      else throw error;
+    }
+  }
+  if (!visualApproved) {
+    const manifestFile = path.join(experienceRoot, "visual-reference-manifest.yaml");
+    const manifest = readYaml(manifestFile, "Visual Reference manifest");
+    if (manifest.artifact_type !== "visual-reference" || !manifest.artifact_id) {
+      throw new Error("Visual Reference manifest identity is invalid.");
+    }
+    const entrypoint = safePath(experienceRoot, manifest.entrypoint, "Visual Reference entrypoint");
+    if (!fs.existsSync(entrypoint) || !fs.statSync(entrypoint).isFile()) {
+      throw new Error("Visual Reference entrypoint is missing.");
+    }
+    if (sha256File(entrypoint) !== requireChecksum(manifest.entrypoint_checksum, "Visual Reference")) {
+      throw new Error("Visual Reference checksum mismatch.");
+    }
+    const pinnedFiles = [confirmationFile, manifestFile, entrypoint];
+    return {
+      projectRoot: root,
+      experienceRoot,
+      experienceRelative,
+      mode: "visual-reference",
+      targetId: manifest.artifact_id,
+      targetChecksum: aggregateChecksum(pinnedFiles),
+      pinnedFiles: pinnedFiles.map((file) => ({ file, checksum: sha256File(file) })),
+      contentRoot: experienceRoot,
+      visualReferencePath: path.relative(experienceRoot, entrypoint).replaceAll("\\", "/"),
+      pages: [],
+      reviewScenes: [],
+      routeGraph: [],
+    };
+  }
+
+  const current = readYaml(path.join(experienceRoot, "prototype.yaml"), "Current Prototype descriptor");
+  const revisionRelative = requestedRevision || String(current.current_revision_ref || "");
+  if (!revisionRelative) throw new Error("UX-VS is approved but no exact Prototype revision was selected.");
+  const validation = validatePrototypeRevision(root, {
+    experience: experienceRelative,
+    revision: revisionRelative,
+  });
+  const revisionFile = safePath(experienceRoot, revisionRelative, "Prototype revision");
+  const revision = readYaml(revisionFile, "Prototype revision");
+  const revisionRoot = path.dirname(revisionFile);
+  const bundleRoot = safePath(revisionRoot, revision.review_bundle.ref, "Prototype review bundle");
+  const sourceRoot = safePath(experienceRoot, revision.source.ref, "Prototype source root");
+  const catalog = revisionCatalog(bundleRoot, revision, validation);
+  const target = {
+    projectRoot: root,
+    experienceRoot,
+    experienceRelative,
+    revisionRelative: path.relative(experienceRoot, revisionFile).replaceAll("\\", "/"),
+    mode: "prototype-revision",
+    targetId: revision.artifact_id,
+    targetChecksum: sha256File(revisionFile),
+    prototypeId: revision.prototype_id,
+    iterationId: revision.iteration_id,
+    catalogSchemaVersion: validation.catalog_schema_version,
+    terminals: catalog.terminals,
+    catalogSummary: catalog.catalogSummary,
+    componentGovernance: catalog.componentGovernance,
+    visualStandard: catalog.visualStandard,
+    ancestorRevisions: validation.ancestor_revisions,
+    revisionFile,
+    sourceRoot,
+    contentRoot: bundleRoot,
+    reviewEntrypoint: revision.review_shell.entrypoint_in_bundle,
+    pages: catalog.pages,
+    reviewScenes: catalog.reviewScenes,
+    routeGraph: catalog.routeGraph,
+    sourceInspectionSnapshots: catalog.sourceInspectionSnapshots,
+  };
+  const reviewed = applyPrototypePageReviewReceipts(
+    target,
+    readPrototypePageReviewReceipts(root),
+  );
+  return { ...target, pages: reviewed.pages, reviewScenes: reviewed.reviewScenes };
+}
+
+export function assertPrototypeReviewTargetFresh(target) {
+  if (target.mode === "visual-reference") {
+    for (const pinned of target.pinnedFiles) {
+      if (!fs.existsSync(pinned.file) || sha256File(pinned.file) !== pinned.checksum) {
+        throw new Error("Visual Reference target changed after the review session started.");
+      }
+    }
+    if (aggregateChecksum(target.pinnedFiles.map((item) => item.file)) !== target.targetChecksum) {
+      throw new Error("Visual Reference target checksum changed after the review session started.");
+    }
+    return;
+  }
+  validatePrototypeRevision(target.projectRoot, {
+    experience: target.experienceRelative,
+    revision: target.revisionRelative,
+  });
+  if (sha256File(target.revisionFile) !== target.targetChecksum) {
+    throw new Error("Prototype revision descriptor changed after the review session started.");
+  }
+}