Trait Repo 

pub trait Repo: Send + Sync {
    // Required methods
    fn walk_commits<'a>(
        &'a self,
        opts: &'a Options,
    ) -> Result<Box<dyn Iterator<Item = Result<CommitEvent>> + Send + 'a>>;
    fn changed_files(&self, rev: &str) -> Result<Vec<FileChange>>;
    fn diff_hunks(&self, rev: &str, path: &str) -> Result<Vec<Hunk>>;
    fn resolve_alias(&self, name: &str, email: &str) -> String;
    fn head_sha(&self) -> Result<String>;
    fn tracked_paths_at_head(&self) -> Result<Vec<String>>;
    fn tags(&self) -> Result<Vec<TagInfo>>;

    // Provided methods
    fn is_worktree_dirty(&self) -> bool { ... }
    fn merge_or_rebase_in_progress(&self) -> bool { ... }
    fn is_shallow(&self) -> bool { ... }
    fn read_blob_at(&self, _rev: &str, _path: &str) -> Result<Option<Vec<u8>>> { ... }
    fn read_blob_at_head(&self, path: &str) -> Result<Option<Vec<u8>>> { ... }
    fn blob_reader_at<'a>(&'a self, rev: &str) -> Box<dyn BlobReader + 'a> { ... }
    fn worktree_changes(&self) -> Result<Vec<WorktreeChange>> { ... }
}

Read-only git operations needed by the codelore pipeline. See spec §3.3.

Required Methods

fn walk_commits<'a>( &'a self, opts: &'a Options, ) -> Result<Box<dyn Iterator<Item = Result<CommitEvent>> + Send + 'a>>

Walk commits matching opts.after/opts.before. Returns an iterator over the resulting commit events.

fn changed_files(&self, rev: &str) -> Result<Vec<FileChange>>

Per-file changes for one commit.

fn diff_hunks(&self, rev: &str, path: &str) -> Result<Vec<Hunk>>

Hunks within one (commit, path) pair.

fn resolve_alias(&self, name: &str, email: &str) -> String

.mailmap-aware author identity canonicalization. Returns the canonical email for the given (name, email) pair after applying any matching .mailmap rule.

name and email are BOTH significant — .mailmap supports two rule formats:

• Canonical Name <canonical@email> <old@email> (email-only match)
• Canonical Name <canonical@email> Old Name <old@email> (name+email match)

Email-only matches succeed even with name = "", but name+email matches REQUIRE the caller to pass the actual author name. Earlier versions of this trait passed only email; the differential test fixtures didn’t include name+email rules so the bug was invisible — real repos with .mailmap files using the name+email form had GitCliRepo and GixRepo produce different canonical authors for the same commit (GixRepo::walk_commits has its own inline resolution that already passes name+email, while GitCliRepo::walk_commits went through this trait method).

fn head_sha(&self) -> Result<String>

Return the full SHA-1 hex string of HEAD. Used by the persistent cache to build the cache key.

fn tracked_paths_at_head(&self) -> Result<Vec<String>>

Every regular-file blob path (the 0o100xxx mode class — canonical 100644/100755 plus legacy non-canonical variants like 100664) in the HEAD commit’s tree, repo-relative with / separators, sorted ascending. Symlinks (120000) and submodule gitlinks (160000) are excluded — neither carries source bytes the HEAD-time scans can parse.

Unlike the walk-derived live-path reconstruction (most recent change per path is not a deletion), this reads the tree directly, so it works without any commit history in the fact store — the head-only ingest mode depends on that.

fn tags(&self) -> Result<Vec<TagInfo>>

Return all git tags in this repository, sorted ascending by date, tie-broken via [tag_tiebreak_cmp] for same-date tags.

Date semantics:

• Annotated tags — the tagger timestamp (when git tag -a was run).
• Lightweight tags — the target commit’s committer timestamp.

target_rev is always the peeled commit SHA (40-char hex); for annotated tags this is the commit the tag object ultimately points at, not the tag object’s own OID.

Provided Methods

fn is_worktree_dirty(&self) -> bool

Whether tracked content differs from HEAD — staged changes (index vs. HEAD) or unstaged changes (worktree vs. index). Untracked files are excluded: every caller (the calibrate-defects mining guard, the cache-hit staleness warning, the dirty cache-write skip) protects HEAD-time metrics computed over tracked_paths_at_head() only. Exception: a submodule whose only change is untracked content in its own worktree may report dirty (backend-dependent).

