rigortype 0.1.3 → 0.1.4

data/lib/rigor/rbs_extended/reporter.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Rigor
+  module RbsExtended
+    # ADR-13 slice 3b — per-run accumulator for `RBS::Extended`
+    # diagnostic events that the parser / resolver cannot surface
+    # at the point of failure (the parsers are fail-soft, returning
+    # `nil` so call sites fall back to the RBS-declared type).
+    #
+    # Owns two event streams:
+    #
+    # - `#unresolved_payloads` — `rigor:v1:*` directive payloads
+    #   the resolver could not turn into a {Rigor::Type}. Surface
+    #   as `dynamic.rbs-extended.unresolved` `:info` diagnostics.
+    # - `#lossy_projections` — shape-projection type functions
+    #   (`pick_of` / `omit_of` / `partial_of` / `required_of` /
+    #   `readonly_of`) applied to a carrier that does not preserve
+    #   shape information (anything other than `Type::HashShape`
+    #   / `Type::Tuple`). Surface as
+    #   `dynamic.shape.lossy-projection` `:info` diagnostics.
+    #
+    # Mutable through the run; consumed once by
+    # {Rigor::Analysis::Runner} at end-of-run. Each event is
+    # deduplicated by `(payload, source_location)` for unresolved
+    # and `(head, source_location)` for lossy-projection so a
+    # single annotation read from many call sites yields one
+    # diagnostic.
+    #
+    # The reporter is intentionally thread-safe via a coarse
+    # `Mutex` because the inference engine may read the same
+    # method definition from multiple files in parallel; the
+    # critical sections are short (Array#include? + Array#<<) so
+    # the lock contention is negligible.
+    class Reporter
+      UnresolvedEntry = Data.define(:payload, :source_location)
+      LossyProjectionEntry = Data.define(:head, :source_location)
+
+      def initialize
+        @unresolved_payloads = []
+        @lossy_projections = []
+        @mutex = Mutex.new
+      end
+
+      # @return [Array<UnresolvedEntry>] frozen snapshot of the
+      #   accumulated unresolved-payload events.
+      def unresolved_payloads
+        @mutex.synchronize { @unresolved_payloads.dup.freeze }
+      end
+
+      # @return [Array<LossyProjectionEntry>] frozen snapshot of
+      #   the accumulated lossy-projection events.
+      def lossy_projections
+        @mutex.synchronize { @lossy_projections.dup.freeze }
+      end
+
+      # Records a `dynamic.rbs-extended.unresolved` event. The
+      # `source_location` argument is the {RBS::Location} attached
+      # to the source annotation (or `nil` when the caller doesn't
+      # have one — the diagnostic falls back to a generic
+      # location in that case).
+      def record_unresolved(payload:, source_location: nil)
+        entry = UnresolvedEntry.new(payload: payload.to_s, source_location: source_location)
+        @mutex.synchronize do
+          return if @unresolved_payloads.include?(entry)
+
+          @unresolved_payloads << entry
+        end
+      end
+
+      # Records a `dynamic.shape.lossy-projection` event for one
+      # of the five shape-projection heads. `head` MUST be a
+      # String (`"pick_of"`, `"omit_of"`, …); the diagnostic
+      # message identifies which projection degraded.
+      def record_lossy_projection(head:, source_location: nil)
+        entry = LossyProjectionEntry.new(head: head.to_s, source_location: source_location)
+        @mutex.synchronize do
+          return if @lossy_projections.include?(entry)
+
+          @lossy_projections << entry
+        end
+      end
+
+      # True when no events have accumulated. Used by callers
+      # that want to skip the diagnostic-emission pass entirely
+      # on the common no-event path.
+      def empty?
+        @mutex.synchronize { @unresolved_payloads.empty? && @lossy_projections.empty? }
+      end
+    end
+  end
+end

data/lib/rigor/rbs_extended.rb

@@ -3,6 +3,7 @@
 require_relative "type"
 require_relative "builtins/imported_refinements"
 require_relative "flow_contribution"
+require_relative "rbs_extended/reporter"
 
 module Rigor
   # Slice 7 phase 15 — first-preview reader for the
@@ -59,7 +60,7 @@ module Rigor
     # current local type; `class_name` is then nil and
     # `negative` is false (refinement-form directives do not
     # support `~T` negation in v0.0.4).
