@gitkraken/core-gitlens 0.7.1 → 0.8.0

package/dist/plus/integrations/manager.d.ts

@@ -7,9 +7,11 @@ import { ConfiguredIntegrationsChangeEvent } from "./authentication/configuredIn
 import { IssueFilter } from "./providerFilters.js";
 import { ConnectionStateChangeEvent, ProviderBroadenResult, ProviderOrganization, ProviderPagedResult, ProviderRepositoryShape, ProviderResult, ProviderSweepResult, ResolveRepositoryResult } from "./results.js";
 import { IssueCountResult, IssueCountScope, PullRequestCountResult, PullRequestCountScope } from "./reads/counts.js";
+import { CurrentAccountResult } from "./reads/currentAccount.js";
 import { SupportedFilters } from "./reads/filters.js";
 import { IssueBatchResult, IssueBatchTarget } from "./reads/issueBatch.js";
-import { TrackerIssueResult } from "./reads/trackerIssue.js";
+import { PullRequestBatchResult, PullRequestBatchTarget } from "./reads/pullRequestBatch.js";
+import { PullRequestBranchResult, PullRequestBranchTarget } from "./reads/pullRequestBranches.js";
 //#region ../plus/integrations/src/manager.d.ts
 /** Neutral repository input accepted by repo-scoped provider reads. */
 export interface ProviderRepositoryInput {
@@ -594,66 +596,120 @@ export interface IntegrationManager {
     domain?: string;
   }): Promise<ProviderResult<IssueCountResult>>;
   /**
-   * Resolves several issues BY COORDINATE — `(owner, repo, number)` — in one request.
+   * Resolves several issues BY IDENTITY in one call. Each target takes the form its provider addresses an issue
+   * by: a repository coordinate `(owner, repo, number)` on GitHub/GHE, GitLab and Azure DevOps (which also needs
+   * `project`, and ignores `repo`), or the tracker's own identifier within a resource `(resourceId, ABC-123)` on
+   * Jira and Linear. A call carrying the other form is refused whole.
    *
    * The read for "which issue does this branch name reference", which is an IDENTITY question rather than a
    * search. Emulating it by paging a scoped list and matching the identifier cannot prove absence without
    * walking the whole scope, so a miss stays unproven, uncacheable, and repeats its whole budget on every pass.
-   * This answers it in one request per chunk, and a miss is final.
+   * Here a miss is final.
    *
    * Results are echoed under the caller's own `key`, so no positional matching is needed. Per-target isolation
-   * is the rule: a chunk that fails upstream warns and drops only its own targets (with `fetchFailed` set) while
+   * is the rule: a read that fails upstream warns and drops only its own targets (with `fetchFailed` set) while
    * every other target still answers.
    *
    * `issue: undefined` means PROVEN ABSENT — the issue does not exist, or is not visible to this connection —
-   * and is safe to cache. A target whose chunk failed is NOT returned at all, so the two are distinguishable;
-   * caching a failure as an absence is exactly the bug this distinction prevents. GitHub/GHE only: a provider
-   * that cannot batch refuses outright rather than degrading into N requests behind the caller's back.
+   * and is safe to cache. A target whose read failed is NOT returned at all, so the two are distinguishable;
+   * caching a failure as an absence is exactly the bug this distinction prevents. Uncached: the caller owns
+   * caching.
+   *
+   * GitHub/GHE resolve up to 25 coordinates per request. GitLab and Azure DevOps cost one request per target, with
+   * bounded concurrency; GitLab spends a second request to confirm a miss, and Azure DevOps trusts a miss only
+   * when its own error body says the work item or project does not exist. Jira (Cloud and Data Center) and Linear
+   * cost one request per target, so a key asked of several resources is one call; `resourceId` is trusted and the
+   * read does no resource discovery, and Jira Cloud also requires `resourceUrl`. Every other provider refuses
+   * outright — Bitbucket because it has no issues, Trello because its single-issue read can fall back to a capped
+   * board scan, which cannot prove an absence.
+   *
+   * A self-managed tracker (Jira Data Center) never falls back to the primary connection, unlike the paged reads:
+   * the call is refused unless `domain` names a host or `connectionId` a configured connection that has one, and
+   * every target's `resourceId` must name the host the read resolved to. Two self-hosted instances routinely issue
+   * the same keys, and a cached absence must name the host it was proven on.
    */
   getIssuesBatch(options: {
     providerId: IntegrationIds;
     /** Each `key` must be unique — a duplicate refuses the whole call, since keys identify results. */
     targets: readonly IssueBatchTarget[];
     connectionId?: string;
-    /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+    /**
+     * Self-managed host domain; see {@link ProviderSweepTarget.domain}. A fallback for a git host, but required
+     * for a self-managed tracker unless `connectionId` names a configured host — see above.
+     */
     domain?: string;
   }): Promise<ProviderResult<IssueBatchResult>>;
   /**
-   * Resolves one issue-tracker issue by key within a resource — the tracker counterpart of
-   * {@link getIssuesBatch}, which cannot serve one.
-   *
-   * `issue: undefined` is a proven absence and may be cached. A failed read returns no item and sets
-   * `fetchFailed`. `resourceId` is required and trusted; Jira Cloud also requires the resource's site URL so the
-   * result retains its browser link. The read performs no resource discovery.
+   * Resolves several pull requests BY COORDINATE — `(owner, repo, number)`, plus `project` on Azure DevOps — in
+   * any state (open, closed or merged). The pull-request twin of {@link getIssuesBatch}, answering the same
+   * identity question: "which pull request does this branch or link name".
    *
-   * Jira (Cloud and Data Center) and Linear only. Trello refuses: its single-issue read falls back to a capped
-   * board scan for a numeric identifier, so it cannot prove absence.
+   * Results are echoed under the caller's own `key`, so no positional matching is needed. Per-target isolation
+   * is the rule: a read that fails upstream warns and drops only its own targets (with `fetchFailed` set) while
+   * every other target still answers.
    *
-   * Jira Data Center is addressed per host and, unlike the paged reads, this one never falls back to the primary
-   * connection: it requires a `domain` or a `connectionId` with a configured host and refuses otherwise, since two
-   * self-hosted instances routinely issue the same keys and a cached absence must name the host it was proven on.
+   * - `{ key, pullRequest }` — found, whatever its state.
+   * - `{ key }` with no `pullRequest` — PROVEN ABSENT: the host answered not-found for the pull request or its
+   *   repository, or it is not visible to this connection. Safe to cache.
+   * - No item for a key, with `fetchFailed` and a warning — the read could not check (auth, rate limit, network,
+   *   missing session, an unmappable response). Never treat that as absent: caching a failure as an absence is
+   *   exactly the bug this distinction prevents.
+   *
+   * UNCACHED, and deliberately not routed through the integration's cached single pull request read: that
+   * cache's key carries no connection, and the GitLens host's by-id bucket never expires a miss, so a proven
+   * absence would become permanent there — and a consumer would hold a second cache, with a different lifetime,
+   * for the same answer. The caller owns caching.
+   *
+   * Request cost: GitHub/GHE resolve up to 25 targets per request (one aliased GraphQL document). Every other
+   * host costs one request per target, run with bounded concurrency; GitLab spends a second request to confirm a
+   * miss, and Azure DevOps one more per target (two for a fork) to fill clone URLs.
    */
