rigortype 0.2.7 → 0.2.8

data/lib/rigor/sig_gen/layout_index.rb

@@ -4,29 +4,22 @@ require "rbs"
 
 module Rigor
   module SigGen
-    # Pre-scans every `.rbs` file under the configured
-    # `signature_paths` to build a `qualified_class_name →
+    # Pre-scans every `.rbs` file under the configured `signature_paths` to build a `qualified_class_name →
     # sig_file_path` map.
     #
-    # ADR-14 path-mapper limitation surfaced repeatedly during
-    # the self-dogfood: the existing rigor `sig/` consolidates
-    # multiple `.rb` sources into one `.rbs` file (e.g.
-    # `sig/rigor/type.rbs` declares all 14 `Type::*` classes,
-    # `sig/rigor.rbs` declares `CLI::TypeOfCommand` and
-    # `CLI::TypeScanCommand`). The naive 1:1 mapper writes new
-    # files alongside the existing consolidated ones, producing
+    # ADR-14 path-mapper limitation surfaced repeatedly during the self-dogfood: the existing rigor `sig/`
+    # consolidates multiple `.rb` sources into one `.rbs` file (e.g. `sig/rigor/type.rbs` declares all 14
+    # `Type::*` classes, `sig/rigor.rbs` declares `CLI::TypeOfCommand` and `CLI::TypeScanCommand`). The naive
+    # 1:1 mapper writes new files alongside the existing consolidated ones, producing
     # `RBS::DuplicatedMethodDefinition` errors at lookup time.
     #
-    # The index lets {PathMapper} route a candidate to the
-    # consolidated sig file when the class is already declared
-    # there, falling back to the 1:1 mirror only when the
-    # class has no existing declaration anywhere under the
-    # signature tree.
+    # The index lets {PathMapper} route a candidate to the consolidated sig file when the class is already
+    # declared there, falling back to the 1:1 mirror only when the class has no existing declaration anywhere
+    # under the signature tree.
     #
-    # First-found wins on duplicate declarations across files;
-    # RBS itself allows the same class to be declared in
-    # multiple files for additive member contributions, but
-    # the writer only needs one canonical target per class.
+    # First-found wins on duplicate declarations across files; RBS itself allows the same class to be declared
+    # in multiple files for additive member contributions, but the writer only needs one canonical target per
+    # class.
     class LayoutIndex
       # @param signature_paths [Array<String, Pathname>, nil]
       #   the `.rigor.yml`-configured signature directories.
@@ -84,8 +77,7 @@ module Rigor
         _, _, decls = RBS::Parser.parse_signature(source)
         record_decls(decls, [], rbs_path, accumulator)
       rescue StandardError
-        # Bad RBS file — skip silently; the user's `rigor
-        # check` run will surface the real parse error
+        # Bad RBS file — skip silently; the user's `rigor check` run will surface the real parse error
         # elsewhere.
       end
 

data/lib/rigor/sig_gen/method_candidate.rb

@@ -4,24 +4,20 @@ module Rigor
   module SigGen
     # Per-method record produced by the generator.
     #
-    # `classification` is one of the {Classification} constants;
-    # the remaining fields are populated only when applicable
-    # to that classification.
+    # `classification` is one of the {Classification} constants; the remaining fields are populated only when
+    # applicable to that classification.
     #
     # - `path` — the source `.rb` file the def came from.
-    # - `class_name` — qualified receiver class name (e.g.
-    #   `"Foo::Bar"`). `nil` for top-level / DSL-block defs
+    # - `class_name` — qualified receiver class name (e.g. `"Foo::Bar"`). `nil` for top-level / DSL-block defs
     #   the MVP skips.
     # - `method_name` — the def's `Symbol` name.
     # - `kind` — `:instance` or `:singleton`.
