monkey_bars 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d42e4b3ee72dbd54a294b38ad21d21a43a08c3c941b0a9dab17bcdb4508f227f
-  data.tar.gz: 47f08f29eb06feb4b73d70679aef3769d4cab20ee3d32b08561522d869e27feb
+  metadata.gz: 959654729be5d09d997d89340df3d00652a0a39f962cbf0f87a3223a24b22195
+  data.tar.gz: b36eaea242ef45cb939040f6436af3ed3f9cb806f261141ab5c68e9ba7c24967
 SHA512:
-  metadata.gz: 0fceae1976fc70683a2aa5633ed612c5b207ddefe66d01666fee6950130d888070bcdfe3cd47af0c3be24cea92ef8167cfeb67ae8d7379eb1b9e0961555fc3bb
-  data.tar.gz: e6dff3e7bc72d25a1fec7b903b022aad32c5440c1228b6c8c9409158aee9523a2fff23c41691a31b2e0e95c1f3cb48937df92e088f42b0aab124433d21a0b289
+  metadata.gz: 5084d4cc7c224bf0fcf5eeaae3aa02da22ea2b5cac93e8561983bb1d1d3d61a371f7a5401d319117b9efce894ff2e85c1f908a7e2a8777d585791160a4959359
+  data.tar.gz: 4633ed06204dd319134fd7c05ff437c649c1c441ab890abe4b3c51b38bcc02c0bc976c41f7e634d17b9bc461b2d0294007bc055f82fa8c71b47e4770322eacd2

data/README.md

@@ -73,6 +73,7 @@ declared inside a block and then applied with `patch` (immediately) or
 - `patch!` applies a prepared patch
 
 If `patch!` runs without any methods or constants defined, it emits a warning.
+Calling `prepare_for_patching` or `patch!` more than once raises an error.
 
 The `monkey` can be:
 
@@ -96,6 +97,30 @@ You can call any of these helpers multiple times; MonkeyBars will combine them.
 This is helpful when you want to ignore some arity check errors (see below) for
 some methods but not others.
 
+When patching existing methods, visibility must match the target method exactly.
+If the target is public, keep the patch method public. If the target is
+protected/private, mark the patch method as protected/private in the block.
+
+```ruby
+patch_instance_methods do
+  private
+
+  def internal_token
+    "#{super}-patched"
+  end
+end
+```
+
+```ruby
+patch_instance_methods do
+  def internal_token(*args)
+    super(*args)
+  end
+
+  protected :internal_token
+end
+```
+
 ### Method arity checks
 
 When patching existing methods, arity must match by default. You can opt out:
@@ -209,11 +234,16 @@ MonkeyBars raises specific errors to keep patches safe and explicit:
 - `MonkeyBars::NoPatchableClassMethodFoundError`
 - `MonkeyBars::MismatchedInstanceMethodArityError`
 - `MonkeyBars::MismatchedClassMethodArityError`
+- `MonkeyBars::PatchableInstanceMethodIsPrivateError`
+- `MonkeyBars::PatchableInstanceMethodIsNotPrivateError`
+- `MonkeyBars::PatchableClassMethodIsPrivateError`
+- `MonkeyBars::PatchableClassMethodIsNotPrivateError`
 - `MonkeyBars::NewInstanceMethodAlreadyExistsError`
 - `MonkeyBars::NewClassMethodAlreadyExistsError`
 - `MonkeyBars::PatchConstantNotFoundError`
 - `MonkeyBars::NewConstantAlreadyExistsError`
 - `MonkeyBars::PatchAlreadyPerformedError`
+- `MonkeyBars::PrepareForPatchingAlreadyPerformedError`
 
 ## Development
 

data/docs/llm-usage.md

@@ -46,6 +46,8 @@ compares it with `version` using exact equality. Mismatches raise
 - `prepare_for_patching(...)` validates and stores the patch.
 - `patch!` applies a previously prepared patch and can only be called once.
 
+Calling `prepare_for_patching` more than once raises
+`MonkeyBars::PrepareForPatchingAlreadyPerformedError`.
 Calling `patch!` more than once raises `MonkeyBars::PatchAlreadyPerformedError`.
 
 ## API reference
