rigortype 0.1.7 → 0.1.9

data/lib/rigor/plugin/protocol_contract.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    # ADR-28 declaration: "every instance/singleton method named
+    # `method_name`, defined in a source file matching `path_glob`,
+    # is implicitly required to satisfy the declared parameter +
+    # return-type protocol."
+    #
+    # Authored on a plugin manifest:
+    #
+    #   manifest(
+    #     id: "web",
+    #     version: "0.1.0",
+    #     protocol_contracts: [
+    #       Rigor::Plugin::ProtocolContract.new(
+    #         path_glob: "lib/controller/**/*.rb",
+    #         method_name: :get,
+    #         param_types: [{ index: 0, type_name: "Rack::Request" }],
+    #         return_type_name: "Rack::Response"
+    #       )
+    #     ]
+    #   )
+    #
+    # The contract drives two distinct engine behaviours (ADR-28
+    # § "provide-and-check"):
+    #
+    # - **provide** — when the inference engine binds the parameter
+    #   list of a matching `def`, {Rigor::Inference::MethodParameterBinder}
+    #   substitutes the declared `param_types` for the usual
+    #   `Dynamic[Top]` fallback, so the method body is analysed as
+    #   if the parameter carried its protocol type.
+    # - **check** — the contributing plugin's `#diagnostics_for_file`
+    #   hook confirms the method exists and its inferred return type
+    #   conforms to `return_type_name`.
+    #
+    # ## Fields
+    #
+    # - `path_glob` — `File.fnmatch` glob (String) selecting the
+    #   source files the contract applies to, relative to the
+    #   analysed project root (e.g. `"lib/controller/**/*.rb"`).
+    # - `method_name` — Symbol; the instance (or singleton) method
+    #   the contract constrains.
+    # - `singleton` — Boolean; `true` constrains `def self.<name>`,
+    #   `false` (default) constrains instance methods.
+    # - `param_types` — Array of `ParamType` (positional index →
+    #   fully-qualified type name). The type names resolve against
+    #   the analysed project's environment lazily, at consumption
+    #   time, so the contract value object stays independent of
+    #   environment construction order.
+    # - `return_type_name` — fully-qualified type name (String) the
+    #   method's inferred return type must conform to.
+    # - `severity` — Symbol diagnostic severity for contract
+    #   violations (`:error` default).
+    #
+    # ## Ractor-shareability
+    #
+    # Every field is frozen at construction (ADR-15 Phase 1); the
+    # nested `ParamType` is a frozen `Data`. `Ractor.shareable?`
+    # returns true after `#initialize`, so the contract survives
+    # `Plugin::Registry.materialize` into a worker Ractor.
+    class ProtocolContract
+      VALID_SEVERITIES = %i[error warning info].freeze
+
+      # One positional-parameter provision: the zero-based index of
+      # the parameter and the fully-qualified name of the type it
+      # carries under the protocol.
+      ParamType = Data.define(:index, :type_name)
+
+      attr_reader :path_glob, :method_name, :singleton, :param_types, :return_type_name, :severity
+
+      def initialize(path_glob:, method_name:, return_type_name: nil, param_types: [], singleton: false,
+                     severity: :error)
+        validate_path_glob!(path_glob)
+        validate_method_name!(method_name)
+        validate_return_type_name!(return_type_name)
+        validate_severity!(severity)
+
+        @path_glob = path_glob.dup.freeze
+        @method_name = method_name.to_sym
+        @singleton = singleton ? true : false
+        @param_types = coerce_param_types(param_types)
+        @return_type_name = return_type_name.nil? ? nil : return_type_name.dup.freeze
+        @severity = severity.to_sym
+        freeze
+      end
+
+      # Returns a copy with `path_glob` replaced. Plugins use this to
+      # honour a per-project config override of the convention path
+      # without rebuilding the whole contract by hand.
+      def with_path_glob(glob)
+        ProtocolContract.new(
+          path_glob: glob,
+          method_name: method_name,
+          return_type_name: return_type_name,
+          param_types: param_types.map { |pt| { index: pt.index, type_name: pt.type_name } },
+          singleton: singleton,
+          severity: severity
+        )
+      end
+
+      def to_h
+        {
+          "path_glob" => path_glob,
+          "method_name" => method_name.to_s,
+          "singleton" => singleton,
+          "param_types" => param_types.map { |pt| { "index" => pt.index, "type_name" => pt.type_name } },
+          "return_type_name" => return_type_name,
+          "severity" => severity.to_s
+        }
+      end
+
+      def ==(other)
+        other.is_a?(ProtocolContract) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      private
+
+      def validate_path_glob!(value)
+        return if value.is_a?(String) && !value.empty?
+
+        raise ArgumentError,
+              "Plugin::ProtocolContract#path_glob must be a non-empty String, got #{value.inspect}"
+      end
+
+      def validate_method_name!(value)
+        return if value.is_a?(Symbol) || (value.is_a?(String) && !value.empty?)
+
+        raise ArgumentError,
+              "Plugin::ProtocolContract#method_name must be a Symbol/non-empty String, got #{value.inspect}"
+      end
+
+      def validate_return_type_name!(value)
+        return if value.nil?
+        return if value.is_a?(String) && !value.empty?
+
+        raise ArgumentError,
+              "Plugin::ProtocolContract#return_type_name must be a non-empty String or nil, got #{value.inspect}"
+      end
+
+      def validate_severity!(value)
+        return if VALID_SEVERITIES.include?(value.to_sym)
+
+        raise ArgumentError,
+              "Plugin::ProtocolContract#severity must be one of #{VALID_SEVERITIES.inspect}, got #{value.inspect}"
+      rescue NoMethodError
+        raise ArgumentError,
+              "Plugin::ProtocolContract#severity must be one of #{VALID_SEVERITIES.inspect}, got #{value.inspect}"
+      end
+
+      def coerce_param_types(param_types)
+        unless param_types.is_a?(Array)
+          raise ArgumentError,
+                "Plugin::ProtocolContract#param_types must be an Array, got #{param_types.inspect}"
+        end
+
+        param_types.map { |entry| coerce_param_type(entry) }.freeze
+      end
+
+      def coerce_param_type(entry)
+        return entry if entry.is_a?(ParamType)
+
+        unless entry.is_a?(Hash)
+          raise ArgumentError,
+                "Plugin::ProtocolContract param_types entry must be a Hash or ParamType, got #{entry.inspect}"
+        end
+
+        index = entry[:index] || entry["index"]
+        type_name = entry[:type_name] || entry["type_name"]
+        unless index.is_a?(Integer) && index >= 0 && type_name.is_a?(String) && !type_name.empty?
+          raise ArgumentError,
+                "Plugin::ProtocolContract param_types entry needs an Integer index >= 0 and a " \
+                "non-empty String type_name, got #{entry.inspect}"
+        end
+
+        ParamType.new(index: index, type_name: type_name.dup.freeze)
+      end
+    end
+  end
+end

