rigortype 0.2.0 → 0.2.1

data/lib/rigor/cli/fused_protection_renderer.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rigor
+  class CLI
+    # Renders a {FusedProtectionReport} (ADR-70) as text or JSON. The text form
+    # leads with the fused protected ratio (caught by *either* a type or a test),
+    # splits it into the two axes, then lists the unprotected breakages ("add a
+    # type or a test here") and the least-protected files. The framing is always
+    # *where to add protection*, never "your code is broken".
+    class FusedProtectionRenderer
+      TOP_CALLS = 15
+      TOP_FILES = 10
+
+      def initialize(out:)
+        @out = out
+      end
+
+      def render(report, format:)
+        format == "json" ? render_json(report) : render_text(report)
+      end
+
+      private
+
+      def render_json(report)
+        @out.puts(JSON.pretty_generate(report.to_h))
+      end
+
+      def render_text(report)
+        pct = (report.ratio * 100).round(1)
+        @out.puts "Fused protection (static type ∪ dynamic test)"
+        @out.puts "  protected: #{report.protected_total} / #{report.grand_total}  (#{pct}%)"
+        @out.puts "    by type:  #{report.total_type_killed}"
+        @out.puts "    by test:  #{report.total_test_killed}  (type-survivors a test caught)"
+        @out.puts "  unprotected: #{report.total_unprotected}  (neither — add a type or a test)"
+        render_unprotected(report)
+        render_files(report)
+      end
+
+      def render_unprotected(report)
+        unprotected = report.unprotected
+        return if unprotected.empty?
+
+        @out.puts "\nAdd protection here — breakages neither a type nor a test caught:"
+        unprotected.first(TOP_CALLS).each do |call|
+          @out.puts format("  %<count>-5d #%<method>s   e.g. %<sites>s",
+                           count: call.count, method: call.method_name, sites: call.examples.join("  "))
+        end
+        @out.puts "  (#{unprotected.size - TOP_CALLS} more)" if unprotected.size > TOP_CALLS
+      end
+
+      def render_files(report)
+        worst = report.files.reject { |f| f.unprotected.zero? }.sort_by(&:ratio).first(TOP_FILES)
+        return if worst.empty?
+
+        @out.puts "\nLeast-protected files:"
+        worst.each do |file|
+          total = file.type_killed + file.test_killed + file.unprotected
+          protected_n = file.type_killed + file.test_killed
+          @out.puts format("  %<pct>5.1f%%  %<path>s  (%<n>d/%<total>d protected)",
+                           pct: file.ratio * 100, path: file.path, n: protected_n, total: total)
+        end
+      end
+    end
+  end
+end

