StructuredMerge Ruby

StructuredMerge Ruby provides Ruby gems for building merge-aware tools that need portable structured-merge contracts, fixture-backed behavior, and Ruby-native integration points.

The monorepo includes the core AST/review contracts, parser substrate support, format-specific merge gems, binary/ZIP planning helpers, provider adapters, and a Ruby packaging recipe gem.

Project links:

• Website: https://structuredmerge.org
• Implementations: https://structuredmerge.org/implementations.html
• Specification: https://github.com/structuredmerge/structuredmerge-spec
• Shared fixtures: https://github.com/structuredmerge/structuredmerge-fixtures

Package Family

StructuredMerge Ruby is a layered gem family. The lower layers provide parser, range, AST, merge, and template contracts; format gems apply those contracts to specific languages and data formats; provider gems bind a format family to a parser or serializer; workflow gems package the behavior for Git drivers, release automation, and monorepo maintenance.

Package README files keep this section short and link here. This root guide is the implementation inventory for Ruby users who need to choose gems, understand backend coverage, or wire a focused backend into a test suite.

The family is intentionally layered:

• tree_haver provides parser portability, backend discovery, byte ranges, and runtime capability reporting.
• ast-merge provides the cross-format merge substrate: shared base classes, layout/comment ownership, diagnostics, review state, and execution reports.
• Family gems such as markdown-merge, yaml-merge, and toml-merge own parser-neutral behavior for one format family.
• Provider gems such as markly-merge, psych-merge, and citrus-toml-merge register backend-specific parser/emitter behavior.
• Workflow gems such as ast-merge-git, smorg-rb, and kettle-jem package the family for Git, release, and templating workflows.

Core and Workflow Gems

Gem	Layer	What it provides
tree_haver	Parser substrate	Parser backend registry, byte ranges, node wrappers, source locations, binary tree contracts, and backend selection helpers.
ast-merge	Merge substrate	AST merge contracts, diagnostics, structural edit plans, review/replay vocabulary, nested merge orchestration, backend provider registration, and shared spec helpers.
ast-template	Template substrate	Template/session transport objects used by recipe tooling and language-specific templating layers.
ast-merge-git	Git integration	Merge-driver, diff-driver, conflict inspection, language registry, and command plumbing for smorg-rb.
smorg-rb	Command package	Ruby implementation command packaging and executable entry points.
kettle-jem	Recipe tooling	Template recipes, monorepo root materialization, gem maintenance helpers, and StructuredMerge Ruby release support.

Transformation Gems

Gem	Layer	What it provides
ast-crispr	Generic AST edits	Structured document surgery recipes for generated blocks and template-owned regions.
ast-crispr-ruby-prism	Ruby AST edits	Prism-backed Ruby source edits, including require insertion and template-managed Ruby regions.
ast-crispr-markdown-markly	Markdown AST edits	Markly-backed Markdown block replacement and README recipe support.

Format Gems

Gem	Family	What it provides
plain-merge	Text	Line-backed TreeHaver parser registration, plain-text fallback contracts, and conflict-preserving merge behavior.
json-merge	JSON and JSONC	Object/array-aware JSON merge behavior using the shared StructuredMerge merge substrate and tree-sitter JSON grammar coverage where the selected backend supplies it.
yaml-merge	YAML	YAML-family merge contracts, shared provider tags, and provider-neutral behavior.
toml-merge	TOML	TOML-family merge contracts and provider-neutral behavior.
dotenv-merge	dotenv	Dotenv line parser registration and key/value configuration merge behavior built on the plain text substrate.
markdown-merge	Markdown	Markdown-family merge contracts, heading/table/list matching, link-reference handling, fenced-code flow, and provider-neutral behavior.
ruby-merge	Ruby source	Ruby source merge contracts and parser-backed source-language behavior.
rbs-merge	RBS	Ruby signature merge behavior, declaration matching, and template-owned signature updates using RBS and tree-sitter RBS grammar coverage where available.
bash-merge	Bash source	Shell source merge contracts and parser-backed shell-language behavior using tree-sitter Bash where available.
go-merge	Go source	Go source merge contracts for the cross-language StructuredMerge family.
rust-merge	Rust source	Rust source merge contracts for the cross-language StructuredMerge family.
typescript-merge	TypeScript source	TypeScript source merge contracts for the cross-language StructuredMerge family.
binary-merge	Binary	Kaitai/binary-family substrate for byte-range ownership, preservation reports, unsafe diagnostics, and renderer planning.
zip-merge	Archives	ZIP parser registration and archive-aware merge contracts built on the binary-family substrate.

