rigortype 0.0.9 → 0.1.1

data/lib/rigor/environment/rbs_loader.rb

@@ -125,19 +125,42 @@ module Rigor
 
         env.class_decls.each_key { |rbs_name| yield rbs_name.to_s }
         env.class_alias_decls.each_key { |rbs_name| yield rbs_name.to_s }
-      rescue StandardError
-        # fail-soft: a broken environment yields no names.
+      rescue ::RBS::BaseError
+        # fail-soft: a broken RBS environment yields no names.
+        # Analyzer-internal errors (NameError, NoMethodError,
+        # LoadError) are NOT swallowed — those are bugs and
+        # must surface so they don't hide silently the way the
+        # v0.0.9 cache `Cache::Descriptor` regression did.
       end
 
       # @return [RBS::Definition, nil] the resolved instance definition
       #   for `class_name`, or nil when the class is unknown or its
       #   definition cannot be built (RBS may raise on broken hierarchies;
       #   we fail-soft and return nil so the caller can fall back).
+      #
+      # When `cache_store` is set, the loader fetches the per-class
+      # definition through {Cache::RbsInstanceDefinitions.fetch} so
+      # subsequent runs (and other loaders sharing the same Store)
+      # skip the `RBS::DefinitionBuilder.build_instance` step.
+      # In-memory `@instance_definition_cache` keeps the per-process
+      # short-circuit on top.
       def instance_definition(class_name)
         key = class_name.to_s
         return @instance_definition_cache[key] if @instance_definition_cache.key?(key)
 
-        @instance_definition_cache[key] = build_instance_definition(class_name)
+        @instance_definition_cache[key] = if cache_store
+                                            cached_instance_definition(class_name)
+                                          else
+                                            build_instance_definition(class_name)
+                                          end
+      end
+
+      # Public uncached accessor used by the cache producer
+      # ({Rigor::Cache::RbsInstanceDefinitions}). Avoids the
+      # `private_method_called` round-trip a `loader.send(...)`
+      # callsite would require.
+      def uncached_instance_definition(class_name)
+        build_instance_definition(class_name)
       end
 
       # @return [RBS::Definition::Method, nil]
@@ -153,11 +176,25 @@ module Rigor
       #   definition are the *class methods* of `class_name`, including
       #   those inherited from `Class` and `Module` for class types.
       #   Returns nil for unknown names and on RBS build errors (fail-soft).
+      #
+      # When `cache_store` is set, the loader fetches the per-class
+      # singleton definition through
+      # {Cache::RbsSingletonDefinitions.fetch}; the same caching
+      # discipline as {#instance_definition}.
       def singleton_definition(class_name)
         key = class_name.to_s
         return @singleton_definition_cache[key] if @singleton_definition_cache.key?(key)
 
-        @singleton_definition_cache[key] = build_singleton_definition(class_name)
+        @singleton_definition_cache[key] = if cache_store
+                                             cached_singleton_definition(class_name)
+                                           else
+                                             build_singleton_definition(class_name)
+                                           end
+      end
+
+      # Public uncached accessor used by the cache producer.
+      def uncached_singleton_definition(class_name)
+        build_singleton_definition(class_name)
       end
 
       # @return [RBS::Definition::Method, nil] the class method on
@@ -214,7 +251,7 @@ module Rigor
       #   should keep using {#constant_type} for point lookups.
       def constant_names
         env.constant_decls.keys.map(&:to_s)
-      rescue StandardError
+      rescue ::RBS::BaseError
         []
       end
 
@@ -229,8 +266,8 @@ module Rigor
         env.constant_decls.each do |rbs_name, entry|
           yield rbs_name.to_s, entry
         end
-      rescue StandardError
-        # fail-soft: a broken environment yields no entries.
+      rescue ::RBS::BaseError
+        # fail-soft: a broken RBS environment yields no entries.
       end
 
       # Slice A constant-value lookup. Returns the translated
@@ -258,7 +295,7 @@ module Rigor
         else
           translate_constant_decl(rbs_name)
         end
-      rescue StandardError
+      rescue ::RBS::BaseError
         nil
       end
 
@@ -290,7 +327,7 @@ module Rigor
         return false unless rbs_name
 
         known_class_names_set.include?(rbs_name.to_s)
