@kungfu-tech/buildchain 4.0.2-alpha.9 → 4.0.3-alpha.0

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,
@@ -110,6 +112,13 @@ function ensureMaintainabilityRevisionsAvailable(
   );
 }
 
+function implementationPathAtPresent(root, historicalPath) {
+  const policyPath = path.join(root, "architecture/implementation-naming.json");
+  if (!fs.existsSync(policyPath)) return historicalPath;
+  const policy = readJson(root, "architecture/implementation-naming.json");
+  return policy.pathMigrations[historicalPath] || historicalPath;
+}
+
 function sourceMetricsAtRevision(root, revision) {
   const files = gitOutput(root, ["ls-tree", "-r", "--name-only", revision])
     .split("\n")
@@ -117,7 +126,7 @@ function sourceMetricsAtRevision(root, revision) {
     .sort();
   return Object.fromEntries(
     files.map((file) => [
-      file,
+      implementationPathAtPresent(root, file),
       analyzeSource(file, gitOutput(root, ["show", `${revision}:${file}`])),
     ]),
   );
@@ -132,7 +141,7 @@ function testMetricsAtRevision(root, revision) {
     .sort();
   return Object.fromEntries(
     files.map((file) => [
-      file,
+      implementationPathAtPresent(root, file),
       analyzeSource(file, gitOutput(root, ["show", `${revision}:${file}`])),
     ]),
   );
@@ -162,116 +171,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 +396,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 +423,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-public-dogfood-contract.mjs → check-public-dogfood-contract.mjs}

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import fs from "node:fs";
+import { readWorkflowTaxonomy, workflowPath } from "./workflow-taxonomy.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -8,13 +9,13 @@ const DEFAULT_ROOT = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
   "..",
 );
-const CALLER_PATH = ".github/workflows/v4-public-consumer-dogfood.yml";
-const REUSABLE_PATH = ".github/workflows/v4-stage-capsule-canary.yml";
-export const V4_PUBLIC_DOGFOOD_ALPHA_REF = "v4-alpha";
+const CALLER_PATH = ".github/workflows/self-build-public-consumer-dogfood.yml";
+const REUSABLE_PATH = ".github/workflows/public-build-stage-capsule-canary.yml";
+export const PUBLIC_DOGFOOD_ALPHA_REF = "v4-alpha";
 const PRIVATE_CONSUMER = ["buildchain", "self", "dogfood"].join("-");
 const PRIVATE_SHADOW = ["kungfu", "shadow"].join("-");
 
-export function expectedV4PublicDogfoodWorkflow(validationRef) {
+export function expectedPublicDogfoodWorkflow(validationRef) {
   return `name: V4 Public Consumer Dogfood
 
 on:
@@ -26,7 +27,7 @@ permissions:
 
 jobs:
   dogfood:
-    uses: kungfu-systems/buildchain/.github/workflows/v4-stage-capsule-canary.yml@${validationRef}
+    uses: kungfu-systems/buildchain/.github/workflows/public-build-stage-capsule-canary.yml@${validationRef}
     with:
       consumer: buildchain
       node-version: "24"
@@ -93,18 +94,27 @@ function assertReusableWorkflow(root) {
 
 function assertWorkflowInventory(root) {
   const workflowRoot = path.join(root, ".github/workflows");
+  const taxonomy = readWorkflowTaxonomy(root);
   for (const entry of fs.readdirSync(workflowRoot, { withFileTypes: true })) {
     if (!entry.isFile() || !/\.ya?ml$/u.test(entry.name)) continue;
-    const relative = `.github/workflows/${entry.name}`;
+    let relative = `.github/workflows/${entry.name}`;
     const text = read(root, relative);
+    const canonical = taxonomy?.entries.find(
+      (item) => workflowPath(item) === relative && item.compatibility,
+    );
+    if (canonical) {
+      if (read(root, canonical.compatibility.path) !== text)
+        fail(`${relative} differs from its public compatibility identity`);
+      relative = canonical.compatibility.path;
+    }
     if (
       relative !== REUSABLE_PATH &&
-      text.includes("scripts/v4-stage-capsule-qualification.mjs")
+      text.includes("scripts/stage-capsule-qualification.mjs")
     )
       fail(`${relative} invokes the private qualification script directly`);
     if (
       relative !== CALLER_PATH &&
-      text.includes(".github/workflows/v4-stage-capsule-canary.yml@")
+      text.includes(".github/workflows/public-build-stage-capsule-canary.yml@")
     )
       fail(`${relative} creates a second v4 dogfood caller`);
     if (relative !== REUSABLE_PATH && relative !== CALLER_PATH)
@@ -113,18 +123,20 @@ function assertWorkflowInventory(root) {
 }
 
 function assertProtectedVerify(root) {
-  const verify = read(root, ".github/workflows/verify.yml");
+  const verify = read(root, ".github/workflows/self-build-verify.yml");
   for (const required of [
     "needs: stage-capsule-checkpoints",
-    "name: Enforce public consumer-only v4 dogfood",
-    "run: node scripts/check-v4-public-dogfood-contract.mjs",
+    "name: Run declared verify lifecycle (full source tests and generated artifact checks)",
+    "node .buildchain/runtime/bin/buildchain.mjs lifecycle run verify",
+    "run: node scripts/source-verification-evidence.mjs plan",
+    "run: node scripts/source-verification-evidence.mjs seal",
   ])
     if (!verify.includes(required))
       fail(`Verify is missing protected gate ${required}`);
   for (const forbidden of [
     "stage-capsule-qualification:",
     "stage-capsule-qualification-reconciliation:",
-    "scripts/v4-stage-capsule-qualification.mjs",
+    "scripts/stage-capsule-qualification.mjs",
   ])
     if (verify.includes(forbidden))
       fail(`Verify retains private dogfood path ${forbidden}`);
@@ -133,14 +145,14 @@ function assertProtectedVerify(root) {
 function assertArchitecture(root) {
   const architecture = exactJson(
     root,
-    "architecture/v4-stage-capsule-qualification.json",
+    "architecture/stage-capsule-qualification.json",
   );
   const dogfood = architecture.publicConsumerDogfood;
   const validationRef = dogfood?.validationRef;
-  if (validationRef !== V4_PUBLIC_DOGFOOD_ALPHA_REF)
+  if (validationRef !== PUBLIC_DOGFOOD_ALPHA_REF)
     fail("architecture validationRef must use the floating v4-alpha channel");
   const caller = read(root, CALLER_PATH);
-  if (caller !== expectedV4PublicDogfoodWorkflow(validationRef))
+  if (caller !== expectedPublicDogfoodWorkflow(validationRef))
     fail(`${CALLER_PATH} must remain the exact thin public consumer caller`);
   if (JSON.stringify(architecture.campaign?.consumers) !== '["buildchain"]')
     fail(
@@ -150,7 +162,7 @@ function assertArchitecture(root) {
     !dogfood ||
     dogfood.callerWorkflow !== CALLER_PATH ||
     dogfood.reusableWorkflow !==
-      "kungfu-systems/buildchain/.github/workflows/v4-stage-capsule-canary.yml" ||
+      "kungfu-systems/buildchain/.github/workflows/public-build-stage-capsule-canary.yml" ||
     dogfood.runtimeBinding !== "job.workflow_sha" ||
     dogfood.consumerSourceBinding !== "github.sha" ||
     JSON.stringify(dogfood.executableStages) !==
@@ -193,6 +205,7 @@ function assertConsumerLifecycle(root) {
     '[lifecycle.install]\ncommand = "corepack enable pnpm && corepack pnpm@11.7.0 install --frozen-lockfile"',
     '[lifecycle.build]\ncommand = "corepack pnpm@11.7.0 run build && corepack pnpm@11.7.0 run generate:site"',
     "[lifecycle.verify]\ncommands = [",
+    '"corepack pnpm@11.7.0 run check",',
   ])
     if (!lifecycle.includes(declaration))
       fail(
@@ -205,10 +218,10 @@ function assertConsumerLifecycle(root) {
 
 function assertPolicySources(root) {
   for (const relative of [
-    "packages/core/v4-stage-capsule-qualification.js",
-    "packages/core/v4-stage-capsule-qualification-campaign.js",
-    "scripts/v4-stage-capsule-qualification.mjs",
-    "architecture/v4-stage-capsule-qualification.json",
+    "packages/core/stage-capsule-qualification.js",
+    "packages/core/stage-capsule-qualification-campaign.js",
+    "scripts/stage-capsule-qualification.mjs",
+    "architecture/stage-capsule-qualification.json",
     "docs/v4-stage-capsule.md",
   ])
     assertNoPrivateMarkers(relative, read(root, relative));
@@ -218,7 +231,7 @@ function assertPolicySources(root) {
     "same public reusable-workflow contract as every other consumer",
     "No agent may add or restore a relative/self reusable-workflow call",
     "never solve recursion with an internal exception",
-    "scripts/check-v4-public-dogfood-contract.mjs",
+    "scripts/check-public-dogfood-contract.mjs",
     "source-persisted exact commit SHA",
     "v4-alpha",
   ])
@@ -228,13 +241,13 @@ function assertPolicySources(root) {
   const packageJson = exactJson(root, "package.json");
   if (
     !String(packageJson.scripts?.check || "").includes(
-      "node scripts/check-v4-public-dogfood-contract.mjs",
+      "node scripts/check-public-dogfood-contract.mjs",
     )
   )
     fail("pnpm run check does not include the public dogfood gate");
 }
 
-export function checkV4PublicDogfoodContract(root = DEFAULT_ROOT) {
+export function checkPublicDogfoodContract(root = DEFAULT_ROOT) {
   assertReusableWorkflow(root);
   assertWorkflowInventory(root);
   assertProtectedVerify(root);
@@ -257,7 +270,7 @@ if (
   path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
 ) {
   try {
-    process.stdout.write(`${JSON.stringify(checkV4PublicDogfoodContract())}\n`);
+    process.stdout.write(`${JSON.stringify(checkPublicDogfoodContract())}\n`);
   } catch (error) {
     process.stderr.write(`${error.message}\n`);
     process.exitCode = 1;