rigortype 0.2.7 → 0.2.8

data/lib/rigor/source/literals.rb

@@ -6,26 +6,21 @@ module Rigor
   module Source
     # Extracts literal Symbol/String values from Prism call arguments.
     #
-    # The "is this argument a literal `:sym` or `"str"`, and if so what
-    # Symbol does it name?" question recurs across the analyzer (sig-gen
-    # observation, attr-accessor generation, synthetic-method scanning)
-    # and across nearly every DSL plugin (`state :draft`,
-    # `has_one_attached :avatar`, `validate_presence_of(:name)`, …). This
-    # module is the one place that answers it, so the
-    # `node.unescaped.to_sym if SymbolNode || StringNode` shape is written
-    # once rather than copied per call site.
+    # The "is this argument a literal `:sym` or `"str"`, and if so what Symbol does it name?" question
+    # recurs across the analyzer (sig-gen observation, attr-accessor generation, synthetic-method scanning)
+    # and across nearly every DSL plugin (`state :draft`, `has_one_attached :avatar`,
+    # `validate_presence_of(:name)`, …). This module is the one place that answers it, so the
+    # `node.unescaped.to_sym if SymbolNode || StringNode` shape is written once rather than copied per call
+    # site.
     #
-    # `#unescaped` (not `#value`) is used deliberately so an interpolation-
-    # free `"foo"` / `:foo` round-trips to `:foo` consistently for both
-    # node kinds.
+    # `#unescaped` (not `#value`) is used deliberately so an interpolation- free `"foo"` / `:foo`
+    # round-trips to `:foo` consistently for both node kinds.
     #
-    # The surface is a small grid over two axes — which node kinds are
-    # accepted (`SymbolNode` only, or `SymbolNode`/`StringNode`) and what
-    # the caller wants back (the interned `Symbol`, or the raw `String`
-    # name). The SymbolNode-only forms ({.symbol} / {.symbol_name}) exist
-    # so a DSL that distinguishes `state :draft` from `state "draft"`
-    # keeps that distinction instead of silently widening to accept the
-    # string literal.
+    # The surface is a small grid over two axes — which node kinds are accepted (`SymbolNode` only, or
+    # `SymbolNode`/`StringNode`) and what the caller wants back (the interned `Symbol`, or the raw `String`
+    # name). The SymbolNode-only forms ({.symbol} / {.symbol_name}) exist so a DSL that distinguishes `state
+    # :draft` from `state "draft"` keeps that distinction instead of silently widening to accept the string
+    # literal.
     #
     # | accepts            | → Symbol            | → String                 |
     # | ------------------ | ------------------- | ------------------------ |
@@ -34,8 +29,8 @@ module Rigor
     module Literals
       module_function
 
-      # The Symbol a literal `Prism::SymbolNode` / `Prism::StringNode`
-      # names, or `nil` for any other node (including `nil`).
+      # The Symbol a literal `Prism::SymbolNode` / `Prism::StringNode` names, or `nil` for any other node
+      # (including `nil`).
       #
       # @param node [Prism::Node, nil]
       # @return [Symbol, nil]
@@ -45,12 +40,10 @@ module Rigor
         node.unescaped.to_sym
       end
 
-      # The String a literal `Prism::SymbolNode` / `Prism::StringNode`
-      # names, or `nil` for any other node (including `nil`). The
-      # String-returning sibling of {.symbol_or_string} — for callers
-      # that key on the raw name rather than the interned Symbol (route
-      # helpers, factory names, filter targets). `#unescaped` round-trips
-      # an interpolation-free `:foo` / `"foo"` to `"foo"` for both kinds.
+      # The String a literal `Prism::SymbolNode` / `Prism::StringNode` names, or `nil` for any other node
+      # (including `nil`). The String-returning sibling of {.symbol_or_string} — for callers that key on the
+      # raw name rather than the interned Symbol (route helpers, factory names, filter targets).
+      # `#unescaped` round-trips an interpolation-free `:foo` / `"foo"` to `"foo"` for both kinds.
       #
       # @param node [Prism::Node, nil]
       # @return [String, nil]
@@ -60,11 +53,9 @@ module Rigor
         node.unescaped
       end
 
