rigortype 0.4.0 → 0.4.2

data/lib/rigor/inference/declaration_walk/context.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require_relative "../../source/constant_path"
+
+module Rigor
+  module Inference
+    module DeclarationWalk
+      # What `self`, the cref and `Module.nesting` are at one node of a {DeclarationWalk} (ADR-116 WD5). The walk
+      # derives each child's context from its parent's through the transitions below, so every collector reads
+      # the same answer for the same node and none of them recomputes it.
+      #
+      # - `prefix` — the qualified-name segments of the innermost `class` / `module` a name reaches, which is
+      #   what the tables key lexical facts under: `["Admin", "User"]` inside `module Admin; class User`, `[]`
+      #   at the top level. It is not always the cref. Directly inside `class << self` the cref is the
+      #   singleton class, which has no name, and `prefix` stays the enclosing class's while `singleton_cref`
+      #   says so; below a bare header there (`class D` opens `#<Class:C>::D`, which no name spells) it is
+      #   `[]`.
+      # - `self_owner` — the rebound `self` a `self::` header, write target or eval receiver anchors on. nil
+      #   while `self` is the lexical class; a prefix while a meta-new or eval-family block rebinds it; `[]`
+      #   while it names nothing (a `class <<` body, an anonymous factory block, an eval receiver no name
+      #   reaches).
+      # - `singleton_cref` — whether the lexical cref is unnameable. `class <<` sets it, and a header that
+      #   still names its class re-anchors it.
+      # - `nesting` — `Module.nesting` as the ancestry tables record it (issue #682): a nameable
+      #   `class`/`module` keyword pushes, a `self::` header pushes the prefix its rebound self gives it, and
+      #   nothing else pushes. nil when the caller does not track it, or when it was lost below a header that
+      #   renders no name ({#lost_header_body}). The context keeps the two apart: a `self::` header below a
+      #   rebound self grows a lost chain again, while an untracked one stays nil everywhere.
+      # - `scope` — the census scope a collector types an rvalue under, carrying the chain
+      #   {ScopeIndexer.scope_entering_declaration} stamps at each header. nil when the caller has none.
+      # - `source_path` — the path of the file being walked, which an anonymous class's synthetic name carries
+      #   ({AnonymousMetaClass.name_for}). nil when the caller has none. Read it through
+      #   {#anonymous_class_path}, which answers each variant of that rule.
+      # - `class_body` — whether a `class` / `module` body, a meta-new write's body or an eval-family block's
+      #   body encloses the node. A `class <<` body and a bare factory block do not set it. It exists for the
+      #   `anonymous_class_path` variant {#anonymous_class_path} documents, and nothing else reads it.
+      #
+      # Nameability is derived, not stored: {#unnameable_self?} answers it from the fields above.
+      #
+      # `nesting` and the chain on `scope` are two fields because the walks that threaded them disagree. The
+      # scope's chain is pushed at EVERY header, an unnameable one and the lenient render of a `self::` header
+      # included (`class self::D` pushes `Outer::D`); the ancestry chain is not. A move keeps both answers
+      # (ADR-116's variant rule); the scope's is wrong below `class <<` (#1520), and converging the two is
+      # #1521's.
+      #
+      # The rules themselves stay in {ScopeIndexer} ({ScopeIndexer.decl_body_context},
+      # {ScopeIndexer.meta_new_block_split}, {ScopeIndexer.eval_block_split}), where the walkers not yet ported
+      # still call them; this class is the one place a ported collector reaches them from. That is why the
+      # entry point is `rigor/inference/declaration_walk`, which loads `ScopeIndexer` and, through it, this file.
+      class Context
+        EMPTY_PREFIX = [].freeze
+
+        # The chain below a header that renders no name, held in place of it so that a `self::` header can
+        # tell it from an untracked one. {#nesting} answers nil for it; only its identity is read. Not an empty
+        # Array: Ruby folds every `[].freeze` literal into one shared object, so the sentinel would be the
+        # top level's `[]` chain.
+        LOST_NESTING = Object.new.freeze
+        private_constant :LOST_NESTING
+
+        attr_reader :prefix, :self_owner, :singleton_cref, :scope, :source_path, :class_body
+
+        # A file's top level: `self` is `main`, which the lexical-class convention (a nil `self_owner`)
+        # already answers.
+        def self.root(scope: nil, nesting: nil, source_path: nil)
+          new(EMPTY_PREFIX, nil, false, nesting, scope, source_path, false)
+        end
+
+        def initialize(prefix, self_owner, singleton_cref, nesting, scope, source_path, class_body)
+          @prefix = prefix
+          @self_owner = self_owner
+          @singleton_cref = singleton_cref
+          @nesting = nesting
+          @scope = scope
+          @source_path = source_path
+          @class_body = class_body
+          freeze
+        end
+
+        def nesting
+          @nesting unless @nesting.equal?(LOST_NESTING)
+        end
+
+        # Whether a bare, `self` or `self::` reference here names nothing a table can key on: inside a
+        # `class <<` body, under a `self` an eval or factory block left unnamed, or below an unnameable cref
+        # that no rebound self re-anchors.
+        def unnameable_self?
+          ScopeIndexer.unnameable_eval_self?(false, self_owner, prefix, singleton_cref)
+        end
+
+        # The file path an anonymous class created at this node carries in its synthetic name, under the
+        # variant of that rule the asking collector follows (see {DeclarationWalk::RULE_VARIANTS}):
+        #
+        # - `:whole_file` — the walk's rule: the path everywhere, as the evaluator, the dispatcher and the
+        #   methods walker name the class.
+        # - `:outside_class_bodies` — `walk_class_superclasses`' rule, kept so the superclass table stays
+        #   byte-identical: nil once {#class_body} is set, so `Class.new(P) { }` inside `class C` is keyed
+        #   `#<Class:L:C>` while the other tables name it `#<Class:path:L:C>` (#1521 item 11).
+        def anonymous_class_path(variant)
+          case variant
+          when :whole_file then source_path
+          when :outside_class_bodies then class_body ? nil : source_path
+          else raise ArgumentError, "no anonymous_class_path variant #{variant.inspect}"
+          end
+        end
+
+        # The context a `class` / `module` header gives its body, or nil when the header renders no prefix
+        # (a parsed header always renders one; nil keeps the transition total). `self` is the class again,
+        # so the rebound self resets.
+        def declaration_body(node)
+          self_decl, child_prefix, child_cref =
+            ScopeIndexer.decl_body_context(node, prefix, self_owner, singleton_cref)
+          return nil unless child_prefix
+
+          Context.new(child_cref ? EMPTY_PREFIX : child_prefix, nil, child_cref,
+                      declaration_nesting(node, self_decl, child_cref),
+                      ScopeIndexer.scope_entering_declaration(scope, node.constant_path), source_path, true)
+        end
+
+        # The context of a `class << expr` body. `self` is the singleton class, which no `self::` path names,
+        # and the cref is unnameable until a nameable header re-anchors it. The rung Ruby pushes names nothing,
+        # so neither chain moves.
+        def singleton_class_body
+          Context.new(prefix, EMPTY_PREFIX, true, @nesting, scope, source_path, class_body)
+        end
+
+        # The body of a `K = Class.new { … }`-shaped write: `self` is the class the write names (`[]` when it
+        # names none). The cref and both chains stay lexical.
+        def meta_new_body(owner)
+          Context.new(prefix, owner, singleton_cref, @nesting, scope, source_path, true)
+        end
+
+        # The body of an eval-family block: `self` is the receiver (`[]` when no name reaches it). The cref and
+        # both chains stay lexical.
+        def eval_body(owner)
+          Context.new(prefix, owner, singleton_cref, @nesting, scope, source_path, true)
+        end
+
+        # The body of a bare factory block under the walk's rule: `self` is an anonymous class no name reaches.
+        # The cref and both chains stay lexical.
+        def factory_body
+          Context.new(prefix, EMPTY_PREFIX, singleton_cref, @nesting, scope, source_path, class_body)
+        end
+
+        # The body of a `class` / `module` whose header renders no name (`class foo`, `module` followed by a
+        # `def`: parse-error shapes), under the `:body_with_lost_nesting` variant of the `unrendered_header`
+        # rule (see {DeclarationWalk::RULE_VARIANTS}). `self` is the class again; the chain is kept below an
+        # unnameable cref and lost otherwise, because nothing can be pushed for a header with no name. An
+        # untracked chain stays untracked.
+        def lost_header_body
+          lost = singleton_cref || @nesting.nil? ? @nesting : LOST_NESTING
+          Context.new(prefix, nil, singleton_cref, lost, scope, source_path, true)
+        end
+
+        # The prefix the meta-new and eval-family splits resolve against, under the variant of the
+        # `lexical_prefix` rule the asking collectors follow: `:prefix` is the walk's rule; `:nesting_head` is
+        # `walk_def_nestings`' — the innermost `Module.nesting` entry split into segments, or `[]`. The two
+        # differ below a compact header (`["Admin::Widget"]` against `["Admin", "Widget"]`, which resolve an
+        # eval receiver through different chains) and below an unnameable cref (`[]` against the enclosing
+        # entry) (#1521).
+        def lexical_prefix(variant = :prefix)
+          case variant
+          when :prefix then prefix
+          when :nesting_head then (head = nesting&.first) ? head.split("::") : EMPTY_PREFIX
+          else raise UnknownVariant, "no lexical_prefix variant #{variant.inspect}"
+          end
+        end
+
+        # `[enclosing_parts, body, body_self]` for a `K = Class.new { … }`-shaped write, or nil when its
+        # rvalue is not the idiom ({ScopeIndexer.meta_new_block_split}).
+        def meta_new_split(node, variant = :prefix)
+          ScopeIndexer.meta_new_block_split(node, lexical_prefix(variant), self_owner, singleton_cref)
+        end
+
+        # `[enclosing_parts, body, eval_self]` for an eval-family call with a block, or nil
+        # ({ScopeIndexer.eval_block_split}).
+        def eval_split(node, variant = :prefix)
+          ScopeIndexer.eval_block_split(node, lexical_prefix(variant), self_owner, singleton_cref)
+        end
+
+        private
+
+        # An untracked chain stays untracked. A `self::` header pushes the prefix its rebound self gives it even
+        # below a lost chain, which is how `walk_def_nestings` has always read `[joined, *nil]`; any other
+        # header keeps a lost chain lost.
+        def declaration_nesting(node, self_decl, child_cref)
+          return @nesting if child_cref || @nesting.nil?
+          return [self_decl.join("::"), *nesting].freeze if self_decl
+          return @nesting if @nesting.equal?(LOST_NESTING)
+
+          Source::ConstantPath.pushed_nesting(@nesting, node.constant_path) || @nesting
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/declaration_walk/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Inference
+    module DeclarationWalk
+      # A failure of the walk's contract rather than of the file being walked: a shadow-harness divergence
+      # ({Shadow::Divergence}) or a collector naming a variant no rule has ({UnknownVariant}). The discovery
+      # passes skip a file they cannot read or parse, and the run-result cache path falls back to an uncached
+      # run on an error; both let this through, because skipping the file would hide the failure and drop the
+      # file from the project index. In a file's own index the per-file rescue still reports it as an error
+      # row on the file.
+      class ContractError < StandardError; end
+
+      # A collector's `VARIANTS` names a rule or a variant {RULE_VARIANTS} does not have.
+      class UnknownVariant < ContractError; end
+    end
+  end
+end