data/lib/rigor/cli/fused_protection_report.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Rigor
+  class CLI
+    # ADR-70 — aggregates per-file {Protection::MutationScanner::FusedFileResult}
+    # into a project-level **fused** protection report: how many type-visible
+    # breakages were caught by the type checker, how many of the *type-survivors*
+    # were caught by the test suite, and which sites neither axis caught — the
+    # ranked "add a type OR a test here" list.
+    #
+    # Framing (ADR-63 / ADR-62 Criterion A, extended): the payload is the
+    # **attribution** — which protection axis is missing — never raw survival.
+    # An unprotected site is "add protection here", never "your code is broken".
+    FusedFileProtection = Data.define(:path, :type_killed, :test_killed, :unprotected, :ratio)
+    UnprotectedBreakage = Data.define(:method_name, :count, :examples)
+
+    FusedProtectionReport = Data.define(:files, :unprotected, :parse_errors) do
+      def total_type_killed = files.sum(&:type_killed)
+      def total_test_killed = files.sum(&:test_killed)
+      def total_unprotected = files.sum(&:unprotected)
+      def grand_total = total_type_killed + total_test_killed + total_unprotected
+      def protected_total = total_type_killed + total_test_killed
+      def ratio = grand_total.zero? ? 1.0 : protected_total.to_f / grand_total
+
+      def to_h
+        {
+          "mode" => "protection-fused",
+          "type_killed" => total_type_killed,
+          "test_killed" => total_test_killed,
+          "unprotected" => total_unprotected,
+          "protected_ratio" => ratio.round(4),
+          "files" => files.map do |f|
+            { "path" => f.path, "type_killed" => f.type_killed, "test_killed" => f.test_killed,
+              "unprotected" => f.unprotected, "ratio" => f.ratio.round(4) }
+          end,
+          "add_protection_here" => unprotected.map do |m|
+            { "method" => m.method_name, "count" => m.count, "examples" => m.examples }
+          end,
+          "parse_errors" => parse_errors
+        }
+      end
+    end
+
+    class FusedProtectionAccumulator
+      def initialize
+        @files = []
+        @unprotected = Hash.new { |h, k| h[k] = { count: 0, examples: [] } }
+        @parse_errors = []
+      end
+
+      def absorb(file_result)
+        @files << FusedFileProtection.new(
+          path: file_result.path, type_killed: file_result.type_killed,
+          test_killed: file_result.test_killed, unprotected: file_result.unprotected,
+          ratio: file_result.ratio
+        )
+        file_result.sites.each do |site|
+          bucket = @unprotected[site.method_name]
+          bucket[:count] += 1
+          bucket[:examples] << "#{file_result.path}:#{site.line}" if bucket[:examples].size < 3
+        end
+      end
+
+      def record_parse_error(path, errors)
+        @parse_errors << { "path" => path, "errors" => errors.size }
+      end
+
+      def to_report
+        unprotected = @unprotected
+                      .map { |m, v| UnprotectedBreakage.new(method_name: m, count: v[:count], examples: v[:examples]) }
+                      .sort_by { |m| [-m.count, m.method_name] }
+        FusedProtectionReport.new(files: @files, unprotected: unprotected, parse_errors: @parse_errors)
+      end
+    end
+  end
+end

