rigortype 0.2.7 → 0.2.8

data/lib/rigor/inference/struct_fold_safety.rb

@@ -6,58 +6,49 @@ require_relative "../source/constant_path"
 
 module Rigor
   module Inference
-    # ADR-48 Struct follow-up, slice 3 — the fold-safe-local scan. Determines,
-    # for a single local-variable scope (a method body or the program
-    # top-level), which `Struct`-materialised locals are **provably never
-    # mutated, aliased, or escaped** and so may have their member reads folded
-    # off a *stored* binding (relaxing the slice-2 fresh-receiver gate).
+    # ADR-48 Struct follow-up, slice 3 — the fold-safe-local scan. Determines, for a single local-variable scope (a
+    # method body or the program top-level), which `Struct`-materialised locals are **provably never mutated, aliased,
+    # or escaped** and so may have their member reads folded off a *stored* binding (relaxing the slice-2 fresh-receiver
+    # gate).
     #
-    # The analysis is a conservative ALLOW-LIST, not a deny-list: a local is
-    # fold-safe only when *every* read of it is the receiver of a known-pure
-    # read call. Anything the scan does not recognise as a pure read — a
-    # setter, an `[]=` / operator-write, an argument / alias / container store
-    # / return (escape), or an unknown method call (which could mutate `self`
-    # internally) — disqualifies the local. A missed case therefore makes the
-    # scan over-conservative (no fold), **never unsound** (folding a mutated
-    # value) — the false-positive-safe direction.
+    # The analysis is a conservative ALLOW-LIST, not a deny-list: a local is fold-safe only when *every* read of it is
+    # the receiver of a known-pure read call. Anything the scan does not recognise as a pure read — a setter, an `[]=` /
+    # operator-write, an argument / alias / container store / return (escape), or an unknown method call (which could
+    # mutate `self` internally) — disqualifies the local. A missed case therefore makes the scan over-conservative (no
+    # fold), **never unsound** (folding a mutated value) — the false-positive-safe direction.
     #
-    # Soundness rests on a counting identity: a local `n` is fold-safe iff
-    # *every* `LocalVariableReadNode(n)` is the receiver of a pure-read call.
-    # Equivalently `total_reads(n) == pure_receiver_reads(n)`. Any other
-    # occurrence — `n` as a setter receiver (`n.x = v` is a `:x=` call, not a
-    # pure read), an `[]=`/operator-write receiver (the receiver read is not
-    # under a pure call), a call argument, an assignment RHS (alias), a
-    # container element, a bare value (return/escape) — leaves a read that is
-    # not a pure-receiver read, so the counts diverge.
+    # Soundness rests on a counting identity: a local `n` is fold-safe iff *every* `LocalVariableReadNode(n)` is the
+    # receiver of a pure-read call. Equivalently `total_reads(n) == pure_receiver_reads(n)`. Any other occurrence — `n`
+    # as a setter receiver (`n.x = v` is a `:x=` call, not a pure read), an `[]=`/operator-write receiver (the receiver
+    # read is not under a pure call), a call argument, an assignment RHS (alias), a container element, a bare value
+    # (return/escape) — leaves a read that is not a pure-receiver read, so the counts diverge.
     #
-    # See docs/notes/20260615-struct-folding-slice3-design.md and
-    # docs/adr/48-data-struct-value-folding.md § "Struct follow-up".
+    # See docs/notes/20260615-struct-folding-slice3-design.md and docs/adr/48-data-struct-value-folding.md § "Struct
+    # follow-up".
     module StructFoldSafety
       module_function
 
       EMPTY = Set.new.freeze
 
-      # The fixed `Struct` read methods that never mutate. A member-reader name
-      # (`:x`) is added per-local from the local's recorded layout. A setter
-      # (`:x=`), `:[]=`, `store`, `push`, etc. are deliberately absent.
+      # The fixed `Struct` read methods that never mutate. A member-reader name (`:x`) is added per-local from the
+      # local's recorded layout. A setter (`:x=`), `:[]=`, `store`, `push`, etc. are deliberately absent.
       FIXED_READS = %i[
         [] dig to_h to_hash to_a values members deconstruct deconstruct_keys
         == != eql? equal? hash inspect to_s size length frozen? each each_pair
         values_at with
       ].to_set.freeze
 
