rigortype 0.1.9 → 0.1.11

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

@@ -0,0 +1,490 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "helper_table"
+
+module Rigor
+  module Plugin
+    class RailsRoutes < Rigor::Plugin::Base
+      # Statically interprets `config/routes.rb`'s DSL via
+      # Prism — never executes the file. The interpreter is
+      # deliberately narrow; it covers the subset documented
+      # in the plugin's README and degrades silently on
+      # constructs it doesn't recognise.
+      #
+      # Recognised DSL surface (per the Rails-plugins
+      # roadmap):
+      #
+      # - `Rails.application.routes.draw do ... end` (entry
+      #   block; the body is interpreted)
+      # - `resources :name [, only: [...] | except: [...]]`
+      # - `resource :name`
+      # - `get/post/patch/put/delete "path", to:, as:`
+      # - `root to: "..."` / `root "..."`
+      # - One level of `namespace :foo do ... end`
+      # - One level of nested `resources` (`resources :users
+      #   do; resources :posts; end`)
+      # - `member do ... end` / `collection do ... end`
+      #   inside `resources`
+      #
+      # Out of scope for v0.1.0 (silent skips):
+      #
+      # - `scope :path:` / `scope :module:` / `scope :as:`
+      # - Constraints (`constraints: { id: /\d+/ }`)
+      # - `mount` / engine routes
+      # - `direct(:name) { |obj| ... }`
+      # - Format restrictions
+      module RoutesParser
+        # Standard resource actions Rails generates by default.
+        DEFAULT_RESOURCE_ACTIONS = %i[index show new create edit update destroy].freeze
+        # Default actions for `resource` (singular) — no index,
+        # no `:id` segment.
+        DEFAULT_SINGULAR_ACTIONS = %i[show new create edit update destroy].freeze
+
+        # Helper-name conventions per action. `:show` and
+        # `:update` / `:destroy` share the singular-form
+        # helper (Rails dedupes).
+        ACTION_HTTP_METHODS = {
+          index: :get,
+          show: :get,
+          new: :get,
+          create: :post,
+          edit: :get,
+          update: :patch, # also :put
+          destroy: :delete
+        }.freeze
+
+        module_function
+
+        # @param contents [String] raw `config/routes.rb` source
+        # @return [HelperTable]
+        def parse(contents)
+          parse_result = Prism.parse(contents)
+          return HelperTable.new([]) unless parse_result.errors.empty?
+
+          context = Context.new
+          interpret(parse_result.value, context)
+
+          # Each helper has both `_path` and `_url` forms.
+          paired = context.entries.flat_map do |entry|
+            [
+              entry,
+              HelperTable::Entry.new(
+                name: entry.name.sub(/_path\z/, "_url"),
+                arity: entry.arity,
+                path: entry.path,
+                http_method: entry.http_method,
+                action: entry.action
+              )
+            ]
+          end
+          HelperTable.new(paired)
+        end
+
+        # Per-parse mutable accumulator. Tracks the current
+        # nesting prefix (namespaces + parent resource) and the
+        # entries collected so far.
+        class Context
+          attr_reader :entries
+
+          def initialize
+            @entries = []
+            # Stack of prefix segments. Each entry is one of:
+            # - `{ kind: :namespace, name: "admin" }`
+            # - `{ kind: :scope, parent: "user", arity_segments: [":user_id"] }`
+            @stack = []
+          end
+
+          def push_namespace(name)
+            @stack.push(kind: :namespace, name: name.to_s)
+            yield
+          ensure
+            @stack.pop
+          end
+
+          def push_resource(parent_name)
+            singular = singularize(parent_name.to_s)
+            @stack.push(kind: :scope, parent: singular, arity_segments: [":#{singular}_id"])
+            yield
+          ensure
+            @stack.pop
+          end
+
+          # Helper-name prefix from namespaces (`admin_`,
+          # `admin_users_`, …).
+          def helper_prefix
+            segments = @stack.filter_map { |frame| frame_helper_segment(frame) }
+            segments.map { |segment| "#{segment}_" }.join
+          end
+
+          # Path prefix — including the parent's `:user_id`
+          # segments for nested resources and the namespace
+          # path prefix.
+          def path_prefix
+            parts = @stack.flat_map { |frame| frame_path_segments(frame) }
+            parts.join
+          end
+
+          # Number of dynamic segments (`:user_id`-style)
+          # captured by the parent scope chain. Used to
+          # compute helper arity for nested resources.
+          def parent_segment_count
+            @stack.count { |frame| frame[:kind] == :scope }
+          end
+
+          private
+
+          def frame_helper_segment(frame)
+            case frame[:kind]
+            when :namespace then frame[:name]
+            when :scope then frame[:parent]
+            end
+          end
+
+          def frame_path_segments(frame)
+            case frame[:kind]
+            when :namespace then ["/#{frame[:name]}"]
+            when :scope then ["/#{pluralize(frame[:parent])}/:#{frame[:parent]}_id"]
+            else []
+            end
+          end
+
+          # Tiny English inflector. Sufficient for the standard
+          # `posts` ↔ `post`, `users` ↔ `user` rename Rails
+          # generates by default; users with custom
+          # inflections need to author RBS by hand for the
+          # affected helpers (out of scope for v0.1.0).
+          #
+          # The canonical English uncountable noun set from
+          # ActiveSupport::Inflector::Inflections (Rails 8.x).
+          # `singularize("news")` returns `"news"` rather than
+          # `"new"`. Pre-fix the parser stripped the trailing
+          # 's' from `news`, so `resources :news` registered
+          # `new_path` / `news_path` / `new_news_path` (broken
+          # — Rails actually generates `news_path` for both
+          # index and show, with the show form taking `:id`).
+          # Redmine hit this 81× across `news_path(id)` calls.
+          UNCOUNTABLE = %w[
+            equipment information rice money species series fish
+            sheep jeans police news media settings
+          ].to_set.freeze
+          private_constant :UNCOUNTABLE
+
+          def singularize(word)
+            return word if UNCOUNTABLE.include?(word)
+            return "#{word.chomp('ies')}y" if word.end_with?("ies") && word.length > 3
+            return word.chomp("es") if word.end_with?("ses") || word.end_with?("xes")
+            return word.chomp("s") if word.end_with?("s")
+
+            word
+          end
+
+          def pluralize(word)
+            return word if UNCOUNTABLE.include?(word)
+            return word if word.end_with?("s")
+            return "#{word.chomp('y')}ies" if word.end_with?("y") && word.length > 1
+
+            "#{word}s"
+          end
+        end
+
+        def interpret(node, context)
+          return unless node.is_a?(Prism::Node)
+
+          case node
+          when Prism::CallNode
+            interpret_call(node, context)
+          else
+            node.compact_child_nodes.each { |child| interpret(child, context) }
+          end
+        end
+
+        def interpret_call(node, context)
+          case node.name
+          when :draw
+            # `Rails.application.routes.draw do ... end` —
+            # interpret the block body.
+            interpret_block_body(node, context)
+          when :namespace
+            handle_namespace(node, context)
+          when :resources
+            handle_resources(node, context)
+          when :resource
+            handle_resource(node, context)
+          when :root
+            handle_root(node, context)
+          when :get, :post, :patch, :put, :delete
+            handle_explicit_route(node, context)
+          when :member, :collection
+            # Inside a `resources` block, `member do ... end`
+            # / `collection do ... end` introduces extra
+            # routes. Interpreted only when we have a parent
+            # scope (otherwise the call is meaningless).
+            handle_member_or_collection(node, context)
+          else
+            interpret_block_body(node, context)
+          end
+        end
+
+        def interpret_block_body(node, context)
+          body = node.block&.body
+          return if body.nil?
+
+          body.compact_child_nodes.each { |child| interpret(child, context) }
+        end
+
+        def handle_namespace(node, context)
+          name = symbol_argument(node, 0)
+          return interpret_block_body(node, context) if name.nil?
+
+          context.push_namespace(name) { interpret_block_body(node, context) }
+        end
+
+        def handle_resources(node, context)
+          name = symbol_argument(node, 0)
+          return interpret_block_body(node, context) if name.nil?
+
+          actions = restrict_actions(node, DEFAULT_RESOURCE_ACTIONS)
+          base_arity = context.parent_segment_count
+
+          register_resourceful_helpers(name, actions, base_arity, context, plural: true)
+
+          context.push_resource(name) do
+            interpret_block_body(node, context)
+          end
+        end
+
+        def handle_resource(node, context)
+          name = symbol_argument(node, 0)
+          return interpret_block_body(node, context) if name.nil?
+
+          actions = restrict_actions(node, DEFAULT_SINGULAR_ACTIONS)
+          base_arity = context.parent_segment_count
+
+          # Singular resource — no `:id` segment, no `:index`
+          # / pluralised helper. The "show" helper is
+          # `<name>_path` (singular).
+          register_resourceful_helpers(name, actions, base_arity, context, plural: false)
+
+          # Nested `resources :things` inside `resource :profile`
+          # is rare; we still descend so the inner declarations
+          # collect their own helpers.
+          interpret_block_body(node, context)
+        end
+
+        def handle_root(node, context)
+          # `root to: "..."` / `root "..."` — single helper
+          # `root_path`, arity 0, GET. Real-world Rails apps also
+          # use `root :to => 'welcome#index', :as => 'home'` (the
+          # canonical Redmine idiom across 230+ call sites), which
+          # registers an additional `home_path` / `home_url` alias
+          # for the same path. Mastodon and Solidus also use the
+          # `as:` form occasionally for analytics-friendly URL
+          # naming.
+          path = context.path_prefix.empty? ? "/" : context.path_prefix
+          context.entries << HelperTable::Entry.new(
+            name: "#{context.helper_prefix}root_path",
+            arity: 0, path: path, http_method: :get, action: :root
+          )
+
+          alias_name = keyword_symbol(node, :as)
+          return if alias_name.nil?
+
+          context.entries << HelperTable::Entry.new(
+            name: "#{context.helper_prefix}#{alias_name}_path",
+            arity: 0, path: path, http_method: :get, action: :root
+          )
+        end
+
+        def handle_explicit_route(node, context)
+          # `get "/about", to: "static#about", as: :about`
+          path = string_argument(node, 0)
+          as_name = keyword_symbol(node, :as)
+          return if as_name.nil? && path.nil?
+
+          # When `as:` is omitted, Rails generates a helper
+          # name from the path. For our static analysis
+          # we only register helpers when we can name them
+          # confidently — i.e. when `as:` is present.
+          return if as_name.nil?
+
+          name = "#{context.helper_prefix}#{as_name}_path"
+          arity = context.parent_segment_count + count_path_placeholders(path)
+          context.entries << HelperTable::Entry.new(
+            name: name, arity: arity,
+            path: "#{context.path_prefix}#{path || ''}",
+            http_method: node.name, action: :custom
+          )
+        end
+
+        def handle_member_or_collection(node, context)
+          # Only meaningful when we're inside a `resources` /
+          # `resource` block. The Context's stack tells us.
+          return unless context.parent_segment_count.positive? || in_singular_resource?(context)
+
+          # The Context doesn't currently distinguish
+          # "inside resources" from "inside resource" — for
+          # v0.1.0 we treat both the same way and let the
+          # explicit `as:` in member/collection do the
+          # naming work.
+          interpret_block_body(node, context)
+        end
+
+        def in_singular_resource?(*)
+          # Slice 1 doesn't model the singular-resource frame
+          # separately; placeholder so member / collection
+          # blocks at least descend.
+          true
+        end
+
+        # Generate the standard helpers for a resource(s).
+        # `plural: true` for `resources :users`, `false` for
+        # `resource :profile`.
+        def register_resourceful_helpers(name, actions, base_arity, context, plural:)
+          singular = singularize_word(name.to_s)
+          plural_form = plural ? name.to_s : singular # `resource :foo` uses singular path
+          path_base = "#{context.path_prefix}/#{plural_form}"
+
+          actions.each do |action|
+            entry = entry_for_action(
+              action,
+              name: name, singular: singular, base_arity: base_arity,
+              path_base: path_base, helper_prefix: context.helper_prefix, plural: plural
+            )
+            context.entries << entry if entry
+          end
+        end
+
+        # `:create` / `:update` / `:destroy` don't generate
+        # `*_path` helpers separate from the show / index
+        # helper Rails reuses for their forms; the case
+        # statement returns nil for those and the caller
+        # skips them.
+        def entry_for_action(action, name:, singular:, base_arity:, path_base:, helper_prefix:, plural:)
+          case action
+          when :index then index_entry(plural, helper_prefix, name, base_arity, path_base)
+          when :show then show_entry(plural, helper_prefix, singular, base_arity, path_base)
+          when :new
+            HelperTable::Entry.new(
+              name: "#{helper_prefix}new_#{singular}_path",
+              arity: base_arity, path: "#{path_base}/new",
+              http_method: :get, action: :new
+            )
+          when :edit then edit_entry(plural, helper_prefix, singular, base_arity, path_base)
+          end
+        end
+
+        def index_entry(plural, helper_prefix, name, base_arity, path_base)
+          return nil unless plural
+
+          HelperTable::Entry.new(
+            name: "#{helper_prefix}#{name}_path",
+            arity: base_arity, path: path_base,
+            http_method: :get, action: :index
+          )
+        end
+
+        def show_entry(plural, helper_prefix, singular, base_arity, path_base)
+          show_path = plural ? "#{path_base}/:id" : path_base
+          show_arity = plural ? base_arity + 1 : base_arity
+          HelperTable::Entry.new(
+            name: "#{helper_prefix}#{singular}_path",
+            arity: show_arity, path: show_path,
+            http_method: :get, action: :show
+          )
+        end
+
+        def edit_entry(plural, helper_prefix, singular, base_arity, path_base)
+          edit_path = plural ? "#{path_base}/:id/edit" : "#{path_base}/edit"
+          edit_arity = plural ? base_arity + 1 : base_arity
+          HelperTable::Entry.new(
+            name: "#{helper_prefix}edit_#{singular}_path",
+            arity: edit_arity, path: edit_path,
+            http_method: :get, action: :edit
+          )
+        end
+
+        def restrict_actions(node, default)
+          options = options_hash(node)
+          # `resources :foo, only: :show` is the same as
+          # `only: [:show]` in Rails; `options_hash` preserves the
+          # Symbol shape from the source, so coerce here.
+          if (only = options[:only])
+            Array(only) & default
+          elsif (except = options[:except])
+            default - Array(except)
+          else
+            default
+          end
+        end
+
+        def options_hash(node)
+          args = node.arguments&.arguments || []
+          last = args.last
+          return {} unless last.is_a?(Prism::KeywordHashNode)
+
+          last.elements.each_with_object({}) do |element, into|
+            next unless element.is_a?(Prism::AssocNode)
+            next unless element.key.is_a?(Prism::SymbolNode)
+
+            value = symbol_array(element.value) || symbol_value(element.value) || string_value(element.value)
+            into[element.key.unescaped.to_sym] = value
+          end
+        end
+
+        def symbol_argument(node, index)
+          arg = (node.arguments&.arguments || [])[index]
+          symbol_value(arg)
+        end
+
+        def string_argument(node, index)
+          arg = (node.arguments&.arguments || [])[index]
+          string_value(arg)
+        end
+
+        def keyword_symbol(node, key)
+          options_hash(node)[key]
+        end
+
+        def symbol_value(node)
+          node.is_a?(Prism::SymbolNode) ? node.unescaped.to_sym : nil
+        end
+
+        def string_value(node)
+          node.is_a?(Prism::StringNode) ? node.unescaped : nil
+        end
+
+        def symbol_array(node)
+          return nil unless node.is_a?(Prism::ArrayNode)
+
+          values = node.elements.map { |e| symbol_value(e) }
+          values.all? ? values : nil
+        end
+
+        def count_path_placeholders(path)
+          return 0 if path.nil?
+
+          path.scan(/:[a-z_][a-z0-9_]*/).size
+        end
+
+        # Shared with `Context::Inflector#singularize` — kept in
+        # sync until one of the two call sites can adopt the
+        # other.
+        UNCOUNTABLE = %w[
+          equipment information rice money species series fish
+          sheep jeans police news media settings
+        ].to_set.freeze
+
+        def singularize_word(word)
+          return word if UNCOUNTABLE.include?(word)
+          return "#{word.chomp('ies')}y" if word.end_with?("ies") && word.length > 3
+          return word.chomp("es") if word.end_with?("ses") || word.end_with?("xes")
+          return word.chomp("s") if word.end_with?("s")
+
+          word
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+require_relative "rails_routes/helper_table"
+require_relative "rails_routes/routes_parser"
+require_relative "rails_routes/analyzer"
+
+module Rigor
+  module Plugin
+    # 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).
+    # Statically interprets the routes DSL via Prism — no
+    # `rails` runtime dependency. Recognised v0.1.0 surface:
+    #
+    # - `Rails.application.routes.draw do ... end`
+    # - `resources :name [, only: [...] | except: [...]]`
+    # - `resource :name`
+    # - `get/post/patch/put/delete "/path", to:, as:`
+    # - `root to: "..."` / `root "..."`
+    # - One level of `namespace :foo do ... end`
+    # - One level of nested `resources`
+    #
+    # The plugin publishes its parsed `:helper_table` through
+    # the ADR-9 cross-plugin fact store so future
+    # `rigor-actionpack` Phase 4 can consume it for
+    # route-helper validation in controller code.
+    #
+    # ## Configuration
+    #
+    #     plugins:
+    #       - gem: rigor-rails-routes
+    #         config:
+    #           routes_file: config/routes.rb   # default; optional
+    #
+    # ## Limitations (v0.1.0)
+    #
+    # - `scope :path:` / `scope :module:` / `scope :as:` are
+    #   not interpreted — helpers nested inside these
+    #   constructs are silently skipped.
+    # - Constraints / format restrictions / mountable
+    #   engines are out of scope.
+    # - The English inflector is intentionally tiny: it
+    #   handles `posts` ↔ `post`, `users` ↔ `user`,
+    #   `categories` ↔ `category`, `boxes` ↔ `box`. Custom
+    #   inflections (`fish` ↔ `fish`, `child` ↔ `children`)
+    #   are out of scope; users who need them ship a hand-
+    #   written RBS for the affected helper.
+    class RailsRoutes < Rigor::Plugin::Base
+      manifest(
+        id: "rails-routes",
+        version: "0.1.0",
+        description: "Validates Rails route-helper calls against `config/routes.rb`.",
+        config_schema: {
+          "routes_file" => :string
+        },
+        produces: [:helper_table]
+      )
+
+      DEFAULT_ROUTES_FILE = "config/routes.rb"
+
+      # Cached producer — reads `config/routes.rb` through
+      # the trusted `IoBoundary` and parses through
+      # {RoutesParser}. The descriptor's auto-collected
+      # `FileEntry` digest invalidates the cache on routes-
+      # file edits.
+      producer :helper_table do |_params|
+        contents = io_boundary.read_file(@routes_file)
+        RoutesParser.parse(contents)
+      end
+
+      def init(_services)
+        @routes_file = config.fetch("routes_file", DEFAULT_ROUTES_FILE)
+        @helper_table = nil
+        @load_error = nil
+      end
+
+      # Publishes the parsed table to the cross-plugin fact
+      # store so future Tier 2 plugins (rigor-actionpack
+      # Phase 4) can read it via `services.fact_store.read`.
+      def prepare(services)
+        table = helper_table_or_nil
+        return if table.nil?
+
+        services.fact_store.publish(
+          plugin_id: manifest.id,
+          name: :helper_table,
+          value: table.to_h
+        )
+      end
+
+      def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
+        table = helper_table_or_nil
+        if table.nil? && @load_error
+          return [] if @load_error_emitted
+
+          @load_error_emitted = true
+          return [load_error_diagnostic(path)]
+        end
+        return [] if table.nil? || table.empty?
+
+        Analyzer.diagnose(path: path, root: root, helper_table: table)
+                .map { |diag| build_diagnostic(diag) }
+      end
+
+      private
+
+      # The load-error path used to emit the same warning on
+      # every analyzed file in the project. On large monorepos
+      # (Mastodon: 1,302 files; Solidus: ~1,000 files) and on
+      # legacy projects without a top-level `config/routes.rb`,
+      # this multiplied a single root cause into 1,000+
+      # identical diagnostics. The error is project-global —
+      # report it once per run.
+
+      def helper_table_or_nil
+        return @helper_table if @helper_table
+
+        # Read first so the IoBoundary's FileEntry digest
+        # captures into the descriptor before `cache_for`
+        # snapshots it (the same pattern documented in
+        # rigor-routes / rigor-activerecord).
+        io_boundary.read_file(@routes_file)
+        @helper_table = cache_for(:helper_table, params: {}).call
+      rescue Plugin::AccessDeniedError => e
+        @load_error = "rigor-rails-routes: #{e.message}"
+        nil
+      rescue Errno::ENOENT
+        @load_error = "rigor-rails-routes: routes file `#{@routes_file}` not found; route checks skipped"
+        nil
+      rescue StandardError => e
+        @load_error = "rigor-rails-routes: failed to parse `#{@routes_file}`: #{e.class}: #{e.message}"
+        nil
+      end
+
+      def load_error_diagnostic(path)
+        Rigor::Analysis::Diagnostic.new(
+          path: path, line: 1, column: 1,
+          message: @load_error,
+          severity: :warning,
+          rule: "load-error"
+        )
+      end
+
+      def build_diagnostic(diag)
+        Rigor::Analysis::Diagnostic.new(
+          path: diag.path, line: diag.line, column: diag.column,
+          message: diag.message, severity: diag.severity, rule: diag.rule
+        )
+      end
+    end
+
+    Rigor::Plugin.register(RailsRoutes)
+  end
+end

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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "rigor/plugin/rails_routes"