@gitkraken/core-gitlens 0.6.0 → 0.7.0

package/dist/git/providers/maintenance.d.ts

@@ -1,3 +1,4 @@
+//#region ../git/src/providers/maintenance.d.ts
 /**
  * Git maintenance / optimization sub-provider — the data plane behind the Git Health feature.
  *
@@ -28,195 +29,196 @@ export type GitOptimizationId = 'untrackedCache' | 'fsmonitor' | 'backgroundMain
  * across worktrees (keyed by common path). Everything here is derivable without inflating objects.
  */
 export interface GitHealthSnapshot {
-    /** Repository shape that changes how the remaining measurements should be interpreted. */
-    readonly repository: {
-        /** Whether local history stops at an intentional shallow boundary; `undefined` when detection failed. */
-        readonly shallow: boolean | undefined;
-        /** Whether missing objects may be supplied by a promisor remote; `undefined` when detection failed. */
-        readonly partial: boolean | undefined;
-        /** Whether the worktree is populated from a sparse specification; `undefined` when config was unreadable. */
-        readonly sparseCheckout: boolean | undefined;
-        /** Whether sparse checkout uses directory-based cone mode; `undefined` when config was unreadable. */
-        readonly sparseCheckoutCone: boolean | undefined;
-        /** Whether the index is configured to use sparse-directory entries; `undefined` when config was unreadable. */
-        readonly sparseIndex: boolean | undefined;
-        /** Whether this worktree uses a split index; `undefined` when detection failed. */
-        readonly splitIndex: boolean | undefined;
-        /** Reference storage selected by the repository format. */
-        readonly refFormat: 'files' | 'reftable' | 'unknown';
-    };
-    /** Bounded loose-reference count for the files ref backend; exact unless the probe reached its cap. */
-    readonly looseRefs: {
-        readonly count: number;
-        readonly exact: boolean;
-    };
-    /** Presence + mtime of `objects/info/commit-graph` (or the split `commit-graphs/` chain), and changed-path Bloom filter state. */
-    readonly commitGraph: {
-        readonly present: boolean;
-        readonly mtime: number | undefined;
-        /** Whether the NEWEST graph layer carries changed-path Bloom filters (`BIDX` chunk). */
-        readonly changedPaths: boolean;
-        /** Whether this repo can write them (Git 2.31+ and not a partial clone). */
-        readonly changedPathsSupported: boolean;
-        /** `true` once the user disabled GitLens's automatic commit-graph maintenance for this repo (`gk.commitGraphDisabled`). */
-        readonly disabled: boolean;
-        /**
-         * `true` when `core.commitGraph` is EXPLICITLY false in the user's git config — git won't read the
-         * cache, and `ensureCommitGraph` honors the same setting as a write opt-out, so the view must not
-         * claim the graph is (or will be) maintained.
-         */
-        readonly readDisabled: boolean;
-    };
-    /** Presence of a classic or incremental multi-pack-index. */
-    readonly multiPackIndex: boolean;
-    /** Whether Git is configured to read/write the multi-pack-index; `undefined` when config was unreadable. */
-    readonly multiPackIndexEnabled: boolean | undefined;
-    /** Count of `*.pack` files in `objects/pack`. */
-    readonly packCount: number;
-    /** Pack files not represented by the active multi-pack-index; `undefined` when it could not be established. */
-    readonly packsOutsideMultiPackIndex: number | undefined;
-    /** Effective `maintenance.incremental-repack.auto` threshold; `undefined` when invalid or unreadable. */
-    readonly incrementalRepackAutoThreshold: number | undefined;
-    /** Total bytes of all `*.pack` files. */
-    readonly packBytes: number;
-    /** Raw loose-object sample (a handful of the 256 fanout dirs); the host extrapolates the estimate. */
-    readonly looseObjects: {
-        readonly objectsInSampledDirs: number;
-        readonly dirsSampled: number;
-    };
-    /** Size of the worktree index in bytes (including the largest shared base for a split index). */
-    readonly indexBytes: number;
+  /** Repository shape that changes how the remaining measurements should be interpreted. */
+  readonly repository: {
+    /** Whether local history stops at an intentional shallow boundary; `undefined` when detection failed. */
+    readonly shallow: boolean | undefined;
+    /** Whether missing objects may be supplied by a promisor remote; `undefined` when detection failed. */
+    readonly partial: boolean | undefined;
+    /** Whether the worktree is populated from a sparse specification; `undefined` when config was unreadable. */
+    readonly sparseCheckout: boolean | undefined;
+    /** Whether sparse checkout uses directory-based cone mode; `undefined` when config was unreadable. */
+    readonly sparseCheckoutCone: boolean | undefined;
+    /** Whether the index is configured to use sparse-directory entries; `undefined` when config was unreadable. */
+    readonly sparseIndex: boolean | undefined;
+    /** Whether this worktree uses a split index; `undefined` when detection failed. */
+    readonly splitIndex: boolean | undefined;
+    /** Reference storage selected by the repository format. */
+    readonly refFormat: 'files' | 'reftable' | 'unknown';
+  };
+  /** Bounded loose-reference count for the files ref backend; exact unless the probe reached its cap. */
+  readonly looseRefs: {
+    readonly count: number;
+    readonly exact: boolean;
+  };
+  /** Presence + mtime of `objects/info/commit-graph` (or the split `commit-graphs/` chain), and changed-path Bloom filter state. */
+  readonly commitGraph: {
+    readonly present: boolean;
+    readonly mtime: number | undefined;
+    /** Whether the NEWEST graph layer carries changed-path Bloom filters (`BIDX` chunk). */
+    readonly changedPaths: boolean;
+    /** Whether this repo can write them (Git 2.31+ and not a partial clone). */
+    readonly changedPathsSupported: boolean;
+    /** `true` once the user disabled GitLens's automatic commit-graph maintenance for this repo (`gk.commitGraphDisabled`). */
+    readonly disabled: boolean;
     /**
-     * Entry count from the index header (`DIRC`, version, count — all big-endian). For a normal index this is
-     * the exact tracked-file count; for a sparse index it counts the populated working set plus sparse-directory
-     * entries. It is deliberately `undefined` for a split index, whose header covers only its mutable layer,
-     * and during conflicts, whose stage entries duplicate paths.
+     * `true` when `core.commitGraph` is EXPLICITLY false in the user's git config — git won't read the
+     * cache, and `ensureCommitGraph` honors the same setting as a write opt-out, so the view must not
+     * claim the graph is (or will be) maintained.
      */
-    readonly indexEntryCount: number | undefined;
-    /** How {@link indexEntryCount} should be interpreted. */
-    readonly indexEntryCountType: 'full' | 'sparse' | 'split' | 'conflicted' | 'unavailable';
-    /** Current state of the config levers this feature toggles. */
-    readonly config: {
-        readonly fsmonitor: boolean;
-        readonly untrackedCache: boolean;
-        /**
-         * Whether `core.untrackedCache` carries an explicit value in ANY scope (local/global/system).
-         * {@link untrackedCache} alone can't tell "unset" from a deliberate `false`/`keep`, and this is the
-         * one lever the auto tier applies silently — so it only ever fills in an unset value.
-         */
-        readonly untrackedCacheConfigured: boolean;
-        readonly manyFiles: boolean;
-    };
+    readonly readDisabled: boolean;
+  };
+  /** Presence of a classic or incremental multi-pack-index. */
+  readonly multiPackIndex: boolean;
+  /** Whether Git is configured to read/write the multi-pack-index; `undefined` when config was unreadable. */
+  readonly multiPackIndexEnabled: boolean | undefined;
+  /** Count of `*.pack` files in `objects/pack`. */
+  readonly packCount: number;
+  /** Pack files not represented by the active multi-pack-index; `undefined` when it could not be established. */
+  readonly packsOutsideMultiPackIndex: number | undefined;
+  /** Effective `maintenance.incremental-repack.auto` threshold; `undefined` when invalid or unreadable. */
+  readonly incrementalRepackAutoThreshold: number | undefined;
+  /** Total bytes of all `*.pack` files. */
+  readonly packBytes: number;
+  /** Raw loose-object sample (a handful of the 256 fanout dirs); the host extrapolates the estimate. */
+  readonly looseObjects: {
+    readonly objectsInSampledDirs: number;
+    readonly dirsSampled: number;
+  };
+  /** Size of the worktree index in bytes (including the largest shared base for a split index). */
+  readonly indexBytes: number;
+  /**
+   * Entry count from the index header (`DIRC`, version, count — all big-endian). For a normal index this is
+   * the exact tracked-file count; for a sparse index it counts the populated working set plus sparse-directory
+   * entries. It is deliberately `undefined` for a split index, whose header covers only its mutable layer,
+   * and during conflicts, whose stage entries duplicate paths.
+   */
+  readonly indexEntryCount: number | undefined;
+  /** How {@link indexEntryCount} should be interpreted. */
+  readonly indexEntryCountType: 'full' | 'sparse' | 'split' | 'conflicted' | 'unavailable';
+  /** Current state of the config levers this feature toggles. */
+  readonly config: {
+    readonly fsmonitor: boolean;
+    readonly untrackedCache: boolean;
     /**
-     * Whether this repo is registered for system-scheduled `git maintenance` (global `maintenance.repo`).
-     * `undefined` when the registration list could not be read — never treat that as "not registered": a
-     * repo the user registered themselves would read as unregistered, get suggested again, and a later
-     * Undo would silently remove their registration.
+     * Whether `core.untrackedCache` carries an explicit value in ANY scope (local/global/system).
+     * {@link untrackedCache} alone can't tell "unset" from a deliberate `false`/`keep`, and this is the
+     * one lever the auto tier applies silently — so it only ever fills in an unset value.
      */
-    readonly maintenanceRegistered: boolean | undefined;
-    /** `true` once FSMonitor failed to enable here (from the `gk.fsmonitorNotApplicable` marker) — never re-suggest. */
-    readonly fsmonitorNotApplicable: boolean;
-    /** `true` once the untracked cache failed git's filesystem probe here (`gk.untrackedCacheNotApplicable`) — never re-suggest. */
-    readonly untrackedCacheNotApplicable: boolean;
-    /**
-     * Which levers GitLens itself applied (from the `gk.applied.*` ownership markers). Lets the view render a
-     * lever the user turned on themselves as "already enabled" (no Undo) versus one GitLens applied (Apply/Undo).
-     * Distinct from {@link config}, which reports the effective state regardless of who set it.
-     */
-    readonly applied: {
-        readonly untrackedCache: boolean;
-        readonly fsmonitor: boolean;
-        readonly manyFiles: boolean;
-        readonly backgroundMaintenance: boolean;
-        /** Worktree-scoped ownership; sparse indexes are not shared between linked worktrees. */
-        readonly sparseIndex: boolean;
-    };
-    /** Whether the installed git supports `git maintenance run` (2.30+) — gates the auto-tier tasks. */
-    readonly supportsMaintenanceRun: boolean;
-    /** Whether the installed git includes the `pack-refs` maintenance task (2.31+). */
-    readonly supportsPackRefsMaintenance: boolean;
+    readonly untrackedCacheConfigured: boolean;
+    readonly manyFiles: boolean;
+  };
+  /**
+   * Whether this repo is registered for system-scheduled `git maintenance` (global `maintenance.repo`).
+   * `undefined` when the registration list could not be read — never treat that as "not registered": a
+   * repo the user registered themselves would read as unregistered, get suggested again, and a later
+   * Undo would silently remove their registration.
+   */
+  readonly maintenanceRegistered: boolean | undefined;
+  /** `true` once FSMonitor failed to enable here (from the `gk.fsmonitorNotApplicable` marker) — never re-suggest. */
+  readonly fsmonitorNotApplicable: boolean;
+  /** `true` once the untracked cache failed git's filesystem probe here (`gk.untrackedCacheNotApplicable`) — never re-suggest. */
+  readonly untrackedCacheNotApplicable: boolean;
+  /**
+   * Which levers GitLens itself applied (from the `gk.applied.*` ownership markers). Lets the view render a
+   * lever the user turned on themselves as "already enabled" (no Undo) versus one GitLens applied (Apply/Undo).
+   * Distinct from {@link config}, which reports the effective state regardless of who set it.
+   */
+  readonly applied: {
+    readonly untrackedCache: boolean;
+    readonly fsmonitor: boolean;
+    readonly manyFiles: boolean;
+    readonly backgroundMaintenance: boolean;
+    /** Worktree-scoped ownership; sparse indexes are not shared between linked worktrees. */
+    readonly sparseIndex: boolean;
+  };
+  /** Whether the installed git supports `git maintenance run` (2.30+) — gates the auto-tier tasks. */
+  readonly supportsMaintenanceRun: boolean;
+  /** Whether the installed git includes the `pack-refs` maintenance task (2.31+). */
+  readonly supportsPackRefsMaintenance: boolean;
 }
 /** On-demand detail computed only when the Git Health view opens (cheap-ish git walks). */
 export interface GitHealthDetails {
-    /** `git rev-list --count --all` — total reachable commits. `undefined` if the walk failed. */
-    readonly commitCount: number | undefined;
-    /**
-     * Parsed `git count-objects -v` breakdown. `undefined` if it failed. The `size`, `sizePack`, and
-     * `sizeGarbage` fields are normalized to BYTES — git itself reports them in KiB.
-     */
-    readonly countObjects: {
-        readonly count: number;
-        readonly size: number;
-        readonly inPack: number;
-        readonly packs: number;
-        readonly sizePack: number;
-        readonly prunePackable: number;
-        readonly garbage: number;
-        readonly sizeGarbage: number;
-    } | undefined;
+  /** `git rev-list --count --all` — total reachable commits. `undefined` if the walk failed. */
+  readonly commitCount: number | undefined;
+  /**
+   * Parsed `git count-objects -v` breakdown. `undefined` if it failed. The `size`, `sizePack`, and
+   * `sizeGarbage` fields are normalized to BYTES — git itself reports them in KiB.
+   */
+  readonly countObjects: {
+    readonly count: number;
+    readonly size: number;
+    readonly inPack: number;
+    readonly packs: number;
+    readonly sizePack: number;
+    readonly prunePackable: number;
+    readonly garbage: number;
+    readonly sizeGarbage: number;
+  } | undefined;
 }
 /** Whether a given optimization lever is available for a repo, with a user-facing reason when it isn't. */
 export interface GitOptimizationCapability {
-    readonly id: GitOptimizationId;
-    readonly supported: boolean;
-    /** Present only when `supported` is `false` — why (git version, platform, virtual FS). */
-    readonly reason?: string;
-    /** Optional caveat to surface even when supported (e.g. `manyFiles` enabling an index older tools can't read). */
-    readonly note?: string;
+  readonly id: GitOptimizationId;
+  readonly supported: boolean;
+  /** Present only when `supported` is `false` — why (git version, platform, virtual FS). */
+  readonly reason?: string;
+  /** Optional caveat to surface even when supported (e.g. `manyFiles` enabling an index older tools can't read). */
+  readonly note?: string;
 }
 export interface GitMaintenanceSubProvider {
-    /** Cheap filesystem + config probe of the repo's object store and lever states. */
-    getHealthSnapshot(repoPath: string, cancellation?: AbortSignal): Promise<GitHealthSnapshot>;
-    /** On-demand commit count + `count-objects` breakdown (only when the view opens). */
-    getHealthDetails(repoPath: string, cancellation?: AbortSignal): Promise<GitHealthDetails>;
-    /** Availability of each optimization lever (git version + platform gated). */
-    getCapabilities(repoPath: string): Promise<GitOptimizationCapability[]>;
-    /**
-     * Hint that a task's cache is worth refreshing now, applying that task's cadence policy. Callers normally
-     * ignore the returned promise; consumers that need freshness may await it. It resolves `true` only when a
-     * write completed and `false` when a supported request was gated or failed, and never rejects.
-     * `commit-graph` runs the demand cadence (minutes throttle + single-flight, both keyed by common git dir),
-     * fully gated on the auto-tier switches; `loose-objects`/`incremental-repack` are no-ops here (the daily
-     * pass owns them) and return `undefined`.
-     */
-    request(repoPath: string, task: GitMaintenanceTask): Promise<boolean> | undefined;
-    /**
-     * Atomically claims the once-per-`intervalMs` maintenance pass for this repo, stamping the shared
-     * `gk.maintenanceLastRun` if and only if the claim succeeds. Returns `false` when another window already
-     * holds it. Read-then-write from the host would not be atomic across VS Code windows, so the claim lives
-     * here where it can be taken under a real file lock.
-     */
-    claimMaintenancePass(repoPath: string, intervalMs: number): Promise<boolean>;
-    /**
-     * Runs a single maintenance task. Resolves `true` when a supported invocation completed and `false` when
-     * it is not applicable. With `auto`, Git evaluates its native condition and may intentionally do no work.
-     * A genuine command failure THROWS. `commit-graph` writes directly (2.24+); other tasks go through
-     * `git maintenance run --task=…` (2.30+).
-     */
-    runMaintenanceTask(repoPath: string, task: GitMaintenanceTask, options?: {
-        readonly auto?: boolean;
-        readonly cancellation?: AbortSignal;
-    }): Promise<boolean>;
-    /**
-     * Applies an optimization lever. Returns `true` when it took effect; `false` for a legitimate
-     * not-applicable outcome (e.g. the FSMonitor daemon wouldn't start, or the untracked cache failed git's
-     * filesystem probe — the config is restored and the repo recorded not-applicable so it's never
-     * re-suggested). A genuine command failure (config write refused, `maintenance start` errored) THROWS.
-     * Before mutating, the lever's prior value is recorded so {@link revertOptimization} can restore it.
-     */
-    applyOptimization(repoPath: string, id: GitOptimizationId, cancellation?: AbortSignal): Promise<boolean>;
-    /**
-     * Reverts a lever GitLens applied back to its recorded prior value (never a hardcoded inverse). A no-op
-     * when GitLens didn't apply it (no ownership marker) — a user-enabled lever is never touched. A genuine
-     * command failure THROWS.
-     */
-    revertOptimization(repoPath: string, id: GitOptimizationId, cancellation?: AbortSignal): Promise<void>;
-    /**
-     * Enables or disables GitLens's automatic commit-graph maintenance for this repo — a per-repository off
-     * switch, distinct from the global `gitlens.gitOptimizations.enabled` master switch. Writes the
-     * `gk.commitGraphDisabled` marker when disabling; clears it when re-enabling (tolerating an
-     * already-absent marker). User-clicked, so a genuine write failure THROWS.
-     */
-    setCommitGraphDisabled(repoPath: string, disabled: boolean, cancellation?: AbortSignal): Promise<void>;
+  /** Cheap filesystem + config probe of the repo's object store and lever states. */
+  getHealthSnapshot(repoPath: string, cancellation?: AbortSignal): Promise<GitHealthSnapshot>;
+  /** On-demand commit count + `count-objects` breakdown (only when the view opens). */
+  getHealthDetails(repoPath: string, cancellation?: AbortSignal): Promise<GitHealthDetails>;
+  /** Availability of each optimization lever (git version + platform gated). */
+  getCapabilities(repoPath: string): Promise<GitOptimizationCapability[]>;
+  /**
+   * Hint that a task's cache is worth refreshing now, applying that task's cadence policy. Callers normally
+   * ignore the returned promise; consumers that need freshness may await it. It resolves `true` only when a
+   * write completed and `false` when a supported request was gated or failed, and never rejects.
+   * `commit-graph` runs the demand cadence (minutes throttle + single-flight, both keyed by common git dir),
+   * fully gated on the auto-tier switches; `loose-objects`/`incremental-repack` are no-ops here (the daily
+   * pass owns them) and return `undefined`.
+   */
+  request(repoPath: string, task: GitMaintenanceTask): Promise<boolean> | undefined;
+  /**
+   * Atomically claims the once-per-`intervalMs` maintenance pass for this repo, stamping the shared
+   * `gk.maintenanceLastRun` if and only if the claim succeeds. Returns `false` when another window already
+   * holds it. Read-then-write from the host would not be atomic across VS Code windows, so the claim lives
+   * here where it can be taken under a real file lock.
+   */
+  claimMaintenancePass(repoPath: string, intervalMs: number): Promise<boolean>;
+  /**
+   * Runs a single maintenance task. Resolves `true` when a supported invocation completed and `false` when
+   * it is not applicable. With `auto`, Git evaluates its native condition and may intentionally do no work.
+   * A genuine command failure THROWS. `commit-graph` writes directly (2.24+); other tasks go through
+   * `git maintenance run --task=…` (2.30+).
+   */
+  runMaintenanceTask(repoPath: string, task: GitMaintenanceTask, options?: {
+    readonly auto?: boolean;
+    readonly cancellation?: AbortSignal;
+  }): Promise<boolean>;
+  /**
+   * Applies an optimization lever. Returns `true` when it took effect; `false` for a legitimate
+   * not-applicable outcome (e.g. the FSMonitor daemon wouldn't start, or the untracked cache failed git's
+   * filesystem probe — the config is restored and the repo recorded not-applicable so it's never
+   * re-suggested). A genuine command failure (config write refused, `maintenance start` errored) THROWS.
+   * Before mutating, the lever's prior value is recorded so {@link revertOptimization} can restore it.
+   */
+  applyOptimization(repoPath: string, id: GitOptimizationId, cancellation?: AbortSignal): Promise<boolean>;
+  /**
+   * Reverts a lever GitLens applied back to its recorded prior value (never a hardcoded inverse). A no-op
+   * when GitLens didn't apply it (no ownership marker) — a user-enabled lever is never touched. A genuine
+   * command failure THROWS.
+   */
+  revertOptimization(repoPath: string, id: GitOptimizationId, cancellation?: AbortSignal): Promise<void>;
+  /**
+   * Enables or disables GitLens's automatic commit-graph maintenance for this repo — a per-repository off
+   * switch, distinct from the global `gitlens.gitOptimizations.enabled` master switch. Writes the
+   * `gk.commitGraphDisabled` marker when disabling; clears it when re-enabling (tolerating an
+   * already-absent marker). User-clicked, so a genuine write failure THROWS.
+   */
+  setCommitGraphDisabled(repoPath: string, disabled: boolean, cancellation?: AbortSignal): Promise<void>;
 }