-      # Nested `def` / `class` / `module` bodies open a *new* local-variable
-      # scope, so the scan does not descend into them — a local of the same
-      # name there is a different binding. Blocks share the enclosing locals
-      # (closures), so the scan does descend into them.
+      # Nested `def` / `class` / `module` bodies open a *new* local-variable scope, so the scan does not descend into
+      # them — a local of the same name there is a different binding. Blocks share the enclosing locals (closures), so
+      # the scan does descend into them.
       def scope_boundary?(node)
         node.is_a?(Prism::DefNode) || node.is_a?(Prism::ClassNode) ||
           node.is_a?(Prism::ModuleNode) || node.is_a?(Prism::SingletonClassNode)
       end
 
       # @param root [Prism::Node, nil] the local-variable scope to scan.
-      # @param layout_lookup [#call] a `String -> Array[Symbol] | nil` resolver
-      #   mapping a constant receiver name to its struct member list.
+      # @param layout_lookup [#call] a `String -> Array[Symbol] | nil` resolver mapping a constant receiver name to its
+      #   struct member list.
       # @return [Set<Symbol>] the fold-safe local names.
       def fold_safe_locals(root, layout_lookup)
         return EMPTY if root.nil?
@@ -77,9 +68,8 @@ module Rigor
         safe.empty? ? EMPTY : safe.to_set
       end
 
-      # Pass 1 — record each local's single struct materialisation (its member
-      # set) and count its assignments. A local assigned more than once is
-      # later excluded (the static fold-safe set cannot track a rebinding).
+      # Pass 1 — record each local's single struct materialisation (its member set) and count its assignments. A local
+      # assigned more than once is later excluded (the static fold-safe set cannot track a rebinding).
       def collect_struct_locals(node, layout_lookup, members, writes)
         return if node.nil?
 
@@ -94,8 +84,7 @@ module Rigor
         end
       end
 
-      # Pass 2 — count, per recorded struct local, total reads vs. reads that
-      # are the receiver of a pure-read call.
+      # Pass 2 — count, per recorded struct local, total reads vs. reads that are the receiver of a pure-read call.
       def count_uses(node, members, total, pure)
         return if node.nil?
 
@@ -114,17 +103,15 @@ module Rigor
         end
       end
 
-      # A call is a pure read of the receiver when its name is a fixed Struct
-      # read or one of the receiver's member readers. Setters (`:x=`), `:[]=`,
-      # and any unknown method are excluded.
+      # A call is a pure read of the receiver when its name is a fixed Struct read or one of the receiver's member
+      # readers. Setters (`:x=`), `:[]=`, and any unknown method are excluded.
       def pure_read_call?(call_node, member_set)
         name = call_node.name
         FIXED_READS.include?(name) || member_set.include?(name)
       end
 
-      # The member set of a `<Struct chain>.new(...)` / `.[]` materialisation,
-      # or nil. Handles the inline `Struct.new(:a, :b).new(...)` form and the
-      # `Const.new(...)` form (resolved through the layout side-table).
+      # The member set of a `<Struct chain>.new(...)` / `.[]` materialisation, or nil. Handles the inline
+      # `Struct.new(:a, :b).new(...)` form and the `Const.new(...)` form (resolved through the layout side-table).
       def struct_materialization_members(value_node, layout_lookup)
         return nil unless value_node.is_a?(Prism::CallNode)
         return nil unless %i[new []].include?(value_node.name)
@@ -140,9 +127,8 @@ module Rigor
         end
       end
 
-      # The Symbol member set of a literal `Struct.new(:a, :b [, keyword_init:])`
-      # call, or nil. (A leading String name and the trailing options hash are
-      # ignored — only the literal-Symbol positionals contribute.)
+      # The Symbol member set of a literal `Struct.new(:a, :b [, keyword_init:])` call, or nil. (A leading String name
+      # and the trailing options hash are ignored — only the literal-Symbol positionals contribute.)
       def struct_new_member_set(call_node)
         return nil unless call_node.is_a?(Prism::CallNode) && call_node.name == :new
         return nil unless meta_constant?(call_node.receiver, :Struct)
@@ -167,8 +153,8 @@ module Rigor
         end
       end
 
-      # Yields each child to recurse into, skipping the subtree of a nested
-      # local-variable-scope boundary (a `def` / `class` / `module`).
+      # Yields each child to recurse into, skipping the subtree of a nested local-variable-scope boundary (a `def` /
+      # `class` / `module`).
       def each_local_scope_child(node)
         node.compact_child_nodes.each do |child|
           next if scope_boundary?(child)

