@gitkraken/core-gitlens 0.4.0 → 0.4.101

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

@@ -0,0 +1,473 @@
+import { mapBounded } from '../../../utils/promise.js';
+import { mergeAssessmentInto } from '../collectionMetadata.js';
+import type { IntegrationIds } from '../constants.js';
+import {
+	GitCloudHostIntegrationId,
+	GitSelfManagedHostIntegrationId,
+	providerFanOutConcurrency,
+	supportedOrderedCloudIntegrationIds,
+	supportedOrderedCloudIssuesIntegrationIds,
+} from '../constants.js';
+import type { ListOrgsOptions, ListProjectsOptions } from '../manager.js';
+import { isIssuesIntegration } from '../models/issuesIntegration.js';
+import { toProviderRepositoryShape } from '../providers/models.js';
+import type {
+	ProviderOrganization,
+	ProviderPagedResult,
+	ProviderRepositoryShape,
+	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 {
+	assertHierarchyReadTarget,
+	mergeHierarchyResults,
+	orgForProject,
+	resourceMatchesOrg,
+	resourceToOrg,
+	withProviderContext,
+} from './hierarchy.utils.js';
+import { pageToCursor, refusedPage, resolveContinuation, resolveCurrentPage, toProviderPageInfo } from './paging.js';
+import { gitHostOnlySurfaceWarning, otherWarning } from './warnings.js';
+
+export async function listOrgs(
+	ctx: ProviderReadContext,
+	options?: ListOrgsOptions,
+): Promise<ProviderResult<ProviderOrganization>> {
+	assertHierarchyReadTarget('listOrgs', options);
+	const ids = options?.providerId != null ? [options.providerId] : supportedOrderedCloudIntegrationIds;
+	const singleProvider = ids.length === 1;
+	const connectionId = singleProvider ? options?.connectionId : undefined;
+	const requestedDomain = singleProvider ? options?.domain : undefined;
+
+	const results = await mapBounded(ids, providerFanOutConcurrency, async id => {
+		const integration = await ctx.getIntegrationForRead(id, connectionId, requestedDomain);
+		if (integration == null) {
+			// A specifically requested connection that can't be resolved is a broken connection, not a
+			// provider with no orgs — surface it (warning + fetchFailed) instead of dropping the id
+			// silently, so a caller can tell it apart from an account that genuinely has no orgs.
+			const early = ctx.earlyReturnConnectionWarnings(id, connectionId, requestedDomain);
+			return {
+				items: [] as ProviderOrganization[],
+				warnings: early.warnings,
+				fetchFailed: early.fetchFailed,
+			};
+		}
+
+		const items: ProviderOrganization[] = [];
+		const warnings: ProviderWarning[] = [];
+		let fetchFailed = false;
+		const domain = ctx.domainForRead(integration, id, connectionId, requestedDomain);
+		const warnOnMissingSession = warnOnMissingSessionForDomain(id, requestedDomain);
+		if (isIssuesIntegration(integration)) {
+			// Issue trackers expose "resources" (Jira sites, Linear orgs, …) as their org analogue.
+			const { value: resources, warning } = await runCaptured(
+				id,
+				domain,
+				connectionId,
+				() => integration.getResourcesForUserResult(connectionId),
+				{ warnOnMissingSession: warnOnMissingSession },
+			);
+			if (resources != null) {
+				items.push(...resources.map(r => resourceToOrg(id, r)));
+			}
+			if (warning != null) {
+				warnings.push(warning);
+				// A warning with no value is a hard read failure, not an empty account.
+				if (resources == null) {
+					fetchFailed = true;
+				}
+			}
+		} else if (!integration.supportsOrganizationDiscovery) {
+			// The provider registers no org-discovery hook (e.g. Bitbucket Data Center). Report it as
+			// explicitly unsupported rather than contributing a silent empty list that a caller can't
+			// tell apart from "this account has no orgs".
+			fetchFailed = true;
+			warnings.push(
+				otherWarning(id, domain, connectionId, `Organization discovery is not supported by '${id}'.`),
+			);
+		} else {
+			const { value, warning } = await runCaptured(
+				id,
+				domain,
+				connectionId,
+				() => integration.getOrganizationsForUserResult(connectionId),
+				{ warnOnMissingSession: warnOnMissingSession },
+			);
+			if (value != null) {
+				items.push(...value.values.map(org => withProviderContext(id, org)));
+				if (value.truncated) {
+					warnings.push(
+						otherWarning(
+							id,
+							domain,
+							connectionId,
+							'Organization listing was truncated before the upstream results were exhausted.',
+						),
+					);
+					// `ProviderResult` has no page object on which to carry truncation. Mark the flat
+					// hierarchy result incomplete so consumers don't treat omitted orgs as authoritative.
+					fetchFailed = true;
+				}
+
+				const assessment = mergeAssessmentInto(warnings, id, domain, connectionId, value.metadata);
+				if (assessment.fetchFailed || assessment.truncated) {
+					fetchFailed = true;
+				}
+			}
+			if (warning != null) {
+				warnings.push(warning);
+				if (value == null) {
+					fetchFailed = true;
+				}
+			}
+		}
+
+		return { items: items, warnings: warnings, fetchFailed: fetchFailed };
+	});
+
+	return mergeHierarchyResults(results);
+}
+
+export async function listProjects(
+	ctx: ProviderReadContext,
+	options?: ListProjectsOptions,
+): Promise<ProviderResult<ProviderOrganization>> {
+	assertHierarchyReadTarget('listProjects', options);
+	const ids =
+		options?.providerId != null
+			? [options.providerId]
+			: [
+					...supportedOrderedCloudIssuesIntegrationIds,
+					GitCloudHostIntegrationId.AzureDevOps,
+					GitSelfManagedHostIntegrationId.AzureDevOpsServer,
+				];
+	const singleProvider = ids.length === 1;
+	const connectionId = singleProvider ? options?.connectionId : undefined;
+	const requestedDomain = singleProvider ? options?.domain : undefined;
+
+	const results = await mapBounded(ids, providerFanOutConcurrency, async id => {
+		const integration = await ctx.getIntegrationForRead(id, connectionId, requestedDomain);
+		if (integration == null) {
+			// A requested connection that can't be resolved is a broken connection, not a provider with
+			// no projects — surface it (warning + fetchFailed) instead of dropping the id silently.
+			const early = ctx.earlyReturnConnectionWarnings(id, connectionId, requestedDomain);
+			return {
+				items: [] as ProviderOrganization[],
+				warnings: early.warnings,
+				fetchFailed: early.fetchFailed,
+			};
+		}
+
+		const items: ProviderOrganization[] = [];
+		const warnings: ProviderWarning[] = [];
+		let fetchFailed = false;
+		const domain = ctx.domainForRead(integration, id, connectionId, requestedDomain);
+		const org = options?.org;
+		const warnOnMissingSession = warnOnMissingSessionForDomain(id, requestedDomain);
+
+		// Git hosts with a project tier (Azure DevOps) read projects through their own hierarchy hook,
+		// scoped to `org` when given. Non-Azure git hosts have no project tier and return undefined.
+		if (!isIssuesIntegration(integration)) {
+			// Check the capability first, like listOrgs/listRepos/listIssuesPage do. Without it, a host
+			// with no project tier returns `undefined` from a successful read, which `runCaptured` can't
+			// tell apart from an unresolvable session — turning a healthy provider into a `no-connection`
+			// warning + `fetchFailed` (and, in Kepler, a spurious reconnect prompt).
+			if (!integration.supportsProjectDiscovery) {
+				return { items: items, warnings: warnings, fetchFailed: false };
+			}
+
+			const { value: projects, warning } = await runCaptured(
+				id,
+				domain,
+				connectionId,
+				() => integration.getProjectsForOrgResult(org, connectionId),
+				{ warnOnMissingSession: warnOnMissingSession },
+			);
+			if (warning != null) {
+				warnings.push(warning);
+				if (projects == null) {
+					fetchFailed = true;
+				}
+			}
+			if (projects != null) {
+				items.push(...projects.values.map(project => withProviderContext(id, project)));
+
+				if (projects.truncated) {
+					warnings.push(
+						otherWarning(
+							id,
+							domain,
+							connectionId,
+							'Project listing was truncated before the upstream results were exhausted.',
+						),
+					);
+					// Unlike paged repository reads, this flattened hierarchy result has no continuation
+					// or page metadata. `fetchFailed` is its structural non-authoritative signal.
+					fetchFailed = true;
+				}
+
+				const assessment = mergeAssessmentInto(warnings, id, domain, connectionId, projects.metadata);
+				if (assessment.fetchFailed || assessment.truncated) {
+					fetchFailed = true;
+				}
+			}
+			return { items: items, warnings: warnings, fetchFailed: fetchFailed };
+		}
+
+		const { value: resources, warning: resourcesWarning } = await runCaptured(
+			id,
+			domain,
+			connectionId,
+			() => integration.getResourcesForUserResult(connectionId),
+			{ warnOnMissingSession: warnOnMissingSession },
+		);
+		if (resourcesWarning != null) {
+			warnings.push(resourcesWarning);
+			if (resources == null) {
+				fetchFailed = true;
+			}
+		}
+
+		const scopedResources =
+			org != null ? resources?.filter(resource => resourceMatchesOrg(resource, org)) : resources;
+		if (scopedResources != null && scopedResources.length !== 0) {
+			const { value: projects, warning: projectsWarning } = await runCaptured(id, domain, connectionId, () =>
+				integration.getProjectsForResourcesWithMetadataResult(scopedResources, connectionId),
+			);
+			if (projectsWarning != null) {
+				warnings.push(projectsWarning);
+				if (projects == null) {
+					fetchFailed = true;
+				}
+			}
+			if (projects != null) {
+				items.push(
+					...projects.values.map(project =>
+						resourceToOrg(id, project, orgForProject(id, project, scopedResources)),
+					),
+				);
+			}
+			const assessment = mergeAssessmentInto(warnings, id, domain, connectionId, projects?.metadata);
+			if (assessment.fetchFailed || assessment.truncated) {
+				fetchFailed = true;
+			}
+		}
+
+		return { items: items, warnings: warnings, fetchFailed: fetchFailed };
+	});
+
+	return mergeHierarchyResults(results);
+}
+
+export async function listRepos(
+	ctx: ProviderReadContext,
+	options: {
+		providerId: IntegrationIds;
+		org?: string;
+		project?: string;
+		page?: number;
+		cursor?: string;
+		itemsPerPage?: number;
+		connectionId?: string;
+		domain?: string;
+	},
+): Promise<ProviderPagedResult<ProviderRepositoryShape>> {
+	const page = Math.max(1, options.page ?? 1);
+	if (isIssuesHostIntegrationId(options.providerId)) {
+		return refusedPage(
+			page,
+			[gitHostOnlySurfaceWarning(options.providerId, undefined, options.connectionId, 'repository discovery')],
+			true,
+		);
+	}
+
+	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 —
+		// surface a no-connection warning + fetchFailed rather than a silent empty page.
+		const early = ctx.earlyReturnConnectionWarnings(options.providerId, options.connectionId, options.domain);
+		return refusedPage(page, early.warnings, early.fetchFailed);
+	}
+	if (!isGitHostIntegration(integration)) {
+		return refusedPage(
+			page,
+			[gitHostOnlySurfaceWarning(options.providerId, undefined, options.connectionId, 'repository discovery')],
+			true,
+		);
+	}
+
+	const domain = ctx.domainForRead(integration, options.providerId, options.connectionId, options.domain);
+
+	const accountWide = options.org == null;
+	const supported = accountWide
+		? integration.supportsUserRepositoryDiscovery
+		: integration.supportsRepositoryDiscovery;
+	if (!supported) {
+		// No matching repo-discovery hook — org-scoped (e.g. Bitbucket Data Center) or account-wide (e.g.
+		// Bitbucket/Azure, whose repos can only be walked per workspace/org). Report unsupported rather than
+		// a silent empty page indistinguishable from "no repos"; for the account-wide case the caller should
+		// fan out per org from listOrgs instead.
+		return refusedPage(
+			page,
+			[
+				otherWarning(
+					options.providerId,
+					domain,
+					options.connectionId,
+					accountWide
+						? `Account-wide repository discovery is not supported by '${options.providerId}'; list repositories per org instead.`
+						: `Repository discovery is not supported by '${options.providerId}'.`,
+				),
+			],
+			true,
+		);
+	}
+
+	const org = options.org;
+	const warnOnMissingSession = warnOnMissingSessionForDomain(options.providerId, options.domain);
+	const readPage = (cursor: string | undefined) =>
+		runCaptured(
+			options.providerId,
+			domain,
+			options.connectionId,
+			() =>
+				org == null
+					? integration.getRepositoriesForUserResult({ cursor: cursor, connectionId: options.connectionId })
+					: integration.getRepositoriesForOrgResult(org, {
+							project: options.project,
+							cursor: cursor,
+							connectionId: options.connectionId,
+						}),
+			{ warnOnMissingSession: warnOnMissingSession },
+		);
+
+	/**
+	 * Builds one page's result from what the provider returned. Shared by the initial read and by every round of
+	 * the cursor walk below, so a walked page N is described by exactly the same rules as a directly-requested one
+	 * (position, continuation, truncation) rather than by a second copy of them.
+	 */
+	const toResult = (
+		{ value, warning }: Awaited<ReturnType<typeof readPage>>,
+		requestedPage: number,
+		suppliedCursor: string | undefined,
+	): ProviderPagedResult<ProviderRepositoryShape> => {
+		const items = value?.values ?? [];
+		const warnings = warning != null ? [warning] : [];
+		// The repos read core is cursor-only and can't accept a page size, so don't echo the requested
+		// `itemsPerPage` as if it were applied — report what the provider returned (its own pageSize when
+		// available, else the actual item count).
+		const paged = toProviderPageInfo(items.length, value?.paging);
+		// Convert the SDK collection metadata into scope-aware warnings + failure/truncation flags, appending
+		// them to any captured thrown-error warning without discarding the partial result's items.
+		const assessment = mergeAssessmentInto(
+			warnings,
+			options.providerId,
+			domain,
+			options.connectionId,
+			value?.metadata,
+		);
+		// Whether this read honors a page NUMBER, decided from what the provider actually reported rather than
+		// guessed from the absence of a cursor. A numbered-page repos host reports its position (`paging.page`)
+		// and/or its successor (`paging.nextPage`) — Bitbucket's workspace walk consumes `page` as a real 1-based
+		// page and reports `nextPage` without echoing `currentPage`, so both signals have to count. Every wired
+		// cursor-based repos read (GitHub's org/user walks, GitLab's user walk, Bitbucket's cursor read) reports
+		// neither. Keying off `paged.cursor == null` instead read the paging layer's "reported another page,
+		// handed back no continuation" sentinel as evidence of a numbered host, which is exactly backwards.
+		const pageAdvanceable = value?.paging?.page != null || value?.paging?.nextPage != null;
+		// Numbered-page hosts that don't echo `currentPage` may still be advanced by the requested `page` (initial
+		// read) or by the cursor the caller threaded back. A cursor-only host ignores an UNTHREADED `page`
+		// request, so its page-less first page is page 1.
+		const currentPage = resolveCurrentPage({
+			providerPage: paged.page.currentPage,
+			requestedPage: requestedPage,
+			suppliedCursor: suppliedCursor,
+			pageAdvanceable: pageAdvanceable,
+		});
+		// Never advertise `hasMore` without a continuation the caller can act on — the same contract
+		// `listPullRequestsPage`, `listIssuesPage` and `broadenIssues` hold, via the same helper. A provider that
+		// reports another page but hands back neither `endCursor` nor `nextPage` (surfaced as the `'{}'` sentinel,
+		// which `toProviderPageInfo` drops) is terminal-but-incomplete: `hasMore: false` + `page.truncated`.
+		// Synthesizing a page-number cursor for a cursor-only host instead — which is what this read used to do
+		// unconditionally — handed back a continuation the provider ignores, so it answered with its FIRST page
+		// again while still reporting `hasMore: true`. A consumer draining until `hasMore` clears (Kepler's repo
+		// drain does exactly that) then looped to its own page cap, accumulating a duplicate copy of every repo
+		// per round, and never saw a truncation signal.
+		const continuation = resolveContinuation(paged, pageAdvanceable ? currentPage + 1 : undefined);
+		// The org-hierarchy read can also stop at a defensive backstop with more repos unlisted and no cursor to
+		// resume (top-level `truncated`, or `paging.truncated` on a single-page read). Metadata incompleteness and
+		// a demoted continuation are two further, independent sources of the same signal.
+		const truncated =
+			(value?.truncated ?? false) ||
+			(value?.paging?.truncated ?? false) ||
+			assessment.truncated ||
+			continuation.truncated;
+		return {
+			// Normalize the raw provider-apis repos to the GitLens-owned shape at the surface boundary.
+			items: items.map(toProviderRepositoryShape),
+			warnings: warnings,
+			page: { ...paged.page, currentPage: currentPage, truncated: truncated || undefined },
+			hasMore: continuation.hasMore,
+			cursor: continuation.cursor,
+			fetchFailed: assessment.fetchFailed || (warning != null && value == null) || undefined,
+		};
+	};
+
+	const first = await readPage(options.cursor ?? pageToCursor(page));
+	const result = toResult(first, page, options.cursor);
+	// A numbered-page host honored the synthesized cursor, so this IS page N; a cursor-only host ignored it and
+	// answered with page 1, which the walk below advances. Decided from the provider's own paging metadata rather
+	// than assumed, hence after the read.
+	const pageAdvanceable = first.value?.paging?.page != null || first.value?.paging?.nextPage != null;
+	if (options.cursor != null || page === 1 || pageAdvanceable) return result;
+
+	// Walk the provider's real continuations to the requested page. Only the last page's items are kept — pages
+	// 1..N returned as "page N" would duplicate items for a normal paged consumer — while warnings, truncation,
+	// and failure accumulate across the whole walked prefix, since an earlier round's problem still means this
+	// result isn't authoritative. The provider read is re-issued per round, but the integration is resolved once:
+	// re-entering this function per page would repeat its auth resolution N times for page N.
+	const walkedWarnings = [...result.warnings];
+	let walkedFetchFailed = result.fetchFailed === true;
+	let walkedTruncated = result.page.truncated === true;
+	let previous = result;
+	for (let currentPage = 2; currentPage <= page; currentPage++) {
+		if (!previous.hasMore || previous.cursor == null) {
+			// The requested page lies past the provider's terminal cursor: an EMPTY page N, never the last
+			// available page relabeled (see ProviderPageInfo.currentPage).
+			return {
+				items: [],
+				warnings: walkedWarnings,
+				page: { currentPage: page, itemsPerPage: 0, truncated: walkedTruncated || undefined },
+				hasMore: false,
+				fetchFailed: walkedFetchFailed || undefined,
+			};
+		}
+
+		const suppliedCursor = previous.cursor;
+		const requested = toResult(await readPage(suppliedCursor), currentPage, suppliedCursor);
+		for (const warning of requested.warnings) {
+			appendDedupedWarning(walkedWarnings, warning);
+		}
+		walkedFetchFailed ||= requested.fetchFailed === true;
+		walkedTruncated ||= requested.page.truncated === true;
+		if (currentPage === page) {
+			return {
+				...requested,
+				warnings: walkedWarnings,
+				page: { ...requested.page, truncated: walkedTruncated || undefined },
+				fetchFailed: walkedFetchFailed || undefined,
+			};
+		}
+
+		previous = requested;
+	}
+
+	return result;
+}

