@gitkraken/core-gitlens 0.5.102 → 0.5.104

package/docs/integrations.md

@@ -120,6 +120,8 @@ it with `page` + `hasMore` + `cursor?`. **No read throws for a provider-side fai
 | `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.                 |
 | `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.                           |
 | `listIssueTrackerIssuesPage` | `IssueShape`              | Jira / Linear / Trello (issues live under resource → project).                        |
 | `sweepPullRequests`          | `ProviderSweepResult`     | Drains **every** page across providers (`maxPages`, default 100).                     |
 | `sweepClosedPullRequests`    | `ProviderSweepResult`     | Same, pinned to `['closed','merged']`.                                                |
@@ -169,6 +171,77 @@ Invariants worth relying on:
   set" on `page.allPages === true`, which is false for _both_ truncation and failure — unlike
   `page.truncated`, which can be misread as a benign cap.
 
+### 5.1 The filtered issue search and its count probe
+
+`searchIssuesPage` answers "every issue in this scope matching X", which no other issue read can: the
+account-wide `listIssuesPage` is bound to the user's own relationships, and its repo-scoped path goes through
+the SDK read whose over-limit recovery walk can spend up to 128 sequential requests and still return an
+incomplete set. This one is a single request per page.
+
+```ts
+const caps = manager.getSupportedFilters(providerId).issueSearch;
+if (caps.relationships.length === 0) return; // provider has no filtered issue search — hide the surface
+
+const result = await manager.searchIssuesPage({
+	providerId: providerId,
+	repos: [{ namespace: 'gitkraken', name: 'vscode-gitlens' }],
+	criteria: {
+		relationships: ['unassigned'],
+		...(caps.updatedAfter ? { updatedAfter: '2026-05-05' } : {}),
+	},
+});
+```
+
+Three parts of the contract that are decisions, not incidentals:
+
+- **Scope is mandatory.** Pass `repos`, `org`, or a user relationship (`authored` / `assigned` / `mentioned`).
+  `any-assignee` and `unassigned` do **not** scope anything — they describe the issue, not the caller, so
+  either one alone matches every such issue on the host. A call carrying only those is refused (warning +
+  `fetchFailed`), as is one scoping by repository **id**: a search names repositories by path, so ids would
+  silently widen the read to the whole org.
+- **Ordering is always most-recently-updated-first.** Not an option: a "show the N most recent" policy at the
+  result ceiling is only correct under a guaranteed order.
+- **`itemsPerPage` is per RELATIONSHIP**, since each becomes its own provider query: a page of an
+  N-relationship search returns up to `N × itemsPerPage` items before deduplication, and fewer where they
+  overlap. Read `page.itemsPerPage` for what actually came back.
+- **At the result ceiling the read SUCCEEDS.** More matches than the provider will serve is an _omission_, not
+  a failure: `fetchFailed` stays absent, and the warning carries `omission.totalCount` (how many matched),
+  `omission.limit` (how many are reachable) and `recovery: 'none'` — the rest is unreachable however you page,
+  so never offer a "load more" here. Narrowing the criteria is the only way through.
+
+`criteria` is validated all-or-nothing against the capability table before the read runs, exactly like
+`filters` (§7). Free-form values (`text`, `labels`, `milestone`) are sanitized so user input cannot inject a
+qualifier and re-scope the search; `text` additionally drops tokens containing `:`, since the structured
+criteria are the qualifier channel.
+
+**`countIssues`** answers "how many match" without fetching any — what a "this will fetch ~N issues" preview
+needs, and what a live count beside an unapplied filter chip needs. Measured against GitHub, 30 counts are a
+single rate-limit point, but each batch is still a network request: debounce and cache it if it's driven from
+UI state.
+
+```ts
+const counts = await manager.countIssues({
+	providerId: providerId,
+	scopes: [
+		{ key: 'unassigned', repos: repos, criteria: { relationships: ['unassigned'] } },
+		{ key: 'recent', repos: repos, criteria: { updatedAfter: '2026-05-05' } },
+	],
+});
+```
+
+- Results are echoed under your own `key`, so no positional matching. A **duplicate key refuses the whole
+  call** — two results under one key make matching ambiguous for every scope.
+- **`count: undefined` means "not reported", never zero.** Render the difference: showing an unknown count as
+  0 tells the user a filter matches nothing when it may match thousands. A provider that can't count at all
+  refuses rather than fabricating.
+- `exceedsProviderLimit` is the signal to warn before starting an expensive fetch.
+- Isolation is per scope and per batch: a refused scope (unscoped, id-based repos, inexpressible criteria)
+  costs no request and drops only itself, and a failed batch drops only its own scopes — `fetchFailed` is set
+  and every other count still comes back.
+- One relationship per scope. A relationship set is OR-ed, which a single count can neither sum (it would
+  double-count overlaps) nor max (it would under-report), so such a scope is refused. Give each relationship
+  its own `key`.
+
 ## 6. Failures: warnings, `fetchFailed`, `truncated`
 
 A per-provider (or per-connection, or per-scope) failure degrades to a **warning attached to a partial