data/lib/rigor/config_audit.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require_relative "signature_path_audit"
+require_relative "analysis/check_rules"
+
+module Rigor
+  # Audits a loaded {Configuration} for the class of mistake where a
+  # configured value silently resolves to nothing — a typo'd or moved
+  # path, an unknown library name, an inert rule id. The shared failure
+  # mode is that the loader filters the bad entry without a word, so the
+  # only symptom is downstream and confusing: missing signatures turn
+  # every call into the types they were meant to cover into a
+  # high-confidence `call.undefined-method`, and an unrecognised
+  # suppression token leaves the rule firing as if the `disable:` line
+  # were never written. This module surfaces each such entry up front so
+  # the cause is visible instead of inferred.
+  #
+  # Every check is held to the same bar that {SignaturePathAudit} set:
+  # it mirrors the loader's own acceptance test, so a warning means the
+  # loader really did load nothing, and it never fires on a setup that
+  # works. In particular the rule-token check only flags a token under a
+  # built-in family (`call`, `flow`, …) — a plugin- or `rbs_extended.*`
+  # rule id (whose family Rigor cannot statically enumerate, since a
+  # `node_rule` block emits any `rule:` string it likes) is left alone, so
+  # disabling a plugin rule is never mistaken for a typo.
+  module ConfigAudit
+    # One config-level finding. `kind` discriminates the source key
+    # (`:signature_path`, `:library`, `:disabled_rule`,
+    # `:severity_override`, `:bundler_bundle_path`, `:bundler_lockfile`,
+    # `:rbs_collection_lockfile`); `fields` carries the kind-specific
+    # structured data merged into {#to_h} for JSON consumers.
+    Warning = Data.define(:kind, :message, :fields) do
+      def to_h
+        { "kind" => kind.to_s, "message" => message }.merge(fields)
+      end
+    end
+
+    # @param configuration [Rigor::Configuration]
+    # @param project_root [String] the directory the run's relative
+    #   bundler / collection paths resolve against (the CLI's CWD), used
+    #   only by the explicit-path checks.
+    # @return [Array<Warning>]
+    def self.warnings(configuration, project_root: Dir.pwd)
+      signature_path_warnings(configuration) +
+        library_warnings(configuration) +
+        rule_token_warnings(configuration) +
+        explicit_path_warnings(configuration, project_root)
+    end
+
+    # `signature_paths:` entries that resolve to nothing — delegated to
+    # {SignaturePathAudit}, which mirrors the loader's `directory?` +
+    # recursive `**/*.rbs` acceptance test.
+    def self.signature_path_warnings(configuration)
+      SignaturePathAudit.warnings(configuration.signature_paths).map do |entry|
+        Warning.new(
+          kind: :signature_path,
+          message: entry.message,
+          fields: { "path" => entry.path, "status" => entry.status.to_s, "rbs_file_count" => entry.rbs_file_count }
+        )
+      end
+    end
+
+    # `libraries:` entries RBS does not recognise. Uses the same
+    # `RBS::EnvironmentLoader#has_library?` guard the loader filters
+    # through ({Environment::RbsLoader} `build_env_for`), so a flagged
+    # name is exactly one the loader skipped. Fails soft: if RBS itself
+    # raises, no warning rather than a crash.
+    def self.library_warnings(configuration)
+      configured = Array(configuration.libraries)
+      return [] if configured.empty?
+
+      loader = ::RBS::EnvironmentLoader.new
+      configured.reject { |lib| loader.has_library?(library: lib.to_s, version: nil) }.map do |lib|
+        Warning.new(
+          kind: :library,
+          message: "libraries: #{lib.to_s.inspect} is not an available RBS library (no signatures loaded from it)",
+          fields: { "name" => lib.to_s }
+        )
+      end
+    rescue StandardError
+      []
+    end
+
+    # `disable:` tokens and `severity_overrides:` keys that name no rule.
+    # Restricted to tokens under a built-in family so a plugin rule id is
+    # never mis-flagged (see the module docstring).
+    def self.rule_token_warnings(configuration)
+      disable = Array(configuration.disabled_rules).filter_map do |token|
+        next unless inert_builtin_token?(token.to_s)
+
+        Warning.new(
+          kind: :disabled_rule,
+          message: "disable: #{token.to_s.inspect} is not a recognized rule id; the suppression has no effect",
+          fields: { "token" => token.to_s }
+        )
+      end
+      overrides = configuration.severity_overrides.keys.filter_map do |key|
+        next unless inert_builtin_token?(key.to_s)
+
+        Warning.new(
+          kind: :severity_override,
+          message: "severity_overrides: #{key.to_s.inspect} is not a recognized rule id; the override has no effect",
+          fields: { "token" => key.to_s }
+        )
+      end
+      disable + overrides
+    end
+
+    # True when `token` looks like a built-in rule id but matches none —
+    # its first segment is a built-in family yet it is neither a bare
+    # family wildcard nor a known canonical id. A token whose family is
+    # not built-in (a plugin / `rbs_extended.*` rule, or a bare legacy
+    # alias) is deliberately NOT flagged: it may resolve at run time, so
+    # under-warning is the FP-safe choice.
+    def self.inert_builtin_token?(token)
+      family = token.split(".").first
+      return false unless Analysis::CheckRules::RULE_FAMILIES.include?(family)
+      return false if token == family
+      return false if Analysis::CheckRules::ALL_RULES.include?(token)
+
+      true
+    end
+
+    # Explicitly-configured bundler / rbs-collection paths that do not
+    # exist. Only the explicit form is audited (a nil value means
+    # auto-detection, which finding nothing is normal); messages stay
+    # factual about the path rather than guessing the fallback.
+    def self.explicit_path_warnings(configuration, project_root)
+      warnings = []
+      add_missing_dir(warnings, configuration.bundler_bundle_path, project_root,
+                      :bundler_bundle_path, "bundler.bundle_path")
+      add_missing_file(warnings, configuration.bundler_lockfile, project_root,
+                       :bundler_lockfile, "bundler.lockfile")
+      add_missing_file(warnings, configuration.rbs_collection_lockfile, project_root,
+                       :rbs_collection_lockfile, "rbs_collection.lockfile")
+      warnings
+    end
+
+    def self.add_missing_dir(warnings, path, project_root, kind, key)
+      return if path.nil? || File.directory?(File.expand_path(path, project_root))
+
+      warnings << Warning.new(kind: kind, message: "#{key}: #{path.inspect} is not a directory",
+                              fields: { "path" => path })
+    end
+
+    def self.add_missing_file(warnings, path, project_root, kind, key)
+      return if path.nil? || File.file?(File.expand_path(path, project_root))
+
+      warnings << Warning.new(kind: kind, message: "#{key}: #{path.inspect} does not exist", fields: { "path" => path })
+    end
+  end
+end