data/lib/rigor/plugin/registry.rb

@@ -104,7 +104,73 @@ module Rigor
         Inference::HktRegistry.new(registrations: registrations, definitions: definitions)
       end
 
+      # ADR-25 — flat, ordered list of every loaded plugin's
+      # resolved RBS signature directories (absolute paths), in
+      # plugin registration order. `Environment.for_project`
+      # merges these into the signature-path set fed to
+      # `RbsLoader`, alongside the configuration's `signature_paths:`
+      # and the `bundler:` / `rbs_collection:` discovery output.
+      def signature_paths
+        plugins.flat_map(&:signature_paths)
+      end
+
+      # ADR-26 — the aggregate set of "open" receiver class names
+      # declared across loaded plugins (manifest `open_receivers:`).
+      # A class is open when a plugin vouches that it responds
+      # beyond its RBS-declared method surface. `open_receiver?`
+      # is the membership predicate `Analysis::CheckRules` consults
+      # to skip the `call.undefined-method` rule for such a class.
+      def open_receivers
+        plugins.flat_map { |plugin| plugin.manifest.open_receivers }
+      end
+
+      def open_receiver?(class_name)
+        return false if class_name.nil?
+
+        open_receivers.include?(class_name.to_s)
+      end
+
+      # ADR-28 — flat, ordered list of every loaded plugin's
+      # path-scoped method-protocol contracts, in plugin
+      # registration order. Read from each plugin's
+      # `#protocol_contracts` (which the manifest backs by default
+      # but a plugin MAY override to fold in per-project config).
+      # Consumed by `Inference::MethodParameterBinder` (the
+      # parameter-type provision) and by contributing plugins'
+      # `#diagnostics_for_file` hooks (the presence + return-type
+      # check).
+      def protocol_contracts
+        plugins.flat_map(&:protocol_contracts)
+      end
+
+      # ADR-28 — the subset of `protocol_contracts` whose
+      # `path_glob` matches `path`. Contract globs are authored
+      # project-root-relative (`lib/controller/**/*.rb`); the
+      # analyzer may hand this method either a project-relative
+      # path (`rigor check` run from the project root) or an
+      # absolute one (run from elsewhere, or a spec tmpdir), so the
+      # glob is matched both directly and as a `**/`-prefixed path
+      # suffix. `File::FNM_PATHNAME` keeps `*` from crossing `/`;
+      # `File::FNM_EXTGLOB` enables `{a,b}` groups. Returns `[]` for
+      # a nil path so the binder can call this unconditionally.
+      def contracts_for_path(path)
+        return [] if path.nil?
+
+        path_s = path.to_s
+        protocol_contracts.select { |contract| path_matches_glob?(contract.path_glob, path_s) }
+      end
+
+      FNMATCH_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+      private_constant :FNMATCH_FLAGS
+
       EMPTY = new.freeze
