rigortype 0.2.7 → 0.2.8

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

@@ -10,7 +10,8 @@ module Rigor
   module Plugin
     # rigor-dry-schema — Tier A per
     # [ADR-12](../../../../../docs/adr/12-dry-rb-packaging.md) and the
-    # slicing plan in [docs/design/20260517-dry-validation-slicing.md](../../../../../docs/design/20260517-dry-validation-slicing.md).
+    # slicing plan in
+    # [docs/design/20260517-dry-validation-slicing.md](../../../../../docs/design/20260517-dry-validation-slicing.md).
     #
     # Recognises the canonical dry-schema declaration shapes:
     #
@@ -28,51 +29,42 @@ module Rigor
     #       required(:foo).value(:string)
     #     end
     #
-    # and publishes the resulting
-    # `{schema_const_fqn => {required: {key => underlying_class}, optional: {…}}}`
-    # table as the `:dry_schema_table` cross-plugin fact (ADR-9).
-    # Downstream `rigor-dry-validation` consumes the fact for
-    # per-Contract typed-payload synthesis.
+    # and publishes the resulting `{schema_const_fqn => {required: {key => underlying_class}, optional:
+    # {…}}}` table as the `:dry_schema_table` cross-plugin fact (ADR-9). Downstream `rigor-dry-validation`
+    # consumes the fact for per-Contract typed-payload synthesis.
     #
     # ## Predicate type recognition
     #
-    # Each `required(:key).<predicate>(<arg>)` row maps the predicate
-    # argument to an underlying Ruby class via the dry-schema
-    # canonical-type vocabulary:
+    # Each `required(:key).<predicate>(<arg>)` row maps the predicate argument to an underlying Ruby
+    # class via the dry-schema canonical-type vocabulary:
     #
-    # - `:string` / `:integer` / `:float` / `:decimal` / `:symbol` /
-    #   `:bool` / `:nil` / `:date` / `:date_time` / `:time` / `:hash`
-    #   / `:array` map to their underlying class.
-    # - The four predicate verbs `filled` / `value` / `maybe` /
-    #   `each` are accepted on the same row; their semantic
-    #   difference (whether the value is nullable or coerced) does
-    #   not change the underlying class for Rigor's purposes.
-    # - References to dry-types aliases (`value(Types::Email)`,
-    #   `filled(Types::String)`) resolve through the
-    #   `:dry_type_aliases` ADR-9 fact published by `rigor-dry-types`
-    #   when that plugin is loaded; without it the row degrades to
-    #   "no type contribution from this key".
+    # - `:string` / `:integer` / `:float` / `:decimal` / `:symbol` / `:bool` / `:nil` / `:date` /
+    #   `:date_time` / `:time` / `:hash` / `:array` map to their underlying class.
+    # - The four predicate verbs `filled` / `value` / `maybe` / `each` are accepted on the same row; their
+    #   semantic difference (whether the value is nullable or coerced) does not change the underlying
+    #   class for Rigor's purposes.
+    # - References to dry-types aliases (`value(Types::Email)`, `filled(Types::String)`) resolve through
+    #   the `:dry_type_aliases` ADR-9 fact published by `rigor-dry-types` when that plugin is loaded;
+    #   without it the row degrades to "no type contribution from this key".
     #
     # ## Floor / ceiling (slice 1)
     #
     # Slice 1 ships the **floor**:
     #
-    # - Top-level `Foo = Dry::Schema.{Params,JSON,define} { ... }`
-    #   assignments. Class-level constants (`class Bar; SCHEMA =
-    #   Dry::Schema.Params { ... }; end`) work too — the walker
-    #   prefixes the enclosing constant chain.
-    # - `required(:key).<predicate>(:type_symbol_or_constant)` rows
-    #   for the canonical-type vocabulary above.
+    # - Top-level `Foo = Dry::Schema.{Params,JSON,define} { ... }` assignments. Class-level constants
+    #   (`class Bar; SCHEMA = Dry::Schema.Params { ... }; end`) work too — the walker prefixes the
+    #   enclosing constant chain.
+    # - `required(:key).<predicate>(:type_symbol_or_constant)` rows for the canonical-type vocabulary
+    #   above.
     # - Publishes the table; no user-facing diagnostics yet.
     #
     # The **ceiling** (slice 2+):
     #