-      # The Symbol a literal `Prism::SymbolNode` names, or `nil` for any
-      # other node (including a `Prism::StringNode` and `nil`). Stricter
-      # than {.symbol_or_string}: a DSL that accepts only `:draft` and
-      # not `"draft"` keeps that distinction by reaching for this rather
-      # than the Symbol-or-String form.
+      # The Symbol a literal `Prism::SymbolNode` names, or `nil` for any other node (including a
+      # `Prism::StringNode` and `nil`). Stricter than {.symbol_or_string}: a DSL that accepts only `:draft`
+      # and not `"draft"` keeps that distinction by reaching for this rather than the Symbol-or-String form.
       #
       # @param node [Prism::Node, nil]
       # @return [Symbol, nil]
@@ -74,9 +65,8 @@ module Rigor
         node.unescaped.to_sym
       end
 
-      # The String a literal `Prism::SymbolNode` names, or `nil` for any
-      # other node (including a `Prism::StringNode` and `nil`). The
-      # String-returning sibling of {.symbol} — SymbolNode-only, but the
+      # The String a literal `Prism::SymbolNode` names, or `nil` for any other node (including a
+      # `Prism::StringNode` and `nil`). The String-returning sibling of {.symbol} — SymbolNode-only, but the
       # caller wants the raw name rather than the interned Symbol.
       #
       # @param node [Prism::Node, nil]
@@ -87,9 +77,8 @@ module Rigor
         node.unescaped
       end
 
-      # Every literal Symbol/String positional argument of a call, in
-      # source order. Non-literal arguments are dropped. Returns `[]` when
-      # the call has no argument list.
+      # Every literal Symbol/String positional argument of a call, in source order. Non-literal arguments
+      # are dropped. Returns `[]` when the call has no argument list.
       #
       # @param call_node [Prism::CallNode, nil]
       # @return [Array<Symbol>]
@@ -100,11 +89,9 @@ module Rigor
         args.filter_map { |arg| symbol_or_string(arg) }
       end
 
-      # Whether a node is a literal `Prism::SymbolNode` that names `name`.
-      # The key-comparison counterpart to {.symbol_name} — for callers
-      # that need a predicate rather than an extraction (hash-key matching
-      # in keyword or assoc argument positions, e.g.
-      # `el.is_a?(AssocNode) && symbol_named?(el.key, "required")`).
+      # Whether a node is a literal `Prism::SymbolNode` that names `name`. The key-comparison counterpart to
+      # {.symbol_name} — for callers that need a predicate rather than an extraction (hash-key matching in
+      # keyword or assoc argument positions, e.g. `el.is_a?(AssocNode) && symbol_named?(el.key, "required")`).
       # Uses `#unescaped` (not `#value`) for round-trip consistency.
       #
       # @param node [Prism::Node, nil]
@@ -114,9 +101,8 @@ module Rigor
         node.is_a?(Prism::SymbolNode) && node.unescaped == name
       end
 
-      # The literal Symbol/String at positional `index`, or `nil` when the
-      # call has no argument list, the index is out of range, or the
-      # argument there is not a literal Symbol/String.
+      # The literal Symbol/String at positional `index`, or `nil` when the call has no argument list, the
+      # index is out of range, or the argument there is not a literal Symbol/String.
       #
       # @param call_node [Prism::CallNode, nil]
       # @param index [Integer]

data/lib/rigor/source/node_locator.rb

@@ -6,17 +6,16 @@ module Rigor
   module Source
     # Locates the deepest Prism AST node enclosing a given source position.
     #
-    # The locator works on byte offsets internally so that multibyte source
-    # text behaves consistently with Prism, which itself reports offsets in
-    # bytes. Convenience constructors translate from `(line, column)` pairs.
+    # The locator works on byte offsets internally so that multibyte source text behaves consistently with
+    # Prism, which itself reports offsets in bytes. Convenience constructors translate from `(line, column)`
+    # pairs.
     #
-    # Lines are 1-indexed (matching editor / Prism / gcc conventions).
-    # Columns are 1-indexed when supplied via the `(line, column)` API; this
-    # matches the canonical `file.rb:line:col` form most tools emit. Internal
-    # offsets remain 0-indexed bytes.
+    # Lines are 1-indexed (matching editor / Prism / gcc conventions). Columns are 1-indexed when supplied
+    # via the `(line, column)` API; this matches the canonical `file.rb:line:col` form most tools emit.
+    # Internal offsets remain 0-indexed bytes.
     #
-    # The locator is read-only: a single instance binds to one source buffer
-    # and AST root, and queries are pure functions of the byte offset.
+    # The locator is read-only: a single instance binds to one source buffer and AST root, and queries are
+    # pure functions of the byte offset.
     class NodeLocator
       class OutOfRangeError < StandardError; end
 