-  getTrackerIssue(options: {
+  getPullRequestsBatch(options: {
     providerId: IntegrationIds;
-    /**
-     * Provider resource ID for the Atlassian site or Linear workspace. For Jira Data Center it is the host, the
-     * instance's single resource as `listOrgs` reports it, and must name the host the read resolves to.
-     */
-    resourceId: string;
-    /**
-     * Jira site URL from resource discovery. Required for Jira Cloud so the result retains a browser link; Jira
-     * Data Center builds it from the connection's own base URL.
-     */
-    resourceUrl?: string;
-    /** The provider's own key, e.g. `ABC-123`. Not a number. */
-    key: string;
+    /** Each `key` must be unique — a duplicate refuses the whole call, since keys identify results. */
+    targets: readonly PullRequestBatchTarget[];
     connectionId?: string;
-    /**
-     * Self-managed tracker host; see {@link ProviderSweepTarget.domain}. Ignored for the cloud trackers. Required
-     * for Jira Data Center unless `connectionId` names a configured host — see above.
-     */
+    /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+    domain?: string;
+  }): Promise<ProviderResult<PullRequestBatchResult>>;
+  /**
+   * Finds, for each branch, every pull request whose head is that branch — in any state (open, closed or merged),
+   * most recently updated first, up to 10 per branch. "Which pull requests does this branch have", answered
+   * without the user's relationship to them, so a teammate's pull request from the user's branch is found too,
+   * which the account-wide sweeps can't do.
+   *
+   * A target names the repository the pull requests are opened AGAINST, the head branch's short name, and, for a
+   * branch in a fork, `headOwner` (the base repository's own owner, or none, means the base repository). A pull
+   * request matches only when its head repository is the right one — the base repository itself, or the fork
+   * `headOwner` owns — so a `main` in the base repository never claims every fork's `main`. The match is on the
+   * head branch NAME, so a merged pull request whose branch was since deleted is still found.
+   *
+   * Same result contract as {@link getPullRequestsBatch}, echoed under the caller's own `key`:
+   * - `{ key, pullRequests: [...] }` — found. `truncated` means more may match than were returned.
+   * - `{ key, pullRequests: [] }` with no `truncated` — PROVEN NONE: the host answered and nothing matched, or the
+   *   base repository doesn't exist or isn't visible to this connection. Safe to cache.
+   * - No item for a key, with `fetchFailed` and a warning — the read could not check. Never treat that as none.
+   *
+   * UNCACHED, and not routed through the integration's cached single pull request read for a branch (see
+   * `IntegrationCacheProvider.getPullRequestForBranch`), which answers one pull request and, on several hosts,
+   * looks the branch ref up and so answers "none" once a merged branch is deleted. The caller owns caching.
+   *
+   * Request cost: GitHub/GHE answer up to 25 targets per request (one aliased GraphQL document, fetching up to 10
+   * full pull requests per target). Every other host costs one request per target, run with bounded concurrency;
+   * GitLab and Azure DevOps then resolve each matched pull request — typically 0–1 per branch — through
+   * {@link getPullRequestsBatch}'s own read, at that read's cost, so their rows are exactly its rows. Rows carry
+   * the list reads' fields on GitHub/GHE and Bitbucket Data Center and Bitbucket Cloud's by-id read's on
+   * Bitbucket Cloud. A `headOwner` naming another owner is refused on Bitbucket Data Center and Azure DevOps,
+   * where a fork can't be found by its owner.
+   */
+  getPullRequestsForBranches(options: {
+    providerId: IntegrationIds;
+    /** Each `key` must be unique — a duplicate refuses the whole call, since keys identify results. */
+    targets: readonly PullRequestBranchTarget[];
+    connectionId?: string;
+    /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
     domain?: string;
-  }): Promise<ProviderResult<TrackerIssueResult>>;
+  }): Promise<ProviderResult<PullRequestBranchResult>>;
   /**
    * How many pull requests match each scope — the PR twin of {@link countIssues}, behind a "this will fetch ~N pull
    * requests" preview and a live count next to an unapplied filter. Same per-scope isolation, `key`-echo, and
@@ -743,6 +799,20 @@ export interface IntegrationManager {
      */
     domain?: string;
   }): Promise<ResolveRepositoryResult>;
