rigortype 0.1.14 → 0.1.15

data/lib/rigor/analysis/runner.rb

@@ -109,8 +109,10 @@ module Rigor
         @cached_plugin_prepare_diagnostics = [].freeze
         @project_discovered_classes = {}.freeze
         @project_discovered_def_nodes = {}.freeze
+        @project_discovered_def_sources = {}.freeze
         @project_discovered_superclasses = {}.freeze
         @project_discovered_includes = {}.freeze
+        @project_discovered_method_visibilities = {}.freeze
       end
 
       # ADR-pending editor mode — present when the runner is wired
@@ -257,8 +259,10 @@ module Rigor
         def_index =
           Inference::ScopeIndexer.discovered_def_index_for_paths(expansion.fetch(:files), buffer: @buffer)
         @project_discovered_def_nodes = def_index.fetch(:def_nodes)
+        @project_discovered_def_sources = def_index.fetch(:def_sources)
         @project_discovered_superclasses = def_index.fetch(:superclasses)
         @project_discovered_includes = def_index.fetch(:includes)
+        @project_discovered_method_visibilities = def_index.fetch(:method_visibilities)
       end
 
       # Internal: adopts a frozen {ProjectScan} snapshot supplied
@@ -1449,10 +1453,16 @@ module Rigor
         unless @project_discovered_def_nodes.empty?
           scope = scope.with_discovered_def_nodes(@project_discovered_def_nodes)
         end
+        unless @project_discovered_def_sources.empty?
+          scope = scope.with_discovered_def_sources(@project_discovered_def_sources)
+        end
         unless @project_discovered_superclasses.empty?
           scope = scope.with_discovered_superclasses(@project_discovered_superclasses)
         end
         scope = scope.with_discovered_includes(@project_discovered_includes) unless @project_discovered_includes.empty?
+        unless @project_discovered_method_visibilities.empty?
+          scope = scope.with_discovered_method_visibilities(@project_discovered_method_visibilities)
+        end
         scope
       end
 

