@gitkraken/core-gitlens 0.5.104 → 0.5.106

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

@@ -5,6 +5,8 @@ import type {
 	IssueSearchCriteria,
 	IssueSearchRelationship,
 	PullRequestFilter,
+	PullRequestSearchCapabilities,
+	PullRequestSearchCriteria,
 } from '../providerFilters.js';
 import type { ProviderRepoInput, ProviderReposInput } from '../providers/models.js';
 import { providersMetadata } from '../providers/models.js';
@@ -65,6 +67,88 @@ export function resolveAccountWidePullRequestFilters(
 	return { filters: [...new Set(filters)], unsupported: false };
 }
 
+/** Why {@link resolvePullRequestSearchCriteria} refused a criteria set. */
+export type PullRequestSearchCriteriaRejection =
+	/** The provider has no filtered pull-request search. */
+	| { reason: 'unsupported-search' }
+	/** The provider has one, but cannot express every requested criterion server-side. */
+	| { reason: 'unsupported-criteria'; criteria: string[] };
+
+/**
+ * Validates filtered pull-request search criteria all-or-nothing. Dropping an unsupported criterion would
+ * widen the provider query while leaving its page and cursor describing the wider set, so the facade refuses the
+ * request before any upstream call instead.
+ */
+export function resolvePullRequestSearchCriteria(
+	id: IntegrationIds,
+	criteria: PullRequestSearchCriteria | undefined,
+): { rejection?: PullRequestSearchCriteriaRejection } {
+	const supported = providersMetadata[id]?.supportedPullRequestSearch;
+	if (supported == null || supported.relationships.length === 0) {
+		return { rejection: { reason: 'unsupported-search' } };
+	}
+	if (criteria == null) return {};
+
+	const unsupported: string[] = [];
+	for (const relationship of criteria.relationships ?? []) {
+		if (!supported.relationships.includes(relationship)) {
+			unsupported.push(`relationships:${relationship}`);
+		}
+	}
+	for (const state of criteria.states ?? []) {
+		if (!supported.states.includes(state)) {
+			unsupported.push(`states:${state}`);
+		}
+	}
+	if (criteria.text != null && criteria.text.trim().length > 0 && !supported.text) {
+		unsupported.push('text');
+	}
+	if (criteria.includeArchived === true && !supported.includeArchived) {
+		unsupported.push('includeArchived');
+	}
+
+	return unsupported.length > 0 ? { rejection: { reason: 'unsupported-criteria', criteria: unsupported } } : {};
+}
+
+/** Why a filtered pull-request search's repository/organization boundary was refused. */
+export type PullRequestSearchScopeRejection =
+	| 'unscoped'
+	| 'repo-ids'
+	| 'unsupported-repository-scope'
+	| 'unsupported-organization-scope';
+
+/**
+ * Validates the search boundary independently from its criteria. A current-user relationship is itself a safe
+ * account-wide boundary; without one, a repository or organization scope is mandatory.
+ */
+export function resolvePullRequestSearchScope(
+	id: IntegrationIds,
+	repos: ProviderReposInput | undefined,
+	org: string | undefined,
+	criteria: PullRequestSearchCriteria | undefined,
+): { rejection?: PullRequestSearchScopeRejection; repos?: ProviderRepoInput[] } {
+	const supported = providersMetadata[id]?.supportedPullRequestSearch;
+	let resolvedRepos: ProviderRepoInput[] | undefined;
+
+	if (repos?.length) {
+		if (repos.some(r => typeof r === 'string' || typeof r === 'number')) return { rejection: 'repo-ids' };
+		if (supported?.repositoryScope !== true) return { rejection: 'unsupported-repository-scope' };
+
+		resolvedRepos = repos as ProviderRepoInput[];
+	}
+
+	const hasOrganizationScope = org != null && org.length > 0;
+	if (hasOrganizationScope && supported?.organizationScope !== true) {
+		return { rejection: 'unsupported-organization-scope' };
+	}
+
+	if (resolvedRepos != null || hasOrganizationScope || (criteria?.relationships?.length ?? 0) > 0) {
+		return { repos: resolvedRepos };
+	}
+
+	return { rejection: 'unscoped' };
+}
+
 /**
  * Validates a caller-provided issue filter set against what the provider's ACCOUNT-WIDE issue read can express
  * server-side (`ProviderMetadata.supportedAccountWideIssueFilters`), which is a different — usually narrower —
@@ -182,6 +266,16 @@ const unsupportedIssueSearchCapabilities: IssueSearchCapabilities = {
 	states: false,
 };
 
+/** What a provider with no filtered pull-request search reports. */
+const unsupportedPullRequestSearchCapabilities: PullRequestSearchCapabilities = {
+	relationships: [],
+	states: [],
+	text: false,
+	includeArchived: false,
+	repositoryScope: false,
+	organizationScope: false,
+};
+
 /** Why a filtered issue search's scope was refused, or `undefined` when it is usable. */
 export type IssueSearchScopeRejection =
 	/** No repositories, no org, and no user-relative relationship: a search of the whole host. */