+//#endregion
 //# sourceMappingURL=maintenance.d.ts.map

package/dist/git/providers/maintenance.js

@@ -1,20 +0,0 @@
-/**
- * Git maintenance / optimization sub-provider — the data plane behind the Git Health feature.
- *
- * Two tiers of levers (see `.work/dev/git-health/spec.md`):
- * - **Auto tier** — inert, repo-local maintenance applied silently: the demand-cadence commit-graph
- *   write and `git maintenance run` one-shots. No config levers — the auto tier never rewrites config.
- * - **Ask tier** — config levers surfaced for one-click apply/undo (`core.untrackedCache`,
- *   `core.fsmonitor`, `git maintenance start`, `feature.manyFiles`).
- *
- * The commit-graph is a task OF this service, not a thing beside it: `MaintenanceGitSubProvider` owns its
- * implementation (a direct `git commit-graph write --reachable --split` — usable at 2.24, unlike the 2.30
- * `maintenance run --task=commit-graph`), its policy, and its demand cadence (minutes throttle + single-flight
- * keyed by common git dir). `GraphGitSubProvider` and the repo-open shape probe merely `request(...)` it.
- *
- * Every method is repo-path-first (so the `RepositoryService` proxy can auto-inject `repoPath`) and
- * `AbortSignal`-able. The provider is optional — it exists only on the desktop CLI provider, so web
- * builds and virtual repos never register it (availability is a per-repo capability, `repo.git.maintenance`).
- */
-export {};
-//# sourceMappingURL=maintenance.js.map