rigortype 0.3.2 → 0.3.4

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

@@ -58,7 +58,8 @@ module Rigor
     class Factorybot < Rigor::Plugin::Base
       manifest(
         id: "factorybot",
-        version: "0.2.0",
+        # Bumped 2026-08-16 — publishes `:reachability_references` for `rigor unused` (ADR-102 WD3 / #350).
+        version: "0.3.0",
         description: "Validates FactoryBot.create / build / attributes_for call shapes; " \
                      "publishes per-factory attribute set + inferred model class as the " \
                      ":factory_index ADR-9 fact (Pillar 2 Slice 3).",
@@ -67,7 +68,8 @@ module Rigor
         },
         consumes: [
           { plugin_id: "activerecord", name: :model_index, optional: true }
-        ]
+        ],
+        produces: [:reachability_references]
       )
 
       producer :factory_index, watch: -> { [[@factory_search_paths, "**/*.rb"]] } do |_params|
@@ -81,6 +83,32 @@ 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`.
+      #
+      # 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.
+      def prepare(services)
+        index = producer_value(:factory_index)
+        return if index.nil? || index.empty?
+
+        references = index.entries.values.filter_map do |entry|
+          { name: entry.model_class, role: :test } if entry.model_class
+        end.uniq
+        return if references.empty?
+
+        services.fact_store.publish(plugin_id: manifest.id, name: :reachability_references, value: references)
+      end
+
       # 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

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

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "rigor/source/node_children"
+
+require "prism"
+
+module Rigor
+  module Plugin
+    class Pundit < Rigor::Plugin::Base
+      # ADR-102 WD3 / #350 — which policy classes does this project's code actually *reach*?
+      #
+      # A Pundit policy is the textbook case for a plugin-supplied reachability root: `authorize @post` runs
+      # `PostPolicy#update?`, and the string `PostPolicy` appears nowhere in the application. A reference
+      # index therefore sees a live policy exactly as it sees a dead one, and `rigor unused` reports every
+      # policy in the project as a candidate.
+      #
+      # **What this deliberately does NOT do is publish every class under `policy_search_paths`.** "A file
+      # exists under `app/policies`" is not evidence that anything authorizes against it — it is the same
+      # non-argument as "a file exists under `app/workers`". Rooting the whole directory would answer the
+      # question by refusing to ask it, and an over-claiming root source silently hides real dead code
+      # (ADR-102 § Consequences). So this walks the call sites instead and derives the policy each one names.
+      #
+      # Two derivations, both grounded in Pundit's own `PolicyFinder`, which builds the policy name from the
+      # record's class:
+      #
+      # - a constant argument — `authorize Post`, `policy_scope(Post.all)` — names `PostPolicy` exactly;
+      # - a receiverless name — `authorize @post` / `authorize post` — is camelized, because the Rails
+      #   convention that names the carrier after the record is the same convention Pundit's lookup assumes.
+      #
+      # The camelization is a plain underscore split rather than `Rigor::Plugin::Inflector` (ADR-39), and the
+      # reason it may be: the caller intersects every derived name with the policies {PolicyDiscoverer}
+      # actually found, so a name this scan gets wrong matches nothing and is DROPPED. Inflection error can
+      # only cost coverage here, never manufacture a root — which is the opposite of the direction ADR-39's
+      # no-approximation rule is defending, where a wrong inflection becomes a wrong diagnostic.
+      class AuthorizationScan
+        # Pundit's entry points. `authorize` resolves and calls a predicate; `policy` and `policy_scope`
+        # resolve without calling one. All three reach the policy class, which is what a root records.
+        ENTRY_METHODS = %i[authorize policy policy_scope].freeze
+
+        def initialize(io_boundary:, search_paths:)
+          @io_boundary = io_boundary
+          @search_paths = search_paths
+        end
+
+        # @return [Array<String>] policy class names named by an authorization call, sorted and unique. Not
+        #   yet intersected with the discovered policies — the caller does that.
+        def policy_names
+          names = Set.new
+          ruby_files_under(@search_paths).each do |path|
+            contents = read_safely(path)
+            next if contents.nil?
+
+            parsed = Prism.parse(contents)
+            next unless parsed.success?
+
+            walk(parsed.value, names)
+          end
+          names.to_a.sort
+        end
+
+        private
+
+        def read_safely(path)
+          @io_boundary.read_file(path)
+        rescue Plugin::AccessDeniedError, Errno::ENOENT
+          nil
+        end
+
+        def ruby_files_under(roots)
+          roots.flat_map do |root|
+            absolute = File.expand_path(root)
+            next [] unless File.directory?(absolute)
+
+            Dir.glob(File.join(absolute, "**", "*.rb"))
+          end
+        end
+
+        def walk(node, names)
+          return unless node.is_a?(Prism::Node)
+
+          record_call(node, names) if node.is_a?(Prism::CallNode)
+          node.rigor_each_child { |child| walk(child, names) }
+        end
+
+        def record_call(node, names)
+          return unless ENTRY_METHODS.include?(node.name) && node.receiver.nil?
+
+          record = node.arguments&.arguments&.first
+          return if record.nil?
+
+          name = policy_name_for(record)
+          names << name if name
+        end
+
+        # @return [String, nil] the policy class the argument names, or nil when the argument is an
+        #   expression this reading cannot attribute to a record (a method call with arguments, a literal, an
+        #   index read). Silence, not a guess: an unattributable call contributes nothing.
+        def policy_name_for(node)
+          record = record_name_for(node)
+          record && "#{record}Policy"
+        end
+
+        def record_name_for(node)
+          case node
+          when Prism::ConstantReadNode, Prism::ConstantPathNode then constant_name(node)
+          when Prism::InstanceVariableReadNode then camelize(node.name.to_s.delete_prefix("@"))
+          when Prism::LocalVariableReadNode then camelize(node.name.to_s)
+          when Prism::CallNode then call_record_name(node)
+          end
+        end
+
+        # `policy_scope(Post.all)` scopes `PostPolicy::Scope`, so the receiver constant is the record. A
+        # receiverless bare name (`authorize post`) is the local-variable case Prism parses as a call when no
+        # assignment made it a local — the memoised `def post` helper every Rails controller has.
+        def call_record_name(node)
+          return constant_name(node.receiver) if node.receiver.is_a?(Prism::ConstantReadNode) ||
+                                                 node.receiver.is_a?(Prism::ConstantPathNode)
+          return nil unless node.receiver.nil? && node.arguments.nil? && node.block.nil?
+
+          camelize(node.name.to_s)
+        end
+
+        def camelize(token)
+          return nil if token.empty? || !/\A[a-z_][a-z0-9_]*\z/.match?(token)
+
+          token.split("_").reject(&:empty?).map { |part| part[0].upcase + part[1..].to_s }.join
+        end
+
+        def constant_name(node)
+          case node
+          when Prism::ConstantReadNode then node.name.to_s
+          when Prism::ConstantPathNode then constant_path_name(node)
+          end
+        end
+
+        def constant_path_name(node)
+          parts = []
+          current = node
+          while current.is_a?(Prism::ConstantPathNode)
+            parts.unshift(current.name.to_s)
+            current = current.parent
+          end
+          case current
+          when nil then parts.join("::")
+          when Prism::ConstantReadNode then "#{current.name}::#{parts.join('::')}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -4,6 +4,7 @@ require "rigor/plugin"
 
 require_relative "pundit/policy_index"
 require_relative "pundit/policy_discoverer"