data/lib/rigor/inference/synthetic_method.rb

@@ -2,24 +2,17 @@
 
 module Rigor
   module Inference
-    # ADR-16 Tier C output — one synthetic method declared by a
-    # plugin's `Plugin::Macro::HeredocTemplate` entry, after the
-    # pre-pass has interpolated the call-site literal symbol into
-    # the template name. Stored in {SyntheticMethodIndex} and
-    # consulted by {MethodDispatcher} below the RBS dispatch tier.
+    # ADR-16 Tier C output — one synthetic method declared by a plugin's `Plugin::Macro::HeredocTemplate` entry, after
+    # the pre-pass has interpolated the call-site literal symbol into the template name. Stored in
+    # {SyntheticMethodIndex} and consulted by {MethodDispatcher} below the RBS dispatch tier.
     #
-    # Per ADR-16 § WD13 (cost-bounded best-effort): method names
-    # emit with return types promoted by the dispatcher's Slice 6
-    # tiers — Slice 6a promotes via `origin_module` (TierB) and
-    # Slice 6b via `return_type` nominal lookup (TierC). The
-    # `return_type` string is preserved so promotion can resolve
-    # it without re-walking; `"untyped"` / `"void"` placeholders
-    # fall back to `Dynamic[Top]`.
+    # Per ADR-16 § WD13 (cost-bounded best-effort): method names emit with return types promoted by the dispatcher's
+    # Slice 6 tiers — Slice 6a promotes via `origin_module` (TierB) and Slice 6b via `return_type` nominal lookup
+    # (TierC). The `return_type` string is preserved so promotion can resolve it without re-walking; `"untyped"` /
+    # `"void"` placeholders fall back to `Dynamic[Top]`.
     #
-    # The `provenance` Hash carries debug / `--explain` metadata:
-    # plugin id, the template's call shape, and the source
-    # location of the originating DSL call. Surfaced through the
-    # dispatcher's `macro.tier_c.*` provenance markers.
+    # The `provenance` Hash carries debug / `--explain` metadata: plugin id, the template's call shape, and the source
+    # location of the originating DSL call. Surfaced through the dispatcher's `macro.tier_c.*` provenance markers.
     class SyntheticMethod
       INSTANCE = :instance
       SINGLETON = :singleton

data/lib/rigor/inference/synthetic_method_index.rb

@@ -4,43 +4,30 @@ require_relative "synthetic_method"
 
 module Rigor
   module Inference
-    # Frozen, Ractor-shareable lookup table for the synthetic
-    # methods emitted by ADR-16 Tier C declarations during a
-    # single `Analysis::Runner#run`. Constructed by the pre-pass
-    # scanner (see {SyntheticMethodScanner}) and consulted by
-    # {MethodDispatcher} below `RbsDispatch.try_dispatch` (per WD13:
-    # user-authored RBS overrides substrate synthesis).
+    # Frozen, Ractor-shareable lookup table for the synthetic methods emitted by ADR-16 Tier C declarations during a
+    # single `Analysis::Runner#run`. Constructed by the pre-pass scanner (see {SyntheticMethodScanner}) and consulted by
+    # {MethodDispatcher} below `RbsDispatch.try_dispatch` (per WD13: user-authored RBS overrides substrate synthesis).
     #
-    # The index is keyed by `(class_name, method_name, kind)`. A
-    # single key may resolve to multiple {SyntheticMethod} records
-    # if two plugins emit the same name (e.g. `rigor-dry-struct`
-    # and a hypothetical `rigor-dry-struct-extras` both registering
-    # the same attribute). Per ADR-16 WD11 / the WD-discussion in
-    # `## Open questions` the dispatcher uses first-wins by
-    # registration order; this index preserves that order in
-    # `lookup`'s return.
+    # The index is keyed by `(class_name, method_name, kind)`. A single key may resolve to multiple {SyntheticMethod}
+    # records if two plugins emit the same name (e.g. `rigor-dry-struct` and a hypothetical `rigor-dry-struct-extras`
+    # both registering the same attribute). Per ADR-16 WD11 / the WD-discussion in `## Open questions` the dispatcher
+    # uses first-wins by registration order; this index preserves that order in `lookup`'s return.
     #
     # ## Slice 2b — return-type precision posture
     #
