@scolladon/tsgit 0.9.0 → 1.1.0

package/dist/types/primitives/index.d.cts

@@ -1,217 +1,254 @@
-import { O as ObjectId, b as FilePath, a as Context, j as RefName } from '../chunks/context-Ku1aP8Ie.cjs';
-import { A as AuthorIdentity, F as FileMode, T as TreeDiff } from '../chunks/diff-change-BwO75AgS.cjs';
-import '../chunks/http-transport--_NdQOiw.cjs';
-
-interface Blob {
-    readonly type: 'blob';
-    readonly id: ObjectId;
-    readonly content: Uint8Array;
-}
-
-interface ExtraHeader {
-    readonly key: string;
-    readonly value: string;
-}
-interface CommitData {
-    readonly tree: ObjectId;
-    readonly parents: ReadonlyArray<ObjectId>;
-    readonly author: AuthorIdentity;
-    readonly committer: AuthorIdentity;
-    readonly message: string;
-    readonly gpgSignature?: string;
-    readonly extraHeaders: ReadonlyArray<ExtraHeader>;
-}
-interface Commit {
-    readonly type: 'commit';
-    readonly id: ObjectId;
-    readonly data: CommitData;
-}
-
-type ObjectType = 'blob' | 'tree' | 'commit' | 'tag';
-
-interface TagData {
-    readonly object: ObjectId;
-    readonly objectType: ObjectType;
-    readonly tagName: string;
-    readonly tagger?: AuthorIdentity;
-    readonly message: string;
-    readonly gpgSignature?: string;
-    readonly extraHeaders: ReadonlyArray<ExtraHeader>;
-}
-interface Tag {
-    readonly type: 'tag';
-    readonly id: ObjectId;
-    readonly data: TagData;
-}
-
-interface TreeEntry {
-    readonly mode: FileMode;
-    readonly name: string;
-    readonly id: ObjectId;
-}
-interface Tree {
-    readonly type: 'tree';
-    readonly id: ObjectId;
-    readonly entries: ReadonlyArray<TreeEntry>;
-}
-
-type GitObject = Blob | Tree | Commit | Tag;
-
-interface IndexEntryFlags {
-    readonly assumeValid: boolean;
-    readonly extended: boolean;
-    readonly stage: 0 | 1 | 2 | 3;
-}
-interface IndexEntry {
-    readonly ctimeSeconds: number;
-    readonly ctimeNanoseconds: number;
-    readonly mtimeSeconds: number;
-    readonly mtimeNanoseconds: number;
-    readonly dev: number;
-    readonly ino: number;
-    readonly mode: FileMode;
-    readonly uid: number;
-    readonly gid: number;
-    readonly fileSize: number;
-    readonly id: ObjectId;
-    readonly flags: IndexEntryFlags;
-    readonly path: FilePath;
-}
-interface IndexExtension {
-    readonly signature: string;
-    readonly data: Uint8Array;
-}
-interface GitIndex {
-    readonly version: 2;
-    readonly entries: ReadonlyArray<IndexEntry>;
-    readonly extensions: ReadonlyArray<IndexExtension>;
-}
-
-interface RenameDetectOptions {
-    readonly limit?: number;
-    readonly maxSameIdDeletes?: number;
-}
+import { G as GitIndex, I as IndexEntry } from '../chunks/write-tree-DVp0RJ_r.cjs';
+export { C as CreateCommitInput, D as DiffTreesInput, a as DiffTreesOptions, M as MAX_COMMIT_MESSAGE_BYTES, b as MAX_GITIGNORE_BYTES, c as MAX_HAVES, d as MAX_INDEX_BYTES, e as MAX_PEEL_DEPTH, f as MAX_PUSH_OBJECTS, g as MAX_SYMBOLIC_REF_DEPTH, h as MAX_WALK_QUEUE_SIZE, i as MAX_WALK_SEEDS, j as MAX_WORKING_TREE_BLOB_BYTES, R as ReadObjectOptions, k as ResolveRefOptions, U as UpdateRefOptions, W as WalkCommitsOptions, l as WalkIgnorePredicate, m as WalkTreeEntry, n as WalkTreeOptions, o as WalkWorkingTreeEntry, p as WalkWorkingTreeOptions, q as createCommit, r as diffTrees, s as getRepoRoot, t as mergeBase, u as readBlob, v as readIndex, w as readObject, x as readTree, y as resolveRef, z as updateRef, A as walkCommits, B as walkTree, E as walkWorkingTree, F as writeObject, H as writeSymbolicRef, J as writeTree } from '../chunks/write-tree-DVp0RJ_r.cjs';
+import { d as FilePath, O as ObjectId, b as Context } from '../chunks/context-D84z1i5F.cjs';
+import { F as FileMode } from '../chunks/diff-change-Bm1zvVsC.cjs';
+export { T as TreeDiff } from '../chunks/diff-change-Bm1zvVsC.cjs';
+import { b as HttpTransport } from '../chunks/http-transport-DirKfK2S.cjs';
 
 /**
- * Phase 7 primitive option shapes, walker value types, and shared constants.
- * Defined in one location to avoid circular imports between primitive modules.
+ * Pure helper that diffs a current GitIndex against a target tree's flat
+ * entry list and emits an ordered ChangesetEntry list. No FS, no ctx; the
+ * impure write side lives in `apply-changeset.ts`.
+ *
+ * Stage-0 entries only — unmerged stages are invisible to checkout (Phase
+ * 13.1 design step 5).
  */
 