+  /**
+   * Who the connection is signed in as on a git host. `account` is never absent without a warning. Goes through
+   * the host-supplied `IntegrationManagerCacheProvider.getCurrentAccount` cache rather than adding a second one.
+   * Issue trackers refuse: they have only a per-resource account, not a per-connection one.
+   */
+  getCurrentAccount(options: {
+    providerId: IntegrationIds;
+    connectionId?: string;
+    /**
+     * Explicit self-managed host domain. Used only when the requested connection has no configured domain;
+     * it must come from the trusted authentication configuration, not repository or remote data.
+     */
+    domain?: string;
+  }): Promise<CurrentAccountResult>;
 }
 //#endregion
 //# sourceMappingURL=manager.d.ts.map

package/dist/plus/integrations/models/gitHostIntegration.d.ts

@@ -2,17 +2,17 @@ import { PagedResult } from "../../../utils/paging.js";
 import { ResourceDescriptor } from "../../../git/models/resourceDescriptor.js";
 import { IssueOrPullRequestState } from "../../../git/models/issueOrPullRequest.js";
 import { IssueSearchCriteria, IssueShape } from "../../../git/models/issue.js";
-import { PullRequest, PullRequestFilter, PullRequestMergeMethod, PullRequestSearchCriteria, PullRequestStackInfo, PullRequestStateFilter } from "../../../git/models/pullRequest.js";
+import { PullRequest, PullRequestFilter, PullRequestMergeMethod, PullRequestSearchCriteria, PullRequestShape, PullRequestStackInfo, PullRequestStateFilter } from "../../../git/models/pullRequest.js";
 import { Account as Account$1, UnidentifiedAuthor } from "../../../git/models/author.js";
 import { DefaultBranch } from "../../../git/models/defaultBranch.js";
 import { RepositoryMetadata } from "../../../git/models/repositoryMetadata.js";
 import { PullRequestUrlIdentity } from "../../../git/utils/pullRequest.utils.js";
 import { ProviderAuthenticationSession } from "../authentication/models.js";
 import { IntegrationIds } from "../constants.js";