-    PredicateEffect = Data.define(:edge, :target_kind, :target_name, :class_name, :negative, :refinement_type) do
+    class PredicateEffect < Data.define(:edge, :target_kind, :target_name, :class_name, :negative, :refinement_type)
       def truthy_only? = edge == :truthy_only
       def falsey_only? = edge == :falsey_only
       def negative? = negative == true
@@ -98,7 +99,7 @@ module Rigor
     #
     # `negative` mirrors `PredicateEffect`: true when the
     # directive uses `~ClassName` syntax.
-    AssertEffect = Data.define(:condition, :target_kind, :target_name, :class_name, :negative, :refinement_type) do
+    class AssertEffect < Data.define(:condition, :target_kind, :target_name, :class_name, :negative, :refinement_type)
       def always? = condition == :always
       def if_truthy_return? = condition == :if_truthy_return
       def if_falsey_return? = condition == :if_falsey_return
@@ -129,15 +130,30 @@ module Rigor
     # `rigor:v1:` directives are dropped. Returns an empty
     # array (NEVER `nil`) for a method with no recognised
     # annotations so callers can iterate unconditionally.
-    def read_predicate_effects(method_def)
+    #
+    # @param environment [Rigor::Environment, nil] ADR-13 slice
+    #   3b. When provided, threads the plugin-supplied
+    #   `name_scope:` and the per-run reporter through the
+    #   annotation-parse path. `nil` (default) preserves the
+    #   pre-slice-3b behaviour — no plugin resolvers consulted
+    #   and no diagnostics accumulated.
+    def read_predicate_effects(method_def, environment: nil)
       return [] if method_def.nil?
 
       annotations = method_def.annotations
       return [] if annotations.nil? || annotations.empty?
 
+      name_scope = environment&.name_scope
+      reporter = environment&.rbs_extended_reporter
+
       effects = []
       annotations.each do |annotation|
-        effect = parse_predicate_annotation(annotation.string)
+        effect = parse_predicate_annotation(
+          annotation.string,
+          name_scope: name_scope,
+          reporter: reporter,
+          source_location: annotation.location
+        )
         effects << effect if effect
       end
       effects.uniq
@@ -168,7 +184,7 @@ module Rigor
     /x
     private_constant :PREDICATE_DIRECTIVE_PATTERN
 
-    def parse_predicate_annotation(string)
+    def parse_predicate_annotation(string, name_scope: nil, reporter: nil, source_location: nil)
       match = PREDICATE_DIRECTIVE_PATTERN.match(string)
       return nil if match.nil?
 
@@ -176,8 +192,16 @@ module Rigor
       target = match[:target].to_s
       edge = directive == "predicate-if-true" ? :truthy_only : :falsey_only
       target_kind, target_name = target_fields(target)
-      class_name, refinement_type, negative = resolve_directive_rhs(match)
-      return nil if class_name.nil? && refinement_type.nil?
+      class_name, refinement_type, negative = resolve_directive_rhs(
+        match,
+        name_scope: name_scope,
+        reporter: reporter,
+        source_location: source_location
+      )
+      if class_name.nil? && refinement_type.nil?
+        record_unresolved(reporter, string, source_location)
+        return nil
+      end
 
       PredicateEffect.new(
         edge: edge,
@@ -194,15 +218,26 @@ module Rigor
     # `RBS::Definition::Method#annotations`. Returns an empty
     # array when no recognised assertion directives are
     # attached to the method.
-    def read_assert_effects(method_def)
+    #
+    # See {.read_predicate_effects} for the `environment:`
+    # keyword contract.
+    def read_assert_effects(method_def, environment: nil)
       return [] if method_def.nil?
 
       annotations = method_def.annotations
       return [] if annotations.nil? || annotations.empty?
 
+      name_scope = environment&.name_scope
+      reporter = environment&.rbs_extended_reporter
+
       effects = []
       annotations.each do |annotation|
-        effect = parse_assert_annotation(annotation.string)
+        effect = parse_assert_annotation(
+          annotation.string,
+          name_scope: name_scope,
+          reporter: reporter,
+          source_location: annotation.location
+        )
         effects << effect if effect
       end
       effects.uniq
@@ -232,7 +267,7 @@ module Rigor
     }.freeze
     private_constant :ASSERT_CONDITIONS
 
-    def parse_assert_annotation(string)
+    def parse_assert_annotation(string, name_scope: nil, reporter: nil, source_location: nil)
       match = ASSERT_DIRECTIVE_PATTERN.match(string)
       return nil if match.nil?
 
