@gitkraken/core-gitlens 0.7.0 → 0.7.2

package/docs/integrations.md

@@ -113,39 +113,42 @@ provider before calling the token backend; never reuse an id discovered under a
 Every read returns `ProviderResult<T>` (`items` + `warnings` + `fetchFailed?`), and every paged read extends
 it with `page` + `hasMore` + `cursor?`. **No read throws for a provider-side failure** — see §6.
 
-| Method                       | Returns                   | Scope                                                                                   |
-| ---------------------------- | ------------------------- | --------------------------------------------------------------------------------------- |
-| `listOrgs`                   | `ProviderOrganization`    | Orgs / workspaces / groups; issue-tracker resources (Jira sites, …).                    |
-| `listProjects`               | `ProviderOrganization`    | The project tier: Azure DevOps, and issue-tracker projects.                             |
-| `listRepos`                  | `ProviderRepositoryShape` | Repos of an `org`, or account-wide user-affiliated repos when `org` is omitted.         |
-| `listPullRequestsPage`       | `PullRequestShape`        | With `repos`: those repos' PRs. Without: the user's PRs account-wide.                   |
-| `searchPullRequestsPage`     | `PullRequestShape`        | PRs involving the user that match structured criteria, optionally repo/org-scoped.      |
-| `countPullRequests`          | `PullRequestCountResult`  | How many PRs match each scope, fetching none of them. See §5.1.                         |
-| `listIssuesPage`             | `IssueShape`              | Same split, for a **git host**'s issues.                                                |
-| `searchIssuesPage`           | `IssueShape`              | Issues matching structured criteria over a repo/org scope — **no** `@me` binding.       |
-| `countIssues`                | `IssueCountResult`        | How many match each scope, fetching none of them. See §5.1.                             |
-| `getIssuesBatch`             | `IssueBatchResult`        | Resolves N `(owner, repo, number)` coordinates in one request; an absence is proven.    |
-| `getTrackerIssue`            | `TrackerIssueResult`      | Resolves ONE tracker issue by key within a resource; an absence is proven. Jira/Linear. |
-| `listIssueTrackerIssuesPage` | `IssueShape`              | Jira (Cloud + Data Center) / Linear / Trello (issues live under resource → project).    |
-| `sweepPullRequests`          | `ProviderSweepResult`     | Drains **every** page across providers (`maxPages`, default 100).                       |
-| `sweepClosedPullRequests`    | `ProviderSweepResult`     | Same, pinned to `['closed','merged']`.                                                  |
-| `broadenIssues`              | `ProviderBroadenResult`   | Per-org fan-out for every visible issue, unfiltered by assignee.                        |
-| `resolveRepository`          | `ResolveRepositoryResult` | Remote URL → canonical provider identity (the `gk repo resolve` equivalent).            |
-| `getSupportedFilters`        | filter capability table   | Static, connection-free. See §7.                                                        |
+| Method                       | Returns                   | Scope                                                                                                           |
+| ---------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `listOrgs`                   | `ProviderOrganization`    | Orgs / workspaces / groups / Bitbucket DC projects; issue-tracker resources (Jira sites, …).                    |
+| `listProjects`               | `ProviderOrganization`    | The project tier: Azure DevOps, and issue-tracker projects.                                                     |
+| `listRepos`                  | `ProviderRepositoryShape` | Repos of an `org`, or account-wide user-affiliated repos when `org` is omitted.                                 |
+| `listPullRequestsPage`       | `PullRequestShape`        | With `repos`: those repos' PRs. Without: the user's PRs account-wide.                                           |
+| `searchPullRequestsPage`     | `PullRequestShape`        | PRs involving the user that match structured criteria, optionally repo/org-scoped.                              |
+| `countPullRequests`          | `PullRequestCountResult`  | How many PRs match each scope, fetching none where the provider can count. See §5.1.                            |
+| `listIssuesPage`             | `IssueShape`              | Same split, for a **git host**'s issues.                                                                        |
+| `searchIssuesPage`           | `IssueShape`              | Issues matching structured criteria over a repo/org scope — **no** `@me` binding.                               |
+| `countIssues`                | `IssueCountResult`        | How many match each scope, fetching none of them. See §5.1.                                                     |
+| `getIssuesBatch`             | `IssueBatchResult`        | Resolves N `(owner, repo, number)` coordinates in one request; an absence is proven.                            |
+| `getTrackerIssue`            | `TrackerIssueResult`      | Resolves ONE tracker issue by key within a resource; an absence is proven. Jira (Cloud + Data Center) / Linear. |
+| `listIssueTrackerIssuesPage` | `IssueShape`              | Jira (Cloud + Data Center) / Linear / Trello (issues live under resource → project).                            |
+| `sweepPullRequests`          | `ProviderSweepResult`     | Drains **every** page across providers (`maxPages`, default 100).                                               |
+| `sweepClosedPullRequests`    | `ProviderSweepResult`     | Same, pinned to `['closed','merged']`.                                                                          |
+| `broadenIssues`              | `ProviderBroadenResult`   | Per-org fan-out for every visible issue, unfiltered by assignee.                                                |
+| `resolveRepository`          | `ResolveRepositoryResult` | Remote URL → canonical provider identity (the `gk repo resolve` equivalent).                                    |
+| `getSupportedFilters`        | filter capability table   | Static, connection-free. See §7.                                                                                |
 
 A provider that cannot serve a surface says so explicitly — a warning explaining that the operation is
 unsupported plus `fetchFailed`, never a silent empty page. That distinction is the whole point of the result
 shape: an empty `items` with no warning means "this account genuinely has nothing".
 