Provider Gems

Provider gems register themselves with the backend tag system used by ast-merge and tree_haver. That registry lets a spec suite run against a single selected backend, lets a format gem ask for a capability instead of a hard dependency, and keeps parser-specific behavior out of provider-neutral merge gems.

Gem	Provides	Runtime notes
psych-merge	YAML provider	Uses Ruby's Psych parser and emitter.
citrus-toml-merge	TOML provider	Registers a TreeHaver TOML backend backed by a Citrus grammar, commonly paired with toml-rb style TOML data handling.
parslet-toml-merge	TOML provider	Registers a TreeHaver TOML backend backed by Parslet, commonly paired with toml style TOML data handling.
commonmarker-merge	Markdown provider	Uses CommonMarker for CommonMark-oriented Markdown parsing.
kramdown-merge	Markdown provider	Uses Kramdown for Ruby-native Markdown parsing.
markly-merge	Markdown provider	Uses Markly for cmark-gfm-backed Markdown parsing and README templating support.
prism-merge	Ruby provider	Uses Prism for Ruby source parsing and Ruby-specific merge refiners.

Ruby Backend Notes

Ruby has the broadest backend surface in the StructuredMerge implementation set. tree_haver owns the parser backend registry and byte-range contracts; ast-merge owns provider registration and merge orchestration. The backend tags are capability names, not package preferences.

Backend or provider path	Used by	Notes
:TSLP	source-family gems	Uses tree-sitter-language-pack parser aggregation where available. This is the preferred tree-sitter provider path for broad language coverage.
:MRI	source-family gems	Uses ruby_tree_sitter; retained as the MRI-native tree-sitter backend name.
:rust	source-family gems	Uses tree_stump where that native Rust-backed parser path is selected.
:ffi	source-family gems	Uses FFI bindings to libtree-sitter; suitable where the runtime and native library support the needed ABI.
:java	source-family gems	Uses JVM tree-sitter bindings through java-tree-sitter / jtreesitter for JRuby-oriented parser runs.
Prism	ruby-merge, prism-merge, ast-crispr-ruby-prism	Ruby-native parser path for Ruby source and structured Ruby source edits.
Psych	yaml-merge, psych-merge	Ruby standard YAML parser/emitter path.
RBS	rbs-merge	Ruby signature parser path.
CommonMarker, Markly, Kramdown	markdown-merge providers	Markdown parser families with different CommonMark/GFM/Ruby-native tradeoffs.
Citrus, Parslet	toml-merge providers	Pure-Ruby TOML parser families exposed as provider-specific TreeHaver backend paths.
Kaitai Struct	binary-merge, zip-merge	Schema-oriented binary parsing support and shared binary-family merge behavior.

Backend Platform Compatibility

tree_haver supports multiple Ruby parser backends, but not every backend works on every Ruby runtime:

