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

package/scripts/generate-v4-universal-workflow-facades.mjs

@@ -0,0 +1,415 @@
+#!/usr/bin/env node
+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 contractPath = path.join(
+  root,
+  "architecture/v4-universal-workflow-bootstrap.json",
+);
+const contract = JSON.parse(fs.readFileSync(contractPath, "utf8"));
+const laneBudgetPath = path.join(
+  root,
+  "architecture/ci-lane-change-budget.json",
+);
+const recoveryTemplatePath = path.join(
+  root,
+  contract.bootstrap.consumerRecoveryTemplate,
+);
+const recoveryWorkflowPath = path.join(
+  root,
+  contract.bootstrap.consumerRecoveryWorkflow,
+);
+const universalInput = `      universal-request-json:
+        description: "Versioned exact-candidate request envelope; empty preserves the compatibility path"
+        default: ""
+        required: false
+        type: string
+`;
+const bootstrapJob = `  universal-bootstrap:
+    name: Universal exact-candidate execution
+    if: \${{ inputs.universal-request-json != '' }}
+    uses: ./.github/workflows/bootstrap.yml
+    with:
+      request-json: \${{ inputs.universal-request-json }}
+
+`;
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function activeFacadePaths() {
+  const retired = new Set(contract.retiredWorkflowSurfaces || []);
+  return contract.inventoryWorkflows.filter(
+    (relative) =>
+      relative !== contract.bootstrap.publicWorkflow &&
+      relative !== contract.bootstrap.consumerRecoveryWorkflow &&
+      !retired.has(relative),
+  );
+}
+
+function sourceRevision() {
+  const revision = contract.migration.facadeSourceRevision;
+  if (!/^[0-9a-f]{40}$/u.test(revision || ""))
+    fail("migration.facadeSourceRevision must be an exact commit");
+  return revision;
+}
+
+function materializeSourceRevision() {
+  const revision = sourceRevision();
+  try {
+    execFileSync("git", ["cat-file", "-e", `${revision}^{commit}`], {
+      cwd: root,
+      stdio: "ignore",
+    });
+    return;
+  } catch {}
+  try {
+    execFileSync(
+      "git",
+      ["fetch", "--no-tags", "--depth=1", "origin", revision],
+      { cwd: root, stdio: "pipe" },
+    );
+    execFileSync("git", ["cat-file", "-e", `${revision}^{commit}`], {
+      cwd: root,
+      stdio: "ignore",
+    });
+  } catch (error) {
+    const detail = String(error?.stderr || error?.message || error).trim();
+    fail(
+      `facade source revision ${revision} is unavailable and could not be hydrated from origin${detail ? `: ${detail}` : ""}`,
+    );
+  }
+}
+
+function frozenFacadeSource(relative) {
+  return execFileSync("git", ["show", `${sourceRevision()}:${relative}`], {
+    cwd: root,
+    encoding: "utf8",
+  });
+}
+
+function isChannelGeneratedFacade(relative) {
+  return (contract.migration.channelGeneratedFacades || []).includes(relative);
+}
+
+function addUniversalInput(source, relative) {
+  if (source.includes("      universal-request-json:\n")) return source;
+  const workflowCall = source.match(/^(\s*)workflow_call:\s*$/mu);
+  if (!workflowCall) fail(`${relative} has no workflow_call mapping`);
+  const callIndent = workflowCall[1];
+  const inputHeader = `${callIndent}  inputs:\n`;
+  const callEnd = workflowCall.index + workflowCall[0].length;
+  if (source.slice(callEnd + 1).startsWith(inputHeader)) {
+    const insertion = callEnd + 1 + inputHeader.length;
+    return `${source.slice(0, insertion)}${universalInput}${source.slice(insertion)}`;
+  }
+  return `${source.slice(0, callEnd + 1)}\n${inputHeader}${universalInput}${source.slice(callEnd + 1)}`;
+}
+
+function conditionExpression(source, relative, jobId) {
+  const child = source.match(/^(\s+)[A-Za-z0-9_-]+:/mu);
+  const indent = child?.[1] || "    ";
+  const match = source.match(new RegExp(`^${indent}if:\\s*(.*)$`, "mu"));
+  if (!match)
+    return `${indent}if: \${{ inputs.universal-request-json == '' }}\n`;
+  const suffix = match[1].trim();
+  if (suffix === ">-" || suffix === "|") {
+    const start = match.index + match[0].length + 1;
+    const tail = source.slice(start);
+    const endMatch = tail.match(/^    [A-Za-z0-9_-]+:/mu);
+    const end = endMatch ? start + endMatch.index : source.length;
+    const raw = source.slice(start, end).trim();
+    const inner = raw
+      .replace(/^\$\{\{\s*/u, "")
+      .replace(/\s*\}\}$/u, "")
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .join("\n          ");
+    if (!inner) fail(`${relative}#${jobId} has an empty multiline if`);
+    return {
+      start: match.index,
+      end,
+      value: `${indent}if: >-\n${indent}  \${{\n${indent}    inputs.universal-request-json == '' &&\n${indent}    (\n${indent}      ${inner}\n${indent}    )\n${indent}  }}\n`,
+    };
+  }
+  const inner = suffix.startsWith("${{")
+    ? suffix.replace(/^\$\{\{\s*/u, "").replace(/\s*\}\}$/u, "")
+    : suffix;
+  return {
+    start: match.index,
+    end:
+      match.index +
+      match[0].length +
+      (source[match.index + match[0].length] === "\n" ? 1 : 0),
+    value: `${indent}if: \${{ inputs.universal-request-json == '' && (${inner}) }}\n`,
+  };
+}
+
+function guardCompatibilityJobs(source, relative) {
+  const jobs = source.match(/^jobs:\s*$/mu);
+  if (!jobs) fail(`${relative} has no jobs mapping`);
+  const bodyStart = jobs.index + jobs[0].length + 1;
+  const body = source.slice(bodyStart);
+  const headers = [...body.matchAll(/^  ([A-Za-z0-9_-]+):\s*$/gmu)];
+  if (headers.length === 0) fail(`${relative} has no jobs`);
+  let rewritten = body;
+  for (let index = headers.length - 1; index >= 0; index -= 1) {
+    const header = headers[index];
+    if (header[1] === "universal-bootstrap") continue;
+    const start = header.index + header[0].length + 1;
+    const end = headers[index + 1]?.index ?? body.length;
+    const job = body.slice(start, end);
+    if (job.includes("inputs.universal-request-json == ''")) continue;
+    const condition = conditionExpression(job, relative, header[1]);
+    if (typeof condition === "string") {
+      rewritten = `${rewritten.slice(0, start)}${condition}${rewritten.slice(start)}`;
+    } else {
+      rewritten = `${rewritten.slice(0, start + condition.start)}${condition.value}${rewritten.slice(start + condition.end)}`;
+    }
+  }
+  const withGuards = `${source.slice(0, bodyStart)}${rewritten}`;
+  return withGuards.includes("  universal-bootstrap:\n")
+    ? withGuards
+    : `${withGuards.slice(0, bodyStart)}${bootstrapJob}${withGuards.slice(bodyStart)}`;
+}
+
+export function migrateV4UniversalWorkflowFacade(source, relative) {
+  return guardCompatibilityJobs(addUniversalInput(source, relative), relative);
+}
+
+function verify(source, relative) {
+  for (const snippet of [
+    "      universal-request-json:\n",
+    "  universal-bootstrap:\n",
+    "uses: ./.github/workflows/bootstrap.yml",
+  ]) {
+    if (!source.includes(snippet))
+      fail(`${relative} is missing ${snippet.trim()}`);
+  }
+  const jobs = source.slice(source.search(/^jobs:\s*$/mu));
+  const headers = [...jobs.matchAll(/^  ([A-Za-z0-9_-]+):\s*$/gmu)];
+  for (let index = 0; index < headers.length; index += 1) {
+    const header = headers[index];
+    if (header[1] === "universal-bootstrap") continue;
+    const end = headers[index + 1]?.index ?? jobs.length;
+    const block = jobs.slice(header.index, end);
+    if (!block.includes("inputs.universal-request-json == ''"))
+      fail(`${relative}#${header[1]} can overlap universal execution`);
+  }
+  if (!isChannelGeneratedFacade(relative)) {
+    const expected = migrateV4UniversalWorkflowFacade(
+      frozenFacadeSource(relative),
+      relative,
+    );
+    if (source !== expected)
+      fail(
+        `${relative} differs from the exact generated facade rooted at ${sourceRevision()}`,
+      );
+  }
+}
+
+function laneBudget({ laneId, authorityClass, triggerClass, minutes, metric }) {
+  return {
+    laneId,
+    authorityClass,
+    triggerClass,
+    concurrencyPolicy: { mode: "none", cancelInProgress: false },
+    expectedRunnerMinutes: minutes,
+    cancellationBehavior: "finish-started",
+    sloImpact: {
+      mergeCritical: false,
+      metric,
+      expectedContributionSeconds: 0,
+      rationale:
+        "The opt-in universal path preserves the default compatibility lane and executes only an exact admitted runtime.",
+    },
+  };
+}
+
+function updateLaneBudgets() {
+  const policy = JSON.parse(fs.readFileSync(laneBudgetPath, "utf8"));
+  const mixed = new Set([
+    ".github/workflows/release-governance-reconcile.yml",
+    ".github/workflows/v4-adopter-delivery.yml",
+  ]);
+  const facadeLanes = activeFacadePaths().map(
+    (relative) => `${relative}#universal-bootstrap`,
+  );
+  policy.declarationFamilies = [
+    {
+      ...laneBudget({
+        laneId: "",
+        authorityClass: "governed-delegation",
+        triggerClass: "reusable",
+        minutes: 60,
+        metric: "opt-in exact-candidate execution latency",
+      }),
+      laneIds: facadeLanes.filter(
+        (laneId) => !mixed.has(laneId.split("#", 1)[0]),
+      ),
+    },
+    {
+      ...laneBudget({
+        laneId: "",
+        authorityClass: "governed-delegation",
+        triggerClass: "mixed",
+        minutes: 60,
+        metric: "mixed-trigger exact-candidate execution latency",
+      }),
+      laneIds: facadeLanes.filter((laneId) =>
+        mixed.has(laneId.split("#", 1)[0]),
+      ),
+    },
+  ].map(({ laneId: _laneId, ...family }) => family);
+  const universalLaneIds = new Set([
+    ".github/workflows/bootstrap.yml#admit",
+    ".github/workflows/bootstrap.yml#execute",
+    ".github/workflows/bootstrap.yml#settle",
+    ".github/workflows/universal-bootstrap-recovery.yml#recovery-admit",
+    ".github/workflows/universal-bootstrap-recovery.yml#recovery-execute",
+    ".github/workflows/universal-bootstrap-recovery.yml#recovery-settle",
+    ".github/workflows/universal-bootstrap-dogfood.yml#public-bootstrap",
+    ".github/workflows/universal-bootstrap-dogfood.yml#prepare",
+    ".github/workflows/universal-bootstrap-dogfood.yml#primary-conformance",
+    ".github/workflows/universal-bootstrap-dogfood.yml#recovery-conformance",
+    ".github/workflows/universal-bootstrap-dogfood.yml#primary-alpha",
+    ".github/workflows/universal-bootstrap-dogfood.yml#recovery-alpha",
+    ".github/workflows/universal-bootstrap-dogfood.yml#primary-stable",
+    ".github/workflows/universal-bootstrap-dogfood.yml#recovery-stable",
+    ".github/workflows/universal-bootstrap-dogfood.yml#reconcile",
+  ]);
+  policy.declarations = policy.declarations.filter(
+    ({ laneId }) => !universalLaneIds.has(laneId),
+  );
+  policy.declarations.push(
+    laneBudget({
+      laneId: ".github/workflows/bootstrap.yml#admit",
+      authorityClass: "evidence",
+      triggerClass: "reusable",
+      minutes: 10,
+      metric: "exact-candidate admission latency",
+    }),
+    laneBudget({
+      laneId: ".github/workflows/bootstrap.yml#execute",
+      authorityClass: "governed-delegation",
+      triggerClass: "reusable",
+      minutes: 60,
+      metric: "exact-candidate execution latency",
+    }),
+    laneBudget({
+      laneId: ".github/workflows/bootstrap.yml#settle",
+      authorityClass: "evidence",
+      triggerClass: "reusable",
+      minutes: 10,
+      metric: "universal terminal settlement latency",
+    }),
+    laneBudget({
+      laneId:
+        ".github/workflows/universal-bootstrap-recovery.yml#recovery-admit",
+      authorityClass: "evidence",
+      triggerClass: "reusable",
+      minutes: 10,
+      metric: "consumer-owned exact-candidate admission latency",
+    }),
+    laneBudget({
+      laneId:
+        ".github/workflows/universal-bootstrap-recovery.yml#recovery-execute",
+      authorityClass: "governed-delegation",
+      triggerClass: "reusable",
+      minutes: 60,
+      metric: "consumer-owned exact-candidate execution latency",
+    }),
+    laneBudget({
+      laneId:
+        ".github/workflows/universal-bootstrap-recovery.yml#recovery-settle",
+      authorityClass: "evidence",
+      triggerClass: "reusable",
+      minutes: 10,
+      metric: "consumer-owned terminal settlement latency",
+    }),
+    laneBudget({
+      laneId: ".github/workflows/universal-bootstrap-dogfood.yml#prepare",
+      authorityClass: "evidence",
+      triggerClass: "mixed",
+      minutes: 10,
+      metric: "Train-first self-dogfood admission latency",
+    }),
+    ...[
+      "primary-conformance",
+      "recovery-conformance",
+      "primary-alpha",
+      "recovery-alpha",
+      "primary-stable",
+      "recovery-stable",
+    ].map((job) =>
+      laneBudget({
+        laneId: `.github/workflows/universal-bootstrap-dogfood.yml#${job}`,
+        authorityClass: "governed-delegation",
+        triggerClass: "mixed",
+        minutes: 60,
+        metric: "Train-first exact-candidate self-dogfood latency",
+      }),
+    ),
+    laneBudget({
+      laneId: ".github/workflows/universal-bootstrap-dogfood.yml#reconcile",
+      authorityClass: "evidence",
+      triggerClass: "mixed",
+      minutes: 10,
+      metric: "primary and recovery equivalence latency",
+    }),
+  );
+  fs.writeFileSync(laneBudgetPath, `${JSON.stringify(policy, null, 2)}\n`);
+}
+
+function main() {
+  const check = process.argv.includes("--check");
+  const fresh = process.argv.includes("--fresh");
+  materializeSourceRevision();
+  if (check) {
+    if (
+      fs.readFileSync(recoveryWorkflowPath, "utf8") !==
+      fs.readFileSync(recoveryTemplatePath, "utf8")
+    )
+      fail(
+        "consumer recovery workflow differs from its pre-positioned template",
+      );
+  } else {
+    fs.writeFileSync(
+      recoveryWorkflowPath,
+      fs.readFileSync(recoveryTemplatePath, "utf8"),
+    );
+  }
+  for (const relative of activeFacadePaths()) {
+    const target = path.join(root, relative);
+    const source = fresh
+      ? frozenFacadeSource(relative)
+      : fs.readFileSync(target, "utf8");
+    if (check) verify(source, relative);
+    else
+      fs.writeFileSync(
+        target,
+        migrateV4UniversalWorkflowFacade(source, relative),
+      );
+  }
+  if (!check) {
+    contract.bootstrapGovernedWorkflows = [
+      contract.bootstrap.publicWorkflow,
+      ...activeFacadePaths(),
+    ].sort();
+    contract.migration.compatibilityFacades = "generated-dual-path";
+    fs.writeFileSync(contractPath, `${JSON.stringify(contract, null, 2)}\n`);
+    updateLaneBudgets();
+    process.stdout.write(
+      `${JSON.stringify({ migrated: activeFacadePaths().length })}\n`,
+    );
+  }
+}
+
+const isMain =
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) main();

