@gitkraken/core-gitlens 0.5.101 → 0.5.103

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

@@ -11,6 +11,68 @@ export interface ConnectionStateChangeEvent {
  * needs re-connection); `isAuth` is retained as a convenience mirror of `kind === 'auth'`.
  */
 export type ProviderWarningKind = 'auth' | 'rate-limit' | 'not-found' | 'no-connection' | 'other';
+/**
+ * Why a read that SUCCEEDED still withheld results:
+ * - `provider-limit`: the provider refuses to serve past a cap it enforces (GitHub search's 1,000-result
+ *   ceiling, Trello's `cards_limit`), so the excess is unreachable through that query.
+ * - `recovery-budget`: the internal partitioned recovery stopped spending upstream requests before it ran
+ *   out of partitions to visit.
+ * - `pagination-incomplete`: pages were left unread — a sub-scope of a multi-scope read that was not drained,
+ *   a drain that stopped at its own page backstop, or a provider that advertised another page and gave no way
+ *   to reach it. These have DIFFERENT remedies, so the kind alone does not say whether more can be fetched;
+ *   read {@link ProviderWarningOmission.recovery} for that.
+ *
+ * Mirrors the vocabulary the SDK reports. Declared here rather than imported so this module stays free of
+ * `@gitkraken/provider-apis` types (see the export block in `index.ts`); `collectionMetadata.ts` holds the
+ * compile-time link, so an SDK bump that adds a kind fails the build at that boundary.
+ */
+export type ProviderWarningOmissionKind = 'provider-limit' | 'recovery-budget' | 'pagination-incomplete';
+/**
+ * What, if anything, would fetch the withheld results — the question `kind` cannot answer.
+ *
+ * `kind` says WHY results are missing, and two omissions of the same kind can need opposite handling: a drain
+ * that stopped at a caller-settable page budget and a provider that advertised another page without a usable
+ * cursor are both `pagination-incomplete`, but only the first can be fetched. A consumer offering a "load
+ * more" affordance gates it on this, never on `kind`.
+ *
+ * - `none`: nothing the consumer can call returns the missing items — a provider-enforced cap, an internal
+ *   budget it does not control, or a continuation the provider refused to hand back. Say the results are
+ *   capped; do not offer to fetch more.
+ * - `page-budget`: re-run the SAME read with a higher page budget (`maxPages` on the sweep options). Note this
+ *   re-reads from the start rather than continuing — a sweep exposes no cursor — so it is a deliberate,
+ *   user-initiated action, not something to retry automatically.
+ *
+ * Required, not optional: an absent value would be indistinguishable from `none` while actually meaning "this
+ * producer didn't say", which is the ambiguity {@link ProviderWarning.omission} exists to remove. And a
+ * conservative union on purpose — it names only what a producer can PROVE. A value is added when some layer
+ * can vouch for it, never so that a plausible-looking case has something to map to; see
+ * `collectionMetadata.ts` for the SDK shape that looks recoverable and is not.
+ */
+export type ProviderWarningOmissionRecovery = 'none' | 'page-budget';
+/** Which repository / project / resource an omission is attributed to. All fields optional; a scope may name none. */
+export interface ProviderWarningOmissionScope {
+    providerId?: string;
+    resourceId?: string;
+    projectId?: string;
+    repositoryId?: string;
+}
+export interface ProviderWarningOmission {
+    kind: ProviderWarningOmissionKind;
+    /**
+     * Whether anything would fetch the missing items, and what. Gate a "load more" affordance on this rather
+     * than on `kind` — see {@link ProviderWarningOmissionRecovery}.
+     */
+    recovery: ProviderWarningOmissionRecovery;
+    /**
+     * The cap the provider enforces, when it reports one. NOT a result count for every kind: on
+     * `recovery-budget` this is a REQUEST budget and must not be shown to a user as a number of results.
+     */
+    limit?: number;
+    /** Total matches the provider reported, when it reports one. Only GitHub's search cap does today. */
+    totalCount?: number;
+    /** Which repository / project / resource was affected, when one is attributed. */
+    scope?: ProviderWarningOmissionScope;
+}
 export interface ProviderWarning {
     providerId: IntegrationIds;
     /** Disambiguates connections on self-managed hosts (where one provider id spans multiple domains). */
@@ -21,6 +83,29 @@ export interface ProviderWarning {
     kind: ProviderWarningKind;
     /** Convenience mirror of `kind === 'auth'`. */
     isAuth: boolean;
+    /**
+     * Present when this warning describes results the read could not return even though the request itself
+     * SUCCEEDED — a provider-enforced cap, an exhausted recovery budget, a page budget, or a sub-scope the read
+     * did not drain.
+     *
+     * Its presence is the signal: an omission is not a failure. Message it as incompleteness rather than as a
+     * failed read, and do NOT derive that from `message`, which is English prose and subject to rewording.
+     * `kind` stays `'other'` for these, so the failure discriminant keeps meaning exactly what it meant before
+     * this field existed.
+     *
+     * Whether anything would fetch the rest is a SEPARATE question — read {@link ProviderWarningOmission.recovery},
+     * not `kind`, and never assume a retry of the same request returns more.
+     *
+     * `limit` / `totalCount` / `scope` are forwarded only when they are reported; most omissions carry none of
+     * the three, so render correctly without them — and see {@link ProviderWarningOmission.limit} before
+     * showing that figure as a result count.
+     *
+     * Its ABSENCE proves nothing. It is never set on a warning derived from a caught exception (see
+     * {@link toProviderWarning}) or from a structured scope failure — those are failures, and the field would
+     * be a lie there. But it is also absent whenever incompleteness was reported without naming what was left
+     * out, so treat a bare `kind: 'other'` warning as unclassified rather than as a proven failure.
+     */
+    omission?: ProviderWarningOmission;
 }
 export interface ProviderPageInfo {
     /**
@@ -184,6 +269,35 @@ export interface ProviderRepositoryShape {
  * a 404 isn't mislabeled as auth.
  */
 export declare function toProviderWarning(providerId: IntegrationIds, domain: string | undefined, connectionId: string | undefined, ex: unknown): ProviderWarning;
-/** Appends `warning` to `into` only when an equal warning (by provider/connection/domain/kind/message) is absent. */
+/**
+ * A scope's identity, as the stable string that keys it.
+ *
+ * The single definition of what "the same scope" means, shared by the failure and omission dedup keys in
+ * `providerPaging.ts` and by {@link providerWarningKey} below, so a scope gaining a field is one edit rather
+ * than three. `providerId` is included: the same repository ID under two providers is two scopes.
+ *
+ * The parameter is structural rather than the SDK's `CollectionScope` so this module keeps naming no
+ * `@gitkraken/provider-apis` types (see the export block in `index.ts`) while still serving its SDK-facing
+ * callers, which pass that type in unchanged.
+ */
+export declare function collectionScopeKey(scope: ProviderWarningOmissionScope | undefined): string;
+/**
+ * Strips the omission from every warning in `warnings` when the read as a whole failed.
+ *
+ * An omission asserts the request SUCCEEDED, and a drain only learns it failed AFTER it may have emitted one:
+ * an early page can report its own truncation and then a later page can die. Deciding per warning, at the
+ * moment each is built, cannot see that future — so the aggregate is reconciled once, here, where
+ * `fetchFailed` is final. Call it at the point a read returns its `fetchFailed`.
+ *
+ * Re-dedupes as it goes: the omission is part of a warning's identity, so two warnings that differed only
+ * there become identical once it is gone, and the array's contract is that no two entries are equal.
+ *
+ * Mutates in place: the warning array is the one being returned, and callers accumulate into it across pages.
+ */
+export declare function reconcileOmissionsWithFailure(warnings: ProviderWarning[], fetchFailed: boolean): void;
+/**
+ * Appends `warning` to `into` only when an equal warning (by provider/connection/domain/kind/message, plus the
+ * structured omission when one is present) is absent.
+ */
 export declare function appendDedupedWarning(into: ProviderWarning[], warning: ProviderWarning): void;
 //# sourceMappingURL=results.d.ts.map

package/dist/plus/integrations/results.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../../../src/plus/integrations/results.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../../../src/plus/integrations/results.ts"],"names":[],"mappings":"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"}

package/dist/plus/integrations/results.js

@@ -48,11 +48,86 @@ export function toProviderWarning(providerId, domain, connectionId, ex) {
         isAuth: kind === 'auth',
     };
 }
-/** A stable key for deduplicating warnings accumulated across drained pages / fan-out scopes. */
+/**
+ * A scope's identity, as the stable string that keys it.
+ *
+ * The single definition of what "the same scope" means, shared by the failure and omission dedup keys in
+ * `providerPaging.ts` and by {@link providerWarningKey} below, so a scope gaining a field is one edit rather
+ * than three. `providerId` is included: the same repository ID under two providers is two scopes.
+ *
+ * The parameter is structural rather than the SDK's `CollectionScope` so this module keeps naming no
+ * `@gitkraken/provider-apis` types (see the export block in `index.ts`) while still serving its SDK-facing
+ * callers, which pass that type in unchanged.
+ */
+export function collectionScopeKey(scope) {
+    return [scope?.providerId ?? '', scope?.resourceId ?? '', scope?.projectId ?? '', scope?.repositoryId ?? ''].join(' ');
+}
+/**
+ * The omission's contribution to a warning's identity — empty when there is none, so a warning without an
+ * omission keeps deduping exactly as it did before the field existed.
+ *
+ * Two omissions of different kinds do produce different `message` values today, so message alone would still
+ * separate them. That is incidental: the premise of `omission` is that consumers must not depend on prose
+ * carrying the distinguishing fact, and this key must not either.
+ */
+function providerWarningOmissionKey(omission) {
+    if (omission == null)
+        return '';
+    return [
+        omission.kind,
+        omission.recovery,
+        omission.limit ?? '',
+        omission.totalCount ?? '',
+        collectionScopeKey(omission.scope),
+    ].join(' ');
+}
+/**
+ * Strips the omission from every warning in `warnings` when the read as a whole failed.
+ *
+ * An omission asserts the request SUCCEEDED, and a drain only learns it failed AFTER it may have emitted one:
+ * an early page can report its own truncation and then a later page can die. Deciding per warning, at the
+ * moment each is built, cannot see that future — so the aggregate is reconciled once, here, where
+ * `fetchFailed` is final. Call it at the point a read returns its `fetchFailed`.
+ *
+ * Re-dedupes as it goes: the omission is part of a warning's identity, so two warnings that differed only
+ * there become identical once it is gone, and the array's contract is that no two entries are equal.
+ *
+ * Mutates in place: the warning array is the one being returned, and callers accumulate into it across pages.
+ */
+export function reconcileOmissionsWithFailure(warnings, fetchFailed) {
+    if (!fetchFailed || !warnings.some(w => w.omission != null))
+        return;
+    const reconciled = [];
+    for (const warning of warnings) {
+        if (warning.omission == null) {
+            appendDedupedWarning(reconciled, warning);
+            continue;
+        }
+        const { omission: _omission, ...rest } = warning;
+        appendDedupedWarning(reconciled, rest);
+    }
+    warnings.splice(0, warnings.length, ...reconciled);
+}
+/**
+ * A stable key for deduplicating warnings accumulated across drained pages / fan-out scopes.
+ *
+ * `message` stays LAST. It is the only free-form segment — provider prose, spaces and all — so anything
+ * appended after it could be impersonated by a message that happens to end in the same text.
+ */
 function providerWarningKey(warning) {
-    return [warning.providerId, warning.connectionId ?? '', warning.domain ?? '', warning.kind, warning.message].join(' ');
+    return [
+        warning.providerId,
+        warning.connectionId ?? '',
+        warning.domain ?? '',
+        warning.kind,
+        providerWarningOmissionKey(warning.omission),
+        warning.message,
+    ].join(' ');
 }
-/** Appends `warning` to `into` only when an equal warning (by provider/connection/domain/kind/message) is absent. */
+/**
+ * Appends `warning` to `into` only when an equal warning (by provider/connection/domain/kind/message, plus the
+ * structured omission when one is present) is absent.
+ */
 export function appendDedupedWarning(into, warning) {
     const key = providerWarningKey(warning);
     if (into.some(existing => providerWarningKey(existing) === key))

package/dist/plus/integrations/results.js.map

@@ -1 +1 @@
-{"version":3,"file":"results.js","sourceRoot":"","sources":["../../../src/plus/integrations/results.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AA8K1G,MAAM,+BAA+B,GAAG,GAAG,CAAC;AAE5C,SAAS,sBAAsB,CAAC,EAAW;IAC1C,MAAM,GAAG,GAAG,CAAC,EAAE,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACnE,MAAM,OAAO,GAAG,EAA8E,CAAC;IAC/F,MAAM,MAAM,GACX,OAAO,OAAO,EAAE,MAAM,KAAK,QAAQ;QAClC,CAAC,CAAC,OAAO,CAAC,MAAM;QAChB,CAAC,CAAC,OAAO,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,QAAQ;YAC9C,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM;YACzB,CAAC,CAAC,SAAS,CAAC;IAEf,4GAA4G;IAC5G,6GAA6G;IAC7G,IAAI,wCAAwC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACxD,OAAO,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,uCAAuC,MAAM,GAAG,CAAC,CAAC,CAAC,0BAA0B,CAAC;IACvG,CAAC;IAED,IAAI,CAAC,GAAG,EAAE,CAAC;QACV,OAAO,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,uCAAuC,MAAM,GAAG,CAAC,CAAC,CAAC,0BAA0B,CAAC;IACvG,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,GAAG,+BAA+B;QAClD,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,+BAA+B,GAAG,CAAC,CAAC,KAAK;QAC3D,CAAC,CAAC,GAAG,CAAC;AACR,CAAC;AA+BD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAChC,UAA0B,EAC1B,MAA0B,EAC1B,YAAgC,EAChC,EAAW;IAEX,IAAI,IAA6B,CAAC;IAClC,IAAI,EAAE,YAAY,mBAAmB,EAAE,CAAC;QACvC,IAAI,GAAG,MAAM,CAAC;IACf,CAAC;SAAM,IAAI,EAAE,YAAY,qBAAqB,EAAE,CAAC;QAChD,IAAI,GAAG,YAAY,CAAC;IACrB,CAAC;SAAM,IAAI,EAAE,YAAY,oBAAoB,EAAE,CAAC;QAC/C,IAAI,GAAG,WAAW,CAAC;IACpB,CAAC;SAAM,CAAC;QACP,IAAI,GAAG,OAAO,CAAC;IAChB,CAAC;IAED,OAAO;QACN,UAAU,EAAE,UAAU;QACtB,MAAM,EAAE,MAAM;QACd,YAAY,EAAE,YAAY;QAC1B,OAAO,EAAE,sBAAsB,CAAC,EAAE,CAAC;QACnC,IAAI,EAAE,IAAI;QACV,MAAM,EAAE,IAAI,KAAK,MAAM;KACvB,CAAC;AACH,CAAC;AAED,iGAAiG;AACjG,SAAS,kBAAkB,CAAC,OAAwB;IACnD,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,YAAY,IAAI,EAAE,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAChH,GAAG,CACH,CAAC;AACH,CAAC;AAED,qHAAqH;AACrH,MAAM,UAAU,oBAAoB,CAAC,IAAuB,EAAE,OAAwB;IACrF,MAAM,GAAG,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,kBAAkB,CAAC,QAAQ,CAAC,KAAK,GAAG,CAAC;QAAE,OAAO;IAExE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACpB,CAAC"}
+{"version":3,"file":"results.js","sourceRoot":"","sources":["../../../src/plus/integrations/results.ts"],"names":[],"mappings":"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"}

package/docs/integrations.md

@@ -177,13 +177,13 @@ result** instead of rejecting the call. One provider's expired token never blank
 `ProviderWarning.kind` (also exported as `ProviderWarningKind`) carries the classifications the facade can
 prove from structured errors:
 
-| `kind`          | Meaning                                                                                       | Reasonable response                                                                         |
-| --------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `auth`          | Token rejected (401/403 that isn't a throttle).                                               | Prompt to reconnect that connection.                                                        |
-| `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.                                                   |
-| `other`         | Catch-all: unsupported input, truncation, upstream/network failure, or an unclassified error. | Preserve the warning and use the result flags; do not assume it is benign or non-retryable. |
+| `kind`          | Meaning                                                                                                                                         | Reasonable response                                                                         |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `auth`          | Token rejected (401/403 that isn't a throttle).                                                                                                 | Prompt to reconnect that connection.                                                        |
+| `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.                                                   |
+| `other`         | Catch-all: unsupported input, truncation, upstream/network failure, or an unclassified error. Read `omission` before treating one as a failure. | Preserve the warning and use the result flags; do not assume it is benign or non-retryable. |
 
 `isAuth` is a convenience mirror of `kind === 'auth'`. **Collapsing `kind` into that boolean loses the
 rate-limit and not-found distinctions**, which then have to be re-derived from raw provider prose.
@@ -191,6 +191,70 @@ 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.
 
+### `omission` — succeeded, but withheld results
+
+`other` covers two facts with **opposite remedies**: a request that failed, and a request that succeeded while
+part of the answer was withheld. `ProviderWarning.omission` is set only for the second, so a consumer can act
+on it without parsing `message`:
+
+```ts
+if (warning.omission != null) {
+	// The read SUCCEEDED — message it as incompleteness, not failure.
+	// Whether anything would fetch the rest is a separate question; see `recovery` below.
+	if (warning.omission.recovery !== 'none') offerLoadMore(warning.omission);
+}
+```
+
+`kind` stays `'other'` for these on purpose: it is the discriminant derived from a caught exception's type, and
+adding a member would silently change what `'other'` means for every existing build.
+
+**Its absence proves nothing.** It is never set on a failure — an exception or a structured scope failure —
+where it would be a lie. But it is also absent whenever incompleteness was reported without naming what was
+left out, so treat a bare `kind: 'other'` warning as unclassified rather than as a proven failure.
+
+The line that matters is whether the request **succeeded**, not whether a tail was left unread. A drain that
+stopped on its own accounting succeeded and is capped, so it carries the omission; a drain that was interrupted
+mid-read left an unread tail too, but a retry may complete it — that one carries no omission and sets
+`fetchFailed`.
+
+`kind` says **why** results are missing:
+
+| `omission.kind`         | What happened                                                                                                                      |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `provider-limit`        | The provider refuses to serve past a cap (GitHub search's 1,000, Trello's `cards_limit`).                                          |
+| `recovery-budget`       | The internal partitioned recovery stopped before visiting every partition.                                                         |
+| `pagination-incomplete` | Pages were left unread: an undrained sub-scope, a page budget, or a provider that advertised another page without a usable cursor. |
+
+#### `recovery` — what, if anything, would fetch the rest
+
+**`kind` does not answer that**, and `pagination-incomplete` is why: a drain that stopped at a page budget and
+a provider that gave no usable cursor are the same kind, but only the first can be fetched. Gate a "load more"
+affordance on `recovery`, never on `kind`:
+
+| `omission.recovery` | Means                                                          | What a consumer does                                                       |
+| ------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `none`              | Nothing you can call returns the missing items.                | Say the results are capped. Do not offer to fetch more.                    |
+| `page-budget`       | Re-run the same read with a higher `maxPages` (sweep options). | Offer it — but note it re-reads from the start, so make it user-initiated. |
+
+`recovery` is **required** — unlike `limit`, `totalCount` and `scope`, it is never absent. An absent value
+would be indistinguishable from `none` while actually meaning "this producer didn't say", which is the
+ambiguity `omission` exists to remove.
+
+It is also **conservative**: it names only what a producer can prove, so `none` means "not known to be
+recoverable", not "proven unrecoverable". Today only a sweep that spent its own page budget reports
+`page-budget`; everything else — every provider cap, every exhausted internal budget, and every omission
+derived from SDK metadata — is `none`. A `scope` does not change that. It attributes where results were
+withheld, and the SDK reports the same scoped shape both for a scope it merely sampled and for one whose
+cursor stalled, so re-reading it is not something this layer can promise.
+
+`limit`, `totalCount` and `scope` are forwarded only when reported; **most omissions carry none of the three**,
+so render correctly without them. Two traps: `totalCount` is `number | undefined` and never `null` (the SDK's
+`null` is normalized to absent at the boundary), and `limit` on `recovery-budget` is a **request** budget — do
+not show it to a user as a number of results.
+
+Warnings dedup on their structure, `omission` included, so two omissions that differ only in kind, recovery or
+scope stay two warnings even if their messages ever converge.
+
 | Flag                    | Says                                                                                                                                          |
 | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | `fetchFailed`           | `items` is incomplete because a scope failed, or because a flat hierarchy read was truncated. Distinguishes this from a genuine empty result. |
@@ -199,6 +263,16 @@ and keep unknown failures conservative.
 | `failedProviderIds`     | Sweeps/broadens: providers whose requested scopes produced no usable result.                                                                  |
 | `incompleteProviderIds` | Sweeps/broadens: providers with a usable result plus a failed, partial, or truncated sibling scope.                                           |
 
+An omission pairs with `page.truncated: true` — results are missing — and typically with `fetchFailed: false`,
+since nothing failed. But the flags are **per result** and `omission` is **per warning**, so the two can differ
+on a fan-out: a sweep where provider A was capped and provider B failed outright reports `fetchFailed: true`
+while A's omission stays true for A. Read `omission` on the warning that carries it — its `providerId`,
+`domain` and `connectionId` say who it is about — rather than inferring it from the aggregate.
+
+What is guaranteed is the narrower thing: a warning never claims its own read succeeded when it didn't. A drain
+that dies mid-read publishes its unread tail with no omission, even if an earlier page had already reported
+one.
+
 `resolveRepository` reports through `resolution.status` instead: `resolved` · `not-found` · `unauthorized` ·
 `unsupported-provider` · `invalid-remote-url` · `host-mismatch` · `undetermined`. A `resolved` identity
 carries the provider's **canonical** owner/name plus `renamed: true` when the local remote is stale.

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.101",
+  "version": "0.5.103",
   "license": "SEE LICENSE IN LICENSE",
   "author": {
     "name": "GitKraken",

package/src/plus/integrations/collectionMetadata.ts

@@ -7,7 +7,7 @@ import type {
 import { AuthenticationError, RequestNotFoundError, RequestRateLimitError } from '../../git/errors.js';
 import type { IntegrationIds } from './constants.js';
 import { isRateLimitResponse } from './errors.js';
-import type { ProviderWarning } from './results.js';
+import type { ProviderWarning, ProviderWarningOmission } from './results.js';
 import { appendDedupedWarning } from './results.js';
 
 /**
@@ -73,19 +73,6 @@ function toCollectionFailureWarningKind(failure: CollectionScopeFailure): Provid
 	}
 }
 
-/**
- * A scope's identity, as the stable string that keys it.
- *
- * The dedup keys in `providerPaging.ts` build on this, so failures and omissions can never disagree about
- * what "the same scope" means. `providerId` is included: the same repository ID under two providers is two
- * scopes.
- */
-export function collectionScopeKey(scope: CollectionScope | undefined): string {
-	return [scope?.providerId ?? '', scope?.resourceId ?? '', scope?.projectId ?? '', scope?.repositoryId ?? ''].join(
-		' ',
-	);
-}
-
 /** ` (resource r, project p, repository o/n)` for the scope IDs present; empty when the scope names none. */
 function collectionScopeText(scope: CollectionScope | undefined): string {
 	const parts: string[] = [];
@@ -110,9 +97,10 @@ function collectionFailureMessage(failure: CollectionScopeFailure): string {
 /**
  * Explains one omission in the consumer's terms — what was left out and, where the SDK reports it, how much.
  *
- * An omission is a completeness fact, never a failure: the read succeeded and the provider (or the SDK's own
- * recovery budget) is what withheld results, so retrying the same request cannot recover them. That is why
- * these never contribute to `fetchFailed`.
+ * An omission is a completeness fact, never a failure: the read succeeded, and the provider (or the SDK's own
+ * recovery budget) is what withheld results. That is why these never contribute to `fetchFailed`. Whether a
+ * retry would recover anything is a separate question this layer cannot answer — see the `recovery` note on
+ * {@link toProviderWarningOmission}.
  */
 function collectionOmissionMessage(omission: CollectionOmission): string {
 	const scopeText = collectionScopeText(omission.scope);
@@ -142,6 +130,39 @@ function collectionOmissionMessage(omission: CollectionOmission): string {
 	}
 }
 
+/**
+ * Forwards an SDK omission as the structured signal consumers read instead of parsing {@link
+ * collectionOmissionMessage}'s prose.
+ *
+ * `results.ts` re-spells `CollectionOmissionKind` rather than importing it, so the published warning surface
+ * carries no `@gitkraken/provider-apis` types (see the export block in `index.ts`). The return type is what
+ * keeps the two unions honest: an SDK bump that adds a member fails to compile here, alongside
+ * `collectionOmissionMessage`'s `satisfies never`.
+ *
+ * `scope` is copied because the SDK's own object is retained and re-merged across drained pages
+ * (`providerPaging.ts`), and this one crosses the package boundary.
+ *
+ * `recovery` is always `'none'`, deliberately, and a scoped `pagination-incomplete` is why it looks wrong: the
+ * SDK emits that one shape from situations with opposite remedies and says so itself — "Either the read
+ * deliberately took one page per scope, or the provider advertised another page it gave no way to reach." Its
+ * `collectAcrossScopes` producers (Azure, Bitbucket, Bitbucket Server) are the first, its `drainAcrossScopes`
+ * producers (GitLab, Jira) the second, and those report an omission only when a cursor STALLED — so re-reading
+ * that scope stalls at the identical page. Nothing in `CollectionOmission` separates the two, so claiming
+ * recoverability would ship the dead-end button `recovery` exists to prevent. Making the recoverable case
+ * claimable needs provider-apis to say whether a scope was drained or merely sampled: a fact to forward, not
+ * to guess here.
+ */
+function toProviderWarningOmission(omission: CollectionOmission): ProviderWarningOmission {
+	return {
+		kind: omission.kind,
+		recovery: 'none',
+		...(omission.limit != null ? { limit: omission.limit } : {}),
+		// The SDK types this `number | null | undefined`; normalize to one absence for consumers.
+		...(omission.totalCount != null ? { totalCount: omission.totalCount } : {}),
+		...(omission.scope != null ? { scope: { ...omission.scope } } : {}),
+	};
+}
+
 /**
  * Whether SDK metadata describes a read that may be missing results.
  *
@@ -184,7 +205,8 @@ export function assessCollectionMetadata(
 
 	// Omissions explain WHY a read is incomplete when nothing failed — a provider cap, an exhausted recovery
 	// budget, an undrained scope. They classify as `other`, never `auth`, and are deliberately excluded from
-	// `fetchFailed` below: the request succeeded, so a retry would return the same truncated set.
+	// `fetchFailed` below: the request itself succeeded. `omission` carries that same fact structurally, so a
+	// consumer can act on it without parsing the message.
 	const omissions = metadata.omissions ?? [];
 	for (const omission of omissions) {
 		appendDedupedWarning(warnings, {
@@ -194,12 +216,17 @@ export function assessCollectionMetadata(
 			message: collectionOmissionMessage(omission),
 			kind: 'other',
 			isAuth: false,
+			omission: toProviderWarningOmission(omission),
 		});
 	}
 
 	const incomplete = isIncompleteCollection(metadata);
 	// Only fall back to the generic message when nothing more specific was reported; an omission already
 	// explains the incompleteness in the consumer's terms, so adding this on top would be noise.
+	//
+	// This one deliberately carries no `omission`: it fires precisely when the SDK reported incompleteness
+	// WITHOUT saying what was left out, so there is no structured fact to forward and synthesizing one would
+	// assert a specificity this layer does not have.
 	if (incomplete && failures.length === 0 && omissions.length === 0) {
 		appendDedupedWarning(warnings, {
 			providerId: providerId,
@@ -217,17 +244,36 @@ export function assessCollectionMetadata(
 	return { warnings: warnings, fetchFailed: failures.length > 0, truncated: incomplete };
 }
 
-/** Appends neutral warnings derived from SDK metadata and returns its failure/truncation assessment. */
+/**
+ * Appends neutral warnings derived from SDK metadata and returns its failure/truncation assessment.
+ *
+ * `reported` says whether the metadata described this read's incompleteness at all. A caller that would
+ * otherwise add its own generic "this was truncated" warning uses it to stay quiet — the same rule
+ * {@link assessCollectionMetadata} applies to its own generic fallback, one layer up: whatever the metadata
+ * reported already names this provider and, unless it was that same fallback, says something a consumer can
+ * act on. Restating it in a weaker vocabulary is how one gap becomes two warnings with two different verdicts.
+ *
+ * `truncated` is the near-synonym that must NOT be used for that question: it comes from
+ * {@link isIncompleteCollection}, which does not consider failures, so metadata carrying a typed failure
+ * alongside `completeness: 'complete'` reports `truncated: false` while having already appended the warning
+ * that explains everything. Gating on it would restate exactly the case this field exists to keep quiet.
+ */
 export function mergeAssessmentInto(
 	warnings: ProviderWarning[],
 	providerId: IntegrationIds,
 	domain: string | undefined,
 	connectionId: string | undefined,
 	metadata: CollectionMetadata | undefined,
-): { fetchFailed: boolean; truncated: boolean } {
+): { fetchFailed: boolean; truncated: boolean; reported: boolean } {
 	const assessment = assessCollectionMetadata(providerId, domain, connectionId, metadata);
 	for (const warning of assessment.warnings) {
 		appendDedupedWarning(warnings, warning);
 	}
-	return { fetchFailed: assessment.fetchFailed, truncated: assessment.truncated };
+	return {
+		fetchFailed: assessment.fetchFailed,
+		truncated: assessment.truncated,
+		// What the assessment PRODUCED, not what `appendDedupedWarning` accepted: a warning dropped as a
+		// duplicate is still one the consumer will see, so it still makes a restatement redundant.
+		reported: assessment.warnings.length > 0,
+	};
 }

package/src/plus/integrations/index.ts

@@ -202,6 +202,10 @@ export type {
 	ProviderSweepResult,
 	ProviderWarning,
 	ProviderWarningKind,
+	ProviderWarningOmission,
+	ProviderWarningOmissionKind,
+	ProviderWarningOmissionRecovery,
+	ProviderWarningOmissionScope,
 	ProviderOrganization,
 	ProviderRepositoryShape,
 	RepositoryIdentity,

package/src/plus/integrations/providers/utils/providerPaging.ts

@@ -6,7 +6,8 @@ import type {
 } from '@gitkraken/provider-apis';
 import { isCancellationError } from '../../../../utils/cancellation.js';
 import { uniqueBy } from '../../../../utils/iterable.js';
-import { collectionScopeKey, toCollectionScopeFailure } from '../../collectionMetadata.js';
+import { toCollectionScopeFailure } from '../../collectionMetadata.js';
+import { collectionScopeKey } from '../../results.js';
 import type { ProviderApiPagedResult, ProviderHierarchyResult } from '../models.js';
 
 /**