@@ -299,6 +372,11 @@ const filters = wanted.filter(f => capability.includes(f));
   (`listIssueTrackerIssuesPage` validates against this field).
 - `issuesAccountWide` — the account-wide git-host read only. Usually narrower (GitLab can express
   `Assignee` and `Author`, but not `Mention`), and empty for issue trackers.
+- `issueSearch` — the **filtered issue search** (`searchIssuesPage`, and `countIssues` over the same
+  criteria). A third, wider surface: not bound to the user at all, so it takes relationships the other two
+  can't name. Reported as per-criterion flags rather than a list, and **always present** — a provider with no
+  filtered issue search reports empty `relationships` and all-false flags, which is the signal to hide the
+  surface rather than individual chips.
 
 It's a _capability_ table, not a recommendation: passing fewer filters than listed is fine.
 
@@ -316,6 +394,12 @@ On the account-wide issue read, `filters` **replaces** the provider's own defini
 `[Assignee]` means `assignee:@me` wherever it's expressible. `includeAllAssignees`
 does the opposite (drops the user scope); passing both on that account-wide read is refused as contradictory.
 
+`searchIssuesPage`'s `criteria.relationships` follows the same all-or-nothing rule and the same OR semantics
+(one provider query per member, unioned and deduped), with two additions that are **not** about the user:
+`any-assignee` (assigned to anyone) and `unassigned` (assigned to nobody). They partition the scope between
+them, so requesting both is refused. Note that "all visible issues" is the **omitted** relationship set, not
+`any-assignee` — which excludes unassigned issues.
+
 `includeReviewRequested` is a legacy account-wide breadth option used only when no explicit `filters` are
 supplied. It remains useful for Bitbucket Cloud, where the reviewer slice requires an expensive
 O(workspaces × repos) fan-out; prefer `filters: [ReviewRequested]` when an exact relationship is required.
@@ -339,6 +423,8 @@ Derived from the provider models and `providersMetadata`. ✓ supported · ✗ r
 | PR `states` account-wide     |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |  —   |   —    |   —    |
 | Issues, repo-scoped          |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |  —   |   —    |   —    |
 | Issues, account-wide         |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |  —   |   —    |   —    |
+| `searchIssuesPage`           |      ✓       |          ✗           |     ✗     |      ✗       |            ✗            |  ✗   |   ✗    |   ✗    |
+| `countIssues`                |      ✓       |          ✗           |     ✗     |      ✗       |            ✗            |  ✗   |   ✗    |   ✗    |
 | Issues by `org`/`project`    |      ✗       |          ✗           |     ✗     |      ✗       |            ✓            |  ✓   |   ✓    |   ✓    |
 | `listIssueTrackerIssuesPage` |      —       |          —           |     —     |      —       |            —            |  ✓   |   ✓    |   ✓    |
 | `broadenIssues`              |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |  ✗   |   ✗    |   ✗    |
