@gitkraken/core-gitlens 0.5.115 → 0.5.116

package/src/plus/integrations/manager.ts

@@ -404,15 +404,36 @@ export interface IntegrationManager {
 	 */
 	searchPullRequestsPage(options: {
 		providerId: IntegrationIds;
-		/** Repository descriptors that bound the search; ids cannot name provider search qualifiers. */
+		/**
+		 * Repository descriptors that bound the search; ids cannot name provider search qualifiers.
+		 *
+		 * Both halves of a descriptor must reach the provider unchanged — see `org` — since a search names a
+		 * repository by its `namespace/name` path.
+		 */
 		repos?: ProviderRepositoriesInput;
-		/** Organization/account that bounds the search. */
+		/**
+		 * Organization/account that bounds the search.
+		 *
+		 * Held to a STRICTER rule than the free-form `criteria.text`, which is sanitized: a scope name carrying a
+		 * quote, or an inner space or control character, is REFUSED (warning + `fetchFailed`), and the refusal
+		 * names the value. Leading and trailing whitespace and control characters are stripped and accepted,
+		 * since removing them cannot change which scope the query names. Sanitizing a scope would answer the wrong question — the sanitized value may name a real but
+		 * DIFFERENT organization, whose result looks entirely normal. Pass the name exactly as the provider spells
+		 * it; `''` means "no org supplied" and falls through to the other scopes.
+		 */
 		org?: string;
 		criteria?: PullRequestSearchCriteria;
 		/** Cursor-only: without a cursor, reaching page N costs O(N) upstream requests. */
 		page?: number;
 		cursor?: string;
-		/** Page size per relationship × state facet; the deduped union can contain more rows. */
+		/**
+		 * Page size PER RELATIONSHIP × STATE facet, not per page. Each facet is its own aliased provider query —
+		 * one axis more than {@link searchIssuesPage}'s per-relationship fan-out — so a page of a 3-relationship,
+		 * 2-state search returns up to `6 × itemsPerPage` items before deduplication, and fewer than that where
+		 * the facets overlap. Deduplication does NOT bring the page back to this size: it removes only the rows the
+		 * facets share. `page.itemsPerPage` reports what actually came back, so size the UI off that rather than
+		 * off this. A provider may also cap it below what is asked for.
+		 */
 		itemsPerPage?: number;
 		forceSync?: boolean;
 		connectionId?: string;
@@ -420,7 +441,9 @@ export interface IntegrationManager {
 		domain?: string;
 		/**
 		 * Requests the lightweight row shape: identity, body, author, repository, branch refs and stack info,
-		 * without review, check or diff statistics. It also raises the default page size.
+		 * without review, check or diff statistics. It also replaces the flat per-facet default page size with a
+		 * fixed budget shared across the search's ACTIVE facets, so with up to three of them it raises the page
+		 * and from four on it LOWERS it — measured against GitHub, a 100-row budget versus a flat 30 each.
 		 *
 		 * A provider without a lightweight projection ignores it and returns its usual shape, so this is a hint
 		 * rather than a contract about which fields are present.
@@ -513,9 +536,23 @@ export interface IntegrationManager {
 	 */
 	searchIssuesPage(options: {
 		providerId: IntegrationIds;
-		/** Repositories to search. Combines with `org`; both constrain the same query. */
+		/**
+		 * Repositories to search. Combines with `org`; both constrain the same query.
+		 *
+		 * Both halves of a descriptor must reach the provider unchanged — see `org` — since a search names a
+		 * repository by its `namespace/name` path.
+		 */
 		repos?: ProviderRepositoriesInput;
-		/** Organization/account to search. Combines with `repos`. */
+		/**
+		 * Organization/account to search. Combines with `repos`.
+		 *
+		 * Held to a STRICTER rule than the free-form criteria, which are sanitized: a scope name carrying a quote,
+		 * or an inner space or control character, is REFUSED (warning + `fetchFailed`), and the refusal names the
+		 * value. Leading and trailing whitespace and control characters are stripped and accepted, since removing
+		 * them cannot change which scope the query names.
+		 * The sanitized value may name a real but DIFFERENT org, whose result looks entirely normal. `''` means
+		 * "no org supplied" and falls through to the other scopes.
+		 */
 		org?: string;
 		criteria?: IssueSearchCriteria;
 		/**

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

@@ -25,6 +25,7 @@ import {
 	otherWarning,
 	truncationWarning,
 	unsupportedIssueSearchCriteriaWarning,
+	unusableSearchScopeMessage,
 } from './warnings.js';
 
 /**
@@ -350,21 +351,6 @@ interface OrgIssuesRead {
 	nothingToRead?: boolean;
 }
 
-/**
- * Whether this org can be read through the FILTERED issue search instead of the repository drain.
- *
- * Two conditions, and the second is not a formality: an empty org name is dropped by the provider's scope
- * translation rather than rejected, which would leave a search of the WHOLE HOST — so the scope is validated
- * through {@link resolveIssueSearchScope}, the same rule `searchIssuesPage` refuses on, rather than by an
- * `org.name.length > 0` written here and free to drift from it.
- */
-function canSearchOrgIssues(org: ProviderBroadenOrg): boolean {
-	return (
-		supportsFilteredIssueSearch(org.providerId) &&
-		resolveIssueSearchScope(undefined, org.name, undefined).rejection == null
-	);
-}
-
 /**
  * The org-scoped filtered search: ONE request per page, whatever the org contains.
  *
@@ -602,6 +588,34 @@ async function readOrgSlice(
 		);
 	}
 
+	// An org name NEITHER engine can use, refused before either is chosen. Declining the search for it is not
+	// enough, because falling through to the repository drain is not the safe default it looks like: the drain
+	// passes the SAME name to the org repository read, which matches nothing and reports `nothingToRead` — an
+	// org that reads as empty, with no warning and no `fetchFailed`, after up to 100 requests. Indistinguishable
+	// from an org that genuinely has no issues, and strictly worse than saying so.
+	//
+	// EVERY rejection, not just `unusable-scope`: with no repositories and no criteria the only other reachable
+	// one is `unscoped`, which here means exactly `org.name === ''` — the same bad outcome by the same route, so
+	// drawing the line between them would leave the emptiest case on the wrong side of the rule. (`repo-ids`
+	// cannot arise: no repositories are passed.) Refusing them all is also what lets the engine choice below be
+	// a plain capability question again, since no rejection survives this point.
+	const scopeRejection = resolveIssueSearchScope(undefined, org.name, undefined).rejection;
+	if (scopeRejection != null) {
+		return barrenSlice(
+			[
+				otherWarning(
+					org.providerId,
+					ctx.domainForRead(integration, org.providerId, connectionId, requestedDomain),
+					connectionId,
+					scopeRejection.reason === 'unusable-scope'
+						? unusableSearchScopeMessage('issue broadening scopes', scopeRejection.scopes)
+						: 'Issue broadening must name an organization; one was supplied with an empty name.',
+				),
+			],
+			{ fetchFailed: true },
+		);
+	}
+
 	// An org a prior round already drained must not be re-read: cursor-only providers would answer a
 	// fresh page-1 request with their first page again, duplicating issues across rounds. Skip it
 	// before any work (including the repo drain) and keep it marked exhausted so it stays skipped
@@ -614,7 +628,12 @@ async function readOrgSlice(
 
 	const domain = ctx.domainForRead(integration, org.providerId, connectionId, requestedDomain);
 	const cursor = getBroadenIssuesCursor(options.cursor, org, page, options.orgs.length);
-	const read = canSearchOrgIssues(org)
+	// A plain capability question, and only because the refusal above has already turned away every org whose
+	// name the scope rule rejects. That order matters: `readOrgIssuesViaSearch` calls the integration's
+	// `searchIssuesPageResult` directly rather than the `searchIssuesPage` read, and that method documents its
+	// scope as already validated ("the facade rejects it before here") — so an unvalidated name reaching it would
+	// go straight to the provider query that sanitizes it.
+	const read = supportsFilteredIssueSearch(org.providerId)
 		? await readOrgIssuesViaSearch(integration, org, domain, cursor)
 		: await readOrgIssuesViaRepoDrain(integration, org, domain, cursor);
 	if (read.nothingToRead === true) {

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

@@ -27,6 +27,7 @@ import {
 	otherWarning,
 	unsupportedIssueSearchCriteriaWarning,
 	unsupportedPullRequestSearchCriteriaWarning,
+	unusableSearchScopeMessage,
 } from './warnings.js';
 
 /**
@@ -199,6 +200,23 @@ export async function countIssues(
 		return refused(issuesUnsupportedWarning(options.providerId, domain, options.connectionId));
 	}
 
+	// A provider with no filtered issue search has no count either: refuse ONCE for the provider rather than
+	// letting every scope repeat the same rejection. `undefined` criteria probes only the search's existence.
+	// Matches `countPullRequests`. Refusing it here rather than per scope also keeps the loop's warnings from
+	// being dominated by N copies of one provider-level fact — see the dedupe below, which handles the
+	// keyless refusals that remain.
+	const searchSupport = resolveIssueSearchCriteria(options.providerId, undefined);
+	if (searchSupport.rejection != null) {
+		return refused(
+			unsupportedIssueSearchCriteriaWarning(
+				options.providerId,
+				domain,
+				options.connectionId,
+				searchSupport.rejection,
+			),
+		);
+	}
+
 	const providerLimit = providersMetadata[options.providerId]?.issueSearchResultLimit;
 	const warnings: ProviderWarning[] = [];
 	let fetchFailed = false;
@@ -209,10 +227,12 @@ export async function countIssues(
 	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);
+			// Deduped rather than pushed. The rejections that name the offending SCOPE embed its own key, and
+			// duplicate keys were already refused above, so those can never collapse. But the ones that report a
+			// PROVIDER-level fact — a criterion it cannot express, a contradictory relationship pair — name no
+			// scope, so several scopes failing the same way produce byte-identical warnings, and one refusal
+			// reported N times reads as N different problems.
+			appendDedupedWarning(warnings, warning);
 			fetchFailed = true;
 			continue;
 		}
@@ -304,8 +324,15 @@ function rejectScope(
 	connectionId: string | undefined,
 	scope: IssueCountScope,
 ): ProviderWarning | undefined {
+	const resolved = resolveIssueSearchCriteria(providerId, scope.criteria);
+	if (resolved.rejection != null) {
+		return unsupportedIssueSearchCriteriaWarning(providerId, domain, connectionId, resolved.rejection);
+	}
+
+	// AFTER the criteria check, mirroring `searchIssuesPage`: a provider with no filtered issue search is the more
+	// fundamental refusal, and a count must preview the refusal its read would give.
 	const scoping = resolveIssueSearchScope(scope.repos, scope.org, scope.criteria);
-	switch (scoping.rejection) {
+	switch (scoping.rejection?.reason) {
 		case 'repo-ids':
 			return otherWarning(
 				providerId,
@@ -320,11 +347,15 @@ function rejectScope(
 				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);
+		// A count applies exactly the qualifiers its search would, so an unusable scope would make it agree with
+		// the wrong search rather than expose it — see `isUsableSearchScopeName`.
+		case 'unusable-scope':
+			return otherWarning(
+				providerId,
+				domain,
+				connectionId,
+				unusableSearchScopeMessage('scopes', scoping.rejection.scopes, `Issue count scope '${scope.key}'`),
+			);
 	}
 
 	// Count-only, with no counterpart in the read: a relationship set is an OR across several searches, which one
@@ -435,9 +466,11 @@ export async function countPullRequests(
 	for (const scope of options.scopes) {
 		const warning = rejectPullRequestScope(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.
-			warnings.push(warning);
+			// Deduped rather than pushed: see the issue twin. Here the keyless set is wider — besides the criteria
+			// rejections, `unsupported-repository-scope` and `unsupported-organization-scope` are scope rejections
+			// that route through the criteria warning and name no key, and both are provider-level facts every
+			// scope would repeat.
+			appendDedupedWarning(warnings, warning);
 			fetchFailed = true;
 			continue;
 		}
@@ -516,7 +549,7 @@ function rejectPullRequestScope(
 	scope: PullRequestCountScope,
 ): ProviderWarning | undefined {
 	const scoping = resolvePullRequestSearchScope(providerId, scope.repos, scope.org, scope.criteria);
-	switch (scoping.rejection) {
+	switch (scoping.rejection?.reason) {
 		case 'repo-ids':
 			return otherWarning(
 				providerId,
@@ -536,9 +569,23 @@ function rejectPullRequestScope(
 			return unsupportedPullRequestSearchCriteriaWarning(providerId, domain, connectionId, {
 				reason: 'unsupported-criteria',
 				criteria: [
-					scoping.rejection === 'unsupported-repository-scope' ? 'repositoryScope' : 'organizationScope',
+					scoping.rejection.reason === 'unsupported-repository-scope'
+						? 'repositoryScope'
+						: 'organizationScope',
 				],
 			});
+		// See the issue twin, and `isUsableSearchScopeName` for the rule.
+		case 'unusable-scope':
+			return otherWarning(
+				providerId,
+				domain,
+				connectionId,
+				unusableSearchScopeMessage(
+					'scopes',
+					scoping.rejection.scopes,
+					`Pull request count scope '${scope.key}'`,
+				),
+			);
 	}
 
 	const resolved = resolvePullRequestSearchCriteria(providerId, scope.criteria);

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

@@ -129,14 +129,19 @@ export function resolvePullRequestSearchCriteria(
 
 /** Why a filtered pull-request search's repository/organization boundary was refused. */
 export type PullRequestSearchScopeRejection =
-	| 'unscoped'
-	| 'repo-ids'
-	| 'unsupported-repository-scope'
-	| 'unsupported-organization-scope';
+	| { reason: 'unscoped' }
+	| { reason: 'repo-ids' }
+	| { reason: 'unsupported-repository-scope' }
+	| { reason: 'unsupported-organization-scope' }
+	/** Scope names a query cannot carry AS GIVEN; see {@link unusableSearchScopeNames}. */
+	| { reason: 'unusable-scope'; scopes: string[] };
 
 /**
  * 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.
+ *
+ * Scope names go through the same {@link unusableSearchScopeNames} rule the issue search uses — shared rather
+ * than re-derived, because the defect is identical on both reads.
  */
 export function resolvePullRequestSearchScope(
 	id: IntegrationIds,
@@ -148,22 +153,32 @@ export function resolvePullRequestSearchScope(
 	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' };
+		if (repos.some(r => typeof r === 'string' || typeof r === 'number')) {
+			return { rejection: { reason: 'repo-ids' } };
+		}
+		if (supported?.repositoryScope !== true) return { rejection: { reason: 'unsupported-repository-scope' } };
 
 		resolvedRepos = repos as ProviderRepoInput[];
 	}
 
 	const hasOrganizationScope = org != null && org.length > 0;
 	if (hasOrganizationScope && supported?.organizationScope !== true) {
-		return { rejection: 'unsupported-organization-scope' };
+		return { rejection: { reason: 'unsupported-organization-scope' } };
 	}
 
+	// After the capability checks and before the "is it scoped at all" rule: a scope the provider cannot express
+	// at all is the more fundamental refusal, and an unusable value that WAS supplied must not be reported as a
+	// missing one. `org` is passed bare, matching the issue twin — the helper applies its own empty-means-
+	// unsupplied guard, so re-testing `hasOrganizationScope` here would only make the two resolvers look like
+	// they differ.
+	const unusable = unusableSearchScopeNames(org, resolvedRepos);
+	if (unusable.length > 0) return { rejection: { reason: 'unusable-scope', scopes: unusable } };
+
 	if (resolvedRepos != null || hasOrganizationScope || (criteria?.relationships?.length ?? 0) > 0) {
 		return { repos: resolvedRepos };
 	}
 
-	return { rejection: 'unscoped' };
+	return { rejection: { reason: 'unscoped' } };
 }
 
 /**
@@ -321,25 +336,105 @@ const unsupportedPullRequestSearchCapabilities: PullRequestSearchCapabilities =
 /** 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'
+	| { reason: 'unscoped' }
 	/** Repositories given as ids. A search names repositories by PATH, so ids can't express a scope. */
-	| 'repo-ids';
+	| { reason: 'repo-ids' }
+	/** Scope names a query cannot carry AS GIVEN; see {@link unusableSearchScopeNames}. */
+	| { reason: 'unusable-scope'; scopes: string[] };
 
 /**
- * Whether a scope name survives the provider's sanitizing, i.e. whether it will actually constrain the query.
+ * Whether a scope name reaches the provider NAMING THE SAME SCOPE — the one rule behind every `unusable-scope`
+ * refusal, and the canonical home for its reasoning: the call sites point here rather than restating it.
+ *
+ * The defect it exists to prevent: the boundary is checked against the value AS SUPPLIED while the request is
+ * built from the value AFTER the provider sanitizes it, so a name a query cannot spell produces a read that is no
+ * longer the read that was authorized. Three outcomes, all of which LOOK LIKE SUCCESS, so there is nothing for a
+ * consumer to branch on:
+ * - **emptied** — a value of only quotes/whitespace/control characters emits no scope qualifier at all. A scope is
+ *   also what makes a relationship-less read legal, so the request carries neither and every item on the host
+ *   matches: measured at 52 million issues across unrelated accounts.
+ * - **altered** — a quote inside a real name sanitizes to a real but DIFFERENT scope (`git"kraken` -> `gitkraken`),
+ *   whose answer looks entirely normal.
+ * - **split** — whitespace delimits qualifiers, so `my org` emits `org:my org`: a search of `my` additionally
+ *   filtered by the free text `org`. Measured against the live API this is a wrong NARROWING rather than a
+ *   widening — `org:gitkraken bar` returns 12 where `org:gitkraken` returns 379.
+ *
+ * Refusing beats sanitizing, and the count probes are why it matters most: they deliberately apply exactly the
+ * qualifiers their search would, so a sanitized scope makes the count AGREE with the wrong search rather than
+ * disagree with it, and a consumer cross-checking "N matched" cannot detect it by construction. Nor can it
+ * pre-empt the rule — the free-text sanitizing rules are published precisely so a caller can mirror them, the
+ * scope rules are not — so only the caller knows which scope it meant, and the refusal goes back to it NAMING the
+ * offending value.
  *
  * Provider-NEUTRAL by design, and deliberately not an import of GitHub's `sanitizeGitHubQualifierValue`: this
  * module validates for every provider, and a GitHub-specific rule reaching in here would be wrong for the next
- * one that declares a search. What is common to any query language is the part that matters: a value made only of
- * whitespace, quotes and control characters carries no name, and every sanitizer strips exactly those (quotes
- * because they would close their own qualifier, control characters because they cannot appear in a query at all).
+ * one that declares a search. Only GitHub and GHE declare one today, so the character class below is GitHub's in
+ * practice; it is stated as the common part of any query language because each class breaks a query on its own
+ * terms — a quote closes its own qualifier, a control character cannot appear at all, whitespace delimits the
+ * next qualifier — but a provider whose names legitimately carry one (Azure DevOps project names can contain
+ * spaces) needs its own rule alongside its `supported*Search` capability rather than an exception here.
+ *
+ * EDGES ARE STRIPPED before the test, which is what keeps the predicate no stricter than the provider's own
+ * sanitizing — the invariant that makes refusing safe to add, since it means this can only reject a name the
+ * provider would have altered, never one it would have resolved correctly. Leading and trailing whitespace AND
+ * control characters both qualify: a sanitizer maps a control character to a space, then collapses and trims, so
+ * `'gitkraken\n'` and `'gitkraken\u0000'` alike emit `org:gitkraken` — the scope that was asked for. Note this
+ * is wider than `String.trim()`, which leaves control characters in place.
  *
- * Strictly weaker than any provider's own sanitizing, which is the safe direction: this can only pass a name the
- * provider would then narrow further, never reject one the provider would have accepted.
+ * None of the three outcomes above survives the stripping, so the rule loses nothing: an all-edge value still
+ * empties, an INNER space or control character still splits (`'git\u0000kraken'` emits `git kraken`, two
+ * tokens), and a quote still alters wherever it sits.
  */
 function isUsableSearchScopeName(name: string): boolean {
+	const stripped = stripSearchScopeEdges(name);
 	// eslint-disable-next-line no-control-regex
-	return name.replace(/["\u0000-\u001f\u007f\s]/g, '').length > 0;
+	return stripped.length > 0 && !/["\u0000-\u001f\u007f\s]/.test(stripped);
+}
+
+/** The leading/trailing run a provider's sanitizing removes — see {@link isUsableSearchScopeName}. */
+function stripSearchScopeEdges(value: string): string {
+	// eslint-disable-next-line no-control-regex
+	return value.replace(/^[\s\u0000-\u001f\u007f]+|[\s\u0000-\u001f\u007f]+$/g, '');
+}
+
+/**
+ * The scope names a search cannot carry as given, as the strings to name in the refusal — empty when every one is
+ * usable. See {@link isUsableSearchScopeName} for the rule and why it refuses rather than sanitizes.
+ */
+function unusableSearchScopeNames(org: string | undefined, repos: readonly ProviderRepoInput[] | undefined): string[] {
+	const unusable: string[] = [];
+
+	// An EMPTY org is "no org supplied" and falls through to the remaining scopes; any other unusable value WAS
+	// supplied, so it is refused rather than dropped.
+	if (org != null && org.length > 0 && !isUsableSearchScopeName(org)) {
+		unusable.push(org);
+	}
+
+	// A `repo:` qualifier names a repository by its JOINED `namespace/name` path, which is the value the rule
+	// below is applied to. Both halves are read defensively, through the SAME locals the label is built from: the
+	// descriptor form is only narrowed from a union by an element-type check, so a half-built descriptor reaches
+	// here as `undefined` and must refuse rather than throw out of a facade that reports refusals as warnings —
+	// and reporting it as `undefined/a` would name a value the caller never passed.
+	for (const repo of repos ?? []) {
+		const namespace = repo.namespace ?? '';
+		const name = repo.name ?? '';
+		const path = `${namespace}/${name}`;
+		// BOTH the composite and each half, because neither sees what the other does:
+		// - the composite catches an offender the halves cannot, since an edge of a half is an INTERIOR character
+		//   of the path — `{ 'git ', 'kraken' }` has two usable-looking halves and emits `repo:git /kraken`.
+		// - the halves catch a BLANK one the composite cannot, since that offender sits at a composite EDGE where
+		//   stripping removes it — `' /a'` strips to `'/a'`, a perfectly spellable qualifier naming no repository.
+		// Each half is measured after the same stripping, so `' '` and `''` are one case rather than two.
+		if (
+			!isUsableSearchScopeName(path) ||
+			stripSearchScopeEdges(namespace).length === 0 ||
+			stripSearchScopeEdges(name).length === 0
+		) {
+			unusable.push(path);
+		}
+	}
+
+	return unusable;
 }
 
 /**
@@ -351,32 +446,39 @@ function isUsableSearchScopeName(name: string): boolean {
  * 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.
+ * `repo-ids` and `unscoped` are mutually exclusive — one requires repositories and the other requires none — so
+ * their relative order is free. `unusable-scope` is NOT: it must precede `unscoped`, so a value that was supplied
+ * but cannot be used is never reported as a missing one.
  *
- * An org is checked for what SURVIVES SANITIZING, not merely for being non-empty, and that distinction is a
- * SECURITY one rather than a nicety: the provider query drops a value that sanitizes away rather than rejecting
- * it (`toGitHubIssueSearchScopeQualifiers` emits no bare `org:`, which GitHub would reject), so an org of `'   '`
- * or `'"'` would pass a length check, emit NO scope qualifier at all, and leave a search of the entire host —
- * measured at 52 million issues across unrelated accounts. Whitespace and quotes are exactly what a name pasted
- * from a config or a URL degrades to, so this is reachable without anything adversarial.
+ * Every scope name is checked for naming the same scope after the provider sanitizes it, not merely for being
+ * non-empty, and that distinction is a SECURITY one rather than a nicety — see {@link isUsableSearchScopeName}.
  */
 export function resolveIssueSearchScope(
 	repos: ProviderReposInput | undefined,
 	org: string | undefined,
 	criteria: IssueSearchCriteria | undefined,
 ): { rejection?: IssueSearchScopeRejection; repos?: ProviderRepoInput[] } {
+	let resolvedRepos: ProviderRepoInput[] | undefined;
+
 	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' };
+		if (repos.some(r => typeof r === 'string' || typeof r === 'number')) {
+			return { rejection: { reason: 'repo-ids' } };
+		}
 
-		return { repos: repos as ProviderRepoInput[] };
+		resolvedRepos = repos as ProviderRepoInput[];
 	}
 
-	if (org != null && isUsableSearchScopeName(org)) return {};
+	// Checked BEFORE the "is it scoped at all" rule below, so an unusable value is never reported as a missing
+	// one: it was supplied, and telling the caller to pass a scope it already passed names the wrong defect.
+	const unusable = unusableSearchScopeNames(org, resolvedRepos);
+	if (unusable.length > 0) return { rejection: { reason: 'unusable-scope', scopes: unusable } };
+
+	if (resolvedRepos != null) return { repos: resolvedRepos };
+	if (org != null && org.length > 0) return {};
 	if (criteria?.relationships?.some(r => userScopingIssueSearchRelationships.includes(r)) === true) return {};
 
-	return { rejection: 'unscoped' };
+	return { rejection: { reason: 'unscoped' } };
 }
 
 /**

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) =>