monkey_lens 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d1f86a074dcc3f3a8e7294549267b5a45db15a4e421a155adaf2b4ac6c562853
+  data.tar.gz: 8260182a2b09f07a983d6a5ba481dc1849a1f1ade79afd94710df7d85a76fced
+SHA512:
+  metadata.gz: 526967dd0425e75440c63878be6e34a28deab3d777d022337a340b527855defb439438c1bf5a47057f888734ba515b10fc4ed0f66fd63d281cb09c17bea5a98d
+  data.tar.gz: a9dacd19531ff3934fe76b8a96192e3b2e5a38f911531ea8d535acd25d68a4d1d53231b5fdea1e5913439e64eb1c740304ececf2f26609f95e7b87c888120713

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to MonkeyLens are documented here.
+
+## 0.1.0 — 2026-08-04
+
+- Initial runtime snapshot and drift engine.
+- CLI commands for capture, check, diff, inspect, and doctor.
+- Text, JSON, and SARIF formatters.
+- Rake and Rails integrations.
+- RBS signatures, CI, Pages, release, and RubyGems publishing workflows.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Looney
+
+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,182 @@
+<p align="center">
+  <img src="assets/brand/monkeylens-lockup.svg" alt="MonkeyLens — make runtime patches visible" width="760">
+</p>
+
+<p align="center">
+  <strong>Audit monkey patches, method ownership, prepend layers, and Ruby runtime drift.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/theworker02/monkeylens/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/theworker02/monkeylens/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://rubygems.org/gems/monkey_lens"><img alt="RubyGems" src="https://img.shields.io/gem/v/monkey_lens.svg"></a>
+  <a href="https://theworker02.github.io/monkeylens/"><img alt="Website" src="https://img.shields.io/badge/website-GitHub%20Pages-f97316.svg"></a>
+  <a href="LICENSE.txt"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+</p>
+
+MonkeyLens captures the effective Ruby method table for selected classes and modules, records who owns every method, tracks source locations, visibility, signatures, and ancestor order, then compares that runtime against a committed baseline.
+
+It turns invisible runtime mutation into reviewable evidence.
+
+## Why MonkeyLens?
+
+Ruby deliberately makes classes open. That flexibility is powerful, but a production process can behave differently because a gem reopened a core class, a concern used `prepend`, a test helper redefined a method, or load order changed which implementation won.
+
+MonkeyLens answers:
+
+- Which methods were added, removed, or redefined?
+- Which module currently owns the method Ruby will dispatch?
+- Did a `prepend` layer enter or leave the ancestor chain?
+- Did arity, parameters, visibility, or source location change?
+- Does CI boot with the same runtime shape as the approved baseline?
+
+## Install
+
+Add the gem to your bundle:
+
+```ruby
+gem "monkey_lens"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+After release, direct installation will be:
+
+```bash
+gem install monkey_lens
+```
+
+## Quick start
+
+Create `.monkeylens.yml`:
+
+```yaml
+targets:
+  - String
+  - Array
+  - MyApp::User
+fail_on: high
+format: text
+```
+
+Capture the approved runtime:
+
+```bash
+bundle exec monkeylens capture --output .monkeylens.json
+```
+
+Check for drift:
+
+```bash
+bundle exec monkeylens check
+```
+
+## CLI
+
+```text
+monkeylens capture   Capture a runtime baseline
+monkeylens check     Compare the current runtime with a baseline
+monkeylens diff      Compare two saved snapshots
+monkeylens inspect   Explain one target's effective method table
+monkeylens doctor    Validate configuration and runtime support
+monkeylens version   Print the installed version
+```
+
+### Load an application before capture
+
+```bash
+bundle exec monkeylens capture \
+  --require ./config/environment \
+  --output .monkeylens.json
+```
+
+### JSON or SARIF output
+
+```bash
+bundle exec monkeylens check --format json
+bundle exec monkeylens check --format sarif > monkeylens.sarif
+```
+
+SARIF output can be uploaded to GitHub code scanning or processed by other security tooling.
+
+## Library API
+
+```ruby
+require "monkey_lens"
+
+baseline = MonkeyLens.capture(targets: ["String", "MyApp::User"])
+baseline.write(".monkeylens.json")
+
+current = MonkeyLens.capture(targets: ["String", "MyApp::User"])
+result = MonkeyLens.diff(baseline, current)
+
+abort result.to_text unless result.clean?
+```
+
+## Rake integration
+
+```ruby
+require "monkey_lens/rake_task"
+
+MonkeyLens::RakeTask.new do |task|
+  task.config = ".monkeylens.yml"
+  task.baseline = ".monkeylens.json"
+end
+```
+
+This creates `monkey_lens:capture` and `monkey_lens:check` tasks.
+
+## Rails integration
+
+Add MonkeyLens to your development and test groups. Its Railtie adds the same Rake tasks after the application environment loads.
+
+```ruby
+group :development, :test do
+  gem "monkey_lens"
+end
+```
+
+## Change severities
+
+| Change | Default severity |
+| --- | --- |
+| Method owner changed | Critical |
+| Method source changed | High |
+| Method removed | High |
+| Prepend/ancestor order changed | High |
+| Method signature changed | Medium |
+| Visibility changed | Medium |
+| Method added | Low |
+
+The threshold is configured with `fail_on: low|medium|high|critical`.
+
+## Design guarantees
+
+- Does not execute arbitrary project files unless explicitly passed with `--require`.
+- Does not upload runtime information.
+- Produces deterministic JSON for the same runtime state.
+- Uses Ruby's public reflection APIs.
+- Supports Ruby 3.2 and newer.
+
+## Documentation
+
+- [Configuration](docs/configuration.md)
+- [Architecture](docs/architecture.md)
+- [Release process](docs/releasing.md)
+- [Brand guidelines](docs/branding.md)
+- [Security policy](SECURITY.md)
+- [Contributing](CONTRIBUTING.md)
+
+## Funding
+
+MonkeyLens supports:
+
+- [GitHub Sponsors](https://github.com/sponsors/theworker02)
+- [thanks.dev](https://thanks.dev/u/gh/theworker02)
+
+## License
+
+MIT © 2026 Matthew Looney

data/assets/brand/monkeylens-lockup.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 360" role="img" aria-labelledby="title desc">
+  <title id="title">MonkeyLens logo</title>
+  <desc id="desc">A lens inspecting a Ruby method chain beside the MonkeyLens wordmark.</desc>
+  <defs>
+    <linearGradient id="lens" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#fb923c"/><stop offset="1" stop-color="#dc2626"/></linearGradient>
+    <linearGradient id="ruby" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#ef4444"/><stop offset="1" stop-color="#991b1b"/></linearGradient>
+  </defs>
+  <g transform="translate(34 18) scale(.63)">
+    <circle cx="228" cy="218" r="146" fill="#111827" stroke="url(#lens)" stroke-width="25"/>
+    <path d="M331 321 456 446" stroke="#f97316" stroke-width="42" stroke-linecap="round"/>
+    <path d="M142 208c35-70 137-81 185-18-44 69-139 78-185 18Z" fill="#0f172a" stroke="#fdba74" stroke-width="13"/>
+    <circle cx="234" cy="207" r="39" fill="url(#ruby)" stroke="#fecaca" stroke-width="9"/>
+    <path d="m206 207 22-25 30 13-5 34-34 5-13-27Z" fill="#fff1f2" opacity=".9"/>
+    <path d="M96 113h92M105 151h61M286 111h76M308 151h65M91 292h83M292 287h77" stroke="#fb923c" stroke-width="12" stroke-linecap="round" opacity=".9"/>
+  </g>
+  <text x="390" y="168" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="112" font-weight="800" letter-spacing="-5" fill="#111827">MonkeyLens</text>
+  <text x="397" y="235" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="32" font-weight="600" letter-spacing="2.6" fill="#64748b">MAKE RUNTIME PATCHES VISIBLE</text>
+</svg>

data/assets/brand/monkeylens-mark.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-labelledby="title desc">
+  <title id="title">MonkeyLens mark</title>
+  <desc id="desc">A magnifying lens inspecting a Ruby method chain.</desc>
+  <defs>
+    <linearGradient id="lens" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#fb923c"/><stop offset="1" stop-color="#dc2626"/></linearGradient>
+    <linearGradient id="ruby" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#ef4444"/><stop offset="1" stop-color="#991b1b"/></linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="150%" height="150%"><feDropShadow dx="0" dy="14" stdDeviation="16" flood-color="#020617" flood-opacity=".35"/></filter>
+  </defs>
+  <circle cx="220" cy="218" r="148" fill="#111827" stroke="url(#lens)" stroke-width="26" filter="url(#shadow)"/>
+  <path d="M327 325 459 457" stroke="#f97316" stroke-width="44" stroke-linecap="round"/>
+  <path d="M132 208c35-70 137-81 185-18-44 69-139 78-185 18Z" fill="#0f172a" stroke="#fdba74" stroke-width="13"/>
+  <circle cx="224" cy="207" r="40" fill="url(#ruby)" stroke="#fecaca" stroke-width="9"/>
+  <path d="m196 207 22-26 31 14-5 34-35 5-13-27Z" fill="#fff1f2" opacity=".9"/>
+  <path d="M84 111h94M94 151h62M278 108h78M301 149h65M80 294h83M283 290h78" stroke="#fb923c" stroke-width="12" stroke-linecap="round" opacity=".9"/>
+</svg>

data/exe/monkeylens

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "monkey_lens/cli"
+
+exit MonkeyLens::CLI.run(ARGV)

data/lib/monkey_lens/capture.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "set"
+
+module MonkeyLens
+  class Capture
+    VISIBILITIES = %i[public protected private].freeze
+
+    def initialize(targets:, ignore_methods: [])
+      @targets = targets
+      @ignore_methods = ignore_methods.to_set
+    end
+
+    def call
+      records = @targets.sort.to_h do |target_name|
+        target = constantize(target_name)
+        [target_name, capture_target(target_name, target)]
+      end
+
+      Snapshot.new(
+        schema: Snapshot::SCHEMA,
+        ruby: RUBY_DESCRIPTION,
+        engine: defined?(RUBY_ENGINE) ? RUBY_ENGINE : "ruby",
+        targets: records
+      )
+    end
+
+    private
+
+    def constantize(name)
+      constant = name.split("::").reject(&:empty?).inject(Object) { |scope, part| scope.const_get(part, false) }
+      return constant if constant.is_a?(Module)
+
+      raise ConfigurationError, "#{name} is not a class or module"
+    rescue NameError => error
+      raise ConfigurationError, "cannot resolve target #{name}: #{error.message}"
+    end
+
+    def capture_target(name, target)
+      {
+        "kind" => target.is_a?(Class) ? "class" : "module",
+        "ancestors" => target.ancestors.map { |ancestor| constant_name(ancestor) },
+        "instance_methods" => capture_methods(name, target, singleton: false),
+        "singleton_methods" => capture_methods(name, target.singleton_class, singleton: true)
+      }
+    end
+
+    def capture_methods(target_name, receiver, singleton:)
+      names = VISIBILITIES.flat_map { |visibility| receiver.public_send("#{visibility}_instance_methods", true) }.uniq
+
+      names.sort_by(&:to_s).filter_map do |method_name|
+        identifier = singleton ? "#{target_name}.#{method_name}" : "#{target_name}##{method_name}"
+        next if @ignore_methods.include?(identifier)
+
+        method = receiver.instance_method(method_name)
+        visibility = VISIBILITIES.find { |candidate| receiver.public_send("#{candidate}_method_defined?", method_name) }
+
+        [method_name.to_s, {
+          "owner" => constant_name(method.owner),
+          "visibility" => visibility.to_s,
+          "parameters" => method.parameters.map { |kind, parameter| [kind.to_s, parameter&.to_s] },
+          "arity" => method.arity,
+          "source_location" => normalize_source(method.source_location)
+        }]
+      rescue NameError
+        nil
+      end.to_h
+    end
+
+    def constant_name(value)
+      value.name || value.inspect
+    end
+
+    def normalize_source(location)
+      return nil unless location
+
+      path, line = location
+      [normalize_path(path), line]
+    end
+
+    def normalize_path(path)
+      absolute = File.expand_path(path)
+      cwd = File.expand_path(Dir.pwd)
+      absolute.start_with?("#{cwd}/") ? absolute.delete_prefix("#{cwd}/") : absolute
+    end
+  end
+end

data/lib/monkey_lens/change.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module MonkeyLens
+  class Change
+    LEVELS = {"low" => 1, "medium" => 2, "high" => 3, "critical" => 4}.freeze
+
+    attr_reader :type, :severity, :target, :method_id, :before, :after, :message
+
+    def initialize(type:, severity:, target:, method_id: nil, before: nil, after: nil, message:)
+      @type = type
+      @severity = severity
+      @target = target
+      @method_id = method_id
+      @before = before
+      @after = after
+      @message = message
+    end
+
+    def level
+      LEVELS.fetch(severity)
+    end
+
+    def to_h
+      {
+        "type" => type,
+        "severity" => severity,
+        "target" => target,
+        "method" => method_id,
+        "message" => message,
+        "before" => before,
+        "after" => after
+      }
+    end
+  end
+end

data/lib/monkey_lens/cli.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../monkey_lens"
+
+module MonkeyLens
+  class CLI
+    class << self
+      def run(argv, out: $stdout, err: $stderr)
+        new(argv, out:, err:).run
+      end
+    end
+
+    def initialize(argv, out:, err:)
+      @argv = argv.dup
+      @out = out
+      @err = err
+    end
+
+    def run
+      command = @argv.shift
+      case command
+      when "capture" then capture
+      when "check" then check
+      when "diff" then diff
+      when "inspect" then inspect_target
+      when "doctor" then doctor
+      when "version", "--version", "-v" then version
+      when nil, "help", "--help", "-h" then help
+      else
+        @err.puts "Unknown command: #{command}"
+        help(@err)
+        2
+      end
+    rescue OptionParser::ParseError, MonkeyLens::Error, Errno::ENOENT => error
+      @err.puts "MonkeyLens error: #{error.message}"
+      2
+    end
+
+    private
+
+    def capture
+      options = common_options.merge(output: ".monkeylens.json")
+      parser = parser_for("capture", options) do |opts|
+        opts.on("-o", "--output PATH", "Snapshot output path") { |value| options[:output] = value }
+      end
+      parser.parse!(@argv)
+      config = load_runtime(options)
+      snapshot = MonkeyLens.capture(targets: config.targets, ignore_methods: config.ignore_methods)
+      snapshot.write(options[:output])
+      @out.puts "Captured #{snapshot.targets.length} target(s) to #{options[:output]}"
+      0
+    end
+
+    def check
+      options = common_options.merge(baseline: nil, format: nil, fail_on: nil)
+      parser = parser_for("check", options) do |opts|
+        opts.on("-b", "--baseline PATH", "Baseline path") { |value| options[:baseline] = value }
+        opts.on("-f", "--format FORMAT", %w[text json sarif], "Report format") { |value| options[:format] = value }
+        opts.on("--fail-on LEVEL", Config::LEVELS, "Failure threshold") { |value| options[:fail_on] = value }
+      end
+      parser.parse!(@argv)
+      config = load_runtime(options)
+      baseline = Snapshot.read(options[:baseline] || config.baseline)
+      current = MonkeyLens.capture(targets: config.targets, ignore_methods: config.ignore_methods)
+      result = MonkeyLens.diff(baseline, current)
+      format = options[:format] || config.format
+      @out.puts Formatter.render(result, format:)
+      result.failure?(options[:fail_on] || config.fail_on) ? 1 : 0
+    end
+
+    def diff
+      options = {format: "text", fail_on: nil}
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: monkeylens diff BASELINE CURRENT [options]"
+        opts.on("-f", "--format FORMAT", %w[text json sarif]) { |value| options[:format] = value }
+        opts.on("--fail-on LEVEL", Config::LEVELS) { |value| options[:fail_on] = value }
+      end
+      parser.parse!(@argv)
+      baseline_path, current_path = @argv
+      raise OptionParser::MissingArgument, "BASELINE and CURRENT are required" unless baseline_path && current_path
+
+      result = MonkeyLens.diff(Snapshot.read(baseline_path), Snapshot.read(current_path))
+      @out.puts Formatter.render(result, format: options[:format])
+      options[:fail_on] && result.failure?(options[:fail_on]) ? 1 : 0
+    end
+
+    def inspect_target
+      options = common_options
+      parser = parser_for("inspect", options)
+      parser.parse!(@argv)
+      target = @argv.shift
+      raise OptionParser::MissingArgument, "TARGET is required" unless target
+
+      load_requires(options[:requires])
+      snapshot = MonkeyLens.capture(targets: [target])
+      record = snapshot.targets.fetch(target)
+      @out.puts "#{target} (#{record.fetch("kind")})"
+      @out.puts "Ancestors: #{record.fetch("ancestors").join(" -> ")}"
+      record.fetch("instance_methods").each do |name, method|
+        @out.puts "  ##{name} [#{method.fetch("visibility")}] owner=#{method.fetch("owner")} source=#{method.fetch("source_location")&.join(":") || "native"}"
+      end
+      0
+    end
+
+    def doctor
+      options = common_options
+      parser_for("doctor", options).parse!(@argv)
+      config = Config.load(options[:config])
+      @out.puts "MonkeyLens #{VERSION}"
+      @out.puts RUBY_DESCRIPTION
+      @out.puts "Config: #{options[:config]}"
+      @out.puts "Baseline: #{File.exist?(config.baseline) ? config.baseline : "not found"}"
+      0
+    end
+
+    def version
+      @out.puts VERSION
+      0
+    end
+
+    def help(io = @out)
+      io.puts <<~HELP
+        MonkeyLens #{VERSION} — make Ruby runtime patches visible
+
+        Usage: monkeylens COMMAND [options]
+
+        Commands:
+          capture   Capture a runtime baseline
+          check     Compare the current runtime against a baseline
+          diff      Compare two saved snapshots
+          inspect   Explain a target's effective method table
+          doctor    Validate configuration and runtime support
+          version   Print the installed version
+      HELP
+      0
+    end
+
+    def common_options
+      {config: ".monkeylens.yml", requires: []}
+    end
+
+    def parser_for(command, options)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: monkeylens #{command} [options]"
+        opts.on("-c", "--config PATH", "Configuration path") { |value| options[:config] = value }
+        opts.on("-r", "--require PATH", "Require an application file before capture") { |value| options[:requires] << value }
+        yield opts if block_given?
+      end
+    end
+
+    def load_runtime(options)
+      config = Config.load(options[:config])
+      load_requires(config.requires + options[:requires])
+      config
+    end
+
+    def load_requires(paths)
+      paths.each do |path|
+        expanded = File.expand_path(path)
+        require expanded
+      end
+    end
+  end
+end

data/lib/monkey_lens/config.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module MonkeyLens
+  class Config
+    LEVELS = %w[low medium high critical].freeze
+    FORMATS = %w[text json sarif].freeze
+
+    attr_reader :targets, :ignore_methods, :fail_on, :format, :baseline, :requires
+
+    def initialize(targets:, ignore_methods: [], fail_on: "high", format: "text", baseline: ".monkeylens.json", requires: [])
+      @targets = Array(targets).map(&:to_s).uniq
+      @ignore_methods = Array(ignore_methods).map(&:to_s).uniq
+      @fail_on = fail_on.to_s
+      @format = format.to_s
+      @baseline = baseline.to_s
+      @requires = Array(requires).map(&:to_s)
+      validate!
+    end
+
+    def self.load(path = ".monkeylens.yml")
+      data = File.exist?(path) ? YAML.safe_load_file(path, permitted_classes: [], aliases: false) : {}
+      data ||= {}
+      new(
+        targets: data.fetch("targets", []),
+        ignore_methods: data.fetch("ignore_methods", []),
+        fail_on: data.fetch("fail_on", "high"),
+        format: data.fetch("format", "text"),
+        baseline: data.fetch("baseline", ".monkeylens.json"),
+        requires: data.fetch("requires", [])
+      )
+    rescue Psych::Exception => error
+      raise ConfigurationError, "invalid YAML in #{path}: #{error.message}"
+    end
+
+    private
+
+    def validate!
+      raise ConfigurationError, "targets must contain at least one class or module name" if targets.empty?
+      raise ConfigurationError, "fail_on must be one of #{LEVELS.join(", ")}" unless LEVELS.include?(fail_on)
+      raise ConfigurationError, "format must be one of #{FORMATS.join(", ")}" unless FORMATS.include?(format)
+    end
+  end
+end

data/lib/monkey_lens/diff.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module MonkeyLens
+  class Diff
+    class Result
+      attr_reader :baseline, :current, :changes
+
+      def initialize(baseline:, current:, changes:)
+        @baseline = baseline
+        @current = current
+        @changes = changes.sort_by { |change| [-change.level, change.target, change.method_id.to_s, change.type] }
+      end
+
+      def clean?
+        changes.empty?
+      end
+
+      def failure?(threshold)
+        minimum = Change::LEVELS.fetch(threshold.to_s)
+        changes.any? { |change| change.level >= minimum }
+      end
+
+      def to_h
+        {
+          "schema" => 1,
+          "clean" => clean?,
+          "summary" => Change::LEVELS.keys.to_h { |level| [level, changes.count { |change| change.severity == level }] },
+          "changes" => changes.map(&:to_h)
+        }
+      end
+
+      def to_text
+        Formatter::Text.new(self).render
+      end
+    end
+
+    def initialize(baseline:, current:)
+      @baseline = baseline
+      @current = current
+    end
+
+    def call
+      changes = []
+      target_names = (@baseline.targets.keys | @current.targets.keys).sort
+      target_names.each { |target| compare_target(target, changes) }
+      Result.new(baseline: @baseline, current: @current, changes:)
+    end
+
+    private
+
+    def compare_target(target, changes)
+      before = @baseline.targets[target]
+      after = @current.targets[target]
+
+      unless before
+        changes << change("target_added", "low", target, message: "target entered the runtime snapshot", after:)
+        return
+      end
+      unless after
+        changes << change("target_removed", "critical", target, message: "target disappeared from the runtime snapshot", before:)
+        return
+      end
+
+      if before.fetch("ancestors") != after.fetch("ancestors")
+        changes << change(
+          "ancestor_chain_changed",
+          "high",
+          target,
+          before: before.fetch("ancestors"),
+          after: after.fetch("ancestors"),
+          message: "ancestor/prepend order changed"
+        )
+      end
+
+      compare_methods(target, "instance_methods", "#", before, after, changes)
+      compare_methods(target, "singleton_methods", ".", before, after, changes)
+    end
+
+    def compare_methods(target, key, separator, before_target, after_target, changes)
+      before_methods = before_target.fetch(key)
+      after_methods = after_target.fetch(key)
+      (before_methods.keys | after_methods.keys).sort.each do |name|
+        method_id = "#{target}#{separator}#{name}"
+        before = before_methods[name]
+        after = after_methods[name]
+
+        unless before
+          changes << change("method_added", "low", target, method_id:, after:, message: "method was added")
+          next
+        end
+        unless after
+          changes << change("method_removed", "high", target, method_id:, before:, message: "method was removed")
+          next
+        end
+
+        compare_method_fields(target, method_id, before, after, changes)
+      end
+    end
+
+    def compare_method_fields(target, method_id, before, after, changes)
+      if before.fetch("owner") != after.fetch("owner")
+        changes << change("owner_changed", "critical", target, method_id:, before: before.fetch("owner"), after: after.fetch("owner"), message: "effective method owner changed")
+      end
+      if before.fetch("source_location") != after.fetch("source_location")
+        changes << change("source_changed", "high", target, method_id:, before: before.fetch("source_location"), after: after.fetch("source_location"), message: "method implementation source changed")
+      end
+      if before.fetch("parameters") != after.fetch("parameters") || before.fetch("arity") != after.fetch("arity")
+        changes << change("signature_changed", "medium", target, method_id:, before: signature(before), after: signature(after), message: "method signature changed")
+      end
+      if before.fetch("visibility") != after.fetch("visibility")
+        changes << change("visibility_changed", "medium", target, method_id:, before: before.fetch("visibility"), after: after.fetch("visibility"), message: "method visibility changed")
+      end
+    end
+
+    def signature(method)
+      {"parameters" => method.fetch("parameters"), "arity" => method.fetch("arity")}
+    end
+
+    def change(type, severity, target, method_id: nil, before: nil, after: nil, message:)
+      Change.new(type:, severity:, target:, method_id:, before:, after:, message:)
+    end
+  end
+end

data/lib/monkey_lens/formatter/json.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "json"
+
+module MonkeyLens
+  module Formatter
+    class JSON
+      def initialize(result)
+        @result = result
+      end
+
+      def render
+        ::JSON.pretty_generate(@result.to_h)
+      end
+    end
+  end
+end

data/lib/monkey_lens/formatter/sarif.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "json"
+
+module MonkeyLens
+  module Formatter
+    class SARIF
+      LEVELS = {"low" => "note", "medium" => "warning", "high" => "error", "critical" => "error"}.freeze
+
+      def initialize(result)
+        @result = result
+      end
+
+      def render
+        ::JSON.pretty_generate(
+          {
+            "$schema" => "https://json.schemastore.org/sarif-2.1.0.json",
+            "version" => "2.1.0",
+            "runs" => [{
+              "tool" => {"driver" => {"name" => "MonkeyLens", "version" => MonkeyLens::VERSION, "rules" => rules}},
+              "results" => results
+            }]
+          }
+        )
+      end
+
+      private
+
+      def rules
+        @result.changes.map(&:type).uniq.sort.map do |type|
+          {"id" => type, "shortDescription" => {"text" => type.tr("_", " ")}}
+        end
+      end
+
+      def results
+        @result.changes.map do |change|
+          {
+            "ruleId" => change.type,
+            "level" => LEVELS.fetch(change.severity),
+            "message" => {"text" => "#{change.target}#{change.method_id ? " #{change.method_id}" : ""}: #{change.message}"},
+            "properties" => change.to_h
+          }
+        end
+      end
+    end
+  end
+end

data/lib/monkey_lens/formatter/text.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module MonkeyLens
+  module Formatter
+    class Text
+      def initialize(result)
+        @result = result
+      end
+
+      def render
+        return "MonkeyLens PASS — no runtime drift detected" if @result.clean?
+
+        counts = Change::LEVELS.keys.map do |level|
+          "#{@result.changes.count { |change| change.severity == level }} #{level}"
+        end.join(", ")
+
+        lines = ["MonkeyLens DRIFT — #{counts}", ""]
+        @result.changes.each do |change|
+          subject = change.method_id || change.target
+          lines << "[#{change.severity.upcase}] #{change.type} #{subject}"
+          lines << "  #{change.message}"
+          lines << "  before: #{change.before.inspect}" unless change.before.nil?
+          lines << "  after:  #{change.after.inspect}" unless change.after.nil?
+          lines << ""
+        end
+        lines.join("\n").rstrip
+      end
+    end
+  end
+end

data/lib/monkey_lens/formatter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "formatter/text"
+require_relative "formatter/json"
+require_relative "formatter/sarif"
+
+module MonkeyLens
+  module Formatter
+    module_function
+
+    def render(result, format: "text")
+      formatter = case format.to_s
+                  when "text" then Text
+                  when "json" then JSON
+                  when "sarif" then SARIF
+                  else raise ConfigurationError, "unknown format #{format}"
+                  end
+      formatter.new(result).render
+    end
+  end
+end

data/lib/monkey_lens/railtie.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module MonkeyLens
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      require "monkey_lens/rake_task"
+      MonkeyLens::RakeTask.new
+    end
+  end
+end

data/lib/monkey_lens/rake_task.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "rake"
+require "monkey_lens/cli"
+
+module MonkeyLens
+  class RakeTask
+    attr_accessor :name, :config, :baseline
+
+    def initialize(name = :monkey_lens)
+      @name = name
+      @config = ".monkeylens.yml"
+      @baseline = ".monkeylens.json"
+      yield self if block_given?
+      define_tasks
+    end
+
+    private
+
+    def define_tasks
+      namespace name do
+        desc "Capture a MonkeyLens runtime baseline"
+        task :capture do
+          status = CLI.run(["capture", "--config", config, "--output", baseline])
+          abort "MonkeyLens capture failed" unless status.zero?
+        end
+
+        desc "Check the current Ruby runtime against the MonkeyLens baseline"
+        task :check do
+          status = CLI.run(["check", "--config", config, "--baseline", baseline])
+          abort "MonkeyLens detected runtime drift" unless status.zero?
+        end
+      end
+    end
+  end
+end

data/lib/monkey_lens/snapshot.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "json"
+
+module MonkeyLens
+  class Snapshot
+    SCHEMA = 1
+
+    attr_reader :schema, :ruby, :engine, :targets
+
+    def initialize(schema: SCHEMA, ruby:, engine:, targets:)
+      @schema = Integer(schema)
+      @ruby = ruby.to_s
+      @engine = engine.to_s
+      @targets = targets.transform_keys(&:to_s)
+      validate!
+    end
+
+    def self.read(path)
+      data = JSON.parse(File.read(path))
+      new(
+        schema: data.fetch("schema"),
+        ruby: data.fetch("ruby"),
+        engine: data.fetch("engine"),
+        targets: data.fetch("targets")
+      )
+    rescue JSON::ParserError, KeyError => error
+      raise SnapshotError, "invalid snapshot #{path}: #{error.message}"
+    end
+
+    def write(path)
+      File.write(path, "#{JSON.pretty_generate(to_h)}\n")
+      self
+    end
+
+    def to_h
+      {
+        "schema" => schema,
+        "ruby" => ruby,
+        "engine" => engine,
+        "targets" => targets.sort.to_h
+      }
+    end
+
+    private
+
+    def validate!
+      raise SnapshotError, "unsupported snapshot schema #{schema}" unless schema == SCHEMA
+      raise SnapshotError, "snapshot targets must be an object" unless targets.is_a?(Hash)
+    end
+  end
+end

data/lib/monkey_lens/version.rb

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

data/lib/monkey_lens.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "monkey_lens/version"
+require_relative "monkey_lens/config"
+require_relative "monkey_lens/snapshot"
+require_relative "monkey_lens/change"
+require_relative "monkey_lens/capture"
+require_relative "monkey_lens/diff"
+require_relative "monkey_lens/formatter"
+
+module MonkeyLens
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class SnapshotError < Error; end
+
+  module_function
+
+  def capture(targets:, ignore_methods: [])
+    Capture.new(targets:, ignore_methods:).call
+  end
+
+  def diff(baseline, current)
+    Diff.new(baseline:, current:).call
+  end
+end
+
+require_relative "monkey_lens/railtie" if defined?(Rails::Railtie)

data/sig/monkey_lens.rbs

@@ -0,0 +1,51 @@
+module MonkeyLens
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class SnapshotError < Error
+  end
+
+  class Snapshot
+    SCHEMA: Integer
+    attr_reader schema: Integer
+    attr_reader ruby: String
+    attr_reader engine: String
+    attr_reader targets: Hash[String, untyped]
+
+    def self.read: (String path) -> Snapshot
+    def write: (String path) -> Snapshot
+    def to_h: () -> Hash[String, untyped]
+  end
+
+  class Change
+    attr_reader type: String
+    attr_reader severity: String
+    attr_reader target: String
+    attr_reader method_id: String?
+    attr_reader before: untyped
+    attr_reader after: untyped
+    attr_reader message: String
+
+    def level: () -> Integer
+    def to_h: () -> Hash[String, untyped]
+  end
+
+  class Config
+    attr_reader targets: Array[String]
+    attr_reader ignore_methods: Array[String]
+    attr_reader fail_on: String
+    attr_reader format: String
+    attr_reader baseline: String
+    attr_reader requires: Array[String]
+
+    def self.load: (?String path) -> Config
+  end
+
+  def self.capture: (targets: Array[String], ?ignore_methods: Array[String]) -> Snapshot
+  def self.diff: (Snapshot baseline, Snapshot current) -> Diff::Result
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: monkey_lens
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Looney
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !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'
+description: MonkeyLens captures method ownership, source locations, signatures, visibility,
+  and ancestor order for selected Ruby classes and modules, then detects runtime drift
+  against a committed baseline.
+email:
+- theworker02@users.noreply.github.com
+executables:
+- monkeylens
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- assets/brand/monkeylens-lockup.svg
+- assets/brand/monkeylens-mark.svg
+- exe/monkeylens
+- lib/monkey_lens.rb
+- lib/monkey_lens/capture.rb
+- lib/monkey_lens/change.rb
+- lib/monkey_lens/cli.rb
+- lib/monkey_lens/config.rb
+- lib/monkey_lens/diff.rb
+- lib/monkey_lens/formatter.rb
+- lib/monkey_lens/formatter/json.rb
+- lib/monkey_lens/formatter/sarif.rb
+- lib/monkey_lens/formatter/text.rb
+- lib/monkey_lens/railtie.rb
+- lib/monkey_lens/rake_task.rb
+- lib/monkey_lens/snapshot.rb
+- lib/monkey_lens/version.rb
+- sig/monkey_lens.rbs
+homepage: https://github.com/theworker02/monkeylens
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/theworker02/monkeylens/issues
+  changelog_uri: https://github.com/theworker02/monkeylens/blob/main/CHANGELOG.md
+  documentation_uri: https://theworker02.github.io/monkeylens/
+  funding_uri: https://github.com/sponsors/theworker02
+  homepage_uri: https://github.com/theworker02/monkeylens
+  source_code_uri: https://github.com/theworker02/monkeylens
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Audit monkey patches and Ruby runtime method drift
+test_files: []