@gitkraken/core-gitlens 0.5.108 → 0.5.110

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

@@ -41,26 +41,22 @@ import type {
 	SetPullRequestInput,
 	Trello,
 } from '@gitkraken/provider-apis';
-import entityIdentifiersModule from '@gitkraken/provider-apis/entity-identifiers';
-import providerUtilsModule from '@gitkraken/provider-apis/provider-utils';
+import { EntityIdentifierUtils } from '@gitkraken/provider-apis/entity-identifiers';
+import { GitProviderUtils } from '@gitkraken/provider-apis/provider-utils';
 import { githubSearchResultLimit } from '../../git-github/api/config.js';
 import type { Account as UserAccount } from '../../../git/models/author.js';
-import type { IssueMember, IssueProject, IssueShape, IssueStateFilter } from '../../../git/models/issue.js';
+import type { IssueProject, IssueShape, IssueStateFilter } from '../../../git/models/issue.js';
 import { Issue, RepositoryAccessLevel } from '../../../git/models/issue.js';
 import type {
-	PullRequestMember,
 	PullRequestRef,
 	PullRequestRefs,
 	PullRequestRepositoryIdentityDescriptor,
-	PullRequestReviewer,
 	PullRequestState,
 	PullRequestStateFilter,
 } from '../../../git/models/pullRequest.js';
 import {
 	PullRequest,
 	PullRequestMergeableState,
-	PullRequestReviewDecision,
-	PullRequestReviewState,
 	PullRequestStatusCheckRollupState,
 } from '../../../git/models/pullRequest.js';
 import type { Provider, ProviderReference } from '../../../git/models/remoteProvider.js';
@@ -75,7 +71,12 @@ 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,
+	PullRequestSorting,
+} from '../providerFilters.js';
 import { IssueFilter, PullRequestFilter } from '../providerFilters.js';
 
 export { IssueFilter, PullRequestFilter } from '../providerFilters.js';
@@ -83,12 +84,37 @@ export type {
 	IssueSearchCapabilities,
 	IssueSearchCriteria,
 	IssueSearchRelationship,
+	IssueSortField,
+	IssueSorting,
 	PullRequestSearchCapabilities,
 	PullRequestSearchCriteria,
+	PullRequestSortField,
+	PullRequestSorting,
 } from '../providerFilters.js';
 import type { ProviderRepositoryShape } from '../results.js';
 
 export type { ProviderOrganization, ProviderRepositoryShape } from '../results.js';
+import { fromProviderAccount, toProviderAccount } from './accounts.js';
+import {
+	azureAccountWideIssueSorts,
+	azureIssueSorts,
+	githubAccountWideIssueSorts,
+	githubIssueSorts,
+	gitlabAccountWideIssueSorts,
+	gitlabIssueSorts,
+	jiraIssueSorts,
+	linearIssueSorts,
+	trelloIssueSorts,
+} from './issueSorts.js';
+import type { ProviderPullRequestReview, ProviderPullRequestReviews } from './pullRequestReviews.js';
+import {
+	fromPullRequestReviewDecision,
+	providerPullRequestReviewStateDismissed,
+	toCompletedReviews,
+	toProviderReviewDecision,
+	toProviderReviews,
+	toReviewRequests,
+} from './pullRequestReviews.js';
 import { getEntityIdentifierInput } from './utils.js';
 
 type GitBuildStatusState = GitBuildStatusStateType;
@@ -97,9 +123,6 @@ type GitPullRequestMergeableState = GitPullRequestMergeableStateType;
 type GitPullRequestReviewState = GitPullRequestReviewStateType;
 type GitPullRequestState = GitPullRequestStateType;
 
-const { EntityIdentifierUtils } = entityIdentifiersModule;
-const { GitProviderUtils } = providerUtilsModule;
-
 // Local runtime copies of the `@gitkraken/provider-apis` string enums. Duplicated (not imported as
 // values) because the SDK ships as CJS whose named enum exports can't be statically imported as ESM
 // values from the bundled `dist`. Exported so the enum-parity test can deep-equal them against the
@@ -156,7 +179,29 @@ type EnrichableItem = any;
 export type ProviderAccount = Account;
 export type ProviderReposInput = (string | number)[] | GetRepoInput[];
 export type ProviderRepoInput = GetRepoInput;