+
+      private
+
+      def path_matches_glob?(glob, path)
+        File.fnmatch?(glob, path, FNMATCH_FLAGS) ||
+          File.fnmatch?(File.join("**", glob), path, FNMATCH_FLAGS)
+      end
     end
   end
 end

data/lib/rigor/scope.rb

@@ -21,6 +21,7 @@ module Rigor
                 :class_ivars, :class_cvars, :program_globals,
                 :discovered_classes, :in_source_constants, :discovered_methods,
                 :discovered_def_nodes, :discovered_method_visibilities,
+                :discovered_superclasses, :discovered_includes,
                 :source_path
 
     EMPTY_DECLARED_TYPES = {}.compare_by_identity.freeze
@@ -51,6 +52,8 @@ module Rigor
       discovered_methods: EMPTY_CLASS_BINDINGS,
       discovered_def_nodes: EMPTY_CLASS_BINDINGS,
       discovered_method_visibilities: EMPTY_CLASS_BINDINGS,
+      discovered_superclasses: EMPTY_CLASS_BINDINGS,
+      discovered_includes: EMPTY_CLASS_BINDINGS,
       source_path: nil
     )
       @environment = environment
@@ -69,6 +72,8 @@ module Rigor
       @discovered_methods = discovered_methods
       @discovered_def_nodes = discovered_def_nodes
       @discovered_method_visibilities = discovered_method_visibilities
+      @discovered_superclasses = discovered_superclasses
+      @discovered_includes = discovered_includes
       @source_path = source_path
       freeze
     end
