ast-merge 4.0.1 → 4.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6af6467980a8e2076bd454a35bea42e18064fed0651704754f459353a85087a
-  data.tar.gz: 1d89bad2aa237d11aafd957f68391d8ca83248cc0f7946bad54e788cc1fa05c2
+  metadata.gz: 29e3c1eb54812e59b30a8ae0dc42792486ef2e4992dbd43234452cfce0f2b1ab
+  data.tar.gz: bb1b200aa2a2d8a48c127952510984cf2ccd71e2517ced1d422fe542a7969c78
 SHA512:
-  metadata.gz: a45b949a5b6b835ba26d0422eb855daa9a62e513131bf06627abe8b68dba2daae28dd835f51fce43758c36f652fb44851885adcec3f82a64519bc2baed6f77f9
-  data.tar.gz: c2a7c05cedc23b3552f5eaef980cc890cf034060efe82f51f0c7acc98cba5b5df3bc2441a96bcde188c48391baebe5474dd76f735e5a2dbda053ff85b07a6748
+  metadata.gz: b0823b5b64b77947faa3213463c18289a4275b5b8fd7d5a0dcf258c1ae4088dcc50a34923f459944473cfae67e7c18dd646e3236f7ff6eb0898edfdb8b5d9ab2
+  data.tar.gz: 0f8dafa6c932a75504c898793fb0f51dfa9977d288f70e6e8e9fc8aff9f0f3452742a0302dbdd23aee33db8ab4528834048322af37d7c4d44ec9fb473e682855

data/CHANGELOG.md

@@ -30,6 +30,33 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [4.0.2] - 2026-01-12
+
+- TAG: [v4.0.2][4.0.2t]
+- COVERAGE: 97.30% -- 2739/2815 lines in 53 files
+- BRANCH COVERAGE: 89.84% -- 893/994 branches in 53 files
+- 98.81% documented
+
+### Added
+
+- **`Recipe::Runner` target file override**: Accept `target_files` parameter to override recipe targets
+  - `Runner.new(recipe, target_files: ["file1.md", "file2.md"])` - Process only specified files
+  - Paths are expanded relative to `base_dir`
+  - When not specified, falls back to recipe's configured targets
+- **`exe/ast-merge-recipe` file arguments**: Accept target files on command line
+  - `ast-merge-recipe recipe.yml file1.md file2.md` - Override recipe targets
+  - Updated help text and banner to document new usage
+- **`bin/update_gem_family_section` file arguments**: Accept target files on command line
+  - `bin/update_gem_family_section vendor/my-gem/README.md` - Process specific file(s)
+  - If no files specified, defaults to `README.md` + `vendor/*/README.md`
+  - Added `--skip-fix` option to skip the formatting fix step
+
+### Changed
+
+- **`bin/update_gem_family_section`**: Refactored to use `OptionParser` for clean option handling
+  - Consistent with `bin/fix_readme_formatting` style
+  - Properly separates options from file arguments
+
 ## [4.0.1] - 2026-01-11
 
 - TAG: [v4.0.1][4.0.1t]
@@ -637,7 +664,11 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - Initial release
 
-[Unreleased]: https://github.com/kettle-rb/ast-merge/compare/v4.0.1...HEAD
+[Unreleased]: https://github.com/kettle-rb/ast-merge/compare/v4.0.3...HEAD
+[4.0.3]: https://github.com/kettle-rb/ast-merge/compare/v4.0.2...v4.0.3
+[4.0.3t]: https://github.com/kettle-rb/ast-merge/releases/tag/v4.0.3
+[4.0.2]: https://github.com/kettle-rb/ast-merge/compare/v4.0.1...v4.0.2
+[4.0.2t]: https://github.com/kettle-rb/ast-merge/releases/tag/v4.0.2
 [4.0.1]: https://github.com/kettle-rb/ast-merge/compare/v4.0.0...v4.0.1
 [4.0.1t]: https://github.com/kettle-rb/ast-merge/releases/tag/v4.0.1
 [4.0.0]: https://github.com/kettle-rb/ast-merge/compare/v3.1.0...v4.0.0

data/README.md

@@ -208,24 +208,24 @@ The `*-merge` gem family is built on a two-layer architecture:
 
 [tree\_haver][tree_haver] provides cross-Ruby parsing capabilities:
 
-  - **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
+- **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)
 
 Ast::Merge builds on tree\_haver to provide:
 
-  - **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
+- **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
 
 ### Creating a New Merge Gem
 
