ast-merge v2.0.0 released!

2.0.0 - 2025-12-28

• TAG: v2.0.0
• COVERAGE: 88.47% – 2894/3271 lines in 53 files
• BRANCH COVERAGE: 67.83% – 698/1029 branches in 53 files
• 98.82% documented

Added

• RSpec Dependency Tags: Conditional test execution based on available merge gems
  • New lib/ast/merge/rspec/dependency_tags.rb provides automatic test filtering
  • Tags for all merge gems: :markly_merge, :prism_merge, :json_merge, :toml_merge, etc.
  • Composite tag :any_markdown_merge for tests that work with any markdown merger
  • Negated tags (e.g., :not_prism_merge) for testing fallback behavior
  • AST_MERGE_DEBUG=1 environment variable prints dependency summary
  • Eliminates need for require statements inside spec files
  • See lib/ast/merge/rspec/README.md for full documentation
• Recipe::Preset: Base class for merge configuration presets
  • Provides merge configuration (signature generators, node typing, preferences) without requiring template files
  • Recipe::Config now inherits from Preset, adding template/target handling
  • to_h method converts preset to SmartMerger-compatible options hash
  • Enables kettle-jem and other libraries to define reusable merge presets
  • Supports script loading for signature generators and node typing via ScriptLoader
• exe/ast-merge-recipe: Shipped executable for running merge recipes
  • Uses bundler/inline for dependency management
  • Supports --dry-run, --verbose, --parser, --base-dir options
  • Uses optparse for proper option parsing
  • Loads merge gems from recipe YAML merge_gems section
  • Development mode via KETTLE_RB_DEV=true or --dev-root option
  • All gems sourced from gem.coop
• PartialTemplateMerger: Section-based merging for partial templates
  • Find and merge specific sections in destination documents
  • Support for both replace_mode (full replacement) and merge mode (intelligent merging)
  • Configurable anchor and boundary matchers for section detection
  • Custom signature_generator and node_typing support for advanced matching
  • when_missing behavior: :skip, :append, :prepend
• Recipe: YAML-based recipe system for defining merge operations
  • Load recipes from YAML files with Recipe.load(path)
  • Define template, targets, injection point, merge preferences
  • Support for when_missing: skip|add|error behavior
  • Support for replace_mode option
  • Automatic path resolution relative to recipe file location
• RecipeRunner: Execute recipes against multiple target files
  • Uses PartialTemplateMerger for section-based merging
  • Dry-run mode with --dry-run flag
  • Results tracking with status, stats, and error reporting
  • TableTennis integration for formatted output
  • Support for different parsers (markly, commonmarker, prism, psych)
• RecipeScriptLoader: Load Ruby scripts referenced by recipes
  • Convention: scripts in folder matching recipe basename (e.g., my_recipe/ for my_recipe.yml)
  • Support for inline lambda expressions in YAML
  • Script caching for performance
  • Validation that scripts return callable objects
• bin/ast-merge-recipe: CLI for running merge recipes
  • bin/ast-merge-recipe RECIPE_FILE [--dry-run] [--verbose]
  • Color-coded output with status symbols
  • Summary table with counts
• NavigableStatement: New wrapper class for uniform node navigation (language-agnostic)
  • Provides flat list navigation (next, previous, index) for all nodes
  • Tree depth calculation with tree_depth method
  • same_or_shallower_than? for level-based boundary detection
  • Language-agnostic section boundaries using tree hierarchy
  • Provides tree navigation (tree_parent, tree_next, tree_previous) for parser-backed nodes
  • synthetic? method to detect nodes without tree navigation (GapLineNode, LinkDefinitionNode, etc.)
  • type? and text_matches? helpers for node matching
  • node_attribute for accessing parser-specific attributes with fallbacks
  • each_following and take_until for sequential traversal
  • find_matching and find_first class methods for querying statement lists
  • build_list class method to create linked statement lists from raw statements
• InjectionPoint: New class for defining where content can be injected (language-agnostic)
  • Supports positions: :before, :after, :first_child, :last_child, :replace
  • Optional boundary for replacement ranges
  • replacement?, child_injection?, sibling_injection? predicates
  • replaced_statements to get all statements in a replacement range