@@ -58,8 +57,7 @@ module Rigor
         descend(@root, offset)
       end
 
-      # Translate a `(line, column)` pair into a 0-indexed byte offset for the
-      # bound source buffer.
+      # Translate a `(line, column)` pair into a 0-indexed byte offset for the bound source buffer.
       def position_to_offset(line, column)
         raise ArgumentError, "source buffer required for position lookup" if @source.nil?
         raise OutOfRangeError, "line must be >= 1, got #{line}" if line < 1

data/lib/rigor/source/node_walker.rb

@@ -6,14 +6,12 @@ module Rigor
   module Source
     # Yields every `Prism::Node` reachable from a root in DFS pre-order.
     #
-    # The walker is the source-positioning analogue to `NodeLocator`: where the
-    # locator answers "what node is at this point?", the walker enumerates the
-    # full set of Prism nodes for tooling that needs to operate on each one
-    # (coverage probes, lint passes, IDE outlines).
+    # The walker is the source-positioning analogue to `NodeLocator`: where the locator answers "what node
+    # is at this point?", the walker enumerates the full set of Prism nodes for tooling that needs to
+    # operate on each one (coverage probes, lint passes, IDE outlines).
     #
-    # Non-Prism children (literals embedded in node attributes, virtual nodes,
-    # or `nil` slots) are silently skipped so callers can rely on every yielded
-    # value responding to the `Prism::Node` API.
+    # Non-Prism children (literals embedded in node attributes, virtual nodes, or `nil` slots) are silently
+    # skipped so callers can rely on every yielded value responding to the `Prism::Node` API.
     module NodeWalker
       module_function
 
@@ -33,12 +31,10 @@ module Rigor
         node.compact_child_nodes.each { |child| walk(child, &) }
       end
 
-      # Like {.each}, but also yields the node's lexical ancestor chain
-      # (outermost first, EXCLUDING the node itself). The yielded
-      # `ancestors` array is the live descent stack — callers that retain
-      # it past the block invocation MUST copy it (`Plugin::NodeContext`
-      # does). Used by the plugin engine to give `node_rule` blocks their
-      # enclosing class / method / block context (ADR-37 slice 1d).
+      # Like {.each}, but also yields the node's lexical ancestor chain (outermost first, EXCLUDING the node
+      # itself). The yielded `ancestors` array is the live descent stack — callers that retain it past the
+      # block invocation MUST copy it (`Plugin::NodeContext` does). Used by the plugin engine to give
+      # `node_rule` blocks their enclosing class / method / block context (ADR-37 slice 1d).
       #
       # @yieldparam node [Prism::Node]
       # @yieldparam ancestors [Array<Prism::Node>]

data/lib/rigor/source.rb

@@ -2,10 +2,9 @@
 
 # Source-text and AST positioning utilities.
 #
-# Anything that maps between a Ruby source buffer and Prism AST nodes belongs
-# here. The contents of this namespace deliberately stay independent of the
-# inference engine so that future tooling (LSP, refactoring helpers, doc
-# extractors) can reuse the same primitives without dragging in `Rigor::Type`.
+# Anything that maps between a Ruby source buffer and Prism AST nodes belongs here. The contents of this
+# namespace deliberately stay independent of the inference engine so that future tooling (LSP, refactoring
+# helpers, doc extractors) can reuse the same primitives without dragging in `Rigor::Type`.
 module Rigor
   module Source
   end

data/lib/rigor/testing.rb

@@ -3,21 +3,18 @@
 module Rigor
   # Slice 7 phase 19 — PHPStan-style typing helpers.
   #
