@gitkraken/core-gitlens 0.5.115 → 0.6.0

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

@@ -25,6 +25,7 @@ import {
 	otherWarning,
 	truncationWarning,
 	unsupportedIssueSearchCriteriaWarning,
+	unusableSearchScopeMessage,
 } from './warnings.js';
 
 /**
@@ -69,11 +70,7 @@ export async function searchIssuesPage(
 		criteria?: IssueSearchCriteria;
 		page?: number;
 		cursor?: string;
-		/**
-		 * Page size PER RELATIONSHIP: each one is its own provider query, so a page of an N-relationship search
-		 * returns up to `N × itemsPerPage` items before the url dedupe, and fewer where they overlap.
-		 * `page.itemsPerPage` reports what actually came back.
-		 */
+		/** Per relationship, not per page; see {@link IntegrationManager.searchIssuesPage}. */
 		itemsPerPage?: number;
 		forceSync?: boolean;
 		connectionId?: string;
@@ -117,8 +114,18 @@ export async function searchIssuesPage(
 		return refused(issuesUnsupportedWarning(options.providerId, domain, options.connectionId));
 	}
 
+	const resolved = resolveIssueSearchCriteria(options.providerId, options.criteria);
+	if (resolved.rejection != null) {
+		return refused(
+			unsupportedIssueSearchCriteriaWarning(options.providerId, domain, options.connectionId, resolved.rejection),
+		);
+	}
+
+	// AFTER the criteria check, which is what reports a provider with no filtered issue search at all: that is
+	// the more fundamental refusal, and answering "your scope name is malformed" to a caller whose provider has
+	// no such search names the wrong defect. Matches the pull-request twin, which probes existence first.
 	const scope = resolveIssueSearchScope(options.repos, options.org, options.criteria);
-	switch (scope.rejection) {
+	switch (scope.rejection?.reason) {
 		case 'unscoped':
 			return refused(
 				otherWarning(
@@ -140,13 +147,16 @@ export async function searchIssuesPage(
 					'A filtered issue search cannot be scoped by repository id; pass repository descriptors (namespace + name) instead.',
 				),
 			);
-	}
-
-	const resolved = resolveIssueSearchCriteria(options.providerId, options.criteria);
-	if (resolved.rejection != null) {
-		return refused(
-			unsupportedIssueSearchCriteriaWarning(options.providerId, domain, options.connectionId, resolved.rejection),
-		);
+		// A scope the query cannot spell, refused rather than sanitized — see `isUsableSearchScopeName`.
+		case 'unusable-scope':
+			return refused(
+				otherWarning(
+					options.providerId,
+					domain,
+					options.connectionId,
+					unusableSearchScopeMessage('issue search scopes', scope.rejection.scopes),
+				),
+			);
 	}
 
 	const readPage = (cursor: string | undefined) =>

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

@@ -24,6 +24,7 @@ import {
 	pullRequestSearchCapResultWarning,
 	truncationWarning,
 	unsupportedPullRequestSearchCriteriaWarning,
+	unusableSearchScopeMessage,
 } from './warnings.js';
 
 /**
@@ -44,6 +45,7 @@ export async function searchPullRequestsPage(
 		criteria?: PullRequestSearchCriteria;
 		page?: number;
 		cursor?: string;
+		/** Per relationship × state facet, not per page; see {@link IntegrationManager.searchPullRequestsPage}. */
 		itemsPerPage?: number;
 		forceSync?: boolean;
 		connectionId?: string;
@@ -100,7 +102,7 @@ export async function searchPullRequestsPage(
 	}
 
 	const scope = resolvePullRequestSearchScope(options.providerId, options.repos, options.org, options.criteria);
-	switch (scope.rejection) {
+	switch (scope.rejection?.reason) {
 		case 'unscoped':
 			return refused(
 				otherWarning(
@@ -125,10 +127,22 @@ export async function searchPullRequestsPage(
 				unsupportedPullRequestSearchCriteriaWarning(options.providerId, domain, options.connectionId, {
 					reason: 'unsupported-criteria',
 					criteria: [
-						scope.rejection === 'unsupported-repository-scope' ? 'repositoryScope' : 'organizationScope',
+						scope.rejection.reason === 'unsupported-repository-scope'
+							? 'repositoryScope'
+							: 'organizationScope',
 					],
 				}),
 			);
+		// A scope the query cannot spell, refused rather than sanitized — see `isUsableSearchScopeName`.
+		case 'unusable-scope':
+			return refused(
+				otherWarning(
+					options.providerId,
+					domain,
+					options.connectionId,
+					unusableSearchScopeMessage('pull request search scopes', scope.rejection.scopes),
+				),
+			);
 	}
 
 	const readPage = (cursor: string | undefined) =>

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

@@ -261,6 +261,25 @@ export function unsupportedFiltersWarning(
 	);
 }
 
+/**
+ * The one sentence every `unusable-scope` refusal uses — the five surfaces that validate a search scope (both
+ * searches, both count probes, and issue broadening) differ only in the noun and in whether they name a count
+ * key, so the reason a scope is unusable is written once. `prefix` is what the count probes put in front of it
+ * to name their key.
+ *
+ * NAMES the offending values, because which failure mode applied is not deducible from the value: a quote makes
+ * `git"kraken` a request for the real and different org `gitkraken`, a space makes `my org` a search of `my`
+ * filtered by the text `org`, and a value of only quotes or whitespace leaves no scope at all. The caller is the
+ * only layer that knows which scope it meant.
+ *
+ * Says how to fix it rather than what was stripped: a consumer cannot mirror this rule (unlike free-text
+ * sanitizing, whose rules are published for exactly that), so "pass the scope as the provider names it" is the
+ * actionable half.
+ */
+export function unusableSearchScopeMessage(noun: string, scopes: readonly string[], prefix?: string): string {
+	return `${prefix != null ? `${prefix}: ` : ''}The requested ${noun} (${scopes.map(s => JSON.stringify(s)).join(', ')}) cannot be used as given: a scope name cannot contain quotes, or an inner space or control character, which a query would drop or read as a second qualifier — searching a different scope, or none. Pass the scope exactly as the provider names it.`;
+}
+
 /** Warning for a filtered pull-request search the provider cannot run as requested. */
 export function unsupportedPullRequestSearchCriteriaWarning(
 	id: IntegrationIds,