monkey_lens 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1f86a074dcc3f3a8e7294549267b5a45db15a4e421a155adaf2b4ac6c562853
-  data.tar.gz: 8260182a2b09f07a983d6a5ba481dc1849a1f1ade79afd94710df7d85a76fced
+  metadata.gz: 731b73d48ea7d97b0d3ce1f66a5f246fee22298053e4011c2f1e3a8fd8060f57
+  data.tar.gz: a3ddb66de6351e173ee7db2b785949e1ea602487192c0a899396ef345efe745f
 SHA512:
-  metadata.gz: 526967dd0425e75440c63878be6e34a28deab3d777d022337a340b527855defb439438c1bf5a47057f888734ba515b10fc4ed0f66fd63d281cb09c17bea5a98d
-  data.tar.gz: a9dacd19531ff3934fe76b8a96192e3b2e5a38f911531ea8d535acd25d68a4d1d53231b5fdea1e5913439e64eb1c740304ececf2f26609f95e7b87c888120713
+  metadata.gz: 5939da5fffbbb4c203da4f5d2168a3a04e03b578c67e323ef80b54bacbf7265ceec4916bea7cf87502b8977e5d60907e52c1306eb3ec35373f8dae701efb5ab9
+  data.tar.gz: 22c9b607eb22bf61e6455346fc10b07eae60d3ef3d8186fcb8e7b238c3996a689381c3fc0b503b1df890db617b48e74a4109f5e31d557af26d0923f488b37d80

data/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to MonkeyLens are documented here.
 
+## 0.4.0 — 2026-08-14
+
+- Record `original_name`, `aliases`, and `super_owner` on every captured method.
+- Diff `alias_changed` and `super_owner_changed` so alias_method and prepend-layer shifts are visible.
+- Inspect output includes aliases and the super-method owner.
+
+## 0.3.0 — 2026-08-11
+
+- Added `MonkeyLens::Provenance` to attribute method `source_location` to gem, app, stdlib, or eval origins.
+- Opt-in provenance capture via `provenance: true` on `MonkeyLens.capture` and `--provenance` on CLI capture/inspect.
+- Included provenance in inspect output and snapshot method records when enabled.
+
+## 0.2.0 — 2026-08-04
+
+- Added `MonkeyLens::Policy` for approving known runtime drift without deleting evidence from the baseline.
+- Added wildcard waivers for change type, target, and method identifiers.
+- Required a written reason for every waiver.
+- Added optional ISO-date expiration for temporary approvals.
+- Added YAML policy loading through `MonkeyLens::Policy.load`.
+- Added `Policy::Decision` with effective and waived changes, threshold evaluation, and JSON-ready output.
+- Added the `MonkeyLens.evaluate` convenience API.
+
 ## 0.1.0 — 2026-08-04
 
 - Initial runtime snapshot and drift engine.

data/README.md

@@ -13,6 +13,14 @@
   <a href="LICENSE.txt"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
 </p>
 
+<p align="center">
+  <a href="https://rubygems.org/gems/monkey_lens"><strong>Official RubyGems gem</strong></a>
+  ·
+  <a href="https://theworker02.github.io/monkeylens/"><strong>Documentation website</strong></a>
+  ·
+  <a href="https://github.com/theworker02/monkeylens/releases/latest"><strong>Latest GitHub release</strong></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.
@@ -43,7 +51,7 @@ Then run:
 bundle install
 ```
 
-After release, direct installation will be:
+Install directly from the official RubyGems release:
 
 ```bash
 gem install monkey_lens
@@ -144,11 +152,13 @@ end
 | Change | Default severity |
 | --- | --- |
 | Method owner changed | Critical |
+| Super-method owner changed | High |
 | Method source changed | High |
 | Method removed | High |
 | Prepend/ancestor order changed | High |
 | Method signature changed | Medium |
 | Visibility changed | Medium |
+| Method aliases changed | Medium |
 | Method added | Low |
 
 The threshold is configured with `fail_on: low|medium|high|critical`.

data/lib/monkey_lens/capture.rb

@@ -6,9 +6,10 @@ module MonkeyLens
   class Capture
     VISIBILITIES = %i[public protected private].freeze
 
