@gitkraken/core-gitlens 0.5.108 → 0.5.110

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

@@ -0,0 +1,124 @@
+import type { IssueShape, IssueSorting } from '../../../git/models/issue.js';
+import { defaultIssueSort } from '../../../git/models/issue.js';
+import { getIssueComparator } from '../../../git/utils/issue.utils.js';
+
+/**
+ * How an issue read decides what order to request, and how to order a page it assembled itself.
+ *
+ * Its own module rather than more of `filters.ts` because it answers a different question. That file validates what
+ * a caller asked to NARROW to; this one resolves what a caller asked to ORDER by — and unlike a filter, an order
+ * doesn't only have to be expressible by the provider, it also has to survive the read's own merging. Every issue
+ * read makes both decisions in the same shape, so they are resolved here once rather than at each read.
+ */
+
+/**
+ * Why {@link resolveIssueSort} refused a key, carrying what the refusal has to say — the same shape
+ * `IssueSearchCriteriaRejection` uses for the filtered search, and for the same reason.
+ *
+ * The payload travels WITH the rejection rather than being re-read at the warning: the check already held both
+ * values, so handing them back is what lets a caller word the refusal without re-deriving anything TypeScript
+ * can no longer narrow (which is how this grew five non-null assertions), and it makes it impossible for the
+ * message to name a supported list the check didn't use.
+ */
+export type UnsupportedIssueSortRejection = {
+	reason: 'unsupported-sort';
+	/** The key the caller asked for. Non-optional, unlike the `sort` a successful resolve returns. */
+	requested: IssueSorting;
+	/** Every key this surface CAN express, for the message. `undefined` when the read can't be ordered at all. */
+	supported: IssueSorting[] | undefined;
+};
+
+/**
+ * Resolves the order an issue read should request: validates a caller-supplied key against what one provider
+ * surface can express server-side, and supplies this facade's default when the caller asked for none.
+ *
+ * Three outcomes, and each is a decision rather than a convenience:
+ * - A key the surface can't express is REJECTED and the read refused whole, never resolved to the nearest
+ *   supported key. Same reason a dropped filter isn't dropped: the provider serves at most a bounded window of
+ *   matches, so a list ordered by something else is a DIFFERENT subset than the one asked for, and the cursor that
+ *   comes with it describes that other subset — indistinguishable, from the result, from the order requested.
+ * - An omitted key becomes {@link defaultIssueSort}, because leaving it to the provider is what makes the same
+ *   read return different things on different hosts (Azure by creation, Jira by nothing at all). The default is
+ *   this facade's promise; the SDK deliberately has no opinion.
+ * - An omitted key on a surface that can't express even the default returns `undefined`, leaving that provider's
+ *   own order. A default the caller never asked for must not refuse a read that works today.
+ *
+ * Takes the supported list rather than an `IntegrationIds`, unlike the filter validators, because which list
+ * applies is the CALLER's decision — `supportedIssueSorts` for a repo-scoped or tracker read,
+ * `supportedAccountWideIssueSorts` for an account-wide one — and that branch already exists at the call site
+ * (`repos` present or not). Resolving it in here would duplicate it.
+ */
+export function resolveIssueSort(
+	supported: IssueSorting[] | undefined,
+	sort: IssueSorting | undefined,
+): { rejection?: UnsupportedIssueSortRejection; sort?: IssueSorting } {
+	if (sort == null) {
+		return supported?.includes(defaultIssueSort) ? { sort: defaultIssueSort } : {};
+	}
+	if (!supported?.includes(sort)) {
+		return { rejection: { reason: 'unsupported-sort', requested: sort, supported: supported } };
+	}
+
+	return { sort: sort };
+}
+
+/**
+ * Why a merged page can't honor the key it was given: the read fans out over several provider queries and no
+ * normalized issue carries the field to merge on.
+ *
+ * Named for the same reason {@link UnsupportedIssueSortRejection} is, and kept separate from it because the two
+ * refusals are different claims: that one says the PROVIDER can't express the key, this one says the provider
+ * can but this READ's shape can't — the same key against the same provider succeeds on a single scope.
+ */
+export type UnmergeableIssueSort = {
+	/** The key the caller asked for, which a single-scope read of this provider would have honored. */
+	requested: IssueSorting;
+};
+
+/**
+ * What a read does with the order it resolved, once it also knows whether the page it is about to build MERGES
+ * several provider queries.
+ *
+ * Both facts are bound here, at the one point a read knows them, rather than consulted separately at the refusal
+ * and again at the sort. That is the difference this type buys: `merged` and the comparator were each tested twice
+ * per read, and the two tests are the same decision — whether the requested order survives this page's shape.
+ */
+export type IssueOrdering = {
+	/** The key to send to the provider, or `undefined` to leave the provider's own order. */
+	readonly sort: IssueSorting | undefined;
+	/**
+	 * Set when the requested key cannot be honored: this page merges several queries, and no normalized issue
+	 * carries the field to merge on. The read refuses rather than serving concatenated per-scope runs, which would
+	 * look ordered without being so. `undefined` for a single-query page, where the provider did the ordering.
+	 *
+	 * Carries the key rather than being a bare flag, for the same reason {@link UnsupportedIssueSortRejection}
+	 * does: the refusal needs it, and re-reading `sort` at the call site needs an assertion for an invariant this
+	 * type would otherwise not express.
+	 */
+	readonly unmergeable: UnmergeableIssueSort | undefined;
+	/**
+	 * Orders a merged page. A no-op for a single-query page (the provider already ordered it, and re-sorting could
+	 * only reproduce that order while hiding a provider that ignored the key) and for a read with no key at all.
+	 *
+	 * Returns a new array rather than sorting in place: the input is often the provider's own `values`, and a read
+	 * that mutates what it was handed is a surprise waiting for the next caller to share that reference.
+	 */
+	order(items: IssueShape[]): IssueShape[];
+};
+
+/**
+ * Binds a resolved sort key to the shape of the page about to be built.
+ *
+ * `merged` is the caller's own count of provider queries reduced to the only thing that matters: GitHub sends one
+ * search however many repositories are named, GitLab one per repository, Azure and the trackers one per project,
+ * and every account-wide read is a union of several. Above one, the union is what gets published, and only a field
+ * an {@link IssueShape} carries can order it.
+ */
+export function toIssueOrdering(sort: IssueSorting | undefined, merged: boolean): IssueOrdering {
+	const comparator = sort != null ? getIssueComparator(sort) : undefined;
+	return {
+		sort: sort,
+		unmergeable: merged && sort != null && comparator == null ? { requested: sort } : undefined,
+		order: (items: IssueShape[]) => (merged && comparator != null ? [...items].sort(comparator) : items),
+	};
+}

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

