rigortype 0.3.9 → 0.4.0

data/lib/rigor/effects/scanner.rb

@@ -4,7 +4,9 @@ require "prism"
 
 require_relative "../source/constant_path"
 require_relative "../source/node_children"
+require_relative "ancestry_recorder"
 require_relative "attribution"
+require_relative "definition_context"
 require_relative "envelope_index"
 require_relative "file_collection"
 require_relative "local_ownership"
@@ -13,6 +15,7 @@ require_relative "framework_units"
 require_relative "plugin_facts"
 require_relative "summary"
 require_relative "unit_scan"
+require_relative "visibility"
 
 module Rigor
   module Effects
@@ -21,8 +24,10 @@ module Rigor
     # The scanner owns **identity** — which effect units the file defines and what each is keyed as — and
     # delegates each unit's body to {UnitScan}. Keys follow the existing symbol tables (ADR-103 WD14):
     # `Class#m` for an instance method, `Class.m` for a singleton one, and `<toplevel>#m` for a `def`
-    # outside any class body. Reopenings in one file join here; reopenings across files join when the
-    # runner merges the collections.
+    # outside any class body. The side is the one Ruby defines the method on, which the enclosing method
+    # does not decide: {DefinitionContext} carries it down the walk, and a definition it cannot place is
+    # no unit. Reopenings in one file join here; reopenings across files join when the runner merges the
+    # collections.
     #
     # Three kinds of unit exist beyond a plain `def`:
     #
@@ -30,7 +35,9 @@ module Rigor
     #   skip it, so this is the minimal extension WD14 calls for, made here rather than in `ScopeIndexer`
     #   because nothing outside effects needs it yet.
     # - `attr_reader` / `attr_writer` / `attr_accessor` — synthesised: a reader is ∅, a writer is
-    #   `mutate.self`. Without them a caller's edge into an accessor would read as unresolved.
+    #   `mutate.self` (`mutate.static` where `self` is the singleton class, since it writes the class
+    #   object's ivar).
+    #   Without them a caller's edge into an accessor would read as unresolved.
     # - a nested `def` — its own unit under the same class, never contained in the enclosing method.
     #
     # **This walk exists only when collection is on.** ADR-103 WD13 prefers riding `ScopeIndexer`'s
@@ -47,77 +54,121 @@ module Rigor
       # its own that no slice models yet.
       DECLARATION_MACROS = %i[include prepend attr_reader attr_writer attr_accessor define_method].to_set.freeze
 
-      MUTATE_SELF = LabelSet.new(["mutate.self"])
-      private_constant :MUTATE_SELF
-
       # A synthesised writer's summary is the same value at every `attr_accessor` in the project, so it is
-      # built once rather than per accessor.
-      WRITER_SUMMARY = Summary.new(bundles: { Origin.construct("attr-writer") => MUTATE_SELF })
-      private_constant :WRITER_SUMMARY
-
+      # built once rather than per accessor. A singleton writer sets an ivar on the class object, and is
+      # labelled as an ivar write in a body that runs on a class is.
+      WRITER_SUMMARY = Summary.new(bundles: { Origin.construct("attr-writer") => UnitScan::MUTATE_SELF })
+      SINGLETON_WRITER_SUMMARY = Summary.new(bundles: { Origin.construct("attr-writer") => UnitScan::MUTATE_STATIC })
+      private_constant :WRITER_SUMMARY, :SINGLETON_WRITER_SUMMARY
+
+      # Every argument is one collection input the scan reads; a context object would move the same list
+      # one call further out.
+      # rubocop:disable Metrics/ParameterLists
       def self.scan(root:, path:, calls:, attribution: Attribution.empty, envelopes: EnvelopeIndex.empty,
-                    plugin_facts: PluginFacts.empty)
+                    plugin_facts: PluginFacts.empty, unit_key: nil, unit_owner: nil)
         new(path: path, calls: calls, attribution: attribution, envelopes: envelopes,
-            plugin_facts: plugin_facts).scan(root)
+            plugin_facts: plugin_facts, unit_key: unit_key, unit_owner: unit_owner).scan(root)
       end
 
       def initialize(path:, calls:, attribution: Attribution.empty, envelopes: EnvelopeIndex.empty,
-                     plugin_facts: PluginFacts.empty)
+                     plugin_facts: PluginFacts.empty, unit_key: nil, unit_owner: nil)
+        # rubocop:enable Metrics/ParameterLists
         @path = path