@@ -242,8 +277,16 @@ module Rigor
 
       target = match[:target].to_s
       target_kind, target_name = target_fields(target)
-      class_name, refinement_type, negative = resolve_directive_rhs(match)
-      return nil if class_name.nil? && refinement_type.nil?
+      class_name, refinement_type, negative = resolve_directive_rhs(
+        match,
+        name_scope: name_scope,
+        reporter: reporter,
+        source_location: source_location
+      )
+      if class_name.nil? && refinement_type.nil?
+        record_unresolved(reporter, string, source_location)
+        return nil
+      end
 
       AssertEffect.new(
         condition: condition,
@@ -273,7 +316,7 @@ module Rigor
     # - Refinement payload unparseable: returns
     #   `[nil, nil, false]` so callers can drop the directive
     #   silently (fail-soft policy).
-    def resolve_directive_rhs(match)
+    def resolve_directive_rhs(match, name_scope: nil, reporter: nil, source_location: nil)
       negative = match[:negation].to_s == "~"
       class_capture = match[:class_name]
       return [class_capture.to_s.sub(/\A::/, ""), nil, negative] if class_capture
@@ -281,7 +324,12 @@ module Rigor
       refinement_capture = match[:refinement]
       return [nil, nil, false] if refinement_capture.nil?
 
-      type = Builtins::ImportedRefinements.parse(refinement_capture)
+      type = Builtins::ImportedRefinements.parse(
+        refinement_capture,
+        name_scope: name_scope,
+        reporter: reporter,
+        source_location: source_location
+      )
       return [nil, nil, false] if type.nil?
 
       [nil, type, negative]
@@ -326,16 +374,25 @@ module Rigor
     # - the directive's payload names a refinement not
     #   registered in `Rigor::Builtins::ImportedRefinements`
     #   (the analyzer prefers a silent miss over crashing on a
-    #   typo; future slices MAY surface the miss as a
-    #   `:warning` self-diagnostic).
-    def read_return_type_override(method_def)
+    #   typo; ADR-13 slice 3b surfaces the miss as a
+    #   `dynamic.rbs-extended.unresolved` `:info` diagnostic when
+    #   an `environment:` is supplied).
+    def read_return_type_override(method_def, environment: nil)
       return nil if method_def.nil?
 
       annotations = method_def.annotations
       return nil if annotations.nil? || annotations.empty?
 
+      name_scope = environment&.name_scope
+      reporter = environment&.rbs_extended_reporter
+
       annotations.each do |annotation|
-        type = parse_return_type_override(annotation.string)
+        type = parse_return_type_override(
+          annotation.string,
+          name_scope: name_scope,
+          reporter: reporter,
+          source_location: annotation.location
+        )
         return type if type
       end
       nil
@@ -360,11 +417,18 @@ module Rigor
     /x
     private_constant :RETURN_DIRECTIVE_PATTERN
 
-    def parse_return_type_override(string)
+    def parse_return_type_override(string, name_scope: nil, reporter: nil, source_location: nil)
       match = RETURN_DIRECTIVE_PATTERN.match(string)
       return nil if match.nil?
 
-      Builtins::ImportedRefinements.parse(match[:payload])
+      type = Builtins::ImportedRefinements.parse(
+        match[:payload],
+        name_scope: name_scope,
+        reporter: reporter,
+        source_location: source_location
+      )
+      record_unresolved(reporter, string, source_location) if type.nil?
+      type
     end
 
     # Returned for `rigor:v1:param: <name> <refinement>`. The
@@ -397,13 +461,23 @@ module Rigor
     # purposes; passing a too-wide `Nominal[String]` argument
     # is flagged as an argument-type mismatch at the call
     # site.
-    def read_param_type_overrides(method_def)
+    def read_param_type_overrides(method_def, environment: nil)
       return [] if method_def.nil?
 
       annotations = method_def.annotations
       return [] if annotations.nil? || annotations.empty?
 
-      annotations.filter_map { |annotation| parse_param_annotation(annotation.string) }
+      name_scope = environment&.name_scope
+      reporter = environment&.rbs_extended_reporter
+
+      annotations.filter_map do |annotation|
+        parse_param_annotation(
+          annotation.string,
+          name_scope: name_scope,
+          reporter: reporter,
+          source_location: annotation.location
+        )
+      end
     end
 
     # Convenience reader for call sites that want to look up
@@ -411,8 +485,10 @@ module Rigor
     # Hash<Symbol, Rigor::Type>; missing keys mean "use the
     # RBS-declared type". Callers MUST treat the hash as
     # read-only.
-    def param_type_override_map(method_def)
-      read_param_type_overrides(method_def).to_h { |o| [o.param_name, o.type] }.freeze
+    def param_type_override_map(method_def, environment: nil)
+      read_param_type_overrides(method_def, environment: environment)
+        .to_h { |o| [o.param_name, o.type] }
+        .freeze
     end
 
     # The `is` glue word is optional so authors can write
@@ -434,12 +510,20 @@ module Rigor
     /x
     private_constant :PARAM_DIRECTIVE_PATTERN
 
-    def parse_param_annotation(string)
+    def parse_param_annotation(string, name_scope: nil, reporter: nil, source_location: nil)
       match = PARAM_DIRECTIVE_PATTERN.match(string)
       return nil if match.nil?
 
-      type = Builtins::ImportedRefinements.parse(match[:payload])
-      return nil if type.nil?
+      type = Builtins::ImportedRefinements.parse(
+        match[:payload],
+        name_scope: name_scope,
+        reporter: reporter,
+        source_location: source_location
+      )
+      if type.nil?
+        record_unresolved(reporter, string, source_location)
+        return nil
+      end
 
       ParamOverride.new(param_name: match[:param].to_sym, type: type)
     end
@@ -477,18 +561,21 @@ module Rigor
     # Returns `nil` when the method carries no recognised
     # contribution directives (callers can skip the merge step
     # without iterating an empty bundle).
-    def read_flow_contribution(method_def)
+    #
+    # See {.read_predicate_effects} for the `environment:`
+    # keyword contract.
+    def read_flow_contribution(method_def, environment: nil)
       return nil if method_def.nil?
 
-      predicate_effects = read_predicate_effects(method_def)
-      assert_effects = read_assert_effects(method_def)
-      return_override = read_return_type_override(method_def)
+      predicate_effects = read_predicate_effects(method_def, environment: environment)
+      assert_effects = read_assert_effects(method_def, environment: environment)
+      return_override = read_return_type_override(method_def, environment: environment)
       return nil if predicate_effects.empty? && assert_effects.empty? && return_override.nil?
 
       build_flow_contribution(predicate_effects, assert_effects, return_override)
     end
 
-    def build_flow_contribution(predicate_effects, assert_effects, return_override) # rubocop:disable Metrics/CyclomaticComplexity
+    def build_flow_contribution(predicate_effects, assert_effects, return_override)
       truthy = predicate_effects.select(&:truthy_only?).map(&:to_fact)
       falsey = predicate_effects.select(&:falsey_only?).map(&:to_fact)
       post_return = []
@@ -513,5 +600,17 @@ module Rigor
     def nilable_slot(facts)
       facts.empty? ? nil : facts
     end
+
+    # ADR-13 slice 3b — guards every reporter call so the
+    # in-RbsExtended-module call sites can record events
+    # uniformly without nil-checking each time. When the
+    # reporter is nil (the v0.1.0 → v0.1.3 default for call
+    # sites that do not yet thread `environment:`), the call is
+    # a no-op and the parser stays fail-soft.
+    def record_unresolved(reporter, payload, source_location)
+      return if reporter.nil?
+
+      reporter.record_unresolved(payload: payload, source_location: source_location)
+    end
   end
 end

data/lib/rigor/scope.rb

@@ -20,7 +20,8 @@ module Rigor
                 :ivars, :cvars, :globals,
                 :class_ivars, :class_cvars, :program_globals,
                 :discovered_classes, :in_source_constants, :discovered_methods,
-                :discovered_def_nodes, :discovered_method_visibilities
+                :discovered_def_nodes, :discovered_method_visibilities,
+                :source_path
 
     EMPTY_DECLARED_TYPES = {}.compare_by_identity.freeze
     EMPTY_VAR_BINDINGS = {}.freeze
@@ -28,8 +29,9 @@ module Rigor
     private_constant :EMPTY_DECLARED_TYPES, :EMPTY_VAR_BINDINGS, :EMPTY_CLASS_BINDINGS
 
     class << self
-      def empty(environment: Environment.default)
-        new(environment: environment, locals: {}.freeze, fact_store: Analysis::FactStore.empty)
+      def empty(environment: Environment.default, source_path: nil)
+        new(environment: environment, locals: {}.freeze,
+            fact_store: Analysis::FactStore.empty, source_path: source_path)
       end
     end
 
@@ -48,7 +50,8 @@ module Rigor
       in_source_constants: EMPTY_VAR_BINDINGS,
       discovered_methods: EMPTY_CLASS_BINDINGS,
       discovered_def_nodes: EMPTY_CLASS_BINDINGS,
-      discovered_method_visibilities: EMPTY_CLASS_BINDINGS
+      discovered_method_visibilities: EMPTY_CLASS_BINDINGS,
+      source_path: nil
     )
       @environment = environment
       @locals = locals
