@gitkraken/core-gitlens 0.5.107 → 0.5.109

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/sweeps.ts

@@ -2,7 +2,12 @@ import type { PullRequestShape } from '../../../git/models/pullRequest.js';
 import { mapBounded } from '../../../utils/promise.js';
 import type { IntegrationIds } from '../constants.js';
 import { providerFanOutConcurrency } from '../constants.js';
-import type { ClosedPullRequestSweepOptions, PullRequestSweepOptions } from '../manager.js';
+import type {
+	ClosedPullRequestSweepOptions,
+	ProviderSweepTarget,
+	ProviderSweepTargetEvent,
+	PullRequestSweepOptions,
+} from '../manager.js';
 import { fromProviderPullRequest } from '../providers/models.js';
 import type { ProviderSweepResult, ProviderWarning } from '../results.js';
 import { appendDedupedWarning } from '../results.js';
@@ -37,89 +42,158 @@ interface SweepSlice {
 	failedProvider: boolean;
 }
 
-export async function sweepPullRequests(
+/**
+ * Drain ONE sweep target. Extracted from the fan-out so the fan-out callback has a single exit: every
+ * per-target observation (see `onTargetSettled`) is then reported in one place instead of at each of this
+ * function's several early returns, where a missed branch would silently drop a provider's attribution.
+ *
+ * `undefined` means the target resolved to no reachable connection and is deliberately not attributed in the
+ * aggregate result.
+ */
+async function sweepTarget(
 	ctx: ProviderReadContext,
-	options?: PullRequestSweepOptions,
-): Promise<ProviderSweepResult<PullRequestShape>> {
-	const { targets, attributeUnavailableProviders } = resolvePullRequestSweepTargets(options);
-	const maxPages = options?.maxPages ?? 100;
+	options: PullRequestSweepOptions | undefined,
+	target: ProviderSweepTarget,
+	attributeUnavailableProviders: boolean,
+): Promise<SweepSlice | undefined> {
+	const { providerId: id, connectionId, domain: requestedDomain } = target;
 	const repos = options?.repos ?? [];
+	const maxPages = options?.maxPages ?? 100;
+	/** A target that never reached a drain: the provider itself failed, so its slice is empty and attributed. */
+	const rejectedTarget = (warnings: ProviderWarning[]): SweepSlice => ({
+		items: [],
+		warnings: warnings,
+		fetchFailed: true,
+		truncated: false,
+		providerId: id,
+		failedProvider: true,
+	});
 
-	const results = await mapBounded(targets, providerFanOutConcurrency, async target => {
-		const { providerId: id, connectionId, domain: requestedDomain } = target;
-		/** A target that never reached a drain: the provider itself failed, so its slice is empty and attributed. */
-		const rejectedTarget = (warnings: ProviderWarning[]): SweepSlice => ({
-			items: [],
-			warnings: warnings,
-			fetchFailed: true,
-			truncated: false,
-			providerId: id,
-			failedProvider: true,
-		});
-
-		if (isIssuesHostIntegrationId(id)) {
-			return rejectedTarget([
-				gitHostOnlySurfaceWarning(id, requestedDomain, connectionId, 'pull request sweeps'),
-			]);
-		}
+	if (isIssuesHostIntegrationId(id)) {
+		return rejectedTarget([gitHostOnlySurfaceWarning(id, requestedDomain, connectionId, 'pull request sweeps')]);
+	}
 
-		const integration = await ctx.getIntegrationForRead(id, connectionId, requestedDomain);
-		if (integration == null) {
-			// A requested connection that can't be resolved is a broken connection — surface it as a
-			// warning + fetchFailed rather than dropping the provider's slice silently.
-			const early = ctx.earlyReturnConnectionWarnings(id, connectionId, requestedDomain);
-			if (early.warnings.length === 0 && !attributeUnavailableProviders) return undefined;
+	const integration = await ctx.getIntegrationForRead(id, connectionId, requestedDomain);
+	if (integration == null) {
+		// A requested connection that can't be resolved is a broken connection — surface it as a
+		// warning + fetchFailed rather than dropping the provider's slice silently.
+		const early = ctx.earlyReturnConnectionWarnings(id, connectionId, requestedDomain);
+		if (early.warnings.length === 0 && !attributeUnavailableProviders) return undefined;
 
-			return rejectedTarget(
-				early.warnings.length !== 0 ? early.warnings : [noConnectionWarning(id, requestedDomain, connectionId)],
-			);
-		}
-		if (!isGitHostIntegration(integration)) {
-			return rejectedTarget([
-				gitHostOnlySurfaceWarning(id, requestedDomain, connectionId, 'pull request sweeps'),
-			]);
-		}
+		return rejectedTarget(
+			early.warnings.length !== 0 ? early.warnings : [noConnectionWarning(id, requestedDomain, connectionId)],
+		);
+	}
+	if (!isGitHostIntegration(integration)) {
+		return rejectedTarget([gitHostOnlySurfaceWarning(id, requestedDomain, connectionId, 'pull request sweeps')]);
+	}
 
-		await ctx.forceRefreshIfRequested(integration, options?.forceSync, connectionId);
-
-		const domain = ctx.domainForRead(integration, id, connectionId, requestedDomain);
-		const accountWide = repos.length === 0;
-		const requestedFilters = target.filters ?? options?.filters;
-		const resolved = accountWide
-			? resolveAccountWidePullRequestFilters(id, requestedFilters)
-			: resolvePullRequestFilters(id, requestedFilters);
-		if (resolved.unsupported) {
-			return rejectedTarget([
-				accountWide
-					? unsupportedAccountWidePullRequestFiltersWarning(id, domain, connectionId, requestedFilters ?? [])
-					: unsupportedFiltersWarning(id, domain, connectionId),
-			]);
-		}
+	await ctx.forceRefreshIfRequested(integration, options?.forceSync, connectionId);
 
-		const drain = await drainPullRequests(
-			integration,
-			id,
-			domain,
-			repos,
-			options?.states,
-			resolved.filters,
-			accountWide ? (options?.includeReviewRequested ?? false) : false,
-			connectionId,
-			maxPages,
-			attributeUnavailableProviders,
-		);
-		const currentAccountId = drain.items.some(pr => pr.author != null)
-			? await getCurrentAccountId(integration, connectionId)
-			: undefined;
-		// Normalize the raw provider-apis PRs to the GitLens-owned shape here, where the per-provider
-		// `integration` (the mapper's provider reference) is in scope; the aggregation below only sees drains.
-		return {
-			...drain,
-			items: drain.items.map(pr =>
-				fromProviderPullRequest(pr, integration, { currentAccountId: currentAccountId }),
-			),
-			providerId: id,
+	const domain = ctx.domainForRead(integration, id, connectionId, requestedDomain);
+	const accountWide = repos.length === 0;
+	const requestedFilters = target.filters ?? options?.filters;
+	const resolved = accountWide
+		? resolveAccountWidePullRequestFilters(id, requestedFilters)
+		: resolvePullRequestFilters(id, requestedFilters);
+	if (resolved.unsupported) {
+		return rejectedTarget([
+			accountWide
+				? unsupportedAccountWidePullRequestFiltersWarning(id, domain, connectionId, requestedFilters ?? [])
+				: unsupportedFiltersWarning(id, domain, connectionId),
+		]);
+	}
+
+	const drain = await drainPullRequests(
+		integration,
+		id,
+		domain,
+		repos,
+		options?.states,
+		resolved.filters,
+		accountWide ? (options?.includeReviewRequested ?? false) : false,
+		connectionId,
+		maxPages,
+		attributeUnavailableProviders,
+	);
+	const currentAccountId = drain.items.some(pr => pr.author != null)
+		? await getCurrentAccountId(integration, connectionId)
+		: undefined;
+	// Normalize the raw provider-apis PRs to the GitLens-owned shape here, where the per-provider
+	// `integration` (the mapper's provider reference) is in scope; the aggregation below only sees drains.
+	return {
+		...drain,
+		items: drain.items.map(pr => fromProviderPullRequest(pr, integration, { currentAccountId: currentAccountId })),
+		providerId: id,
+	};
+}
+
+/**
+ * How a target ended, as the consumer buckets it. `failedProvider` outranks `fetchFailed` because a target
+ * whose provider failed produced no slice to be partial about, and `undefined` is the target that resolved to
+ * no reachable connection at all.
+ */
+function sliceOutcome(slice: SweepSlice | undefined): ProviderSweepTargetEvent['outcome'] {
+	if (slice == null) return 'skipped';
+	if (slice.failedProvider) return 'failed-provider';
+	if (slice.fetchFailed) return 'fetch-failed';
+	return 'ok';
+}
+
+/**
+ * Per-target reporting for a sweep's `onTargetSettled`, opened once per sweep: this stamps the fan-out start,
+ * the returned function stamps one target's start, and the function IT returns is the only thing that can
+ * report that target. The timestamps therefore never cross a boundary, so there is no pair of interchangeable
+ * numbers for a call site to transpose, and the whole reporting concern is one value the fan-out either has or
+ * does not. That is also what keeps the option free when it is omitted: with no observer there is nothing to
+ * open, so no clock is read and no reporting object exists — do not "simplify" that into an unconditional
+ * open, because a host whose perf gate is off (the default) is entitled to pay nothing for it.
+ *
+ * The try/catch is what makes the observer observation-only: called from the fan-out's success path, a throwing
+ * callback would otherwise propagate out of the `mapBounded` task and reject the entire sweep — corrupting the
+ * read, not just the metric. Swallowed silently; the consumer owns its own aggregation.
+ *
+ * The domain is resolved here rather than carried out of {@link sweepTarget}, so every target reports it by the
+ * same rule no matter how far it got. `resolveDomainForRead` needs no integration instance, which is what makes
+ * that possible: a target rejected by the first guard resolves the same host a fully drained one does.
+ */
+function startSweepReporting(ctx: ProviderReadContext, observe: (event: ProviderSweepTargetEvent) => void) {
+	const fanOutStartedAt = performance.now();
+
+	return function beginTarget(target: ProviderSweepTarget) {
+		const startedAt = performance.now();
+
+		return function reportSettled(slice: SweepSlice | undefined) {
+			try {
+				observe({
+					providerId: target.providerId,
+					domain: ctx.resolveDomainForRead(target.providerId, target.connectionId, target.domain),
+					connectionId: target.connectionId,
+					count: slice?.items.length ?? 0,
+					durationMs: performance.now() - startedAt,
+					queueWaitMs: startedAt - fanOutStartedAt,
+					outcome: sliceOutcome(slice),
+					truncated: slice?.truncated ?? false,
+				});
+			} catch {}
 		};
+	};
+}
+
+export async function sweepPullRequests(
+	ctx: ProviderReadContext,
+	options?: PullRequestSweepOptions,
+): Promise<ProviderSweepResult<PullRequestShape>> {
+	const { targets, attributeUnavailableProviders } = resolvePullRequestSweepTargets(options);
+
+	const observe = options?.onTargetSettled;
+	const beginTarget = observe != null ? startSweepReporting(ctx, observe) : undefined;
+
+	const results = await mapBounded(targets, providerFanOutConcurrency, async target => {
+		const reportSettled = beginTarget?.(target);
+		const slice = await sweepTarget(ctx, options, target, attributeUnavailableProviders);
+		reportSettled?.(slice);
+		return slice;
 	});
 
 	const items: PullRequestShape[] = [];

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

@@ -2,12 +2,14 @@ import type { IntegrationIds } from '../constants.js';
 import type {
 	IssueFilter,
 	IssueSearchCapabilities,
+	IssueSorting,
 	PullRequestFilter,
 	PullRequestSearchCapabilities,
 } 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
@@ -343,9 +345,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 +420,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 +432,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 +453,7 @@ export function issueSearchCapResultWarning(
 			recovery: 'none',
 			limit: limit,
 			totalCount: totalCount,
+			sort: sort,
 		},
 	};
 }

package/src/plus/integrations/results.ts

@@ -1,4 +1,5 @@
 import { AuthenticationError, RequestNotFoundError, RequestRateLimitError } from '../../git/errors.js';
+import type { IssueSorting } from '../../git/models/issue.js';
 import type { IntegrationIds } from './constants.js';
 
 export interface ConnectionStateChangeEvent {
@@ -77,6 +78,15 @@ 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.
+	 */
+	sort?: IssueSorting;
 	/** Which repository / project / resource was affected, when one is attributed. */
 	scope?: ProviderWarningOmissionScope;
 }