+        # #392 — a template unit: the WHOLE file is one effect unit, keyed `view:<logical_name>`. A
+        # template has no `def` to key on and no owner class of its own, so the ordinary walk — which only
+        # ever mints a unit at a `def` — would report nothing for a file that calls into the project all
+        # the way down.
+        @unit_key = unit_key
+        # The declared `self` the unit's implicit-self calls resolve against — the plugin's `self_type:`.
+        # Without it a helper call in a template reads as an unresolved self-call and taints the unit.
+        @unit_owner = unit_owner
         @calls = calls
         @attribution = attribution
         @envelopes = envelopes
         @plugin_facts = plugin_facts
         @summaries = {}
         @edges = {}
-        @superclasses = {}
-        @includes = {}
+        @ancestry = AncestryRecorder.new
+        # #1048 — `{class name => Set[method name]}` for the `private` / `protected` members each class
+        # body declared. Read only by a UNIT callee rule, and only to decline.
+        @non_public = {}
         # ADR-103 WD10 / #387 — the class-body facts the framework-edge strategies read, harvested only
         # when a loaded plugin declared one. A run with no `effect_edges:` never allocates them.
         @harvest = plugin_facts.edges? ? {} : nil
       end
 
       def scan(root)
-        walk(root, [], false)
+        return scan_template_unit(root) if @unit_key
+
+        walk(root, [], DefinitionContext::TOP_LEVEL)
         synthesize_framework_units
         FileCollection.new(
           path: @path, summaries: @summaries, edges: @edges,
-          superclasses: @superclasses, includes: @includes
+          superclasses: @ancestry.superclasses, includes: @ancestry.includes
         )
       end
 
       private
 
-      def walk(node, prefix, singleton)
+      # The whole file body as one unit under {@unit_key}. Deliberately NOT combined with the ordinary
+      # walk: a compiled template is straight-line statements, a `def` inside one would be a method the
+      # render site cannot call, and a second keying rule over the same nodes would double-count every
+      # origin in the file.
+      def scan_template_unit(root)
+        summary, edges = UnitScan.new(
+          context: DefinitionContext::INSTANCE_METHOD_BODY, parameters: [], block_parameter: nil,
+          owned_locals: LocalOwnership.owned(root, [], singleton: false), calls: @calls,
+          attribution: @attribution, envelopes: @envelopes, plugin_facts: @plugin_facts,
+          owner_class: @unit_owner, method_name: @unit_key
+        ).run(root)
+        merge_unit(@unit_key, summary, edges)
+        FileCollection.new(path: @path, summaries: @summaries, edges: @edges)
+      rescue StandardError
+        FileCollection.new(path: @path, summaries: { @unit_key => Summary.tainted("collector-error", @unit_key) })
+      end
+
+      # `context` is the {DefinitionContext} of the class-body position `node` sits at. A `class <<` body
+      # and a block that rebinds `self` move it; a nested namespace starts afresh.
+      def walk(node, prefix, context)
         return unless node.is_a?(Prism::Node)
 
         case node
         when Prism::ClassNode, Prism::ModuleNode
           return walk_namespace(node, prefix)
-        when Prism::SingletonClassNode
-          return walk(node.body, prefix, true) if node.body
         when Prism::DefNode
-          return enter_def(node, prefix, singleton)
+          return enter_def(node, prefix, context)
+        when Prism::ConstantWriteNode, Prism::ConstantPathWriteNode
+          @ancestry.record_constant_class(node, prefix)
+        when Prism::AliasMethodNode
+          return record_initialize_alias(prefix) if @ancestry.alias_to_initialize?(node, context)
         when Prism::CallNode
           harvest_class_body_macro(node, prefix)
-          return record_declaration(node, prefix) if declaration?(node)
+          return record_initialize_alias(prefix) if @ancestry.alias_to_initialize?(node, context)
+          return record_declaration(node, prefix, context) if declaration?(node)
         end
 
-        node.rigor_each_child { |child| walk(child, prefix, singleton) }
+        rebinds = DefinitionContext.rebinds?(node)
+        node.rigor_each_child { |child| walk(child, prefix, rebinds ? context.for_child(node, child) : context) }
       end
 
       def walk_namespace(node, prefix)
         nested = Source::ConstantPath.declaration_prefix(prefix, node.constant_path)