-`getTrackerIssue` takes `resourceId` for both supported trackers. Jira Cloud also takes `resourceUrl`, the site URL
+`getTrackerIssue` takes `resourceId` for every supported tracker. Jira Cloud also takes `resourceUrl`, the site URL
 returned by `listOrgs`; the REST response only supplies an API `self` link, so the caller provides the already-known
-site identity rather than making this point read perform resource discovery. Linear does not need it.
+site identity rather than making this point read perform resource discovery. Linear does not need it, and neither
+does Jira Data Center, whose browser link is built from the connection's own base URL.
 
-`getTrackerIssue` does **not** serve Jira Data Center. That read takes no `domain`, so for a host-keyed tracker it
-would answer from whichever connection is primary — a different instance's issue under the right key, since two
-self-hosted instances routinely share project and issue keys. It is refused explicitly (warning + `fetchFailed`)
-rather than answered wrongly. Use `listIssueTrackerIssuesPage` with a `domain`, or read the issue through the
-integration for that host.
+For Jira Data Center `resourceId` is the host — the instance's single resource, as `listOrgs` reports it — and the
+read takes the `domain` its siblings take to select the instance. Unlike them it never falls back to the primary
+connection: a self-managed tracker requires a `domain` or a `connectionId` with a configured host, and is refused
+(warning + `fetchFailed`) otherwise. Two self-hosted instances routinely share project and issue keys, and this
+read's `issue: undefined` is a proven absence a caller may cache, so an answer from whichever host happens to be
+primary would be cached under a key that names a different instance. For the same reason a `resourceId` that names
+a different host than the one the read resolves to is refused rather than read.
 
 ## 5. Paging
 
@@ -214,9 +217,11 @@ Omit `relationships` to search every PR in the supplied repo/org scope; without
 relationship is mandatory. This is deliberately not `involves:@me`: that GitHub shortcut excludes
 `review-requested` but includes `commenter`, so it cannot match the adjacent visible-PR list.
 
-The provider always orders this read most-recently-updated-first. A threaded `cursor` is exactly one upstream
-request; GitHub puts every active relationship × state facet into aliases in that one GraphQL document. A page
-number without a cursor walks from page 1. At GitHub's 1,000-result-per-facet ceiling, `page.truncated` is true and
+The read is ordered by `criteria.sort`, most-recently-updated-first when omitted; the keys a provider accepts are
+`getSupportedFilters().pullRequestSearch.sorts`. On GitHub/GHE a threaded `cursor` is exactly one upstream request,
+since every active relationship × state facet travels as an alias in one GraphQL document; Bitbucket Data Center
+has no such batching and spends one request per repository × relationship facet still being read. A page number
+without a cursor walks from page 1. At GitHub's 1,000-result-per-facet ceiling, `page.truncated` is true and
 the warning's `omission` carries `totalCount`, `limit`, and `recovery: 'none'`. `totalCount` is the largest
 provider-reported pre-ceiling facet count, matching the per-search ceiling's unit; it is not the returned or
 still-reachable row count. Free text is sanitized so qualifier-shaped tokens such as `org:other` are removed
@@ -328,11 +333,23 @@ const counts = await manager.countPullRequests({
 });
 ```
 
-The one difference is inherent to pull requests: a scope's `states` (open/closed/merged) are counted as
-independent searches, so the reported `count` is the **largest** of them — the same total
+The one difference is inherent to pull requests: on GitHub/GHE a scope's `states` (open/closed/merged) are
+counted as independent searches, so the reported `count` is the **largest** of them — the same total
 `searchPullRequestsPage` surfaces — not their sum. Because the result ceiling applies per search, that max is
 what `exceedsProviderLimit` compares against. Several states in one scope are therefore fine (they are
-disjoint); only several relationships are refused.
+disjoint); only several relationships are refused, except on Bitbucket Data Center (below). Azure DevOps Server
+reads every state in one drain, so its count is their union (the sum, since states are disjoint), again the total
+its search pages through.
+
+Bitbucket Data Center has no count query, no total on its pages and no result ceiling, so it counts by reading
+each facet's first page of up to 1,000 pull requests through the same predicates the search applies. Its `count`
+is therefore the exact **union** of the requested states — the number of rows the search returns — and when a
+facet has more than one page it comes back with `lowerBound: true`: a floor, to be shown as "N+" and treated as
+at least that expensive. Absent `lowerBound` means the count is exact, though computed from the rows read rather
+than reported by the server. Because it reads the
+rows, it also counts several relationships in one scope as their exact union, the same OR the search applies, so
+the one-relationship-per-scope refusal does not apply there. Each scope is its own set of requests, so a Bitbucket
+Data Center count is not free the way a GitHub one is; debounce and cache it.
 
 ## 6. Failures: warnings, `fetchFailed`, `truncated`
 
@@ -344,7 +361,7 @@ prove from structured errors:
 
 | `kind`          | Meaning                                                                                                                                         | Reasonable response                                                                         |
 | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `auth`          | Token rejected (401/403 that isn't a throttle).                                                                                                 | Prompt to reconnect that connection.                                                        |
+| `auth`          | Token rejected (401/403 that isn't a throttle).                                                                                                 | Prompt to reconnect that connection. A scoped one is narrower: see `scope` below.           |
 | `rate-limit`    | Throttled (429, or a 403 whose body says so).                                                                                                   | Back off and retry; keep the last snapshot.                                                 |
 | `not-found`     | 404/410/422 on the requested scope.                                                                                                             | Drop that scope; don't reconnect.                                                           |
 | `no-connection` | The requested `connectionId`/`domain` doesn't resolve.                                                                                          | Re-resolve the target or re-authenticate.                                                   |
@@ -356,6 +373,92 @@ Conversely, `other` is intentionally not a complete failure taxonomy. Treat `mes
 text rather than a stable protocol; use `fetchFailed`, `page.truncated`, and `page.allPages` for completeness
 and keep unknown failures conservative.
 