-    def initialize(targets:, ignore_methods: [])
+    def initialize(targets:, ignore_methods: [], provenance: false)
       @targets = targets
       @ignore_methods = ignore_methods.to_set
+      @provenance = provenance
     end
 
     def call
@@ -54,14 +55,21 @@ module MonkeyLens
 
         method = receiver.instance_method(method_name)
         visibility = VISIBILITIES.find { |candidate| receiver.public_send("#{candidate}_method_defined?", method_name) }
+        aliases = aliases_for(receiver, method_name, method)
+        super_method = method.super_method
+        original = method.respond_to?(:original_name) ? method.original_name.to_s : method_name.to_s
 
         [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)
-        }]
+          "source_location" => normalize_source(method.source_location),
+          "provenance" => provenance_for(method.source_location),
+          "original_name" => original,
+          "aliases" => aliases,
+          "super_owner" => super_method && constant_name(super_method.owner)
+        }.compact]
       rescue NameError
         nil
       end.to_h
@@ -83,5 +91,21 @@ module MonkeyLens
       cwd = File.expand_path(Dir.pwd)
       absolute.start_with?("#{cwd}/") ? absolute.delete_prefix("#{cwd}/") : absolute
     end
+
+    def provenance_for(location)
+      return nil unless @provenance
+
+      Provenance.for_source_location(location)&.to_h
+    end
+
+    def aliases_for(receiver, method_name, method)
+      receiver.instance_methods(true).filter_map do |other|
+        next if other == method_name
+
+        other.to_s if receiver.instance_method(other) == method
+      rescue NameError
+        nil
+      end.sort
+    end
   end
 end

data/lib/monkey_lens/cli.rb

@@ -40,13 +40,14 @@ module MonkeyLens
     private
 
     def capture
-      options = common_options.merge(output: ".monkeylens.json")
+      options = common_options.merge(output: ".monkeylens.json", provenance: false)
       parser = parser_for("capture", options) do |opts|
         opts.on("-o", "--output PATH", "Snapshot output path") { |value| options[:output] = value }
+        opts.on("--provenance", "Attribute method source to gem/app/stdlib/eval") { options[:provenance] = true }
       end
       parser.parse!(@argv)
       config = load_runtime(options)
-      snapshot = MonkeyLens.capture(targets: config.targets, ignore_methods: config.ignore_methods)
+      snapshot = MonkeyLens.capture(targets: config.targets, ignore_methods: config.ignore_methods, provenance: options[:provenance])
       snapshot.write(options[:output])
       @out.puts "Captured #{snapshot.targets.length} target(s) to #{options[:output]}"
       0
@@ -87,18 +88,26 @@ module MonkeyLens
 
     def inspect_target
       options = common_options
-      parser = parser_for("inspect", options)
+      parser = parser_for("inspect", options) do |opts|
+        opts.on("--provenance", "Attribute method source to gem/app/stdlib/eval") { |value| options[:provenance] = true }
+      end
       parser.parse!(@argv)
       target = @argv.shift
       raise OptionParser::MissingArgument, "TARGET is required" unless target
 
       load_requires(options[:requires])
-      snapshot = MonkeyLens.capture(targets: [target])
+      snapshot = MonkeyLens.capture(targets: [target], provenance: options[:provenance])
       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"}"
+        source = method.fetch("source_location")&.join(":") || "native"
+        provenance = method["provenance"]
+        provenance_text = provenance ? " provenance=#{provenance.fetch("kind")}" : ""
+        aliases = Array(method["aliases"])
+        alias_text = aliases.empty? ? "" : " aliases=#{aliases.join(",")}"
+        super_text = method["super_owner"] ? " super=#{method["super_owner"]}" : ""
+        @out.puts "  ##{name} [#{method.fetch("visibility")}] owner=#{method.fetch("owner")} source=#{source}#{provenance_text}#{alias_text}#{super_text}"
       end
       0
     end
@@ -137,7 +146,7 @@ module MonkeyLens
     end
 
     def common_options
-      {config: ".monkeylens.yml", requires: []}
+      {config: ".monkeylens.yml", requires: [], provenance: false}
     end
 
     def parser_for(command, options)

data/lib/monkey_lens/diff.rb

@@ -101,8 +101,8 @@ module MonkeyLens
       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")