data/lib/rigor/cli/plugin_command.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module Rigor
+  class CLI
+    # `rigor plugin` (singular) — discover and read the plugin source
+    # bundled with the `rigortype` gem.
+    #
+    # Rigor ships ~30 production plugins under `plugins/` and a set of
+    # tutorial plugins under `examples/`. When Rigor is installed via
+    # `mise` / `gem install` the gem checkout is on disk, so a plugin
+    # author (or an AI coding agent following the `rigor-plugin-author`
+    # skill) can read a real, working plugin as a worked example —
+    # instead of guessing the `Rigor::Plugin::Base` surface from prose.
+    # This command outputs the absolute paths so they can be found and
+    # read regardless of where the gem landed.
+    #
+    # It is deliberately distinct from `rigor plugins` (plural), which
+    # reports the activation status of the plugins configured in *your*
+    # `.rigor.yml`. This command (singular) browses the plugins bundled
+    # in the *toolchain*. Mnemonic: "plugins" = my config; "plugin" =
+    # the catalogue I can learn from.
+    #
+    # Subcommands:
+    #
+    # - `rigor plugin list`          — every bundled plugin + example,
+    #                                  name + absolute directory path.
+    # - `rigor plugin path <name>`   — one-line absolute path to the
+    #                                  plugin's directory (Read-tool input).
+    # - `rigor plugin print <name>`  — a header (dir / lib / sig / README
+    #                                  paths) followed by the plugin's main
+    #                                  `lib/<name>.rb` source body.
+    # - `rigor plugin root`          — the rigortype gem root and its key
+    #                                  subdirectories (lib/, plugins/,
+    #                                  examples/, skills/, sig/), so an
+    #                                  author can read the public plugin
+    #                                  API (`lib/rigor/plugin.rb`) directly.
+    #
+    # `rigor plugin` with no subcommand is an alias for `list`.
+    #
+    # **Docker / cross-filesystem note.** Every path printed is resolved
+    # at runtime from this file's location, so it is correct *on the
+    # filesystem where `rigor` runs*. If you run `rigor` inside a
+    # container but read files from the host (or vice versa), the paths
+    # will not resolve — read them from the same environment that ran
+    # the command (`rigor plugin print` inlines the body for exactly
+    # this case: it works with no file-reading tool at all).
+    class PluginCommand
+      USAGE = <<~USAGE
+        Usage: rigor plugin <subcommand> [args]
+
+        Browse the plugins bundled in the rigortype toolchain (worked
+        examples for authoring your own). For the activation status of
+        the plugins in your .rigor.yml, use `rigor plugins` (plural).
+
+        Subcommands:
+          list                  List bundled + example plugins (default)
+          path  <name>          Print the absolute directory path of <name>
+          print <name>          Print <name>'s main lib source, with a header
+          root                  Print the gem root + key subdirectories
+
+        Examples:
+          rigor plugin list
+          rigor plugin path  rigor-activerecord
+          rigor plugin print rigor-activesupport-core-ext
+          rigor plugin root
+      USAGE
+
+      # The bundled plugins/examples/source live at `<gem_root>/...`.
+      # From `lib/rigor/cli/plugin_command.rb` the gem root is three
+      # directories up (matching SkillCommand::SKILLS_ROOT).
+      GEM_ROOT     = File.expand_path("../../..", __dir__)
+      PLUGINS_ROOT = File.join(GEM_ROOT, "plugins")
+      EXAMPLES_ROOT = File.join(GEM_ROOT, "examples")
+
+      def initialize(argv:, out: $stdout, err: $stderr)
+        @argv = argv
+        @out = out
+        @err = err
+      end
+
+      # @return [Integer] CLI exit status.
+      def run
+        subcommand = @argv.shift || "list"
+
+        case subcommand
+        when "list" then run_list
+        when "path" then run_path
+        when "print" then run_print
+        when "root" then run_root
+        when "-h", "--help", "help"
+          @out.puts(USAGE)
+          0
+        else
+          @err.puts("Unknown subcommand: #{subcommand}")
+          @err.puts(USAGE)
+          Rigor::CLI::EXIT_USAGE
+        end
+      end
+
+      private
+
+      def run_list
+        plugins = discover(PLUGINS_ROOT)
+        examples = discover(EXAMPLES_ROOT)
+        if plugins.empty? && examples.empty?
+          @err.puts("No bundled plugins found under #{PLUGINS_ROOT}")
+          return 1
+        end
+
+        width = (plugins + examples).map { |p| p.fetch(:name).length }.max
+        emit_group("Production plugins", PLUGINS_ROOT, plugins, width)
+        emit_group("Example plugins (tutorials)", EXAMPLES_ROOT, examples, width)
+        @out.puts
+        @out.puts("Engine source root: #{GEM_ROOT}")
+        @out.puts("  public plugin API: #{File.join(GEM_ROOT, 'lib/rigor/plugin.rb')}")
+        @out.puts(docker_note)
+        0
+      end
+
+      def emit_group(label, root, entries, width)
+        return if entries.empty?
+
+        @out.puts("#{label} — under #{root}:")
+        entries.each do |entry|
+          @out.puts(format("  %-#{width}s  %s", entry.fetch(:name), entry.fetch(:path)))
+        end
+      end
+
+      def run_path
+        name = @argv.shift
+        return usage_error("`path` requires a plugin name") if name.nil?
+
+        plugin = find(name)
+        return name_error(name) if plugin.nil?
+
+        @out.puts(plugin.fetch(:path))
+        0
+      end
+
+      def run_print
+        name = @argv.shift
+        return usage_error("`print` requires a plugin name") if name.nil?
+
+        plugin = find(name)
+        return name_error(name) if plugin.nil?
+
+        @out.puts(render_print_header(plugin))
+        @out.puts
+        entry = main_source_file(plugin)
+        if entry
+          @out.write(File.read(entry))
+        else
+          @out.puts("# (no lib/#{plugin.fetch(:name)}.rb entry file found; browse the directory above)")
+        end
+        0
+      end
+
+      def run_root
+        @out.puts("rigortype gem root: #{GEM_ROOT}")
+        {
+          "lib (engine source)" => File.join(GEM_ROOT, "lib"),
+          "lib/rigor/plugin.rb (public plugin API)" => File.join(GEM_ROOT, "lib/rigor/plugin.rb"),
+          "plugins (production plugins)" => PLUGINS_ROOT,
+          "examples (tutorial plugins)" => EXAMPLES_ROOT,
+          "skills (Agent Skills)" => File.join(GEM_ROOT, "skills"),
+          "sig (bundled RBS)" => File.join(GEM_ROOT, "sig")
+        }.each do |label, path|
+          marker = File.exist?(path) ? "" : "  (missing)"
+          @out.puts(format("  %<label>-42s %<path>s%<marker>s", label: label, path: path, marker: marker))
+        end
+        @out.puts(docker_note)
+        0
+      end
+
+      # The header that precedes the plugin body when an author runs
+      # `rigor plugin print <name>`. `# `-prefixed so the combined
+      # output stays readable; the Ruby body below it is unchanged.
+      def render_print_header(plugin)
+        dir = plugin.fetch(:path)
+        sig = File.join(dir, "sig")
+        readme = File.join(dir, "README.md")
+        <<~HEADER.chomp
+          # Rigor plugin: #{plugin.fetch(:name)}  (#{plugin.fetch(:kind)})
+          # Directory: #{dir}
+          # Lib:       #{File.join(dir, 'lib')}
+          # Sig:       #{File.directory?(sig) ? sig : '(none)'}
+          # README:    #{File.file?(readme) ? readme : '(none)'}
+          #
+          # A real, working plugin shipped with rigortype #{Rigor::VERSION}.
+          # The main source body is below; read the other files from the
+          # paths above. To suppress `call.undefined-method` for methods a
+          # DSL generates, study how an RBS-bundle plugin ships `sig/` (see
+          # `rigor plugin print rigor-activesupport-core-ext`).
+        HEADER
+      end
+
+      def discover(root)
+        return [] unless File.directory?(root)
+
+        kind = root == EXAMPLES_ROOT ? "example" : "production"
+        Dir.children(root).sort.filter_map do |name|
+          dir = File.join(root, name)
+          next unless File.directory?(dir)
+
+          { name: name, path: dir, kind: kind }
+        end
+      end
+
+      # Match the directory name with or without the conventional
+      # `rigor-` prefix, so both `rigor-activerecord` and
+      # `activerecord` resolve.
+      def find(name)
+        all = discover(PLUGINS_ROOT) + discover(EXAMPLES_ROOT)
+        all.find { |p| p.fetch(:name) == name } ||
+          all.find { |p| p.fetch(:name).delete_prefix("rigor-") == name.delete_prefix("rigor-") }
+      end
+
+      def main_source_file(plugin)
+        dir = plugin.fetch(:path)
+        candidate = File.join(dir, "lib", "#{plugin.fetch(:name)}.rb")
+        return candidate if File.file?(candidate)
+
+        Dir.glob(File.join(dir, "lib", "*.rb")).min
+      end
+
+      def docker_note
+        "\nNote: paths are local to where `rigor` runs. If you run rigor in a " \
+          "container,\nread these files from the same filesystem (use " \
+          "`rigor plugin print` to inline a body)."
+      end
+
+      def name_error(name)
+        @err.puts("Unknown plugin: #{name}")
+        @err.puts("Run `rigor plugin list` to see the bundled plugins.")
+        1
+      end
+
+      def usage_error(message)
+        @err.puts(message)
+        @err.puts(USAGE)
+        Rigor::CLI::EXIT_USAGE
+      end
+    end
+  end
+end

