@osdlc/typed-gh 0.9.6 → 0.12.0

package/dist/verbs.js

@@ -13,7 +13,7 @@
  * `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 { notAnOption, stderrOrError } from '@osdlc/command-seam';
 import { parseLabels, parsePrSearchHit, parsePullRequest, parseRepository } from "./parse.js";
 import { isAbsent } from "./failure.js";
 import { isRepoSlug, parsePrUrl } from "./repo.js";
@@ -48,16 +48,26 @@ export function checkTarget(target) {
         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. */
-function repoArgs(target, repo) {
+/**
+ * `[host/]owner/name` for `repo` (else the target's repo), the form `--repo`
+ * and `gh repo view` take, or `undefined` when neither names one. The host is
+ * the target's, through {@link hostOf}, so a hostname of `''` is "not set".
+ * Both are checked first.
+ */
+function qualifiedRepo(target, repo) {
     checkTarget(target);
-    const slug = repo ?? target?.repo;
-    if (slug === undefined)
-        return [];
     if (repo !== undefined)
         checkTarget({ repo });
+    const slug = repo ?? target?.repo;
+    if (slug === undefined)
+        return undefined;
     const hostname = hostOf(target);
-    return ['--repo', hostname === undefined ? slug : `${hostname}/${slug}`];
+    return hostname === undefined ? slug : `${hostname}/${slug}`;
+}
+/** `--repo [host/]owner/name` for `pr`, `issue` and `label` verbs. `repo` overrides the target's. */
+function repoArgs(target, repo) {
+    const qualified = qualifiedRepo(target, repo);
+    return qualified === undefined ? [] : ['--repo', qualified];
 }
 /** `--hostname <host>` for `api` and `auth` verbs. */
 function hostArgs(target) {
@@ -144,24 +154,7 @@ function oneOrNull(r) {
  * failed. A caller must be able to tell "no PRs" from "couldn't ask".
  */
 function manyOrNull(r) {
-    if (r.exitCode !== 0)
-        return null;
-    let data;
-    try {
-        data = JSON.parse(r.stdout || '[]');
-    }
-    catch {
-        return null;
-    }
-    if (!Array.isArray(data))
-        return null;
-    const rows = [];
-    for (const item of data) {
-        const pr = parsePullRequest(item);
-        if (pr !== null)
-            rows.push(pr);
-    }
-    return rows;
+    return rowsOrNull(r, (item) => parsePullRequest(item));
 }
 /** Throw `RangeError` unless `limit` is a positive integer. */
 function checkLimit(limit) {
@@ -169,11 +162,23 @@ function checkLimit(limit) {
         throw new RangeError(`limit must be a positive integer, got ${limit}`);
     }
 }
-/** `rows` cut to `limit`, with whether there were more. Null stays null. */
-function limited(rows, limit) {
+/**
+ * The most results GitHub search returns for one query. A call that goes
+ * through search and gets this many rows may have been cut off by search,
+ * whatever the `limit`. gh uses search for `pr list` with a non-empty
+ * `--search` or with `--author`, for `issue list` with `--label`, and for
+ * `search prs`.
+ */
+const SEARCH_RESULT_CAP = 1000;
+/**
+ * `rows` cut to `limit`, with whether there were more. With `cap`, reaching
+ * it counts as more too, since the source stops there. Null stays null.
+ */
+function limited(rows, limit, cap) {
     if (rows === null)
         return null;
-    return { rows: rows.slice(0, limit), truncated: rows.length > limit };
+    const truncated = rows.length > limit || (cap !== undefined && rows.length >= cap);
+    return { rows: rows.slice(0, limit), truncated };
 }
 /** A mutation's result carries no value. */
 function nothing() { }
@@ -232,24 +237,7 @@ function oneIssueOrNull(r) {
  * on failure, as {@link manyOrNull} does for PRs.
  */
 function manyIssuesOrNull(r) {
-    if (r.exitCode !== 0)
-        return null;
-    let data;
-    try {
-        data = JSON.parse(r.stdout || '[]');
-    }
-    catch {
-        return null;
-    }
-    if (!Array.isArray(data))
-        return null;
-    const rows = [];
-    for (const item of data) {
-        const row = parseIssueRow(item);
-        if (row !== null)
-            rows.push(row);
-    }
-    return rows;
+    return rowsOrNull(r, parseIssueRow);
 }
 /** `gh pr list …`: open PRs by default. `opts.repo` overrides the target's repo. */
 export function prList(opts = {}, target) {
@@ -278,7 +266,8 @@ export function prList(opts = {}, target) {
         checked: false,
         readOnly: true,
         parse(r) {
-            const result = limited(manyOrNull(r), limit);
+            // A search stops at 1000 results, so 1000 rows may be a cut, not the end.
+            const result = limited(manyOrNull(r), limit, (opts.search ?? '') !== '' || opts.author !== undefined ? SEARCH_RESULT_CAP : undefined);
             if (result === null || head === undefined)
                 return result;
             return { ...result, rows: result.rows.filter((pr) => pr.headRefName === head) };
@@ -294,9 +283,8 @@ function withFields(fields, required) {
  * argument would read as a flag.
  */
 function notAFlag(what, value) {
-    if (value.startsWith('-')) {
-        throw new RangeError(`${what} must not start with "-", got ${JSON.stringify(value)}`);
-    }
+    const message = (v) => `${what} must not start with "-", got ${JSON.stringify(v)}`;
+    notAnOption(value, (v) => new RangeError(message(v)));
 }
 /**
  * `gh pr view <number|branch|url> --json …`: one PR, with the full field set
@@ -313,15 +301,14 @@ export function prView(ref, fields = PR_VIEW_FIELDS, target) {
     // omits it would read as "no such PR". Always ask for it, and each field once.
     const asked = withFields(fields, ['number']);
     const isUrl = typeof ref === 'string' && parsePrUrl(ref) !== null;
+    // gh reads a selector as a URL only with an http(s) scheme; a scheme-less
+    // one (`github.com/o/r/pull/7`, which parsePrUrl accepts) would be taken as
+    // a branch name.
+    const selector = typeof ref === 'string' && isUrl && !/^https?:\/\//i.test(ref.trim())
+        ? `https://${ref.trim()}`
+        : String(ref);
     return {
-        argv: [
-            'pr',
-            'view',
-            String(ref),
-            ...(isUrl ? [] : repoArgs(target)),
-            '--json',
-            asked.join(','),
-        ],
+        argv: ['pr', 'view', selector, ...(isUrl ? [] : repoArgs(target)), '--json', asked.join(',')],
         checked: false,
         readOnly: true,
         absent: noSuch('pr'),
@@ -392,6 +379,27 @@ function flattenPages(body) {
         return body;
     return body.flat();
 }
+/**
+ * True when any operation in a GraphQL document is a `mutation` or a
+ * `subscription`. Strings and comments are dropped first, and only the words
+ * outside every `{…}` and `(…)` are read, which is where an operation's
+ * keyword stands. So a leading fragment, a leading `,` (an ignored token) or a
+ * second operation after a query cannot hide one.
+ */
+function writesOrStreams(document) {
+    const code = document.replace(/"""[\s\S]*?"""|"(?:[^"\\\n]|\\.)*"|#[^\n]*/g, ' ');
+    let depth = 0;
+    for (const token of code.matchAll(/[{}()]|[_A-Za-z][_0-9A-Za-z]*/g)) {
+        const t = token[0];
+        if (t === '{' || t === '(')
+            depth += 1;
+        else if (t === '}' || t === ')')
+            depth = Math.max(0, depth - 1);
+        else if (depth === 0 && (t === 'mutation' || t === 'subscription'))
+            return true;
+    }
+    return false;
+}
 /**
  * `gh api graphql -f query=… [--paginate --slurp]`: a GraphQL query.
  *
@@ -401,15 +409,16 @@ function flattenPages(body) {
  * 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`.
+ * target's repo, or by gh from the clone. A document holding any mutation or
+ * subscription throws `RangeError`, as does a variable named `query` or
+ * `operationName`, which gh would send as the request's own fields. This is a
+ * read, and changes go through `raw`.
  *
  * @experimental
  */
 export function graphql(query, variables = {}, opts = {}, target) {
     checkTarget(target);
-    const body = query.replace(/^(?:\s|#[^\n]*\n?)*/, '');
-    if (/^mutation\b/.test(body) || /^subscription\b/.test(body)) {
+    if (writesOrStreams(query)) {
         throw new RangeError('graphql: only queries are allowed; send a mutation through raw');
     }
     const paginate = opts.paginate === true;
@@ -421,7 +430,10 @@ export function graphql(query, variables = {}, opts = {}, target) {
         argv.push('--paginate', '--slurp');
     const [owner, name] = target?.repo?.split('/') ?? [];
     for (const [key, value] of Object.entries(variables)) {
-        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+        // gh lifts `query` and `operationName` out of the variables into the
+        // request itself, so either would replace the checked document or pick
+        // another operation in it.
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || key === 'query' || key === 'operationName') {
             throw new RangeError(`graphql: bad variable name ${JSON.stringify(key)}`);
         }
         if (typeof value === 'string') {
@@ -605,7 +617,14 @@ export function issueList(opts = {}, target) {
     if (opts.label !== undefined)
         argv.push('--label', opts.label);
     argv.push('--json', ISSUE_FIELDS, '--limit', String(limit + 1));
-    return { argv, checked: false, readOnly: true, parse: (r) => limited(manyIssuesOrNull(r), limit) };
+    // gh lists issues by label through search, which stops at 1000 results.
+    const cap = opts.label === undefined ? undefined : SEARCH_RESULT_CAP;
+    return {
+        argv,
+        checked: false,
+        readOnly: true,
+        parse: (r) => limited(manyIssuesOrNull(r), limit, cap),
+    };
 }
 /** `gh issue view <n> --json …`: one issue, same field set as {@link issueList}. */
 export function issueView(number, target) {
@@ -688,14 +707,11 @@ export function repoList(owner, opts = {}, target) {
  * `owner` and `name` are in GitHub's casing, not as passed.
  */
 export function repoView(repo, fields = REPO_FIELDS, target) {
-    checkTarget(target);
-    if (repo !== undefined)
-        checkTarget({ repo });
-    const slug = repo ?? target?.repo;
+    // The same `[host/]owner/name` rule as `--repo`.
+    const qualified = qualifiedRepo(target, repo);
     const argv = ['repo', 'view'];
-    if (slug !== undefined) {
-        argv.push(target?.hostname === undefined ? slug : `${target.hostname}/${slug}`);
-    }
+    if (qualified !== undefined)
+        argv.push(qualified);
     argv.push('--json', withFields(fields, ['nameWithOwner']).join(','));
     return {
         argv,
@@ -737,7 +753,9 @@ export function searchPrs(query, opts = {}, target) {
     else if (opts.state !== undefined)
         argv.push('--state', opts.state);
     argv.push('--json', withFields(opts.fields ?? SEARCH_PR_FIELDS, ['number']).join(','));
-    argv.push('--limit', String(limit + 1));
+    // gh refuses a search limit over 1000, so ask for at most that. 1000 rows
+    // then read as truncated: search may hold more.
+    argv.push('--limit', String(Math.min(limit + 1, SEARCH_RESULT_CAP)));
     if (query !== '')
         argv.push('--', query);
     return {
@@ -745,7 +763,7 @@ export function searchPrs(query, opts = {}, target) {
         checked: false,
         readOnly: true,
         env: hostEnv(target),
-        parse: (r) => limited(rowsOrNull(r, parsePrSearchHit), limit),
+        parse: (r) => limited(rowsOrNull(r, parsePrSearchHit), limit, SEARCH_RESULT_CAP),
     };
 }
 /**
@@ -909,6 +927,7 @@ export function prReviewThreads(number, target) {
  * and description are set to these instead of failing.
  */
 export function createLabel(opts, target) {
+    notAFlag('createLabel name', opts.name);
     const argv = [
         'label',
         'create',
@@ -924,6 +943,7 @@ export function createLabel(opts, target) {
 }
 /** `gh label edit <name>`: change the color or description. A flag not given is left out. */
 export function editLabel(name, opts, target) {
+    notAFlag('editLabel name', name);
     const argv = ['label', 'edit', name, ...repoArgs(target)];
     if (opts.color !== undefined)
         argv.push('--color', opts.color);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/typed-gh",
-  "version": "0.9.6",
+  "version": "0.12.0",
   "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",
@@ -10,6 +10,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
     }
   },
   "files": [
@@ -22,9 +26,9 @@
     "LICENSE-APACHE"
   ],
   "dependencies": {
-    "@osdlc/command-seam": "^0.12.1",
-    "@osdlc/result": "^0.1.0",
-    "@osdlc/typed-git": "^0.8.2"
+    "@osdlc/command-seam": "^0.14.0",
+    "@osdlc/typed-git": "^0.10.0",
+    "@osdlc/result": "^0.1.0"
   },
   "engines": {
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"