-    # - `inferred_return` — `Rigor::Type` instance (or `nil`
-    #   when the inference pass disqualified the def).
-    # - `declared_return_rbs` — the existing RBS-declared return
-    #   spelling, or `nil` when no RBS declares the method.
-    # - `rbs` — the rendered RBS one-liner the generator would
-    #   emit (`nil` for skipped / equivalent rows).
-    # - `skip_reason` — one of {Classification::SKIP_DIAGNOSTIC_IDS}
-    #   keys when classification is `:skipped`, else `nil`.
+    # - `inferred_return` — `Rigor::Type` instance (or `nil` when the inference pass disqualified the def).
+    # - `declared_return_rbs` — the existing RBS-declared return spelling, or `nil` when no RBS declares the
+    #   method.
+    # - `rbs` — the rendered RBS one-liner the generator would emit (`nil` for skipped / equivalent rows).
+    # - `skip_reason` — one of {Classification::SKIP_DIAGNOSTIC_IDS} keys when classification is `:skipped`,
+    #   else `nil`.
     class MethodCandidate
       attr_reader :path, :class_name, :method_name, :kind, :classification,
                   :inferred_return, :declared_return_rbs, :rbs, :skip_reason,
@@ -41,10 +37,9 @@ module Rigor
         @skip_reason = skip_reason
         @namespace_kinds = namespace_kinds.freeze
         @class_shells = class_shells.freeze
-        # Qualified-class-name => superclass source token (e.g.
-        # `{ "Foo::Bar" => "Base" }`). Only plain-constant
-        # superclasses appear; computed ones are absent. The Writer
-        # emits `class Bar < Base` for the leaf when present.
+        # Qualified-class-name => superclass source token (e.g. `{ "Foo::Bar" => "Base" }`). Only plain-constant
+        # superclasses appear; computed ones are absent. The Writer emits `class Bar < Base` for the leaf when
+        # present.
         @class_superclasses = class_superclasses.freeze
         freeze
       end

data/lib/rigor/sig_gen/observation_collector.rb

@@ -10,37 +10,26 @@ require_relative "../inference/scope_indexer"
 
 module Rigor
   module SigGen
-    # ADR-14 slice 3 — caller-side argument-type observation
-    # collector.
+    # ADR-14 slice 3 — caller-side argument-type observation collector.
     #
-    # Walks the user-supplied `--observe=PATH...` tree (default
-    # `spec/`), parses every `.rb` file with `Prism`, scope-
-    # indexes it the same way the main generator does, and
-    # records the per-call-site argument-type tuples for every
-    # `Prism::CallNode` whose receiver types as a
-    # `Type::Nominal`. The {Generator} consumes the resulting
-    # map to render `--params=observed` RBS:
+    # Walks the user-supplied `--observe=PATH...` tree (default `spec/`), parses every `.rb` file with `Prism`,
+    # scope- indexes it the same way the main generator does, and records the per-call-site argument-type tuples
+    # for every `Prism::CallNode` whose receiver types as a `Type::Nominal`. The {Generator} consumes the
+    # resulting map to render `--params=observed` RBS:
     #
-    # @return [Hash{[class_name, method_name] =>
-    #   Array<Array<Rigor::Type>>}]
+    # @return [Hash{[class_name, method_name] => Array<Array<Rigor::Type>>}]
     #
-    # ADR-5 clause 2 compliance: the observed union is the
-    # MOST PERMISSIVE parameter contract the existing callers
-    # prove sufficient — by construction it accepts every type
-    # any caller has already passed. The collector only
-    # surfaces the data; the default `--params=untyped` keeps
-    # the observation inert until the user opts in.
+    # ADR-5 clause 2 compliance: the observed union is the MOST PERMISSIVE parameter contract the existing
+    # callers prove sufficient — by construction it accepts every type any caller has already passed. The
+    # collector only surfaces the data; the default `--params=untyped` keeps the observation inert until the
+    # user opts in.
     #
     # MVP scope:
-    # - Explicit-receiver calls only (`foo.bar(args)`). Implicit-
-    #   self calls inside class bodies and RSpec-style
-    #   `let` / `subject` bindings ride on slice 5's optional
-    #   `rigor-rspec` integration.
-    # - Calls whose receiver does not type as a `Type::Nominal`
-    #   (e.g. `(some_dynamic).bar(...)`) are skipped — the
-    #   collector cannot attribute them to a specific class.
-    # - Zero-argument calls give no observation; methods are
-    #   matched by `(class_name, method_name)` only.
+    # - Explicit-receiver calls only (`foo.bar(args)`). Implicit-self calls inside class bodies and RSpec-style
+    #   `let` / `subject` bindings ride on slice 5's optional `rigor-rspec` integration.
+    # - Calls whose receiver does not type as a `Type::Nominal` (e.g. `(some_dynamic).bar(...)`) are skipped —
+    #   the collector cannot attribute them to a specific class.
+    # - Zero-argument calls give no observation; methods are matched by `(class_name, method_name)` only.
     class ObservationCollector # rubocop:disable Metrics/ClassLength
       # @param configuration [Rigor::Configuration]
       # @param paths [Array<String>] observe paths (files /
