weave

# weave

> Entity-level semantic merge driver for Git. Resolves conflicts at the function and class level using tree-sitter.

## Overview

weave replaces git's line-level merge with entity-level merge. It parses all three versions (base, ours, theirs) with tree-sitter, extracts functions/classes/methods, matches them by name and structural hash, and merges per-entity instead of per-line.

Two developers editing different functions in the same file? No conflict. Git would flag this as a conflict because the line ranges overlap. weave knows they're different entities and merges cleanly.

## Install

```
brew install weave
weave setup
```

Or build from source. Two binaries, both required — `weave` (the CLI) and
`weave-driver` (the binary git itself invokes; `weave setup` needs it on PATH):
```
git clone https://github.com/Ataraxy-Labs/weave
cd weave && cargo install --path crates/weave-cli
cargo install --path crates/weave-driver
```

## Benchmark

31 synthetic merge scenarios across 7 languages:
- weave: 31/31 clean (100%)
- mergiraf: 26/31 clean (83%)
- git: 15/31 clean (48%)

Real-world benchmarks (4,917 file merges from 5 major repos):
- 83 wins (git conflicted, weave resolved cleanly)
- 0 regressions on C, Python, Go
- Repos tested: git/git (C), Flask (Python), CPython (C/Python), Go (Go), TypeScript (TS)

Full benchmark suite: 11ms. Individual merges: 65-374us.

## How It Works

1. Parse all three versions with tree-sitter into entity lists
2. Split file into Entity and Interstitial regions
3. Match entities across versions by name and structural_hash
4. Per-entity resolution: only-ours, only-theirs, both-identical, or true conflict
5. Inner entity merge: when both modify the same class, decompose into methods and merge by name
6. Reconstruct file preserving ours-side ordering
7. A real conflict leaves a marker box with one `refused_by: <guard> · collision: <line>` line
   naming why, plus a trailing comment naming `weave explain` and `weave check`

## Resolving a conflict

- `weave explain <file>` — per conflicted entity: which guard refused, and the hunks BOTH
  sides wrote in. Reads the three merge stages out of git's index.
- `weave check` — with no arguments, verifies the WORKING TREE (the file as edited) against
  the three merge stages: leftover markers, unanimous-line loss, duplicated lines/definitions,
  dangling references. One verdict sentence per file, never a bare empty result. Exit 0 clean,
  exit 1 findings. With `--base/--ours/--theirs` it instead checks two revisions for cross-file
  binding breakage (a rename in one file orphaning a caller in another) and emits JSON findings.
- `weave patch extract/apply` — typed entity ops: extract the ops that turn one file into
  another, apply them three-way to a target that may have drifted from the base.

## Key Features

- 23 languages + 5 data formats (see full list below)
- Rename detection via confidence-scored structural hashing (0.95/0.8/0.6 scoring)
- Commutative import merge with group preservation
- Unordered class members (methods added at same position resolve cleanly)
- Inner entity merge (both modify same class, methods merged independently)
- Comment/decorator bundling (decorators move with their function)
- Conflict classification (Text/Syntax/Functional) with a stated refusal reason, not advice
- Multi-line signature detection (paren depth tracking)
- Cosmetic vs structural change detection
- Post-merge semantic + parse validation
- LRU entity cache in MCP server (500 entries)
- Configurable: WEAVE_TIMEOUT, WEAVE_MAX_DUPLICATES, WEAVE_REPO

## Architecture

Cargo workspace with 6 crates:
- weave-core: merge algorithm, entity extraction via sem-core, diffy fallback
- weave-driver: git merge driver binary (called with %O %A %B %L %P)
- weave-cli: setup, explain, check, patch, preview, status, bench, summary commands
- weave-crdt: Automerge-backed agent coordination state
- weave-mcp: MCP server with 22 tools for AI agent integration
- weave-github: GitHub integration

## MCP Tools (22)

Merge analysis — read git refs or the working tree directly, no setup needed:
- weave_findings: typed findings for a merge between two branches (the agent-facing read contract)
- weave_check: cross-file binding check between two revisions (defaults to HEAD x MERGE_HEAD)
- weave_preview_merge: dry-run clean/conflict verdict and stats between two branches
- weave_diff: entity-level diff between two refs (added/modified/deleted/renamed)
- weave_merge_audit: per-entity resolution-strategy audit trail for a two-branch merge
- weave_validate_merge: semantic-risk subset of weave_findings (modified entities referencing modified entities)
- weave_merge_summary: parse an already-conflicted file's markers into structured JSON
- weave_extract_entities: list entities in a file with type and line range
- weave_get_dependencies / weave_get_dependents: what an entity calls / who calls it
- weave_impact_analysis: full transitive blast radius of changing an entity