-    # The recorded `SyntheticMethod#return_type` is a String
-    # (e.g. `"ActiveStorage::Attached::One"`), preserved verbatim
-    # from the manifest's emit table. Slice 2b's engine wiring
-    # treats every match as returning `Dynamic[T]` per WD13's
-    # floor — the recorded string is the input to a later slice's
-    # precision promotion via ADR-13's `Plugin::TypeNodeResolver`.
+    # The recorded `SyntheticMethod#return_type` is a String (e.g. `"ActiveStorage::Attached::One"`), preserved verbatim
+    # from the manifest's emit table. Slice 2b's engine wiring treats every match as returning `Dynamic[T]` per WD13's
+    # floor — the recorded string is the input to a later slice's precision promotion via ADR-13's
+    # `Plugin::TypeNodeResolver`.
     class SyntheticMethodIndex
       attr_reader :entries, :class_names
 
       # @param entries [Array<SyntheticMethod>]
-      # @param class_names [Array<String>, Set<String>] names of
-      #   classes the substrate synthesises wholesale (ADR-36
-      #   nested-class emission — the variant subclasses that have
-      #   no RBS/source declaration of their own). Recorded so
-      #   `Environment#class_known?` can resolve them as classes
-      #   (their constant reference + `.new` dispatch) even though
-      #   nothing else in the type universe declares them. Tier B/C
-      #   method emissions leave this empty (their receiver classes
-      #   are already real).
+      # @param class_names [Array<String>, Set<String>] names of classes the substrate synthesises wholesale (ADR-36
+      #   nested-class emission — the variant subclasses that have no RBS/source declaration of their own). Recorded so
+      #   `Environment#class_known?` can resolve them as classes (their constant reference + `.new` dispatch) even
+      #   though nothing else in the type universe declares them. Tier B/C method emissions leave this empty (their
+      #   receiver classes are already real).
       def initialize(entries: [], class_names: [])
         unless entries.is_a?(Array) && entries.all?(SyntheticMethod)
           raise ArgumentError,
@@ -59,16 +46,14 @@ module Rigor
         entries.empty? && class_names.empty?
       end
 
-      # True when `name` is a substrate-synthesised class (an
-      # ADR-36 variant subclass). Used by `Environment#class_known?`
-      # so the constant resolves and `.new` dispatches.
+      # True when `name` is a substrate-synthesised class (an ADR-36 variant subclass). Used by
+      # `Environment#class_known?` so the constant resolves and `.new` dispatches.
       def knows_class?(name)
         @class_name_set.include?(name.to_s)
       end
 
-      # Returns an Array of matching {SyntheticMethod} records in
-      # plugin-registration order. Empty Array when no plugin has
-      # declared a Tier C entry that interpolates to this name.
+      # Returns an Array of matching {SyntheticMethod} records in plugin-registration order. Empty Array when no plugin
+      # has declared a Tier C entry that interpolates to this name.
       def lookup_instance(class_name, method_name)
         @by_instance.fetch([class_name, method_name.to_sym], EMPTY_ROW)
       end

data/lib/rigor/inference/synthetic_method_scanner.rb

@@ -10,13 +10,10 @@ require_relative "synthetic_method_index"
 
 module Rigor
   module Inference
-    # ADR-16 slice 2b pre-pass — scans the project's source paths
-    # for class-level DSL calls that match any registered plugin's
-    # `Plugin::Macro::HeredocTemplate` entry, instantiates the
-    # corresponding {SyntheticMethod} records, and returns a frozen
-    # {SyntheticMethodIndex} the dispatcher consults below the RBS
-    # tier (per WD13 — user-authored RBS overrides substrate
-    # synthesis).
+    # ADR-16 slice 2b pre-pass — scans the project's source paths for class-level DSL calls that match any registered
+    # plugin's `Plugin::Macro::HeredocTemplate` entry, instantiates the corresponding {SyntheticMethod} records, and
+    # returns a frozen {SyntheticMethodIndex} the dispatcher consults below the RBS tier (per WD13 — user-authored RBS
+    # overrides substrate synthesis).
     #
     # Two-phase walk:
     #
@@ -32,36 +29,31 @@ module Rigor
     #    class must equal or inherit (lexically OR through the
     #    RBS env) from the template's `receiver_constraint`.
     #
