@kungfu-tech/buildchain 4.0.1-alpha.5 → 4.0.1-alpha.55

package/scripts/check-ci-lane-change-budget.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { execFileSync } from "node:child_process";
+import { evaluateCiLaneChangeBudget } from "../packages/core/ci-lane-change-budget.js";
+
+const root = process.cwd();
+const workflowRoot = path.join(root, ".github", "workflows");
+const policyPath = path.join(
+  root,
+  "architecture",
+  "ci-lane-change-budget.json",
+);
+
+const workflows = fs
+  .readdirSync(workflowRoot, { withFileTypes: true })
+  .filter((entry) => entry.isFile() && /\.(?:yaml|yml)$/u.test(entry.name))
+  .map((entry) => {
+    const workflowPath = path.posix.join(".github/workflows", entry.name);
+    return {
+      path: workflowPath,
+      text: fs.readFileSync(path.join(workflowRoot, entry.name), "utf8"),
+    };
+  })
+  .sort((left, right) => left.path.localeCompare(right.path));
+
+const policy = JSON.parse(fs.readFileSync(policyPath, "utf8"));
+const baselineRevision = String(policy.baseline?.gitRevision || "").trim();
+if (!/^[0-9a-f]{40}$/u.test(baselineRevision)) {
+  throw new Error("baseline.gitRevision must be an exact Git commit");
+}
+const embeddedBaselineLanes = policy.baseline?.lanes;
+if (
+  !Array.isArray(embeddedBaselineLanes) ||
+  embeddedBaselineLanes.length === 0
+) {
+  throw new Error("baseline.lanes must contain the exact offline lane set");
+}
+const embeddedLaneSetRoot = `sha256:${crypto
+  .createHash("sha256")
+  .update(`${JSON.stringify(embeddedBaselineLanes)}\n`)
+  .digest("hex")}`;
+if (embeddedLaneSetRoot !== policy.baseline?.laneSetRoot) {
+  throw new Error("baseline laneSetRoot does not match baseline.lanes");
+}
+
+let baselineWorkflows = null;
+try {
+  execFileSync("git", ["cat-file", "-e", `${baselineRevision}^{commit}`], {
+    cwd: root,
+    stdio: "ignore",
+  });
+  const baselinePaths = execFileSync(
+    "git",
+    [
+      "ls-tree",
+      "-r",
+      "--name-only",
+      baselineRevision,
+      "--",
+      ".github/workflows",
+    ],
+    { cwd: root, encoding: "utf8" },
+  )
+    .split(/\r?\n/u)
+    .filter((value) => /\.(?:yaml|yml)$/u.test(value))
+    .sort();
+  baselineWorkflows = baselinePaths.map((workflowPath) => ({
+    path: workflowPath,
+    text: execFileSync("git", ["show", `${baselineRevision}:${workflowPath}`], {
+      cwd: root,
+      encoding: "utf8",
+    }),
+  }));
+} catch {
+  // Shallow and exported source cuts may not contain the pinned commit object.
+  // The content-rooted embedded lane set remains the exact offline authority.
+}
+
+const embeddedEvaluation = evaluateCiLaneChangeBudget({
+  policy,
+  workflows,
+});
+const evaluation = baselineWorkflows
+  ? evaluateCiLaneChangeBudget({ policy, workflows, baselineWorkflows })
+  : embeddedEvaluation;
+if (
+  baselineWorkflows &&
+  (evaluation.baselineLaneCount !== embeddedEvaluation.baselineLaneCount ||
+    JSON.stringify(evaluation.newLanes) !==
+      JSON.stringify(embeddedEvaluation.newLanes))
+) {
+  throw new Error(
+    "embedded baseline lanes do not match the pinned baseline revision",
+  );
+}
+process.stdout.write(`${JSON.stringify(evaluation, null, 2)}\n`);
+if (!evaluation.ok) process.exitCode = 1;

package/scripts/check-internal-architecture.mjs