@@ -66,6 +69,7 @@ module Rigor
       @discovered_methods = discovered_methods
       @discovered_def_nodes = discovered_def_nodes
       @discovered_method_visibilities = discovered_method_visibilities
+      @source_path = source_path
       freeze
     end
 
@@ -92,6 +96,16 @@ module Rigor
       rebuild(self_type: type)
     end
 
+    # ADR-11 per-call-site assertion gating prerequisite. The
+    # analyzer's per-file boundary stamps the current source
+    # file's path onto the seed scope; nested rebuilds carry
+    # the value through so plugin hooks like
+    # `flow_contribution_for` can resolve "which file does
+    # this call site belong to?" without thread-locals.
+    def with_source_path(path)
+      rebuild(source_path: path)
+    end
+
     # Slice A-declarations. Returns a scope that carries an
     # identity-comparing Hash of `Prism::Node => Rigor::Type`
     # overrides. `ExpressionTyper#type_of(node)` MUST consult
@@ -333,7 +347,7 @@ module Rigor
       build_joined_scope(joined_locals, joined_ivars, joined_cvars, joined_globals, other)
     end
 
-    def ==(other) # rubocop:disable Metrics/CyclomaticComplexity
+    def ==(other)
       other.is_a?(Scope) &&
         environment.equal?(other.environment) &&
         @locals == other.locals &&