data/lib/rigor/cli.rb

@@ -33,6 +33,7 @@ module Rigor
       "triage" => :run_triage,
       "coverage" => :run_coverage,
       "plugins" => :run_plugins,
+      "plugin" => :run_plugin,
       "playground" => :run_playground,
       "skill" => :run_skill
     }.freeze
@@ -642,6 +643,12 @@ module Rigor
       CLI::SkillCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    def run_plugin
+      require_relative "cli/plugin_command"
+
+      CLI::PluginCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def write_result(result, format)
       case format
       when "json"
@@ -688,6 +695,7 @@ module Rigor
           triage     Summarise diagnostics: distribution, hotspots, hints (ADR-23)
           coverage   Report type-precision coverage (precise vs Dynamic ratio)
           plugins    Report activation status of every configured plugin
+          plugin     Browse bundled plugin source as worked examples (list/path/print/root)
           playground Start the browser playground (requires rigor-playground gem)
           skill      List or print bundled Agent Skills (rigor-project-init, ...)
           version    Print the Rigor version

data/lib/rigor/configuration/severity_profile.rb

@@ -51,6 +51,9 @@ module Rigor
           "dump.type" => :info,
           "def.return-type-mismatch" => :warning,
           "def.method-visibility-mismatch" => :warning,
+          "def.override-visibility-reduced" => :off,
+          "def.override-return-widened" => :off,
+          "def.override-param-narrowed" => :off,
           "def.ivar-write-mismatch" => :warning
         }.freeze,
         balanced: {
@@ -67,6 +70,9 @@ module Rigor
           "dump.type" => :info,
           "def.return-type-mismatch" => :warning,
           "def.method-visibility-mismatch" => :error,
+          "def.override-visibility-reduced" => :warning,
+          "def.override-return-widened" => :warning,
+          "def.override-param-narrowed" => :warning,
           "def.ivar-write-mismatch" => :warning
         }.freeze,
         strict: {
@@ -83,6 +89,9 @@ module Rigor
           "dump.type" => :error,
           "def.return-type-mismatch" => :error,
           "def.method-visibility-mismatch" => :error,
+          "def.override-visibility-reduced" => :error,
+          "def.override-return-widened" => :error,
+          "def.override-param-narrowed" => :error,
           "def.ivar-write-mismatch" => :error
         }.freeze
       }.freeze

