@osdlc/typed-gh 0.5.0 → 0.7.0

package/dist/doors.js

@@ -0,0 +1,183 @@
+/**
+ * The three doors, as `@osdlc/typed-git` has them: the plain verb (checked),
+ * `gh.try.*` and `gh.soft.*`.
+ *
+ *   - **Plain / checked**: a value, or a throw. 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.
+ *
+ * Both are facades over the whole client, so a new method costs nothing 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.
+ *
+ * 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`
+ * could not be read completely, and throws.
+ *
+ * @throws `FailureError` carrying the classified {@link GhFailure} for a failed run.
+ * @throws `FailureError` carrying an `unreadable` {@link GhFailure}.
+ */
+export function settle(verb, result, binary) {
+    if (verb.checked || verb.probe === true)
+        return verb.parse(result);
+    if (result.neverExited === true || result.exitCode !== 0) {
+        if (result.neverExited !== true && verb.absent?.(result) === true)
+            return verb.parse(result);
+        throw ghFailureError(new CommandFailed(verb.argv, result, binary));
+    }
+    const value = verb.parse(result);
+    if (value === null) {
+        throw new FailureError(unreadableFailure(verb.argv, result.stdout, binary));
+    }
+    return value;
+}
+/**
+ * The error the plain door throws 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.
+ */
+export function ghFailureError(error) {
+    return isCommandFailed(error) ? new FailureError(classifyGhFailure(error)) : error;
+}
+/** {@link runChecked}, throwing {@link ghFailureError}'s classified failure. */
+export function runCheckedGh(runner, argv, opts) {
+    try {
+        return runChecked(runner, argv, opts);
+    }
+    catch (error) {
+        throw ghFailureError(error);
+    }
+}
+/** {@link runCheckedAsync}, rejecting with {@link ghFailureError}'s classified failure. */
+export async function runCheckedGhAsync(runner, argv, opts) {
+    try {
+        return await runCheckedAsync(runner, argv, opts);
+    }
+    catch (error) {
+        throw ghFailureError(error);
+    }
+}
+/**
+ * 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.
+ */
+export const SOFT_METHODS = [
+    'prList',
+    'prView',
+    'prFind',
+    'openPrFor',
+    'prViewSettled',
+    'prBody',
+    'graphql',
+    'labelList',
+    'issueList',
+    'issueView',
+    'repoList',
+    'repoView',
+    'searchPrs',
+    '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.
+ */
+function isGhFailure(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        isFailure(error.failure));
+}
+/** The failure a caught `CommandFailed` or `FailureError` stands for. */
+export function failureOf(error) {
+    const thrown = error;
+    return isCommandFailed(thrown) ? classifyGhFailure(thrown) : error.failure;
+}
+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.
+            const value = Reflect.get(target, prop);
+            if (typeof value !== 'function')
+                return value;
+            const method = value;
+            const name = String(prop);
+            return (...args) => wrap(() => method.apply(target, args), name);
+        },
+    });
+}
+/** Wrap a synchronous client so every method returns a `Result<T, GhFailure>`. */
+export function triedSync(client) {
+    return facade(client, (call) => {
+        try {
+            return ok(call());
+        }
+        catch (error) {
+            if (isGhFailure(error))
+                return err(failureOf(error));
+            throw error;
+        }
+    });
+}
+/** Wrap an awaitable client so every method promises a `Result<T, GhFailure>`. */
+export function triedAsync(client) {
+    return facade(client, async (call) => {
+        try {
+            return ok(await call());
+        }
+        catch (error) {
+            if (isGhFailure(error))
+                return err(failureOf(error));
+            throw error;
+        }
+    });
+}
+function checkSoft(name) {
+    if (!SOFT_METHODS.includes(name)) {
+        throw new TypeError(`gh.soft.${name} has no soft form; call it through gh.try (or the plain method) instead`);
+    }
+}
+/** Wrap a synchronous client so a failed query returns `null`. */
+export function softSync(client) {
+    return facade(client, (call, name) => {
+        checkSoft(name);
+        try {
+            return call();
+        }
+        catch (error) {
+            if (isGhFailure(error))
+                return null;
+            throw error;
+        }
+    });
+}
+/** Wrap an awaitable client so a failed query resolves to `null`. */
+export function softAsync(client) {
+    return facade(client, async (call, name) => {
+        checkSoft(name);
+        try {
+            return await call();
+        }
+        catch (error) {
+            if (isGhFailure(error))
+                return null;
+            throw error;
+        }
+    });
+}

