rigortype 0.3.3 → 0.3.5

data/lib/rigor/effects/unknown_label_check.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "unknown_label_report"
+
+module Rigor
+  module Effects
+    # Turns the declarations a run carries into `effect.unknown-label` findings (ADR-103 WD1 / WD14;
+    # #384). Pure: it reads envelopes and config values and answers value objects, never diagnostics
+    # and never the filesystem — positioning the finding is the caller's job, because only the caller
+    # knows whether a `virtual:` buffer has to be mapped back to the `.rb` the author wrote in.
+    #
+    # Two producers today, one shape:
+    #
+    # - {.for_envelopes} — every `%a{pure}` / `%a{rigor:v1:effect …}` the envelope scanner read, in
+    #   `.rbs` or through rbs-inline. One finding per (declaration, unrecognised token); a
+    #   `def self?.x` member declares two keys off ONE annotation, so findings are deduplicated by
+    #   where they were written rather than by which method they bind.
+    # - {.for_config} — a `.rigor.yml` label list: `effects.tolerated:`, `effects.labels:`, each
+    #   `envelopes[].effect` and each `attribution:` value. The key path is a parameter rather than a
+    #   literal precisely because there are four of them and each names a different place to edit.
+    module UnknownLabelCheck
+      # `location` is the `path:line` the declaration was written at, or nil for a config value —
+      # the caller resolves both. `spelling` is the author's own annotation text, which is also how a
+      # finding read out of a synthesized buffer is found again in the Ruby source.
+      Finding = Data.define(:token, :subject, :consequence, :location, :spelling, :report) do
+        def message = report.message(subject: subject, consequence: consequence)
+      end
+
+      ENVELOPE_CONSEQUENCE = "the annotation now bounds nothing"
+
+      module_function
+
+      # @param method_envelopes [Hash{String => Envelope}]
+      # @param class_envelopes [Hash{String => Envelope}]
+      # @param registry [Rigor::Effects::Registry]
+      # @return [Array<Finding>]
+      def for_envelopes(method_envelopes:, class_envelopes:, registry:)
+        seen = {}
+        declarations(method_envelopes, class_envelopes).each do |envelope|
+          envelope.unknown_labels.each do |token|
+            report = UnknownLabelReport.for(
+              token: token, registry: registry, siblings: envelope.declared_labels
+            )
+            next if report.nil?
+
+            seen[[envelope.location, envelope.spelling, token]] ||= envelope_finding(envelope, token, report)
+          end
+        end
+        seen.values
+      end
+
+      # @param labels [Array<String>] the list as written, in source order.
+      # @param key_path [String] the `.rigor.yml` key, for the message (`effects.tolerated`).
+      # @param consequence [String] what the degradation cost, for the message.
+      # @return [Array<Finding>]
+      def for_config(labels:, key_path:, consequence:, registry:)
+        tokens = Array(labels).map(&:to_s)
+        tokens.filter_map do |token|
+          report = UnknownLabelReport.for(token: token, registry: registry, siblings: tokens)
+          next if report.nil?
+
+          Finding.new(
+            token: token, subject: "`#{key_path}:` in .rigor.yml", consequence: consequence,
+            location: nil, spelling: nil, report: report
+          )
+        end
+      end
+
+      # Method-level declarations first, so a method that also carries a class-level bound reports
+      # against its own annotation rather than against the distributed one.
+      def declarations(method_envelopes, class_envelopes)
+        method_envelopes.values + class_envelopes.values
+      end
+
+      def envelope_finding(envelope, token, report)
+        Finding.new(
+          token: token, subject: "Effect envelope on #{envelope.owner_key}",
+          consequence: ENVELOPE_CONSEQUENCE, location: envelope.location,
+          spelling: envelope.spelling, report: report
+        )
+      end
+
+      private_class_method :declarations, :envelope_finding
+    end
+  end
+end