-        return node.rigor_each_child { |child| walk(child, prefix, false) } if nested.nil?
+        return node.rigor_each_child { |child| walk(child, prefix, DefinitionContext::CLASS_BODY) } if nested.nil?
+
+        @ancestry.record_superclass(nested.join("::"), node, prefix) if node.is_a?(Prism::ClassNode)
+        return if node.body.nil?
 
-        record_superclass(nested.join("::"), node, prefix) if node.is_a?(Prism::ClassNode)
-        walk(node.body, nested, false) if node.body
+        @non_public[nested.join("::")] = Visibility.non_public_names(node.body)
+        walk(node.body, nested, DefinitionContext::CLASS_BODY)
       end
 
-      def enter_def(node, prefix, singleton)
-        own_singleton = singleton || !node.receiver.nil?
-        scan = add_unit(class_name_for(prefix), node.name.to_s, own_singleton, node.body, node.parameters)
-        harvest_def(prefix, node.name.to_s, own_singleton, scan) if @harvest && !prefix.empty?
+      def enter_def(node, prefix, context)
+        body_context = context.def_body(node)
+        return if body_context.nil?
+
+        scan = add_unit(class_name_for(prefix), node.name.to_s, body_context, node.body, node.parameters,
+                        non_public: non_public?(prefix, node.name.to_s))
+        harvest_def(prefix, node.name.to_s, body_context.singleton?, scan) if @harvest && !prefix.empty?
       end
 
       # What the framework strategies need to know about a `def` the class body spelled out itself: that it
@@ -162,6 +213,10 @@ module Rigor
         end || false
       end
 
+      def non_public?(prefix, name)
+        prefix.empty? ? false : @non_public[class_name_for(prefix)]&.include?(name) || false
+      end
+
       def harvest_for(prefix)
         @harvest[class_name_for(prefix)] ||= { defs: [], units: {}, macros: {}, uniqueness: false }
       end
@@ -184,21 +239,28 @@ module Rigor
       # per unit (ADR-103 WD13): a unit the scanner cannot finish is recorded as non-exhaustive with
       # `collector-error` and its siblings are unaffected.
       #
+      # `context` is the {DefinitionContext} the body runs under, and the unit is keyed singleton exactly
+      # when that body runs on a class. The enclosing unit's own bit does not decide where the units nested
+      # in it land: `def self.outer` is scanned as a singleton method, and a `def inner` inside it is
+      # `Class#inner`.
+      #
       # @return the finished scan, or nil when the unit failed soft
-      def add_unit(class_name, method_name, singleton, body, parameters)
-        key = "#{class_name}#{singleton ? '.' : '#'}#{method_name}"
+      def add_unit(class_name, method_name, context, body, parameters, non_public: false, shared_slot: false)
+        key = "#{class_name}#{context.singleton? ? '.' : '#'}#{method_name}"
         names = parameter_names(parameters)
         scan = UnitScan.new(
-          singleton: singleton, parameters: names,
+          context: context, parameters: names,
           block_parameter: block_parameter_name(parameters),
-          owned_locals: LocalOwnership.owned(body, names), calls: @calls,
+          owned_locals: LocalOwnership.owned(body, names, singleton: context.singleton?), calls: @calls,
           attribution: @attribution, envelopes: @envelopes, plugin_facts: @plugin_facts,
-          owner_class: class_name, method_name: method_name
+          owner_class: class_name, method_name: method_name, non_public: non_public, shared_slot: shared_slot
         )
         summary, edges = scan.run(body)
         merge_unit(key, summary, edges)
-        scan.nested.each do |name, nested_singleton, nested_body, nested_parameters|
-          add_unit(class_name, name, singleton || nested_singleton, nested_body, nested_parameters)
+        scan.nested.each do |name, nested_context, nested_body, nested_parameters, nested_shared_slot|
+          # A `def` inside a method is never an action, whatever the enclosing body's visibility.
+          add_unit(class_name, name, nested_context, nested_body, nested_parameters,
+                   non_public: true, shared_slot: nested_shared_slot)
         end
         scan
       rescue StandardError
@@ -213,51 +275,42 @@ module Rigor
         node.receiver.nil? && DECLARATION_MACROS.include?(node.name)
       end
 
-      def record_declaration(node, prefix)
+      def record_declaration(node, prefix, context)
         class_name = class_name_for(prefix)
         case node.name