+require_relative "pundit/authorization_scan"
 require_relative "pundit/analyzer"
 
 module Rigor
@@ -22,6 +23,7 @@ module Rigor
     #         config:
     #           policy_search_paths: ["app/policies"]    # default; optional
     #           policy_base_classes: ["ApplicationPolicy"]  # default; optional
+    #           authorization_call_paths: ["app/controllers"]  # default; optional
     #
     # ## What it checks
     #
@@ -44,12 +46,22 @@ module Rigor
     class Pundit < Rigor::Plugin::Base
       manifest(
         id: "pundit",
-        version: "0.1.0",
+        # Bumped 2026-08-16 — publishes `:reachability_roots` for `rigor unused` (ADR-102 WD3): the policy
+        # classes the project's own `authorize` / `policy` / `policy_scope` calls name by convention.
+        version: "0.2.0",
         description: "Validates Pundit policy / authorize calls.",
         config_schema: {
           "policy_search_paths" => { kind: :array, default: ["app/policies"] },
-          "policy_base_classes" => { kind: :array, default: %w[ApplicationPolicy] }
-        }
+          "policy_base_classes" => { kind: :array, default: %w[ApplicationPolicy] },
+          # `authorization_call_paths` — where {AuthorizationScan} looks for the `authorize` / `policy` /
+          # `policy_scope` calls that ground the reachability roots. Deliberately narrower than the whole
+          # `app/` tree: controllers are where Pundit's entry points overwhelmingly live, the walk is a Prism
+          # parse per file on every run, and a project that also authorizes from `app/graphql` or
+          # `app/services` widens the list itself. Under-supply is the safe direction here — a policy this
+          # never sees stays in the report as a candidate, which is a visible row rather than a silent one.
+          "authorization_call_paths" => { kind: :array, default: ["app/controllers"] }
+        },
+        produces: [:reachability_roots]
       )
 
       producer :policy_index, watch: -> { [[@policy_search_paths, "**/*.rb"]] } do |_params|