data/lib/rigor/effects/unknown_label_report.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "label_intent"
+
+module Rigor
+  module Effects
+    # One `effect.unknown-label` finding, rendered (ADR-103 WD1 / WD14; #384).
+    #
+    # It carries the spelling, the nearest recognised label and the retirement record, and knows how
+    # to say all three in one sentence. What it deliberately does NOT carry is where the label was
+    # written or what the surface was: an envelope in `.rbs`, an rbs-inline annotation in `.rb` and a
+    # `.rigor.yml` list all reduce to "a place named this label, and now it means nothing", so the
+    # caller supplies the `subject` and the `consequence` and this supplies the vocabulary judgment.
+    # That is the seam [#385](https://github.com/rigortype/rigor/issues/385)'s `envelopes[].effect`
+    # and `attribution:` values point at.
+    #
+    # {.for} answers `nil` unless {LabelIntent} says the spelling is evidently a label — the whole
+    # point of the diagnostic is that it fires where intent is evident and nowhere else.
+    class UnknownLabelReport < Data.define(:token, :suggestion, :retirement)
+      # @param token [String] the spelling as written.
+      # @param registry [Rigor::Effects::Registry, nil] the vocabulary after plugin load.
+      # @param siblings [Array<String>] the other tokens written alongside it.
+      # @return [UnknownLabelReport, nil]
+      def self.for(token:, registry:, siblings: [])
+        return nil unless LabelIntent.evident?(token, registry, siblings: siblings)
+
+        new(
+          token: token.to_s,
+          suggestion: registry.suggest(token.to_s),
+          retirement: Array(registry.retired(token.to_s)).map(&:to_s).freeze
+        )
+      end
+
+      # Whether the vocabulary once carried this spelling and moved it. A retirement outranks a
+      # nearest-neighbour guess: the registry KNOWS where this label went, so guessing would be
+      # strictly worse information.
+      def retired?
+        !retirement.nil? && !retirement.empty?
+      end
+
+      # The sentence a reader can act on. `subject` names the declaration ("Effect envelope on
+      # `Foo#bar`"), `consequence` says what the degradation cost ("the annotation now bounds
+      # nothing") — the fail-open reading stated out loud, because a silently-unbounded envelope is
+      # exactly what this diagnostic exists to make visible.
+      def message(subject:, consequence:)
+        "#{subject} names #{token}, which is not a known effect label#{qualifier}; #{consequence}."
+      end
+
+      private
+
+      def qualifier
+        return " (#{token} is retired; write #{retirement.join(' or ')} instead)" if retired?
+        return " (did you mean #{suggestion}?)" if suggestion
+
+        ""
+      end
+    end
+  end
+end

data/lib/rigor/effects.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "effects/label"
+require_relative "effects/label_set"
+require_relative "effects/registry"
+require_relative "effects/taint_cause"
+require_relative "effects/attribution"
+require_relative "effects/catalog"
+require_relative "effects/collector"
+require_relative "effects/config_envelopes"
+require_relative "effects/discharge"
+require_relative "effects/effect_table"
+require_relative "effects/envelope"
+require_relative "effects/envelope_check"
+require_relative "effects/envelope_index"
+require_relative "effects/file_collection"
+require_relative "effects/liskov_check"
+require_relative "effects/method_key"
+require_relative "effects/origin"
+require_relative "effects/propagator"
+require_relative "effects/summary"
+
+module Rigor
+  # The effect-label vocabulary (ADR-103; normative in
+  # `docs/type-specification/effect-labels.md`).
+  #
+  # Two layers live here. The label *language* — the grammar, the subsumption relation, the label
+  # sets a summary and an envelope are made of, the registry that says which spellings are
+  # recognised, and the closed enum of taint causes. And, on top of it, the observational machinery
+  # of #379: the {Collector} that records what the typer decided, the {Summary} / {FileCollection}
+  # values it produces, the built-in {Catalog}, and the {Propagator} that closes them into an
+  # {EffectTable}. On top of both sits the one thing here that DOES judge: an {Envelope} — an
+  # author-declared upper bound read off the project's RBS or written by convention in `.rigor.yml`
+  # ({ConfigEnvelopes}) — and the two checks that judge one: {EnvelopeCheck} compares a method against
+  # its own bound (`effect.envelope-exceeded`, #383 / #385) and {LiskovCheck} an override against the
+  # bound it inherits (`effect.liskov-widened`, #386). The same declarations are read a third way, which
+  # judges nothing: {EnvelopeIndex} resolves them per CALL SITE, so a caller reads what its callee
+  # promised as a `≤` bound. Beside them sit the project's policy
+  # surfaces: {Attribution} colours code Rigor never analysed, into the declared lane, and {Discharge}
+  # applies `effects.tolerated:` per origin at judgment time. The effect snapshot (#381) and the
+  # vocabulary diagnostic (#384) are their own slices.
+  #
+  # "Effect label", "effect summary" and "effect envelope" are trapped compounds in `CONTEXT.md`;
+  # bare "effect" still names `Rigor::FlowContribution`'s flow-effect bundle.
+  module Effects
+  end
+end

