rigortype 0.1.9 → 0.1.11

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "prism"
+require "rigor/plugin"
+
+require_relative "hanami/action_checker"
+
+module Rigor
+  module Plugin
+    # rigor-hanami — enforces the Hanami::Action protocol.
+    #
+    # Hanami 3.x actions inherit from `Hanami::Action` and
+    # define a single entry-point:
+    #
+    #   def handle(request, response)
+    #     response.status = 200
+    #     response.body = "Hello"
+    #   end
+    #
+    # The method is void — the response is mutated in-place;
+    # the return value is discarded by the framework.
+    #
+    # This plugin uses the **ADR-28 path-scoped
+    # method-protocol contract** to:
+    #
+    # 1. **Provide** `Hanami::Action::Request` and
+    #    `Hanami::Action::Response` as the types of the
+    #    first and second parameters of every `#handle`
+    #    method defined inside `app/actions/**/*.rb`.
+    #    The engine substitutes these types for the usual
+    #    `Dynamic[Top]` fallback, so misuse of `request` or
+    #    `response` inside an action body surfaces as a
+    #    core diagnostic.
+    #
+    # 2. **Check** that every class under `app/actions/`
+    #    defines `#handle`. Missing definitions emit
+    #    `missing-handle-method`.
+    #
+    # Return-type conformance is NOT checked — Hanami
+    # actions are void by contract, and checking a void
+    # return would produce false positives on every `if`
+    # branch that doesn't end with an explicit `nil`.
+    #
+    # ## Configuration
+    #
+    #     plugins:
+    #       - gem: rigor-hanami
+    #         config:
+    #           action_path: "app/actions/**/*.rb"   # default; optional
+    #
+    # ## Diagnostics
+    #
+    # | Event                                    | Severity | Rule                    |
+    # | ---                                      | ---      | ---                     |
+    # | action class defines no `#handle`        | `:error` | `missing-handle-method` |
+    # | `request` / `response` misuse in body    | core engine diagnostic  |
+    #
+    # A misused `request` or `response` (e.g.
+    # `request.no_such_method`) surfaces as a standard
+    # engine `call.undefined-method` diagnostic once the
+    # plugin provides the parameter types.
+    class Hanami < Rigor::Plugin::Base
+      manifest(
+        id: "hanami",
+        version: "0.1.0",
+        description: "Enforces the Hanami::Action protocol: #handle(request, response) → void.",
+        config_schema: {
+          "action_path" => :string
+        },
+        signature_paths: ["sig"],
+        protocol_contracts: [
+          Rigor::Plugin::ProtocolContract.new(
+            path_glob: "app/actions/**/*.rb",
+            method_name: :handle,
+            param_types: [
+              { index: 0, type_name: "Hanami::Action::Request" },
+              { index: 1, type_name: "Hanami::Action::Response" }
+            ]
+            # return_type_name: nil — void; skip return-type conformance check
+          )
+        ]
+      )
+
+      def init(_services)
+        override = config["action_path"]
+        @protocol_contracts =
+          if override.nil? || override.to_s.empty?
+            manifest.protocol_contracts
+          else
+            manifest.protocol_contracts.map { |c| c.with_path_glob(override.to_s) }
+          end
+      end
+
+      # ADR-28: override so the per-project `action_path` config
+      # reaches both the engine's parameter-provision tier and
+      # this plugin's check half.
+      def protocol_contracts
+        @protocol_contracts || manifest.protocol_contracts
+      end
+
+      def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
+        contracts = protocol_contracts
+        return [] if contracts.empty?
+
+        ActionChecker.new(contracts: contracts).check(path: path, root: root)
+      end
+    end
+
+    Rigor::Plugin.register(Hanami)
+  end
+end

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

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

data/plugins/rigor-hanami/sig/hanami_action.rbs