@@ -354,6 +440,13 @@ Issue filters: GitHub/GHE + Azure + Jira `Author, Assignee, Mention` · GitLab `
 Linear + Trello `Assignee` · Bitbucket family none.
 Account-wide issue filters: GitHub/GHE `Author, Assignee, Mention` · Azure `Author, Assignee` · GitLab
 `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.
 
 > `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
@@ -364,8 +457,12 @@ Account-wide issue filters: GitHub/GHE `Author, Assignee, Mention` · Azure `Aut
 - **GitHub / GHE** — cursor-only everywhere. The account-wide issue read is three searches (`author:@me`,
   `assignee:@me`, `mentions:@me`) behind one composite cursor; a filtered account-wide PR read is one search
   per state × relationship facet behind a composite cursor that resumes only active facets. Each search caps
-  at GitHub's own result ceiling, surfaced as `page.truncated`. `includeAllAssignees` is refused account-wide
-  (scope to repos instead).
+  at GitHub's own 1.000-result ceiling, surfaced as `page.truncated` — and on `searchIssuesPage` additionally
+  as an omission carrying the total match count (§5.1). The only provider with a filtered issue search today.
+  `includeAllAssignees` is refused on the **account-wide** issue read: it becomes `assignee:*`, which needs a
+  scope to mean anything (unscoped it matches millions of issues across all of GitHub) and that read has none
+  to offer. Any scope works, though — one repository, several, or an org — so "assigned to anyone over these
+  repos" is `searchIssuesPage` with `relationships: ['any-assignee']`.
 - **GitLab / self-hosted** — numbered per-repo cursors for repo-scoped reads. Account-wide PR state selection
   is forwarded to each relationship query. Account-wide issues can independently narrow to assignee or author;
   the unfiltered read unions both.
@@ -392,6 +489,17 @@ Account-wide issue filters: GitHub/GHE `Author, Assignee, Mention` · Azure `Aut
   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.
 
+**`broadenIssues` vs `searchIssuesPage`.** If you already know your repository set, prefer
+`searchIssuesPage({ repos })`: `broadenIssues` has to discover each org's repositories first (a paged drain)
+and then reads their issues through the SDK path with the recovery walk, so it costs strictly more for the
+same answer. 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.
+
+If you do migrate: broaden means **all visible** — it drops the assignee constraint entirely, so unassigned
+issues are included. The equivalent is therefore an **omitted** `relationships`, **not**
+`['any-assignee']` — `assignee:*` means "has some assignee" and would silently exclude every unassigned issue.
+
 The same warning holds for `IssueShape.id` generally: it's the provider's **display** number/key (rendered
 as `#{id}`, used for branch names). `nodeId` is the stable provider-native id, but its uniqueness scope is
 provider-specific (Azure work-item ids are organization-scoped). For cross-scope correlation, key by

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

@@ -110,3 +110,60 @@ unchanged.
 
 **Caveat:** Azure DevOps is scoped within a single organization; multi-org scoping remains unsupported (the
 existing single-org guard stands).
