import { Context, Effect, Layer, Option, Schema } from "effect"; import { GitHubClient } from "./GitHubClient.js"; import { GitHubError } from "./GitHubError.js"; import type { GitHubGraphQLError } from "./GraphQL.js"; import { GraphQLDocument } from "./GraphQL.js"; import { unstubbed } from "./internal/unstubbed.js"; import { Repo } from "./Repo.js"; const CreateLinkedBranch = GraphQLDocument.make({ name: "createLinkedBranch", document: `mutation ($issueId: ID!, $name: String!, $oid: GitObjectID!, $repositoryId: ID!) { createLinkedBranch(input: { issueId: $issueId, name: $name, oid: $oid, repositoryId: $repositoryId }) { linkedBranch { id } } }`, response: Schema.Struct({}), })<{ readonly issueId: string; readonly name: string; readonly oid: string; readonly repositoryId: string; }>(); /** * What {@link GitBranchShape.upsert} did. * * @public */ export type BranchOutcome = "created" | "reset"; /** * Branch refs in GitHub's Git Database API. * * @remarks * **Not local git.** Despite the name this is `POST /repos/…/git/refs` and * friends — no subprocess, no working tree, no checkout. `@effected/git` is the * package that runs git. * * @public */ export interface GitBranchShape { /** Create a branch at `sha`. Fails `alreadyExists` when it is already there. */ readonly create: (name: string, sha: string) => Effect.Effect; /** * Point `name` at `sha`, creating it if needed. * * @remarks * **One call, one intent.** Creating a branch that may already exist needs no * `exists` check, no catch and no second attempt: this creates the ref, and * when GitHub answers `alreadyExists` it resets the ref to `sha`. It is one * round trip in the common case and two in the raced one, and the recovery * **resets** rather than inheriting a branch a concurrent creator rooted * somewhere else. The result says which happened: `"created"` or `"reset"`. * * **A reset is observable, and open pull requests react to it.** Resetting a * branch to its PR's base — `upsert(branch, targetHead)` — makes that PR's * head equal its base, and GitHub **auto-closes a PR whose diff is empty**. * The window is invisible at this call site: `upsert(releaseBranch, mainHead)` * followed a few seconds later by a commit that re-adds content can lose an * open release PR in between while the run reports success. When the end state is "the target head plus * a commit", build the commit first — `GitCommit.get` the target for its * `treeSha`, `createTree` on it, `createCommit` with the target as parent — * and upsert **once**, straight to the finished sha, so the ref never rests * on the bare target head. */ readonly upsert: (name: string, sha: string) => Effect.Effect; /** Is the branch there? A 404 is `false`, not an error. */ readonly exists: (name: string) => Effect.Effect; /** The commit the branch points at. Fails `notFound` when it does not exist. */ readonly sha: (name: string) => Effect.Effect; /** As {@link GitBranchShape.sha}, with absence as `Option.none`. */ readonly shaOption: (name: string) => Effect.Effect, GitHubError, Repo>; /** Force the branch to `sha`. Fails `notFound` when it does not exist. */ readonly reset: (name: string, sha: string) => Effect.Effect; /** Delete the branch. */ readonly delete: (name: string) => Effect.Effect; /** * Create a branch **linked to an issue**, as the GitHub UI's "create a branch" * button does. * * @remarks * The one operation in this package with **no REST equivalent** — GitHub * exposes `createLinkedBranch` only through GraphQL, which is why the document * is owned here rather than left in a consumer. A linked branch shows up on the * issue and closes it when the branch's pull request merges; a branch created * with {@link GitBranchShape.create} does neither. */ readonly createLinked: (input: { readonly issueNodeId: string; readonly repositoryNodeId: string; readonly name: string; readonly sha: string; }) => Effect.Effect; } /** * Create, move, read and delete branch refs through GitHub's Git Database API, * with an `upsert` that needs no existence check. * * @remarks * Provide it with {@link GitBranch.layer}, which needs a `GitHubClient`; each * method also needs a `Repo` in `R`. Branch names are accepted as `main`, * `heads/main` or `refs/heads/main`. * * @example * ```ts * import { GitBranch } from "@effected/github"; * import { Effect } from "effect"; * * const ensureBranch = (name: string, sha: string) => * Effect.gen(function* () { * const branches = yield* GitBranch; * return yield* branches.upsert(name, sha); // "created" | "reset" * }); * ``` * * @public */ export class GitBranch extends Context.Service()("@effected/github/GitBranch") { /** * The live service, built over a `GitHubClient`. * * @remarks * The callback is written `(client) => make(client)` rather than passed as * `make` directly, and that is load-bearing: a static initializer runs while * the module body is still evaluating, so naming a `const` declared further * down throws `Cannot access 'make' before initialization` **at import time**, * with a clean typecheck. Wrapping it in an arrow defers the read to when the * layer is built. */ static readonly layer: Layer.Layer = Layer.effect( this, Effect.map(GitHubClient, (client) => make(client)), ); /** An in-memory double; an unstubbed member dies when run, naming itself. */ static readonly makeTest = (overrides: Partial = {}): GitBranchShape => ({ create: overrides.create ?? (() => dies("create")), upsert: overrides.upsert ?? (() => dies("upsert")), exists: overrides.exists ?? (() => dies("exists")), sha: overrides.sha ?? (() => dies("sha")), shaOption: overrides.shaOption ?? (() => dies("shaOption")), reset: overrides.reset ?? (() => dies("reset")), delete: overrides.delete ?? (() => dies("delete")), createLinked: overrides.createLinked ?? (() => dies("createLinked")), }); /** {@link GitBranch.makeTest} behind a `Layer`. */ static readonly layerTest = (overrides: Partial = {}): Layer.Layer => Layer.succeed(GitBranch, GitBranch.makeTest(overrides)); } const dies = unstubbed("GitBranch.makeTest"); /** * `main`, `refs/heads/main` and `heads/main` all name the same branch. * * @remarks * GitHub's own API is inconsistent here — creation wants the full * `refs/heads/x`, every other operation wants `heads/x` — so callers routinely * pass whichever they last saw. Normalizing once is cheaper than documenting it * seven times. */ const shortName = (name: string): string => name.replace(/^refs\/heads\//, "").replace(/^heads\//, ""); const rejectEmpty = (operation: string, name: string): Effect.Effect => { const short = shortName(name).trim(); return short === "" ? Effect.fail(GitHubError.rejected(operation, 422, "a branch name is required")) : Effect.succeed(short); }; /** * Every method resolves {@link Repo} per call rather than once at layer * construction. * * @remarks * This is what makes `Repo.provide(other)` mean something. Capturing the * coordinate when the layer is built would give each method `R = never` — the * house pattern for a stable dependency — but it would also make a scoped * override silently do nothing, because the resource would already hold the * repository it was built with. The repository is precisely the dependency that * is *not* stable: one program may loop over many target repositories. * * The client stays resolved at construction, so this costs one context read per * call and nothing else. */ const make = (client: GitHubClient["Service"]): GitBranchShape => { const create = Effect.fn("GitBranch.create")(function* (branch: string, sha: string) { const { owner, repo } = yield* Repo; const short = yield* rejectEmpty("GitBranch.create", branch); yield* Effect.annotateCurrentSpan({ owner, repo, branch: short }); yield* client.request("POST /repos/{owner}/{repo}/git/refs", { owner, repo, ref: `refs/heads/${short}`, sha, }); }); const reset = Effect.fn("GitBranch.reset")(function* (branch: string, sha: string) { const { owner, repo } = yield* Repo; const short = yield* rejectEmpty("GitBranch.reset", branch); yield* Effect.annotateCurrentSpan({ owner, repo, branch: short }); yield* client.request("PATCH /repos/{owner}/{repo}/git/refs/{ref}", { owner, repo, ref: `heads/${short}`, sha, force: true, }); }); const upsert = Effect.fn("GitBranch.upsert")(function* (branch: string, sha: string) { const short = yield* rejectEmpty("GitBranch.upsert", branch); yield* Effect.annotateCurrentSpan({ branch: short }); return yield* create(short, sha).pipe( Effect.as("created"), // The whole point of a structural `alreadyExists`: a concurrent creator // is recognized by the error's shape, not by matching its prose, and the // recovery needs no second existence check to tell the cases apart. Effect.catchIf(GitHubError.hasKind("alreadyExists"), () => Effect.as(reset(short, sha), "reset" as const)), ); }); const readRef = (operation: string, branch: string) => Effect.gen(function* () { const { owner, repo } = yield* Repo; const short = yield* rejectEmpty(operation, branch); return yield* client.request("GET /repos/{owner}/{repo}/git/ref/{ref}", { owner, repo, ref: `heads/${short}`, }); }); const shaOption = Effect.fn("GitBranch.shaOption")(function* (branch: string) { yield* Effect.annotateCurrentSpan({ branch }); return yield* readRef("GitBranch.shaOption", branch).pipe( Effect.map((ref) => Option.some(ref.object.sha)), Effect.catchIf(GitHubError.hasKind("notFound"), () => Effect.succeed(Option.none())), ); }); return { create, upsert, reset, exists: Effect.fn("GitBranch.exists")(function* (branch: string) { yield* Effect.annotateCurrentSpan({ branch }); return yield* Effect.map(shaOption(branch), Option.isSome); }), sha: Effect.fn("GitBranch.sha")(function* (branch: string) { yield* Effect.annotateCurrentSpan({ branch }); const ref = yield* readRef("GitBranch.sha", branch); return ref.object.sha; }), shaOption, createLinked: Effect.fn("GitBranch.createLinked")(function* (input: { readonly issueNodeId: string; readonly repositoryNodeId: string; readonly name: string; readonly sha: string; }) { const short = shortName(input.name); yield* Effect.annotateCurrentSpan({ branch: short }); yield* client.graphql(CreateLinkedBranch, { issueId: input.issueNodeId, repositoryId: input.repositoryNodeId, name: short, oid: input.sha, }); }), delete: Effect.fn("GitBranch.delete")(function* (branch: string) { const { owner, repo } = yield* Repo; const short = yield* rejectEmpty("GitBranch.delete", branch); yield* Effect.annotateCurrentSpan({ owner, repo, branch: short }); yield* client.request("DELETE /repos/{owner}/{repo}/git/refs/{ref}", { owner, repo, ref: `heads/${short}`, }); }), }; };