data/lib/rigor/configuration.rb

@@ -600,6 +600,18 @@ module Rigor
       raise ArgumentError, "severity_overrides must be a Hash, got #{value.inspect}" unless value.is_a?(Hash)
 
       value.to_h do |k, v|
+        # YAML 1.1 parses bare `off`/`on`/`no`/`yes`/`true`/`false`
+        # as booleans, so a user who wrote `off` (a valid severity)
+        # without quotes hands us `false`. Catch the non-Symbol /
+        # non-String case before `to_sym` blows up with a backtrace.
+        unless v.is_a?(String) || v.is_a?(Symbol)
+          hint = v == false ? %( — did you mean the string "off"?) : ""
+          raise ArgumentError,
+                "severity_overrides[#{k.inspect}] is #{v.inspect}, a YAML boolean#{hint} " \
+                "Bare off/on/no/yes/true/false are parsed as booleans; quote the severity " \
+                "(e.g. \"off\")."
+        end
+
         sym = v.to_sym
         unless SeverityProfile::VALID_SEVERITIES.include?(sym)
           raise ArgumentError,

data/lib/rigor/environment/rbs_loader.rb

@@ -323,6 +323,33 @@ module Rigor
           [Pathname(CORE_OVERLAY_SIGS_ROOT)]
         end
 
+        # Rigor-owned per-gem RBS overlays (`data/gem_overlay/<gem>/`),
+        # ADR-72. Unlike the unconditional `core_overlay`, each gem's
+        # overlay is loaded ONLY when that gem is locked in the
+        # project's Gemfile.lock but ships no RBS of its own —
+        # {Environment.for_project} decides eligibility and passes the
+        # already-filtered gem-name set here. One directory per gem name
+        # keeps the membership check a cheap `File.directory?`.
+        GEM_OVERLAY_SIGS_ROOT = File.expand_path(
+          "../../../data/gem_overlay",
+          __dir__
+        ).freeze
+
+        # @param gem_names [Enumerable<String>] overlay-eligible
+        #   Gemfile.lock gem names (the caller filters to the
+        #   `:missing`-coverage, no-conflicting-plugin set).
+        # @return [Array<Pathname>] the bundled overlay directory for
+        #   each gem that ships one; empty when none match or the
+        #   overlay root is absent.
+        def gem_overlay_sig_paths(gem_names)
+          return [] unless File.directory?(GEM_OVERLAY_SIGS_ROOT)
+
+          gem_names.filter_map do |name|
+            dir = File.join(GEM_OVERLAY_SIGS_ROOT, name.to_s)
+            Pathname(dir) if File.directory?(dir)
+          end
+        end
+
         def vendored_gem_sig_paths
           return [] unless File.directory?(VENDORED_GEM_SIGS_ROOT)
 

data/lib/rigor/environment.rb

@@ -65,6 +65,13 @@ module Rigor
       prism rbs
     ].freeze
 
