@kungfu-tech/buildchain 4.0.2-alpha.10 → 4.0.2-alpha.12

package/scripts/check-maintainability.mjs

@@ -19,6 +19,8 @@ import {
   evaluateTestBudgets,
   evaluateWorkflowBudgets,
 } from "./maintainability-governance.mjs";
+import { governUniversalFacadeWorkflowMetrics } from "./universal-facade-maintainability.mjs";
+import { evaluatePublicSurface } from "./maintainability-public-surface.mjs";
 
 function collectHotspots(
   root,
@@ -162,116 +164,6 @@ function selectedFunction(metrics, file, name) {
   return metrics.files[file]?.functions.find((entry) => entry.name === name);
 }
 
-function readJsonAtRevision(root, revision, file) {
-  return JSON.parse(gitOutput(root, ["show", `${revision}:${file}`]));
-}
-
-function publicSurfaceContract(entry, kind) {
-  if (kind === "cli") return { id: entry.id, usage: entry.usage };
-  if (kind === "node")
-    return {
-      export: entry.export,
-      specifier: entry.specifier,
-      target: entry.target,
-    };
-  return {
-    id: entry.id,
-    path: entry.path,
-    reusable: entry.reusable,
-    inputs: entry.inputs || [],
-    secrets: entry.secrets || [],
-    outputs: entry.outputs || [],
-  };
-}
-
-function evaluatePublicSurface({ root, revision, policy }) {
-  const issues = [];
-  const lifecycleFields = policy.publicSurfacePolicy.requiredLifecycleFields;
-  const capabilityGroups = new Set(
-    readJson(root, "dist/site/capability-registry.json").groups.map(
-      (entry) => entry.id,
-    ),
-  );
-  const definitions = [
-    {
-      file: "dist/site/cli-registry.json",
-      collection: "commands",
-      kind: "cli",
-      key: "id",
-    },
-    {
-      file: "dist/site/node-api-registry.json",
-      collection: "exports",
-      kind: "node",
-      key: "export",
-    },
-    {
-      file: "dist/site/workflow-registry.json",
-      collection: "workflows",
-      kind: "workflow",
-      key: "id",
-    },
-    {
-      file: "dist/site/workflow-registry.json",
-      collection: "actions",
-      kind: "action",
-      key: "id",
-    },
-  ];
-  for (const definition of definitions) {
-    const current =
-      readJson(root, definition.file)[definition.collection] || [];
-    const baseline =
-      readJsonAtRevision(root, revision, definition.file)[
-        definition.collection
-      ] || [];
-    const baselineByKey = new Map(
-      baseline.map((entry) => [entry[definition.key], entry]),
-    );
-    for (const entry of current) {
-      const label = `${definition.kind}:${entry[definition.key]}`;
-      for (const field of lifecycleFields) {
-        if (
-          !Object.prototype.hasOwnProperty.call(entry, field) ||
-          typeof entry[field] !== "string"
-        ) {
-          issues.push(`${label}: lifecycle field ${field} is missing`);
-        }
-      }
-      if (!capabilityGroups.has(entry.capabilityGroup)) {
-        issues.push(
-          `${label}: capability group ${entry.capabilityGroup || "<empty>"} is not registered`,
-        );
-      }
-      const previous = baselineByKey.get(entry[definition.key]);
-      const currentContract = publicSurfaceContract(entry, definition.kind);
-      if (
-        previous &&
-        JSON.stringify(currentContract) !==
-          JSON.stringify(publicSurfaceContract(previous, definition.kind))
-      ) {
-        const approval = policy.approvedPublicSurfaceTransitions?.[label];
-        const approved =
-          approval?.fromRevision === revision &&
-          String(approval?.rationale || "").trim() &&
-          JSON.stringify(approval?.contract) ===
-            JSON.stringify(currentContract);
-        if (!approved) {
-          issues.push(
-            `${label}: existing public contract drifted from ${revision}`,
-          );
-        }
-      }
-      if (!previous && !entry.nonDuplicationRationale) {
-        issues.push(
-          `${label}: new public surface requires a non-duplication rationale`,
-        );
-      }
-    }
-  }
-  return issues;
-}
-
 function evaluateAddedFunctionBudgets({
   file,
   metrics,
@@ -497,12 +389,18 @@ function checkMaintainability({ root = process.cwd() } = {}) {
     root,
     extendedCoverageRevision,
   );
+  const { governed: governedCurrent, migration: facadeMigration } =
+    governUniversalFacadeWorkflowMetrics({
+      root,
+      current,
+      workflowMetricsAtRevision,
+    });
   const issues = evaluateExceptionGovernance({ policy });
   issues.push(...evaluateExceptionBudget({ policy }));
   const hotspots = collectHotspots(root, current, 20, debt.hotspots || []);
   issues.push(
     ...evaluateDebtAuthority({
-      current,
+      current: governedCurrent,
       policy,
       debt,
       capabilityIds: new Set(
@@ -518,14 +416,19 @@ function checkMaintainability({ root = process.cwd() } = {}) {
   );
   issues.push(
     ...evaluateWorkflowBudgets({
-      current,
+      current: governedCurrent,
       baselineFiles: baselineWorkflows,
       policy,
     }),
   );
   issues.push(...evaluateRepositoryBudgets({ current, policy }));
   issues.push(
-    ...evaluatePublicSurface({ root, revision: enforcementRevision, policy }),
+    ...evaluatePublicSurface({
+      root,
+      revision: enforcementRevision,
+      policy,
+      migration: facadeMigration,
+    }),
   );
   if (issues.length > 0) {
     throw new Error(`maintainability check failed:\n- ${issues.join("\n- ")}`);

package/scripts/check-v4-release-topology.mjs

@@ -180,7 +180,9 @@ function permission(block, name) {
 function workflowSnapshot(relative) {
   const source = read(relative);
   const document = parseWorkflowDocument(source);
-  const jobs = document.jobs.map((job) => {
+  const jobs = document.jobs
+    .filter((job) => job.id !== "universal-bootstrap")
+    .map((job) => {
     const block = jobBlock(source, job.id);
     const uses = job.uses || null;
     return {
@@ -206,7 +208,7 @@ function workflowSnapshot(relative) {
           "direct-publication-command",
       ].filter(Boolean),
     };
-  });
+    });
   return {
     path: relative,
     triggers: document.triggers,
@@ -214,6 +216,7 @@ function workflowSnapshot(relative) {
     reusableEdges: parseYamlUses(source)
       .map(({ value }) => value)
       .filter((value) => /\.github\/workflows\//u.test(value))
+      .filter((value) => !/\/bootstrap\.yml(?:@v4)?$/u.test(value))
       .sort(),
   };
 }

package/scripts/check-v4-universal-workflow-bootstrap.mjs

@@ -0,0 +1,257 @@
+import assert from "node:assert/strict";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const contract = JSON.parse(
+  fs.readFileSync(
+    path.join(root, "architecture/v4-universal-workflow-bootstrap.json"),
+    "utf8",
+  ),
+);
+const admissionPolicy = JSON.parse(
+  fs.readFileSync(
+    path.join(root, "architecture/v4-universal-workflow-train-admission.json"),
+    "utf8",
+  ),
+);
+const fileRoot = (relative) =>
+  `sha256:${crypto
+    .createHash("sha256")
+    .update(fs.readFileSync(path.join(root, relative)))
+    .digest("hex")}`;
+
+const workflowRoot = path.join(root, ".github/workflows");
+const discovered = fs
+  .readdirSync(workflowRoot)
+  .filter((name) => /\.ya?ml$/u.test(name))
+  .map((name) => `.github/workflows/${name}`)
+  .filter((relative) =>
+    /(?:^|\n)\s*workflow_call:\s*(?:\n|$)/u.test(
+      fs.readFileSync(path.join(root, relative), "utf8"),
+    ),
+  )
+  .sort();
+
+assert.equal(
+  contract.schema,
+  "kungfu-buildchain-v4-universal-workflow-bootstrap/v1",
+);
+assert.deepEqual(
+  contract.inventoryWorkflows,
+  [...new Set(contract.inventoryWorkflows)].sort(),
+  "inventoried public workflows must be sorted and duplicate-free",
+);
+assert.deepEqual(
+  contract.inventoryWorkflows,
+  discovered,
+  "every active public workflow_call surface must be inventoried",
+);
+for (const relative of contract.inventoryWorkflows)
+  assert.ok(
+    fs.statSync(path.join(root, relative)).isFile(),
+    `inventoried workflow is unavailable: ${relative}`,
+  );
+assert.deepEqual(
+  contract.bootstrapGovernedWorkflows,
+  [...new Set(contract.bootstrapGovernedWorkflows)].sort(),
+  "Bootstrap-governed workflows must be sorted and duplicate-free",
+);
+assert.deepEqual(
+  contract.retiredWorkflowSurfaces,
+  [...new Set(contract.retiredWorkflowSurfaces)].sort(),
+  "retired workflow surfaces must be sorted and duplicate-free",
+);
+for (const relative of contract.retiredWorkflowSurfaces) {
+  assert.ok(
+    contract.inventoryWorkflows.includes(relative),
+    `retired workflow is outside the inventory: ${relative}`,
+  );
+  assert.match(
+    fs.readFileSync(path.join(root, relative), "utf8"),
+    /retired/u,
+    `retired workflow does not fail closed explicitly: ${relative}`,
+  );
+}
+const activeWorkflows = contract.inventoryWorkflows.filter(
+  (relative) =>
+    !contract.retiredWorkflowSurfaces.includes(relative) &&
+    relative !== contract.bootstrap.consumerRecoveryWorkflow,
+);
+assert.deepEqual(
+  contract.bootstrapGovernedWorkflows,
+  activeWorkflows,
+  "every active public reusable workflow must be Bootstrap-governed",
+);
+for (const relative of contract.bootstrapGovernedWorkflows) {
+  assert.ok(
+    contract.inventoryWorkflows.includes(relative),
+    `Bootstrap-governed workflow is outside the inventory: ${relative}`,
+  );
+  const source = fs.readFileSync(path.join(root, relative), "utf8");
+  assert.ok(
+    relative === contract.bootstrap.publicWorkflow ||
+      /uses:\s+(?:\.\/)?\.github\/workflows\/bootstrap\.yml/u.test(source) ||
+      /uses:\s+kungfu-systems\/buildchain\/\.github\/workflows\/bootstrap\.yml@/u.test(
+        source,
+      ),
+    `workflow is declared governed without a Bootstrap edge: ${relative}`,
+  );
+}
+
+assert.deepEqual(contract.complexityBudget, {
+  bootstrapAbis: 1,
+  requestEnvelopes: 1,
+  candidateResolvers: 1,
+  candidateEngines: 1,
+  terminalReceiptAuthorities: 1,
+  perWorkflowBootstrapImplementations: 0,
+  buildchainOnlySelfReleasePaths: 0,
+  perIncidentConsumerEdits: 0,
+});
+assert.equal(contract.bootstrap.discoveryRefExecutionAuthority, false);
+assert.equal(contract.bootstrap.exactShaExecutionAuthority, true);
+assert.equal(contract.bootstrap.consumerSourceMutationPerIncident, false);
+assert.equal(contract.bootstrap.buildchainReleasePromotionPerIncident, false);
+assert.equal(contract.bootstrap.selfDogfoodUsesPublicContract, true);
+assert.equal(contract.bootstrap.recoveryDependsOnPublishedBuildchain, false);
+assert.deepEqual(
+  contract.capabilityAdapters.map(({ id }) => id).sort(),
+  [...admissionPolicy.allowedCapabilities].sort(),
+  "every admitted capability must have one real candidate adapter",
+);
+for (const adapter of contract.capabilityAdapters) {
+  assert.match(adapter.execution, /^exact-candidate-/u);
+  assert.ok(adapter.payloadSchema.endsWith("/v1"));
+}
+assert.ok(!admissionPolicy.allowedCapabilities.includes("workflow-contract"));
+assert.deepEqual(
+  admissionPolicy.contractRoots,
+  [
+    fileRoot("architecture/v4-universal-workflow-bootstrap.json"),
+    fileRoot(contract.bootstrap.faultCampaign),
+    fileRoot("packages/core/v4-universal-workflow-bootstrap.js"),
+    fileRoot("scripts/v4-universal-workflow-backflow.mjs"),
+    fileRoot("scripts/v4-universal-workflow-engine.mjs"),
+    fileRoot("scripts/v4-universal-workflow-self-dogfood.mjs"),
+    fileRoot(contract.bootstrap.publicWorkflow),
+  ].sort(),
+);
+assert.doesNotMatch(
+  fs.readFileSync(
+    path.join(root, contract.bootstrap.candidateEnginePath),
+    "utf8",
+  ),
+  /request\.capability\.id\s*===\s*["']workflow-contract["']/u,
+  "contract-only validation must not be admitted as successful execution",
+);
+const bootstrapSource = fs.readFileSync(
+  path.join(root, contract.bootstrap.publicWorkflow),
+  "utf8",
+);
+assert.doesNotMatch(
+  bootstrapSource,
+  /admission-policy-json:/u,
+  "callers must not supply their own admission authority",
+);
+execFileSync(
+  process.execPath,
+  [path.join(root, contract.migration.compatibilityFacadeGenerator), "--check"],
+  { stdio: "inherit" },
+);
+assert.doesNotMatch(bootstrapSource, /^    permissions:/mu);
+assert.match(bootstrapSource, /settle:[\s\S]*needs: \[admit, execute\]/u);
+assert.match(
+  bootstrapSource,
+  /ascii_downcase\) == "kungfu-origin"[\s\S]*\.name == "check"[\s\S]*map\(select\(\.status == "completed" and \(\.conclusion \/\/ ""\) != ""\)\)[\s\S]*candidate\/architecture\/v4-universal-workflow-train-admission\.json/u,
+);
+const consumerTemplate = fs.readFileSync(
+  path.join(root, contract.bootstrap.consumerTemplate),
+  "utf8",
+);
+const consumerRecoveryTemplate = fs.readFileSync(
+  path.join(root, contract.bootstrap.consumerRecoveryTemplate),
+  "utf8",
+);
+const consumerRecoveryWorkflow = fs.readFileSync(
+  path.join(root, contract.bootstrap.consumerRecoveryWorkflow),
+  "utf8",
+);
+const selfDogfood = fs.readFileSync(
+  path.join(root, contract.bootstrap.selfDogfoodWorkflow),
+  "utf8",
+);
+assert.match(
+  consumerTemplate,
+  /uses:\s+kungfu-systems\/buildchain\/\.github\/workflows\/bootstrap\.yml@v4/u,
+);
+assert.match(
+  consumerRecoveryTemplate,
+  /recovery-admit:[\s\S]*recovery-execute:/u,
+);
+assert.match(
+  consumerRecoveryTemplate,
+  /Parse exact recovery coordinates without Buildchain code[\s\S]*Prove exact independent review before candidate code runs[\s\S]*ascii_downcase\) == "kungfu-origin"[\s\S]*\.name == "check"[\s\S]*Admit candidate policy and exact-head checks[\s\S]*map\(select\(\.status == "completed" and \(\.conclusion \/\/ ""\) != ""\)\)/u,
+);
+assert.match(
+  consumerRecoveryTemplate,
+  /recovery-execute:[\s\S]*needs: recovery-admit[\s\S]*contents: write/u,
+);
+assert.doesNotMatch(
+  consumerRecoveryTemplate,
+  /uses:\s+kungfu-systems\/buildchain\/\.github\/workflows\//u,
+  "consumer recovery must not parse any published Buildchain workflow",
+);
+assert.equal(
+  consumerRecoveryWorkflow,
+  consumerRecoveryTemplate,
+  "the Buildchain self-consumer must exercise the exact distributable recovery shell",
+);
+assert.match(
+  selfDogfood,
+  /uses:\s+kungfu-systems\/buildchain\/\.github\/workflows\/bootstrap\.yml@train\/v4\/v4\.0\/universal-reusable-workflow-bootstrap/u,
+);
+assert.match(
+  selfDogfood,
+  /uses:\s+\.\/\.github\/workflows\/universal-bootstrap-recovery\.yml/u,
+);
+assert.doesNotMatch(
+  selfDogfood,
+  /\.github\/workflows\/bootstrap\.yml@(?:v4|v4-alpha)(?:\s|$)/u,
+  "Train self-dogfood must not depend on an alpha or stable Bootstrap tag",
+);
+for (const channel of ["conformance", "alpha", "stable"]) {
+  assert.match(selfDogfood, new RegExp(`primary-${channel}:`, "u"));
+  assert.match(selfDogfood, new RegExp(`recovery-${channel}:`, "u"));
+}
+assert.match(
+  selfDogfood,
+  /\.state == "APPROVED"[\s\S]*ascii_downcase\) == "kungfu-origin"[\s\S]*\.name == "check"[\s\S]*\.conclusion == "success"/u,
+);
+assert.match(
+  consumerRecoveryTemplate,
+  /result-json:[\s\S]*value:\s*\$\{\{ jobs\.recovery-execute\.outputs\.result-json \}\}/u,
+);
+
+console.log(
+  JSON.stringify({
+    ok: true,
+    schema: contract.schema,
+    publicWorkflowCount: discovered.length,
+    activePublicWorkflowCount: activeWorkflows.length,
+    retiredWorkflowCount: contract.retiredWorkflowSurfaces.length,
+    inventoriedWorkflowCount: contract.inventoryWorkflows.length,
+    inventoryCoveragePercent: 100,
+    governedWorkflowCount: contract.bootstrapGovernedWorkflows.length,
+    governedCoveragePercent: Number(
+      (
+        (contract.bootstrapGovernedWorkflows.length / activeWorkflows.length) *
+        100
+      ).toFixed(2),
+    ),
+    migration: contract.migration,
+  }),
+);

package/scripts/generate-channel-build-workflow.mjs

@@ -3,6 +3,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { migrateV4UniversalWorkflowFacade } from "./generate-v4-universal-workflow-facades.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const sourcePath = path.join(root, ".github/workflows/.build.yml");
@@ -403,7 +404,10 @@ export function generateChannelBuildWorkflow(source) {
       ].join("\n"),
     )
     .replace("\n  alpha:\n", `\n${routerControllerPlanJob()}\n\n  alpha:\n`);
-  return `${generated.trimEnd()}\n\n${routerControllerReceiptJob()}\n\n${routerAggregateJob()}\n`;
+  return migrateV4UniversalWorkflowFacade(
+    `${generated.trimEnd()}\n\n${routerControllerReceiptJob()}\n\n${routerAggregateJob()}\n`,
+    ".github/workflows/build.yml",
+  );
 }
 
 function main() {

package/scripts/generate-channel-promotion-workflow.mjs

@@ -3,6 +3,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { migrateV4UniversalWorkflowFacade } from "./generate-v4-universal-workflow-facades.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const sourcePath = path.join(root, ".github/workflows/.release-candidate-promote.yml");
@@ -302,7 +303,7 @@ export function generateChannelPromotionWorkflow(source, { major = 2, shellRouti
     if (!inputNames.includes(required)) throw new Error(`advanced promotion workflow missing input: ${required}`);
   }
   const invokeForwarded = routedInputs(inputNames, alphaRoute, major);
-  return `# Generated by scripts/generate-channel-promotion-workflow.mjs. Do not edit directly.
+  return migrateV4UniversalWorkflowFacade(`# Generated by scripts/generate-channel-promotion-workflow.mjs. Do not edit directly.
 name: Release Candidate Promote
 
 on:
@@ -513,7 +514,7 @@ ${consumerAdmissionJob()}
     with:
 ${invokeForwarded}
     secrets: inherit
-`;
+`, ".github/workflows/release-candidate-promote.yml");
 }
 
 function main() {