# 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; the first box's closing marker line also names `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, exit 2 nothing verified (git failed, or the run passed `--timeout`, default
  300 s). 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, one tool per weave command, for AI agent integration
- weave-github: GitHub integration

## MCP Tools

Listed, one per weave command:
- weave_preview: dry-run a merge of two branches; detail summary (default) | findings | entities
- weave_explain: why a file conflicted, from the merge's three stages; markers=true summarizes weave markers in the file
- weave_check: verify the resolution in the working tree plus cross-file breakage (DANGLING, SHADOW); base/ours/theirs for two revisions
- weave_land: label a stopped merge's files PROVEN / VERIFIED / REFUSED and write the ones that pass; dry_run, resolver, revisions
- weave_patch: extract typed entity ops (base_content -> file) or apply them (ops) to a drifted file, three-way

For callers, dependencies and blast radius use sem's MCP server (sem_find, sem_impact).
Older tool names (weave_findings, weave_preview_merge, weave_merge_audit, weave_diff, weave_get_dependents, ...)
still answer when called but are not listed.

Experimental, listed only with WEAVE_EXPERIMENTAL=1: 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