package/dist/failure.d.ts

@@ -0,0 +1,59 @@
+/**
+ * {@link GhFailure}: a failed `gh` call, classified. The `gh.try.*` door
+ * returns 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`
+ * with `gh`'s first stderr line, never a wrong kind.
+ */
+import { type CommandFailed, type CommandFailureKind } from '@osdlc/command-seam';
+import { type Failure } from '@osdlc/result';
+/**
+ * Why a `gh` call failed:
+ *
+ * - everything `@osdlc/command-seam` reports (`not-installed`, `not-executable`,
+ *   `bad-cwd`, `timeout`, `output-cap`, `signal`, `aborted`, `spawn`, `exit`);
+ * - `not-authenticated`: `gh` has no usable credentials, or GitHub refused
+ *   them ("gh auth login", "HTTP 401", "HTTP 403", "Bad credentials"). A 403 that
+ *   is a rate limit stays `rate-limited`;
+ * - `network`: GitHub could not be reached ("error connecting to
+ *   api.github.com", "Could not resolve host", "dial tcp", "i/o timeout");
+ * - `not-found`: GitHub has no such thing, or hides it ("Could not resolve to a
+ *   PullRequest", "HTTP 404", "no pull requests found for branch");
+ * - `rate-limited`: "API rate limit exceeded", "secondary rate limit", "HTTP 429";
+ * - `unreadable`: `gh` exited 0 but its output could not be read completely
+ *   (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. */
+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. */
+    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. */
+    cause?: CommandFailed | undefined;
+}
+/** What a verb that reads one thing asks GitHub for. */
+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.
+ *
+ * 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
+ * wrong repository rather than a missing pull request, so it is a `not-found`
+ * failure and not absence. Likewise a bare `HTTP 404` does not say which part
+ * of the request was missing.
+ */
+export declare function isAbsent(thing: Thing, text: string): boolean;
+/** The gh failure for a failed `gh` run. */
+export declare function classifyGhFailure(failed: CommandFailed): GhFailure;
+/** The failure for a run that exited 0 but whose output the verb could not read. */
+export declare function unreadableFailure(argv: readonly string[], stdout: string, binary: string | undefined): GhFailure;

package/dist/failure.js

