rigortype 0.3.8 → 0.4.0

data/lib/rigor/effects/callee_rule.rb

@@ -0,0 +1,368 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Effects
+    # Callee resolution for plugin attribution rows (#1048; ADR-103 WD10 / WD13; design note § 11.2).
+    #
+    # A framework method can be an **edge** as well as a label. `render :show` inside `UsersController`
+    # runs `app/views/users/show.html.erb`, synchronously and in-process, and since #393 that template is
+    # an effect unit keyed `view:users/show.html` sitting in the very same summaries table. Nothing
+    # produced the edge, because the only plugin-facing edge surface ({Plugin::EffectEdge}) names a
+    # receiver *class* and mints units on a class body, and {Plugin::EffectAttribution} carried labels but
+    # no callee.
+    #
+    # This module is the missing half, and it is deliberately shaped exactly like {Narrowing}: the plugin
+    # writes a **rule name** on its row (`callee: "rails_render"`) and the engine owns the strategy. A
+    # block would have to run inside the per-file effect scan — the one place ADR-103 WD13 forbids
+    # anything that resolves, walks or types — and would not survive the fork-pool / Ractor boundary. A
+    # name is a String: declarative, Marshal-clean, and reviewable in the plugin's manifest.
+    #
+    # ## What a rule may read
+    #
+    # **The call's own argument literals, the unit's owner class, and the unit's own key.** No dataflow,
+    # no typer question, no filesystem. A rule that needed to know whether `app/views/users/show.html.erb`
+    # exists would make a plugin row's meaning a function of the view tree, which the scan does not have
+    # and must not read; instead an unresolvable answer is `nil` and a resolvable-looking one that no unit
+    # answers is **dropped by the propagator**, which restores the row's taint from
+    # {FileCollection::Edge#taint_if_unresolved}. So "the template is not in the table" and "the argument
+    # was computed" both keep the `template-not-analysed` taint, and only a render that reached a real
+    # unit clears it.
+    #
+    # ## Two kinds of rule
+    #
+    # - a **site rule** ({SITE_RULES}) answers for one call node — `render :show`, `render partial: "card"`;
+    # - a **unit rule** ({UNIT_RULES}) answers for a whole unit and reads no node at all. Rails' *implicit*
+    #   render is the case that needs one: an action that falls off its end without rendering still renders
+    #   `<controller>/<action>`, and the fact that produces the edge is the **absence** of a call. Only the
+    #   unit scan can observe that, which is why the rule is applied there rather than in
+    #   {FrameworkUnits} — a class body cannot see which of its methods responded.
+    #
+    #   A unit rule contributes an **edge and nothing else**: no labels, no taint. That is what keeps it
+    #   FP-safe on the private helper a controller also defines — `def load_user` gets an edge to
+    #   `view:users/load_user.html`, no unit answers it, and the unit is exactly as it was.
+    module CalleeRule
+      # The callee an applied rule names, as the two halves {FileCollection::Edge} carries. The key the
+      # propagator reconstructs is `"#{receiver}.#{selector}"` — `view:users/show` + `html`.
+      #
+      # `fallbacks` is the ordered list of selectors the propagator retries when `selector` resolves to
+      # nothing (#1065), or nil for none. The rule only COPIES it off the plugin's table: whether
+      # `view:users/_row.js` exists is a question about the merged table, which the scan cannot ask.
+      Callee = Data.define(:receiver, :selector, :fallbacks) do
+        def initialize(fallbacks: nil, **) = super
+      end
+
+      # Must agree with {MethodKey::TEMPLATE_UNIT_PREFIX} and `Plugin::TemplateUnit::KEY_PREFIX`; pinned
+      # equal by spec.
+      TEMPLATE_PREFIX = "view:"
+
+      # The format a controller action renders absent a `formats:` override — Rails' own default, and the
+      # only one a `render :show` with no other evidence may be read as.
+      DEFAULT_FORMAT = "html"
+
+      # Rules that answer for one call node.
+      SITE_RULES = %w[rails_render rails_render_partial].freeze
+
+      # Rules that answer for a whole unit, from its owner and its own key. A UNIT rule may additionally
+      # be applied **per format arm** of a `respond_to` block (#1071): the arm is the unit's own body, and
+      # the arm's format is a literal the unit scan read, so it travels as data the same way the unit's key
+      # does.
+      UNIT_RULES = %w[rails_implicit_render].freeze
+
+      RULES = (SITE_RULES + UNIT_RULES).freeze
+
+      # `render json:` / `plain:` / `inline:` and friends render no template. They are listed so the rule
+      # can decline rather than read a `partial:` that is not there — declining keeps the row's taint,
+      # which is the conservative answer for a shape this rule does not model.
+      NON_TEMPLATE_OPTIONS = %w[json xml plain text html body js inline file nothing].freeze
+
+      # Template handlers, which a logical name never carries: `Plugin::TemplateUnit#logical_name` is
+      # `users/show.html`, not `users/show.html.erb`. An author may still write the handler out —
+      # `render template: "users/show.html.erb"` is legal Rails — so it is stripped rather than left to
+      # build a key no unit could ever answer.
+      HANDLERS = %w[erb haml slim jbuilder builder rabl ruby].freeze
+
+      module_function
+
+      def known?(name)
+        RULES.include?(name.to_s)
+      end
+
+      def site_rule?(name)
+        SITE_RULES.include?(name.to_s)
+      end
+
+      def unit_rule?(name)
+        UNIT_RULES.include?(name.to_s)
+      end
+
+      # Applies a site rule to one call node.
+      #
+      # @param name — the row's `callee:`
+      # @param node — the `Prism::CallNode` the row matched
+      # @param owner_class — the unit's owner (`"UsersController"`, `"ActionView::Base"`)
+      # @param unit_key — the unit's own key: a selector for a method, `view:users/show.html` for a
+      #   template unit
+      # @param fallbacks — the row's `callee_fallbacks:` table (#1065). Only a rule whose selector the
+      #   CONTEXT supplied consults it; see {rails_render_partial}.
+      # @return the {Callee} the rule named, or nil whenever it cannot settle the target from
+      #   literals alone
+      def site(name, node, owner_class:, unit_key: nil, fallbacks: nil)
+        case name.to_s
+        when "rails_render" then rails_render(node, owner_class)
+        when "rails_render_partial" then rails_render_partial(node, unit_key, fallbacks)
+        end
+      end
+
+      # Applies a unit rule. Reads no node; a `format:` from a `respond_to` arm (#1071) narrows the
+      # template the rule names from the default to that arm's own. Nil, or absent (`DEFAULT_FORMAT`).
+      #
+      # @return the {Callee} the rule named, or nil.
+      def unit(name, owner_class:, unit_key: nil, format: nil)
+        case name.to_s
+        when "rails_implicit_render" then rails_implicit_render(owner_class, unit_key, format: format)
+        end
+      end
+
+      # `render` inside a controller. The positional form names an **action template**
+      # (`render :show` → `users/show`), which is the one place a controller and a view disagree about
+      # what a bare string means.
+      #
+      # Never consults a format fallback (#1065). The format here is either one the author wrote, or
+      # Rails' `html` default standing in for a REQUEST format the rule cannot see — and the lookup order
+      # a controller-side render follows is derived from that request (`request.formats`, an `Accept`
+      # header), not from anything in the source.
+      def rails_render(node, owner_class)
+        directory = controller_directory(owner_class)
+        return nil if directory.nil?
+
+        format = format_for(node, DEFAULT_FORMAT)
+        return nil if format.nil?
+
+        name = template_name(node, directory) || partial_name(node, directory, layout: false)
+        name.nil? ? nil : template_callee(name, format)
+      end
+
+      # `render` inside a template. A bare positional argument is a **partial** here, and so is `layout:`
+      # — in a view `render layout: "shared/wrapper"` names `shared/_wrapper`, not an `app/views/layouts`
+      # file, because `RenderingHelper#render` rewrites `layout:` to `partial:` when a block is given.
+      # Since #1047 a layout compiles to a unit like any other template, so such an edge resolves where
+      # the named partial exists and keeps its taint where it does not.
+      #
+      # **The format fallback (#1065).** The format travels from the enclosing unit, and while a `.js.erb`
+      # template is rendering Rails' lookup context holds `[:js, :html]` — `LookupContext#formats=` appends
+      # `:html` to a lone `:js`, and `AbstractRenderer#prepend_formats` puts the template's own format in
+      # front of the request's. So `render partial: "watchers"` from `_set_watcher.js.erb` runs
+      # `_watchers.js.erb` where one exists and `_watchers.html.erb` otherwise. The rule copies the row's
+      # table for the inherited format onto the callee, and the propagator takes the first key that
+      # resolves.
+      #
+      # The table is consulted only for an INHERITED format. A `formats:` / `format:` keyword or a format
+      # spelled into the name is the author's word, and the fallback stands down: that is the direction
+      # that keeps a taint rather than guessing at a lookup the call overrode.
+      def rails_render_partial(node, unit_key, fallbacks)
+        directory, inherited = template_context(unit_key)
+        return nil if directory.nil?
+
+        format = format_for(node, inherited)
+        return nil if format.nil?
+
+        retry_formats = format_keyword?(node) ? nil : fallbacks&.fetch(format, nil)
+        explicit = keyword_name(node, "template")
+        return template_callee(qualify(explicit, directory), format, retry_formats) if explicit
+
+        name = partial_name(node, directory) || positional_partial(node, directory)
+        name.nil? ? nil : template_callee(name, format, retry_formats)
+      end
+
+      # Rails' implicit render: an action that never rendered still renders `<controller>/<action>`. A
+      # `respond_to` arm (#1071) is the same convention per format: `format.js` with no responding block
+      # renders `<controller>/<action>.js`, so the rule narrows the format it answers for, and an arm that
+      # IS answered outright is not applied at all (the unit scan decides that half and calls with the
+      # arm's format only for arms that still fall through).
+      def rails_implicit_render(owner_class, unit_key, format: nil)
+        directory = controller_directory(owner_class)
+        return nil if directory.nil? || unit_key.nil?
+
+        action = unit_key.to_s
+        return nil unless /\A[a-z_][A-Za-z0-9_]*[?!=]?\z/.match?(action)
+        return nil if action.end_with?("?", "!", "=")
+
+        template_callee("#{directory}/#{action}", format || DEFAULT_FORMAT)
+      end
+
+      # `UsersController` → `users`; `Admin::UsersController` → `admin/users`. A class whose name does not
+      # end in `Controller` is not one this rule can read a view directory off, and answers nil.
+      def controller_directory(owner_class)
+        return nil if owner_class.nil?
+
+        segments = owner_class.to_s.split("::")
+        last = segments.pop
+        return nil unless last&.end_with?("Controller") && last != "Controller"
+
+        segments.push(last.delete_suffix("Controller"))
+        segments.map { |segment| underscore(segment) }.join("/")
+      end
+
+      # `[directory, format]` for a template unit's own key — `view:users/show.html` → `["users", "html"]`.
+      # A partial rendered from a `.json` template is a `.json` partial, which is why the format travels.
+      def template_context(unit_key)
+        key = unit_key.to_s
+        return [nil, nil] unless key.start_with?(TEMPLATE_PREFIX)
+
+        logical = key.delete_prefix(TEMPLATE_PREFIX)
+        name, _, format = logical.rpartition(".")
+        return [nil, nil] if name.empty?
+
+        directory = name.include?("/") ? name[0...name.rindex("/")] : ""
+        [directory, format]
+      end
+
+      # The explicit template spellings: `template: "users/show"` and `action: :edit`.
+      def template_name(node, directory)
+        explicit = keyword_name(node, "template")
+        return qualify(explicit, directory) if explicit
+
+        action = keyword_name(node, "action")
+        return "#{directory}/#{action}" if action && !action.include?("/")
+        return action if action
+
+        positional_template(node, directory)
+      end
+
+      # `render :show` / `render "show"` / `render "admin/form"`, but only when no option keyword the rule
+      # does not model is present.
+      def positional_template(node, directory)
+        name = literal_name(positional(node).first)
+        return nil if name.nil?
+
+        qualify(name, directory)
+      end
+
+      # `render "card"` inside a template — the same literal, read as a partial.
+      def positional_partial(node, directory)
+        name = literal_name(positional(node).first)
+        name.nil? ? nil : partialize(qualify(name, directory))
+      end
+
+      # `partial: "card"` / `partial: "users/card"`, and the view-side `layout:`. `collection:` changes
+      # how many times the partial runs and not which one, so it is read and ignored on purpose: an
+      # effect summary is an upper bound over the body, not a count.
+      def partial_name(node, directory, layout: true)
+        name = keyword_name(node, "partial") || (layout ? keyword_name(node, "layout") : nil)
+        name.nil? ? nil : partialize(qualify(name, directory))
+      end
+
+      # The requested format, or nil to decline. Absent is `fallback`; a literal narrows; anything
+      # computed is genuinely unknown and must not be guessed at `html`.
+      def format_for(node, fallback)
+        return nil if non_template?(node)
+
+        value = keyword_argument(node, "formats") || keyword_argument(node, "format")
+        return fallback if value.nil?
+
+        literal = literal_name(value) || literal_name(array_head(value))
+        literal&.split(".")&.last
+      end
+
+      def format_keyword?(node)
+        !(keyword_argument(node, "formats") || keyword_argument(node, "format")).nil?
+      end
+
+      def non_template?(node)
+        NON_TEMPLATE_OPTIONS.any? { |option| keyword_argument(node, option) }
+      end
+
+      def array_head(node)
+        node.elements.first if node.is_a?(Prism::ArrayNode)
+      end
+
+      # `fallbacks` survives only when the name spelled no format of its own: `render "row.json"` from a
+      # `.js` template is the author naming `json`, and a `js` table has nothing to say about it.
+      def template_callee(name, format, fallbacks = nil)
+        spelled = split_suffixes(name, nil).last
+        name, format = split_suffixes(name, format)
+        return nil if name.nil? || name.empty? || format.nil? || format.empty?
+        return nil if name.include?(" ") || format.include?(" ") || format.include?(".")
+
+        fallbacks = nil unless spelled.nil? && fallbacks && !fallbacks.empty?
+        Callee.new(receiver: "#{TEMPLATE_PREFIX}#{name}", selector: format, fallbacks: fallbacks)
+      end
+
+      # Splits a written handler and format off the name's last segment, so `render "show.json"` names
+      # `view:users/show` + `json` and `render template: "users/show.html.erb"` names
+      # `view:users/show` + `html` rather than the impossible `view:users/show.html.erb.html`. A name
+      # that spells a format wins over the rule's default, because the author said so; a name that
+      # spells only a handler keeps the default.
+      def split_suffixes(name, format)
+        return [name, format] if name.nil?
+
+        directory, separator, base = name.rpartition("/")
+        segments = base.split(".")
+        return [name, format] if segments.length <= 1
+
+        stem = segments.shift
+        segments.reject! { |segment| HANDLERS.include?(segment) }
+        ["#{directory}#{separator}#{stem}", segments.first || format]
+      end
+
+      # `"card"` in `users` → `"users/_card"`; `"admin/card"` → `"admin/_card"`. A name already spelled
+      # with the underscore keeps it, because that is what Rails accepts too.
+      def partialize(name)
+        return nil if name.nil?
+
+        directory, separator, base = name.rpartition("/")
+        return base.start_with?("_") ? name : "_#{name}" if separator.empty?
+
+        base.start_with?("_") ? name : "#{directory}/_#{base}"
+      end
+
+      # A name with a `/` is rooted at the views directory; a bare one is relative to the rendering
+      # unit's own directory.
+      def qualify(name, directory)
+        return nil if name.nil? || name.empty?
+        return name if name.include?("/") || directory.nil? || directory.empty?
+
+        "#{directory}/#{name}"
+      end
+
+      def keyword_name(node, key)
+        literal_name(keyword_argument(node, key))
+      end
+
+      def literal_name(value)
+        case value
+        when Prism::SymbolNode, Prism::StringNode then value.unescaped
+        end
+      end
+
+      def positional(node)
+        node.arguments&.arguments&.grep_v(Prism::KeywordHashNode) || []
+      end
+
+      def keyword_argument(node, name)
+        hash = node.arguments&.arguments&.find { |argument| argument.is_a?(Prism::KeywordHashNode) }
+        pair = hash&.elements&.find do |element|
+          element.is_a?(Prism::AssocNode) && element.key.is_a?(Prism::SymbolNode) &&
+            element.key.unescaped == name
+        end
+        pair&.value
+      end
+
+      # `ActiveStorage` → `active_storage`. The engine's own reading of a constant segment; deliberately
+      # not an inflector call, because a rule may read nothing outside the strings it was given.
+      def underscore(segment)
+        segment.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+      end
+
+      private_class_method :rails_render, :rails_render_partial, :rails_implicit_render,
+                           :controller_directory, :template_context, :template_name,
+                           :positional_template, :positional_partial, :partial_name,
+                           :format_for, :format_keyword?, :non_template?, :array_head, :template_callee,
+                           :split_suffixes, :partialize,
+                           :qualify, :keyword_name, :literal_name, :positional, :keyword_argument,
+                           :underscore
+    end
+  end
+end

