rigortype 0.1.8 → 0.1.9

data/lib/rigor/plugin/protocol_contract.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    # ADR-28 declaration: "every instance/singleton method named
+    # `method_name`, defined in a source file matching `path_glob`,
+    # is implicitly required to satisfy the declared parameter +
+    # return-type protocol."
+    #
+    # Authored on a plugin manifest:
+    #
+    #   manifest(
+    #     id: "web",
+    #     version: "0.1.0",
+    #     protocol_contracts: [
+    #       Rigor::Plugin::ProtocolContract.new(
+    #         path_glob: "lib/controller/**/*.rb",
+    #         method_name: :get,
+    #         param_types: [{ index: 0, type_name: "Rack::Request" }],
+    #         return_type_name: "Rack::Response"
+    #       )
+    #     ]
+    #   )
+    #
+    # The contract drives two distinct engine behaviours (ADR-28
+    # § "provide-and-check"):
+    #
+    # - **provide** — when the inference engine binds the parameter
+    #   list of a matching `def`, {Rigor::Inference::MethodParameterBinder}
+    #   substitutes the declared `param_types` for the usual
+    #   `Dynamic[Top]` fallback, so the method body is analysed as
+    #   if the parameter carried its protocol type.
+    # - **check** — the contributing plugin's `#diagnostics_for_file`
+    #   hook confirms the method exists and its inferred return type
+    #   conforms to `return_type_name`.
+    #
+    # ## Fields
+    #
+    # - `path_glob` — `File.fnmatch` glob (String) selecting the
+    #   source files the contract applies to, relative to the
+    #   analysed project root (e.g. `"lib/controller/**/*.rb"`).
+    # - `method_name` — Symbol; the instance (or singleton) method
+    #   the contract constrains.
+    # - `singleton` — Boolean; `true` constrains `def self.<name>`,
+    #   `false` (default) constrains instance methods.
+    # - `param_types` — Array of `ParamType` (positional index →
+    #   fully-qualified type name). The type names resolve against
+    #   the analysed project's environment lazily, at consumption
+    #   time, so the contract value object stays independent of
+    #   environment construction order.
+    # - `return_type_name` — fully-qualified type name (String) the
+    #   method's inferred return type must conform to.
+    # - `severity` — Symbol diagnostic severity for contract
+    #   violations (`:error` default).
+    #
+    # ## Ractor-shareability
+    #
+    # Every field is frozen at construction (ADR-15 Phase 1); the
+    # nested `ParamType` is a frozen `Data`. `Ractor.shareable?`
+    # returns true after `#initialize`, so the contract survives
+    # `Plugin::Registry.materialize` into a worker Ractor.
+    class ProtocolContract
+      VALID_SEVERITIES = %i[error warning info].freeze
+
+      # One positional-parameter provision: the zero-based index of
+      # the parameter and the fully-qualified name of the type it
+      # carries under the protocol.
+      ParamType = Data.define(:index, :type_name)
+
+      attr_reader :path_glob, :method_name, :singleton, :param_types, :return_type_name, :severity
+
+      def initialize(path_glob:, method_name:, return_type_name: nil, param_types: [], singleton: false,
+                     severity: :error)
+        validate_path_glob!(path_glob)
+        validate_method_name!(method_name)
+        validate_return_type_name!(return_type_name)
+        validate_severity!(severity)
+
+        @path_glob = path_glob.dup.freeze
+        @method_name = method_name.to_sym
+        @singleton = singleton ? true : false
+        @param_types = coerce_param_types(param_types)
+        @return_type_name = return_type_name.nil? ? nil : return_type_name.dup.freeze
+        @severity = severity.to_sym
+        freeze
+      end
+
+      # Returns a copy with `path_glob` replaced. Plugins use this to
+      # honour a per-project config override of the convention path
+      # without rebuilding the whole contract by hand.
+      def with_path_glob(glob)
+        ProtocolContract.new(
+          path_glob: glob,
+          method_name: method_name,
+          return_type_name: return_type_name,
+          param_types: param_types.map { |pt| { index: pt.index, type_name: pt.type_name } },
+          singleton: singleton,
+          severity: severity
+        )
+      end
+
+      def to_h
+        {
+          "path_glob" => path_glob,
+          "method_name" => method_name.to_s,
+          "singleton" => singleton,
+          "param_types" => param_types.map { |pt| { "index" => pt.index, "type_name" => pt.type_name } },
+          "return_type_name" => return_type_name,
+          "severity" => severity.to_s
+        }
+      end
+
+      def ==(other)
+        other.is_a?(ProtocolContract) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      private
+
+      def validate_path_glob!(value)
+        return if value.is_a?(String) && !value.empty?
+
+        raise ArgumentError,
+              "Plugin::ProtocolContract#path_glob must be a non-empty String, got #{value.inspect}"
+      end
+
+      def validate_method_name!(value)
+        return if value.is_a?(Symbol) || (value.is_a?(String) && !value.empty?)
+
+        raise ArgumentError,
+              "Plugin::ProtocolContract#method_name must be a Symbol/non-empty String, got #{value.inspect}"
+      end
+
+      def validate_return_type_name!(value)
+        return if value.nil?
+        return if value.is_a?(String) && !value.empty?
+
+        raise ArgumentError,
+              "Plugin::ProtocolContract#return_type_name must be a non-empty String or nil, got #{value.inspect}"
+      end
+
+      def validate_severity!(value)
+        return if VALID_SEVERITIES.include?(value.to_sym)
+
+        raise ArgumentError,
+              "Plugin::ProtocolContract#severity must be one of #{VALID_SEVERITIES.inspect}, got #{value.inspect}"
+      rescue NoMethodError
+        raise ArgumentError,
+              "Plugin::ProtocolContract#severity must be one of #{VALID_SEVERITIES.inspect}, got #{value.inspect}"
+      end
+
+      def coerce_param_types(param_types)
+        unless param_types.is_a?(Array)
+          raise ArgumentError,
+                "Plugin::ProtocolContract#param_types must be an Array, got #{param_types.inspect}"
+        end
+
+        param_types.map { |entry| coerce_param_type(entry) }.freeze
+      end
+
+      def coerce_param_type(entry)
+        return entry if entry.is_a?(ParamType)
+
+        unless entry.is_a?(Hash)
+          raise ArgumentError,
+                "Plugin::ProtocolContract param_types entry must be a Hash or ParamType, got #{entry.inspect}"
+        end
+
+        index = entry[:index] || entry["index"]
+        type_name = entry[:type_name] || entry["type_name"]
+        unless index.is_a?(Integer) && index >= 0 && type_name.is_a?(String) && !type_name.empty?
+          raise ArgumentError,
+                "Plugin::ProtocolContract param_types entry needs an Integer index >= 0 and a " \
+                "non-empty String type_name, got #{entry.inspect}"
+        end
+
+        ParamType.new(index: index, type_name: type_name.dup.freeze)
+      end
+    end
+  end
+end

