@scolladon/tsgit 0.9.0 → 1.1.0

package/dist/types/chunks/write-tree-DVp0RJ_r.d.cts

@@ -0,0 +1,282 @@
+import { O as ObjectId, d as FilePath, e as FileStat, b as Context, R as RefName } from './context-D84z1i5F.cjs';
+import { A as AuthorIdentity, F as FileMode, T as TreeDiff } from './diff-change-Bm1zvVsC.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;
+}
+
+/**
+ * Primitive option shapes, walker value types, and shared constants.
+ * Defined in one location to avoid circular imports between primitive modules.
+ */
+
+/** 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;
+/**
+ * Per-file size cap enforced by `add --all` before reading working-tree
+ * bytes into memory. Mirrors `MAX_CONFLICT_OUTPUT_BYTES` (256 MiB) so the
+ * write-side memory ceiling matches the read-side ceiling.
+ * See `docs/adr/032-add-all-large-file-guard.md`.
+ */
+declare const MAX_WORKING_TREE_BLOB_BYTES: number;
+/**
+ * Per-file cap on `.gitignore`, `.git/info/exclude`, and the global
+ * excludesFile. 1 MiB leaves a 20× margin over real-world max-size
+ * gitignore corpora. See `docs/adr/036-gitignore-bounded-read.md`.
+ */
+declare const MAX_GITIGNORE_BYTES: number;
+interface ReadObjectOptions {
+    readonly verifyHash?: boolean;
+    /**
+     * Reject objects whose serialised payload exceeds this byte count, before
+     * inflating the full content into memory. Counts the raw object content
+     * (post-inflate, pre-loose-header). When unset, no cap applies.
+     *
+     * Used by `merge`'s content merger to bound peak memory when an adversarial
+     * remote ships pathologically large blobs. See `docs/design/phase-13-8-
+     * bounded-object-reads.md`.
+     */
+    readonly maxBytes?: number;
+}
+interface ResolveRefOptions {
+    readonly peel?: boolean;
+    readonly maxSymbolicDepth?: number;
+    readonly maxPeelDepth?: number;
+}
+interface UpdateRefOptions {
+    readonly expected?: ObjectId | 'absent';
+    readonly delete?: boolean;
+}
+interface WalkCommitsOptions {
+    readonly from: ReadonlyArray<ObjectId>;
+    readonly until?: ReadonlyArray<ObjectId>;
+    readonly order?: 'topo' | 'first-parent';
+    readonly ignoreMissing?: boolean;
+    readonly verifyHash?: boolean;
+    /**
+     * Commits whose parents must NOT be enqueued. Used for shallow boundaries
+     * . The commit itself is still yielded — only its parents are
+     * skipped. Callers that want to also skip the boundary commit pass it in
+     * `until`.
+     */
+    readonly shallow?: ReadonlySet<ObjectId>;
+}
+/** Maximum `have` lines a single-round fetch will send. */
+declare const MAX_HAVES = 256;
+/** Hard cap on objects enumerated for a single push. design */
+declare const MAX_PUSH_OBJECTS = 1000000;
+interface WalkTreeEntry {
+    readonly path: FilePath;
+    readonly id: ObjectId;
+    readonly mode: FileMode;
+}
+interface WalkTreeOptions {
+    readonly recursive?: boolean;
+    readonly maxDepth?: number;
+    readonly maxEntries?: number;
+}
+interface WalkWorkingTreeEntry {
+    readonly path: FilePath;
+    readonly stat: FileStat;
+}
+type WalkIgnorePredicate = (path: FilePath, isDirectory: boolean) => boolean | Promise<boolean>;
+interface WalkWorkingTreeOptions {
+    readonly maxDepth?: number;
+    readonly maxEntries?: number;
+    /**
+     * predicate. 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). May be sync or async.
+     */
+    readonly ignore?: WalkIgnorePredicate;
+}
+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>;
+}
+type DiffTreesInput = Tree | ObjectId | undefined;
+interface DiffTreesOptions {
+    readonly detectRenames?: boolean;
+    readonly renameOptions?: RenameDetectOptions;
+}
+
+declare function createCommit(ctx: Context, input: CreateCommitInput): Promise<ObjectId>;
+
+declare function diffTrees(ctx: Context, a: DiffTreesInput, b: DiffTreesInput, options?: DiffTreesOptions): Promise<TreeDiff>;
+
+/**
+ * Compute a merge base — the first commit reachable from BOTH `a` and `b`.
+ *
+ * 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 `undefined` for unrelated histories. Documented limitation: cherry-picks
+ * and criss-cross merges may yield non-optimal bases — `recursive`-strategy
+ * multi-base resolution is v2.
+ */
+declare const mergeBase: (ctx: Context, a: ObjectId, b: ObjectId) => Promise<ObjectId | undefined>;
+
+/**
+ * Pure path helpers composing `ctx.layout.gitDir` with known sub-paths.
+ * No I/O. No port access. Primitive step 3.
+ */
+
+/**
+ * Repository working-tree root. Returns the workDir from the current context;
+ * facade-tier code is responsible for discovery / realpath pinning
+ * at construction time. Primitives consume the already-resolved path.
+ */
+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>;
+
+/**
+ * Depth-first walk of the working tree starting at `ctx.layout.workDir`.
+ *
+ * Yields leaf entries (files and symlinks) as `{ path, stat }`. Directories
+ * are descended into, not yielded. `.git` at any level is skipped
+ * (case-insensitive, NTFS-trimmed). Embedded repositories (directories
+ * containing a `.git` child) are skipped entirely — yields nothing under
+ * them. Symlinks are surfaced via `lstat` (no follow); a symlink to a
+ * directory is yielded as a leaf, not descended into.
+ *
+ * The host repository's own `.git` is NOT treated as an embedded-repo
+ * marker — at the workDir root we only skip the `.git` entry itself, not
+ * the workDir.
+ */
+declare function walkWorkingTree(ctx: Context, options?: WalkWorkingTreeOptions): AsyncIterable<WalkWorkingTreeEntry>;
+
+declare function writeObject(ctx: Context, object: GitObject): Promise<ObjectId>;
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+declare const writeSymbolicRef: (ctx: Context, name: RefName, target: RefName) => Promise<void>;
+
+declare function writeTree(ctx: Context, entries: ReadonlyArray<TreeEntry>): Promise<ObjectId>;
+
+export { walkCommits as A, walkTree as B, walkWorkingTree as E, writeObject as F, writeSymbolicRef as H, writeTree as J, MAX_COMMIT_MESSAGE_BYTES as M, MAX_GITIGNORE_BYTES as b, MAX_HAVES as c, MAX_INDEX_BYTES as d, MAX_PEEL_DEPTH as e, MAX_PUSH_OBJECTS as f, MAX_SYMBOLIC_REF_DEPTH as g, MAX_WALK_QUEUE_SIZE as h, MAX_WALK_SEEDS as i, MAX_WORKING_TREE_BLOB_BYTES as j, createCommit as q, diffTrees as r, getRepoRoot as s, mergeBase as t, readBlob as u, readIndex as v, readObject as w, readTree as x, resolveRef as y, updateRef as z };
+export type { CreateCommitInput as C, DiffTreesInput as D, GitIndex as G, IndexEntry as I, ReadObjectOptions as R, UpdateRefOptions as U, WalkCommitsOptions as W, DiffTreesOptions as a, ResolveRefOptions as k, WalkIgnorePredicate as l, WalkTreeEntry as m, WalkTreeOptions as n, WalkWorkingTreeEntry as o, WalkWorkingTreeOptions as p };

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

