sailfork / t3code-github / .repos/ alchemy-effect/ packages/ github/ src/ BranchProtection.ts

import * as Repos from "@distilled.cloud/github/repos";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { withBaseUrl, gitHubBaseUrlChanged } from "./BaseUrl.ts";
import type * as GitHub from "./Providers.ts";

export interface BranchProtectionProps {
  /**
   * Repository owner (user or organization).
   */
  owner: string;

  /**
   * Repository name.
   */
  repository: string;

  /**
   * Name of the branch to protect (e.g. `main`). The branch is the rule's
   * identity — changing it replaces the protection. The branch must exist.
   */
  branch: string;

  /**
   * Require status checks to pass before merging. Omit to disable.
   */
  requiredStatusChecks?: {
    /**
     * Require branches to be up to date with the base branch before merging.
     * @default false
     */
    strict?: boolean;

    /**
     * Status check contexts that must pass. Prefer `checks` for control over
     * which GitHub App must report the check.
     */
    contexts?: string[];

    /**
     * Status checks that must pass, optionally pinned to the GitHub App that
     * must report them. When this is set, the update sends `checks` and
     * omits `contexts`. GitHub rejects a request that includes both.
     */
    checks?: {
      /**
       * Name of the required check.
       */
      context: string;

      /**
       * ID of the GitHub App that must provide this check. Omit to accept the
       * app that most recently reported it; pass `-1` to accept any app.
       */
      appId?: number;
    }[];
  };

  /**
   * Require pull request reviews before merging. Omit to disable.
   */
  requiredPullRequestReviews?: {
    /**
     * Dismiss approving reviews when a new commit is pushed.
     * @default false
     */
    dismissStaleReviews?: boolean;

    /**
     * Block merging until code owners have reviewed.
     * @default false
     */
    requireCodeOwnerReviews?: boolean;

    /**
     * Number of approving reviews required (0–6).
     * @default 0
     */
    requiredApprovingReviewCount?: number;

    /**
     * Require the most recent push to be approved by someone other than the
     * pusher.
     * @default false
     */
    requireLastPushApproval?: boolean;

    /**
     * Who may dismiss pull request reviews. Only available on
     * organization-owned repositories; omit for personal repositories.
     */
    dismissalRestrictions?: {
      /**
       * User logins with dismissal access.
       */
      users?: string[];

      /**
       * Team slugs with dismissal access.
       */
      teams?: string[];

      /**
       * App slugs with dismissal access.
       */
      apps?: string[];
    };

    /**
     * Who may bypass pull request requirements.
     */
    bypassPullRequestAllowances?: {
      /**
       * User logins allowed to bypass.
       */
      users?: string[];

      /**
       * Team slugs allowed to bypass.
       */
      teams?: string[];

      /**
       * App slugs allowed to bypass.
       */
      apps?: string[];
    };
  };

  /**
   * Restrict who can push to the branch. Only available on
   * organization-owned repositories. Omit to disable.
   */
  restrictions?: {
    /**
     * User logins with push access.
     */
    users?: string[];

    /**
     * Team slugs with push access.
     */
    teams?: string[];

    /**
     * App slugs with push access.
     */
    apps?: string[];
  };

  /**
   * Enforce all configured restrictions for repository administrators.
   * @default false
   */
  enforceAdmins?: boolean;

  /**
   * Require signed commits on the branch.
   * @default false
   */
  requiredSignatures?: boolean;

  /**
   * Require a linear commit history (no merge commits). The repository must
   * allow squash or rebase merging.
   * @default false
   */
  requiredLinearHistory?: boolean;

  /**
   * Permit force pushes by anyone with write access.
   * @default false
   */
  allowForcePushes?: boolean;

  /**
   * Permit deletion of the branch by anyone with write access.
   * @default false
   */
  allowDeletions?: boolean;

  /**
   * When `restrictions` is set, also block pushes that create new branches
   * unless the pusher is allowed by the restrictions.
   * @default false
   */
  blockCreations?: boolean;

  /**
   * Require all pull request conversations to be resolved before merging.
   * @default false
   */
  requiredConversationResolution?: boolean;

  /**
   * Make the branch read-only.
   * @default false
   */
  lockBranch?: boolean;