data/lib/rigor/inference/scope_indexer.rb

@@ -114,15 +114,14 @@ module Rigor
         # def nodes, the class -> superclass map, and the
         # class/module -> included-modules map, each merged under
         # the cross-file pre-pass seed (see below).
-        seeded_scope = merge_project_method_indexes(seeded_scope, default_scope, root)
-
         # v0.1.2 — per-class table of method visibilities
         # (`:public` / `:private` / `:protected`). The
-        # `def.method-visibility-mismatch` CheckRule consults
-        # the table to flag explicit-non-self calls to a
-        # private user method.
-        discovered_method_visibilities = build_discovered_method_visibilities(root)
-        seeded_scope = seeded_scope.with_discovered_method_visibilities(discovered_method_visibilities)
+        # `def.method-visibility-mismatch` and ADR-35
+        # `def.override-visibility-reduced` CheckRules consult the
+        # table. Seeded inside `merge_project_method_indexes` so the
+        # per-file visibilities merge OVER the cross-file project seed
+        # rather than overwriting it.
+        seeded_scope = merge_project_method_indexes(seeded_scope, default_scope, root)
 
         table = {}.compare_by_identity
         table.default = seeded_scope
@@ -161,11 +160,18 @@ module Rigor
         includes = default_scope.discovered_includes.merge(
           build_discovered_includes(root)
         ) { |_class, cross_file, per_file| (cross_file + per_file).uniq }
+        # ADR-35 — per-file visibilities merged OVER the cross-file
+        # seed (the current file is authoritative for its own classes;
+        # sibling-file ancestors are preserved from the project seed).
+        method_visibilities = default_scope.discovered_method_visibilities.merge(
+          build_discovered_method_visibilities(root)
+        ) { |_class, cross_file, per_file| cross_file.merge(per_file) }
 
         seeded_scope
           .with_discovered_def_nodes(def_nodes)
           .with_discovered_superclasses(superclasses)
           .with_discovered_includes(includes)
