@kungfu-tech/buildchain 3.0.1-alpha.2 → 3.0.1-alpha.4

package/packages/core/issue-reporting.js

@@ -214,9 +214,6 @@ export function buildWorkflowFrictionIssueReport(options = {}) {
     repository,
     workflow,
     channel,
-    releaseIntent,
-    sourceRef,
-    sourceSha,
     frictionClass,
   });
   const marker = workflowFrictionMarker(fingerprint);
@@ -265,6 +262,10 @@ export function buildWorkflowFrictionIssueReport(options = {}) {
         `- Workflow: ${workflow || "(unknown)"}`,
         `- Run: ${runUrl || runId || "(unknown)"}`,
         `- Attempt: ${runAttempt || "(unknown)"}`,
+        `- Channel: ${channel || "(unknown)"}`,
+        `- Release intent: ${releaseIntent || "(unknown)"}`,
+        `- Source ref: ${sourceRef || "(unknown)"}`,
+        `- Source SHA: ${sourceSha || "(unknown)"}`,
         `- Friction class: ${frictionClass}`,
         `- Fingerprint: ${fingerprint}`,
         options.summary ? `\n${options.summary}` : "",
@@ -275,6 +276,10 @@ export function buildWorkflowFrictionIssueReport(options = {}) {
   return {
     contract: BUILDCHAIN_WORKFLOW_FRICTION_ISSUE_CONTRACT,
     targetRepository: target.fullName,
+    repository,
+    workflow,
+    channel,
+    frictionClass,
     fingerprint,
     marker,
     title,

package/packages/core/logging.js

@@ -5,6 +5,13 @@ import path from "node:path";
 
 export const BUILDCHAIN_LOG_EVENT_CONTRACT = "kungfu-buildchain-log-event";
 export const BUILDCHAIN_LOG_SUMMARY_CONTRACT = "kungfu-buildchain-log-summary";
+export const BUILDCHAIN_CONTROL_PLANE_SUMMARY_CONTRACT =
+  "kungfu-buildchain-control-plane-summary";
+
+const CONTROL_PLANE_EVENT_NAMES = {
+  "workflow-friction": "control-plane.workflow-friction.outcome",
+  "release-intent": "control-plane.release-intent.outcome",
+};
 
 const SECRET_KEY_PATTERN =
   /(authorization|cookie|credential|password|passwd|private[_-]?key|secret|token|api[_-]?key)/i;
@@ -90,6 +97,98 @@ function groupSummary(events, field) {
   );
 }
 
+function countOutcomes(events) {
+  const counts = {};
+  for (const event of events) {
+    const outcome = String(event.attributes?.outcome || "unknown");
+    counts[outcome] = (counts[outcome] || 0) + 1;
+  }
+  return Object.fromEntries(
+    Object.entries(counts).sort(([left], [right]) => left.localeCompare(right)),
+  );
+}
+
+function ratio(numerator, denominator) {
+  return denominator > 0 ? Number((numerator / denominator).toFixed(4)) : null;
+}
+
+export function summarizeBuildchainControlPlaneEvents(input = {}) {
+  const events = Array.isArray(input)
+    ? input
+    : typeof input === "string"
+      ? readBuildchainLogEvents(input)
+      : readBuildchainLogEvents(input.path);
+  const workflowFrictionEvents = events.filter(
+    (event) => event.event === CONTROL_PLANE_EVENT_NAMES["workflow-friction"],
+  );
+  const releaseIntentEvents = events.filter(
+    (event) => event.event === CONTROL_PLANE_EVENT_NAMES["release-intent"],
+  );
+  const workflowFriction = countOutcomes(workflowFrictionEvents);
+  const releaseIntent = countOutcomes(releaseIntentEvents);
+  const incidentDecisions = Number(workflowFriction.created || 0) + Number(workflowFriction.reused || 0);
+  const releaseIntentDecisions =
+    Number(releaseIntent.created || 0) +
+    Number(releaseIntent.reused || 0) +
+    Number(releaseIntent.suppressed || 0);
+  const suppressionReasons = {};
+  for (const event of releaseIntentEvents) {
+    if (event.attributes?.outcome !== "suppressed") continue;
+    const reason = String(event.attributes?.reason || "unknown");
+    suppressionReasons[reason] = (suppressionReasons[reason] || 0) + 1;
+  }
+  return {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_CONTROL_PLANE_SUMMARY_CONTRACT,
+    eventCount: workflowFrictionEvents.length + releaseIntentEvents.length,
+    workflowFriction: {
+      eventCount: workflowFrictionEvents.length,
+      outcomes: workflowFriction,
+      incidentReuseRate: ratio(Number(workflowFriction.reused || 0), incidentDecisions),
+    },
+    releaseIntent: {
+      eventCount: releaseIntentEvents.length,
+      outcomes: releaseIntent,
+      suppressionRate: ratio(Number(releaseIntent.suppressed || 0), releaseIntentDecisions),
+      suppressionReasons: Object.fromEntries(
+        Object.entries(suppressionReasons).sort(([left], [right]) => left.localeCompare(right)),
+      ),
+    },
+  };
+}
+
+export function recordBuildchainControlPlaneOutcome({
+  domain,
+  action = "",
+  outcome = "",
+  reason = "",
+  attributes = {},
+} = {}, options = {}) {
+  if (!Object.hasOwn(CONTROL_PLANE_EVENT_NAMES, domain)) {
+    throw new Error(`unsupported Buildchain control-plane domain: ${domain || "<empty>"}`);
+  }
+  const logger = options.logger || createBuildchainLogger({
+    cwd: options.cwd,
+    path: options.path,
+    console: options.console ?? false,
+    source: "buildchain",
+    component: "control-plane",
+    phase: domain,
+  });
+  const normalizedOutcome = outcome || action || "unknown";
+  const details = {
+    attributes: {
+      ...attributes,
+      action,
+      outcome: normalizedOutcome,
+      reason,
+    },
+  };
+  return ["failed", "error"].includes(normalizedOutcome)
+    ? logger.warn(CONTROL_PLANE_EVENT_NAMES[domain], details)
+    : logger.info(CONTROL_PLANE_EVENT_NAMES[domain], details);
+}
+
 export function summarizeBuildchainLogEvents(input = {}) {
   const events = Array.isArray(input)
     ? input
@@ -109,6 +208,8 @@ export function summarizeBuildchainLogEvents(input = {}) {
     sources: groupSummary(events, "source"),
     phases: groupSummary(events, "phase"),
     components: groupSummary(events, "component"),
+    events: groupSummary(events, "event"),
+    controlPlane: summarizeBuildchainControlPlaneEvents(events),
   };
 }
 

package/scripts/auditable-demo.mjs

@@ -316,7 +316,7 @@ function runAdapter(values) {
     const result = spawnSync(
       adapter,
       ["--artifact-root", artifactRoot, "--output", output, "--source-coordinate", sourceCoordinate],
-      { cwd: sourceRoot, env, encoding: "utf8", maxBuffer: 4 * 1024 * 1024 },
+      { cwd: sourceRoot, env: environment, encoding: "utf8", maxBuffer: 4 * 1024 * 1024 },
     );
     fs.writeFileSync(path.join(diagnostics, "adapter.stdout.log"), result.stdout || "");
     fs.writeFileSync(path.join(diagnostics, "adapter.stderr.log"), result.stderr || result.error?.message || "");

package/scripts/check-inventory.mjs

@@ -19,6 +19,28 @@ import {
 const root = process.cwd();
 const sharedActionTsupConfig = fs.readFileSync(path.join(root, "scripts/tsup-action.config.mjs"), "utf8");
 const commonJsSourcePattern = /\b(require\s*\(|module\.exports|exports\.|require\.main|createRequire)\b/;
+
+function assertSelfReleaseImpactContract(impact, { expectedVersion = "" } = {}) {
+  if (!impact || typeof impact !== "object" || Array.isArray(impact)) {
+    throw new Error("Buildchain self release impact must be a JSON object");
+  }
+  const version = String(impact.release?.version || "").trim();
+  const versionMatch = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/);
+  if (!versionMatch) throw new Error("Buildchain self release impact release.version must be a semantic version");
+  if (expectedVersion && version !== expectedVersion) {
+    throw new Error("Buildchain self release impact version must match package.json version");
+  }
+  const expectedLine = `v${versionMatch[1]}.${versionMatch[2]}`;
+  const line = String(impact.release?.line || "").trim();
+  if (line !== expectedLine) {
+    throw new Error(`Buildchain self release impact line must be ${expectedLine} for release.version ${version}`);
+  }
+  const summary = String(impact.summary || "").trim();
+  if (!summary.startsWith(`Buildchain ${line} `)) {
+    throw new Error(`Buildchain self release impact summary must describe the current ${line} line`);
+  }
+}
+
 const requiredPaths = [
   "AGENTS.md",
   "CONTRIBUTING.md",
@@ -707,7 +729,7 @@ for (const requiredSnippet of [
 for (const requiredSnippet of [
   "Capability Coverage",
   "KFD-1 / KFD-2 / KFD-3",
-  "floating `@v2`",
+  "floating `@v3`",
   "npm publish transactions",
   "Git/source/version/module/product build facts",
   "GitHub Release",
@@ -778,7 +800,7 @@ for (const requiredSnippet of [
 for (const [docName, docSource] of Object.entries({ "docs/cli.md": cliDoc, "docs/install.md": installDoc })) {
   for (const requiredSnippet of [
     "minimumReleaseAgeExclude",
-    "@kungfu-tech/buildchain@2.2.5",
+    "@kungfu-tech/buildchain@3.0.0",
     "package/version-specific",
   ]) {
     if (!docSource.includes(requiredSnippet)) {
@@ -844,19 +866,16 @@ const selfHostedRunnerSmokeWorkflow = fs.readFileSync(path.join(root, ".github/w
 const npmDryRunScript = fs.readFileSync(path.join(root, "scripts/npm-publish-dry-run.mjs"), "utf8");
 const npmPublishTransactionScript = fs.readFileSync(path.join(root, "scripts/npm-publish-transaction.mjs"), "utf8");
 const rootPackageJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
-const selfReleaseImpact = JSON.parse(fs.readFileSync(path.join(root, ".buildchain/release-impact.json"), "utf8"));
-const selfReleaseLineMatch = String(rootPackageJson.version || "").match(/^(\d+)\.(\d+)\./);
-const expectedSelfReleaseLine = selfReleaseLineMatch ? `v${selfReleaseLineMatch[1]}.${selfReleaseLineMatch[2]}` : "";
-if (selfReleaseImpact.release?.version !== rootPackageJson.version) {
-  throw new Error("Buildchain self release impact version must match package.json version");
-}
-if (!expectedSelfReleaseLine || selfReleaseImpact.release?.line !== expectedSelfReleaseLine) {
-  throw new Error("Buildchain self release impact line must match package.json major/minor line");
-}
+const selfReleaseImpactPath = path.resolve(
+  root,
+  process.env.BUILDCHAIN_SELF_RELEASE_IMPACT_PATH || ".buildchain/release-impact.json",
+);
+const selfReleaseImpact = JSON.parse(fs.readFileSync(selfReleaseImpactPath, "utf8"));
+assertSelfReleaseImpactContract(selfReleaseImpact, { expectedVersion: rootPackageJson.version });
 if (!["patch", "minor", "major"].includes(selfReleaseImpact.classification)) {
   throw new Error("Buildchain self release impact classification must be patch, minor, or major");
 }
-if (!String(selfReleaseImpact.summary || "").trim() || !Array.isArray(selfReleaseImpact.surfaceImpacts) || selfReleaseImpact.surfaceImpacts.length === 0) {
+if (!Array.isArray(selfReleaseImpact.surfaceImpacts) || selfReleaseImpact.surfaceImpacts.length === 0) {
   throw new Error("Buildchain self release impact requires a summary and surfaceImpacts[]");
 }
 for (const requiredSnippet of [
@@ -969,7 +988,7 @@ for (const retiredWorkflow of [
   const retiredSource = fs.readFileSync(path.join(workflowDir, retiredWorkflow), "utf8");
   for (const requiredSnippet of [
     "release path is retired",
-    "release-candidate-promote.yml@v2",
+    "release-candidate-promote.yml@v3",
     "publish-gate source-lock enforcement",
   ]) {
     if (!retiredSource.includes(requiredSnippet)) {
@@ -1115,12 +1134,12 @@ if (inventory.release !== "buildchain-v2") {
   throw new Error("inventory release must be buildchain-v2");
 }
 
-if (inventory.stableRefs?.actions !== "kungfu-systems/buildchain/actions/<name>@v2") {
-  throw new Error("inventory stable action ref must point at @v2");
+if (inventory.stableRefs?.actions !== "kungfu-systems/buildchain/actions/<name>@v3") {
+  throw new Error("inventory stable action ref must point at @v3");
 }
 
-if (inventory.stableRefs?.workflows !== "kungfu-systems/buildchain/.github/workflows/<workflow>.yml@v2") {
-  throw new Error("inventory stable workflow ref must point at @v2");
+if (inventory.stableRefs?.workflows !== "kungfu-systems/buildchain/.github/workflows/<workflow>.yml@v3") {
+  throw new Error("inventory stable workflow ref must point at @v3");
 }
 if (inventory.safety?.releasePassport?.line !== "v2.2") {
   throw new Error("release passport inventory must be registered as a v2.2 surface");

package/scripts/init-repo.mjs

@@ -5,7 +5,7 @@ import { pathToFileURL } from "node:url";
 import { BUILDCHAIN_CONFIG_PATH } from "../packages/core/buildchain-layout.js";
 import { detectPackageManager, assertPackageManager } from "../packages/core/package-manager.js";
 
-const BUILDCHAIN_WORKFLOW_REF = "kungfu-systems/buildchain/.github/workflows/.build.yml@v2";
+const BUILDCHAIN_WORKFLOW_REF = "kungfu-systems/buildchain/.github/workflows/.build.yml@v3";
 const DEFAULT_PUBLICATION_LATEX_IMAGE = "ghcr.io/kungfu-systems/build-images/latex-pdf-builder";
 const DEFAULT_PUBLICATION_LATEX_DIGEST = "sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8";
 const DEFAULT_PUBLICATION_LATEX_COMMAND = "latexmk -pdf -outdir=_build paper/main.tex";
@@ -349,7 +349,7 @@ permissions:
 
 jobs:
   publication:
-    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v3
     with:
       buildchain-ref: \${{ inputs.buildchain-ref || '' }}
       toolchain-type: config

package/scripts/web-surface-production-release-pr.mjs

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import path from "node:path";
+import {
+  defaultBuildchainLogPath,
+  recordBuildchainControlPlaneOutcome,
+} from "../packages/core/logging.js";
 
 function requiredString(value, name) {
   const normalized = String(value || "").trim();
@@ -70,6 +74,34 @@ function runUrl({ serverUrl = "", repository = "", runId = "" } = {}) {
   return `${serverUrl.replace(/\/$/, "")}/${repository}/actions/runs/${runId}`;
 }
 
+export function recordProductionReleasePrOutcome(result, env = process.env) {
+  const outcome = result.action === "created"
+    ? "created"
+    : result.action === "updated"
+      ? "reused"
+      : result.action === "suppressed-merged-release-pr"
+        ? "suppressed"
+        : ["permission-denied", "app-token-unavailable", "failed"].includes(result.action)
+          ? "failed"
+          : "skipped";
+  return recordBuildchainControlPlaneOutcome({
+    domain: "release-intent",
+    action: result.action,
+    outcome,
+    reason: result.suppressionReason || result.status,
+    attributes: {
+      repository: result.repository,
+      channel: result.productionReleaseChannel,
+      pullNumber: result.pullNumber,
+      sourceSha: result.sourceSha,
+    },
+  }, {
+    path: optionalString(env.BUILDCHAIN_LOG_PATH) ||
+      (env.GITHUB_ACTIONS === "true" ? defaultBuildchainLogPath() : false),
+    console: false,
+  });
+}
+
 function urlsFromResult(result = {}) {
   const urls = result.urls && typeof result.urls === "object" ? result.urls : {};
   if (Object.keys(urls).length > 0) return urls;
@@ -374,6 +406,33 @@ async function createOrUpdateBranch({ apiUrl, token, owner, repo, branchName, so
   return createdCommit.sha;
 }
 
+function findMergedProductionReleasePr({
+  pullRequests = [],
+  repository,
+  productionReleaseLabel = "buildchain-release",
+  productionReleaseHeadPrefix = "release/",
+  base = "main",
+} = {}) {
+  const fullName = requiredString(repository, "repository");
+  const label = requiredString(productionReleaseLabel, "productionReleaseLabel");
+  const headPrefix = optionalString(productionReleaseHeadPrefix);
+  const candidates = (Array.isArray(pullRequests) ? pullRequests : []).filter((pull) => {
+    const labels = Array.isArray(pull?.labels) ? pull.labels.map((entry) => entry?.name || entry) : [];
+    const headRef = optionalString(pull?.head?.ref);
+    return Boolean(pull?.merged_at) &&
+      pull?.base?.ref === base &&
+      pull?.head?.repo?.full_name === fullName &&
+      labels.includes(label) &&
+      (!headPrefix || headRef.startsWith(headPrefix));
+  });
+  if (candidates.length > 1) {
+    throw new Error(
+      `multiple merged production release PRs matched the source commit: ${candidates.map((pull) => `#${pull.number}`).join(", ")}`,
+    );
+  }
+  return candidates[0];
+}
+
 export async function openProductionReleasePr({
   apiUrl = "https://api.github.com",
   token,
@@ -400,6 +459,43 @@ export async function openProductionReleasePr({
   });
   const { owner, repo, branchName, title, body, head } = handoff;
   const normalizedToken = requiredString(token, "token");
+  const associated = await githubJson({
+    apiUrl,
+    token: normalizedToken,
+    path: `/repos/${owner}/${repo}/commits/${encodeURIComponent(handoff.sourceSha)}/pulls?per_page=100`,
+  });
+  let mergedReleasePull = findMergedProductionReleasePr({
+    pullRequests: associated,
+    repository,
+    productionReleaseLabel,
+    productionReleaseHeadPrefix,
+    base: handoff.base,
+  });
+  if (!mergedReleasePull) {
+    const closedByDeterministicHead = await githubJson({
+      apiUrl,
+      token: normalizedToken,
+      path: `/repos/${owner}/${repo}/pulls?state=closed&base=${encodeURIComponent(handoff.base)}&head=${encodeURIComponent(head)}&per_page=100`,
+    });
+    mergedReleasePull = findMergedProductionReleasePr({
+      pullRequests: closedByDeterministicHead,
+      repository,
+      productionReleaseLabel,
+      productionReleaseHeadPrefix,
+      base: handoff.base,
+    });
+  }
+  if (mergedReleasePull) {
+    return {
+      action: "suppressed-merged-release-pr",
+      status: "suppressed-merged-release-pr",
+      ...handoff,
+      branchName,
+      pullNumber: mergedReleasePull.number,
+      pullUrl: mergedReleasePull.html_url || mergedReleasePull.url || "",
+      suppressionReason: "source-commit-already-has-qualifying-merged-release-pr",
+    };
+  }
   const existing = await githubJson({
     apiUrl,
     token: normalizedToken,
@@ -524,6 +620,7 @@ export async function webSurfaceProductionReleasePrCli(env = process.env) {
       if (failOnReleasePrError) {
         writeJsonFile(summaryPath, result);
         if (env.GITHUB_STEP_SUMMARY) fs.appendFileSync(env.GITHUB_STEP_SUMMARY, renderStepSummary(result));
+        recordProductionReleasePrOutcome(result, env);
         throw new Error(result.error.message);
       }
     } else {
@@ -562,12 +659,14 @@ export async function webSurfaceProductionReleasePrCli(env = process.env) {
         if (status !== "permission-denied" || failOnReleasePrError) {
           writeJsonFile(summaryPath, result);
           if (env.GITHUB_STEP_SUMMARY) fs.appendFileSync(env.GITHUB_STEP_SUMMARY, renderStepSummary(result));
+          recordProductionReleasePrOutcome(result, env);
           throw error;
         }
       }
     }
   }
 
+  recordProductionReleasePrOutcome(result, env);
   writeJsonFile(summaryPath, result);
   if (env.GITHUB_STEP_SUMMARY) {
     fs.appendFileSync(env.GITHUB_STEP_SUMMARY, renderStepSummary(result));

package/scripts/workflow-friction-report.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import path from "node:path";
+import { recordBuildchainControlPlaneOutcome } from "../packages/core/logging.js";
 import { pathToFileURL } from "node:url";
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
 
@@ -346,6 +347,15 @@ export async function workflowFrictionReportCli() {
     })}\n`);
     console.error(`::warning::${diagnosis.replace(/\r?\n/g, "%0A")}`);
   }
+  recordBuildchainControlPlaneOutcome({
+    domain: "workflow-friction",
+    action: "classified",
+    outcome: "classified",
+    attributes: {
+      frictionClass: result.frictionClass,
+      pullRequest: result.pullRequest,
+    },
+  });
   writeGitHubOutputs({
     "friction-class": result.frictionClass,
     summary: result.summary,