Used by the persistent-cache code path to emit a tracing::warn! when a cache HIT occurs on a dirty tree — HEAD-time metrics (complexity, clones) are computed from the working tree at ingest time, so a cached result keyed off head_sha can mismatch what the user sees on disk now. The warning recommends --no-cache.

Default impl returns false (assume clean) so backends without a cheap dirty-check can opt out. Implementations that fail to detect MUST return false rather than propagating an error — a missed warning is better than a hard analyze failure on a state-detection edge case (e.g. unusual submodule layout).

fn merge_or_rebase_in_progress(&self) -> bool

Whether the repository is partway through a merge, rebase, cherry-pick, or revert — an ambiguous-HEAD state where the working tree and HEAD no longer describe one coherent commit. True when any of MERGE_HEAD, CHERRY_PICK_HEAD, REVERT_HEAD, rebase-merge/, or rebase-apply/ is present in the repository’s git dir (worktree- correct: a linked worktree keeps this state in its own git dir, not the common one).

The agent-loop briefing tools call this so they can disclose the ambiguous state honestly rather than presenting committed-HEAD history as the whole picture.

Default impl returns false so backends without a cheap check can opt out. Like is_worktree_dirty, detection is a hint rather than a contract: an implementation that cannot determine the state returns false (a missed note) instead of surfacing an error.

fn is_shallow(&self) -> bool

Whether the repository is a shallow clone — history truncated at a depth boundary, with a non-empty .git/shallow grafts list, so commits beyond the boundary (and the parents of the boundary commits) are absent.

The gate paths consult this to warn that a verdict was computed over partial history: a shallow fetch-depth checkout can leave the fact store empty, or the new-code window without a pre-window baseline, and the operator otherwise has no signal that the checkout — not the repository — is the cause.

Default impl returns false so backends without a cheap check can opt out, mirroring is_worktree_dirty: a missed warning is better than a hard failure on a detection edge case.

fn read_blob_at(&self, _rev: &str, _path: &str) -> Result<Option<Vec<u8>>>

Read the blob bytes at revision rev for path (POSIX- separated, repo-relative). rev is any git revision the backend can resolve — a commit SHA, "HEAD", a tag, etc. Returns Ok(None) if the path isn’t a tracked blob at that revision (deleted there, a directory, or a submodule gitlink). Returns Err only on real object-database I/O failure (corrupted pack, missing shallow object) — NOT on “path doesn’t exist at rev”.

Reading blobs from the object database (rather than the working tree via std::fs::read) is what lets HEAD-time scans (complexity, clones) AND historical scans (architecture-trend) work on bare repos, ignore dirty-worktree edits, and skip untracked files by construction.

Default impl returns Ok(None) so backends without an efficient blob lookup can opt out and fall back to the working-tree path.

fn read_blob_at_head(&self, path: &str) -> Result<Option<Vec<u8>>>

Read the blob bytes at HEAD for path. Convenience wrapper over read_blob_at — the HEAD-time scans’ entry point. Backends override read_blob_at, not this.

Errors

Propagates object-database I/O failures from read_blob_at; “not tracked at HEAD” is Ok(None), not an error.

fn blob_reader_at<'a>(&'a self, rev: &str) -> Box<dyn BlobReader + 'a>

Open a reader for many blobs at rev without re-resolving rev→commit→root-tree on every call. Construction is INFALLIBLE (resolution happens lazily on the first BlobReader::read) so it slots directly into rayon’s map_init idiom — the HEAD-time scans build one per worker thread and reuse it across every file that worker processes.

Default impl: a thin per-call forwarder to read_blob_at, so every backend that doesn’t override this (GitCliRepo — the differential-test oracle — and any future non-gix backend) keeps its exact current per-call behavior.

fn worktree_changes(&self) -> Result<Vec<WorktreeChange>>

Enumerate tracked working-tree changes vs HEAD (union of staged and unstaged, net-classified; untracked files excluded; symlinks and submodule pointers excluded; sorted by path). Errors on unmerged (conflict) entries. Hint quality: backends agree via differential tests.

Default impl returns an empty list so backends without a status facility can opt out — the same convention as is_worktree_dirty.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Repo for GitCliRepo

impl Repo for GixRepo