-  # `Rigor::Testing` ships two runtime no-op helpers that serve
-  # as anchors for static-analysis diagnostics:
-  #
-  # - `dump_type(value)` — returns `value` unchanged at runtime.
-  #   The Rigor analyzer surfaces an `:info`-severity diagnostic
-  #   at the call site showing the inferred type of `value` so
-  #   the user can see what the engine sees at that program point.
-  # - `assert_type(expected, value)` — returns `value` unchanged
-  #   at runtime. The analyzer compares `value`'s inferred type
-  #   (rendered through `Rigor::Type#describe(:short)`) against
-  #   the literal `expected` String; a mismatch produces an
-  #   `:error`-severity diagnostic. This lets a user-written
-  #   fixture be self-asserting: `rigor check fixture.rb` exits
-  #   non-zero exactly when the engine's inference drifts from
-  #   what the fixture documents.
+  # `Rigor::Testing` ships two runtime no-op helpers that serve as anchors for
+  # static-analysis diagnostics:
+  #
+  # - `dump_type(value)` — returns `value` unchanged at runtime. The Rigor analyzer surfaces
+  #   an `:info`-severity diagnostic at the call site showing the inferred type of `value`
+  #   so the user can see what the engine sees at that program point.
+  # - `assert_type(expected, value)` — returns `value` unchanged at runtime. The analyzer
+  #   compares `value`'s inferred type (rendered through `Rigor::Type#describe(:short)`)
+  #   against the literal `expected` String; a mismatch produces an `:error`-severity
+  #   diagnostic. This lets a user-written fixture be self-asserting: `rigor check
+  #   fixture.rb` exits non-zero exactly when the engine's inference drifts from what the
+  #   fixture documents.
   #
   # Three usage shapes are recognised by the static rules:
   #
@@ -36,9 +33,8 @@ module Rigor
   #   Rigor.dump_type(x)
   #   Rigor.assert_type("Constant[\"hello\"]", x)
   #
-  # All three resolve to the same no-op runtime body, so a
-  # fixture may freely run under MRI without depending on the
-  # analyzer being present.
+  # All three resolve to the same no-op runtime body, so a fixture may freely run under MRI
+  # without depending on the analyzer being present.
   module Testing
     module_function
 
@@ -52,8 +48,8 @@ module Rigor
   end
 
   class << self
-    # Convenience aliases on `Rigor` itself, so fixtures can
-    # write `Rigor.dump_type(x)` without an `include` line.
+    # Convenience aliases on `Rigor` itself, so fixtures can write `Rigor.dump_type(x)`
+    # without an `include` line.
     def dump_type(value)
       Testing.dump_type(value)
     end

data/lib/rigor/triage/catalogue.rb

@@ -6,17 +6,13 @@ 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).
+    # {.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" —
+    # 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
@@ -27,9 +23,8 @@ module Rigor
       # `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).
+      # 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
@@ -72,8 +67,8 @@ module Rigor
       }.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.
+      # 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
@@ -87,16 +82,12 @@ module Rigor
       GENUINE_BUG_MAX_COUNT = 5    # rule total ≤ N → "likely genuine bug"
       private_constant :SYSTEMIC_THRESHOLD, :MONKEY_PATCH_MIN_FILES, :GENUINE_BUG_MAX_COUNT
 
-      # WD6 (ADR-23): H5 (systemic cluster) and H6 (genuine bugs) are
-      # the only count-based, severity-agnostic recognisers, so they
-      # alone risk reading plugin recognition trace (`:info`
-      # `*.model-call` / `*.helper`, …) as a "systemic cluster" or a
-      # "genuine bug" — frightening working code. They are guarded
-      # against `:info` unless `include_info` restores the pre-v0.2.3
-      # behaviour. Every other recogniser keys on an error/warning rule
-      # (H1/H2/H2K/H4/H7) or intentionally reads an info notice
-      # (H3 — the `gem-without-rbs` `rbs.coverage.missing-gem`), so the
-      # full pool is correct for them.
+      # WD6 (ADR-23): H5 (systemic cluster) and H6 (genuine bugs) are the only count-based, severity-agnostic
+      # recognisers, so they alone risk reading plugin recognition trace (`:info` `*.model-call` / `*.helper`, …) as a
+      # "systemic cluster" or a "genuine bug" — frightening working code. They are guarded against `:info` unless
+      # `include_info` restores the pre-v0.2.3 behaviour. Every other recogniser keys on an error/warning rule
+      # (H1/H2/H2K/H4/H7) or intentionally reads an info notice (H3 — the `gem-without-rbs` `rbs.coverage.missing-gem`),
+      # so the full pool is correct for them.
       INFO_GUARDED = %i[h5_systemic_cluster h6_genuine_bugs].freeze
       private_constant :INFO_GUARDED
 
@@ -116,19 +107,14 @@ module Rigor
         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.
+      # 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.
       #
-      # 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.
+      # 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
            h2k_known_project_patch h2_monkey_patch h7_unresolved_toplevel
@@ -154,13 +140,10 @@ module Rigor
       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.
+      # 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?
@@ -231,13 +214,10 @@ module Rigor
       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.
