@kungfu-tech/buildchain 4.0.9 → 4.1.0-alpha.0

package/packages/core/release/promote-ref/internal/channel-governance.js

@@ -0,0 +1,297 @@
+import {
+  getGitCommitWithRetry,
+  listPullRequestsAssociatedWithCommitWithRetry,
+  notFound,
+} from "./github-adapter.js";
+import {
+  expectedHeadRefForTarget,
+  parsePublishGateChannelRef,
+  parseReleaseLineRecoveryRef,
+  getPromotionRule,
+  parseReleaseLineRef,
+  MAJOR_GATE_REF,
+} from "./promotion-policy.js";
+import { parseVersionStateBranchName } from "./generated-branch.js";
+export async function getCommitInfo(octokit, owner, repo, sha) {
+  const { data } = await getGitCommitWithRetry({
+    octokit,
+    owner,
+    repo,
+    commitSha: sha,
+  });
+  return {
+    treeSha: data.tree?.sha,
+    parents: (data.parents || []).map((parent) => parent.sha),
+  };
+}
+export async function assertChannelPromotionPr({
+  octokit,
+  owner,
+  repo,
+  sha,
+  targetRef,
+}) {
+  const expectedHeadRef = expectedHeadRefForTarget(targetRef);
+  const { data: pullRequests } =
+    await listPullRequestsAssociatedWithCommitWithRetry({
+      octokit,
+      owner,
+      repo,
+      commitSha: sha,
+    });
+  const matchingPullRequest = pullRequests.find((pullRequest) => {
+    const baseRef = pullRequest.base?.ref;
+    const headRef = pullRequest.head?.ref;
+    const headRepo = pullRequest.head?.repo?.full_name;
+    const matchingVersionStateTarget = parseVersionStateBranchName(headRef);
+    const matchingPublishGateTarget =
+      parsePublishGateChannelRef(headRef)?.targetRef;
+    const matchingReleaseRecoveryTarget =
+      parseReleaseLineRecoveryRef(headRef)?.targetRef;
+    if (getPromotionRule(targetRef).channel === "major") {
+      return (
+        pullRequest.merged_at &&
+        baseRef === targetRef &&
+        (parseReleaseLineRef(headRef) ||
+          matchingVersionStateTarget === targetRef) &&
+        headRepo === `${owner}/${repo}`
+      );
+    }
+    return (
+      pullRequest.merged_at &&
+      baseRef === targetRef &&
+      (headRef === expectedHeadRef ||
+        matchingVersionStateTarget === targetRef ||
+        matchingPublishGateTarget === targetRef ||
+        matchingReleaseRecoveryTarget === targetRef) &&
+      headRepo === `${owner}/${repo}`
+    );
+  });
+  if (!matchingPullRequest) {
+    throw new Error(
+      `Promotion source ${sha} must come from a merged same-repository PR ${expectedHeadRef} -> ${targetRef}, publish-gate/${getPromotionRule(targetRef).channel}/... -> ${targetRef}, buildchain/version-state/* -> ${targetRef}, or an exact line-scoped channel recovery PR`,
+    );
+  }
+  return matchingPullRequest;
+}
+export async function getMajorGateSource({
+  octokit,
+  owner,
+  repo,
+  sha,
+  targetRef = MAJOR_GATE_REF,
+}) {
+  const pullRequest = await assertChannelPromotionPr({
+    octokit,
+    owner,
+    repo,
+    sha,
+    targetRef,
+  });
+  const source = parseReleaseLineRef(pullRequest.head?.ref);
+  if (!source) {
+    throw new Error(
+      `Promotion source ${sha} must come from a merged same-repository PR release/vN/vN.M -> ${targetRef}`,
+    );
+  }
+  return {
+    source,
+    pullRequest,
+    major: source.major + 1,
+    minor: 0,
+    releasePrefix: `v${source.major + 1}.0`,
+    majorTag: `v${source.major + 1}`,
+    minorTag: `v${source.major + 1}.0`,
+    alphaTag: `v${source.major + 1}.0-alpha`,
+  };
+}
+export function protectedStatusCheckNames(protection = {}) {
+  const checks = protection.required_status_checks;
+  return [
+    ...new Set(
+      [
+        ...(checks?.contexts || []),
+        ...((checks?.checks || []).map(
+          (check) => check.context || check.app_id,
+        ) || []),
+      ].map(String),
+    ),
+  ];
+}
+export function resolveProtectedStatusCheckContext({
+  protection = {},
+  requiredStatusCheck = "check",
+} = {}) {
+  const declared = String(requiredStatusCheck || "").trim();
+  const checkNames = protectedStatusCheckNames(protection);
+  if (checkNames.includes(declared)) return declared;
+  const emittedCandidates = [
+    ...new Set(
+      checkNames.filter(
+        (name) =>
+          name === `${declared} / ${declared}` ||
+          name.startsWith(`${declared} / `),
+      ),
+    ),
+  ];
+  return emittedCandidates.length === 1 ? emittedCandidates[0] : declared;
+}
+export async function assertProviderEnforcedChannelTransaction({
+  octokit,
+  owner,
+  repo,
+  targetRef,
+  sourceSha,
+  expectedChannelSha = sourceSha,
+  requiredStatusCheck,
+}) {
+  const { data: branch } = await octokit.rest.repos.getBranch({
+    owner,
+    repo,
+    branch: targetRef,
+  });
+  const protection = branch.protection || {};
+  const resolvedStatusCheck = resolveProtectedStatusCheckContext({
+    protection,
+    requiredStatusCheck,
+  });
+  const requiredCheck = (protection.required_status_checks?.checks || []).find(
+    (entry) => entry.context === resolvedStatusCheck,
+  );
+  const pullRequest = await assertChannelPromotionPr({
+    octokit,
+    owner,
+    repo,
+    sha: sourceSha,
+    targetRef,
+  });
+  const { data: reviews } = await octokit.rest.pulls.listReviews({
+    owner,
+    repo,
+    pull_number: pullRequest.number,
+    per_page: 100,
+  });
+  const latestReviews = new Map();
+  for (const review of reviews || []) {
+    const login = String(review?.user?.login || "");
+    if (login) latestReviews.set(login, review);
+  }
+  const independentApproval = [...latestReviews.values()].some(
+    (review) =>
+      review.state === "APPROVED" &&
+      review.user?.login !== pullRequest.user?.login,
+  );
+  const pullRequestHeadSha = String(pullRequest.head?.sha || "").trim();
+  const validPullRequestHeadSha = /^[0-9a-f]{40}$/i.test(pullRequestHeadSha);
+  const { data: checkRuns } = validPullRequestHeadSha
+    ? await octokit.rest.checks.listForRef({
+        owner,
+        repo,
+        ref: pullRequestHeadSha,
+        check_name: resolvedStatusCheck,
+        filter: "latest",
+        per_page: 100,
+      })
+    : { data: { check_runs: [] } };
+  const requiredCheckPassed = (checkRuns.check_runs || []).some(
+    (entry) =>
+      entry.name === resolvedStatusCheck &&
+      entry.conclusion === "success" &&
+      (!requiredCheck?.app_id || entry.app?.id === requiredCheck.app_id),
+  );
+  const missing = [];
+  if (branch.protected !== true) missing.push("must be provider-protected");
+  if (branch.commit?.sha !== expectedChannelSha)
+    missing.push("must still point at the exact admitted channel head");
+  if (protection.required_status_checks?.enforcement_level !== "everyone") {
+    missing.push("must enforce required status checks for everyone");
+  }
+  if (!protectedStatusCheckNames(protection).includes(resolvedStatusCheck)) {
+    missing.push(
+      `must require a ${requiredStatusCheck} status check using the exact context`,
+    );
+  }
+  if (!validPullRequestHeadSha) {
+    missing.push("merged source PR must expose an immutable head SHA");
+  }
+  if (!requiredCheckPassed)
+    missing.push(
+      `required status check ${resolvedStatusCheck} must pass from its configured app`,
+    );
+  if (!independentApproval)
+    missing.push(
+      "must have an independent approving review on the merged source PR",
+    );
+  if (missing.length > 0) {
+    throw new Error(
+      `Protected channel ${targetRef} provider transaction is not qualifying: ${missing.join("; ")}`,
+    );
+  }
+  return resolvedStatusCheck;
+}
+export async function assertProtectedChannel({
+  octokit,
+  owner,
+  repo,
+  targetRef,
+  sourceSha,
+  expectedChannelSha = sourceSha,
+  requiredStatusCheck = "check",
+}) {
+  let protection;
+  try {
+    ({ data: protection } = await octokit.rest.repos.getBranchProtection({
+      owner,
+      repo,
+      branch: targetRef,
+    }));
+  } catch (error) {
+    if (error.status === 403 || notFound(error)) {
+      return assertProviderEnforcedChannelTransaction({
+        octokit,
+        owner,
+        repo,
+        targetRef,
+        sourceSha,
+        expectedChannelSha,
+        requiredStatusCheck,
+      });
+    }
+    throw error;
+  }
+  const missing = [];
+  if (protection.enforce_admins?.enabled !== true) {
+    missing.push("must enforce branch protection for administrators");
+  }
+  if (protection.allow_force_pushes?.enabled !== false) {
+    missing.push("must disallow force pushes");
+  }
+  if (protection.allow_deletions?.enabled !== false) {
+    missing.push("must disallow branch deletion");
+  }
+  if (protection.required_conversation_resolution?.enabled !== true) {
+    missing.push("must require conversation resolution");
+  }
+  const reviews = protection.required_pull_request_reviews;
+  if (!reviews || Number(reviews.required_approving_review_count || 0) < 1) {
+    missing.push("must require at least one approving review");
+  }
+  const checks = protection.required_status_checks;
+  if (!checks) missing.push("must require status checks");
+  const checkNames = protectedStatusCheckNames(protection);
+  const resolvedStatusCheck = resolveProtectedStatusCheckContext({
+    protection,
+    requiredStatusCheck,
+  });
+  if (!checkNames.includes(resolvedStatusCheck)) {
+    missing.push(
+      `must require a ${requiredStatusCheck} status check using the exact context`,
+    );
+  }
+  if (missing.length > 0) {
+    throw new Error(
+      `Protected channel ${targetRef} is missing required protection settings: ${missing.join("; ")}`,
+    );
+  }
+  return resolvedStatusCheck;
+}

