@gitkraken/core-gitlens 0.5.108 → 0.5.109

package/dist/plus/git-github/api/github.js

@@ -8,8 +8,10 @@ import { graphql, GraphqlResponseError } from '@octokit/graphql';
 import { request } from '@octokit/request';
 import { RequestError } from '@octokit/request-error';
 import { AuthenticationError, AuthenticationErrorReason, RequestClientError, RequestNotFoundError, RequestRateLimitError, } from '../../../git/errors.js';
+import { defaultIssueSort } from '../../../git/models/issue.js';
 import { PullRequestMergeMethod } from '../../../git/models/pullRequest.js';
 import { getGitHubNoReplyAddressParts } from '../../../git/remotes/github.js';
+import { effectiveIssueSort, getIssueComparator } from '../../../git/utils/issue.utils.js';
 import { createRevisionRange, getRevisionRangeParts, isRevisionRange, isSha, } from '../../../git/utils/revision.utils.js';
 import { chunk } from '../../../utils/array.js';
 import { base64 } from '../../../utils/base64.js';
@@ -24,9 +26,18 @@ import { parseUri } from '../../../utils/uri.js';
 import { fromString, satisfies } from '../../../utils/version.js';
 import { fromGitHubIssue, fromGitHubIssueOrPullRequestState, fromGitHubPullRequest, fromGitHubPullRequestLite, } from '../models.js';
 import { githubSearchResultLimit } from './config.js';
-import { gitHubIssueSearchRelationships, toGitHubIssueSearchQualifiers, toGitHubIssueSearchScopeQualifiers, } from './issueSearchQuery.js';
+import { gitHubIssueSearchRelationships, toGitHubIssueSearchQualifiers, toGitHubIssueSearchScopeQualifiers, toGitHubIssueSortQualifier, } from './issueSearchQuery.js';
 import { toGitHubPullRequestSearchFacets } from './pullRequestSearchQuery.js';
 const emptyPagedResult = Object.freeze({ values: [] });
+/**
+ * What an issue-search cursor records when the caller asked for no ordering at all.
+ *
+ * A sentinel rather than an omitted field, because omitted already means something else and more important: a
+ * cursor persisted before ordering existed. Distinguishing the two is what lets an old cursor keep resuming while
+ * a genuine change from unordered to ordered is still refused. Not an `IssueSorting`, so it can never collide
+ * with one.
+ */
+const unsortedCursorSort = 'unsorted';
 const emptyBlameResult = Object.freeze({ ranges: [] });
 // Transient gateway/network failures (e.g. an upstream `502 Bad Gateway`) are worth a few quick
 // retries before surfacing to the caller. octokit provides no built-in retry for the standalone