data/lib/rigor/effects/catalog.rb

@@ -36,14 +36,17 @@ module Rigor
       class Error < StandardError
       end
 
-      DATA_PATH = File.expand_path("../../../data/effects/core.yml", __dir__)
+      DATA_PATH = File.expand_path("../../../data/effects/core.yml", __dir__).freeze
 
       # The mutator sets a value class may name, by reference. Adding a name here is the only way a
-      # class gets one — the data file may not spell a selector list of its own.
+      # class gets one — the data file may not spell a selector list of its own. Each is the set
+      # {MutationClassifier#mutating?} reads for that class, so a posture's answer and the classifier's
+      # cannot disagree: `hash` is the classifier's union of the widening's two Hash tables, because
+      # `compare_by_identity` mutates the receiver although the widening keeps it off `HASH_MUTATORS`.
       MUTATOR_SETS = {
         "array" => Inference::MutationWidening::ARRAY_MUTATORS,
-        "hash" => Inference::MutationWidening::HASH_MUTATORS,
-        "string" => MutationClassifier::STRING_MUTATORS
+        "hash" => MutationClassifier::HASH_MUTATORS,
+        "string" => Inference::StringMutation::MUTATORS
       }.freeze
 
       NO_MUTATORS = Set[].freeze

data/lib/rigor/effects/collector.rb