@@ -284,6 +289,41 @@ module Rigor
       rebuild(discovered_def_nodes: 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"`,
+    # possibly a qualified `"A::B"`). Populated by `ScopeIndexer`
+    # — per-file plus the cross-file project pre-pass — and
+    # consumed by `ExpressionTyper#try_user_method_inference`
+    # to walk the superclass chain when an implicit-self call
+    # does not resolve against the enclosing class's own defs.
+    # The as-written name is resolved to a qualified class at
+    # walk time against the call's lexical nesting.
+    def superclass_of(class_name)
+      @discovered_superclasses[class_name.to_s]
+    end
+
+    def with_discovered_superclasses(table)
+      rebuild(discovered_superclasses: table)
+    end
+
+    # ADR-24 slice 2 — per-class/module table mapping a fully
+    # qualified user class or module to the list of module
+    # names it `include`s / `prepend`s, AS WRITTEN at the
+    # mixin call. Populated by `ScopeIndexer` (per-file plus
+    # the cross-file pre-pass) and consumed by
+    # `ExpressionTyper#resolve_user_def_through_ancestors` so an
+    # implicit-self call resolves against an included module's
+    # `def`s, not just the superclass chain. As-written names
+    # are resolved to qualified classes at walk time.
+    def includes_of(class_name)
+      @discovered_includes[class_name.to_s] || []
+    end
+
+    def with_discovered_includes(table)
+      rebuild(discovered_includes: table)
+    end
+
     # v0.1.2 — per-class table mapping `method_name (Symbol) →
     # :public | :private | :protected`. Populated by
     # `ScopeIndexer` for every `def` it sees inside a class
@@ -372,6 +412,8 @@ module Rigor
       discovered_classes: @discovered_classes, in_source_constants: @in_source_constants,
       discovered_methods: @discovered_methods, discovered_def_nodes: @discovered_def_nodes,
       discovered_method_visibilities: @discovered_method_visibilities,
+      discovered_superclasses: @discovered_superclasses,
+      discovered_includes: @discovered_includes,
       source_path: @source_path
     )
       self.class.new(
@@ -386,6 +428,8 @@ module Rigor
         discovered_methods: discovered_methods,
         discovered_def_nodes: discovered_def_nodes,
         discovered_method_visibilities: discovered_method_visibilities,
+        discovered_superclasses: discovered_superclasses,
+        discovered_includes: discovered_includes,
         source_path: source_path
       )
     end
@@ -413,6 +457,8 @@ module Rigor
         discovered_methods: discovered_methods,
         discovered_def_nodes: discovered_def_nodes,
         discovered_method_visibilities: discovered_method_visibilities,
+        discovered_superclasses: discovered_superclasses,
+        discovered_includes: discovered_includes,
         source_path: source_path
       )
     end