+      # 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?
@@ -290,11 +270,9 @@ module Rigor
 
       # --- 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`.
+      # 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
 
@@ -319,8 +297,7 @@ module Rigor
         m && [m[1], m[2]]
       end
 
-      # Normalises a message receiver token to a class name. The fold
-      # logic is shared with the selector axis — see
+      # Normalises a message receiver token to a class name. The fold logic is shared with the selector axis — see
       # {Triage.normalize_receiver}.
       def receiver_class(token)
         Triage.normalize_receiver(token)
@@ -342,10 +319,9 @@ module Rigor
         groups.keys.first(3).map { |method, recv| "`#{method}` on #{recv}" }.join(", ")
       end
 
-      # `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).
+      # `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)

data/lib/rigor/triage.rb

@@ -4,46 +4,34 @@ require_relative "triage/hint"
 require_relative "triage/catalogue"
 
 module Rigor
-  # ADR-23 — diagnostic triage. Aggregates a `rigor check`
-  # diagnostic stream into the data behind the `rigor triage`
-  # report: a rule-ID distribution, per-file hotspots, and the
-  # heuristic hint catalogue ({Triage::Catalogue}).
+  # ADR-23 — diagnostic triage. Aggregates a `rigor check` diagnostic stream into the data behind the `rigor triage`
+  # report: a rule-ID distribution, per-file hotspots, and the heuristic hint catalogue ({Triage::Catalogue}).
   #
-  # Pure over the diagnostic stream — no second analysis pass, no
-  # analyzer internals. `Triage.analyze` is the single entry point;
-  # rendering is {CLI::TriageRenderer}'s job.
+  # Pure over the diagnostic stream — no second analysis pass, no analyzer internals. `Triage.analyze` is the single
+  # entry point; rendering is {CLI::TriageRenderer}'s job.
   module Triage
     UNCATEGORISED = "(uncategorised)"
 
     Summary = Data.define(:total, :error, :warning, :info)
     RuleCount = Data.define(:rule, :count)
     Hotspot = Data.define(:file, :count, :by_rule)
-    # A (receiver-class, method) dispatch target the diagnostics
-    # cluster on, built from the structured `Diagnostic#receiver_type`
-    # / `#method_name` fields — never from message-string parsing.
-    # `receiver` is nil for method-only diagnostics (a toplevel call,
-    # a `def`-side return / override finding that has no call
-    # receiver); `files` is the distinct-file count (a systemic vs.
-    # localised signal); `rules` is the per-rule breakdown.
+    # A (receiver-class, method) dispatch target the diagnostics cluster on, built from the structured
+    # `Diagnostic#receiver_type` / `#method_name` fields — never from message-string parsing. `receiver` is nil for
+    # method-only diagnostics (a toplevel call, a `def`-side return / override finding that has no call receiver);
+    # `files` is the distinct-file count (a systemic vs. localised signal); `rules` is the per-rule breakdown.
     Selector = Data.define(:receiver, :method_name, :count, :files, :rules)
     Report = Data.define(:summary, :distribution, :selectors, :hotspots, :hints, :include_info)
 
     module_function
 
-    # WD6 (ADR-23): the volume views — distribution / selectors /
-    # hotspots — route only the *actionable* diagnostics (error +
-    # warning) by default. Plugin-emitted `:info` diagnostics are
-    # overwhelmingly recognition trace (`plugin.activerecord.model-call`,
-    # `plugin.rails-routes.helper`, …) — positive "Rigor resolved this
-    # call" records, not problems — and on a real Rails app they swamp
-    # the genuine error/warning signal (the field trip: 257 of 267
-    # diagnostics were such trace) and invert the hotspot ranking
-    # towards the files with the *most working* code. The summary still
-    # reports the full info count, and `include_info: true` (the
-    # `--include-info` flag) restores the pre-v0.2.3 behaviour. Hints
-    # always see the full stream so the `gem-without-rbs` notice (an
-    # info-severity `rbs.coverage.missing-gem`) survives; the
-    # count-based H5/H6 recognisers guard against info themselves so
+    # WD6 (ADR-23): the volume views — distribution / selectors / hotspots — route only the *actionable* diagnostics
+    # (error + warning) by default. Plugin-emitted `:info` diagnostics are overwhelmingly recognition trace
+    # (`plugin.activerecord.model-call`, `plugin.rails-routes.helper`, …) — positive "Rigor resolved this call" records,
+    # not problems — and on a real Rails app they swamp the genuine error/warning signal (the field trip: 257 of 267
+    # diagnostics were such trace) and invert the hotspot ranking towards the files with the *most working* code. The
+    # summary still reports the full info count, and `include_info: true` (the `--include-info` flag) restores the
+    # pre-v0.2.3 behaviour. Hints always see the full stream so the `gem-without-rbs` notice (an info-severity
+    # `rbs.coverage.missing-gem`) survives; the count-based H5/H6 recognisers guard against info themselves so
     # recognition trace never reads as a bug.
     #
     # @param diagnostics [Array<Analysis::Diagnostic>]
