@gitkraken/core-gitlens 0.5.109 → 0.5.110

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

@@ -1,4 +1,5 @@
 import type { IssueSearchCriteria } from '../../../git/models/issue.js';
+import type { PullRequestSearchCriteria } from '../../../git/models/pullRequest.js';
 import { chunk } from '../../../utils/array.js';
 import { mapBounded } from '../../../utils/promise.js';
 import type { IntegrationIds } from '../constants.js';
@@ -14,12 +15,18 @@ import {
 } from '../utils/integration.utils.js';
 import type { ProviderReadContext } from './context.js';
 import { runCaptured } from './drains.js';
-import { resolveIssueSearchCriteria, resolveIssueSearchScope } from './filters.js';
+import {
+	resolveIssueSearchCriteria,
+	resolveIssueSearchScope,
+	resolvePullRequestSearchCriteria,
+	resolvePullRequestSearchScope,
+} from './filters.js';
 import {
 	gitHostOnlySurfaceWarning,
 	issuesUnsupportedWarning,
 	otherWarning,
 	unsupportedIssueSearchCriteriaWarning,
+	unsupportedPullRequestSearchCriteriaWarning,
 } from './warnings.js';
 
 /**
@@ -32,6 +39,15 @@ import {
  */
 const issueCountChunkSize = 25;
 
+/**
+ * How many pull-request scopes go into one upstream request.
+ *
+ * The same latency/complexity reasoning as {@link issueCountChunkSize}, kept slightly smaller because a pull-request
+ * scope can fan out into one aliased count PER requested state (open/closed/merged), so a chunk of scopes carries a
+ * small multiple of that many `search` aliases.
+ */
+const pullRequestCountChunkSize = 15;
+
 /**
  * One scope to count.
  *
@@ -73,6 +89,42 @@ export interface IssueCountResult {
 	providerLimit?: number;
 }
 
+/**
+ * One scope to count pull requests over — the PR twin of {@link IssueCountScope}.
+ *
+ * `key` is caller-owned and echoed back verbatim, never reaching the provider query (the aliases are generated), so
+ * it can be any string the caller finds meaningful.
+ */
+export interface PullRequestCountScope {
+	key: string;
+	/** Repositories to count over. Combines with `org`, exactly as in `searchPullRequestsPage`. */
+	repos?: ProviderReposInput;
+	org?: string;
+	/**
+	 * Same criteria model as `searchPullRequestsPage`, validated against the same capability table — so a count
+	 * refuses exactly what the read would, and never previews a fetch that can't happen.
+	 */
+	criteria?: PullRequestSearchCriteria;
+}
+
+/** The count for one {@link PullRequestCountScope}, echoed back under the caller's own `key`. */
+export interface PullRequestCountResult {
+	key: string;
+	/**
+	 * Total matches the provider reports. `undefined` when the provider didn't report one for this scope — NEVER
+	 * zero, which is a real answer. For a multi-state scope this is the LARGEST of its per-state counts, the same
+	 * total `searchPullRequestsPage` surfaces, not their sum.
+	 */
+	count?: number;
+	/**
+	 * True when `count` exceeds the provider's own per-search result ceiling, so a full read CANNOT return
+	 * everything no matter how it is paged. This is the signal to warn before starting an expensive fetch.
+	 */
+	exceedsProviderLimit: boolean;
+	/** The ceiling itself, when the provider declares one. */
+	providerLimit?: number;
+}
+
 /**
  * Counts issues for many scopes without fetching any — the probe behind a "this will fetch ~N issues" preview.
  *
@@ -228,7 +280,7 @@ export async function countIssues(
 }
 
 /** The first key that appears twice, or `undefined` when every key is unique. */
