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

import * as Repos from "@distilled.cloud/github/repos";
import { Unowned } from "alchemy/AdoptPolicy";
import { deepEqual, 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 RulesetProps {
  /**
   * Repository owner — a user or organization login.
   */
  owner: string;

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

  /**
   * Ruleset name. The name is displayed in the GitHub UI and can be updated.
   */
  name: string;

  /**
   * The enforcement level of the ruleset. Can be `disabled`, `active`, or
   * `evaluate` (log-only mode).
   * @default "active"
   */
  enforcement?: "disabled" | "active" | "evaluate";

  /**
   * Whether the ruleset targets branches or tags.
   * @default "branch"
   */
  target?: "branch" | "tag";

  /**
   * Conditions for targeting refs. When omitted, applies to all refs of the
   * target type.
   */
  conditions?: {
    /**
     * Ref patterns to include (e.g. `["refs/heads/main", "refs/heads/release/*"]`).
     * Supports glob patterns.
     */
    include?: string[];

    /**
     * Ref patterns to exclude (e.g. `["refs/heads/dev/*"]`).
     * Supports glob patterns.
     */
    exclude?: string[];
  };

  /**
   * Actors allowed to bypass the ruleset. Omit to allow no bypasses.
   */
  bypassActors?: Array<{
    /**
     * The type of actor that can bypass the ruleset.
     */
    actorType: "RepositoryRole" | "Team" | "Integration" | "OrganizationAdmin";

    /**
     * The ID of the actor (role ID, team ID, or integration ID).
     * RepositoryRole IDs are 2 for write, 4 for maintain, and 5 for admin.
     */
    actorId?: number;

    /**
     * Whether the actor can always bypass or only through pull requests.
     * @default "always"
     */
    bypassMode?: "always" | "pull_request";
  }>;

  /**
   * Require status checks to pass before merging.
   */
  requiredStatusChecks?: {
    /**
     * Status checks that must pass. Each entry is a context name or
     * integration ID.
     */
    checks: Array<{
      /**
       * The status check context name.
       */
      context: string;

      /**
       * Optional integration ID.
       */
      integrationId?: number;
    }>;

    /**
     * Whether to require branches to be up to date before merging.
     * @default false
     */
    strictRequiredStatusChecksPolicy?: boolean;
  };

  /**
   * Require commits to be signed.
   */
  requiredSignatures?: boolean;

  /**
   * Require pull request before merging.
   */
  pullRequest?: {
    /**
     * Number of required approving reviews.
     */
    requiredApprovingReviewCount?: number;

    /**
     * Dismiss stale reviews when new commits are pushed.
     */
    dismissStaleReviewsOnPush?: boolean;

    /**
     * Require review from code owners.
     */
    requireCodeOwnerReview?: boolean;

    /**
     * Require approval of the most recent reviewable push.
     */
    requireLastPushApproval?: boolean;

    /**
     * Required review thread resolution.
     */
    requiredReviewThreadResolution?: boolean;

    /**
     * Merge methods allowed for pull requests. GitHub allows all three when omitted.
     */
    allowedMergeMethods?: Array<"merge" | "squash" | "rebase">;

    /**
     * Require another approval for changes pushed by someone other than the commit author.
     * @default true
     */
    requireExtraApprovalForUnattributedChanges?: boolean;
  };

  /**
   * Prevent creation of matching refs.
   */
  creation?: boolean;

  /**
   * Prevent updates to matching refs.
   */
  update?: boolean;

  /**
   * Prevent deletion of matching refs.
   */
  deletion?: boolean;

  /**
   * Require linear history.
   */
  requiredLinearHistory?: boolean;

  /**
   * Prevent force pushes.
   */
  nonFastForward?: boolean;

  /**
   * Require pull requests to merge through a merge queue. Only applies to
   * branch rulesets in organization-owned repositories.
   */
  mergeQueue?: {
    /**
     * Method used to merge the queued pull requests.
     * @default "MERGE"
     */
    mergeMethod?: "MERGE" | "SQUASH" | "REBASE";

    /**
     * `ALLGREEN` requires every entry's checks to pass; `HEADGREEN` only
     * requires the checks of the group's head commit.
     * @default "ALLGREEN"
     */
    groupingStrategy?: "ALLGREEN" | "HEADGREEN";

    /**
     * Maximum number of queued pull requests building at the same time.
     * @default 5
     */
    maxEntriesToBuild?: number;

    /**
     * Minimum number of pull requests merged together in a group.
     * @default 1
     */
    minEntriesToMerge?: number;

    /**
     * Maximum number of pull requests merged together in a group.
     * @default 5
     */
    maxEntriesToMerge?: number;

    /**
     * Minutes to wait for `minEntriesToMerge` pull requests after the first
     * one is queued before merging a smaller group.
     * @default 5
     */
    minEntriesToMergeWaitMinutes?: number;

    /**
     * Minutes to wait for a required status check before treating it as failed.
     * @default 60
     */
    checkResponseTimeoutMinutes?: number;
  };

  /**
   * 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 name on a
   * different GitHub instance is a different physical resource.
   */
  baseUrl?: string;
}

/**
 * Props as persisted before the rules moved from a nested `rules` object to
 * the top level. Only previously deployed state can still have this shape.
 */
type PersistedRulesetProps = RulesetProps & {
  rules?: Pick<
    RulesetProps,
    | "requiredStatusChecks"
    | "requiredSignatures"
    | "pullRequest"
    | "creation"
    | "update"
    | "deletion"
    | "requiredLinearHistory"
    | "nonFastForward"
    | "mergeQueue"
  >;
};

/**
 * Lifts the rules of persisted props out of the legacy nested `rules` object.
 */
const upgradeProps = ({ rules, ...props }: PersistedRulesetProps): RulesetProps => ({
  ...rules,
  ...props,
});

export interface Ruleset extends Resource<
  "GitHub.Ruleset",
  RulesetProps,
  {
    /**
     * Numeric GitHub ruleset ID.
     */
    rulesetId: number;

    /**
     * GraphQL node ID of the ruleset, when returned by GitHub.
     */
    nodeId: string | undefined;

    /**
     * The ruleset name.
     */
    name: string;

    /**
     * ISO-8601 timestamp of when the ruleset was created.
     */
    createdAt: string | undefined;

    /**
     * ISO-8601 timestamp of the last update.
     */
    updatedAt: string | undefined;
  },
  never,
  GitHub.Providers
> {}

/**
 * A GitHub repository ruleset.
 *
 * `Ruleset` manages branch and tag protection rules at the repository level.
 * Rulesets replace the legacy branch protection API with a more flexible
 * system that can target multiple branches or tags with a single ruleset.
 *
 * Rulesets default to **retain** on removal — destroying the stack does NOT
 * delete the ruleset on GitHub, protecting production branches from
 * accidental removal. Opt in to actual deletion by wrapping the resource in
 * {@link destroy}() from `alchemy/RemovalPolicy`.
 *
 * Authentication is resolved via the GitHub `Credentials` service supplied by
 * `GitHub.providers()` (env, stored PAT, `gh` CLI, or OAuth). The token needs
 * `repo` scope, or repository Administration write permission for a
 * fine-grained token. Ruleset deletion does not require `delete_repo`.
 *
 * ### Creating a Ruleset
 * **Example:** Protect Main Branch
 * ```typescript
 * yield* GitHub.Ruleset("main-protection", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   name: "main protection",
 *   target: "branch",
 *   conditions: {
 *     include: ["refs/heads/main"],
 *   },
 *   nonFastForward: true,
 *   deletion: true,
 *   requiredLinearHistory: true,
 * })
 * ```
 *
 * **Example:** Require PR Reviews
 * ```typescript
 * yield* GitHub.Ruleset("pr-reviews", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   name: "require reviews",
 *   target: "branch",
 *   conditions: {
 *     include: ["refs/heads/main", "refs/heads/release/*"],
 *   },
 *   pullRequest: {
 *     requiredApprovingReviewCount: 2,
 *     requireCodeOwnerReview: true,
 *     dismissStaleReviewsOnPush: true,
 *     requiredReviewThreadResolution: true,
 *   },
 * })
 * ```
 *
 * ### Status Checks
 * **Example:** Require CI to Pass
 * ```typescript
 * yield* GitHub.Ruleset("ci-checks", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   name: "CI required",
 *   target: "branch",
 *   conditions: {
 *     include: ["refs/heads/main"],
 *   },
 *   requiredStatusChecks: {
 *     checks: [
 *       { context: "ci/test" },
 *       { context: "ci/lint" },
 *     ],
 *     strictRequiredStatusChecksPolicy: true,
 *   },
 * })
 * ```
 *
 * ### Merge Queue
 * GitHub only supports merge queues on branch rulesets in
 * organization-owned repositories.
 *
 * **Example:** Merge Through a Squash Merge Queue
 * ```typescript
 * yield* GitHub.Ruleset("merge-queue", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   name: "Merge queue",
 *   conditions: {
 *     include: ["~DEFAULT_BRANCH"],
 *   },
 *   mergeQueue: {
 *     mergeMethod: "SQUASH",
 *     groupingStrategy: "ALLGREEN",
 *     maxEntriesToBuild: 2,
 *     maxEntriesToMerge: 1,
 *     minEntriesToMergeWaitMinutes: 1,
 *   },
 * })
 * ```
 *
 * ### Bypass Actors
 * **Example:** Allow Admins to Bypass
 * ```typescript
 * yield* GitHub.Ruleset("protected-with-bypass", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   name: "protected with bypass",
 *   target: "branch",
 *   conditions: {
 *     include: ["refs/heads/main"],
 *   },
 *   bypassActors: [
 *     { actorType: "RepositoryRole", actorId: 5 },
 *   ],
 *   nonFastForward: true,
 * })
 * ```
 *
 * ### Adopting an Existing Ruleset
 * Ruleset names are unique per repository. A ruleset that already exists
 * with the same name is foreign until you opt in with `adopt(true)` or
 * `--adopt`; adoption then converges it to the declared props in place.
 *
 * **Example:** Take over a ruleset created in the GitHub UI
 * ```typescript
 * import { adopt } from "alchemy/AdoptPolicy";
 *
 * yield* GitHub.Ruleset("main-protection", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   name: "main protection",
 *   conditions: {
 *     include: ["~DEFAULT_BRANCH"],
 *   },
 *   deletion: true,
 *   nonFastForward: true,
 * }).pipe(adopt(true))
 * ```
 *
 * @resource
 * @product Repository
 */
export const Ruleset = Resource<Ruleset>("GitHub.Ruleset", {
  defaultRemovalPolicy: "retain",
});

export const RulesetProvider = () =>
  Provider.succeed(Ruleset, {
    stables: ["rulesetId", "nodeId"],

    diff: Effect.fn(function* ({ news, olds: persisted }) {
      if (!isResolved(news)) return;
      if (persisted === undefined) return;
      const olds = upgradeProps(persisted);
      if (
        news.owner !== olds.owner ||
        news.repository !== olds.repository ||
        (yield* gitHubBaseUrlChanged(olds, news))
      ) {
        return { action: "replace" };
      }
      // State persisted with nested rules declares the same ruleset as the
      // top-level rules it upgrades to.
      if ("rules" in persisted && deepEqual(olds, news, { stripNullish: true })) {
        return { action: "noop" };
      }
    }),

    reconcile: Effect.fn(
      function* ({ news, output }) {
        let observed = output === undefined ? undefined : yield* getRuleset(news, output.rulesetId);

        const rules: NonNullable<Repos.CreateRepoRulesetRequest["rules"]> = [];

        if (news.creation) {
          rules.push({ type: "creation" });
        }
        if (news.update) {
          rules.push({
            type: "update",
            parameters: { update_allows_fetch_and_merge: false },
          });
        }
        if (news.deletion) {
          rules.push({ type: "deletion" });
        }
        if (news.nonFastForward) {
          rules.push({ type: "non_fast_forward" });
        }
        if (news.requiredLinearHistory) {
          rules.push({ type: "required_linear_history" });
        }
        if (news.requiredSignatures) {
          rules.push({ type: "required_signatures" });
        }
        if (news.pullRequest) {
          const pullRequest = news.pullRequest;
          // `require_extra_approval_for_unattributed_changes` is accepted by the API but missing
          // from its OpenAPI description, so it is added outside the typed literal.
          const parameters = {
            required_approving_review_count: pullRequest.requiredApprovingReviewCount ?? 0,
            dismiss_stale_reviews_on_push: pullRequest.dismissStaleReviewsOnPush ?? false,
            require_code_owner_review: pullRequest.requireCodeOwnerReview ?? false,
            require_last_push_approval: pullRequest.requireLastPushApproval ?? false,
            required_review_thread_resolution: pullRequest.requiredReviewThreadResolution ?? false,
            ...(pullRequest.allowedMergeMethods !== undefined && {
              allowed_merge_methods: pullRequest.allowedMergeMethods,
            }),
            ...(pullRequest.requireExtraApprovalForUnattributedChanges !== undefined && {
              require_extra_approval_for_unattributed_changes:
                pullRequest.requireExtraApprovalForUnattributedChanges,
            }),
          };
          rules.push({ type: "pull_request", parameters });
        }
        if (news.mergeQueue) {
          const mergeQueue = news.mergeQueue;
          rules.push({
            type: "merge_queue",
            parameters: {
              merge_method: mergeQueue.mergeMethod ?? "MERGE",
              grouping_strategy: mergeQueue.groupingStrategy ?? "ALLGREEN",
              max_entries_to_build: mergeQueue.maxEntriesToBuild ?? 5,
              min_entries_to_merge: mergeQueue.minEntriesToMerge ?? 1,
              max_entries_to_merge: mergeQueue.maxEntriesToMerge ?? 5,
              min_entries_to_merge_wait_minutes: mergeQueue.minEntriesToMergeWaitMinutes ?? 5,
              check_response_timeout_minutes: mergeQueue.checkResponseTimeoutMinutes ?? 60,
            },
          });
        }
        if (news.requiredStatusChecks) {
          rules.push({
            type: "required_status_checks",
            parameters: {
              required_status_checks: news.requiredStatusChecks.checks.map((check) => ({
                context: check.context,
                integration_id: check.integrationId,
              })),
              strict_required_status_checks_policy:
                news.requiredStatusChecks.strictRequiredStatusChecksPolicy ?? false,
            },
          });
        }

        const conditions = {
          ref_name: {
            include: news.conditions?.include ?? ["~ALL"],
            exclude: news.conditions?.exclude ?? [],
          },
        };

        // Build the bypass actors payload
        const bypassActors = news.bypassActors?.map((actor) => ({
          actor_type: actor.actorType,
          actor_id: actor.actorId,
          bypass_mode: actor.bypassMode ?? "always",
        }));

        const desired = {
          name: news.name,
          target: news.target ?? "branch",
          enforcement: news.enforcement ?? "active",
          bypass_actors: bypassActors ?? [],
          conditions,
          rules,
        } satisfies Omit<Repos.CreateRepoRulesetRequest, "owner" | "repo">;

        if (observed === undefined) {
          observed = yield* Repos.createRepoRuleset({
            owner: news.owner,
            repo: news.repository,
            ...desired,
          });
        }

        if (
          !deepEqual(
            {
              name: observed.name,
              target: observed.target,
              enforcement: observed.enforcement,
              bypass_actors: observed.bypass_actors ?? [],
              conditions: observed.conditions,
              rules: observed.rules ?? [],
            },
            desired,
          )
        ) {
          const rulesetId = observed.id;
          observed = yield* Repos.updateRepoRuleset({
            owner: news.owner,
            repo: news.repository,
            ruleset_id: rulesetId,
            ...desired,
          });
        }

        return attrsOf(observed);
      },
      (effect, { news }) => effect.pipe(withBaseUrl(news.baseUrl)),
    ),

    read: Effect.fn(
      function* ({ olds, output }) {
        if (output !== undefined) {
          const observed = yield* getRuleset(olds, output.rulesetId);
          return observed === undefined ? undefined : attrsOf(observed);
        }
        const rulesets = yield* Stream.runCollect(
          Repos.getRepoRulesets.items({
            owner: olds.owner,
            repo: olds.repository,
            includes_parents: false,
            per_page: 100,
          }),
        ).pipe(Effect.catchTag("NotFound", () => Effect.succeed([])));
        const match = rulesets.find((ruleset) => ruleset.name === olds.name);
        if (match === undefined) return undefined;
        const observed = yield* getRuleset(olds, match.id);
        return observed === undefined ? undefined : Unowned(attrsOf(observed));
      },
      (effect, { olds }) => effect.pipe(withBaseUrl(olds.baseUrl)),
    ),

    list: Effect.fn(function* () {
      const repos = yield* Stream.runCollect(
        Repos.listForAuthenticatedUser.items({ per_page: 100 }),
      );
      const perRepo = yield* Effect.forEach(
        repos,
        (repo) =>
          Stream.runCollect(
            Repos.getRepoRulesets.items({
              owner: repo.owner.login,
              repo: repo.name,
              includes_parents: false,
              per_page: 100,
            }),
          ).pipe(
            Effect.map((rulesets) => rulesets.map(attrsOf)),
            Effect.catchTag(["Forbidden", "NotFound"], () => Effect.succeed([])),
          ),
        { concurrency: 10 },
      );
      return perRepo.flat();
    }),

    delete: Effect.fn(
      function* ({ olds, output }) {
        if (output?.rulesetId === undefined) return;
        yield* Repos.deleteRepoRuleset({
          owner: olds.owner,
          repo: olds.repository,
          ruleset_id: output.rulesetId,
        }).pipe(Effect.catchTag("NotFound", () => Effect.void));
      },
      (effect, { olds }) => effect.pipe(withBaseUrl(olds.baseUrl)),
    ),
  });

const getRuleset = Effect.fn(
  function* (props: Pick<RulesetProps, "owner" | "repository" | "baseUrl">, rulesetId: number) {
    return yield* Repos.getRepoRuleset({
      owner: props.owner,
      repo: props.repository,
      ruleset_id: rulesetId,
    }).pipe(Effect.catchTag("NotFound", () => Effect.undefined));
  },
  (effect, props) => effect.pipe(withBaseUrl(props.baseUrl)),
);

const attrsOf = (ruleset: {
  id: number;
  node_id?: string;
  name: string;
  created_at?: string;
  updated_at?: string;
}) => ({
  rulesetId: ruleset.id,
  nodeId: ruleset.node_id,
  name: ruleset.name,
  createdAt: ruleset.created_at,
  updatedAt: ruleset.updated_at,
});