+          .with_discovered_method_visibilities(method_visibilities)
       end
 
       # Slice 7 phase 2. Builds the class-level ivar accumulator
@@ -1365,31 +1371,63 @@ module Rigor
       # (`Mastodon::CLI::Accounts` calling a helper defined in
       # `Mastodon::CLI::Base`).
       #
+      # The returned `def_sources` map mirrors `def_nodes` but stores
+      # a `"path:line"` String per `(class_name, method_name)` instead
+      # of the `Prism::DefNode`. A `Prism::Location` does not expose
+      # its source file through public API, so the source site is
+      # captured here, in the pre-pass loop that still holds `path`.
+      # `CheckRules#undefined_method_diagnostic` consults the seeded
+      # copy to name the defining file when a project monkey-patch on
+      # a core/stdlib/gem class is called cross-file (ADR-17). First
+      # write wins, matching `def_nodes`' own merge order.
+      #
       # @param paths  [Array<String>] project file paths.
       # @param buffer [Rigor::Analysis::BufferBinding, nil]
-      # @return [Hash{Symbol => Hash}] `{ def_nodes:, superclasses: }`
+      # @return [Hash{Symbol => Hash}]
+      #   `{ def_nodes:, def_sources:, superclasses:, includes: }`
       def discovered_def_index_for_paths(paths, buffer: nil)
-        def_nodes = {}
-        superclasses = {}
-        includes = {}
+        acc = { def_nodes: {}, def_sources: {}, superclasses: {}, includes: {}, method_visibilities: {} }
         paths.each do |path|
           physical = buffer ? buffer.resolve(path) : path
           root = Prism.parse(File.read(physical), filepath: path).value
-          build_discovered_def_nodes(root).each do |class_name, methods|
-            (def_nodes[class_name] ||= {}).merge!(methods)
-          end
-          superclasses.merge!(build_discovered_superclasses(root))
-          build_discovered_includes(root).each do |class_name, mods|
-            includes[class_name] = ((includes[class_name] || []) + mods).uniq
-          end
+          accumulate_project_index(acc, path, root)
         rescue StandardError
           # Skip files that fail to parse or read; the per-file
           # analyzer surfaces the parse error separately.
           next
         end
-        def_nodes.each_value(&:freeze)
-        includes.each_value(&:freeze)
-        { def_nodes: def_nodes.freeze, superclasses: superclasses.freeze, includes: includes.freeze }
+        %i[def_nodes def_sources includes method_visibilities].each { |key| acc[key].each_value(&:freeze) }
+        acc.transform_values(&:freeze)
+      end
+
+      # Folds one file's class-keyed indexes into the cross-file
+      # accumulator. `method_visibilities` (ADR-35) is collected here so
+      # the override-visibility-reduced rule can read an ancestor's
+      # visibility declared in a sibling file.
+      def accumulate_project_index(acc, path, root)
+        merge_discovered_defs(acc[:def_nodes], acc[:def_sources], path, root)
+        acc[:superclasses].merge!(build_discovered_superclasses(root))
+        build_discovered_includes(root).each do |class_name, mods|
+          acc[:includes][class_name] = ((acc[:includes][class_name] || []) + mods).uniq
+        end
+        build_discovered_method_visibilities(root).each do |class_name, table|
+          (acc[:method_visibilities][class_name] ||= {}).merge!(table)
+        end
+      end
+
+      # Merges one file's `class → method → DefNode` map into the
+      # cross-file `def_nodes` index and records each method's first-
+      # seen `"path:line"` definition site in `def_sources` (ADR-17 —
+      # the un-registered-project-patch signal `call.undefined-method`
+      # and `rigor triage` key on).
+      def merge_discovered_defs(def_nodes, def_sources, path, root)
+        build_discovered_def_nodes(root).each do |class_name, methods|
+          (def_nodes[class_name] ||= {}).merge!(methods)
+          sources = (def_sources[class_name] ||= {})
+          methods.each do |method_name, def_node|
+            sources[method_name] ||= "#{path}:#{def_node.location&.start_line || 1}"
+          end
+        end
       end
 
       # Class-only variant of `record_declarations` — descends

