@osdlc/typed-gh 0.9.0 → 0.9.2

package/dist/async.js

@@ -1,13 +1,14 @@
 /**
- * `AsyncGh` — the awaitable GitHub client, with the same methods as {@link Gh}.
+ * `AsyncGh`: the awaitable GitHub client, with the same methods as {@link Gh}.
  *
- * Same three doors, promised: the plain method resolves to a value or rejects
- * (a `FailureError` carrying the classified `GhFailure` for a failed gh or output it cannot read;
- * a query for one thing resolves `null` when GitHub has no such thing),
- * `try` resolves to a `Result<T, GhFailure>`, `soft` resolves `null` for a
- * failure, and `raw`/`rawChecked` are the hatches. It is driven by the same pure verb
- * table as `Gh`, so the two cannot drift on argv or parsing. Use it where the
- * sync client would block the event loop: a fan-out of per-PR queries.
+ * It has the same three call styles, as Promises. The plain method resolves to
+ * a value or rejects with a `FailureError` carrying the classified `GhFailure`,
+ * for a failed gh or output it cannot read. A query for one thing resolves
+ * `null` when GitHub has no such thing. `try` resolves to a
+ * `Result<T, GhFailure>`. `soft` resolves `null` for a failure. `raw` and
+ * `rawChecked` run any `gh` call. It uses the same verb table as `Gh`, so the
+ * two cannot differ on argv or parsing. Use it where the sync client would
+ * block the event loop, such as many per-PR queries at once.
  */
 import { resolveRunnerAsync, } from '@osdlc/command-seam';
 import { runCheckedGhAsync, softAsync, triedAsync } from "./doors.js";