  /**
   * Allow fork syncing (pulling upstream changes) while the branch is locked.
   * @default false
   */
  allowForkSyncing?: boolean;

  /**
   * Override the GitHub host or API base URL for this resource only (e.g.
   * `github.example.com` for GitHub Enterprise). Falls back to
   * `GitHub.providers({ baseUrl })`, then to the host resolved by the auth
   * provider. Changing it replaces the resource — the same branch on a
   * different GitHub instance is a different physical resource.
   */
  baseUrl?: string;
}

export interface BranchProtection extends Resource<
  "GitHub.BranchProtection",
  BranchProtectionProps,
  {
    /**
     * API URL of the branch protection rule.
     */
    url: string;

    /**
     * The protected branch name.
     */
    branch: string;

    /**
     * Whether restrictions are enforced for administrators.
     */
    enforceAdmins: boolean;

    /**
     * Whether signed commits are required.
     */
    requiredSignatures: boolean;

    /**
     * Whether a linear history is required.
     */
    requiredLinearHistory: boolean;

    /**
     * Whether force pushes are allowed.
     */
    allowForcePushes: boolean;

    /**
     * Whether branch deletion is allowed.
     */
    allowDeletions: boolean;

    /**
     * Whether conversation resolution is required before merging.
     */
    requiredConversationResolution: boolean;

    /**
     * Whether the branch is locked (read-only).
     */
    lockBranch: boolean;
  },
  never,
  GitHub.Providers
> {}

/**
 * A GitHub branch protection rule.
 *
 * `BranchProtection` manages the classic branch protection settings on a
 * single branch: required status checks, required pull request reviews,
 * push restrictions, admin enforcement, signed commits, linear history, and
 * the force-push / deletion / lock toggles. Pair it with `GitHub.Repository`
 * to protect the default branch of a repository provisioned in the same
 * stack.
 *
 * Branch protection is available on public repositories on every plan;
 * private repositories require GitHub Pro, Team, or Enterprise. Push
 * restrictions and dismissal restrictions are only available on
 * organization-owned repositories.
 *
 * Authentication is resolved via the GitHub `Credentials` service supplied
 * by `GitHub.providers()` (env, stored PAT, `gh` CLI, or OAuth). The token
 * needs `repo` scope and admin access to the repository.
 *
 * ### Protecting a Branch
 * **Example:** Require Pull Request Reviews
 * ```typescript
 * yield* GitHub.BranchProtection("main", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   branch: "main",
 *   requiredPullRequestReviews: {
 *     requiredApprovingReviewCount: 1,
 *     dismissStaleReviews: true,
 *   },
 * });
 * ```
 *
 * **Example:** Require Status Checks and a Linear History
 * ```typescript
 * yield* GitHub.BranchProtection("main", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   branch: "main",
 *   requiredStatusChecks: {
 *     strict: true,
 *     checks: [{ context: "ci" }],
 *   },
 *   requiredLinearHistory: true,
 *   requiredConversationResolution: true,
 *   enforceAdmins: true,
 * });
 * ```
 *
 * ### Protecting a Repository's Default Branch
 * **Example:** Protect the Default Branch of a New Repository
 * ```typescript
 * import * as Output from "alchemy/Output";
 *
 * const repo = yield* GitHub.Repository("repo", {
 *   owner: "my-org",
 *   name: "my-repo",
 *   autoInit: true,
 * });
 *
 * yield* GitHub.BranchProtection("main", {
 *   owner: "my-org",
 *   repository: Output.map(repo.fullName, (fullName) => fullName.split("/")[1]!),
 *   branch: repo.defaultBranch,
 *   requiredPullRequestReviews: { requiredApprovingReviewCount: 1 },
 *   allowForcePushes: false,
 *   allowDeletions: false,
 * });
 * ```
 *
 * ### Restricting Pushes
 * **Example:** Only a Team May Push
 * ```typescript
 * yield* GitHub.BranchProtection("release", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   branch: "release",
 *   restrictions: { teams: ["release-managers"] },
 *   blockCreations: true,
 *   requiredSignatures: true,
 * });
 * ```
 *
 * @resource
 * @product Repository
 */
export const BranchProtection = Resource<BranchProtection>("GitHub.BranchProtection");