@@ -104,11 +93,9 @@ module Rigor
         walk_calls(parse_result.value, scope_index, bindings, observations)
       end
 
-      # Pre-walks `@source_paths` to collect every qualified
-      # class / module declaration. The result seeds the
-      # `discovered_classes` table on each observe-tree scope so
-      # `Foo.new` and `Foo` resolve to the right singleton carrier
-      # even when no RBS sig describes `Foo` yet.
+      # Pre-walks `@source_paths` to collect every qualified class / module declaration. The result seeds the
+      # `discovered_classes` table on each observe-tree scope so `Foo.new` and `Foo` resolve to the right
+      # singleton carrier even when no RBS sig describes `Foo` yet.
       def preindex_source_classes
         accumulator = {}
         resolve_paths(@source_paths).each { |path| harvest_classes_from(path, accumulator) }
@@ -122,8 +109,7 @@ module Rigor
 
         walk_class_decls(parse_result.value, [], accumulator)
       rescue StandardError
-        # Source-side harvest failures are tolerated silently
-        # — the collector still runs on whichever files
+        # Source-side harvest failures are tolerated silently — the collector still runs on whichever files
         # parsed cleanly.
       end
 
@@ -180,13 +166,10 @@ module Rigor
         observations[key] << observation
       end
 
-      # ADR-14 follow-up (A): `.new` → `:initialize` routing.
-      # `MethodCatalog.new(path: ...)` types its receiver as
-      # `Type::Singleton[MethodCatalog]` and its call name as
-      # `:new`, but the *implicit* effect at runtime is a call
-      # to `MethodCatalog#initialize(path: ...)`. Route the
-      # observation under `[class_name, :initialize]` so the
-      # initialize-stub renderer can consult it.
+      # ADR-14 follow-up (A): `.new` → `:initialize` routing. `MethodCatalog.new(path: ...)` types its receiver
+      # as `Type::Singleton[MethodCatalog]` and its call name as `:new`, but the *implicit* effect at runtime is
+      # a call to `MethodCatalog#initialize(path: ...)`. Route the observation under `[class_name, :initialize]`
+      # so the initialize-stub renderer can consult it.
       def observation_key(call_node, receiver_type)
         if receiver_type.is_a?(Type::Singleton) && call_node.name == :new
           [receiver_type.class_name, :initialize]
@@ -195,20 +178,15 @@ module Rigor
         end
       end
 
-      # ADR-14 slice 5 — RSpec-aware receiver typing.
-      # Resolves a CallNode receiver against the collected
-      # `bindings` map (built by {#collect_rspec_bindings})
-      # before falling back to ordinary `scope.type_of`. The
+      # ADR-14 slice 5 — RSpec-aware receiver typing. Resolves a CallNode receiver against the collected
+      # `bindings` map (built by {#collect_rspec_bindings}) before falling back to ordinary `scope.type_of`. The
       # three RSpec-shaped receivers we recognise:
       #
-      # - Bare-name CallNode (`subject`, `other`, ...) whose
-      #   name matches a `subject` / `let(:name)` binding —
+      # - Bare-name CallNode (`subject`, `other`, ...) whose name matches a `subject` / `let(:name)` binding —
       #   return the binding's recorded type.
-      # - `described_class.new(...)` chain — when the
-      #   surrounding `describe Foo do … end` resolved `Foo`,
+      # - `described_class.new(...)` chain — when the surrounding `describe Foo do … end` resolved `Foo`,
       #   return `Type::Nominal[Foo]`.