@@ -56,16 +57,16 @@ export class AsyncGh {
     get soft() {
         return (this.softened ??= softAsync(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 — rejects with the classified failure on a non-zero exit. */
+    /** Run any `gh` call. Rejects with the classified failure on a non-zero exit. */
     rawChecked(argv, opts = {}) {
         return runCheckedGhAsync(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. */
     async exec(verb, call = {}) {
         return runVerbAsync(verb, this.runner, {
             cwd: this.cwd,
@@ -73,12 +74,12 @@ export class AsyncGh {
             signal: call.signal,
         });
     }
-    /** {@link exec} for a verb that never answers `null` as a value: a failed or unreadable run rejects. */
+    /** {@link exec} for a verb that never returns `null` as a value. A failed or unreadable run rejects. */
     async read(verb, call = {}) {
         return (await this.exec(verb, call));
     }
     // ── queries ───────────────────────────────────────────────────────────────
-    /** Pull requests matching `opts`. Rejects when gh fails; `soft.prList` resolves null instead. */
+    /** Pull requests matching `opts`. Rejects when gh fails. `soft.prList` resolves null instead. */
     prList(opts = {}) {
         return this.read(v.prList(opts, this.target), opts);
     }
@@ -111,7 +112,7 @@ export class AsyncGh {
         });
         return v.pickPrForBranch(rows.rows, branch);
     }
-    /** {@link prView}, re-asked until GitHub settles the merge state. See `Gh.prViewSettled`. */
+    /** {@link prView}, asked again until GitHub has computed the merge state. See `Gh.prViewSettled`. */
     async prViewSettled(number, opts = {}) {
         const attempts = Math.max(1, opts.attempts ?? 3);
         const sleep = opts.sleep ?? sleepAsync;
@@ -129,12 +130,12 @@ export class AsyncGh {
     prBody(number, opts = {}) {
         return this.read(v.prBody(number, this.target), opts);
     }
-    /** A REST GET through `gh api`; failure is `ok: false`, never a rejection. */
+    /** A REST GET through `gh api`. Failure is `ok: false`, never a rejection. */
     api(endpoint, opts = {}) {
         return this.exec(v.api(endpoint, opts, this.target), opts);
     }
     /**
-     * A GraphQL query; each page's `data`. Rejects on a failed or partial result. See `Gh.graphql`.
+     * A GraphQL query. Resolves to each page's `data`. Rejects on a failed or partial result. See `Gh.graphql`.
      *
      * @experimental
      */
@@ -149,7 +150,7 @@ export class AsyncGh {
     issueList(opts = {}) {
         return this.read(v.issueList(opts, this.target), opts);
     }
-    /** One issue with its labels; null when there is no such issue. */
+    /** One issue with its labels, or null when there is no such issue. */
     issueView(number, opts = {}) {
         return this.exec(v.issueView(number, this.target), opts);
     }
@@ -157,7 +158,7 @@ export class AsyncGh {
     repoList(owner, opts = {}) {
         return this.read(v.repoList(owner, opts, this.target), opts);
     }
-    /** One repository; null when there is no such repository. See `Gh.repoView`. */
+    /** One repository, or null when there is no such repository. See `Gh.repoView`. */
     repoView(repo, opts = {}) {
         return this.exec(v.repoView(repo, opts.fields ?? v.REPO_FIELDS, this.target), opts);
     }
@@ -177,13 +178,13 @@ export class AsyncGh {
     authStatus() {
         return this.exec(v.authStatus(this.target));
     }
-    /** True iff `gh` is installed AND authenticated; short-circuits. */
+    /** True iff `gh` is installed and authenticated. Skips the auth check when `gh` is not installed. */
     async ready() {
         return (await this.installed()) && (await this.authenticated());
     }
     /**
      * `{owner, repo}` parsed from the remote URL you pass, or null when it is
-     * null or names no project. Pure, so it is sync on purpose.
+     * null or names no project. It starts no process, so it is sync on purpose.
      */
     ownerRepo(remoteUrl) {
         return remoteUrl === null ? null : parseOwnerRepo(remoteUrl);
@@ -201,16 +202,16 @@ export class AsyncGh {
     editPrBody(number, body) {
         return this.exec(v.editPrBody(number, body, this.target));
     }
-    /** The PR's unified diff; rejects with the classified failure when gh cannot produce it. */
+    /** The PR's unified diff. Rejects with 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; resolves to its URL ('' if gh printed none). */
+    /** Post one conversation comment on a PR. Resolves to 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; resolves to the review's URL ('' if none came back).
+     * Create a `COMMENT` review with inline comments. Resolves to the review's URL ('' if none came back).
      *
      * @experimental
      */
@@ -226,19 +227,19 @@ export class AsyncGh {
         return this.exec(v.prSetDraft(number, draft, this.target));
     }
     /**
-     * Rewrite one PR conversation comment's body. `commentId` is the numeric REST id; anything else rejects with `RangeError`.
+     * Rewrite one PR conversation comment's body. `commentId` is the numeric REST id. Anything else rejects with `RangeError`.
      *
      * @experimental
      */
     async issueCommentEdit(commentId, body) {
-        // async, so a bad id rejects the Promise instead of throwing at the call.
+        // async, so a bad id rejects the Promise instead of throwing at the call site.
         return 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) {
         return this.exec(v.prMerge(number, opts, this.target));
     }
-    /** A PR's review threads, or null when they could not be read completely. */
+    /** A PR's review threads. Rejects when they could not be read completely. `soft.prReviewThreads` resolves null instead. */
     prReviewThreads(number) {
         return this.read(v.prReviewThreads(number, this.target));
     }

package/dist/doors.d.ts

@@ -1,34 +1,36 @@
 /**
- * The three doors, as `@osdlc/typed-git` has them: the plain verb (checked),
- * `gh.try.*` and `gh.soft.*`.
+ * The three call styles, as `@osdlc/typed-git` has them: the method that
+ * throws, `gh.try.*` and `gh.soft.*`.
  *
- *   - **Plain / checked**: a value, or a throw. A failed `gh` throws a
+ *   - The method that throws returns a value or throws. A failed `gh` throws a
  *     `FailureError` carrying the classified `GhFailure` (its `cause` is the
- *     `CommandFailed`), so a caller that reports it, such as `runMain`, reads
- *     "signed out" or "rate limited" and not a bare exit; output that exited 0
- *     but could not be read throws one of kind `unreadable`. A verb that
- *     reads one thing (`prView`, `issueView`, `repoView`) answers `null` when
- *     GitHub says there is no such thing: absence is an answer.
- *   - **`try`**: the same call, with the failure returned as
- *     `Result<T, GhFailure>`. It catches a thrown failure (a `FailureError`, or a
- *     `CommandFailed` from `raw`-level code) and nothing else: a `RangeError` for a bad argument still throws.
- *   - **`soft`**: the same call, with `null` for a failure. Only the queries
- *     have a soft form; no mutation does.
+ *     `CommandFailed`). So a caller that reports it, such as `runMain`, shows
+ *     "signed out" or "rate limited" and not a bare exit code. Output that
+ *     exited 0 but could not be read throws one of kind `unreadable`. A verb
+ *     that reads one thing (`prView`, `issueView`, `repoView`) returns `null`
+ *     when GitHub says there is no such thing.
+ *   - `try` makes the same call and returns the failure as
+ *     `Result<T, GhFailure>`. It catches a thrown failure (a `FailureError`, or
+ *     a `CommandFailed` from `raw`-level code) and nothing else. A `RangeError`
+ *     for a bad argument still throws.
+ *   - `soft` makes the same call and returns `null` for a failure. Only the
+ *     queries have a soft form. No mutation does.
  *
- * Both are facades over the whole client, so a new method costs nothing here.
+ * `try` and `soft` are proxies over the whole client, so a new method needs no
+ * change here.
  */
 import { type AsyncCommandRunner, type AsyncCommandRunOptions, type CommandResult, type CommandRunner, type CommandRunOptions } from '@osdlc/command-seam';
 import { type Failure, type Result } from '@osdlc/result';
 import { type GhFailure } from './failure.ts';
 import type { GhVerb } from './verbs.ts';
 /**
- * Read the result of running `verb` as the plain door does.
+ * Read the result of running `verb` as the methods that throw do.
  *
  * A checked verb has already thrown on a non-zero exit (the runner is
- * `runChecked`), and a probe (`installed`, `authStatus`, `api`) carries its
- * failure in its value. A read that exited non-zero throws `CommandFailed`,
- * unless the verb's `absent` says gh's answer was "there is no such thing",
- * which `parse` turns into `null`. A read that exited 0 but parsed to `null`
+ * `runChecked`). A probe (`installed`, `authStatus`, `api`) carries its
+ * failure in its value. A read that exited non-zero throws the classified
+ * failure, unless the verb's `absent` says gh's answer was "there is no such
+ * thing", which `parse` turns into `null`. A read that exited 0 but parsed to `null`
  * could not be read completely, and throws.
  *
  * @throws `FailureError` carrying the classified {@link GhFailure} for a failed run.
@@ -36,7 +38,7 @@ import type { GhVerb } from './verbs.ts';
  */
 export declare function settle<T>(verb: GhVerb<T>, result: CommandResult, binary: string | undefined): T;
 /**
- * The error the plain door throws for a failed run: a `FailureError` carrying
+ * The error the methods that throw raise for a failed run: a `FailureError` carrying
  * the {@link GhFailure} that {@link classifyGhFailure} reads from it, with the
  * `CommandFailed` as its `cause`. Anything else is returned as it is.
  */
@@ -45,7 +47,7 @@ export declare function ghFailureError(error: unknown): unknown;
 export declare function runCheckedGh(runner: CommandRunner, argv: string[], opts: CommandRunOptions): CommandResult;
 /** {@link runCheckedAsync}, rejecting with {@link ghFailureError}'s classified failure. */
 export declare function runCheckedGhAsync(runner: AsyncCommandRunner, argv: string[], opts: AsyncCommandRunOptions): Promise<CommandResult>;
-/** The methods the doors leave out: the escape hatches, pure helpers and plain properties. */
+/** The members `try` and `soft` leave out: `raw`, `rawChecked`, helpers that run nothing, and properties. */
 type Triable<C> = Omit<C, 'raw' | 'rawChecked' | 'at' | 'withRepo' | 'ownerRepo' | 'try' | 'soft' | 'cwd' | 'repo' | 'hostname'>;
 /** Every synchronous client method, returning a `Result<T, GhFailure>`. */
 export type TriedSync<C> = {
@@ -56,8 +58,8 @@ export type TriedAsync<C> = {
     [K in keyof Triable<C>]: Triable<C>[K] extends (...a: infer A) => Promise<infer R> ? (...a: A) => Promise<Result<R, GhFailure>> : never;
 };
 /**
- * The queries that have a soft form. A mutation has none: swallowing the failure
- * of a write is how a caller ends up believing it worked.
+ * The queries that have a soft form. A mutation has none. If a write's failure
+ * were dropped, the caller would believe the write worked.
  */
 export declare const SOFT_METHODS: readonly ["prList", "prView", "prFind", "openPrFor", "prViewSettled", "prBody", "graphql", "labelList", "issueList", "issueView", "repoList", "repoView", "searchPrs", "prReviewThreads"];
 /** The name of a method with a soft form. */

package/dist/doors.js

@@ -1,33 +1,35 @@
 /**
- * The three doors, as `@osdlc/typed-git` has them: the plain verb (checked),
- * `gh.try.*` and `gh.soft.*`.
+ * The three call styles, as `@osdlc/typed-git` has them: the method that
+ * throws, `gh.try.*` and `gh.soft.*`.
  *
- *   - **Plain / checked**: a value, or a throw. A failed `gh` throws a
+ *   - The method that throws returns a value or throws. A failed `gh` throws a
  *     `FailureError` carrying the classified `GhFailure` (its `cause` is the
- *     `CommandFailed`), so a caller that reports it, such as `runMain`, reads
- *     "signed out" or "rate limited" and not a bare exit; output that exited 0
- *     but could not be read throws one of kind `unreadable`. A verb that
- *     reads one thing (`prView`, `issueView`, `repoView`) answers `null` when
- *     GitHub says there is no such thing: absence is an answer.
- *   - **`try`**: the same call, with the failure returned as
- *     `Result<T, GhFailure>`. It catches a thrown failure (a `FailureError`, or a
- *     `CommandFailed` from `raw`-level code) and nothing else: a `RangeError` for a bad argument still throws.
- *   - **`soft`**: the same call, with `null` for a failure. Only the queries
- *     have a soft form; no mutation does.
+ *     `CommandFailed`). So a caller that reports it, such as `runMain`, shows
+ *     "signed out" or "rate limited" and not a bare exit code. Output that
+ *     exited 0 but could not be read throws one of kind `unreadable`. A verb
+ *     that reads one thing (`prView`, `issueView`, `repoView`) returns `null`
+ *     when GitHub says there is no such thing.
+ *   - `try` makes the same call and returns the failure as
+ *     `Result<T, GhFailure>`. It catches a thrown failure (a `FailureError`, or
+ *     a `CommandFailed` from `raw`-level code) and nothing else. A `RangeError`
+ *     for a bad argument still throws.
+ *   - `soft` makes the same call and returns `null` for a failure. Only the
+ *     queries have a soft form. No mutation does.
  *
- * Both are facades over the whole client, so a new method costs nothing here.
+ * `try` and `soft` are proxies over the whole client, so a new method needs no
+ * change here.
  */
 import { CommandFailed, isCommandFailed, runChecked, runCheckedAsync, } from '@osdlc/command-seam';
 import { err, FailureError, isFailure, ok } from '@osdlc/result';
 import { classifyGhFailure, unreadableFailure } from "./failure.js";
 /**
- * Read the result of running `verb` as the plain door does.
+ * Read the result of running `verb` as the methods that throw do.
  *
  * A checked verb has already thrown on a non-zero exit (the runner is
- * `runChecked`), and a probe (`installed`, `authStatus`, `api`) carries its
- * failure in its value. A read that exited non-zero throws `CommandFailed`,
- * unless the verb's `absent` says gh's answer was "there is no such thing",
- * which `parse` turns into `null`. A read that exited 0 but parsed to `null`
+ * `runChecked`). A probe (`installed`, `authStatus`, `api`) carries its
+ * failure in its value. A read that exited non-zero throws the classified
+ * failure, unless the verb's `absent` says gh's answer was "there is no such
+ * thing", which `parse` turns into `null`. A read that exited 0 but parsed to `null`
  * could not be read completely, and throws.
  *
  * @throws `FailureError` carrying the classified {@link GhFailure} for a failed run.
@@ -48,7 +50,7 @@ export function settle(verb, result, binary) {
     return value;
 }
 /**
- * The error the plain door throws for a failed run: a `FailureError` carrying
+ * The error the methods that throw raise for a failed run: a `FailureError` carrying
  * the {@link GhFailure} that {@link classifyGhFailure} reads from it, with the
  * `CommandFailed` as its `cause`. Anything else is returned as it is.
  */
@@ -74,8 +76,8 @@ export async function runCheckedGhAsync(runner, argv, opts) {
     }
 }
 /**
- * The queries that have a soft form. A mutation has none: swallowing the failure
- * of a write is how a caller ends up believing it worked.
+ * The queries that have a soft form. A mutation has none. If a write's failure
+ * were dropped, the caller would believe the write worked.
  */
 export const SOFT_METHODS = [
     'prList',
@@ -94,9 +96,9 @@ export const SOFT_METHODS = [
     'prReviewThreads',
 ];
 /**
- * Whether `error` carries a failure to hand back rather than a bug to let
- * through. By shape, not `instanceof`: two installed copies of command-seam or
- * result each have their own classes.
+ * Whether `error` carries a failure to return, rather than a bug to rethrow.
+ * Checked by shape, not `instanceof`, because two installed copies of
+ * command-seam or result each have their own classes.
  */
 function isGhFailure(error) {
     return (typeof error === 'object' &&
@@ -111,8 +113,8 @@ export function failureOf(error) {
 function facade(client, wrap) {
     return new Proxy(client, {
         get(target, prop) {
-            // Read from the target, not the proxy: a getter (`try` itself) must run
-            // against the real client rather than recursing through the facade.
+            // Read from the target, not the proxy. A getter (`try` itself) must run
+            // against the real client, not recurse through the proxy.
             const value = Reflect.get(target, prop);
             if (typeof value !== 'function')
                 return value;

package/dist/failure.d.ts

@@ -1,10 +1,10 @@
 /**
- * {@link GhFailure}: a failed `gh` call, classified. The `gh.try.*` door
- * returns it as the error of a `Result`; its `cause` is the `CommandFailed`
+ * {@link GhFailure}: a failed `gh` call, classified. The `gh.try.*` methods
+ * return it as the error of a `Result`. Its `cause` is the `CommandFailed`
  * it was read from.
  *
- * The kinds beyond the subprocess layer's come from `gh`'s stderr, matched in
- * English. A message that matches none stays the subprocess layer's `exit`
+ * The kinds beyond command-seam's come from `gh`'s stderr and stdout, matched
+ * in English. A message that matches none stays the subprocess layer's `exit`
  * with `gh`'s first stderr line, never a wrong kind.
  */
 import { type CommandFailed, type CommandFailureKind } from '@osdlc/command-seam';
@@ -26,17 +26,17 @@ import { type Failure } from '@osdlc/result';
  *   (malformed JSON, a partial GraphQL answer, a review-thread list cut short).
  */
 export type GhFailureKind = CommandFailureKind | 'not-authenticated' | 'network' | 'not-found' | 'rate-limited' | 'unreadable';
-/** A failed `gh` call. `message` is one line for a person; `detail` is `gh`'s own output. */
+/** A failed `gh` call. `message` is one line for a person. `detail` is `gh`'s own output. */
 export interface GhFailure extends Failure<GhFailureKind> {
     /** The binary that ran (`gh`), when known. */
     binary?: string | undefined;
     /** The arguments `gh` ran with, without the binary name. */
     argv: string[];
-    /** `gh`'s exit code; `null` when it never reported one. */
+    /** `gh`'s exit code, or `null` when it never reported one. */
     exitCode: number | null;
     /** The signal that ended `gh`, when the runner knows it. */
     signal?: NodeJS.Signals | null | undefined;
-    /** The `CommandFailed` this was classified from; absent for `unreadable`, where `gh` succeeded. */
+    /** The `CommandFailed` this was classified from. Absent for `unreadable`, where `gh` succeeded. */
     cause?: CommandFailed | undefined;
 }
 /** What a verb that reads one thing asks GitHub for. */
@@ -44,7 +44,7 @@ export type Thing = 'pr' | 'issue' | 'repo';
 /**
  * Whether the text of a failed `gh` run (stderr then stdout, as
  * {@link classifyGhFailure} reads it) means "there is no such `thing`", for a
- * verb that reads one thing: an answer, not a failure.
+ * verb that reads one thing. That is an answer, not a failure.
  *
  * Narrower than the `not-found` failure kind on purpose. A mistyped `--repo`
  * makes `gh pr view 7` say "Could not resolve to a Repository", which is a

package/dist/failure.js

@@ -1,10 +1,10 @@
 /**
- * {@link GhFailure}: a failed `gh` call, classified. The `gh.try.*` door
- * returns it as the error of a `Result`; its `cause` is the `CommandFailed`
+ * {@link GhFailure}: a failed `gh` call, classified. The `gh.try.*` methods
+ * return it as the error of a `Result`. Its `cause` is the `CommandFailed`
  * it was read from.
  *
- * The kinds beyond the subprocess layer's come from `gh`'s stderr, matched in
- * English. A message that matches none stays the subprocess layer's `exit`
+ * The kinds beyond command-seam's come from `gh`'s stderr and stdout, matched
+ * in English. A message that matches none stays the subprocess layer's `exit`
  * with `gh`'s first stderr line, never a wrong kind.
  */
 import { classifyFailure } from '@osdlc/command-seam';
@@ -22,7 +22,7 @@ const ABSENT = {
 /**
  * Whether the text of a failed `gh` run (stderr then stdout, as
  * {@link classifyGhFailure} reads it) means "there is no such `thing`", for a
- * verb that reads one thing: an answer, not a failure.
+ * verb that reads one thing. That is an answer, not a failure.
  *
  * Narrower than the `not-found` failure kind on purpose. A mistyped `--repo`
  * makes `gh pr view 7` say "Could not resolve to a Repository", which is a
@@ -35,7 +35,7 @@ export function isAbsent(thing, text) {
 }
 /** The gh failure for a failed `gh` run. */
 export function classifyGhFailure(failed) {
-    // The client's runner may not name its binary; this is gh either way, so the
+    // The client's runner may not name its binary. It is gh either way, so the
     // messages say `gh` rather than "The command".
     const f = failed.binary === undefined
         ? (classifyFailure(failed.result, { binary: 'gh', argv: failed.argv }) ?? failed.failure)

package/dist/index.d.ts

@@ -1,21 +1,20 @@
 /**
- * `@osdlc/typed-gh` — a typed GitHub client for TypeScript, over the `gh`
+ * `@osdlc/typed-gh`: a typed GitHub client for TypeScript, over the `gh`
  * CLI. The GitHub-side companion of `@osdlc/typed-git`.
  *
- * Three things it is:
+ * It has three parts:
  *
- *   - **A model.** `PullRequest`, `Review`, `CheckRun` and their enums, so a
- *     caller stops reading `payload["mergeable"] as string | undefined`. Every
- *     field is total: one a query did not ask for lands at its "not known"
- *     value, because absent and unknowable are the same answer.
- *   - **Pure argv builders and parsers.** The verb table and `parse.ts` never
- *     spawn anything, so an async fan-out drives them through its own runner
- *     without duplicating a line of parsing.
- *   - **A client.** `Gh`, with `Git`'s three doors: the plain method returns a
- *     value or throws a `FailureError` carrying the classified
- *     `GhFailure`; `gh.try.*` returns a
- *     `Result<T, GhFailure>`; `gh.soft.*` returns `null` for a failed query.
- *     `raw` is the hatch.
+ *   - A model. `PullRequest`, `Review`, `CheckRun` and their enums, so a
+ *     caller does not read `payload["mergeable"] as string | undefined`. Every
+ *     field always has a value. A field the query did not ask for gets its
+ *     "not known" value, because absent and unknowable are the same answer.
+ *   - Argv builders and parsers with no side effects. The verb table and
+ *     `parse.ts` never start a process, so code that runs many calls at once
+ *     can run them through its own runner and reuse the parsing.
+ *   - A client. `Gh` has the same three call styles as `Git`. The method that
+ *     throws returns a value or throws a `FailureError` carrying the
+ *     classified `GhFailure`. `gh.try.*` returns a `Result<T, GhFailure>`.
+ *     `gh.soft.*` returns `null` for a failed query. `raw` runs any `gh` call.
  *
  * Authentication is `gh`'s. No token is read, stored, or forwarded.
  */

package/dist/index.js

@@ -1,21 +1,20 @@
 /**
- * `@osdlc/typed-gh` — a typed GitHub client for TypeScript, over the `gh`
+ * `@osdlc/typed-gh`: a typed GitHub client for TypeScript, over the `gh`
  * CLI. The GitHub-side companion of `@osdlc/typed-git`.
  *
- * Three things it is:
+ * It has three parts:
  *
- *   - **A model.** `PullRequest`, `Review`, `CheckRun` and their enums, so a
- *     caller stops reading `payload["mergeable"] as string | undefined`. Every
- *     field is total: one a query did not ask for lands at its "not known"
- *     value, because absent and unknowable are the same answer.
- *   - **Pure argv builders and parsers.** The verb table and `parse.ts` never
- *     spawn anything, so an async fan-out drives them through its own runner
- *     without duplicating a line of parsing.
- *   - **A client.** `Gh`, with `Git`'s three doors: the plain method returns a
- *     value or throws a `FailureError` carrying the classified
- *     `GhFailure`; `gh.try.*` returns a
- *     `Result<T, GhFailure>`; `gh.soft.*` returns `null` for a failed query.
- *     `raw` is the hatch.
+ *   - A model. `PullRequest`, `Review`, `CheckRun` and their enums, so a
+ *     caller does not read `payload["mergeable"] as string | undefined`. Every
+ *     field always has a value. A field the query did not ask for gets its
+ *     "not known" value, because absent and unknowable are the same answer.
+ *   - Argv builders and parsers with no side effects. The verb table and
+ *     `parse.ts` never start a process, so code that runs many calls at once
+ *     can run them through its own runner and reuse the parsing.
+ *   - A client. `Gh` has the same three call styles as `Git`. The method that
+ *     throws returns a value or throws a `FailureError` carrying the
+ *     classified `GhFailure`. `gh.try.*` returns a `Result<T, GhFailure>`.
+ *     `gh.soft.*` returns `null` for a failed query. `raw` runs any `gh` call.
  *
  * Authentication is `gh`'s. No token is read, stored, or forwarded.
  */
@@ -27,7 +26,7 @@ export { Gh, defaultRunnerFactory } from "./sync.js";
 export { api, authStatus, createPr, editPr, editPrBody, graphql, createLabel, createReview, editLabel, installed, issueList, issueView, labelList, nodesAt, openPrsForBranch, pickPrForBranch, prBody, prComment, prSetDraft, issueCommentEdit, prDiff, prList, prMerge, prReviewThreads, prUpdateBranch, prView, repoList, repoView, searchPrs, setIssueLabel, PR_LIST_FIELDS, PR_REF_FIELDS, PR_VIEW_FIELDS, REPO_FIELDS, SEARCH_PR_FIELDS, } from "./verbs.js";
 export { anyCheckFailed, normalizeAuthorLogin, parsePullRequest } from "./parse.js";
 export { ownerRepoSlug, parseOwnerRepo, parsePrRef, parsePrUrl, } from "./repo.js";
-// The seam's error and runner types appear in this package's signatures, so
+// command-seam's error and runner types appear in this package's signatures, so
 // they are re-exported. Its functions are not: import them from
 // `@osdlc/command-seam`.
 export { CommandFailed, } from '@osdlc/command-seam';

package/dist/parse.d.ts

@@ -1,31 +1,31 @@
 /**
- * `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.
  */
 import type { Actor, CheckRun, Label, PrSearchHit, PullRequest, Repository } from './types.ts';
 /**
- * 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 declare function normalizeAuthorLogin(login: string): string;
 /**
- * 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 declare function parseActor(x: unknown): Actor | null;
@@ -33,13 +33,13 @@ export declare function parseActor(x: unknown): Actor | null;
 export declare function parseCheckRun(x: unknown): CheckRun | null;
 /** True iff any check in the rollup failed. */
 export declare function anyCheckFailed(checks: readonly CheckRun[]): boolean;
-/** 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 declare function parseLabels(x: unknown): Label[];
 /**
  * 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 declare function parsePullRequest(raw: unknown): PullRequest | null;