data/lib/rigor/scope.rb

@@ -20,7 +20,7 @@ module Rigor
                 :ivars, :cvars, :globals,
                 :class_ivars, :class_cvars, :program_globals,
                 :discovered_classes, :in_source_constants, :discovered_methods,
-                :discovered_def_nodes, :discovered_method_visibilities,
+                :discovered_def_nodes, :discovered_def_sources, :discovered_method_visibilities,
                 :discovered_superclasses, :discovered_includes,
                 :indexed_narrowings, :method_chain_narrowings,
                 :source_path
@@ -89,6 +89,7 @@ module Rigor
       in_source_constants: EMPTY_VAR_BINDINGS,
       discovered_methods: EMPTY_CLASS_BINDINGS,
       discovered_def_nodes: EMPTY_CLASS_BINDINGS,
+      discovered_def_sources: EMPTY_CLASS_BINDINGS,
       discovered_method_visibilities: EMPTY_CLASS_BINDINGS,
       discovered_superclasses: EMPTY_CLASS_BINDINGS,
       discovered_includes: EMPTY_CLASS_BINDINGS,
@@ -111,6 +112,7 @@ module Rigor
       @in_source_constants = in_source_constants
       @discovered_methods = discovered_methods
       @discovered_def_nodes = discovered_def_nodes
+      @discovered_def_sources = discovered_def_sources
       @discovered_method_visibilities = discovered_method_visibilities
       @discovered_superclasses = discovered_superclasses
       @discovered_includes = discovered_includes
@@ -361,6 +363,27 @@ module Rigor
       rebuild(discovered_def_nodes: table)
     end
 
+    # Companion to {#user_def_for}: returns the `"path:line"` where
+    # the project defines `class_name#method_name` (instance-side),
+    # or nil. Populated only by the cross-file project pre-pass
+    # ({Inference::ScopeIndexer.discovered_def_index_for_paths}) — a
+    # `Prism::Location` hides its source file, so the site is recorded
+    # at scan time. `CheckRules#undefined_method_diagnostic` consults
+    # this to name the defining file when a project monkey-patch on a
+    # core/stdlib/gem class is called cross-file, so the diagnostic
+    # can point at `pre_eval:` (ADR-17) instead of reading as a bare
+    # unresolved call.
+    def user_def_site_for(class_name, method_name)
+      table = @discovered_def_sources[class_name.to_s]
+      return nil unless table
+
+      table[method_name.to_sym]
+    end
+
+    def with_discovered_def_sources(table)
+      rebuild(discovered_def_sources: table)
+    end
+
     # ADR-24 slice 2 — per-class table mapping a fully
     # qualified user-class name to its superclass name AS
     # WRITTEN at the `class Foo < Bar` declaration (`"Bar"`,
@@ -558,6 +581,7 @@ module Rigor
       class_ivars: @class_ivars, class_cvars: @class_cvars, program_globals: @program_globals,
       discovered_classes: @discovered_classes, in_source_constants: @in_source_constants,
       discovered_methods: @discovered_methods, discovered_def_nodes: @discovered_def_nodes,
+      discovered_def_sources: @discovered_def_sources,
       discovered_method_visibilities: @discovered_method_visibilities,
       discovered_superclasses: @discovered_superclasses,
       discovered_includes: @discovered_includes,
@@ -576,6 +600,7 @@ module Rigor
         in_source_constants: in_source_constants,
         discovered_methods: discovered_methods,
         discovered_def_nodes: discovered_def_nodes,
+        discovered_def_sources: discovered_def_sources,
         discovered_method_visibilities: discovered_method_visibilities,
         discovered_superclasses: discovered_superclasses,
         discovered_includes: discovered_includes,