data/lib/rigor/plugin/registry.rb

@@ -104,7 +104,73 @@ module Rigor
         Inference::HktRegistry.new(registrations: registrations, definitions: definitions)
       end
 
+      # ADR-25 — flat, ordered list of every loaded plugin's
+      # resolved RBS signature directories (absolute paths), in
+      # plugin registration order. `Environment.for_project`
+      # merges these into the signature-path set fed to
+      # `RbsLoader`, alongside the configuration's `signature_paths:`
+      # and the `bundler:` / `rbs_collection:` discovery output.
+      def signature_paths
+        plugins.flat_map(&:signature_paths)
+      end
+
+      # ADR-26 — the aggregate set of "open" receiver class names
+      # declared across loaded plugins (manifest `open_receivers:`).
+      # A class is open when a plugin vouches that it responds
+      # beyond its RBS-declared method surface. `open_receiver?`
+      # is the membership predicate `Analysis::CheckRules` consults
+      # to skip the `call.undefined-method` rule for such a class.
+      def open_receivers
+        plugins.flat_map { |plugin| plugin.manifest.open_receivers }
+      end
+
+      def open_receiver?(class_name)
+        return false if class_name.nil?
+
+        open_receivers.include?(class_name.to_s)
+      end
+
+      # ADR-28 — flat, ordered list of every loaded plugin's
+      # path-scoped method-protocol contracts, in plugin
+      # registration order. Read from each plugin's
+      # `#protocol_contracts` (which the manifest backs by default
+      # but a plugin MAY override to fold in per-project config).
+      # Consumed by `Inference::MethodParameterBinder` (the
+      # parameter-type provision) and by contributing plugins'
+      # `#diagnostics_for_file` hooks (the presence + return-type
+      # check).
+      def protocol_contracts
+        plugins.flat_map(&:protocol_contracts)
+      end
+
+      # ADR-28 — the subset of `protocol_contracts` whose
+      # `path_glob` matches `path`. Contract globs are authored
+      # project-root-relative (`lib/controller/**/*.rb`); the
+      # analyzer may hand this method either a project-relative
+      # path (`rigor check` run from the project root) or an
+      # absolute one (run from elsewhere, or a spec tmpdir), so the
+      # glob is matched both directly and as a `**/`-prefixed path
+      # suffix. `File::FNM_PATHNAME` keeps `*` from crossing `/`;
+      # `File::FNM_EXTGLOB` enables `{a,b}` groups. Returns `[]` for
+      # a nil path so the binder can call this unconditionally.
+      def contracts_for_path(path)
+        return [] if path.nil?
+
+        path_s = path.to_s
+        protocol_contracts.select { |contract| path_matches_glob?(contract.path_glob, path_s) }
+      end
+
+      FNMATCH_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+      private_constant :FNMATCH_FLAGS
+
       EMPTY = new.freeze