@@ -63,8 +51,8 @@ module Rigor
       )
     end
 
-    # Diagnostics without a `rule` (parse errors, internal-analyzer
-    # errors) bucket under a single sentinel rather than vanishing.
+    # Diagnostics without a `rule` (parse errors, internal-analyzer errors) bucket under a single sentinel rather than
+    # vanishing.
     def rule_key(diagnostic)
       diagnostic.qualified_rule || UNCATEGORISED
     end
@@ -85,15 +73,11 @@ module Rigor
                  .sort_by { |row| [-row.count, row.rule] }
     end
 
-    # The class/method aggregation axis (ADR-23 follow-up). Groups
-    # every diagnostic that carries a `method_name` by its
-    # `(receiver_type, method_name)` pair so a consumer can answer
-    # "which method / class concentrates the diagnostics?" with a
-    # `jq` query over the JSON instead of parsing message text.
-    # Method-only diagnostics (nil `receiver_type`) keep a null
-    # `receiver` and still group by method. The full list is
-    # returned uncapped — the JSON is the agent-facing surface; the
-    # text renderer caps its own rows.
+    # The class/method aggregation axis (ADR-23 follow-up). Groups every diagnostic that carries a `method_name` by its
+    # `(receiver_type, method_name)` pair so a consumer can answer "which method / class concentrates the diagnostics?"
+    # with a `jq` query over the JSON instead of parsing message text. Method-only diagnostics (nil `receiver_type`)
+    # keep a null `receiver` and still group by method. The full list is returned uncapped — the JSON is the
+    # agent-facing surface; the text renderer caps its own rows.
     def build_selectors(diagnostics)
       diagnostics.select(&:method_name)
                  .group_by { |d| [normalize_receiver(d.receiver_type) || d.receiver_type, d.method_name.to_s] }
@@ -101,16 +85,12 @@ module Rigor
                  .sort_by { |s| [-s.count, s.receiver.to_s, s.method_name] }
     end
 
-    # Folds a receiver token — a `Diagnostic#receiver_type` display
-    # string or a message-parsed token — to the class the diagnostics
-    # should bucket under, so the selector axis does not fragment one
-    # method across every distinct literal receiver. String / integer
-    # / float / symbol literals collapse to their class; `singleton(C)`
-    # and a bare `C` fold to `C`; a generic `C[...]` keeps the
-    # `Array[String]` element form (the AR-relation heuristic keys on
-    # it). Returns nil for a token it cannot reduce to a class (a
-    # union display, an inferred shape) — the caller keeps the raw
-    # string then, never losing the row. Shared with {Catalogue}.
+    # Folds a receiver token — a `Diagnostic#receiver_type` display string or a message-parsed token — to the class the
+    # diagnostics should bucket under, so the selector axis does not fragment one method across every distinct literal
+    # receiver. String / integer / float / symbol literals collapse to their class; `singleton(C)` and a bare `C` fold
+    # to `C`; a generic `C[...]` keeps the `Array[String]` element form (the AR-relation heuristic keys on it). Returns
+    # nil for a token it cannot reduce to a class (a union display, an inferred shape) — the caller keeps the raw string
+    # then, never losing the row. Shared with {Catalogue}.
     def normalize_receiver(token)
       return nil if token.nil?
 
@@ -170,9 +150,8 @@ module Rigor
           { "file" => h.file, "count" => h.count, "by_rule" => h.by_rule }
         end,
         "hints" => report.hints.map(&:to_h),
-        # WD6: false means distribution / selectors / hotspots above
-        # exclude `:info` (their counts will not sum to summary.total);
-        # the summary's `info` field still reports the full count.
+        # WD6: false means distribution / selectors / hotspots above exclude `:info` (their counts will not sum to
+        # summary.total); the summary's `info` field still reports the full count.
         "include_info" => report.include_info
       }
     end