package/scripts/maintainability-public-surface.mjs

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import {
+  isGeneratedFacadePublicTransition,
+  loadUniversalFacadeMigration,
+} from "./universal-facade-maintainability.mjs";
+
+function readJson(root, file) {
+  return JSON.parse(fs.readFileSync(path.join(root, file), "utf8"));
+}
+
+function readJsonAtRevision(root, revision, file) {
+  return JSON.parse(
+    execFileSync("git", ["show", `${revision}:${file}`], {
+      cwd: root,
+      encoding: "utf8",
+    }),
+  );
+}
+
+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,
+  migration = loadUniversalFacadeMigration(root),
+}) {
+  const issues = [];
+  const capabilityGroups = new Set(
+    readJson(root, "dist/site/capability-registry.json").groups.map(
+      (entry) => entry.id,
+    ),
+  );
+  const definitions = [
+    ["dist/site/cli-registry.json", "commands", "cli", "id"],
+    ["dist/site/node-api-registry.json", "exports", "node", "export"],
+    ["dist/site/workflow-registry.json", "workflows", "workflow", "id"],
+    ["dist/site/workflow-registry.json", "actions", "action", "id"],
+  ];
+  for (const [file, collection, kind, key] of definitions) {
+    const current = readJson(root, file)[collection] || [];
+    const baseline = readJsonAtRevision(root, revision, file)[collection] || [];
+    const previousByKey = new Map(baseline.map((entry) => [entry[key], entry]));
+    for (const entry of current) {
+      const label = `${kind}:${entry[key]}`;
+      for (const field of policy.publicSurfacePolicy.requiredLifecycleFields) {
+        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 = previousByKey.get(entry[key]);
+      const currentContract = publicSurfaceContract(entry, kind);
+      if (
+        previous &&
+        JSON.stringify(currentContract) !==
+          JSON.stringify(publicSurfaceContract(previous, kind))
+      ) {
+        const approval = policy.approvedPublicSurfaceTransitions?.[label];
+        const approvedContract =
+          approval?.fromRevision === revision &&
+          String(approval?.rationale || "").trim()
+            ? approval.contract
+            : null;
+        const generated = isGeneratedFacadePublicTransition({
+          entry,
+          kind,
+          migration,
+          baseContract:
+            approvedContract || publicSurfaceContract(previous, kind),
+          currentContract,
+        });
+        if (
+          !generated &&
+          (!approvedContract ||
+            JSON.stringify(approvedContract) !==
+              JSON.stringify(currentContract))
+        )
+          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;
+}
+
+export { evaluatePublicSurface, publicSurfaceContract };

package/scripts/universal-facade-maintainability.mjs

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+function loadUniversalFacadeMigration(root) {
+  const contract = JSON.parse(
+    fs.readFileSync(
+      path.join(root, "architecture/v4-universal-workflow-bootstrap.json"),
+      "utf8",
+    ),
+  );
+  const retired = new Set(contract.retiredWorkflowSurfaces || []);
+  const paths = (contract.bootstrapGovernedWorkflows || []).filter(
+    (entry) =>
+      entry !== contract.bootstrap?.publicWorkflow && !retired.has(entry),
+  );
+  const sourceRevision = contract.migration?.facadeSourceRevision || "";
+  if (!/^[0-9a-f]{40}$/u.test(sourceRevision)) {
+    throw new Error(
+      "universal facade migration requires an exact facadeSourceRevision",
+    );
+  }
+  return { paths: new Set(paths), sourceRevision };
+}
+
+function verifyUniversalFacadeMigration(root) {
+  execFileSync(
+    process.execPath,
+    ["scripts/generate-v4-universal-workflow-facades.mjs", "--check"],
+    { cwd: root, stdio: "pipe" },
+  );
+}
+
+function governUniversalFacadeWorkflowMetrics({
+  root,
+  current,
+  workflowMetricsAtRevision,
+}) {
+  const migration = loadUniversalFacadeMigration(root);
+  verifyUniversalFacadeMigration(root);
+  const frozen = workflowMetricsAtRevision(root, migration.sourceRevision);
+  const governed = { ...current, workflows: { ...current.workflows } };
+  for (const file of migration.paths) {
+    if (!frozen[file])
+      throw new Error(`frozen universal facade source is missing ${file}`);
+    governed.workflows[file] = frozen[file];
+  }
+  return { governed, migration };
+}
+
+function isGeneratedFacadePublicTransition({
+  entry,
+  kind,
+  migration,
+  baseContract,
+  currentContract,
+}) {
+  if (kind !== "workflow" || !migration?.paths.has(entry.path) || !baseContract)
+    return false;
+  const { inputs: currentInputs, ...currentRest } = currentContract;
+  const { inputs: previousInputs, ...previousRest } = baseContract;
+  if (JSON.stringify(currentRest) !== JSON.stringify(previousRest))
+    return false;
+  const added = currentInputs.filter(
+    (input) => !previousInputs.includes(input),
+  );
+  const removed = previousInputs.filter(
+    (input) => !currentInputs.includes(input),
+  );
+  return (
+    removed.length === 0 &&
+    added.length === 1 &&
+    added[0] === "universal-request-json"
+  );
+}
+
+export {
+  governUniversalFacadeWorkflowMetrics,
+  isGeneratedFacadePublicTransition,
+  loadUniversalFacadeMigration,
+  verifyUniversalFacadeMigration,
+};