@@ -86,6 +88,14 @@ Overrides existing instance methods via `prepend`.
 - Error: `MonkeyBars::NoPatchableInstanceMethodFoundError` if method does not exist.
 - Error: `MonkeyBars::MismatchedInstanceMethodArityError` when arity differs,
   unless `ignore_arity_errors: true` is set.
+- Error: `MonkeyBars::PatchableInstanceMethodIsPrivateError` when the target
+  method is private but the patch method is defined as public/protected.
+- Error: `MonkeyBars::PatchableInstanceMethodIsNotPrivateError` when the target
+  method is public/protected but the patch method is marked `private`.
+- Error: `MonkeyBars::PatchableInstanceMethodIsProtectedError` when the target
+  method is protected but the patch method is defined as public/private.
+- Error: `MonkeyBars::PatchableInstanceMethodIsNotProtectedError` when the target
+  method is public/private but the patch method is marked `protected`.
 - `include_super_super: true` makes `#super_super` available for these methods.
 
 #### `new_class_methods(&block)`
@@ -101,6 +111,14 @@ Overrides existing class methods via `singleton_class.prepend`.
 - Error: `MonkeyBars::NoPatchableClassMethodFoundError` if method does not exist.
 - Error: `MonkeyBars::MismatchedClassMethodArityError` when arity differs,
   unless `ignore_arity_errors: true` is set.
+- Error: `MonkeyBars::PatchableClassMethodIsPrivateError` when the target class
+  method is private but the patch method is defined as public/protected.
+- Error: `MonkeyBars::PatchableClassMethodIsNotPrivateError` when the target
+  class method is public/protected but the patch method is marked `private`.
+- Error: `MonkeyBars::PatchableClassMethodIsProtectedError` when the target class
+  method is protected but the patch method is defined as public/private.
+- Error: `MonkeyBars::PatchableClassMethodIsNotProtectedError` when the target
+  class method is public/private but the patch method is marked `protected`.
 - `include_super_super: true` makes `#super_super` available for these methods.
 
 #### `patch_constants(&block)`
@@ -140,6 +158,24 @@ class FixPatch
 end
 ```
 
+### Patch a protected method
+
+```ruby
+class ProtectedPatch
+  extend MonkeyBars
+
+  patch(SomeLibrary, version: "1.0.0", version_check: -> { SomeLibrary::VERSION }) do
+    patch_instance_methods do
+      def internal_token(value)
+        super(value) + "-patched"
+      end
+
+      protected :internal_token
+    end
+  end
+end
+```
+
 ### Add new class method and constant
 
 ```ruby
@@ -200,8 +236,31 @@ Use this section when the patch fails. The message usually suggests the fix.
   Update the version string or the version check.
 - `MonkeyBars::NoPatchableInstanceMethodFoundError`: method does not exist.
   Move it to `new_instance_methods` or fix the method name.
+- `MonkeyBars::PatchableInstanceMethodIsPrivateError`: target method is private
+  but patch method is public/protected. Mark the patch method as `private`.
+- `MonkeyBars::PatchableInstanceMethodIsNotPrivateError`: target method is
+  public/protected but patch method is private. Remove `private` in the patch
+  block or patch a private target.
+- `MonkeyBars::PatchableInstanceMethodIsProtectedError`: target method is
+  protected but patch method is public/private. Mark the patch method as
+  `protected`.
+- `MonkeyBars::PatchableInstanceMethodIsNotProtectedError`: target method is
+  public/private but patch method is protected. Remove `protected` in the patch
+  block or patch a protected target.
 - `MonkeyBars::NoPatchableClassMethodFoundError`: method does not exist.
   Move it to `new_class_methods` or fix the method name.
+- `MonkeyBars::PatchableClassMethodIsPrivateError`: target class method is
+  private but patch method is public/protected. Mark the patch method as
+  `private`.
+- `MonkeyBars::PatchableClassMethodIsNotPrivateError`: target class method is
+  public/protected but patch method is private. Remove `private` in the patch
+  block or patch a private target.
+- `MonkeyBars::PatchableClassMethodIsProtectedError`: target class method is
+  protected but patch method is public/private. Mark the patch method as
+  `protected`.
+- `MonkeyBars::PatchableClassMethodIsNotProtectedError`: target class method is
+  public/private but patch method is protected. Remove `protected` in the patch
+  block or patch a protected target.
 - `MonkeyBars::MismatchedInstanceMethodArityError`: arity differs.
   Match the signature or set `ignore_arity_errors: true`.
 - `MonkeyBars::MismatchedClassMethodArityError`: arity differs.
