rigortype 0.1.10 → 0.1.12

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

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+require_relative "rails_routes/helper_table"
+require_relative "rails_routes/routes_parser"
+require_relative "rails_routes/helper_discoverer"
+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",
+        # Bumped 2026-05-28 — GitLab FOSS sweep adds: (a)
+        # `draw_all :name` support (action_dispatch-draw_all
+        # gem; single-file load semantics matching `draw :name`);
+        # (b) keyword-style `scope(path: ':project_id',
+        # as: :project)` — path read from the `:path` keyword,
+        # not only from the positional first arg; (c) detection
+        # of iterative `direct(name.sub(FROM, TO)) do ... end`
+        # alias-generation idiom — generates `<TO>_*` aliases
+        # for every registered `<FROM>_*` helper. GitLab uses
+        # this to shorten `namespace_project_*` → `project_*`.
+        version: "0.27.0",
+        description: "Validates Rails route-helper calls against `config/routes.rb`.",
+        config_schema: {
+          "routes_file" => :string,
+          "helper_paths" => :array
+        },
+        produces: [:helper_table]
+      )
+
+      DEFAULT_ROUTES_FILE = "config/routes.rb"
+
+      # The directories `HelperDiscoverer` walks for project-
+      # defined `*_path` / `*_url` methods. Default to the whole
+      # `app/` tree — the suffix filter inside the discoverer
+      # keeps the registered set tight, and real-world Rails
+      # apps routinely keep URL builders under `app/controllers`
+      # (private `def page_url`, `def callback_url` shapes),
+      # `app/lib` (Mastodon's `TranslationService::DeepL#base_url`),
+      # `app/services` (`SoftwareUpdateCheckService#api_url`),
+      # `app/serializers`, `app/presenters`, `app/decorators`,
+      # not only `app/helpers/`. Walking the whole tree is the
+      # honest answer to "does this `_path` / `_url` name exist
+      # anywhere in the project?"; the cost is a one-time Prism
+      # parse per file at startup, which is bounded.
+      DEFAULT_HELPER_PATHS = ["app"].freeze
+
+      # 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.
+      #
+      # Passes a `file_reader` lambda so the parser can follow
+      # `draw(:admin)` → `config/routes/admin.rb` partials.
+      producer :helper_table do |_params|
+        routes_dir = "#{File.dirname(@routes_file)}/routes"
+        file_reader = lambda do |name|
+          io_boundary.read_file("#{routes_dir}/#{name}")
+        rescue StandardError
+          nil
+        end
+        contents = io_boundary.read_file(@routes_file)
+        custom_helpers = discover_custom_helpers
+        RoutesParser.parse(contents, file_reader: file_reader, custom_helpers: custom_helpers)
+      end
+
+      def init(_services)
+        @routes_file = config.fetch("routes_file", DEFAULT_ROUTES_FILE)
+        @helper_paths = Array(config.fetch("helper_paths", DEFAULT_HELPER_PATHS)).map(&:to_s)
+        @helper_table = nil
+        @load_error = nil
+      end
+
+      # Walks every configured `helper_paths:` directory
+      # through the trusted `IoBoundary` and returns the set
+      # of project-defined `*_path` / `*_url` method names
+      # for {HelperDiscoverer}. Each file digest is captured
+      # by the boundary so editing a helper file invalidates
+      # the `:helper_table` cache automatically. Returns the
+      # empty set when nothing under `helper_paths:` exists —
+      # the routes table still works.
+      def discover_custom_helpers
+        contents_per_path = {}
+        each_helper_file do |path|
+          contents_per_path[path] = io_boundary.read_file(path)
+        rescue Plugin::AccessDeniedError, Errno::ENOENT
+          next
+        end
+        HelperDiscoverer.discover(contents_per_path)
+      end
+
+      def pre_read_helper_files
+        each_helper_file do |path|
+          io_boundary.read_file(path)
+        rescue Plugin::AccessDeniedError, Errno::ENOENT
+          next
+        end
+      end
+
+      def each_helper_file(&)
+        @helper_paths.each do |dir|
+          absolute = File.expand_path(dir)
+          next unless File.directory?(absolute)
+
+          Dir.glob(File.join(absolute, "**", "*.rb")).each(&)
+        end
+      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). Helper files are
+        # pre-read for the same reason — editing a file under
+        # `app/helpers/` MUST invalidate the helper_table cache
+        # so the new custom-helper set is picked up.
+        io_boundary.read_file(@routes_file)
+        pre_read_helper_files
+        @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"

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+# ADR-32 — bundled `rigor-rbs-inline` plugin.
+#
+# Synthesises RBS from project Ruby files that carry
+# rbs-inline-shaped comments (`#: () -> T`, `# @rbs name: T`,
+# `# @rbs return: T`, attribute `#:`, …) and contributes the
+# result to the analysis environment through the
+# `source_rbs_synthesizer:` manifest hook.
+#
+# By default (WD2) only files starting with the upstream
+# `# rbs_inline: enabled` magic comment are processed; a host
+# context can flip this off by setting `require_magic_comment:
+# false` in the plugin config (WD10).
+module Rigor
+  module Plugin
+    # The plugin gem requires `rbs/inline` at load time; without
+    # the upstream library the synthesizer can't do its job.
+    # Wrapped in a begin/rescue so the analyzer still loads if
+    # the user activated this plugin without installing the
+    # `rbs-inline` gem (loud-on-activation, fail-soft to no
+    # contribution).
+    begin
+      require "prism"
+      require "rbs/inline"
+      RBS_INLINE_AVAILABLE = true
+    rescue ::LoadError => e
+      warn(
+        "rigor-rbs-inline: failed to load `rbs/inline` " \
+        "(#{e.message}). The plugin will load but contribute no " \
+        "synthesised RBS. Install the `rbs-inline` gem to enable " \
+        "inline-RBS comment ingestion."
+      )
+      RBS_INLINE_AVAILABLE = false
+    end
+
+    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).
+      class Synthesizer
+        # @param require_magic_comment [Boolean] when `true`
+        #   (the default, WD2), only files with
+        #   `# rbs_inline: enabled` at the top are processed.
+        #   When `false` (WD10 host-context override), every
+        #   file is treated as if it carried the magic comment.
+        def initialize(require_magic_comment:)
+          @require_magic_comment = require_magic_comment
+          freeze
+        end
+
+        # Return value contract:
+        # - `String` (non-empty)         → successful synthesis
+        # - `nil`                        → no contribution
+        # - `[:error, message_string]`   → parse failed, surface
+        #   info diagnostic per ADR-32 WD6
+        def call(source_file_path)
+          return nil unless RBS_INLINE_AVAILABLE
+          return nil unless File.file?(source_file_path)
+
+          source = File.read(source_file_path)
+          return nil if source.empty?
+
+          result = ::Prism.parse(source)
+          # `opt_in: true` is rbs-inline's "require the magic
+          # comment" mode (per upstream parser.rb:62). The
+          # plugin's `require_magic_comment:` config knob maps
+          # directly onto it.
+          parsed = ::RBS::Inline::Parser.parse(result, opt_in: @require_magic_comment)
+          return nil if parsed.nil?
+
+          uses, decls, rbs_decls = parsed
+          rendered = ::RBS::Inline::Writer.write(uses, decls, rbs_decls)
+          return nil if rendered.nil? || rendered.strip.empty?
+
+          rendered
+        rescue ::StandardError => e
+          # WD6 fail-soft — surface a structured error tuple so
+          # the engine's `Environment.for_project` can emit a
+          # `source-rbs-synthesis-failed` info diagnostic
+          # naming the file + the upstream error message,
+          # without crashing analysis.
+          [:error, "#{e.class}: #{e.message.to_s.lines.first.to_s.strip}"]
+        end
+      end
+
+      manifest(
+        id: "rbs-inline",
+        version: "0.1.0",
+        description: "Ingests rbs-inline-shaped comments " \
+                     "(`# @rbs name: T`, `#: () -> T`, …) as RBS contributions.",
+        config_schema: { "require_magic_comment" => :boolean },
+        source_rbs_synthesizer: nil # set per-instance below
+      )
+
+      # Per-instance synthesizer — built from the manifest's
+      # default + the project's plugin config. The manifest
+      # `source_rbs_synthesizer:` is nil at the class level so
+      # the registry sees the instance's override (returned by
+      # `#manifest`, which `Plugin::Registry#source_rbs_synthesizers`
+      # consults via `plugin.manifest.source_rbs_synthesizer`).
+      #
+      # ADR-32 WD10 — `require_magic_comment` defaults to
+      # `true`. Setting it to `false` in `.rigor.yml` flips the
+      # synthesizer into "process every file" mode.
+      def initialize(services:, config: {})
+        super
+        @require_magic_comment = config.fetch("require_magic_comment", true) ? true : false
+        @synthesizer = Synthesizer.new(require_magic_comment: @require_magic_comment)
+        # Build the per-instance manifest eagerly (before
+        # `freeze`) so the registry's repeated reads return
+        # the same object and we don't need to mutate a
+        # frozen instance later.
+        base = self.class.manifest
+        @manifest_with_synth = build_manifest_with_synthesizer(base)
+        freeze
+      end
+
+      attr_reader :synthesizer
+
+      # Override the manifest-level `source_rbs_synthesizer:`
+      # (which is nil at the class level) with the per-instance
+      # synthesizer built from the merged config. The registry
+      # reads this through `plugin.manifest.source_rbs_synthesizer`.
+      def manifest
+        @manifest_with_synth
+      end
+
+      private
+
+      def build_manifest_with_synthesizer(base)
+        Rigor::Plugin::Manifest.new(
+          id: base.id,
+          version: base.version,
+          description: base.description,
+          protocols: base.protocols,
+          config_schema: base.config_schema,
+          produces: base.produces,
+          consumes: base.consumes,
+          owns_receivers: base.owns_receivers,
+          open_receivers: base.open_receivers,
+          type_node_resolvers: base.type_node_resolvers,
+          block_as_methods: base.block_as_methods,
+          heredoc_templates: base.heredoc_templates,
+          trait_registries: base.trait_registries,
+          external_files: base.external_files,
+          hkt_registrations: base.hkt_registrations,
+          hkt_definitions: base.hkt_definitions,
+          signature_paths: base.signature_paths,
+          protocol_contracts: base.protocol_contracts,
+          source_rbs_synthesizer: @synthesizer
+        )
+      end
+    end
+
+    Rigor::Plugin.register(RbsInline)
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# rigor-rbs-inline — ingests rbs-inline-shaped comments
+# (`# @rbs name: T`, `#: () -> T`, `# @rbs return: T`, attribute
+# `#:`, ivars, generics, override, …) as RBS contributions to
+# the analysis environment.
+#
+# Per ADR-32 the plugin gates per file on the upstream
+# `# rbs_inline: enabled` magic comment by default. A host
+# context that owns the entire analysis scope (e.g. the
+# ADR-29 browser playground) can set `require_magic_comment:
+# false` in the plugin config to skip the gate — every file
+# the synthesizer sees is treated as if it carried the magic
+# comment.
+#
+#     # .rigor.yml
+#     plugins:
+#       - id: rigor-rbs-inline
+#         config:
+#           require_magic_comment: false   # default true
+#
+# The plugin depends on the upstream `rbs-inline` gem; Rigor's
+# core `rigortype` gemspec stays zero-dep per ADR-0 / ADR-32 WD1.
+require_relative "rigor/plugin/rbs_inline"

