@osdlc/typed-gh 0.7.0 → 0.9.1

package/dist/sync.js

@@ -1,24 +1,26 @@
 /**
- * `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 { resolveRunner, spawnRunner, } from '@osdlc/command-seam';
-import { runCheckedGh, settle, softSync, triedSync } from "./doors.js";
+import { runCheckedGh, softSync, triedSync } from "./doors.js";
+import { runVerb } from "./run.js";
 import * as v from "./verbs.js";
 import { ownerRepoSlug, parseOwnerRepo, parsePrRef } from "./repo.js";
-/** Default factory: real, spawnSync-backed runners. */
+/** The default factory: real runners that use `spawnSync`. */
 export const defaultRunnerFactory = spawnRunner;
 /** How long to wait between merge-state retries, in milliseconds. */
 const MERGE_STATE_RETRY_DELAY_MS = 1_500;
@@ -62,69 +64,61 @@ export class 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() {
         return (this.tried ??= triedSync(this));
     }
     /**
      * 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() {
         return (this.softened ??= softSync(this));
     }
-    // ── escape hatches ────────────────────────────────────────────────────────
-    /** Unchecked passthrough for verbs not yet lifted into the API. */
+    // ── raw calls ─────────────────────────────────────────────────────────────
+    /** Run any `gh` call and return the result, whatever the exit code. */
     raw(argv, opts = {}) {
         return this.runner.run(argv, { cwd: this.cwd, ...opts });
     }
-    /** 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, opts = {}) {
         return runCheckedGh(this.runner, argv, { cwd: this.cwd, ...opts });
     }
-    /** Run one verb from the table, honouring its checked/unchecked contract. */
+    /** Run one verb from the table, checked or unchecked as the verb says. */
     exec(verb, timeoutMs) {
-        const opts = { cwd: this.cwd };
-        if (verb.input !== undefined)
-            opts.input = verb.input;
-        if (verb.env !== undefined)
-            opts.env = verb.env;
-        if (timeoutMs !== undefined)
-            opts.timeoutMs = timeoutMs;
-        const result = verb.checked
-            ? runCheckedGh(this.runner, verb.argv, opts)
-            : this.runner.run(verb.argv, opts);
-        return settle(verb, result, this.runner.binary);
-    }
-    /** {@link exec} for a verb that never answers `null` as a value: a failed or unreadable run throws. */
+        return runVerb(verb, this.runner, { cwd: this.cwd, timeoutMs });
+    }
+    /** {@link exec} for a verb that never returns `null` as a value. A failed or unreadable run throws. */
     read(verb, timeoutMs) {
         return this.exec(verb, timeoutMs);
     }
     // ── queries ───────────────────────────────────────────────────────────────
-    /** 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 = {}) {
         return this.read(v.prList(opts, this.target), opts.timeoutMs);
     }
     /**
-     * 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, opts = {}) {
         return this.exec(v.prView(ref, opts.fields ?? v.PR_VIEW_FIELDS, this.target), opts.timeoutMs);
     }
     /**
-     * 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}.
@@ -146,12 +140,10 @@ export 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, opts = {}) {
         const rows = this.prList({
@@ -162,16 +154,16 @@ export class Gh {
         return v.pickPrForBranch(rows.rows, branch);
     }
     /**
-     * {@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, opts = {}) {
         const attempts = Math.max(1, opts.attempts ?? 3);
@@ -191,15 +183,15 @@ export class Gh {
         return this.read(v.prBody(number, this.target), opts.timeoutMs);
     }
     /**
-     * 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, opts = {}) {
         return this.exec(v.api(endpoint, opts, this.target), opts.timeoutMs);
     }
     /**
-     * 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
      */
