@osdlc/typed-gh 0.9.0 → 0.9.2

package/dist/parse.js

@@ -1,21 +1,22 @@
 /**
- * `gh --json` payloads → the typed model.
+ * Parsers from `gh --json` payloads to the typed model.
  *
- * Everything here is pure, so an async fan-out can reuse it without going
- * near a subprocess, and so the awkward cases can be tested as data.
+ * Nothing here has side effects, so code that runs its own calls can reuse
+ * it without starting a process, and the hard cases can be tested as data.
  *
- * Two shape hazards this file exists to absorb:
+ * It handles two payload differences:
  *
- *  1. **Author logins differ by transport.** GraphQL (`gh pr view --json`)
- *     returns a suffix-less login (`github-actions`); REST (`gh api`) returns
- *     the suffixed one (`github-actions[bot]`). Comparing one against the
- *     other silently never matches, which is how bot noise gets treated as
- *     human review feedback. Logins are normalized to the suffix-less form
- *     here, once.
- *  2. **`statusCheckRollup` holds two different node types.** A modern
- *     `CheckRun` carries `name`/`status`/`conclusion`; a legacy
- *     `StatusContext` carries `context`/`state`. They are folded onto one
- *     verdict axis so a caller never has to know which it got.
+ *  1. Author logins differ between GraphQL and REST. GraphQL
+ *     (`gh pr view --json`) returns a login without a suffix
+ *     (`github-actions`). REST (`gh api`) returns the suffixed one
+ *     (`github-actions[bot]`). Comparing one with the other never matches,
+ *     and no error shows it. Then a bot's comments are treated as human
+ *     review feedback. Logins are normalized here, once, to the form without
+ *     the suffix.
+ *  2. `statusCheckRollup` holds two node types. A modern `CheckRun` carries
+ *     `name`/`status`/`conclusion`. A legacy `StatusContext` carries
+ *     `context`/`state`. Both map to one verdict, so a caller never has to
+ *     know which it got.
  */
 // ── primitives ──────────────────────────────────────────────────────────────
 function isRecord(x) {
@@ -31,8 +32,8 @@ function bool(x) {
     return x === true;
 }
 /**
- * A comment/review id: GraphQL sends a string node id, REST a numeric one —
- * stringify either. A numeric id of 2^53 or more has already lost precision
+ * A comment/review id. GraphQL sends a string node id, REST a numeric one.
+ * Either becomes a string. A numeric id of 2^53 or more has already lost precision
  * in `JSON.parse` by the time it gets here.
  */
 function idOrNull(x) {
@@ -47,15 +48,14 @@ function list(x) {
 }
 // ── actors ──────────────────────────────────────────────────────────────────
 /**
- * Strip a single trailing `[bot]` suffix — REST shape folded to GraphQL shape.
- *
- * The one normalization that makes a login from either transport comparable.
+ * Strip a single trailing `[bot]` suffix, so a REST login matches the
+ * GraphQL one.
  */
 export function normalizeAuthorLogin(login) {
     return login.endsWith('[bot]') ? login.slice(0, -'[bot]'.length) : login;
 }
 /**
- * Parse an author node from either transport (`author` or REST's `user`).
+ * Parse an author node from GraphQL (`author`) or REST (`user`).
  * Null when there is no login, or the login is empty once `[bot]` is removed.
  */
 export function parseActor(x) {
@@ -67,7 +67,7 @@ export function parseActor(x) {
         return null;
     return {
         login,
-        // `is_bot` is REST/GraphQL-dependent; the suffix is the portable signal.
+        // Only some payloads carry `is_bot`. The suffix works for both.
         isBot: bool(x['is_bot']) || raw.endsWith('[bot]'),
     };
 }
@@ -75,10 +75,9 @@ export function parseActor(x) {
 /**
  * Conclusions that mean the check failed.
  *
- * `ACTION_REQUIRED` is deliberately not here: it means a human must do
- * something, not that the build broke, and the existing consumers treat it as
- * neutral. Widening this set changes triage verdicts, so it is a decision to
- * make on purpose rather than by adding a plausible-looking member.
+ * `ACTION_REQUIRED` is not here on purpose. It means a person must do
+ * something, not that the build broke, and callers treat it as neutral.
+ * Adding a member changes every caller's verdicts, so decide it on purpose.
  */
 const FAILED_CONCLUSIONS = new Set(['FAILURE', 'TIMED_OUT', 'CANCELLED', 'STARTUP_FAILURE']);
 /** Legacy StatusContext `state` values that mean failure. */
@@ -104,12 +103,11 @@ export function parseCheckRun(x) {
         return null;
     const status = str(x['status']).toUpperCase();
     const conclusion = strOrNull(x['conclusion']);
-    // `detailsUrl` is the modern CheckRun field; `targetUrl` is the legacy
-    // StatusContext one — a raw payload occasionally carries either under a
-    // `name`-shaped node, so read both rather than assume the field follows
-    // the node-type split strictly.
+    // `detailsUrl` is the modern CheckRun field and `targetUrl` the legacy
+    // StatusContext one. A payload sometimes carries either on a node with a
+    // `name`, so read both.
     const url = strOrNull(x['detailsUrl']) ?? strOrNull(x['targetUrl']);
-    // Still running: not a pass. Reading "no failure yet" as green merges red.
+    // Still running, so not a pass. If "no failure yet" counted as green, a red build could merge.
     if (status !== '' && status !== 'COMPLETED') {
         return { name, status, conclusion, verdict: 'pending', url };
     }
@@ -127,7 +125,7 @@ export function anyCheckFailed(checks) {
     return checks.some((c) => c.verdict === 'failure');
 }
 // ── the pull request ────────────────────────────────────────────────────────
-/** Parse a `labels` field (PR, issue, or a bare `gh label list` array) into {@link Label} rows — the one label-array parse every `gh` caller shares. Skips an item with no name, or an empty-string name (indistinguishable from absent). */
+/** Parse a `labels` field (PR, issue, or a bare `gh label list` array) into {@link Label} rows. Every label list in this package goes through it. Skips an item with no name, or an empty name, which reads the same as no name. */
 export function parseLabels(x) {
     const out = [];
     for (const item of list(x)) {
@@ -170,12 +168,12 @@ function parseReviews(x) {
     }
     return out;
 }
-/** `mergeable` is tri-state; anything unrecognized (or absent) is UNKNOWN. */
+/** `mergeable` has three states. Anything unknown, or absent, is UNKNOWN. */
 function parseMergeable(x) {
     const v = str(x).toUpperCase();
     return v === 'MERGEABLE' || v === 'CONFLICTING' ? v : 'UNKNOWN';
 }
-/** gh returns `""` for "no decision yet"; the model says `null`. */
+/** gh returns `""` for "no decision yet". The model says `null`. */
 function parseReviewDecision(x) {
     const v = strOrNull(x);
     return v === 'APPROVED' || v === 'CHANGES_REQUESTED' || v === 'REVIEW_REQUIRED' ? v : null;
@@ -183,8 +181,8 @@ function parseReviewDecision(x) {
 /**
  * One PR from a `gh --json` object, or null when it carries no usable number.
  *
- * Total by construction: a field `gh` was not asked for lands at its "not
- * known" value rather than `undefined`, so the result is safe to build from
+ * Every field gets a value. A field `gh` was not asked for gets its "not
+ * known" value, not `undefined`, so the result is safe to build from
  * any field subset.
  */
 export function parsePullRequest(raw) {
@@ -257,7 +255,7 @@ export function parsePrSearchHit(raw) {
     return {
         number,
         title: str(raw['title']),
-        // Search answers in lower case; `PullRequest.state` is upper case.
+        // Search answers in lower case. `PullRequest.state` is upper case.
         state: str(raw['state']).toUpperCase(),
         url: str(raw['url']),
         isDraft: bool(raw['isDraft']),

package/dist/repo.d.ts

@@ -1,11 +1,11 @@
 /**
- * Turning a git remote into a GitHub coordinate.
+ * Reading the GitHub owner and repository from a git remote, and a pull
+ * request from a URL or what a person typed.
  *
- * This is `@osdlc/typed-git`'s `parseGitUrl` applied to the one question a
- * GitHub client always ends up asking. It lives here rather than in each
- * caller because the hand-rolled version is always a regex over
- * `remote.origin.url`, and that regex is always missing a URL shape —
- * scp-style, a trailing `.git`, an `ssh://` port, a bare `owner/repo`.
+ * `parseOwnerRepo` uses `@osdlc/typed-git`'s `parseGitUrl`. It lives here so
+ * callers do not each write a regex over `remote.origin.url`. Such a regex
+ * usually misses a URL form: scp-style, a trailing `.git`, an `ssh://` port,
+ * or a bare `owner/repo`.
  */
 import type { OwnerRepo } from './types.ts';
 /**
@@ -27,11 +27,11 @@ export interface PullRequestRef extends OwnerRepo {
  *
  * Accepts `https://<host>/<owner>/<repo>/pull/<n>` with or without a scheme,
  * a trailing slash, a sub-page (`/files`, `/commits`), a query string or a
- * fragment — every shape a browser's address bar hands over. The host is
+ * fragment, as copied from a browser's address bar. The host is
  * `github.com` (a `www.` prefix is dropped) or a GitHub Enterprise host such
- * as `github.acme.com` or `acme.ghe.com`; without a scheme the host must
- * contain a dot. `parseGitUrl` is the wrong tool here: it reads `/pull/<n>`
- * as part of the project path.
+ * as `github.acme.com` or `acme.ghe.com`. Without a scheme the host must
+ * contain a dot. `parseGitUrl` does not fit here, because it reads
+ * `/pull/<n>` as part of the project path.
  */
 export declare function parsePrUrl(url: string): PullRequestRef | null;
 /**
@@ -58,9 +58,9 @@ export type PrRef = {
  * Read what a person typed to name a pull request: a number, `#42`,
  * `owner/name#42`, a URL, or a branch name. Null when it is none of these.
  *
- * Pure: it starts no process. Digits are read as a number first, the way
- * `gh pr view 42` reads them; `orBranch` keeps the branch reading. The
- * clients' `prFind` tries both.
+ * It starts no process. Digits are read as a number first, the way
+ * `gh pr view 42` reads them. `orBranch` keeps the text for reading it as a
+ * branch. The clients' `prFind` tries both.
  */
 export declare function parsePrRef(input: string): PrRef | null;
 /** True for `owner/name` as GitHub spells it. */

package/dist/repo.js

@@ -1,11 +1,11 @@
 /**
- * Turning a git remote into a GitHub coordinate.
+ * Reading the GitHub owner and repository from a git remote, and a pull
+ * request from a URL or what a person typed.
  *
- * This is `@osdlc/typed-git`'s `parseGitUrl` applied to the one question a
- * GitHub client always ends up asking. It lives here rather than in each
- * caller because the hand-rolled version is always a regex over
- * `remote.origin.url`, and that regex is always missing a URL shape —
- * scp-style, a trailing `.git`, an `ssh://` port, a bare `owner/repo`.
+ * `parseOwnerRepo` uses `@osdlc/typed-git`'s `parseGitUrl`. It lives here so
+ * callers do not each write a regex over `remote.origin.url`. Such a regex
+ * usually misses a URL form: scp-style, a trailing `.git`, an `ssh://` port,
+ * or a bare `owner/repo`.
  */
 import { parseGitUrl } from '@osdlc/typed-git';
 /**
@@ -31,11 +31,11 @@ export function ownerRepoSlug(r) {
  *
  * Accepts `https://<host>/<owner>/<repo>/pull/<n>` with or without a scheme,
  * a trailing slash, a sub-page (`/files`, `/commits`), a query string or a
- * fragment — every shape a browser's address bar hands over. The host is
+ * fragment, as copied from a browser's address bar. The host is
  * `github.com` (a `www.` prefix is dropped) or a GitHub Enterprise host such
- * as `github.acme.com` or `acme.ghe.com`; without a scheme the host must
- * contain a dot. `parseGitUrl` is the wrong tool here: it reads `/pull/<n>`
- * as part of the project path.
+ * as `github.acme.com` or `acme.ghe.com`. Without a scheme the host must
+ * contain a dot. `parseGitUrl` does not fit here, because it reads
+ * `/pull/<n>` as part of the project path.
  */
 export function parsePrUrl(url) {
     const m = /^(?:(https?:)\/\/)?([a-z0-9](?:[a-z0-9.-]*[a-z0-9])?(?::\d+)?)\/([^/\s]+)\/([^/\s]+)\/pull\/(\d+)(?:[/?#].*)?$/i.exec(url.trim());
@@ -58,9 +58,9 @@ export function parsePrUrl(url) {
  * Read what a person typed to name a pull request: a number, `#42`,
  * `owner/name#42`, a URL, or a branch name. Null when it is none of these.
  *
- * Pure: it starts no process. Digits are read as a number first, the way
- * `gh pr view 42` reads them; `orBranch` keeps the branch reading. The
- * clients' `prFind` tries both.
+ * It starts no process. Digits are read as a number first, the way
+ * `gh pr view 42` reads them. `orBranch` keeps the text for reading it as a
+ * branch. The clients' `prFind` tries both.
  */
 export function parsePrRef(input) {
     const text = input.trim();

package/dist/run.d.ts

@@ -1,12 +1,12 @@
 /**
- * `runVerb` and `runVerbAsync` — run one {@link GhVerb} through a runner the
+ * `runVerb` and `runVerbAsync` run one {@link GhVerb} through a runner the
  * caller owns, with everything the verb asks for applied.
  *
  * A verb carries more than `argv`: `input` (a payload on stdin), `env` (the
  * target host as `GH_HOST`), and `checked` (whether a non-zero exit throws).
- * `verb.parse(await runner.run(verb.argv))` drops the first two without a
- * word, so a query goes to github.com and a review is never sent. These two
- * apply all of it, as `Gh` and `AsyncGh` do; both clients call them.
+ * `verb.parse(await runner.run(verb.argv))` drops the first two with no
+ * error, so a query goes to github.com and a review is never sent. These two
+ * functions apply all of it. `Gh` and `AsyncGh` call them too.
  */
 import type { AsyncCommandRunner, CommandRunner } from '@osdlc/command-seam';
 import type { GhVerb } from './verbs.ts';
@@ -18,20 +18,19 @@ export interface RunVerbOptions {
 }
 /** {@link RunVerbOptions} for {@link runVerbAsync}, with the abort signal. */
 export interface RunVerbAsyncOptions extends RunVerbOptions {
-    /** Aborts the call; the runner stops the child. */
+    /** Aborts the call. The runner stops the child process. */
     signal?: AbortSignal | undefined;
 }
 /**
- * Run `verb` through `runner` and return its parsed value, honouring the
- * verb's `input`, `env`, `timeoutMs` and `checked`, and its checked or
- * unchecked contract: a failed `gh` throws a `FailureError` carrying the
- * classified `GhFailure`, output that cannot be read throws one of kind
- * `unreadable`, and a query for one thing answers `null` when GitHub says
- * there is no such thing.
+ * Run `verb` through `runner` and return its parsed value. It applies the
+ * verb's `input`, `env` and `checked`, and the `timeoutMs` option. A failed
+ * `gh` throws a `FailureError` carrying the classified `GhFailure`. Output
+ * that cannot be read throws one of kind `unreadable`. A query for one thing
+ * returns `null` when GitHub says there is no such thing.
  *
- * A plain `(binary, argv, opts) => result` function is not a runner: wrap it
+ * A plain `(binary, argv, opts) => result` function is not a runner. Wrap it
  * as `{ run: (argv, opts) => fn('gh', argv, opts) }`.
  */
 export declare function runVerb<T>(verb: GhVerb<T>, runner: CommandRunner, opts: RunVerbOptions): T;
-/** {@link runVerb} for an `AsyncCommandRunner`; rejects where that throws. */
+/** {@link runVerb} for an `AsyncCommandRunner`. It rejects where `runVerb` throws. */
 export declare function runVerbAsync<T>(verb: GhVerb<T>, runner: AsyncCommandRunner, opts: RunVerbAsyncOptions): Promise<T>;

package/dist/run.js

@@ -1,23 +1,22 @@
 /**
- * `runVerb` and `runVerbAsync` — run one {@link GhVerb} through a runner the
+ * `runVerb` and `runVerbAsync` run one {@link GhVerb} through a runner the
  * caller owns, with everything the verb asks for applied.
  *
  * A verb carries more than `argv`: `input` (a payload on stdin), `env` (the
  * target host as `GH_HOST`), and `checked` (whether a non-zero exit throws).
- * `verb.parse(await runner.run(verb.argv))` drops the first two without a
- * word, so a query goes to github.com and a review is never sent. These two
- * apply all of it, as `Gh` and `AsyncGh` do; both clients call them.
+ * `verb.parse(await runner.run(verb.argv))` drops the first two with no
+ * error, so a query goes to github.com and a review is never sent. These two
+ * functions apply all of it. `Gh` and `AsyncGh` call them too.
  */
 import { runCheckedGh, runCheckedGhAsync, settle } from "./doors.js";
 /**
- * Run `verb` through `runner` and return its parsed value, honouring the
- * verb's `input`, `env`, `timeoutMs` and `checked`, and its checked or
- * unchecked contract: a failed `gh` throws a `FailureError` carrying the
- * classified `GhFailure`, output that cannot be read throws one of kind
- * `unreadable`, and a query for one thing answers `null` when GitHub says
- * there is no such thing.
+ * Run `verb` through `runner` and return its parsed value. It applies the
+ * verb's `input`, `env` and `checked`, and the `timeoutMs` option. A failed
+ * `gh` throws a `FailureError` carrying the classified `GhFailure`. Output
+ * that cannot be read throws one of kind `unreadable`. A query for one thing
+ * returns `null` when GitHub says there is no such thing.
  *
- * A plain `(binary, argv, opts) => result` function is not a runner: wrap it
+ * A plain `(binary, argv, opts) => result` function is not a runner. Wrap it
  * as `{ run: (argv, opts) => fn('gh', argv, opts) }`.
  */
 export function runVerb(verb, runner, opts) {
@@ -31,7 +30,7 @@ export function runVerb(verb, runner, opts) {
     const result = verb.checked ? runCheckedGh(runner, verb.argv, run) : runner.run(verb.argv, run);
     return settle(verb, result, runner.binary);
 }
-/** {@link runVerb} for an `AsyncCommandRunner`; rejects where that throws. */
+/** {@link runVerb} for an `AsyncCommandRunner`. It rejects where `runVerb` throws. */
 export async function runVerbAsync(verb, runner, opts) {
     const run = { cwd: opts.cwd };
     if (verb.input !== undefined)

package/dist/sync.d.ts

@@ -1,18 +1,19 @@
 /**
- * `Gh` — the synchronous GitHub client, the companion of `@osdlc/typed-git`'s
+ * `Gh`: the synchronous GitHub client, the companion of `@osdlc/typed-git`'s
  * `Git`, bound to one working directory and one {@link CommandRunner}.
  *
- * Authentication is `gh`'s, not ours: no token is read, stored, or passed.
- * That is the whole reason this shells out to the CLI instead of speaking
- * REST — the credential already exists in the user's keychain, and a library
- * that reaches for `GITHUB_TOKEN` is a library that can leak one.
+ * `gh` handles authentication. No token is read, stored, or passed. That is
+ * why this runs the CLI instead of calling the REST API. The credential is
+ * already in the user's keychain. A library that reads `GITHUB_TOKEN` can
+ * leak it.
  *
- * The same three doors as the git client. The plain method returns a value
- * or throws: a failed `gh` throws a `FailureError` carrying the classified
- * `GhFailure`, output that cannot be read throws one of kind `unreadable`, and a query for one thing (`prView`, `issueView`,
- * `repoView`) answers `null` when GitHub says there is no such thing.
- * `gh.try.*` returns the failure as a `Result<T, GhFailure>`; `gh.soft.*` returns
- * `null` for it. `raw`/`rawChecked` are the escape hatches.
+ * It has the same three call styles as the git client. The plain method
+ * returns a value or throws. A failed `gh` throws a `FailureError` carrying
+ * the classified `GhFailure`. Output that cannot be read throws one of kind
+ * `unreadable`. A query for one thing (`prView`, `issueView`, `repoView`)
+ * returns `null` when GitHub says there is no such thing. `gh.try.*` returns
+ * the failure as a `Result<T, GhFailure>`. `gh.soft.*` returns `null` for it.
+ * `raw` and `rawChecked` run any `gh` call.
  */
 import { type CommandResult, type CommandRunner } from '@osdlc/command-seam';
 import { type Soft, type TriedSync } from './doors.ts';
@@ -20,12 +21,12 @@ import * as v from './verbs.ts';
 import type { ApiOptions, ApiResponse, AuthStatus, GhTarget, IssueListOptions, ListResult, PrListOptions } from './verbs.ts';
 import type { IssueRow, Label, OwnerRepo, PrSearchHit, PullRequest, Repository } from './types.ts';
 /**
- * Factory of per-binary runners — the injectable subprocess seam a CLI tail
- * threads through its call graph. Production uses `spawnRunner`; tests supply
- * a recording factory so a whole tail runs offline.
+ * Makes a runner for a binary. A CLI passes one factory to every place that
+ * runs a command. Real code uses `spawnRunner`. Tests pass a factory that
+ * records calls, so the CLI runs offline.
  */
 export type RunnerFactory = (binary: string) => CommandRunner;
-/** Default factory: real, spawnSync-backed runners. */
+/** The default factory: real runners that use `spawnSync`. */
 export declare const defaultRunnerFactory: RunnerFactory;
 /** What a client is built with: the runner, and the repository and host it talks to. */
 export interface GhOptions extends GhTarget {
@@ -60,50 +61,52 @@ export declare class Gh {
     withRepo(repo: string): Gh;
     /**
      * The whole surface again, returning a `Result<T, GhFailure>` instead of
-     * throwing: `gh.try.prList()` is `{ ok: true, value } | { ok: false, error }`.
+     * throwing. `gh.try.prList()` is `{ ok: true, value } | { ok: false, error }`.
      * A query for one thing that finds nothing is `ok: true` with `null`. See
      * `./doors.ts`.
      *
-     * The type leaves out the escape hatches and the pure helpers; at runtime
-     * the proxy wraps `raw` and `rawChecked` too. Call those on the client itself.
+     * The type leaves out `raw`, `rawChecked` and the helpers that run nothing.
+     * At runtime the proxy wraps `raw` and `rawChecked` too. Call those on the
+     * client itself.
      */
     get try(): TriedSync<Gh>;
     /**
      * Each query again, returning `null` instead of throwing when `gh` fails. A
-     * mutation has no soft form. Do not gate a write on a `null` from `soft`:
-     * it is the answer for "could not ask" as well as for "nothing there". Use
+     * mutation has no soft form. Do not decide a write on a `null` from `soft`.
+     * It is the answer for "could not ask" as well as for "nothing there". Use
      * `try` where the difference matters.
      */
     get soft(): Soft<Gh>;
-    /** Unchecked passthrough for verbs not yet lifted into the API. */
+    /** Run any `gh` call and return the result, whatever the exit code. */
     raw(argv: string[], opts?: {
         timeoutMs?: number | undefined;
     }): CommandResult;
-    /** Checked passthrough — throws the classified failure on a non-zero exit. */
+    /** Run any `gh` call. Throws the classified failure on a non-zero exit. */
     rawChecked(argv: string[], opts?: {
         timeoutMs?: number | undefined;
     }): CommandResult;
-    /** Run one verb from the table, honouring its checked/unchecked contract. */
+    /** Run one verb from the table, checked or unchecked as the verb says. */
     private exec;
-    /** {@link exec} for a verb that never answers `null` as a value: a failed or unreadable run throws. */
+    /** {@link exec} for a verb that never returns `null` as a value. A failed or unreadable run throws. */
     private read;
-    /** Pull requests matching `opts`. Throws when gh fails; `soft.prList` gives null instead. */
+    /** Pull requests matching `opts`. Throws when gh fails. `soft.prList` gives null instead. */
     prList(opts?: PrListOptions & {
         timeoutMs?: number | undefined;
     }): ListResult<PullRequest>;
     /**
-     * One PR by number, branch or URL, with the heavy fields; null when there is
-     * no such PR. Throws when gh fails otherwise.
+     * One PR by number, branch or URL, with the full field set. Null when there
+     * is no such PR. Throws when gh fails otherwise.
      */
     prView(ref: number | string, opts?: {
         fields?: readonly string[] | undefined;
         timeoutMs?: number | undefined;
     }): PullRequest | null;
     /**
-     * The one PR that `input` names, or null: what a person typed, such as `42`,
-     * `#42`, `owner/name#42`, a URL or a branch (read by `parsePrRef`).
+     * The one PR that `input` names, or null. `input` is what a person typed,
+     * such as `42`, `#42`, `owner/name#42`, a URL or a branch (read by
+     * `parsePrRef`).
      *
-     * Digits are a PR number first; when no such PR comes back, they are tried
+     * Digits are a PR number first. When no such PR comes back, they are tried
      * as a branch. A branch gives its open PR, or else its newest closed or
      * merged one, so a tool run after the merge still finds it. Fields default
      * to {@link PR_LIST_FIELDS}.
@@ -115,28 +118,26 @@ export declare class Gh {
     /**
      * The open PR whose head exactly equals `branch`, or null.
      *
-     * Defaults to {@link PR_REF_FIELDS}: identifying a PR must not cost a
-     * merge-state computation. Pass `opts.fields` to ask for more (e.g.
-     * `isDraft`) in the SAME call, when a caller needs a field beyond identity
-     * before deciding whether to act on the PR at all — asking `prList`/`prView`
-     * separately would cost a second round trip for the common case where the
-     * caller already knows it wants that field up front.
+     * Defaults to {@link PR_REF_FIELDS}, so finding a PR does not make GitHub
+     * compute the merge state. Pass `opts.fields` to ask for more (such as
+     * `isDraft`) in the same call. That saves a second `prList` or `prView`
+     * call when the caller already knows it needs the field.
      */
     openPrFor(branch: string, opts?: {
         limit?: number | undefined;
         fields?: readonly string[] | undefined;
     }): PullRequest | null;
     /**
-     * {@link prView}, re-asked until GitHub settles the merge state.
+     * {@link prView}, asked again until GitHub has computed the merge state.
      *
-     * GitHub computes mergeability lazily: the first query kicks it off and
-     * answers `UNKNOWN` while it runs. A caller that believes that first answer
-     * mis-triages every PR that is merely slow to compute, so this re-asks
-     * `attempts` times before returning what it has. The last answer is
-     * returned whether or not it settled — `UNKNOWN` is a legitimate final
-     * verdict and callers must still handle it.
+     * GitHub computes mergeability only when asked. The first query starts it
+     * and answers `UNKNOWN` while it runs. A caller that trusts that first
+     * answer misjudges every PR whose computation is slow. So this asks up to
+     * `attempts` times while the answer is `UNKNOWN`. The last answer is
+     * returned either way. `UNKNOWN` can be the final answer, and callers must
+     * still handle it.
      *
-     * `sleep` is injected so a test does not spend real seconds waiting.
+     * `sleep` is an option so a test does not spend real seconds waiting.
      */
     prViewSettled(number: number, opts?: {
         attempts?: number | undefined;
@@ -149,15 +150,15 @@ export declare class Gh {
         timeoutMs?: number | undefined;
     }): string;
     /**
-     * A REST GET through `gh api`. Never throws for a failed call, in any door:
-     * failure is `ok: false` on the returned {@link ApiResponse}.
+     * A REST GET through `gh api`. Never throws for a failed call, in any call
+     * style. Failure is `ok: false` on the returned {@link ApiResponse}.
      */
     api(endpoint: string, opts?: ApiOptions & {
         timeoutMs?: number | undefined;
     }): ApiResponse;
     /**
-     * A GraphQL query; each page's `data`. Throws on a failed or partial result;
-     * `soft.graphql` gives null. See the `graphql` verb.
+     * A GraphQL query. Returns each page's `data`. Throws on a failed or partial
+     * result. `soft.graphql` gives null. See the `graphql` verb.
      *
      * @experimental
      */
@@ -173,7 +174,7 @@ export declare class Gh {
     issueList(opts?: IssueListOptions & {
         timeoutMs?: number | undefined;
     }): ListResult<IssueRow>;
-    /** One issue with its labels; null when there is no such issue. Throws when gh fails otherwise. */
+    /** One issue with its labels, or null when there is no such issue. Throws when gh fails otherwise. */
     issueView(number: number, opts?: {
         timeoutMs?: number | undefined;
     }): IssueRow | null;
@@ -193,25 +194,26 @@ export declare class Gh {
     /** True iff the `gh` binary is on PATH and runs. */
     installed(): boolean;
     /**
-     * True iff `gh` holds credentials. Asked on its own only by a caller that
-     * reports the two halves separately — "gh is missing" and "gh is not logged
-     * in" are different things to tell a person, and a report that collapses
-     * them sends someone to install software they already have.
+     * True iff `gh` holds credentials. Call it on its own to report the two
+     * checks separately. "gh is missing" and "gh is not logged in" need
+     * different fixes. A report that merges them sends someone to install
+     * software they already have.
      */
     authenticated(): boolean;
-    /** Login state and what `gh auth status` printed; `authenticated()` is its `ok`. */
+    /** Login state and what `gh auth status` printed. `authenticated()` is its `ok`. */
     authStatus(): AuthStatus;
     /**
-     * True iff `gh` is installed AND authenticated — the two-step probe.
+     * True iff `gh` is installed and authenticated.
      *
-     * Short-circuits: an absent binary cannot be asked about credentials.
+     * Skips the auth check when `gh` is not installed, since there is nothing to
+     * ask.
      */
     ready(): boolean;
     /**
      * `{owner, repo}` parsed from the remote URL you pass, or null when it is
      * null or names no project.
      *
-     * Pure: it reads no git config, starts no process and does not ask GitHub.
+     * It reads no git config, starts no process and does not ask GitHub.
      */
     ownerRepo(remoteUrl: string | null): OwnerRepo | null;
     /** Open a PR and return its URL ('' if gh printed none). */
@@ -221,12 +223,12 @@ export declare class Gh {
         title?: string | undefined;
         body?: string | undefined;
     }): void;
-    /** The PR's unified diff; throws the classified failure when gh cannot produce it. */
+    /** The PR's unified diff. Throws the classified failure when gh cannot produce it. */
     prDiff(number: number): string;
-    /** Post one conversation comment on a PR; returns its URL ('' if gh printed none). */
+    /** Post one conversation comment on a PR. Returns its URL ('' if gh printed none). */
     prComment(number: number, body: string): string;
     /**
-     * Create a `COMMENT` review with inline comments; returns the review's URL ('' if none came back).
+     * Create a `COMMENT` review with inline comments. Returns the review's URL ('' if none came back).
      *
      * @experimental
      */
@@ -238,12 +240,12 @@ export declare class Gh {
     /** Mark a PR ready for review (`draft: false`) or convert it to a draft (`draft: true`). */
     prSetDraft(number: number, draft: boolean): void;
     /**
-     * Rewrite one PR conversation comment's body. `commentId` is the numeric REST id; anything else throws `RangeError`.
+     * Rewrite one PR conversation comment's body. `commentId` is the numeric REST id. Anything else throws `RangeError`.
      *
      * @experimental
      */
     issueCommentEdit(commentId: string, body: string): void;
-    /** Merge a PR; GitHub refuses when its head is no longer `opts.headSha`. */
+    /** Merge a PR. GitHub refuses when its head is no longer `opts.headSha`. */
     prMerge(number: number, opts: {
         method: v.PrMergeMethod;
         headSha: string;
@@ -259,8 +261,8 @@ export declare class Gh {
     }): void;
     /**
      * Swap an issue's label: remove `currentLabel` (when given) and add
-     * `newLabel`, in a single `gh issue edit` call — never a briefly-unlabeled
-     * or briefly-double-labeled intermediate state.
+     * `newLabel`, in a single `gh issue edit` call. The issue is never left
+     * with neither label or both labels in between.
      */
     setIssueLabel(number: number, currentLabel: string | null, newLabel: string): void;
 }