/**
 * The `GET .../protection` payload. Both the GET and PUT responses share this
 * shape for the fields we surface; every nested block is optional because
 * GitHub omits disabled aspects entirely.
 */
interface ProtectionPayload {
  url?: string;
  enforce_admins?: { enabled?: boolean };
  required_signatures?: { enabled?: boolean };
  required_linear_history?: { enabled?: boolean };
  allow_force_pushes?: { enabled?: boolean };
  allow_deletions?: { enabled?: boolean };
  required_conversation_resolution?: { enabled?: boolean };
  lock_branch?: { enabled?: boolean };
}

type RequiredStatusChecks = Repos.UpdateBranchProtectionRequest["required_status_checks"];

const requiredStatusChecksOf = (
  checks: BranchProtectionProps["requiredStatusChecks"],
): RequiredStatusChecks => {
  // `contexts` or `checks`, never both: GitHub rejects a body with both.
  if (checks === undefined) return null;
  const strict = checks.strict ?? false;
  if (checks.checks === undefined) {
    return { strict, contexts: checks.contexts ?? [] };
  }
  return {
    strict,
    checks: checks.checks.map((check) => ({
      context: check.context,
      ...(check.appId === undefined ? {} : { app_id: check.appId }),
    })),
  };
};

const attrsOf = (
  branch: string,
  protection: ProtectionPayload,
): BranchProtection["Attributes"] => ({
  url: protection.url ?? "",
  branch,
  enforceAdmins: protection.enforce_admins?.enabled ?? false,
  requiredSignatures: protection.required_signatures?.enabled ?? false,
  requiredLinearHistory: protection.required_linear_history?.enabled ?? false,
  allowForcePushes: protection.allow_force_pushes?.enabled ?? false,
  allowDeletions: protection.allow_deletions?.enabled ?? false,
  requiredConversationResolution: protection.required_conversation_resolution?.enabled ?? false,
  lockBranch: protection.lock_branch?.enabled ?? false,
});