@@ -216,6 +275,9 @@ Use this section when the patch fails. The message usually suggests the fix.
   Move it to `patch_constants`.
 - `MonkeyBars::PatchAlreadyPerformedError`: `patch!` was called twice.
   Ensure you only call `patch!` once per prepared patch.
+- `MonkeyBars::PrepareForPatchingAlreadyPerformedError`:
+  `prepare_for_patching` was called twice. Ensure you only prepare once per
+  patcher.
 
 ## Best practices for LLMs
 
@@ -223,6 +285,8 @@ Use this section when the patch fails. The message usually suggests the fix.
 - Prefer `patch(...)` for immediate application unless delayed patching is required.
 - Use `patch_*` helpers for existing methods/constants and `new_*` for new ones.
 - Keep patched method arity identical to the original unless explicitly allowed.
+- Keep patched method visibility aligned exactly with the target
+  (`public`/`protected`/`private`).
 - Add targeted tests around the patched behavior; avoid testing internal details.
 
 ## Testing checklist

data/lib/monkey_bars/errors.rb

@@ -61,6 +61,54 @@ module MonkeyBars
     end
   end
 
+  class PatchableClassMethodIsNotPrivateError < StandardError
+    def initialize(patcher_name, monkey: nil, method: nil)
+      super("[#{patcher_name}] The class method `.#{method}` on `#{monkey}` is not private, but is on the patch. Remove it from `private` in your patch.")
+    end
+  end
+
+  class PatchableClassMethodIsPrivateError < StandardError
+    def initialize(patcher_name, monkey: nil, method: nil)
+      super("[#{patcher_name}] The class method `.#{method}` on `#{monkey}` is private, but isn't on the patch. Mark it as `private` in your patch.")
+    end
+  end
+
+  class PatchableClassMethodIsNotProtectedError < StandardError
+    def initialize(patcher_name, monkey: nil, method: nil)
+      super("[#{patcher_name}] The class method `.#{method}` on `#{monkey}` is not protected, but is on the patch. Remove it from `protected` in your patch.")
+    end
+  end
+
+  class PatchableClassMethodIsProtectedError < StandardError
+    def initialize(patcher_name, monkey: nil, method: nil)
+      super("[#{patcher_name}] The class method `.#{method}` on `#{monkey}` is protected, but isn't on the patch. Mark it as `protected` in your patch.")
+    end
+  end
+
+  class PatchableInstanceMethodIsNotPrivateError < StandardError
+    def initialize(patcher_name, monkey: nil, method: nil)
+      super("[#{patcher_name}] The instance method `##{method}` on `#{monkey}` is not private, but is on the patch. Remove it from `private` in your patch.")
+    end
+  end
+
+  class PatchableInstanceMethodIsPrivateError < StandardError
+    def initialize(patcher_name, monkey: nil, method: nil)
+      super("[#{patcher_name}] The instance method `##{method}` on `#{monkey}` is private, but isn't on the patch. Mark it as `private` in your patch.")
+    end
+  end
+
+  class PatchableInstanceMethodIsNotProtectedError < StandardError
+    def initialize(patcher_name, monkey: nil, method: nil)
+      super("[#{patcher_name}] The instance method `##{method}` on `#{monkey}` is not protected, but is on the patch. Remove it from `protected` in your patch.")
+    end
+  end
+
+  class PatchableInstanceMethodIsProtectedError < StandardError
+    def initialize(patcher_name, monkey: nil, method: nil)
+      super("[#{patcher_name}] The instance method `##{method}` on `#{monkey}` is protected, but isn't on the patch. Mark it as `protected` in your patch.")
+    end
+  end
+
   class PatchAlreadyPerformedError < StandardError
     def initialize(patcher_name)
       super("[#{patcher_name}] `#patch!` has already been called and cannot be called again")
@@ -72,4 +120,10 @@ module MonkeyBars
       super("[#{patcher_name}] Couldn't find constant `#{constant}` on `#{monkey}` despite it being marked as patchable. Perhaps move it to the `new_constants` block?")
     end
   end