-        when :include, :prepend then record_includes(class_name, node, prefix)
-        when :define_method then declare_define_method(class_name, node)
-        else synthesize_accessors(class_name, node)
+        when :include, :prepend then @ancestry.record_includes(class_name, node, prefix, context)
+        when :define_method then declare_define_method(class_name, node, context)
+        else synthesize_accessors(class_name, node, context.module_call_body)
         end
       end
 
-      def declare_define_method(class_name, node)
-        unit = UnitScan.define_method_unit(node)
-        return if unit.nil?
+      def declare_define_method(class_name, node, context)
+        name, body, parameters = UnitScan.define_method_unit(node)
+        body_context = context.module_call_body
+        return if name.nil? || body_context.nil?
 
-        name, singleton, body, parameters = unit
-        add_unit(class_name, name, singleton, body, parameters)
+        # The block runs on the special-variable slot of the body that calls `define_method`, shared by every sibling.
+        add_unit(class_name, name, body_context, body, parameters, shared_slot: true)
       end
 
-      def synthesize_accessors(class_name, node)
+      # `attr_*` is a call on `self`, as `define_method` is, so it defines on the side `define_method` would:
+      # the class's own accessors inside `class << self`, and none where no key names the owner.
+      def synthesize_accessors(class_name, node, body_context)
+        return if body_context.nil?
+
+        singleton = body_context.singleton?
+        separator = singleton ? "." : "#"
         symbol_arguments(node).each do |name|
-          merge_unit("#{class_name}##{name}", Summary.empty, []) unless node.name == :attr_writer
+          merge_unit("#{class_name}#{separator}#{name}", Summary.empty, []) unless node.name == :attr_writer
           next if node.name == :attr_reader
 
-          merge_unit("#{class_name}##{name}=", WRITER_SUMMARY, [])
+          merge_unit("#{class_name}#{separator}#{name}=", singleton ? SINGLETON_WRITER_SUMMARY : WRITER_SUMMARY, [])
         end
       end
 
-      def record_includes(class_name, node, prefix)
-        names = constant_arguments(node).flat_map { |name| lexical_candidates(name, prefix) }
-        (@includes[class_name] ||= []).concat(names) unless names.empty?
-      end
-
-      def record_superclass(full_name, node, prefix)
-        superclass = node.superclass && Source::ConstantPath.qualified_name(node.superclass)
-        @superclasses[full_name] = lexical_candidates(superclass, prefix) if superclass
-      end
-
-      # An ancestry name is recorded AS WRITTEN — `class Loud < Base` inside `module Tracer` names
-      # `Base`, not `Tracer::Base` — and a single file cannot say which constant that resolves to. So the
-      # scanner records the candidates Ruby's own lexical lookup would try, most-qualified first, and the
-      # propagator picks the one the merged project actually defines. Same shape as `ScopeIndexer`'s
-      # as-written superclass table, resolved at the same point: when the whole project is in view.
-      def lexical_candidates(name, prefix)
-        return [name] if prefix.empty? || name.start_with?("#{prefix.join('::')}::")
-
-        prefix.length.downto(1).map { |depth| "#{prefix.first(depth).join('::')}::#{name}" } + [name]
+      # The opaque-ancestry recordings the walk routes here; {AncestryRecorder} owns what they mean.
+      def record_initialize_alias(prefix)
+        @ancestry.record_initialize_alias(class_name_for(prefix))
       end
 
       def merge_unit(key, summary, edges)
@@ -274,10 +327,6 @@ module Rigor
           []
       end
 
-      def constant_arguments(node)
-        node.arguments&.arguments&.filter_map { |argument| Source::ConstantPath.qualified_name(argument) } || []
-      end
-
       def parameter_names(parameters)
         return Set.new unless parameters.is_a?(Prism::ParametersNode)
 

data/lib/rigor/effects/signature_sources.rb

@@ -35,7 +35,7 @@ module Rigor
         ANNOTATION_BRACKETS.map do |opener, closer|
           /%a#{Regexp.escape(opener)}\s*(?:pure\s*#{Regexp.escape(closer)}|rigor:v1:effect\b)/
         end
-      )
+      ).freeze
 
       # A `virtual:<plugin-id>:<source path>` buffer is rbs-inline's (or a plugin's) synthesized RBS for
       # a Ruby file the author actually wrote in. Naming that file is what a reader can act on, so the

data/lib/rigor/effects/snapshot.rb

@@ -306,7 +306,8 @@ module Rigor
           )
         end
 