+import { ProviderOrganization } from "../results.js";
 import { ProviderPullRequestCount, ProviderPullRequestSearchPage } from "./pullRequestReads.js";
 import { MyIssuesForReposOptions, ProviderIssueSearchPage, ProviderSearchCount } from "./issueReads.js";
-import { IntegrationBase, IntegrationResult, IntegrationType } from "./integration.js";
-import { ProviderOrganization } from "../results.js";
+import { BatchSlot, IntegrationBase, IntegrationResult, IntegrationType } from "./integration.js";
 import { ProviderApiPagedResult, ProviderHierarchyResult, ProviderIssue, ProviderPullRequest, ProviderRepoInput, ProviderReposInput, ProviderRepository } from "../providers/models.js";
 import { CollectionMetadata } from "@gitkraken/provider-apis";
 //#region ../plus/integrations/src/models/gitHostIntegration.d.ts
@@ -392,8 +392,10 @@ export declare abstract class GitHostIntegration<ID extends IntegrationIds = Int
     criteria?: IssueSearchCriteria;
   }[], cancellation?: AbortSignal): Promise<ProviderSearchCount[] | undefined>;
   /**
-   * Result-returning wrapper for the BATCH issue read: resolves several `(owner, repo, number)` coordinates in
-   * one request. Recovers thrown errors into `{ error }` like the reads around it.
+   * Result-returning wrapper for the BATCH issue read: resolves several `(owner, repo, number)` coordinates, plus
+   * `project` on Azure DevOps, in ONE call to {@link getProviderIssuesBatch}. One settled slot per input
+   * coordinate: `fulfilled` with `undefined` means the issue does not exist or is not visible to this token;
+   * `rejected` means that target could not be checked, never that it is absent.
    *
    * Distinct from every search on this class, and deliberately so. A search answers "what matches"; this answers
    * "does this exact issue exist", which is the question a caller correlating a branch name to an issue is
@@ -402,26 +404,139 @@ export declare abstract class GitHostIntegration<ID extends IntegrationIds = Int
    * miss instead of re-walking for it forever.
    *
    * Results come back POSITIONALLY — one per input coordinate, in order — for the same reason
-   * {@link countIssuesResult} does: a caller's key must never reach the provider query. `undefined` in a slot
-   * means the issue does not exist or is not visible to this token, never that the read failed.
+   * {@link countIssuesResult} does: a caller's key must never reach the provider query.
+   *
+   * Failure isolation happens PER TARGET, mirroring {@link getPullRequestsBatchResult}: the whole call counts
+   * as a failure against the integration's request-exception budget only when EVERY slot rejected, and not even
+   * then when a credential that checks out was refused by each target's own scope (`settleBatchRefusals`).
+   * Server errors and timeouts on the targets show one notice however many hit one, and cost a strike only as
+   * part of that whole-call failure (`reportDeferredRequestFailures`), so a call never spends more than one.
    */
   getIssuesBatchResult(coordinates: readonly {
     owner: string;
     repo: string;
     number: number;
-  }[], cancellation?: AbortSignal, connectionId?: string): Promise<IntegrationResult<(IssueShape | undefined)[] | undefined>>;
+    project?: string;
+  }[], cancellation?: AbortSignal, connectionId?: string): Promise<IntegrationResult<BatchSlot<IssueShape | undefined>[] | undefined>>;
   /**
-   * OPTIONAL: only a provider that can resolve SEVERAL issues by coordinate in one request implements this.
-   * GitHub aliases its point read into one document; the SDK exposes only a singular `getIssue` for every other
-   * provider, and there is no plural variant to build on. A provider that can't answer doesn't implement it and
-   * the facade refuses the read, so a caller keeps its own per-issue path rather than being handed a batch that
-   * silently degraded into N requests.
+   * OPTIONAL: one settled slot per input coordinate, in order, in the same shape the list reads return for this
+   * provider. `fulfilled` with `undefined` is a PROVEN ABSENCE a caller may cache; `rejected` means that target
+   * could not be checked — never conflate the two, so a host implements this only where it can tell them apart.
+   *
+   * GitHub/GHE alias up to 25 coordinates into one document and so chunk internally; a chunk that throws rejects
+   * every slot in that chunk, not the ones in other chunks. GitLab and Azure DevOps read one issue per request and
+   * fan out with `mapSettledBounded`, so one target's failure rejects only its own slot. Bitbucket has no issues.
    */
   protected getProviderIssuesBatch?(session: ProviderAuthenticationSession, coordinates: readonly {
     owner: string;
     repo: string;
     number: number;
-  }[], cancellation?: AbortSignal): Promise<(IssueShape | undefined)[] | undefined>;
+    project?: string;
+  }[], cancellation?: AbortSignal): Promise<PromiseSettledResult<IssueShape | undefined>[] | undefined>;
+  /**
+   * Result-returning wrapper for the BATCH pull request read: resolves several coordinates, in any state, BY
+   * IDENTITY, in ONE call to {@link getProviderPullRequestsBatch}. One settled slot per input coordinate:
+   * `fulfilled` with `undefined` means the pull request does not exist or is not visible to this token;
+   * `rejected` means that target could not be checked, never that it is absent.
+   *
+   * Failure isolation happens PER TARGET, not per call: a hook that reads one pull request per request (every
+   * host but GitHub/GHE) fans its coordinates out itself and settles each independently, so one bad target
+   * rejects only its own slot. Mirrors {@link getMyPullRequestsForReposResult}'s per-repo fan-out — the whole
+   * call counts as a failure against the integration's request-exception budget only when EVERY slot rejected,
+   * and not even then when a credential that checks out was refused by each target's own scope
+   * (`settleBatchRefusals`). Server errors and timeouts on the targets show one notice however many hit one, and
+   * cost a strike only as part of that whole-call failure (`reportDeferredRequestFailures`).
+   */
+  getPullRequestsBatchResult(coordinates: readonly {
+    owner: string;
+    repo: string;
+    number: number;
+    project?: string;
+  }[], options?: {
+    currentAccount?: {
+      id: string;
+      username?: string;
+    };
+  }, cancellation?: AbortSignal, connectionId?: string): Promise<IntegrationResult<BatchSlot<PullRequestShape | undefined>[] | undefined>>;
+  /**
+   * OPTIONAL: resolves several coordinates, returning one settled slot per input coordinate, in order, in the
+   * same shape the list reads return for this provider. `fulfilled` with `undefined` is a PROVEN ABSENCE a
+   * caller may cache; `rejected` means that target could not be checked — never conflate the two.
+   *
+   * A provider that reads one pull request per upstream request (every host but GitHub/GHE) fans its
+   * coordinates out with `mapSettledBounded`, so one target's failure rejects only its own slot instead of
+   * taking the whole call down. GitHub/GHE alias up to 25 coordinates into one document and so chunk
+   * internally; a chunk that throws rejects every slot in that chunk, not the ones in other chunks.
+   */
+  protected getProviderPullRequestsBatch?(session: ProviderAuthenticationSession, coordinates: readonly {
+    owner: string;
+    repo: string;
+    number: number;
+    project?: string;
+  }[], options: {
+    currentAccount?: {
+      id: string;
+      username?: string;
+    };
+  } | undefined, cancellation?: AbortSignal): Promise<PromiseSettledResult<PullRequestShape | undefined>[] | undefined>;
+  /**
+   * Result-returning wrapper for the pull-requests-by-branch read: for each target, every pull request whose head
+   * is that branch, in any state, in ONE call to {@link getProviderPullRequestsForBranches}. One settled slot
+   * per target: `fulfilled` with an empty list means the host answered and nothing matched; `rejected` means
+   * that target could not be checked, never that it has no pull requests.
+   *
+   * Uncached, and deliberately not built on {@link getPullRequestForBranch}: that read caches through
+   * `IntegrationCacheProvider.getPullRequestForBranch`, answers one pull request, and on several hosts looks the
+   * branch ref up, which answers "none" once a merged pull request's branch is deleted.
+   *
+   * Failure isolation is per target, as in {@link getPullRequestsBatchResult}: the whole call counts against the
+   * request-exception budget only when EVERY slot rejected, and not when each target's own scope refused a
+   * credential that checks out. Server errors and timeouts on the targets show one notice however many hit one, and
+   * cost a strike only as part of that whole-call failure.
+   */
+  getPullRequestsForBranchesResult(targets: readonly {
+    owner: string;
+    repo: string;
+    project?: string;
+    branch: string;
+    headOwner?: string;
+  }[], options: {
+    currentAccount?: {
+      id: string;
+      username?: string;
+    };
+    limit: number;
+  }, cancellation?: AbortSignal, connectionId?: string): Promise<IntegrationResult<BatchSlot<{
+    pullRequests: PullRequestShape[];
+    truncated: boolean;
+  }>[] | undefined>>;
+  /**
+   * OPTIONAL: one settled slot per target, in order. A fulfilled slot lists the matching pull requests, newest
+   * first and at most `options.limit` of them, in the same shape the list reads return for this provider where
+   * the host allows it; `truncated` means more may match than were returned.
+   *
+   * A row matches only when its head branch is the target's `branch` AND its head repository is the base
+   * repository itself (`headOwner` omitted) or the fork `headOwner` owns — a same-named branch in some other
+   * fork is a different branch. A host that reads one target per request fans out with `mapSettledBounded`, so
+   * one target's failure rejects only its own slot; GitHub/GHE alias up to 25 targets per request, and a request
+   * that throws rejects only its own targets.
+   */
+  protected getProviderPullRequestsForBranches?(session: ProviderAuthenticationSession, targets: readonly {
+    owner: string;
+    repo: string;
+    project?: string;
+    branch: string;
+    headOwner?: string;
+  }[], options: {
+    currentAccount?: {
+      id: string;
+      username?: string;
+    };
+    limit: number;
+  }, cancellation?: AbortSignal): Promise<PromiseSettledResult<{
+    pullRequests: PullRequestShape[];
+    truncated: boolean;
+  }>[] | undefined>;
   /**
    * The PR twin of {@link countIssuesResult}: counts each scope's pull requests, transferring none where the
    * provider has a count query. Each slot is a {@link ProviderPullRequestCount}, so a provider that can only count