@@ -248,6 +342,9 @@ export function resolveIssueSearchScope(
  * rather than a list, because its criteria aren't a single kind. An empty `relationships` means the provider has
  * no filtered issue search — hide the surface, not just its chips.
  *
+ * `pullRequestSearch` describes the separate filtered PR search. Its table declares each criteria vocabulary
+ * plus repository/organization scope support; an empty relationship list means the search itself is absent.
+ *
  * Note this is a CAPABILITY table — "what the provider can express" — not a recommendation. A consumer
  * matching another tool's behavior may deliberately pass fewer filters than are listed here (or none, where an
  * already-scoped read would only be narrowed by them). Intersecting against this table is what keeps a
@@ -256,15 +353,23 @@ export function resolveIssueSearchScope(
 export function getSupportedFilters(providerId: IntegrationIds): {
 	pullRequests: PullRequestFilter[];
 	pullRequestsAccountWide: PullRequestFilter[];
+	pullRequestSearch: PullRequestSearchCapabilities;
 	issues: IssueFilter[];
 	issuesAccountWide: IssueFilter[];
 	issueSearch: IssueSearchCapabilities;
 } {
 	const metadata = providersMetadata[providerId];
 	const issueSearch = metadata?.supportedIssueSearch;
+	const pullRequestSearch = metadata?.supportedPullRequestSearch;
 	return {
 		pullRequests: [...(metadata?.supportedPullRequestFilters ?? [])],
 		pullRequestsAccountWide: [...(metadata?.supportedAccountWidePullRequestFilters ?? [])],
+		pullRequestSearch: {
+			...unsupportedPullRequestSearchCapabilities,
+			...pullRequestSearch,
+			relationships: [...(pullRequestSearch?.relationships ?? [])],
+			states: [...(pullRequestSearch?.states ?? [])],
+		},
 		issues: [...(metadata?.supportedIssueFilters ?? [])],
 		issuesAccountWide: [...(metadata?.supportedAccountWideIssueFilters ?? [])],
 		// Always an object, never `undefined`: a provider WITHOUT a filtered issue search reports one whose

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

@@ -0,0 +1,210 @@
+import type { PullRequestSearchCriteria, PullRequestShape } 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';
+import {
+	isGitHostIntegration,
+	isIssuesHostIntegrationId,
+	warnOnMissingSessionForDomain,
+} from '../utils/integration.utils.js';
+import type { ProviderReadContext } from './context.js';
+import { runCaptured } from './drains.js';
+import { resolvePullRequestSearchCriteria, resolvePullRequestSearchScope } from './filters.js';
+import {
+	drainFlatPagesToRequestedPage,
+	refusedPage,
+	resolveContinuation,
+	resolveCurrentPage,
+	usableCursor,
+} from './paging.js';
+import {
+	gitHostOnlySurfaceWarning,
+	otherWarning,
+	pullRequestSearchCapResultWarning,
+	truncationWarning,
+	unsupportedPullRequestSearchCriteriaWarning,
+} from './warnings.js';
+
+/**
+ * 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.
+ */
+export async function searchPullRequestsPage(
+	ctx: ProviderReadContext,
+	options: {
+		providerId: IntegrationIds;
+		repos?: ProviderReposInput;
+		org?: string;
+		criteria?: PullRequestSearchCriteria;
+		page?: number;
+		cursor?: string;
+		itemsPerPage?: number;
+		forceSync?: boolean;
+		connectionId?: string;
+		domain?: string;
+	},
+): Promise<ProviderPagedResult<PullRequestShape>> {
+	const page = Math.max(1, Math.trunc(options.page ?? 1));
+	const refused = (warning: ProviderWarning) => refusedPage<PullRequestShape>(1, [warning], true);
+
+	if (isIssuesHostIntegrationId(options.providerId)) {
+		return refused(
+			gitHostOnlySurfaceWarning(
+				options.providerId,
+				undefined,
+				options.connectionId,
+				'Filtered pull request search',
+			),
+		);
+	}
+
+	const integration = await ctx.getIntegrationForRead(options.providerId, options.connectionId, options.domain);
+	if (integration == null) {
+		const early = ctx.earlyReturnConnectionWarnings(options.providerId, options.connectionId, options.domain);
+		return refusedPage(1, early.warnings, early.fetchFailed);
+	}
+	if (!isGitHostIntegration(integration)) {
+		return refused(
+			gitHostOnlySurfaceWarning(
+				options.providerId,
+				undefined,
+				options.connectionId,
+				'Filtered pull request search',
+			),
+		);
+	}
+
+	await ctx.forceRefreshIfRequested(integration, options.forceSync, options.connectionId);
+
+	const domain = ctx.domainForRead(integration, options.providerId, options.connectionId, options.domain);
+	const warnOnMissingSession = warnOnMissingSessionForDomain(options.providerId, options.domain);
+
+	const resolved = resolvePullRequestSearchCriteria(options.providerId, options.criteria);
+	if (resolved.rejection != null) {
+		return refused(
+			unsupportedPullRequestSearchCriteriaWarning(
+				options.providerId,
+				domain,
+				options.connectionId,
+				resolved.rejection,
+			),
+		);
+	}
+
+	const scope = resolvePullRequestSearchScope(options.providerId, options.repos, options.org, options.criteria);
+	switch (scope.rejection) {
+		case 'unscoped':
+			return refused(
+				otherWarning(
+					options.providerId,
+					domain,
+					options.connectionId,
+					'A filtered pull request search must be scoped: pass `repos`, `org`, or at least one current-user relationship.',
+				),
+			);
+		case 'repo-ids':
+			return refused(
+				otherWarning(
+					options.providerId,
+					domain,
+					options.connectionId,
+					'A filtered pull request search cannot be scoped by repository id; pass repository descriptors (namespace + name) instead.',
+				),
+			);
+		case 'unsupported-repository-scope':
+		case 'unsupported-organization-scope':
+			return refused(
+				unsupportedPullRequestSearchCriteriaWarning(options.providerId, domain, options.connectionId, {
+					reason: 'unsupported-criteria',
+					criteria: [
+						scope.rejection === 'unsupported-repository-scope' ? 'repositoryScope' : 'organizationScope',
+					],
+				}),
+			);
+	}
+
+	const readPage = (cursor: string | undefined) =>
+		runCaptured(
+			options.providerId,
+			domain,
+			options.connectionId,
+			() =>
+				integration.searchPullRequestsPageResult(
+					{
+						repos: scope.repos,
+						org: options.org,
+						criteria: options.criteria,
+						cursor: cursor,
+						pageSize: options.itemsPerPage,
+					},
+					undefined,
+					options.connectionId,
+				),
+			{ warnOnMissingSession: warnOnMissingSession },
+		);
+
+	const first = await readPage(options.cursor);
+	const warnings = first.warning != null ? [first.warning] : [];
+	let totalCount = first.value?.totalCount;
+	const drained = await drainFlatPagesToRequestedPage(first, {
+		requestedPage: page,
+		suppliedCursor: options.cursor,
+		warnings: warnings,
+		readPage: readPage,
+		fold: p => {
+			if (p.totalCount != null) {
+				totalCount = Math.max(totalCount ?? 0, p.totalCount);
+			}
+		},
+	});
+	const { value, currentPage, requestedPageMissing } = drained;
+
+	if (value == null && warnings.length === 0) {
+		return refused(
+			unsupportedPullRequestSearchCriteriaWarning(options.providerId, domain, options.connectionId, {
+				reason: 'unsupported-search',
+			}),
+		);
+	}
+
+	const items = requestedPageMissing ? [] : (value?.values ?? []);
+	const continuation = resolveContinuation(
+		{
+			hasMore: requestedPageMissing ? false : (value?.hasMore ?? false),
+			cursor: requestedPageMissing ? undefined : usableCursor(value?.cursor),
+			truncated: drained.truncated,
+		},
+		undefined,
+	);
+	const truncated = continuation.truncated;
+	if (truncated && warnings.length === 0) {
+		warnings.push(
+			pullRequestSearchCapResultWarning(options.providerId, domain, options.connectionId, totalCount) ??
+				truncationWarning(options.providerId, domain, options.connectionId, 'Pull request search', 'exhausted'),
+		);
+	}
+
+	return {
+		items: items,
+		warnings: warnings,
+		page: {
+			currentPage: requestedPageMissing
+				? page
+				: resolveCurrentPage({
+						providerPage: currentPage,
+						requestedPage: page,
+						suppliedCursor: options.cursor,
+						pageAdvanceable: false,
+					}),
+			itemsPerPage: items.length,
+			truncated: truncated || undefined,
+		},
+		hasMore: continuation.hasMore,
+		cursor: continuation.cursor,
+		fetchFailed: drained.fetchFailed || undefined,
+	};
+}

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

@@ -1,8 +1,13 @@
 import type { IntegrationIds } from '../constants.js';
-import type { IssueFilter, IssueSearchCapabilities, PullRequestFilter } from '../providerFilters.js';
+import type {
+	IssueFilter,
+	IssueSearchCapabilities,
+	PullRequestFilter,
+	PullRequestSearchCapabilities,
+} from '../providerFilters.js';
 import { providersMetadata } from '../providers/models.js';
 import type { ProviderWarning } from '../results.js';
-import type { IssueSearchCriteriaRejection } from './filters.js';
+import type { IssueSearchCriteriaRejection, PullRequestSearchCriteriaRejection } from './filters.js';
 
 /**
  * The warnings the provider facade raises on its OWN terms, as opposed to the ones derived from a caught
@@ -154,7 +159,8 @@ type TruncatedReadKind =
 	| 'Organization'
 	| 'Project'
 	| 'Account-wide issue search'
-	| 'Issue search';
+	| 'Issue search'
+	| 'Pull request search';
 
 /** {@link incompleteReadWarning} for a paged or drained read, phrased per surface. */
 export function truncationWarning(
@@ -246,6 +252,44 @@ export function unsupportedFiltersWarning(
 	);
 }
 
+/** Warning for a filtered pull-request search the provider cannot run as requested. */
+export function unsupportedPullRequestSearchCriteriaWarning(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	rejection: PullRequestSearchCriteriaRejection,
+): ProviderWarning {
+	let message: string;
+	switch (rejection.reason) {
+		case 'unsupported-search':
+			message = `Filtered pull request search is not supported by '${id}'; use \`listPullRequestsPage\` for its own pull request reads.`;
+			break;
+		case 'unsupported-criteria': {
+			const supported = providersMetadata[id]?.supportedPullRequestSearch;
+			message = unsupportedNarrowingMessage(
+				id,
+				'pull request search criteria',
+				rejection.criteria.join(', '),
+				supported != null ? describePullRequestSearchCapabilities(supported) : '',
+			);
+			break;
+		}
+	}
+
+	return otherWarning(id, domain, connectionId, message);
+}
+
+function describePullRequestSearchCapabilities(capabilities: PullRequestSearchCapabilities): string {
+	return [
+		...(capabilities.relationships.length ? [`relationships:${capabilities.relationships.join('|')}`] : []),
+		...(capabilities.states.length ? [`states:${capabilities.states.join('|')}`] : []),
+		...(capabilities.text ? ['text'] : []),
+		...(capabilities.includeArchived ? ['includeArchived'] : []),
+		...(capabilities.repositoryScope ? ['repository scope'] : []),
+		...(capabilities.organizationScope ? ['organization scope'] : []),
+	].join(', ');
+}
+
 /**
  * Warning for a filtered issue search whose criteria the provider can't serve — either it has no such search at
  * all, or it can't express what was asked for, or the set contradicts itself.
@@ -343,6 +387,32 @@ export function issueSearchCapResultWarning(
 	};
 }
 
+/** Quantified omission for a pull-request search that exceeded the provider's reachable result window. */
+export function pullRequestSearchCapResultWarning(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	totalCount: number | undefined,
+): ProviderWarning | undefined {
+	const limit = providersMetadata[id]?.pullRequestSearchResultLimit;
+	if (limit == null || totalCount == null || totalCount <= limit) return undefined;
+
+	return {
+		...otherWarning(
+			id,
+			domain,
+			connectionId,
+			`Pull request search matched ${totalCount} results, but '${id}' serves at most ${limit}; narrow the search to read the rest.`,
+		),
+		omission: {
+			kind: 'provider-limit',
+			recovery: 'none',
+			limit: limit,
+			totalCount: totalCount,
+		},
+	};
+}
+
 /** Warning for a git host that doesn't expose issues on this surface (e.g. Bitbucket, deprecated in favor of Jira). */
 export function issuesUnsupportedWarning(
 	id: IntegrationIds,