@@ -100,8 +100,8 @@ function dependencyCycles(graph) {
 }
 
 function assertIndexShape(index) {
-  if (index?.schemaVersion !== 1) {
-    throw new Error("internal architecture index schemaVersion must be 1");
+  if (index?.schemaVersion !== 2) {
+    throw new Error("internal architecture index schemaVersion must be 2");
   }
   for (const field of [
     "coverageRoots",
@@ -209,7 +209,27 @@ function evaluateCapabilities(root, index) {
     if (!Array.isArray(capability.tests) || capability.tests.length === 0) {
       issues.push(`${capability.id}: test mapping is empty`);
     }
-    for (const field of ["implementation", "tests", "contracts"]) {
+    if (!Array.isArray(capability.generatedOutputs)) {
+      issues.push(`${capability.id}: generated output mapping is missing`);
+    }
+    if (
+      !Array.isArray(capability.validationCommands) ||
+      capability.validationCommands.length === 0
+    ) {
+      issues.push(`${capability.id}: validation command mapping is empty`);
+    } else if (
+      capability.validationCommands.some(
+        (command) => !String(command || "").trim(),
+      )
+    ) {
+      issues.push(`${capability.id}: validation command is empty`);
+    }
+    for (const field of [
+      "implementation",
+      "tests",
+      "contracts",
+      "generatedOutputs",
+    ]) {
       for (const relativePath of capability[field] || []) {
         if (!fs.existsSync(path.resolve(root, relativePath))) {
           issues.push(

package/scripts/check-inventory.mjs

@@ -285,6 +285,10 @@ const channelPromotionWorkflow = fs.readFileSync(
   path.join(root, ".github/workflows/release-candidate-promote.yml"),
   "utf8",
 );
+const boundedAlphaRecoveryWorkflow = fs.readFileSync(
+  path.join(root, ".github/workflows/buildchain-ref-promotion-recovery.yml"),
+  "utf8",
+);
 const promotionShellRouting = parsePromotionShellRouting(
   fs.readFileSync(path.join(root, ".buildchain/promotion-shell-routing.json"), "utf8"),
   { major: Number(selfDogfoodMajor) },
@@ -295,6 +299,20 @@ if (channelPromotionWorkflow !== generateChannelPromotionWorkflow(advancedPromot
 })) {
   throw new Error("generated channel promotion workflow is stale");
 }
+for (const requiredSnippet of [
+  "uses: kungfu-systems/buildchain/.github/workflows/.release-candidate-promote.yml@alpha/v4/v4.0",
+  "promotion-shell-ref: ${{ needs.consumer-admission.outputs.shell-call-ref }}",
+  "declarative-release-tail: true",
+]) {
+  if (!boundedAlphaRecoveryWorkflow.includes(requiredSnippet)) {
+    throw new Error(`bounded alpha recovery missing bootstrap contract: ${requiredSnippet}`);
+  }
+}
+for (const workflowSource of [boundedAlphaRecoveryWorkflow, channelPromotionWorkflow]) {
+  if (workflowSource.includes("channel-finalization-recovery")) {
+    throw new Error("Buildchain-only alpha bootstrap must not add a public or recovery workflow input");
+  }
+}
 for (const requiredSnippet of [
   "buildchain-channel:",
   `/${promotionShellRouting.alpha.workflowPath}@${promotionShellRouting.alpha.callRef}`,
@@ -759,8 +777,8 @@ const registeredActionIds = (workflowRegistry.actions || []).map((entry) => entr
 const readmeActionIndex = fs.readFileSync(path.join(root, "README.md"), "utf8");
 const mapActionIndex = fs.readFileSync(path.join(root, "docs/MAP.md"), "utf8");
 const retrospectiveActionIndex = fs.readFileSync(path.join(root, ".github/retrospectives/2026-07-10-buildchain-consolidation.md"), "utf8");
-if (registeredActionIds.length !== 7) {
-  throw new Error(`workflow-registry.json must expose the seven current action entries, got ${registeredActionIds.length}`);
+if (registeredActionIds.length !== 8) {
+  throw new Error(`workflow-registry.json must expose the eight current action entries, got ${registeredActionIds.length}`);
 }
 for (const actionId of registeredActionIds) {
   if (!readmeActionIndex.includes(`actions/${actionId}`) || !mapActionIndex.includes(`actions/${actionId}`)) {
@@ -1021,16 +1039,16 @@ for (const forbiddenSnippet of [
 for (const requiredSnippet of [
   "id-token: write",
   "actions: write",
-  "uses: ./.github/workflows/.release-candidate-promote.yml",
+  "uses: kungfu-systems/buildchain/.github/workflows/.release-candidate-promote.yml@v4-alpha",
   "github.event.workflow_run.event == 'push'",
   "!startsWith(github.event.workflow_run.display_title, 'chore(release): prepare v')",
   "!startsWith(github.event.workflow_run.display_title, 'chore(release): release v')",
   "resume-candidate-run-id:",
   "resume-expected-source-tree:",
-  "resume-buildchain-runtime-sha:",
-  "github-release: true",
+  "resume-buildchain-runtime-ref:",
+  "uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v4",
   "release-passport-buildchain-self-kfd: true",
-  "artifact-patterns: ${{ startsWith(github.event.workflow_run.head_branch || inputs['target-ref'], 'alpha/') && 'buildchain-package-*' || '' }}",
+  "declarative-release-tail: true",
   "release-passport-impact-json: .buildchain/release-impact.json",
 ]) {
   if (!buildchainRefPromotionWorkflow.includes(requiredSnippet)) {

package/scripts/check-maintainability.mjs

@@ -5,10 +5,52 @@ import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
 import {
-  analyzeJavaScript,
+  analyzeSource,
+  analyzeWorkflow,
   collectMaintainabilityMetrics,
   isHandMaintainedSource,
 } from "./maintainability-metrics.mjs";
+import {
+  calculateDebtMeasuredExcess,
+  evaluateDebtAuthority,
+  evaluateDebtBudget,
+  evaluateExceptionBudget,
+  evaluateExceptionGovernance,
+  evaluateTestBudgets,
+  evaluateWorkflowBudgets,
+} from "./maintainability-governance.mjs";
+
+function collectHotspots(root, current, limit = 20, shallowFallback = []) {
+  const maintained = new Set([
+    ...Object.keys(current.files || {}),
+    ...Object.keys(current.tests || {}),
+    ...Object.keys(current.workflows || {}),
+  ]);
+  // Shallow consumers cannot reproduce repository-wide churn ranking.
+  // Reuse the audited routes; full clones still re-rank them below.
+  // This keeps consumer verification deterministic without inventing history.
+  if (
+    gitOutput(root, ["rev-parse", "--is-shallow-repository"]).trim() === "true"
+  ) {
+    return shallowFallback.slice(0, limit);
+  }
+  const counts = new Map();
+  const record = (file) =>
+    maintained.has(file) && counts.set(file, (counts.get(file) || 0) + 1);
+  for (const args of [
+    ["log", "-n", "500", "--format=", "--name-only"],
+    ["diff", "--name-only"],
+  ])
+    for (const file of gitOutput(root, args).split("\n").filter(Boolean))
+      record(file);
+  return [...counts]
+    .sort(
+      ([leftPath, left], [rightPath, right]) =>
+        right - left || leftPath.localeCompare(rightPath),
+    )
+    .slice(0, limit)
+    .map(([file]) => file);
+}
 
 function readJson(root, file) {
   return JSON.parse(fs.readFileSync(path.join(root, file), "utf8"));
@@ -68,7 +110,35 @@ function sourceMetricsAtRevision(root, revision) {
   return Object.fromEntries(
     files.map((file) => [
       file,
-      analyzeJavaScript(file, gitOutput(root, ["show", `${revision}:${file}`])),
+      analyzeSource(file, gitOutput(root, ["show", `${revision}:${file}`])),
+    ]),
+  );
+}
+
+function testMetricsAtRevision(root, revision) {
+  const files = gitOutput(root, ["ls-tree", "-r", "--name-only", revision])
+    .split("\n")
+    .filter((file) =>
+      /(?:^tests\/|(?:^|\/)tests?\/).+\.(?:c|m)?js$/u.test(file),
+    )
+    .sort();
+  return Object.fromEntries(
+    files.map((file) => [
+      file,
+      analyzeSource(file, gitOutput(root, ["show", `${revision}:${file}`])),
+    ]),
+  );
+}
+
+function workflowMetricsAtRevision(root, revision) {
+  const files = gitOutput(root, ["ls-tree", "-r", "--name-only", revision])
+    .split("\n")
+    .filter((file) => /^\.github\/workflows\/.*\.ya?ml$/u.test(file))
+    .sort();
+  return Object.fromEntries(
+    files.map((file) => [
+      file,
+      analyzeWorkflow(file, gitOutput(root, ["show", `${revision}:${file}`])),
     ]),
   );
 }
@@ -276,10 +346,14 @@ function evaluateRepositoryBudgets({ current, policy }) {
   return issues;
 }
 
+function budgetsForFile(policy, file) {
+  return file.endsWith(".rs") ? policy.rustBudgets : policy.sourceBudgets;
+}
+
 function evaluateMaintainability({ current, baselineFiles, policy }) {
   const issues = [];
-  const budgets = policy.sourceBudgets;
   for (const [file, metrics] of Object.entries(current.files)) {
+    const budgets = budgetsForFile(policy, file);
     const baseline = baselineFiles[file];
     if (!baseline) {
       const transition = policy.approvedNewFileTransitions?.[file];
@@ -381,15 +455,66 @@ function evaluateMaintainability({ current, baselineFiles, policy }) {
 
 function checkMaintainability({ root = process.cwd() } = {}) {
   const policy = readJson(root, "architecture/maintainability-policy.json");
+  if (policy.schemaVersion !== 2) {
+    throw new Error("maintainability policy schemaVersion must be 2");
+  }
   const baseline = readJson(root, policy.baseline);
   const enforcementRevision = policy.enforcementRevision || baseline.revision;
+  const extendedCoverageRevision =
+    policy.extendedCoverageRevision || enforcementRevision;
   const hydratedRevisions = ensureMaintainabilityRevisionsAvailable(root, {
     baselineRevision: baseline.revision,
     enforcementRevision,
   });
+  const hydratedExtendedCoverageRevision = ensureRevisionAvailable(
+    root,
+    extendedCoverageRevision,
+  );
   const current = collectMaintainabilityMetrics({ root });
+  const debt = readJson(root, "architecture/maintainability-debt.json");
+  const architecture = readJson(
+    root,
+    "architecture/internal-capabilities.json",
+  );
   const baselineFiles = sourceMetricsAtRevision(root, enforcementRevision);
-  const issues = evaluateMaintainability({ current, baselineFiles, policy });
+  const extendedSourceFiles = sourceMetricsAtRevision(
+    root,
+    extendedCoverageRevision,
+  );
+  for (const [file, metrics] of Object.entries(extendedSourceFiles)) {
+    if (file.endsWith(".rs")) baselineFiles[file] = metrics;
+  }
+  const baselineTests = testMetricsAtRevision(root, extendedCoverageRevision);
+  const baselineWorkflows = workflowMetricsAtRevision(
+    root,
+    extendedCoverageRevision,
+  );
+  const issues = evaluateExceptionGovernance({ policy });
+  issues.push(...evaluateExceptionBudget({ policy }));
+  const hotspots = collectHotspots(root, current, 20, debt.hotspots || []);
+  issues.push(
+    ...evaluateDebtAuthority({
+      current,
+      policy,
+      debt,
+      capabilityIds: new Set(
+        architecture.capabilities.map((entry) => entry.id),
+      ),
+      hotspots,
+    }),
+  );
+  issues.push(...evaluateDebtBudget({ debt, policy }));
+  issues.push(...evaluateMaintainability({ current, baselineFiles, policy }));
+  issues.push(
+    ...evaluateTestBudgets({ current, baselineFiles: baselineTests, policy }),
+  );
+  issues.push(
+    ...evaluateWorkflowBudgets({
+      current,
+      baselineFiles: baselineWorkflows,
+      policy,
+    }),
+  );
   issues.push(...evaluateRepositoryBudgets({ current, policy }));
   issues.push(
     ...evaluatePublicSurface({ root, revision: enforcementRevision, policy }),
@@ -401,12 +526,18 @@ function checkMaintainability({ root = process.cwd() } = {}) {
     schemaVersion: 1,
     baselineRevision: baseline.revision,
     enforcementRevision,
+    extendedCoverageRevision,
     hydratedBaselineRevision: hydratedRevisions[baseline.revision],
     hydratedEnforcementRevision: hydratedRevisions[enforcementRevision],
+    hydratedExtendedCoverageRevision,
     trackedFiles: current.repository.trackedFiles,
     sourceFiles: current.repository.handMaintainedSourceFiles,
     publicSurface: current.publicSurface,
     hotspots: current.hotspots,
+    governedDebtSurfaces: Object.values(debt.surfaces).reduce(
+      (total, entries) => total + Object.keys(entries).length,
+      0,
+    ),
   };
 }
 
@@ -427,11 +558,21 @@ if (
 }
 
 export {
+  calculateDebtMeasuredExcess,
   checkMaintainability,
+  collectHotspots,
   ensureMaintainabilityRevisionsAvailable,
   ensureRevisionAvailable,
   evaluateMaintainability,
+  evaluateDebtAuthority,
+  evaluateDebtBudget,
+  evaluateExceptionBudget,
+  evaluateExceptionGovernance,
   evaluateRepositoryBudgets,
+  evaluateTestBudgets,
+  evaluateWorkflowBudgets,
   evaluatePublicSurface,
   sourceMetricsAtRevision,
+  testMetricsAtRevision,
+  workflowMetricsAtRevision,
 };

package/scripts/check-project-cut-merge-queue-admission.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import {
+  ProjectCutAdmissionError,
+  qualifyProjectCut,
+  releaseFamilyQueueLease,
+} from "./project-cut-merge-queue-admission.mjs";
+
+function parseArguments(argv) {
+  const options = {};
+  const names = new Map([
+    ["--base", "base"],
+    ["--head", "head"],
+    ["--initiative-id", "initiativeId"],
+    ["--assignment-id", "assignmentId"],
+    ["--delivery-class", "deliveryClass"],
+    ["--queue-attempt", "queueAttempt"],
+    ["--admission-proof-root", "admissionProofRoot"],
+    ["--release-family-marker", "releaseFamilyMarker"],
+    ["--expected-pr-head", "expectedPullRequestHead"],
+    ["--terminal-reason", "terminalReason"],
+    ["--evidence-root", "evidenceRoot"],
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const name = argv[index];
+    const key = names.get(name);
+    if (!key) throw new Error(`unknown argument: ${name}`);
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("--"))
+      throw new Error(`${name} requires a value`);
+    if (Object.hasOwn(options, key))
+      throw new Error(`${name} was provided more than once`);
+    options[key] = value;
+    index += 1;
+  }
+  return options;
+}
+
+function markerText(path) {
+  return path === "-"
+    ? fs.readFileSync(0, "utf8")
+    : fs.readFileSync(path, "utf8");
+}
+
+function repairReceipt(error) {
+  return {
+    schema: "project.cut.merge-queue-admission/v1",
+    ok: false,
+    decision: "repair-required",
+    retryable: false,
+    compositionChanged: false,
+    reasonCodes: [error.reasonCode],
+    error: error.message,
+  };
+}
+
+export function main(argv = process.argv.slice(2)) {
+  try {
+    const options = parseArguments(argv);
+    if (options.releaseFamilyMarker) {
+      console.log(
+        JSON.stringify(
+          releaseFamilyQueueLease(
+            markerText(options.releaseFamilyMarker),
+            options,
+          ),
+        ),
+      );
+      return 0;
+    }
+    if (!options.base || !options.head)
+      throw new Error("--base and --head are required");
+    console.log(
+      JSON.stringify(qualifyProjectCut({ cwd: process.cwd(), ...options })),
+    );
+    return 0;
+  } catch (error) {
+    if (error instanceof ProjectCutAdmissionError) {
+      console.log(JSON.stringify(repairReceipt(error)));
+      return 1;
+    }
+    console.error(`project-cut admission error: ${error.message}`);
+    return 2;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) process.exitCode = main();