rigortype 0.4.6 → 0.4.7

data/plugins/rigor-activesupport-core-ext/lib/rigor/plugin/activesupport_core_ext.rb

@@ -3,6 +3,7 @@
 require "rigor/plugin"
 
 require_relative "activesupport_core_ext/effects"
+require_relative "activesupport_core_ext/symbolize_keys"
 
 module Rigor
   module Plugin
@@ -43,12 +44,15 @@ module Rigor
       manifest(
         id: "activesupport-core-ext",
         target_gems: ["activesupport"],
+        # Bumped 2026-10-27 (#2433) — `Hash#symbolize_keys` / `#to_options` map each key member through a
+        # `dynamic_return` hook instead of claiming `Hash[Symbol, V]`.
+        #
         # Bumped 2026-09-10 (#534 item 7) — `ActiveSupport::Concern` is declared, so `extend
         # ActiveSupport::Concern` resolves instead of reading as an unresolved constant.
         #
         # Bumped 2026-09-02 (#632) — `ActiveSupport::Duration`'s reader surface (`ago`/`to_i`/`iso8601`/…)
         # is now declared, open_receivers-protected; see the class comment above.
-        version: "0.5.0",
+        version: "0.6.0",
         description: "RBS bundle for the most-frequently-flagged ActiveSupport core_ext extensions, " \
                      "plus the `ActiveSupport::Duration` type of the numeric time multipliers and its " \
                      "reader surface.",
@@ -190,11 +194,9 @@ module Rigor
         argument = duration_arithmetic_argument(call_node)
         next nil if argument.nil?
 
-        # The ARGUMENT is checked before the receiver: it is the cheaper of the two on the overwhelmingly
-        # common shapes (`i + 1`, `n * 2`), and a call with no Duration operand must cost as little as
-        # possible — this rule is consulted on every `+` / `-` / `*` in the project. The early exit is
-        # what makes the ordering worth anything: an argument that is no Duration operand at all
-        # (`"a" + b`, `list + other`) declines here and never types its receiver on this rule's behalf.
+        # The ARGUMENT is checked before the receiver: it is the cheaper test on the common shapes (`i + 1`,
+        # `n * 2`), and this rule is consulted on every `+` / `-` / `*`. An argument that is no Duration
+        # operand (`"a" + b`, `list + other`) declines here and never types its receiver on this rule's behalf.
         argument_kind = duration_operand_kind(scope&.type_of(argument))
         next nil if argument_kind.nil?
 
@@ -204,6 +206,17 @@ module Rigor
         duration_arithmetic_result(call_node.name, receiver_kind, argument_kind)
       end
 
+      # #2433 — `symbolize_keys` / `to_options` keep a key without `to_sym`, so the key type is mapped per
+      # member; see {SymbolizeKeys}. The RBS rows answer `Hash[untyped, V]` wherever this declines.
+      dynamic_return methods: %i[symbolize_keys to_options] do |call_node, scope|
+        next nil unless call_node.is_a?(Prism::CallNode)
+        next nil unless call_node.receiver
+        next nil unless call_node.arguments.nil?
+
+        # A block is ignored by `symbolize_keys`, so it does not decline.
+        SymbolizeKeys.result(scope&.type_of(call_node.receiver), scope)
+      end
+
       # ADR-88 WD1 — both tables are static and the RBS bundle ships with the gem; nothing here reads a
       # project file, so a project enabling this plugin stays incremental-capable.
       def incremental_state_fingerprint

data/plugins/rigor-activesupport-core-ext/sig/active_support/core_ext.rbs

@@ -1565,28 +1565,35 @@ class Hash[unchecked out K, unchecked out V]
   # non-bang half is `%a{pure}`. `assert_valid_keys` raises rather than
   # mutating (raising is not an effect label).
   %a{pure}
-  def symbolize_keys: () -> Hash[Symbol, V]
+  # `key.to_sym rescue key` keeps a key without `to_sym`, so no one key type is right: `Hash[untyped, V]` here,
+  # and the plugin's `dynamic_return` hook (#2433) maps each key member where it can.
+  def symbolize_keys: () -> Hash[untyped, V]
+  # `symbolize_keys!` keeps `-> self`: `key.to_sym rescue key` leaves a key without `to_sym` as it is, so
+  # `Hash[Symbol, V]` is wrong for an Integer-keyed receiver (#2424 review). The other bang forms below
+  # answer the re-keyed or re-valued hash.
   def symbolize_keys!: () -> self
   %a{pure}
   def deep_symbolize_keys: () -> Hash[untyped, untyped]
-  def deep_symbolize_keys!: () -> self
+  def deep_symbolize_keys!: () -> Hash[untyped, untyped]
   %a{pure}
   def stringify_keys: () -> Hash[String, V]
-  def stringify_keys!: () -> self
+  def stringify_keys!: () -> Hash[String, V]
   %a{pure}
   def deep_stringify_keys: () -> Hash[untyped, untyped]
-  def deep_stringify_keys!: () -> self
+  def deep_stringify_keys!: () -> Hash[untyped, untyped]
   %a{pure}
   def assert_valid_keys: (*K | Array[K]) -> self
+  # The block's result is the new key at every level, so the keys are its type, not `K`: `{ a: 1 }
+  # .deep_transform_keys(&:to_s)` has String keys. Nested values are re-keyed too, so they read `untyped`.
   %a{pure}
-  def deep_transform_keys: () { (K) -> K } -> Hash[K, untyped]
-  def deep_transform_keys!: () { (K) -> K } -> self
+  def deep_transform_keys: [X] () { (K) -> X } -> Hash[X, untyped]
+  def deep_transform_keys!: [X] () { (K) -> X } -> Hash[X, untyped]
   %a{pure}
   def deep_transform_values: () { (V) -> untyped } -> Hash[K, untyped]
-  def deep_transform_values!: () { (V) -> untyped } -> self
+  def deep_transform_values!: () { (V) -> untyped } -> Hash[K, untyped]
   # `alias_method`s of `symbolize_keys` / `symbolize_keys!`.
   %a{pure}
-  def to_options: () -> Hash[Symbol, V]
+  def to_options: () -> Hash[untyped, V]
   def to_options!: () -> self
 
   # `core_ext/hash/deep_dup` — allocates a deep copy, never touches the
@@ -1600,11 +1607,17 @@ class Hash[unchecked out K, unchecked out V]
   # `core_ext/hash/deep_merge` — the block receives `(key, this_val,
   # other_val)` and returns the merged value; neither `deep_merge` nor its
   # block mutates either hash (containment covers the block itself).
-  %a{pure}
-  def deep_merge: (Hash[K, V]) -> Hash[K, V]
-                | (Hash[K, V]) { (K, V, V) -> V } -> Hash[K, V]
-  def deep_merge!: (Hash[K, V]) -> self
-                 | (Hash[K, V]) { (K, V, V) -> V } -> self
+  # The result carries the argument's keys and values as well as the
+  # receiver's, and a key both hold a Hash under merges into a third Hash
+  # that is neither side's value type (`{ n: { x: 1 } }.deep_merge(n: { y:
+  # "s" })[:n]` is `{ x: 1, y: "s" }`), so the values read `untyped`.
+  # `(Hash[K, V]) -> Hash[K, V]` typed `h.deep_merge(b: "x")[:b]` as the
+  # receiver's value type (#2424 review). The bang form answers the receiver.
+  %a{pure}
+  def deep_merge: [A, B] (Hash[A, B] other_hash) -> Hash[K | A, untyped]
+                | [A, B] (Hash[A, B] other_hash) { (K | A, untyped, untyped) -> untyped } -> Hash[K | A, untyped]
+  def deep_merge!: [A, B] (Hash[A, B] other_hash) -> Hash[K | A, untyped]
+                 | [A, B] (Hash[A, B] other_hash) { (K | A, untyped, untyped) -> untyped } -> Hash[K | A, untyped]
   # `other.is_a?(Hash)` — the hook `ActiveSupport::DeepMergeable` asks before
   # recursing into a value. `:nodoc:`, but public.
   %a{pure}

data/plugins/rigor-alba/lib/rigor/plugin/alba/resource_index.rb

@@ -37,9 +37,9 @@ module Rigor
           @classes.empty?
         end
 
-        # The classes alba infers for the associations that name no resource, limited to
-        #   those that exist in the project. The block receives each association name and returns alba's
-        #   `classify` of it (the caller owns the inflector; ADR-39).
+        # The classes alba infers for the associations that name no resource, limited to those that exist in
+        # the project. The block receives each association name and returns alba's `classify` of it (the
+        # caller owns the inflector; ADR-39).
         def inferred_roots(&classify)
           roots = @associations.filter_map do |association|
             next unless resource?(association.owner)

data/plugins/rigor-dry-schema/lib/rigor/plugin/dry_schema/schema_scanner.rb

@@ -212,9 +212,7 @@ module Rigor
         # ... end` row's own recursive call (see {#each_block_type_info}). It caps the recursion at ONE
         # level deep: with `nested: true`, {#walk_predicate_chain} declines a FURTHER `each do ... end`
         # rather than recursing again (issue #137 deliberately does not model doubly-nested arrays of
-        # arrays). This also keeps `collect_schema_shape` from calling itself — {#each_block_type_info}
-        # is the only caller that ever passes `nested: true}` — so the call graph has no cycle for the
-        # engine's return-type inference to approximate through.
+        # arrays). The recursion through {#each_block_type_info} is therefore bounded and terminates.
         def collect_schema_shape(block_node, type_aliases, nested:)
           required = {}
           optional = {}

data/plugins/rigor-dry-struct/lib/rigor/plugin/dry_struct.rb

@@ -34,9 +34,9 @@ module Rigor
     #
     # The synthetic reader's return type is resolved via ADR-18's `returns_from_arg:` fact lookup: the
     # call-site's second argument (`Types::String` etc.) is looked up through the `:dry_type_aliases`
-    # fact published by `rigor-dry-types`, yielding `Nominal[String]` for common cases. When the lookup
-    # misses (e.g. inline method-chain argument whose chain-head isn't currently extracted), the row
-    # falls back to `Dynamic[Top]` silently.
+    # fact published by `rigor-dry-types`, yielding the aliased class (`String`) for common cases. When the
+    # lookup misses (e.g. inline method-chain argument whose chain-head isn't currently extracted), the row
+    # falls back to the untyped floor silently.
     #
     # ## Scope (slice 2c minimum)
     #
@@ -58,8 +58,8 @@ module Rigor
                      "by consuming `rigor-dry-types`'s `:dry_type_aliases` fact.",
         # ADR-9 consumption — the precision-promotion path below uses `:dry_type_aliases` published by
         # `rigor-dry-types`. The fact is optional: when the `rigor-dry-types` plugin isn't loaded, the
-        # `returns_from_arg:` lookup misses and the synthetic readers fall back to `Dynamic[Top]` (the
-        # pre-ADR-18 floor).
+        # `returns_from_arg:` lookup misses and the synthetic readers fall back to the untyped floor (the
+        # pre-ADR-18 behaviour).
         consumes: [{ plugin_id: "dry-types", name: :dry_type_aliases, optional: true }],
         heredoc_templates: [
           Rigor::Plugin::Macro::HeredocTemplate.new(
@@ -69,7 +69,7 @@ module Rigor
             # ADR-18 — the synthetic reader's return type comes from the call site's second argument
             # (`Types::String` etc.), resolved through the `:dry_type_aliases` fact. When the lookup
             # misses (e.g. inline `attribute :tag, Types::String.constrained(...)`, whose receiver chain
-            # head isn't currently extracted), the row falls back to Dynamic[Top].
+            # head isn't currently extracted), the row falls back to the untyped floor.
             emit: [{
               name: "\#{name}",
               returns_from_arg: {

data/plugins/rigor-dry-types/lib/rigor/plugin/dry_types/alias_scanner.rb

@@ -33,10 +33,9 @@ module Rigor
         # `Coercible::*` (everything-to-target coercion), `Strict::*` (no coercion; raise if mismatch),
         # `Params::*` (HTTP / query-string-style coercion, used by Hanami / Roda / dry-web in request
         # handling), `JSON::*` (JSON-shape coercion). Each category exposes the same set of names as the
-        # canonical shortcuts above, plus a few additions that are category-specific (`Params::Nil`,
-        # `JSON::Symbol`). For Rigor's purposes the underlying class is the same regardless of category —
-        # coercion semantics are a runtime concern. We register every `<module>::<Category>::<Name>`
-        # mapping the upstream gem publishes so call-site references work uniformly.
+        # canonical shortcuts above; only those names are registered here, so a category-specific extra
+        # is not covered. For Rigor's purposes the underlying class is the same regardless of category —
+        # coercion semantics are a runtime concern.
         NESTED_CATEGORIES = %w[Coercible Strict Params JSON].freeze
         private_constant :NESTED_CATEGORIES
 
@@ -229,8 +228,8 @@ module Rigor
 
         # `include Dry.Types()` at the top of the module body is the canonical alias declaration. We
         # accept the call anywhere in the body (some projects guard it with a `if defined?` check). The
-        # argument list must be empty (or a kwargs-only `default: :nominal` style accepted by upstream;
-        # we treat both as "alias-installing").
+        # `Dry.Types(...)` argument list is not inspected: kwargs such as `default: :nominal` install the
+        # aliases too.
         def contains_dry_types_include?(body)
           return false if body.nil?
 

data/plugins/rigor-dry-types/lib/rigor/plugin/dry_types.rb

@@ -21,7 +21,7 @@ module Rigor
     # cross-plugin fact (ADR-9). Other dry-rb adapter plugins consume this fact:
     #
     # - `rigor-dry-struct` reads it so `attribute :city, Types::String` promotes `address.city` from
-    #   `Dynamic[Top]` to `Nominal[String]` via ADR-18's `returns_from_arg:` fact lookup.
+    #   from an untyped value to `String` via ADR-18's `returns_from_arg:` fact lookup.
     # - `rigor-dry-validation` / `rigor-dry-schema` read it for per-key type recognition in `schema { … }`
     #   / `params { … }` blocks (separate plugin slice).
     #

data/plugins/rigor-dry-validation/lib/rigor/plugin/dry_validation/params_shape.rb

@@ -44,9 +44,8 @@ module Rigor
         end
 
         # Renders `Foo` / `Foo::Bar` / `::Foo::Bar` as the `::`-joined String {ContractScanner}'s table is
-        # keyed by. Duplicated from rigor-dry-schema's identical helper rather than shared — five lines,
-        # no dependency on anything ELSE in that plugin, and reusing it would need a `registered_for`
-        # guard here too even though this leaf never touches dry-schema's own type/alias machinery.
+        # keyed by. Duplicated from rigor-dry-schema rather than shared: this leaf must not depend on that
+        # plugin, and reusing the helper would need a `registered_for` guard here too.
         def constant_name(node)
           case node
           when Prism::ConstantReadNode then node.name.to_s

data/plugins/rigor-dry-validation/lib/rigor/plugin/dry_validation.rb

@@ -58,19 +58,16 @@ module Rigor
 
       # ADR-37 dynamic return — refines `NewUserContract.new.call(input).to_h` to the per-contract
       # `HashShape` when {#result_shape_for} finds one. Gated on the method name alone (mirrors
-      # rigor-dry-schema's own `.to_h` rule): the RBS overlay types `Contract#call`'s return as the
-      # generic `Result`, but that alone can't select a PER-CONTRACT shape, so the block does its own
-      # syntactic chain match via {ParamsShape.contract_name} before touching the table. When
-      # rigor-dry-schema isn't loaded, or the chain isn't a Contract call, this returns nil and the RBS
-      # overlay's generic `Hash[Symbol, untyped]` stands.
+      # rigor-dry-schema's `.to_h` rule); the chain match is in {ParamsShape.contract_name}, because the
+      # RBS overlay's generic `Result` cannot select a per-contract shape. Otherwise returns nil and the
+      # overlay's generic hash type stands.
       dynamic_return methods: [:to_h] do |call_node, _scope|
         result_shape_for(call_node)
       end
 
       # ADR-37 slice 1c two-pass — the "collect" half of `dry-validation.rule-key-mismatch`. Reads the
-      # SAME `:dry_type_aliases` fact `#prepare` does (a plain `services.fact_store.read`, not
-      # `#read_fact`'s memoised wrapper — `services` at collect time is the run-wide instance, so an
-      # in-block memo isn't needed here the way it is across many per-call `dynamic_return` invocations).
+      # same `:dry_type_aliases` fact as `#prepare`, straight from `services.fact_store` (no `#read_fact`
+      # memo: `services` here is run-wide, unlike the per-call `dynamic_return` blocks).
       node_file_context do |root, _scope|
         type_aliases = services.fact_store.read(plugin_id: "dry-types", name: :dry_type_aliases) || {}
         ContractScanner.rule_key_issues(root, type_aliases)

data/plugins/rigor-ethon/lib/rigor/plugin/ethon.rb

@@ -14,7 +14,6 @@ module Rigor
         signature_paths: ["sig"]
       )
 
-      # Option catalogue and return types for Easy methods
       EASY_RETURN_TYPES = {
         perform: -> { Rigor::Type::Combinator.nominal_of("Integer") },
         response_code: -> { Rigor::Type::Combinator.nominal_of("Integer") },

data/plugins/rigor-factorybot/lib/rigor/plugin/factorybot/factory_discoverer.rb

@@ -115,7 +115,7 @@ module Rigor
         # 3. Inflected from the factory name — `:user` → `"User"`, `:admin_user` → `"AdminUser"`. The
         #    factory name is already singular by FactoryBot convention, so we only need camelization.
         #
-        # Returns a String (the canonical class name).
+        # Returns the canonical class name.
         def factory_model_class(call_node, factory_name)
           explicit = explicit_class_option(call_node)
           return explicit if explicit

data/plugins/rigor-factorybot/lib/rigor/plugin/factorybot.rb

@@ -84,27 +84,20 @@ module Rigor
         @factory_search_paths = Array(config.fetch("factory_search_paths")).map(&:to_s)
       end
 
-      # ADR-102 WD3 / #350 — the model classes the factories build, published as `:reachability_references`
-      # rather than as `:reachability_roots`.
+      # ADR-102 WD3 / #350 — the factories' model classes are published as `:reachability_references`,
+      # not `:reachability_roots`.
       #
-      # Both halves of that sentence are load-bearing.
-      #
-      # It is a CONTRIBUTION at all because a factory names its class by a mechanism the constant scan cannot
-      # follow: `factory :user, class: "Admin::User"` is a string, and a bare `factory :user` is FactoryBot's
-      # own constantization of the factory name. Neither leaves a constant node anywhere in the project.
-      #
-      # It is a REFERENCE rather than a root because factories live in the test tree. Rooting them would make
-      # every factoried class production-reachable and erase ADR-102 WD8's "reachable only from tests"
-      # category for exactly the classes it is most likely to be about — a model kept alive by its factory
-      # and its spec and nothing else is the archetype of dead production code with a live test, and that is
-      # the single most actionable row this report produces. Carrying the `:test` role keeps the finding.
+      # It is a contribution because a factory names its class by a mechanism the constant scan cannot
+      # follow (`factory :user, class: "Admin::User"` is a string; a bare `factory :user` is constantized by
+      # FactoryBot). It is a reference rather than a root because factories live in the test tree: rooting
+      # them would make every factoried class production-reachable and erase ADR-102 WD8's "reachable only
+      # from tests" category. The `:test` role keeps that finding.
       def prepare(services)
         index = producer_value(:factory_index)
         return if index.nil? || index.empty?
 
-        # The producer value and the ADR-9 fact are different channels (#921) — `producer_value` is this
-        # plugin's own cached computation, read back via `producer_value` above; `fact_store.publish` is
-        # what makes it visible to another plugin's `read_fact`, which is how rigor-rspec binds
+        # The producer value and the ADR-9 fact are different channels (#921): `fact_store.publish` is what
+        # makes the index visible to another plugin's `read_fact`, as rigor-rspec uses it to bind
         # `create(:name)` to the factory's model class.
         services.fact_store.publish(plugin_id: manifest.id, name: :factory_index, value: index)
 
@@ -118,8 +111,7 @@ module Rigor
 
       # ADR-37 — per-call factory/attribute validation over the engine-owned walk. Each violation carries
       # its own location (the call's message_loc, or the offending attribute key), so it is positioned
-      # via `diagnostic(node, location:)`. No file-level diagnostic remains, so there is no
-      # `diagnostics_for_file`.
+      # via `diagnostic(node, location:)`.
       node_rule Prism::CallNode do |node, _scope, path|
         index = producer_value(:factory_index)
         next [] if index.nil? || index.empty?

data/plugins/rigor-ffi/lib/rigor/plugin/ffi/analyzer.rb

@@ -40,7 +40,6 @@ module Rigor
           all_args = call_node.arguments&.arguments || []
           return nil if all_args.empty?
 
-          # Strip trailing keyword options hash if present
           pos_args = all_args.grep_v(Prism::KeywordHashNode)
           return nil if pos_args.empty?
 

data/plugins/rigor-ffi/lib/rigor/plugin/ffi/discoverer.rb

@@ -149,7 +149,6 @@ module Rigor
               end
             end
           when :callback
-            # Issue 4 fix: extract callback definitions
             args = node.arguments&.arguments || []
             if args.size >= 3
               cb_name = Analyzer.extract_symbol(args[0])
@@ -193,7 +192,6 @@ module Rigor
               end
             end
           else
-            # Issue 5 fix: pass mod_name to sub-plugin recognizers
             FFI.binding_recognizers.each do |recognizer|
               facts = recognizer.recognize(node, mod_name)
               Array(facts).each do |fact|

data/plugins/rigor-ffi/lib/rigor/plugin/ffi.rb

@@ -38,11 +38,10 @@ module Rigor
       # Dynamic return rule for attached FFI functions
       # Gated on known FFI library receivers and attached function names
       #
-      # Issue #701 — both receiver kinds are declared because the block below already resolved
-      # `Nominal` and `Singleton` alike: `attach_function` installs the binding on the library module
-      # itself (`MyLib.strlen`) and `include`ing that module makes the same name an instance call, so
-      # neither kind is an accident. The kind-aware gate makes that intent explicit rather than relying
-      # on a `receivers:` entry answering for both.
+      # Issue #701 — both receiver kinds are declared because the block below already resolves `Nominal`
+      # and `Singleton` alike: `attach_function` installs the binding on the library module itself
+      # (`MyLib.strlen`), and `include`ing that module makes the same name an instance call. The
+      # kind-aware gate makes that intent explicit rather than relying on one `receivers:` entry for both.
       dynamic_return receivers: -> { both_receiver_kinds(producer_value(:ffi_catalog)&.libraries) },
                      methods: -> { producer_value(:ffi_catalog)&.function_method_names || [] } do |call_node, scope|
         catalog = producer_value(:ffi_catalog)

data/plugins/rigor-grape/lib/rigor/plugin/grape.rb

@@ -85,7 +85,6 @@ module Rigor
             method_names: NAMESPACE_METHODS,
             self_type: "singleton(Grape::API::Instance)"
           ),
-          # `params do ... end` — body `instance_eval`s on a `ParamsScope` instance.
           Rigor::Plugin::Macro::BlockAsMethod.new(
             receiver_constraint: "Grape::API",
             method_names: %i[params],
@@ -121,7 +120,6 @@ module Rigor
             method_names: %i[desc],
             self_type: "Grape::DSL::Desc::ConfigContext"
           ),
-          # Verb bodies run inside `Grape::Endpoint` instances.
           Rigor::Plugin::Macro::BlockAsMethod.new(
             receiver_constraint: "Grape::API",
             method_names: VERB_METHODS,

data/plugins/rigor-graphql/lib/rigor/plugin/graphql/type_scanner.rb

@@ -23,9 +23,8 @@ module Rigor
         }.freeze
 
         # The base class name a Schema::Object subclass MUST inherit from to be recognised. Match is on
-        # the rightmost segment of the superclass constant chain so both `GraphQL::Schema::Object` and
-        # the locally-aliased `BaseObject = GraphQL::Schema::Object` shape work when the alias's RHS is
-        # the canonical path.
+        # the last two segments of the superclass constant chain (see {#schema_subclass?}), so a locally
+        # aliased base such as `BaseObject = GraphQL::Schema::Object` is not followed.
         SCHEMA_OBJECT_TAIL = "Object"
         SCHEMA_ENUM_TAIL = "Enum"
         SCHEMA_INPUT_OBJECT_TAIL = "InputObject"
@@ -183,7 +182,7 @@ module Rigor
         private_class_method :statement_nodes
 
         # Walks every top-level `value "..."` call inside an enum subclass body and returns the value
-        # names as an Array<String>. Both shapes graphql-ruby accepts work:
+        # names. Both shapes graphql-ruby accepts work:
         #
         #     value "ACTIVE"
         #     value "DISABLED", value: :off, description: "..."
@@ -299,7 +298,7 @@ module Rigor
         end
         private_class_method :parse_field_call
 
-        # Resolves the `Type` positional argument to a `{type: "ClassName", list: bool}` tuple.
+        # Resolves the `Type` positional argument to a `type:` class name and a `list:` flag.
         # ArrayNode forms (`[String]` / `[Types::User]`) unwrap the single element and mark `list: true`.
         # Bare constant refs are not lists. Returns nil for unrecognised shapes (string types `"User"`,
         # Proc lazy types, etc.) so callers drop the field.
@@ -350,8 +349,8 @@ module Rigor
         end
         private_class_method :extract_nullability
 
-        # Returns the constant chain as an Array of String segments (`["GraphQL", "Schema", "Object"]`).
-        # Empty array for unrecognised node kinds.
+        # Returns the constant chain's segments, e.g. `["GraphQL", "Schema", "Object"]`. Empty for
+        # unrecognised node kinds.
         def constant_path_segments(node)
           case node
           when Prism::ConstantReadNode then [node.name.to_s]

data/plugins/rigor-hanami/lib/rigor/plugin/hanami/action_checker.rb

@@ -20,10 +20,8 @@ module Rigor
           @contracts = contracts
         end
 
-        # Per-`ClassNode` check over the engine-owned walk (ADR-37): called once per class node the
-        # `node_rule` in `hanami.rb` dispatches, against every contract whose `path_glob` matches the
-        # file. No cross-class-node state is needed, so the checker ships no `class_nodes` traversal of
-        # its own.
+        # Per-`ClassNode` check over the engine-owned walk (ADR-37): called once per class node by the
+        # `node_rule` in `hanami.rb`, against every contract whose `path_glob` matches the file.
         def check_class(class_node, path:)
           @contracts.filter_map do |contract|
             next unless path_matches?(contract.path_glob, path)

data/plugins/rigor-hanami/lib/rigor/plugin/hanami.rb

@@ -87,11 +87,8 @@ module Rigor
         @protocol_contracts || manifest.protocol_contracts
       end
 
-      # ADR-37 — per-class-node validation over the engine-owned walk. Each `Prism::ClassNode` is checked
-      # against every contract independently, so the plugin no longer ships its own `class_nodes`
-      # traversal; `ActionChecker#check_class` keeps the per-class contract logic. (A per-class contract
-      # check is exactly what `node_rule` is for — the return type is void, so no `scope` query is
-      # needed.)
+      # ADR-37 — per-class-node validation over the engine-owned walk; `ActionChecker#check_class` holds the
+      # per-class contract logic. The return type is void, so no `scope` query is needed.
       node_rule Prism::ClassNode do |node, _scope, path|
         contracts = protocol_contracts
         next [] if contracts.empty?

data/plugins/rigor-mangrove/lib/rigor/plugin/mangrove.rb

@@ -51,8 +51,8 @@ module Rigor
     #
     # - `is_a?(Result::Ok)` / `Some` / `None` exhaustive narrowing — core control-flow analysis over a sealed
     #   hierarchy, not a plugin surface.
-    # - The `variants do variant Const, Type end` Enum DSL is handled via ADR-36 `nested_class_templates:` in
-    #   this plugin's manifest (Slice A — see `nested_class_templates:` block below).
+    # - The `variants do variant Const, Type end` Enum DSL is not part of the unwrap contribution; it is
+    #   synthesised through the ADR-36 `nested_class_templates:` in this plugin's manifest (Slice A).
     class Mangrove < Rigor::Plugin::Base
       manifest(
         id: "mangrove",

data/plugins/rigor-minitest/lib/rigor/plugin/minitest/assertion_analyzer.rb

@@ -17,8 +17,8 @@ module Rigor
       #
       #   assert_kind_of(T, x)        →  narrow x to T
       #   assert_instance_of(T, x)    →  narrow x to T
-      #   assert_nil(x)               →  narrow x to Constant<nil>
-      #   assert_equal(literal, x)    →  meet x with Constant<literal> (see "Equality is not identity")
+      #   assert_nil(x)               →  narrow x to nil
+      #   assert_equal(literal, x)    →  meet x with the literal (see "Equality is not identity")
       #   assert_match(regex, x)      →  narrow x to String
       #
       # ### (2) Minitest / Test::Unit `refute_*` / `assert_not_*` (negative) ###
@@ -26,7 +26,7 @@ module Rigor
       #   refute_kind_of(T, x)        →  narrow x AWAY from T
       #   refute_instance_of(T, x)    →  narrow x AWAY from T
       #   refute_nil(x)               →  narrow x AWAY from nil
-      #   refute_equal(literal, x)    →  negative Constant<literal> fact (the engine keeps x unchanged)
+      #   refute_equal(literal, x)    →  negative fact on the literal (the engine keeps x unchanged)
       #
       # Test::Unit's `assert_not_nil(x)` / `assert_not_equal(...)` / `assert_not_kind_of(...)` /
       # `assert_not_instance_of(...)` share the recognizer with `refute_*` (they're aliases).
@@ -35,8 +35,8 @@ module Rigor
       #
       #   _(x).must_be_kind_of(T)     →  narrow x to T
       #   _(x).must_be_instance_of(T) →  narrow x to T
-      #   _(x).must_be_nil            →  narrow x to Constant<nil>
-      #   _(x).must_equal(literal)    →  meet x with Constant<literal> (see "Equality is not identity")
+      #   _(x).must_be_nil            →  narrow x to nil
+      #   _(x).must_equal(literal)    →  meet x with the literal (see "Equality is not identity")
       #   _(x).must_match(regex)      →  narrow x to String
       #
       # The legacy bare `x.must_be_kind_of(T)` form (Minitest < 6.0 monkey-patched onto Object) is
@@ -48,7 +48,7 @@ module Rigor
       #
       #   _(x).wont_be_kind_of(T)     →  narrow x AWAY from T
       #   _(x).wont_be_nil            →  narrow x AWAY from nil
-      #   _(x).wont_equal(literal)    →  negative Constant<literal> fact (the engine keeps x unchanged)
+      #   _(x).wont_equal(literal)    →  negative fact on the literal (the engine keeps x unchanged)
       #
       # ## Equality is not identity
       #

data/plugins/rigor-pundit/lib/rigor/plugin/pundit/policy_discoverer.rb

@@ -10,7 +10,8 @@ module Rigor
   module Plugin
     class Pundit < Rigor::Plugin::Base
       # Walks the configured policy-search paths via the plugin's `IoBoundary`, parses each `.rb` file with
-      # Prism, and collects classes whose immediate superclass is one of the configured base classes.
+      # Prism, and collects classes whose immediate superclass is one of the configured base classes and
+      # whose name ends in `Policy`.
       #
       # For each discovered policy class, the discoverer collects every instance-side `def name?` predicate
       # method. Non-predicate methods (`initialize`, `resolve`, helper methods) are ignored — Pundit's

data/plugins/rigor-rails-i18n/lib/rigor/plugin/rails_i18n/analyzer.rb

@@ -192,15 +192,10 @@ module Rigor
           first.unescaped
         end
 
-        # Pulls the interpolation hash from the call's arguments. The trailing `Hash` argument (or
+        # Pulls the interpolation hash from the call's arguments. The trailing hash argument (or
         # `Prism::KeywordHashNode`) carries both reserved I18n options (`default:`, `scope:`, …) and
-        # interpolation variables. Returns:
-        #   {
-        #     :has_default     => bool,
-        #     :all_keys        => Set<Symbol>     (every assoc key in the hash),
-        #     :non_reserved    => Set<Symbol>     (keys NOT in RESERVED_OPTION_KEYS),
-        #     :hash_node       => Prism::Node (or nil)
-        #   }
+        # interpolation variables. Returns `:has_default`, `:all_keys` (every assoc key), `:non_reserved`
+        # (keys outside RESERVED_OPTION_KEYS) and `:hash_node` (nil when there is no hash argument).
         #
         # Note: a reserved option key (e.g. `count:`) can also serve as an interpolation value when the
         # locale's leaf string has `%{count}`. The analyzer therefore checks the missing-placeholder set

data/plugins/rigor-rails-i18n/lib/rigor/plugin/rails_i18n/locale_index.rb

@@ -11,9 +11,8 @@ module Rigor
       # placeholder names. The actual translated values are not retained — the analyzer doesn't need them
       # and keeping them would bloat the cache slice.
       class LocaleIndex
-        # `placeholders` is a Hash: `locale_name => Set<String>`. `array_value` is true when at least one
-        # locale's leaf is an Array (used by `l(time, format:)` and similar). `value_kinds` is a Hash:
-        # `locale_name => Symbol` (`:string` / `:array` / `:hash`).
+        # `placeholders` maps each locale name to the `%{var}` placeholder names of its leaf. `value_kinds`
+        # maps each locale name to the leaf's kind (`:string` / `:array` / `:hash` / `:scalar`).
         Entry = Data.define(:dotted_key, :placeholders, :value_kinds) do
           def locales
             placeholders.keys

data/plugins/rigor-rails-i18n/lib/rigor/plugin/rails_i18n/locale_loader.rb

@@ -36,8 +36,8 @@ module Rigor
         end
 
         def load
-          per_key = {} # dotted_key => { locale => Set<String> }
-          per_key_kinds = {} # dotted_key => { locale => :string|:array|:hash }
+          per_key = {} # dotted_key => { locale => placeholder names }
+          per_key_kinds = {} # dotted_key => { locale => leaf kind }
           locales = Set.new
 
           locale_files.each do |path|
@@ -98,12 +98,9 @@ module Rigor
         # leaves are *not* recorded as entries themselves — only their descendants — but every leaf scalar
         # / array IS recorded.
         #
-        # `breadcrumbs` is a single mutable stack reused across the whole walk (push before recursing, pop
-        # after): for the 530-file / 14 MB Mastodon locale corpus the old
-        # `flat_map { flatten_tree(v, breadcrumbs + [k]) }` shape allocated a fresh breadcrumb Array at
-        # every node plus an intermediate result Array at every level — millions of short-lived objects and
-        # the run's top allocation site. The dotted key is still materialised once per leaf (it has to
-        # be); everything else is now allocation-free traversal.
+        # `breadcrumbs` is one mutable stack reused across the walk (push before recursing, pop after). A
+        # per-node Array allocation was the run's top allocation site on the 530-file Mastodon corpus; only
+        # the dotted key is materialised, once per leaf.
         def each_flattened(node, breadcrumbs, &)
           if node.is_a?(Hash)
             node.each do |k, v|

data/plugins/rigor-rails-routes/lib/rigor/plugin/rails_routes/analyzer.rb

@@ -124,7 +124,6 @@ module Rigor
           if name
             names << name
           elsif call_node.name == :subject && call_node.arguments.nil?
-            # Bare `subject { ... }` defines `:subject` itself.
             names << "subject"
           end
         end
@@ -201,8 +200,7 @@ module Rigor
         end
 
         def unknown_helper_violation(name, helper_table)
-          # ADR-39 / boilerplate 0c — the shared DidYouMean-backed suggester replaces the hand-rolled
-          # Levenshtein this module used to carry.
+          # ADR-39 / boilerplate 0c — the shared DidYouMean-backed suggester.
           suggestion = Rigor::Plugin::Base.suggest(name, helper_table.names)
           message = "no route helper `#{name}`"
           message += " (did you mean `#{suggestion}`?)" if suggestion