-    # Per WD4 the pre-pass mechanism is "scan all files once at
-    # startup, populate the index before per-file inference."
-    # Slice 2b ships this strategy; future iterations may revisit
-    # to lazy emit (per WD4 alternatives) if the warm-cache profile
-    # justifies it.
+    # Per WD4 the pre-pass mechanism is "scan all files once at startup, populate the index before per-file inference."
+    # Slice 2b ships this strategy; future iterations may revisit to lazy emit (per WD4 alternatives) if the warm-cache
+    # profile justifies it.
     #
-    # Per WD13 floor — `return_type` is recorded but not resolved.
-    # `Macro::HeredocTemplate::Emit#returns` strings round-trip
-    # through {SyntheticMethod#return_type} verbatim; the
-    # dispatcher's slice-2b tier translates every match to
-    # `Dynamic[T]`. Precise resolution via the ADR-13 resolver
-    # chain is the ceiling, deferred.
+    # Per WD13 floor — `return_type` is recorded but not resolved. `Macro::HeredocTemplate::Emit#returns` strings
+    # round-trip through {SyntheticMethod#return_type} verbatim; the dispatcher's slice-2b tier translates every match
+    # to `Dynamic[T]`. Precise resolution via the ADR-13 resolver chain is the ceiling, deferred.
     module SyntheticMethodScanner # rubocop:disable Metrics/ModuleLength
       module_function
 
       # @param plugin_registry [Rigor::Plugin::Registry]
-      # @param paths           [Array<String>] absolute paths to the project
+      # @param paths [Array<String>] absolute paths to the project
       #   source files to scan.
-      # @param environment     [Rigor::Environment, nil] used for
+      # @param environment [Rigor::Environment, nil] used for
       #   inheritance resolution against RBS-known classes
       #   (ActiveRecord::Base, Dry::Struct, etc.) that aren't
       #   declared in project source.
-      # @param fact_store      [Rigor::Plugin::FactStore, nil]
+      # @param fact_store [Rigor::Plugin::FactStore, nil]
       #   the per-run cross-plugin fact store. ADR-18 lookups
       #   (`Plugin::Macro::HeredocTemplate::Emit#returns_from_arg`)
       #   consult this at scan time to resolve per-call-site
       #   return types from published facts; without it, those
       #   emit rows fall back to their static `returns:` (or
       #   `"untyped"` → `Dynamic[Top]`).
-      # @param buffer          [Rigor::Analysis::BufferBinding, nil]
+      # @param buffer [Rigor::Analysis::BufferBinding, nil]
       #   editor-mode buffer binding. When set, reads for the
       #   logical path resolve to the buffer's physical path so
       #   the pre-pass sees the in-flight bytes instead of the
@@ -94,8 +86,7 @@ module Rigor
         SyntheticMethodIndex.new(entries: entries, class_names: class_names)
       end
 
-      # Aggregates `(plugin_id, template)` pairs across every
-      # plugin's `manifest.heredoc_templates` in registration
+      # Aggregates `(plugin_id, template)` pairs across every plugin's `manifest.heredoc_templates` in registration
       # order. Empty when no plugin contributes Tier C entries.
       def collect_templates(plugin_registry)
         return [] if plugin_registry.nil? || plugin_registry.empty?
@@ -108,10 +99,8 @@ module Rigor
         end
       end
 
-      # ADR-16 Tier B (slice 3b). Aggregates `(plugin_id, registry)`
-      # pairs across every plugin's `manifest.trait_registries` in
-      # registration order. Empty when no plugin contributes Tier B
-      # entries.
+      # ADR-16 Tier B (slice 3b). Aggregates `(plugin_id, registry)` pairs across every plugin's
+      # `manifest.trait_registries` in registration order. Empty when no plugin contributes Tier B entries.
       def collect_trait_registries(plugin_registry)
         return [] if plugin_registry.nil? || plugin_registry.empty?
 
@@ -123,9 +112,8 @@ module Rigor
         end
       end
 
-      # ADR-36 — aggregates `(plugin_id, template)` pairs across
-      # every plugin's `manifest.nested_class_templates`. Empty when
-      # no plugin contributes the nested-class emission tier.
+      # ADR-36 — aggregates `(plugin_id, template)` pairs across every plugin's `manifest.nested_class_templates`. Empty
+      # when no plugin contributes the nested-class emission tier.
       def collect_nested_class_templates(plugin_registry)
         return [] if plugin_registry.nil? || plugin_registry.empty?
 