@@ -1,6 +1,6 @@
-import { b as FilePath, a as Context, j as RefName, O as ObjectId } from '../chunks/context-Ku1aP8Ie.cjs';
-import { A as AuthorIdentity, T as TreeDiff } from '../chunks/diff-change-BwO75AgS.cjs';
-import '../chunks/http-transport--_NdQOiw.cjs';
+import { d as FilePath, b as Context, R as RefName, O as ObjectId } from '../chunks/context-D84z1i5F.cjs';
+import { A as AuthorIdentity, T as TreeDiff } from '../chunks/diff-change-Bm1zvVsC.cjs';
+import '../chunks/http-transport-DirKfK2S.cjs';
 
 interface AddOptions {
     readonly force?: boolean;
@@ -13,14 +13,17 @@ interface AddResult {
     readonly removed: ReadonlyArray<FilePath>;
 }
 /**
- * Add the given pathspecs to the index. Performs:
- * 1. Repo + bare + pending-op preflight checks.
- * 2. Path validation for every input (no I/O on rejection).
- * 3. Read working-tree contents → write blob → produce IndexEntry.
- * 4. Atomically replace `.git/index` under the index lock.
+ * Stage paths in the index. Two modes:
  *
- * Bulk mode (`all: true`) is not yet implemented — this is the literal-paths
- * happy path used by `init`/`commit` integration tests.
+ * - **Literal-path mode** (`paths` non-empty, `all` falsy): every path is
+ *  validated, read, hashed, and staged. Missing paths reject the whole call.
+ * - **Bulk mode** (`paths` empty, `all === true`): walk the working tree,
+ *  stage every modified/new tracked file plus every untracked, non-ignored
+ *  file. Files missing from disk but present in the prior index land in
+ *  `removed`. `.git` and embedded repositories are skipped.
+ *
+ * Both modes acquire `.git/index.lock` once, read the existing index under
+ * the lock, and commit a single replacement — no partial writes.
  */
 declare const add: (ctx: Context, paths: ReadonlyArray<string>, opts?: AddOptions) => Promise<AddResult>;
 
@@ -63,15 +66,21 @@ type BranchResult = {
 };
 declare const branch: (ctx: Context, action: BranchAction) => Promise<BranchResult>;
 
-interface CheckoutOptions {
+interface CheckoutSwitchOptions {
     readonly target: string;
     readonly detach?: boolean;
     readonly force?: boolean;
 }
+interface CheckoutPathsOptions {
+    readonly paths: ReadonlyArray<string>;
+    readonly source?: 'index' | 'HEAD' | ObjectId;
+}
+type CheckoutOptions = CheckoutSwitchOptions | CheckoutPathsOptions;
 interface CheckoutResult {
     readonly branch: RefName | undefined;
     readonly id: ObjectId;
     readonly detached: boolean;
+    readonly changedPaths: number;
 }
 declare const checkout: (ctx: Context, opts: CheckoutOptions) => Promise<CheckoutResult>;
 
@@ -82,6 +91,10 @@ interface CloneOptions {
     readonly url: string;
     readonly bare?: boolean;
     readonly initialBranch?: string;
+    /**
+     * Shallow clone depth. When set, sends `deepen N` and persists the
+     * resulting shallow boundaries to `.git/shallow`.
+     */
     readonly depth?: number;
     /** DNS resolver injected by the caller; required to enforce SSRF guards. */
     readonly resolver?: DnsResolver;
@@ -122,6 +135,8 @@ interface CommitResult {
  */
 declare const commit: (ctx: Context, opts: CommitOptions) => Promise<CommitResult>;
 
+type ConflictType = 'content' | 'add-add' | 'modify-delete' | 'type-change' | 'rename-rename' | 'gitlink' | 'binary';
+
 interface DiffOptions {
     /** Resolve to a tree. Accepts ref name, oid, or 'HEAD'. */
     readonly from?: string;
@@ -139,15 +154,24 @@ interface FetchOptions {
     readonly remote?: string;
     readonly refspecs?: ReadonlyArray<string>;
     readonly prune?: boolean;
+    /** Shallow clone depth. Delegates to fetchPack's deepen path. */
+    readonly depth?: number;
+}
+interface FetchUpdate {
+    readonly name: RefName;
+    readonly oldId: ObjectId | undefined;
+    readonly newId: ObjectId;
 }
 interface FetchResult {
     readonly remote: string;
     readonly url: string;
-    readonly updatedRefs: ReadonlyArray<{
-        readonly name: RefName;
-        readonly oldId: ObjectId | undefined;
-        readonly newId: ObjectId;
-    }>;
+    readonly updatedRefs: ReadonlyArray<FetchUpdate>;
+    /** Refs deleted because the server no longer advertises them (prune semantics). */
+    readonly prunedRefs: ReadonlyArray<RefName>;
+    /** New shallow boundaries written to `.git/shallow` during this fetch. */
+    readonly shallow: ReadonlyArray<ObjectId>;
+    /** Commits that crossed the shallow → non-shallow boundary during this fetch. */
+    readonly unshallow: ReadonlyArray<ObjectId>;
 }
 declare const fetch: (ctx: Context, opts?: FetchOptions) => Promise<FetchResult>;
 
@@ -167,7 +191,7 @@ interface InitResult {
  *
  * For non-bare repos, the gitDir is `<workDir>/.git`. For bare, gitDir IS the
  * working dir — callers must construct a Context with `bare: true` for that
- * shape (Phase 10 facade will derive this automatically).
+ * shape.
  */
 declare const init: (ctx: Context, opts?: InitOptions) => Promise<InitResult>;
 
@@ -200,6 +224,10 @@ interface MergeOptions {
     readonly author?: AuthorIdentity;
     readonly committer?: AuthorIdentity;
 }
+interface MergeConflictDescriptor {
+    readonly path: FilePath;
+    readonly type: ConflictType;
+}
 type MergeResult = {
     readonly kind: 'up-to-date';
     readonly id: ObjectId;
@@ -212,14 +240,24 @@ type MergeResult = {
     readonly id: ObjectId;
     readonly branch: RefName;
     readonly parents: ReadonlyArray<ObjectId>;
+} | {
+    readonly kind: 'conflict';
+    readonly conflicts: ReadonlyArray<MergeConflictDescriptor>;
+    readonly mergeHead: ObjectId;
+    readonly origHead: ObjectId;
 };
 /**
- * Merge `target` into the current HEAD branch. v1 supports:
- * - Up-to-date detection (target is ancestor of HEAD).
- * - Fast-forward (HEAD is ancestor of target → branch advances).
- * - True merge for diverged histories: writes a merge commit using HEAD's tree
- *   (callers must run `add` to incorporate target's content). Conflict
- *   resolution and three-way tree merge land in Phase 11.
+ * Merge `target` into the current HEAD branch.
+ *
+ * - Up-to-date: target is ancestor of HEAD → no-op.
+ * - Fast-forward: HEAD is ancestor of target → branch advances.
+ * - True merge for diverged histories:.4a wired the three-way
+ *  tree merge (`mergeTrees` + `mergeContent`) so a CLEAN merge commits
+ *  the merged tree directly.4b persists conflict state on
+ *  disk (marker files, stage-1/2/3 index entries, MERGE_HEAD /
+ *  MERGE_MSG / ORIG_HEAD) and returns `{ kind: 'conflict',... }`.
+ *  Resolution path: edit the marker files, `repo.add(paths)`,
+ *  `repo.commit({ message })` — the resulting commit has two parents.
  */
 declare const merge: (ctx: Context, opts: MergeOptions) => Promise<MergeResult>;
 
@@ -229,14 +267,17 @@ interface PushOptions {
     readonly force?: boolean;
     readonly forceWithLease?: ObjectId | 'auto';
 }
+interface PushedRef {
+    readonly name: RefName;
+    readonly oldId: ObjectId;
+    readonly newId: ObjectId;
+    readonly status: 'ok' | 'rejected';
+    readonly reason?: string;
+}
 interface PushResult {
     readonly remote: string;
     readonly url: string;
-    readonly pushedRefs: ReadonlyArray<{
-        readonly name: RefName;
-        readonly newId: ObjectId;
-        readonly status: 'ok' | 'rejected';
-    }>;
+    readonly pushedRefs: ReadonlyArray<PushedRef>;
 }
 declare const push: (ctx: Context, opts?: PushOptions) => Promise<PushResult>;
 
@@ -253,13 +294,18 @@ interface ResetResult {
 /**
  * Reset HEAD (and optionally index/working tree) to `target`.
  *
- * - `soft`:  HEAD only.
- * - `mixed`: HEAD + clears the index (Phase 9 stub: index cleared via lock release).
- * - `hard`:  HEAD + index + working tree (working-tree mutation deferred to Phase 11).
+ * - `soft`: HEAD only.
+ * - `mixed`: HEAD + rebuild the index from the target commit's tree
+ *  (stat-cache donor strategy preserves cache for unchanged paths —
+ * ). Working tree is NOT touched.
+ * - `hard`: HEAD + index + working tree — materialise the target tree onto
+ *  the working tree with `force: true`, then commit the post-write
+ *  index entries. Bare repos are rejected upfront.
  *
- * v1 implements the HEAD-update path; index/working-tree side effects beyond
- * the HEAD move land in subsequent passes once `materializeFile`/`removeFile`
- * orchestration is in place.
+ * Ordering: working tree → index → HEAD. The index lock wraps both the
+ * working-tree write AND the index commit, matching tightened
+ * pattern. A crash between the index commit and HEAD update leaves the index
+ * ahead of HEAD — same recoverable hazard as canonical git.
  */
 declare const reset: (ctx: Context, opts: ResetOptions) => Promise<ResetResult>;
 
@@ -293,10 +339,10 @@ interface StatusResult {
 /**
  * Summarize the state of the working tree relative to the index, and the
  * branch HEAD points at. Working-tree-vs-HEAD diff (Git's "staged" column)
- * is approximated via index-vs-working-tree comparisons until Phase 11
+ * is approximated via index-vs-working-tree comparisons until
  * adds the stat-cache fast path.
  *
- * Progress reporting (Phase 10 §6.2): emits `status:scan` start before the
+ * Progress reporting: emits `status:scan` start before the
  * fan-out, updates at every 100 lstat completions, and end in a finally
  * block so the consumer always pairs start with end. `total` is undefined
  * — design choice that prevents revealing repository size to non-trusted