• InjectionPointFinder: New class for finding injection points by matching criteria
  • find to locate a single injection point by type/text pattern
  • find_all to locate all matching injection points
  • Works with any *-merge gem (prism-merge, markly-merge, psych-merge, etc.)
• SmartMergerBase: add_template_only_nodes now accepts a callable filter
  • Boolean true/false still works as before (add all or none)
  • Callable (Proc/Lambda) receives (node, entry) and returns truthy to add the node
  • Enables selective addition of template-only nodes based on signature, type, or content
  • Example use case: Add missing link reference definitions while skipping other template content
  • Entry hash includes :template_node, :signature, :template_index for filtering decisions
• ContentMatchRefiner: New match refiner for fuzzy text content matching
  • Uses Levenshtein distance to pair nodes with similar (but not identical) text
  • Configurable scoring weights for content similarity, length, and position
  • Custom content extractor support for parser-specific text extraction
  • Node type filtering to limit which types are processed
  • Can be combined with other refiners (e.g., TableMatchRefiner)
  • Useful for matching paragraphs, headings, comments with minor edits
• SmartMergerBase: Added validity check after FileAnalysis creation
  • Checks valid? after creating FileAnalysis and raises appropriate parse error if invalid
  • Catches silent failures like grammar not available or parse errors
  • Documented the FileAnalysis error handling pattern for all *-merge gems
• SmartMergerBase: Added explicit node_typing parameter
  • All child SmartMergers were already using node_typing via **format_options
  • Now explicitly documented and accessible via attr_reader :node_typing
  • Validates node_typing configuration via NodeTyping.validate! if provided
  • Enables per-node-type merge preferences across all *-merge gems
• ConflictResolverBase: Added match_refiner parameter and **options for forward compatibility
  • All batch-strategy resolvers were storing match_refiner locally
  • Now explicitly accepted in base class with attr_reader :match_refiner
  • Added **options catch-all for future parameters without breaking child classes
• MergeResultBase: Added **options for forward compatibility
  • Allows subclasses to accept new parameters without modification
  • Maintains backward compatibility with existing no-arg and keyword-arg constructors
• RBS Signatures: Added comprehensive type signatures for base classes
  • SmartMergerBase with all standard options and abstract method declarations
  • ConflictResolverBase with strategy-based resolution methods
  • MergeResultBase with unified constructor and decision tracking
  • MatchRefinerBase with similarity computation interface
  • RegionMergeable module for nested content merging
  • NodeTyping module with Wrapper class for typed nodes
  • Type aliases: node_typing_callable, node_typing_hash, preference_type
• Documentation: Updated README with comprehensive base class documentation
  • Standard options table with all SmartMergerBase parameters
  • Forward compatibility section explaining the **options pattern
  • Complete “Creating a New Merge Gem” example with all base classes
  • Base Classes Reference table

Changed

• BREAKING - Namespace Reorganization: Major restructuring for better organization
  • Ast::Merge::Region → Ast::Merge::Detector::Region (Struct moved into Detector namespace)
  • Ast::Merge::RegionDetectorBase → Ast::Merge::Detector::Base
  • Ast::Merge::RegionMergeable → Ast::Merge::Detector::Mergeable
  • Ast::Merge::FencedCodeBlockDetector → Ast::Merge::Detector::FencedCodeBlock
  • Ast::Merge::YamlFrontmatterDetector → Ast::Merge::Detector::YamlFrontmatter
  • Ast::Merge::TomlFrontmatterDetector → Ast::Merge::Detector::TomlFrontmatter
  • Ast::Merge::Recipe class → Ast::Merge::Recipe::Config
  • Ast::Merge::RecipeRunner → Ast::Merge::Recipe::Runner
  • Ast::Merge::RecipeScriptLoader → Ast::Merge::Recipe::ScriptLoader
  • Ast::Merge::RegionMergeable::RegionConfig → Ast::Merge::Detector::Mergeable::Config
  • Ast::Merge::RegionMergeable::ExtractedRegion → Ast::Merge::Detector::Mergeable::ExtractedRegion

Official Discord 👉️

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