+
+      private
+
+      def path_matches_glob?(glob, path)
+        File.fnmatch?(glob, path, FNMATCH_FLAGS) ||
+          File.fnmatch?(File.join("**", glob), path, FNMATCH_FLAGS)
+      end
     end
   end
 end

data/lib/rigor/triage/catalogue.rb

@@ -122,8 +122,8 @@ module Rigor
           diagnostic_count: matched.size,
           summary: "undefined-method on core classes (#{top_methods(matched)}) — " \
                    "ActiveSupport monkey-patches these",
-          action: "Wire the rigor-activesupport-core-ext RBS bundle via " \
-                  "`signature_paths:` in .rigor.yml."
+          action: "Add rigor-activesupport-core-ext to `plugins:` in .rigor.yml " \
+                  "(it is an RBS-bundle plugin — ADR-25)."
         ), matched]
       end
 

data/lib/rigor/type/constant.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "date"
 require_relative "../trinary"
 
 module Rigor
@@ -24,6 +25,13 @@ module Rigor
         Complex,
         Regexp,
         Pathname,
+        ::Set,
+        # `Date` covers `DateTime` (a subclass). `Time` is core.
+        # Both arise only from deterministic constructor folding
+        # (`Date.new` / `Time.utc`) — there is no Date / Time
+        # literal node — so a `Constant` carrier is always sound.
+        Date,
+        Time,
         TrueClass,
         FalseClass,
         NilClass
@@ -42,12 +50,31 @@ module Rigor
           raise ArgumentError, "Rigor::Type::Constant only carries scalar literals; got #{value.class}"
         end
 
-        @value = value.is_a?(String) ? value.dup.freeze : value
+        @value = freezable_carrier?(value) ? value.dup.freeze : value
         freeze
       end
 
