鈽笍 ast-merge: TreeHaver-based merge/templating tool
Published on December 19, 2025 by Peter Boling
馃尰 Synopsis
Ast::Merge provides base classes, modules or building intelligent file mergers using AST analysis. Ast::Merge is **not typically used directly** - instead, use one of the format-specific gems built on top of it.
The `*-merge` Gem Family
Provides intelligent, AST-based merging for various file formats. At the foundation is tree_haver, which provides a unified cross-Ruby parsing API that works seamlessly across MRI, JRuby, and TruffleRuby.
聽
The *-merge gem family is built on a two-layer architecture:
聽
Layer 1: tree_haver (Parsing Foundation)
- Universal Backend Support: Automatically selects the best parsing backend for your Ruby implementation (MRI, JRuby, TruffleRuby)
- 10 Backend Options: MRI C extensions, Rust bindings, FFI, Java (JRuby), language-specific parsers (Prism, Psych, Commonmarker, Markly), and pure Ruby fallback (Citrus)
- Unified API: Write parsing code once, run on any Ruby implementation
- Grammar Discovery: Built-in GrammarFinder for platform-aware grammar library discovery
- Thread-Safe: Language registry with thread-safe caching
Layer 2: ast-merge (Merge Infrastructure)
- Base Classes: FreezeNode, MergeResult base classes with unified constructors
- Shared Modules: FileAnalysisBase, FileAnalyzable, MergerConfig, DebugLogger
- Freeze Block Support: Configurable marker patterns for multiple comment syntaxes (preserve sections during merge)
- Node Typing System: NodeTyping for canonical node type identification across different parsers
- Conflict Resolution: ConflictResolverBase with pluggable strategies
- Error Classes: ParseError, TemplateParseError, DestinationParseError
- Region Detection: RegionDetectorBase, FencedCodeBlockDetector for text-based analysis
- RSpec Shared Examples: Test helpers for implementing new merge gems