+      if before.fetch("source_location", nil) != after.fetch("source_location", nil)
+        changes << change("source_changed", "high", target, method_id:, before: before.fetch("source_location", nil), after: after.fetch("source_location", nil), 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")
@@ -110,6 +110,12 @@ module MonkeyLens
       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
+      if before.fetch("aliases", []) != after.fetch("aliases", [])
+        changes << change("alias_changed", "medium", target, method_id:, before: before.fetch("aliases", []), after: after.fetch("aliases", []), message: "method aliases changed")
+      end
+      if before.fetch("super_owner", nil) != after.fetch("super_owner", nil)
+        changes << change("super_owner_changed", "high", target, method_id:, before: before.fetch("super_owner", nil), after: after.fetch("super_owner", nil), message: "super-method owner changed")
+      end
     end
 
     def signature(method)

data/lib/monkey_lens/policy.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "date"
+require "yaml"
+
+module MonkeyLens
+  class Policy
+    class Waiver
+      attr_reader :type, :target, :method_pattern, :reason, :expires_on
+
+      def initialize(type: "*", target: "*", method: "*", reason:, expires_on: nil)
+        raise ConfigurationError, "waiver reason is required" if reason.to_s.strip.empty?
+
+        @type = type.to_s
+        @target = target.to_s
+        @method_pattern = method.to_s
+        @reason = reason.to_s
+        @expires_on = expires_on && Date.iso8601(expires_on.to_s)
+      rescue Date::Error
+        raise ConfigurationError, "invalid waiver expiration #{expires_on.inspect}"
+      end
+
+      def match?(change, today: Date.today)
+        return false if expired?(today:)
+
+        matches?(type, change.type) &&
+          matches?(target, change.target) &&
+          matches?(method_pattern, change.method_id.to_s)
+      end
+
+      def expired?(today: Date.today)
+        expires_on && expires_on < today
+      end
+
+      def to_h
+        {
+          "type" => type,
+          "target" => target,
+          "method" => method_pattern,
+          "reason" => reason,
+          "expires_on" => expires_on&.iso8601
+        }.compact
+      end
+
+      private
+
+      def matches?(pattern, value)
+        File.fnmatch?(pattern, value.to_s, File::FNM_EXTGLOB)
+      end
+    end
+
+    class Decision
+      attr_reader :result, :effective_changes, :waived_changes, :threshold
+
+      def initialize(result:, effective_changes:, waived_changes:, threshold:)
+        @result = result
+        @effective_changes = effective_changes.freeze
+        @waived_changes = waived_changes.freeze
+        @threshold = threshold.to_s
+      end
+
+      def clean?
+        effective_changes.empty?
+      end
+
+      def failure?
+        minimum = Change::LEVELS.fetch(threshold)
+        effective_changes.any? { |change| change.level >= minimum }
+      end
+
+      def to_h
+        {
+          "schema" => 1,
+          "clean" => clean?,
+          "failure" => failure?,
+          "threshold" => threshold,
+          "summary" => Change::LEVELS.keys.to_h do |level|
+            [level, effective_changes.count { |change| change.severity == level }]
+          end,
+          "effective_changes" => effective_changes.map(&:to_h),
+          "waived_changes" => waived_changes.map do |item|
+            {"change" => item.fetch(:change).to_h, "waiver" => item.fetch(:waiver).to_h}
+          end
+        }
+      end
+    end
+
+    attr_reader :waivers
+
+    def self.load(path)
+      data = YAML.safe_load_file(path, permitted_classes: [Date], aliases: false) || {}
+      from_hash(data)
+    rescue Psych::Exception => error
+      raise ConfigurationError, "invalid policy file #{path}: #{error.message}"
+    end
+
+    def self.from_hash(data)
+      values = data["waivers"] || data[:waivers] || []
+      new(waivers: values)
+    end
+
+    def initialize(waivers: [])
+      @waivers = waivers.map do |waiver|
+        waiver.is_a?(Waiver) ? waiver : Waiver.new(**symbolize(waiver))
+      end.freeze
+    end
+
+    def evaluate(result, threshold: "high", today: Date.today)
+      Change::LEVELS.fetch(threshold.to_s)
+      effective = []
+      waived = []
+      result.changes.each do |change|
+        waiver = waivers.find { |candidate| candidate.match?(change, today:) }
+        waiver ? waived << {change:, waiver:} : effective << change
+      end
+      Decision.new(result:, effective_changes: effective, waived_changes: waived, threshold:)
+    end
+
+    private
+
+    def symbolize(value)
+      value.to_h.each_with_object({}) { |(key, item), result| result[key.to_sym] = item }
+    end
+  end
+end

data/lib/monkey_lens/provenance.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module MonkeyLens
+  class Provenance
+    KINDS = %w[gem app stdlib eval unknown].freeze
+
+    attr_reader :kind, :gem, :path, :line
+
+    def initialize(kind:, gem: nil, path: nil, line: nil)
+      @kind = kind.to_s
+      @gem = gem
+      @path = path
+      @line = line
+    end
+
+    def self.for_source_location(location)
+      return nil unless location
+
+      path, line = location
+      path = path.to_s
+      line = Integer(line)
+      kind, gem_name = classify(path)
+      new(kind:, gem: gem_name, path: normalize_path(path), line:)
+    end
+
+    def self.classify(path)
+      return ["eval", nil] if eval_path?(path)
+
+      expanded = File.expand_path(path)
+      gem_info = gem_for_path(expanded)
+      return ["gem", gem_info] if gem_info
+
+      if stdlib_path?(expanded)
+        ["stdlib", nil]
+      elsif app_path?(expanded)
+        ["app", nil]
+      else
+        ["unknown", nil]
+      end
+    end
+
+    def self.eval_path?(path)
+      path.start_with?("(eval") || path == "eval"
+    end
+
+    def self.gem_for_path(path)
+      Gem.loaded_specs.each_value do |spec|
+        spec.full_require_paths.each do |require_path|
+          expanded = File.expand_path(require_path)
+          next unless path.start_with?("#{expanded}/") || path == expanded
+
+          return spec.name
+        end
+      end
+      nil
+    end
+
+    def self.stdlib_path?(path)
+      ruby_root = RbConfig::CONFIG["rubylibdir"]
+      return path.start_with?(ruby_root) if ruby_root
+
+      path.include?("/ruby/") && path.include?("/lib/")
+    end
+
+    def self.app_path?(path)
+      cwd = File.expand_path(Dir.pwd)
+      path.start_with?("#{cwd}/") || path == cwd
+    end
+
+    def self.normalize_path(path)
+      absolute = File.expand_path(path)
+      cwd = File.expand_path(Dir.pwd)
+      absolute.start_with?("#{cwd}/") ? absolute.delete_prefix("#{cwd}/") : absolute
+    end
+
+    def to_h
+      {
+        "kind" => kind,
+        "gem" => gem,
+        "path" => path,
+        "line" => line
+      }.compact
+    end
+  end
+end

data/lib/monkey_lens/version.rb

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

data/lib/monkey_lens.rb

@@ -5,6 +5,7 @@ require_relative "monkey_lens/config"
 require_relative "monkey_lens/snapshot"
 require_relative "monkey_lens/change"
 require_relative "monkey_lens/capture"
+require_relative "monkey_lens/provenance"
 require_relative "monkey_lens/diff"
 require_relative "monkey_lens/formatter"
 
@@ -15,13 +16,18 @@ module MonkeyLens
 
   module_function
 
-  def capture(targets:, ignore_methods: [])
-    Capture.new(targets:, ignore_methods:).call
+  def capture(targets:, ignore_methods: [], provenance: false)
+    Capture.new(targets:, ignore_methods:, provenance:).call
   end
 
   def diff(baseline, current)
     Diff.new(baseline:, current:).call
   end
+
+  def evaluate(result, policy:, threshold: "high", today: Date.today)
+    policy.evaluate(result, threshold:, today:)
+  end
 end
 
+require_relative "monkey_lens/policy"
 require_relative "monkey_lens/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monkey_lens
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Matthew Looney
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -63,6 +63,8 @@ files:
 - lib/monkey_lens/formatter/json.rb
 - lib/monkey_lens/formatter/sarif.rb
 - lib/monkey_lens/formatter/text.rb
+- lib/monkey_lens/policy.rb
+- lib/monkey_lens/provenance.rb
 - lib/monkey_lens/railtie.rb
 - lib/monkey_lens/rake_task.rb
 - lib/monkey_lens/snapshot.rb