sailfork / t3code-github / .repos/ alchemy-effect/ packages/ git/ src/ Api/ Pulls.ts

/**
 * The `pulls` group: pull-request lifecycle + merge (DESIGN.md §5).
 *
 * PRs are same-repo branch PRs (no cross-fork), tracking **live** branches
 * by ref name: diff and mergeability are computed on read from current ref
 * tips. Merging fast-forwards when possible; otherwise it creates a merge
 * commit iff the three-way tree merge is trivial (no path touched on both
 * sides relative to the merge base) — a conflicting PR is a typed 409, the
 * server never writes conflict markers.
 */
import * as HttpApiEndpoint from "effect/http-api/HttpApiEndpoint";
import * as HttpApiGroup from "effect/http-api/HttpApiGroup";
import * as Schema from "effect/Schema";
import {
  BranchMissing,
  MergeConflict,
  MergeResult,
  NothingToMerge,
  Oid,
  OwnerName,
  Paginated,
  Pull,
  PullDetail,
  PullExists,
  PullNotFound,
  PullStateConflict,
  ReadOnlyRepo,
  RefConflict,
  RepoName,
  RepoNotFound,
  RepoPath,
  ValidationError,
  PushDenied,
} from "./Schema.ts";

/** `(owner, repo, number)` path segments for single-PR endpoints. */
export const PullPath = Schema.Struct({
  owner: OwnerName,
  repo: RepoName,
  /** The PR number (path segment; decoded from its string form). */
  number: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
});

/**
 * Opens a PR. `base`/`head` accept short (`main`) or full
 * (`refs/heads/main`) branch names — only branches are legal (no tags).
 */
export const CreatePull = HttpApiEndpoint.post("create", "/repos/:owner/:repo/pulls", {
  params: RepoPath,
  payload: Schema.Struct({
    title: Schema.String.check(Schema.isMinLength(1)),
    body: Schema.optional(Schema.String),
    /** Target branch, short or full name. */
    base: Schema.String,
    /** Source branch, short or full name. Must differ from `base`. */
    head: Schema.String,
  }),
  success: Pull,
  error: [RepoNotFound, BranchMissing, PullExists, ValidationError],
});

/** Lists PRs, newest first. `state` defaults to `open`. Anonymous on public repos. */
export const ListPulls = HttpApiEndpoint.get("list", "/repos/:owner/:repo/pulls", {
  params: RepoPath,
  query: Schema.Struct({
    /** Filter by lifecycle state. @default open */
    state: Schema.optional(Schema.Literals(["open", "closed", "merged", "all"])),
    cursor: Schema.optional(Schema.String),
    limit: Schema.optional(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 100 }))),
  }),
  success: Paginated(Pull),
  error: [RepoNotFound],
});

/** Reads one PR with live compare fields (aheadBy/behindBy/mergeable). */
export const GetPull = HttpApiEndpoint.get("get", "/repos/:owner/:repo/pulls/:number", {
  params: PullPath,
  success: PullDetail,
  error: [RepoNotFound, PullNotFound],
});

/** Patches title/body, or closes/reopens via `state`. */
export const UpdatePull = HttpApiEndpoint.patch("update", "/repos/:owner/:repo/pulls/:number", {
  params: PullPath,
  payload: Schema.Struct({
    title: Schema.optional(Schema.String.check(Schema.isMinLength(1))),
    /** `null` clears the body. */
    body: Schema.String.pipe(Schema.NullOr, Schema.optional),
    /**
     * `closed` closes an open PR; `open` reopens a closed one. Merged
     * PRs reject both (409).
     */
    state: Schema.optional(Schema.Literals(["open", "closed"])),
  }),
  success: Pull,
  error: [RepoNotFound, PullNotFound, PullStateConflict],
});

/**
 * Merges an open PR: fast-forward when possible, else a merge commit iff
 * the three-way tree merge is trivial.
 */
export const MergePull = HttpApiEndpoint.post("merge", "/repos/:owner/:repo/pulls/:number/merge", {
  params: PullPath,
  payload: Schema.Struct({
    /**
     * Merge-commit message; defaults to
     * `Merge pull request #N from <head>`. Ignored on fast-forward.
     */
    message: Schema.optional(Schema.String),
    /**
     * Race guard: fail RefConflict if the head tip moved (force-push)
     * since the caller inspected it.
     */
    expectedHeadOid: Schema.optional(Oid),
  }),
  success: MergeResult,
  error: [
    PushDenied,
    RepoNotFound,
    PullNotFound,
    PullStateConflict,
    BranchMissing,
    NothingToMerge,
    MergeConflict,
    RefConflict,
    ReadOnlyRepo,
  ],
});

/** The `pulls` group, mounted at `/api/v1`. */
export class Pulls extends HttpApiGroup.make("pulls")
  .add(CreatePull, ListPulls, GetPull, UpdatePull, MergePull)
  .prefix("/api/v1") {}