@@ -137,10 +125,8 @@ module Rigor
         end
       end
 
-      # ADR-36 nested-class emission. For each class that `extend`s a
-      # template's `receiver_constraint` and carries a
-      # `<block_method> do ... end` block, mint one synthetic
-      # subclass per `<variant_method> <Const>, <Type>` row:
+      # ADR-36 nested-class emission. For each class that `extend`s a template's `receiver_constraint` and carries a
+      # `<block_method> do ... end` block, mint one synthetic subclass per `<variant_method> <Const>, <Type>` row:
       #
       #   class Shape
       #     extend Mangrove::Enum
@@ -149,13 +135,10 @@ module Rigor
       #     end
       #   end
       #
-      # yields synthetic class `Shape::Circle` + instance method
-      # `Shape::Circle#inner -> Float`. The variant subclass name is
-      # recorded in `class_names` so `Environment#class_known?`
-      # resolves the constant (and `.new` dispatches through
-      # `meta_new`); `#inner`'s return type is the literal constant
-      # type argument (non-constant inner shapes degrade to
-      # `Dynamic[Top]` per the slice-A floor).
+      # yields synthetic class `Shape::Circle` + instance method `Shape::Circle#inner -> Float`. The variant subclass
+      # name is recorded in `class_names` so `Environment#class_known?` resolves the constant (and `.new` dispatches
+      # through `meta_new`); `#inner`'s return type is the literal constant type argument (non-constant inner shapes
+      # degrade to `Dynamic[Top]` per the slice-A floor).
       def collect_nested_class_entries(entries, class_names, nested_templates, ast, path)
         return if ast.nil?
 
@@ -173,9 +156,8 @@ module Rigor
         end
       end
 
-      # Walks every class declaration, yielding its fully-qualified
-      # name and the `Prism::ClassNode`. Mirrors `walk_class_bodies`'
-      # scope-stack bookkeeping but hands back the class node itself.
+      # Walks every class declaration, yielding its fully-qualified name and the `Prism::ClassNode`. Mirrors
+      # `walk_class_bodies`' scope-stack bookkeeping but hands back the class node itself.
       def walk_classes(node, scope_stack = [], &)
         return unless node.respond_to?(:compact_child_nodes)
 
@@ -198,9 +180,8 @@ module Rigor
         body.respond_to?(:body) ? body.body.compact : []
       end
 
-      # True when the class body carries `extend <constraint>`
-      # (receiverless `extend` call with the constraint constant as
-      # its first argument).
+      # True when the class body carries `extend <constraint>` (receiverless `extend` call with the constraint constant
+      # as its first argument).
       def body_extends?(body, constraint)
         body.any? do |stmt|
           stmt.is_a?(Prism::CallNode) && stmt.receiver.nil? && stmt.name == :extend &&
@@ -208,9 +189,8 @@ module Rigor
         end
       end
 
-      # Yields `(variant_const_name, inner_type_node)` for every
-      # `<variant_method> <Const>, <Type>` call inside the template's
-      # `<block_method> do ... end` block(s).
+      # Yields `(variant_const_name, inner_type_node)` for every `<variant_method> <Const>, <Type>` call inside the
+      # template's `<block_method> do ... end` block(s).
       def each_variant_call(body, template, &)
         body.each do |stmt|
           next unless variants_block_call?(stmt, template)
@@ -275,8 +255,7 @@ module Rigor
 
       # ADR-16 slice 4 — Concern re-targeting index.
       #
-      # Walks every top-level / nested `module M` decl looking for
-      # the ActiveSupport::Concern shape:
+      # Walks every top-level / nested `module M` decl looking for the ActiveSupport::Concern shape:
       #
       #     module M
       #       extend ActiveSupport::Concern
@@ -287,9 +266,8 @@ module Rigor
       #       end
       #     end
       #
-      # The returned Hash maps `module_name => [deferred_call_node, ...]`.
-      # When a class body later contains `include M`, the substrate
-      # replays each deferred call against the including class.
+      # The returned Hash maps `module_name => [deferred_call_node, ...]`. When a class body later contains `include M`,
+      # the substrate replays each deferred call against the including class.
       #
       # Slice 4 scope (floor):
       # - constant-path `include M` only (not `include some_var`).