@@ -1,4 +1,5 @@
 import type { IssueSearchCriteria, IssueShape } from '../../../git/models/issue.js';
+import { effectiveIssueSort } from '../../../git/utils/issue.utils.js';
 import type { IntegrationIds } from '../constants.js';
 import type { ProviderReposInput } from '../providers/models.js';
 import type { ProviderPagedResult, ProviderWarning } from '../results.js';
@@ -40,8 +41,13 @@ import {
  * for the same reason `broaden.ts`, `sweeps.ts` and `issueTracker.ts` are separate files.
  *
  * Contract details worth knowing before calling:
- * - Ordering is ALWAYS most-recently-updated-first. Not an option: a "show the N most recent" policy at the
- *   provider's result ceiling is only correct under a guaranteed order.
+ * - Ordering is `criteria.sort`, most-recently-updated-first by default, and validated like every other criterion
+ *   against `getSupportedFilters().issueSearch.sorts`. SOME order is always requested — a "show the N most recent"
+ *   policy at the provider's result ceiling is only correct under a guaranteed one, and the ceiling warning names
+ *   the key it selected the window under. A key the provider can't express refuses the read rather than serving a
+ *   differently-ordered result; do not change it mid-pagination (a cursor is bound to the order it was made under,
+ *   and threading it under a different key is refused with a warning + `fetchFailed` — drop the cursor and read
+ *   from the first page instead).
  * - Paging is cursor-only. `page` alone walks 1..N internally (O(N) requests); a page past the last one is an
  *   empty page N, never page N−1 relabeled.
  * - At the provider's result ceiling the read SUCCEEDS and reports an omission carrying the total match count,
@@ -214,7 +220,13 @@ export async function searchIssuesPage(
 		// warning carrying the total. Anything else truncated (an unusable continuation, a provider that stopped
 		// advancing) falls back to the generic wording.
 		warnings.push(
-			issueSearchCapResultWarning(options.providerId, domain, options.connectionId, totalCount) ??
+			issueSearchCapResultWarning(
+				options.providerId,
+				domain,
+				options.connectionId,
+				totalCount,
+				effectiveIssueSort(options.criteria?.sort),
+			) ??
 				truncationWarning(
 					options.providerId,
 					domain,

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

@@ -1,4 +1,5 @@
 import type { PullRequestSearchCriteria, PullRequestShape } from '../../../git/models/pullRequest.js';
+import { defaultPullRequestSort } from '../../../git/models/pullRequest.js';
 import type { IntegrationIds } from '../constants.js';
 import type { ProviderReposInput } from '../providers/models.js';
 import type { ProviderPagedResult, ProviderWarning } from '../results.js';
@@ -29,9 +30,10 @@ import {
  * Pull requests matching structured criteria over a repository/organization or current-user relationship scope.
  *
  * The read is deliberately separate from `listPullRequestsPage`: the list has provider-specific "my PRs"
- * semantics and no text channel, while this method promises a sanitized query, most-recently-updated-first
- * ordering, one upstream request per cursor-threaded page, and a quantified omission at the provider's result
- * ceiling.
+ * semantics and no text channel, while this method promises a sanitized query, an ordering the caller chooses
+ * (`criteria.sort`, defaulting to most-recently-updated-first) and that is applied to the merged page as a whole,
+ * one upstream request per cursor-threaded page, and a quantified omission at the provider's result ceiling that
+ * names the order the reachable window was selected under.
  */
 export async function searchPullRequestsPage(
 	ctx: ProviderReadContext,
@@ -183,7 +185,13 @@ export async function searchPullRequestsPage(
 	const truncated = continuation.truncated;
 	if (truncated && warnings.length === 0) {
 		warnings.push(
-			pullRequestSearchCapResultWarning(options.providerId, domain, options.connectionId, totalCount) ??
+			pullRequestSearchCapResultWarning(
+				options.providerId,
+				domain,
+				options.connectionId,
+				totalCount,
+				options.criteria?.sort ?? defaultPullRequestSort,
+			) ??
 				truncationWarning(options.providerId, domain, options.connectionId, 'Pull request search', 'exhausted'),
 		);
 	}

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

@@ -111,7 +111,7 @@ async function sweepTarget(
 		repos,
 		options?.states,
 		resolved.filters,
-		accountWide ? (options?.includeReviewRequested ?? false) : false,
+		options,
 		connectionId,
 		maxPages,
 		attributeUnavailableProviders,

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

@@ -2,12 +2,15 @@ import type { IntegrationIds } from '../constants.js';
 import type {
 	IssueFilter,
 	IssueSearchCapabilities,
+	IssueSorting,
 	PullRequestFilter,
 	PullRequestSearchCapabilities,
+	PullRequestSorting,
 } from '../providerFilters.js';
 import { providersMetadata } from '../providers/models.js';
 import type { ProviderWarning } from '../results.js';
 import type { IssueSearchCriteriaRejection, PullRequestSearchCriteriaRejection } from './filters.js';
+import type { UnmergeableIssueSort, UnsupportedIssueSortRejection } from './ordering.js';
 
 /**
  * The warnings the provider facade raises on its OWN terms, as opposed to the ones derived from a caught
@@ -284,9 +287,13 @@ function describePullRequestSearchCapabilities(capabilities: PullRequestSearchCa
 		...(capabilities.relationships.length ? [`relationships:${capabilities.relationships.join('|')}`] : []),
 		...(capabilities.states.length ? [`states:${capabilities.states.join('|')}`] : []),
 		...(capabilities.text ? ['text'] : []),
+		...(capabilities.updatedAfter ? ['updatedAfter'] : []),
+		...(capabilities.createdAfter ? ['createdAfter'] : []),
 		...(capabilities.includeArchived ? ['includeArchived'] : []),
+		...(capabilities.draft ? ['draft'] : []),
 		...(capabilities.repositoryScope ? ['repository scope'] : []),
 		...(capabilities.organizationScope ? ['organization scope'] : []),
+		...(capabilities.sorts.length ? [`sorts:${capabilities.sorts.join('|')}`] : []),
 	].join(', ');
 }
 
@@ -343,9 +350,71 @@ function describeIssueSearchCapabilities(capabilities: IssueSearchCapabilities):
 	return [
 		...capabilities.relationships.map(r => `relationships:${r}`),
 		...flags.filter(([, supported]) => supported).map(([name]) => name),
+		...capabilities.sorts.map(s => `sort:${s}`),
 	].join(', ');
 }
 
+/**
+ * Warning for an issue read asked to order by a key its provider can't express server-side.
+ *
+ * Separate from {@link unsupportedIssueSearchCriteriaWarning} because it serves the reads that take `sort` as an
+ * OPTION rather than as a criterion — repo-scoped, account-wide, and issue-tracker — where there is no criteria
+ * set to fold it into. The filtered search keeps reporting it as one more `unsupported-criteria` entry, so a
+ * caller there still gets a single refusal listing everything at once.
+ *
+ * Takes the rejection the check produced rather than a re-read supported list: which of the two tables applies is
+ * the caller's own branch (`repos` present or not), so reading it back here — or threading it by hand — would be
+ * free to disagree with the check that refused.
+ */
+export function unsupportedIssueSortWarning(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	rejection: UnsupportedIssueSortRejection,
+): ProviderWarning {
+	return otherWarning(
+		id,
+		domain,
+		connectionId,
+		unsupportedNarrowingMessage(id, 'issue sort', rejection.requested, (rejection.supported ?? []).join(', ')),
+	);
+}
+
+/**
+ * Warning for a merged issue read asked to order by a key that no normalized issue carries.
+ *
+ * The distinction this exists to make is not about the provider: the provider orders by `priority` perfectly well
+ * within ONE project. It is about the read, which fans out over several and merges the results here, where the
+ * only fields available are the ones {@link IssueShape} models. Serving the concatenated per-scope runs would look
+ * ordered without being so, which is why this refuses instead — and why the message says WHY, since the same key
+ * against the same provider succeeds on a single-scope read.
+ *
+ * What a read fans out OVER differs by read, hence the `scope`: repositories, projects, or — where one query is
+ * issued per requested relationship and the runs are unioned within a single project (Jira) — the filters
+ * themselves. Naming the wrong one would tell a caller to narrow something that isn't what merged.
+ */
+export function unmergeableIssueSortWarning(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	unmergeable: UnmergeableIssueSort,
+	scope: 'repositories' | 'projects' | 'filters',
+): ProviderWarning {
+	// Both forms are spelled out rather than depluralized at runtime: the message needs each, and
+	// `'repositories'.replace(/s$/, '')` is `'repositorie'`.
+	const nouns = {
+		repositories: { many: 'repositories', one: 'repository' },
+		projects: { many: 'projects', one: 'project' },
+		filters: { many: 'issue relationships', one: 'relationship' },
+	}[scope];
+	return otherWarning(
+		id,
+		domain,
+		connectionId,
+		`Cannot order by '${unmergeable.requested}' across several ${nouns.many}: this read merges their results, and a normalized issue carries no such field to merge on. Read one ${nouns.one} at a time, or order by a date, title, comment or reaction count.`,
+	);
+}
+
 /**
  * The omission for a filtered issue search that hit the provider's RESULT CEILING: more issues matched than the
  * provider will ever serve for one query, however it is paged.
@@ -356,6 +425,10 @@ function describeIssueSearchCapabilities(capabilities: IssueSearchCapabilities):
  * 'none'` because the items past the ceiling are UNREACHABLE, not merely unfetched: no budget, no retry, and no
  * cursor would return them. Narrowing the criteria is the only way through, which is a decision for the caller.
  *
+ * The message names the ORDER, and has to now that ordering is an option: the reachable window is the top `limit`
+ * under that key, so "the 1.000 most recent" is a true sentence only while the key is the default one. The same
+ * value goes on the omission, so a consumer wording its own sentence doesn't have to remember what it asked for.
+ *
  * Returns `undefined` when the provider declares no ceiling, so the caller falls back to the generic wording
  * rather than reporting a limit it invented.
  */
@@ -364,18 +437,20 @@ export function issueSearchCapResultWarning(
 	domain: string | undefined,
 	connectionId: string | undefined,
 	totalCount: number | undefined,
+	sort: IssueSorting,
 ): ProviderWarning | undefined {
 	const limit = providersMetadata[id]?.issueSearchResultLimit;
 	if (limit == null) return undefined;
 	// Below the ceiling this warning would be a false claim; the caller's truncation had another cause.
 	if (totalCount == null || totalCount <= limit) return undefined;
 
+	const [field, direction] = sort.split(':');
 	return {
 		...otherWarning(
 			id,
 			domain,
 			connectionId,
-			`Issue search matched ${totalCount} results, but '${id}' serves at most ${limit}; narrow the search to read the rest.`,
+			`Issue search matched ${totalCount} results, but '${id}' serves at most ${limit}, ordered by ${field} ${direction}ending; narrow the search to read the rest.`,
 		),
 		omission: {
 			kind: 'provider-limit',
@@ -383,6 +458,7 @@ export function issueSearchCapResultWarning(
 			recovery: 'none',
 			limit: limit,
 			totalCount: totalCount,
+			sort: sort,
 		},
 	};
 }
@@ -393,22 +469,28 @@ export function pullRequestSearchCapResultWarning(
 	domain: string | undefined,
 	connectionId: string | undefined,
 	totalCount: number | undefined,
+	sort: PullRequestSorting,
 ): ProviderWarning | undefined {
 	const limit = providersMetadata[id]?.pullRequestSearchResultLimit;
 	if (limit == null || totalCount == null || totalCount <= limit) return undefined;
 
+	// Name the order: the reachable window is the first `limit` under THIS sort, and a different key reaches a
+	// different subset, so a ceiling message that omits it can't say which slice was served. Same reasoning as
+	// `issueSearchCapResultWarning`.
+	const [field, direction] = sort.split(':');
 	return {
 		...otherWarning(
 			id,
 			domain,
 			connectionId,
-			`Pull request search matched ${totalCount} results, but '${id}' serves at most ${limit}; narrow the search to read the rest.`,
+			`Pull request search matched ${totalCount} results, but '${id}' serves at most ${limit}, ordered by ${field} ${direction}ending; narrow the search to read the rest.`,
 		),
 		omission: {
 			kind: 'provider-limit',
 			recovery: 'none',
 			limit: limit,
 			totalCount: totalCount,
+			sort: sort,
 		},
 	};
 }

package/src/plus/integrations/results.ts

@@ -1,4 +1,6 @@
 import { AuthenticationError, RequestNotFoundError, RequestRateLimitError } from '../../git/errors.js';
+import type { IssueSorting } from '../../git/models/issue.js';
+import type { PullRequestSorting } from '../../git/models/pullRequest.js';
 import type { IntegrationIds } from './constants.js';
 
 export interface ConnectionStateChangeEvent {
@@ -77,6 +79,19 @@ export interface ProviderWarningOmission {
 	limit?: number;
 	/** Total matches the provider reported, when it reports one. Only GitHub's search cap does today. */
 	totalCount?: number;
+	/**
+	 * The order the reachable window was selected under, as `field:direction`, when the omission is a result
+	 * ceiling.
+	 *
+	 * Present so a consumer can word its own "N matched, showing the first M" without assuming WHICH M: the
+	 * provider serves the top M under this key, so the sentence is only true if it names it. Absent for every
+	 * omission that isn't a ceiling, where no window was selected by an order.
+	 *
+	 * A union of both vocabularies rather than the issue one alone: `PullRequestSorting` happens to be a subset
+	 * today, so narrowing this to {@link IssueSorting} would still compile while describing only half the reads
+	 * that set it — and would break the day the PR search gains a key the issue search has no name for.
+	 */
+	sort?: IssueSorting | PullRequestSorting;
 	/** Which repository / project / resource was affected, when one is attributed. */
 	scope?: ProviderWarningOmissionScope;
 }