-      # - Anything else — pass through to `scope.type_of`,
-      #   matching slice-3 behaviour.
+      # - Anything else — pass through to `scope.type_of`, matching slice-3 behaviour.
       def resolve_receiver_type(receiver, scope, bindings)
         return resolve_described_class_new(bindings) if described_class_new?(receiver)
         return bindings[receiver.name] if bound_call?(receiver, bindings)
@@ -246,21 +224,14 @@ module Rigor
           node.block.nil?
       end
 
-      # Walks the spec file for `describe X do … end` /
-      # `RSpec.describe X do … end` blocks plus the
-      # `subject` / `let(:name)` declarations inside them.
-      # Returns a flat map `{ binding_name (Symbol) => Type }`
-      # plus a synthetic `:described_class` slot keyed off
-      # the nearest enclosing `describe`.
+      # Walks the spec file for `describe X do … end` / `RSpec.describe X do … end` blocks plus the
+      # `subject` / `let(:name)` declarations inside them. Returns a flat map `{ binding_name (Symbol) => Type }`
+      # plus a synthetic `:described_class` slot keyed off the nearest enclosing `describe`.
       #
-      # The recogniser is intentionally lightweight: it does
-      # not enforce RSpec scope rules across `describe` /
-      # `context` blocks. Nested `describe` declarations
-      # overwrite the outer `described_class` for the
-      # remainder of the walk; same-name `let` bindings are
-      # last-wins. This matches the typical one-spec-file
-      # shape ADR-14 slice 5 targets without re-implementing
-      # the `rigor-rspec` plugin's full scope analyser.
+      # The recogniser is intentionally lightweight: it does not enforce RSpec scope rules across `describe` /
+      # `context` blocks. Nested `describe` declarations overwrite the outer `described_class` for the
+      # remainder of the walk; same-name `let` bindings are last-wins. This matches the typical one-spec-file
+      # shape ADR-14 slice 5 targets without re-implementing the `rigor-rspec` plugin's full scope analyser.
       def collect_rspec_bindings(root, scope_index)
         bindings = {}
         walk_rspec_bindings(root, bindings, scope_index)
@@ -339,12 +310,9 @@ module Rigor
         end
       end
 
-      # ADR-14 follow-up (B): walks a call's argument list
-      # separating positional from keyword arguments and
-      # returning an {ObservedCall} carrier. Splat /
-      # forwarded / block arguments still abort the
-      # observation (`nil`) — those don't map cleanly to a
-      # single per-position type the renderer can union.
+      # ADR-14 follow-up (B): walks a call's argument list separating positional from keyword arguments and
+      # returning an {ObservedCall} carrier. Splat / forwarded / block arguments still abort the observation
+      # (`nil`) — those don't map cleanly to a single per-position type the renderer can union.
       def collect_args(call_node, scope)
         positional = []
         keyword = {}

data/lib/rigor/sig_gen/observed_call.rb

@@ -2,27 +2,19 @@
 
 module Rigor
   module SigGen
-    # Per-call-site argument observation produced by
-    # {ObservationCollector}. ADR-14 follow-up: the earlier
-    # MVP shape (`Array[Type]` of positional types only)
-    # could not represent keyword arguments — keyword calls
-    # like `MethodCatalog.new(path: ..., mutating_selectors: ...)`
-    # were silently skipped in that shape.
-    # The new shape carries positional and keyword arg types
-    # in parallel so the per-position / per-keyword unions
-    # can each be reconstructed independently.
+    # Per-call-site argument observation produced by {ObservationCollector}. ADR-14 follow-up: the earlier MVP
+    # shape (`Array[Type]` of positional types only) could not represent keyword arguments — keyword calls like
+    # `MethodCatalog.new(path: ..., mutating_selectors: ...)` were silently skipped in that shape. The new shape
+    # carries positional and keyword arg types in parallel so the per-position / per-keyword unions can each be
+    # reconstructed independently.
     #
     # The carrier is intentionally minimal:
-    # - `positional` — frozen Array of `Rigor::Type` per
-    #   positional argument, in call-site order.
-    # - `keyword` — frozen Hash mapping each keyword
-    #   argument's Symbol name to its `Rigor::Type`.
+    # - `positional` — frozen Array of `Rigor::Type` per positional argument, in call-site order.
+    # - `keyword` — frozen Hash mapping each keyword argument's Symbol name to its `Rigor::Type`.
     #