+### `scope` — which part of the read failed
+
+A fan-out read records a failure against the organization, project or repository it happened in.
+`ProviderWarning.scope` forwards that attribution (`resourceId`, `projectId`, `repositoryId`, whichever the
+provider reported), so a consumer can tell "one organization refused this token" from "the connection's token
+is dead" without parsing `message`:
+
+```ts
+if (warning.kind === 'auth' && warning.scope == null) {
+	promptToReconnect(warning.providerId, warning.connectionId);
+} else if (warning.kind === 'auth') {
+	// One organization/project/repository refused the credential, e.g. an Azure DevOps organization with
+	// third-party OAuth access disabled, one in another Entra tenant, or a Conditional Access policy.
+	// Reconnecting cannot fix that, so mark only that scope unavailable and keep the others.
+	markScopeUnavailable(warning.providerId, warning.connectionId, warning.scope);
+}
+```
+
+`kind` and `isAuth` do not change with it: a scoped 401 is still an authentication failure, and `scope` says
+how far it reaches. **Its absence means account-wide or unattributed**, so a consumer that ignores the field
+keeps its existing behavior. It is set only on warnings derived from a structured scope failure, and names at
+least one ID when present; a failure attributed to nothing below the provider carries none. A warning built
+from a caught exception never carries one, even when that call targeted a single organization, and an omission
+keeps its attribution in `omission.scope` instead.
+
+A scoped `auth` failure also means **the credential itself was accepted**. A dead token can come back as
+nothing but scoped refusals wherever a read reaches its scopes without an uncached request to the connection
+first: discovery served from a per-token cache (Azure DevOps, Bitbucket and Jira Cloud cache the account, its
+organizations, workspaces or sites, and their projects), or an SDK fan-out across the requested repositories
+(Bitbucket Data Center). So when a read's only auth failures are scoped, those providers confirm the credential
+with one uncached check before reporting them. A refused credential fails the whole read instead: an
+unscoped `auth` warning, `fetchFailed`, no results served from the cache, and the usual connection recovery.
+A refusal the provider pins on the credential itself, like Bitbucket's or Jira Cloud's for a token missing the
+OAuth scopes the read needs, is published unscoped too, once for the connection, because a reconnect
+(consenting to them again) is what fixes it; the scopes that answered keep their results.
+
+The promise holds for a read that carries no unscoped `auth` warning of its own: one that does already asks for a
+reconnect, and its other scoped refusals are not checked. Two cases stay scoped even then. A check that could not
+complete or was denied (a network error, a throttle, a `403`, Bitbucket Data Center refusing a credential it
+authenticated, or a Bitbucket Data Center project access token, whose user the check cannot find) proves nothing,
+so the warnings are published unconfirmed and carry no `cause`, and the next read checks again: a credential the
+check can never confirm, like a project access token, costs one check on every read that has scoped refusals. And a
+credential confirmed within the last minute is not checked again, so a scope that keeps refusing it costs at most
+one extra check a minute, and a revocation can take up to a minute to surface as a connection failure.
+
+`scope.resourceId` is the resource as the read addressed it: its id on most reads, its name on the few that
+address it by name (Azure DevOps' repo-scoped reads, Bitbucket's workspace reads). Match it against both
+`ProviderOrganization.id` and `name`.
+
+Warnings also dedup on `scope` and `cause`, so failures of two scopes stay two warnings.
+
+### `cause` — why a sound credential was refused
+
+A scoped `auth` warning can also say **why** the scope refused, so a consumer recommends the fix instead of a
+reconnect. `ProviderWarning.cause` carries a closed `reason` to switch on (also exported as
+`ProviderWarningCauseReason`), the provider's own `code` when it reports one, and a `remedyUrl` when this layer
+can address the setting behind the refusal. `message` says the same in prose.
+
+```ts
+switch (warning.cause?.reason) {
+	case 'oauth-app-not-allowed':
+		// An admin enables the org's third-party OAuth policy at `remedyUrl`, or the user connects with a PAT.
+		suggestAllowingOAuthApps(warning.scope, warning.cause.remedyUrl);
+		break;
+	case 'access-denied':
+		suggestRequestingAccess(warning.scope);
+		break;
+	case 'conditional-access':
+		suggestAskingTheTenantAdmin(warning.scope);
+		break;
+}
+```
+
+| `cause.reason`          | Means                                                                                    | Fixed by                                                                                                                                                                      |
+| ----------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `oauth-app-not-allowed` | The organization does not let third-party OAuth apps in.                                 | An organization admin enabling **Third-party application access via OAuth** (Azure DevOps; off by default for new organizations), or a PAT, which the policy does not govern. |
+| `access-denied`         | The account has no access to that organization or project (not a member, no permission). | Someone who administers it granting access.                                                                                                                                   |
+| `conditional-access`    | A Microsoft Entra Conditional Access policy blocked the request (`VS403463`).            | The tenant admin exempting the request.                                                                                                                                       |
+
+It is set **only on a scoped `auth` warning whose credential was confirmed** (see `scope` above), because until
+then these refusals look exactly like a dead credential: Azure DevOps answers a third-party OAuth app its
+organization disallows with the same bare `401` it gives an expired token. Only Azure DevOps names causes today,
+from answers captured against the live service. **Its absence proves nothing**: a refusal this layer cannot name
+still carries the provider's own explanation, when it gave one, in `message`, e.g. an organization that only
+allowlists global personal access tokens.
+
 ### `omission` — succeeded, but withheld results
 
 `other` covers two facts with **opposite remedies**: a request that failed, and a request that succeeded while