package/src/plus/integrations/reads/hierarchy.utils.ts

@@ -0,0 +1,155 @@
+import type { IssueResourceDescriptor, ResourceDescriptor } from '../../../git/models/resourceDescriptor.js';
+import { IssuesCloudHostIntegrationId } from '../constants.js';
+import type { IntegrationIds } from '../constants.js';
+import type { ProviderOrganization, ProviderResult, ProviderWarning } from '../results.js';
+import { appendDedupedWarning } from '../results.js';
+
+/**
+ * Mapping of a provider's own hierarchy vocabulary onto the single {@link ProviderOrganization} shape the facade
+ * publishes.
+ *
+ * Providers disagree about what sits above a repo or an issue: git hosts have orgs (and Azure DevOps a project
+ * tier below that), while issue trackers have "resources" (Jira sites, Linear orgs, Trello workspaces) with
+ * projects beneath them. `listOrgs`/`listProjects` unify all of it, so these helpers exist to keep the
+ * per-provider shape-guessing — which field is the id, which is the display label, which resource is a
+ * project's parent — in one place instead of inline in those reads.
+ *
+ * Everything here reads through the base {@link ResourceDescriptor} (which only guarantees `key`) and casts to
+ * the concrete {@link IssueResourceDescriptor} for the optional `id`/`name`. That cast is why the fallbacks are
+ * spelled out rather than assumed.
+ */
+
+/** The label to show for a resource: its name, else its id, else the key that is always present. */
+export function resourceLabel(resource: ResourceDescriptor): string {
+	const typed = resource as IssueResourceDescriptor;
+	return typed.name ?? typed.id ?? resource.key;
+}
+
+/** Whether `org` addresses this resource by any of the identifiers a caller could reasonably have. */
+export function resourceMatchesOrg(resource: ResourceDescriptor, org: string): boolean {
+	const typed = resource as IssueResourceDescriptor;
+	return resource.key === org || typed.id === org || typed.name === org;
+}
+
+/**
+ * The id of the RESOURCE a project belongs to, used to look up which account (and therefore which user) that
+ * project's issues should be scoped to. Falls back through the project's own identifiers because some providers
+ * (and test doubles) return project descriptors without naming their parent.
+ */
+export function resourceIdForProject(project: ResourceDescriptor): string | undefined {
+	const typed = project as IssueResourceDescriptor & { resourceId?: string };
+	return typed.resourceId ?? typed.id ?? project.key;
+}
+
+/**
+ * A stable identity for one project across facade pages, for the retry/completed bookkeeping an issue-tracker
+ * cursor carries. All three identifiers are included rather than one preferred value: two trackers can reuse the
+ * same project id, so keying on a single field would collapse them into one entry.
+ */
+export function projectKey(project: ResourceDescriptor): string {
+	const typed = project as IssueResourceDescriptor & { resourceId?: string };
+	return JSON.stringify([typed.resourceId ?? '', typed.id ?? '', project.key]);
+}
+
+/**
+ * Maps an issue-tracker resource descriptor to the unified {@link ProviderOrganization} org shape. `url` is
+ * synthesized when the descriptor carries none, rather than widening the shared `ProviderOrganization.url` to
+ * optional for the one provider family that may omit it.
+ */
+export function resourceToOrg(
+	providerId: IntegrationIds,
+	resource: ResourceDescriptor,
+	org?: string,
+): ProviderOrganization {
+	const typed = resource as IssueResourceDescriptor & { url?: string };
+	return {
+		id: typed.id ?? resource.key,
+		providerId: providerId,
+		name: resourceLabel(resource),
+		...(org != null ? { org: org } : {}),
+		url: typed.url ?? '',
+	};
+}
+
+/**
+ * The resource a project belongs under, as a display label — the `org` of the project's unified org shape.
+ *
+ * A project doesn't reliably name its parent, so try each identifier it does carry against the resources that
+ * were read alongside it. When none matches but only ONE resource was in scope, that resource is the parent by
+ * construction. Trello is excluded: its boards have no enclosing resource to name.
+ */
+export function orgForProject(
+	providerId: IntegrationIds,
+	project: ResourceDescriptor,
+	resources: ResourceDescriptor[],
+): string | undefined {
+	if (providerId === IssuesCloudHostIntegrationId.Trello) return undefined;
+
+	const typedProject = project as IssueResourceDescriptor & { resourceId?: string };
+	const parentMatch = [typedProject.resourceId, typedProject.id, project.key]
+		.filter((value): value is string => value != null)
+		.map(candidate => resources.find(resource => resourceMatchesOrg(resource, candidate)))
+		.find((resource): resource is ResourceDescriptor => resource != null);
+
+	return parentMatch != null
+		? resourceLabel(parentMatch)
+		: resources.length === 1
+			? resourceLabel(resources[0])
+			: undefined;
+}
+
+/**
+ * Stamps the provider onto an org the provider's own client produced. A git host's client fills the rest of the
+ * shape but doesn't know which integration id it was reached through — and on a self-managed host the same
+ * client serves several — so the fan-out attributes it here.
+ */
+export function withProviderContext(providerId: IntegrationIds, item: ProviderOrganization): ProviderOrganization {
+	return {
+		...item,
+		providerId: providerId,
+		...(item.org != null ? { org: item.org } : {}),
+	};
+}
+
+/**
+ * Merges the per-provider slices of a hierarchy fan-out into one flat result.
+ *
+ * `ProviderResult` has no page object, so `fetchFailed` is its only non-authoritative signal — any slice that
+ * failed or came back incomplete has to set it, or a caller would treat a short list as the whole account.
+ * Warnings are deduped because the same account can surface under two ids in one fan-out.
+ */
+export function mergeHierarchyResults<T>(
+	results: readonly ({ items: T[]; warnings: ProviderWarning[]; fetchFailed: boolean } | undefined)[],
+): ProviderResult<T> {
+	const items: T[] = [];
+	const warnings: ProviderWarning[] = [];
+	let fetchFailed = false;
+	for (const result of results) {
+		if (result == null) continue;
+
+		items.push(...result.items);
+		for (const warning of result.warnings) {
+			appendDedupedWarning(warnings, warning);
+		}
+		if (result.fetchFailed) {
+			fetchFailed = true;
+		}
+	}
+
+	return { items: items, warnings: warnings, fetchFailed: fetchFailed || undefined };
+}
+
+/**
+ * Rejects a hierarchy read whose scoped selectors have no provider to apply to. `connectionId` and `domain`
+ * both select among the connections OF a provider, so either one without `providerId` is ambiguous rather than
+ * merely redundant — the fan-out would have to guess which provider the caller meant, and silently picking one
+ * would read that connection's data under another provider's name.
+ */
+export function assertHierarchyReadTarget(
+	method: 'listOrgs' | 'listProjects',
+	options: { providerId?: IntegrationIds; connectionId?: string; domain?: string } | undefined,
+): void {
+	if (options?.providerId == null && (options?.connectionId != null || options?.domain != null)) {
+		throw new TypeError(`'${method}' requires 'providerId' when 'connectionId' or 'domain' is supplied`);
+	}
+}