@@ -607,6 +632,7 @@ module Rigor
         in_source_constants: in_source_constants,
         discovered_methods: discovered_methods,
         discovered_def_nodes: discovered_def_nodes,
+        discovered_def_sources: discovered_def_sources,
         discovered_method_visibilities: discovered_method_visibilities,
         discovered_superclasses: discovered_superclasses,
         discovered_includes: discovered_includes,

data/lib/rigor/triage/catalogue.rb

@@ -22,6 +22,7 @@ module Rigor
       module_function
 
       UNDEFINED_METHOD_RULE = "call.undefined-method"
+      UNRESOLVED_TOPLEVEL_RULE = "call.unresolved-toplevel"
 
       # `undefined method `foo' for <receiver>`
       UNDEF_METHOD = /\Aundefined method [`'"]([^`'"]+)['"`] for (.+)\z/
@@ -104,9 +105,19 @@ module Rigor
       # monkey-patch): a known AR method on `Array[...]` deserves
       # the precise relation-misinference hint, not the generic
       # "project core-ext" guess H2 would otherwise claim it for.
+      #
+      # H2K (known project patch) runs before the generic H2: the
+      # engine has already proved the defining site via the
+      # `project_definition_site` field (ADR-17), so those
+      # diagnostics get the high-confidence file-naming hint rather
+      # than the spread-based guess. H7 (unresolved toplevel) runs
+      # before the systemic / genuine-bug catch-alls so toplevel
+      # resolution misses route to `pre_eval:` (ADR-34) instead of
+      # reading as scattered bugs.
       def recognisers
         %i[h1_activesupport h4_ar_relation h3_gem_without_rbs
-           h2_monkey_patch h5_systemic_cluster h6_genuine_bugs]
+           h2k_known_project_patch h2_monkey_patch h7_unresolved_toplevel
+           h5_systemic_cluster h6_genuine_bugs]
       end
 
       # --- H1 — likely ActiveSupport core_ext --------------------
@@ -127,6 +138,31 @@ module Rigor
         ), matched]
       end
 
+      # --- H2K — known project monkey-patch (engine-proven) ------
+      # ADR-17 / WD3 slice 4: the `call.undefined-method` rule sets
+      # `project_definition_site` when the project itself defines the
+      # called method on the receiver class somewhere in the file set
+      # (a reopened core/stdlib/gem class the dispatcher does not
+      # apply cross-file). That is direct evidence — not a spread
+      # heuristic — so this recogniser is `:likely` and names the
+      # defining files outright. It runs before the generic H2.
+      def h2k_known_project_patch(pool)
+        matched = pool.select(&:project_definition_site)
+        return nil if matched.empty?
+
+        files = matched.map { |d| d.project_definition_site.sub(/:\d+\z/, "") }
+                       .uniq.sort
+        [Hint.new(
+          id: "project-monkey-patch-known", confidence: :likely,
+          diagnostic_count: matched.size,
+          summary: "#{matched.size} undefined-method site(s) resolve to project " \
+                   "definitions in #{files.first(3).join(', ')} — reopened core/" \
+                   "stdlib/gem classes Rigor does not apply cross-file",
+          action: "List #{files.size == 1 ? 'this file' : 'these files'} in " \
+                  "`.rigor.yml`'s `pre_eval:` (ADR-17): #{files.join(', ')}"
+        ), matched]
+      end
+
       # --- H2 — likely a project monkey-patch / refinement -------
       def h2_monkey_patch(pool)
         groups = undefined_method_groups(pool).select do |(_method, _recv), diags|
@@ -179,6 +215,30 @@ module Rigor
         ), matched]
       end
 