-export type ProviderPullRequest = GitPullRequest;
+
+/**
+ * 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 = Omit<GitPullRequest, 'reviews'> & { reviews: ProviderPullRequestReviews };
 export type ProviderRepository = GitRepository;
 export type ProviderIssue = ProviderApiIssue;
 export type ProviderEnterpriseOptions = EnterpriseOptions;
@@ -331,6 +376,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 +551,8 @@ export type GetIssuesForCurrentUserInput = PagingInput & {
 	assigneeUsername?: string;
 	authorUsername?: string;
 	pageSize?: number;
+	/** See {@link GetIssuesOptions.sort}. */
+	sort?: IssueSorting;
 };
 
 export type GetIssuesForCurrentUserFn = (
@@ -624,10 +685,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 +790,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,21 +865,40 @@ 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,
 };
 
+/**
+ * The ordering vocabulary of GitHub's filtered PR search: `created` and `updated`, both directions.
+ *
+ * Hand-declared rather than derived from `@gitkraken/provider-apis` (which has no PR-sort surface), and narrower
+ * than the issue set on purpose: the merged relationship × state facets can only be re-ordered by a field a
+ * `PullRequestShape` carries (see `getPullRequestComparator`), and GitHub PRs have no priority and no relevance
+ * that orders stably under the result ceiling. A parity test pins this to `gitHubPullRequestSortQualifiers`' keys
+ * so the capability can't outrun the emitter.
+ */
+const githubPullRequestSorts: PullRequestSorting[] = ['updated:desc', 'updated:asc', 'created:desc', 'created:asc'];
+
 /** GitHub and GHE use the same filtered pull-request search syntax and result ceiling. */
 const githubPullRequestSearchCapabilities: PullRequestSearchCapabilities = {
 	relationships: [
 		PullRequestFilter.Author,
 		PullRequestFilter.Assignee,
 		PullRequestFilter.ReviewRequested,
+		PullRequestFilter.Reviewed,
 		PullRequestFilter.Mention,
 	],
 	states: ['open', 'closed', 'merged', 'all'],
 	text: true,
+	updatedAfter: true,
+	createdAfter: true,
 	includeArchived: true,
+	draft: true,
 	repositoryScope: true,
 	organizationScope: true,
+	// `sort:updated`, `sort:updated-asc`, `sort:created-desc`, `sort:created-asc` — see `githubPullRequestSorts`.
+	sorts: githubPullRequestSorts,
 };
 
 export const providersMetadata: ProvidersMetadata = {
@@ -811,6 +921,7 @@ export const providersMetadata: ProvidersMetadata = {
 			PullRequestFilter.Author,
 			PullRequestFilter.Assignee,
 			PullRequestFilter.ReviewRequested,
+			PullRequestFilter.Reviewed,
 			PullRequestFilter.Mention,
 		],
 		supportedPullRequestSearch: githubPullRequestSearchCapabilities,
@@ -820,6 +931,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'],
@@ -843,6 +958,7 @@ export const providersMetadata: ProvidersMetadata = {
 			PullRequestFilter.Author,
 			PullRequestFilter.Assignee,
 			PullRequestFilter.ReviewRequested,
+			PullRequestFilter.Reviewed,
 			PullRequestFilter.Mention,
 		],
 		supportedPullRequestSearch: githubPullRequestSearchCapabilities,
@@ -852,6 +968,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 +1001,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 +1032,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 +1084,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 +1115,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 +1165,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 +1178,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 +1191,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,
 	},
 };
 
@@ -1203,22 +1349,6 @@ export const fromProviderBuildStatusState = {
 	[GitBuildStatusState.Warning]: undefined,
 };
 
