@gitkraken/core-gitlens 0.5.103 → 0.5.104

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

@@ -1,7 +1,8 @@
 import type { IntegrationIds } from '../constants.js';
-import type { IssueFilter, PullRequestFilter } from '../providerFilters.js';
+import type { IssueFilter, IssueSearchCapabilities, PullRequestFilter } from '../providerFilters.js';
 import { providersMetadata } from '../providers/models.js';
 import type { ProviderWarning } from '../results.js';
+import type { IssueSearchCriteriaRejection } from './filters.js';
 
 /**
  * The warnings the provider facade raises on its OWN terms, as opposed to the ones derived from a caught
@@ -152,7 +153,8 @@ type TruncatedReadKind =
 	| 'Repository'
 	| 'Organization'
 	| 'Project'
-	| 'Account-wide issue search';
+	| 'Account-wide issue search'
+	| 'Issue search';
 
 /** {@link incompleteReadWarning} for a paged or drained read, phrased per surface. */
 export function truncationWarning(
@@ -187,6 +189,17 @@ function truncationMessage(id: IntegrationIds, readKind: TruncatedReadKind, caus
 	// is not the same case — that union is the SDK's, and can widen under a dependency bump.)
 }
 
+/**
+ * The one sentence every "you asked for a narrowing this provider can't express" refusal uses.
+ *
+ * Shared because the three callers below differ only in a noun: the wording is consumer-visible, and three
+ * hand-written copies drift three ways — including the `(supported: …)` clause, which exists to avoid emitting an
+ * empty parenthetical and has to be the same guard in all of them.
+ */
+function unsupportedNarrowingMessage(id: IntegrationIds, noun: string, requested: string, supported: string): string {
+	return `The requested ${noun} (${requested}) are not supported by '${id}'${supported.length > 0 ? ` (supported: ${supported})` : ''}; skipped to avoid returning a wider result than requested.`;
+}
+
 /** Warning for an account-wide issue read whose requested filters the provider can't express server-side. */
 export function unsupportedAccountWideIssueFiltersWarning(
 	id: IntegrationIds,
@@ -199,7 +212,7 @@ export function unsupportedAccountWideIssueFiltersWarning(
 		id,
 		domain,
 		connectionId,
-		`The requested account-wide issue filters (${filters.join(', ')}) are not supported by '${id}'${supported.length ? ` (supported: ${supported.join(', ')})` : ''}; skipped to avoid returning a wider result than requested.`,
+		unsupportedNarrowingMessage(id, 'account-wide issue filters', filters.join(', '), supported.join(', ')),
 	);
 }
 
@@ -215,7 +228,7 @@ export function unsupportedAccountWidePullRequestFiltersWarning(
 		id,
 		domain,
 		connectionId,
-		`The requested account-wide pull request filters (${filters.join(', ')}) are not supported by '${id}'${supported.length ? ` (supported: ${supported.join(', ')})` : ''}; skipped to avoid returning a wider result than requested.`,
+		unsupportedNarrowingMessage(id, 'account-wide pull request filters', filters.join(', '), supported.join(', ')),
 	);
 }
 
@@ -233,6 +246,103 @@ export function unsupportedFiltersWarning(
 	);
 }
 
+/**
+ * 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.
+ *
+ * One builder for all three because they are one decision from the caller's side ("this search can't be run as
+ * asked") and the remedy differs only in what the message says. The rejection shape carries which case it is, so
+ * the wording can't drift from the check that produced it (see {@link resolveIssueSearchCriteria}).
+ */
+export function unsupportedIssueSearchCriteriaWarning(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	rejection: IssueSearchCriteriaRejection,
+): ProviderWarning {
+	let message: string;
+	switch (rejection.reason) {
+		case 'unsupported-search':
+			message = `Filtered issue search is not supported by '${id}'; use \`listIssuesPage\` for its own issue reads.`;
+			break;
+		case 'unsupported-criteria': {
+			const supported = providersMetadata[id]?.supportedIssueSearch;
+			message = unsupportedNarrowingMessage(
+				id,
+				'issue search criteria',
+				rejection.criteria.join(', '),
+				supported != null ? describeIssueSearchCapabilities(supported) : '',
+			);
+			break;
+		}
+		case 'contradictory-relationships':
+			message = `The relationships \`any-assignee\` and \`unassigned\` are contradictory — they partition the scope between them, so no issue satisfies both; pass only one.`;
+			break;
+	}
+	// No `default`: the union is declared alongside the validator, so `noImplicitReturns` fails the build here if
+	// a rejection reason is added without its own wording.
+
+	return otherWarning(id, domain, connectionId, message);
+}
+
+/** The criteria a provider CAN express, for the "supported: …" half of a refusal message. */
+function describeIssueSearchCapabilities(capabilities: IssueSearchCapabilities): string {
+	const flags: [name: string, supported: boolean][] = [
+		['text', capabilities.text],
+		['labels', capabilities.labels],
+		['milestone', capabilities.milestone],
+		['updatedAfter', capabilities.updatedAfter],
+		['createdAfter', capabilities.createdAfter],
+		['withoutLinkedPullRequest', capabilities.withoutLinkedPullRequest],
+		['state', capabilities.states],
+	];
+	return [
+		...capabilities.relationships.map(r => `relationships:${r}`),
+		...flags.filter(([, supported]) => supported).map(([name]) => name),
+	].join(', ');
+}
+
+/**
+ * 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.
+ *
+ * Distinct from {@link truncationWarning} because this is the one incompleteness this read can quantify —
+ * `totalCount` is how many matched, `limit` how many are reachable — which is what lets a consumer say "19.240
+ * matched, showing the 1.000 most recently updated" instead of a bare "results may be incomplete". `recovery:
+ * '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.
+ *
+ * Returns `undefined` when the provider declares no ceiling, so the caller falls back to the generic wording
+ * rather than reporting a limit it invented.
+ */
+export function issueSearchCapResultWarning(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	totalCount: number | undefined,
+): 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;
+
+	return {
+		...otherWarning(
+			id,
+			domain,
+			connectionId,
+			`Issue search matched ${totalCount} results, but '${id}' serves at most ${limit}; narrow the search to read the rest.`,
+		),
+		omission: {
+			kind: 'provider-limit',
+			// The items past the ceiling can't be fetched by anything, so never offer a "load more".
+			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,