@@ -357,7 +371,8 @@ module Rigor
       class_ivars: @class_ivars, class_cvars: @class_cvars, program_globals: @program_globals,
       discovered_classes: @discovered_classes, in_source_constants: @in_source_constants,
       discovered_methods: @discovered_methods, discovered_def_nodes: @discovered_def_nodes,
-      discovered_method_visibilities: @discovered_method_visibilities
+      discovered_method_visibilities: @discovered_method_visibilities,
+      source_path: @source_path
     )
       self.class.new(
         environment: environment, locals: locals,
@@ -370,7 +385,8 @@ module Rigor
         in_source_constants: in_source_constants,
         discovered_methods: discovered_methods,
         discovered_def_nodes: discovered_def_nodes,
-        discovered_method_visibilities: discovered_method_visibilities
+        discovered_method_visibilities: discovered_method_visibilities,
+        source_path: source_path
       )
     end
 
@@ -396,7 +412,8 @@ module Rigor
         in_source_constants: in_source_constants,
         discovered_methods: discovered_methods,
         discovered_def_nodes: discovered_def_nodes,
-        discovered_method_visibilities: discovered_method_visibilities
+        discovered_method_visibilities: discovered_method_visibilities,
+        source_path: source_path
       )
     end
   end

data/lib/rigor/sig_gen/classification.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Rigor
+  module SigGen
+    # The five classifications a candidate method falls into
+    # after the generator has compared the inferred return
+    # type against the project's existing RBS.
+    #
+    # The strings are the diagnostic-family identifiers ADR-14
+    # reserves under `sig.*`; the MVP carries them as plain
+    # symbols on the method candidate and renders the matching
+    # identifier in JSON / text output. They are added to the
+    # diagnostic family hierarchy in `docs/type-specification/
+    # diagnostic-policy.md` even though slice 1 does not yet
+    # emit them as diagnostics.
+    module Classification
+      NEW_FILE = :new_file
+      NEW_METHOD = :new_method
+      TIGHTER_RETURN = :tighter_return
+      EQUIVALENT = :equivalent
+      SKIPPED = :skipped
+
+      DIAGNOSTIC_IDS = {
+        NEW_FILE => "sig.generated.new-file",
+        NEW_METHOD => "sig.generated.new-method",
+        TIGHTER_RETURN => "sig.generated.tighter-return"
+      }.freeze
+
+      SKIP_DIAGNOSTIC_IDS = {
+        complex_shape: "sig.skipped.complex-shape",
+        user_authored: "sig.skipped.user-authored",
+        untyped_return: "sig.skipped.untyped-return"
+      }.freeze
+    end
+  end
+end