Live coordination — a shared CRDT (.weave/state.automerge) for agents editing one repo at once;
call weave_agent_register first:
- weave_agent_register / weave_agent_heartbeat: announce and keep an agent's presence live
- weave_claim_entity / weave_release_entity: advisory lock before/after editing an entity
- weave_status / weave_who_is_editing / weave_potential_conflicts: see claims and live collisions
- weave_update_entity_content / weave_get_entity_content: write/read an entity's CRDT content
- weave_merge_file: entity-level merge of one file's CRDT state
- weave_resolve_conflict: resolve an entity weave_merge_file flagged as conflicted

Concurrent-edit backstop: weave_update_entity_content accepts an optional whole-file
snapshot pair (base_content = the file as you read it, ours_content = the file as you
intend it). If the disk drifted since your read, disjoint entity changes merge clean —
the response carries merged_content for YOU to write (weave never writes files) plus
merged_over naming what changed underneath — and a true same-entity collision is
refused with merge_conflicts instead of overwriting anyone. weave_claim_entity's
response includes entity_id; pass it back to update/release so a rename between claim
and update never breaks the claim.

Known limitation (disclosed, deliberate): there is a window between weave's drift
check (its fresh read of the file) and the caller's own subsequent write of
merged_content — a third writer landing inside that window can still be overwritten.
The claim fast-path narrows the window and a caller's post-write verification catches
most fallout; file locking is deliberately out of scope.

## MCP Setup

```
# Claude Code
claude mcp add --scope user weave -- weave-mcp

# Claude Desktop (~/.config/claude/claude_desktop_config.json)
{ "mcpServers": { "weave": { "command": "weave-mcp" } } }
```

## Language Support

23 programming languages:

| Language | Extensions | Entity Types |
|----------|-----------|--------------|
| TypeScript | .ts .tsx | functions, classes, interfaces, types, enums, exports |
| JavaScript | .js .jsx .mjs .cjs | functions, classes, variables, exports |
| Python | .py | functions, classes, decorated definitions |
| Go | .go | functions, methods, types, vars, consts |
| Rust | .rs | functions, structs, enums, impls, traits, mods, consts |
| Java | .java | classes, methods, interfaces, enums, fields, constructors |
| Dart | .dart | classes, functions, methods, enums, extensions, mixins |
| Scala | .scala .sc .sbt | classes, objects, traits, functions, types |
| C | .c .h | functions, structs, enums, unions, typedefs |
| C++ | .cpp .cc .hpp | functions, classes, structs, enums, namespaces, templates |
| C# | .cs | classes, methods, interfaces, enums, structs, properties |
| Ruby | .rb | methods, classes, modules |
| PHP | .php | functions, classes, methods, interfaces, traits, enums |
| Swift | .swift | functions, classes, protocols, structs, enums, properties |
| Elixir | .ex .exs | modules, functions, macros, guards, protocols |
| Bash | .sh | functions |
| HCL/Terraform | .hcl .tf .tfvars | blocks, attributes (qualified names) |
| Kotlin | .kt .kts | classes, interfaces, objects, functions, properties |
| Fortran | .f90 .f95 .f | functions, subroutines, modules, programs |
| Vue | .vue | template/script/style blocks + inner TS/JS entities |
| Svelte | .svelte .svelte.js .svelte.ts | component blocks, rune modules + inner JS/TS entities |
| XML | .xml .plist .svg .csproj | elements (nested, tag-name identity) |
| ERB | .erb | blocks, expressions, code tags |

Plus structured data formats:

| Format | Extensions | Entity Types |
|--------|-----------|--------------|
| JSON | .json | properties, objects (RFC 6901 paths) |
| YAML | .yml .yaml | sections, properties (dot paths) |
| TOML | .toml | sections, properties |
| CSV | .csv .tsv | rows (first column as ID) |
| Markdown | .md .mdx | heading-based sections |

## Git Integration

weave plugs into git as a merge driver. Works with merge, rebase, and cherry-pick.

```
# .gitattributes (created by weave setup)
*.ts merge=weave
*.py merge=weave
*.rs merge=weave
# ... all supported extensions
```

## Links

- GitHub: https://github.com/Ataraxy-Labs/weave
- Website: https://ataraxy-labs.github.io/weave
- Homebrew: brew install weave
- Entity extraction: https://github.com/Ataraxy-Labs/sem (sem-core)
- License: MIT