just-git 1.5.5 → 1.5.7

package/dist/repo/index.d.ts

@@ -1,5 +1,5 @@
 import { g as GitRepo, Z as RefEntry, e as Commit, a3 as TreeEntry, i as ObjectId, h as Identity, a4 as TreeDiffEntry, d as GitContext, F as FileSystem } from '../hooks-CimfP56a.js';
-export { B as BuildCommitOptions, C as CommitAuthor, a as CommitIdentity, b as CommitOptions, c as CommitResult, d as CreateAnnotatedTagOptions, e as CreateCommitOptions, T as TreeEntryInput, f as TreeUpdate, g as buildCommit, h as commit, i as createAnnotatedTag, j as createCommit, u as updateTree, w as writeBlob, k as writeTree } from '../writing-IwfRRrts.js';
+export { B as BuildCommitOptions, b as CommitAuthor, c as CommitIdentity, C as CommitOptions, a as CommitResult, d as CreateAnnotatedTagOptions, e as CreateCommitOptions, T as TreeEntryInput, f as TreeUpdate, g as buildCommit, h as commit, i as createAnnotatedTag, j as createCommit, u as updateTree, w as writeBlob, k as writeTree } from '../writing-CF-eYohc.js';
 
 /** Extract the short branch name from a full ref path like "refs/heads/main" → "main". */
 declare function branchNameFromRef(ref: string): string;
@@ -200,6 +200,15 @@ interface FileDiff {
     similarity?: number;
     hunks: DiffHunk[];
 }
+/** Shared options for {@link diffCommits} and {@link formatDiff}. */
+interface DiffOptions {
+    /** Only include files matching these paths (exact prefix match). */
+    paths?: string[];
+    /** Number of context lines around each change (default 3). */
+    contextLines?: number;
+    /** Enable rename detection (default true). */
+    renames?: boolean;
+}
 /**
  * Produce structured, line-level diffs between two commits.
  *
@@ -217,14 +226,19 @@ interface FileDiff {
  * }
  * ```
  */
