@gitkraken/core-gitlens 0.5.108 → 0.5.109

package/src/plus/integrations/providers/models.ts

@@ -75,7 +75,7 @@ import {
 	IssuesCloudHostIntegrationId,
 } from '../constants.js';
 import type { Integration, IntegrationType } from '../models/integration.js';
-import type { IssueSearchCapabilities, PullRequestSearchCapabilities } from '../providerFilters.js';
+import type { IssueSearchCapabilities, IssueSorting, PullRequestSearchCapabilities } from '../providerFilters.js';
 import { IssueFilter, PullRequestFilter } from '../providerFilters.js';
 
 export { IssueFilter, PullRequestFilter } from '../providerFilters.js';
@@ -83,12 +83,25 @@ export type {
 	IssueSearchCapabilities,
 	IssueSearchCriteria,
 	IssueSearchRelationship,
+	IssueSortField,
+	IssueSorting,
 	PullRequestSearchCapabilities,
 	PullRequestSearchCriteria,
 } from '../providerFilters.js';
 import type { ProviderRepositoryShape } from '../results.js';
 
 export type { ProviderOrganization, ProviderRepositoryShape } from '../results.js';
+import {
+	azureAccountWideIssueSorts,
+	azureIssueSorts,
+	githubAccountWideIssueSorts,
+	githubIssueSorts,
+	gitlabAccountWideIssueSorts,
+	gitlabIssueSorts,
+	jiraIssueSorts,
+	linearIssueSorts,
+	trelloIssueSorts,
+} from './issueSorts.js';
 import { getEntityIdentifierInput } from './utils.js';
 
 type GitBuildStatusState = GitBuildStatusStateType;
@@ -156,6 +169,28 @@ type EnrichableItem = any;
 export type ProviderAccount = Account;
 export type ProviderReposInput = (string | number)[] | GetRepoInput[];
 export type ProviderRepoInput = GetRepoInput;
+
+/**
+ * Which half of {@link ProviderReposInput} a caller supplied: repository IDS rather than descriptors.
+ *
+ * The union has no discriminant, so the answer is the element shape — and several layers need it for different
+ * reasons (`ProvidersApi` to pick `repoIds` vs `repos` in the SDK input, `GitHostIntegration` to refuse an
+ * id-based read a provider can't serve, `listIssuesPage` to know GitLab's id form takes the SDK's own merging
+ * aggregate). One predicate rather than one per layer, because each copy is free to disagree about the shape,
+ * and the symptom of disagreement is a read routed to the wrong provider query.
+ *
+ * Takes `unknown` rather than {@link ProviderReposInput} because `ProvidersApi.isRepoIdsInput` forwards here and
+ * is public with an unvalidated parameter, so the array check has to stay part of the rule rather than be assumed
+ * from the parameter type.
+ */
+export function isRepoIdsInput(input: unknown): input is (string | number)[] {
+	return (
+		input != null &&
+		Array.isArray(input) &&
+		input.every(repo => typeof repo === 'string' || typeof repo === 'number')
+	);
+}
+
 export type ProviderPullRequest = GitPullRequest;
 export type ProviderRepository = GitRepository;
 export type ProviderIssue = ProviderApiIssue;