TreeHaver backend	MRI	JRuby	TruffleRuby	Notes
:TSLP (tree-sitter-language-pack)	✅	❓	❓	Aggregated tree-sitter provider used by StructuredMerge language-family gems where available.
:MRI (ruby_tree_sitter)	✅	❌	❌	C extension, MRI only.
:rust (tree_stump)	✅	❌	❌	Rust extension through Ruby native-extension tooling, MRI only.
:ffi (FFI + libtree-sitter)	✅	✅	❌	TruffleRuby FFI does not support the tree-sitter struct-by-value ABI.
:java (java-tree-sitter / jtreesitter)	❌	✅	❌	JRuby-oriented path that requires matching grammar JARs.
Prism	✅	✅	✅	Ruby parser, standard library in Ruby 3.4+.
Psych	✅	✅	✅	YAML parser/emitter, standard library.
Citrus	✅	✅	✅	Pure Ruby PEG parser.
Parslet	✅	✅	✅	Pure Ruby PEG parser.
CommonMarker	✅	❌	❓	Native Markdown parser used through commonmarker-merge.
Markly	✅	❌	❓	Native cmark-gfm parser used through markly-merge.
Kramdown	✅	✅	✅	Pure Ruby Markdown parser.

Legend: ✅ = works, ❌ = does not work, ❓ = not part of the supported runtime claim.

Install

Install the gems your tool needs:

bundle add ast-merge json-merge

Command

The Ruby implementation ships the implementation-specific smorg-rb command. Use that name in git configuration unless a package manager or local install has provided a smorg symlink.

Package-manager formulas may expose the selected implementation as smorg. For a local user-created symlink:

ln -s "$(command -v smorg-rb)"~/.local/bin/smorg

git config merge.smorg-rb.driver 'smorg-rb merge-driver %O %A %B %P'
git config diff.smorg-rb.command 'smorg-rb diff-driver'
smorg-rb conflicts diff path/to/file-with-conflicts.go
smorg-rb languages --gitattributes

merge-driver updates Git's %A file by default, or writes to --output when used outside git. diff-driver accepts both the two-argument local form and the seven- or nine-argument forms Git passes to external diff commands. conflicts diff reports conflict-marker regions in a file that already contains Git conflict markers.

Semantic merge-driver coverage is fixture-backed for JSON. Other language and format paths are git-compatible command surfaces without semantic driver coverage.

Gems

Core and transformation gems:

• tree_haver - parser substrate, byte ranges, backend adapters, and binary tree contracts.
• ast-merge - AST merge contracts, diagnostics, planning, review, replay, and nested-merge vocabulary.
• ast-template - template/session transport contracts.
• ast-crispr - generic AST edit recipes for generated blocks and template-owned regions.
• ast-crispr-ruby-prism - Prism-backed Ruby source edits.
• ast-crispr-markdown-markly - Markly-backed Markdown source edits.

Format libraries:

• plain-merge
• bash-merge
• dotenv-merge
• json-merge
• rbs-merge
• yaml-merge
• toml-merge
• markdown-merge
• ruby-merge
• go-merge
• rust-merge
• typescript-merge
• binary-merge
• zip-merge

Provider and recipe gems:

• ast-merge-git
• psych-merge
• citrus-toml-merge
• parslet-toml-merge
• commonmarker-merge
• kramdown-merge
• markly-merge
• prism-merge
• kettle-jem
• smorg-rb

Portability

The Ruby gems are developed against the [shared StructuredMerge fixtures][structuredmerge-fixtures]. Those fixtures define the cross-language behavior expected from the Go, TypeScript, Rust, and Ruby implementations. Conformance checks live in gem specs and in the shared spec/fixture tooling rather than in a static status document.

Development

Use the family tooling from the monorepo root for broad checks:

bundle exec kettle-family install --execute
bundle exec kettle-family lint --execute
bundle exec kettle-family test --execute

For a single gem, run commands from that gem directory:

bundle exec kettle-test
bin/rake rubocop_gradual:autocorrect

Prefer kettle-test over direct rspec so local verification exercises the same parallel runner, worker isolation, filtering, and formatter behavior used by CI. Use direct rspec only for narrow debugging when kettle-test cannot express the probe, then rerun kettle-test before treating the suite as verified.

Bundler path gems are the default isolation mechanism inside this monorepo. When this repository needs to consume sibling workspace projects outside the monorepo itself, prefer nomono-driven Bundler wiring rather than manual Ruby load-path changes.