@osdlc/typed-gh 0.7.0 → 0.9.1

package/dist/verbs.d.ts

@@ -1,66 +1,67 @@
 /**
- * The verb table — every `gh` invocation this library knows, as data.
+ * The verb table: every `gh` call this library knows, as data.
  *
- * Same shape and same reasoning as `@osdlc/typed-git`'s: a {@link GhVerb}
- * pairs the argv to run with the function that reads the result, and nothing
- * here spawns anything. That is what lets a synchronous client and an
- * asynchronous fan-out drive the same definitions without either duplicating
- * the other's parsing.
+ * It has the same shape as `@osdlc/typed-git`'s. A {@link GhVerb} pairs the
+ * argv to run with the function that reads the result, and nothing here
+ * starts a process. So the sync client, the async client and callers with
+ * their own runner all use the same definitions and the same parsing.
  *
  * `checked` marks a verb the runner throws for on a non-zero exit, with
- * stderr: every mutation, and `prDiff`, which is a read. Other queries are run
- * unchecked and `parse` folds a failure into `null`, which is the verb's
- * *soft* reading. The clients' plain door reads them through `settle` (see
- * `doors.ts`) instead: a failure throws, except where the verb declares
- * `absent` or is a `probe`.
+ * stderr. That is every mutation, and `prDiff`, which is a read. Other
+ * queries run unchecked, and `parse` turns a failure into `null`, which is
+ * what `soft` returns. The clients' methods that throw read them through
+ * `settle` (see `doors.ts`) instead. There a failure throws, except where the
+ * verb declares `absent` or is a `probe`.
  */
 import { type CommandResult } from '@osdlc/command-seam';
 import type { IssueRow, Label, PrSearchHit, PullRequest, Repository } from './types.ts';
 /** One `gh` invocation: what to run, and how to read what came back. */
 export interface GhVerb<T> {
     argv: string[];
-    /** True for every mutation and for `prDiff` — throw on a non-zero exit instead of parsing. */
+    /** True for every mutation and for `prDiff`: throw on a non-zero exit instead of parsing. */
     checked: boolean;
     /**
-     * True when the call only reads: it changes nothing on GitHub. Every query
-     * is read-only, and so is `prDiff`; every mutation is not. A caller that
+     * True when the call only reads and changes nothing on GitHub. Every query
+     * is read-only, and so is `prDiff`. No mutation is. A caller that
      * keeps an allowlist of safe calls can check this before running a verb.
      */
     readOnly: boolean;
     /** Written to the child's stdin, for a verb whose payload is too large or structured for argv. */
     input?: string | undefined;
     /**
-     * Variables to set on the child, for a target gh takes no flag for: `GH_HOST`
-     * on `gh search` and `gh repo list`.
+     * Variables to set on the child process, for a target gh has no flag for:
+     * `GH_HOST` on `gh search` and `gh repo list`.
      */
     env?: Record<string, string> | undefined;
     /**
-     * True for a read whose failure is part of its answer: `installed`,
-     * `authStatus` and `api` return what `parse` makes of any result, in every
-     * door. Other reads fail the plain door when gh exits non-zero.
+     * True for a read whose failure is part of its answer. `installed`,
+     * `authStatus` and `api` return what `parse` makes of any result, in all
+     * three call styles. Other reads throw from the plain method when gh exits
+     * non-zero.
      */
     probe?: boolean | undefined;
     /**
      * For a read of one thing: whether a non-zero result means GitHub has no such
-     * thing (`prView`, `issueView`, `repoView`). The plain door then returns what
-     * `parse` makes of it, `null`, because absence is an answer. Other non-zero
-     * results fail the call.
+     * thing (`prView`, `issueView`, `repoView`). The plain method then returns
+     * what `parse` makes of it, `null`, because a missing item is an answer.
+     * Other non-zero results fail the call.
      */
     absent?: ((result: CommandResult) => boolean) | undefined;
     parse(result: CommandResult): T;
 }
 /**
- * The repository and host a verb talks to. Both are optional: with no `repo`,
- * gh uses the repository of the clone at the client's working directory, and
- * with no `hostname`, gh's default host.
+ * The repository and host a verb talks to. Both are optional. With no `repo`,
+ * gh uses the repository of the clone at the client's working directory. With
+ * no `hostname`, it uses gh's default host.
  */
 export interface GhTarget {
     /** `owner/name`. */
     repo?: string | undefined;
     /**
      * A GitHub host: `github.com`, a GitHub Enterprise Server host such as
-     * `github.acme.com`, or a `<tenant>.ghe.com` host. Other forges are out of
-     * reach: gh speaks only GitHub's API.
+     * `github.acme.com`, or a `<tenant>.ghe.com` host. Other forges are not
+     * supported, because gh supports only GitHub's API. `''` means the same as
+     * `undefined`, so a value read from config can be passed as it is.
      */
     hostname?: string | undefined;
 }
