just-git 1.2.12 → 1.3.0

package/dist/repo/index.d.ts

@@ -1,4 +1,4 @@
-import { _ as ObjectId, $ as Identity, d as GitContext, f as GitRepo, F as FileSystem, a0 as TreeDiffEntry, V as RefEntry, a1 as Commit, O as ObjectStore, a2 as ObjectType, a3 as RawObject, a as RefStore, a4 as Ref } from '../hooks-4DvkF2xT.js';
+import { _ as ObjectId, $ as Identity, d as GitContext, f as GitRepo, F as FileSystem, a0 as TreeDiffEntry, V as RefEntry, a1 as Commit, O as ObjectStore, a2 as ObjectType, a3 as RawObject, a4 as PackObject, a as RefStore, a5 as Ref } from '../hooks-BtbyLyYE.js';
 
 interface BlameEntry {
     hash: ObjectId;
@@ -18,6 +18,15 @@ interface BlameEntry {
     };
 }
 
+/**
+ * Core grep matching logic shared by the `git grep` command and the
+ * repo-level `grep` helper.
+ */
+interface GrepMatch {
+    lineNo: number;
+    line: string;
+}
+
 interface MergeConflict {
     path: string;
     reason: "content" | "delete-modify" | "add-add" | "rename-delete" | "rename-rename" | "directory-rename";
@@ -94,6 +103,50 @@ declare function readBlobText(repo: GitRepo, hash: string): Promise<string>;
 declare function flattenTree(repo: GitRepo, treeHash: string): Promise<FlatTreeEntry[]>;
 /** Diff two tree objects and return the list of added/deleted/modified entries. Pass null for an empty tree. */
 declare function diffTrees(repo: GitRepo, treeA: string | null, treeB: string | null): Promise<TreeDiffEntry[]>;
+/** A single hunk in a file diff. */
+interface DiffHunk {
+    oldStart: number;
+    oldCount: number;
+    newStart: number;
+    newCount: number;
+    /** Lines prefixed with ' ' (context), '+' (insert), or '-' (delete). */
+    lines: string[];
+}
+/** One file's diff between two commits. */
+interface FileDiff {
+    path: string;
+    status: "added" | "modified" | "deleted" | "renamed";
+    /** Original path when status is "renamed". */
+    oldPath?: string;
+    /** Similarity percentage (0–100) for renames. */
+    similarity?: number;
+    hunks: DiffHunk[];
+}
+/**
+ * Produce structured, line-level diffs between two commits.
+ *
+ * Accepts commit hashes or ref names. Returns one `FileDiff` per
+ * changed file, each containing hunks with prefixed diff lines.
+ * Rename detection is enabled by default.
+ *
+ * ```ts
+ * const diffs = await diffCommits(repo, "main", "feature");
+ * for (const file of diffs) {
+ *   console.log(`${file.status} ${file.path}`);
+ *   for (const hunk of file.hunks) {
+ *     for (const line of hunk.lines) console.log(line);
+ *   }
+ * }
+ * ```
+ */
+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[]>;
 /** Find the merge base(s) of two commits. Returns one hash for most cases, multiple for criss-cross merges. */
 declare function findMergeBases(repo: GitRepo, commitA: string, commitB: string): Promise<string[]>;
 /** Result of a tree-level merge via {@link mergeTrees} or {@link mergeTreesFromTreeHashes}. */
@@ -184,8 +237,8 @@ declare function writeBlob(repo: GitRepo, content: string): Promise<string>;
  * Returns null if the file doesn't exist at that commit.
  */
 declare function readFileAtCommit(repo: GitRepo, commitHash: string, filePath: string): Promise<string | null>;
-/** Result of {@link checkoutTo}. */
-interface CheckoutToResult {
+/** Result of {@link extractTree}. */
+interface ExtractTreeResult {
     commitHash: string;
     treeHash: string;
     filesWritten: number;
@@ -200,7 +253,7 @@ interface CheckoutToResult {
  * Useful inside server hooks and platform callbacks to inspect, build,
  * or lint the code at a given commit without affecting the repo itself.
  */
-declare function checkoutTo(repo: GitRepo, refOrHash: string, fs: FileSystem, targetDir?: string): Promise<CheckoutToResult>;
+declare function extractTree(repo: GitRepo, refOrHash: string, fs: FileSystem, targetDir?: string): Promise<ExtractTreeResult>;
 interface CreateWorktreeOptions {
     /** Ref name or commit hash to check out (default: "HEAD"). */
     ref?: string;
@@ -231,7 +284,7 @@ interface WorktreeResult {
  * command handlers use the shared stores instead of the VFS:
  *
  * ```ts
- * const repo = storage.repo("my-repo");
+ * const repo = await storage.createRepo("my-repo");
  * const fs = new InMemoryFs();
  * const { ctx } = await createWorktree(repo, fs);
  * const git = createGit({
@@ -263,12 +316,64 @@ declare function blame(repo: GitRepo, commitHash: string, path: string, opts?: {
 /**
  * Walk the commit graph starting from one or more hashes, yielding
  * commits in reverse chronological order. Supports excluding commits
- * reachable from specified hashes and following only first parents.
+ * reachable from specified hashes, following only first parents, and
+ * filtering to commits that touch specific paths.
+ *
+ * When `paths` is provided, history simplification is applied: at
+ * merge points, only TREESAME parents are followed (matching git's
+ * default simplification for `git log -- <path>`).
  */
 declare function walkCommitHistory(repo: GitRepo, startHash: string | string[], opts?: {
     exclude?: string[];
     firstParent?: boolean;
+    paths?: string[];
 }): AsyncGenerator<CommitInfo>;
+/** Options for {@link grep}. */
+interface GrepOptions {
+    /** Treat patterns as fixed strings, not regexps. */
+    fixed?: boolean;
+    /** Case-insensitive matching. */
+    ignoreCase?: boolean;
+    /** Match whole words only. */
+    wordRegexp?: boolean;
+    /** Require ALL patterns to hit at least one line in a file (AND). Default is OR. */
+    allMatch?: boolean;
+    /** Invert the match — return non-matching lines. */
+    invert?: boolean;
+    /** Limit matches per file. */
+    maxCount?: number;
+    /** Max directory depth (0 = only root-level files). */
+    maxDepth?: number;
+    /** Only search files whose paths match these globs. Matched against the full repo-relative path. */
+    paths?: string[];
+}
+/** A single file's grep results from {@link grep}. */
+interface GrepFileMatch {
+    /** Repo-relative file path. */
+    path: string;
+    /** Matching lines (empty for binary matches). */
+    matches: GrepMatch[];
+    /** True when the file is binary and a pattern matched its raw content. */
+    binary: boolean;
+}
+
+/**
+ * Search files at a commit for lines matching one or more patterns.
+ *
+ * Operates purely on the object store — no filesystem, index, or
+ * worktree needed. Takes a commit hash (not a ref name) and returns
+ * structured match results.
+ *
+ * ```ts
+ * const results = await grep(repo, commitHash, ["TODO", "FIXME"]);
+ * for (const file of results) {
+ *   for (const m of file.matches) {
+ *     console.log(`${file.path}:${m.lineNo}: ${m.line}`);
+ *   }
+ * }
+ * ```
+ */
+declare function grep(repo: GitRepo, commitHash: string, patterns: (string | RegExp)[], options?: GrepOptions): Promise<GrepFileMatch[]>;
 /**
  * Wrap a `GitRepo` so all write operations throw.
  *
@@ -290,6 +395,59 @@ declare function walkCommitHistory(repo: GitRepo, startHash: string | string[],
  * ```
  */
 declare function readonlyRepo(repo: GitRepo): GitRepo;
+/**
+ * Wrap a `GitRepo` with copy-on-write overlay stores.
+ *
+ * Read operations pass through to the underlying stores.
+ * Write operations (write, writeRef, deleteRef, ingestPack,
+ * compareAndSwapRef) are captured in an in-memory overlay
+ * and never reach the inner repo.
+ *
+ * Use for ephemeral operations (CI, previews, dry-run merges)
+ * where you need full read-write semantics but must not
+ * mutate the real repository.
+ *
+ * ```ts
+ * const ephemeral = overlayRepo(storage.repo("my-repo"));
+ * // writes succeed but only exist in memory
+ * await ephemeral.objectStore.write("blob", content);
+ * // original repo is untouched
+ * ```
+ */
+declare function overlayRepo(repo: GitRepo): GitRepo;
+/**
+ * Create an ephemeral worktree backed by overlay stores and a lazy filesystem.
+ *
+ * - Object/ref writes go to an in-memory overlay (real repo untouched)
+ * - Worktree files are read lazily from the object store on demand
+ * - All state is discarded when the returned context goes out of scope
+ *
+ * Designed for server hooks that need to run tools against pushed code
+ * without paying the cost of materializing the entire tree and without
+ * risking mutation of the real repository.
+ *
+ * ```ts
+ * hooks: {
+ *   async preReceive({ repo, updates }) {
+ *     const { ctx } = await createSandboxWorktree(repo, {
+ *       ref: updates[0].newHash,
+ *     });
+ *     const git = createGit({
+ *       objectStore: ctx.objectStore,
+ *       refStore: ctx.refStore,
+ *     });
+ *     const bash = new Bash({ fs: ctx.fs, cwd: ctx.workTree! });
+ *     const result = await bash.exec("cat package.json");
+ *     // reads lazily from object store — only touched files are loaded
+ *   }
+ * }
+ * ```
+ */
+declare function createSandboxWorktree(repo: GitRepo, options?: {
+    ref?: string;
+    workTree?: string;
+    gitDir?: string;
+}): Promise<WorktreeResult>;
 
 /**
  * Git object storage: compressed loose objects for new writes, with
@@ -310,6 +468,7 @@ declare class PackedObjectStore implements ObjectStore {
     read(hash: ObjectId): Promise<RawObject>;
     exists(hash: ObjectId): Promise<boolean>;
     ingestPack(packData: Uint8Array): Promise<number>;
+    ingestPackStream(entries: AsyncIterable<PackObject>): Promise<number>;
     invalidatePacks(): void;
     findByPrefix(prefix: string): Promise<ObjectId[]>;
     /** Load the pack data for a slot on demand. */
@@ -340,4 +499,4 @@ declare class FileSystemRefStore implements RefStore {
     private walkRefs;
 }
 
-export { type BlameEntry, type CheckoutToResult, type CommitInfo, type CreateCommitOptions, type CreateWorktreeOptions, FileSystemRefStore, GitRepo, Identity, type MergeConflict, type MergeTreesResult, PackedObjectStore, type TreeEntryInput, type WorktreeResult, blame, checkoutTo, countAheadBehind, createCommit, createWorktree, diffTrees, findMergeBases, flattenTree, getChangedFiles, getNewCommits, isAncestor, listBranches, listTags, mergeTrees, mergeTreesFromTreeHashes, readBlob, readBlobText, readCommit, readFileAtCommit, readonlyRepo, resolveRef, walkCommitHistory, writeBlob, writeTree };
+export { type BlameEntry, type CommitInfo, type CreateCommitOptions, type CreateWorktreeOptions, type DiffHunk, type ExtractTreeResult, type FileDiff, FileSystemRefStore, GitRepo, type GrepFileMatch, type GrepMatch, type GrepOptions, Identity, type MergeConflict, type MergeTreesResult, PackedObjectStore, type TreeEntryInput, type WorktreeResult, blame, countAheadBehind, createCommit, createSandboxWorktree, createWorktree, diffCommits, diffTrees, extractTree, findMergeBases, flattenTree, getChangedFiles, getNewCommits, grep, isAncestor, listBranches, listTags, mergeTrees, mergeTreesFromTreeHashes, overlayRepo, readBlob, readBlobText, readCommit, readFileAtCommit, readonlyRepo, resolveRef, walkCommitHistory, writeBlob, writeTree };