+      # --- H7 — unresolved toplevel implicit-self calls ----------
+      # ADR-34: `call.unresolved-toplevel` fires on a toplevel
+      # implicit-self call (no receiver, outside any def / class /
+      # module) that resolves against no visible contributor. The
+      # canonical opt-out is `pre_eval:` — the file is usually a
+      # script relying on methods defined by a monkey-patch or a
+      # required helper Rigor did not walk. Grouped, not per-site,
+      # so the report names the cluster once.
+      def h7_unresolved_toplevel(pool)
+        matched = pool.select { |d| rule_of(d) == UNRESOLVED_TOPLEVEL_RULE }
+        return nil if matched.empty?
+
+        files = matched.map(&:path).uniq.sort
+        [Hint.new(
+          id: "unresolved-toplevel", confidence: :possible,
+          diagnostic_count: matched.size,
+          summary: "#{matched.size} toplevel call(s) resolve to nothing visible " \
+                   "across #{files.size} file(s) (#{top_methods(matched, parser: :toplevel)})",
+          action: "If a monkey-patch or required helper defines these, list its " \
+                  "file in `.rigor.yml`'s `pre_eval:` (ADR-17); otherwise they may " \
+                  "be genuine typos or missing requires."
+        ), matched]
+      end
+
       # --- H5 — systemic single-file cluster ---------------------
       def h5_systemic_cluster(pool)
         bucket = pool.group_by { |d| [d.path, rule_of(d)] }
@@ -282,10 +342,16 @@ module Rigor
         groups.keys.first(3).map { |method, recv| "`#{method}` on #{recv}" }.join(", ")
       end
 
-      def top_methods(diagnostics, limit: 5)
-        diagnostics.filter_map { |d| parse_undefined_method(d)&.fetch(:method) }
-                   .tally.sort_by { |method, count| [-count, method] }
-                         .first(limit).map { |method, count| "#{method}×#{count}" }.join(" ")
+      # `parser: :undefined_method` (default) reads the method from
+      # the parsed `undefined-method` shape; `parser: :toplevel`
+      # reads the structured `method_name` field directly (the
+      # `unresolved-toplevel` rule carries no receiver to parse).
+      def top_methods(diagnostics, limit: 5, parser: :undefined_method)
+        names = diagnostics.filter_map do |d|
+          parser == :toplevel ? d.method_name : parse_undefined_method(d)&.fetch(:method)
+        end
+        names.tally.sort_by { |method, count| [-count, method] }
+                   .first(limit).map { |method, count| "#{method}×#{count}" }.join(" ")
       end
 
       def rule_of(diag)

data/lib/rigor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rigor
-  VERSION = "0.1.14"
+  VERSION = "0.1.15"
 end

data/sig/rigor/scope.rbs

@@ -15,6 +15,7 @@ module Rigor
     attr_reader in_source_constants: Hash[String, Type::t]
     attr_reader discovered_methods: Hash[String, Hash[Symbol, Symbol]]
     attr_reader discovered_def_nodes: Hash[String, Hash[Symbol, untyped]]
+    attr_reader discovered_def_sources: Hash[String, Hash[Symbol, String]]
     attr_reader discovered_method_visibilities: Hash[String, Hash[Symbol, Symbol]]
     attr_reader discovered_superclasses: Hash[String, String]
     attr_reader discovered_includes: Hash[String, Array[String]]
@@ -56,7 +57,9 @@ module Rigor
     def with_discovered_methods: (Hash[String, Hash[Symbol, Symbol]] table) -> Scope
     def discovered_method?: (String | Symbol class_name, String | Symbol method_name, Symbol kind) -> bool
     def with_discovered_def_nodes: (Hash[String, Hash[Symbol, untyped]] table) -> Scope
+    def with_discovered_def_sources: (Hash[String, Hash[Symbol, String]] table) -> Scope
     def user_def_for: (String | Symbol class_name, String | Symbol method_name) -> untyped?
+    def user_def_site_for: (String | Symbol class_name, String | Symbol method_name) -> String?
     def top_level_def_for: (String | Symbol method_name) -> untyped?
     def toplevel?: () -> bool
     def with_discovered_method_visibilities: (Hash[String, Hash[Symbol, Symbol]] table) -> Scope