@gitkraken/core-gitlens 0.5.114 → 0.5.116

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/issueTracker.ts

@@ -2,7 +2,7 @@ import type { CollectionMetadata } from '@gitkraken/provider-apis';
 import type { IssueShape, IssueSorting } from '../../../git/models/issue.js';
 import type { ResourceDescriptor } from '../../../git/models/resourceDescriptor.js';
 import { mapBounded } from '../../../utils/promise.js';
-import { mergeAssessmentInto } from '../collectionMetadata.js';
+import { assessCollectionMetadata, mergeAssessmentInto } from '../collectionMetadata.js';
 import type { IntegrationIds } from '../constants.js';
 import { providerFanOutConcurrency } from '../constants.js';
 import { isIssuesIntegration } from '../models/issuesIntegration.js';
@@ -452,10 +452,7 @@ export async function listIssueTrackerIssuesPage(
 	// Partial project discovery means some projects' issues are missing from this page; propagate it so the
 	// page reports fetchFailed even when every discovered project's own read succeeded.
 	let fetchFailed = projectDiscoveryFailed || accountLookupFailed;
-	// A project whose internal page-drain hit its backstop (Jira/Linear cap at maxPagesPerRequest) reports
-	// `truncated`; surface it as `page.truncated` so a windowed read isn't published as having drained each
-	// project completely.
-	let projectTruncated = projectDiscoveryTruncated;
+	let truncationRecovery: 'narrow-scope' | 'none' | undefined = projectDiscoveryTruncated ? 'none' : undefined;
 	let drainMetadata: CollectionMetadata | undefined;
 	for (const { project, value: result, warning } of perProject) {
 		const key = projectKey(project);
@@ -465,7 +462,7 @@ export async function listIssueTrackerIssuesPage(
 			// single failing token repeats verbatim once per project in the window.
 			appendDedupedWarning(warnings, warning);
 			fetchFailed = true;
-			projectTruncated = true;
+			truncationRecovery = 'none';
 		}
 		// A thrown/unsupported read (e.g. Linear not-implemented) surfaces as a warning with no value;
 		// mark the aggregate as fetchFailed so an empty result isn't mistaken for "no issues".
@@ -475,7 +472,8 @@ export async function listIssueTrackerIssuesPage(
 		if (result != null) {
 			items.push(...result.values);
 			if (result.truncated) {
-				projectTruncated = true;
+				const recovery = result.recovery;
+				truncationRecovery = truncationRecovery == null || truncationRecovery === recovery ? recovery : 'none';
 			}
 			if (result.metadata != null) {
 				drainMetadata = mergeCollectionMetadata(drainMetadata, result.metadata);
@@ -497,29 +495,33 @@ export async function listIssueTrackerIssuesPage(
 	// publishes. A no-op when nothing merged, since the tracker already ordered that single run.
 	const orderedItems = ordering.order(items);
 
-	const drainAssessment = mergeAssessmentInto(
-		warnings,
-		options.providerId,
-		domain,
-		options.connectionId,
-		drainMetadata,
-	);
+	const projectReadReportedTruncation = truncationRecovery != null;
+	const drainAssessment = assessCollectionMetadata(options.providerId, domain, options.connectionId, drainMetadata);
+	for (const warning of drainAssessment.warnings) {
+		// A project result already supplies the recovery semantics. Replace metadata's unstructured fallback with
+		// the structured warning below, while retaining specific failures and omissions.
+		if (projectReadReportedTruncation && !drainAssessment.fetchFailed && warning.omission == null) continue;
+
+		appendDedupedWarning(warnings, warning);
+	}
 	fetchFailed = fetchFailed || drainAssessment.fetchFailed;
-	projectTruncated = projectTruncated || drainAssessment.truncated;
+	if (drainAssessment.truncated) {
+		truncationRecovery = 'none';
+	}
 
-	// A per-project read that returned data but couldn't confirm completeness (e.g. Trello's provider-native
-	// cap) sets `truncated` without a structured failure. Add one provider-neutral incompleteness warning so
-	// the caller sees the truncation, but only when no warning already explains it (avoid duplicate noise).
-	if (projectTruncated && warnings.length === 0) {
-		warnings.push(
+	const projectTruncated = truncationRecovery != null;
+	const scopeTooLarge = !fetchFailed && truncationRecovery === 'narrow-scope';
+	if (scopeTooLarge || (!fetchFailed && projectTruncated && !warnings.some(warning => warning.omission != null))) {
+		appendDedupedWarning(
+			warnings,
 			incompleteReadWarning(
 				options.providerId,
 				domain,
 				options.connectionId,
-				'Some issues were omitted; the provider returned an incomplete result.',
-				// `exhausted`, not `page-budget`: the per-project drain's backstop is an internal constant
-				// (`maxPagesPerRequest`), not an option this read exposes, so no caller can raise it.
-				fetchFailed ? 'interrupted' : 'exhausted',
+				scopeTooLarge
+					? 'Some projects hold more issues than one read can return; narrow the scope to read the rest.'
+					: 'Some issues were omitted; the provider returned an incomplete result.',
+				scopeTooLarge ? 'scope-too-large' : 'exhausted',
 			),
 		);
 	}

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/trackerIssue.ts

@@ -0,0 +1,105 @@
+import type { IssueShape } from '../../../git/models/issue.js';
+import type { IntegrationIds } from '../constants.js';
+import { IssuesCloudHostIntegrationId } from '../constants.js';
+import { isIssuesIntegration } from '../models/issuesIntegration.js';
+import type { ProviderResult, ProviderWarning } from '../results.js';
+import { isIssuesHostIntegrationId } from '../utils/integration.utils.js';
+import type { ProviderReadContext } from './context.js';
+import { runCaptured } from './drains.js';
+import { issueTrackerOnlySurfaceWarning, otherWarning } from './warnings.js';
+
+export interface TrackerIssueResult {
+	key: string;
+	/**
+	 * The resolved issue, or `undefined` when it provably does not exist or is not visible to this connection.
+	 * A failed read returns no item and sets `fetchFailed`.
+	 */
+	issue?: IssueShape;
+}
+
+/** Issue trackers are cloud-only, so this read takes no `domain`. */
+export async function getTrackerIssue(
+	ctx: ProviderReadContext,
+	options: {
+		providerId: IntegrationIds;
+		resourceId: string;
+		resourceUrl?: string;
+		key: string;
+		connectionId?: string;
+	},
+): Promise<ProviderResult<TrackerIssueResult>> {
+	const refused = (warning: ProviderWarning): ProviderResult<TrackerIssueResult> => ({
+		items: [],
+		warnings: [warning],
+		fetchFailed: true,
+	});
+	const surface = 'Issue resolution by key';
+
+	if (!isIssuesHostIntegrationId(options.providerId)) {
+		return refused(issueTrackerOnlySurfaceWarning(options.providerId, options.connectionId, surface));
+	}
+
+	if (options.resourceId.trim().length === 0) {
+		return refused(
+			otherWarning(options.providerId, undefined, options.connectionId, `${surface} requires a resource id.`),
+		);
+	}
+
+	if (options.key.trim().length === 0) {
+		return refused(
+			otherWarning(options.providerId, undefined, options.connectionId, `${surface} requires an issue key.`),
+		);
+	}
+
+	const resourceUrl = options.resourceUrl?.trim() || undefined;
+	if (options.providerId === IssuesCloudHostIntegrationId.Jira && resourceUrl == null) {
+		return refused(
+			otherWarning(
+				options.providerId,
+				undefined,
+				options.connectionId,
+				`${surface} requires the Jira resource URL so the result contains a browser link without resource discovery.`,
+			),
+		);
+	}
+
+	const integration = await ctx.getIntegrationForRead(options.providerId, options.connectionId);
+	if (integration == null) {
+		const early = ctx.earlyReturnConnectionWarnings(options.providerId, options.connectionId);
+		return { items: [], warnings: early.warnings, fetchFailed: early.fetchFailed || undefined };
+	}
+	if (!isIssuesIntegration(integration)) {
+		return refused(issueTrackerOnlySurfaceWarning(options.providerId, options.connectionId, surface));
+	}
+	if (!integration.supportsIssueLookupByResourceId) {
+		return refused(
+			otherWarning(
+				options.providerId,
+				undefined,
+				options.connectionId,
+				`${surface} is not supported by '${options.providerId}'; its single-issue read cannot prove an absence, so a miss would not be safe to cache.`,
+			),
+		);
+	}
+
+	const domain = ctx.domainForRead(integration, options.providerId, options.connectionId);
+	const issue = await runCaptured(
+		options.providerId,
+		domain,
+		options.connectionId,
+		() =>
+			integration.getIssueByResourceIdResult(options.resourceId, options.key, {
+				connectionId: options.connectionId,
+				resourceUrl: resourceUrl,
+			}),
+		{ warnOnMissingSession: true },
+	);
+	if (issue.warning != null) {
+		return refused(issue.warning);
+	}
+
+	return {
+		items: [{ key: options.key, ...(issue.value != null ? { issue: issue.value } : {}) }],
+		warnings: [],
+	};
+}

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

@@ -8,7 +8,7 @@ import type {
 	PullRequestSorting,
 } from '../providerFilters.js';
 import { providersMetadata } from '../providers/models.js';
-import type { ProviderWarning } from '../results.js';
+import type { ProviderWarning, ProviderWarningOmissionRecovery } from '../results.js';
 import type { IssueSearchCriteriaRejection, PullRequestSearchCriteriaRejection } from './filters.js';
 import type { UnmergeableIssueSort, UnsupportedIssueSortRejection } from './ordering.js';
 
@@ -101,21 +101,23 @@ export function issueTrackerOnlySurfaceWarning(
 	);
 }
 
-/**
- * Why a read the facade drove itself returned less than everything. The two questions a consumer cannot
- * answer from `truncated` or from the message, kept together because they are decided together:
- *
- * - `interrupted`: the read did NOT succeed — the session went away, a later page failed. It leaves an unread
- *   tail like the others, but it is a failure: it sets `fetchFailed`, and a retry is exactly the right move.
- *   Gets no omission at all, since the omission asserts the opposite.
- * - `page-budget`: the drain stopped at its own `maxPages`, with a usable cursor still in hand. The items ARE
- *   reachable and were simply not fetched, so re-running with a higher budget returns them.
- * - `exhausted`: everything else that succeeded and came back short — the provider capped the page it served,
- *   advertised another page without a usable cursor (or with one it had already handed out), or a read could
- *   not confirm it had drained everything. The default of the three: choose it whenever a raisable budget is
- *   not demonstrably what stopped the read, so a consumer is never offered a fetch that cannot deliver.
- */
-export type IncompleteReadCause = 'interrupted' | 'page-budget' | 'exhausted';
+/** Why a facade-driven read returned fewer results than requested. */
+export type IncompleteReadCause = 'interrupted' | 'page-budget' | 'exhausted' | 'scope-too-large';
+
+function recoveryForIncompleteReadCause(cause: IncompleteReadCause): ProviderWarningOmissionRecovery {
+	switch (cause) {
+		case 'page-budget':
+			return 'page-budget';
+		case 'scope-too-large':
+			return 'narrow-scope';
+		case 'interrupted':
+		case 'exhausted':
+			return 'none';
+		default:
+			cause satisfies never;
+			return 'none';
+	}
+}
 
 /**
  * Builds the warning for a read that returned less than everything, carrying the two facts a consumer cannot
@@ -143,7 +145,7 @@ export function incompleteReadWarning(
 		...warning,
 		omission: {
 			kind: 'pagination-incomplete',
-			recovery: cause === 'page-budget' ? 'page-budget' : 'none',
+			recovery: recoveryForIncompleteReadCause(cause),
 		},
 	};
 }
@@ -192,6 +194,10 @@ function truncationMessage(id: IntegrationIds, readKind: TruncatedReadKind, caus
 			return `${readKind} read for '${id}' stopped at its page budget; more results can be read by raising it.`;
 		case 'exhausted':
 			return `${readKind} read for '${id}' was truncated and cannot be continued; results may be incomplete.`;
+		case 'scope-too-large':
+			// Says what is true — the scope is larger than a read of it — rather than blaming the provider for a
+			// ceiling that is ours, and names the remedy that exists, since no retry or budget has one.
+			return `${readKind} read for '${id}' covers more than one read can return; narrow the scope to read the rest.`;
 	}
 	// No `default`: `IncompleteReadCause` is declared in this file, so `noImplicitReturns` already fails the
 	// build here if a cause is added without its own wording. (`collectionOmissionMessage`'s `satisfies never`
@@ -255,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,