export const BranchProtectionProvider = () =>
  Provider.succeed(BranchProtection, {
    stables: ["url", "branch"],

    // {owner, repository, branch, host} is the rule's path identity — GitHub
    // has no rename, so changing any of them replaces the resource.
    diff: Effect.fn(function* ({ news, olds }) {
      if (olds === undefined) return;
      // Unresolved props may change the path identity and orphan the old rule.
      if (!isResolved(news)) return { action: "replace" };
      if (
        news.owner !== olds.owner ||
        news.repository !== olds.repository ||
        news.branch !== olds.branch ||
        (yield* gitHubBaseUrlChanged(olds, news))
      ) {
        return { action: "replace" };
      }
    }),

    reconcile: Effect.fn(
      function* ({ news }) {
        const branch = { owner: news.owner, repo: news.repository, branch: news.branch };

        // Ensure & Sync — the PUT is a full upsert of the rule. Send explicit
        // values (or `null`) for every aspect so removed props converge back
        // to their defaults rather than being left as-is.
        const requiredStatusChecks = requiredStatusChecksOf(news.requiredStatusChecks);
        const reviews = news.requiredPullRequestReviews;
        const restrictions = news.restrictions;

        yield* Repos.updateBranchProtection({
          ...branch,
          required_status_checks: requiredStatusChecks,
          enforce_admins: news.enforceAdmins ?? false,
          required_pull_request_reviews:
            reviews === undefined
              ? null
              : {
                  dismiss_stale_reviews: reviews.dismissStaleReviews ?? false,
                  require_code_owner_reviews: reviews.requireCodeOwnerReviews ?? false,
                  required_approving_review_count: reviews.requiredApprovingReviewCount ?? 0,
                  require_last_push_approval: reviews.requireLastPushApproval ?? false,
                  ...(reviews.dismissalRestrictions === undefined
                    ? {}
                    : {
                        dismissal_restrictions: {
                          users: reviews.dismissalRestrictions.users ?? [],
                          teams: reviews.dismissalRestrictions.teams ?? [],
                          apps: reviews.dismissalRestrictions.apps ?? [],
                        },
                      }),
                  ...(reviews.bypassPullRequestAllowances === undefined
                    ? {}
                    : {
                        bypass_pull_request_allowances: {
                          users: reviews.bypassPullRequestAllowances.users ?? [],
                          teams: reviews.bypassPullRequestAllowances.teams ?? [],
                          apps: reviews.bypassPullRequestAllowances.apps ?? [],
                        },
                      }),
                },
          restrictions:
            restrictions === undefined
              ? null
              : {
                  users: restrictions.users ?? [],
                  teams: restrictions.teams ?? [],
                  apps: restrictions.apps ?? [],
                },
          required_linear_history: news.requiredLinearHistory ?? false,
          allow_force_pushes: news.allowForcePushes ?? false,
          allow_deletions: news.allowDeletions ?? false,
          block_creations: news.blockCreations ?? false,
          required_conversation_resolution: news.requiredConversationResolution ?? false,
          lock_branch: news.lockBranch ?? false,
          allow_fork_syncing: news.allowForkSyncing ?? false,
        });

        // Sync — required signatures live behind dedicated endpoints that the
        // top-level PUT does not touch. Diff the observed flag against the
        // desired one and only call the API on a real change.
        const observed: ProtectionPayload = yield* Repos.getBranchProtection(branch);

        const desiredSignatures = news.requiredSignatures ?? false;
        const observedSignatures = observed.required_signatures?.enabled ?? false;
        if (desiredSignatures !== observedSignatures) {
          yield* desiredSignatures
            ? Repos.createCommitSignatureProtection(branch)
            : Repos.deleteCommitSignatureProtection(branch);
        }

        return attrsOf(news.branch, {
          ...observed,
          required_signatures: { enabled: desiredSignatures },
        });
      },
      (effect, { news }) => effect.pipe(withBaseUrl(news.baseUrl)),
    ),

    // Refresh from the live rule. A 404 means either the branch is no longer
    // protected or the branch/repository is gone — both are "missing".
    read: Effect.fn(
      function* ({ olds }) {
        return yield* Repos.getBranchProtection({
          owner: olds.owner,
          repo: olds.repository,
          branch: olds.branch,
        }).pipe(
          Effect.map((protection) => attrsOf(olds.branch, protection)),
          Effect.catchTag("NotFound", () => Effect.undefined),
        );
      },
      (effect, { olds }) => effect.pipe(withBaseUrl(olds.baseUrl)),
    ),

    // Enumerate every protected branch across the repositories the token can
    // see — protection rules are keyed by {owner, repository, branch} with no
    // account-wide list endpoint, so walk the repos like the Environment
    // provider does and fetch the rule for each protected branch.
    list: Effect.fn(function* () {
      const repos = yield* Stream.runCollect(
        Repos.listForAuthenticatedUser.items({ per_page: 100 }),
      );
      const perRepo = yield* Effect.forEach(
        repos,
        (repo) => {
          const scope = { owner: repo.owner.login, repo: repo.name };
          return Stream.runCollect(
            Repos.listBranches.items({ ...scope, protected: true, per_page: 100 }),
          ).pipe(
            Effect.flatMap((branches) =>
              Effect.forEach(branches, (branch) =>
                Repos.getBranchProtection({ ...scope, branch: branch.name }).pipe(
                  Effect.map((protection) => [attrsOf(branch.name, protection)]),
                  // Protection may be removed between the list and the get, or
                  // the branch may be governed by a ruleset only.
                  Effect.catchTag("NotFound", () => Effect.succeed([])),
                ),
              ),
            ),
            Effect.map((rules) => rules.flat()),
            // Repos without branch protection support (plan limits) or where
            // the token lacks access reject with 403/404 — skip them rather
            // than failing the whole enumeration.
            Effect.catchTag(["Forbidden", "NotFound"], () => Effect.succeed([])),
          );
        },
        { concurrency: 10 },
      );
      return perRepo.flat();
    }),

    delete: Effect.fn(
      function* ({ olds }) {
        yield* Repos.deleteBranchProtection({
          owner: olds.owner,
          repo: olds.repository,
          branch: olds.branch,
        }).pipe(
          // Already unprotected, or the branch/repository is gone.
          Effect.catchTag("NotFound", () => Effect.void),
        );
      },
      (effect, { olds }) => effect.pipe(withBaseUrl(olds.baseUrl)),
    ),
  });