data/lib/rigor/environment/rbs_loader.rb

@@ -1256,6 +1256,40 @@ module Rigor
         end
       end
 
+      # ADR-103 WD6 / #386 — yields `[class name, RBS::AST::Members::MethodDefinition]` for every method
+      # member in the built environment that carries at least one annotation.
+      #
+      # The one reason this walk lives here rather than in its caller: `#env` is private, and it stays
+      # private. The effect-envelope reader needs the *annotations* a gem's shipped signatures and
+      # Rigor's bundled overlays declare — the accepted stratum of ADR-103 WD6, which discharges a call
+      # site's taint because the same trust is already extended to those files' types — and nothing more
+      # of the environment. Handing out the environment to get at them would trade a several-MB mutable
+      # object for a read the loader can perform itself.
+      #
+      # Nested declarations are not descended into: `RBS::Environment` already flattens a nested
+      # `class Foo::Bar` into its own `class_decls` entry, so a descent would key one member twice.
+      #
+      # Fail-soft, like every other query here: no environment (a build failure) yields nothing.
+      def each_annotated_method_member
+        environment = env
+        return if environment.nil?
+
+        environment.class_decls.each do |type_name, entry|
+          class_name = type_name.to_s.sub(/\A::/, "")
+          self.class.entry_declarations(entry).each do |decl|
+            members = decl.respond_to?(:members) ? decl.members : nil
+            next if members.nil?
+
+            members.each do |member|
+              next unless member.is_a?(::RBS::AST::Members::MethodDefinition)
+              next if member.annotations.nil? || member.annotations.empty?
+
+              yield class_name, member
+            end
+          end
+        end
+      end
+
       private
 
       # The `::`-stripped names of every class/module entry whose declarations ALL originated from the given

data/lib/rigor/environment.rb

@@ -311,11 +311,18 @@ module Rigor
       # activesupport, the Rack status table) can then require the analyzed project's own locked gems when
       # Rigor's host gem environment does not carry them — the standalone `gem install rigortype` case,
       # where activesupport is deliberately not a runtime dependency.
+      # The hand-off is a module ivar, which a non-main Ractor may not write (`Ractor::IsolationError`) —
+      # and every Ractor-pool worker builds its Environment inside its own Ractor, so an unguarded write
+      # killed the whole backend at `WorkerSession#initialize` (#414). The resolution is deterministic per
+      # configuration and `Runner`'s pre-passes already perform it on the main Ractor before the pool
+      # spawns, so a worker reads the value the main set (a frozen String, hence shareable) and skips the
+      # write. The local return value is unaffected, so the missing-gem constant index still gets its root
+      # even when the write is skipped.
       def resolve_target_bundle_root(bundle_path:, project_root:, auto_detect:)
         bundle_root = BundleSigDiscovery.resolve_bundle_path(
           bundle_path: bundle_path, project_root: project_root, auto_detect: auto_detect
         )&.to_s