@@ -331,6 +366,20 @@ export interface GetIssuesOptions {
 	page?: number;
 	// Items to request per page (numbered-page providers, plus GitHub's maxPageSize).
 	pageSize?: number;
+	/**
+	 * How the provider should order the result, as `field:direction`.
+	 *
+	 * Passed through to the SDK verbatim — the translation to each provider's own vocabulary lives THERE, next to
+	 * the capability map it validates against, so that the table this facade publishes and the table that does the
+	 * translating can't drift apart across two repositories. A key the provider can't express raises the SDK's
+	 * `UnsupportedSortError`, which is why the facade validates against `supportedIssueSorts` first: reaching that
+	 * error means this table has outrun the SDK's.
+	 *
+	 * Always supplied by the facade's reads, never omitted. Omitting it would delegate the order to each provider's
+	 * own default, which is the incoherence across providers the SDK deliberately preserves and this layer
+	 * deliberately does not.
+	 */
+	sort?: IssueSorting;
 }
 
 export interface GetIssuesForRepoInput extends GetIssuesOptions {
@@ -492,6 +541,8 @@ export type GetIssuesForCurrentUserInput = PagingInput & {
 	assigneeUsername?: string;
 	authorUsername?: string;
 	pageSize?: number;
+	/** See {@link GetIssuesOptions.sort}. */
+	sort?: IssueSorting;
 };
 
 export type GetIssuesForCurrentUserFn = (
@@ -624,10 +675,10 @@ export type GetBitbucketServerPullRequestsForCurrentUserFn = (
 	data: GitPullRequest[];
 }>;
 export type GetIssuesForProjectFn = Jira['getIssuesForProject'];
-export type GetIssuesForResourceForCurrentUserFn = (
-	input: { resourceId: string },
-	options?: EnterpriseOptions,
-) => Promise<{ data: ProviderIssue[] }>;
+// Derived from the client method rather than hand-declared, as its project-scoped sibling above already is: the
+// hand-written shape named only `resourceId`, so every other field the SDK accepts (the cursor, the sort, the
+// transitions switch) was invisible to the type system and had to be smuggled through `getPagedResult`'s `any`.
+export type GetIssuesForResourceForCurrentUserFn = Jira['getIssuesForResourceForCurrentUser'];
 
 // Trello reads (issues-capable provider). The Trello client is keyed by an `appKey` (the Trello app key from
 // the cloud token exchange) alongside the OAuth token, so these mirror the client method shapes directly.
@@ -729,6 +780,36 @@ export interface ProviderMetadata {
 	 * axes; it omits `Mention` because that REST read has no first-class mention filter.
 	 */
 	supportedAccountWideIssueFilters?: IssueFilter[];
+	/**
+	 * Sort keys the REPO-scoped issue read can express server-side — and, for an issue tracker (Jira/Linear/Trello),
+	 * its project-scoped read, which is the only issue surface a tracker has.
+	 *
+	 * Absent/empty means the read can't be ordered at all, so a request carrying `sort` is refused rather than
+	 * served in whatever order the provider felt like. Present, it is a promise: every key here reaches the
+	 * provider query.
+	 *
+	 * A key listed here is expressible on ONE provider query, which is what this read is when it is given ONE
+	 * scope. Given several (GitLab across repositories, Azure across projects, a tracker across projects) it merges
+	 * their results here and can only honor a key a normalized issue carries, so it additionally refuses
+	 * `priority`/`dueDate`/`resolved` — see `getIssueComparator`. That depends on the caller's scope count rather
+	 * than on the provider, which is why it is a runtime refusal and not a fourth table: encoding it here would
+	 * under-report the single-scope read, which really does support those keys.
+	 */
+	supportedIssueSorts?: IssueSorting[];
+	/**
+	 * Sort keys the ACCOUNT-WIDE issue read can express server-side, which is NOT the same set as
+	 * {@link ProviderMetadata.supportedIssueSorts} — for GitLab the two reads are different APIs (GraphQL vs REST)
+	 * with genuinely different vocabularies, not one narrowed twice.
+	 *
+	 * Absent means the account-wide read can't be ordered (or doesn't exist). An issue tracker leaves this empty
+	 * and reports under `supportedIssueSorts`, so reading a tracker's capability from here under-reports it.
+	 *
+	 * Unlike {@link ProviderMetadata.supportedIssueSorts} this needs no companion runtime refusal, because every
+	 * provider's account-wide read is a union of several queries with no scope count for a caller to reduce: it
+	 * ALWAYS merges. So the keys a merge can't order by are simply absent here — the table states what the read can
+	 * honor, which is what makes intersecting against it sufficient.
+	 */
+	supportedAccountWideIssueSorts?: IssueSorting[];
 	/**
 	 * What the provider's FILTERED issue search (`searchIssuesPage`, and the `countIssues` probe over the same
 	 * criteria) can express server-side. A third, wider surface than either filter set above: it is not bound to
@@ -774,6 +855,8 @@ const githubIssueSearchCapabilities: IssueSearchCapabilities = {
 	withoutLinkedPullRequest: true,
 	// `is:open` / `is:closed`, or neither for all states.
 	states: true,
+	// `sort:created-desc`, `sort:updated`, `sort:comments-asc`, … — see `githubIssueSorts`.
+	sorts: githubIssueSorts,
 };
 
 /** GitHub and GHE use the same filtered pull-request search syntax and result ceiling. */
@@ -820,6 +903,10 @@ export const providersMetadata: ProvidersMetadata = {
 		// The account-wide read is three independent searches (`author:@me`, `assignee:@me`, `mentions:@me`) behind
 		// one composite cursor, so any subset of them is expressible.
 		supportedAccountWideIssueFilters: [IssueFilter.Author, IssueFilter.Assignee, IssueFilter.Mention],
+		// One `search` field serves all three issue reads (repo-scoped, account-wide, filtered search), so the same
+		// qualifiers are expressible on each — the account-wide one narrowed to what its three-alias merge can order.
+		supportedIssueSorts: githubIssueSorts,
+		supportedAccountWideIssueSorts: githubAccountWideIssueSorts,
 		supportedIssueSearch: githubIssueSearchCapabilities,
 		issueSearchResultLimit: githubSearchResultLimit,
 		scopes: ['repo', 'read:user', 'user:email'],
@@ -852,6 +939,10 @@ export const providersMetadata: ProvidersMetadata = {
 		// The account-wide read is three independent searches (`author:@me`, `assignee:@me`, `mentions:@me`) behind
 		// one composite cursor, so any subset of them is expressible.
 		supportedAccountWideIssueFilters: [IssueFilter.Author, IssueFilter.Assignee, IssueFilter.Mention],
+		// One `search` field serves all three issue reads (repo-scoped, account-wide, filtered search), so the same
+		// qualifiers are expressible on each — the account-wide one narrowed to what its three-alias merge can order.
+		supportedIssueSorts: githubIssueSorts,
+		supportedAccountWideIssueSorts: githubAccountWideIssueSorts,
 		supportedIssueSearch: githubIssueSearchCapabilities,
 		issueSearchResultLimit: githubSearchResultLimit,
 		scopes: ['repo', 'read:user', 'user:email'],
@@ -881,6 +972,10 @@ export const providersMetadata: ProvidersMetadata = {
 		// unioned, so either axis is expressible on its own. Mention is absent because GitLab's REST issue read has
 		// no first-class mention filter to narrow with.
 		supportedAccountWideIssueFilters: [IssueFilter.Assignee, IssueFilter.Author],
+		// Two different surfaces, not one narrowed twice: the repository-scoped read is GraphQL and the
+		// account-wide one is REST, and REST has neither `title` nor `closed_at`.
+		supportedIssueSorts: gitlabIssueSorts,
+		supportedAccountWideIssueSorts: gitlabAccountWideIssueSorts,
 		scopes: ['api', 'read_user', 'read_repository'],
 	},
 	[GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted]: {
@@ -908,6 +1003,10 @@ export const providersMetadata: ProvidersMetadata = {
 		// unioned, so either axis is expressible on its own. Mention is absent because GitLab's REST issue read has
 		// no first-class mention filter to narrow with.
 		supportedAccountWideIssueFilters: [IssueFilter.Assignee, IssueFilter.Author],
+		// Two different surfaces, not one narrowed twice: the repository-scoped read is GraphQL and the
+		// account-wide one is REST, and REST has neither `title` nor `closed_at`.
+		supportedIssueSorts: gitlabIssueSorts,
+		supportedAccountWideIssueSorts: gitlabAccountWideIssueSorts,
 		scopes: ['api', 'read_user', 'read_repository'],
 	},
 	[GitCloudHostIntegrationId.Bitbucket]: {
@@ -956,6 +1055,11 @@ export const providersMetadata: ProvidersMetadata = {
 		// The account-wide read drains one (project × assignee) and one (project × author) query per project, so
 		// either axis is expressible on its own. There is no mention query to narrow to.
 		supportedAccountWideIssueFilters: [IssueFilter.Author, IssueFilter.Assignee],
+		// Both reads emit the same WIQL, but the account-wide one drains every (project x relationship) query and
+		// merges the results, so it can only honor keys a normalized issue carries — `resolved` and `priority` are
+		// dropped from that surface for the same reason they are dropped from GitLab's.
+		supportedIssueSorts: azureIssueSorts,
+		supportedAccountWideIssueSorts: azureAccountWideIssueSorts,
 		scopes: ['vso.code', 'vso.identity', 'vso.project', 'vso.profile', 'vso.work'],
 	},
 	[GitSelfManagedHostIntegrationId.AzureDevOpsServer]: {
@@ -982,6 +1086,11 @@ export const providersMetadata: ProvidersMetadata = {
 		// The account-wide read drains one (project × assignee) and one (project × author) query per project, so
 		// either axis is expressible on its own. There is no mention query to narrow to.
 		supportedAccountWideIssueFilters: [IssueFilter.Author, IssueFilter.Assignee],
+		// Both reads emit the same WIQL, but the account-wide one drains every (project x relationship) query and
+		// merges the results, so it can only honor keys a normalized issue carries — `resolved` and `priority` are
+		// dropped from that surface for the same reason they are dropped from GitLab's.
+		supportedIssueSorts: azureIssueSorts,
+		supportedAccountWideIssueSorts: azureAccountWideIssueSorts,
 		scopes: ['vso.code', 'vso.identity', 'vso.project', 'vso.profile', 'vso.work'],
 	},
 	[IssuesCloudHostIntegrationId.Jira]: {
@@ -1027,6 +1136,9 @@ export const providersMetadata: ProvidersMetadata = {
 			'read:project-version:jira',
 		],
 		supportedIssueFilters: [IssueFilter.Author, IssueFilter.Assignee, IssueFilter.Mention],
+		// A tracker's issues live under resource -> project, so it has no account-wide surface to declare: its
+		// capability is reported under `issues`, which is what `listIssueTrackerIssuesPage` validates against.
+		supportedIssueSorts: jiraIssueSorts,
 	},
 	[IssuesCloudHostIntegrationId.Linear]: {
 		domain: 'linear.app',
@@ -1037,6 +1149,9 @@ export const providersMetadata: ProvidersMetadata = {
 		scopes: [],
 		// Linear scopes "my issues" client-side by the viewer's assignee id; author/mention aren't supported.
 		supportedIssueFilters: [IssueFilter.Assignee],
+		// Both directions, and one table for both reads: they are the same root `issues` query taking the same
+		// `sort` argument, so there is no account-wide narrowing to declare.
+		supportedIssueSorts: linearIssueSorts,
 	},
 	[IssuesCloudHostIntegrationId.Trello]: {
 		domain: 'trello.com',
@@ -1047,6 +1162,8 @@ export const providersMetadata: ProvidersMetadata = {
 		scopes: [],
 		// Trello cards are filtered by the assignee (member) only; author/mention have no Trello equivalent.
 		supportedIssueFilters: [IssueFilter.Assignee],
+		// `sort:edited` / `sort:-edited`. Trello's other search sorts (`created`, `due`) have no card-order effect.
+		supportedIssueSorts: trelloIssueSorts,
 	},
 };
 

package/src/plus/integrations/providers/providersApi.ts

@@ -39,6 +39,7 @@ import type {
 	GetPullRequestsOptions,
 	GetReposOptions,
 	IssueFilter,
+	IssueSorting,
 	PageInfo,
 	PagingInput,
 	PagingMode,
@@ -67,7 +68,7 @@ import type {
 	Providers,
 	PullRequestFilter,
 } from './models.js';
-import { providersMetadata } from './models.js';
+import { isRepoIdsInput, providersMetadata } from './models.js';
 import {
 	collectProviderPagedResult,
 	mergeCollectionMetadata,
@@ -132,6 +133,14 @@ function isGraphQLRepoNotFoundError(ex: unknown): boolean {
 
 const trelloBaseUrl = 'https://api.trello.com';
 
+/**
+ * Jira computes an issue's available transitions per issue, from the workflow and the reader's permissions, so a
+ * list read at a page size of 100 pays for 100 of those in both server work and response payload. Nothing in this
+ * package reads `statusTransitions` off a list — only the singular `getIssue` path exposes them, and it always
+ * expands them — so every list read opts out. Revisit the day a list row offers a status change straight off it.
+ */
+const jiraListIncludeTransitions = false;
+
 type TrelloMemberResponse = {
 	id: string;
 	username?: string | null;
@@ -479,12 +488,9 @@ export class ProvidersApi {
 		);
 	}
 
-	isRepoIdsInput(input: any): input is (string | number)[] {
-		return (
-			input != null &&
-			Array.isArray(input) &&
-			input.every((id: any) => typeof id === 'string' || typeof id === 'number')
-		);
+	/** See {@link isRepoIdsInput}, which owns the rule; kept as a method because callers reach it through the api. */
+	isRepoIdsInput(input: unknown): input is (string | number)[] {
+		return isRepoIdsInput(input);
 	}
 
 	private async getProviderToken<T extends IntegrationIds>(
@@ -868,7 +874,10 @@ export class ProvidersApi {
 	async getLinearIssues(
 		tokenOptInfo: TokenWithInfo<IssuesCloudHostIntegrationId.Linear>,
 		input: { teams?: string[]; projects?: string[]; labels?: string[] },
-		options?: PagingInput,
+		options?: PagingInput & {
+			/** See {@link GetIssuesOptions.sort}. Linear expresses `created`/`updated`, descending only. */
+			sort?: IssueSorting;
+		},
 	): Promise<PagedResult<ProviderIssue>> {
 		const { provider, tokenWithInfo } = await this.ensureProviderTokenAndFunction(
 			tokenOptInfo,
@@ -1565,6 +1574,8 @@ export class ProvidersApi {
 			 */
 			authorUsername?: string;
 			pageSize?: number;
+			/** See {@link GetIssuesOptions.sort}. Forwarded to the provider fn; ordering is translated in the SDK. */
+			sort?: IssueSorting;
 			isPAT?: boolean;
 			baseUrl?: string;
 		},
@@ -1580,6 +1591,7 @@ export class ProvidersApi {
 				authorUsername: options?.authorUsername,
 				page: options?.page,
 				pageSize: options?.pageSize,
+				sort: options?.sort,
 			},
 			provider.getIssuesForCurrentUserFn,
 			tokenWithInfo,
@@ -1626,7 +1638,12 @@ export class ProvidersApi {
 
 		try {
 			const result = await provider.getIssuesForProjectFn?.(
-				{ projectKey: project, resourceId: resourceId, ...options },
+				{
+					projectKey: project,
+					resourceId: resourceId,
+					...options,
+					includeTransitions: jiraListIncludeTransitions,
+				},
 				{ token: token },
 			);
 
@@ -1655,7 +1672,12 @@ export class ProvidersApi {
 
 		try {
 			const result = await provider.getIssuesForProjectFn?.(
-				{ projectKey: project, resourceId: resourceId, ...options },
+				{
+					projectKey: project,
+					resourceId: resourceId,
+					...options,
+					includeTransitions: jiraListIncludeTransitions,
+				},
 				{ token: token },
 			);
 			if (result == null) return undefined;
@@ -1760,7 +1782,12 @@ export class ProvidersApi {
 		tokenOptInfo: TokenWithInfo,
 		appKey: string,
 		boardId: string,
-		options?: { assigneeLogins?: string[]; trelloBoardListsById?: Record<string, { name: string }> },
+		options?: {
+			assigneeLogins?: string[];
+			trelloBoardListsById?: Record<string, { name: string }>;
+			/** See {@link GetIssuesOptions.sort}. Trello expresses only `updated`, in either direction. */
+			sort?: IssueSorting;
+		},
 	): Promise<ProviderApiCollectionResult<ProviderIssue>> {
 		const { provider, tokenWithInfo } = await this.ensureProviderTokenAndFunction(
 			tokenOptInfo,
@@ -1782,7 +1809,18 @@ export class ProvidersApi {
 	async getIssuesForResourceForCurrentUser(
 		tokenOptInfo: TokenWithInfo,
 		resourceId: string,
-		options?: { cursor?: string; isPAT?: boolean; baseUrl?: string },
+		options?: {
+			cursor?: string;
+			/**
+			 * See {@link GetIssuesOptions.sort}. Forwarded for the same reason as every sibling issue read, even
+			 * though nothing reaches this one with a sort today: `IssuesIntegration.searchProviderMyIssues` is the
+			 * only caller and takes no options. A wrapper that accepted the SDK's input and silently dropped one
+			 * field of it would give whoever adds that option no ordering and no error.
+			 */
+			sort?: IssueSorting;
+			isPAT?: boolean;
+			baseUrl?: string;
+		},
 	): Promise<PagedResult<ProviderIssue>> {
 		const { provider, tokenWithInfo } = await this.ensureProviderTokenAndFunction(
 			tokenOptInfo,
@@ -1790,7 +1828,7 @@ export class ProvidersApi {
 		);
 
 		return this.getPagedResult<ProviderIssue>(
-			{ resourceId: resourceId },
+			{ resourceId: resourceId, sort: options?.sort, includeTransitions: jiraListIncludeTransitions },
 			provider.getIssuesForResourceForCurrentUserFn,
 			tokenWithInfo,
 			options?.cursor,

package/src/plus/integrations/providers/trello.ts

@@ -9,8 +9,8 @@ import type { ProviderAuthenticationSession } from '../authentication/models.js'
 import { toTokenWithInfo } from '../authentication/models.js';
 import { IssuesCloudHostIntegrationId } from '../constants.js';
 import { IntegrationReadUnavailableError } from '../errors.js';
+import type { IssuesForProjectOptions } from '../models/issueReads.js';
 import { IssuesIntegration } from '../models/issuesIntegration.js';
-import type { IssueFilter } from './models.js';
 import { fromProviderIssue, providersMetadata, toIssueShape } from './models.js';
 
 const metadata = providersMetadata[IssuesCloudHostIntegrationId.Trello];
@@ -95,7 +95,7 @@ export class TrelloIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 	protected override async getProviderIssuesForProject(
 		session: ProviderAuthenticationSession,
 		project: ResourceDescriptor,
-		options?: { user?: string; filters?: IssueFilter[] },
+		options?: IssuesForProjectOptions,
 	): Promise<IssueShape[] | undefined> {
 		return (await this.getProviderIssuesForProjectWithTruncation(session, project, options))?.values;
 	}
@@ -103,7 +103,7 @@ export class TrelloIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 	protected override async getProviderIssuesForProjectWithTruncation(
 		session: ProviderAuthenticationSession,
 		project: ResourceDescriptor,
-		options?: { user?: string; filters?: IssueFilter[] },
+		options?: IssuesForProjectOptions,
 	): Promise<{ values: IssueShape[]; truncated: boolean; metadata?: CollectionMetadata } | undefined> {
 		// A non-issue descriptor genuinely has nothing to read (empty), but a missing app key is a broken read.
 		if (!isIssueResourceDescriptor(project)) return undefined;
@@ -129,6 +129,7 @@ export class TrelloIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 		const result = await api.getTrelloIssuesForBoard(tokenWithInfo, appKey, project.id, {
 			assigneeLogins: options?.user != null ? [options.user] : undefined,
 			trelloBoardListsById: trelloBoardListsById,
+			sort: options?.sort,
 		});
 
 		const values = result.values.flatMap(issue => {

package/src/plus/integrations/providers/utils/providerPaging.ts

@@ -6,7 +6,7 @@ import type {
 } from '@gitkraken/provider-apis';
 import { isCancellationError } from '../../../../utils/cancellation.js';
 import { uniqueBy } from '../../../../utils/iterable.js';
-import { toCollectionScopeFailure } from '../../collectionMetadata.js';
+import { throwIfCallerContractError, toCollectionScopeFailure } from '../../collectionMetadata.js';
 import { collectionScopeKey } from '../../results.js';
 import type { ProviderApiPagedResult, ProviderHierarchyResult } from '../models.js';
 
@@ -144,6 +144,11 @@ export async function collectProviderPagedResult<T>(
 		} catch (ex) {
 			if (isCancellationError(ex)) throw ex;
 
+			// A caller-contract error is not a fact about this scope, so it is never recorded as one — see
+			// `throwIfCallerContractError`. Checked alongside cancellation because both are errors that a
+			// per-scope failure would misdescribe.
+			throwIfCallerContractError(ex);
+
 			// When the caller supplied a scope, preserve the items already fetched from that scope and record the
 			// failure in collection metadata rather than re-throwing and discarding the prefix. Callers without a
 			// scope keep the legacy throw behavior.

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

@@ -33,6 +33,12 @@ import { gitHostOnlySurfaceWarning, issuesUnsupportedWarning, noConnectionWarnin
  * `includeAllAssignees: true`, which resolves to no assignee constraint at all, so unassigned issues ARE
  * included. The equivalent is an OMITTED `relationships`, not `['any-assignee']`: `assignee:*` means "has some
  * assignee" and would silently exclude every unassigned issue, which is the opposite of broadening.
+ *
+ * Takes no `sort`, unlike `listIssuesPage` and `searchIssuesPage`. One logical page here spans several orgs, each
+ * at its own provider position in a cursor bundle, so honoring an order across them would need a k-way merge with
+ * a buffer per org rather than a sort of what arrived — the page is a slice of several independent walks, not a
+ * union of one round's results. `searchIssuesPage({ repos, criteria: { sort } })` answers the ordered version of
+ * this question for a caller that knows its repositories, and is already the recommended migration above.
  */
 
 export interface BroadenIssuesOptions {

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

@@ -44,7 +44,14 @@ export interface IssueCountScope {
 	/** Repositories to count over. Combines with `org`, exactly as in `searchIssuesPage`. */
 	repos?: ProviderReposInput;
 	org?: string;
-	/** Same criteria model as `searchIssuesPage`, validated against the same capability table. */
+	/**
+	 * Same criteria model as `searchIssuesPage`, validated against the same capability table.
+	 *
+	 * `criteria.sort` does not affect the count — a total is invariant under ordering — but it is still VALIDATED,
+	 * and an unsupported key refuses this scope exactly as it would refuse the read. That is the point of the
+	 * count: it previews the constraints the read will apply, so one that accepted what the read refuses would
+	 * promise a fetch that can't happen, which is worse than no preview at all.
+	 */
 	criteria?: IssueSearchCriteria;
 }
 

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 ?? [])],
 	};
 }