monkey_bars 0.1.0.pre.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fc4ba27dfd0e854430540e31905974d75e4f37f297ff1ac54358f0d36b13d154
+  data.tar.gz: '0369347b930b2d800823ed47e1cd1771d7af1a9300181e397f48b39e17e00649'
+SHA512:
+  metadata.gz: 0c5538b4c1268aa4fe8be82ce589b8151298d4ea2dc6a533227b5b2e2376e718a799fe003bfa7fffd813574ca58a087f5868f89eb76e30e8d083e545a7282ecc
+  data.tar.gz: 5a431c19c204c317090c7983ba9d76442c291d0c3a2b98c31be15defbee27e7b87c808681ff6b51ba431f5c4dfe51f8c889ce9e80acbad9afd6457bb969e46fa

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,122 @@
+## Code of Conduct
+
+This project follows the Contributor Covenant Code of Conduct.
+
+### Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+### Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+### Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+### Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+### Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+afrojas@gmail.com. All complaints will be reviewed and investigated promptly
+and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+### Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+#### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+#### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+#### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+#### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+### Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 2.1,
+available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+
+Community Impact Guidelines were inspired by
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html#enforcement-guidelines

data/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+## Contributing
+
+Thanks for taking the time to contribute!
+
+### Reporting issues
+
+- Search existing issues before opening a new one.
+- Include a minimal reproduction, Ruby version, and gem version.
+
+### Development setup
+
+- Install dependencies: `bundle install`
+- Run tests: `bundle exec rspec`
+- Run formatting: `bundle exec standardrb`
+- Ensure it works across all versions with `bin/docker-test --all`
+
+### Pull requests
+
+- Keep changes focused and small.
+- Add or update tests for behavior changes.
+- Update documentation and examples when relevant.
+- Run the test suite and formatter before submitting.
+
+By participating, you agree to follow the code of conduct in
+`CODE_OF_CONDUCT.md`.

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Andrés Rojas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

data/README.md