@@ -60,9 +72,40 @@ module Rigor
         ).discover
       end
 
+      # Cached separately from `:policy_index` because the two invalidate on different trees: adding a
+      # controller changes which policies are reached without touching `app/policies` at all.
+      producer :authorized_policies, watch: -> { [[@authorization_call_paths, "**/*.rb"]] } do |_params|
+        AuthorizationScan.new(
+          io_boundary: io_boundary,
+          search_paths: @authorization_call_paths
+        ).policy_names
+      end
+
       def init(_services)
         @policy_search_paths = Array(config.fetch("policy_search_paths")).map(&:to_s)
         @policy_base_classes = Array(config.fetch("policy_base_classes")).map(&:to_s)
+        @authorization_call_paths = Array(config.fetch("authorization_call_paths")).map(&:to_s)
+      end
+
+      # ADR-102 WD3 — publishes the policies the project actually authorizes against, for `rigor unused`.
+      #
+      # The intersection is the whole design. {AuthorizationScan} says which policy names the code NAMES;
+      # {PolicyDiscoverer} says which policy classes EXIST. A root is published only where both agree, so
+      # neither an unrecognised call shape nor a mis-camelized record name can root a policy nothing reaches
+      # — the failure mode is a missing root, which shows up in the report as a candidate a human can judge,
+      # rather than a spurious root, which shows up as nothing at all.
+      #
+      # Publishing every class under `policy_search_paths` would have been one line and is exactly what this
+      # refuses to do: it would report a genuinely orphaned policy as reachable forever.
+      def prepare(services)
+        index = producer_value(:policy_index)
+        named = producer_value(:authorized_policies)
+        return if index.nil? || named.nil?
+
+        roots = named.select { |name| index.known?(name) }
+        return if roots.empty?
+
+        services.fact_store.publish(plugin_id: manifest.id, name: :reachability_roots, value: roots)
       end
 
       # File-level only: the load-error emission. The per-call policy validation runs over the engine-owned

data/plugins/rigor-rails/lib/rigor-rails.rb

@@ -14,6 +14,7 @@
 # whose `target_gems:` are actually in the project's `Gemfile.lock`. If that is rejected, ADR-60 WD1's
 # never-wired-surface criterion applies and this directory goes.
 