-/** Max symbolic-ref dereferences resolveRef will follow. */
-declare const MAX_SYMBOLIC_REF_DEPTH = 5;
-/** Max tag-peel hops resolveRef / readTree will follow when peeling. */
-declare const MAX_PEEL_DEPTH = 5;
-/** Max seeds walkCommits.from can contain. */
-declare const MAX_WALK_SEEDS = 1024;
-/** Hard cap on walkCommits' pending queue size to prevent unbounded heap growth. */
-declare const MAX_WALK_QUEUE_SIZE: number;
-/** Max .git/index file size readIndex will accept. */
-declare const MAX_INDEX_BYTES: number;
-/** Max commit message byte length createCommit will accept. */
-declare const MAX_COMMIT_MESSAGE_BYTES: number;
-interface ReadObjectOptions {
-    readonly verifyHash?: boolean;
-}
-interface ResolveRefOptions {
-    readonly peel?: boolean;
-    readonly maxSymbolicDepth?: number;
-    readonly maxPeelDepth?: number;
+interface ChangesetEntry {
+    readonly kind: 'add' | 'update' | 'delete' | 'noop';
+    readonly path: FilePath;
+    readonly mode: FileMode;
+    readonly id: ObjectId | undefined;
+    readonly previousId: ObjectId | undefined;
+    readonly previousMode: FileMode | undefined;
 }
-interface UpdateRefOptions {
-    readonly expected?: ObjectId | 'absent';
-    readonly delete?: boolean;
+interface ChangesetStats {
+    readonly add: number;
+    readonly update: number;
+    readonly delete: number;
+    readonly noop: number;
 }
-interface WalkCommitsOptions {
-    readonly from: ReadonlyArray<ObjectId>;
-    readonly until?: ReadonlyArray<ObjectId>;
-    readonly order?: 'topo' | 'first-parent';
-    readonly ignoreMissing?: boolean;
-    readonly verifyHash?: boolean;
+interface Changeset {
+    readonly entries: ReadonlyArray<ChangesetEntry>;
+    readonly stats: ChangesetStats;
 }
-interface WalkTreeEntry {
+interface TargetEntry {
     readonly path: FilePath;
     readonly id: ObjectId;
     readonly mode: FileMode;
 }
-interface WalkTreeOptions {
-    readonly recursive?: boolean;
-    readonly maxDepth?: number;
-    readonly maxEntries?: number;
-}
-interface CreateCommitInput {
-    readonly tree: ObjectId;
-    readonly parents: ReadonlyArray<ObjectId>;
-    readonly author: AuthorIdentity;
-    readonly committer: AuthorIdentity;
-    readonly message: string;
-    readonly gpgSignature?: string;
-    readonly extraHeaders?: ReadonlyArray<ExtraHeader>;
+declare const computeChangeset: (currentIndex: GitIndex, targetTree: ReadonlyArray<TargetEntry>) => Changeset;
+
+interface ApplyChangesetOpts {
+    readonly changeset: Changeset;
+    readonly force: boolean;
+    readonly workdir: string;
 }
-type DiffTreesInput = Tree | ObjectId | undefined;
-interface DiffTreesOptions {
-    readonly detectRenames?: boolean;
-    readonly renameOptions?: RenameDetectOptions;
+interface ApplyChangesetResult {
+    readonly writtenEntries: ReadonlyArray<IndexEntry>;
+    readonly written: number;
+    readonly deleted: number;
 }
+declare const applyChangeset: (ctx: Context, opts: ApplyChangesetOpts) => Promise<ApplyChangesetResult>;
 
-declare function createCommit(ctx: Context, input: CreateCommitInput): Promise<ObjectId>;
+/**
+ * Project a target tree onto a fresh stage-0 IndexEntry list, preserving
+ * stat-cache fields from the prior index where the path's `id` AND `mode`
+ * both match (the "stat-cache donor" strategy).
+ *
+ * Pure with respect to the working tree: this primitive never calls
+ * `fs.lstat`, `fs.read`, or any working-tree-side API. It only reads git
+ * objects via `walkTree` → `readObject` for nested trees.
+ *
+ * Used by `reset --mixed` to rebuild the index from a target
+ * commit's tree. Will be re-used by `reset --hard` composed
+ * with `materializeTree` to also write the working tree.
+ *
+ * ## Preconditions
+ *
+ * `currentIndex` MUST be read under the same `acquireIndexLock` that will
+ * later commit the result. Reading the index BEFORE the lock is acquired
+ * lets a concurrent writer mutate it between the donor-map build and the
+ * commit, producing a result that reflects neither the pre-reset nor the
+ * post-reset state. See `reset.ts:rebuildIndexFromCommit` for the
+ * canonical pattern: acquire → read → build → commit → release-in-finally.
+ */
 
-declare function diffTrees(ctx: Context, a: DiffTreesInput, b: DiffTreesInput, options?: DiffTreesOptions): Promise<TreeDiff>;
+interface BuildIndexFromTreeOpts {
+    readonly targetTree: ObjectId;
+    readonly currentIndex: GitIndex;
+}
+declare const buildIndexFromTree: (ctx: Context, opts: BuildIndexFromTreeOpts) => Promise<ReadonlyArray<IndexEntry>>;
+
+interface BuildPackInput {
+    readonly oids: ReadonlyArray<ObjectId>;
+}
+interface BuildPackResult {
+    readonly bytes: Uint8Array;
+    /** Hex SHA of the pack body, also the trailer (last 20 bytes). */
+    readonly sha: string;
+    readonly objectCount: number;
+}
+declare const buildPack: (ctx: Context, input: BuildPackInput) => Promise<BuildPackResult>;
+
+interface EnumeratePushObjectsInput {
+    /**
+     * Object ids the caller wants on the remote. Each MUST resolve to a
+     * commit or an annotated tag (tags are unwrapped to commits before the
+     * commit walk).
+     */
+    readonly wants: ReadonlyArray<ObjectId>;
+    /** Object ids the remote already has (server's advertised ref tips). */
+    readonly haves: ReadonlyArray<ObjectId>;
+    /** Hard cap on objects emitted. Defaults to MAX_PUSH_OBJECTS. */
+    readonly maxObjects?: number;
+}
+declare function enumeratePushObjects(ctx: Context, input: EnumeratePushObjectsInput): AsyncIterable<ObjectId>;
+
+interface FetchPackInput {
+    /** Advertised refs the caller wants. MUST be non-empty (server-side requirement). */
+    readonly wants: ReadonlyArray<ObjectId>;
+    /** Objects the caller already has (negotiation). Empty for clone, populated for fetch. */
+    readonly haves: ReadonlyArray<ObjectId>;
+    /** Negotiated capabilities (intersection of advertised + supported). */
+    readonly capabilities: ReadonlyArray<string>;
+    /** Base remote URL (the same URL passed to clone). */
+    readonly url: string;
+    /** Progress op label — clone uses 'clone:write-objects', fetch uses 'fetch:write-objects'. */
+    readonly progressOp: string;
+    /**
+     * Shallow clone depth. When set, sends `deepen N` and consumes the
+     * accompanying `shallow <oid>` / `unshallow <oid>` response block.
+     *
+     */
+    readonly depth?: number;
+}
+interface FetchPackResult {
+    readonly packPath: string;
+    readonly idxPath: string;
+    readonly objectCount: number;
+    /** Hex-encoded SHA of the pack trailer; also the on-disk filename stem. */
+    readonly packSha: string;
+    /** Commits the server advertised as new shallow boundaries (empty when depth is unset). */
+    readonly shallow: ReadonlyArray<ObjectId>;
+    /** Commits the server advertised as no-longer-shallow (empty when depth is unset). */
+    readonly unshallow: ReadonlyArray<ObjectId>;
+}
+declare const fetchPack: (ctx: Context, transport: HttpTransport, input: FetchPackInput) => Promise<FetchPackResult>;
 
 /**
- * Compute a merge base — the first commit reachable from BOTH `a` and `b`.
+ * Compose `walkTree → computeChangeset → applyChangeset` to update the
+ * working tree to a target tree's contents.
+ *
+ * - Branch switch mode: `paths === undefined` — diff the entire current
+ *  index against the entire target tree.
+ * - Path-restore mode: `paths !== undefined` — restrict both sides of
+ *  the diff to those paths.
  *
- * Algorithm: bidirectional BFS with two visited sets. After each layer
- * advance, check the intersection. When non-empty, return the
- * lexicographically smallest oid (deterministic tie-breaker).
+ * Returns the new IndexEntry list for the caller to commit, plus
+ * written/deleted counts. The primitive does NOT commit the index — the
+ * caller decides.
  *
- * Returns `undefined` for unrelated histories. Documented limitation: cherry-picks
- * and criss-cross merges may yield non-optimal bases — `recursive`-strategy
- * multi-base resolution is v2.
+ * ## Stat-source contract for `newIndexEntries` (load-bearing for)
+ *
+ * - **Paths that were written/added** (`add` or `update` changeset entries):
+ *  the IndexEntry carries **post-write `lstat`-derived stat fields**
+ *  (ctime/mtime/dev/ino/uid/gid/fileSize). These reflect the file we just
+ *  wrote, so the next `status` runs the fast `isStatClean` path.
+ * - **Paths whose changeset classification was `noop`** (skipped — index
+ *  already matched target by `id + mode`): the IndexEntry is the caller's
+ *  `currentIndex` entry verbatim. Donor stats survive across the call.
+ * - `reset --hard` therefore MUST set `forceRewriteAll: true` so every noop
+ *  upgrades to update and the post-write stats land in the output. Without
+ *  that, a locally-modified working-tree file that the index still records
+ *  as clean would survive the reset, AND the donor stats would be stale
+ *  relative to the actual disk state.
  */
-declare const mergeBase: (ctx: Context, a: ObjectId, b: ObjectId) => Promise<ObjectId | undefined>;
+
+interface MaterializeTreeOpts {
+    readonly targetTree: ObjectId;
+    readonly currentIndex: GitIndex;
+    readonly force?: boolean;
+    readonly paths?: ReadonlySet<FilePath>;
+    /**
+     * When true, every target-tree path is written to the working tree
+     * unconditionally — even paths the index→target diff classified as `noop`
+     * (same `id` AND `mode`). Required by `reset --hard`, where the working
+     * tree may diverge from the index (uncommitted local modifications); the
+     * standard index→target diff cannot see that drift, so noops would skip
+     * paths the caller wants overwritten. Default `false` keeps the Phase
+     * 13.1 checkout behaviour: clean files are never spuriously rewritten.
+     */
+    readonly forceRewriteAll?: boolean;
+}
+interface MaterializeTreeResult {
+    readonly newIndexEntries: ReadonlyArray<IndexEntry>;
+    readonly written: number;
+    readonly deleted: number;
+}
+declare const materializeTree: (ctx: Context, opts: MaterializeTreeOpts) => Promise<MaterializeTreeResult>;
 
 /**
- * Pure path helpers composing `ctx.layout.gitDir` with known sub-paths.
- * No I/O. No port access. Primitive step 3.
+ * Read `.git/shallow`. Returns an empty set when the file does not exist or
+ * contains no oids. Malformed lines are tolerated (skipped) — canonical
+ * git behaves the same; a corrupted shallow file should not block a fetch.
  */
-
+declare const readShallow: (ctx: Context) => Promise<ReadonlySet<ObjectId>>;
+interface ShallowUpdate {
+    readonly shallow: ReadonlyArray<ObjectId>;
+    readonly unshallow: ReadonlyArray<ObjectId>;
+}
 /**
- * Repository working-tree root. Returns the workDir from the current context;
- * facade-tier code (Phase 10) is responsible for discovery / realpath pinning
- * at construction time. Primitives consume the already-resolved path.
+ * Apply a set of shallow / unshallow updates to `.git/shallow`. Writes
+ * atomically via lock-rename; deletes the file when the resulting set is
+ * empty.
  */
-declare const getRepoRoot: (ctx: Context) => FilePath;
-
-declare function readBlob(ctx: Context, id: ObjectId, options?: ReadObjectOptions): Promise<Blob>;
-
-declare function readIndex(ctx: Context): Promise<GitIndex>;
-
-declare function readObject(ctx: Context, id: ObjectId, options?: ReadObjectOptions): Promise<GitObject>;
-
-declare function readTree(ctx: Context, ref: RefName | ObjectId): Promise<Tree>;
-
-declare function resolveRef(ctx: Context, name: RefName | 'HEAD', options?: ResolveRefOptions): Promise<ObjectId>;
-
-declare function updateRef(ctx: Context, name: RefName, newId: ObjectId, options?: UpdateRefOptions): Promise<void>;
-
-declare function walkCommits(ctx: Context, options: WalkCommitsOptions): AsyncIterable<Commit>;
-
-declare function walkTree(ctx: Context, treeIdOrObject: ObjectId | Tree, options?: WalkTreeOptions): AsyncIterable<WalkTreeEntry>;
-
-declare function writeObject(ctx: Context, object: GitObject): Promise<ObjectId>;
+declare const updateShallow: (ctx: Context, updates: ShallowUpdate) => Promise<void>;
 
 /**
- * Write a symbolic ref atomically. Used for HEAD updates that point at a
- * branch, branch renames affecting the current HEAD, and `clone`/`init`
- * to set the initial HEAD.
+ * Synthesise a nested `Tree` object from a flat `GitIndex` and return the
+ * root tree's `ObjectId`. Sub-trees are written to the object store as a
+ * side-effect of the recursive descent — only stage-0 entries contribute.
+ *
+ * Used by `checkout({ paths, source: 'index' })` to restore
+ * the working tree from staged content even when the index has diverged
+ * from HEAD via `add` / `rm`. The previous placeholder fell back to
+ * HEAD's tree, which silently lost the divergence.
+ *
+ * The synthesis is the inverse of `buildIndexFromTree`:
+ * "tree → index" and "index → tree" form a round-trip identity for any
+ * stage-0-only index.
+ *
+ * Pure with respect to the working tree — never calls `fs.lstat`,
+ * `fs.read`, or any working-tree-side API. Only writes git objects via
+ * the existing `writeTree` primitive.
  *
- * Single-level only in v1: target MUST be a direct ref name (no chained
- * symrefs). Validation runs through `validateRefName` for both `name` and
- * `target` — invalid inputs throw INVALID_REF before any I/O.
+ * ## Safety
+ *
+ * - **Path validation**:.7 hoisted segment-level validation into
+ *  `parseIndex` (`src/domain/git-index/path-validator.ts`). Every
+ *  `IndexEntry` reaching this primitive THROUGH THE CANONICAL PARSER
+ *  carries a `FilePath` value already free of `..`, `.`, empty segments,
+ *  and leading-slash absolute paths. However, the primitive is also
+ *  reachable from callers that construct `IndexEntry` records outside
+ *  the parser (test fixtures, in-memory adapters, future synthesisers).
+ *  Defence-in-depth: every entry is re-validated here so the primitive
+ *  stays safe even when the parser-trusted path is bypassed.
+ * - **Depth cap**: synthesis bounds recursion at `MAX_TREE_DEPTH` (4096,
+ *  matching git's canonical limit). The cap is enforced at the input
+ *  boundary by counting slashes — by the time recursion would catch a
+ *  pathological depth, the JS engine has already exhausted its call
+ *  stack. Path validation does NOT subsume this check: a path can be
+ *  safe segment-by-segment (no `..`/`.`/empty) and still be 10 000
+ *  levels deep.
  */
-declare const writeSymbolicRef: (ctx: Context, name: RefName, target: RefName) => Promise<void>;
 
-declare function writeTree(ctx: Context, entries: ReadonlyArray<TreeEntry>): Promise<ObjectId>;
+/**
+ * Public entry: pass the `entries` array directly (typically
+ * `index.entries`, but callers holding a filtered list may supply it
+ * without wrapping in a fake `GitIndex`).
+ */
+declare const synthesizeTreeFromIndex: (ctx: Context, entries: ReadonlyArray<IndexEntry>) => Promise<ObjectId>;
 
-export { MAX_COMMIT_MESSAGE_BYTES, MAX_INDEX_BYTES, MAX_PEEL_DEPTH, MAX_SYMBOLIC_REF_DEPTH, MAX_WALK_QUEUE_SIZE, MAX_WALK_SEEDS, TreeDiff, createCommit, diffTrees, getRepoRoot, mergeBase, readBlob, readIndex, readObject, readTree, resolveRef, updateRef, walkCommits, walkTree, writeObject, writeSymbolicRef, writeTree };
-export type { CreateCommitInput, DiffTreesInput, DiffTreesOptions, ReadObjectOptions, ResolveRefOptions, UpdateRefOptions, WalkCommitsOptions, WalkTreeEntry, WalkTreeOptions };
+export { applyChangeset, buildIndexFromTree, buildPack, computeChangeset, enumeratePushObjects, fetchPack, materializeTree, readShallow, synthesizeTreeFromIndex, updateShallow };
+export type { ApplyChangesetOpts, ApplyChangesetResult, BuildIndexFromTreeOpts, BuildPackInput, BuildPackResult, Changeset, ChangesetEntry, ChangesetStats, EnumeratePushObjectsInput, FetchPackInput, FetchPackResult, MaterializeTreeOpts, MaterializeTreeResult };