@@ -214,7 +206,7 @@ export class Gh {
     issueList(opts = {}) {
         return this.read(v.issueList(opts, this.target), opts.timeoutMs);
     }
-    /** 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, opts = {}) {
         return this.exec(v.issueView(number, this.target), opts.timeoutMs);
     }
@@ -235,22 +227,23 @@ export class Gh {
         return this.exec(v.installed());
     }
     /**
-     * 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() {
         return this.authStatus().ok;
     }
-    /** 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() {
         return this.exec(v.authStatus(this.target));
     }
     /**
-     * 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() {
         return this.installed() && this.authenticated();
@@ -259,7 +252,7 @@ export class Gh {
      * `{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) {
         return remoteUrl === null ? null : parseOwnerRepo(remoteUrl);
@@ -273,16 +266,16 @@ export class Gh {
     editPr(number, opts) {
         this.exec(v.editPr(number, opts, this.target));
     }
-    /** 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) {
         return this.exec(v.prDiff(number, this.target));
     }
-    /** 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, body) {
         return this.exec(v.prComment(number, body, this.target));
     }
     /**
-     * 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
      */
@@ -302,14 +295,14 @@ export class Gh {
         this.exec(v.prSetDraft(number, draft, this.target));
     }
     /**
-     * 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, body) {
         this.exec(v.issueCommentEdit(commentId, body, this.target));
     }
-    /** 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, opts) {
         this.exec(v.prMerge(number, opts, this.target));
     }
@@ -327,8 +320,8 @@ export class Gh {
     }
     /**
      * 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, currentLabel, newLabel) {
         this.exec(v.setIssueLabel(number, currentLabel, newLabel, this.target));
@@ -346,9 +339,9 @@ function prForBranchOn(gh, branch, call) {
     return v.branchPr(rows);
 }
 /**
- * Block the calling thread. Crude on purpose: the synchronous client has no
- * event loop to await on, and the alternative — making every caller async to
- * accommodate one retry delay — colors the whole call graph.
+ * Block the calling thread. The synchronous client has no event loop to
+ * await on. The alternative is to make every caller async for one retry
+ * delay.
  */
 function sleepSync(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);

package/dist/types.d.ts

@@ -1,16 +1,16 @@
 /**
  * The GitHub model, typed.
  *
- * `gh` returns GraphQL-shaped JSON whose fields depend on what you asked for,
- * so every field here is total: a value, or the enum member that means "not
- * known". Absent and unknowable are the same answer to a caller, and giving
- * them one representation is what keeps a consumer from reading a field it
- * never requested as a fact.
+ * `gh` returns GraphQL-shaped JSON whose fields depend on what you asked for.
+ * So every field here always has a value: a real one, or the value that means
+ * "not known". Absent and unknowable are the same answer to a caller. Giving
+ * them one value keeps a caller from reading a field it never requested as a
+ * fact.
  *
  * Most enums are open on purpose. GitHub adds members, and a client that
- * crashes on an unrecognized one is worse than a client that carries it
- * through: unions end in `(string & {})` so a new value still types as the
- * enum while the known members keep their autocomplete.
+ * crashes on an unknown one is worse than a client that passes it on. Unions
+ * end in `(string & {})`, so a new value still types as the enum and the known
+ * members keep their autocomplete.
  *
  * Two are closed: {@link MergeableState} and {@link ReviewDecision}. Callers
  * compare them member by member to decide whether to merge, so the parser
@@ -25,10 +25,10 @@ export type MergeableState = 'MERGEABLE' | 'CONFLICTING' | 'UNKNOWN';
 /**
  * The merge-button state.
  *
- * `BEHIND` only ever appears when branch protection *requires* an up-to-date
- * branch. Without that rule a branch a hundred commits behind still reports
- * `CLEAN`, so this is a corroborating hint about staleness and never the
- * measure of it — compute that from the commit graph.
+ * `BEHIND` appears only when branch protection requires an up-to-date branch.
+ * Without that rule, a branch a hundred commits behind still reports `CLEAN`.
+ * So `BEHIND` is a hint that a branch is out of date, not a measure of it.
+ * Compute that from the commit graph.
  */
 export type MergeStateStatus = 'BEHIND' | 'BLOCKED' | 'CLEAN' | 'DIRTY' | 'DRAFT' | 'HAS_HOOKS' | 'UNKNOWN' | 'UNSTABLE' | (string & {});
 /** Where a pull request is in its life: open, closed without a merge, or merged. */
@@ -41,23 +41,22 @@ export type PullRequestState = 'OPEN' | 'CLOSED' | 'MERGED' | (string & {});
 export type ReviewDecision = 'APPROVED' | 'CHANGES_REQUESTED' | 'REVIEW_REQUIRED' | null;
 /** The state of one review. `PENDING` is a review its author has not submitted yet. */
 export type ReviewState = 'APPROVED' | 'CHANGES_REQUESTED' | 'COMMENTED' | 'DISMISSED' | 'PENDING' | (string & {});
-/** Who wrote something. `login` is normalized — a `[bot]` suffix is stripped. */
+/** Who wrote something. `login` is normalized: a `[bot]` suffix is stripped. */
 export interface Actor {
     login: string;
     /** True when GitHub marks the account as a bot, or the login carried `[bot]`. */
     isBot: boolean;
 }
-/** A repository label. `color` is hex digits such as `d73a4a`; a field the payload lacks is `''`. */
+/** A repository label. `color` is hex digits such as `d73a4a`. A field the payload lacks is `''`. */
 export interface Label {
     name: string;
     color: string;
     description: string;
 }
 /**
- * A GitHub issue, off `gh issue list`/`gh issue view --json
- * number,title,body,labels,state`. Deliberately a small field set — not the
- * full PR-sized model, since nothing here reads reviews, checks or comments
- * off an issue.
+ * A GitHub issue, from `gh issue list`/`gh issue view --json
+ * number,title,body,labels,state`. It has a small field set on purpose,
+ * because nothing here reads reviews, checks or comments on an issue.
  */
 export interface IssueRow {
     number: number;
@@ -69,22 +68,22 @@ export interface IssueRow {
 /**
  * How a finished check ended, as GitHub reports it. Null while the check is
  * still running, and always null for a legacy status context. Read
- * {@link CheckRun.verdict} for the answer folded across both node types.
+ * {@link CheckRun.verdict} for one answer that covers both node types.
  */
 export type CheckConclusion = 'SUCCESS' | 'FAILURE' | 'NEUTRAL' | 'CANCELLED' | 'TIMED_OUT' | 'ACTION_REQUIRED' | 'SKIPPED' | 'STALE' | 'STARTUP_FAILURE' | (string & {}) | null;
-/** One rolled-up check, with the two GitHub shapes folded into one. */
+/** One check from the status rollup, with GitHub's two node types mapped to one shape. */
 export interface CheckRun {
     /** A CheckRun's `name`, or a legacy StatusContext's `context`. */
     name: string;
-    /** `QUEUED` / `IN_PROGRESS` / `COMPLETED`; null for a status context. */
+    /** `QUEUED` / `IN_PROGRESS` / `COMPLETED`. Null for a status context. */
     status: string | null;
     conclusion: CheckConclusion;
     /**
-     * The normalized verdict. A check still running is `pending`, not a pass —
-     * treating "no failure yet" as green is how a red build merges.
+     * The normalized verdict. A check still running is `pending`, not a pass.
+     * If "no failure yet" counted as green, a red build could merge.
      */
     verdict: 'pending' | 'success' | 'failure' | 'neutral';
-    /** A CheckRun's `detailsUrl`, or a legacy StatusContext's `targetUrl` — where to read the log. Null when the code host gives none. */
+    /** A CheckRun's `detailsUrl`, or a legacy StatusContext's `targetUrl`: where to read the log. Null when GitHub gives none. */
     url: string | null;
 }
 /** One conversation comment on a pull request. */
@@ -114,7 +113,7 @@ export interface Review {
  *
  * Fields `gh` was not asked for come back at their "not known" value, so this
  * type is safe to build from any field subset. `number` is the only field
- * without one — a PR with no number is not a PR, and parsing returns null.
+ * without one. A payload with no number is not a PR, and parsing returns null.
  */
 export interface PullRequest {
     number: number;
@@ -125,11 +124,11 @@ export interface PullRequest {
     isDraft: boolean;
     baseRefName: string;
     headRefName: string;
-    /** Head commit sha, when requested — the thing to pin a force-push lease to. */
+    /** Head commit sha, when requested. Use it as the expected value for `--force-with-lease`. */
     headRefOid: string | null;
     /**
-     * True when the head branch lives in a fork. Its ref is then not on the
-     * base repository's `origin`; fetch `refs/pull/<n>/head` instead.
+     * True when the head branch is in a fork. Its ref is then not on the
+     * base repository's `origin`. Fetch `refs/pull/<n>/head` instead.
      */
     isCrossRepository: boolean;
     mergeable: MergeableState;
@@ -152,7 +151,7 @@ export interface OwnerRepo {
 /** Who can see a repository. */
 export type RepositoryVisibility = 'PUBLIC' | 'PRIVATE' | 'INTERNAL' | (string & {});
 /**
- * A repository, off `gh repo list`/`gh repo view --json`. A field not asked
+ * A repository, from `gh repo list`/`gh repo view --json`. A field not asked
  * for comes back at its "not known" value. `nameWithOwner` is the only field
  * without one: a row without it is dropped.
  */
@@ -162,15 +161,15 @@ export interface Repository {
     owner: string;
     name: string;
     description: string;
-    /** The default branch; null when not asked for, or the repository is empty. */
+    /** The default branch. Null when not asked for, or when the repository is empty. */
     defaultBranch: string | null;
     visibility: RepositoryVisibility | null;
     isArchived: boolean;
     url: string;
 }
 /**
- * One pull request found by `gh search prs`. Search has its own field set:
- * it names the repository but carries no head or base branch, so this is not
+ * One pull request found by `gh search prs`. Search has its own field set.
+ * It names the repository but carries no head or base branch, so this is not
  * a {@link PullRequest}. `state` is upper-cased to match `PullRequest`.
  */
 export interface PrSearchHit {

package/dist/types.js

@@ -1,16 +1,16 @@
 /**
  * The GitHub model, typed.
  *
- * `gh` returns GraphQL-shaped JSON whose fields depend on what you asked for,
- * so every field here is total: a value, or the enum member that means "not
- * known". Absent and unknowable are the same answer to a caller, and giving
- * them one representation is what keeps a consumer from reading a field it
- * never requested as a fact.
+ * `gh` returns GraphQL-shaped JSON whose fields depend on what you asked for.
+ * So every field here always has a value: a real one, or the value that means
+ * "not known". Absent and unknowable are the same answer to a caller. Giving
+ * them one value keeps a caller from reading a field it never requested as a
+ * fact.
  *
  * Most enums are open on purpose. GitHub adds members, and a client that
- * crashes on an unrecognized one is worse than a client that carries it
- * through: unions end in `(string & {})` so a new value still types as the
- * enum while the known members keep their autocomplete.
+ * crashes on an unknown one is worse than a client that passes it on. Unions
+ * end in `(string & {})`, so a new value still types as the enum and the known
+ * members keep their autocomplete.
  *
  * Two are closed: {@link MergeableState} and {@link ReviewDecision}. Callers
  * compare them member by member to decide whether to merge, so the parser