@@ -39,12 +39,16 @@ module Rigor
 
       # Per-file, per-thread accumulator. Not frozen and never shared: it lives for one `analyze_file`.
       class Accumulator
-        attr_reader :path, :calls, :attribution, :envelopes, :plugin_facts
+        attr_reader :path, :calls, :attribution, :envelopes, :plugin_facts, :unit_key, :unit_owner
         attr_accessor :root
 
         def initialize(path, attribution: Attribution.empty, envelopes: EnvelopeIndex.empty,
-                       plugin_facts: PluginFacts.empty)
+                       plugin_facts: PluginFacts.empty, unit_key: nil, unit_owner: nil)
           @path = path
+          # #392 — set for a template unit, where the whole file is ONE effect unit keyed
+          # `view:<logical_name>` under the plugin's declared `self`.
+          @unit_key = unit_key
+          @unit_owner = unit_owner
           @attribution = attribution
           @envelopes = envelopes
           @plugin_facts = plugin_facts
@@ -92,10 +96,11 @@ module Rigor
       # {EnvelopeIndex} of #386, carried the same way and for the same reason — the declared lane a call
       # site imports must not depend on which process typed the file.
       def collect_for(path, attribution: Attribution.empty, envelopes: EnvelopeIndex.empty,
-                      plugin_facts: PluginFacts.empty)
+                      plugin_facts: PluginFacts.empty, unit_key: nil, unit_owner: nil)
         previous = Thread.current[KEY]
         accumulator = Accumulator.new(path.to_s, attribution: attribution, envelopes: envelopes,
-                                                 plugin_facts: plugin_facts)
+                                                 plugin_facts: plugin_facts, unit_key: unit_key,
+                                                 unit_owner: unit_owner)
         Thread.current[KEY] = accumulator
         @mutex.synchronize { @active_count += 1 }
         yield