@@ -372,10 +372,10 @@ merger = MyFormat::SmartMerger.new(
 
 This is particularly useful for:
 
-  - Paragraphs with minor edits (typos, rewording)
-  - Headings with slight changes
-  - Comments with updated text
-  - Any text-based node that may have been slightly modified
+- Paragraphs with minor edits (typos, rewording)
+- Headings with slight changes
+- Comments with updated text
+- Any text-based node that may have been slightly modified
 
 ### Namespace Reference
 
@@ -391,11 +391,11 @@ The `Ast::Merge` module is organized into several namespaces, each with detailed
 
 **Key Classes by Namespace:**
 
-  - **Detector**: `Region`, `Base`, `Mergeable`, `FencedCodeBlock`, `YamlFrontmatter`, `TomlFrontmatter`
-  - **Recipe**: `Config`, `Runner`, `ScriptLoader`
-  - **Comment**: `Line`, `Block`, `Empty`, `Parser`, `Style`
-  - **Text**: `SmartMerger`, `FileAnalysis`, `LineNode`, `WordNode`, `Section`
-  - **RSpec**: Shared examples and dependency tags for testing `*-merge` implementations
+- **Detector**: `Region`, `Base`, `Mergeable`, `FencedCodeBlock`, `YamlFrontmatter`, `TomlFrontmatter`
+- **Recipe**: `Config`, `Runner`, `ScriptLoader`
+- **Comment**: `Line`, `Block`, `Empty`, `Parser`, `Style`
+- **Text**: `SmartMerger`, `FileAnalysis`, `LineNode`, `WordNode`, `Section`
+- **RSpec**: Shared examples and dependency tags for testing `*-merge` implementations
 
 ## 💡 Info you can shake a stick at
 
@@ -447,18 +447,13 @@ The maintainers of this and thousands of other packages are working with Tidelif
 
 [![Get help from me on Tidelift][🏙️entsup-tidelift-img]][🏙️entsup-tidelift]
 
-  - 💡Subscribe for support guarantees covering *all* your FLOSS dependencies
-
-  - 💡Tidelift is part of [Sonar][🏙️entsup-tidelift-sonar]
-
-  - 💡Tidelift pays maintainers to maintain the software you depend on\!<br/>📊`@`Pointy Haired Boss: An [enterprise support][🏙️entsup-tidelift] subscription is "[never gonna let you down][🧮kloc]", and *supports* open source maintainers
-    Alternatively:
-
-  - [![Live Chat on Discord][✉️discord-invite-img-ftb]][🖼️galtzo-discord]
-
-  - [![Get help from me on Upwork][👨🏼‍🏫expsup-upwork-img]][👨🏼‍🏫expsup-upwork]
-
-  - [![Get help from me on Codementor][👨🏼‍🏫expsup-codementor-img]][👨🏼‍🏫expsup-codementor]
+- 💡Subscribe for support guarantees covering *all* your FLOSS dependencies
+- 💡Tidelift is part of [Sonar][🏙️entsup-tidelift-sonar]
+- 💡Tidelift pays maintainers to maintain the software you depend on\!<br/>📊`@`Pointy Haired Boss: An [enterprise support][🏙️entsup-tidelift] subscription is "[never gonna let you down][🧮kloc]", and *supports* open source maintainers
+  Alternatively:
+- [![Live Chat on Discord][✉️discord-invite-img-ftb]][🖼️galtzo-discord]
+- [![Get help from me on Upwork][👨🏼‍🏫expsup-upwork-img]][👨🏼‍🏫expsup-upwork]
+- [![Get help from me on Codementor][👨🏼‍🏫expsup-codementor-img]][👨🏼‍🏫expsup-codementor]
 
 </details>
 
@@ -537,17 +532,17 @@ merger = SomeFormat::Merge::SmartMerger.new(
 
 Control which source wins when both files have the same structural element:
 
-  - **`:template`** - Template values replace destination values
-  - **`:destination`** (default) - Destination values are preserved
-  - **Hash** - Per-node-type preference (see Advanced Configuration)
+- **`:template`** - Template values replace destination values
+- **`:destination`** (default) - Destination values are preserved
+- **Hash** - Per-node-type preference (see Advanced Configuration)
 
 ### Template-Only Nodes
 
 Control whether to add nodes that only exist in the template:
 
-  - **`true`** - Add all template-only nodes
-  - **`false`** (default) - Skip template-only nodes
-  - **Callable** - Filter which template-only nodes to add
+- **`true`** - Add all template-only nodes
+- **`false`** (default) - Skip template-only nodes
+- **Callable** - Filter which template-only nodes to add
 
 #### Callable Filter
 
@@ -577,10 +572,10 @@ merger = Markly::Merge::SmartMerger.new(
 
 The `entry` hash contains:
 
-  - `:template_node` - The node being considered for addition
-  - `:signature` - The node's signature (Array or other value)
-  - `:template_index` - Index in the template statements
-  - `:dest_index` - Always `nil` for template-only nodes
+- `:template_node` - The node being considered for addition
+- `:signature` - The node's signature (Array or other value)
+- `:template_index` - Index in the template statements
+- `:dest_index` - Always `nil` for template-only nodes
 
 ## 🔧 Basic Usage
 
@@ -606,11 +601,11 @@ end
 
 ### Available Shared Examples
 
-  - `"Ast::Merge::FreezeNode"` - Tests for FreezeNode implementations
-  - `"Ast::Merge::MergeResult"` - Tests for MergeResult implementations
-  - `"Ast::Merge::DebugLogger"` - Tests for DebugLogger implementations
-  - `"Ast::Merge::FileAnalysisBase"` - Tests for FileAnalysis implementations
-  - `"Ast::Merge::MergerConfig"` - Tests for SmartMerger implementations
+- `"Ast::Merge::FreezeNode"` - Tests for FreezeNode implementations
+- `"Ast::Merge::MergeResult"` - Tests for MergeResult implementations
+- `"Ast::Merge::DebugLogger"` - Tests for DebugLogger implementations
+- `"Ast::Merge::FileAnalysisBase"` - Tests for FileAnalysis implementations
+- `"Ast::Merge::MergerConfig"` - Tests for SmartMerger implementations
 
 ## 🎛️ Advanced Configuration
 
@@ -622,9 +617,9 @@ This is useful for hand-edited customizations you never want overwritten.
 
 A freeze block consists of:
 
-  - A **start marker** comment (e.g., `# mytoken:freeze`)
-  - The protected content
-  - An **end marker** comment (e.g., `# mytoken:unfreeze`)
+- A **start marker** comment (e.g., `# mytoken:freeze`)
+- The protected content
+- An **end marker** comment (e.g., `# mytoken:unfreeze`)
 
 ```ruby
 # In a Ruby file with prism-merge:
@@ -669,13 +664,13 @@ preferences for different types of nodes (e.g., prefer template for linter confi
 
 1.  **Define a `node_typing`**: A Hash mapping node type symbols to callables that receive a node and return either:
 
-      - The original node (no special handling)
-      - A wrapped node with a `merge_type` attribute (via `Ast::Merge::NodeTyping::Wrapper`)
+    - The original node (no special handling)
+    - A wrapped node with a `merge_type` attribute (via `Ast::Merge::NodeTyping::Wrapper`)
 
 2.  **Use a Hash-based preference**: Instead of a simple `:destination` or `:template` Symbol, pass a Hash with:
 
-      - `:default` key for the fallback preference
-      - Custom keys matching the `merge_type` values from your `node_typing`
+    - `:default` key for the fallback preference
+    - Custom keys matching the `merge_type` values from your `node_typing`
 
 ```ruby
 # Example: Prefer template for lint gem configs, destination for everything else
@@ -903,7 +898,7 @@ is a *breaking change* to an API, and for that reason the bike shedding is endle
 To get a better understanding of how SemVer is intended to work over a project's lifetime,
 read this article from the creator of SemVer:
 
-  - ["Major Version Numbers are Not Sacred"][📌major-versions-not-sacred]
+- ["Major Version Numbers are Not Sacred"][📌major-versions-not-sacred]
 
 </details>
 
@@ -1108,7 +1103,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.647-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.815-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/exe/ast-merge-recipe

@@ -171,9 +171,10 @@ class AstMergeRecipeCLI
 
   def parse_options(argv)
     @option_parser = OptionParser.new do |opts|
-      opts.banner = "Usage: #{File.basename($0)} RECIPE_FILE [options]"
+      opts.banner = "Usage: #{File.basename($0)} RECIPE_FILE [FILES...] [options]"
       opts.separator("")
       opts.separator("Run a YAML-based merge recipe against target files.")
+      opts.separator("If FILES are specified, they override the recipe's targets.")
       opts.separator("")
       opts.separator("Options:")
 
@@ -225,9 +226,15 @@ class AstMergeRecipeCLI
       opts.on("-h", "--help", "Show this help message") do
         puts opts
         puts
+        puts "Arguments:"
+        puts "  RECIPE_FILE    Path to the YAML recipe file (required)"
+        puts "  [FILES...]     Target files to process (optional, overrides recipe targets)"
+        puts
         puts "Examples:"
         puts "  #{File.basename($0)} .merge-recipes/gem_family_section.yml --dry-run"
         puts "  #{File.basename($0)} recipe.yml --verbose --parser=commonmarker"
+        puts "  #{File.basename($0)} recipe.yml vendor/my-gem/README.md"
+        puts "  #{File.basename($0)} recipe.yml README.md vendor/*/README.md"
         puts
         puts "Recipe YAML format:"
         puts "  See lib/ast/merge/recipe/README.md for full documentation"
@@ -241,10 +248,8 @@ class AstMergeRecipeCLI
     # First non-option argument is the recipe file
     @options[:recipe_file] = remaining.shift
 
-    # Warn about extra arguments
-    if remaining.any?
-      $stderr.puts Colors.yellow("WARNING: Ignoring extra arguments: #{remaining.join(", ")}")
-    end
+    # Remaining arguments are target files (override recipe targets)
+    @options[:target_files] = remaining if remaining.any?
   end
 
   def validate_options!
@@ -271,14 +276,19 @@ class AstMergeRecipeCLI
     recipe = Ast::Merge::Recipe::Config.load(@options[:recipe_file])
     print_recipe_info(recipe)
 
-    # Create runner
-    runner = Ast::Merge::Recipe::Runner.new(
-      recipe,
+    # Build runner options
+    runner_opts = {
       dry_run: @options[:dry_run],
       base_dir: @options[:base_dir],
       parser: @options[:parser],
       verbose: @options[:verbose],
-    )
+    }
+
+    # If target files specified on command line, override recipe targets
+    runner_opts[:target_files] = @options[:target_files] if @options[:target_files]
+
+    # Create runner
+    runner = Ast::Merge::Recipe::Runner.new(recipe, **runner_opts)
 
     # Run and display results
     puts Colors.cyan("Processing files...")

data/lib/ast/merge/recipe/runner.rb

@@ -40,6 +40,9 @@ module Ast
         # @return [Symbol] Parser to use (:markly, :commonmarker, :prism, :psych, etc.)
         attr_reader :parser
 
+        # @return [Array<String>, nil] Target files override (from command line)
+        attr_reader :target_files
+
         # @return [Array<Result>] Results from the last run
         attr_reader :results
 
@@ -50,12 +53,14 @@ module Ast
         # @param base_dir [String, nil] Base directory for path resolution
         # @param parser [Symbol] Which parser to use
         # @param verbose [Boolean] Enable verbose output
-        def initialize(recipe, dry_run: false, base_dir: nil, parser: :markly, verbose: false)
+        # @param target_files [Array<String>, nil] Override recipe targets with these files
+        def initialize(recipe, dry_run: false, base_dir: nil, parser: :markly, verbose: false, target_files: nil, **options)
           @recipe = recipe
           @dry_run = dry_run
           @base_dir = base_dir || Dir.pwd
           @parser = parser
           @verbose = verbose
+          @target_files = target_files
           @results = []
         end
 
@@ -66,10 +71,17 @@ module Ast
           @results = []
 
           template_content = load_template
-          # Let the recipe expand targets from its own location
-          target_files = recipe.expand_targets
 
-          target_files.each do |target_path|
+          # Use command-line targets if provided, otherwise expand from recipe
+          files_to_process = if @target_files && !@target_files.empty?
+            # Expand paths relative to base_dir
+            @target_files.map { |f| File.expand_path(f, @base_dir) }
+          else
+            # Let the recipe expand targets from its own location
+            recipe.expand_targets
+          end
+
+          files_to_process.each do |target_path|
             result = process_file(target_path, template_content)
             @results << result
             yield result if block_given?

data/lib/ast/merge/version.rb

@@ -5,7 +5,7 @@ module Ast
     # Version information for Ast::Merge
     module Version
       # Current version of the ast-merge gem
-      VERSION = "4.0.1"
+      VERSION = "4.0.2"
     end
     VERSION = Version::VERSION # traditional location
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ast-merge
 version: !ruby/object:Gem::Version
-  version: 4.0.1
+  version: 4.0.2
 platform: ruby
 authors:
 - Peter H. Boling
@@ -382,10 +382,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://ast-merge.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/ast-merge/tree/v4.0.1
-  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v4.0.1/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/ast-merge/tree/v4.0.2
+  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v4.0.2/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/ast-merge/issues
-  documentation_uri: https://www.rubydoc.info/gems/ast-merge/4.0.1
+  documentation_uri: https://www.rubydoc.info/gems/ast-merge/4.0.2
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-rb/ast-merge/wiki
   news_uri: https://www.railsbling.com/tags/ast-merge