@@ -334,8 +312,8 @@ module Rigor
         end
       end
 
-      # Recognises a module body that begins with (or contains at
-      # top level) an `extend ActiveSupport::Concern` statement.
+      # Recognises a module body that begins with (or contains at top level) an `extend ActiveSupport::Concern`
+      # statement.
       def concern_module_body?(body)
         return false unless body.respond_to?(:body)
 
@@ -358,13 +336,10 @@ module Rigor
         end
       end
 
-      # Slice 4 hook. When the current class body contains
-      # `include M` and M is a Concern with deferred DSL calls,
-      # replay each deferred call against the including class.
-      # Acts as a re-targeting walker — no new manifest entries
-      # needed; downstream `collect_entries` /
-      # `collect_trait_entries` fire just as if the calls had been
-      # written directly in X's body.
+      # Slice 4 hook. When the current class body contains `include M` and M is a Concern with deferred DSL calls,
+      # replay each deferred call against the including class. Acts as a re-targeting walker — no new manifest entries
+      # needed; downstream `collect_entries` / `collect_trait_entries` fire just as if the calls had been written
+      # directly in X's body.
       def collect_concern_re_targeted_entries(entries, call_node, class_name, concern_index, # rubocop:disable Metrics/ParameterLists
                                               templates, registries, hierarchy, environment, path, fact_store = nil)
         return unless call_node.name == :include && call_node.receiver.nil?
@@ -383,9 +358,8 @@ module Rigor
         end
       end
 
-      # Builds a lexical inheritance map `class_name => parent_class_name`
-      # by walking every top-level / nested `class X < Y` decl
-      # across the AST set.
+      # Builds a lexical inheritance map `class_name => parent_class_name` by walking every top-level / nested `class X
+      # < Y` decl across the AST set.
       def build_hierarchy(asts)
         hierarchy = {}
         asts.each_value do |ast|
@@ -415,11 +389,9 @@ module Rigor
         end
       end
 
-      # Yields `(class_name, call_node)` for every Prism::CallNode
-      # at class-body top level (singleton-context calls). Nested
-      # method bodies, blocks, and conditionals are skipped — the
-      # Tier C call shapes the substrate targets all live at the
-      # class body's top level.
+      # Yields `(class_name, call_node)` for every Prism::CallNode at class-body top level (singleton-context calls).
+      # Nested method bodies, blocks, and conditionals are skipped — the Tier C call shapes the substrate targets all
+      # live at the class body's top level.
       def walk_class_bodies(node, scope_stack = [], &) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
         return unless node.respond_to?(:compact_child_nodes)
 
@@ -487,18 +459,14 @@ module Rigor
         end
       end
 
-      # ADR-16 Tier B (slice 3b). For each matching call like
-      # `<X>.<method_name>(:trait_a, :trait_b)` where X inherits
-      # from the registry's receiver_constraint: collect every
-      # registered trait symbol's module (silently skipping
-      # unknown traits per design decision (2)) plus the
-      # always_included modules, then per-method-explode each
-      # module's RBS instance methods into the index.
+      # ADR-16 Tier B (slice 3b). For each matching call like `<X>.<method_name>(:trait_a, :trait_b)` where X inherits
+      # from the registry's receiver_constraint: collect every registered trait symbol's module (silently skipping
+      # unknown traits per design decision (2)) plus the always_included modules, then per-method-explode each module's
+      # RBS instance methods into the index.
       #
-      # Per slice 3 floor (per user agreement): the synthesised
-      # methods adopt `return_type: "untyped"` (Dynamic[T] at
-      # dispatch). Precision promotion — looking up the module's
-      # actual RBS return type — is reserved for the ceiling slice.
+      # Per slice 3 floor (per user agreement): the synthesised methods adopt `return_type: "untyped"` (Dynamic[T] at
+      # dispatch). Precision promotion — looking up the module's actual RBS return type — is reserved for the ceiling
+      # slice.
       def collect_trait_entries(entries, registries, class_name, call_node, hierarchy, environment, path)
         registries.each do |(plugin_id, registry)|
           next unless call_node.name == registry.method_name
@@ -511,16 +479,14 @@ module Rigor
         end
       end
 
