ast-merge v4.0.0 released!

4.0.0 - 2026-01-11

• TAG: v4.0.0
• COVERAGE: 96.52% – 2555/2647 lines in 51 files
• BRANCH COVERAGE: 87.62% – 814/929 branches in 51 files
• 98.80% documented

Added

• Recipe::Preset#normalize_whitespace - option to collapse excessive blank lines in merged output
• Recipe::Preset#rehydrate_link_references - option to convert inline links to reference style
• Recipe::Runner::Result#problems - access document problems found during merge
• exe/ast-merge-recipe --show-problems - flag to display document problems in CLI output
• Ast::Merge::DiffMapperBase - Abstract base class for mapping unified git diffs to AST node paths
  • DiffHunk struct for representing diff hunks with line numbers and content
  • DiffLine struct for individual diff lines with type (:context, :addition, :removal)
  • DiffMapping struct for mapping changes to AST paths with operation type
  • DiffParseResult struct for parsed diff with file paths and hunks
  • #parse_diff(diff_text) - Parse unified git diff format into structured hunks
  • #determine_operation(hunk) - Detect :add, :remove, or :modify from hunk content
  • Abstract #map_hunk_to_paths for format-specific implementations
  • Abstract #create_analysis for format-specific file analysis
• Ast::Merge::ConflictResolverBase - New options for advanced merge control:
  • recursive: true | false | Integer - Control recursive merging of nested structures
    • true (default): Unlimited depth recursive merging
    • false: Disabled, replace entire matched nodes
    • Integer > 0: Maximum recursion depth
    • 0: Invalid, raises ArgumentError
  • remove_template_missing_nodes: false - When true, removes destination nodes not present in template
  • #should_recurse?(depth) - Helper to check if recursion should continue at given depth
  • #validate_recursive! - Validation for recursive parameter
• exe/ast-merge-diff - CLI executable for applying git diffs via AST-aware merging
  • Auto-detects format from file extension (.yml, .yaml, .json, .rb, etc.)
  • --diff FILE - Path to unified diff file (use - for stdin, default: stdin)
  • --original FILE - Original file for AST path mapping (required)
  • --destination FILE - Destination file to merge into (required)
  • --format FORMAT - Override format auto-detection
  • --dry-run - Preview changes without writing
  • --verbose - Detailed output
  • --add-only - Only apply additions from diff
  • --remove-only - Only apply removals from diff
  • Uses bundler/inline with dynamic gem loading based on detected format

Changed

• BREAKING: Upgrade to tree_haver v5.0.0
• BREAKING: Refactored navigation classes into Ast::Merge::Navigable namespace
  • Ast::Merge::NavigableStatement → Ast::Merge::Navigable::Statement
  • Ast::Merge::InjectionPoint → Ast::Merge::Navigable::InjectionPoint
  • Ast::Merge::InjectionPointFinder → Ast::Merge::Navigable::InjectionPointFinder
  • Each class is now in its own file under lib/ast/merge/navigable/
  • Uses autoload for lazy loading
• bin/fix_readme_formatting - Rewritten to use SmartMerger API
  • Now uses Markdown::Merge::SmartMerger with normalize_whitespace: :link_refs and rehydrate_link_references: true
  • The :link_refs mode collapses excessive blank lines AND removes blank lines between consecutive link reference definitions
  • Merges empty template with destination to apply cleanup transformations
  • Reports duplicate link definitions, link ref spacing fixes, and other problems from MergeResult#problems
  • Removed custom regex-based link rehydration and whitespace normalization

Fixed

• Ast::Merge::PartialTemplateMergerBase#normalize_matcher now preserves same_or_shallower key from boundary config
• Ast::Merge::PartialTemplateMergerBase#merge now passes boundary_same_or_shallower to InjectionPointFinder#find

Official Discord 👉️

Many paths lead to being a sponsor or a backer of this project. Are you on such a path?