-        Plugin::Isolation.target_bundle_root = bundle_root
+        Plugin::Isolation.target_bundle_root = bundle_root if Ractor.current == Ractor.main
         bundle_root
       end
 

data/lib/rigor/flow_contribution/element.rb

@@ -21,6 +21,7 @@ module Rigor
       invalidation
       exception
       role
+      effects
     ].freeze
 
     class Element < Data.define(:target, :edge, :kind, :payload, :provenance)

data/lib/rigor/flow_contribution/merge_result.rb

@@ -13,13 +13,13 @@ module Rigor
     # for the slice-3 normative description.
     class MergeResult
       attr_reader :return_type, :truthy_facts, :falsey_facts, :post_return_facts,
-                  :mutations, :invalidations, :exceptional, :role_conformance,
+                  :mutations, :invalidations, :exceptional, :role_conformance, :effects,
                   :provenances, :conflicts
 
       # rubocop:disable Metrics/ParameterLists
       def initialize(return_type: nil, truthy_facts: [], falsey_facts: [],
                      post_return_facts: [], mutations: [], invalidations: [],
-                     exceptional: nil, role_conformance: [],
+                     exceptional: nil, role_conformance: [], effects: nil,
                      provenances: [], conflicts: [])
         # rubocop:enable Metrics/ParameterLists
         @return_type = return_type
@@ -30,6 +30,7 @@ module Rigor
         @invalidations = invalidations.dup.freeze
         @exceptional = exceptional
         @role_conformance = role_conformance.dup.freeze
+        @effects = effects
         @provenances = provenances.dup.freeze
         @conflicts = conflicts.dup.freeze
         freeze
@@ -42,7 +43,7 @@ module Rigor
       def empty?
         @return_type.nil? && @truthy_facts.empty? && @falsey_facts.empty? &&
           @post_return_facts.empty? && @mutations.empty? && @invalidations.empty? &&
-          @exceptional.nil? && @role_conformance.empty?
+          @exceptional.nil? && @role_conformance.empty? && @effects.nil?
       end
 
       def to_h
@@ -55,6 +56,7 @@ module Rigor
           "invalidations" => invalidations,
           "exceptional" => exceptional,
           "role_conformance" => role_conformance,
+          "effects" => effects,
           "provenances" => provenances.map { |p| p.respond_to?(:to_h) ? p.to_h : p },
           "conflicts" => conflicts.map(&:to_h)
         }

data/lib/rigor/flow_contribution/merger.rb

@@ -99,6 +99,7 @@ module Rigor
           fold_effects(state, contribution)
           fold_exceptional(state, contribution, tier)
           fold_role_conformance(state, contribution)
+          fold_effect_labels(state, contribution)
         end
 
         def fold_return_type(state, contribution, tier)
@@ -182,6 +183,18 @@ module Rigor
           accumulate(state.role_conformance, contribution.role_conformance)
         end
 
+        # ADR-103 WD5 — the `effects` slot merges by UNION, unconditionally and across every authority
+        # tier. A label set is an upper bound on what a call does, and two sources that each name part of
+        # a footprint together name more of it; there is no reading under which one source's claim
+        # cancels another's, so there is no conflict to report either. `nil` ("says nothing") stays nil
+        # until some contribution speaks.
+        def fold_effect_labels(state, contribution)
+          incoming = contribution.effects
+          return if incoming.nil?
+
+          state.effects = state.effects.nil? ? incoming : state.effects.join(incoming)
+        end
+
         def accumulate(target, incoming)
           Array(incoming).each do |item|
             target << item unless target.include?(item)
@@ -217,7 +230,7 @@ module Rigor
       # {MergeResult} at the end via {#to_result}.
       class MergeState
         attr_accessor :return_type, :return_type_tier, :return_type_provenance,