@@ -0,0 +1,78 @@
+# Minimal Hanami::Action type stubs for rigor-hanami.
+#
+# Hanami::Action::Request and Hanami::Action::Response are
+# defined as standalone types (without declaring Rack::Request /
+# Rack::Response inheritance) so this file is self-contained
+# regardless of whether a Rack RBS bundle is present in the
+# analysed project.
+#
+# The methods listed here cover the surface documented at:
+# https://guides.hanamirb.org/v3.0/actions/request-and-response/
+
+module Hanami
+  module Action
+    # Represents the incoming HTTP request inside `#handle`.
+    class Request
+      def path_info: () -> String
+      def request_method: () -> String
+      def get?: () -> bool
+      def post?: () -> bool
+      def patch?: () -> bool
+      def put?: () -> bool
+      def delete?: () -> bool
+      def head?: () -> bool
+      def xhr?: () -> bool
+      def params: () -> Hanami::Action::Params
+      def session: () -> Hash[Symbol, untyped]
+      def flash: () -> Hash[Symbol, untyped]
+      def content_type: () -> String?
+      def env: () -> Hash[String, untyped]
+      def body: () -> String
+      def get_header: (String name) -> String?
+      def ip: () -> String?
+      def referer: () -> String?
+      def user_agent: () -> String?
+      def subdomain: (?Integer tld_length) -> String?
+      def subdomains: (?Integer tld_length) -> Array[String]
+      def cookies: () -> Hash[String, String]
+      def host: () -> String
+      def port: () -> Integer
+      def url: () -> String
+      def base_url: () -> String
+      def query_string: () -> String
+      def multipart?: () -> bool
+      def form_data?: () -> bool
+    end
+
+    # Represents the outgoing HTTP response inside `#handle`.
+    # The response is mutated in-place; the `#handle` return
+    # value is discarded by the framework.
+    class Response
+      def status: () -> Integer
+      def status=: (Integer | Symbol) -> void
+      def body: () -> Array[String]
+      def body=: (String | Array[String]) -> void
+      def headers: () -> Hash[String, String]
+      def format=: (Symbol | String) -> void
+      def redirect_to: (String url, ?Integer status) -> void
+      def write: (String str) -> void
+      def set_cookie: (String name, ?(String | Hash[Symbol, untyped]) value) -> void
+      def delete_cookie: (String name, ?Hash[Symbol, untyped] options) -> void
+      def content_type: () -> String
+      def content_type=: (String) -> void
+    end
+
+    # Typed parameter container. Values are coerced by the
+    # action's `params` block schema (if declared); otherwise
+    # all values are `untyped`.
+    class Params
+      def []: (Symbol key) -> untyped
+      def dig: (Symbol, *Symbol) -> untyped
+      def valid?: () -> bool
+      def errors: () -> Hash[Symbol, Array[String]]
+      def to_h: () -> Hash[Symbol, untyped]
+      def fetch: (Symbol key, ?untyped default) -> untyped
+      def slice: (*Symbol keys) -> Hash[Symbol, untyped]
+    end
+  end
+end

