monkey_lens 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1f86a074dcc3f3a8e7294549267b5a45db15a4e421a155adaf2b4ac6c562853
-  data.tar.gz: 8260182a2b09f07a983d6a5ba481dc1849a1f1ade79afd94710df7d85a76fced
+  metadata.gz: 9c3c706d59eb29d1ad4de38b99d3e5539891aa630fac314d39dc16fa3b3fbdbd
+  data.tar.gz: 60e610c3c01434eadb5edc1e4dc2dfe699f48d914c685bd0b1659cff1649f0f5
 SHA512:
-  metadata.gz: 526967dd0425e75440c63878be6e34a28deab3d777d022337a340b527855defb439438c1bf5a47057f888734ba515b10fc4ed0f66fd63d281cb09c17bea5a98d
-  data.tar.gz: a9dacd19531ff3934fe76b8a96192e3b2e5a38f911531ea8d535acd25d68a4d1d53231b5fdea1e5913439e64eb1c740304ececf2f26609f95e7b87c888120713
+  metadata.gz: 5908c484375db223128fadb7cf724de9f79d0a14c8e713a886962a965ae00882b73762d05a4f360fd3761464811f749fcbadcb6dff2644ca1f9c6a17f17d080e
+  data.tar.gz: 7f64d16a2bc0035ed66caca551786d53495b1bed098cbfd6cad47f7532cb177ac73feec73e83e3c4108ec24c3545c14588fd1822c10d85fc88af5693a05f7d6e

data/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to MonkeyLens are documented here.
 
+## 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

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
@@ -60,8 +61,9 @@ module MonkeyLens
           "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)
+        }.compact]
       rescue NameError
         nil
       end.to_h
@@ -83,5 +85,11 @@ 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
   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,23 @@ 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")}" : ""
+        @out.puts "  ##{name} [#{method.fetch("visibility")}] owner=#{method.fetch("owner")} source=#{source}#{provenance_text}"
       end
       0
     end
@@ -137,7 +143,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")

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.3.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.3.0
 platform: ruby
 authors:
 - Matthew Looney
@@ -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