+require "rigor-railties"
 require "rigor-rails-routes"
 require "rigor-rails-i18n"
 require "rigor-actionmailer"

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+module Rigor
+  module Plugin
+    class RailsI18n < Rigor::Plugin::Base
+      # rigor-rails-i18n's effect contract (ADR-103 WD10; design note § 11.2; issue #387).
+      #
+      # `I18n.t` is not pure, and the reason is worth stating because it looks pure: it reads
+      # `I18n.locale`, which is per-fiber mutable process state, and on first use it loads the backend's
+      # translations. So a translation lookup is `global.read` — which is exactly the kind of label a
+      # project puts in `tolerated:` and then stops thinking about, and exactly why the *meaning* label
+      # matters more than the transport here. `rails.i18n.translate` is what a presenter envelope names
+      # when it wants to permit translation and nothing else.
+      #
+      # `I18n.locale=` is a `global.write`, and that one is worth surfacing: a presenter that changes the
+      # locale changes it for everything downstream in the request.
+      module Effects
+        I18N = "I18n"
+        READ = ["global.read", "rails.i18n.translate"].freeze
+        WRITE = ["global.write"].freeze
+
+        LOOKUPS = %w[t t! translate translate! l localize].freeze
+        WRITERS = %w[locale= default_locale= backend= load_path= with_locale].freeze
+
+        module_function
+
+        def attributions
+          LOOKUPS.map do |selector|
+            EffectAttribution.new(
+              receiver: I18N, method: selector, labels: READ, singleton: true, discharge: true,
+              why: "reads `I18n.locale` (per-fiber mutable process state) and lazily loads the backend's " \
+                   "translations; `rails.i18n.translate` is the meaning a presenter envelope permits"
+            )
+          end +
+            WRITERS.map do |selector|
+              EffectAttribution.new(
+                receiver: I18N, method: selector, labels: WRITE, singleton: true, discharge: true,
+                why: "changes process- or fiber-wide translation state, which every later lookup reads"
+              )
+            end
+        end
+      end
+    end
+  end
+end

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

@@ -5,6 +5,7 @@ require "rigor/plugin"
 require_relative "rails_i18n/locale_index"
 require_relative "rails_i18n/locale_loader"
 require_relative "rails_i18n/analyzer"
+require_relative "rails_i18n/effects"
 
 module Rigor
   module Plugin
@@ -64,7 +65,12 @@ module Rigor
           "locale_search_paths" => { kind: :array, default: ["config/locales"] },
           "configured_locales" => { kind: :array, default: ["en"] },
           "view_search_paths" => { kind: :array, default: ["app/views"] }
