@effected/github 0.14.0 → 0.15.1

package/GitHubRepository.js

@@ -10,10 +10,7 @@ import { Context, Effect, Layer, Schema } from "effect";
 *
 * @remarks
 * The supported spelling for "apply only what was configured" — the natural
-* shape for a sync action, and the one the checker cannot follow on its own.
-* Without it a consumer under the recommended tsconfig is quietly pushed toward
-* `as`, which is a real cost in a package whose stated design property is that
-* the route is the key and there are no casts.
+* shape for a sync action, without a cast at the call site.
 *
 * Dropping the key rather than sending `undefined` is what the wire needs:
 * `PATCH` treats an absent field as "leave it alone", while an explicit `null`
@@ -74,12 +71,9 @@ const SECURITY_ANALYSIS_STATUS_FIELDS = /* @__PURE__ */ new Set([
 * `PATCH /repos/{owner}/{repo}` route accepts none of them, and
 * `has_discussions` is the treacherous one: the REST **read** returns it, so
 * routing its write to the PATCH looks symmetric, but the PATCH silently
-* ignores unknown body fields and answers 200 — reported as applied on every
-* run while the repository never changed (effected#358). Setting any of these
-* forces a second round trip to learn the repository's node id.
-*
-* Field names verified against `UpdateRepositoryInput` by live introspection,
-* 2026-08-15.
+* ignores unknown body fields and answers 200, so the write would look applied
+* while the repository never changed. Setting any of these forces a second
+* round trip to learn the repository's node id.
 *
 * @public
 */
@@ -175,11 +169,31 @@ const preparePatch = (patch) => {
 	return out;
 };
 /**
-* Repository settings and coordinates.
+* Read and update a repository's settings, including settings only GraphQL can
+* write, and look up its default branch, node id and owner type.
+*
+* @remarks
+* Provide it with {@link GitHubRepository.layer}, which needs a `GitHubClient`;
+* every member also needs a `Repo` in `R`. `settings`, `defaultBranch`, `nodeId`
+* and `ownerType` are `Effect` values, not functions.
+*
+* @example
+* ```ts
+* import { GitHubRepository } from "@effected/github";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const repository = yield* GitHubRepository;
+*   const branch = yield* repository.defaultBranch;
+*   const applied = yield* repository.applySettings({ has_wiki: false, has_discussions: true });
+*   return { branch, applied }; // applied.rest, applied.graphql
+* });
+* ```
 *
 * @public
 */
 var GitHubRepository = class GitHubRepository extends Context.Service()("@effected/github/GitHubRepository") {
+	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
 	/** An in-memory double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({

package/GitTag.js

@@ -39,11 +39,29 @@ const versionFromTag = (tag) => {
 	return stripped === "" ? Option.none() : Option.some(stripped);
 };
 /**
-* Tags.
+* Create, move, resolve, list and delete tag refs through GitHub's Git Database
+* API, and find the newest version-shaped tag.
+*
+* @remarks
+* Provide it with {@link GitTag.layer}, which needs a `GitHubClient`; each
+* method also needs a `Repo` in `R`.
+*
+* @example
+* ```ts
+* import { GitTag } from "@effected/github";
+* import { Effect, Option } from "effect";
+*
+* const latest = Effect.gen(function* () {
+*   const tags = yield* GitTag;
+*   const newest = yield* tags.latestSemver({ prefix: "v" });
+*   return Option.map(newest, (tag) => tag.version.toString());
+* });
+* ```
 *
 * @public
 */
 var GitTag = class GitTag extends Context.Service()("@effected/github/GitTag") {
+	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
 	/** An in-memory double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({

package/GraphQL.js

@@ -19,7 +19,7 @@ var GraphQLErrorEntry = class extends Schema.Class("GraphQLErrorEntry")({
 * @remarks
 * Separate from `GitHubError` because GraphQL genuinely answers differently:
 * a 200 response can still carry failures, and it carries a **list** of them.
-* `errors` is the one structured field a surveyed consumer actually read.
+* `errors` carries every entry GitHub reported, in order.
 *
 * @public
 */
@@ -29,9 +29,8 @@ var GitHubGraphQLError = class GitHubGraphQLError extends Schema.TaggedError()("
 	*
 	* @remarks
 	* `"alreadyExists"` exists here for the same reason it exists on the REST
-	* error: without it a consumer lowercases the message and greps it for
-	* `"already"` and `"exists"`, which is exactly what one surveyed repo did to
-	* make project creation idempotent.
+	* error: it lets a caller make a create idempotent without lowercasing the
+	* message and grepping it.
 	*/
 	kind: Schema.Literals([
 		"alreadyExists",
@@ -131,25 +130,29 @@ const classify = (status, entries, reason, retryAfterMillis) => {
 *
 * @remarks
 * This is the mechanism that makes `client.graphql` return a **domain value**
-* rather than an `unknown` the caller casts. The package this replaces took a
-* query string and a caller-chosen type parameter with nothing connecting them,
-* so every consumer wrote its own response interface and hoped.
+* rather than an `unknown` the caller casts: the response schema ties the
+* query to its decoded type.
 *
-* The kit owns the documents its resources need; a consumer with a domain of
-* its own — silk-sync-action's ProjectV2 work, for instance — builds its own
-* `GraphQLDocument` and gets the same typing and the same error taxonomy
-* without this package having to know about its schema.
+* This package owns the documents its resource services need; a consumer with a
+* domain of its own (GitHub Projects, say) builds its own `GraphQLDocument` and
+* gets the same typing and the same error taxonomy.
 *
 * @example
 * ```ts
-* import { GraphQLDocument } from "@effected/github";
-* import { Schema } from "effect";
+* import { GitHubClient, GraphQLDocument } from "@effected/github";
+* import { Effect, Schema } from "effect";
 *
-* const ViewerLogin = GraphQLDocument.make({
-*   name: "viewerLogin",
-*   document: `query { viewer { login } }`,
-*   response: Schema.Struct({ viewer: Schema.Struct({ login: Schema.String }) }),
-* })<{ readonly login: string }>();
+* const OwnerLogin = GraphQLDocument.make({
+*   name: "ownerLogin",
+*   document: `query ($owner: String!) { repositoryOwner(login: $owner) { login } }`,
+*   response: Schema.Struct({ repositoryOwner: Schema.NullOr(Schema.Struct({ login: Schema.String })) }),
+* })<{ readonly owner: string }>();
+*
+* const login = Effect.gen(function* () {
+*   const client = yield* GitHubClient;
+*   const data = yield* client.graphql(OwnerLogin, { owner: "effect-ts" });
+*   return data.repositoryOwner?.login;
+* });
 * ```
 *
 * @public

package/PullRequest.js

@@ -18,13 +18,9 @@ const MergeMethod = Schema.Literals([
 *
 * @remarks
 * This is the **domain** shape, and the only pull-request type this package
-* exports. The wire shape GitHub actually answers with is the private
-* `RawPull` interface further down this module, and the two are deliberately
-* different: `RawPull` nests `head`/`base` as `{ ref, sha }` and spells the
-* link `html_url`, where this class flattens them to `head`/`headSha` and
-* spells it `url`. Reading the wrong one produces code that typechecks against
-* a member set the boundary will never hand it. If you are writing a test
-* double or a fixture, this is the type you build.
+* exports. It flattens GitHub's nested `head`/`base` objects to
+* `head`/`headSha` and `base`/`baseSha`, and spells the link `url`. If you are
+* writing a test double or a fixture, this is the type you build.
 *
 * @public
 */
@@ -85,11 +81,34 @@ const GRAPHQL_MERGE_METHOD = {
 	rebase: "REBASE"
 };
 /**
-* Pull requests.
+* Read, list, create, update, merge and label pull requests, and control
+* auto-merge.
+*
+* @remarks
+* Provide it with {@link PullRequest.layer}, which needs a `GitHubClient`; each
+* method also needs a `Repo` in `R`.
+*
+* @example
+* ```ts
+* import { PullRequest } from "@effected/github";
+* import { Effect } from "effect";
+*
+* const openOrUpdate = Effect.gen(function* () {
+*   const pulls = yield* PullRequest;
+*   const { pullRequest, created } = yield* pulls.upsert({
+*     title: "chore: release",
+*     head: "changeset-release/main",
+*     base: "main",
+*   });
+*   yield* pulls.setAutoMerge(pullRequest, "squash");
+*   return created;
+* });
+* ```
 *
 * @public
 */
 var PullRequest = class PullRequest extends Context.Service()("@effected/github/PullRequest") {
+	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
 	/** An in-memory double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({

package/PullRequestComment.js

@@ -8,11 +8,9 @@ import { Context, Effect, Layer, Option, Schema } from "effect";
 * The hidden marker that makes a comment findable again.
 *
 * @remarks
-* A pure class, not a hardcoded string. The surface this replaces baked
-* `<!-- savvy-web:${key} -->` into the library — one vendor's name, inside a
-* package meant to be general. Here the namespace is the caller's, the marker is
-* testable without a client, and the library has no opinion about whose comments
-* these are.
+* The marker is `<!-- namespace:key -->`, an HTML comment appended to the body.
+* The namespace is the caller's, so the library has no opinion about whose
+* comments these are, and a marker is testable without a client.
 *
 * @public
 */
@@ -32,7 +30,7 @@ var CommentMarker = class extends Schema.Class("CommentMarker")({
 	}
 };
 /**
-* A comment this package wrote or found.
+* A comment this package wrote or found: its id, body and web URL.
 *
 * @public
 */
@@ -42,11 +40,31 @@ var CommentRecord = class extends Schema.Class("CommentRecord")({
 	url: Schema.String
 }) {};
 /**
-* Sticky comments.
+* Post, update, find and delete comments on a pull request or issue, including
+* a "sticky" comment kept current through a `CommentMarker`.
+*
+* @remarks
+* Provide it with {@link PullRequestComment.layer}, which needs a `GitHubClient`;
+* each method also needs a `Repo` in `R`.
+*
+* @example
+* ```ts
+* import { CommentMarker, PullRequestComment } from "@effected/github";
+* import { Effect } from "effect";
+*
+* const marker = CommentMarker.make({ namespace: "my-action", key: "report" });
+*
+* const report = (pullNumber: number, body: string) =>
+*   Effect.gen(function* () {
+*     const comments = yield* PullRequestComment;
+*     return yield* comments.upsert(pullNumber, marker, body); // edits the marked comment in place
+*   });
+* ```
 *
 * @public
 */
 var PullRequestComment = class PullRequestComment extends Context.Service()("@effected/github/PullRequestComment") {
+	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
 	/** An in-memory double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({

package/README.md

@@ -7,10 +7,10 @@
 
 Typed GitHub REST and GraphQL for [Effect](https://effect.website) v4. `client.request("GET /repos/{owner}/{repo}", { owner, repo })` types both the parameters and the returned `data` from the route literal alone — no `operation: string`, no callback, no cast. One `GitHubError` covers every REST failure with a `kind` you branch on instead of grepping a message, one pagination engine backs every paginating route and `client.request`'s `Stream` form, and a set of resource services (`GitBranch`, `GitTag`, `CheckRun`, `PullRequest`, `PullRequestComment`, `GitHubRelease`, `Attestation`) turn multi-call dances — "does this branch already exist?", "conclude this check run no matter how the program exits" — into one call. A second tier writes the configuration half: secrets, variables, rulesets, deployment environments, the security toggles and CodeQL default setup. `GitHubApp` mints and revokes installation tokens for App auth.
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered
@@ -287,7 +287,7 @@ const TestClient = GitHubClient.layerFixture(fixtures);
 // A route with no entry above DIES naming itself, rather than failing typed.
 ```
 
-- **An unstubbed route dies by default.** A missing fixture is test wiring rather than a domain outcome, and a typed failure is only loud in code that does not catch — a program handling `GitHubError` per resource turns a missing stub into a different execution path, and the assertions then fail for reasons that name no fixture. `unstubbed: "fail"` restores the old typed not-found, and `"empty"` serves an empty value for a suite whose subject is decisions rather than endpoints.
+- **An unstubbed route dies by default.** A missing fixture is test wiring rather than a domain outcome, and a typed failure is only loud in code that does not catch — a program handling `GitHubError` per resource turns a missing stub into a different execution path, and the assertions then fail for reasons that name no fixture. `unstubbed: "fail"` fails the route with a typed not-found instead, and `"empty"` serves an empty value for a suite whose subject is decisions rather than endpoints.
 - **A recorded `GitHubError` value is the response.** That is how a suite stubs a 404, a 422 or a rate limit deliberately. Leaning on a route's absence says only "unwired"; a recorded error says which route fails and why.
 - **`fixtures.requested` records every call.** Each `RecordedCall` carries the `kind` of surface used, the `route` (the document name for `graphql`), the `params` the call was made with, and `perPage` for a paginated read. Params are what let a test assert what a method *sent*, which is the question any normalising write turns on.
 

package/Repo.js

@@ -56,33 +56,26 @@ var RepoRef = class RepoRef extends Schema.Class("RepoRef")({
 * `{ owner, repo }` argument**, which is what makes a read like
 * `GitHubRepository.defaultBranch` a single expression instead of a preamble.
 *
-* The package this replaces read `process.env.GITHUB_REPOSITORY` in three
-* places — inside the client, inside the App layer, and transitively in every
-* caller of `client.repo` — which is most of what coupled a GitHub API client to
-* the GitHub Actions runtime. Here the coordinate is a value, the env-driven way
-* to get one is a layer variant **named for being env-driven**, and a program
-* that acts on several repositories uses {@link Repo.provide}:
+* The coordinate is a plain value. The only env-driven way to get one is
+* {@link Repo.layerFromConfig}, which is named for being env-driven, and a
+* program that acts on several repositories uses {@link Repo.provide}.
+*
+* The service shape is entirely one immutable value (a `RepoRef`), with no
+* methods, so `Layer.succeed` is the correct test double.
 *
 * @example
 * ```ts
-* import { Repo } from "@effected/github";
+* import { Repo, RepoRef } from "@effected/github";
 * import { Effect } from "effect";
 *
 * declare const syncOne: Effect.Effect<void, never, Repo>;
-* declare const targets: ReadonlyArray<Repo["Service"]>;
+* declare const targets: ReadonlyArray<RepoRef>;
 *
 * const syncAll = Effect.forEach(targets, (target) => syncOne.pipe(Repo.provide(target)), {
 *   concurrency: 4,
 * });
 * ```
 *
-* **A deliberate exception to "no non-effectful members on a service shape."**
-* This shape is entirely one immutable value: there is nothing to leave
-* unimplemented, so `Layer.mock` has nothing to degrade and `Layer.succeed` is
-* the correct double. The rule exists to stop a sync member from quietly
-* degrading a *mixed* shape's partial mock. The boundary to hold: the moment a
-* method appears here, this is a service again and the rule applies.
-*
 * @public
 */
 var Repo = class Repo extends Context.Service()("@effected/github/Repo") {

package/RepositorySecret.js

@@ -26,7 +26,8 @@ const ROUTES = {
 	}
 };
 /**
-* Secrets, encrypted client-side before they leave the process.
+* Write, list and delete repository and environment secrets, encrypted
+* client-side before they leave the process.
 *
 * @remarks
 * Every write is a **two-step**: fetch the store's public key, then `PUT` a
@@ -42,10 +43,27 @@ const ROUTES = {
 * the type; this module performs the single `Redacted.value` unwrap, at the
 * moment of encryption, and the sealed box is what continues.
 *
+* Provide it with {@link RepositorySecret.layer}, which needs a `GitHubClient`;
+* each method also needs a `Repo` in `R`.
+*
+* @example
+* ```ts
+* import { RepositorySecret } from "@effected/github";
+* import { Effect, Redacted } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const secrets = yield* RepositorySecret;
+*   yield* secrets.set("NPM_TOKEN", Redacted.make("npm_example"), "actions");
+*   return yield* secrets.list("actions"); // names only; values are never returned
+* });
+* ```
+*
 * @public
 */
 var RepositorySecret = class RepositorySecret extends Context.Service()("@effected/github/RepositorySecret") {
 	/**
+	* The live service, built over a `GitHubClient`.
+	*
 	* @remarks
 	* `(client) => make(client)` rather than `make`: a static initializer runs
 	* while the module body is still evaluating, so naming a `const` declared

package/RepositorySecurity.js

@@ -4,7 +4,8 @@ import { Context, Effect, Layer } from "effect";
 
 //#region src/RepositorySecurity.ts
 /**
-* Repository security features with dedicated endpoints.
+* Read and toggle Dependabot alerts, Dependabot security fixes and private
+* vulnerability reporting.
 *
 * @remarks
 * These are **not** `security_and_analysis` fields and cannot ride along on the
@@ -27,10 +28,28 @@ import { Context, Effect, Layer } from "effect";
 * every other failure still fails. A 404 from the other two is a real failure
 * and stays one, which is why the mapping is not applied uniformly.
 *
+* Provide it with {@link RepositorySecurity.layer}, which needs a
+* `GitHubClient`; each method also needs a `Repo` in `R`.
+*
+* @example
+* ```ts
+* import { RepositorySecurity } from "@effected/github";
+* import { Effect } from "effect";
+*
+* const harden = Effect.gen(function* () {
+*   const security = yield* RepositorySecurity;
+*   yield* security.setVulnerabilityAlerts(true);
+*   yield* security.setPrivateVulnerabilityReporting(true);
+*   return yield* security.vulnerabilityAlerts(); // true
+* });
+* ```
+*
 * @public
 */
 var RepositorySecurity = class RepositorySecurity extends Context.Service()("@effected/github/RepositorySecurity") {
 	/**
+	* The live service, built over a `GitHubClient`.
+	*
 	* @remarks
 	* `(client) => make(client)` rather than `make`: a static initializer runs
 	* while the module body is still evaluating, so naming a `const` declared

package/RepositoryVariable.js

@@ -4,7 +4,8 @@ import { Context, Effect, Layer } from "effect";
 
 //#region src/RepositoryVariable.ts
 /**
-* Repository and environment variables.
+* Create or update, list and delete Actions variables on a repository and on
+* its environments.
 *
 * @remarks
 * No encryption and no public key, unlike secrets — but also **no upsert**,
@@ -12,10 +13,27 @@ import { Context, Effect, Layer } from "effect";
 * the create and update routes are different endpoints with different verbs and
 * neither tolerates the other's case.
 *
+* Provide it with {@link RepositoryVariable.layer}, which needs a
+* `GitHubClient`; each method also needs a `Repo` in `R`.
+*
+* @example
+* ```ts
+* import { RepositoryVariable } from "@effected/github";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const variables = yield* RepositoryVariable;
+*   yield* variables.set("DEPLOY_REGION", "eu-west-1"); // creates or updates
+*   return yield* variables.list();
+* });
+* ```
+*
 * @public
 */
 var RepositoryVariable = class RepositoryVariable extends Context.Service()("@effected/github/RepositoryVariable") {
 	/**
+	* The live service, built over a `GitHubClient`.
+	*
 	* @remarks
 	* `(client) => make(client)` rather than `make`: a static initializer runs
 	* while the module body is still evaluating, so naming a `const` declared

package/Resilience.js

@@ -10,11 +10,8 @@ import { Duration, Effect, Random, Schedule, Schema } from "effect";
 * one. Read it through the client's `rateLimit` member when you want to pace
 * yourself — **nothing in this package throttles on your behalf.**
 *
-* The package this replaces coupled the writer and the reader through an
-* optional shared `Ref` service that both resolved with `Effect.serviceOption`,
-* so an application that forgot to provide it got two private cells and a
-* silently dead feature. Here the cell lives inside the client layer that writes
-* it, and this is the only way to read it.
+* The cell lives inside the client layer that writes it, so there is nothing
+* extra to provide: reading it through the client is the only way.
 *
 * @public
 */
@@ -40,15 +37,22 @@ var RateLimitSnapshot = class extends Schema.Class("RateLimitSnapshot")({
 *
 * @remarks
 * There is exactly **one** retry policy in this package, and it is wired into
-* the client so every resource inherits it and no resource carries its own. The
-* package this replaces shipped four mutually inconsistent policies — a
-* hand-rolled recursive loop, a second exported `Schedule` that ignored
-* server-advised delays, a per-operation branch retry layered on top of the
-* client's, and a rate-limiter retry with no predicate at all, which cheerfully
-* retried permission denials — and consumers added two more on top.
+* the client so every resource inherits it and no resource carries its own.
 *
-* Only failures that report `retryable` are retried, which for `GitHubError` means a transport failure or a rate limit. A 404, a
-* validation rejection and an authorization failure fail on the first attempt.
+* Only failures that report `retryable` are retried, which for `GitHubError`
+* means a transport failure or a rate limit. A 404, a validation rejection and
+* an authorization failure fail on the first attempt.
+*
+* @example
+* ```ts
+* import { GitHubClient, RetryPolicy } from "@effected/github";
+* import { Duration, Redacted } from "effect";
+*
+* const layer = GitHubClient.layerFromToken({
+*   token: Redacted.make("ghp_example"),
+*   retry: RetryPolicy.make({ ...RetryPolicy.default, maxRetries: 2, maxDelay: Duration.seconds(10) }),
+* });
+* ```
 *
 * @public
 */
@@ -133,9 +137,7 @@ var RetryPolicy = class RetryPolicy extends Schema.Class("RetryPolicy")({
 	* Built on `Schedule.modifyDelay`, whose callback receives the schedule's
 	* `Metadata` — including the **input that failed**. That is what makes a
 	* header-driven policy expressible as a `Schedule` at all: the delay is a
-	* function of the error, not only of the attempt number. Not knowing this was
-	* available is why the package this replaces hand-rolled a recursive retry
-	* loop instead of using `Effect.retry`.
+	* function of the error, not only of the attempt number.
 	*/
 	schedule() {
 		return Schedule.forever.pipe(Schedule.modifyDelay(({ input, attempt }) => Effect.map(Random.next, (random) => this.delayFor(input, attempt, random))), Schedule.while(({ input, attempt }) => attempt <= this.maxRetries && this.retries(input)));

package/Rest.js

@@ -5,10 +5,8 @@ import { Schema } from "effect";
 * How far a paginated read should go.
 *
 * @remarks
-* Both fields are honored by every paginating method in this package. The
-* package it replaces accepted them on the client and then passed `{}` at six
-* of its eight call sites, so callers silently got 100-item pages and an
-* unbounded walk with no way to say otherwise.
+* Both fields are honored by every paginating method in this package. Unset,
+* a read requests 100-item pages and walks until GitHub stops.
 *
 * `perPage` is **validated, not clamped**: GitHub caps a page at 100 and
 * silently ignores anything larger, so a caller asking for 250 has a bug whose

package/Ruleset.js

@@ -5,7 +5,8 @@ import { Context, Effect, Layer } from "effect";
 
 //#region src/Ruleset.ts
 /**
-* Repository rulesets.
+* Create or update, list and delete repository rulesets, and look up the team
+* and role ids their bypass actors need.
 *
 * @remarks
 * ## An inherited ruleset is never written to
@@ -17,14 +18,34 @@ import { Context, Effect, Layer } from "effect";
 * that never mentioned the organization.
 *
 * {@link RulesetShape.upsert} filters on `source_type` before matching, so an
-* inherited ruleset can never be the target of a write. This arrived as a fix
-* for a live defect in the consumer this module was ported from, where the
-* filter was absent.
+* inherited ruleset can never be the target of a write.
+*
+* Provide it with {@link Ruleset.layer}, which needs a `GitHubClient`; each
+* method also needs a `Repo` in `R`.
+*
+* @example
+* ```ts
+* import { Ruleset } from "@effected/github";
+* import { Effect } from "effect";
+*
+* const protectMain = Effect.gen(function* () {
+*   const rulesets = yield* Ruleset;
+*   yield* rulesets.upsert({
+*     name: "protect-main",
+*     target: "branch",
+*     enforcement: "active",
+*     conditions: { ref_name: { include: ["~DEFAULT_BRANCH"], exclude: [] } },
+*     rules: [{ type: "deletion" }],
+*   });
+* });
+* ```
 *
 * @public
 */
 var Ruleset = class Ruleset extends Context.Service()("@effected/github/Ruleset") {
 	/**
+	* The live service, built over a `GitHubClient`.
+	*
 	* @remarks
 	* `(client) => make(client)` rather than `make`: a static initializer runs
 	* while the module body is still evaluating, so naming a `const` declared

package/TokenPermissions.js

@@ -36,7 +36,9 @@ var PermissionGap = class extends Schema.Class("PermissionGap")({
 * @public
 */
 var ExtraPermission = class extends Schema.Class("ExtraPermission")({
+	/** The permission's name, e.g. `"contents"`. */
 	permission: Schema.String,
+	/** What the token has. */
 	granted: PermissionLevel,
 	/** What was asked for, when anything was. */
 	required: Schema.optionalKey(PermissionLevel)
@@ -80,17 +82,12 @@ var TokenPermissionError = class extends Schema.TaggedError()("TokenPermissionEr
 * The permissions a token was granted, and what they satisfy.
 *
 * @remarks
-* **A pure class, not a service.** The version this replaces was a
-* `Context.Service` whose live layer was a `Layer.succeed` with zero octokit
-* calls and an empty `R` — a `read < write < admin` comparator behind a service
-* boundary that bought nothing. It cost something, though: its test double
-* reimplemented the entire ranking and every assertion branch, making it the
-* heaviest of the thirty-eight doubles in the package.
-*
-* Here there is no service, no layer and no double: a caller holds the
-* permissions GitHub already gave it (`InstallationToken.permissions`) and
-* compares them. The only `Effect`s are the two assertions, and they exist only
-* because failing typed is more useful than returning a boolean.
+* **A pure class, not a service.** It compares permission levels
+* (`read < write < admin`), so there is no layer and no test double: a caller
+* holds the permissions GitHub already gave it (`InstallationToken.permissions`)
+* and compares them. The only `Effect`s are the two assertions, which fail with
+* `TokenPermissionError` because failing typed is more useful than returning a
+* boolean.
 *
 * @example
 * ```ts