+
+## 7. Filtered issue search + count probe
+
+Gap raised by [kepler#1745](https://github.com/gitkraken/kepler/issues/1745) Part 2 (the "All visible" issue
+explorer). Kepler needed three things no existing read provided, and the reason is one asymmetry: the PR side
+had a free-text, repo-scoped, relationship-optional search primitive (`searchPullRequests` /
+`searchMyPullRequestsPage`) and the issue side had none. Every issue read was either bound to `@me` or routed
+through `getIssuesForRepos`, which is the 128-request `recoverOverLimitSearch` path — the source of the
+reported 116 s / 88 omissions.
+
+**`searchIssuesPage`** (`IssueShape`, one request per page) is the issue counterpart. Structured
+`IssueSearchCriteria` rather than a raw query string: a raw string is exactly why `searchPullRequests` is
+GitHub-only in practice and why its capability is undeclarable, and Kepler has to render filter chips and hide
+the unsupported ones, which needs a typed model plus `getSupportedFilters().issueSearch`.
+
+**`countIssues`** answers "how many match" with zero issues transferred, which is what makes the cost dialog
+and the live count label affordable. Verified against the live GitHub API: 30 aliased counts cost **1**
+rate-limit point.
+
+Decisions worth recording, because each closes off a plausible-looking alternative:
+
+- **A separate method, not `countOnly` on the read.** Transferring zero issues is the whole value; a flag
+  would return a `ProviderPagedResult` whose `items`, `cursor` and `hasMore` are all meaningless.
+- **A sibling read, not a mode of `listIssuesPage`.** That read is already two divergent branches around a
+  contract where `filters` replaces the provider's definition of "my issues"; `any-assignee` / `unassigned`
+  aren't "my issues" at all. Same reasoning as `broaden.ts` / `sweeps.ts` being separate files.
+- **`sort:updated` is a contract, not an option.** Kepler's cap policy ("the 1.000 most recent") is only
+  correct under a guaranteed order; an option invites picking relevance order and then truncating to an
+  arbitrary subset.
+- **The result ceiling is an omission, not a failure.** `fetchFailed` absent, `recovery: 'none'`, and
+  `omission.totalCount` populated — which is the number in Kepler's "This will fetch ~19.240 issues". The
+  `ProviderWarningOmission.totalCount` field already existed and was documented as "Only GitHub's search cap
+  does today"; it simply had never been populated on this path, because `searchMyIssues` computed
+  `issueCount > 1000` into a boolean and discarded the number.
+- **Scope is mandatory, and `any-assignee` / `unassigned` do not count as one.** They describe the issue, not
+  the caller (measured: unscoped `no:assignee` is tens of millions of results).
+
+**Corrected along the way:** the source claimed GitHub honors `assignee:*` only for a single repository, which
+was the standing argument for refusing a multi-repo "assigned to anyone" read. Measured
+(`is:issue is:open archived:false`): kepler 111 + vscode-gitlens 133 = **244** for both repos together, and
+`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.
+
+**Not done, deliberately:** `broadenIssues` was left as-is rather than reimplemented on top of this. It is a
+multi-provider, multi-org fan-out with its own result type and per-org cursor bundle, so only its inner
+per-org read could be swapped; and its "all visible" breadth maps to an OMITTED relationship set, not to
+`any-assignee`, which excludes unassigned issues. See the note in `reads/broaden.ts` and
+[`integrations.md` §9](./integrations.md#9-per-provider-behavior-worth-designing-around).
+
+**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.5.102",
+  "version": "0.5.104",
   "license": "SEE LICENSE IN LICENSE",
   "author": {
     "name": "GitKraken",

package/src/git/models/issue.ts

@@ -7,6 +7,87 @@ import type { RepositoryIdentityDescriptor } from './repositoryIdentities.js';
 /** Selects which issue states a read should include. `all` covers open + closed. */
 export type IssueStateFilter = 'open' | 'closed' | 'all';
 
+/**
+ * One relationship a filtered issue search can constrain on.
+ *
+ * The last two are USER-INDEPENDENT — they describe the issue, not the caller — and neither is a SCOPE: either
+ * one alone matches every such issue on the host, so a search using one still needs a repository/org scope.
+ */
+export type IssueSearchRelationship =
+	/** Authored by the current user. */
+	| 'authored'
+	/** Assigned to the current user. */
+	| 'assigned'
+	/** Mentions the current user. */
+	| 'mentioned'
+	/** Assigned to ANYONE. Excludes unassigned issues — see {@link IssueSearchCriteria.relationships}. */
+	| 'any-assignee'
+	/** Assigned to nobody. The complement of `any-assignee`, not a broadening of it. */
+	| 'unassigned';
+
+/**
+ * What a filtered issue search narrows on: a provider-neutral criteria set, translated to each provider's own
+ * query language by its integration.
+ *
+ * Structured rather than a provider query string so a consumer can render filter chips and hide the ones a
+ * provider can't express, and so the same criteria mean the same thing on a provider whose query language looks
+ * nothing like GitHub's search syntax. Every field is validated against the provider's declared capability
+ * BEFORE the read runs, all-or-nothing: a criterion the provider can't express server-side refuses the whole
+ * read rather than serving a list that was never narrowed. Client-side narrowing is not an option — the dropped
+ * items still counted toward the page and cursor the provider produced, so a post-filter would leave the items
+ * describing a different result set than the paging that came with them.
+ */
+export interface IssueSearchCriteria {
+	/**
+	 * Relationships to constrain on, OR-ed together (each becomes its own provider query, unioned and deduped).
+	 * Omitted means NO relationship constraint at all — every issue in scope, assigned or not — which requires a
+	 * repository/org scope.
+	 *
+	 * `any-assignee` and `unassigned` partition the scope between them and are mutually exclusive; passing both is
+	 * refused rather than silently dropping one. Note that "all visible issues" is the OMITTED case, NOT
+	 * `any-assignee`, which excludes unassigned issues.
+	 */
+	relationships?: IssueSearchRelationship[];
+	/**
+	 * Free text, matched by the provider's own relevance rules — NOT a substring match, and not a way to smuggle
+	 * qualifiers: a token that would read as one is dropped, as are quotes and control characters, so text can
+	 * never re-scope the search. The structured criteria are the qualifier channel.
+	 */
+	text?: string;
+	/** Issue states to include. Omitted reads open issues only. */
+	state?: IssueStateFilter;
+	/** Labels the issue must carry — AND-ed, matching GitHub's own `label:` semantics. */
+	labels?: string[];
+	milestone?: string;
+	/** ISO date (`YYYY-MM-DD`). The most effective narrowing criterion by far on a large scope. */
+	updatedAfter?: string;
+	/** ISO date (`YYYY-MM-DD`). */
+	createdAfter?: string;
+	/** Issues with no linked pull request. */
+	withoutLinkedPullRequest?: boolean;
+	/** Includes issues in archived repositories, which are excluded by default. */
+	includeArchived?: boolean;
+}
+
+/**
+ * Which {@link IssueSearchCriteria} fields a provider's filtered issue search can express server-side.
+ *
+ * An empty `relationships` with every flag false means the provider has NO filtered issue search — the read is
+ * refused outright, so a consumer should offer neither the surface nor its chips.
+ */
+export interface IssueSearchCapabilities {
+	/** Relationships the search can constrain on. Empty means the search itself is unsupported. */
+	relationships: IssueSearchRelationship[];
+	text: boolean;
+	labels: boolean;
+	milestone: boolean;
+	updatedAfter: boolean;
+	createdAfter: boolean;
+	withoutLinkedPullRequest: boolean;
+	/** Whether {@link IssueSearchCriteria.state} can select anything other than the provider's default (open). */
+	states: boolean;
+}
+
 export interface IssueShape extends IssueOrPullRequest {
 	/** `undefined` when the provider can't resolve the author, e.g. a deleted GitHub account */
 	author: IssueMember | undefined;

package/src/plus/git-github/api/config.ts

@@ -76,3 +76,16 @@ export interface GitHubApiConfig {
 	 */
 	getLaunchpadIgnoredOrganizations?(): string[];
 }
+
+/**
+ * The maximum number of results GitHub's search will serve for ONE query, however it is paged. A search whose
+ * `issueCount` exceeds this cannot be read in full: the items past the ceiling are UNREACHABLE, not merely
+ * unfetched — no budget, no retry and no cursor returns them.
+ *
+ * It lives in this leaf module rather than beside the search that detects it because the facade's
+ * provider-agnostic metadata table reports the same ceiling to consumers, and the two must be one number: a
+ * duplicated literal drifts silently, and drift here means quoting a limit the client doesn't enforce. Importing
+ * it from `github.ts` would have pulled that module — and its octokit dependencies — eagerly into the graph of
+ * one of the most widely imported modules in the integrations package, for the sake of a single integer.
+ */
+export const githubSearchResultLimit = 1000;