-                      :exceptional, :exceptional_tier, :exceptional_provenance
+                      :exceptional, :exceptional_tier, :exceptional_provenance, :effects
         attr_reader :truthy_facts, :falsey_facts, :post_return_facts,
                     :mutations, :invalidations, :role_conformance,
                     :provenances, :conflicts
@@ -235,6 +248,7 @@ module Rigor
           @exceptional_tier = nil
           @exceptional_provenance = nil
           @role_conformance = []
+          @effects = nil
           @provenances = []
           @conflicts = []
         end
@@ -253,6 +267,7 @@ module Rigor
             invalidations: @invalidations,
             exceptional: @exceptional,
             role_conformance: @role_conformance,
+            effects: @effects,
             provenances: @provenances,
             conflicts: @conflicts
           )

data/lib/rigor/flow_contribution.rb

@@ -9,7 +9,7 @@ module Rigor
   # [ADR-2 § "Plugin Contribution Merging"](../../docs/adr/2-extension-api.md) rather than letting any one
   # source override another silently.
   #
-  # Eight content slots plus a {Provenance} block. A slot left as `nil` (or, for collection-shaped slots, an
+  # Nine content slots plus a {Provenance} block. A slot left as `nil` (or, for collection-shaped slots, an
   # empty collection) means the contribution does not assert anything in that dimension; the merge policy
   # treats it as absent.
   #
@@ -38,8 +38,15 @@ module Rigor
       invalidations
       exceptional
       role_conformance
+      effects
     ].freeze
 
+    # `effects` is scalar-shaped like `return_type` and `exceptional`: only `nil` means "asserts
+    # nothing". An EMPTY {Rigor::Effects::LabelSet} is the positive claim that the call performs no
+    # effects — the reading of `%a{pure}` — so it must not be mistaken for an unset slot the way an
+    # empty fact Array is.
+    SCALAR_SLOTS = %i[return_type exceptional effects].freeze
+
     attr_reader(*SLOT_NAMES, :provenance)
 
     # @param return_type [Object, nil] normal-edge return type. Use `nil` when the contribution does not
@@ -54,12 +61,17 @@ module Rigor
     #   imply.
     # @param exceptional [Object, nil] non-returning, raising, or unreachable effect.
     # @param role_conformance [Array, nil] capability-role conformance facts the contribution provides.
+    # @param effects [Rigor::Effects::LabelSet, nil] ADR-103 WD5 — the effect labels this call edge
+    #   attributes to its callee, as an upper bound. `nil` means "says nothing about effects", which is
+    #   NOT the same as the empty set (which asserts the call performs none). Merged by union, the
+    #   conservative direction: two sources that each name part of a call's footprint together name
+    #   more of it, and neither can shrink the other's claim.
     # @param provenance [Provenance] source-family, plugin-id, node, and cache-descriptor metadata. Defaults
     #   to `Provenance.builtin`.
     # rubocop:disable Metrics/ParameterLists
     def initialize(return_type: nil, truthy_facts: nil, falsey_facts: nil,
                    post_return_facts: nil, mutations: nil, invalidations: nil,
-                   exceptional: nil, role_conformance: nil,
+                   exceptional: nil, role_conformance: nil, effects: nil,
                    provenance: Provenance.builtin)
       # rubocop:enable Metrics/ParameterLists
       @return_type = return_type
@@ -70,6 +82,7 @@ module Rigor
       @invalidations = freeze_collection(invalidations)
       @exceptional = exceptional
       @role_conformance = freeze_collection(role_conformance)
+      @effects = effects
       @provenance = provenance
       freeze
     end
@@ -77,7 +90,7 @@ module Rigor
     # @return [Boolean] true when every content slot is unset (nil or an empty collection). Provenance does
     #   not count toward emptiness — an empty bundle still carries source attribution.
     def empty?