-    # Generator-side callers also accept a legacy shape
-    # (plain Array of types) for backward compatibility with
-    # specs that constructed observations directly before
-    # this carrier existed; `ObservedCall.from(...)` does the
-    # lift.
+    # Generator-side callers also accept a legacy shape (plain Array of types) for backward compatibility with
+    # specs that constructed observations directly before this carrier existed; `ObservedCall.from(...)` does
+    # the lift.
     class ObservedCall
       attr_reader :positional, :keyword
 
@@ -45,11 +37,9 @@ module Rigor
         [ObservedCall, positional, keyword].hash
       end
 
-      # Lifts the legacy plain-Array shape into an
-      # `ObservedCall` carrier. Already-lifted values pass
-      # through unchanged. Used by `Generator#initialize`'s
-      # observations-normalisation pass so spec fixtures
-      # written against the slice-3 surface keep working.
+      # Lifts the legacy plain-Array shape into an `ObservedCall` carrier. Already-lifted values pass through
+      # unchanged. Used by `Generator#initialize`'s observations-normalisation pass so spec fixtures written
+      # against the slice-3 surface keep working.
       def self.from(value)
         case value
         when ObservedCall then value

data/lib/rigor/sig_gen/path_mapper.rb

@@ -2,33 +2,24 @@
 
 module Rigor
   module SigGen
-    # Maps a source `.rb` file to its target `.rbs` sig file
-    # under the project's signature tree.
+    # Maps a source `.rb` file to its target `.rbs` sig file under the project's signature tree.
     #
     # ADR-14 § "Output layout":
-    # - `--write` MUST NOT touch files outside
-    #   `configuration.signature_paths` (default `sig/`).
-    # - The first slice supports one source file → one RBS
-    #   file; multi-class files emit one RBS containing both
+    # - `--write` MUST NOT touch files outside `configuration.signature_paths` (default `sig/`).
+    # - The first slice supports one source file → one RBS file; multi-class files emit one RBS containing both
     #   classes (handled by the {Writer}, not here).
     #
-    # The mapping convention mirrors the Ruby community
-    # default: strip the source root prefix (the first entry
-    # of `configuration.paths`, typically `"lib"`), swap the
-    # extension, and place the result under the first entry of
-    # `configuration.signature_paths` (typically `"sig"`).
+    # The mapping convention mirrors the Ruby community default: strip the source root prefix (the first entry
+    # of `configuration.paths`, typically `"lib"`), swap the extension, and place the result under the first
+    # entry of `configuration.signature_paths` (typically `"sig"`).
     #
-    # ADR-14 follow-up: when a class is already declared in
-    # an existing consolidated sig file (e.g. `sig/rigor/type.rbs`
-    # holds all `Rigor::Type::*` classes), the optional
-    # `LayoutIndex` re-routes the target to that file so the
-    # writer updates the consolidated declaration instead of
-    # creating a duplicate at the 1:1 mirror path.
+    # ADR-14 follow-up: when a class is already declared in an existing consolidated sig file (e.g.
+    # `sig/rigor/type.rbs` holds all `Rigor::Type::*` classes), the optional `LayoutIndex` re-routes the target
+    # to that file so the writer updates the consolidated declaration instead of creating a duplicate at the 1:1
+    # mirror path.
     #
-    # When the source path is not under any configured source
-    # root (e.g. files supplied directly on the CLI from
-    # outside `lib/`), the full relative path is preserved
-    # under the sig root.
+    # When the source path is not under any configured source root (e.g. files supplied directly on the CLI
+    # from outside `lib/`), the full relative path is preserved under the sig root.
     class PathMapper
       # @param configuration [Rigor::Configuration]
       # @param project_root [String, Pathname] (defaults to `Dir.pwd`)
@@ -63,9 +54,8 @@ module Rigor
         @layout_index.file_for(class_name)
       end
 
-      # The directory `--write` is allowed to create / modify.
-      # Used by callers to assert the target stays inside the
-      # configured signature tree before touching the disk.
+      # The directory `--write` is allowed to create / modify. Used by callers to assert the target stays inside
+      # the configured signature tree before touching the disk.
       def sig_root_dir
         @sig_root_dir ||= @project_root / sig_root_name
       end
