@osdlc/typed-gh 0.9.0 → 0.9.2

package/dist/verbs.js

@@ -1,28 +1,39 @@
 /**
- * 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 { stderrOrError } from '@osdlc/command-seam';
 import { parseLabels, parsePrSearchHit, parsePullRequest, parseRepository } from "./parse.js";
 import { isAbsent } from "./failure.js";
 import { isRepoSlug, parsePrUrl } from "./repo.js";
-/** Whether a failed run says GitHub has no such `thing`: read from the same text the classifier reads. */
+/** Whether a failed run says GitHub has no such `thing`. Reads the same text the classifier reads. */
 function noSuch(thing) {
     return (r) => isAbsent(thing, `${r.stderr}\n${r.stdout}`);
 }
+/**
+ * A bare host, with an optional port: letters, digits, dots and hyphens, that
+ * starts and ends with a letter or digit, then optionally `:` and digits
+ * (`github.com`, `ghe.acme.com`, `localhost:8080`). No scheme, path, spaces or
+ * leading `-`, so the value cannot be read by gh as a flag or a URL. It does
+ * not check that the host exists or that its labels are well formed, and it
+ * does not accept IPv6 literals.
+ */
 const HOSTNAME = /^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?(?::\d+)?$/;
+/** The target's host, or `undefined` when it has none. `''` is "not set". */
+function hostOf(target) {
+    return target?.hostname === '' ? undefined : target?.hostname;
+}
 /**
  * Throw `RangeError` unless `target.repo` is `owner/name` and
  * `target.hostname` is a bare host. Run by every verb that uses a target, so
@@ -32,11 +43,12 @@ export function checkTarget(target) {
     if (target?.repo !== undefined && !isRepoSlug(target.repo)) {
         throw new RangeError(`repo must be owner/name, got ${JSON.stringify(target.repo)}`);
     }
-    if (target?.hostname !== undefined && !HOSTNAME.test(target.hostname)) {
-        throw new RangeError(`hostname must be a bare host, got ${JSON.stringify(target.hostname)}`);
+    const hostname = hostOf(target);
+    if (hostname !== undefined && !HOSTNAME.test(hostname)) {
+        throw new RangeError(`hostname must be a bare host, got ${JSON.stringify(hostname)}`);
     }
 }
-/** `--repo [host/]owner/name` for `pr`, `issue` and `label` verbs; `repo` overrides the target's. */
+/** `--repo [host/]owner/name` for `pr`, `issue` and `label` verbs. `repo` overrides the target's. */
 function repoArgs(target, repo) {
     checkTarget(target);
     const slug = repo ?? target?.repo;
@@ -44,17 +56,20 @@ function repoArgs(target, repo) {
         return [];
     if (repo !== undefined)
         checkTarget({ repo });
-    return ['--repo', target?.hostname === undefined ? slug : `${target.hostname}/${slug}`];
+    const hostname = hostOf(target);
+    return ['--repo', hostname === undefined ? slug : `${hostname}/${slug}`];
 }
 /** `--hostname <host>` for `api` and `auth` verbs. */
 function hostArgs(target) {
     checkTarget(target);
-    return target?.hostname === undefined ? [] : ['--hostname', target.hostname];
+    const hostname = hostOf(target);
+    return hostname === undefined ? [] : ['--hostname', hostname];
 }
 /** `GH_HOST` for the verbs gh gives no host flag. */
 function hostEnv(target) {
     checkTarget(target);
-    return target?.hostname === undefined ? undefined : { GH_HOST: target.hostname };
+    const hostname = hostOf(target);
+    return hostname === undefined ? undefined : { GH_HOST: hostname };
 }
 /**
  * `endpoint` with `{owner}` and `{repo}` filled from the target. With no
@@ -68,21 +83,21 @@ function fillRepo(endpoint, target) {
     return endpoint.replaceAll('{owner}', owner).replaceAll('{repo}', name);
 }
 /**
- * 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 const PR_REF_FIELDS = ['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 const PR_LIST_FIELDS = [
     'number',
@@ -103,7 +118,7 @@ export const PR_LIST_FIELDS = [
     '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 const PR_VIEW_FIELDS = [
     ...PR_LIST_FIELDS,
     'body',
@@ -125,8 +140,8 @@ function oneOrNull(r) {
     return parsePullRequest(data);
 }
 /**
- * Parse a `--json` payload that is an array. Null — not `[]` — when the call
- * failed: a caller must be able to tell "no PRs" from "couldn't ask".
+ * Parse a `--json` payload that is an array. Null, not `[]`, when the call
+ * failed. A caller must be able to tell "no PRs" from "couldn't ask".
  */
 function manyOrNull(r) {
     if (r.exitCode !== 0)
@@ -163,10 +178,9 @@ function limited(rows, limit) {
 /** A mutation's result carries no value. */
 function nothing() { }
 /**
- * Parse a `gh label list --json name,color,description` payload. Null — not
- * `[]` — when the call failed, same "no rows" vs. "couldn't ask" split as
- * {@link manyOrNull}: a repo with genuinely zero labels and a `gh` call that
- * never ran must not collapse onto the same value.
+ * Parse a `gh label list --json name,color,description` payload. Null, not
+ * `[]`, when the call failed, as in {@link manyOrNull}. A repo with no labels
+ * and a `gh` call that never ran must not give the same value.
  */
 function manyLabelsOrNull(r) {
     if (r.exitCode !== 0)
@@ -182,7 +196,7 @@ function manyLabelsOrNull(r) {
         return null;
     return parseLabels(data);
 }
-/** The `gh issue list`/`view --json` field set the `issues` surface needs. */
+/** The `gh issue list`/`view --json` field set an {@link IssueRow} reads. */
 const ISSUE_FIELDS = 'number,title,body,labels,state';
 /** Parse one `gh issue list`/`view --json` row into an {@link IssueRow}. */
 function parseIssueRow(data) {
@@ -214,9 +228,8 @@ function oneIssueOrNull(r) {
     return parseIssueRow(data);
 }
 /**
- * Parse a `gh issue list --json` payload that is an array. Null — not `[]` —
- * on failure, the same "no rows" vs. "couldn't ask" split {@link manyOrNull}
- * makes for PRs.
+ * Parse a `gh issue list --json` payload that is an array. Null, not `[]`,
+ * on failure, as {@link manyOrNull} does for PRs.
  */
 function manyIssuesOrNull(r) {
     if (r.exitCode !== 0)
@@ -238,7 +251,7 @@ function manyIssuesOrNull(r) {
     }
     return rows;
 }
-/** `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 function prList(opts = {}, target) {
     const limit = opts.limit ?? 100;
     checkLimit(limit);
@@ -251,8 +264,8 @@ export function prList(opts = {}, target) {
         argv.push('--search', opts.search);
     if (opts.author !== undefined)
         argv.push('--author', opts.author);
-    // A row without `number` does not parse and is dropped, so always ask for it;
-    // the exact-head filter below also reads `headRefName`.
+    // A row without `number` does not parse and is dropped, so always ask for it.
+    // The exact-head filter below also reads `headRefName`.
     const asked = withFields(opts.fields ?? PR_LIST_FIELDS, [
         'number',
         ...(opts.head === undefined ? [] : ['headRefName']),
@@ -286,7 +299,7 @@ function notAFlag(what, value) {
     }
 }
 /**
- * `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
@@ -318,15 +331,15 @@ export function prView(ref, fields = PR_VIEW_FIELDS, target) {
 /**
  * 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 function openPrsForBranch(branch, limit = 5, target) {
     return prList({ head: branch, limit, fields: PR_REF_FIELDS }, target);
 }
 /**
- * `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).
@@ -340,10 +353,10 @@ export function prBody(number, target) {
     };
 }
 /**
- * `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 function api(endpoint, opts = {}, target) {
@@ -380,16 +393,16 @@ function flattenPages(body) {
     return body.flat();
 }
 /**
- * `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
  */
@@ -458,8 +471,8 @@ export function graphql(query, variables = {}, opts = {}, target) {
     };
 }
 /**
- * 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.
  *
@@ -485,7 +498,7 @@ export function nodesAt(pages, path) {
     }
     return out;
 }
-/** One header block off the front of `text`: the block, and what follows its blank line. */
+/** Split one header block off the front of `text`: the block, and what follows its blank line. */
 function takeHeaderBlock(text) {
     const crlf = text.indexOf('\r\n\r\n');
     const lf = text.indexOf('\n\n');
@@ -498,7 +511,7 @@ function takeHeaderBlock(text) {
 const STATUS_LINE = /^HTTP\/[\d.]+\s+\d{3}/i;
 /**
  * Split a `gh api -i` payload (status line + headers, blank line, body) and decode it.
- * A real `gh` prints one block. As a guard, if several are stacked, the last one is read:
+ * A real `gh` prints one block. If there are several, the last one is read:
  * its status and ETag, and the body that follows it.
  */
 function parseApi(r, withHeaders) {
@@ -542,7 +555,7 @@ function parseApi(r, withHeaders) {
         ...(r.error === undefined ? {} : { error: r.error }),
     };
 }
-/** `gh --version` — the install probe. True when `gh` runs. */
+/** `gh --version`: checks that `gh` is installed. True when `gh` runs. */
 export function installed() {
     return {
         argv: ['--version'],
@@ -552,7 +565,7 @@ export function installed() {
         parse: (r) => r.exitCode === 0,
     };
 }
-/** `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 function authStatus(target) {
     return {
         argv: ['auth', 'status', ...hostArgs(target)],
@@ -563,8 +576,8 @@ export function authStatus(target) {
     };
 }
 /**
- * `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 function labelList(opts = {}, target) {
     const limit = opts.limit ?? 1000;
@@ -584,7 +597,7 @@ export function labelList(opts = {}, target) {
         parse: (r) => limited(manyLabelsOrNull(r), limit),
     };
 }
-/** `gh issue list --json …` — open issues by default, optionally by label. */
+/** `gh issue list --json …`: open issues, optionally by label. */
 export function issueList(opts = {}, target) {
     const limit = opts.limit ?? 200;
     checkLimit(limit);
@@ -594,7 +607,7 @@ export function issueList(opts = {}, target) {
     argv.push('--json', ISSUE_FIELDS, '--limit', String(limit + 1));
     return { argv, checked: false, readOnly: true, parse: (r) => limited(manyIssuesOrNull(r), limit) };
 }
-/** `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 function issueView(number, target) {
     return {
         argv: ['issue', 'view', String(number), ...repoArgs(target), '--json', ISSUE_FIELDS],
@@ -643,8 +656,8 @@ function rowsOrNull(r, parse) {
     return data.map(parse).filter((row) => row !== null);
 }
 /**
- * `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 function repoList(owner, opts = {}, target) {
     notAFlag('repoList owner', owner);
@@ -668,7 +681,7 @@ export function repoList(owner, opts = {}, target) {
     };
 }
 /**
- * `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 function repoView(repo, fields = REPO_FIELDS, target) {
@@ -699,9 +712,9 @@ export function repoView(repo, fields = REPO_FIELDS, target) {
     };
 }
 /**
- * `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 function searchPrs(query, opts = {}, target) {
@@ -755,7 +768,7 @@ export function createPr(opts, target) {
         },
     };
 }
-/** `gh pr edit <n>` — retitle or rewrite the body. */
+/** `gh pr edit <n>`: change the title or the body. */
 export function editPr(number, opts, target) {
     const argv = ['pr', 'edit', String(number), ...repoArgs(target)];
     if (opts.title !== undefined)
@@ -764,18 +777,18 @@ export function editPr(number, opts, target) {
         argv.push('--body', opts.body);
     return { argv, checked: true, readOnly: false, parse: nothing };
 }
-/** `gh pr edit <n> --body` — rewrite just the body. */
+/** `gh pr edit <n> --body`: rewrite just the body. */
 export function editPrBody(number, body, target) {
     return editPr(number, { body }, target);
 }
-/** `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 function prUpdateBranch(number, style = 'merge', target) {
     const argv = ['pr', 'update-branch', String(number), ...repoArgs(target)];
     if (style === 'rebase')
         argv.push('--rebase');
     return { argv, checked: true, readOnly: false, parse: nothing };
 }
-/** `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 function prSetDraft(number, draft, target) {
     const argv = ['pr', 'ready', String(number), ...repoArgs(target)];
     if (draft)
@@ -783,13 +796,13 @@ export function prSetDraft(number, draft, target) {
     return { argv, checked: true, readOnly: false, parse: nothing };
 }
 /**
- * `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.
@@ -817,10 +830,10 @@ export function issueCommentEdit(commentId, body, target) {
 }
 /**
  * `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 function prMerge(number, opts, target) {
     const argv = [
@@ -837,14 +850,13 @@ export function prMerge(number, opts, target) {
 const REVIEW_THREADS_QUERY = 'query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){reviewThreads(first:100){pageInfo{hasNextPage} nodes{isResolved isOutdated comments(last:1){nodes{author{login}}}}}}}}';
 /**
  * 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 function prReviewThreads(number, target) {
     checkTarget(target);
-    // `-F` lets gh fill the placeholders from the clone; real values go as plain strings.
+    // `-F` lets gh fill the placeholders from the clone. Real values go as plain strings.
     const [owner, name] = target?.repo?.split('/') ?? [];
     const repo = owner === undefined || name === undefined
         ? ['-F', 'owner={owner}', '-F', 'name={repo}']
@@ -890,7 +902,7 @@ export function prReviewThreads(number, target) {
 }
 /**
  * `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 function createLabel(opts, target) {
@@ -907,7 +919,7 @@ export function createLabel(opts, target) {
     ];
     return { argv, checked: true, readOnly: false, parse: nothing };
 }
-/** `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 function editLabel(name, opts, target) {
     const argv = ['label', 'edit', name, ...repoArgs(target)];
     if (opts.color !== undefined)
@@ -917,21 +929,18 @@ export function editLabel(name, opts, target) {
     return { argv, checked: true, readOnly: false, parse: nothing };
 }
 /**
- * `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 function setIssueLabel(number, currentLabel, newLabel, target) {
     const argv = ['issue', 'edit', String(number), ...repoArgs(target)];
@@ -940,7 +949,7 @@ export function setIssueLabel(number, currentLabel, newLabel, target) {
     argv.push('--add-label', newLabel);
     return { argv, checked: true, readOnly: false, parse: nothing };
 }
-/** `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 function prDiff(number, target) {
     return {
         argv: ['pr', 'diff', String(number), ...repoArgs(target)],
@@ -949,7 +958,7 @@ export function prDiff(number, target) {
         parse: (r) => r.stdout,
     };
 }
-/** `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 function prComment(number, body, target) {
     return {
         argv: ['pr', 'comment', String(number), ...repoArgs(target), '--body', body],
@@ -967,10 +976,10 @@ export function prComment(number, body, target) {
 }
 /**
  * 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
@@ -1041,10 +1050,10 @@ export function branchPrFields(fields) {
 /**
  * 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 function needsMergeStateRetry(pr) {
     return pr.mergeable === 'UNKNOWN' || pr.mergeStateStatus === 'UNKNOWN';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/typed-gh",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "A typed GitHub client for TypeScript over the gh CLI. A total PullRequest/Review/CheckRun model, pure argv builders and parsers, and a tri-modal client — queries return parsed values, mutations throw, raw() is the escape hatch. Uses gh's own credentials; reads no token.",
   "license": "MIT OR Apache-2.0",
   "author": "sksizer",
@@ -22,8 +22,8 @@
     "LICENSE-APACHE"
   ],
   "dependencies": {
-    "@osdlc/command-seam": "^0.9.1",
-    "@osdlc/typed-git": "^0.7.0",
+    "@osdlc/command-seam": "^0.10.0",
+    "@osdlc/typed-git": "^0.7.1",
     "@osdlc/result": "^0.1.0"
   },
   "engines": {