weavatrix-git

# Weavatrix Git

[![CI](https://github.com/sergii-ziborov/weavatrix-git/actions/workflows/ci.yml/badge.svg)](https://github.com/sergii-ziborov/weavatrix-git/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/weavatrix-git.svg)](https://crates.io/crates/weavatrix-git)
[![npm](https://img.shields.io/npm/v/weavatrix-git.svg)](https://www.npmjs.com/package/weavatrix-git)
[![docs.rs](https://docs.rs/weavatrix-git/badge.svg)](https://docs.rs/weavatrix-git)

`weavatrix-git` gives AI coding agents fast, bounded, read-only Git evidence.
Install it from npm as a native MCP server or embed its dependency-free Rust
core. Both paths parse repository storage directly: no `git` subprocess, C
library, hooks, filters, network access, checkout, or mutation.

On the checked-in exact-parity benchmark, 1,000 warm history entries took
**0.355 ms** with Weavatrix, **0.884 ms** with `gix`, and **1.552 ms** with
`libgit2`. Across eight repositories, Weavatrix won all five measured p50
contracts. These are engine measurements from release builds; the MCP
transport is deliberately not hidden inside the claim.

## Run the MCP server

No Rust toolchain is required:

```bash
npx -y weavatrix-git@0.3.1 --repository /absolute/path/to/repository
```

Generic stdio client configuration:

```json
{
  "mcpServers": {
    "weavatrix-git": {
      "command": "npx",
      "args": [
        "-y",
        "weavatrix-git@0.3.1",
        "--repository",
        "/absolute/path/to/repository"
      ]
    }
  }
}
```

The npm package contains verified native binaries for Windows x64, Linux x64
and ARM64, and macOS x64 and ARM64. Node only selects and launches the matching
binary; repository parsing and MCP handling stay in safe Rust.

### Tools for agents

| MCP tool | Evidence returned |
| --- | --- |
| `git_head` | repository identity, hash kind, symbolic HEAD, exact target ID, pack count |
| `git_history` | paginated commit IDs, trees, parents, signatures, timestamps, summaries |
| `git_diff` | paginated added/deleted/modified/type-changed paths with old/new object IDs |
| `git_status` | tracked index and worktree state; untracked files are intentionally excluded |
| `git_snapshot` | canonical immutable path, mode, kind, and object-ID manifest for a revision |

Every list tool returns `nextCursor`, exact object IDs, and a `truncated` flag.
Non-UTF-8 paths retain their exact bytes in `pathHex`; display text is never
silently presented as exact evidence.

### Runtime limits

The MCP binary uses [`mcport`](https://crates.io/crates/mcport)'s controlled,
Tokio-free runtime:

- 256 KiB maximum request and 1 MiB maximum response;
- four in-flight handlers and bounded request/output queues;
- 30-second handler deadline with cooperative cancellation checks;
- panic isolation and atomic response-overflow errors;
- bounded Git object, history, tree, bitmap, reflog, and index reads;
- optional progress notifications and configurable response batching.

Defaults are suitable for interactive stdio. `--help` exposes overrides for
byte budgets, concurrency, queues, deadline, and batch size. The server writes
only newline-delimited UTF-8 JSON-RPC to stdout; diagnostics go to stderr.

Native Cargo installation is also available:

```bash
cargo install weavatrix-git --version 0.3.1 --features mcp \
  --bin weavatrix-git-mcp
weavatrix-git-mcp --repository /absolute/path/to/repository
```

## Why a separate crate?

A scanner discovers files. A code graph models relationships. This crate owns
version-control evidence. Keeping that boundary independent lets any Rust
application reuse Git intelligence without importing a larger product.

## Supported contract

| Area | Support |
| --- | --- |
| Layouts | worktree, bare, `.git` indirection, linked worktree `commondir` |
| Hashes | SHA-1 and SHA-256 object identifiers |
| Refs | loose, symbolic, detached HEAD, packed refs, reflogs |
| Objects | commit, tree, blob, annotated tag |
| Loose storage | bounded zlib/DEFLATE decoded by this crate |
| Packed storage | PACK v2/v3, index v2, OFS_DELTA, REF_DELTA |
| Object lookup | alternates, classic MIDX, caches, shared zero-copy snapshots |
| Commit acceleration | monolithic and split commit-graph chains |
| Path acceleration | changed-path Bloom filters v1/v2 |
| Reachability | pack and MIDX EWAH bitmaps with RIDX ordering |
| Index | DIRC v2/v3/v4, auto-refreshing shared snapshots |
| Queries | typed reads, lazy revwalk, history, tracked status, tree diff |
| Immutable views | canonical commit snapshots with path, mode, and object evidence |
| Scale-out | parallel open, revision-aware timelines, change sets, correlation |
| Extension | ordered, thread-safe, read-only custom ODB backends |

All public reads are in-process. Library code contains no subprocess fallback.
Unsupported data returns a typed error rather than an approximate answer.

## Rust library

```rust
use weavatrix_git::{PathBloom, Repository};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let repository = Repository::open(".")?;
    let head = repository.resolve("HEAD")?;

    for id in repository.revwalk().push_head()?.take(100) {
        println!("{}", id?);
    }

    if repository.commit_maybe_changed_path(head, b"src/lib.rs")?
        == Some(PathBloom::DefinitelyNot)
    {
        println!("the commit definitely did not change src/lib.rs");
    }

    if let Some(objects) = repository.bitmap_reachable(head)? {
        println!("{} reachable objects", objects.len());
    }
    Ok(())
}
```

Custom stores use the same object contract:

```rust
use std::sync::Arc;
use weavatrix_git::{Limits, MemoryObjectBackend, Repository};

let backend = Arc::new(MemoryObjectBackend::default());
let repository =
    Repository::open_with_backends(".", Limits::default(), vec![backend])?;
# Ok::<_, weavatrix_git::GitError>(repository)
```

For cross-repository analysis, `RepositorySet` keeps object stores isolated and
returns deterministic serial or parallel results:

```rust
use weavatrix_git::{HistoryOptions, RepositorySet};

let repositories = RepositorySet::open_parallel([
    ("service", "/code/service"),
    ("client", "/code/client"),
])?;
let histories =
    repositories.histories_from_parallel("HEAD", HistoryOptions::default())?;
let snapshots = repositories.snapshots_parallel("HEAD")?;
let timeline = repositories.timeline("HEAD", HistoryOptions::default())?;
let shared = repositories.shared_commits(HistoryOptions::default())?;
# Ok::<_, weavatrix_git::GitError>((histories, snapshots, timeline, shared))
```

The diagnostic CLI uses the library:

```text
weavatrix-git [-C repository] head
weavatrix-git [-C repository] log [revision] [max-count]
weavatrix-git [-C repository] cat <object>
weavatrix-git [-C repository] diff <old-commit> <new-commit>
```

## Architecture

```text
Repository
  +-- refs + reflog
  +-- commit-graph chain + changed-path Bloom
  +-- index -> tracked status
  +-- custom ODB backends
  +-- object directories + alternates
        +-- loose object -> bounded zlib
        +-- MIDX -> pack -> bounded delta chain
        +-- pack/MIDX bitmap -> reachable object IDs
```

`Limits` bounds object bytes, cache bytes, delta/ref/tree depth, tree and index
entries, reflog/history length, parent count, and bitmap expansion. The crate
forbids unsafe Rust. The default library feature set remains dependency-free;
only the separate `mcp` feature adds `mcport`.

The source tree follows explicit modular boundaries:

| Layer | Responsibility |
| --- | --- |
| `model` | object IDs, typed Git objects, errors, and validation contracts |
| `storage` | loose/pack/MIDX/commit-graph decoding, bounded inflate and caches |
| `repository` | refs, history, diffs, status, snapshots, trees, and revwalks |
| `workspace` | deterministic multi-repository queries and correlation |
| `mcp` | optional read-only protocol adapter over the library |
| `facade / CLI` | stable Rust exports and diagnostic command entry points |

The checked-in strict architecture contract rejects files over 300 physical
lines, functions over 100 physical lines, runtime cycles, mixed `foo.rs` plus
`foo/` module ownership, and any dependency from the protocol-independent
library into the optional MCP adapter. It has no baseline or exceptions.

## Correctness

The suite creates real Git repositories and verifies:

- loose and aggressively packed OFS/REF delta objects;
- SHA-1 and SHA-256 repositories;
- bare and linked-worktree layouts;
- classic MIDX lookup;
- multi-layer split commit-graphs and changed-path Bloom answers;
- pack and MIDX bitmap reachability against `git rev-list --objects`;
- index v2 and v4, reflog order, revwalk hide/reset, and tracked status;
- deterministic parallel and cross-repository results;
- immutable revision snapshots, merged timelines, and batch change sets;
- hostile format and configured-limit failures.

Current core line coverage is 85.27%. CI runs Rust 1.88 on Linux, Windows, and macOS,
Clippy with warnings denied, coverage, audit, docs, and package verification.

## Performance

Release measurements on Windows, 2026-07-27. Every row materializes the result
and proves exact identifier, path, object-byte, or status parity before timing:

| Exact-parity operation | `weavatrix-git` p50 | `git.exe` p50 |
| --- | ---: | ---: |
| 6,000-object bitmap reachability | 0.431 ms | 72.656 ms |
| one-entry index read | 0.033 ms | 60.758 ms |
| clean tracked status | 0.186 ms | 72.735 ms |
| cached commit lookup | 0.001 ms | 65.267 ms |
| 1,000-commit history, reused repository | 0.086 ms | 66.961 ms |

Direct in-process comparison on the same packed 2,000-commit fixture:

| Exact-parity operation | Weavatrix p50 | `gix` 0.86 p50 | `git2` 0.21 p50 |
| --- | ---: | ---: | ---: |
| 1,000-commit history, warm | 0.355 ms | 0.884 ms | 1.552 ms |
| 1,000-commit history, reopen | 2.521 ms | 3.940 ms | 10.483 ms |
| 1,000 cached object reads | 0.082 ms | 0.068 ms | 5.640 ms |
| history plus 1,000 raw objects | 0.494 m