@@ -76,8 +66,7 @@ module Rigor
         path = Pathname(source_path)
         return path unless path.absolute?
 
-        # Both sides go through realpath so macOS `/tmp` vs
-        # `/private/tmp` (and any other symlinked project
+        # Both sides go through realpath so macOS `/tmp` vs `/private/tmp` (and any other symlinked project
         # root) compare cleanly.
         path.realpath.relative_path_from(@project_root.realpath)
       rescue ArgumentError, Errno::ENOENT
@@ -95,9 +84,8 @@ module Rigor
         components.empty? ? Pathname("") : Pathname(components.join(File::SEPARATOR))
       end
 
-      # `Configuration` resolves `paths:` and `signature_paths:`
-      # to absolute Strings. We only need the trailing basename
-      # for the mapping (`/abs/lib` → `lib`, `/abs/app` → `app`).
+      # `Configuration` resolves `paths:` and `signature_paths:` to absolute Strings. We only need the trailing
+      # basename for the mapping (`/abs/lib` → `lib`, `/abs/app` → `app`).
       def source_root_name
         @source_root_name ||= begin
           path = @configuration.paths.first

data/lib/rigor/sig_gen/renderer.rb

@@ -9,16 +9,12 @@ module Rigor
     # Output formatter for `rigor sig-gen`.
     #
     # Supports three modes:
-    # - `:print` (default) — RBS skeletons grouped by source
-    #   file and class declaration, ready for the user to
+    # - `:print` (default) — RBS skeletons grouped by source file and class declaration, ready for the user to
     #   paste into `sig/<path>.rbs`.
-    # - `:diff` — a unified-style diff comparing the existing
-    #   RBS spelling (if any) against the inferred spelling.
-    #   The MVP renders a minimal "- declared / + inferred"
-    #   block; full per-file diffing arrives with slice 2's
-    #   `--write` merge.
-    # - `:json` — machine-readable payload with the same
-    #   classification table as `:print`.
+    # - `:diff` — a unified-style diff comparing the existing RBS spelling (if any) against the inferred
+    #   spelling. The MVP renders a minimal "- declared / + inferred" block; full per-file diffing arrives with
+    #   slice 2's `--write` merge.
+    # - `:json` — machine-readable payload with the same classification table as `:print`.
     class Renderer
       def initialize(out:)
         @out = out
@@ -107,10 +103,8 @@ module Rigor
 
       public
 
-      # Renders the per-source-file outcomes of a `--write`
-      # run. Distinct from {#render} because the write
-      # path's reporting surface is action-oriented (created
-      # / updated / skipped) rather than candidate-oriented.
+      # Renders the per-source-file outcomes of a `--write` run. Distinct from {#render} because the write
+      # path's reporting surface is action-oriented (created / updated / skipped) rather than candidate-oriented.
       def render_write(results:, format:)
         case format
         when "json" then render_write_json(results)

data/lib/rigor/sig_gen/type_elaborator.rb

@@ -5,30 +5,20 @@ require_relative "../type"
 
 module Rigor
   module SigGen
-    # ADR-14 follow-up to the dogfood findings: when the
-    # inference engine produces a `Type::Nominal` for a class
-    # that requires type parameters (`Array`, `Hash`, `Set`,
-    # `Range`, `Enumerable`, `Enumerator`, ...) with an empty
-    # `type_args` array, the carrier is structurally valid but
-    # `erase_to_rbs` renders just `Array` / `Hash` / etc. While
-    # RBS itself accepts the bare form, downstream consumers
-    # (Steep, IDE plugins, gem-published `sig/` trees) expect
-    # the elaborated `Array[untyped]` / `Hash[untyped, untyped]`
-    # spelling.
+    # ADR-14 follow-up to the dogfood findings: when the inference engine produces a `Type::Nominal` for a class
+    # that requires type parameters (`Array`, `Hash`, `Set`, `Range`, `Enumerable`, `Enumerator`, ...) with an
+    # empty `type_args` array, the carrier is structurally valid but `erase_to_rbs` renders just `Array` /
+    # `Hash` / etc. While RBS itself accepts the bare form, downstream consumers (Steep, IDE plugins,
+    # gem-published `sig/` trees) expect the elaborated `Array[untyped]` / `Hash[untyped, untyped]` spelling.
     #