+
+  class PrepareForPatchingAlreadyPerformedError < StandardError
+    def initialize(patcher_name)
+      super("[#{patcher_name}] `#prepare_for_patching` has already been called and cannot be called again")
+    end
+  end
 end

data/lib/monkey_bars/validation.rb

@@ -34,6 +34,16 @@ module MonkeyBars
         preexisting_instance_method => {block:, ignore_arity_errors:, include_super_super:}
         module_to_prepend.module_eval(&block)
         module_to_prepend.instance_methods.each do |method_name|
+          next if module_to_prepend.protected_method_defined?(method_name)
+
+          if @monkey.protected_method_defined?(method_name)
+            raise(PatchableInstanceMethodIsProtectedError.new(@monkey_patcher_name, monkey: @monkey, method: method_name))
+          end
+
+          if @monkey.private_method_defined?(method_name)
+            raise(PatchableInstanceMethodIsPrivateError.new(@monkey_patcher_name, monkey: @monkey, method: method_name))
+          end
+
           unless @monkey.method_defined?(method_name)
             raise(NoPatchableInstanceMethodFoundError.new(@monkey_patcher_name, monkey: @monkey, method: method_name))
           end
@@ -47,6 +57,42 @@ module MonkeyBars
           end
         end
 
+        module_to_prepend.protected_instance_methods.each do |method_name|
+          if @monkey.private_method_defined?(method_name) || (@monkey.method_defined?(method_name) && !@monkey.protected_method_defined?(method_name))
+            raise(PatchableInstanceMethodIsNotProtectedError.new(@monkey_patcher_name, monkey: @monkey, method: method_name))
+          end
+
+          unless @monkey.protected_method_defined?(method_name)
+            raise(NoPatchableInstanceMethodFoundError.new(@monkey_patcher_name, monkey: @monkey, method: method_name))
+          end
+
+          next if ignore_arity_errors
+
+          prepatched_method = @monkey.instance_method(method_name)
+          patched_method = module_to_prepend.instance_method(method_name)
+          if prepatched_method.arity != patched_method.arity
+            raise(MismatchedInstanceMethodArityError.new(@monkey_patcher_name, monkey: @monkey, method: method_name, prepatched_arity: prepatched_method.arity, patched_arity: patched_method.arity))
+          end
+        end
+
+        module_to_prepend.private_instance_methods.each do |method_name|
+          if @monkey.method_defined?(method_name)
+            raise(PatchableInstanceMethodIsNotPrivateError.new(@monkey_patcher_name, monkey: @monkey, method: method_name))
+          end
+
+          unless @monkey.private_method_defined?(method_name)
+            raise(NoPatchableInstanceMethodFoundError.new(@monkey_patcher_name, monkey: @monkey, method: method_name))
+          end
+
+          next if ignore_arity_errors
+
+          prepatched_method = @monkey.instance_method(method_name)
+          patched_method = module_to_prepend.instance_method(method_name)
+          if prepatched_method.arity != patched_method.arity
+            raise(MismatchedInstanceMethodArityError.new(@monkey_patcher_name, monkey: @monkey, method: method_name, prepatched_arity: prepatched_method.arity, patched_arity: patched_method.arity))
+          end
+        end
+
         # If anyone asks for super_super, include it
         @include_instance_super_super = true if include_super_super
         @patch_instance_methods_module.module_eval(&block)
@@ -80,6 +126,16 @@ module MonkeyBars
         preexisting_class_method => {block:, ignore_arity_errors:, include_super_super:}
         module_to_prepend.module_eval(&block)
         module_to_prepend.instance_methods.each do |method_name|
+          next if module_to_prepend.protected_method_defined?(method_name)
+
+          if @monkey.singleton_class.protected_method_defined?(method_name)
+            raise(PatchableClassMethodIsProtectedError.new(@monkey_patcher_name, monkey: @monkey, method: method_name))
+          end
+
+          if @monkey.singleton_class.private_method_defined?(method_name)
+            raise(PatchableClassMethodIsPrivateError.new(@monkey_patcher_name, monkey: @monkey, method: method_name))
+          end
+
           unless @monkey.singleton_class.method_defined?(method_name)
             raise(NoPatchableClassMethodFoundError.new(@monkey_patcher_name, monkey: @monkey, method: method_name))
           end