-declare function diffCommits(repo: GitRepo, base: string, head: string, options?: {
-    /** Only include files matching these paths (exact prefix match). */
-    paths?: string[];
-    /** Number of context lines around each change (default 3). */
-    contextLines?: number;
-    /** Enable rename detection (default true). */
-    renames?: boolean;
-}): Promise<FileDiff[]>;
+declare function diffCommits(repo: GitRepo, base: string, head: string, options?: DiffOptions): Promise<FileDiff[]>;
+/**
+ * Produce a unified diff (patch) string between two commits.
+ *
+ * Uses `formatUnifiedDiff` directly — the same formatter behind
+ * `git diff` — so the output is byte-identical to CLI output
+ * and natively consumable by any unified-diff parser.
+ *
+ * ```ts
+ * const diff = await formatDiff(repo, "main~1", "main");
+ * ```
+ */
+declare function formatDiff(repo: GitRepo, base: string, head: string, options?: DiffOptions): Promise<string>;
 /**
  * Walk the commit graph starting from one or more hashes, yielding
  * commits in reverse chronological order. Supports excluding commits
@@ -391,6 +405,141 @@ declare function createSandboxWorktree(repo: GitRepo, options?: {
     gitDir?: string;
 }): Promise<WorktreeResult>;
 
+/** Minimal filesystem surface needed to write a materialized tree. */
+interface MaterializeTarget {
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    symlink?(target: string, path: string): Promise<void>;
+}
+
+/**
+ * Lazy accessor for the worktree contents at a specific tree.
+ *
+ * Provides progressively richer access to files without requiring
+ * upfront materialization:
+ *
+ * - {@link readFile} / {@link readFileBytes} — read a single file (O(tree depth), no flatten)
+ * - {@link files} — list all tracked file paths (walks tree objects, no blob reads)
+ * - {@link fs} — get a full {@link FileSystem} view (lazy reads, in-memory writes)
+ * - {@link materialize} — write all tracked files onto a target filesystem
+ */
+interface TreeAccessor {
+    /** The underlying git tree object hash. */
+    readonly treeHash: string;
+    /** Read a file's text content. Returns `null` if the file doesn't exist. */
+    readFile(path: string): Promise<string | null>;
+    /** Read a file's raw bytes. Returns `null` if the file doesn't exist. */
+    readFileBytes(path: string): Promise<Uint8Array | null>;
+    /** List all tracked file paths (no blob content is read). */
+    files(): Promise<string[]>;
+    /**
+     * Get a full `FileSystem` backed by this tree.
+     *
+     * Files are read lazily from the object store on demand.
+     * Writes go to an in-memory overlay and never touch the repo.
+     * Created once on first call, then cached for the lifetime of this accessor.
+     */
+    fs(root?: string): FileSystem;
+    /**
+     * Write all tracked files onto a filesystem.
+     *
+     * @param target — target filesystem (only needs `mkdir`, `writeFile`,
+     *   and optionally `symlink`)
+     * @param targetDir — root directory on the target fs (default `"/"`)
+     * @returns the number of files written
+     */
+    materialize(target: MaterializeTarget, targetDir?: string): Promise<number>;
+}
+/**
+ * Create a lazy {@link TreeAccessor} for a git tree hash.
+ *
+ * Single-file reads use O(tree depth) traversal via {@link TreeBackedFs}.
+ * Full-tree operations (`files`, `materialize`) flatten on demand.
+ */
+declare function createTreeAccessor(repo: GitRepo, treeHash: string): TreeAccessor;
+
+/** Options for {@link bisect}. */
+interface BisectOptions {
+    /** Known bad commit (hash, branch, tag, or any rev-parse expression). */
+    bad: string;
+    /** One or more known good commits. */
+    good: string | string[];
+    /**
+     * Test a candidate commit. Return:
+     * - `true` — commit is good (bug not present)
+     * - `false` — commit is bad (bug present)
+     * - `"skip"` — commit is untestable
+     *
+     * The `tree` parameter provides lazy access to the worktree contents
+     * at the candidate commit — read individual files, list paths, or
+     * get a full `FileSystem` for build/test scenarios.
+     */
+    test: (hash: string, tree: TreeAccessor) => boolean | "skip" | Promise<boolean | "skip">;
+    /** Follow only first parent at merge commits (default false). */
+    firstParent?: boolean;
+    /** Called after each step with progress info. */
+    onStep?: (info: BisectStepInfo) => void;
+}
+/** Progress info passed to {@link BisectOptions.onStep}. */
+interface BisectStepInfo {
+    hash: string;
+    subject: string;
+    verdict: "good" | "bad" | "skip";
+    remaining: number;
+    estimatedSteps: number;
+    stepNumber: number;
+}
+/**
+ * Result of {@link bisect}.
+ *
+ * - `found: true` — the first bad commit was identified.
+ * - `found: false, reason: "all-skipped"` — only skipped commits remain;
+ *   `candidates` lists them (plus the current bad).
+ * - `found: false, reason: "no-testable-commits"` — no commits exist
+ *   between the good and bad boundaries.
+ */
+type BisectSearchResult = {
+    found: true;
+    hash: string;
+    stepsTaken: number;
+} | {
+    found: false;
+    reason: "all-skipped";
+    candidates: string[];
+} | {
+    found: false;
+    reason: "no-testable-commits";
+};
+/**
+ * Binary-search the commit graph to find the first bad commit.
+ *
+ * Operates purely on the object store — no filesystem, index, working
+ * tree, or state files. The caller provides a `test` callback that
+ * inspects each candidate commit and returns whether it is good, bad,
+ * or should be skipped.
+ *
+ * Uses the same weighted-midpoint algorithm as `git bisect`: each step
+ * picks the commit that maximizes information gain (closest to
+ * eliminating half the remaining candidates).
+ *
+ * ```ts
+ * const result = await bisect(repo, {
+ *   bad: "main",
+ *   good: "v1.0.0",
+ *   test: async (hash, tree) => {
+ *     const content = await tree.readFile("src/config.ts");
+ *     return content !== null && !content.includes("broken_call");
+ *   },
+ * });
+ * if (result.found) {
+ *   console.log(`First bad commit: ${result.hash}`);
+ * }
+ * ```
+ */
+declare function bisect(repo: GitRepo, options: BisectOptions): Promise<BisectSearchResult>;
+
 /**
  * Wrap a `GitRepo` so all write operations throw.
  *
@@ -425,4 +574,4 @@ declare function readonlyRepo(repo: GitRepo): GitRepo;
  */
 declare function overlayRepo(repo: GitRepo): GitRepo;
 
-export { type BlameEntry, Commit, type CommitInfo, type CreateWorktreeOptions, type DiffHunk, type ExtractTreeResult, type FileDiff, type FlatTreeEntry, GitRepo, type GrepFileMatch, type GrepMatch, type GrepOptions, type HeadInfo, Identity, type MergeConflict, type MergeTreesResult, RefEntry, TreeDiffEntry, TreeEntry, type WorktreeResult, blame, branchNameFromRef, countAheadBehind, createSandboxWorktree, createWorktree, diffCommits, diffTrees, extractTree, findMergeBases, flattenTree, getChangedFiles, getNewCommits, grep, isAncestor, listBranches, listTags, mergeTrees, mergeTreesFromTreeHashes, overlayRepo, readBlob, readBlobText, readCommit, readFileAtCommit, readHead, readTree, readonlyRepo, resolveRef, tagNameFromRef, walkCommitHistory };
+export { type BisectOptions, type BisectSearchResult, type BisectStepInfo, type BlameEntry, Commit, type CommitInfo, type CreateWorktreeOptions, type DiffHunk, type DiffOptions, type ExtractTreeResult, type FileDiff, type FlatTreeEntry, GitRepo, type GrepFileMatch, type GrepMatch, type GrepOptions, type HeadInfo, Identity, type MaterializeTarget, type MergeConflict, type MergeTreesResult, RefEntry, type TreeAccessor, TreeDiffEntry, TreeEntry, type WorktreeResult, bisect, blame, branchNameFromRef, countAheadBehind, createSandboxWorktree, createTreeAccessor, createWorktree, diffCommits, diffTrees, extractTree, findMergeBases, flattenTree, formatDiff, getChangedFiles, getNewCommits, grep, isAncestor, listBranches, listTags, mergeTrees, mergeTreesFromTreeHashes, overlayRepo, readBlob, readBlobText, readCommit, readFileAtCommit, readHead, readTree, readonlyRepo, resolveRef, tagNameFromRef, walkCommitHistory };