+    # ADR-72 — a Gemfile.lock gem name mapped to the opt-in plugin id
+    # that ships the SAME core-ext RBS. When that plugin is loaded the
+    # auto-overlay for the gem stands down, so the two never both
+    # declare the methods (which would raise a duplicate-declaration
+    # error). Keyed on the gem name `RbsCoverageReport` reports.
+    GEM_OVERLAY_PLUGIN_IDS = { "activesupport" => "activesupport-core-ext" }.freeze
+
     attr_reader :class_registry, :rbs_loader, :plugin_registry, :dependency_source_index,
                 :reporters, :name_scope,
                 :synthetic_method_index, :project_patched_methods
@@ -291,7 +298,24 @@ module Rigor
         # collection discovery. A duplicate-declaration conflict
         # degrades through the same O7 failure-memo path.
         plugin_sig_paths = plugin_registry ? plugin_registry.signature_paths.map(&:to_s) : []
-        loader_signature_paths = resolved_paths + plugin_sig_paths + gem_sig_paths + collection_paths
+        # ADR-72 — Gemfile.lock-gated bundled RBS overlays. For each
+        # locked gem that ships no RBS through any resolution path
+        # (`:missing`) and has a Rigor-bundled overlay, load that
+        # overlay so its core-class extensions resolve (e.g.
+        # `Integer#minutes` on a Rails project) — turning a systematic
+        # false `call.undefined-method` into a no-op while a project
+        # WITHOUT the gem still sees the genuine diagnostic. Appended
+        # last so any RBS the project already supplies wins, and skipped
+        # for a gem whose opt-in plugin twin is loaded (no duplicate
+        # declaration). The paths ride in `loader_signature_paths`, so
+        # the env cache descriptor digests them for free.
+        overlay_paths = gem_overlay_paths(
+          locked: locked, default_libraries: merged_libraries,
+          bundle_sig_paths: gem_sig_paths, rbs_collection_paths: collection_paths,
+          plugin_registry: plugin_registry
+        )
+        loader_signature_paths = resolved_paths + plugin_sig_paths + gem_sig_paths +
+                                 collection_paths + overlay_paths
         # ADR-32 WD4 + WD5 — invoke each loaded plugin's
         # `source_rbs_synthesizer` once per project source file
         # and collect non-nil `[filename, rbs_source]` pairs.
@@ -346,6 +370,30 @@ module Rigor
         sig.directory? ? [sig] : []
       end
 
+      # ADR-72 — resolve the bundled RBS overlay directories to load for
+      # this project. A gem is eligible when it is locked in the
+      # Gemfile.lock, classified `:missing` by {RbsCoverageReport}
+      # (no RBS through default-library / vendored / bundle-`sig/` /
+      # rbs-collection), and its conflicting opt-in plugin (if any) is
+      # not loaded. Returns `[Pathname]`, deterministically ordered, or
+      # `[]` when no lockfile / no eligible gem.
+      def gem_overlay_paths(locked:, default_libraries:, bundle_sig_paths:,
+                            rbs_collection_paths:, plugin_registry:)
+        return [] if locked.empty?
+
+        missing = RbsCoverageReport.classify(
+          locked_gems: locked, default_libraries: default_libraries,
+          bundle_sig_paths: bundle_sig_paths, rbs_collection_paths: rbs_collection_paths
+        ).select { |row| row.source == :missing }.map(&:gem_name)
+
+        loaded_ids = plugin_registry ? plugin_registry.ids.to_set : Set.new
+        eligible = missing.reject do |gem_name|
+          plugin_id = GEM_OVERLAY_PLUGIN_IDS[gem_name]
+          plugin_id && loaded_ids.include?(plugin_id)
+        end.sort
+        RbsLoader.gem_overlay_sig_paths(eligible)
+      end
+
       # ADR-32 WD4 + WD5 — for each project source file, invoke
       # every plugin-registered synthesizer once and collect
       # non-nil returns. The returned array is `[[virtual_filename,

