@kungfu-tech/buildchain 2.14.1 → 2.14.2-alpha.1

package/packages/core/release-line-bootstrap.js

@@ -158,6 +158,8 @@ export function planReleaseLineBootstrap({
   const alphaRef = `alpha/v${parsedMajor}/${line}`;
   const releaseRef = `release/v${parsedMajor}/${line}`;
   const loadedConfig = loadBuildchainConfig(cwd);
+  const declaredMergeQueue = loadedConfig?.config?.governance?.dev?.mergeQueue;
+  const mergeQueueMode = declaredMergeQueue?.mode || "inherit";
   const versionFiles = discoverVersionStateFiles(cwd, loadedConfig);
   const lifecycleVersionState =
     getLifecycleStage(loadedConfig, "version-state") ||
@@ -201,22 +203,33 @@ export function planReleaseLineBootstrap({
       enforceAdmins: true,
       protectedRefs: [devRef, alphaRef, releaseRef],
     },
+    governance: {
+      mergeQueue: {
+        declared: Boolean(declaredMergeQueue),
+        mode: mergeQueueMode,
+        source: mergeQueueMode === "inherit" ? "repository-default-branch" : "buildchain-config",
+        requiredWorkflows: declaredMergeQueue?.requiredWorkflows || [],
+        reconcileBeforeDefaultBranchSwitch: true,
+      },
+    },
     repositoryActions: [
       { action: "create-or-verify-source-ref", ref: source },
       { action: "commit-initial-version-state", ref: branch, version: resolvedInitialVersion },
       { action: "create-dev-branch", ref: devRef, from: branch },
       { action: "create-alpha-branch", ref: alphaRef, from: source },
       { action: "create-release-branch", ref: releaseRef, from: source },
-      ...(setDefault ? [{ action: "set-default-branch", ref: devRef }] : []),
       { action: "protect-branch", ref: devRef },
       { action: "protect-branch", ref: alphaRef },
       { action: "protect-branch", ref: releaseRef },
+      { action: "reconcile-dev-merge-queue", ref: devRef, mode: mergeQueueMode },
+      ...(setDefault ? [{ action: "set-default-branch", ref: devRef }] : []),
       ...(createAlphaPr ? [{ action: "open-alpha-pr", head: devRef, base: alphaRef }] : []),
     ],
     notes: [
       "This bootstrap creates the new minor line before the first alpha promotion.",
       "The source ref stays as the baseline for alpha/release until reviewed channel PRs move them.",
       "The dev branch receives only the initial version-state commit and becomes the active line when setDefault is true.",
+      "Merge queue governance is reconciled after branch protection and before the repository default branch moves.",
     ],
   };
 }

package/scripts/buildchain-patrol.mjs

@@ -91,6 +91,7 @@ export function normalizePatrolOptions(options = {}) {
     sameRepositoryOnly: options.sameRepositoryOnly ?? process.env.BUILDCHAIN_PATROL_SAME_REPOSITORY_ONLY,
     maxActions: intOption(options.maxActions ?? process.env.BUILDCHAIN_PATROL_MAX_ACTIONS, 1),
     mergeMethod: String(options.mergeMethod || process.env.BUILDCHAIN_PATROL_MERGE_METHOD || "merge").trim(),
+    landingMode: String(options.landingMode || process.env.BUILDCHAIN_PATROL_LANDING_MODE || "auto").trim(),
     dryRun: boolOption(options.dryRun ?? process.env.BUILDCHAIN_PATROL_DRY_RUN, true),
     outputPath: String(options.outputPath || process.env.BUILDCHAIN_PATROL_OUTPUT_PATH || DEFAULT_OUTPUT_PATH),
   };
@@ -167,6 +168,7 @@ export async function runBuildchainPatrol(optionsInput = {}, clientInput) {
         sameRepositoryOnly: options.sameRepositoryOnly,
         maxMerges: options.maxActions,
         mergeMethod: options.mergeMethod,
+        landingMode: options.landingMode,
         dryRun: options.dryRun,
         outputPath: path.join(path.dirname(options.outputPath), "dev-pr-auto-merge.json"),
       },
@@ -178,7 +180,7 @@ export async function runBuildchainPatrol(optionsInput = {}, clientInput) {
       result: mergeResult,
     });
     result.summary.evaluatedCount += mergeResult.evaluated.length;