-      # Resolves the set of modules to include from a Tier B
-      # call site:
+      # Resolves the set of modules to include from a Tier B call site:
       #
       # - `always_included` modules (unconditional);
       # - one module per literal Symbol argument the call carries
       #   (resolved through `registry.modules_by_symbol`; unknown
       #   symbols silently skipped per design decision (2)).
       #
-      # Returns an Array<String> of module names in
-      # `always_included` order followed by argument order.
+      # Returns an Array<String> of module names in `always_included` order followed by argument order.
       def resolve_trait_modules(registry, call_node)
         modules = registry.always_included.dup
         positional_symbols(call_node, registry).each do |symbol|
@@ -558,10 +524,9 @@ module Rigor
         end
       end
 
-      # Returns the Symbol method-name list defined on `module_name`'s
-      # RBS instance definition. Empty Array when the module is not
-      # in the RBS env (silent skip — the synthetic emit produces
-      # nothing rather than fabricating method names).
+      # Returns the Symbol method-name list defined on `module_name`'s RBS instance definition. Empty Array when the
+      # module is not in the RBS env (silent skip — the synthetic emit produces nothing rather than fabricating method
+      # names).
       def module_instance_method_names(module_name, environment)
         return [] if environment.nil?
 
@@ -630,8 +595,7 @@ module Rigor
         )
       end
 
-      # ADR-18 three-tier fallback for the synthetic method's
-      # `return_type` string:
+      # ADR-18 three-tier fallback for the synthetic method's `return_type` string:
       #
       # 1. When `row.returns_from_arg` is present AND the
       #    call-site argument at the declared position is a
@@ -663,13 +627,10 @@ module Rigor
         fact[source_rep]
       end
 
-      # Extracts the source-text qualified-constant representation
-      # of the call's positional argument (e.g.,
-      # `"Types::String"`). Returns nil for non-constant shapes
-      # (literals, method chains, blocks, …). The floor
-      # intentionally accepts only ConstantReadNode /
-      # ConstantPathNode per ADR-18; chained-call argument
-      # resolution stays deferred.
+      # Extracts the source-text qualified-constant representation of the call's positional argument (e.g.,
+      # `"Types::String"`). Returns nil for non-constant shapes (literals, method chains, blocks, …). The floor
+      # intentionally accepts only ConstantReadNode / ConstantPathNode per ADR-18; chained-call argument resolution
+      # stays deferred.
       def argument_source_representation(call_node, position)
         args = call_node.arguments&.arguments
         return nil if args.nil? || position >= args.size
@@ -709,8 +670,7 @@ module Rigor
           current = parent
         end
 
-        # Fall back to the env's RBS-aware ordering for the case
-        # where the chain terminates at an RBS-known class
+        # Fall back to the env's RBS-aware ordering for the case where the chain terminates at an RBS-known class
         # (ActiveRecord::Base, Dry::Struct, Sinatra::Base, …).
         return false if environment.nil?
 

data/lib/rigor/language_server/buffer_resolution.rb

@@ -6,18 +6,15 @@ module Rigor
   module LanguageServer
     # Shared buffer lookup for the LSP providers.
     #
-    # Every provider's `provide` opens with the same two steps: translate
-    # the document URI to an on-disk path, then fetch the open buffer
-    # entry from the buffer table — returning nil to the editor when
-    # either is missing. The parse step that follows differs per provider
-    # (strict vs error-tolerant, whole-buffer vs cursor-recovery), so
-    # only this resolution is shared here.
+    # Every provider's `provide` opens with the same two steps: translate the document URI to an on-disk path,
+    # then fetch the open buffer entry from the buffer table — returning nil to the editor when either is
+    # missing. The parse step that follows differs per provider (strict vs error-tolerant, whole-buffer vs
+    # cursor-recovery), so only this resolution is shared here.
     module BufferResolution
       private
 
-      # Resolves `[path, entry]` for the document `uri`, or nil when the
-      # uri has no file path or no open buffer. A caller that destructures
-      # `path, entry = buffer_for(uri)` can guard on `entry.nil?` to cover
+      # Resolves `[path, entry]` for the document `uri`, or nil when the uri has no file path or no open
+      # buffer. A caller that destructures `path, entry = buffer_for(uri)` can guard on `entry.nil?` to cover
       # both misses (a nil return leaves both locals nil).
       def buffer_for(uri)
         path = Uri.to_path(uri)