-function findDuplicateKey(scopes: readonly IssueCountScope[]): string | undefined {
+function findDuplicateKey(scopes: readonly { key: string }[]): string | undefined {
 	const seen = new Set<string>();
 	for (const scope of scopes) {
 		if (seen.has(scope.key)) return scope.key;
@@ -290,3 +342,222 @@ function rejectScope(
 
 	return undefined;
 }
+
+/**
+ * Counts pull requests for many scopes without fetching any — the PR twin of {@link countIssues}, and the probe
+ * behind a "this will fetch ~N pull requests" preview.
+ *
+ * Identical batching, per-scope isolation, and `key`-echo contract as {@link countIssues}; see it for the cost
+ * model and the `count: undefined` ≠ zero rule. The one difference is inherent to pull requests: a scope's criteria
+ * can name several STATES, which the provider counts as independent searches — the reported `count` is the LARGEST
+ * of them (mirroring `searchPullRequestsPage`'s total), so an unpaged read still can't exceed a single search's
+ * ceiling undetected.
+ */
+export async function countPullRequests(
+	ctx: ProviderReadContext,
+	options: {
+		providerId: IntegrationIds;
+		scopes: readonly PullRequestCountScope[];
+		connectionId?: string;
+		/**
+		 * Explicit self-managed host domain. Used only when the requested connection has no configured domain;
+		 * it must come from the trusted authentication configuration, not repository or remote data.
+		 */
+		domain?: string;
+	},
+): Promise<ProviderResult<PullRequestCountResult>> {
+	const refused = (warning: ProviderWarning): ProviderResult<PullRequestCountResult> => ({
+		items: [],
+		warnings: [warning],
+		fetchFailed: true,
+	});
+
+	if (isIssuesHostIntegrationId(options.providerId)) {
+		return refused(
+			gitHostOnlySurfaceWarning(options.providerId, undefined, options.connectionId, 'Pull request counts'),
+		);
+	}
+
+	// Nothing was asked for, so nothing is missing: an empty success, not a refusal.
+	if (options.scopes.length === 0) return { items: [], warnings: [] };
+
+	const duplicateKey = findDuplicateKey(options.scopes);
+	if (duplicateKey != null) {
+		// Refuses the whole call rather than deduping: `key` exists so the caller can match results without
+		// positional bookkeeping, and two results under one key make that ambiguous for EVERY scope, not just the
+		// repeated one.
+		return refused(
+			otherWarning(
+				options.providerId,
+				undefined,
+				options.connectionId,
+				`Duplicate pull request count scope key '${duplicateKey}'; keys identify results, so each must be unique.`,
+			),
+		);
+	}
+
+	const integration = await ctx.getIntegrationForRead(options.providerId, options.connectionId, options.domain);
+	if (integration == null) {
+		// A supplied connection or domain that no longer resolves is a broken target, not an empty account.
+		const early = ctx.earlyReturnConnectionWarnings(options.providerId, options.connectionId, options.domain);
+		return { items: [], warnings: early.warnings, fetchFailed: early.fetchFailed || undefined };
+	}
+	if (!isGitHostIntegration(integration)) {
+		return refused(
+			gitHostOnlySurfaceWarning(options.providerId, undefined, options.connectionId, 'Pull request counts'),
+		);
+	}
+
+	const domain = ctx.domainForRead(integration, options.providerId, options.connectionId, options.domain);
+	const warnOnMissingSession = warnOnMissingSessionForDomain(options.providerId, options.domain);
+
+	// A provider with no filtered pull-request search has no count either: refuse ONCE for the provider rather than
+	// letting every scope repeat the same rejection. `undefined` criteria probes only the search's existence.
+	const searchSupport = resolvePullRequestSearchCriteria(options.providerId, undefined);
+	if (searchSupport.rejection != null) {
+		return refused(
+			unsupportedPullRequestSearchCriteriaWarning(
+				options.providerId,
+				domain,
+				options.connectionId,
+				searchSupport.rejection,
+			),
+		);
+	}
+
+	const providerLimit = providersMetadata[options.providerId]?.pullRequestSearchResultLimit;
+	const warnings: ProviderWarning[] = [];
+	let fetchFailed = false;
+
+	// Validate every scope first, so a refusal costs no request at all and the countable ones are still batched
+	// together.
+	const countable: PullRequestCountScope[] = [];
+	for (const scope of options.scopes) {
+		const warning = rejectPullRequestScope(options.providerId, domain, options.connectionId, scope);
+		if (warning != null) {
+			// `push`, not `appendDedupedWarning`: every rejection message embeds the scope's own key, and duplicate
+			// keys were already refused above, so no two of these can ever collapse.
+			warnings.push(warning);
+			fetchFailed = true;
+			continue;
+		}
+
+		countable.push(scope);
+	}
+
+	// Chunks are independent requests over their own slice of scopes, `runCaptured` never throws, so they run
+	// concurrently, bounded like every other fan-out on the facade. `mapBounded` returns in input order, so `items`
+	// and `warnings` stay in scope order.
+	const batches = await mapBounded(chunk(countable, pullRequestCountChunkSize), providerFanOutConcurrency, batch =>
+		runCaptured(
+			options.providerId,
+			domain,
+			options.connectionId,
+			() =>
+				integration.countPullRequestsResult(
+					batch.map(s => ({
+						repos: s.repos as ProviderRepoInput[] | undefined,
+						org: s.org,
+						criteria: s.criteria,
+					})),
+					undefined,
+					options.connectionId,
+				),
+			{ warnOnMissingSession: warnOnMissingSession },
+		).then(result => ({ batch: batch, ...result })),
+	);
+
+	const items: PullRequestCountResult[] = [];
+	for (const { batch, value, warning } of batches) {
+		if (warning != null) {
+			appendDedupedWarning(warnings, warning);
+		}
+		if (value == null) {
+			// This batch contributes nothing, but the batches around it still do. Drop only these scopes.
+			fetchFailed = true;
+			continue;
+		}
+
+		for (let i = 0; i < batch.length; i++) {
+			const count = value[i];
+			items.push({
+				key: batch[i].key,
+				count: count,
+				// Only a reported count can exceed a declared ceiling; unknown-vs-limit is not a comparison.
+				exceedsProviderLimit: count != null && providerLimit != null && count > providerLimit,
+				providerLimit: providerLimit,
+			});
+		}
+	}
+
+	// A provider that reported nothing for any scope and raised no warning: say so explicitly rather than letting it
+	// read as "every scope matched nothing".
+	if (items.length === 0 && warnings.length === 0) {
+		return refused(
+			unsupportedPullRequestSearchCriteriaWarning(options.providerId, domain, options.connectionId, {
+				reason: 'unsupported-search',
+			}),
+		);
+	}
+
+	return { items: items, warnings: warnings, fetchFailed: fetchFailed || undefined };
+}
+
+/**
+ * Why one pull-request scope can't be counted, as the warning to report — or `undefined` when it can. The PR twin
+ * of {@link rejectScope}, validating against the same {@link resolvePullRequestSearchScope} /
+ * {@link resolvePullRequestSearchCriteria} the read uses, so a count always previews the constraints the read
+ * would apply.
+ */
+function rejectPullRequestScope(
+	providerId: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	scope: PullRequestCountScope,
+): ProviderWarning | undefined {
+	const scoping = resolvePullRequestSearchScope(providerId, scope.repos, scope.org, scope.criteria);
+	switch (scoping.rejection) {
+		case 'repo-ids':
+			return otherWarning(
+				providerId,
+				domain,
+				connectionId,
+				`Pull request count scope '${scope.key}' cannot be scoped by repository id; pass repository descriptors (namespace + name) instead.`,
+			);
+		case 'unscoped':
+			return otherWarning(
+				providerId,
+				domain,
+				connectionId,
+				`Pull request count scope '${scope.key}' is unscoped; pass \`repos\`, \`org\`, or at least one current-user relationship.`,
+			);
+		case 'unsupported-repository-scope':
+		case 'unsupported-organization-scope':
+			return unsupportedPullRequestSearchCriteriaWarning(providerId, domain, connectionId, {
+				reason: 'unsupported-criteria',
+				criteria: [
+					scoping.rejection === 'unsupported-repository-scope' ? 'repositoryScope' : 'organizationScope',
+				],
+			});
+	}
+
+	const resolved = resolvePullRequestSearchCriteria(providerId, scope.criteria);
+	if (resolved.rejection != null) {
+		return unsupportedPullRequestSearchCriteriaWarning(providerId, domain, connectionId, resolved.rejection);
+	}
+
+	// Count-only, with no counterpart in the read: a relationship set is an OR across several searches, which one
+	// count can't express — summing would double-count overlaps and max would under-report. Ask the caller to count
+	// each relationship as its own scope, where the keys make the OR explicit. (States are disjoint, so a scope may
+	// still name several — the provider counts them as the max, not a refusal.)
+	if ((scope.criteria?.relationships?.length ?? 0) > 1) {
+		return otherWarning(
+			providerId,
+			domain,
+			connectionId,
+			`Pull request count scope '${scope.key}' requests several relationships, which a single count can't express (they are OR-ed, so overlapping matches would be double-counted); pass one scope per relationship.`,
+		);
+	}
+
+	return undefined;
+}

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

@@ -70,7 +70,12 @@ export async function drainPullRequests(
 	repos: ProviderReposInput,
 	state: PullRequestStateFilter[] | undefined,
 	filters: PullRequestFilter[] | undefined,
-	includeReviewRequested: boolean,
+	/**
+	 * Breadth opt-ins that only the account-wide read can express. Grouped rather than passed positionally
+	 * because they are same-typed neighbors a transposition would silently swap, and picked from the sweep
+	 * options rather than restated so a third opt-in is declared once.
+	 */
+	accountWideOptions: Pick<PullRequestSweepOptions, 'includeReviewRequested' | 'includeReviews'> | undefined,
 	connectionId: string | undefined,
 	maxPages: number,
 	attributeUnavailableProvider: boolean,
@@ -100,6 +105,10 @@ export async function drainPullRequests(
 	// With no repos this is an account-wide "my PRs" sweep. The repo-scoped core rejects an empty `repos`
 	// input, so read the provider-native account-wide core instead.
 	const accountWide = repos.length === 0;
+	// The breadth opt-ins are only expressible on the account-wide core, so gate them here — the single place
+	// that already knows which core it is about to call.
+	const includeReviewRequested = accountWide && (accountWideOptions?.includeReviewRequested ?? false);
+	const includeReviews = accountWide && (accountWideOptions?.includeReviews ?? false);
 	/** Every cursor already followed, so a provider that cycles them can't keep the drain walking in circles. */
 	const seenCursors = new Set<string>();
 
@@ -115,7 +124,8 @@ export async function drainPullRequests(
 							cursor: pageCursor,
 							includeReviewRequested: includeReviewRequested,
 							filters: filters,
-							summary: true,
+							// Lite by default; the full projection (reviews) only when a caller opts in.
+							summary: !includeReviews,
 						},
 						connectionId,
 					)

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

@@ -104,9 +104,25 @@ export function resolvePullRequestSearchCriteria(
 	if (criteria.text != null && criteria.text.trim().length > 0 && !supported.text) {
 		unsupported.push('text');
 	}
+	if (criteria.updatedAfter != null && !supported.updatedAfter) {
+		unsupported.push('updatedAfter');
+	}
+	if (criteria.createdAfter != null && !supported.createdAfter) {
+		unsupported.push('createdAfter');
+	}
 	if (criteria.includeArchived === true && !supported.includeArchived) {
 		unsupported.push('includeArchived');
 	}
+	// `!= null`, not truthy: `draft: false` (only ready-for-review) is as much a request as `draft: true`.
+	if (criteria.draft != null && !supported.draft) {
+		unsupported.push('draft');
+	}
+	// Folded into the same `unsupported-criteria` rejection rather than its own reason, so a caller asking for one
+	// inexpressible filter and one inexpressible sort learns about both at once. `updated:desc` is always in
+	// `sorts` for a usable search, so the omitted (default) case never rejects.
+	if (criteria.sort != null && !supported.sorts.includes(criteria.sort)) {
+		unsupported.push(`sort:${criteria.sort}`);
+	}
 
 	return unsupported.length > 0 ? { rejection: { reason: 'unsupported-criteria', criteria: unsupported } } : {};
 }
@@ -279,9 +295,13 @@ const unsupportedPullRequestSearchCapabilities: PullRequestSearchCapabilities =
 	relationships: [],
 	states: [],
 	text: false,
+	updatedAfter: false,
+	createdAfter: false,
 	includeArchived: false,
+	draft: false,
 	repositoryScope: false,
 	organizationScope: false,
+	sorts: [],
 };
 
 /** Why a filtered issue search's scope was refused, or `undefined` when it is usable. */
@@ -428,6 +448,8 @@ export function getSupportedFilters(providerId: IntegrationIds): SupportedFilter
 			...pullRequestSearch,
 			relationships: [...(pullRequestSearch?.relationships ?? [])],
 			states: [...(pullRequestSearch?.states ?? [])],
+			// Copied, so mutating the result can't corrupt the metadata table.
+			sorts: [...(pullRequestSearch?.sorts ?? [])],
 		},
 		issues: [...(metadata?.supportedIssueFilters ?? [])],
 		issuesAccountWide: [...(metadata?.supportedAccountWideIssueFilters ?? [])],

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

@@ -5,6 +5,7 @@ import type {
 	IssueSorting,
 	PullRequestFilter,
 	PullRequestSearchCapabilities,
+	PullRequestSorting,
 } from '../providerFilters.js';
 import { providersMetadata } from '../providers/models.js';
 import type { ProviderWarning } from '../results.js';
@@ -286,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(', ');
 }
 
@@ -464,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,5 +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 {
@@ -85,8 +86,12 @@ export interface ProviderWarningOmission {
 	 * 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;
+	sort?: IssueSorting | PullRequestSorting;
 	/** Which repository / project / resource was affected, when one is attributed. */
 	scope?: ProviderWarningOmissionScope;
 }