-      SLOT_NAMES.all? { |slot| slot_empty?(public_send(slot)) }
+      SLOT_NAMES.all? { |slot| slot_empty?(slot, public_send(slot)) }
     end
 
     def to_h
@@ -102,6 +115,7 @@ module Rigor
     # | invalidations       | normal        | invalidation        | (per-fact target)       |
     # | exceptional         | exceptional   | exception           | :raise                  |
     # | role_conformance    | normal        | role                | (per-role target)       |
+    # | effects             | normal        | effects             | :effects                |
     #
     # @return [Array<Element>]
     def to_element_list # rubocop:disable Metrics/AbcSize
@@ -116,6 +130,7 @@ module Rigor
       Array(invalidations).each { |i| elements << element_for(fact_target(i), :normal, :invalidation, i) }
       elements << element_for(:raise, :exceptional, :exception, exceptional) unless exceptional.nil?
       Array(role_conformance).each { |r| elements << element_for(fact_target(r), :normal, :role, r) }
+      elements << element_for(:effects, :normal, :effects, effects) unless effects.nil?
       elements.freeze
     end
 
@@ -149,8 +164,9 @@ module Rigor
       value.dup.freeze
     end
 
-    def slot_empty?(value)
+    def slot_empty?(slot, value)
       return true if value.nil?
+      return false if SCALAR_SLOTS.include?(slot)
       return value.empty? if value.respond_to?(:empty?)
 
       false

data/lib/rigor/inference/expression_typer.rb

@@ -13,6 +13,7 @@ require_relative "body_fixpoint"
 require_relative "budget_trace"
 require_relative "dynamic_origin"
 require_relative "origin_lookup"
+require_relative "../effects/collector"
 require_relative "fallback"
 require_relative "flow_tracer"
 require_relative "indexed_narrowing"
@@ -1134,6 +1135,11 @@ module Rigor
         arg_types = call_arg_types(node)
         block_type = block_return_type_for(node, receiver, arg_types)
 
+        # ADR-103 WD13 — the effect collector's one hot-path site. Purely observational: it reads the
+        # receiver type the typer has just computed and the `dynamic_origins` cause already recorded, and
+        # asks nothing further of dispatch. Off (the default) this is one integer read.
+        Effects::Collector.record_call(node, receiver, scope) if Effects::Collector.active?
+
         local_def_result = try_local_def_dispatch(node, receiver, arg_types)
         return local_def_result if local_def_result
 
@@ -1181,11 +1187,19 @@ module Rigor
         # semantic outcome, not a fail-soft compromise, so it MUST NOT record a tracer event.
         return inherit_receiver_origin(node) if receiver.is_a?(Type::Dynamic)
 
-        # ADR-24 slice 4a — this is the engine choke-point where an implicit-self call has exhausted every
-        # resolution tier (RBS dispatch + user-class ancestor walk) and falls through to `Dynamic[top]`. When
-        # the slice-4 recorder is active, capture the miss so a later slice's closed-class gate can flag it.
-        # Off by default: `active?` is a plain integer read.
+        unresolved_call_result(node, receiver)
+      end
+
+      # The engine choke-point where a call has exhausted every resolution tier (RBS dispatch + user-class
+      # ancestor walk) and falls through to `Dynamic[top]`. Two observational recorders read it, both a
+      # plain integer read when inactive, and neither changes the answer:
+      #
+      # - ADR-24 slice 4a captures an implicit-self miss so a later slice's closed-class gate can flag it;
+      # - ADR-103 WD13 retracts the effect collector's optimistic `resolved: true`, which is what separates
+      #   an implicit-self call the closed world has no definition for from an ordinary inherited one.
+      def unresolved_call_result(node, receiver)
         record_unresolved_self_call(node, receiver) if Analysis::SelfCallResolutionRecorder.active?
+        Effects::Collector.record_unresolved(node, scope.source_path) if Effects::Collector.active?
 
         fallback_for(node, family: :prism)
       end