@@ -0,0 +1,224 @@
+# MonkeyBars
+
+Safe, version-aware monkey patching for Ruby modules and classes. MonkeyBars
+gives you a structured DSL to add or override methods and constants while
+verifying the target's version and validating method arity.
+
+## But... why?
+
+Monkey patching is sometimes necessary, but it is easy to get wrong. This gem
+adds guardrails so patches fail loudly when:
+
+- The target module/class is missing
+- The target version is not what you expect
+- You try to add a method/constant that already exists
+- You try to patch a method/constant that does not exist
+- Method arity changes unexpectedly
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "monkey_bars"
+```
+
+Or install directly:
+
+```sh
+gem install monkey_bars
+```
+
+Requires Ruby 3.2+.
+
+## Quick start
+
+Create a patcher class and extend `MonkeyBars`, then call the appropriate
+methods:
+
+```ruby
+class MyPatch
+  extend MonkeyBars
+
+  patch(SomeLibrary, version: "2.3.1", version_check: -> { SomeLibrary::VERSION }) do
+    new_instance_methods do
+      def new_method
+        "added"
+      end
+    end
+  end
+end
+```
+
+## LLM usage guide
+
+If you want LLM-friendly, structured guidance for patching, see:
+
+- `docs/llm-usage.md`
+
+## Core DSL
+
+The patcher is a class or module that `extend`s `MonkeyBars`. Patches are
+declared inside a block and then applied with `patch` (immediately) or
+`prepare_for_patching` + `patch!` (deferred).
+
+### Patch entry points
+
+- `patch(monkey, version:, version_check:)` applies immediately
+- `prepare_for_patching(monkey, version:, version_check:)` prepares a patch
+- `patch!` applies a prepared patch
+
+If `patch!` runs without any methods or constants defined, it emits a warning.
+
+The `monkey` can be:
+
+- A module/class reference
+- A string constant name (resolved with `Kernel.const_get`)
+- A lambda/proc that returns a module/class
+
+### Patch blocks
+
+Use these block helpers to describe changes:
+
+- `patch_instance_methods` to override existing instance methods
+- `new_instance_methods` to add new instance methods
+- `patch_class_methods` to override existing class methods
+- `new_class_methods` to add new class methods
+- `patch_constants` to redefine existing constants
+- `new_constants` to add new constants
+- `post_patch` to run after patching (with 0 or 1 arg)
+
+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.
+
+### Method arity checks
+
+When patching existing methods, arity must match by default. You can opt out:
+
+```ruby
+patch_instance_methods(ignore_arity_errors: true) do
+  def method_with_args(*args)
+    args.sum
+  end
+end
+```
+
+### super_super helper
+
+If you're looking to mimic fully replacing an existing method and need to call
+`super`, meaning, you want to 'skip' over the original implementation you are
+patching on top of, you can include this helper which exposes a `#super_super`
+method that does just that.
+
+```ruby
+class A
+  VERSION = "1.0"
+
+  def cut_out_the_middlemane
+    puts "A#cut_out_the_middlemane"
+  end
+end
+
+class B < A
+  def cut_out_the_middlemane
+    puts "B#cut_out_the_middlemane"
+    super
+  end
+end
+
+class BPatcher
+  extend MonkeyBars
+
+  patch(B, version: "1.0", version_check: -> { B::VERSION }) do
+    patch_instance_methods(include_super_super: true) do
+      def cut_out_the_middlemane
+        puts "BPatcher#cut_out_the_middlemane"
+        super_super
+      end
+    end
+  end
+end
+
+# B.new.cut_out_the_middlemane
+# => BPatcher#cut_out_the_middlemane
+# => A#cut_out_the_middlemane
+```
+
+The same option is available for class methods.
+
+## Example: full patch
+
+```ruby
+class IntegrationPatch
+  extend MonkeyBars
+
+  patch("SomeLibrary", version: "1.0.0", version_check: -> { SomeLibrary::VERSION }) do
+    new_class_methods do
+      def new_class_method
+        "new class"
+      end
+    end
+
+    patch_class_methods do
+      def class_method
+        super + " + modified"
+      end
+    end
+
+    new_instance_methods do
+      def new_instance_method
+        "new instance"
+      end
+    end
+
+    patch_instance_methods do
+      def instance_method
+        super + " + modified"
+      end
+    end
+
+    patch_constants do
+      const_set(:TIMEOUT, 60)
+    end
+
+    new_constants do
+      const_set(:MAX_RETRIES, 5)
+    end
+
+    post_patch do |monkey|
+      # optional callback
+    end
+  end
+
+end
+```
+
+## Errors you may see
+
+MonkeyBars raises specific errors to keep patches safe and explicit:
+
+- `MonkeyBars::NoPatchableMonkeyFoundError`
+- `MonkeyBars::NoPatchableVersionCheckError`
+- `MonkeyBars::NoPatchableVersionFoundError`
+- `MonkeyBars::NoPatchableInstanceMethodFoundError`
+- `MonkeyBars::NoPatchableClassMethodFoundError`
+- `MonkeyBars::MismatchedInstanceMethodArityError`
+- `MonkeyBars::MismatchedClassMethodArityError`
+- `MonkeyBars::NewInstanceMethodAlreadyExistsError`
+- `MonkeyBars::NewClassMethodAlreadyExistsError`
+- `MonkeyBars::PatchConstantNotFoundError`
+- `MonkeyBars::NewConstantAlreadyExistsError`
+- `MonkeyBars::PatchAlreadyPerformedError`
+
+## Development
+
+```sh
+bin/setup
+bin/console
+bundle exec rspec
+```
+
+## License
+
+MIT. See `LICENSE.txt`.

data/docs/llm-usage.md