-      rescue StandardError
+      rescue ::RBS::BaseError
         false
       end
 
@@ -311,6 +348,45 @@ module Rigor
         Cache::RbsEnvironment.fetch(loader: self, store: cache_store)
       end
 
+      # Per-process Hash<String, RBS::Definition> for the instance
+      # side. Loaded once on first miss through the
+      # {Cache::RbsInstanceDefinitions} producer (single Marshal
+      # blob); subsequent calls are pure Hash lookups. Cold runs
+      # build every known class once and persist; warm runs (and
+      # other loaders sharing the same Store) skip the
+      # `RBS::DefinitionBuilder.build_instance` work entirely.
+      def cached_instance_definition(class_name)
+        instance_definitions_table[normalise_class_key(class_name)]
+      end
+
+      def instance_definitions_table
+        @state[:instance_definitions_table] ||= begin
+          require_relative "../cache/rbs_instance_definitions"
+          Cache::RbsInstanceDefinitions.fetch(loader: self, store: cache_store)
+        end
+      end
+
+      def cached_singleton_definition(class_name)
+        singleton_definitions_table[normalise_class_key(class_name)]
+      end
+
+      def singleton_definitions_table
+        @state[:singleton_definitions_table] ||= begin
+          require_relative "../cache/rbs_instance_definitions"
+          Cache::RbsSingletonDefinitions.fetch(loader: self, store: cache_store)
+        end
+      end
+
+      # The cache producers persist class names in
+      # `RBS::TypeName#to_s` form (top-level prefixed
+      # `"::Hash"`); plain-name lookups (`"Hash"`) normalise
+      # before the Hash query so callers stay agnostic to the
+      # prefix.
+      def normalise_class_key(class_name)
+        s = class_name.to_s
+        s.start_with?("::") ? s : "::#{s}"
+      end
+
       def builder
         @state[:builder] ||= RBS::DefinitionBuilder.new(env: env)
       end
@@ -325,7 +401,7 @@ module Rigor
         return nil unless env.class_decls.key?(rbs_name)
 
         builder.build_instance(rbs_name)
-      rescue StandardError
+      rescue ::RBS::BaseError
         nil
       end
 
@@ -335,7 +411,7 @@ module Rigor
         return nil unless env.class_decls.key?(rbs_name)
 
         builder.build_singleton(rbs_name)
-      rescue StandardError
+      rescue ::RBS::BaseError
         nil
       end
 
@@ -345,7 +421,7 @@ module Rigor
 
         s = "::#{s}" unless s.start_with?("::")
         RBS::TypeName.parse(s)
-      rescue StandardError
+      rescue ::RBS::BaseError
         nil
       end
 
@@ -358,7 +434,7 @@ module Rigor
         # them under one map post-resolution. Aliases live in their
         # own table.
         env.class_decls.key?(rbs_name) || env.class_alias_decls.key?(rbs_name)
-      rescue StandardError
+      rescue ::RBS::BaseError
         false
       end
     end

data/lib/rigor/environment.rb

@@ -41,7 +41,7 @@ module Rigor
       prism rbs
     ].freeze
 
-    attr_reader :class_registry, :rbs_loader
+    attr_reader :class_registry, :rbs_loader, :plugin_registry
 
     # @param class_registry [Rigor::Environment::ClassRegistry]
     # @param rbs_loader [Rigor::Environment::RbsLoader, nil] when nil the
@@ -50,9 +50,17 @@ module Rigor
     #   wires the shared core loader, which is itself lazy: requesting an
     #   environment instance does NOT load RBS until a method or class
     #   query actually consults the loader.
-    def initialize(class_registry: ClassRegistry.default, rbs_loader: nil)
+    # @param plugin_registry [Rigor::Plugin::Registry, nil] v0.1.1
+    #   Track 2 slice 7. The per-run plugin registry the
+    #   inference engine consults at call sites for plugin
+    #   `#flow_contribution_for` overrides. When nil (the
+    #   default), no plugin-level return-type contribution
+    #   participates — useful for tests, the `Environment.default`
+    #   facade, and analyses that don't load plugins.
+    def initialize(class_registry: ClassRegistry.default, rbs_loader: nil, plugin_registry: nil)
       @class_registry = class_registry
       @rbs_loader = rbs_loader
+      @plugin_registry = plugin_registry
       freeze
     end
 