@@ -0,0 +1,93 @@
+/**
+ * {@link GhFailure}: a failed `gh` call, classified. The `gh.try.*` door
+ * returns 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`
+ * with `gh`'s first stderr line, never a wrong kind.
+ */
+import { classifyFailure } from '@osdlc/command-seam';
+import {} from '@osdlc/result';
+const INSTALL_HINT = 'Install it from https://cli.github.com, then run `gh auth login`.';
+const RATE_LIMITED = /API rate limit exceeded|secondary rate limit|rate limit exceeded|HTTP 429/i;
+const NOT_AUTHENTICATED = /gh auth login|HTTP 401|HTTP 403|Bad credentials|authentication required|not logged in/i;
+const NETWORK = /error connecting to|Could not resolve host|no such host|dial tcp|i\/o timeout|network is unreachable|connection refused/i;
+const NOT_FOUND = /Could not resolve to an? [A-Za-z]+|HTTP 404|no pull requests found for branch|\(HTTP 404\)|Not Found/;
+const ABSENT = {
+    pr: /Could not resolve to a PullRequest|no pull requests found for branch/,
+    issue: /Could not resolve to an Issue/,
+    repo: /Could not resolve to a Repository/,
+};
+/**
+ * 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.
+ *
+ * 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
+ * wrong repository rather than a missing pull request, so it is a `not-found`
+ * failure and not absence. Likewise a bare `HTTP 404` does not say which part
+ * of the request was missing.
+ */
+export function isAbsent(thing, text) {
+    return ABSENT[thing].test(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
+    // messages say `gh` rather than "The command".
+    const f = failed.binary === undefined
+        ? (classifyFailure(failed.result, { binary: 'gh', argv: failed.argv }) ?? failed.failure)
+        : failed.failure;
+    const base = { ...f, cause: failed };
+    if (f.kind === 'not-installed')
+        return { ...base, hint: INSTALL_HINT };
+    if (f.kind !== 'exit')
+        return base;
+    const text = `${failed.result.stderr}\n${failed.result.stdout}`;
+    if (RATE_LIMITED.test(text)) {
+        return {
+            ...base,
+            kind: 'rate-limited',
+            message: "GitHub's API rate limit was reached.",
+            hint: 'Wait a few minutes and try again.',
+        };
+    }
+    if (NOT_AUTHENTICATED.test(text)) {
+        return {
+            ...base,
+            kind: 'not-authenticated',
+            message: 'gh is not signed in to GitHub.',
+            hint: 'Run `gh auth login`.',
+        };
+    }
+    if (NETWORK.test(text)) {
+        return {
+            ...base,
+            kind: 'network',
+            message: 'GitHub could not be reached.',
+            hint: 'Check your network connection.',
+        };
+    }
+    if (NOT_FOUND.test(text)) {
+        return {
+            ...base,
+            kind: 'not-found',
+            message: 'GitHub has no such pull request, issue or repository, or you cannot see it.',
+            hint: 'Check the number or name, and that your account can see the repository.',
+        };
+    }
+    return base;
+}
+/** The failure for a run that exited 0 but whose output the verb could not read. */
+export function unreadableFailure(argv, stdout, binary) {
+    return {
+        kind: 'unreadable',
+        message: 'gh answered, but its output could not be read completely.',
+        ...(stdout.trim() === '' ? {} : { detail: stdout.trim().slice(0, 2000) }),
+        binary: binary ?? 'gh',
+        argv: [...argv],
+        exitCode: 0,
+    };
+}

package/dist/index.d.ts

@@ -11,16 +11,20 @@
  *   - **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`, tri-modal like `Git`: queries return parsed values
- *     and never throw, mutations throw `CommandFailed`, `raw` is the hatch.
+ *   - **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.
  *
  * Authentication is `gh`'s. No token is read, stored, or forwarded.
  */
-export { AsyncGh, type AsyncCallOptions } from './async.ts';
-export { Gh, defaultRunnerFactory, type RunnerFactory } from './sync.ts';
-export { api, authStatus, createPr, editPr, editPrBody, createLabel, createReview, editLabel, installed, issueList, issueView, labelList, openPrsForBranch, pickPrForBranch, prBody, prComment, prSetDraft, issueCommentEdit, prDiff, prList, prMerge, prReviewThreads, prUpdateBranch, prView, setIssueLabel, PR_LIST_FIELDS, PR_REF_FIELDS, PR_VIEW_FIELDS, type ApiOptions, type ApiResponse, type AuthStatus, type CreateLabelOptions, type CreatePrOptions, type CreateReviewOptions, type GhVerb, type IssueListOptions, type PrListOptions, type PrMergeMethod, type ReviewComment, type ReviewThread, } from './verbs.ts';
+export { AsyncGh, type AsyncCallOptions, type AsyncGhOptions } from './async.ts';
+export { classifyGhFailure, type GhFailure, type GhFailureKind } from './failure.ts';
+export { type Soft, type TriedAsync, type TriedSync } from './doors.ts';
+export { Gh, defaultRunnerFactory, type GhOptions, type RunnerFactory } from './sync.ts';
+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, type ApiOptions, type ApiResponse, type AuthStatus, type CreateLabelOptions, type CreatePrOptions, type CreateReviewOptions, type GhTarget, type GraphqlOptions, type GraphqlVariable, type GhVerb, type IssueListOptions, type ListResult, type PrListOptions, type PrMergeMethod, type RepoListOptions, type ReviewComment, type ReviewThread, type SearchPrsOptions, } from './verbs.ts';
 export { anyCheckFailed, normalizeAuthorLogin, parsePullRequest } from './parse.ts';
-export { ownerRepoSlug, parseOwnerRepo, parsePrUrl, type PullRequestRef } from './repo.ts';
-export type { Actor, CheckConclusion, CheckRun, Comment, IssueRow, Label, MergeableState, MergeStateStatus, OwnerRepo, PullRequest, PullRequestState, Review, ReviewDecision, ReviewState, } from './types.ts';
+export { ownerRepoSlug, parseOwnerRepo, parsePrRef, parsePrUrl, type PrRef, type PullRequestRef, } from './repo.ts';
+export type { Actor, CheckConclusion, CheckRun, Comment, IssueRow, Label, MergeableState, MergeStateStatus, OwnerRepo, PullRequest, PrSearchHit, PullRequestState, Repository, RepositoryVisibility, Review, ReviewDecision, ReviewState, } from './types.ts';
 export { CommandFailed, type AsyncCommandRunner, type CommandResult, type CommandRunner, type CommandRunOptions, } from '@osdlc/command-seam';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -11,16 +11,21 @@
  *   - **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`, tri-modal like `Git`: queries return parsed values
- *     and never throw, mutations throw `CommandFailed`, `raw` is the hatch.
+ *   - **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.
  *
  * Authentication is `gh`'s. No token is read, stored, or forwarded.
  */
 export { AsyncGh } from "./async.js";
+export { classifyGhFailure } from "./failure.js";
+export {} from "./doors.js";
 export { Gh, defaultRunnerFactory } from "./sync.js";
-export { api, authStatus, createPr, editPr, editPrBody, createLabel, createReview, editLabel, installed, issueList, issueView, labelList, openPrsForBranch, pickPrForBranch, prBody, prComment, prSetDraft, issueCommentEdit, prDiff, prList, prMerge, prReviewThreads, prUpdateBranch, prView, setIssueLabel, PR_LIST_FIELDS, PR_REF_FIELDS, PR_VIEW_FIELDS, } from "./verbs.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, parsePrUrl } from "./repo.js";
+export { ownerRepoSlug, parseOwnerRepo, parsePrRef, parsePrUrl, } from "./repo.js";
 // The 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`.

package/dist/parse.d.ts

@@ -17,7 +17,7 @@
  *     `StatusContext` carries `context`/`state`. They are folded onto one
  *     verdict axis so a caller never has to know which it got.
  */
-import type { Actor, CheckRun, Label, PullRequest } from './types.ts';
+import type { Actor, CheckRun, Label, PrSearchHit, PullRequest, Repository } from './types.ts';
 /**
  * Strip a single trailing `[bot]` suffix — REST shape folded to GraphQL shape.
  *
@@ -43,4 +43,7 @@ export declare function parseLabels(x: unknown): Label[];
  * any field subset.
  */
 export declare function parsePullRequest(raw: unknown): PullRequest | null;
-//# sourceMappingURL=parse.d.ts.map
+/** A `gh repo list`/`view --json` row as a {@link Repository}, or null without `nameWithOwner`. */
+export declare function parseRepository(raw: unknown): Repository | null;
+/** A `gh search prs --json` row as a {@link PrSearchHit}, or null without a `number`. */
+export declare function parsePrSearchHit(raw: unknown): PrSearchHit | null;

package/dist/parse.js

@@ -223,3 +223,51 @@ export function parsePullRequest(raw) {
         updatedAt: strOrNull(raw['updatedAt'] ?? raw['updated_at']),
     };
 }