-export const toProviderPullRequestReviewState = {
-	[PullRequestReviewState.Approved]: GitPullRequestReviewState.Approved,
-	[PullRequestReviewState.ChangesRequested]: GitPullRequestReviewState.ChangesRequested,
-	[PullRequestReviewState.Commented]: GitPullRequestReviewState.Commented,
-	[PullRequestReviewState.ReviewRequested]: GitPullRequestReviewState.ReviewRequested,
-	[PullRequestReviewState.Dismissed]: null,
-	[PullRequestReviewState.Pending]: null,
-};
-
-export const fromProviderPullRequestReviewState = {
-	[GitPullRequestReviewState.Approved]: PullRequestReviewState.Approved,
-	[GitPullRequestReviewState.ChangesRequested]: PullRequestReviewState.ChangesRequested,
-	[GitPullRequestReviewState.Commented]: PullRequestReviewState.Commented,
-	[GitPullRequestReviewState.ReviewRequested]: PullRequestReviewState.ReviewRequested,
-};
-
 export const toProviderPullRequestMergeableState = {
 	[PullRequestMergeableState.Mergeable]: GitPullRequestMergeableState.Mergeable,
 	[PullRequestMergeableState.Conflicting]: GitPullRequestMergeableState.Conflicts,
@@ -1238,68 +1368,6 @@ export const fromProviderPullRequestMergeableState = {
 	[GitPullRequestMergeableState.Unstable]: PullRequestMergeableState.Unknown,
 };
 
-export function toProviderReviews(reviewers: PullRequestReviewer[]): ProviderPullRequest['reviews'] {
-	return reviewers
-		.filter(r => r.state !== PullRequestReviewState.Dismissed && r.state !== PullRequestReviewState.Pending)
-		.map(reviewer => ({
-			reviewer: toProviderAccount(reviewer.reviewer),
-			state: toProviderPullRequestReviewState[reviewer.state] ?? GitPullRequestReviewState.ReviewRequested,
-		}));
-}
-
-export function toReviewRequests(reviews: ProviderPullRequest['reviews']): PullRequestReviewer[] | undefined {
-	return reviews == null
-		? undefined
-		: reviews
-				?.filter(r => r.state === GitPullRequestReviewState.ReviewRequested)
-				.map(r => ({
-					isCodeOwner: false, // TODO: Find this value, and implement in the shared lib if needed
-					reviewer: fromProviderAccount(r.reviewer),
-					state: PullRequestReviewState.ReviewRequested,
-				}));
-}
-
-export function toCompletedReviews(reviews: ProviderPullRequest['reviews']): PullRequestReviewer[] | undefined {
-	return reviews == null
-		? undefined
-		: reviews
-				?.filter(r => r.state !== GitPullRequestReviewState.ReviewRequested)
-				.map(r => ({
-					isCodeOwner: false, // TODO: Find this value, and implement in the shared lib if needed
-					reviewer: fromProviderAccount(r.reviewer),
-					state: fromProviderPullRequestReviewState[r.state],
-				}));
-}
-
-export function toProviderReviewDecision(
-	reviewDecision?: PullRequestReviewDecision,
-	reviewers?: PullRequestReviewer[],
-): GitPullRequestReviewState | null {
-	switch (reviewDecision) {
-		case PullRequestReviewDecision.Approved:
-			return GitPullRequestReviewState.Approved;
-		case PullRequestReviewDecision.ChangesRequested:
-			return GitPullRequestReviewState.ChangesRequested;
-		case PullRequestReviewDecision.ReviewRequired:
-			return GitPullRequestReviewState.ReviewRequested;
-		default: {
-			if (reviewers?.some(r => r.state === PullRequestReviewState.ReviewRequested)) {
-				return GitPullRequestReviewState.ReviewRequested;
-			} else if (reviewers?.some(r => r.state === PullRequestReviewState.Commented)) {
-				return GitPullRequestReviewState.Commented;
-			}
-			return null;
-		}
-	}
-}
-
-export const fromPullRequestReviewDecision = {
-	[GitPullRequestReviewState.Approved]: PullRequestReviewDecision.Approved,
-	[GitPullRequestReviewState.ChangesRequested]: PullRequestReviewDecision.ChangesRequested,
-	[GitPullRequestReviewState.Commented]: undefined,
-	[GitPullRequestReviewState.ReviewRequested]: PullRequestReviewDecision.ReviewRequired,
-};
-
 export function toProviderPullRequestState(state: PullRequestState): GitPullRequestState {
 	return state === 'opened'
 		? GitPullRequestState.Open
@@ -1424,7 +1492,11 @@ export function toProviderPullRequest(pr: PullRequest): ProviderPullRequest {
 						name: pr.refs.head.branch,
 						oid: pr.refs.head.sha,
 					},
-		reviews: toProviderReviews(prReviews),
+		// `null` when the source carried no review data at all, rather than the empty array a lite read would
+		// otherwise produce: `toCompletedReviews`/`toReviewRequests` map `null` back to `undefined`, which is what
+		// lets a consumer tell "nobody has reviewed this" from "this read never fetched reviews" (see
+		// `PullRequestShape.latestReviews`). An empty array from a full projection stays an empty array.
+		reviews: pr.reviewRequests == null && pr.latestReviews == null ? null : toProviderReviews(prReviews),
 		reviewDecision: toProviderReviewDecision(pr.reviewDecision, prReviews),
 		repository:
 			pr.repository != null
@@ -1623,46 +1695,31 @@ export function fromProviderIssue(
 }
 
 export function toProviderPullRequestWithUniqueId(pr: PullRequest): PullRequestWithUniqueID {
+	const { reviews, ...providerPr } = toProviderPullRequest(pr);
 	return {
-		...toProviderPullRequest(pr),
+		...providerPr,
+		// The SDK boundary: `getActionablePullRequests` categorizes by review state and only knows
+		// provider-apis' own vocabulary, so the locally-added dismissed state is dropped here rather than
+		// handed over as a value it would fall through on. Our own projection keeps it — see
+		// `providerPullRequestReviewStateDismissed`. `commitOid` rides along on the surviving reviews: it is an
+		// extra property the SDK ignores, not a value it could misread.
+		reviews:
+			reviews?.filter(
+				(r): r is ProviderPullRequestReview & { state: GitPullRequestReviewState } =>
+					r.state !== providerPullRequestReviewStateDismissed,
+			) ?? null,
 		uuid: EntityIdentifierUtils.encode(getEntityIdentifierInput(pr)),
 	};
 }
 
-export function toProviderAccount(account: PullRequestMember | IssueMember): ProviderAccount {
-	return {
-		id: account.id ?? null,
-		avatarUrl: account.avatarUrl ?? null,
-		name: account.name ?? null,
-		url: account.url ?? null,
-		// TODO: Implement these in our own model
-		email: '',
-		username: account.name ?? null,
-	};
-}
-
-export function fromProviderAccount(account: ProviderAccount | null): PullRequestMember | IssueMember {
-	return {
-		id: account?.id ?? '',
-		// An absent name stays absent. `'unknown'` was a display fallback invented in the provider layer, and a
-		// consumer couldn't tell it apart from a member genuinely named that — so it couldn't be undone where a
-		// name-shaped placeholder is wrong (rendering an avatar-only chip, or building an AI prompt, where
-		// `Assignees: unknown` reads as a real assignee). It also disagreed with {@link toIssueShape}, which
-		// collapsed the same absent name to `''` — same facade method, two fallbacks. Both now emit `undefined`.
-		name: account?.name ?? undefined,
-		avatarUrl: account?.avatarUrl ?? undefined,
-		// `url` is optional, so an absent one must be `undefined`, not `''`. `''` passes a `!= null` presence
-		// check and renders as a link to nowhere, and it disagreed with {@link toIssueShape} — which already
-		// collapses to `undefined` — even though BOTH mappers feed `listIssuesPage` (the repo-scoped path goes
-		// through `toIssueShape`, Azure's account-wide path through {@link fromProviderIssue}). Same facade
-		// method, two shapes. Matches {@link toProviderRepositoryShape}, which collapses every absent optional.
-		url: account?.url ?? undefined,
-	};
-}
-
 export type ProviderActionablePullRequest = ActionablePullRequest;
 
-export type EnrichablePullRequest = ProviderPullRequest & {
+/**
+ * Built on the SDK's `GitPullRequest`, NOT the local {@link ProviderPullRequest} widening: this is handed to
+ * `getActionablePullRequests`, which categorizes by review state and only knows provider-apis' vocabulary.
+ * {@link toProviderPullRequestWithUniqueId} is what narrows `reviews` down to it.
+ */
+export type EnrichablePullRequest = GitPullRequest & {
 	uuid: string;
 	type: 'pullrequest';
 	provider: ProviderReference;

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,