data/lib/rigor/inference/method_dispatcher/constant_folding.rb

@@ -114,14 +114,19 @@ module Rigor
         # siblings `:inspect` / `:to_s` remain folded.
         INTEGER_UNARY = Set[
           :odd?, :even?, :zero?, :positive?, :negative?,
+          # `finite?` / `infinite?` are total on Integer (`true` / `nil`
+          # always) and round out the numeric predicate family — the Float
+          # sibling already folds them. `nonzero?` returns `self` (non-zero)
+          # or `nil`, both foldable Constants.
+          :finite?, :infinite?, :nonzero?,
           :succ, :pred, :next, :abs, :magnitude,
           :bit_length, :to_s, :to_i, :to_int, :to_f,
           :floor, :ceil, :round, :truncate, :chr,
           :inspect, :-@, :+@, :~, :to_r, :to_c
         ].freeze
         FLOAT_UNARY = Set[
-          :zero?, :positive?, :negative?,
-          :nan?, :finite?, :infinite?,
+          :zero?, :positive?, :negative?, :nonzero?,
+          :nan?, :finite?, :infinite?, :integer?,
           :abs, :magnitude, :floor, :ceil, :round, :truncate,
           :next_float, :prev_float,
           :to_s, :to_i, :to_int, :to_f, :to_r, :rationalize,
@@ -138,7 +143,11 @@ module Rigor
         SYMBOL_UNARY = Set[
           :to_s, :to_sym, :to_proc, :length, :size,
           :empty?, :upcase, :downcase, :capitalize,
-          :swapcase, :succ, :next, :inspect
+          :swapcase, :succ, :next, :inspect,
+          # `name` (the frozen-string accessor), `id2name` (alias of
+          # `to_s`), and `intern` (alias of `to_sym`) are pure reads of the
+          # symbol's text — siblings of the already-folded `to_s` / `to_sym`.
+          :name, :id2name, :intern
         ].freeze
         BOOL_UNARY = Set[:!, :to_s, :inspect, :&, :|, :^].freeze
         NIL_UNARY  = Set[:nil?, :!, :to_s, :to_a, :to_h, :inspect].freeze
@@ -542,14 +551,15 @@ module Rigor
           build_constant_type(results, source: receiver_values + arg_values)
         end
         # v0.0.7 — `Constant<String>#chars` / `bytes` / `codepoints` /
-        # `lines` / `split` (no-arg) return a Ruby Array of foldable
-        # scalars; `foldable_constant_value?` rejects Array
+        # `grapheme_clusters` / `lines` / `split` (no-arg) return a Ruby
+        # Array of foldable scalars; `foldable_constant_value?` rejects Array
         # results, so the standard unary path declines. Lift the
         # Array to a per-position `Tuple[Constant…]` directly,
         # capped at `STRING_ARRAY_LIFT_LIMIT` to keep the result
         # bounded for long strings. (`codepoints` yields per-character
-        # Integer codepoints, the sibling of the byte-valued `bytes`.)
-        STRING_ARRAY_UNARY_METHODS = Set[:chars, :bytes, :codepoints, :lines, :split].freeze
+        # Integer codepoints, the sibling of the byte-valued `bytes`;
+        # `grapheme_clusters` is the extended-grapheme sibling of `chars`.)
+        STRING_ARRAY_UNARY_METHODS = Set[:chars, :bytes, :codepoints, :grapheme_clusters, :lines, :split].freeze
         # `partition` / `rpartition` always return a fixed 3-element
         # `[head, separator, tail]` Array whose members are substrings of
         # the receiver (bounded by the input), so they lift to a precise

data/lib/rigor/inference/statement_evaluator.rb

@@ -2274,6 +2274,11 @@ module Rigor
         body = block_node.body
         return post_scope if body.nil?
 
+        # Transitive case first: the body may content-mutate a captured local
+        # through a self-call rather than a direct `local[k] = v` write, which
+        # `collect_content_mutations` cannot see (see below).
+        post_scope = floor_block_body_callee_escaped_args(body, post_scope)
+
         mutations = collect_content_mutations(body)
         return post_scope if mutations.empty?
 
@@ -2283,6 +2288,28 @@ module Rigor
         end
       end
 
+      # Inside an ESCAPING block body, a captured outer local can be content-
+      # mutated transitively: the body is (or contains) a self-call that
+      # escape-mutates one of its arguments. The canonical shape is the CLI's
+      # own `OptionParser.new { |opts| define_options(opts, options) }` — the
+      # block body is a bare `define_options(opts, options)` whose `options`
+      # parameter is escape-mutated inside ITS nested `opts.on { options[:k] =
+      # v }` blocks. `collect_content_mutations` only sees direct `local[k] =
+      # v` writes in THIS body, so it misses the transitive write and the
+      # captured Hash keeps its literal-false seed (folding the caller's
+      # `options[:mutation]` guard to an always-falsey constant). Reuse the
+      # cross-method-boundary callee-escaped-argument floor (the same gate the
+      # receiver-chain path uses at the call site) on every self-call in the
+      # body. Sound — only ever floors a captured local passed as an argument
+      # to a callee that demonstrably escape-mutates the matching parameter.
+      def floor_block_body_callee_escaped_args(body, post_scope)
+        acc = post_scope
+        Source::NodeWalker.each(body) do |descendant|
+          acc = floor_callee_escaped_args_for_call(descendant, acc) if descendant.is_a?(Prism::CallNode)
+        end
+        acc
+      end
+
       # The Dynamic-floor carrier for a content-mutated escaping capture, or
       # nil when the pre-state is not a recognised mutable collection (leave
       # it alone — e.g. an already-`Dynamic` binding or an unknown shape).

data/lib/rigor/protection/diagnostic_oracle.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../analysis/runner"
+
+module Rigor
+  module Protection
+    # ADR-69 Seam 1 — the **kill oracle** Rigor's analyzer-teeth measurement uses:
+    # a mutant is killed iff re-analysing it introduces a diagnostic absent from
+    # the clean baseline. This is exactly the behaviour ADR-62/63 shipped, lifted
+    # out of {MutationScanner} so a {TestSuiteOracle} (ADR-70) — which kills by
+    # *running tests* rather than by re-analysis — can sit beside it without the
+    # scanner baking in either assumption.
+    #
+    # The expensive builds (RBS environment + the whole-project pre-pass scan) are
+    # paid once by the caller and threaded in; each mutant reuses them through
+    # `Runner.new(prebuilt:)#run_source` (in-memory overlay, no disk write).
+    # Passing `prebuilt:` disables the run-result cache (whose key digests the
+    # *disk* file), so a mutant is never served a stale clean hit.
+    class DiagnosticOracle
+      def initialize(configuration:, environment:, project_scan:)
+        @configuration = configuration
+        @environment = environment
+        @project_scan = project_scan
+      end
+
+      # The clean per-file baseline: the diagnostic signatures a mutant must add
+      # to count as killed. Computed once per file by the caller.
+      def baseline(source:, path:)
+        analyse(source, path).to_set { |d| sig(d) }
+      end
+
+      # Killed iff the mutant introduces a diagnostic not in `baseline`.
+      def killed?(mutant_source:, path:, baseline:)
+        analyse(mutant_source, path).any? { |d| !baseline.include?(sig(d)) }
+      end
+
+      private
+
+      def analyse(source, path)
+        Rigor::Analysis::Runner.new(
+          configuration: @configuration, environment: @environment, prebuilt: @project_scan,
+          cache_store: nil, collect_stats: false
+        ).run_source(source: source, path: path).diagnostics
+      end
+
+      def sig(diagnostic)
+        [diagnostic.rule, diagnostic.path, diagnostic.line, diagnostic.column, diagnostic.message]
+      end
+    end
+  end
+end