@gitkraken/core-gitlens 0.5.103 → 0.5.104

package/src/plus/integrations/providerFilters.ts

@@ -10,3 +10,18 @@ export enum IssueFilter {
 	Assignee = 'assignee',
 	Mention = 'mention',
 }
+
+/**
+ * The filtered issue search's criteria model, re-exported from the git models so it can be reached from here
+ * alongside the two filter enums above.
+ *
+ * It lives in `@gitkraken/core-gitlens/git` rather than in this package because the provider implementations that translate it
+ * to a query — the GitHub API client among them — sit BELOW this package in the dependency graph and can't import
+ * from it. {@link IssueSearchRelationship} is a superset of {@link IssueFilter}: it adds the two user-independent
+ * relationships (`any-assignee`, `unassigned`) that the user-relative "my issues" filters have no way to name.
+ */
+export type {
+	IssueSearchCapabilities,
+	IssueSearchCriteria,
+	IssueSearchRelationship,
+} from '../../git/models/issue.js';

package/src/plus/integrations/providers/github.ts

@@ -1,6 +1,6 @@
 import type { Account, UnidentifiedAuthor } from '../../../git/models/author.js';
 import type { DefaultBranch } from '../../../git/models/defaultBranch.js';
-import type { Issue, IssueShape } from '../../../git/models/issue.js';
+import type { Issue, IssueSearchCriteria, IssueShape } from '../../../git/models/issue.js';
 import type { IssueOrPullRequest } from '../../../git/models/issueOrPullRequest.js';
 import type {
 	PullRequest,
@@ -25,7 +25,7 @@ import { IntegrationReadUnavailableError } from '../errors.js';
 import type { IntegrationConnectionChangeEvent } from '../integrationService.js';
 import type { SearchMyPullRequestsOptions } from '../models/gitHostIntegration.js';
 import { GitHostIntegration } from '../models/gitHostIntegration.js';
-import type { SearchMyIssuesOptions } from '../models/integration.js';
+import type { ProviderIssueSearchPage, SearchMyIssuesOptions } from '../models/integration.js';
 import type { GitHubIntegrationIds } from './github/github.utils.js';
 import { getGitHubPullRequestIdentityFromMaybeUrl } from './github/github.utils.js';
 import type {
@@ -33,6 +33,7 @@ import type {
 	ProviderHierarchyResult,
 	ProviderOrganization,
 	ProviderPullRequest,
+	ProviderRepoInput,
 	ProviderRepository,
 } from './models.js';
 import {
@@ -592,6 +593,10 @@ abstract class GitHubIntegrationBase<ID extends GitHubIntegrationIds> extends Gi
 		cancellation?: AbortSignal,
 		options?: SearchMyIssuesOptions,
 	): Promise<{ values: IssueShape[]; truncated: boolean } | undefined> {
+		// `includeAllAssignees` becomes `assignee:*`, which needs a scope to mean anything — with none it matches
+		// millions of issues across all of GitHub rather than "assigned to anyone in the user's world". ANY scope
+		// works (one repo, several, or an org), so this refuses only the genuinely unscoped read; the scoped
+		// "assigned to anyone over these repos" request is served by `searchIssuesPage`.
 		if ((repos == null || repos.length === 0) && options?.includeAllAssignees) {
 			throw new IntegrationReadUnavailableError(
 				this.name,
@@ -620,6 +625,63 @@ abstract class GitHubIntegrationBase<ID extends GitHubIntegrationIds> extends Gi
 		);
 	}
 
+	/**
+	 * The filtered issue search: one GraphQL request per page, no forced relationship to the current user, and no
+	 * route through the SDK's repo-scoped read (whose over-limit recovery walk can spend up to 128 requests).
+	 *
+	 * The criteria → qualifier translation and the ordering guarantee live in the API client
+	 * (`GitHubApi.searchIssuesPage`), which is also where user input is sanitized so it can't inject a qualifier.
+	 */
+	protected override async searchProviderIssuesPage(
+		session: ProviderAuthenticationSession,
+		options: {
+			repos?: ProviderRepoInput[];
+			org?: string;
+			criteria?: IssueSearchCriteria;
+			cursor?: string;
+			pageSize?: number;
+		},
+		cancellation?: AbortSignal,
+	): Promise<ProviderIssueSearchPage | undefined> {
+		return (await this.authenticationService.apis.github)?.searchIssuesPage(
+			this,
+			toTokenWithInfo(this.id, session),
+			{
+				// `namespace` is the owner for GitHub, which is how a `repo:` qualifier names a repository.
+				repos: options.repos?.map(r => `${r.namespace}/${r.name}`),
+				org: options.org,
+				criteria: options.criteria,
+				baseUrl: this.apiBaseUrl,
+				includeBody: true,
+				cursor: options.cursor,
+				pageSize: options.pageSize,
+			},
+			cancellation,
+		);
+	}
+
+	/**
+	 * Counts several scopes in ONE request. GitHub's `search` reports `issueCount` on a zero-node selection, so a
+	 * count preview costs no issue transfer — measured, 30 aliased counts are a single rate-limit point.
+	 */
+	protected override async countProviderIssues(
+		session: ProviderAuthenticationSession,
+		scopes: readonly { repos?: ProviderRepoInput[]; org?: string; criteria?: IssueSearchCriteria }[],
+		cancellation?: AbortSignal,
+	): Promise<(number | undefined)[] | undefined> {
+		return (await this.authenticationService.apis.github)?.countIssues(
+			this,
+			toTokenWithInfo(this.id, session),
+			scopes.map(s => ({
+				repos: s.repos?.map(r => `${r.namespace}/${r.name}`),
+				org: s.org,
+				criteria: s.criteria,
+			})),
+			{ baseUrl: this.apiBaseUrl },
+			cancellation,
+		);
+	}
+
 	protected override async searchProviderPullRequests(
 		session: ProviderAuthenticationSession,
 		searchQuery: string,

package/src/plus/integrations/providers/models.ts

@@ -43,6 +43,7 @@ import type {
 } from '@gitkraken/provider-apis';
 import entityIdentifiersModule from '@gitkraken/provider-apis/entity-identifiers';
 import providerUtilsModule from '@gitkraken/provider-apis/provider-utils';
+import { githubSearchResultLimit } from '../../git-github/api/config.js';
 import type { Account as UserAccount } from '../../../git/models/author.js';
 import type { IssueMember, IssueProject, IssueShape, IssueStateFilter } from '../../../git/models/issue.js';
 import { Issue, RepositoryAccessLevel } from '../../../git/models/issue.js';
@@ -74,9 +75,11 @@ import {
 	IssuesCloudHostIntegrationId,
 } from '../constants.js';
 import type { Integration, IntegrationType } from '../models/integration.js';
+import type { IssueSearchCapabilities } from '../providerFilters.js';
 import { IssueFilter, PullRequestFilter } from '../providerFilters.js';
 
 export { IssueFilter, PullRequestFilter } from '../providerFilters.js';
+export type { IssueSearchCapabilities, IssueSearchCriteria, IssueSearchRelationship } from '../providerFilters.js';
 import type { ProviderRepositoryShape } from '../results.js';
 
 export type { ProviderOrganization, ProviderRepositoryShape } from '../results.js';
@@ -710,11 +713,53 @@ export interface ProviderMetadata {
 	 * axes; it omits `Mention` because that REST read has no first-class mention filter.
 	 */
 	supportedAccountWideIssueFilters?: IssueFilter[];
+	/**
+	 * What the provider's FILTERED issue search (`searchIssuesPage`, and the `countIssues` probe over the same
+	 * criteria) can express server-side. A third, wider surface than either filter set above: it is not bound to
+	 * the user at all, so it takes relationships those reads have no way to name (`any-assignee`, `unassigned`),
+	 * plus free text and issue attributes.
+	 *
+	 * Absent means the provider has NO filtered issue search and the read is refused. Present, it is a promise:
+	 * every field declared here reaches the provider query, so a consumer that intersects against it never has a
+	 * read refused, and a criterion is never silently ignored.
+	 */
+	supportedIssueSearch?: IssueSearchCapabilities;
+	/**
+	 * The maximum number of results the provider's filtered issue search will serve for ONE query, however it is
+	 * paged. Matches past it are UNREACHABLE, not merely unfetched, which is why a read that hits this reports an
+	 * omission with `recovery: 'none'` and the total match count rather than offering a "load more".
+	 *
+	 * Absent means the provider declares no ceiling, in which case a truncated read falls back to generic wording
+	 * instead of quoting a limit that was never published.
+	 */
+	issueSearchResultLimit?: number;
 }
 
 export type Providers = Record<IntegrationIds, ProviderInfo>;
 export type ProvidersMetadata = Record<IntegrationIds, ProviderMetadata>;
 
+/**
+ * GitHub and GitHub Enterprise express every criterion as a search qualifier on the same GraphQL `search` field,
+ * so the two share one declaration — a GHE instance running the same search syntax has the same capability, and
+ * two copies of this table would be free to drift.
+ *
+ * Every entry is a claim the implementation must keep: `searchIssuesPage` emits a qualifier for each of these,
+ * and a test asserts that (see the `issueSearch` capability tests) so the table can't quietly outrun the code.
+ */
+const githubIssueSearchCapabilities: IssueSearchCapabilities = {
+	// `author:@me` / `assignee:@me` / `mentions:@me` / `assignee:*` / `no:assignee`, each its own aliased search.
+	relationships: ['authored', 'assigned', 'mentioned', 'any-assignee', 'unassigned'],
+	text: true,
+	labels: true,
+	milestone: true,
+	updatedAfter: true,
+	createdAfter: true,
+	// `-linked:pr`.
+	withoutLinkedPullRequest: true,
+	// `is:open` / `is:closed`, or neither for all states.
+	states: true,
+};
+
 export const providersMetadata: ProvidersMetadata = {
 	[GitCloudHostIntegrationId.GitHub]: {
 		domain: 'github.com',
@@ -742,6 +787,8 @@ export const providersMetadata: ProvidersMetadata = {
 		// The account-wide read is three independent searches (`author:@me`, `assignee:@me`, `mentions:@me`) behind
 		// one composite cursor, so any subset of them is expressible.
 		supportedAccountWideIssueFilters: [IssueFilter.Author, IssueFilter.Assignee, IssueFilter.Mention],
+		supportedIssueSearch: githubIssueSearchCapabilities,
+		issueSearchResultLimit: githubSearchResultLimit,
 		scopes: ['repo', 'read:user', 'user:email'],
 	},
 	[GitSelfManagedHostIntegrationId.CloudGitHubEnterprise]: {
@@ -770,6 +817,8 @@ export const providersMetadata: ProvidersMetadata = {
 		// The account-wide read is three independent searches (`author:@me`, `assignee:@me`, `mentions:@me`) behind
 		// one composite cursor, so any subset of them is expressible.
 		supportedAccountWideIssueFilters: [IssueFilter.Author, IssueFilter.Assignee, IssueFilter.Mention],
+		supportedIssueSearch: githubIssueSearchCapabilities,
+		issueSearchResultLimit: githubSearchResultLimit,
 		scopes: ['repo', 'read:user', 'user:email'],
 	},
 	[GitCloudHostIntegrationId.GitLab]: {

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

@@ -23,6 +23,16 @@ import { gitHostOnlySurfaceWarning, issuesUnsupportedWarning, noConnectionWarnin
  * provider positions — one per org — so its continuation is a per-org cursor BUNDLE (see `cursors.ts`) and its
  * failure attribution is per provider across those orgs. Both are the reason a page number alone can't address a
  * later page, and why {@link broadenIssues} walks prior pages itself when given only `page`.
+ *
+ * SUPERSEDED for a caller that already knows its repositories: `searchIssuesPage({ repos, criteria })` answers
+ * the same question in one request per page, with no repository drain and no route through the SDK read whose
+ * over-limit recovery walk can spend up to 128 requests. This read stays for "fan out across these orgs,
+ * whatever repos they contain", whose per-provider attribution the single-provider search doesn't produce.
+ *
+ * If you migrate a caller, note the semantics carefully: broadening means ALL VISIBLE — it passes
+ * `includeAllAssignees: true`, which resolves to no assignee constraint at all, so unassigned issues ARE
+ * included. The equivalent is an OMITTED `relationships`, not `['any-assignee']`: `assignee:*` means "has some
+ * assignee" and would silently exclude every unassigned issue, which is the opposite of broadening.
  */
 
 export interface BroadenIssuesOptions {

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

@@ -0,0 +1,285 @@
+import type { IssueSearchCriteria } from '../../../git/models/issue.js';
+import { chunk } from '../../../utils/array.js';
+import { mapBounded } from '../../../utils/promise.js';
+import type { IntegrationIds } from '../constants.js';
+import { providerFanOutConcurrency } from '../constants.js';
+import type { ProviderRepoInput, ProviderReposInput } from '../providers/models.js';
+import { providersMetadata } from '../providers/models.js';
+import type { ProviderResult, ProviderWarning } from '../results.js';
+import { appendDedupedWarning } from '../results.js';
+import {
+	isGitHostIntegration,
+	isIssuesHostIntegrationId,
+	warnOnMissingSessionForDomain,
+} from '../utils/integration.utils.js';
+import type { ProviderReadContext } from './context.js';
+import { runCaptured } from './drains.js';
+import { resolveIssueSearchCriteria, resolveIssueSearchScope } from './filters.js';
+import {
+	gitHostOnlySurfaceWarning,
+	issuesUnsupportedWarning,
+	otherWarning,
+	unsupportedIssueSearchCriteriaWarning,
+} from './warnings.js';
+
+/**
+ * How many scopes go into one upstream request.
+ *
+ * Measured against the live GitHub API, 30 aliased counts cost a single rate-limit point and ~2s, and 60 cost the
+ * same point and roughly twice as long — so the constraint isn't rate limit, it's latency and the provider's
+ * (uncontracted, so not to be leaned on) query-complexity limits. 25 keeps a chunk comfortably inside both while
+ * still collapsing a realistic filter matrix into one or two requests.
+ */
+const issueCountChunkSize = 25;
+
+/**
+ * One scope to count.
+ *
+ * `key` is caller-owned and echoed back verbatim, so a batch result needs no positional matching by the consumer.
+ * It never reaches the provider query — the aliases in the upstream document are generated — so it can be any
+ * string the caller finds meaningful.
+ */
+export interface IssueCountScope {
+	key: string;
+	/** Repositories to count over. Combines with `org`, exactly as in `searchIssuesPage`. */
+	repos?: ProviderReposInput;
+	org?: string;
+	/** Same criteria model as `searchIssuesPage`, validated against the same capability table. */
+	criteria?: IssueSearchCriteria;
+}
+
+/** The count for one {@link IssueCountScope}, echoed back under the caller's own `key`. */
+export interface IssueCountResult {
+	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. Render the difference: an unreported count means "unknown", and showing it as
+	 * 0 would tell the user this filter matches nothing.
+	 */
+	count?: number;
+	/**
+	 * True when `count` exceeds the provider's own 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.
+ *
+ * A distinct method rather than a `countOnly` flag on `searchIssuesPage`, because transferring ZERO issues is the
+ * entire value: a flag would return a paged result whose `items`, `cursor` and `hasMore` are all meaningless, and
+ * every consumer would have to know which fields to ignore. A separate method has a return type that only
+ * describes counts.
+ *
+ * Scopes are batched into as few upstream requests as possible ({@link issueCountChunkSize} each). A chunk that
+ * fails warns and drops only its own scopes, leaving the successful chunks' counts intact — so a partial answer is
+ * still useful — with `fetchFailed` set. A scope refused for its own reasons (unscoped, inexpressible criteria) is
+ * likewise isolated: its siblings are still counted.
+ *
+ * Cheap is not free: each chunk is a network request, so a caller driving this from UI state is expected to
+ * debounce and cache.
+ */
+export async function countIssues(
+	ctx: ProviderReadContext,
+	options: {
+		providerId: IntegrationIds;
+		scopes: readonly IssueCountScope[];
+		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<IssueCountResult>> {
+	const refused = (warning: ProviderWarning): ProviderResult<IssueCountResult> => ({
+		items: [],
+		warnings: [warning],
+		fetchFailed: true,
+	});
+
+	if (isIssuesHostIntegrationId(options.providerId)) {
+		return refused(gitHostOnlySurfaceWarning(options.providerId, undefined, options.connectionId, 'Issue 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 issue 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, 'Issue counts'));
+	}
+
+	const domain = ctx.domainForRead(integration, options.providerId, options.connectionId, options.domain);
+	const warnOnMissingSession = warnOnMissingSessionForDomain(options.providerId, options.domain);
+
+	if (!integration.supportsIssues) {
+		return refused(issuesUnsupportedWarning(options.providerId, domain, options.connectionId));
+	}
+
+	const providerLimit = providersMetadata[options.providerId]?.issueSearchResultLimit;
+	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: IssueCountScope[] = [];
+	for (const scope of options.scopes) {
+		const warning = rejectScope(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 — deduping them would only pay
+			// the O(n²) key comparison to prove it.
+			warnings.push(warning);
+			fetchFailed = true;
+			continue;
+		}
+
+		countable.push(scope);
+	}
+
+	// Chunks are independent requests over their own slice of scopes — nothing in one reads what another produced,
+	// and `runCaptured` never throws — so they run concurrently, bounded like every other fan-out on the facade.
+	// Sequentially they would spend exactly the resource this probe is tuned to conserve: latency, ~2s per chunk.
+	// `mapBounded` returns in input order, so `items` and `warnings` stay in scope order.
+	const batches = await mapBounded(chunk(countable, issueCountChunkSize), providerFanOutConcurrency, batch =>
+		runCaptured(
+			options.providerId,
+			domain,
+			options.connectionId,
+			() =>
+				integration.countIssuesResult(
+					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: IssueCountResult[] = [];
+	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 with no count support returns `undefined` with no error, which lands as an empty `items` and no
+	// warning. Say so explicitly rather than letting it read as "every scope matched nothing".
+	if (items.length === 0 && warnings.length === 0) {
+		return refused(
+			unsupportedIssueSearchCriteriaWarning(options.providerId, domain, options.connectionId, {
+				reason: 'unsupported-search',
+			}),
+		);
+	}
+
+	return { items: items, warnings: warnings, fetchFailed: fetchFailed || undefined };
+}
+
+/** The first key that appears twice, or `undefined` when every key is unique. */
+function findDuplicateKey(scopes: readonly IssueCountScope[]): string | undefined {
+	const seen = new Set<string>();
+	for (const scope of scopes) {
+		if (seen.has(scope.key)) return scope.key;
+
+		seen.add(scope.key);
+	}
+	return undefined;
+}
+
+/**
+ * Why one scope can't be counted, as the warning to report — or `undefined` when it can.
+ *
+ * The scope and criteria rules come from {@link resolveIssueSearchScope} / {@link resolveIssueSearchCriteria},
+ * the same validators `searchIssuesPage` uses, so a count always previews the constraints the read would apply.
+ * That is not cosmetic: a count computed under different constraints is a WRONG number rather than a missing
+ * one, which is worse. Only the wording is local, because these name the offending scope's key.
+ */
+function rejectScope(
+	providerId: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	scope: IssueCountScope,
+): ProviderWarning | undefined {
+	const scoping = resolveIssueSearchScope(scope.repos, scope.org, scope.criteria);
+	switch (scoping.rejection) {
+		case 'repo-ids':
+			return otherWarning(
+				providerId,
+				domain,
+				connectionId,
+				`Issue count scope '${scope.key}' cannot be scoped by repository id; pass repository descriptors (namespace + name) instead.`,
+			);
+		case 'unscoped':
+			return otherWarning(
+				providerId,
+				domain,
+				connectionId,
+				`Issue count scope '${scope.key}' is unscoped; pass \`repos\`, \`org\`, or a relationship to the current user. \`any-assignee\` and \`unassigned\` are not scopes.`,
+			);
+	}
+
+	const resolved = resolveIssueSearchCriteria(providerId, scope.criteria);
+	if (resolved.rejection != null) {
+		return unsupportedIssueSearchCriteriaWarning(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 them would double-count anything matching two, and taking the max would
+	// under-report. Rather than answer with a wrong number, ask the caller to count each relationship as its own
+	// scope, where the keys make the OR explicit.
+	if ((scope.criteria?.relationships?.length ?? 0) > 1) {
+		return otherWarning(
+			providerId,
+			domain,
+			connectionId,
+			`Issue 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;
+}