@@ -82,7 +90,7 @@ module Rigor
       #   reflection artefacts) consult the cache. Pass `nil` (the
       #   default) to skip caching for this environment.
       # @return [Rigor::Environment]
-      def for_project(root: Dir.pwd, libraries: [], signature_paths: nil, cache_store: nil)
+      def for_project(root: Dir.pwd, libraries: [], signature_paths: nil, cache_store: nil, plugin_registry: nil)
         resolved_paths = signature_paths || default_signature_paths(root)
         merged_libraries = (DEFAULT_LIBRARIES + libraries.map(&:to_s)).uniq
         loader = RbsLoader.new(
@@ -90,7 +98,7 @@ module Rigor
           signature_paths: resolved_paths,
           cache_store: cache_store
         )
-        new(rbs_loader: loader)
+        new(rbs_loader: loader, plugin_registry: plugin_registry)
       end
 
       private

data/lib/rigor/flow_contribution/conflict.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Rigor
+  class FlowContribution
+    # Records a contradiction between two or more flow contributions
+    # detected during {Merger.merge}. Carried on {MergeResult#conflicts}
+    # so the analyzer / formatter can surface a `:contribution_merge`
+    # diagnostic per ADR-2 § "Plugin Contribution Merging".
+    #
+    # ADR-2 § "Plugin Contribution Merging" rules out first-wins /
+    # last-wins behaviour: when contributions conflict, both sources
+    # are reported and the merger falls back to the nearest non-
+    # conflicting higher-tier (or default) value for the affected
+    # `(target, edge, kind)` slot. The conflict object is the
+    # carrier of that report.
+    #
+    # Slice-3 conflict reasons:
+    #
+    # - `:return_type_collapse` — two return-type contributions
+    #   intersect to `bot`.
+    # - `:exceptional_disagreement` — two contributions assert
+    #   incompatible non-`nil` exceptional effects.
+    # - `:lower_tier_contradiction` — a lower-tier contribution
+    #   would weaken or contradict a higher-tier proof.
+    CONFLICT_VALID_REASONS = %i[
+      return_type_collapse
+      exceptional_disagreement
+      lower_tier_contradiction
+    ].freeze
+
+    Conflict = Data.define(:target, :edge, :kind, :reason, :provenances, :message) do
+      def initialize(target:, edge:, kind:, reason:, provenances:, message:) # rubocop:disable Metrics/ParameterLists
+        unless CONFLICT_VALID_REASONS.include?(reason)
+          raise ArgumentError,
+                "FlowContribution::Conflict reason must be one of " \
+                "#{CONFLICT_VALID_REASONS.inspect}, got #{reason.inspect}"
+        end
+
+        super(target: target, edge: edge, kind: kind, reason: reason,
+              provenances: provenances.dup.freeze, message: message.to_s.dup.freeze)
+      end
+
+      def to_h
+        {
+          "target" => target.to_s,
+          "edge" => edge.to_s,
+          "kind" => kind.to_s,
+          "reason" => reason.to_s,
+          "sources" => provenances.map { |p| p.respond_to?(:to_h) ? p.to_h : p.to_s },
+          "message" => message
+        }
+      end
+
+      # ADR-7 § "Slice 5-C" — converts the conflict into a
+      # `Rigor::Analysis::Diagnostic` for the run result.
+      # Carries `source_family: :contribution_merge` so the
+      # qualified-rule formatter (slice 5 formatter half,
+      # `ef730b2`) prefixes the rule id with
+      # `contribution_merge.` and the JSON output side-bands
+      # `source_family` + `rule` for plugin attribution.
+      #
+      # The `rule` identifier is the kebab-case form of the
+      # conflict reason (`return_type_collapse` →
+      # `return-type-collapse`, etc.) so the qualified rule
+      # reads `[contribution_merge.return-type-collapse]` in
+      # the standard text stream.
+      def to_diagnostic(path:, line:, column:, severity: :error)
+        require_relative "../analysis/diagnostic" unless defined?(Rigor::Analysis::Diagnostic)
+        Rigor::Analysis::Diagnostic.new(
+          path: path,
+          line: line,
+          column: column,
+          message: message,
+          severity: severity,
+          rule: reason.to_s.tr("_", "-"),
+          source_family: :contribution_merge
+        )
+      end
+    end
+  end
+end