@@ -93,6 +149,42 @@ module MonkeyBars
           end
         end
 
+        module_to_prepend.protected_instance_methods.each do |method_name|
+          if @monkey.singleton_class.private_method_defined?(method_name) || (@monkey.singleton_class.method_defined?(method_name) && !@monkey.singleton_class.protected_method_defined?(method_name))
+            raise(PatchableClassMethodIsNotProtectedError.new(@monkey_patcher_name, monkey: @monkey, method: method_name))
+          end
+
+          unless @monkey.singleton_class.protected_method_defined?(method_name)
+            raise(NoPatchableClassMethodFoundError.new(@monkey_patcher_name, monkey: @monkey, method: method_name))
+          end
+
+          next if ignore_arity_errors
+
+          prepatched_method = @monkey.singleton_class.instance_method(method_name)
+          patched_method = module_to_prepend.instance_method(method_name)
+          if prepatched_method.arity != patched_method.arity
+            raise(MismatchedClassMethodArityError.new(@monkey_patcher_name, monkey: @monkey, method: method_name, prepatched_arity: prepatched_method.arity, patched_arity: patched_method.arity))
+          end
+        end
+
+        module_to_prepend.private_instance_methods.each do |method_name|
+          if @monkey.singleton_class.method_defined?(method_name)
+            raise(PatchableClassMethodIsNotPrivateError.new(@monkey_patcher_name, monkey: @monkey, method: method_name))
+          end
+
+          unless @monkey.singleton_class.private_method_defined?(method_name)
+            raise(NoPatchableClassMethodFoundError.new(@monkey_patcher_name, monkey: @monkey, method: method_name))
+          end
+
+          next if ignore_arity_errors
+
+          prepatched_method = @monkey.singleton_class.instance_method(method_name)
+          patched_method = module_to_prepend.instance_method(method_name)
+          if prepatched_method.arity != patched_method.arity
+            raise(MismatchedClassMethodArityError.new(@monkey_patcher_name, monkey: @monkey, method: method_name, prepatched_arity: prepatched_method.arity, patched_arity: patched_method.arity))
+          end
+        end
+
         # If anyone asks for super_super, include it
         @include_class_super_super = true if include_super_super
         @patch_class_methods_module.module_eval(&block)
@@ -124,7 +216,7 @@ module MonkeyBars
         module_to_redefine = Module.new
         module_to_redefine.module_eval(&redefined_constant)
         module_to_redefine.constants(false).each do |const_name|
-          unless @monkey.constants(false).include?(const_name)
+          unless @monkey.const_defined?(const_name, false)
             raise(PatchConstantNotFoundError.new(@monkey_patcher_name, monkey: @monkey, constant: const_name))
           end
         end
@@ -141,7 +233,7 @@ module MonkeyBars
         module_to_include = Module.new
         module_to_include.module_eval(&new_constant)
         module_to_include.constants(false).each do |const_name|
-          if @monkey.constants(false).include?(const_name)
+          if @monkey.const_defined?(const_name, false)
             raise(NewConstantAlreadyExistsError.new(@monkey_patcher_name, monkey: @monkey, constant: const_name))
           end
         end

data/lib/monkey_bars/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MonkeyBars
-  VERSION = "0.1.2"
+  VERSION = "0.2.1"
 end

data/lib/monkey_bars.rb

@@ -31,6 +31,10 @@ module MonkeyBars
   alias_method :🐵, :patch
 
   def prepare_for_patching(monkey, version:, version_check:, patch_immediately: false, &block)
+    if @prepare_for_patching_performed
+      raise(PrepareForPatchingAlreadyPerformedError.new(@monkey_patcher_name))
+    end
+
     @monkey = monkey
     @version = version
     @version_check_block = version_check
@@ -38,6 +42,8 @@ module MonkeyBars
     yield if block_given?
 
     patch! if patch_immediately
+
+    @prepare_for_patching_performed = true
   end
 
   def patch!

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: monkey_bars
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.1
 platform: ruby
 authors:
 - Andrés Rojas
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-10 00:00:00.000000000 Z
+date: 2026-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake