RubyGems - ast-merge - Versions diffs - 4.0.1 → 4.0.3 - Mend

ast-merge 4.0.1 → 4.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

checksums.yaml +4 -4
checksums.yaml.gz.sig +0 -0
data/CHANGELOG.md +55 -1
data/README.md +71 -73
data/exe/ast-merge-recipe +19 -9
data/lib/ast/merge/recipe/runner.rb +16 -4
data/lib/ast/merge/rspec/dependency_tags.rb +15 -0
data/lib/ast/merge/rspec/merge_gem_registry.rb +42 -0
data/lib/ast/merge/version.rb +1 -1
data.tar.gz.sig +0 -0
metadata +7 -7
metadata.gz.sig +0 -0

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6af6467980a8e2076bd454a35bea42e18064fed0651704754f459353a85087a
-  data.tar.gz: 1d89bad2aa237d11aafd957f68391d8ca83248cc0f7946bad54e788cc1fa05c2
+  metadata.gz: 72301b52fa4f37e5f4224041c08fe9ace0117f84521e37b8b1c8b354bc5af500
+  data.tar.gz: 16c3d01ce0e56c17998fcf7e0e4629832fc52db44dc64d07b897004e9981f6ea
 SHA512:
-  metadata.gz: a45b949a5b6b835ba26d0422eb855daa9a62e513131bf06627abe8b68dba2daae28dd835f51fce43758c36f652fb44851885adcec3f82a64519bc2baed6f77f9
-  data.tar.gz: c2a7c05cedc23b3552f5eaef980cc890cf034060efe82f51f0c7acc98cba5b5df3bc2441a96bcde188c48391baebe5474dd76f735e5a2dbda053ff85b07a6748
+  metadata.gz: e0ab85926e6944d30500a5ced0144c86fa966d6a18252cda9c6c8091e4827e62b8743119be97944c30145d9a1e64f8c2fad52c5e9fd6f50d09b3ff70417ce64d
+  data.tar.gz: f57d3ce4c7cdb62dbbe59493581bbe2fb721a62ea029bf327a527edd2e76d394be554b34ad97fe68a82f009abf56e39225994835f03315663b8c3b137e56a459

checksums.yaml.gz.sig CHANGED Viewed

Binary file

data/CHANGELOG.md CHANGED Viewed

@@ -30,6 +30,56 @@ Please file a bug if you notice a violation of semantic versioning.
 ### Security
+## [4.0.3] - 2026-01-19
+- TAG: [v4.0.3][4.0.3t]
+- COVERAGE: 97.30% -- 2739/2815 lines in 53 files
+- BRANCH COVERAGE: 89.84% -- 893/994 branches in 53 files
+- 98.81% documented
+### Added
+- **`Ast::Merge::RSpec::MergeGemRegistry.register_known_gems`**: Selective registration of known merge gems for RSpec dependency tags
+  - Allows test suites to explicitly register only the merge gems they need, avoiding overhead of registering all known gems
+  - Usage in `spec/config/tree_haver.rb`: `MergeGemRegistry.register_known_gems(:prism_merge, :commonmarker_merge)`
+  - Enables proper RSpec tag-based test skipping for optional merge gem dependencies
+  - Example: Tests tagged with `:prism_merge` are automatically skipped when prism-merge isn't available
+### Changed
+- Upgrade to [tree_haver v5.0.2](https://github.com/kettle-rb/tree_haver/releases/tag/v5.0.2)
+- **RSpec dependency tag load order pattern**: Merge gems now load tree_haver and dependency tags early via `spec/config/tree_haver.rb`
+  - Ensures `TreeHaver::RSpec::DependencyTags` is loaded before gems register themselves
+  - Pattern: Load tree_haver/rspec → Load ast/merge/rspec → Register known gems → Load library
+  - Applied to markdown-merge and markly-merge; other merge gems should follow this pattern
+## [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 +687,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 CHANGED Viewed

@@ -62,7 +62,7 @@ The `*-merge` gem family provides intelligent, AST-based merging for various fil
 | Gem                                      | Version                                                        | CI                                                           |          | Language<br>/ Format                                                                                  | Parser Backend(s)                                                                | Description |
 |------------------------------------------|----------------------------------------------------------------|--------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|-------------|
-| [tree_haver][tree_haver]                 | [![Version][tree_haver-gem-i]][tree_haver-gem]                 | [![Version][tree_haver-ci-i]][tree_haver-ci]                 | Multi    | MRI C, Rust, FFI, Java, Prism, Psych, Commonmarker, Markly, Citrus, Parslet                           | **Foundation**: Cross-Ruby adapter for parsing libraries (like Faraday for HTTP) |
+| [tree_haver][tree_haver]                 | [![Version][tree_haver-gem-i]][tree_haver-gem]                 | [![Version][tree_haver-ci-i]][tree_haver-ci]                 | Multi    | Supported Backends: MRI C, Rust, FFI, Java, Prism, Psych, Commonmarker, Markly, Citrus, Parslet       | **Foundation**: Cross-Ruby adapter for parsing libraries (like Faraday for HTTP) |
 | [ast-merge][ast-merge]                   | [![Version][ast-merge-gem-i]][ast-merge-gem]                   | [![Version][ast-merge-ci-i]][ast-merge-ci]                   | Text     | internal                                                                                              | **Infrastructure**: Shared base classes and merge logic for all `*-merge` gems   |
 | [bash-merge][bash-merge]                 | [![Version][bash-merge-gem-i]][bash-merge-gem]                 | [![Version][bash-merge-ci-i]][bash-merge-ci]                 | Bash     | [tree-sitter-bash][ts-bash] (via tree_haver)                                                          | Smart merge for Bash scripts                                                     |
 | [commonmarker-merge][commonmarker-merge] | [![Version][commonmarker-merge-gem-i]][commonmarker-merge-gem] | [![Version][commonmarker-merge-ci-i]][commonmarker-merge-ci] | Markdown | [Commonmarker][commonmarker] (via tree_haver)                                                         | Smart merge for Markdown (CommonMark via comrak Rust)                            |
@@ -80,18 +80,18 @@ The `*-merge` gem family provides intelligent, AST-based merging for various fil
 tree_haver supports multiple parsing backends, but not all backends work on all Ruby platforms:
-| Platform 👉️<br> TreeHaver Backend 👇️         | MRI | JRuby | TruffleRuby | Notes                                               |
-|------------------------------------------------|:---:|:-----:|:-----------:|-----------------------------------------------------|
-| **MRI** ([ruby_tree_sitter][ruby_tree_sitter]) |  ✅  |   ❌   |      ❌      | C extension, MRI only                               |
-| **Rust** ([tree_stump][tree_stump])            |  ✅  |   ❌   |      ❌      | Rust extension via magnus/rb-sys, MRI only          |
-| **FFI**                                        |  ✅  |   ✅   |      ❌      | TruffleRuby's FFI doesn't support `STRUCT_BY_VALUE` |
-| **Java** ([jtreesitter][jtreesitter])          |  ❌  |   ✅   |      ❌      | JRuby only, requires grammar JARs                   |
-| **Prism**                                      |  ✅  |   ✅   |      ✅      | Ruby parsing, stdlib in Ruby 3.4+                   |
-| **Psych**                                      |  ✅  |   ✅   |      ✅      | YAML parsing, stdlib                                |
-| **Citrus**                                     |  ✅  |   ✅   |      ✅      | Pure Ruby PEG parser, no native dependencies        |
-| **Parslet**                                    |  ✅  |   ✅   |      ✅      | Pure Ruby PEG parser, no native dependencies        |
-| **Commonmarker**                               |  ✅  |   ❌   |      ❓      | Rust extension for Markdown                         |
-| **Markly**                                     |  ✅  |   ❌   |      ❓      | C extension for Markdown                            |
+| Platform 👉️<br> TreeHaver Backend 👇️          | MRI | JRuby | TruffleRuby | Notes                                                                      |
+|-------------------------------------------------|:---:|:-----:|:-----------:|----------------------------------------------------------------------------|
+| **MRI** ([ruby_tree_sitter][ruby_tree_sitter])  |  ✅  |   ❌   |      ❌      | C extension, MRI only                                                      |
+| **Rust** ([tree_stump][tree_stump])             |  ✅  |   ❌   |      ❌      | Rust extension via magnus/rb-sys, MRI only                                 |
+| **FFI** ([ffi][ffi])                            |  ✅  |   ✅   |      ❌      | TruffleRuby's FFI doesn't support `STRUCT_BY_VALUE`                        |
+| **Java** ([jtreesitter][jtreesitter])           |  ❌  |   ✅   |      ❌      | JRuby only, requires grammar JARs                                          |
+| **Prism** ([prism][prism])                      |  ✅  |   ✅   |      ✅      | Ruby parsing, stdlib in Ruby 3.4+                                          |
+| **Psych** ([psych][psych])                      |  ✅  |   ✅   |      ✅      | YAML parsing, stdlib                                                       |
+| **Citrus** ([citrus][citrus])                   |  ✅  |   ✅   |      ✅      | Pure Ruby PEG parser, no native dependencies                               |
+| **Parslet** ([parslet][parslet])                |  ✅  |   ✅   |      ✅      | Pure Ruby PEG parser, no native dependencies                               |
+| **Commonmarker** ([commonmarker][commonmarker]) |  ✅  |   ❌   |      ❓      | Rust extension for Markdown (via [commonmarker-merge][commonmarker-merge]) |
+| **Markly** ([markly][markly])                   |  ✅  |   ❌   |      ❓      | C extension for Markdown  (via [markly-merge][markly-merge])               |
 **Legend**: ✅ = Works, ❌ = Does not work, ❓ = Untested
@@ -185,6 +185,7 @@ tree_haver supports multiple parsing backends, but not all backends work on all
 [kettle-jem-ci]: https://github.com/kettle-rb/kettle-jem/actions/workflows/current.yml
 [prism]: https://github.com/ruby/prism
 [psych]: https://github.com/ruby/psych
+[ffi]: https://github.com/ffi/ffi
 [ts-json]: https://github.com/tree-sitter/tree-sitter-json
 [ts-jsonc]: https://gitlab.com/WhyNotHugo/tree-sitter-jsonc
 [ts-bash]: https://github.com/tree-sitter/tree-sitter-bash
@@ -199,6 +200,8 @@ tree_haver supports multiple parsing backends, but not all backends work on all
 [ruby_tree_sitter]: https://github.com/Faveod/ruby-tree-sitter
 [tree_stump]: https://github.com/joker1007/tree_stump
 [jtreesitter]: https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter
+[citrus]: https://github.com/mjackson/citrus
+[parslet]: https://github.com/kschiess/parslet
 ### Architecture: tree\_haver + ast-merge
@@ -208,24 +211,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 +375,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 +394,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 +450,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 +535,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 +575,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 +604,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 +620,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 +667,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
@@ -793,7 +791,7 @@ Support us with a monthly donation and help us continue our activities. \[[Becom
 NOTE: [kettle-readme-backers][kettle-readme-backers] updates this list every day, automatically.
 <!-- OPENCOLLECTIVE-INDIVIDUALS:START -->
-No backers yet. Be the first\!
+No backers yet. Be the first!
 <!-- OPENCOLLECTIVE-INDIVIDUALS:END -->
 ### Open Collective for Organizations
@@ -803,7 +801,7 @@ Become a sponsor and get your logo on our README on GitHub with a link to your s
 NOTE: [kettle-readme-backers][kettle-readme-backers] updates this list every day, automatically.
 <!-- OPENCOLLECTIVE-ORGANIZATIONS:START -->
-No sponsors yet. Be the first\!
+No sponsors yet. Be the first!
 <!-- OPENCOLLECTIVE-ORGANIZATIONS:END -->
 [kettle-readme-backers]: https://github.com/kettle-rb/ast-merge/blob/main/exe/kettle-readme-backers
@@ -903,7 +901,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 +1106,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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/rspec/dependency_tags.rb CHANGED Viewed

@@ -84,6 +84,21 @@ module Ast
   end
 end
+# NOTE: Known merge gems (KNOWN_GEMS) are NOT automatically registered here.
+# Each test suite should explicitly register only the gems it needs in its
+# spec/config/tree_haver.rb file using:
+#
+#   Ast::Merge::RSpec::MergeGemRegistry.register_known_gems(:gem1, :gem2, ...)
+#
+# This avoids wasting time registering gems that aren't needed for a particular
+# test suite. Only the gems that are actually required for testing should be registered.
+#
+# Example for a gem that needs to test with optional markdown backends:
+#   Ast::Merge::RSpec::MergeGemRegistry.register_known_gems(
+#     :commonmarker_merge,
+#     :markly_merge
+#   )
 # Configure RSpec with dependency-based exclusion filters
 RSpec.configure do |config|
   deps = Ast::Merge::RSpec::DependencyTags

data/lib/ast/merge/rspec/merge_gem_registry.rb CHANGED Viewed

@@ -253,6 +253,48 @@ module Ast
           end
         end
+        # Register one or more known gems for RSpec dependency tag support
+        #
+        # This allows test suites to explicitly register only the merge gems they need
+        # for their tests, avoiding the overhead of registering all known gems.
+        #
+        # @param gem_names [Array<Symbol>] list of gem names from KNOWN_GEMS to register
+        # @return [void]
+        #
+        # @example In spec/config/tree_haver.rb
+        #   # Only register the markdown merge gems that markly-merge tests depend on
+        #   Ast::Merge::RSpec::MergeGemRegistry.register_known_gems(:prism_merge)
+        #
+        # @example Register multiple gems
+        #   Ast::Merge::RSpec::MergeGemRegistry.register_known_gems(
+        #     :commonmarker_merge,
+        #     :markly_merge
+        #   )
+        def register_known_gems(*gem_names)
+          gem_names.each do |tag_name|
+            tag_sym = tag_name.to_sym
+            # Skip if not in KNOWN_GEMS
+            unless KNOWN_GEMS.key?(tag_sym)
+              warn("Unknown gem: #{tag_name}. Available: #{KNOWN_GEMS.keys.join(", ")}")
+              next
+            end
+            # Skip if already registered
+            next if registered?(tag_sym)
+            metadata = KNOWN_GEMS[tag_sym]
+            register(
+              tag_sym,
+              require_path: metadata[:require_path],
+              merger_class: metadata[:merger_class],
+              test_source: metadata[:test_source],
+              category: metadata[:category],
+              skip_instantiation: metadata[:skip_instantiation],
+            )
+          end
+        end
         # Get all registered gem tag names (including pre-configured known gems)
         #
         # @return [Array<Symbol>] list of registered tag names

data/lib/ast/merge/version.rb CHANGED Viewed

@@ -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.3"
     end
     VERSION = Version::VERSION # traditional location
   end

data.tar.gz.sig CHANGED Viewed

Binary file

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ast-merge
 version: !ruby/object:Gem::Version
-  version: 4.0.1
+  version: 4.0.3
 platform: ruby
 authors:
 - Peter H. Boling
@@ -66,7 +66,7 @@ dependencies:
         version: '5.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.0.1
+        version: 5.0.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -76,7 +76,7 @@ dependencies:
         version: '5.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.0.1
+        version: 5.0.2
 - !ruby/object:Gem::Dependency
   name: kettle-dev
   requirement: !ruby/object:Gem::Requirement
@@ -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.3
+  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v4.0.3/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.3
   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
@@ -414,7 +414,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.4
 specification_version: 4
 summary: "☯️ Shared infrastructure for the *-merge gem family"
 test_files: []

metadata.gz.sig CHANGED Viewed

Binary file