@gitkraken/core-gitlens 0.5.107 → 0.5.109

package/src/plus/integrations/reads/filters.ts

@@ -4,6 +4,7 @@ import type {
 	IssueSearchCapabilities,
 	IssueSearchCriteria,
 	IssueSearchRelationship,
+	IssueSorting,
 	PullRequestFilter,
 	PullRequestSearchCapabilities,
 	PullRequestSearchCriteria,
@@ -237,6 +238,12 @@ export function resolveIssueSearchCriteria(
 	if (criteria.state != null && criteria.state !== 'open' && !supported.states) {
 		unsupported.push('state');
 	}
+	// Folded into the same `unsupported-criteria` rejection rather than given its own reason, so a caller asking
+	// for one inexpressible filter and one inexpressible sort learns about both at once instead of fixing them one
+	// refusal at a time. The `sorts` list is `supported`'s own, so this needs no branch on which surface it is.
+	if (criteria.sort != null && !supported.sorts.includes(criteria.sort)) {
+		unsupported.push(`sort:${criteria.sort}`);
+	}
 
 	if (unsupported.length > 0) return { rejection: { reason: 'unsupported-criteria', criteria: unsupported } };
 
@@ -264,6 +271,7 @@ const unsupportedIssueSearchCapabilities: IssueSearchCapabilities = {
 	createdAfter: false,
 	withoutLinkedPullRequest: false,
 	states: false,
+	sorts: [],
 };
 
 /** What a provider with no filtered pull-request search reports. */
@@ -313,6 +321,57 @@ export function resolveIssueSearchScope(
 	return { rejection: 'unscoped' };
 }
 
+/**
+ * What {@link getSupportedFilters} reports: every vocabulary a provider's reads can express, so a consumer can
+ * narrow to it BEFORE issuing a read. See that function for the capability table itself and why intersecting
+ * against this is what keeps a filtered read from being refused.
+ *
+ * Named rather than written inline, because the same shape is the declared return type of THREE declarations that
+ * all describe one value — this function, `IntegrationService.getSupportedFilters`, which only forwards to it, and
+ * `IntegrationManager.getSupportedFilters`, which publishes it. Spelled out three times, a member added here
+ * reached one of them and left the others a compile error away from the truth; that is exactly how the two sort
+ * members below came to be written out three times.
+ */
+export type SupportedFilters = {
+	pullRequests: PullRequestFilter[];
+	pullRequestsAccountWide: PullRequestFilter[];
+	/**
+	 * Criteria and scopes the filtered pull-request search can express. Always present; an empty relationship list
+	 * means the provider exposes no filtered pull-request search.
+	 */
+	pullRequestSearch: PullRequestSearchCapabilities;
+	/**
+	 * Filters the repo-scoped issue read accepts — and, for an issue tracker (Jira/Linear/Trello), its
+	 * project-scoped read, that being its only issue surface. A tracker therefore reports here and leaves
+	 * `issuesAccountWide` empty, so intersecting a tracker against that field would read "cannot filter" for a
+	 * provider that filters fine.
+	 */
+	issues: IssueFilter[];
+	issuesAccountWide: IssueFilter[];
+	/**
+	 * What the filtered issue search (and the count probe over the same criteria) can express. Always present: a
+	 * provider with no filtered issue search reports an empty `relationships` and all-false flags, which is the
+	 * signal to hide that surface rather than to hide individual chips.
+	 */
+	issueSearch: IssueSearchCapabilities;
+	/**
+	 * Sort keys the repo-scoped issue read can express — and, for an issue tracker, its project-scoped read. Empty
+	 * means the read can't be ordered, so pass no `sort`.
+	 *
+	 * A key here is expressible on ONE provider query. A page spanning several repositories or projects is a merge,
+	 * and a merge can only order by what a normalized issue carries, so `priority`/`dueDate`/`resolved` are refused
+	 * there even where they are listed. Read one scope at a time to use them.
+	 */
+	issueSorts: IssueSorting[];
+	/**
+	 * Sort keys the account-wide issue read can express — a different vocabulary, not a subset: for GitLab the two
+	 * reads are different APIs. Needs no mergeability caveat, because every account-wide read is a union of several
+	 * queries, so only keys a merge can honor are listed at all. Empty for an issue tracker, which reports under
+	 * `issueSorts`.
+	 */
+	issueSortsAccountWide: IssueSorting[];
+};
+
 /**
  * The filters `listPullRequestsPage`/`listIssuesPage` (and the sweeps) accept for a provider, so a caller can
  * narrow to what the provider can express BEFORE issuing the read.
@@ -345,19 +404,19 @@ export function resolveIssueSearchScope(
  * `pullRequestSearch` describes the separate filtered PR search. Its table declares each criteria vocabulary
  * plus repository/organization scope support; an empty relationship list means the search itself is absent.
  *
+ * `issueSorts` / `issueSortsAccountWide` / `issueSearch.sorts` are the ORDERING vocabulary of those same three
+ * issue reads, split the same way and for the same reason (GitLab's repo-scoped read is GraphQL and its
+ * account-wide read is REST, with genuinely different sort vocabularies). Empty means the read can't be ordered,
+ * so pass no `sort`; a key not listed refuses the whole read exactly like an inexpressible filter. Note a key
+ * listed here is expressible on ONE provider query: a read that fans out across projects can only honor a key
+ * derivable from a normalized issue, so it refuses `priority`/`dueDate`/`resolved` on top of this table.
+ *
  * Note this is a CAPABILITY table — "what the provider can express" — not a recommendation. A consumer
  * matching another tool's behavior may deliberately pass fewer filters than are listed here (or none, where an
  * already-scoped read would only be narrowed by them). Intersecting against this table is what keeps a
  * filtered read from being refused; it isn't a directive to use every filter in it.
  */
-export function getSupportedFilters(providerId: IntegrationIds): {
-	pullRequests: PullRequestFilter[];
-	pullRequestsAccountWide: PullRequestFilter[];
-	pullRequestSearch: PullRequestSearchCapabilities;
-	issues: IssueFilter[];
-	issuesAccountWide: IssueFilter[];
-	issueSearch: IssueSearchCapabilities;
-} {
+export function getSupportedFilters(providerId: IntegrationIds): SupportedFilters {
 	const metadata = providersMetadata[providerId];
 	const issueSearch = metadata?.supportedIssueSearch;
 	const pullRequestSearch = metadata?.supportedPullRequestSearch;
@@ -385,6 +444,9 @@ export function getSupportedFilters(providerId: IntegrationIds): {
 			...issueSearch,
 			// Copied, so mutating the result can't corrupt the metadata table.
 			relationships: [...(issueSearch?.relationships ?? [])],
+			sorts: [...(issueSearch?.sorts ?? [])],
 		},
+		issueSorts: [...(metadata?.supportedIssueSorts ?? [])],
+		issueSortsAccountWide: [...(metadata?.supportedAccountWideIssueSorts ?? [])],
 	};
 }

package/src/plus/integrations/reads/issueTracker.ts

@@ -1,5 +1,5 @@
 import type { CollectionMetadata } from '@gitkraken/provider-apis';
-import type { IssueShape } from '../../../git/models/issue.js';
+import type { IssueShape, IssueSorting } from '../../../git/models/issue.js';
 import type { ResourceDescriptor } from '../../../git/models/resourceDescriptor.js';
 import { mapBounded } from '../../../utils/promise.js';
 import { mergeAssessmentInto } from '../collectionMetadata.js';
@@ -15,7 +15,14 @@ import type { ProviderReadContext } from './context.js';
 import { parseIssueTrackerPageCursor, toIssueTrackerPageCursor } from './cursors.js';
 import { runCaptured } from './drains.js';
 import { projectKey, resourceIdForProject, resourceLabel, resourceMatchesOrg } from './hierarchy.utils.js';
-import { incompleteReadWarning, issueTrackerOnlySurfaceWarning, otherWarning } from './warnings.js';
+import { resolveIssueSort, toIssueOrdering } from './ordering.js';
+import {
+	incompleteReadWarning,
+	issueTrackerOnlySurfaceWarning,
+	otherWarning,
+	unmergeableIssueSortWarning,
+	unsupportedIssueSortWarning,
+} from './warnings.js';
 
 export async function listIssueTrackerIssuesPage(
 	ctx: ProviderReadContext,
@@ -26,6 +33,23 @@ export async function listIssueTrackerIssuesPage(
 		filters?: IssueFilter[];
 		/** Broadens the read to every assignee. Scopes to user-assigned issues when omitted. */
 		includeAllAssignees?: boolean;
+		/**
+		 * How to order the issues, as `field:direction`. Omitted orders most-recently-updated-first where the
+		 * tracker can express it.
+		 *
+		 * Validated against `getSupportedFilters().issues`' sibling `issueSorts` — a tracker reports there, not
+		 * under the account-wide table, because resource -> project IS its only issue surface. A key it can't
+		 * express refuses the read rather than serving a differently-ordered list.
+		 *
+		 * One page can span SEVERAL projects, whose issues are merged here, so a key no normalized issue carries
+		 * (`priority`, `dueDate`, `resolved`) is refused for a multi-project page even though the tracker orders by
+		 * it perfectly well within one project.
+		 *
+		 * Unlike the git-host reads this one is safe to change mid-pagination: its cursor windows PROJECTS and
+		 * drains each to exhaustion, so which projects a round covers doesn't depend on how their issues are
+		 * ordered. Only the order within a page changes.
+		 */
+		sort?: IssueSorting;
 		forceSync?: boolean;
 		page?: number;
 		cursor?: string;
@@ -128,6 +152,19 @@ export async function listIssueTrackerIssuesPage(
 
 	const domain = ctx.domainForRead(integration, options.providerId, options.connectionId);
 
+	// Before any upstream request: the discovery fan-outs below (resources, projects, per-resource accounts) are
+	// three round trips, and an order this tracker can't express refuses the read whatever they return. Placed after
+	// `domain` only because every warning carries it.
+	const resolvedSort = resolveIssueSort(providersMetadata[options.providerId]?.supportedIssueSorts, options.sort);
+	if (resolvedSort.rejection != null) {
+		warnings.push(
+			unsupportedIssueSortWarning(options.providerId, domain, options.connectionId, resolvedSort.rejection),
+		);
+		return emptyPage(true);
+	}
+
+	const sort = resolvedSort.sort;
+
 	await ctx.forceRefreshIfRequested(integration, options.forceSync, options.connectionId);
 
 	const { value: resources, warning: resourcesWarning } = await runCaptured(
@@ -362,6 +399,37 @@ export async function listIssueTrackerIssuesPage(
 		});
 	}
 
+	// A read spanning several projects is a merge, so it can only honor a key a normalized issue carries. Bound here
+	// rather than next to the key's validation above, because the project count is only known now — while still
+	// before any project read, so a refusal costs no request. Refused rather than served as concatenated
+	// per-project runs, which would look ordered without being so.
+	//
+	// Counted over every project the READ covers, not the `scopedProjects` window this page happens to hold: the
+	// window is `itemsPerPage` projects wide, so counting it would refuse a 20-project page and then serve the
+	// final 1-project page of the same paginated call — the same key answered two ways, with the earlier pages'
+	// issues missing from a read that reported success.
+	//
+	// Projects are not the only thing a tracker read merges: a user-scoped read asking for several relationships
+	// issues one provider query PER relationship and unions them within each project (Jira runs one JQL drain per
+	// filter and folds them into one map, in filter order), so a single-project page of two filters is just as
+	// concatenated as a two-project one. Counting only projects published those runs under the requested key.
+	// Not gated on the provider: the two trackers that don't fan out (Linear, Trello) declare `Assignee` as their
+	// only supported filter, so a multi-filter read is already refused above and can never reach this.
+	const mergesFilters = options.includeAllAssignees !== true && (options.filters?.length ?? 0) > 1;
+	const ordering = toIssueOrdering(sort, scopedProjectsWithUsers.length > 1 || mergesFilters);
+	if (ordering.unmergeable != null) {
+		warnings.push(
+			unmergeableIssueSortWarning(
+				options.providerId,
+				domain,
+				options.connectionId,
+				ordering.unmergeable,
+				scopedProjectsWithUsers.length > 1 ? 'projects' : 'filters',
+			),
+		);
+		return emptyPage(true);
+	}
+
 	const perProject = await mapBounded(scopedProjects, providerFanOutConcurrency, async project => ({
 		project: project,
 		...(await runCaptured(options.providerId, domain, options.connectionId, () =>
@@ -370,6 +438,7 @@ export async function listIssueTrackerIssuesPage(
 				{
 					user: userForProject(project),
 					filters: options.filters,
+					sort: sort,
 				},
 				options.connectionId,
 			),
@@ -417,6 +486,11 @@ export async function listIssueTrackerIssuesPage(
 		}
 	}
 
+	// Each provider query arrived ordered by the tracker; the union of them — across projects, and across the
+	// per-relationship queries a multi-filter read fans out into — is not, and the union is what this read
+	// publishes. A no-op when nothing merged, since the tracker already ordered that single run.
+	const orderedItems = ordering.order(items);
+
 	const drainAssessment = mergeAssessmentInto(
 		warnings,
 		options.providerId,
@@ -463,9 +537,9 @@ export async function listIssueTrackerIssuesPage(
 				: [],
 	});
 	return {
-		items: items,
+		items: orderedItems,
 		warnings: warnings,
-		page: { currentPage: page, itemsPerPage: items.length, truncated: projectTruncated || undefined },
+		page: { currentPage: page, itemsPerPage: orderedItems.length, truncated: projectTruncated || undefined },
 		// Failed-project retries alone are manual. Only an untouched project window is automatic progress.
 		hasMore: nextPage != null && cursor != null,
 		cursor: cursor,