@@ -207,7 +212,8 @@ module Rigor
         Scanner.scan(
           root: accumulator.root, path: accumulator.path, calls: accumulator.calls,
           attribution: accumulator.attribution, envelopes: accumulator.envelopes,
-          plugin_facts: accumulator.plugin_facts
+          plugin_facts: accumulator.plugin_facts, unit_key: accumulator.unit_key,
+          unit_owner: accumulator.unit_owner
         )
       rescue StandardError
         FileCollection.new(path: accumulator.path, failed: true)

data/lib/rigor/effects/config_envelopes.rb

@@ -69,9 +69,8 @@ module Rigor
 
       # Resolves `Configuration#effects_envelopes` against a registry.
       #
-      # @param entries [Array<Hash>] the loaded, shape-validated entries
-      # @param registry [Registry] the vocabulary, project extensions included
-      # @return [Array<Entry>]
+      # @param entries — the loaded, shape-validated entries
+      # @param registry — the vocabulary, project extensions included
       def build(entries:, registry:)
         entries.each_with_index.map do |entry, index|
           labels = Array(entry["effect"]).map(&:to_s)
@@ -86,11 +85,10 @@ module Rigor
 
       # The class-level envelopes the entries put on a project.
       #
-      # @param entries [Array<Entry>]
-      # @param class_names [Enumerable<String>] every class the run collected units for
-      # @param sources [Hash{String => Array<String>}] `Runner#effect_sources` — `{method key => [path]}`
-      # @param project_root [String] what `sources` paths are relativised against
-      # @return [Hash{String => Envelope}] one envelope per selected class, keyed by class name
+      # @param class_names — every class the run collected units for
+      # @param sources — `Runner#effect_sources` — `{method key => [path]}`
+      # @param project_root — what `sources` paths are relativised against
+      # @return one envelope per selected class, keyed by class name
       def for_classes(entries:, class_names:, sources: {}, project_root: Dir.pwd)
         return NO_ENVELOPES if entries.empty?
 