-    # This module walks a `Rigor::Type` tree and rebuilds every
-    # raw `Nominal[C]` for a generic `C` into `Nominal[C, [Dynamic, ...]]`
-    # where the arity comes from
-    # `Reflection.class_type_param_names`. The transformation is
-    # purely cosmetic — the resulting carrier is structurally
-    # distinct from the raw form, but `accepts(other) == accepts(other)`
-    # holds because the gradual mode treats `Dynamic[top]`
-    # arguments as covering anything.
+    # This module walks a `Rigor::Type` tree and rebuilds every raw `Nominal[C]` for a generic `C` into
+    # `Nominal[C, [Dynamic, ...]]` where the arity comes from `Reflection.class_type_param_names`. The
+    # transformation is purely cosmetic — the resulting carrier is structurally distinct from the raw form, but
+    # `accepts(other) == accepts(other)` holds because the gradual mode treats `Dynamic[top]` arguments as
+    # covering anything.
     #
-    # The module is sig-gen-local; the broader question of
-    # whether the inference engine itself should always
-    # construct generics with explicit type_args is queued as
-    # an ADR-14 follow-up.
+    # The module is sig-gen-local; the broader question of whether the inference engine itself should always
+    # construct generics with explicit type_args is queued as an ADR-14 follow-up.
     module TypeElaborator
       # @param type [Rigor::Type]
       # @param environment [Rigor::Environment]
@@ -70,12 +60,9 @@ module Rigor
       end
 
       def self.elaborate_hash_shape(type, _environment, _arity_cache)
-        # HashShape's element types are read-only on the carrier;
-        # rebuilding them would need going through the per-pair
-        # required/optional/read-only machinery. Sig-gen only
-        # routes top-level returns through here for now —
-        # nested HashShape elaboration ships as a follow-up if
-        # the need surfaces.
+        # HashShape's element types are read-only on the carrier; rebuilding them would need going through the
+        # per-pair required/optional/read-only machinery. Sig-gen only routes top-level returns through here for
+        # now — nested HashShape elaboration ships as a follow-up if the need surfaces.
         type
       end
 

data/lib/rigor/sig_gen/write_result.rb

@@ -4,24 +4,16 @@ module Rigor
   module SigGen
     # Per-source-file outcome of a `rigor sig-gen --write` run.
     #
-    # The writer reports back what it did so the renderer (and
-    # the CLI's exit-status logic) can summarise actions and
-    # surface user-authored-skip decisions without having to
-    # re-parse the produced files.
+    # The writer reports back what it did so the renderer (and the CLI's exit-status logic) can summarise
+    # actions and surface user-authored-skip decisions without having to re-parse the produced files.
     #
     # - `source_path` — original `.rb` file.
-    # - `target_path` — `.rbs` file the writer was responsible
-    #   for (`nil` when the source path falls outside the
-    #   project signature tree, in which case `action` is
-    #   `:skipped_outside_sig_root`).
-    # - `action` — one of `:created` / `:updated` / `:noop` /
-    #   `:skipped_outside_sig_root`.
-    # - `applied` — the {MethodCandidate}s that actually
-    #   landed on disk.
-    # - `skipped` — the {MethodCandidate}s the writer
-    #   declined (e.g. tighter-return without `--overwrite`).
-    #   Each entry pairs the candidate with a skip reason
-    #   keyword (`:user_authored`).
+    # - `target_path` — `.rbs` file the writer was responsible for (`nil` when the source path falls outside
+    #   the project signature tree, in which case `action` is `:skipped_outside_sig_root`).
+    # - `action` — one of `:created` / `:updated` / `:noop` / `:skipped_outside_sig_root`.
+    # - `applied` — the {MethodCandidate}s that actually landed on disk.
+    # - `skipped` — the {MethodCandidate}s the writer declined (e.g. tighter-return without `--overwrite`). Each
+    #   entry pairs the candidate with a skip reason keyword (`:user_authored`).
     class WriteResult
       attr_reader :source_path, :target_path, :action, :applied, :skipped