frontend-project-context 1.3.0 → 1.6.0

package/src/project-context/upgrade-schema.mjs

@@ -0,0 +1,215 @@
+import { canonicalValue, digestJson } from "./canonical-json.mjs";
+import { fail } from "./errors.mjs";
+
+export const UPGRADE_ASSESSMENT_SCHEMA_VERSION = 1;
+export const MIGRATION_PLAN_SCHEMA_VERSION = 1;
+export const UPGRADE_RESULT_BUNDLE_SCHEMA_VERSION = 1;
+
+const SHA256 = /^sha256:[a-f0-9]{64}$/u;
+const AUTHORITY_FIELDS = new Set(["approved", "approval", "reviewer", "by", "shell", "command", "write"]);
+const BOUNDARY_FIELDS = new Set([
+  "provider", "agentRuntime", "git", "network", "dependencyInstallation", "automaticApproval", "businessCodeWrites",
+  "taskExecution", "stagePathBodyReads", "applyPlan", "scheduler", "daemon", "telemetry", "selfUpdate",
+  "automaticEvidenceUpload", "packageManager", "automaticUpgrade",
+]);
+
+function invalid(code, message) {
+  fail(code, message);
+}
+
+function assertJsonShape(value, label, code, required, options = {}) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalid(code, `${label} must be an object`);
+  const keys = Object.keys(value).sort();
+  const expected = [...required].sort();
+  if (!options.allowExtra && (keys.length !== expected.length || keys.some((key, index) => key !== expected[index]))) {
+    invalid(code, `${label} must contain exactly: ${expected.join(", ")}`);
+  }
+  for (const key of Object.keys(value)) if (AUTHORITY_FIELDS.has(key)) invalid(code, `${label} contains forbidden authority or execution field: ${key}`);
+}
+
+function digest(value, label, code, nullable = false) {
+  if (nullable && value === null) return;
+  if (typeof value !== "string" || !SHA256.test(value)) invalid(code, `${label} must be sha256`);
+}
+
+function string(value, label, code) {
+  if (typeof value !== "string" || value.length === 0) invalid(code, `${label} must be a non-empty string`);
+}
+
+function projectPath(value, label, code) {
+  string(value, label, code);
+  const segments = value.split("/");
+  if (
+    value.includes("\0") || value.includes("\\") || value.startsWith("/") || /^[A-Za-z]:/u.test(value)
+    || segments.some((segment) => segment === "" || segment === "." || segment === "..")
+  ) invalid(code, `${label} must be a canonical project-relative path`);
+}
+
+function sortedUnique(values, label, code) {
+  if (!Array.isArray(values)) invalid(code, `${label} must be an array`);
+  values.forEach((value) => string(value, `${label} entry`, code));
+  const sorted = [...values].sort((left, right) => left.localeCompare(right));
+  if (new Set(values).size !== values.length || values.some((value, index) => value !== sorted[index])) invalid(code, `${label} must be unique and sorted`);
+}
+
+function validateSnapshots(value, label, code, nullable = false) {
+  if (nullable && value === null) return;
+  assertJsonShape(value, label, code, new Set(["contract", "sourcesLock", "projectionsLock"]));
+  digest(value.contract, `${label}.contract`, code);
+  digest(value.sourcesLock, `${label}.sourcesLock`, code);
+  digest(value.projectionsLock, `${label}.projectionsLock`, code);
+}
+
+function validateAction(action, label, code) {
+  assertJsonShape(action, label, code, new Set(["id", "kind", "migrationId", "targets", "writes", "semanticImpact"]));
+  string(action.id, `${label}.id`, code);
+  if (!["verify-complete", "republish-ai-entry", "republish-projection", "built-in-store-migration", "invalidate-ephemeral-protocol"].includes(action.kind)) invalid(code, `${label}.kind is invalid`);
+  if (action.migrationId !== null) string(action.migrationId, `${label}.migrationId`, code);
+  sortedUnique(action.targets, `${label}.targets`, code);
+  action.targets.forEach((target) => projectPath(target, `${label}.targets entry`, code));
+  if (typeof action.writes !== "boolean") invalid(code, `${label}.writes must be boolean`);
+  if (!["none", "managed-rendering", "store-structure", "protocol-artifact-invalidation"].includes(action.semanticImpact)) invalid(code, `${label}.semanticImpact is invalid`);
+}
+
+function verifySelfDigest(value, field, code) {
+  digest(value[field], field, code);
+  const unsigned = Object.fromEntries(Object.entries(value).filter(([key]) => key !== field));
+  if (digestJson(unsigned) !== value[field]) invalid(code, `${field} does not match artifact content`);
+}
+
+function scanForbidden(value, label, code) {
+  if (!value || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value)) {
+    if (AUTHORITY_FIELDS.has(key)) invalid(code, `${label} contains forbidden field: ${key}`);
+    scanForbidden(child, `${label}.${key}`, code);
+  }
+}
+
+export function finalizeUpgradeAssessment(value) {
+  const unsigned = canonicalValue(value);
+  return { ...unsigned, assessmentDigest: digestJson(unsigned) };
+}
+
+export function validateUpgradeAssessment(input) {
+  const code = "upgrade-assessment-invalid";
+  const value = structuredClone(input);
+  assertJsonShape(value, "upgrade assessment", code, new Set([
+    "schemaVersion", "kind", "product", "fromVersion", "targetVersion", "fromVersionEvidence",
+    "manifestSchemaVersion", "manifestDigest", "initialization", "health", "entryState", "findingCodes",
+    "snapshots", "compatibility", "migrationPath", "rollbackClass", "requiresHumanReview", "state", "boundaries", "assessmentDigest",
+  ]));
+  scanForbidden(value, "upgrade assessment", code);
+  if (value.schemaVersion !== 1 || value.kind !== "upgrade-assessment") invalid(code, "upgrade assessment schema or kind is invalid");
+  assertJsonShape(value.product, "product", code, new Set(["name"]));
+  if (value.product.name !== "frontend-project-context") invalid(code, "product name is invalid");
+  string(value.fromVersion, "fromVersion", code); string(value.targetVersion, "targetVersion", code);
+  if (value.fromVersionEvidence !== "host-asserted") invalid(code, "fromVersionEvidence must be host-asserted");
+  if (value.manifestSchemaVersion !== 2) invalid(code, "manifestSchemaVersion must be 2");
+  digest(value.manifestDigest, "manifestDigest", code);
+  assertJsonShape(value.initialization, "initialization", code, new Set(["state", "present", "missing"]));
+  sortedUnique(value.initialization.present, "initialization.present", code);
+  sortedUnique(value.initialization.missing, "initialization.missing", code);
+  if (!["uninitialized", "partial", "initialized", "invalid"].includes(value.initialization.state)) invalid(code, "initialization.state is invalid");
+  if (!["uninitialized", "partial", "invalid", "attention", "conflict", "clean"].includes(value.health)) invalid(code, "health is invalid");
+  assertJsonShape(value.entryState, "entryState", code, new Set(["state", "path", "rendererVersion"]));
+  if (value.entryState.path !== null) string(value.entryState.path, "entryState.path", code);
+  if (value.entryState.rendererVersion !== null && !Number.isInteger(value.entryState.rendererVersion)) invalid(code, "entryState.rendererVersion is invalid");
+  sortedUnique(value.findingCodes, "findingCodes", code);
+  validateSnapshots(value.snapshots, "snapshots", code, true);
+  assertJsonShape(value.compatibility, "compatibility", code, new Set(["stores", "renderers", "protocols"]));
+  const compatibilityKeys = {
+    stores: new Set(["contract", "projectionLock", "proposal", "sourceLock"]),
+    renderers: new Set(["aiEntry", "projection"]),
+    protocols: new Set(["actionPlan", "evidenceBundle", "evidenceInput", "exchange", "integrationReviewBundle", "reviewBundle", "stageContextBundle", "stageReceipt", "taskContextPlan"]),
+  };
+  for (const [name, group] of Object.entries(value.compatibility)) {
+    assertJsonShape(group, `compatibility.${name}`, code, compatibilityKeys[name]);
+    for (const state of Object.values(group)) if (!["compatible", "republish", "regenerate", "invalidate", "unsupported", "not-applicable"].includes(state)) invalid(code, "compatibility state is invalid");
+  }
+  sortedUnique(value.migrationPath, "migrationPath", code);
+  if (!["package-only", "reversible-data", "forward-only"].includes(value.rollbackClass)) invalid(code, "rollbackClass is invalid");
+  if (typeof value.requiresHumanReview !== "boolean") invalid(code, "requiresHumanReview must be boolean");
+  if (!["not-applicable", "blocked", "ready-for-plan", "core-complete"].includes(value.state)) invalid(code, "assessment state is invalid");
+  assertJsonShape(value.boundaries, "boundaries", code, BOUNDARY_FIELDS);
+  for (const boundary of Object.values(value.boundaries)) if (boundary !== false) invalid(code, "upgrade boundaries must all be false");
+  verifySelfDigest(value, "assessmentDigest", code);
+  return canonicalValue(value);
+}
+
+export function finalizeMigrationPlan(value) {
+  const unsigned = canonicalValue(value);
+  return { ...unsigned, planDigest: digestJson(unsigned) };
+}
+
+export function validateMigrationPlan(input) {
+  const code = "upgrade-plan-invalid";
+  const value = structuredClone(input);
+  assertJsonShape(value, "migration plan", code, new Set([
+    "schemaVersion", "kind", "fromVersion", "targetVersion", "manifestDigest", "assessmentDigest", "snapshots",
+    "targetDigests", "nextAction", "remainingMigrationIds", "acceptance", "rollback", "requiresHumanReview", "authority", "planDigest",
+  ]));
+  scanForbidden(value, "migration plan", code);
+  if (value.schemaVersion !== 1 || value.kind !== "target-upgrade-plan") invalid(code, "migration plan schema or kind is invalid");
+  string(value.fromVersion, "fromVersion", code); string(value.targetVersion, "targetVersion", code);
+  digest(value.manifestDigest, "manifestDigest", code); digest(value.assessmentDigest, "assessmentDigest", code);
+  validateSnapshots(value.snapshots, "snapshots", code, true);
+  if (!Array.isArray(value.targetDigests)) invalid(code, "targetDigests must be an array");
+  value.targetDigests.forEach((target, index) => {
+    assertJsonShape(target, `targetDigests[${index}]`, code, new Set(["path", "beforeDigest"]));
+    projectPath(target.path, `targetDigests[${index}].path`, code); digest(target.beforeDigest, `targetDigests[${index}].beforeDigest`, code, true);
+  });
+  const action = value.nextAction;
+  validateAction(action, "nextAction", code);
+  sortedUnique(value.remainingMigrationIds, "remainingMigrationIds", code);
+  assertJsonShape(value.acceptance, "acceptance", code, new Set(["core", "hostRequired"]));
+  sortedUnique(value.acceptance.core, "acceptance.core", code); sortedUnique(value.acceptance.hostRequired, "acceptance.hostRequired", code);
+  assertJsonShape(value.rollback, "rollback", code, new Set(["class", "reverseMigrationId", "externalRestoreRequired"]));
+  if (!["package-only", "reversible-data", "forward-only"].includes(value.rollback.class)) invalid(code, "rollback.class is invalid");
+  if (value.rollback.reverseMigrationId !== null) string(value.rollback.reverseMigrationId, "rollback.reverseMigrationId", code);
+  if (typeof value.rollback.externalRestoreRequired !== "boolean") invalid(code, "rollback.externalRestoreRequired must be boolean");
+  if (typeof value.requiresHumanReview !== "boolean") invalid(code, "requiresHumanReview must be boolean");
+  if ((action.semanticImpact === "store-structure" || value.rollback.reverseMigrationId === null && action.writes) && !value.requiresHumanReview) invalid(code, "write without automatic reverse migration requires human review");
+  if (value.authority !== "human-explicit-write-required") invalid(code, "authority is invalid");
+  verifySelfDigest(value, "planDigest", code);
+  return canonicalValue(value);
+}
+
+export function finalizeUpgradeResult(value) {
+  const unsigned = canonicalValue(value);
+  return { ...unsigned, resultDigest: digestJson(unsigned) };
+}
+
+export function validateUpgradeResult(input) {
+  const code = "upgrade-result-invalid";
+  const value = structuredClone(input);
+  assertJsonShape(value, "upgrade result", code, new Set([
+    "schemaVersion", "kind", "product", "fromVersion", "targetVersion", "manifestDigest", "planDigest", "mode", "action",
+    "written", "targets", "snapshots", "actionResult", "findingCodes", "coreMigration", "hostAcceptance", "overallUpgrade", "resultDigest",
+  ]));
+  scanForbidden(value, "upgrade result", code);
+  if (value.schemaVersion !== 1 || value.kind !== "upgrade-result-bundle") invalid(code, "upgrade result schema or kind is invalid");
+  assertJsonShape(value.product, "product", code, new Set(["name"]));
+  if (value.product.name !== "frontend-project-context") invalid(code, "product name is invalid");
+  string(value.fromVersion, "fromVersion", code); string(value.targetVersion, "targetVersion", code);
+  digest(value.manifestDigest, "manifestDigest", code); digest(value.planDigest, "planDigest", code);
+  if (!["preview", "write"].includes(value.mode)) invalid(code, "mode is invalid");
+  validateAction(value.action, "action", code);
+  if (typeof value.written !== "boolean") invalid(code, "written must be boolean");
+  if (!Array.isArray(value.targets)) invalid(code, "targets must be an array");
+  value.targets.forEach((target, index) => {
+    assertJsonShape(target, `targets[${index}]`, code, new Set(["path", "beforeDigest", "afterDigest"]));
+    projectPath(target.path, `targets[${index}].path`, code);
+    digest(target.beforeDigest, `targets[${index}].beforeDigest`, code, true);
+    digest(target.afterDigest, `targets[${index}].afterDigest`, code, true);
+  });
+  assertJsonShape(value.snapshots, "snapshots", code, new Set(["before", "after"]));
+  validateSnapshots(value.snapshots.before, "snapshots.before", code, true); validateSnapshots(value.snapshots.after, "snapshots.after", code, true);
+  string(value.actionResult, "actionResult", code);
+  sortedUnique(value.findingCodes, "findingCodes", code);
+  if (!["previewed", "applied", "blocked", "complete"].includes(value.coreMigration)) invalid(code, "coreMigration is invalid");
+  sortedUnique(value.hostAcceptance, "hostAcceptance", code);
+  if (value.hostAcceptance.join("|") !== ["dependency-and-lockfile", "independent-new-window", "project-tests-or-ci"].join("|")) invalid(code, "hostAcceptance is invalid");
+  if (value.overallUpgrade !== "host-validation-required") invalid(code, "overallUpgrade is invalid");
+  verifySelfDigest(value, "resultDigest", code);
+  return canonicalValue(value);
+}