data/plugins/rigor-rspec/lib/rigor/plugin/rspec/analyzer.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "scope_walker"
+
+module Rigor
+  module Plugin
+    class Rspec < Rigor::Plugin::Base
+      # Per-file walker that:
+      #
+      # 1. Collects every RSpec scope (each `RSpec.describe`
+      #    plus its nested `describe` / `context` blocks)
+      #    via {ScopeWalker}.
+      # 2. Reports duplicate `let(:name)` / `subject(:name)`
+      #    declarations within the same scope (the second
+      #    declaration wins at runtime — an easy
+      #    copy-paste bug).
+      # 3. Reports recursive self-references —
+      #    `let(:user) { user.something }` will infinite-loop
+      #    at runtime — an easy oversight.
+      module Analyzer
+        Diagnostic = Struct.new(:path, :line, :column, :severity, :rule, :message, keyword_init: true)
+
+        module_function
+
+        # @param path [String]
+        # @param root [Prism::Node]
+        # @return [Array<Diagnostic>]
+        def diagnose(path:, root:)
+          diagnostics = []
+          ScopeWalker.collect_scopes(root).each do |outer|
+            ScopeWalker.each_scope(outer) do |scope|
+              diagnostics.concat(duplicate_diagnostics(path, scope))
+              diagnostics.concat(self_reference_diagnostics(path, scope))
+            end
+          end
+          diagnostics
+        end
+
+        def duplicate_diagnostics(path, scope)
+          counts = Hash.new { |h, k| h[k] = [] }
+          scope.declarations.each { |decl| counts[decl.name] << decl }
+          counts.flat_map do |name, decls|
+            next [] if decls.size < 2
+
+            duplicate_diagnostics_for(path, name, decls)
+          end
+        end
+
+        def duplicate_diagnostics_for(path, name, decls)
+          # Report each subsequent occurrence; the first
+          # one is the "winner" only by literal source
+          # order, but RSpec lets the LAST declaration win
+          # at runtime, so flag everything after the first
+          # so the user can see the full list.
+          decls.drop(1).map do |decl|
+            Diagnostic.new(
+              path: path,
+              line: decl.location.start_line,
+              column: decl.location.start_column + 1,
+              severity: :warning,
+              rule: "duplicate-let",
+              message: "duplicate `#{decl.kind}(:#{name})` in this scope " \
+                       "(first declared at line #{decls.first.location.start_line}); " \
+                       "the last declaration wins at runtime"
+            )
+          end
+        end
+
+        def self_reference_diagnostics(path, scope)
+          scope.declarations.flat_map do |decl|
+            next [] unless self_references?(decl)
+
+            [self_reference_diagnostic(path, decl)]
+          end
+        end
+
+        # Walks the declaration's block body looking for a
+        # call to its own name with no explicit receiver.
+        # Returns true if at least one such call exists.
+        def self_references?(decl)
+          body = decl.block_node&.body
+          return false if body.nil?
+
+          contains_self_reference?(body, decl.name)
+        end
+
+        def contains_self_reference?(node, name)
+          return false unless node.is_a?(Prism::Node)
+          return true if node.is_a?(Prism::CallNode) && node.name == name && node.receiver.nil?
+
+          node.compact_child_nodes.any? { |child| contains_self_reference?(child, name) }
+        end
+
+        def self_reference_diagnostic(path, decl)
+          Diagnostic.new(
+            path: path,
+            line: decl.location.start_line,
+            column: decl.location.start_column + 1,
+            severity: :error,
+            rule: "self-reference",
+            message: "`#{decl.kind}(:#{decl.name})` references its own name `#{decl.name}` — " \
+                     "this will infinite-loop at runtime"
+          )
+        end
+      end
+    end
+  end
+end