@@ -539,7 +642,7 @@ read, and GitHub's carries `latestReviews` natively; account-wide (no `repos`) i
 no option opts it back in. `commitOid` is absent from both: only the full projection populates it.
 
 The paginated read that does carry the full projection is `searchPullRequestsPage` with
-`criteria.relationships` (GitHub/GHE, which is also the only family that exposes a filtered PR search at all):
+`criteria.relationships` on GitHub/GHE (Bitbucket Data Center also exposes the search, with its native row shape):
 its results always include the review projection with `commitOid`, it honors `itemsPerPage`, and one threaded
 cursor page is exactly one upstream request — every relationship × state facet travels in the same query,
 unlike the account-wide read, which spends one request per facet per page. So a surface that pages
@@ -551,31 +654,40 @@ reach for `includeReviews`, which only exists on the all-at-once sweep.
 Derived from the provider models and `providersMetadata`. ✓ supported · ✗ reported unsupported
 (warning + `fetchFailed`) · — not applicable. Self-managed variants inherit their cloud family's hooks.
 
-| Surface                      | GitHub / GHE | GitLab / self-hosted | Bitbucket | Bitbucket DC | Azure DevOps (+ Server) |  Jira (+ DC)   | Linear | Trello |
-| ---------------------------- | :----------: | :------------------: | :-------: | :----------: | :---------------------: | :------------: | :----: | :----: |
-| `listOrgs`                   |      ✓       |          ✓           |     ✓     |      ✗       |            ✓            |       ✓        |   ✓    |   ✓    |
-| `listProjects`               |      —       |          —           |     —     |      —       |            ✓            |       ✓        |   ✓    |   ✓    |
-| `listRepos` (`org`)          |      ✓       |          ✓           |     ✓     |      ✗       |            ✓            |       ✗        |   ✗    |   ✗    |
-| `listRepos` (account-wide)   |      ✓       |          ✓           |     ✗     |      ✗       |            ✗            |       ✗        |   ✗    |   ✗    |
-| PRs, repo-scoped             |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |       ✗        |   ✗    |   ✗    |
-| PRs, account-wide            |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |       ✗        |   ✗    |   ✗    |
-| PR `states` account-wide     |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |       —        |   —    |   —    |
-| `searchPullRequestsPage`     |      ✓       |          ✗           |     ✗     |      ✗       |            ✗            |       ✗        |   ✗    |   ✗    |
-| `countPullRequests`          |      ✓       |          ✗           |     ✗     |      ✗       |            ✗            |       ✗        |   ✗    |   ✗    |
-| Issues, repo-scoped          |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |       —        |   —    |   —    |
-| Issues, account-wide         |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |       —        |   —    |   —    |
-| `searchIssuesPage`           |      ✓       |          ✓           |     ✗     |      ✗       |            ✗            |       ✗        |   ✗    |   ✗    |
-| `countIssues`                |      ✓       |          ✓           |     ✗     |      ✗       |            ✗            |       ✗        |   ✗    |   ✗    |
-| `getIssuesBatch`             |      ✓       |          ✓           |     ✗     |      ✗       |            ✗            |       ✗        |   ✗    |   ✗    |
-| `getTrackerIssue`            |      ✗       |          ✗           |     ✗     |      ✗       |            ✗            | ✓ (Cloud only) |   ✓    |   ✗    |
-| Issues by `org`/`project`    |      ✗       |          ✗           |     ✗     |      ✗       |            ✓            |       ✓        |   ✓    |   ✓    |
-| `listIssueTrackerIssuesPage` |      —       |          —           |     —     |      —       |            —            |       ✓        |   ✓    |   ✓    |
-| `broadenIssues`              |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |       ✗        |   ✗    |   ✗    |
-| `resolveRepository`          |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |       ✗        |   ✗    |   ✗    |
-
-Jira Data Center inherits Jira Cloud's row everywhere except `getTrackerIssue`, which it reports unsupported (see
-§4). Its reads are addressed per host, so `domain` selects the instance and every read below is scoped to that one
-connection; a read that omits it gets the primary configured host. `listOrgs` returns exactly one resource — the
+| Surface                      | GitHub / GHE | GitLab / self-hosted | Bitbucket | Bitbucket DC | Azure DevOps (+ Server) | Jira (+ DC) | Linear | Trello |
+| ---------------------------- | :----------: | :------------------: | :-------: | :----------: | :---------------------: | :---------: | :----: | :----: |
+| `listOrgs`                   |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |      ✓      |   ✓    |   ✓    |
+| `listProjects`               |      —       |          —           |     —     |      —       |            ✓            |      ✓      |   ✓    |   ✓    |
+| `listRepos` (`org`)          |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |      ✗      |   ✗    |   ✗    |
+| `listRepos` (account-wide)   |      ✓       |          ✓           |     ✗     |      ✓       |            ✗            |      ✗      |   ✗    |   ✗    |
+| PRs, repo-scoped             |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |      ✗      |   ✗    |   ✗    |
+| PRs, account-wide            |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |      ✗      |   ✗    |   ✗    |
+| PR `states` account-wide     |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |      —      |   —    |   —    |
+| `searchPullRequestsPage`     |      ✓       |          ✗           |     ✗     |      ✓       |            ✗            |      ✗      |   ✗    |   ✗    |
+| `countPullRequests`          |      ✓       |          ✗           |     ✗     |      ✓       |            ✗            |      ✗      |   ✗    |   ✗    |
+| Issues, repo-scoped          |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |      —      |   —    |   —    |
+| Issues, account-wide         |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |      —      |   —    |   —    |
+| `searchIssuesPage`           |      ✓       |          ✓           |     ✗     |      ✗       |            ✗            |      ✗      |   ✗    |   ✗    |
+| `countIssues`                |      ✓       |          ✓           |     ✗     |      ✗       |            ✗            |      ✗      |   ✗    |   ✗    |
+| `getIssuesBatch`             |      ✓       |          ✓           |     ✗     |      ✗       |            ✗            |      ✗      |   ✗    |   ✗    |
+| `getTrackerIssue`            |      ✗       |          ✗           |     ✗     |      ✗       |            ✗            |      ✓      |   ✓    |   ✗    |
+| Issues by `org`/`project`    |      ✗       |          ✗           |     ✗     |      ✗       |            ✓            |      ✓      |   ✓    |   ✓    |
+| `listIssueTrackerIssuesPage` |      —       |          —           |     —     |      —       |            —            |      ✓      |   ✓    |   ✓    |
+| `broadenIssues`              |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |      ✗      |   ✗    |   ✗    |
+| `resolveRepository`          |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |      ✗      |   ✗    |   ✗    |
+
+Bitbucket Data Center exposes its projects through `listOrgs`: both `id` and `name` are the project key.
+Pass that key as `org` to `listRepos` to select a project, or omit `org` to enumerate all accessible repositories,
+including personal repositories. It has no additional project tier, so `listProjects` is not applicable.
+Project discovery drains up to 20 pages and reports `fetchFailed` with warnings if incomplete. Repository
+discovery returns one page with an opaque continuation cursor; reuse it with the same connection and `org`.
+Both reads deduplicate results across pages and retain the configured installation URL, including its context path.
+A link the server returns is kept only when it names that entry on the configured installation; otherwise the web and
+HTTPS links are rebuilt from the configured URL and an SSH link, whose host and port cannot be derived, is omitted.
+
+Jira Data Center inherits Jira Cloud's row. Its reads are addressed per host, so `domain` selects the instance and
+every read below is scoped to that one connection; a paged read that omits it gets the primary configured host,
+while `getTrackerIssue` refuses instead (see §4). `listOrgs` returns exactly one resource — the
 instance itself, synthesized from the configured host rather than fetched — and its projects carry the display name
 as `key`, because `/rest/api/2/project` reports no project key; reads address the project by id regardless. No
 autolinks are registered for the same reason: an autolink prefix has to be the project key.