@@ -0,0 +1,232 @@
+# LLM Usage Guide for MonkeyBars
+
+This guide is written for LLMs and tools that need precise instructions to
+apply patches safely with MonkeyBars. It focuses on the public API, expected
+inputs/outputs, and common failure modes.
+
+## Quick start
+
+Minimal, correct patch that adds a new instance method:
+
+```ruby
+class MyPatch
+  extend MonkeyBars
+
+  patch(SomeLibrary, version: "2.3.1", version_check: -> { SomeLibrary::VERSION }) do
+    new_instance_methods do
+      def new_method
+        "added"
+      end
+    end
+  end
+end
+```
+
+## Core concepts
+
+### Monkey resolution
+
+The `monkey` argument can be:
+
+- A module/class reference (e.g. `SomeLibrary`)
+- A string constant name (e.g. `"SomeLibrary"`, resolved via `Kernel.const_get`)
+- A lambda/proc that returns a module/class (evaluated at patch time)
+
+If it cannot be resolved, `MonkeyBars::NoPatchableMonkeyFoundError` is raised.
+
+### Version checking
+
+`version_check` must be callable and return the current version. MonkeyBars
+compares it with `version` using exact equality. Mismatches raise
+`MonkeyBars::NoPatchableVersionFoundError`.
+
+### Patch lifecycle
+
+- `patch(...)` validates and applies immediately.
+- `prepare_for_patching(...)` validates and stores the patch.
+- `patch!` applies a previously prepared patch and can only be called once.
+
+Calling `patch!` more than once raises `MonkeyBars::PatchAlreadyPerformedError`.
+
+## API reference
+
+### Entry points
+
+#### `patch(monkey, version:, version_check:)`
+
+Validates and applies a patch immediately.
+
+- `monkey`: module/class, string, or callable
+- `version`: expected version (exact string match)
+- `version_check`: callable returning current version
+- Side effect: mutates the target module/class in place
+
+#### `prepare_for_patching(monkey, version:, version_check:)`
+
+Validates and stores patch definitions for later application.
+
+#### `patch!`
+
+Applies a prepared patch exactly once.
+
+### Patch blocks (helpers)
+
+Each helper can be called multiple times; MonkeyBars combines the definitions.
+
+#### `new_instance_methods(&block)`
+
+Adds new instance methods via `include`.
+
+- Error: `MonkeyBars::NewInstanceMethodAlreadyExistsError` if method exists.
+
+#### `patch_instance_methods(ignore_arity_errors: false, include_super_super: false, &block)`
+
+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.
+- `include_super_super: true` makes `#super_super` available for these methods.
+
+#### `new_class_methods(&block)`
+
+Adds new class methods via `extend`.
+
+- Error: `MonkeyBars::NewClassMethodAlreadyExistsError` if method exists.
+
+#### `patch_class_methods(ignore_arity_errors: false, include_super_super: false, &block)`
+
+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.
+- `include_super_super: true` makes `#super_super` available for these methods.
+
+#### `patch_constants(&block)`
+
+Redefines existing constants (remove + set).
+
+- Error: `MonkeyBars::PatchConstantNotFoundError` if constant does not exist.
+
+#### `new_constants(&block)`
+
+Adds new constants.
+
+- Error: `MonkeyBars::NewConstantAlreadyExistsError` if constant exists.
+
+#### `post_patch(&block)`
+
+Optional callback after patching. If the block arity is:
+
+- `0`: called with no args
+- `1`: called with the patched module/class
+
+## Examples
+
+### Patch an existing instance method
+
+```ruby
+class FixPatch
+  extend MonkeyBars
+
+  patch(SomeLibrary, version: "1.0.0", version_check: -> { SomeLibrary::VERSION }) do
+    patch_instance_methods do
+      def compute(value)
+        super(value) + 1
+      end
+    end
+  end
+end
+```
+
+### Add new class method and constant
+
+```ruby
+class Additions
+  extend MonkeyBars
+
+  patch("SomeLibrary", version: "1.0.0", version_check: -> { SomeLibrary::VERSION }) do
+    new_class_methods do
+      def new_class_method
+        "ok"
+      end
+    end
+
+    new_constants do
+      const_set(:MAX_RETRIES, 5)
+    end
+  end
+end
+```
+
+### Use `super_super` to skip the immediate parent
+
+```ruby
+class Parent
+  def greet
+    "parent"
+  end
+end
+
+class Child < Parent
+  def greet
+    "child -> " + super
+  end
+end
+
+class ChildPatch
+  extend MonkeyBars
+
+  patch(Child, version: "1.0", version_check: -> { "1.0" }) do
+    patch_instance_methods(include_super_super: true) do
+      def greet
+        "patched -> " + super_super
+      end
+    end
+  end
+end
+```
+
+## Error reference and fixes
+
+Use this section when the patch fails. The message usually suggests the fix.
+
+- `MonkeyBars::NoPatchableMonkeyFoundError`: the target constant cannot be found.
+  Use a valid constant or a callable that returns one.
+- `MonkeyBars::NoPatchableVersionCheckError`: `version_check` is missing or not callable.
+  Provide a lambda/proc returning the current version.
+- `MonkeyBars::NoPatchableVersionFoundError`: current version does not match `version`.
+  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::NoPatchableClassMethodFoundError`: method does not exist.
+  Move it to `new_class_methods` or fix the method name.
+- `MonkeyBars::MismatchedInstanceMethodArityError`: arity differs.
+  Match the signature or set `ignore_arity_errors: true`.
+- `MonkeyBars::MismatchedClassMethodArityError`: arity differs.
+  Match the signature or set `ignore_arity_errors: true`.
+- `MonkeyBars::NewInstanceMethodAlreadyExistsError`: method already exists.
+  Move it to `patch_instance_methods`.
+- `MonkeyBars::NewClassMethodAlreadyExistsError`: method already exists.
+  Move it to `patch_class_methods`.
+- `MonkeyBars::PatchConstantNotFoundError`: constant does not exist.
+  Move it to `new_constants` or fix the constant name.
+- `MonkeyBars::NewConstantAlreadyExistsError`: constant already exists.
+  Move it to `patch_constants`.
+- `MonkeyBars::PatchAlreadyPerformedError`: `patch!` was called twice.
+  Ensure you only call `patch!` once per prepared patch.
+
+## Best practices for LLMs
+
+- Always include `version_check` and ensure it returns the exact version string.
+- 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.
+- Add targeted tests around the patched behavior; avoid testing internal details.
+
+## Testing checklist
+
+- Patch applies with the expected version and fails with a mismatched version.
+- Patched method behavior is correct and `super`/`super_super` calls behave as intended.
+- Errors are raised for missing methods/constants and for arity mismatches.

data/lib/monkey_bars/errors.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module MonkeyBars
+  class NewInstanceMethodAlreadyExistsError < StandardError
+    def initialize(patcher_name, monkey: nil, method: nil)
+      super("[#{patcher_name}] The instance method `##{method}` already exists on `#{monkey}` but is marked as new. Perhaps move it to the `patch_instance_methods` block?")
+    end
+  end
+
+  class NewClassMethodAlreadyExistsError < StandardError
+    def initialize(patcher_name, monkey: nil, method: nil)
+      super("[#{patcher_name}] The class method `.#{method}` already exists on `#{monkey}` but is marked as new. Perhaps move it to the `patch_class_methods` block?")
+    end
+  end
+
+  class MismatchedInstanceMethodArityError < StandardError
+    def initialize(patcher_name, monkey: nil, method: nil, prepatched_arity: nil, patched_arity: nil)
+      super("[#{patcher_name}] The instance method `##{method}` on `#{monkey}` has an arity of #{patched_arity} but a prepatched arity of #{prepatched_arity}. If you want to ignore this error, set `ignore_arity_errors: true`.")
+    end
+  end
+
+  class MismatchedClassMethodArityError < StandardError
+    def initialize(patcher_name, monkey: nil, method: nil, prepatched_arity: nil, patched_arity: nil)
+      super("[#{patcher_name}] The class method `.#{method}` on `#{monkey}` has an arity of #{patched_arity} but a prepatched arity of #{prepatched_arity}. If you want to ignore this error, set `ignore_arity_errors: true`.")
+    end
+  end
+
+  class NewConstantAlreadyExistsError < StandardError
+    def initialize(patcher_name, monkey: nil, constant: nil)
+      super("[#{patcher_name}] The constant `#{constant}` already exists on `#{monkey}` but is marked as new. Perhaps move it to the `patch_constants` block?")
+    end
+  end
+
+  class NoPatchableMonkeyFoundError < StandardError
+    def initialize(patcher_name, monkey: nil)
+      super("[#{patcher_name}] Couldn't find `#{monkey}` to patch.")
+    end
+  end
+
+  class NoPatchableVersionFoundError < StandardError
+    def initialize(patcher_name, monkey: nil, version: nil, current_version: nil)
+      super("[#{patcher_name}] Ready to patch `#{monkey}` but found version `#{current_version}` instead of `#{version}`.")
+    end
+  end
+
+  class NoPatchableVersionCheckError < StandardError
+    def initialize(patcher_name, monkey: nil)
+      super("[#{patcher_name}] `version_check` block is missing. Without it, there's no way to know if the version of `#{monkey}` is patchable.")
+    end
+  end
+
+  class NoPatchableClassMethodFoundError < StandardError
+    def initialize(patcher_name, monkey: nil, method: nil)
+      super("[#{patcher_name}] Couldn't find class method `.#{method}` on `#{monkey}` despite it being marked as preexisting. Perhaps move it to the `new_class_methods` block?")
+    end
+  end
+
+  class NoPatchableInstanceMethodFoundError < StandardError
+    def initialize(patcher_name, monkey: nil, method: nil)
+      super("[#{patcher_name}] Couldn't find instance method `##{method}` on `#{monkey}` despite it being marked as patchable. Perhaps move it to the `new_instance_methods` block?")
+    end
+  end
+
+  class PatchAlreadyPerformedError < StandardError
+    def initialize(patcher_name)
+      super("[#{patcher_name}] `#patch!` has already been called and cannot be called again")
+    end
+  end
+
+  class PatchConstantNotFoundError < StandardError
+    def initialize(patcher_name, monkey: nil, constant: nil)
+      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
+end