-        }
+        },
+        # ADR-103 WD10 (#387) — see {Effects}. `rails.i18n.translate` is registered here because this is
+        # the plugin that models I18n, even though the label reads like a whole-framework one.
+        effect_root: "rails",
+        effect_labels: ["rails.i18n.translate"],
+        effect_attributions: Effects.attributions
       )
 
       # `watch:` covers every `.yml` / `.yaml` file under the locale search paths so the cache invalidates

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require "rigor/source/literals"
+require "rigor/source/node_children"
+
+module Rigor
+  module Plugin
+    class RailsRoutes < Rigor::Plugin::Base
+      # The project's own inflector acronyms (`inflect.acronym 'ActivityPub'`), read STATICALLY out of
+      # `config/initializers/inflections.rb` — never executed, in keeping with ADR-39's note that
+      # project-specific inflection rules are ingested by parsing that file rather than by running it.
+      #
+      # Why the controller-name composition needs them: `scope module: :activitypub` names
+      # `ActivityPub::CollectionsController` in a project that registers the acronym, and
+      # `Activitypub::CollectionsController` in one that does not. Rigor loads its own
+      # `ActiveSupport::Inflector`, not the analysed application's, so the acronym table is empty there and
+      # the plain camelization is the wrong name. On Mastodon that is 19 of 280 emitted roots — inert (they
+      # match no declaration), but 19 live controllers left unrooted and therefore reported as dead.
+      #
+      # The correction is a RENAME, never an addition: applying it cannot grow the root set, so it cannot
+      # move the report in the over-supply direction ADR-102 § Consequences warns about.
+      module Acronyms
+        module_function
+
+        # @param contents [String, nil] the source of `config/initializers/inflections.rb`.
+        # @return [Array<String>] declared acronyms in declaration order. Empty for a missing / unparseable
+        #   file, or one that declares none — which leaves composition exactly as it was.
+        def discover(contents)
+          return [] if contents.nil? || contents.empty?
+
+          result = Prism.parse(contents)
+          return [] unless result.success?
+
+          found = []
+          walk(result.value) do |node|
+            next unless node.is_a?(Prism::CallNode) && node.name == :acronym
+
+            value = Rigor::Source::Literals.symbol_or_string_name(node.arguments&.arguments&.first)
+            found << value if value && !value.empty?
+          end
+          found.uniq
+        end
+
+        # Rewrites the camel-case words of an already-camelized name into their acronym spelling.
+        #
+        # Operating on the camelized RESULT rather than re-implementing camelization keeps
+        # `ActiveSupport::Inflector` the authority (ADR-39 forbids a local approximation): the only thing
+        # done here is substituting one spelling of a word for another. A word matches when the plain
+        # camelization of the acronym appears at a camel-word boundary — `Oauth` in `OauthMetadata` and in
+        # `WellKnown::Oauth`, but never the `Oauth` inside a hypothetical `Xoauth`.
+        #
+        # @param name [String] e.g. `"Activitypub::CollectionsController"`.
+        # @param acronyms [Enumerable<String>] as returned by {.discover}.
+        # @return [String] e.g. `"ActivityPub::CollectionsController"`.
+        def apply(name, acronyms)
+          acronyms.reduce(name) do |current, acronym|
+            plain = Rigor::Plugin::Inflector.camelize(acronym.to_s.downcase)
+            next current if plain == acronym.to_s
+
+            current.gsub(boundary_pattern(plain), acronym.to_s)
+          end
+        end
+
+        # A camel word starts at the beginning, after a `::` separator, or after the lowercase / digit tail
+        # of the preceding word; it ends at the end, before a `::`, or before the next word's capital.
+        def boundary_pattern(plain)
+          /(?<=\A|::|[a-z0-9])#{Regexp.escape(plain)}(?=::|[A-Z]|\z)/
+        end
+
+        def walk(node, &)
+          return unless node.is_a?(Prism::Node)
+
+          yield node
+          node.rigor_each_child { |child| walk(child, &) }
+        end
+      end
+    end
+  end
+end

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

@@ -40,7 +40,11 @@ module Rigor
         #   (`"api_v4"`), composed by {GrapeApiDiscoverer} from the project's own `prefix` / `version`
         #   declarations. The names beyond the prefix come from grape's runtime route table and cannot be
         #   enumerated statically, so the namespace is open — same contract as the OmniAuth family above.
-        def initialize(entries, custom_helpers: [], devise_resources: [], grape_prefixes: [])
+        # @param controllers [Enumerable<String>] fully-qualified controller class names the routes file
+        #   dispatches to (`"Admin::UsersController"`). Published as the plugin's `:reachability_roots` fact
+        #   (ADR-102 WD3) — a controller is an entry point nothing in the project references, so without this
+        #   every routed controller reads as unused. Deliberately NOT consulted by any helper-name check.
+        def initialize(entries, custom_helpers: [], devise_resources: [], grape_prefixes: [], controllers: [])
           @entries = entries.freeze
           # Multimap: a single helper name can map to multiple entries when an uncountable-noun resource
           # registers both an arity-0 index helper and an arity-1 show helper under the same `news_path`
@@ -50,9 +54,17 @@ module Rigor
           @custom_helpers = custom_helpers.to_set.freeze
           @devise_resources = devise_resources.to_set(&:to_s).freeze
           @grape_prefixes = grape_prefixes.to_set(&:to_s).freeze
+          @controllers = controllers.map(&:to_s).uniq.sort.freeze
           freeze
         end
 
+        # @return [Array<String>] the routed controller class names (see the `controllers:` parameter). Reads
+        #   through a nil guard rather than `attr_reader` so a table deserialised from a cache slot written
+        #   before this field existed answers `[]` instead of `nil`.
+        def controllers
+          @controllers || []
+        end
+
         # @return [Entry, nil] First matching entry; for the uncountable-noun case this is the index helper
         #   (the show helper is also registered but starts second).
         def find(helper_name)