-    result.summary.actionCount += mergeResult.merged.length;
+    result.summary.actionCount += mergeResult.actions.length;
     result.summary.skippedCount += mergeResult.skipped.length;
   }
 

package/scripts/dev-merge-queue.mjs

@@ -2,8 +2,10 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
+import { loadBuildchainConfig } from "../packages/core/buildchain-config.js";
 
 const RULESET_PREFIX = "Buildchain dev merge queue";
+const RULESET_BYPASS_TYPES = new Set(["Integration", "Team", "User"]);
 
 function positiveInteger(value, label, fallback) {
   const parsed = Number(value || fallback);
@@ -19,6 +21,53 @@ function requiredString(value, label) {
   return normalized;
 }
 
+function normalizeRulesetBypassActors(actors = []) {
+  const normalized = [];
+  const seen = new Set();
+  for (const actor of actors) {
+    const actorType = requiredString(actor?.actor_type, "ruleset bypass actor type");
+    const actorId = Number(actor?.actor_id);
+    if (!RULESET_BYPASS_TYPES.has(actorType)) {
+      throw new Error(`ruleset bypass actor type must be Integration, Team, or User, got '${actorType}'`);
+    }
+    if (!Number.isInteger(actorId) || actorId < 1) {
+      throw new Error("ruleset bypass actor id must be a positive integer");
+    }
+    const key = `${actorType}:${actorId}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    normalized.push({ actor_id: actorId, actor_type: actorType, bypass_mode: "always" });
+  }
+  return normalized;
+}
+
+export async function resolveRulesetBypassActors({
+  api,
+  repository,
+  apps = [],
+  users = [],
+  teams = [],
+} = {}) {
+  const [owner] = requiredString(repository, "repository").split("/");
+  const actors = [];
+  for (const slug of apps) {
+    const app = await api.request("GET", `apps/${encodeURIComponent(requiredString(slug, "bypass app"))}`);
+    actors.push({ actor_id: app.id, actor_type: "Integration" });
+  }
+  for (const login of users) {
+    const user = await api.request("GET", `users/${encodeURIComponent(requiredString(login, "bypass user"))}`);
+    actors.push({ actor_id: user.id, actor_type: "User" });
+  }
+  for (const slug of teams) {
+    const team = await api.request(
+      "GET",
+      `orgs/${encodeURIComponent(owner)}/teams/${encodeURIComponent(requiredString(slug, "bypass team"))}`,
+    );
+    actors.push({ actor_id: team.id, actor_type: "Team" });
+  }
+  return normalizeRulesetBypassActors(actors);
+}
+
 export function selectMergeQueueMethod(repositorySettings = {}) {
   const candidates = [
     ["MERGE", repositorySettings.allow_merge_commit],
@@ -32,6 +81,19 @@ export function selectMergeQueueMethod(repositorySettings = {}) {
   return selected;
 }
 
+function assertMergeQueueMethod(method, repositorySettings = {}) {
+  const normalized = requiredString(method, "merge queue method").toUpperCase();
+  const allowed = {
+    MERGE: repositorySettings.allow_merge_commit === true,
+    SQUASH: repositorySettings.allow_squash_merge === true,
+    REBASE: repositorySettings.allow_rebase_merge === true,
+  };
+  if (!(normalized in allowed) || !allowed[normalized]) {
+    throw new Error(`inherited merge queue method '${normalized}' is not enabled by the repository`);
+  }
+  return normalized;
+}
+
 export function validateMergeGroupWorkflows(workflows = []) {
   if (workflows.length === 0) {
     throw new Error("at least one required workflow must be declared with --workflow");
@@ -64,16 +126,23 @@ export function createDevMergeQueuePlan({
   protection,
   repositorySettings,
   rulesets = [],
+  bypassActors = [],
   checkResponseTimeoutMinutes = 120,
   maxEntriesToBuild = 1,
+  queueParameters = {},
+  allowInheritedWorkflowEvidence = false,
 } = {}) {
   const normalizedRepository = requiredString(repository, "repository");
   const normalizedBranch = requiredString(branch, "branch");
   if (!/^dev\/v\d+\/v\d+\.\d+$/.test(normalizedBranch)) {
     throw new Error(`branch must be a Buildchain dev channel, got '${normalizedBranch}'`);
   }
-  const workflowChecks = validateMergeGroupWorkflows(workflows);
-  const mergeMethod = selectMergeQueueMethod(repositorySettings);
+  const workflowChecks = workflows.length === 0 && allowInheritedWorkflowEvidence
+    ? []
+    : validateMergeGroupWorkflows(workflows);
+  const mergeMethod = queueParameters.merge_method
+    ? assertMergeQueueMethod(queueParameters.merge_method, repositorySettings)
+    : selectMergeQueueMethod(repositorySettings);
   const requiredChecks = protection?.required_status_checks?.checks || [];
   if (requiredChecks.length === 0) {
     throw new Error(`protected branch ${normalizedBranch} must declare required status checks before merge queue enablement`);
@@ -84,6 +153,7 @@ export function createDevMergeQueuePlan({
     name: rulesetName,
     target: "branch",
     enforcement: "active",
+    bypass_actors: normalizeRulesetBypassActors(bypassActors),
     conditions: {
       ref_name: {
         include: [`refs/heads/${normalizedBranch}`],
@@ -93,13 +163,23 @@ export function createDevMergeQueuePlan({
     rules: [{
       type: "merge_queue",
       parameters: {
-        check_response_timeout_minutes: positiveInteger(checkResponseTimeoutMinutes, "check response timeout", 120),
-        grouping_strategy: "ALLGREEN",
-        max_entries_to_build: positiveInteger(maxEntriesToBuild, "max entries to build", 1),
-        max_entries_to_merge: 1,
+        check_response_timeout_minutes: positiveInteger(
+          queueParameters.check_response_timeout_minutes || checkResponseTimeoutMinutes,
+          "check response timeout",
+          120,
+        ),
+        grouping_strategy: queueParameters.grouping_strategy || "ALLGREEN",
+        max_entries_to_build: positiveInteger(
+          queueParameters.max_entries_to_build || maxEntriesToBuild,
+          "max entries to build",
+          1,
+        ),
+        max_entries_to_merge: positiveInteger(queueParameters.max_entries_to_merge, "max entries to merge", 1),
         merge_method: mergeMethod,
-        min_entries_to_merge: 1,
-        min_entries_to_merge_wait_minutes: 0,
+        min_entries_to_merge: positiveInteger(queueParameters.min_entries_to_merge, "min entries to merge", 1),
+        min_entries_to_merge_wait_minutes: Number.isInteger(queueParameters.min_entries_to_merge_wait_minutes)
+          ? queueParameters.min_entries_to_merge_wait_minutes
+          : 0,
       },
     }],
   };
@@ -110,6 +190,7 @@ export function createDevMergeQueuePlan({
     branch: normalizedBranch,
     ok: true,
     workflowChecks,
+    workflowEvidence: workflowChecks.length > 0 ? "declared-workflows" : "inherited-active-ruleset",
     before: {
       strict: protection.required_status_checks?.strict === true,
       requiredStatusChecks: requiredChecks.map((check) => check.context),
@@ -144,13 +225,28 @@ export async function reconcileDevMergeQueue({
   branch,
   workflows,
   apply = false,
+  bypassApps = [],
+  bypassUsers = [],
+  bypassTeams = [],
   checkResponseTimeoutMinutes = 120,
   maxEntriesToBuild = 1,
+  bypassActors,
+  queueParameters = {},
+  allowInheritedWorkflowEvidence = false,
 } = {}) {
   const encodedBranch = encodeURIComponent(requiredString(branch, "branch"));
   const repositorySettings = await api.request("GET", `repos/${repository}`);
   const protection = await api.request("GET", `repos/${repository}/branches/${encodedBranch}/protection`);
   const rulesets = await api.request("GET", `repos/${repository}/rulesets?includes_parents=false&per_page=100`);
+  const resolvedBypassActors = bypassActors === undefined
+    ? await resolveRulesetBypassActors({
+        api,
+        repository,
+        apps: bypassApps,
+        users: bypassUsers,
+        teams: bypassTeams,
+      })
+    : normalizeRulesetBypassActors(bypassActors);
   const plan = createDevMergeQueuePlan({
     repository,
     branch,
@@ -158,8 +254,11 @@ export async function reconcileDevMergeQueue({
     protection,
     repositorySettings,
     rulesets,
+    bypassActors: resolvedBypassActors,
     checkResponseTimeoutMinutes,
     maxEntriesToBuild,
+    queueParameters,
+    allowInheritedWorkflowEvidence,
   });
   if (!apply) return { ...plan, action: "planned", applied: false };
   const results = [];
@@ -177,6 +276,172 @@ export async function reconcileDevMergeQueue({
   };
 }
 
+async function loadDetailedRulesets(api, repository) {
+  const rulesets = await api.request("GET", `repos/${repository}/rulesets?includes_parents=false&per_page=100`);
+  const details = [];
+  for (const ruleset of Array.isArray(rulesets) ? rulesets : []) {
+    if (ruleset?.target !== "branch" || ruleset?.enforcement === "disabled") continue;
+    if (Array.isArray(ruleset.rules) && ruleset.conditions) {
+      details.push(ruleset);
+      continue;
+    }
+    details.push(await api.request("GET", `repos/${repository}/rulesets/${ruleset.id}`));
+  }
+  return details;
+}
+
+function findExactMergeQueueRuleset(rulesets, branch) {
+  const include = `refs/heads/${branch}`;
+  return rulesets.find((ruleset) =>
+    ruleset?.enforcement === "active" &&
+    ruleset?.conditions?.ref_name?.include?.length === 1 &&
+    ruleset.conditions.ref_name.include[0] === include &&
+    ruleset?.rules?.some((rule) => rule?.type === "merge_queue"),
+  );
+}
+
+function mergeQueueRuleParameters(ruleset) {
+  return ruleset?.rules?.find((rule) => rule?.type === "merge_queue")?.parameters || {};
+}
+
+export async function resolveConfiguredDevMergeQueuePolicy({
+  api,
+  repository,
+  branch,
+  cwd = process.cwd(),
+} = {}) {
+  const loadedConfig = loadBuildchainConfig(cwd);
+  const declared = loadedConfig?.config?.governance?.dev?.mergeQueue;
+  const policy = declared || {
+    mode: "inherit",
+    requiredWorkflows: [],
+    checkResponseTimeoutMinutes: 120,
+    maxEntriesToBuild: 1,
+    bypassApps: [],
+    bypassUsers: [],
+    bypassTeams: [],
+  };
+  if (policy.mode === "disabled") {
+    return {
+      mode: "disabled",
+      declared: Boolean(declared),
+      enabled: false,
+      reason: "merge queue policy is explicitly disabled",
+      sourceBranch: null,
+      sourceRulesetId: null,
+      policy,
+    };
+  }
+
+  if (policy.mode === "enabled") {
+    return {
+      mode: "enabled",
+      declared: true,
+      enabled: true,
+      reason: "merge queue policy is explicitly enabled",
+      sourceBranch: null,
+      sourceRulesetId: null,
+      policy,
+      queueParameters: {},
+      inheritedBypassActors: undefined,
+    };
+  }
+
+  const repositorySettings = await api.request("GET", `repos/${repository}`);
+  const sourceBranch = repositorySettings.default_branch;
+  if (!sourceBranch || sourceBranch === branch) {
+    const targetRuleset = findExactMergeQueueRuleset(await loadDetailedRulesets(api, repository), branch);
+    if (!targetRuleset) {
+      return {
+        mode: "inherit",
+        declared: Boolean(declared),
+        enabled: false,
+        reason: "the active dev branch has no exact merge queue ruleset",
+        sourceBranch: sourceBranch || null,
+        sourceRulesetId: null,
+        policy,
+      };
+    }
+    return {
+      mode: "inherit",
+      declared: Boolean(declared),
+      enabled: true,
+      reason: "the active dev branch merge queue policy is inherited",
+      sourceBranch: branch,
+      sourceRulesetId: targetRuleset.id,
+      policy,
+      queueParameters: mergeQueueRuleParameters(targetRuleset),
+      inheritedBypassActors: targetRuleset.bypass_actors || [],
+    };
+  }
+  if (!/^dev\/v\d+\/v\d+\.\d+$/.test(sourceBranch)) {
+    return {
+      mode: "inherit",
+      declared: Boolean(declared),
+      enabled: false,
+      reason: `repository default branch '${sourceBranch}' is not a Buildchain dev channel`,
+      sourceBranch,
+      sourceRulesetId: null,
+      policy,
+    };
+  }
+  const sourceRuleset = findExactMergeQueueRuleset(await loadDetailedRulesets(api, repository), sourceBranch);
+  return {
+    mode: "inherit",
+    declared: Boolean(declared),
+    enabled: Boolean(sourceRuleset),
+    reason: sourceRuleset
+      ? "the active dev branch merge queue policy is inherited"
+      : "the active dev branch has no exact merge queue ruleset",
+    sourceBranch,
+    sourceRulesetId: sourceRuleset?.id || null,
+    policy,
+    queueParameters: mergeQueueRuleParameters(sourceRuleset),
+    inheritedBypassActors: sourceRuleset?.bypass_actors || [],
+  };
+}
+
+export async function reconcileConfiguredDevMergeQueue({
+  api,
+  repository,
+  branch,
+  cwd = process.cwd(),
+  apply = false,
+} = {}) {
+  const resolution = await resolveConfiguredDevMergeQueuePolicy({ api, repository, branch, cwd });
+  if (!resolution.enabled) {
+    return {
+      schemaVersion: 1,
+      contract: "kungfu-buildchain-dev-merge-queue-policy",
+      repository,
+      branch,
+      ok: true,
+      action: "not-required",
+      applied: false,
+      policyResolution: resolution,
+      operations: [],
+    };
+  }
+  const workflows = loadWorkflowSources(cwd, resolution.policy.requiredWorkflows);
+  const result = await reconcileDevMergeQueue({
+    api,
+    repository,
+    branch,
+    workflows,
+    apply,
+    bypassApps: resolution.policy.bypassApps,
+    bypassUsers: resolution.policy.bypassUsers,
+    bypassTeams: resolution.policy.bypassTeams,
+    bypassActors: resolution.mode === "inherit" ? resolution.inheritedBypassActors : undefined,
+    checkResponseTimeoutMinutes: resolution.policy.checkResponseTimeoutMinutes,
+    maxEntriesToBuild: resolution.policy.maxEntriesToBuild,
+    queueParameters: resolution.mode === "inherit" ? resolution.queueParameters : {},
+    allowInheritedWorkflowEvidence:
+      resolution.mode === "inherit" && resolution.policy.requiredWorkflows.length === 0,
+  });
+  return { ...result, policyResolution: resolution };
+}
+
 function createGhApi() {
   return {
     request(method, endpoint, body) {
@@ -236,6 +501,17 @@ async function main(args = process.argv.slice(2)) {
   const cwd = path.resolve(readFlag(args, "cwd", process.cwd()));
   const repository = readFlag(args, "repository", process.env.GITHUB_REPOSITORY || "");
   const branch = readFlag(args, "branch", "");
+  if (args.includes("--from-config")) {
+    const result = await reconcileConfiguredDevMergeQueue({
+      api: createGhApi(),
+      repository,
+      branch,
+      cwd,
+      apply: args.includes("--apply"),
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
   const workflows = loadWorkflowSources(cwd, readRepeatedFlag(args, "workflow"));
   const result = await reconcileDevMergeQueue({
     api: createGhApi(),
@@ -245,6 +521,9 @@ async function main(args = process.argv.slice(2)) {
     apply: args.includes("--apply"),
     checkResponseTimeoutMinutes: readFlag(args, "check-response-timeout-minutes", "120"),
     maxEntriesToBuild: readFlag(args, "max-entries-to-build", "1"),
+    bypassApps: readRepeatedFlag(args, "bypass-app"),
+    bypassUsers: readRepeatedFlag(args, "bypass-user"),
+    bypassTeams: readRepeatedFlag(args, "bypass-team"),
   });
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 }