data/lib/rigor/flow_contribution/element.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Rigor
+  class FlowContribution
+    # Tagged element flattening of a {FlowContribution} bundle —
+    # the analyzer-internal representation [ADR-2 § "Flow
+    # Contribution Bundle"](../../../docs/adr/2-extension-api.md)
+    # routes through the {Merger}.
+    #
+    # The flattening is **mechanical, deterministic, and round-
+    # trippable** with the bundle: every non-empty slot expands
+    # into one or more elements keyed by `(target, edge, kind)`,
+    # and an array of elements rebuilds an equivalent bundle when
+    # routed through `Merger.merge`.
+    #
+    # Plugin authors should not depend on the element shape — the
+    # bundle is the public contract; the element list is the
+    # implementation surface the merge policy operates over.
+    ELEMENT_VALID_EDGES = %i[normal truthy falsey post_return exceptional].freeze
+    ELEMENT_VALID_KINDS = %i[
+      return_type
+      truthy_fact
+      falsey_fact
+      post_return_fact
+      mutation
+      invalidation
+      exception
+      role
+    ].freeze
+
+    Element = Data.define(:target, :edge, :kind, :payload, :provenance) do
+      def initialize(target:, edge:, kind:, payload:, provenance:)
+        unless ELEMENT_VALID_EDGES.include?(edge)
+          raise ArgumentError,
+                "FlowContribution::Element edge must be one of " \
+                "#{ELEMENT_VALID_EDGES.inspect}, got #{edge.inspect}"
+        end
+
+        unless ELEMENT_VALID_KINDS.include?(kind)
+          raise ArgumentError,
+                "FlowContribution::Element kind must be one of " \
+                "#{ELEMENT_VALID_KINDS.inspect}, got #{kind.inspect}"
+        end
+
+        super
+      end
+
+      def merge_key
+        [target, edge, kind]
+      end
+    end
+  end
+end

data/lib/rigor/flow_contribution/fact.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Rigor
+  class FlowContribution
+    # Canonical slot payload for the four edge-aware fact slots
+    # (`truthy_facts`, `falsey_facts`, `post_return_facts`, plus
+    # the equivalent under `mutations` / `invalidations` /
+    # `role_conformance` once those carriers grow Fact-shaped
+    # variants).
+    #
+    # ADR-7 § "Slice 4-A" pins this object as the **single
+    # canonical translation target** for the four parallel
+    # contribution carriers the engine has carried so far:
+    #
+    # 1. Built-in narrowing rules' direct fact emission
+    #    (Inference::Narrowing#predicate_scopes).
+    # 2. RBS::Extended `predicate-if-*` directives
+    #    (`Rigor::RbsExtended::PredicateEffect`).
+    # 3. RBS::Extended `assert*` directives
+    #    (`Rigor::RbsExtended::AssertEffect`).
+    # 4. Future plugin contributions (slice 5 emission protocol).
+    #
+    # Each of those four carriers translates to / from Fact at
+    # its boundary; downstream of {Rigor::FlowContribution#to_element_list}
+    # and {Rigor::FlowContribution::Merger.merge}, every slot
+    # payload is a Fact (or a value that the merger compares by
+    # equality and never inspects). The typed `RbsExtended::*Effect`
+    # carriers stay internal to the parser side — they hold the
+    # source-text shape, but lose their identity at the
+    # `read_flow_contribution` boundary.
+    #
+    # ## Field set
+    #
+    # - `target_kind`: `:parameter` (call-site argument) or
+    #   `:self` (receiver). Future slices may extend the set
+    #   (`:local`, `:ivar`, `:result`); the merger is agnostic
+    #   to the concrete kinds and only requires equality.
+    # - `target_name`: a `Symbol`. For `:parameter` it's the
+    #   declared parameter name. For `:self` it is the literal
+    #   `:self` symbol so the field stays non-nil and the merge
+    #   key is well-defined.
+    # - `type`: a `Rigor::Type::*` (Nominal, Refined,
+    #   IntegerRange, Difference, …) the fact narrows the
+    #   target toward (when `negative` is false) or away from
+    #   (when `negative` is true).
+    # - `negative`: `true` for the `~T` negation form
+    #   (`predicate-if-true x is ~Integer`), `false` for the
+    #   plain positive form. Mirrors the `negative` field on
+    #   `PredicateEffect` / `AssertEffect`.
+    #
+    # The `target` accessor returns `:self` for self-targeted
+    # facts and `[:parameter, name]` otherwise — that's the
+    # value {Element#target} keys on, so two facts that narrow
+    # the same parameter from different contribution sources
+    # land in the same merge bucket.
+    FACT_VALID_TARGET_KINDS = %i[parameter self].freeze
+
+    Fact = Data.define(:target_kind, :target_name, :type, :negative) do
+      def initialize(target_kind:, target_name:, type:, negative: false)
+        unless FACT_VALID_TARGET_KINDS.include?(target_kind)
+          raise ArgumentError,
+                "FlowContribution::Fact target_kind must be one of " \
+                "#{FACT_VALID_TARGET_KINDS.inspect}, got #{target_kind.inspect}"
+        end
+
+        unless target_name.is_a?(Symbol)
+          raise ArgumentError,
+                "FlowContribution::Fact target_name must be a Symbol, got #{target_name.inspect}"
+        end
+
+        super
+      end
+
+      # Composite target identifier the merger keys on. `:self`
+      # for self-targeted facts; otherwise `[:parameter, name]`
+      # so two contributions that narrow the same parameter
+      # (regardless of source family) land in the same merge
+      # bucket.
+      def target
+        target_kind == :self ? :self : [target_kind, target_name]
+      end
+
+      def negative?
+        negative == true
+      end
+    end
+  end
+end