data/lib/monkey_bars/patch.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module MonkeyBars
+  module Patch
+    private
+
+    def perform_patch
+      patch_class_methods_internal
+      patch_instance_methods_internal
+      patch_constants_internal
+      patch_new_constants_internal
+
+      return unless @post_patch_block.respond_to?(:call)
+      if @post_patch_block.arity == 0
+        @post_patch_block.call
+      else
+        @post_patch_block.call(@monkey)
+      end
+    end
+
+    def patch_class_methods_internal
+      patch_additional_class_methods
+      patch_preexisting_class_methods
+    end
+
+    def patch_additional_class_methods
+      return unless @new_class_methods_module
+      @monkey.extend(@new_class_methods_module)
+    end
+
+    def patch_preexisting_class_methods
+      return unless @patch_class_methods_module
+      @monkey.singleton_class.prepend(@patch_class_methods_module)
+      @monkey.singleton_class.prepend(SuperSuper) if @include_class_super_super
+    end
+
+    def patch_instance_methods_internal
+      patch_additional_instance_methods
+      patch_preexisting_instance_methods
+    end
+
+    def patch_additional_instance_methods
+      return unless @new_instance_methods_module
+      @monkey.include(@new_instance_methods_module)
+    end
+
+    def patch_preexisting_instance_methods
+      return unless @patch_instance_methods_module
+      @monkey.prepend(@patch_instance_methods_module)
+      @monkey.include(SuperSuper) if @include_instance_super_super
+    end
+
+    def patch_constants_internal
+      return unless @patch_constants_module
+      @patch_constants_module.constants(false).each do |const_name|
+        new_value = @patch_constants_module.const_get(const_name)
+        @monkey.send(:remove_const, const_name)
+        @monkey.const_set(const_name, new_value)
+      end
+    end
+
+    def patch_new_constants_internal
+      return unless @new_constants_module
+      @new_constants_module.constants(false).each do |const_name|
+        new_value = @new_constants_module.const_get(const_name)
+        @monkey.const_set(const_name, new_value)
+      end
+    end
+
+    def fetch_const_for(module_or_string_or_block)
+      return nil if module_or_string_or_block.nil?
+
+      return module_or_string_or_block if module_or_string_or_block.is_a?(Module)
+
+      if module_or_string_or_block.is_a?(String)
+        begin
+          return Kernel.const_get(module_or_string_or_block)
+        rescue NameError
+          return nil
+        end
+      end
+
+      if module_or_string_or_block.respond_to?(:call)
+        begin
+          module_or_string_or_block.call
+        rescue NameError
+          nil
+        end
+      end
+    end
+  end
+
+  module SuperSuper
+    def super_super(*args, **kwargs)
+      # Get the calling method name from the caller stack
+      # Caller format can be: "file.rb:line:in 'method_name'" or "file.rb:line:in `method_name'"
+      caller_line = caller(1..1).first
+      calling_method_name = caller_line[/in [`'](.*?)[`']/, 1] || caller_line[/in (.*?)$/, 1]
+
+      raise "Could not determine calling method name from: #{caller_line}" if calling_method_name.nil?
+
+      if is_a?(Class)
+        # For class methods (when extended on a class)
+        unless superclass.respond_to?(:singleton_method) && superclass.singleton_methods.include?(calling_method_name.to_sym)
+          raise NoMethodError, "undefined method `#{calling_method_name}' for class `#{superclass}'"
+        end
+        superclass.singleton_method(calling_method_name).call(*args, **kwargs)
+      else
+        # For instance methods
+        unless self.class.superclass&.method_defined?(calling_method_name.to_sym)
+          raise(NoMethodError, "undefined method `#{calling_method_name}' for class `#{self.class.superclass}'")
+        end
+        self.class.superclass.instance_method(calling_method_name).bind_call(self, *args, **kwargs)
+      end
+    end
+  end
+end

data/lib/monkey_bars/validation.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module MonkeyBars
+  module Validation
+    private
+
+    def ensure_monkey_exists
+      found_const = fetch_const_for(@monkey)
+      if found_const
+        @monkey = found_const
+      else
+        raise(NoPatchableMonkeyFoundError.new(@monkey_patcher_name, monkey: @monkey))
+      end
+    end
+
+    def ensure_patchable_version
+      unless @version_check_block.respond_to?(:call)
+        raise(NoPatchableVersionCheckError.new(@monkey_patcher_name, monkey: @monkey))
+      end
+
+      current_version = @version_check_block.call
+      if current_version != @version
+        raise(NoPatchableVersionFoundError.new(@monkey_patcher_name, monkey: @monkey, version: @version, current_version: current_version))
+      end
+    end
+
+    def ensure_patch_instance_methods_are_valid
+      return unless @patch_instance_methods.any?
+
+      @patch_instance_methods_module = Module.new
+      @include_instance_super_super = false
+      @patch_instance_methods.each do |preexisting_instance_method|
+        module_to_prepend = Module.new
+        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|
+          unless @monkey.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)
+      end
+    end
+
+    def ensure_new_instance_methods_are_valid
+      return unless @new_instance_methods.any?
+
+      @new_instance_methods_module = Module.new
+      @new_instance_methods.each do |new_instance_methods_block|
+        module_to_include = Module.new
+        module_to_include.module_eval(&new_instance_methods_block)
+        module_to_include.instance_methods.each do |method_name|
+          if @monkey.method_defined?(method_name)
+            raise(NewInstanceMethodAlreadyExistsError.new(@monkey_patcher_name, monkey: @monkey, method: method_name))
+          end
+        end
+
+        @new_instance_methods_module.module_eval(&new_instance_methods_block)
+      end
+    end
+
+    def ensure_patch_class_methods_are_valid
+      return unless @patch_class_methods.any?
+
+      @patch_class_methods_module = Module.new
+      @include_class_super_super = false
+      @patch_class_methods.each do |preexisting_class_method|
+        module_to_prepend = Module.new
+        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|
+          unless @monkey.singleton_class.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)
+      end
+    end
+
+    def ensure_new_class_methods_are_valid
+      return unless @new_class_methods.any?
+
+      @new_class_methods_module = Module.new
+      @new_class_methods.each do |new_class_methods_block|
+        module_to_include = Module.new
+        module_to_include.module_eval(&new_class_methods_block)
+        module_to_include.instance_methods.each do |method_name|
+          if @monkey.singleton_class.method_defined?(method_name)
+            raise(NewClassMethodAlreadyExistsError.new(@monkey_patcher_name, monkey: @monkey, method: method_name))
+          end
+        end
+
+        @new_class_methods_module.module_eval(&new_class_methods_block)
+      end
+    end
+
+    def ensure_patch_constants_are_valid
+      return unless @patch_constants.any?
+
+      @patch_constants_module = Module.new
+      @patch_constants.each do |redefined_constant|
+        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)
+            raise(PatchConstantNotFoundError.new(@monkey_patcher_name, monkey: @monkey, constant: const_name))
+          end
+        end
+
+        @patch_constants_module.module_eval(&redefined_constant)
+      end
+    end
+
+    def ensure_new_constants_are_valid
+      return unless @new_constants.any?
+
+      @new_constants_module = Module.new
+      @new_constants.each do |new_constant|
+        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)
+            raise(NewConstantAlreadyExistsError.new(@monkey_patcher_name, monkey: @monkey, constant: const_name))
+          end
+        end
+
+        @new_constants_module.module_eval(&new_constant)
+      end
+    end
+  end
+end

