@scolladon/tsgit 1.3.0 → 2.0.1

package/dist/types/chunks/progress-7KKiXXfX.d.ts

@@ -0,0 +1,405 @@
+import { c as FilePath, O as ObjectId, b as Context, F as FileSystem, H as HashService, C as Compressor, P as ProgressReporter } from './context-CCL0_F8R.js';
+import { F as FileMode, a as Tree } from './reflog-entry-CSzjnZd4.js';
+import { G as GitIndex } from './index-entry-UD4dvtKh.js';
+import { H as HttpTransport } from './http-transport--_NdQOiw.js';
+
+/**
+ * Platform-abstracted stat shape for working-tree entries. Aligns with
+ * `src/ports/file-system.ts:FileStat` — `mtimeNs` and `ino` are optional so
+ * the browser adapter (which exposes neither) can satisfy the shape.
+ *
+ * `mode` is included so race detection covers chmod-only changes
+ * (executable-bit flips, permission tweaks). Racy-stat detection prefers
+ * `mtimeNs` when present, falls back to `mtimeMs`, and falls back further
+ * to SHA-trailer comparison for the index file specifically.
+ */
+interface WorkdirStat {
+    readonly mode: FileMode;
+    readonly size: number;
+    readonly mtimeMs: number;
+    readonly mtimeNs?: bigint;
+    readonly ino?: bigint;
+}
+/**
+ * Pure data shape for a working-tree row. `kind` discriminates the four
+ * entry shapes the walker emits; the surfaced `mode` field mirrors
+ * `stat.mode` for ergonomic access.
+ */
+interface WorkdirEntryRow {
+    readonly source: 'workdir';
+    readonly path: FilePath;
+    readonly mode: FileMode;
+    readonly kind: 'file' | 'symlink' | 'directory' | 'submodule';
+    readonly stat: WorkdirStat;
+}
+
+/** A compiled glob — `test` reports whether a path matches the pattern. */
+interface GlobMatcher {
+    test(path: string): boolean;
+}
+
+interface PathspecEntry {
+    /** Original raw pattern (including any leading `!`), for diagnostics. */
+    readonly pattern: string;
+    /** Pattern with the leading `!` (if any) stripped — the part that compiled to `compiled`. */
+    readonly body: string;
+    /** True when the original pattern started with `!`. */
+    readonly negated: boolean;
+    /**
+     * True when the body (post-`!`) contains no glob metacharacters.
+     * Literal entries match the exact path AND any descendant — Git's
+     * `git add src` semantics where `src` covers everything under it.
+     */
+    readonly isLiteral: boolean;
+    /** Compiled glob matcher. Always tested against the candidate path verbatim. */
+    readonly compiled: GlobMatcher;
+}
+type Pathspec = ReadonlyArray<PathspecEntry>;
+
+/**
+ * Three index-entry boolean flags lifted out of git's wire format. Each is
+ * a real index attribute; they collectively cover the bits status / add /
+ * checkout consult.
+ *
+ * - `assumeUnchanged` (git-update-index `--assume-unchanged`): the user has
+ *   promised the file does not change; tools may skip stat checks.
+ * - `skipWorktree` (sparse-checkout): the file is tracked but should not be
+ *   materialized in the working tree.
+ * - `intentToAdd` (`git add --intent-to-add`): the entry exists with mode +
+ *   path but its content has not yet been staged; oid is the empty blob.
+ */
+interface IndexFlags {
+    readonly assumeUnchanged: boolean;
+    readonly skipWorktree: boolean;
+    readonly intentToAdd: boolean;
+}
+/**
+ * Stat snapshot persisted alongside each index entry by git's stat-cache.
+ * May be stale (the file may have been modified since the index was
+ * written); validity is determined by comparing against a fresh `lstat`
+ * per git's racy-stat rules. Fields mirror the optional-precision shape
+ * already used by `src/ports/file-system.ts:FileStat`.
+ */
+interface IndexCachedStat {
+    readonly mtimeMs: number;
+    readonly mtimeNs?: bigint;
+    readonly size: number;
+    readonly ino?: bigint;
+}
+/**
+ * Pure data shape for an index-source row. Stage > 0 means the entry is
+ * part of an unmerged path (1 = base, 2 = ours, 3 = theirs); stage 0 is
+ * the resolved / normal entry.
+ */
+interface IndexEntryRow {
+    readonly source: 'index';
+    readonly path: FilePath;
+    readonly oid: ObjectId;
+    readonly mode: FileMode;
+    readonly stage: 0 | 1 | 2 | 3;
+    readonly flags: IndexFlags;
+    readonly cachedStat?: IndexCachedStat;
+}
+
+/**
+ * Discriminator for snapshot sources. Each `Snapshot` handle carries a
+ * `kind` field so consumers can dispatch on the underlying source at
+ * runtime (matching the static discriminator on the entry's `source` field).
+ *
+ * Compound state heads (`mergeHead`, `cherryPickHead`, etc.) resolve to a
+ * tree but advertise their own kind so callers can distinguish a
+ * fresh-cloned `head` from a `mergeHead` at the snapshot-handle level.
+ */
+type SnapshotKind = 'tree' | 'commit' | 'index' | 'workdir' | 'mergeHead' | 'cherryPickHead' | 'revertHead' | 'fetchHead' | 'stash';
+
+/**
+ * Pure data shape for a tree-source row. Carried inside `TreeEntry`
+ * (application tier) which adds I/O methods. Domain layering rule:
+ * this file has zero outward imports beyond `domain/objects/`.
+ */
+interface TreeEntryRow {
+    readonly source: 'tree';
+    readonly path: FilePath;
+    readonly oid: ObjectId;
+    readonly mode: FileMode;
+    readonly kind: 'file' | 'symlink' | 'submodule';
+}
+
+/**
+ * Options shared by every resolver port. The `bypassCache` flag asks a
+ * caching adapter to skip its cache for this call; raw adapters ignore it.
+ */
+interface ResolveOptions {
+    readonly bypassCache?: boolean;
+}
+/**
+ * Predicate used by `WorkdirEnumerator` to prune working-tree traversal.
+ * Mirrors the existing `WalkIgnorePredicate` shape (14.3) so the same
+ * `repo.ignoreMatcher()` builder can be used at both the legacy walker
+ * surface and the new snapshot surface.
+ *
+ * Invoked on every directory BEFORE descent (returning `true` prunes the
+ * entire subtree, skipping its `lstat` cost) and on every leaf BEFORE
+ * yielding (returning `true` drops the leaf). Composes with `paths`
+ * (pathspec inclusion filter) via logical AND.
+ */
+type WalkIgnorePredicate = (path: FilePath, isDirectory: boolean) => boolean | Promise<boolean>;
+/**
+ * Options for `WorkdirEnumerator.enumerate`. The snapshot layer translates
+ * `WorkdirSnapshotOptions` (which carries higher-level concerns like
+ * `consistency`) down to this shape; the enumerator port itself stays
+ * focused on what to enumerate.
+ */
+interface WorkdirEnumOptions {
+    readonly paths?: Pathspec;
+    readonly excludes?: WalkIgnorePredicate;
+    readonly maxDepth?: number;
+    readonly maxEntries?: number;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Resolves `.git/index` to its parsed `GitIndex` structure. Caching
+ * adapters (see `src/adapters/snapshot-resolvers/caching-index-resolver.ts`)
+ * implement freshness via the `WriteEventStream` + `GenerationView` ports;
+ * raw adapters parse on every call.
+ *
+ * Callers MUST treat the returned value as deeply frozen — implementations
+ * are free to share the same `GitIndex` reference across calls.
+ */
+interface IndexResolver {
+    resolve(ctx: Context, opts?: ResolveOptions): Promise<GitIndex>;
+}
+/**
+ * Resolves a tree object by its oid. Caching adapters use a content-addressed
+ * LRU (oids are immutable, no invalidation needed). Throws on type
+ * mismatch — the oid must address a tree.
+ */
+interface TreeResolver {
+    resolve(ctx: Context, treeId: ObjectId, opts?: ResolveOptions): Promise<Tree>;
+}
+/**
+ * Streams working-tree entries in canonical git path order. Honors
+ * `ctx.signal` and the optional `opts.signal`; aborts surface as
+ * `operationAborted()` from the iterator.
+ */
+interface WorkdirEnumerator {
+    enumerate(ctx: Context, opts: WorkdirEnumOptions): AsyncIterable<WorkdirEntryRow>;
+}
+
+/**
+ * Application-tier wrapper around `IndexEntryRow`. Inherits the sync data
+ * fields (path/oid/mode/stage/flags/cachedStat) and adds `read()`, which
+ * pulls the blob bytes by oid via the existing object resolver chain.
+ *
+ * Index entries' `cachedStat` reflects the index's stat-cache; it MAY
+ * disagree with the live filesystem. Consumers that need fresh stat
+ * data should consult a `WorkdirSnapshot` instead.
+ */
+interface IndexEntry extends IndexEntryRow {
+    read(): Promise<Uint8Array>;
+}
+
+/**
+ * Application-tier wrapper around `TreeEntryRow`. Inherits the sync data
+ * fields (path/oid/mode/kind) and adds the I/O method `read()`, which
+ * pulls the blob bytes for this entry's oid via the existing object
+ * resolver chain.
+ *
+ * Each entry binds to the `Context` it was created with. Holding an entry
+ * past its context's lifetime is undefined — the resolver may reject the
+ * read with an aborted-operation error if the context's signal fires.
+ */
+interface TreeEntry extends TreeEntryRow {
+    read(): Promise<Uint8Array>;
+}
+
+/**
+ * Application-tier wrapper around `WorkdirEntryRow`. Inherits the sync
+ * data fields (path/mode/kind/stat) and adds four named I/O methods:
+ *
+ * - `hash()`  — reads the file, computes its blob-hash (`blob <size>\0` +
+ *               bytes hashed by `ctx.hash`). For a symlink, hashes the
+ *               link target bytes (git's convention).
+ * - `read()`  — raw file bytes (no hash). For a symlink, returns the
+ *               target as UTF-8 bytes.
+ * - `readLink()` — symlink target string. Throws `UNSUPPORTED_OPERATION`
+ *               when `kind !== 'symlink'`.
+ * - `verify()` — re-`lstat`s the entry; throws `WORKDIR_RACE` if any
+ *               of `(mode, size, mtimeMs)` differs from the row's
+ *               original stat. The opt-in race-detection hook for
+ *               `add -p` / `checkout --detect-races` style callers.
+ *
+ * Each entry binds to the `Context` it was created with; the absolute
+ * workdir path is computed once at creation and shared by every method.
+ */
+interface WorkdirEntry extends WorkdirEntryRow {
+    hash(): Promise<ObjectId>;
+    read(): Promise<Uint8Array>;
+    readLink(): Promise<string>;
+    verify(): Promise<void>;
+}
+
+/**
+ * Lazy, atomic-iteration view of a row source (tree / index / workdir / …).
+ * Snapshots are descriptions, not data — no I/O happens until the consumer
+ * starts iterating. See design §8 and ADR-149.
+ *
+ * Iteration-stability invariant: once a snapshot's `entries()` resolves its
+ * underlying source on the first iteration, every subsequent iteration on
+ * the same handle replays from that captured source. Concurrent writes
+ * routed through `WriteEventEmitter.emit(scope)` invalidate the underlying
+ * resolver cache for *new* snapshots but never disturb in-flight iterations.
+ */
+interface Snapshot<E extends SnapshotEntry> {
+    readonly kind: SnapshotKind;
+    entries(opts?: SnapshotOptions): AsyncIterable<E>;
+}
+type SnapshotEntry = TreeEntry | IndexEntry | WorkdirEntry;
+type TreeSnapshot = Snapshot<TreeEntry>;
+type IndexSnapshot = Snapshot<IndexEntry>;
+type WorkdirSnapshot = Snapshot<WorkdirEntry>;
+interface SnapshotOptions {
+    readonly paths?: Pathspec;
+    readonly recurse?: boolean;
+    readonly maxDepth?: number;
+    readonly maxEntries?: number;
+    readonly bypassCache?: boolean;
+    readonly signal?: AbortSignal;
+}
+
+/**
+ * A point-in-time view of a stash entry. The trio (index, workdir,
+ * untracked) is exposed as plain properties — discoverable at hand-out
+ * time, not behind a method (ADR-156 + design §9.1).
+ *
+ * `untracked` is `null` when the stash was created without
+ * `--include-untracked`. Consumers branch on the property's value, not
+ * on whether a method exists.
+ */
+interface StashSnapshot {
+    readonly kind: 'stash';
+    readonly index: TreeSnapshot;
+    readonly workdir: TreeSnapshot;
+    readonly untracked: TreeSnapshot | null;
+}
+declare const createStashSnapshot: (parts: {
+    readonly index: TreeSnapshot;
+    readonly workdir: TreeSnapshot;
+    readonly untracked: TreeSnapshot | null;
+}) => StashSnapshot;
+
+interface WorkdirSnapshotOptions extends SnapshotOptions {
+    readonly excludes?: WalkIgnorePredicate;
+    readonly consistency?: 'eager' | 'verified';
+}
+interface WorkdirSnapshotDeps {
+    readonly ctx: Context;
+    readonly enumerator: WorkdirEnumerator;
+}
+/**
+ * Lazily streams working-tree entries via `WorkdirEnumerator`. Excludes
+ * and consistency are captured at factory time (per design §8.2 boundary
+ * table); the iteration-level option bundle accepts only the base
+ * `SnapshotOptions` overrides.
+ *
+ *   - `'eager'` (default) — stream rows straight from the enumerator;
+ *     race detection is opt-in via `entry.verify()` per row.
+ *   - `'verified'` — drain the enumerator into an array first, then
+ *     yield in stored order. Provides an atomic point-in-time view of
+ *     which paths existed at enumerate-time; per-row content is still
+ *     subject to mutation between yield and consumption.
+ *
+ * `bypassCache` and `recurse` are no-ops here — the working tree has
+ * no resolver cache, and enumeration is inherently recursive.
+ */
+declare const createWorkdirSnapshot: (deps: WorkdirSnapshotDeps, fixed?: WorkdirSnapshotOptions) => Snapshot<WorkdirEntry>;
+
+interface SnapshotFactoryDeps {
+    readonly ctx: Context;
+    readonly indexResolver: IndexResolver;
+    readonly treeResolver: TreeResolver;
+    readonly workdirEnumerator: WorkdirEnumerator;
+}
+interface SnapshotFactory {
+    head(opts?: SnapshotOptions): TreeSnapshot;
+    commit(oid: ObjectId, opts?: SnapshotOptions): TreeSnapshot;
+    tree(oid: ObjectId, opts?: SnapshotOptions): TreeSnapshot;
+    index(opts?: SnapshotOptions): IndexSnapshot;
+    workdir(opts?: WorkdirSnapshotOptions): WorkdirSnapshot;
+    mergeHead(opts?: SnapshotOptions): Promise<TreeSnapshot | null>;
+    cherryPickHead(opts?: SnapshotOptions): Promise<TreeSnapshot | null>;
+    revertHead(opts?: SnapshotOptions): Promise<TreeSnapshot | null>;
+    fetchHead(opts?: SnapshotOptions): Promise<TreeSnapshot | null>;
+    stashEntry(stashIndex: number, opts?: SnapshotOptions): Promise<StashSnapshot | null>;
+}
+/**
+ * Pulls the resolvers, enumerator, and `Context` together behind a
+ * single facade. Every factory method either is purely synchronous
+ * (`head`, `commit`, `tree`, `index`, `workdir`) or returns a promise
+ * solely because it has to check ref-file existence first. None of
+ * them parse the underlying source until the returned snapshot is
+ * iterated (design §9 construction discipline).
+ */
+declare const createSnapshotFactory: (deps: SnapshotFactoryDeps) => SnapshotFactory;
+
+/**
+ * The four adapter ports the facade plumbs into the Context. Each runtime
+ * shim (`index.node.ts`, `index.browser.ts`, `index.default.ts` — wired in
+ * Step 5) provides a `detectAdapter(): AdapterSet` that returns the runtime-
+ * appropriate set.
+ */
+interface AdapterSet {
+    readonly fs: FileSystem;
+    readonly hash: HashService;
+    readonly compressor: Compressor;
+    readonly transport: HttpTransport;
+}
+/**
+ * Prototype-pollution-safe runtime check. Returns true only when `process` is
+ * an object that owns BOTH `versions` and `versions.node` as own properties —
+ * an attacker who pollutes `Object.prototype.versions` cannot make this
+ * return true.
+ *
+ * Used as a manual fallback only; the primary detection mechanism is
+ * `package.json` conditional exports (resolved at bundle time, immune to
+ * runtime pollution).
+ */
+declare const isNode: () => boolean;
+/**
+ * Returns true when both `window` and `navigator` exist AS OWN globals on
+ * `globalThis` AND have non-undefined values. Two-stage check:
+ * - `hasOwn` rejects properties inherited from a polluted `Object.prototype`.
+ * - `typeof` rejects own properties that have been assigned `undefined`
+ *   (e.g., test harnesses that stub the global to undefined).
+ */
+declare const isBrowser: () => boolean;
+/**
+ * Three-way runtime classification used by manual call sites. Node takes
+ * precedence over browser when both look present (e.g., test environments
+ * with jsdom + a real Node process).
+ */
+declare const detectRuntime: () => "node" | "browser" | "memory";
+
+/** No-op reporter — default when the caller does not provide one. */
+declare const noopProgress: ProgressReporter;
+/**
+ * Built-in reporter that emits one line per call to a user-supplied `sink`.
+ *
+ * Format:
+ *   start(op)             → "<safeOp>: start"
+ *   start(op, total)      → "<safeOp>: start/<total>"
+ *   update(op, c)         → "<safeOp>: <c>"
+ *   update(op, c, t)      → "<safeOp>: <c>/<t>"
+ *   update(op, c, t, txt) → "<safeOp>: <c>/<t> <safeText>"
+ *   end(op)               → "<safeOp>: done"
+ *
+ * `op` is sanitized identically to `text` (defense-in-depth: a programming bug
+ * that wires a sideband-derived string into `op` cannot inject control characters).
+ *
+ * A throwing `sink` cannot crash the reporter — every call is wrapped in
+ * try/catch.
+ */
+declare const consoleProgress: (sink: (line: string) => void) => ProgressReporter;
+
+export { isNode as a, consoleProgress as c, detectRuntime as d, isBrowser as i, noopProgress as n, createSnapshotFactory as u, createStashSnapshot as v, createWorkdirSnapshot as w };
+export type { AdapterSet as A, IndexResolver as I, ResolveOptions as R, SnapshotFactory as S, TreeResolver as T, WalkIgnorePredicate as W, Snapshot as b, IndexEntry as e, SnapshotEntry as f, TreeEntry as g, IndexSnapshot as h, SnapshotFactoryDeps as j, SnapshotOptions as k, StashSnapshot as l, TreeSnapshot as m, WorkdirEntry as o, WorkdirEnumOptions as p, WorkdirEnumerator as q, WorkdirSnapshot as r, WorkdirSnapshotDeps as s, WorkdirSnapshotOptions as t };