+// ── repositories and search ─────────────────────────────────────────────────
+/** A `gh repo list`/`view --json` row as a {@link Repository}, or null without `nameWithOwner`. */
+export function parseRepository(raw) {
+    if (!isRecord(raw))
+        return null;
+    const nameWithOwner = str(raw['nameWithOwner']);
+    const slash = nameWithOwner.indexOf('/');
+    if (slash <= 0 || slash === nameWithOwner.length - 1)
+        return null;
+    const branch = raw['defaultBranchRef'];
+    return {
+        nameWithOwner,
+        owner: nameWithOwner.slice(0, slash),
+        name: nameWithOwner.slice(slash + 1),
+        description: str(raw['description']),
+        defaultBranch: isRecord(branch) ? strOrNull(branch['name']) : null,
+        visibility: strOrNull(raw['visibility']),
+        isArchived: bool(raw['isArchived']),
+        url: str(raw['url']),
+    };
+}
+/** A `gh search prs --json` row as a {@link PrSearchHit}, or null without a `number`. */
+export function parsePrSearchHit(raw) {
+    if (!isRecord(raw))
+        return null;
+    const number = raw['number'];
+    if (typeof number !== 'number')
+        return null;
+    const repo = raw['repository'];
+    const slug = isRecord(repo) ? str(repo['nameWithOwner']) : '';
+    const slash = slug.indexOf('/');
+    return {
+        number,
+        title: str(raw['title']),
+        // Search answers in lower case; `PullRequest.state` is upper case.
+        state: str(raw['state']).toUpperCase(),
+        url: str(raw['url']),
+        isDraft: bool(raw['isDraft']),
+        repository: slash > 0 && slash < slug.length - 1
+            ? { owner: slug.slice(0, slash), repo: slug.slice(slash + 1) }
+            : null,
+        author: parseActor(raw['author']),
+        labels: parseLabels(raw['labels']),
+        createdAt: strOrNull(raw['createdAt']),
+        updatedAt: strOrNull(raw['updatedAt']),
+        closedAt: strOrNull(raw['closedAt']),
+    };
+}