-    # - Synthesise typed `result.to_h` returns from each schema
-    #   via ADR-16 Tier C heredoc-template substrate.
+    # - Synthesise typed `result.to_h` returns from each schema via ADR-16 Tier C heredoc-template
+    #   substrate.
     # - Nested schemas (`schema(do ... end)` inside another row).
     # - `predicates(:size?)` / `each { ... }` recursion.
-    # - Per-row `dry-schema.unknown-predicate` /
-    #   `dry-schema.unknown-type` `:info` diagnostics when a
+    # - Per-row `dry-schema.unknown-predicate` / `dry-schema.unknown-type` `:info` diagnostics when a
     #   row's predicate or type symbol isn't recognised.
     class DrySchema < Rigor::Plugin::Base
       manifest(
@@ -84,10 +76,9 @@ module Rigor
         consumes: [{ plugin_id: "dry-types", name: :dry_type_aliases, optional: true }]
       )
 
-      # Walks every project file once during `prepare(services)` to
-      # build the schema table, then publishes via the ADR-9 fact
-      # store. Mirrors the rigor-dry-types `#prepare` shape — the
-      # walk is bounded by `paths:`, parse errors degrade silently.
+      # Walks every project file once during `prepare(services)` to build the schema table, then publishes
+      # via the ADR-9 fact store. Mirrors the rigor-dry-types `#prepare` shape — the walk is bounded by
+      # `paths:`, parse errors degrade silently.
       def prepare(services)
         type_aliases = services.fact_store.read(plugin_id: "dry-types", name: :dry_type_aliases) || {}
         table = SchemaScanner.scan(paths: scannable_paths(services), type_aliases: type_aliases)

data/plugins/rigor-dry-schema/lib/rigor-dry-schema.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-# Gem entry point. Required by Rigor's plugin loader when
-# `.rigor.yml` lists `rigor-dry-schema` under `plugins:`. The
-# loader expects this `require` to side-effect a call to
-# `Rigor::Plugin.register`, which the body of
-# `lib/rigor/plugin/dry_schema.rb` performs at load time.
+# Gem entry point. Required by Rigor's plugin loader when `.rigor.yml` lists `rigor-dry-schema` under
+# `plugins:`. The loader expects this `require` to side-effect a call to `Rigor::Plugin.register`,
+# which the body of `lib/rigor/plugin/dry_schema.rb` performs at load time.
 require_relative "rigor/plugin/dry_schema"

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

@@ -4,16 +4,13 @@ require "rigor/plugin"
 
 module Rigor
   module Plugin
-    # ADR-16 Tier C worked plugin: recognises dry-struct's class-
-    # level `attribute :name, T` DSL and synthesises a reader on
-    # the enclosing `Dry::Struct` subclass.
+    # ADR-16 Tier C worked plugin: recognises dry-struct's class-level `attribute :name, T` DSL and
+    # synthesises a reader on the enclosing `Dry::Struct` subclass.
     #
-    # dry-struct's `Dry::Struct::ClassInterface#attribute` (per the
-    # per-library survey, `lib/dry/struct/class_interface.rb:86-88`
-    # in the upstream gem) is the textbook Tier C target — a
-    # class-level DSL call enumerates a literal Symbol argument, and
-    # `class_interface.rb:452-464` `class_eval`s a heredoc
-    # interpolating that Symbol into a getter:
+    # dry-struct's `Dry::Struct::ClassInterface#attribute` (per the per-library survey,
+    # `lib/dry/struct/class_interface.rb:86-88` in the upstream gem) is the textbook Tier C target — a
+    # class-level DSL call enumerates a literal Symbol argument, and `class_interface.rb:452-464`
+    # `class_eval`s a heredoc interpolating that Symbol into a getter:
     #
     #     class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
     #       def #{key}                       # def city
@@ -21,44 +18,36 @@ module Rigor
     #       end
     #     RUBY
     #
-    # The substrate replays the same contract statically. For
-    # source like:
+    # The substrate replays the same contract statically. For source like:
     #
     #     class Address < Dry::Struct
     #       attribute :city, Types::String
     #       attribute :country, Types::String
     #     end
     #