-        # A synthesised default summary — an `attr_*` writer's `mutate.self`, and the `Struct` / `Data`
+        # A synthesised default summary — an `attr_*` writer's `mutate.self` (`mutate.static` for a
+        # singleton one), and the `Struct` / `Data`
         # accessors that join it when discovery synthesises them — carries no information a reviewer acts
         # on: it restates the `attr_accessor` line. Recognised by its origins being exactly the synthesised
         # constructs, so a hand-written `def name=` keeps its row.

data/lib/rigor/effects/summary.rb

@@ -20,6 +20,8 @@ module Rigor
     #   from {#bundles} because nothing declared is ever proven: diagnostics read {#proven} only, so an
     #   attributed label can never manufacture an `effect.envelope-exceeded`.
     # - {#exhaustive} — false when some call this method makes could not be resolved.
+    # - {#unclaimed} — true when some call it makes was described by nothing at all. A separate question
+    #   from exhaustiveness, with a single reader; see {#unclaimed?}.
     # - {#causes} — why, from {TaintCause}'s closed enum, as `[cause, detail]` pairs. Empty when exhaustive.
     #
     # {#proven} is the flat projection of {#bundles}: the join of every bundle. It is computed once at
@@ -53,10 +55,12 @@ module Rigor
 
       attr_reader :bundles, :declared_bundles, :declared, :causes, :proven
 
-      def initialize(bundles: NO_BUNDLES, declared_bundles: NO_BUNDLES, exhaustive: true, causes: NO_CAUSES)
+      def initialize(bundles: NO_BUNDLES, declared_bundles: NO_BUNDLES, exhaustive: true, causes: NO_CAUSES,
+                     unclaimed: false)
         @bundles = normalize_bundles(bundles)
         @declared_bundles = normalize_bundles(declared_bundles)
         @exhaustive = exhaustive ? true : false
+        @unclaimed = unclaimed ? true : false
         @causes = normalize_causes(causes)
         @proven = flatten(@bundles)
         @declared = flatten(@declared_bundles)
@@ -69,6 +73,24 @@ module Rigor
         @exhaustive
       end
 
+      # Whether this method made a call NOTHING described — no catalogue row, no plugin row, no imported
+      # envelope, and no project definition for the edge to land on (#391).
+      #
+      # It is deliberately **not** a taint. "Every call was resolved" and "every callee's footprint is
+      # known" are different questions, and the model answers the first one everywhere: an unresolved
+      # ordinary edge is dropped rather than tainted, because most such calls are inherited or gem calls
+      # the catalogue has no row for, and tainting them would make almost every method in almost every
+      # project non-exhaustive. That posture is right for a report and for a judgment, both of which read
+      # the proven lane.
+      #
+      # It is wrong for EMISSION. `%a{pure}` written onto a method that calls an undescribed gem method
+      # is a contract nothing re-derives, enforced on that method's callers from then on. So the second
+      # question gets its own bit, read by `rigor sig-gen` and by nothing else: not by the report, not by
+      # the snapshot, not by `effect.envelope-exceeded`, and not by `trivial?`.
+      def unclaimed?
+        @unclaimed
+      end
+
       # Whether this summary is worth showing at all: an exhaustive method whose whole proven footprint is
       # frame-local mutation and which claims nothing. `mutate.local` is tolerated by every envelope
       # (`%a{pure}` included), so a method that only mutates what its own frame allocated reads as pure
@@ -93,18 +115,19 @@ module Rigor
           bundles: merge_bundles(@bundles, other.bundles),
           declared_bundles: merge_bundles(@declared_bundles, other.declared_bundles),
           exhaustive: @exhaustive && other.exhaustive?,
-          causes: @causes + other.causes
+          causes: @causes + other.causes,
+          unclaimed: @unclaimed || other.unclaimed?
         )
       end
 
       def ==(other)
         other.is_a?(Summary) && other.bundles == @bundles && other.declared_bundles == @declared_bundles &&
-          other.exhaustive? == @exhaustive && other.causes == @causes
+          other.exhaustive? == @exhaustive && other.causes == @causes && other.unclaimed? == @unclaimed
       end
       alias eql? ==
 
       def hash
-        [self.class, @bundles, @declared_bundles, @exhaustive, @causes].hash
+        [self.class, @bundles, @declared_bundles, @exhaustive, @causes, @unclaimed].hash
       end
 
       def inspect