package/dist/repo.d.ts

@@ -15,22 +15,53 @@ import type { OwnerRepo } from './types.ts';
 export declare function parseOwnerRepo(remoteUrl: string): OwnerRepo | null;
 /** `owner/repo`, the form `gh api` paths and `--repo` both take. */
 export declare function ownerRepoSlug(r: OwnerRepo): string;
-/** A pull request coordinate: the repository and the PR's number within it. */
+/** A pull request coordinate: the host, the repository and the PR's number within it. */
 export interface PullRequestRef extends OwnerRepo {
+    /** The GitHub host, lower-cased: `github.com`, or an Enterprise host. */
+    hostname: string;
     number: number;
 }
 /**
- * The `{owner, repo, number}` a GitHub pull-request URL names, or null when
- * `url` is not one.
+ * The `{hostname, owner, repo, number}` a GitHub pull-request URL names, or
+ * null when `url` is not one.
  *
- * Accepts `https://github.com/<owner>/<repo>/pull/<n>` with or without a
- * scheme, a `www.` prefix, a trailing slash, a sub-page (`/files`,
- * `/commits`), a query string or a fragment — every shape a browser's address
- * bar hands over. `parseGitUrl` is the wrong tool here: it reads `/pull/<n>`
+ * Accepts `https://<host>/<owner>/<repo>/pull/<n>` with or without a scheme,
+ * a trailing slash, a sub-page (`/files`, `/commits`), a query string or a
+ * fragment — every shape a browser's address bar hands over. The host is
+ * `github.com` (a `www.` prefix is dropped) or a GitHub Enterprise host such
+ * as `github.acme.com` or `acme.ghe.com`; without a scheme the host must
+ * contain a dot. `parseGitUrl` is the wrong tool here: it reads `/pull/<n>`
  * as part of the project path.
- *
- * GitHub.com only. A GitHub Enterprise host is a different coordinate space
- * (the `gh` CLI needs `--hostname`), so it is not silently accepted.
  */
 export declare function parsePrUrl(url: string): PullRequestRef | null;
-//# sourceMappingURL=repo.d.ts.map
+/**
+ * What a person typed to name a pull request, read by {@link parsePrRef}.
+ *
+ * - `number`: `42`, `#42`, or `owner/name#42` (then `repo` is set). For bare
+ *   digits, `orBranch` holds the same text, since a branch can be named `42`.
+ * - `url`: a pull request URL, with what {@link parsePrUrl} read from it.
+ * - `branch`: any other text that is a valid branch name.
+ */
+export type PrRef = {
+    kind: 'number';
+    number: number;
+    repo: OwnerRepo | null;
+    orBranch: string | null;
+} | ({
+    kind: 'url';
+    url: string;
+} & PullRequestRef) | {
+    kind: 'branch';
+    name: string;
+};
+/**
+ * Read what a person typed to name a pull request: a number, `#42`,
+ * `owner/name#42`, a URL, or a branch name. Null when it is none of these.
+ *
+ * Pure: it starts no process. Digits are read as a number first, the way
+ * `gh pr view 42` reads them; `orBranch` keeps the branch reading. The
+ * clients' `prFind` tries both.
+ */
+export declare function parsePrRef(input: string): PrRef | null;
+/** True for `owner/name` as GitHub spells it. */
+export declare function isRepoSlug(text: string): boolean;

package/dist/repo.js