@@ -590,8 +702,16 @@ exposes a reviewed-by axis on the repo-scoped read, so it is absent from the rep
 PR **search** capabilities (`getSupportedFilters().pullRequestSearch`): GitHub/GHE express relationships
 `Author, Assignee, ReviewRequested, Reviewed, Mention`, states `open, closed, merged, all`, `text`, `updatedAfter`,
 `createdAfter`, `includeArchived`, `draft`, repository/organization scopes, and sorts
-`updated:desc|asc, created:desc|asc`. Every other provider declares empty lists and false flags, so the read is
-refused rather than returning a page that did not apply a requested criterion or scope. `updatedAfter` /
+`updated:desc|asc, created:desc|asc`. Bitbucket Data Center expresses relationships `Author, ReviewRequested,
+Reviewed`, states `open, closed, merged, all`, `text` (title or description), `includeArchived`, `draft`, the
+repository scope, and sorts `updated:desc|asc` — no assignee or mention (its pull requests have neither), no date
+filters, no `created` order, and no organization scope, since it has no project-wide pull-request list. Azure DevOps
+Server expresses relationships `Author, Assignee, ReviewRequested` (the last two both read Azure's reviewers, since
+it has no separate assignee), the same four states, `text` (title or description), `updatedAfter`, `createdAfter`,
+`draft`, repository/organization scopes and `updated:desc|asc, created:desc|asc`; not `Reviewed`, `Mention` or
+`includeArchived`. Every other provider — including Azure DevOps Services — declares empty lists and false flags,
+so the read is refused rather than returning a page that did not
+apply a requested criterion or scope. `updatedAfter` /
 `createdAfter` are ISO `YYYY-MM-DD` and are the most effective narrowing on a large scope — the way to bound a broad
 closed-PR read, rather than capping page iterations. `draft` is tri-state: `true` returns only drafts, `false` only
 ready-for-review PRs, and omitting it places no constraint — so a consumer sending `draft: false` must not treat it