data/lib/rigor/flow_contribution/merge_result.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Rigor
+  class FlowContribution
+    # Result of folding any number of {FlowContribution} bundles
+    # through {Merger.merge}. Surfaces the merged content slot-by-
+    # slot, the ordered list of contributing provenances, and the
+    # {Conflict} list collected along the way.
+    #
+    # The merge result is a sibling shape of {FlowContribution} —
+    # the analyzer reads from it to drive narrowing / dispatch /
+    # diagnostics, and the formatter reads from it to surface
+    # plugin / RBS::Extended provenance. The shape is derived per
+    # ADR-2 § "Plugin Contribution Merging"; see
+    # [`docs/internal-spec/flow-contribution-merger.md`](../../../docs/internal-spec/flow-contribution-merger.md)
+    # for the slice-3 normative description.
+    class MergeResult
+      attr_reader :return_type, :truthy_facts, :falsey_facts, :post_return_facts,
+                  :mutations, :invalidations, :exceptional, :role_conformance,
+                  :provenances, :conflicts
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(return_type: nil, truthy_facts: [], falsey_facts: [],
+                     post_return_facts: [], mutations: [], invalidations: [],
+                     exceptional: nil, role_conformance: [],
+                     provenances: [], conflicts: [])
+        # rubocop:enable Metrics/ParameterLists
+        @return_type = return_type
+        @truthy_facts = truthy_facts.dup.freeze
+        @falsey_facts = falsey_facts.dup.freeze
+        @post_return_facts = post_return_facts.dup.freeze
+        @mutations = mutations.dup.freeze
+        @invalidations = invalidations.dup.freeze
+        @exceptional = exceptional
+        @role_conformance = role_conformance.dup.freeze
+        @provenances = provenances.dup.freeze
+        @conflicts = conflicts.dup.freeze
+        freeze
+      end
+
+      def conflict?
+        !@conflicts.empty?
+      end
+
+      def empty? # rubocop:disable Metrics/CyclomaticComplexity
+        @return_type.nil? && @truthy_facts.empty? && @falsey_facts.empty? &&
+          @post_return_facts.empty? && @mutations.empty? && @invalidations.empty? &&
+          @exceptional.nil? && @role_conformance.empty?
+      end
+
+      def to_h
+        {
+          "return_type" => return_type,
+          "truthy_facts" => truthy_facts,
+          "falsey_facts" => falsey_facts,
+          "post_return_facts" => post_return_facts,
+          "mutations" => mutations,
+          "invalidations" => invalidations,
+          "exceptional" => exceptional,
+          "role_conformance" => role_conformance,
+          "provenances" => provenances.map { |p| p.respond_to?(:to_h) ? p.to_h : p },
+          "conflicts" => conflicts.map(&:to_h)
+        }
+      end
+    end
+  end
+end