+      # Mutable-ish carriers are stored as a frozen copy so a later
+      # in-place mutation cannot rewrite the literal under us. `Time`
+      # joins `String` / `Set` here: `Time#localtime` mutates the
+      # receiver's zone in place, so the carrier holds a frozen copy
+      # (the catalog also blocklists the mutators). `Date` is already
+      # immutable, but is duped-and-frozen for symmetry.
+      def freezable_carrier?(value)
+        value.is_a?(String) || value.is_a?(::Set) ||
+          value.is_a?(Date) || value.is_a?(Time)
+      end
+
+      # `Date#inspect` / `DateTime#inspect` spell out the internal
+      # astronomical-Julian-day representation, which is unreadable
+      # in a diagnostic. ISO-8601 is the compact, deterministic
+      # form. `Time#inspect` is already compact (`2026-01-01
+      # 00:00:00 UTC`), so it keeps the default.
       def describe(_verbosity = :short)
-        value.inspect
+        case value
+        when Date then value.iso8601
+        else value.inspect
+        end
       end
 
       # RBS supports `Literal` types for booleans, nil, integer

data/lib/rigor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rigor
-  VERSION = "0.1.8"
+  VERSION = "0.1.9"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rigortype
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.9
 platform: ruby
 authors:
 - Rigor contributors
@@ -261,10 +261,12 @@ files:
 - lib/rigor/cache/rbs_known_class_names.rb
 - lib/rigor/cache/store.rb
 - lib/rigor/cli.rb
+- lib/rigor/cli/annotate_command.rb
 - lib/rigor/cli/baseline_command.rb
 - lib/rigor/cli/diff_command.rb
 - lib/rigor/cli/explain_command.rb
 - lib/rigor/cli/lsp_command.rb
+- lib/rigor/cli/prism_colorizer.rb
 - lib/rigor/cli/sig_gen_command.rb
 - lib/rigor/cli/triage_command.rb
 - lib/rigor/cli/triage_renderer.rb
@@ -327,16 +329,23 @@ files:
 - lib/rigor/inference/macro_block_self_type.rb
 - lib/rigor/inference/method_dispatcher.rb
 - lib/rigor/inference/method_dispatcher/block_folding.rb
+- lib/rigor/inference/method_dispatcher/cgi_folding.rb
 - lib/rigor/inference/method_dispatcher/constant_folding.rb
 - lib/rigor/inference/method_dispatcher/file_folding.rb
 - lib/rigor/inference/method_dispatcher/iterator_dispatch.rb
 - lib/rigor/inference/method_dispatcher/kernel_dispatch.rb
 - lib/rigor/inference/method_dispatcher/literal_string_folding.rb
+- lib/rigor/inference/method_dispatcher/math_folding.rb
 - lib/rigor/inference/method_dispatcher/method_folding.rb
 - lib/rigor/inference/method_dispatcher/overload_selector.rb
 - lib/rigor/inference/method_dispatcher/rbs_dispatch.rb
 - lib/rigor/inference/method_dispatcher/receiver_affinity.rb
+- lib/rigor/inference/method_dispatcher/regexp_folding.rb
+- lib/rigor/inference/method_dispatcher/set_folding.rb
 - lib/rigor/inference/method_dispatcher/shape_dispatch.rb
+- lib/rigor/inference/method_dispatcher/shellwords_folding.rb
+- lib/rigor/inference/method_dispatcher/time_folding.rb
+- lib/rigor/inference/method_dispatcher/uri_folding.rb
 - lib/rigor/inference/method_parameter_binder.rb
 - lib/rigor/inference/multi_target_binder.rb
 - lib/rigor/inference/narrowing.rb
@@ -378,6 +387,7 @@ files:
 - lib/rigor/plugin/macro/heredoc_template.rb
 - lib/rigor/plugin/macro/trait_registry.rb
 - lib/rigor/plugin/manifest.rb
+- lib/rigor/plugin/protocol_contract.rb
 - lib/rigor/plugin/registry.rb
 - lib/rigor/plugin/services.rb
 - lib/rigor/plugin/trust_policy.rb