@@ -115,6 +113,13 @@ module Rigor
         )
       end
 
+      # Whether one entry selects a class — by its fully-qualified name for a `namespace:` entry, by any
+      # file that defines it for a `match:` one.
+      #
+      # Public since #391: `rigor sig-gen`'s emission asks the same question this module's own
+      # {.for_classes} asks, and asks it with a defining file it already has. It was private while
+      # {.for_classes} was the only caller; a second caller with the same inputs is not a reason to
+      # reimplement the predicate.
       def selects?(entry, class_name, paths)
         return namespace_match?(entry.namespace, class_name) if entry.namespace
 
@@ -166,7 +171,7 @@ module Rigor
       def files_by_class(sources, project_root)
         root = "#{File.absolute_path(project_root.to_s).chomp('/')}/"
         sources.each_with_object({}) do |(key, paths), out|
-          owner = MethodKey.owner(key)
+          owner = MethodKey.envelope_owner(key)
           next if owner.nil?
 
           bucket = (out[owner] ||= [])
@@ -179,7 +184,7 @@ module Rigor
         absolute.start_with?(root) ? absolute[root.length..] : path.to_s
       end
 
-      private_class_method :selects?, :match_segments?, :match_deep?, :files_by_class, :relativize
+      private_class_method :match_segments?, :match_deep?, :files_by_class, :relativize
     end
   end
 end

