Structured Merge

Software projects have learned how to lint, format, test, and typecheck with precision. But when it comes to combining structured files, we still fall back to line diffs, brittle heuristics, and hand-maintained exceptions.

That is the problem Structured Merge is trying to solve.

Structured Merge is a new cross-language effort to define and implement a better model for merging structured content: not just text, but syntax-aware formats, comment-bearing formats, and full AST-backed source code workflows. The goal is not another ad hoc merge tool for one ecosystem. The goal is a portable merge stack, a shared lexicon, and a real conformance-oriented spec that can survive across implementations.

The work started in Ruby, where a family of libraries explored AST-aware merge behavior, parser adapters, text refinement, YAML / JSON / JSONC / TOML / Ruby / RBS / Bash / Dotenv / Markdown handling, fallback semantics, policy reporting, templating workflows, and recipe-driven behavior. That work proved the space is real, but it also made something else clear: if the ideas are worth keeping, they need to be separated from the accidents of one implementation language.

So Structured Merge is taking the next step.

We are now building the stack in parallel across:

• 💠 Go
• 💠 Ruby (re-building from scratch)
• 💠 Rust
• 💠 TypeScript

Each language family is being developed as a monorepo of publishable libraries, with a shared fixture corpus and a growing conformance surface. The point is not to “port the original Ruby implementation”. The point is to pressure the ideas until they become specification-grade.

That means we are asking hard questions early:

• 💠 What is a parse result?
• 💠 What counts as a destination parse failure?
• 💠 How should fallback be represented?
• 💠 What is a policy, and how is it reported?
• 💠 How do family capabilities differ from backend capabilities?
• 💠 What is the stable contract for planning, selecting, running, and reporting conformance cases?
• 💠 Which behaviors are essential, and which are implementation detail?

The early results have already been useful. By implementing the same slices across multiple languages, we have been able to tighten vocabulary, expose hidden assumptions, and distinguish true merge semantics from historical coupling. Some Ruby behavior has held up well. Some of it has not. That is exactly what this project is for.

Pragmatic Near Term Goals

• 💠 build a shared spec vocabulary
• 💠 define portable conformance fixtures
• 💠 implement observable behavior slice by slice
• 💠 keep CI honest across all active implementations
• 💠 support tree-sitter-backed and PEG-based parsing where practical
• 💠 make policy, capability, and result reporting explicit

Large Long Term Goals

Structured Merge is meant to become a foundation for:

• 💠 syntax-aware merge engines
• 💠 format-specific merge libraries
• 💠 templating and scaffold reconciliation
• 💠 ruleset-driven merge behavior
• 💠 document comparison and similarity workflows
• 💠 eventually, reliable structured merge infrastructure across ecosystems

This project is still early, but it is no longer just an experiment. The repositories are public, the conformance work is active, and the shape of the system is becoming clearer with every slice.

If you care about structured files, ASTs, parser-backed tooling, reproducible merge behavior, or the future of language-aware development tooling, this project is for you.

Structured Merge is an attempt to treat document merge as a first-class engineering problem.

Not as a patch on top of line diffs. Not as an editor feature. Not as a bundle of one-off special cases.

As a real system, with a real spec, and implementations that can prove it.

This organization was created by @pboling, @afstanton, and @Aboling0 to support the development of a shared standard language & contract for document merge operations.