data/plugins/rigor-minitest/lib/rigor/plugin/minitest/assertion_analyzer.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+require "prism"
+require "rigor/type"
+require "rigor/flow_contribution"
+require "rigor/flow_contribution/fact"
+
+module Rigor
+  module Plugin
+    class Minitest < Rigor::Plugin::Base
+      # Recognises the four shapes of Minitest / Test::Unit
+      # assertions and emits a `post_return_fact` that narrows
+      # the named local on the post-call edge.
+      #
+      # ## Recognised call shapes
+      #
+      # ### (1) Minitest / Test::Unit `assert_*` (positive) ###
+      #
+      #   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)    →  narrow x to Constant<literal>
+      #   assert_match(regex, x)      →  narrow x to String
+      #
+      # ### (2) Minitest / Test::Unit `refute_*` / `assert_not_*` (negative) ###
+      #
+      #   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)    →  narrow x AWAY from Constant<literal>
+      #
+      # 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).
+      #
+      # ### (3) Minitest/spec `_(x).must_*` (positive) ###
+      #
+      #   _(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)    →  narrow x to Constant<literal>
+      #   _(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 intentionally NOT
+      # recognised — the receiver is the value itself rather
+      # than a wrapping `_(value)`, so the analyzer has nothing
+      # to narrow against. Users who still rely on the legacy
+      # form should migrate to `_(x).must_*`.
+      #
+      # ### (4) Minitest/spec `_(x).wont_*` (negative) ###
+      #
+      #   _(x).wont_be_kind_of(T)     →  narrow x AWAY from T
+      #   _(x).wont_be_nil            →  narrow x AWAY from nil
+      #   _(x).wont_equal(literal)    →  narrow x AWAY from Constant<literal>
+      #
+      # ## Not yet recognised
+      #
+      # `assert_predicate(x, :foo?)` (custom predicate) /
+      # `assert_respond_to(x, :method)` / `assert_includes` /
+      # `assert_operator` / `assert_throws` /
+      # `assert_raises(T) { ... }` etc. — each either needs a
+      # carrier Rigor doesn't model today (predicate-state,
+      # respond-to-set) or a multi-edge fact that the
+      # `post_return_facts` slot can't express. Queued for
+      # follow-up slices.
+      module AssertionAnalyzer
+        module_function
+
+        # @param call_node [Prism::CallNode]
+        # @param environment [Rigor::Environment, nil]
+        # @return [Rigor::FlowContribution, nil]
+        def contribution_for(call_node, environment:)
+          return nil unless call_node.is_a?(Prism::CallNode)
+
+          fact =
+            assert_form_fact(call_node, environment: environment) ||
+            spec_form_fact(call_node, environment: environment)
+          return nil if fact.nil?
+
+          Rigor::FlowContribution.new(post_return_facts: [fact])
+        end
+
+        # --- assert_* / refute_* / assert_not_* form ---
+
+        # Maps each recognised assertion name to a tuple
+        # `[shape, negative]`. `shape` is one of:
+        #
+        # - :class_then_local   — `assert_kind_of(T, x)`, T at
+        #   args[0], local at args[1].
+        # - :nil_local          — `assert_nil(x)`, local at args[0].
+        # - :literal_then_local — `assert_equal(literal, x)`,
+        #   literal at args[0], local at args[1].
+        # - :regex_then_local   — `assert_match(regex, x)`,
+        #   regex at args[0], local at args[1].
+        ASSERT_FORM = {
+          assert_kind_of: [:class_then_local, false],
+          assert_instance_of: [:class_then_local, false],
+          refute_kind_of: [:class_then_local, true],
+          refute_instance_of: [:class_then_local, true],
+          assert_not_kind_of: [:class_then_local, true],
+          assert_not_instance_of: [:class_then_local, true],
+          assert_nil: [:nil_local, false],
+          refute_nil: [:nil_local, true],
+          assert_not_nil: [:nil_local, true],
+          assert_equal: [:literal_then_local, false],
+          refute_equal: [:literal_then_local, true],
+          assert_not_equal: [:literal_then_local, true],
+          assert_match: [:regex_then_local, false]
+        }.freeze
+        private_constant :ASSERT_FORM
+
+        def assert_form_fact(call_node, environment:)
+          return nil unless call_node.receiver.nil?
+
+          shape_negative = ASSERT_FORM[call_node.name]
+          return nil if shape_negative.nil?
+
+          shape, negative = shape_negative
+          args = call_node.arguments&.arguments || []
+          fact_for_shape(shape, args, negative: negative, environment: environment)
+        end
+
+        # --- _(x).must_* / .wont_* form ---
+
+        # Maps the spec-style matcher names to `[shape,
+        # negative]`. `shape`:
+        # - :class_arg   — `_(x).must_be_kind_of(T)`, T at args[0].
+        # - :no_arg_nil  — `_(x).must_be_nil`, no args.
+        # - :literal_arg — `_(x).must_equal(literal)`, literal at args[0].
+        # - :regex_arg   — `_(x).must_match(regex)`, regex at args[0].
+        SPEC_MATCHER_FORM = {
+          must_be_kind_of: [:class_arg, false],
+          must_be_instance_of: [:class_arg, false],
+          must_be_a: [:class_arg, false],
+          must_be_an_instance_of: [:class_arg, false],
+          wont_be_kind_of: [:class_arg, true],
+          wont_be_instance_of: [:class_arg, true],
+          must_be_nil: [:no_arg_nil, false],
+          wont_be_nil: [:no_arg_nil, true],
+          must_equal: [:literal_arg, false],
+          wont_equal: [:literal_arg, true],
+          must_match: [:regex_arg, false]
+        }.freeze
+        private_constant :SPEC_MATCHER_FORM
+
+        def spec_form_fact(call_node, environment:)
+          shape_negative = SPEC_MATCHER_FORM[call_node.name]
+          return nil if shape_negative.nil?
+
+          target_local = spec_receiver_local(call_node)
+          return nil if target_local.nil?
+
+          shape, negative = shape_negative
+          args = call_node.arguments&.arguments || []
+          fact_for_spec_shape(shape, target_local, args, negative: negative, environment: environment)
+        end
+
+        # `_(x)` returns a `Minitest::Expectation` wrapping x.
+        # Some specs use `value(x)` or `expect(x)` interchangeably
+        # (Minitest provides all three as aliases). Recognises the
+        # local-variable arg in any of those receiver-call shapes.
+        SPEC_WRAPPER_NAMES = %i[_ value expect].freeze
+        private_constant :SPEC_WRAPPER_NAMES
+
+        def spec_receiver_local(matcher_call)
+          recv = matcher_call.receiver
+          return nil unless recv.is_a?(Prism::CallNode)
+          return nil unless recv.receiver.nil? && SPEC_WRAPPER_NAMES.include?(recv.name)
+
+          args = recv.arguments&.arguments || []
+          return nil unless args.size == 1
+          return nil unless args.first.is_a?(Prism::LocalVariableReadNode)
+
+          args.first.name
+        end
+
+        # --- shape resolvers ---
+
+        def fact_for_shape(shape, args, negative:, environment:)
+          case shape
+          when :class_then_local
+            return nil unless args.size == 2
+            return nil unless args[1].is_a?(Prism::LocalVariableReadNode)
+
+            type = nominal_type_for(args[0], environment: environment)
+            fact_for(args[1].name, type, negative: negative)
+          when :nil_local
+            return nil unless args.size == 1
+            return nil unless args[0].is_a?(Prism::LocalVariableReadNode)
+
+            fact_for(args[0].name, Rigor::Type::Combinator.constant_of(nil), negative: negative)
+          when :literal_then_local
+            return nil unless args.size == 2
+            return nil unless args[1].is_a?(Prism::LocalVariableReadNode)
+
+            literal = literal_value_for(args[0])
+            return nil if literal.equal?(NO_LITERAL)
+
+            fact_for(args[1].name, Rigor::Type::Combinator.constant_of(literal), negative: negative)
+          when :regex_then_local
+            return nil unless args.size == 2
+            return nil unless args[1].is_a?(Prism::LocalVariableReadNode)
+            return nil unless regex_literal?(args[0])
+
+            fact_for(args[1].name, Rigor::Type::Combinator.nominal_of("String"), negative: negative)
+          end
+        end
+
+        def fact_for_spec_shape(shape, target_local, args, negative:, environment:)
+          case shape
+          when :class_arg
+            return nil unless args.size == 1
+
+            type = nominal_type_for(args[0], environment: environment)
+            fact_for(target_local, type, negative: negative)
+          when :no_arg_nil
+            return nil unless args.empty?
+
+            fact_for(target_local, Rigor::Type::Combinator.constant_of(nil), negative: negative)
+          when :literal_arg
+            return nil unless args.size == 1
+
+            literal = literal_value_for(args[0])
+            return nil if literal.equal?(NO_LITERAL)
+
+            fact_for(target_local, Rigor::Type::Combinator.constant_of(literal), negative: negative)
+          when :regex_arg
+            return nil unless args.size == 1
+            return nil unless regex_literal?(args[0])
+
+            fact_for(target_local, Rigor::Type::Combinator.nominal_of("String"), negative: negative)
+          end
+        end
+
+        def fact_for(local_name, type, negative:)
+          return nil if type.nil?
+
+          Rigor::FlowContribution::Fact.new(
+            target_kind: :local,
+            target_name: local_name,
+            type: type,
+            negative: negative
+          )
+        end
+
+        # --- helpers shared with rigor-rspec MatcherAnalyzer ---
+
+        def nominal_type_for(node, environment:)
+          class_name = constant_path_name(node)
+          return nil if class_name.nil?
+
+          if environment
+            environment.nominal_for_name(class_name) ||
+              Rigor::Type::Combinator.nominal_of(class_name)
+          else
+            Rigor::Type::Combinator.nominal_of(class_name)
+          end
+        end
+
+        NO_LITERAL = Object.new.freeze
+        private_constant :NO_LITERAL
+
+        def literal_value_for(node)
+          case node
+          when Prism::IntegerNode then node.value
+          when Prism::FloatNode then node.value
+          when Prism::TrueNode then true
+          when Prism::FalseNode then false
+          when Prism::NilNode then nil
+          when Prism::StringNode then node.unescaped
+          when Prism::SymbolNode then node.unescaped.to_sym
+          else NO_LITERAL
+          end
+        end
+
+        def regex_literal?(node)
+          node.is_a?(Prism::RegularExpressionNode) ||
+            node.is_a?(Prism::InterpolatedRegularExpressionNode)
+        end
+
+        def constant_path_name(node)
+          case node
+          when Prism::ConstantReadNode
+            node.name.to_s
+          when Prism::ConstantPathNode
+            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
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+require_relative "minitest/assertion_analyzer"
+
+module Rigor
+  module Plugin
+    # rigor-minitest — narrows locals through Minitest /
+    # Test::Unit assertions.
+    #
+    # Recognises every supported `assert_*` / `refute_*` /
+    # `assert_not_*` shape (Minitest core + Test::Unit aliases),
+    # plus the Minitest/spec `_(x).must_*` / `.wont_*` matchers
+    # (`expect(x)` / `value(x)` wrappers covered too). For each
+    # recognised assertion the plugin emits a Rigor
+    # `post_return_fact` whose `:local`-kind target narrows the
+    # named local on the post-call edge so downstream calls in
+    # the same `it` / `test_` / `def test_*` body resolve
+    # against the narrowed type.
+    #
+    # ## Why a single plugin covers two frameworks
+    #
+    # Minitest and Test::Unit share the `assert_*` / `refute_*`
+    # surface (Test::Unit's `assert_not_*` aliases are
+    # recognised by the same rule table). The matchers_vaccine
+    # gem layers RSpec-style matcher composition on top of
+    # Minitest's `must` API and is covered by the spec-style
+    # recogniser without additional wiring.
+    #
+    # ## Configuration
+    #
+    # No knobs in v0.1.0. Activate via `plugins: ["rigor-minitest"]`
+    # in `.rigor.yml`.
+    #
+    # ## Limitations (v0.1.0)
+    #
+    # - **No `assert_raises(T) { ... }`** — that's a block-shape
+    #   matcher and Rigor's narrowing model is for
+    #   straight-line locals.
+    # - **No `assert_predicate(x, :foo?)`** — needs a
+    #   predicate-state carrier Rigor doesn't model today.
+    # - **No `assert_respond_to(x, :m)`** — same shape gap
+    #   (respond-to-set carrier).
+    # - **No legacy bare `x.must_be_kind_of(T)`** — the
+    #   receiver IS the value, so the analyzer has nothing to
+    #   narrow against. Users should migrate to `_(x).must_*`.
+    # - **No `assert_in_delta` / `assert_operator`** — float-
+    #   range / generic operator narrowing is future work.
+    # - **No `assert_throws(:tag) { ... }` / `assert_raises`** —
+    #   block-form expectations need a separate slice.
+    class Minitest < Rigor::Plugin::Base
+      manifest(
+        id: "minitest",
+        version: "0.1.0",
+        description: "Narrows locals through Minitest / Test::Unit `assert_*` / `refute_*` " \
+                     "and Minitest/spec `_(x).must_*` / `.wont_*` matchers."
+      )
+
+      # Pillar 2 Slice 1 (rigor-minitest sibling) — emits
+      # `post_return_facts` for every recognised assertion. The
+      # engine routes `:local`-kind facts through
+      # `StatementEvaluator#apply_local_post_return_fact` (added
+      # in v0.1.8 for the rigor-rspec slice).
+      def flow_contribution_for(call_node:, scope:)
+        AssertionAnalyzer.contribution_for(call_node, environment: scope&.environment)
+      end
+    end
+
+    Rigor::Plugin.register(Minitest)
+  end
+end

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

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