@gitkraken/core-gitlens 0.5.102 → 0.5.104

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

@@ -1,5 +1,12 @@
 import type { IntegrationIds } from '../constants.js';
-import type { IssueFilter, PullRequestFilter } from '../providerFilters.js';
+import type {
+	IssueFilter,
+	IssueSearchCapabilities,
+	IssueSearchCriteria,
+	IssueSearchRelationship,
+	PullRequestFilter,
+} from '../providerFilters.js';
+import type { ProviderRepoInput, ProviderReposInput } from '../providers/models.js';
 import { providersMetadata } from '../providers/models.js';
 
 /**
@@ -79,6 +86,139 @@ export function resolveAccountWideIssueFilters(
 	return { filters: filters, unsupported: false };
 }
 
+/** Why {@link resolveIssueSearchCriteria} refused a criteria set, so the caller can word the refusal exactly. */
+export type IssueSearchCriteriaRejection =
+	/** The provider has no filtered issue search at all. */
+	| { reason: 'unsupported-search' }
+	/** The provider has one, but can't express these criteria server-side. */
+	| { reason: 'unsupported-criteria'; criteria: string[] }
+	/** `any-assignee` and `unassigned` partition the scope between them; asking for both asks for nothing. */
+	| { reason: 'contradictory-relationships' };
+
+/**
+ * Validates a filtered issue search's criteria against {@link ProviderMetadata.supportedIssueSearch}.
+ *
+ * All-or-nothing like its three siblings above, and for the same reason: a criterion dropped because the
+ * provider can't express it would serve a WIDER result than was asked for, and narrowing the returned page
+ * afterward would leave `items` describing a different result set than the `hasMore`/`cursor` the provider
+ * produced with it. So an inexpressible set is refused whole and the caller surfaces a warning.
+ *
+ * Unlike the sibling validators this also rejects a set that is internally contradictory, because this criteria
+ * model is the only one with two members that partition the scope between them (`any-assignee` ∪ `unassigned` =
+ * everything, ∩ = nothing). Silently keeping one would answer a question the caller didn't ask.
+ *
+ * `undefined` (or an empty relationship list plus no other criterion) is a valid UNNARROWED search of the given
+ * scope, not an error — the caller's `repos`/`org` is what bounds it.
+ */
+export function resolveIssueSearchCriteria(
+	id: IntegrationIds,
+	criteria: IssueSearchCriteria | undefined,
+): { rejection?: IssueSearchCriteriaRejection } {
+	const supported = providersMetadata[id]?.supportedIssueSearch;
+	if (supported == null) return { rejection: { reason: 'unsupported-search' } };
+	if (criteria == null) return {};
+
+	const relationships = criteria.relationships;
+	if (relationships?.includes('any-assignee') && relationships.includes('unassigned')) {
+		return { rejection: { reason: 'contradictory-relationships' } };
+	}
+
+	const unsupported: string[] = [];
+	for (const relationship of relationships ?? []) {
+		if (!supported.relationships.includes(relationship)) {
+			unsupported.push(`relationships:${relationship}`);
+		}
+	}
+	// Only a criterion the caller actually SET can be unsupported. `false`/empty means "don't narrow on this",
+	// which every provider can honor by doing nothing, so it must not be validated as a request.
+	if (criteria.text != null && criteria.text.trim().length > 0 && !supported.text) {
+		unsupported.push('text');
+	}
+	if (criteria.labels?.length && !supported.labels) {
+		unsupported.push('labels');
+	}
+	if (criteria.milestone != null && !supported.milestone) {
+		unsupported.push('milestone');
+	}
+	if (criteria.updatedAfter != null && !supported.updatedAfter) {
+		unsupported.push('updatedAfter');
+	}
+	if (criteria.createdAfter != null && !supported.createdAfter) {
+		unsupported.push('createdAfter');
+	}
+	if (criteria.withoutLinkedPullRequest === true && !supported.withoutLinkedPullRequest) {
+		unsupported.push('withoutLinkedPullRequest');
+	}
+	// `'open'` is every provider's own default, so asking for it needs no state capability.
+	if (criteria.state != null && criteria.state !== 'open' && !supported.states) {
+		unsupported.push('state');
+	}
+
+	if (unsupported.length > 0) return { rejection: { reason: 'unsupported-criteria', criteria: unsupported } };
+
+	return {};
+}
+
+/**
+ * The relationships that bound a filtered issue search to the CURRENT USER, and so can stand in for a
+ * repository/org scope.
+ *
+ * Derived from the union rather than spelled out per call site, because the distinction it encodes is the whole
+ * reason the scope rule exists: `any-assignee` and `unassigned` are deliberately absent — they describe the
+ * ISSUE, not the caller, so neither reduces the search to anyone's own world (measured: unscoped `no:assignee`
+ * matches ~45 million issues on GitHub).
+ */
+const userScopingIssueSearchRelationships: readonly IssueSearchRelationship[] = ['authored', 'assigned', 'mentioned'];
+
+/** What a provider with NO filtered issue search reports: nothing expressible, spelled out rather than absent. */
+const unsupportedIssueSearchCapabilities: IssueSearchCapabilities = {
+	relationships: [],
+	text: false,
+	labels: false,
+	milestone: false,
+	updatedAfter: false,
+	createdAfter: false,
+	withoutLinkedPullRequest: false,
+	states: 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. */
+	| 'unscoped'
+	/** Repositories given as ids. A search names repositories by PATH, so ids can't express a scope. */
+	| 'repo-ids';
+
+/**
+ * Validates that a filtered issue search is scoped at all, and narrows `repos` to the descriptor form the
+ * provider query needs.
+ *
+ * Shared by `searchIssuesPage` and `countIssues` because a count computed under different constraints than the
+ * read it previews is a WRONG number rather than a missing one. The rejection is returned as a reason code, not a
+ * warning: the two callers word it differently (whole-read vs naming the offending scope's key), and wording is
+ * the warning layer's business.
+ *
+ * The two rejections are mutually exclusive — `repo-ids` requires repositories and `unscoped` requires none — so
+ * the order they're checked in cannot change the outcome.
+ */
+export function resolveIssueSearchScope(
+	repos: ProviderReposInput | undefined,
+	org: string | undefined,
+	criteria: IssueSearchCriteria | undefined,
+): { rejection?: IssueSearchScopeRejection; repos?: ProviderRepoInput[] } {
+	if (repos?.length) {
+		// `ProviderReposInput` is a union of descriptor and id arrays; only the descriptor form is usable here.
+		if (repos.some(r => typeof r === 'string' || typeof r === 'number')) return { rejection: 'repo-ids' };
+
+		return { repos: repos as ProviderRepoInput[] };
+	}
+
+	if (org != null && org.length > 0) return {};
+	if (criteria?.relationships?.some(r => userScopingIssueSearchRelationships.includes(r)) === true) return {};
+
+	return { rejection: 'unscoped' };
+}
+
 /**
  * The filters `listPullRequestsPage`/`listIssuesPage` (and the sweeps) accept for a provider, so a caller can
  * narrow to what the provider can express BEFORE issuing the read.
@@ -103,6 +243,11 @@ export function resolveAccountWideIssueFilters(
  * {@link IntegrationService.listIssueTrackerIssuesPage} validates against, and leaves `issuesAccountWide`
  * empty. Reading a tracker's capability off `issuesAccountWide` therefore under-reports it.
  *
+ * `issueSearch` is a third, wider surface: the FILTERED issue search (`searchIssuesPage`, and the `countIssues`
+ * probe over the same criteria), which is not bound to the user at all. It is a record of per-criterion flags
+ * 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.
+ *
  * 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
@@ -113,12 +258,28 @@ export function getSupportedFilters(providerId: IntegrationIds): {
 	pullRequestsAccountWide: PullRequestFilter[];
 	issues: IssueFilter[];
 	issuesAccountWide: IssueFilter[];
+	issueSearch: IssueSearchCapabilities;
 } {
 	const metadata = providersMetadata[providerId];
+	const issueSearch = metadata?.supportedIssueSearch;
 	return {
 		pullRequests: [...(metadata?.supportedPullRequestFilters ?? [])],
 		pullRequestsAccountWide: [...(metadata?.supportedAccountWidePullRequestFilters ?? [])],
 		issues: [...(metadata?.supportedIssueFilters ?? [])],
 		issuesAccountWide: [...(metadata?.supportedAccountWideIssueFilters ?? [])],
+		// Always an object, never `undefined`: a provider WITHOUT a filtered issue search reports one whose
+		// `relationships` is empty and whose flags are all false, so a consumer reads capabilities the same way
+		// for every provider (and an empty `relationships` is the signal to hide the surface itself).
+		//
+		// Spread over the all-false baseline rather than defaulting each flag: a criterion added to
+		// `IssueSearchCapabilities` then can't be forgotten here and silently reported as `undefined` (which a
+		// consumer's `if (caps.x)` would read as unsupported — right answer, wrong reason, and untyped).
+		// `supportedIssueSearch` is typed as the complete shape, so no member can arrive as an explicit undefined.
+		issueSearch: {
+			...unsupportedIssueSearchCapabilities,
+			...issueSearch,
+			// Copied, so mutating the result can't corrupt the metadata table.
+			relationships: [...(issueSearch?.relationships ?? [])],
+		},
 	};
 }

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

@@ -10,6 +10,7 @@ import {
 } from '../constants.js';
 import type { ListOrgsOptions, ListProjectsOptions } from '../manager.js';
 import { isIssuesIntegration } from '../models/issuesIntegration.js';
+import type { ProviderHierarchyResult } from '../providers/models.js';
 import { toProviderRepositoryShape } from '../providers/models.js';
 import type {
 	ProviderOrganization,
@@ -35,7 +36,46 @@ import {
 	withProviderContext,
 } from './hierarchy.utils.js';
 import { pageToCursor, refusedPage, resolveContinuation, resolveCurrentPage, toProviderPageInfo } from './paging.js';
-import { gitHostOnlySurfaceWarning, otherWarning } from './warnings.js';
+import { gitHostOnlySurfaceWarning, otherWarning, truncationWarning } from './warnings.js';
+
+/**
+ * Folds a flat hierarchy result's incompleteness into `warnings`, returning whether it leaves the read
+ * non-authoritative. The single funnel for both hierarchy reads, so neither can drift from the other on any of
+ * the four decisions it makes:
+ *
+ * - The metadata is assessed FIRST, so the truncation warning can tell whether it already explained this gap.
+ *   Ordered deliberately: emitting first meant an expired credential produced BOTH a typed `auth` warning and
+ *   an unclassifiable one for the same cause, and a consumer routing on classification showed the second as
+ *   "this provider failed to load", with a remedy that doesn't exist, next to the reconnect prompt that was the
+ *   actual fix.
+ * - The read states the truncation itself only when the metadata reported nothing — the rule
+ *   `assessCollectionMetadata` applies to its own generic fallback. Whatever the metadata reported already names
+ *   this provider and says something stronger, so restating it costs a false verdict and adds no information.
+ * - `'exhausted'`, never `'page-budget'`: `truncated` is one boolean here, so a drain that stopped at its page
+ *   budget is indistinguishable from one whose cursor stalled, and `IncompleteReadCause` makes `'exhausted'`
+ *   the default whenever a raisable budget is not demonstrably the cause.
+ * - A truncation counts as non-authoritative even though the omission above asserts the read succeeded. Unlike
+ *   paged repository reads, a flattened hierarchy result has no page object on which to carry incompleteness,
+ *   so `fetchFailed` is the only signal a consumer has that the list is short.
+ */
+function mergeHierarchyIncompleteness(
+	warnings: ProviderWarning[],
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	result: Pick<ProviderHierarchyResult<unknown>, 'truncated' | 'metadata'>,
+	readKind: 'Organization' | 'Project',
+): boolean {
+	const assessment = mergeAssessmentInto(warnings, id, domain, connectionId, result.metadata);
+	if (!result.truncated) return assessment.fetchFailed || assessment.truncated;
+
+	if (!assessment.reported) {
+		// Deduped like every other `truncationWarning` emission (see `drains.ts`), not plain-pushed: no caller can
+		// collide with it today, but nothing about this funnel guarantees a third read won't.
+		appendDedupedWarning(warnings, truncationWarning(id, domain, connectionId, readKind, 'exhausted'));
+	}
+	return true;
+}
 
 export async function listOrgs(
 	ctx: ProviderReadContext,
@@ -103,22 +143,8 @@ export async function listOrgs(
 			);
 			if (value != null) {
 				items.push(...value.values.map(org => withProviderContext(id, org)));
-				if (value.truncated) {
-					warnings.push(
-						otherWarning(
-							id,
-							domain,
-							connectionId,
-							'Organization listing was truncated before the upstream results were exhausted.',
-						),
-					);
-					// `ProviderResult` has no page object on which to carry truncation. Mark the flat
-					// hierarchy result incomplete so consumers don't treat omitted orgs as authoritative.
-					fetchFailed = true;
-				}
 
-				const assessment = mergeAssessmentInto(warnings, id, domain, connectionId, value.metadata);
-				if (assessment.fetchFailed || assessment.truncated) {
+				if (mergeHierarchyIncompleteness(warnings, id, domain, connectionId, value, 'Organization')) {
 					fetchFailed = true;
 				}
 			}
@@ -200,22 +226,7 @@ export async function listProjects(
 			if (projects != null) {
 				items.push(...projects.values.map(project => withProviderContext(id, project)));
 
-				if (projects.truncated) {
-					warnings.push(
-						otherWarning(
-							id,
-							domain,
-							connectionId,
-							'Project listing was truncated before the upstream results were exhausted.',
-						),
-					);
-					// Unlike paged repository reads, this flattened hierarchy result has no continuation
-					// or page metadata. `fetchFailed` is its structural non-authoritative signal.
-					fetchFailed = true;
-				}
-
-				const assessment = mergeAssessmentInto(warnings, id, domain, connectionId, projects.metadata);
-				if (assessment.fetchFailed || assessment.truncated) {
+				if (mergeHierarchyIncompleteness(warnings, id, domain, connectionId, projects, 'Project')) {
 					fetchFailed = true;
 				}
 			}

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

@@ -6,7 +6,7 @@ import type { IssueFilter, ProviderReposInput } from '../providers/models.js';
 import { PagingMode, providersMetadata } from '../providers/models.js';
 import { mergeCollectionMetadata } from '../providers/utils/providerPaging.js';
 import type { ProviderPagedResult, ProviderWarning } from '../results.js';
-import { appendDedupedWarning, reconcileOmissionsWithFailure } from '../results.js';
+import { reconcileOmissionsWithFailure } from '../results.js';
 import {
 	isGitHostIntegration,
 	isIssuesHostIntegrationId,
@@ -16,6 +16,7 @@ import type { ProviderReadContext } from './context.js';
 import { runCaptured } from './drains.js';
 import { resolveAccountWideIssueFilters } from './filters.js';
 import {
+	drainFlatPagesToRequestedPage,
 	drainToRequestedPage,
 	isPageNumberAdvanceable,
 	pageToCursor,
@@ -121,6 +122,11 @@ export async function listIssuesPage(
 			);
 		}
 
+		// GitHub expresses "any assignee" as `assignee:*`, which is meaningless without a scope: unscoped it
+		// matches millions of issues across all of GitHub instead of the user's own world. ANY scope makes it
+		// meaningful (one repository, several, or an org) — it is specifically THIS branch, the account-wide read,
+		// that has none to offer. Scope the read to repositories (or use `searchIssuesPage`, whose criteria model
+		// takes `any-assignee` alongside a `repos`/`org` scope) rather than reading unscoped.
 		if (
 			options.includeAllAssignees === true &&
 			(options.providerId === GitCloudHostIntegrationId.GitHub ||
@@ -185,51 +191,22 @@ export async function listIssuesPage(
 				{ warnOnMissingSession: warnOnMissingSession },
 			);
 		const first = await readAccountWidePage(options.cursor);
-		let value = first.value;
 		const warnings = first.warning != null ? [first.warning] : [];
-		let allMetadata = value?.metadata;
-		let pageFetchFailed = first.warning != null && value == null;
-		let currentPage = value?.page ?? 1;
-		let currentTruncated = value?.truncated ?? false;
-		let requestedPageMissing = false;
-		if (options.cursor == null && page > 1 && value != null) {
-			// Guard against the empty-cursor sentinel: a provider that claims another page without handing
-			// back a usable cursor would otherwise be re-read with `'{}'` and answer with page 1 again.
-			for (
-				let nextCursor = usableCursor(value.cursor);
-				currentPage < page && value.hasMore && nextCursor != null;
-				nextCursor = usableCursor(value.cursor)
-			) {
-				const next = await readAccountWidePage(nextCursor);
-				if (next.warning != null) {
-					appendDedupedWarning(warnings, next.warning);
-				}
-				if (next.value == null) {
-					pageFetchFailed = pageFetchFailed || next.warning != null;
-					value = undefined;
-					requestedPageMissing = true;
-					break;
-				}
-
-				value = next.value;
-				allMetadata = mergeCollectionMetadata(allMetadata, value.metadata);
-				currentTruncated = currentTruncated || value.truncated;
-				currentPage = value.page ?? currentPage + 1;
-				// A provider that hands back the same cursor isn't advancing; stop rather than loop forever.
-				if (usableCursor(value.cursor) === nextCursor) {
-					currentTruncated = true;
-					break;
-				}
-			}
-
-			// A numbered page beyond the provider's terminal cursor is genuinely empty. Never return or
-			// relabel the last available page as the requested one.
-			if (currentPage < page) {
-				requestedPageMissing = true;
-			}
-		} else if (options.cursor == null && page > 1) {
-			requestedPageMissing = true;
-		}
+		// Merged across the walked pages, so a per-scope failure reported on an earlier page isn't lost by
+		// paging past it — the one thing this read accumulates that the filtered search doesn't.
+		let allMetadata = first.value?.metadata;
+		const drained = await drainFlatPagesToRequestedPage(first, {
+			requestedPage: page,
+			suppliedCursor: options.cursor,
+			warnings: warnings,
+			readPage: readAccountWidePage,
+			fold: p => {
+				allMetadata = mergeCollectionMetadata(allMetadata, p.metadata);
+			},
+		});
+		const { value, currentPage, requestedPageMissing } = drained;
+		const currentTruncated = drained.truncated;
+		const pageFetchFailed = drained.fetchFailed;
 
 		// GitHub, GitLab, and Azure implement an account-wide issue search; a provider that doesn't (Bitbucket
 		// exposes no issues at all, and `supportsIssues` already short-circuits it above) returns `undefined`

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

@@ -180,6 +180,108 @@ export function resolveCurrentPage(options: {
 	return options.pageAdvanceable ? options.requestedPage : 1;
 }
 
+/**
+ * One page of a FLAT cursor-paged provider read — the shape both issue reads' providers return directly.
+ *
+ * `hasMore` is optional because one of the two providers leaves it off on a terminal page; absent reads as "no
+ * more", which is what a provider that reported no continuation means.
+ */
+export interface FlatPage {
+	cursor?: string;
+	hasMore?: boolean;
+	page?: number;
+	truncated: boolean;
+}
+
+/** What {@link drainFlatPagesToRequestedPage} established by walking. */
+export interface FlatDrainResult<T extends FlatPage> {
+	/** The requested page, or `undefined` when a page failed mid-walk (which also sets `fetchFailed`). */
+	value: T | undefined;
+	/** The position actually reached — 1 when nothing advanced. */
+	currentPage: number;
+	truncated: boolean;
+	/** True when the requested page is past the provider's last one, so it is genuinely EMPTY. */
+	requestedPageMissing: boolean;
+	fetchFailed: boolean;
+}
+
+/**
+ * Walks a FLAT cursor-paged read forward to a requested page number, for a provider whose pages are
+ * `{cursor, hasMore, page, truncated}` rather than the SDK's `PagedResult` wrapper.
+ *
+ * The sibling of {@link drainToRequestedPage}, not a replacement for it: that one normalizes SDK `paging` through
+ * {@link toProviderPageInfo}, which retains only cursors whose JSON declares `type`/`cursors` — and the composite
+ * cursor of a GitHub aliased search declares neither, so it would be dropped and the walk would never advance.
+ * Two shapes genuinely need two entry points; what they must NOT have is two copies of the rules below, which is
+ * what this exists to prevent (see this module's own note on drift).
+ *
+ * The rules, all of them subtle enough to be worth stating once:
+ * - The empty-cursor sentinel is filtered, so a provider claiming another page without handing back a usable
+ *   continuation is not re-read with `'{}'` (which it would answer with page 1 again).
+ * - A provider that returns the SAME cursor isn't advancing: stop, and report the read as truncated rather than
+ *   looping forever or publishing a short page as complete.
+ * - A page requested past the provider's terminal cursor is that EMPTY page N — never the last available page
+ *   relabeled, per {@link ProviderPageInfo.currentPage}.
+ * - A page that fails mid-walk latches `fetchFailed` and leaves no value, so the caller can tell "the read broke"
+ *   from "the page was genuinely empty".
+ *
+ * `fold` is the one thing the callers differ on — one merges SDK collection metadata across the walked pages, the
+ * other keeps the largest reported match count — so it is a callback rather than a branch.
+ */
+export async function drainFlatPagesToRequestedPage<T extends FlatPage>(
+	first: { value?: T; warning?: ProviderWarning },
+	options: {
+		requestedPage: number;
+		suppliedCursor: string | undefined;
+		warnings: ProviderWarning[];
+		readPage: (cursor: string) => Promise<{ value?: T; warning?: ProviderWarning }>;
+		fold?: (page: T) => void;
+	},
+): Promise<FlatDrainResult<T>> {
+	let value = first.value;
+	let fetchFailed = first.warning != null && value == null;
+	let currentPage = value?.page ?? 1;
+	let truncated = value?.truncated ?? false;
+
+	const walkable = options.suppliedCursor == null && options.requestedPage > 1;
+	if (walkable && value != null) {
+		for (
+			let nextCursor = usableCursor(value.cursor);
+			currentPage < options.requestedPage && value.hasMore === true && nextCursor != null;
+			nextCursor = usableCursor(value.cursor)
+		) {
+			const next = await options.readPage(nextCursor);
+			if (next.warning != null) {
+				appendDedupedWarning(options.warnings, next.warning);
+			}
+			if (next.value == null) {
+				fetchFailed = next.warning != null;
+				value = undefined;
+				break;
+			}
+
+			value = next.value;
+			truncated = truncated || value.truncated;
+			options.fold?.(value);
+			currentPage = value.page ?? currentPage + 1;
+			if (usableCursor(value.cursor) === nextCursor) {
+				truncated = true;
+				break;
+			}
+		}
+	}
+
+	return {
+		value: value,
+		currentPage: currentPage,
+		truncated: truncated,
+		// Every case reduces to "a page was asked for by number and the walk fell short", including the one where
+		// no walk ran at all because the first page was already terminal.
+		requestedPageMissing: walkable && currentPage < options.requestedPage,
+		fetchFailed: fetchFailed,
+	};
+}
+
 /** The mutable state {@link drainToRequestedPage} carries across the pages it walks. */
 export interface DrainState<T> {
 	items: T[];