package/packages/core/release/promote-ref/internal/channel-resume.js

@@ -0,0 +1,198 @@
+import { readDurableReleaseTransaction } from "./durable-transaction-store.js";
+import { releaseTransactionStateRef } from "../../publish-transaction.js";
+import { notFound } from "./github-adapter.js";
+import { stripTagPrefix } from "./promotion-policy.js";
+import { parseAlphaPrereleaseRef } from "./tag-selection.js";
+import {
+  transactionHasPublishedMaterial,
+  releaseCommitIncludesTransactionHead,
+  releaseCommitMatchesTransactionMaterial,
+} from "./transaction-recovery.js";
+import { parseReleaseTransactionStateRef } from "./channel-tags.js";
+export async function readDurableTransactionForVersion({
+  octokit,
+  owner,
+  repo,
+  version,
+}) {
+  if (!version) {
+    return undefined;
+  }
+  try {
+    return await readDurableReleaseTransaction({
+      octokit,
+      owner,
+      repo,
+      stateRef: releaseTransactionStateRef(version),
+    });
+  } catch (error) {
+    const message = error?.message || "";
+    if (
+      notFound(error) ||
+      /missing state\.json|getTree is not a function/i.test(message)
+    ) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+export async function resumableAlphaTransactionState({
+  octokit,
+  owner,
+  repo,
+  cwd,
+  refs,
+  releasePrefix,
+  targetRef,
+  sourceSha,
+  expectedVersion = "",
+}) {
+  const candidates = refs
+    .map((ref) => parseAlphaPrereleaseRef(ref.ref, releasePrefix))
+    .filter((ref) => ref?.source === "release-state")
+    .filter(
+      (ref) => !expectedVersion || stripTagPrefix(ref.tag) === expectedVersion,
+    )
+    .sort((a, b) => b.patch - a.patch || b.prerelease - a.prerelease);
+  for (const candidate of candidates) {
+    const version = stripTagPrefix(candidate.tag);
+    let transaction;
+    try {
+      transaction = await readDurableReleaseTransaction({
+        octokit,
+        owner,
+        repo,
+        stateRef: releaseTransactionStateRef(version),
+      });
+    } catch (error) {
+      const message = error?.message || "";
+      if (notFound(error) || /missing state\.json/i.test(message)) {
+        continue;
+      }
+      throw error;
+    }
+    const publishedMaterial = transactionHasPublishedMaterial(transaction);
+    const exactTransactionSource = [
+      transaction?.source_sha,
+      transaction?.release_sha,
+      transaction?.release_material_sha,
+    ].includes(sourceSha);
+    const includesTransactionHead = (transactionReleaseSha) =>
+      releaseCommitIncludesTransactionHead({
+        octokit,
+        owner,
+        repo,
+        releaseSha: sourceSha,
+        transactionReleaseSha,
+      });
+    const transactionInSourceHistory =
+      !publishedMaterial &&
+      ((await includesTransactionHead(transaction?.release_sha)) ||
+        (await includesTransactionHead(transaction?.release_material_sha)));
+    const publishedMaterialMerge =
+      publishedMaterial &&
+      (await releaseCommitMatchesTransactionMaterial({
+        octokit,
+        owner,
+        repo,
+        releaseSha: sourceSha,
+        transactionReleaseShas: [
+          transaction?.release_sha,
+          transaction?.release_material_sha,
+        ],
+      }));
+    const exactCompletedTransaction =
+      transaction?.state === "complete" && exactTransactionSource;
+    if (
+      transaction &&
+      (!expectedVersion || transaction.version === expectedVersion) &&
+      transaction.target_ref === targetRef &&
+      transaction.exact_tag === candidate.tag &&
+      !["abandoned", "failed_permanently"].includes(transaction.state) &&
+      (exactCompletedTransaction ||
+        (transaction.state !== "complete" &&
+          (exactTransactionSource ||
+            transactionInSourceHistory ||
+            publishedMaterialMerge)))
+    ) {
+      return {
+        ...candidate,
+        version,
+        transaction,
+      };
+    }
+  }
+  return undefined;
+}
+export async function resumableReleaseTransactionState({
+  octokit,
+  owner,
+  repo,
+  refs,
+  releasePrefix,
+  targetRef,
+  sourceSha,
+  expectedVersion = "",
+}) {
+  const candidates = refs
+    .map((ref) => parseReleaseTransactionStateRef(ref.ref, releasePrefix))
+    .filter(Boolean)
+    .sort((a, b) => b.patch - a.patch);
+  for (const candidate of candidates) {
+    const version = stripTagPrefix(candidate.tag);
+    let transaction;
+    try {
+      transaction = await readDurableReleaseTransaction({
+        octokit,
+        owner,
+        repo,
+        stateRef: releaseTransactionStateRef(version),
+      });
+    } catch (error) {
+      const message = error?.message || "";
+      if (notFound(error) || /missing state\.json/i.test(message)) {
+        continue;
+      }
+      throw error;
+    }
+    const exactTransactionSource =
+      transaction?.source_sha === sourceSha ||
+      transaction?.release_sha === sourceSha ||
+      transaction?.release_material_sha === sourceSha;
+    const transactionInSourceHistory =
+      !transactionHasPublishedMaterial(transaction) &&
+      ((await releaseCommitIncludesTransactionHead({
+        octokit,
+        owner,
+        repo,
+        releaseSha: sourceSha,
+        transactionReleaseSha: transaction?.release_sha,
+      })) ||
+        (await releaseCommitIncludesTransactionHead({
+          octokit,
+          owner,
+          repo,
+          releaseSha: sourceSha,
+          transactionReleaseSha: transaction?.release_material_sha,
+        })));
+    const exactCompletedTransaction =
+      transaction?.state === "complete" && exactTransactionSource;
+    if (
+      transaction &&
+      (!expectedVersion || transaction.version === expectedVersion) &&
+      transaction.target_ref === targetRef &&
+      transaction.exact_tag === candidate.tag &&
+      !["abandoned", "failed_permanently"].includes(transaction.state) &&
+      (exactCompletedTransaction ||
+        (transaction.state !== "complete" &&
+          (exactTransactionSource || transactionInSourceHistory)))
+    ) {
+      return {
+        ...candidate,
+        version,
+        transaction,
+      };
+    }
+  }
+  return undefined;
+}

package/packages/core/release/promote-ref/internal/channel-tags.js

@@ -0,0 +1,207 @@
+import { getPromotionRule } from "./promotion-policy.js";
+import { discoverVersionStateFiles } from "../../version-state.js";
+import { releaseTransactionStateRef } from "../../publish-transaction.js";
+export function latestAlphaForPatch(refs, releasePrefix, patch) {
+  return alphaTagsForPatch(refs, releasePrefix, patch)[0];
+}
+export function alphaTagsForPatch(refs, releasePrefix, patch) {
+  return refs
+    .map((ref) => {
+      const parsed = parseAlphaPrereleaseTag(ref.ref, releasePrefix);
+      if (!parsed || parsed.patch !== patch) {
+        return undefined;
+      }
+      return { ...parsed, sha: ref.object?.sha };
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.prerelease - a.prerelease);
+}
+export function ownsMajorAlphaChannel({ refs = [], major, minor }) {
+  const floatingPattern = new RegExp(`^refs/tags/v${major}\\.(\\d+)-alpha$`);
+  const exactPattern = new RegExp(
+    `^refs/tags/v${major}\\.(\\d+)\\.\\d+-alpha\\.\\d+$`,
+  );
+  let highestPublishedMinor = -1;
+  for (const ref of refs) {
+    const refName = String(ref?.ref || "");
+    const match = refName.match(floatingPattern) || refName.match(exactPattern);
+    if (match) {
+      highestPublishedMinor = Math.max(highestPublishedMinor, Number(match[1]));
+    }
+  }
+  return Number(minor) >= highestPublishedMinor;
+}
+export function resolveTagsForTarget(targetRef, inputTags) {
+  const rule = getPromotionRule(targetRef);
+  if (rule.channel === "major" && (!inputTags || inputTags.length === 0)) {
+    return [];
+  }
+  if (rule.channel === "major") {
+    for (const tag of inputTags) {
+      if (
+        !/^v\d+$|^v\d+-alpha$|^v\d+\.0$|^v\d+\.0-alpha$|^v\d+\.0\.\d+$|^v\d+\.0\.\d+-alpha\.\d+$/.test(
+          tag,
+        )
+      ) {
+        throw new Error(
+          `Tag ${tag} is not allowed for publish-gate/major promotion`,
+        );
+      }
+    }
+    return inputTags;
+  }
+  const tags = inputTags && inputTags.length > 0 ? inputTags : rule.tags;
+  for (const tag of tags) {
+    const isLineReleaseTag =
+      tag.startsWith(`${rule.releasePrefix}.`) && !tag.includes("-alpha.");
+    const isLineAlphaTag =
+      tag === rule.alphaTag ||
+      (tag.startsWith(`${rule.releasePrefix}.`) && tag.includes("-alpha."));
+    const allowed =
+      rule.channel === "release"
+        ? tag === rule.majorTag ||
+          tag === rule.majorAlphaTag ||
+          tag === rule.minorTag ||
+          tag === rule.alphaTag ||
+          isLineReleaseTag ||
+          isLineAlphaTag
+        : tag === rule.majorAlphaTag || tag === rule.alphaTag || isLineAlphaTag;
+    if (!allowed) {
+      throw new Error(
+        `Tag ${tag} is not allowed for ${rule.channel} promotion`,
+      );
+    }
+  }
+  return tags;
+}
+export function parseReleasePatchTag(refName, releasePrefix) {
+  const match = String(refName || "").match(
+    new RegExp(`^refs/tags/${releasePrefix.replace(".", "\\.")}\\.(\\d+)$`),
+  );
+  if (!match) {
+    return undefined;
+  }
+  return {
+    tag: refName.replace(/^refs\/tags\//, ""),
+    patch: Number(match[1]),
+  };
+}
+export function parseReleaseTransactionStateRef(refName, releasePrefix) {
+  const statePrefix = releasePrefix.replace(/^v/, "").replaceAll(".", "-");
+  const match = String(refName || "").match(
+    new RegExp(`^refs/heads/buildchain/release-state/${statePrefix}-(\\d+)$`),
+  );
+  if (!match) {
+    return undefined;
+  }
+  return {
+    tag: `${releasePrefix}.${Number(match[1])}`,
+    patch: Number(match[1]),
+    occupied: true,
+  };
+}
+export function parseAlphaPrereleaseTag(refName, releasePrefix) {
+  const match = String(refName || "").match(
+    new RegExp(
+      `^refs/tags/${releasePrefix.replace(".", "\\.")}\\.(\\d+)-alpha\\.(\\d+)$`,
+    ),
+  );
+  if (!match) {
+    return undefined;
+  }
+  return {
+    tag: refName.replace(/^refs\/tags\//, ""),
+    patch: Number(match[1]),
+    prerelease: Number(match[2]),
+  };
+}
+export function parseAlphaPrereleaseVersion(version, releasePrefix) {
+  return parseAlphaPrereleaseTag(`refs/tags/v${version}`, releasePrefix);
+}
+export function parseAlphaTransactionStateRef(refName, releasePrefix) {
+  const statePrefix = releasePrefix.replace(/^v/, "").replaceAll(".", "-");
+  const match = String(refName || "").match(
+    new RegExp(
+      `^refs/heads/buildchain/release-state/${statePrefix}-(\\d+)-alpha-(\\d+)$`,
+    ),
+  );
+  if (!match) {
+    return undefined;
+  }
+  return {
+    tag: `${releasePrefix}.${Number(match[1])}-alpha.${Number(match[2])}`,
+    patch: Number(match[1]),
+    prerelease: Number(match[2]),
+    occupied: true,
+  };
+}
+export function getVersionFileValue(file) {
+  if (file.type === "json" || file.type === "toml") {
+    return String(file.key || "")
+      .split(".")
+      .reduce((current, segment) => current?.[segment], file.content);
+  }
+  if (file.type === "regex") {
+    const match = file.source.match(file.pattern);
+    return match?.groups?.version;
+  }
+  return file.content?.version;
+}
+export function currentAlphaVersionState({ cwd, refs, releasePrefix }) {
+  const discovered = discoverVersionStateFiles(cwd);
+  if (discovered.files.length === 0) {
+    return undefined;
+  }
+  const versions = [
+    ...new Set(
+      discovered.files
+        .map((file) => getVersionFileValue(file))
+        .filter((version) => typeof version === "string" && version.trim()),
+    ),
+  ];
+  if (versions.length !== 1) {
+    return undefined;
+  }
+  const parsed = parseAlphaPrereleaseVersion(versions[0], releasePrefix);
+  if (!parsed) {
+    return undefined;
+  }
+  return {
+    ...parsed,
+    tag: `v${versions[0]}`,
+    version: versions[0],
+  };
+}
+export function currentReleaseVersionState({ cwd, refs, releasePrefix }) {
+  const discovered = discoverVersionStateFiles(cwd);
+  if (discovered.files.length === 0) {
+    return undefined;
+  }
+  const versions = [
+    ...new Set(
+      discovered.files
+        .map((file) => getVersionFileValue(file))
+        .filter((version) => typeof version === "string" && version.trim()),
+    ),
+  ];
+  if (versions.length !== 1) {
+    return undefined;
+  }
+  const parsed = parseReleasePatchTag(
+    `refs/tags/v${versions[0]}`,
+    releasePrefix,
+  );
+  if (!parsed) {
+    return undefined;
+  }
+  const stateRef = `refs/heads/${releaseTransactionStateRef(versions[0])}`;
+  const hasDurableState = refs.some((ref) => ref.ref === stateRef);
+  if (!hasDurableState) {
+    return undefined;
+  }
+  return {
+    ...parsed,
+    tag: `v${versions[0]}`,
+    version: versions[0],
+  };
+}