data/lib/rigor/triage/catalogue.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require_relative "hint"
+
+module Rigor
+  module Triage
+    # ADR-23 § "Heuristic catalogue" — the six v1 recognisers.
+    #
+    # {.recognise} runs them in order over the diagnostic stream.
+    # Each recogniser sees only the diagnostics not yet claimed by
+    # an earlier one, so a `5.minutes` diagnostic counted by H1
+    # (ActiveSupport) is not re-counted by H2 (monkey-patch).
+    #
+    # WD3 / slice 4: recognisers key on the structured
+    # `qualified_rule` first; where they additionally need the
+    # receiver type or method name they read the structured
+    # `Diagnostic#receiver_type` / `#method_name` fields, falling
+    # back to parsing the diagnostic message only when those are
+    # absent. A parse failure degrades to "skip this diagnostic" —
+    # never a crash.
+    module Catalogue # rubocop:disable Metrics/ModuleLength
+      module_function
+
+      UNDEFINED_METHOD_RULE = "call.undefined-method"
+
+      # `undefined method `foo' for <receiver>`
+      UNDEF_METHOD = /\Aundefined method [`'"]([^`'"]+)['"`] for (.+)\z/
+
+      # ActiveSupport `core_ext` selectors, grouped by the core
+      # class they extend. Survey-grounded (the dominant clusters
+      # from the five-project survey + the Mastodon measurement).
+      AS_NUMERIC = %w[
+        day days hour hours minute minutes second seconds week weeks
+        fortnight fortnights month months year years
+        byte bytes kilobyte kilobytes megabyte megabytes gigabyte gigabytes
+        terabyte terabytes petabyte petabytes exabyte exabytes
+        ago since from_now in_milliseconds
+      ].freeze
+      AS_STRING = %w[
+        squish squish! strip_heredoc html_safe underscore camelize camelcase
+        pluralize singularize titleize titlecase humanize dasherize
+        parameterize tableize classify constantize safe_constantize
+        demodulize deconstantize foreign_key indent indent! truncate
+        truncate_words to_datetime to_date to_time exclude? at from
+        remove remove! mb_chars upcase_first downcase_first
+      ].freeze
+      AS_HASH = %w[
+        deep_dup deep_merge deep_merge! symbolize_keys symbolize_keys!
+        stringify_keys stringify_keys! deep_symbolize_keys deep_stringify_keys
+        deep_transform_keys deep_transform_keys! deep_transform_values
+        except! with_indifferent_access assert_valid_keys
+        reverse_merge reverse_merge! extract!
+      ].freeze
+      AS_ARRAY = %w[
+        to_sentence in_groups_of in_groups second third fourth fifth
+        forty_two extract_options! wrap deep_dup
+      ].freeze
+      AS_TIMEDATE = %w[
+        zone current beginning_of_day end_of_day beginning_of_week
+        end_of_week beginning_of_month end_of_month beginning_of_year
+        end_of_year next_week prev_week next_month prev_month
+        tomorrow yesterday all_day all_week all_month advance
+        ago since change to_fs
+      ].freeze
+      AS_BY_CLASS = {
+        "Integer" => AS_NUMERIC, "Float" => AS_NUMERIC, "Numeric" => AS_NUMERIC,
+        "String" => AS_STRING, "Symbol" => AS_STRING,
+        "Hash" => AS_HASH, "Array" => AS_ARRAY,
+        "Time" => AS_TIMEDATE, "Date" => AS_TIMEDATE,
+        "DateTime" => AS_TIMEDATE, "ActiveSupport::TimeWithZone" => AS_TIMEDATE
+      }.freeze
+      private_constant :AS_NUMERIC, :AS_STRING, :AS_HASH, :AS_ARRAY, :AS_TIMEDATE
+
+      # ActiveRecord query-builder methods. When flagged on an
+      # `Array[...]` receiver they signal a relation misinference.
+      AR_QUERY_METHODS = %w[
+        where joins includes preload eager_load references select
+        order reorder distinct group having limit offset pluck
+        find_by find_each find_in_batches in_batches none rewhere
+        unscope merge except_query extending
+      ].freeze
+      private_constant :AR_QUERY_METHODS
+
+      SYSTEMIC_THRESHOLD = 8       # (file, rule) count → "systemic"
+      MONKEY_PATCH_MIN_FILES = 3   # same (method, receiver) across N files
+      GENUINE_BUG_MAX_COUNT = 5    # rule total ≤ N → "likely genuine bug"
+      private_constant :SYSTEMIC_THRESHOLD, :MONKEY_PATCH_MIN_FILES, :GENUINE_BUG_MAX_COUNT
+
+      # @param diagnostics [Array<Analysis::Diagnostic>]
+      # @return [Array<Hint>]
+      def recognise(diagnostics)
+        claimed = {}.compare_by_identity
+        recognisers.filter_map do |recogniser|
+          pool = diagnostics.reject { |d| claimed[d] }
+          hint, matched = send(recogniser, pool)
+          next unless hint
+
+          matched.each { |d| claimed[d] = true }
+          hint
+        end
+      end
+
+      # H4 (ActiveRecord query methods) runs before H2 (generic
+      # 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.
+      def recognisers
+        %i[h1_activesupport h4_ar_relation h3_gem_without_rbs
+           h2_monkey_patch h5_systemic_cluster h6_genuine_bugs]
+      end
+
+      # --- H1 — likely ActiveSupport core_ext --------------------
+      def h1_activesupport(pool)
+        matched = pool.select do |d|
+          parsed = parse_undefined_method(d)
+          parsed && activesupport?(parsed[:receiver], parsed[:method])
+        end
+        return nil if matched.empty?
+
+        [Hint.new(
+          id: "activesupport-core-ext", confidence: :likely,
+          diagnostic_count: matched.size,
+          summary: "undefined-method on core classes (#{top_methods(matched)}) — " \
+                   "ActiveSupport monkey-patches these",
+          action: "Add rigor-activesupport-core-ext to `plugins:` in .rigor.yml " \
+                  "(it is an RBS-bundle plugin — ADR-25)."
+        ), matched]
+      end
+
+      # --- H2 — likely a project monkey-patch / refinement -------
+      def h2_monkey_patch(pool)
+        groups = undefined_method_groups(pool).select do |(_method, _recv), diags|
+          diags.map(&:path).uniq.size >= MONKEY_PATCH_MIN_FILES
+        end
+        return nil if groups.empty?
+
+        matched = groups.values.flatten(1)
+        [Hint.new(
+          id: "project-monkey-patch", confidence: :possible,
+          diagnostic_count: matched.size,
+          summary: "same method undefined across many files " \
+                   "(#{describe_groups(groups)}) — likely a project core-ext / refinement",
+          action: "Register the defining file via `pre_eval:` (ADR-17), " \
+                  "or add an RBS overlay for the method."
+        ), matched]
+      end
+
+      # --- H3 — gem ships no RBS ---------------------------------
+      def h3_gem_without_rbs(pool)
+        notice = pool.find { |d| d.message.match?(/gem\(s\).*have no RBS available/) }
+        return nil unless notice
+
+        count = notice.message[/\A(\d+) gem/, 1] || "some"
+        [Hint.new(
+          id: "gem-without-rbs", confidence: :likely, diagnostic_count: 1,
+          summary: "#{count} Gemfile.lock gem(s) ship no RBS — undefined-method " \
+                   "diagnostics on their classes are expected, not bugs",
+          action: "`rbs collection install`, ship `sig/` in the gem, or opt the " \
+                  "gem into `dependencies.source_inference:` (ADR-10)."
+        ), [notice]]
+      end
+
+      # --- H4 — possible ActiveRecord relation misinference ------
+      def h4_ar_relation(pool)
+        matched = pool.select do |d|
+          parsed = parse_undefined_method(d)
+          parsed && AR_QUERY_METHODS.include?(parsed[:method]) &&
+            parsed[:receiver].start_with?("Array[")
+        end
+        return nil if matched.empty?
+
+        [Hint.new(
+          id: "activerecord-relation-misinference", confidence: :possible,
+          diagnostic_count: matched.size,
+          summary: "ActiveRecord query methods (#{top_methods(matched)}) flagged " \
+                   "on an `Array[...]` receiver",
+          action: "Enable rigor-activerecord; if it persists the receiver is an " \
+                  "engine misinference (an AR relation read as Array) — worth a Rigor issue."
+        ), matched]
+      end
+
+      # --- H5 — systemic single-file cluster ---------------------
+      def h5_systemic_cluster(pool)
+        bucket = pool.group_by { |d| [d.path, rule_of(d)] }
+                     .select { |_key, diags| diags.size >= SYSTEMIC_THRESHOLD }
+                     .max_by { |_key, diags| diags.size }
+        return nil unless bucket
+
+        (path, rule), matched = bucket
+        [Hint.new(
+          id: "systemic-file-cluster", confidence: :likely,
+          diagnostic_count: matched.size,
+          summary: "#{matched.size}× `#{rule}` concentrated in #{path}",
+          action: "Likely systemic in this file — one fix may clear many; " \
+                  "or a strong baseline candidate (ADR-22)."
+        ), matched]
+      end
+
+      # --- H6 — low-count scattered rules = likely genuine bugs --
+      def h6_genuine_bugs(pool)
+        small = pool.group_by { |d| rule_of(d) }
+                    .select { |rule, diags| rule && diags.size.between?(1, GENUINE_BUG_MAX_COUNT) }
+        return nil if small.empty?
+
+        matched = small.values.flatten(1)
+        rules = small.map { |rule, diags| "#{rule}×#{diags.size}" }.sort.join(", ")
+        [Hint.new(
+          id: "genuine-bugs", confidence: :likely,
+          diagnostic_count: matched.size,
+          summary: "low-count, scattered rules (#{rules})",
+          action: "Review these first — low-count diagnostics are usually the " \
+                  "localised bugs Rigor caught, not systemic noise."
+        ), matched]
+      end
+
+      # --- shared helpers ----------------------------------------
+
+      # WD3 / slice 4: prefer the structured `receiver_type` /
+      # `method_name` fields the `call.undefined-method` rule now
+      # populates; fall back to parsing the message only when they
+      # are absent (older diagnostics, plugin-emitted rules). Either
+      # way the receiver token is normalised through `receiver_class`.
+      def parse_undefined_method(diag)
+        return nil unless rule_of(diag) == UNDEFINED_METHOD_RULE
+
+        method, receiver_token = structured_undefined_method(diag) ||
+                                 message_undefined_method(diag)
+        return nil unless method
+
+        receiver = receiver_class(receiver_token)
+        return nil unless receiver
+
+        { method: method, receiver: receiver }
+      end
+
+      def structured_undefined_method(diag)
+        return nil unless diag.method_name && diag.receiver_type
+
+        [diag.method_name, diag.receiver_type]
+      end
+
+      def message_undefined_method(diag)
+        m = UNDEF_METHOD.match(diag.message)
+        m && [m[1], m[2]]
+      end
+
+      # Normalises a message receiver token to a class name.
+      # Integer / string / symbol literals fold to their class;
+      # `Foo[...]` keeps the `Array[...]` form (H4 needs it);
+      # `singleton(Foo)` and bare `Foo` fold to `Foo`.
+      def receiver_class(token)
+        t = token.strip
+        return "Integer" if t.match?(/\A-?\d+\z/)
+        return "Float"   if t.match?(/\A-?\d+\.\d+\z/)
+        return "String"  if t.start_with?('"', "'")
+        return "Symbol"  if t.start_with?(":")
+
+        singleton = t[/\Asingleton\(([\w:]+)\)\z/, 1]
+        return singleton if singleton
+        return t if t.start_with?("Array[")
+
+        nominal = t[/\A([\w:]+)\[/, 1]
+        return nominal if nominal
+        return t if t.match?(/\A[\w:]+\z/)
+
+        nil
+      end
+
+      def activesupport?(receiver, method)
+        AS_BY_CLASS[receiver]&.include?(method) || false
+      end
+
+      def undefined_method_groups(pool)
+        pairs = pool.filter_map do |d|
+          parsed = parse_undefined_method(d)
+          parsed ? [[parsed[:method], parsed[:receiver]], d] : nil
+        end
+        pairs.group_by(&:first).transform_values { |group| group.map(&:last) }
+      end
+
+      def describe_groups(groups)
+        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(" ")
+      end
+
+      def rule_of(diag)
+        diag.qualified_rule
+      end
+    end
+  end
+end

data/lib/rigor/triage/hint.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Triage
+    # ADR-23 — one heuristic finding produced by the {Catalogue}.
+    #
+    # - `id`     — stable kebab-case identifier (`activesupport-core-ext`, …).
+    # - `confidence` — `:likely` or `:possible`. Surfaced in the
+    #   `[likely …]` / `[possible …]` report framing; a hint is
+    #   signal, never a verdict.
+    # - `diagnostic_count` — size of the matched cluster.
+    # - `summary` — one-line evidence string (what was matched).
+    # - `action`  — the suggested next step, phrased imperatively
+    #   for a human / agent (ADR-23 WD4: triage never acts itself).
+    Hint = Data.define(:id, :confidence, :diagnostic_count, :summary, :action) do
+      def to_h
+        {
+          "id" => id,
+          "confidence" => confidence.to_s,
+          "diagnostic_count" => diagnostic_count,
+          "summary" => summary,
+          "action" => action
+        }
+      end
+    end
+  end
+end