# 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:
```
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

## Key Features

- 21 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)
- ConGra conflict taxonomy (Text/Syntax/Functional) with resolution hints
- 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 5 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, preview, status, bench, summary commands
- weave-crdt: Automerge-backed agent coordination state
- weave-mcp: MCP server with 15 tools for AI agent integration

## MCP Tools (15)

- weave_extract_entities: list all entities in a file with types and line ranges
- weave_claim_entity: advisory lock before editing (agent_id, file_path, entity_name)
- weave_release_entity: release lock after editing
- weave_status: entity status with claims for a file
- weave_who_is_editing: check if anyone is editing a specific entity
- weave_potential_conflicts: detect entities edited by multiple agents
- weave_preview_merge: dry-run merge analysis between branches
- weave_validate_merge: semantic risk detection (modified entities that reference each other)
- weave_agent_register: register agent in coordination state
- weave_agent_heartbeat: keep-alive with working_on list
- weave_get_dependencies: what this entity calls/references
- weave_get_dependents: who calls/references this entity
- weave_impact_analysis: transitive blast radius via BFS
- weave_diff: entity-level semantic diff between two refs
- weave_merge_summary: parse conflict markers into structured JSON
- weave_merge_audit: per-entity audit trail of merge resolutions

## 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

21 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 |
| 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