data/lib/rigor/effects/definition_context.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Effects
+    # Which side of its class a definition written at some point lands on, and what `self` its body runs
+    # on, or that the syntax does not say. The scanner keys a unit `Class.m` or `Class#m` from the first, and
+    # scans the body with the second (the singleton bit {MutationClassifier} and
+    # {LocalOwnership.constructor?} read).
+    #
+    # Ruby answers the two from different places, which is why one bit carried down the walk got both
+    # wrong in turn:
+    #
+    # - a receiver-less `def` lands on the **default definee**: the class the lexically enclosing body
+    #   opened, which is the singleton class inside `class << self`. A method body does not move it, so
+    #   `def inner` inside `def self.outer` defines `Foo#inner`, while inside a `def` in `class << self` it
+    #   defines `Foo.inner`.
+    # - `define_method` and the `attr_*` macros are calls on **`self`**, so they define instance methods of
+    #   the module `self` is: `Foo#x` inside `def self.setup`, where `self` is `Foo`, and `Foo.x` inside
+    #   `class << self`, where it is `Foo`'s singleton class.
+    #
+    # Only the spellings that name the new `self` move either answer: `class << self`, and a block given to
+    # `class_eval` / `instance_eval` (or an `_exec` / `module_` alias) on `self` or on `singleton_class`.
+    # Where the syntax cannot say, the answer is **unknown** and a definition there is no unit. That covers
+    # the block of `Class.new` and its kin, an eval on any other receiver, `class << obj`, and a method
+    # defined on one object or on a singleton class's own singleton class. Filed under the enclosing class,
+    # such a definition would join that class's real method of the same name, and a `Class.new(self)`
+    # override shares its name by design.
+    #
+    # `self_kind` is `:instance`, `:class` (the class the enclosing namespace opened), `:singleton_class`
+    # (that class's singleton class) or `:unknown`, and `definee_singleton` is true, false, or nil when
+    # unknown. Every context is allocated once.
+    class DefinitionContext < Data.define(:self_kind, :definee_singleton)
+      CLASS_EVAL_CALLS = %i[class_eval class_exec module_eval module_exec].to_set.freeze
+      INSTANCE_EVAL_CALLS = %i[instance_eval instance_exec].to_set.freeze
+      # The builders whose block defines into a class or module the call itself creates.
+      ANONYMOUS_BUILDERS = { Class: :new, Module: :new, Struct: :new, Data: :define }.freeze
+      # The `self_kind`s that are a class object.
+      CLASS_SELVES = %i[class singleton_class].to_set.freeze
+      private_constant :CLASS_EVAL_CALLS, :INSTANCE_EVAL_CALLS, :ANONYMOUS_BUILDERS, :CLASS_SELVES
+
+      CONTEXTS = %i[instance class singleton_class unknown].to_h do |self_kind|
+        [self_kind, [false, true, nil].to_h do |definee|
+          [definee, new(self_kind: self_kind, definee_singleton: definee)]
+        end.freeze]
+      end.freeze
+      private_constant :CONTEXTS
+
+      def self.of(self_kind, definee_singleton)
+        CONTEXTS.fetch(self_kind).fetch(definee_singleton)
+      end
+
+      # Whether a child of `node` may run under another context than `node` does: a call's block, or a
+      # `class <<` body. Only these need {#for_child}, and asking once per node rather than once per child
+      # keeps the walks from paying a call for every element of a large literal.
+      def self.rebinds?(node)
+        node.is_a?(Prism::SingletonClassNode) || (node.is_a?(Prism::CallNode) && node.block.is_a?(Prism::BlockNode))
+      end
+
+      # A class body.
+      CLASS_BODY = of(:class, false)
+      # A `class << self` body: `self` and the definee are both the singleton class.
+      SINGLETON_CLASS_BODY = of(:singleton_class, true)
+      # The body of an instance method of the class.
+      INSTANCE_METHOD_BODY = of(:instance, false)
+      # The top level, where `self` is `main`, an instance of `Object`, and a `def` defines `Object#m`.
+      TOP_LEVEL = INSTANCE_METHOD_BODY
+      # Where the syntax says neither what `self` is nor where a `def` lands. Every block inside stays here.
+      UNKNOWN = of(:unknown, nil)
+
+      # Whether `self` is a class object here — the singleton bit a unit's body is scanned with.
+      def singleton?
+        CLASS_SELVES.include?(self_kind)
+      end
+
+      # Whether `self` is the singleton class here, so a call on it (`define_method`, an `attr_*` macro,
+      # `include`, `prepend`, `alias_method`) works on the singleton class rather than the class.
+      def self_singleton_class?
+        self_kind == :singleton_class
+      end
+
+      # The context the body of `def` node `node` runs under, or nil where no key names the method. The
+      # unit is keyed singleton exactly when that context is {#singleton?}. The body keeps this default
+      # definee: a `def` nested in it lands where one written beside it would.
+      #
+      # `def self.x` defines a singleton method only where `self` is the class. In an instance method it
+      # defines a method on one object, and in `class << self` one on the singleton class's own singleton
+      # class. `def Const.x` keeps the reading it has always had, a method of the class the unit is keyed
+      # under; any other receiver is an object no key names.
+      def def_body(node)
+        case node.receiver
+        when nil
+          DefinitionContext.of(definee_singleton ? :class : :instance, definee_singleton) unless definee_singleton.nil?
+        when Prism::SelfNode
+          self if self_kind == :class
+        when Prism::ConstantReadNode, Prism::ConstantPathNode
+          DefinitionContext.of(:class, definee_singleton) unless self_kind == :unknown
+        end
+      end
+
+      # The context the block of a literal-name `define_method` written here runs under, or nil where no key
+      # names the method; an `attr_*` macro here defines on the same side. Both are calls on `self`, which
+      # only a class and its singleton class answer, and the block keeps the definee it closed over.
+      def module_call_body
+        case self_kind
+        when :class then DefinitionContext.of(:instance, definee_singleton)
+        when :singleton_class then DefinitionContext.of(:class, definee_singleton)
+        end
+      end
+
+      # The context `child` runs under as a child of `node`, a node {.rebinds?} accepts. A call's block and a
+      # `class <<` body may rebind `self`; every other child keeps this context. (A block is a call's only
+      # `BlockNode` child.)
+      def for_child(node, child)
+        case node
+        when Prism::CallNode then child.is_a?(Prism::BlockNode) ? block(node) : self
+        when Prism::SingletonClassNode then child.equal?(node.body) ? singleton_class_body(node.expression) : self
+        else self
+        end
+      end
+
+      private
+
+      # `class << self` on the class opens its singleton class; any other `class << …` opens one no key names.
+      def singleton_class_body(expression)
+        self_kind == :class && expression.is_a?(Prism::SelfNode) ? SINGLETON_CLASS_BODY : UNKNOWN
+      end
+
+      def block(call)
+        name = call.name
+        if CLASS_EVAL_CALLS.include?(name) then class_eval_block(call.receiver)
+        elsif INSTANCE_EVAL_CALLS.include?(name) then instance_eval_block(call.receiver)
+        elsif anonymous_builder?(call) then UNKNOWN
+        else self
+        end
+      end
+
+      # `class_eval` makes its receiver both `self` and the definee.
+      def class_eval_block(receiver)
+        if self_receiver?(receiver) && singleton? then DefinitionContext.of(self_kind, self_kind == :singleton_class)
+        elsif singleton_class_receiver?(receiver) then SINGLETON_CLASS_BODY
+        else UNKNOWN
+        end
+      end
+
+      # `instance_eval` makes its receiver `self` and the receiver's singleton class the definee. On the
+      # class that is the singleton class. On the singleton class it is that class's own singleton class,
+      # which no key names, so a `define_method` there is keyed and a `def` is not.
+      def instance_eval_block(receiver)
+        if self_receiver?(receiver) && self_kind == :class then DefinitionContext.of(:class, true)
+        elsif (self_receiver?(receiver) && self_kind == :singleton_class) || singleton_class_receiver?(receiver)
+          DefinitionContext.of(:singleton_class, nil)
+        else UNKNOWN
+        end
+      end
+
+      def self_receiver?(receiver)
+        receiver.nil? || receiver.is_a?(Prism::SelfNode)
+      end
+
+      # `singleton_class` called on the class.
+      def singleton_class_receiver?(receiver)
+        self_kind == :class && receiver.is_a?(Prism::CallNode) && receiver.name == :singleton_class &&
+          self_receiver?(receiver.receiver) && receiver.arguments.nil? && receiver.block.nil?
+      end
+
+      # `Class.new { … }` and its kin, spelled on the core constant.
+      def anonymous_builder?(call)
+        receiver = call.receiver
+        name = case receiver
+               when Prism::ConstantReadNode then receiver.name
+               when Prism::ConstantPathNode then receiver.name if receiver.parent.nil?
+               end
+        !name.nil? && ANONYMOUS_BUILDERS[name] == call.name
+      end
+    end
+  end
+end