rigortype 0.4.5 → 0.4.7

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).
     #
@@ -120,16 +120,17 @@ module Rigor
 
       # The `watch:` glob tuples covering the scan's entire input — one `[root, pattern]` per project `paths:`
       # entry. A directory entry watches its whole `**/*.rb` subtree; a single-file `.rb` entry watches
-      # exactly that file (`[dir, basename]`). Roots are expanded to absolute paths by
-      # `Plugin::Base#watch_glob_entries`, so a relative CLI path (`app/models`) re-validates against the same
-      # tree from the project root on the next run. Co-extensive with {#scannable_paths}: every `.rb` the scan
-      # would read is watched, so any edit / addition / removal under those paths invalidates the cache.
+      # exactly that file (`[dir, basename]`, with the basename escaped so `[`, `{`, `*` or `?` match literally).
+      # Roots are expanded to absolute paths by `Plugin::Base#watch_glob_entries`, so a relative CLI path
+      # (`app/models`) re-validates against the same tree from the project root on the next run. Co-extensive
+      # with {#scannable_paths}: every `.rb` the scan would read is watched, so any edit / addition / removal
+      # under those paths invalidates the cache.
       def alias_watch_globs
         services.configuration.paths.filter_map do |entry|
           if io_boundary.directory?(entry)
             [entry, "**/*.rb"]
           elsif io_boundary.file?(entry) && entry.end_with?(".rb")
-            [File.dirname(entry), File.basename(entry)]
+            [File.dirname(entry), Rigor::RootedGlob.literal(File.basename(entry))]
           end
         end
       end

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

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

@@ -16,7 +16,7 @@ module Rigor
       #
       # Scope:
       #
-      # - Recognises the standard six controllers (`:sessions`, `:passwords`, `:confirmations`, `:unlocks`,
+      # - Recognises the standard controllers (`:sessions`, `:passwords`, `:confirmations`, `:unlocks`,
       #   `:registrations`, `:omniauth_callbacks`).
       # - Honours `skip: [...]` to suppress controllers the project disables.
       # - Honours `path: "..."` to remap the URL path (does NOT remap the helper-name prefix — Devise uses
@@ -162,8 +162,7 @@ module Rigor
           OMNIAUTH_SUFFIXES
         end
 
-        # ADR-39 — delegates to the shared inflector (real `ActiveSupport::Inflector` when available),
-        # replacing the tiny AS-replica this module used to duplicate from `RoutesParser`.
+        # ADR-39 — delegates to the shared inflector (real `ActiveSupport::Inflector` when available).
         def singularize(word)
           Rigor::Plugin::Inflector.singularize(word)
         end

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

@@ -7,7 +7,7 @@ require "prism"
 module Rigor
   module Plugin
     class RailsRoutes < Rigor::Plugin::Base
-      # Walks `app/helpers/**/*.rb` (or any configured set of helper directories) and extracts every public
+      # Walks the configured `helper_paths:` directories (default `app/`) and extracts every public
       # module-level method name so the analyzer's `unknown-helper` rule does not false-fire on calls to
       # project-defined `*_path` / `*_url` helpers (the canonical Rails pattern: a `UrlHelper` module
       # exposing `full_asset_url`, `host_to_url`, `frontend_asset_url`, and so on).

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

@@ -409,14 +409,9 @@ module Rigor
             end
           end
 
-          # ADR-39: inflection delegates to the shared `Rigor::Plugin::Inflector`, which calls the real
-          # `ActiveSupport::Inflector` (the authority Rails itself uses to generate helper names) when
-          # available, falling back to a built-in approximation otherwise. This replaces the hand-tuned
-          # AS-replica these methods used to carry — every special case they accreted (`news` uncountable,
-          # `media`→`medium`, `databases`→`database`, `custom_css` ss-preservation,
-          # `async_refresh`→`async_refreshes`) was reverse-engineered `ActiveSupport::Inflector` behaviour,
-          # so the real inflector produces the same result for those and the correct one for the words the
-          # replica never covered.
+          # ADR-39: inflection delegates to the shared `Rigor::Plugin::Inflector`, which uses the real
+          # `ActiveSupport::Inflector` (the authority Rails uses to generate helper names) when available,
+          # and a built-in approximation otherwise.
           def singularize(word)
             Rigor::Plugin::Inflector.singularize(word)
           end
@@ -1286,7 +1281,7 @@ module Rigor
           return nil unless plural
 
           # Rails appends `_index_path` to the index helper name when the singular form of the resource
-          # matches the plural form AND the noun isn't in the canonical UNCOUNTABLE list. The collision
+          # matches the plural form (uncountable nouns included). The collision
           # would otherwise put both the index (`:id`-less) and show (`:id`-bearing) helpers under the same
           # name, and Rails disambiguates by suffixing the index form. Mastodon's `resources
           # :reblogged_by, controller: :reblogged_by_accounts, only: :index` and similar rely on this —
@@ -1432,8 +1427,6 @@ module Rigor
         end
 
         # ADR-39 — delegates to the shared inflector (real `ActiveSupport::Inflector` when available).
-        # Previously a hand-tuned AS-replica kept in sync with `Context#singularize`; both now share the
-        # one authoritative implementation.
         def singularize_word(word)
           Rigor::Plugin::Inflector.singularize(word)
         end

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

@@ -14,7 +14,7 @@ module Rigor
     # rigor-rails-routes — validates Rails route-helper calls (`users_path`, `edit_user_path(@user)`, …)
     # against the project's `config/routes.rb`.
     #
-    # Tier 1A of the [Rails plugins roadmap](../../../../docs/design/20260508-rails-plugins-roadmap.md).
+    # Tier 1A of the [Rails plugins roadmap](../../../../../docs/design/20260508-rails-plugins-roadmap.md).
     # Statically interprets the routes DSL via Prism — no `rails` runtime dependency. Recognised v0.1.0
     # surface:
     #

data/plugins/rigor-rbs-inline/lib/rigor/plugin/rbs_inline.rb

@@ -35,7 +35,8 @@ module Rigor
     class RbsInline < Rigor::Plugin::Base
       # Synthesizer callable invoked once per project Ruby source file by `Environment.for_project` at
       # env-build time. Returns the synthesised RBS source as a String, or `nil` when the file contributes
-      # nothing (no magic comment in the default mode, empty annotation set, parse error per WD6).
+      # nothing (no annotation in the default mode, no magic comment under `require_magic_comment: true`,
+      # or a parse error per WD6).
       class Synthesizer
         # An RDoc directive comment: `#:` followed by a bare word (RDoc allows a hyphen, as in `:call-seq:`)
         # and a closing colon. RDoc predates rbs-inline by about two decades and `#:<name>:` is