@@ -2239,6 +2250,16 @@ export class GitHubApi {
     async searchMyPullRequests(provider, token, options, cancellation) {
         return (await this.searchMyPullRequestsPage(provider, token, options, cancellation)).values;
     }
+    /**
+     * The current user's issues: authored ∪ assigned ∪ mentioned, each its own aliased search behind one composite
+     * cursor. Bound to `@me` by construction, unlike {@link searchIssuesPage}.
+     *
+     * Ordering is OPT-IN here, and that asymmetry with {@link searchIssuesPage} is deliberate: this read has never
+     * requested a sort, so GitHub has always answered it in relevance order. Emitting a default would change which
+     * issues its already-shipped consumers see, so an omitted `sort` still emits no `sort:` qualifier at all and
+     * keeps today's result. Pass one to get a defined order — which is also what makes a page budget meaningful,
+     * since relevance ranking can shift under an unchanged upstream.
+     */
     async searchMyIssues(provider, token, options, cancellation) {
         let search = options?.search?.trim() ?? '';
         if (options?.user) {
@@ -2248,7 +2269,10 @@ export class GitHubApi {
             const repo = '  repo:';
             search += `${repo}${options.repos.join(repo)}`;
         }
-        const baseFilters = 'type:issue is:open archived:false';
+        // A requested sort goes through the same table `searchIssuesPage` uses, so the two GitHub issue reads can't
+        // diverge the first time a key is added. Omitted appends nothing — see this method's contract above.
+        const sortQualifier = toGitHubIssueSortQualifier(options?.sort);
+        const baseFilters = ['type:issue is:open archived:false', sortQualifier].filter(Boolean).join(' ');
         // `includeAllAssignees` broadens the assigned category from "assigned to me" to "assigned to anyone"
         // (`assignee:*` is GitHub's has-any-assignee qualifier). Authored/mentioned stay bound to `@me` — they're
         // user-relative by definition, so an all-assignees read still only surfaces the current user's authored
@@ -2283,25 +2307,45 @@ export class GitHubApi {
         if (requested.authored) {
             searches.push({ alias: 'authored', query: `${search} ${baseFilters} author:@me`.trim() });
         }
-        return this.searchIssuesByAlias(provider, token, searches, options, cancellation);
+        // Field by field, like `searchIssuesPage`: `options` also carries `repos`/`includeAllAssignees`/`categories`,
+        // already folded into `searches[].query` above and undeclared by the callee.
+        return this.searchIssuesByAlias(provider, token, searches, {
+            baseUrl: options?.baseUrl,
+            avatarSize: options?.avatarSize,
+            includeBody: options?.includeBody,
+            cursor: options?.cursor,
+            sort: options?.sort,
+            // This read emitted no `sort:` qualifier at all before ordering existed, so a cursor with no
+            // recorded key came out of a relevance-ordered walk.
+            legacySort: unsortedCursorSort,
+        }, cancellation);
     }
     /**
      * The filtered issue search: issues matching structured criteria over a repository/org scope, with no forced
      * relationship to the current user. The issue counterpart of {@link searchMyPullRequestsPage}, and distinct
      * from {@link searchMyIssues}, which is permanently bound to `@me`.
      *
-     * Ordering is part of the contract, not an option: always `sort:updated` (most recently updated first). A
-     * consumer's "show the N most recent" policy at GitHub's result ceiling is only correct under a guaranteed
-     * order, and an option would let a caller pick relevance order and then truncate to an arbitrary subset.
+     * Ordering is `criteria.sort`, defaulting to most-recently-updated-first — the order this read served before
+     * ordering was an option, so an omitted `sort` emits the identical query. What is NOT optional is that SOME
+     * order is always requested: without one GitHub answers in relevance order, and at the result ceiling that
+     * makes which rows are reachable a function of GitHub's ranking rather than of the request. A key GitHub can't
+     * express (`closed`, `priority`, …) is refused by the facade before the request, not silently downgraded.
+     *
+     * With more than one relationship the page is a UNION of several searches, each ordered by the provider; the
+     * merged page is re-sorted here so the whole page honors the requested key. Across pages the order is still
+     * per-alias — see {@link searchIssuesByAlias}.
      *
      * Each requested relationship becomes its own aliased search, unioned and deduped by url; with none, a single
      * search runs over the scope alone. `criteria.text` and the other free-form values are sanitized so user input
      * cannot inject a qualifier and re-scope the search — see {@link toGitHubIssueSearchQualifiers}.
      */
     async searchIssuesPage(provider, token, options, cancellation) {
+        // Resolved once: the emitted qualifier, the merged page's comparator and the cursor's fingerprint must all
+        // be the same key, which is what `effectiveIssueSort` exists to guarantee.
+        const sort = effectiveIssueSort(options?.criteria?.sort);
         const base = [
             ...toGitHubIssueSearchScopeQualifiers(options?.org, options?.repos),
-            ...toGitHubIssueSearchQualifiers(options?.criteria),
+            ...toGitHubIssueSearchQualifiers(options?.criteria, sort),
         ].join(' ');
         // One aliased search per relationship, OR-ed by union. They can't be one query: GitHub AND-s qualifiers,
         // so `author:@me assignee:@me` would return the intersection — issues the user both opened and is assigned
@@ -2313,7 +2357,21 @@ export class GitHubApi {
                 query: `${base} ${gitHubIssueSearchRelationships[r].qualifier}`.trim(),
             }))
             : [{ alias: 'matched', query: base }];
-        return this.searchIssuesByAlias(provider, token, searches, options, cancellation);
+        // Forwarded field by field rather than spread: `options` also carries `repos`/`org`/`criteria`, which are
+        // already baked into `searches[].query` above and which the callee declares nothing about. `sort` is the
+        // EFFECTIVE key, since the merged page and the cursor's fingerprint must both use the one the query used.
+        return this.searchIssuesByAlias(provider, token, searches, {
+            baseUrl: options?.baseUrl,
+            avatarSize: options?.avatarSize,
+            includeBody: options?.includeBody,
+            cursor: options?.cursor,
+            pageSize: options?.pageSize,
+            sort: sort,
+            // This read has always emitted `sort:updated`, which is `defaultIssueSort` — so a cursor with no
+            // recorded key came out of a walk under exactly that key, and only a caller asking for a
+            // different one has to restart.
+            legacySort: defaultIssueSort,
+        }, cancellation);
     }
     /**
      * Counts issues for several scopes in ONE request, transferring no issues at all — each scope is an aliased
@@ -2332,9 +2390,12 @@ export class GitHubApi {
         if (scopes.length === 0)
             return [];
         const queries = scopes.map(s => {
+            // The same resolved key the search would use, so the count previews the query it previews. Ordering
+            // cannot change a total, but emitting a DIFFERENT qualifier string than the search does would break the
+            // parity this probe is for.
             const qualifiers = [
                 ...toGitHubIssueSearchScopeQualifiers(s.org, s.repos),
-                ...toGitHubIssueSearchQualifiers(s.criteria),
+                ...toGitHubIssueSearchQualifiers(s.criteria, effectiveIssueSort(s.criteria?.sort)),
             ];
             // A relationship set is OR-ed across searches, which a single count can't express — the facade splits
             // such a scope into one count per relationship before calling, so at most one is present here.
@@ -2384,8 +2445,17 @@ export class GitHubApi {
      * {@link searchMyIssues} is one configuration of it (its three `@me` categories), and its alias names are
      * that read's published cursor keys.
      *
-     * `searches` must have unique aliases, each a valid GraphQL name that is neither `page` nor `truncated` —
-     * the composite cursor keys aliases at its top level, alongside those two reserved fields.
+     * `searches` must have unique aliases, each a valid GraphQL name that is none of `page`, `truncated` or
+     * `sort` — the composite cursor keys aliases at its top level, alongside those three reserved fields.
+     *
+     * `sort` is the order the caller asked for, which this does two things with. Each alias comes back ordered by
+     * it (the qualifier is already in `searches[].query`), but the UNION of several aliases is not, so the merged
+     * page is re-sorted here; and the key is recorded in the cursor, so a continuation that changed it THROWS
+     * rather than serving a sequence with gaps and repeats. Omitted means the caller asked for no order at all
+     * ({@link searchMyIssues}'s default), which re-sorts nothing and pins nothing.
+     *
+     * `legacySort` is the order the calling read produced BEFORE this field existed, and is what a cursor with no
+     * recorded key is compared against — such a cursor is not of unknown order, it is of that read's old one.
      */
     async searchIssuesByAlias(provider, token, searches, options, cancellation) {
         const scope = getScopedLogger();
@@ -2394,10 +2464,19 @@ export class GitHubApi {
         // by a cursor string that reads back as page 1, restarting the walk with no error and no truncation flag.
         // Cheap to check, and it fails at the one call that introduced the collision rather than in a consumer's
         // persisted cursor.
-        const reserved = searches.filter(s => s.alias === 'page' || s.alias === 'truncated');
+        const reserved = searches.filter(s => s.alias === 'page' || s.alias === 'truncated' || s.alias === 'sort');
         if (reserved.length > 0) {
             throw new Error(`Issue search alias(es) ${reserved.map(s => `'${s.alias}'`).join(', ')} collide with the composite cursor's reserved keys`);
         }
+        // A key GitHub cannot express emits no `sort:` qualifier, so each alias would come back in RELEVANCE order
+        // while the union below is sorted by that key and the cursor sealed under it: an arbitrary subset,
+        // presented as ordered, resumable only into more of the same. Refused here rather than downgraded, which
+        // is the rule the whole feature is built on. Unreachable through the facade — no `supportedIssueSorts`
+        // table declares a key without a qualifier — so this guards the direct callers of the two public reads,
+        // where `title` is expressible enough to have a comparator and not enough to be a GitHub search qualifier.
+        if (options.sort != null && toGitHubIssueSortQualifier(options.sort) == null) {
+            throw new Error(`GitHub cannot order an issue search by '${options.sort}'`);
+        }
         let cursor;
         if (options?.cursor != null) {
             try {
@@ -2405,6 +2484,28 @@ export class GitHubApi {
             }
             catch { }
         }
+        // The order this request is being made under, as the cursor records it.
+        const requestedSort = options.sort ?? unsortedCursorSort;
+        // A cursor produced under a DIFFERENT order can't be resumed: every alias would continue from a position in
+        // a differently-ordered result set, so the continuation re-emits rows already seen and skips rows never
+        // seen. REFUSED rather than silently restarted from page 1, because a restart cannot be reported honestly
+        // from here: this read is cursor-only, so `resolveCurrentPage` has no page of its own to trust and echoes
+        // the `page` the caller supplied alongside the cursor — page 1's rows would be published as page N, which
+        // is the very confusion the fingerprint exists to prevent. Refusing surfaces a warning + `fetchFailed`, and
+        // the remedy ("drop the cursor") is the caller's to apply.
+        //
+        // A cursor with NO recorded sort predates this field — which is not the same as being of unknown order.
+        // Each read produced exactly one order before ordering was an option (`sort:updated` for the filtered
+        // search, relevance for `searchMyIssues`), so an absent key reads as THAT one, `legacySort`. Compared
+        // rather than waved through: the facade now resolves an omitted key to `defaultIssueSort`, so the
+        // account-wide read's query gained a `sort:updated` qualifier it did not have, and resuming a
+        // relevance-ordered cursor inside it advances each alias through a re-ordered result set — the gaps and
+        // repeats this check exists to prevent, arriving through the very case meant to keep working. A cursor
+        // whose implied key matches the request still resumes, and is sealed with the current one.
+        const cursorSort = cursor?.sort ?? options.legacySort;
+        if (cursor != null && cursorSort !== requestedSort) {
+            throw new Error(`Issue search cursor was produced under sort '${cursorSort}' but '${requestedSort}' was requested; restart the read without a cursor`);
+        }
         const page = Math.max(1, Math.trunc(cursor?.page ?? 1));
         // A slot is a continuation string, `null` (exhausted), or absent. Anything else came from a malformed or
         // foreign cursor, and is read as absent rather than threaded back into the request as a continuation.
@@ -2481,11 +2582,32 @@ export class GitHubApi {
             }
             // Dedupe by `url`, not `IssueShape.id`: for some providers `id` is a per-repository number, so an
             // id-keyed map would collapse distinct issues across repositories.
-            const results = uniqueBy(issues, r => r.url, (original, _current) => original);
+            const deduped = [
+                ...uniqueBy(issues, r => r.url, (original, _current) => original),
+            ];
+            // Each alias arrived ordered by the server; their concatenation is not, so the merged page is ordered
+            // here. AFTER the dedupe, not before, and that ordering is load-bearing: the alias order is also the
+            // dedupe's precedence (an issue both assigned to and authored by the user surfaces as the assigned one,
+            // per `searchMyIssues`), and sorting first would hand `uniqueBy` a different first occurrence and
+            // silently change which copy wins. The pull-request path sorts BEFORE its dedupe because its facets
+            // carry no such precedence — the difference is deliberate, not an inconsistency to tidy up.
+            //
+            // A comparator is always available for a key GitHub declares (`created`/`updated`/`comments`/
+            // `reactions` are all on `IssueShape`), so `undefined` here means the capability table has outrun this
+            // read; leave the provider's per-alias order rather than inventing one.
+            //
+            // Counted over `active`, not `searches`: continuations exhaust aliases one at a time, so a later page of
+            // a three-category walk can come from ONE surviving search — already ordered by the server. Re-sorting
+            // it could only reproduce that order, while hiding a provider that ignored the qualifier.
+            const comparator = options?.sort != null ? getIssueComparator(options.sort) : undefined;
+            if (comparator != null && active.length > 1) {
+                deduped.sort(comparator);
+            }
             // Every alias gets a slot, so an inactive one keeps its `null` and stays out of the next request. A
             // missing slot would be read as "never requested", which for a `searches` set that still lists it
             // would restart it from its first page.
-            const next = { page: page + 1 };
+            // The order is pinned on the way out too, so the next round can refuse a changed key (see above).
+            const next = { page: page + 1, sort: requestedSort };
             let hasMore = false;
             let continuationMissing = false;
             let maxIssueCount = 0;
@@ -2507,7 +2629,7 @@ export class GitHubApi {
             const truncated = cursor?.truncated === true || maxIssueCount > githubSearchResultLimit || continuationMissing;
             next.truncated = truncated || undefined;
             return {
-                values: [...results],
+                values: deduped,
                 cursor: hasMore ? JSON.stringify(next) : undefined,
                 hasMore: hasMore,
                 page: page,