@@ -604,11 +724,13 @@ Account-wide issue filters: GitHub/GHE `Author, Assignee, Mention` · Azure `Aut
 `Assignee, Author` · everything else none.
 Issue **search** criteria (`getSupportedFilters().issueSearch`): GitHub/GHE express all of them —
 relationships `authored, assigned, mentioned, any-assignee, unassigned`, plus `text`, `labels`, `milestone`,
-`updatedAfter`, `createdAfter`, `withoutLinkedPullRequest`, `state` — and every other provider declares none,
-so the read is refused there rather than serving a list that was never narrowed. GitLab and Azure could
-express most of it (GitLab: `search`, `updated_after`, `labels`, `milestone`, one relationship per REST call;
-Azure: WIQL per project), so the gap is unimplemented rather than impossible; `withoutLinkedPullRequest` and
-free text have no equivalent on either.
+`updatedAfter`, `createdAfter`, `withoutLinkedPullRequest`, `state`. Azure DevOps Server expresses relationships
+`authored, assigned, any-assignee, unassigned`, `text` (a title substring), `labels` (whole tags), `updatedAfter`,
+`createdAfter` and `state`, and sorts `updated`, `created`, `closed`, `comments` and `title` in both directions —
+not `mentioned` (`@RecentMentions` only reaches back 30 days), `milestone` or `withoutLinkedPullRequest`, and not
+`priority`/`resolved`, whose process-template fields an on-premises collection may not define. Every other provider
+declares none, so the read is refused there rather than serving a list that was never narrowed. GitLab and Azure
+DevOps Services could express most of it, so the gap is unimplemented rather than impossible.
 
 > `supportedCloudIntegrationDescriptors.supports` (in `constants.ts`) describes what GitLens _advertises in
 > its connect UI_, including enrichment-only capabilities. It is **not** the read-capability answer — use
@@ -699,14 +821,71 @@ Markdown by this package.
   repo walk (list per workspace). The account-wide PR read drains every workspace and returns **one
   aggregate page** (no cross-workspace cursor), so `itemsPerPage` doesn't apply. The review-requested slice
   is opt-in via `includeReviewRequested: true`, because it costs an O(workspaces × repos) fan-out.
-- **Bitbucket Data Center** — no org discovery, no repo discovery, no issues. `provider-apis` converts the
-  public 1-based page number to the REST `start` offset and normalizes `nextPageStart` back to a page number;
-  the facade carries that number inside its opaque cursor.
+- **Bitbucket Data Center** — projects are the org tier; repositories can be listed by project or account-wide.
+  Discovery follows exact `nextPageStart` offsets, with cursors bound to the connection and scope. It has no
+  issues. Pull-request reads use the SDK's 1-based page numbers, carried inside their own opaque cursors.
+  The filtered PR search reads each requested repository × relationship as its own request (a relationship
+  without repositories reads the user's dashboard; `Reviewed` there is two requests, the reviewer and the
+  participant lists, because the dashboard only filters by review status together with a role), follows each
+  facet's own `nextPageStart`, and binds its
+  cursor to the connection, the configured installation URL and the query. Every criterion is re-checked on the
+  rows returned, so a server that ignores one (`draft` before 8.18) narrows instead of widening. A repository that
+  fails becomes a scoped warning with `fetchFailed` while the others still answer, and is retried once, at the
+  page it missed, on the next page; if the retry fails too it is dropped and reported on every later page, so one
+  that never answers can't hold `hasMore` open. A 401, or a 403 on the dashboard, is the credential and fails the
+  read; a 403 on one repository is that repository refusing the token, reported for it alone. Several states
+  (and `closed`, which is `DECLINED` plus `SUPERSEDED`) are read as every state and filtered, rather than costing
+  a request each.
 - **Azure DevOps** — org + project scoped. Repo-scoped reads accept one org per call. Account-wide reads
   drain every project of every org and return one aggregate page; a failed project becomes a scoped warning
   while its siblings survive. Only Azure can narrow an account-wide issue read by `org`/`project`.
   `resolveRepository` needs a project in the remote URL. Azure DevOps Server uses the trusted connection's
-  domain/protocol as `baseUrl`; the remote host must match that configured connection.
+  `baseUrl`, including its installation path. A repository's virtual directory must match that path and is
+  applied once; a connection addressed at the host root takes the repository's own virtual directory. An address
+  that also names a collection (`https://server/tfs/DefaultCollection`) reads that collection without repeating it:
+  discovery reports it as the one collection visible there, since Azure only lists collections at the server level,
+  and another collection's repositories need an address without the collection. Installation paths match case-insensitively, as IIS serves them. An SSH remote
+  that names no virtual directory is read against the whole address, since it can't tell a virtual directory from
+  another collection named there.
+
+  Azure DevOps Server also has the filtered searches and their counts, with the collection applied exactly once
+  whichever way the address is written. Scope names are encoded as URL segments (collections, projects,
+  repositories) or escaped as WIQL string literals (a repository's project in the work-item query), never spliced
+  into a qualifier syntax, so names with spaces or quotes are accepted there.
+  - **Work items** (`searchIssuesPage` / `countIssues`) run ONE WIQL query per page over ONE collection, with every
+    relationship OR-ed in it, so an item matching two relationships is one row and the count is the exact size of
+    the same match set. `org` names the collection; without it the repositories' collection is used, and without
+    either the only collection the account can see. A search across several collections is refused (pass `org`),
+    as is one whose repositories name a project the collection doesn't have. Repositories bound the query by
+    their project, since work items belong to projects. The page reads the first 20,000 matches (Azure's documented
+    query result limit), bounded with `$top`; past that it is `truncated` with a `provider-limit` omission carrying
+    `limit` and `sort` but no `totalCount`, and the count reports `exceedsProviderLimit: true` with no `count` rather
+    than the limit. Verified against Azure DevOps Server 2020 with 20,014 matches. A server that refuses the match set
+    even with `$top` (`VS402337`) fails the page (warning + `fetchFailed`, "narrow the search"), since no bounded query
+    could serve that order's first window; its count still reports `exceedsProviderLimit`.
+    A pagination pages through the ids its first page queried, kept while it keeps reading (5 minutes after the last
+    page, 30 at most, among the 50 most recently read paginations); every first page queries its own, so a pagination of the same query started later never
+    replaces it. A continuation whose snapshot is gone is refused (warning + `fetchFailed`) rather than resumed
+    against a fresh query, where an item moved by the `updated` order could be skipped. Restart without the cursor.
+    A cursor is bound to its query and refused under another one. `page` without a cursor walks from page 1 against
+    a fresh query. Requests use REST `api-version=5.0`, so Azure DevOps Server 2019 or later is required.
+  - **Pull requests** (`searchPullRequestsPage` / `countPullRequests`) drain every facet — each repository, or each
+    project of the `org` (every visible project when only relationships bound the search), times each
+    relationship — reading up to 1,000 pull requests per facet, then apply text, draft and dates, union by repository
+    identity (so pull request #1 in two projects stays two rows) and order the result. A pagination pages through
+    the drain its own first page read while it keeps reading (5 minutes after the last page, 30 at most, among the 50
+    most recently read paginations), from a
+    keyset cursor; a later first page of the same query drains anew without replacing it. A continuation whose drain
+    is gone, or handed to another connection, is refused like an expired work-item snapshot, since a re-drain could
+    move a pull request whose close date changed past the position already served. The count reuses the drain a
+    first page of the same query read within the last minute, and drains afresh otherwise, so a polled count stays
+    live. A facet that exceeds the drain bound makes the result `truncated` with no total, and its count `undefined`.
+    Dates that aren't `YYYY-MM-DD` are refused before anything is read, and in a count only for their own scope. A facet whose
+    read fails fails the whole search rather than serving a union with a hole in its order. Text matches the title
+    or the first 400 characters of the description (all a pull request list returns), and `updatedAfter` compares
+    Azure's close date (or creation date while open), since Azure reports no last-activity date. `itemsPerPage`
+    is per page here, not per facet. A repository name of `.` or `..` is refused rather than resolved as a path.
+
 - **Jira (Cloud + Data Center) / Linear / Trello** — paged by **project**, not by issue: `itemsPerPage` counts projects (default
   20), each drained in full. Passing none of `page`/`cursor`/`itemsPerPage` aggregates every matched project
   in one page. A single project exceeding its internal drain backstop shows up as `page.truncated`.
@@ -718,11 +897,21 @@ Markdown by this package.
   recovered. `hasMore` reports only untouched forward progress. A cursor can therefore remain with
   `hasMore: false`; reusing it is an explicit manual retry of failed work, not a normal paging loop.
 
+Self-managed descriptors keep `domain` as the normalized host and expose the configured installation address
+in `baseUrl`. Provider requests use the selected connection's address, including during account discovery.
+HTTPS repository resolution requires the configured host, web port, and installation path; the installation
+prefix is removed before parsing the repository identity. Without a `connectionId`, the connection whose
+installation path is the longest prefix of the remote resolves it (the primary on a tie); a remote under an
+installation that an unpinned read can't reach through its own session resolves as `host-mismatch` rather
+than through another installation's session. SSH resolution uses the configured web address and
+port, since the SSH endpoint can use a different port and omit the web installation path. If several configured
+web authorities share an SSH hostname, select one with `connectionId` or a trusted `domain`.
+
 **`broadenIssues` vs `searchIssuesPage`.** `broadenIssues` now reads each org through the org-scoped
-filtered search where the provider declares one (GitHub/GHE), so it no longer discovers repositories first
-and no longer routes through the SDK read's recovery walk — one request per page, per org. A provider with
-no filtered search (Azure DevOps, GitLab) still takes the repository drain, since refusing the org would be
-worse. It remains the read for "fan out across these orgs, whatever repos they turn out to contain", with
+filtered search where the provider declares one (GitHub/GHE, Azure DevOps Server), so it no longer discovers
+repositories first and no longer routes through the SDK read's recovery walk — one request per page, per org. A
+provider with no filtered search (Azure DevOps Services, GitLab) still takes the repository drain, since refusing
+the org would be worse. It remains the read for "fan out across these orgs, whatever repos they turn out to contain", with
 per-provider attribution (`broadenedProviderIds` / `failedProviderIds` / `incompleteProviderIds`) that the
 single-provider search doesn't produce; reach for `searchIssuesPage` when you want ONE scope with an order
 you control.

package/docs/kepler-read-api-parity.md

@@ -156,11 +156,12 @@ was the standing argument for refusing a multi-repo "assigned to anyone" read. M
 `org:gitkraken` 315. Any scope works; only the unscoped form is meaningless (6.7 M), which is what the guards
 actually refuse.
 
-**Provider coverage:** GitHub/GHE only. GitLab and Azure declare no `issueSearch` capability, so the read is
-refused there rather than serving an unnarrowed list — unimplemented, not impossible: GitLab maps to `search` /
-`updated_after` / `labels` / `milestone` with one relationship per REST call (its `assignee_username` +
-`author_username` compose with AND, so relationships must stay separate drains), and Azure to per-project WIQL.
-`withoutLinkedPullRequest` and free text have no equivalent on either.
+**Provider coverage:** GitHub/GHE, and Azure DevOps Server through one collection-scoped WIQL query (#5876; see
+[`integrations.md` §9](./integrations.md#9-per-provider-behavior-worth-designing-around) for what it declares).
+GitLab and Azure DevOps Services declare no `issueSearch` capability, so the read is refused there rather than
+serving an unnarrowed list — unimplemented, not impossible: GitLab maps to `search` / `updated_after` / `labels` /
+`milestone` with one relationship per REST call (its `assignee_username` + `author_username` compose with AND, so
+relationships must stay separate drains).
 
 **`countPullRequests`** is the PR twin, closing the asymmetry the audit flagged: the PR side had
 `searchPullRequestsPage` but no count probe, so an explicit "search everywhere" on PRs ran blind while the same
@@ -169,7 +170,10 @@ action on issues showed a number. It reuses GitHub's `issueCount`-on-a-zero-node
 one-relationship-per-scope rules. The one PR-specific decision: a scope's `states` are counted as independent
 searches, so the reported count is the **largest** of them (the total `searchPullRequestsPage` itself surfaces
 via `Math.max` over facets), not their sum, and `exceedsProviderLimit` compares that max against the per-search
-ceiling. GitHub/GHE only, matching `searchPullRequestsPage`.
+ceiling. GitHub/GHE, Bitbucket Data Center and Azure DevOps Server, matching `searchPullRequestsPage`. Bitbucket
+Data Center counts by reading, so it reports the exact union (a floor with `lowerBound` past its first page) and
+accepts several relationships in one scope; Azure's count is the union of the states from the same facet drain its
+search pages through, or `undefined` past the drain bound.
 
 **Since done:** `broadenIssues`' inner per-org read WAS swapped onto the filtered search (#5804). Only that
 inner read changed — the fan-out keeps its own result type, per-org cursor bundle and per-provider
@@ -198,5 +202,14 @@ than a browser link; supplying both retains the one-request contract. Linear nee
 Linear only; Trello refuses because its single-issue read can fall back to a capped board scan for a numeric
 identifier, where a "not found" result cannot be distinguished from a card beyond the cap.
 
+**Jira Data Center point reads (#5872).** The same read serves a self-hosted Jira instance once it carries the host:
+`getTrackerIssue` takes the `domain` its paged siblings already took, and `resourceId` is the host itself (the
+instance's single resource; one naming another host than the read resolves to is refused). It does NOT fall back to the primary connection the way the paged reads do — a
+self-managed tracker requires a `domain` or a `connectionId` with a configured host and is refused otherwise —
+because its proven absence is cacheable and two self-hosted instances routinely issue the same keys, so an answer
+from whichever host is primary would be cached under a key naming a different instance. The branch-association
+resolver (`getIssueFromGitConfigEntityIdentifier`) follows the same rule from the other side: its resolver receives
+the identifier's `domain`, and a Jira Data Center identifier without one is dropped rather than resolved.
+
 **Kepler-side follow-up:** `ProviderScopeFilter` carries a single `repo?: string` today and needs the criteria
 set; the `provider-data` adapter then routes "All visible" to `searchIssuesPage` + `countIssues`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gitkraken/core-gitlens",
   "description": "GitLens core — shared Git / AI / GitHub primitives for internal GitKraken consumption",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "license": "SEE LICENSE IN LICENSE",
   "author": {
     "name": "GitKraken",