-    # the pre-pass scans the file, sees `attribute :city, ...`, and
-    # synthesises `Address#city` as a SyntheticMethod the dispatcher
-    # surfaces below RBS dispatch. Bare `address.city` calls in
-    # other files then dispatch through the synthetic record rather
-    # than falling through to `call.undefined-method`.
+    # the pre-pass scans the file, sees `attribute :city, ...`, and synthesises `Address#city` as a
+    # SyntheticMethod the dispatcher surfaces below RBS dispatch. Bare `address.city` calls in other
+    # files then dispatch through the synthetic record rather than falling through to
+    # `call.undefined-method`.
     #
     # ## Precision model (ADR-16 WD13 + ADR-18)
     #
-    # 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
+    # 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.
     #
     # ## Scope (slice 2c minimum)
     #
     # - Recognises `attribute :name, T` at class body top level.
-    # - Recognises `attribute? :name, T` via a separate template
-    #   entry (omittable attribute; same reader name, `?` stripped).
-    # - Synthesises **only the reader** — the other survey-listed
-    #   emit rows (`schema` key, `to_h` row, `[:key]` access, `.new`
-    #   kwarg) are not yet wired by the substrate (they require
-    #   either RBS-level shape synthesis or additional substrate
-    #   primitives). Slice 2c stops at the reader.
-    # - Nested-block form (`attribute :details do ... end` minting
-    #   `Address::Details`) is out of scope for slice 2c; that
-    #   pattern needs Tier A + Tier C composition + const_set
-    #   emission. Deferred.
+    # - Recognises `attribute? :name, T` via a separate template entry (omittable attribute; same reader
+    #   name, `?` stripped).
+    # - Synthesises **only the reader** — the other survey-listed emit rows (`schema` key, `to_h` row,
+    #   `[:key]` access, `.new` kwarg) are not yet wired by the substrate (they require either RBS-level
+    #   shape synthesis or additional substrate primitives). Slice 2c stops at the reader.
+    # - Nested-block form (`attribute :details do ... end` minting `Address::Details`) is out of scope
+    #   for slice 2c; that pattern needs Tier A + Tier C composition + const_set emission. Deferred.
     class DryStruct < Rigor::Plugin::Base
       manifest(
         id: "dry-struct",
@@ -66,26 +55,20 @@ module Rigor
         description: "Recognises dry-struct `attribute :name, T` DSL via ADR-16 Tier C; " \
                      "promotes the reader's return type through ADR-18's `returns_from_arg:` " \
                      "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).
+        # 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).
         consumes: [{ plugin_id: "dry-types", name: :dry_type_aliases, optional: true }],
         heredoc_templates: [
           Rigor::Plugin::Macro::HeredocTemplate.new(
             receiver_constraint: "Dry::Struct",
             method_name: :attribute,
             symbol_arg_position: 0,
-            # 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].
+            # 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].
             emit: [{
               name: "\#{name}",
               returns_from_arg: {

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

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-# Gem entry point. Required by Rigor's plugin loader when
-# `.rigor.yml` lists `rigor-dry-struct` under `plugins:`. The
-# loader expects this `require` to side-effect a call to
-# `Rigor::Plugin.register`, which the body of
-# `lib/rigor/plugin/dry_struct.rb` performs at load time.
+# Gem entry point. Required by Rigor's plugin loader when `.rigor.yml` lists `rigor-dry-struct` under
+# `plugins:`. The loader expects this `require` to side-effect a call to `Rigor::Plugin.register`,
+# which the body of `lib/rigor/plugin/dry_struct.rb` performs at load time.
 require_relative "rigor/plugin/dry_struct"

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

@@ -5,15 +5,12 @@ require "prism"
 module Rigor
   module Plugin
     class DryTypes < Rigor::Plugin::Base
-      # Walks project source for `module X; include Dry.Types(); end`
-      # shapes and emits a `{ "<X>::<Alias>" => "<UnderlyingClass>" }`
-      # alias table covering the dry-types canonical-shortcut names.
-      # See {DryTypes} module-docstring for the floor / ceiling
-      # scoping.
+      # Walks project source for `module X; include Dry.Types(); end` shapes and emits a
+      # `{ "<X>::<Alias>" => "<UnderlyingClass>" }` alias table covering the dry-types canonical-shortcut
+      # names. See {DryTypes} module-docstring for the floor / ceiling scoping.
       module AliasScanner
-        # The canonical-shortcut names dry-types exposes through
-        # `include Dry.Types()`. Mirrors `Dry::Types.type_keys`
-        # from the upstream gem.
+        # The canonical-shortcut names dry-types exposes through `include Dry.Types()`. Mirrors
+        # `Dry::Types.type_keys` from the upstream gem.
         CANONICAL_ALIASES = {
           "String" => "String",
           "Integer" => "Integer",
@@ -32,29 +29,21 @@ module Rigor
           "Any" => "Object"
         }.freeze
 
-        # Slice 2 — nested-category aliases. dry-types installs
-        # four parallel coercion categories: `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.
+        # Slice 2 — nested-category aliases. dry-types installs four parallel coercion categories:
+        # `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.
         NESTED_CATEGORIES = %w[Coercible Strict Params JSON].freeze
         private_constant :NESTED_CATEGORIES
 
         module_function
 
-        # @param paths [Array<String>] absolute paths to `.rb`
-        #   files the project's `paths:` resolves to.
-        # @return [Hash{String => String}] frozen
-        #   `{aliased_name => underlying_class_name}` map. Empty
+        # @param paths [Array<String>] absolute paths to `.rb` files the project's `paths:` resolves to.
+        # @return [Hash{String => String}] frozen `{aliased_name => underlying_class_name}` map. Empty
         #   when no `include Dry.Types()` declaration is found.
         def scan(paths:)
           results = paths.flat_map { |path| scan_file(path) }
@@ -64,16 +53,16 @@ module Rigor
           base = canonical_table(modules)
           results.each do |result|
             result[:compositions].each do |const_name, underlying|
-              # Each result's compositions are scoped under that
-              # result's enclosing module (`Types::Email`, etc.).
+              # Each result's compositions are scoped under that result's enclosing module
+              # (`Types::Email`, etc.).
               base["#{result[:module_name]}::#{const_name}"] ||= underlying
             end
           end
           base.freeze
         end
 
-        # Populates the canonical-shortcut + nested-category
-        # table (15 + 15 × 4 = 75 entries per alias module).
+        # Populates the canonical-shortcut + nested-category table (15 + 15 × 4 = 75 entries per alias
+        # module).
         def canonical_table(modules)
           modules.each_with_object({}) do |module_name, acc|
             CANONICAL_ALIASES.each do |alias_name, underlying|
@@ -96,22 +85,18 @@ module Rigor
             { module_name: module_info[:module_name], compositions: compositions }
           end
         rescue StandardError
-          # Missing-file / parse failures degrade to "no
-          # contribution from this file"; the plugin's
-          # user-visible surface is the published fact, and
-          # dropping unparseable files keeps the fact stable.
+          # Missing-file / parse failures degrade to "no contribution from this file"; the plugin's
+          # user-visible surface is the published fact, and dropping unparseable files keeps the fact
+          # stable.
           []
         end
         private_class_method :scan_file
 
-        # Walks a Prism AST collecting alias-module info:
-        # `{module_name:, body:}` for every `module X; include
-        # Dry.Types(); …end` shape. Tracks the enclosing module
-        # chain so a nested `module App; module Types; include
-        # Dry.Types(); end; end` publishes `"App::Types"` as the
-        # alias scope. The `body:` field is the
-        # `Prism::StatementsNode` (or nil) we re-walk later for
-        # user-authored compositions (slice 3).
+        # Walks a Prism AST collecting alias-module info: `{module_name:, body:}` for every `module X;
+        # include Dry.Types(); …end` shape. Tracks the enclosing module chain so a nested `module App;
+        # module Types; include Dry.Types(); end; end` publishes `"App::Types"` as the alias scope. The
+        # `body:` field is the `Prism::StatementsNode` (or nil) we re-walk later for user-authored
+        # compositions (slice 3).
         def collect_alias_modules(node, qualified_prefix)
           return [] unless node.is_a?(Prism::Node)
 
@@ -127,9 +112,8 @@ module Rigor
                       end
             current + children
           when Prism::ClassNode
-            # Module-level declarations win; we don't recurse into
-            # class bodies for `include Dry.Types()` because the
-            # canonical pattern is module-level.
+            # Module-level declarations win; we don't recurse into class bodies for `include
+            # Dry.Types()` because the canonical pattern is module-level.
             []
           else
             node.compact_child_nodes.flat_map { |c| collect_alias_modules(c, qualified_prefix) }
@@ -137,31 +121,20 @@ module Rigor
         end
         private_class_method :collect_alias_modules
 
-        # Slice 3 — user-authored composition recognition.
-        # Walks the alias-module body for `Email =
-        # String.constrained(...)` shapes. Each
-        # `ConstantWriteNode` whose RHS is a method chain
-        # rooted on a canonical-shortcut name (`String`,
-        # `Integer`, …) — or on a nested-category form
-        # (`Strict::String` etc.) — registers the LHS under
-        # the canonical head's underlying class. Unions
-        # (`String | Integer`) and intersections are skipped
-        # (no single underlying class).
+        # Slice 3 — user-authored composition recognition. Walks the alias-module body for `Email =
+        # String.constrained(...)` shapes. Each `ConstantWriteNode` whose RHS is a method chain rooted on
+        # a canonical-shortcut name (`String`, `Integer`, …) — or on a nested-category form
+        # (`Strict::String` etc.) — registers the LHS under the canonical head's underlying class. Unions
+        # (`String | Integer`) and intersections are skipped (no single underlying class).
         #
-        # Slice 4 — transitive composition resolution. After
-        # the direct (slice-3) pass collects compositions
-        # whose RHS root is canonical, a second pass walks the
-        # remaining `ConstantWriteNode`s for RHS shapes that
-        # resolve THROUGH an already-published composition —
-        # e.g. `ManagerEmail = Email` (bare reference) or
-        # `ManagerEmail = Email.constrained(min_size: 3)`
-        # (method chain rooted on a composition LHS). Cycle
-        # detection: `A = B; B = A` resolves neither (each
-        # LHS's resolution walk sees itself in the visited
-        # set and bails). Unknown references (`ManagerEmail =
-        # NotAComposition`) silently drop — the user is free
-        # to assign any constant to any other; the plugin only
-        # publishes facts when the underlying class is known.
+        # Slice 4 — transitive composition resolution. After the direct (slice-3) pass collects
+        # compositions whose RHS root is canonical, a second pass walks the remaining
+        # `ConstantWriteNode`s for RHS shapes that resolve THROUGH an already-published composition —
+        # e.g. `ManagerEmail = Email` (bare reference) or `ManagerEmail = Email.constrained(min_size: 3)`
+        # (method chain rooted on a composition LHS). Cycle detection: `A = B; B = A` resolves neither
+        # (each LHS's resolution walk sees itself in the visited set and bails). Unknown references
+        # (`ManagerEmail = NotAComposition`) silently drop — the user is free to assign any constant to
+        # any other; the plugin only publishes facts when the underlying class is known.
         def collect_compositions(body)
           return {} if body.nil?
 
@@ -188,14 +161,10 @@ module Rigor
         end
         private_class_method :collect_compositions
 
-        # Slice-4 helper. Returns the un-resolved RHS root
-        # constant name (not necessarily a CANONICAL_ALIASES
-        # entry) for transitive resolution. Mirrors
-        # {composition_head_canonical} but accepts any
-        # `ConstantReadNode` / `ConstantPathNode` tail rather
-        # than canonical-only. Declines on union / intersection
-        # operators for the same single-underlying-class
-        # reason.
+        # Slice-4 helper. Returns the un-resolved RHS root constant name (not necessarily a
+        # CANONICAL_ALIASES entry) for transitive resolution. Mirrors {composition_head_canonical} but
+        # accepts any `ConstantReadNode` / `ConstantPathNode` tail rather than canonical-only. Declines on
+        # union / intersection operators for the same single-underlying-class reason.
         def transitive_reference_name(node)
           case node
           when Prism::ConstantReadNode
@@ -211,14 +180,10 @@ module Rigor
         end
         private_class_method :transitive_reference_name
 
-        # Slice-4 helper. Resolves `lhs`'s RHS through the
-        # `direct` (slice-3) compositions table, chaining
-        # through `ref_edges` for transitive references.
-        # Returns the canonical underlying-class name (e.g.
-        # `"String"`) or nil when no chain ends at a direct
-        # composition. Cycles silently return nil — every step
-        # adds the current lhs to `visited` and bails on
-        # re-entry.
+        # Slice-4 helper. Resolves `lhs`'s RHS through the `direct` (slice-3) compositions table, chaining
+        # through `ref_edges` for transitive references. Returns the canonical underlying-class name
+        # (e.g. `"String"`) or nil when no chain ends at a direct composition. Cycles silently return nil
+        # — every step adds the current lhs to `visited` and bails on re-entry.
         def resolve_transitive_ref(lhs, direct, ref_edges, visited:)
           return nil if visited.include?(lhs)
 
@@ -231,25 +196,19 @@ module Rigor
         end
         private_class_method :resolve_transitive_ref
 
-        # Walks an RHS expression looking for the canonical
-        # shortcut name at the root of a method chain. Returns
-        # the canonical name (`"String"` etc.) or nil.
+        # Walks an RHS expression looking for the canonical shortcut name at the root of a method chain.
+        # Returns the canonical name (`"String"` etc.) or nil.
         #
         # Recognised shapes (recursively on `node.receiver`):
         #
-        # - Bare `String` / `Integer` — `Prism::ConstantReadNode`
-        #   whose name is in `CANONICAL_ALIASES`.
-        # - `Strict::String` / `Coercible::Integer` / etc. —
-        #   `Prism::ConstantPathNode` whose tail is in
+        # - Bare `String` / `Integer` — `Prism::ConstantReadNode` whose name is in `CANONICAL_ALIASES`.
+        # - `Strict::String` / `Coercible::Integer` / etc. — `Prism::ConstantPathNode` whose tail is in
         #   `CANONICAL_ALIASES`.
-        # - `String.constrained(...)` / `.optional` /
-        #   `.default(...)` / arbitrary single-arg method —
+        # - `String.constrained(...)` / `.optional` / `.default(...)` / arbitrary single-arg method —
         #   recurse on the receiver.
         #
-        # Declines on `String | Integer` (union, `:|`) and
-        # `String & Foo` (intersection, `:&`) so the alias
-        # table doesn't claim a single underlying class for
-        # a multi-class composition.
+        # Declines on `String | Integer` (union, `:|`) and `String & Foo` (intersection, `:&`) so the
+        # alias table doesn't claim a single underlying class for a multi-class composition.
         def composition_head_canonical(node)
           case node
           when Prism::ConstantReadNode
@@ -266,12 +225,10 @@ module Rigor
         end
         private_class_method :composition_head_canonical
 
-        # `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").
+        # `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").
         def contains_dry_types_include?(body)
           return false if body.nil?
 
@@ -295,10 +252,9 @@ module Rigor
         end
         private_class_method :tree_walk
 
-        # Matches `include Dry.Types()` (with or without kwargs).
-        # The receiver of the include call MUST be implicit
-        # (i.e., called on `self`), and the argument MUST be a
-        # method call on the `Dry` constant naming `Types`.
+        # Matches `include Dry.Types()` (with or without kwargs). The receiver of the include call MUST
+        # be implicit (i.e., called on `self`), and the argument MUST be a method call on the `Dry`
+        # constant naming `Types`.
         def include_call_targeting_dry_types?(node)
           return false unless node.is_a?(Prism::CallNode)
           return false unless node.name == :include && node.receiver.nil?
@@ -319,11 +275,9 @@ module Rigor
         end
         private_class_method :dry_types_call?
 
-        # Resolves a `Prism::ConstantPathNode` /
-        # `Prism::ConstantReadNode` chain to its dot-separated
-        # name (e.g. `"App::Types"`). Returns nil for the
-        # dynamic-prefix shape so the scanner treats those as
-        # opaque rather than guessing.
+        # Resolves a `Prism::ConstantPathNode` / `Prism::ConstantReadNode` chain to its dot-separated
+        # name (e.g. `"App::Types"`). Returns nil for the dynamic-prefix shape so the scanner treats
+        # those as opaque rather than guessing.
         def qualified_name_for(node)
           case node
           when Prism::ConstantReadNode then node.name.to_s