@@ -26,24 +26,88 @@ export function ownerRepoSlug(r) {
     return `${r.owner}/${r.repo}`;
 }
 /**
- * The `{owner, repo, number}` a GitHub pull-request URL names, or null when
- * `url` is not one.
+ * The `{hostname, owner, repo, number}` a GitHub pull-request URL names, or
+ * null when `url` is not one.
  *
- * Accepts `https://github.com/<owner>/<repo>/pull/<n>` with or without a
- * scheme, a `www.` prefix, a trailing slash, a sub-page (`/files`,
- * `/commits`), a query string or a fragment — every shape a browser's address
- * bar hands over. `parseGitUrl` is the wrong tool here: it reads `/pull/<n>`
+ * Accepts `https://<host>/<owner>/<repo>/pull/<n>` with or without a scheme,
+ * a trailing slash, a sub-page (`/files`, `/commits`), a query string or a
+ * fragment — every shape a browser's address bar hands over. The host is
+ * `github.com` (a `www.` prefix is dropped) or a GitHub Enterprise host such
+ * as `github.acme.com` or `acme.ghe.com`; without a scheme the host must
+ * contain a dot. `parseGitUrl` is the wrong tool here: it reads `/pull/<n>`
  * as part of the project path.
- *
- * GitHub.com only. A GitHub Enterprise host is a different coordinate space
- * (the `gh` CLI needs `--hostname`), so it is not silently accepted.
  */
 export function parsePrUrl(url) {
-    const m = /^(?:https?:\/\/)?(?:www\.)?github\.com\/([^/\s]+)\/([^/\s]+)\/pull\/(\d+)(?:[/?#].*)?$/i.exec(url.trim());
+    const m = /^(?:(https?:)\/\/)?([a-z0-9](?:[a-z0-9.-]*[a-z0-9])?(?::\d+)?)\/([^/\s]+)\/([^/\s]+)\/pull\/(\d+)(?:[/?#].*)?$/i.exec(url.trim());
     if (m === null)
         return null;
-    const number = Number(m[3]);
+    const host = m[2].toLowerCase();
+    if (m[1] === undefined && !host.includes('.'))
+        return null;
+    const number = Number(m[5]);
     if (!Number.isSafeInteger(number) || number <= 0)
         return null;
-    return { owner: m[1], repo: m[2].replace(/\.git$/, ''), number };
+    return {
+        hostname: host === 'www.github.com' ? 'github.com' : host,
+        owner: m[3],
+        repo: m[4].replace(/\.git$/, ''),
+        number,
+    };
+}
+/**
+ * Read what a person typed to name a pull request: a number, `#42`,
+ * `owner/name#42`, a URL, or a branch name. Null when it is none of these.
+ *
+ * Pure: it starts no process. Digits are read as a number first, the way
+ * `gh pr view 42` reads them; `orBranch` keeps the branch reading. The
+ * clients' `prFind` tries both.
+ */
+export function parsePrRef(input) {
+    const text = input.trim();
+    const digits = /^(#?)(\d+)$/.exec(text);
+    if (digits !== null) {
+        const number = Number(digits[2]);
+        if (Number.isSafeInteger(number) && number > 0) {
+            return { kind: 'number', number, repo: null, orBranch: digits[1] === '' ? text : null };
+        }
+    }
+    const qualified = /^([^/\s#]+)\/([^/\s#]+)#(\d+)$/.exec(text);
+    if (qualified !== null) {
+        const number = Number(qualified[3]);
+        if (!Number.isSafeInteger(number) || number <= 0)
+            return null;
+        if (!isRepoSlug(`${qualified[1]}/${qualified[2]}`))
+            return null;
+        return {
+            kind: 'number',
+            number,
+            repo: { owner: qualified[1], repo: qualified[2] },
+            orBranch: null,
+        };
+    }
+    const url = parsePrUrl(text);
+    if (url !== null)
+        return { kind: 'url', url: text, ...url };
+    return isBranchName(text) ? { kind: 'branch', name: text } : null;
+}
+/** True for `owner/name` as GitHub spells it. */
+export function isRepoSlug(text) {
+    return /^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9_.][A-Za-z0-9_.-]*$/.test(text);
+}
+/**
+ * True when `name` is a branch name git would accept (`git check-ref-format
+ * --branch`), and does not start with `-`, so it cannot read as a flag.
+ */
+function isBranchName(name) {
+    if (name === '' || name === '@' || name.startsWith('-') || name.startsWith('/'))
+        return false;
+    if (name.endsWith('/') || name.endsWith('.'))
+        return false;
+    // Control characters, space, and the characters git reserves.
+    // oxlint-disable-next-line no-control-regex
+    if (/[\x00-\x20\x7f~^:?*[\\]/.test(name))
+        return false;
+    if (name.includes('..') || name.includes('@{') || name.includes('//'))
+        return false;
+    return name.split('/').every((part) => !part.startsWith('.') && !part.endsWith('.lock'));
 }