data/lib/rigor/inference/declaration_walk/shadow.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../../analysis/shadow_harness"
+require_relative "errors"
+
+module Rigor
+  module Inference
+    module DeclarationWalk
+      # ADR-53 Track B's shadow harness, extended from the rule collectors to the discovery tables (ADR-116
+      # WD5). With `RIGOR_SHADOW_RULE_WALK` set, a table a {DeclarationWalk} collector builds is compared with
+      # the one the legacy walker it replaces builds from the same input, and the first difference raises
+      # {Divergence}. Unset, the legacy walker never runs.
+      #
+      # Equality is stricter than `Hash#==`: key ORDER counts, and so do a container's frozenness and
+      # `compare_by_identity`. A table is iterated when it is merged, folded and written to a seed bundle, so
+      # an order change is a change in what later stages see even where `==` holds. Not compared yet: a
+      # `Set`'s order and frozenness (a `Set` compares by `==` alone), a Hash's `default` / `default_proc`,
+      # and the fields inside a `Data` or `Struct` value beyond its `==`. No ported table holds one yet; a
+      # port whose table does extends {#first_difference} first.
+      #
+      # ## Running it
+      #
+      # Set the variable for the whole `rigor check` process, pool workers included: `RIGOR_SHADOW_RULE_WALK=1
+      # rigor check …`. Where a divergence surfaces depends on which pass built the table:
+      #
+      # - in a file's own index ({ScopeIndexer.index}), the raise lands in the per-file rescue and reports
+      #   as an error diagnostic on the file, carrying the message, the same way a rule-walk divergence does;
+      # - in the cross-file project pre-pass (the superclass tables are built there too), the raise aborts
+      #   the run with the message. {Divergence} is a {ContractError}, which the pre-pass loops, the
+      #   run-result cache fallback and the parameter-inference discovery seed all let through (see
+      #   {ContractError}).
+      #
+      # A run that completes with no such row found no divergence. The rule-walk harness reads the same
+      # variable ({Analysis::ShadowHarness}).
+      #
+      # A warm cache cannot answer for a run the harness did not check. The ADR-45 run-result cache (and the
+      # ADR-87 boot-slim probe and the effects sidecar, which share its key) and the ADR-46 incremental
+      # snapshot, seed bundles included, key on {Analysis::ShadowHarness.cache_identity}. So a run with the
+      # variable never replays a result computed without it, and a divergence row cached under it never
+      # replays into a run without it. A warm hit WITH the variable replays what the same engine computed on
+      # the same inputs with the harness on, divergence rows included; `--no-cache` sends every file through
+      # the check again.
+      module Shadow
+        ENV_KEY = Analysis::ShadowHarness::ENV_KEY
+
+        class Divergence < ContractError; end
+
+        module_function
+
+        def enabled?
+          Analysis::ShadowHarness.enabled?
+        end
+
+        # `walk`, after checking it against the table the block builds when the harness is on. The block is
+        # the legacy walker, so a disabled harness never pays for it.
+        def verified(table, path, walk)
+          verify!(table, path, walk, yield) if enabled?
+          walk
+        end
+
+        def verify!(table, path, walk, legacy)
+          difference = first_difference(legacy, walk, "")
+          return if difference.nil?
+
+          raise Divergence,
+                "#{ENV_KEY} divergence: discovery table `#{table}` for #{path || '(no path)'}: #{difference}"
+        end
+
+        # A description of the first place `walk` differs from `legacy`, or nil when they are the same.
+        # `at` is the key path walked so far, rendered as Ruby index syntax.
+        def first_difference(legacy, walk, at)
+          if legacy.is_a?(Hash) && walk.is_a?(Hash)
+            hash_difference(legacy, walk, at)
+          elsif legacy.is_a?(Array) && walk.is_a?(Array)
+            array_difference(legacy, walk, at)
+          elsif legacy.class != walk.class || legacy != walk
+            "#{location(at)}: legacy #{render(legacy)}, declaration walk #{render(walk)}"
+          end
+        end
+
+        def hash_difference(legacy, walk, at)
+          container_difference(legacy, walk, at) ||
+            key_difference(legacy, walk, at) ||
+            legacy.each_key.lazy.filter_map do |key|
+              first_difference(legacy[key], walk[key], "#{at}[#{render_key(key)}]")
+            end.first
+        end
+
+        def array_difference(legacy, walk, at)
+          container_difference(legacy, walk, at) ||
+            (legacy.size == walk.size ? nil : size_difference(legacy, walk, at)) ||
+            legacy.each_index.lazy.filter_map do |index|
+              first_difference(legacy[index], walk[index], "#{at}[#{index}]")
+            end.first
+        end
+
+        def container_difference(legacy, walk, at)
+          if legacy.frozen? != walk.frozen?
+            "#{location(at)}: legacy frozen=#{legacy.frozen?}, declaration walk frozen=#{walk.frozen?}"
+          elsif legacy.is_a?(Hash) && legacy.compare_by_identity? != walk.compare_by_identity?
+            "#{location(at)}: legacy compare_by_identity=#{legacy.compare_by_identity?}, " \
+              "declaration walk compare_by_identity=#{walk.compare_by_identity?}"
+          end
+        end
+
+        def key_difference(legacy, walk, at)
+          missing = legacy.each_key.find { |key| !walk.key?(key) }
+          return "#{location(at)}: key #{render_key(missing)} only in legacy" if missing
+
+          extra = walk.each_key.find { |key| !legacy.key?(key) }
+          return "#{location(at)}: key #{render_key(extra)} only in declaration walk" if extra
+
+          index = legacy.keys.zip(walk.keys).index { |ours, theirs| !ours.eql?(theirs) }
+          return nil if index.nil?
+
+          "#{location(at)}: key order differs at position #{index}: legacy #{render_key(legacy.keys[index])}, " \
+            "declaration walk #{render_key(walk.keys[index])}"
+        end
+
+        def size_difference(legacy, walk, at)
+          "#{location(at)}: legacy has #{legacy.size} elements, declaration walk #{walk.size}"
+        end
+
+        def location(at)
+          at.empty? ? "the table" : at
+        end
+
+        # A key as it inspects, except a Prism node, which keys the identity tables and would inspect as its
+        # whole subtree: that renders as its class, its name where it has one, and where it starts.
+        def render_key(key)
+          return key.inspect unless key.is_a?(Prism::Node)
+
+          name = key.respond_to?(:name) ? " #{key.name}" : ""
+          start = key.location
+          "#<#{key.class.name.delete_prefix('Prism::')}#{name} at #{start.start_line}:#{start.start_column}>"
+        end
+
+        # A Rigor type renders as it describes itself; anything else as it inspects.
+        def render(value)
+          value.respond_to?(:describe) ? value.describe : value.inspect
+        end
+      end
+    end
+  end
+end