@@ -71,35 +72,35 @@ export interface GhTarget {
  */
 export declare function checkTarget(target: GhTarget | undefined): void;
 /**
- * The cheapest useful set: enough to identify a PR and nothing more.
+ * The smallest useful set: enough to identify a PR and nothing more.
  *
- * Reach for this whenever the question is "which PR is this branch?".
- * `mergeable` and `mergeStateStatus` are absent on purpose — GitHub computes
- * them per PR on demand, so asking for them across a fan-out of branches
- * turns a cheap listing into a rate-limit incident.
+ * Use it when the question is "which PR is this branch?". `mergeable` and
+ * `mergeStateStatus` are left out on purpose. GitHub computes them per PR
+ * when asked, so asking for them across many branches can hit the rate
+ * limit.
  */
 export declare const PR_REF_FIELDS: readonly ["number", "state", "headRefName", "url"];
 /**
- * The light field set for triage: everything needed to decide what to do with
- * a PR without paying for its body, comments, reviews, or check rollup.
+ * The smaller field set for triage: enough to decide what to do with a PR,
+ * without its body, comments, reviews, or check rollup.
  *
- * `mergeable` and `mergeStateStatus` are the expensive pair — GitHub computes
- * them lazily and answers `UNKNOWN` until it has, so a cold query over many
- * PRs commonly needs a retry. `prViewSettled` on the clients does it.
+ * `mergeable` and `mergeStateStatus` are the costly pair. GitHub computes
+ * them only when asked and answers `UNKNOWN` until it has. So a first query
+ * over many PRs often needs a retry. `prViewSettled` on the clients does it.
  */
 export declare const PR_LIST_FIELDS: readonly ["number", "state", "title", "url", "isDraft", "baseRefName", "headRefName", "headRefOid", "isCrossRepository", "mergeable", "mergeStateStatus", "reviewDecision", "author", "labels", "mergedAt", "createdAt", "updatedAt"];
-/** {@link PR_LIST_FIELDS} plus the heavy ones a single PR can afford. */
+/** {@link PR_LIST_FIELDS} plus the costly fields, for a single PR. */
 export declare const PR_VIEW_FIELDS: readonly ["number", "state", "title", "url", "isDraft", "baseRefName", "headRefName", "headRefOid", "isCrossRepository", "mergeable", "mergeStateStatus", "reviewDecision", "author", "labels", "mergedAt", "createdAt", "updatedAt", "body", "comments", "reviews", "statusCheckRollup"];
 /**
  * A list query's answer: the rows, and whether `limit` cut the list short.
- * The verb asks gh for one row more than `limit`; `truncated` is true when
+ * The verb asks gh for one row more than `limit`. `truncated` is true when
  * that row came back, and `rows` holds at most `limit`.
  */
 export interface ListResult<T> {
     rows: T[];
     truncated: boolean;
 }
-/** What to narrow a listing to. Every filter is optional; none means "all open". */
+/** What to narrow a listing to. Every filter is optional. None means "all open". */
 export interface PrListOptions {
     /**
      * `owner/name` to list from, instead of the repository at the client's cwd.
@@ -112,7 +113,7 @@ export interface PrListOptions {
     /**
      * Head branch filter, exact: `task/foo` does not match `task/foo-2`. Passed
      * as gh's `--head`, and the rows are filtered again on `headRefName`. Two
-     * forks can share a branch name; ask for `headRepositoryOwner` to tell them
+     * forks can share a branch name. Ask for `headRepositoryOwner` to tell them
      * apart.
      */
     head?: string | undefined;
@@ -120,13 +121,13 @@ export interface PrListOptions {
     search?: string | undefined;
     author?: string | undefined;
     limit?: number | undefined;
-    /** Field subset; defaults to {@link PR_LIST_FIELDS}. */
+    /** Field subset. Defaults to {@link PR_LIST_FIELDS}. `number` is always requested. */
     fields?: readonly string[] | undefined;
 }
-/** `gh pr list …` — open PRs by default. `opts.repo` overrides the target's repo. */
+/** `gh pr list …`: open PRs by default. `opts.repo` overrides the target's repo. */
 export declare function prList(opts?: PrListOptions, target?: GhTarget): GhVerb<ListResult<PullRequest> | null>;
 /**
- * `gh pr view <number|branch|url> --json …` — one PR, with the heavy fields
+ * `gh pr view <number|branch|url> --json …`: one PR, with the full field set
  * by default.
  *
  * A branch is the PR whose head is that branch, as gh picks it. A URL names
@@ -137,13 +138,13 @@ export declare function prView(ref: number | string, fields?: readonly string[],
 /**
  * Open PRs whose head is exactly `branch`.
  *
- * The common shape behind "which PR is this branch?", bundling the cheap
- * field set with a small limit. More than one row comes back only when forks
+ * The usual way to ask "which PR is this branch?". It uses the smallest field
+ * set and a small limit. More than one row comes back only when forks
  * share the branch name.
  */
 export declare function openPrsForBranch(branch: string, limit?: number, target?: GhTarget): GhVerb<ListResult<PullRequest> | null>;
 /**
- * `gh pr view <n> --json body -q .body` — just the PR body. Null when gh
+ * `gh pr view <n> --json body -q .body`: just the PR body. Null when gh
  * failed. gh's `-q` output ends with a newline that is not part of the body,
  * so every trailing `\r` and `\n` is trimmed (including any that were part of
  * the body, such as the `\r\n` of a body saved with CRLF line endings).
@@ -153,13 +154,15 @@ export declare function prBody(number: number, target?: GhTarget): GhVerb<string
 export interface ApiResponse {
     /** True iff gh exited 0 and the status is below 400 (2xx, or a 304 on a conditional GET). */
     ok: boolean;
-    /** HTTP status; read off the header block under `-i`. Without `-i` it is synthesized (200 on exit 0, 0 on failure), not observed. */
+    /** HTTP status, read only when headers were requested (`etag` or `includeHeaders`, which pass `-i`). Without them it is made up from the exit code (200 on exit 0, 0 on failure). */
     status: number;
     /** The response `ETag`, when headers were requested and one came back. */
     etag: string | null;
-    /** The decoded JSON body; null when empty (e.g. a 304), unparseable, or the call failed. */
+    /** The decoded JSON body, whatever gh's exit code (on failure, GitHub's error object). Null when empty (such as a 304) or not valid JSON. */
     body: unknown;
-    /** True when a non-empty body arrived but was not valid JSON (`body` is then null). */
+    /** `body.message` when the body is an object with a string `message` (GitHub's error text), else null. */
+    message: string | null;
+    /** True when a non-empty body arrived but was not valid JSON (`body` is then null). This includes a failed call with a non-JSON body. */
     malformed: boolean;
     /** gh's stderr, trimmed. */
     stderr: string;
@@ -167,7 +170,7 @@ export interface ApiResponse {
     error?: string | undefined;
 }
 /**
- * Options for {@link api}. Both are optional; with neither, the call is a plain
+ * Options for {@link api}. All are optional. With none, the call is a plain
  * `gh api <endpoint>` and the response carries no status or ETag.
  */
 export interface ApiOptions {
@@ -178,21 +181,22 @@ export interface ApiOptions {
     /**
      * Fetch every page (`--paginate --slurp`). `body` is then the pages joined
      * into one array when every page is an array, else the list of pages.
-     * Cannot be combined with `etag` or `includeHeaders`: with `-i` gh prints
-     * a header block per page. `status` is synthesized, as without `-i`.
+     * Cannot be combined with `etag` or `includeHeaders`, because with `-i` gh
+     * prints a header block per page. `status` is made up from the exit code, as
+     * without `-i`.
      */
     paginate?: boolean | undefined;
 }
 /**
- * `gh api [-i] [-H If-None-Match: …] <endpoint>` — a GET against the REST API. `{owner}` and
+ * `gh api [-i] [-H If-None-Match: …] <endpoint>`: a GET against the REST API. `{owner}` and
  * `{repo}` placeholders in the endpoint are filled from the target's repo, or by gh from the
  * cwd's repo when the target names none.
- * Unchecked: failure is a value (`ok: false`), so a caller can tell a 304
+ * Unchecked. Failure is a value (`ok: false`), so a caller can tell a 304
  * from an outage.
  */
 export declare function api(endpoint: string, opts?: ApiOptions, target?: GhTarget): GhVerb<ApiResponse>;
 /**
- * A GraphQL variable: gh sends a string with `-f` and the rest with `-F`.
+ * A GraphQL variable. gh sends a string with `-f` and the rest with `-F`.
  *
  * @experimental
  */
@@ -206,35 +210,35 @@ export interface GraphqlOptions {
     /**
      * Follow every page (`--paginate --slurp`). The query must take
      * `$endCursor: String` and select `pageInfo { hasNextPage endCursor }` on
-     * the one connection it pages through; gh follows only that connection.
+     * the one connection it pages through. gh follows only that connection.
      */
     paginate?: boolean | undefined;
 }
 /**
- * `gh api graphql -f query=… [--paginate --slurp]` — a GraphQL query.
+ * `gh api graphql -f query=… [--paginate --slurp]`: a GraphQL query.
  *
- * Returns each page's `data`, one entry per page (one without `paginate`),
- * or null when the call failed, the output did not parse, or any page
- * carries `errors` or lacks `data`: a partial answer is no answer. Read one
+ * Returns each page's `data`, one entry per page (one without `paginate`).
+ * Returns null when the call failed, the output did not parse, or any page
+ * carries `errors` or lacks `data`. A partial answer counts as a failure. Read one
  * connection across the pages with {@link nodesAt}.
  *
  * A string variable of exactly `{owner}` or `{repo}` is filled from the
  * target's repo, or by gh from the clone. A mutation document throws
- * `RangeError`: this is a read, and changes go through `raw`.
+ * `RangeError`. This is a read, and changes go through `raw`.
  *
  * @experimental
  */
 export declare function graphql(query: string, variables?: Record<string, GraphqlVariable>, opts?: GraphqlOptions, target?: GhTarget): GhVerb<unknown[] | null>;
 /**
- * The `nodes` of one connection, joined across {@link graphql} pages: walk
- * `path` into each page and take its `nodes` array. Null when `pages` is
+ * The `nodes` of one connection, joined across {@link graphql} pages. It
+ * follows `path` into each page and takes its `nodes` array. Null when `pages` is
  * null, or any page lacks the path or a `nodes` array, so a page that came
  * back short is never read as fewer rows.
  *
  * @experimental
  */
 export declare function nodesAt(pages: unknown[] | null, path: readonly string[]): unknown[] | null;
-/** `gh --version` — the install probe. True when `gh` runs. */
+/** `gh --version`: checks that `gh` is installed. True when `gh` runs. */
 export declare function installed(): GhVerb<boolean>;
 /**
  * What `gh auth status` said: whether it passed, and its output (stderr, else the runner's
@@ -244,11 +248,11 @@ export interface AuthStatus {
     ok: boolean;
     detail: string;
 }
-/** `gh auth status [--hostname <host>]` — the credential probe, for one host when the target names it. */
+/** `gh auth status [--hostname <host>]`: checks credentials, for one host when the target names it. */
 export declare function authStatus(target?: GhTarget): GhVerb<AuthStatus>;
 /**
- * `gh label list --json name,color,description` — every label on the repo,
- * up to `limit` (default 1000; `gh`'s own default is 30).
+ * `gh label list --json name,color,description`: every label on the repo,
+ * up to `limit` (default 1000. `gh`'s own default is 30).
  */
 export declare function labelList(opts?: {
     limit?: number | undefined;
@@ -260,9 +264,9 @@ export interface IssueListOptions {
     /** The most issues to return. Defaults to 200. */
     limit?: number | undefined;
 }
-/** `gh issue list --json …` — open issues by default, optionally by label. */
+/** `gh issue list --json …`: open issues, optionally by label. */
 export declare function issueList(opts?: IssueListOptions, target?: GhTarget): GhVerb<ListResult<IssueRow> | null>;
-/** `gh issue view <n> --json …` — one issue, same field set as {@link issueList}. */
+/** `gh issue view <n> --json …`: one issue, same field set as {@link issueList}. */
 export declare function issueView(number: number, target?: GhTarget): GhVerb<IssueRow | null>;
 /** The `gh repo list`/`view --json` fields a {@link Repository} reads. */
 export declare const REPO_FIELDS: readonly ["nameWithOwner", "description", "defaultBranchRef", "visibility", "isArchived", "url"];
@@ -270,21 +274,21 @@ export declare const REPO_FIELDS: readonly ["nameWithOwner", "description", "def
 export declare const SEARCH_PR_FIELDS: readonly ["number", "title", "state", "url", "isDraft", "repository", "author", "labels", "createdAt", "updatedAt", "closedAt"];
 /** What to narrow a repository listing to. Every filter is optional. */
 export interface RepoListOptions {
-    /** True for archived repositories only, false to leave them out; both when absent. */
+    /** True for archived repositories only, false to leave them out. Both when absent. */
     archived?: boolean | undefined;
     visibility?: 'public' | 'private' | 'internal' | undefined;
     /** The most repositories to return. Defaults to 100. */
     limit?: number | undefined;
-    /** Field subset; defaults to {@link REPO_FIELDS}. `nameWithOwner` is always asked for. */
+    /** Field subset. Defaults to {@link REPO_FIELDS}. `nameWithOwner` is always asked for. */
     fields?: readonly string[] | undefined;
 }
 /**
- * `gh repo list <owner> --json …` — an owner's repositories. The host comes
- * from the target (`GH_HOST`); the target's repo is not used.
+ * `gh repo list <owner> --json …`: an owner's repositories. The host comes
+ * from the target (`GH_HOST`). The target's repo is not used.
  */
 export declare function repoList(owner: string, opts?: RepoListOptions, target?: GhTarget): GhVerb<ListResult<Repository> | null>;
 /**
- * `gh repo view [<[host/]owner/name>] --json …` — one repository: `repo`,
+ * `gh repo view [<[host/]owner/name>] --json …`: one repository. That is `repo`,
  * else the target's repo, else the clone at the client's cwd.
  */
 export declare function repoView(repo?: string | undefined, fields?: readonly string[], target?: GhTarget): GhVerb<Repository | null>;
@@ -294,17 +298,17 @@ export interface SearchPrsOptions {
     owner?: string | undefined;
     /** Only this `owner/name` repository. */
     repo?: string | undefined;
-    /** `merged` is `--merged`; `open` and `closed` are `--state`. */
+    /** `merged` is `--merged`. `open` and `closed` are `--state`. */
     state?: 'open' | 'closed' | 'merged' | undefined;
     /** The most hits to return. Defaults to 100. */
     limit?: number | undefined;
-    /** Field subset; defaults to {@link SEARCH_PR_FIELDS}. `number` is always asked for. */
+    /** Field subset. Defaults to {@link SEARCH_PR_FIELDS}. `number` is always asked for. */
     fields?: readonly string[] | undefined;
 }
 /**
- * `gh search prs [flags] -- <query>` — pull requests across repositories,
+ * `gh search prs [flags] -- <query>`: pull requests across repositories,
  * with GitHub's search syntax in `query` (it may start with `-`, as in
- * `-label:bug`). The host comes from the target (`GH_HOST`); the target's
+ * `-label:bug`). The host comes from the target (`GH_HOST`). The target's
  * repo is not used, so pass `opts.repo` or `opts.owner` to narrow.
  */
 export declare function searchPrs(query: string, opts?: SearchPrsOptions, target?: GhTarget): GhVerb<ListResult<PrSearchHit> | null>;
@@ -325,25 +329,25 @@ export interface CreatePrOptions {
  * {@link prComment} does. A line after the URL, such as a tip, is skipped.
  */
 export declare function createPr(opts: CreatePrOptions, target?: GhTarget): GhVerb<string>;
-/** `gh pr edit <n>` — retitle or rewrite the body. */
+/** `gh pr edit <n>`: change the title or the body. */
 export declare function editPr(number: number, opts: {
     title?: string | undefined;
     body?: string | undefined;
 }, target?: GhTarget): GhVerb<void>;
-/** `gh pr edit <n> --body` — rewrite just the body. */
+/** `gh pr edit <n> --body`: rewrite just the body. */
 export declare function editPrBody(number: number, body: string, target?: GhTarget): GhVerb<void>;
-/** `gh pr update-branch <n> [--rebase]` — bring the head up to date with its base. */
+/** `gh pr update-branch <n> [--rebase]`: bring the head up to date with its base. */
 export declare function prUpdateBranch(number: number, style?: 'merge' | 'rebase', target?: GhTarget): GhVerb<void>;
-/** `gh pr ready <n> [--undo]` — mark a draft PR ready for review, or (with `draft`) convert it back to a draft. */
+/** `gh pr ready <n> [--undo]`: mark a draft PR ready for review, or (with `draft`) convert it back to a draft. */
 export declare function prSetDraft(number: number, draft: boolean, target?: GhTarget): GhVerb<void>;
 /**
- * `gh api -X PATCH repos/{owner}/{repo}/issues/comments/<id> -f body=…` — rewrite one
+ * `gh api -X PATCH repos/{owner}/{repo}/issues/comments/<id> -f body=…`: rewrite one
  * conversation comment.
  *
- * `commentId` is the comment's numeric REST id, as text: the `id` that
+ * `commentId` is the comment's numeric REST id, as text. That is the `id` that
  * `gh api repos/{owner}/{repo}/issues/<n>/comments` returns. It is not the
  * GraphQL node id (such as `IC_kw…`) that `gh pr view --json comments` gives
- * in `Comment.id`; the REST path answers 404 for a node id.
+ * in `Comment.id`. The REST path answers 404 for a node id.
  *
  * Throws `RangeError` when `commentId` is not all digits, so a node id fails
  * at once and no text can change which endpoint the PATCH reaches.
@@ -355,10 +359,10 @@ export declare function issueCommentEdit(commentId: string, body: string, target
 export type PrMergeMethod = 'squash' | 'merge' | 'rebase';
 /**
  * `gh pr merge <n> --<method> --match-head-commit <sha>`. The head sha is
- * required, not optional: GitHub refuses the merge when the PR head moved
- * since the caller judged it, so a push that lands between a gate and the
- * merge can never ride in unreviewed. The branch is left alone (no
- * `--delete-branch`); deleting it is the caller's job.
+ * required. GitHub refuses the merge when the PR head moved since the caller
+ * checked it. So a push that lands between the check and the merge cannot be
+ * merged without review. The branch is left alone (no `--delete-branch`).
+ * Deleting it is the caller's job.
  */
 export declare function prMerge(number: number, opts: {
     method: PrMergeMethod;
@@ -368,15 +372,14 @@ export declare function prMerge(number: number, opts: {
 export interface ReviewThread {
     isResolved: boolean;
     isOutdated: boolean;
-    /** Login of the thread's newest comment; null when the account is gone. */
+    /** Login of the author of the thread's newest comment. Null when the account is gone. */
     lastCommentAuthor: string | null;
 }
 /**
  * A PR's review threads over GraphQL (`gh pr view --json` has no thread
- * field). Null — never `[]` — when the call failed, the payload was not the
- * expected shape, or more than 100 threads exist: a caller deciding whether a
- * PR is clear to merge must read "could not tell" differently from "no
- * threads".
+ * field). Null, never `[]`, when the call failed, the payload was not the
+ * expected shape, or more than 100 threads exist. A caller deciding whether a
+ * PR is clear to merge must tell "could not tell" from "no threads".
  */
 export declare function prReviewThreads(number: number, target?: GhTarget): GhVerb<ReviewThread[] | null>;
 /** A label to create. `color` is hex digits such as `d73a4a`. */
@@ -387,36 +390,33 @@ export interface CreateLabelOptions {
 }
 /**
  * `gh label create <name> --color <hex> --description <text> --force`.
- * `--force` makes it safe to repeat: when the label already exists, its color
+ * `--force` makes it safe to repeat. When the label already exists, its color
  * and description are set to these instead of failing.
  */
 export declare function createLabel(opts: CreateLabelOptions, target?: GhTarget): GhVerb<void>;
-/** `gh label edit <name>` — recolor or redescribe; omits a flag not given. */
+/** `gh label edit <name>`: change the color or description. A flag not given is left out. */
 export declare function editLabel(name: string, opts: {
     color?: string | undefined;
     description?: string | undefined;
 }, target?: GhTarget): GhVerb<void>;
 /**
- * `gh issue edit <n> [--remove-label <current>] --add-label <new>` — swap
- * one label for another on an issue in ONE call, so the issue is never
- * briefly unlabeled or briefly holding both labels BETWEEN the remove and the
- * add — that atomicity is real and is this one call's own guarantee. It does
- * NOT cover the window before the call: `currentLabel` is whatever the caller
- * already read (perhaps minutes earlier, from a `gh issue list` snapshot),
- * never re-read here. If the issue's live label changed since then (a human,
- * or another process, relabeled it in between), `--remove-label
- * <currentLabel>` targets a label the issue no longer carries — `gh` no-ops
- * that removal silently rather than erroring — so the call still adds
- * `newLabel`, and the issue ends up holding BOTH the label it actually has
- * now and `newLabel`. A caller that cares about that race re-reads the live
- * label immediately before calling this. `currentLabel` is `null` when the
- * issue carries no prior label to remove — the `--remove-label` flag is then
- * omitted rather than passed empty.
+ * `gh issue edit <n> [--remove-label <current>] --add-label <new>`: swap one
+ * label for another on an issue in one call. The issue is never left with
+ * neither label or both labels between the remove and the add.
+ *
+ * That covers only the call itself. `currentLabel` is whatever the caller
+ * read earlier, perhaps from a `gh issue list` minutes before. It is not read
+ * again here. If someone relabeled the issue since then, `--remove-label
+ * <currentLabel>` names a label the issue no longer has. `gh` skips that
+ * removal with no error and still adds `newLabel`. The issue then has both
+ * its current label and `newLabel`. A caller that cares reads the label again
+ * just before calling this. Pass `null` for `currentLabel` when there is no
+ * label to remove. The `--remove-label` flag is then left out.
  */
 export declare function setIssueLabel(number: number, currentLabel: string | null, newLabel: string, target?: GhTarget): GhVerb<void>;
-/** `gh pr diff <n>` — the PR's unified diff, as text. Checked: an empty diff is a value, a failed call is not. */
+/** `gh pr diff <n>`: the PR's unified diff, as text. Checked, so an empty diff is a value and a failed call throws. */
 export declare function prDiff(number: number, target?: GhTarget): GhVerb<string>;
-/** `gh pr comment <n> --body <body>` — post a conversation comment, returning the URL gh prints ('' if none). */
+/** `gh pr comment <n> --body <body>`: post a conversation comment, returning the URL gh prints ('' if none). */
 export declare function prComment(number: number, body: string, target?: GhTarget): GhVerb<string>;
 /**
  * One inline comment of a review: a line on the right (new) side of the diff.
@@ -435,7 +435,7 @@ export interface ReviewComment {
  * @experimental
  */
 export interface CreateReviewOptions {
-    /** The commit the review is anchored to; line numbers refer to the diff at this sha. */
+    /** The commit the review is on. Line numbers refer to the diff at this sha. */
     commitId: string;
     /** The review summary. GitHub rejects a review whose body and comments are both empty. */
     body: string;
@@ -443,10 +443,10 @@ export interface CreateReviewOptions {
 }
 /**
  * Create a PR review with inline comments, returning the review's URL (empty
- * when GitHub's reply carried none). The event is always `COMMENT`: this
- * library does not offer a way to approve or request changes. Goes through
+ * when GitHub's reply carried none). The event is always `COMMENT`. This
+ * library does not offer a way to approve or request changes. It goes through
  * `gh api` with the payload on stdin, because `gh pr review` cannot attach
- * line-anchored comments; `{owner}`/`{repo}` come from the target's repo, or
+ * comments to lines. `{owner}`/`{repo}` come from the target's repo, or
  * are filled in by `gh` from the client's working directory.
  *
  * @experimental
@@ -471,9 +471,9 @@ export declare function branchPrFields(fields: readonly string[]): string[];
 /**
  * True when GitHub has not finished computing this PR's mergeability.
  *
- * The answer is not stable on a cold query: GitHub kicks off the merge
- * computation when asked and answers `UNKNOWN` until it lands. A caller that
- * treats the first `UNKNOWN` as final will mis-triage a PR that is merely
- * slow, so re-ask a few times before believing it.
+ * The first answer may not be final. GitHub starts the merge computation when
+ * asked and answers `UNKNOWN` until it finishes. A caller that treats the
+ * first `UNKNOWN` as final misjudges a PR whose computation is slow. So ask a
+ * few times before trusting it.
  */
 export declare function needsMergeStateRetry(pr: PullRequest): boolean;