data/lib/monkey_bars/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MonkeyBars
+  VERSION = "0.1.0-pre"
+end

data/lib/monkey_bars.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "monkey_bars/version"
+require_relative "monkey_bars/errors"
+require_relative "monkey_bars/validation"
+require_relative "monkey_bars/patch"
+
+module MonkeyBars
+  include Validation
+  include Patch
+
+  def self.extended(monkey_patcher)
+    monkey_patcher.instance_variable_set(:@monkey_patcher_name, monkey_patcher.name)
+    monkey_patcher.instance_variable_set(:@patch_class_methods, [])
+    monkey_patcher.instance_variable_set(:@new_class_methods, [])
+    monkey_patcher.instance_variable_set(:@patch_instance_methods, [])
+    monkey_patcher.instance_variable_set(:@new_instance_methods, [])
+    monkey_patcher.instance_variable_set(:@patch_constants, [])
+    monkey_patcher.instance_variable_set(:@new_constants, [])
+  end
+
+  def patch(monkey, version:, version_check:, &block)
+    prepare_for_patching(
+      monkey,
+      version: version,
+      version_check: version_check,
+      patch_immediately: true,
+      &block
+    )
+  end
+  alias_method :🐵, :patch
+
+  def prepare_for_patching(monkey, version:, version_check:, patch_immediately: false, &block)
+    @monkey = monkey
+    @version = version
+    @version_check_block = version_check
+
+    yield if block_given?
+
+    patch! if patch_immediately
+  end
+
+  def patch!
+    if @patch_performed
+      raise(PatchAlreadyPerformedError.new(@monkey_patcher_name))
+    end
+
+    if @patch_class_methods.empty? &&
+        @new_class_methods.empty? &&
+        @patch_instance_methods.empty? &&
+        @new_instance_methods.empty? &&
+        @patch_constants.empty? &&
+        @new_constants.empty?
+      warn "[#{self}] No methods or constants defined. Maybe you're not calling `#patch!` last?"
+    end
+
+    ensure_monkey_exists
+    ensure_patchable_version
+    ensure_patch_instance_methods_are_valid
+    ensure_new_instance_methods_are_valid
+    ensure_patch_class_methods_are_valid
+    ensure_new_class_methods_are_valid
+    ensure_patch_constants_are_valid
+    ensure_new_constants_are_valid
+
+    perform_patch
+
+    @patch_performed = true
+  end
+
+  def patch_class_methods(ignore_arity_errors: false, include_super_super: false, &block)
+    @patch_class_methods << {
+      block: block,
+      ignore_arity_errors: ignore_arity_errors,
+      include_super_super: include_super_super
+    }
+  end
+
+  def new_class_methods(&block)
+    @new_class_methods << block
+  end
+
+  def patch_instance_methods(ignore_arity_errors: false, include_super_super: false, &block)
+    @patch_instance_methods << {
+      block: block,
+      ignore_arity_errors: ignore_arity_errors,
+      include_super_super: include_super_super
+    }
+  end
+
+  def new_instance_methods(&block)
+    @new_instance_methods << block
+  end
+
+  def patch_constants(&block)
+    @patch_constants << block
+  end
+
+  def new_constants(&block)
+    @new_constants << block
+  end
+
+  def post_patch(&block)
+    @post_patch_block = block
+  end
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: monkey_bars
+version: !ruby/object:Gem::Version
+  version: 0.1.0.pre.pre
+platform: ruby
+authors:
+- Andrés Rojas
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.40'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.40'
+description: MonkeyBars provides a structured DSL for safely monkey patching Ruby
+  modules with built-in version checking, method validation, and constant management
+  to prevent silent breakage when dependencies update.
+email:
+- afrojas@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- docs/llm-usage.md
+- lib/monkey_bars.rb
+- lib/monkey_bars/errors.rb
+- lib/monkey_bars/patch.rb
+- lib/monkey_bars/validation.rb
+- lib/monkey_bars/version.rb
+homepage: https://github.com/afrojas/monkey_bars
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/afrojas/monkey_bars
+  source_code_uri: https://github.com/afrojas/monkey_bars
+  bug_tracker_uri: https://github.com/afrojas/monkey_bars/issues
+  documentation_uri: https://rubydoc.info/gems/monkey_bars
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Safe, version-aware monkey patching for Ruby modules
+test_files: []