audition 0.3.0 → 0.4.1

data/lib/audition/static/checks/ractor_isolation.rb

@@ -9,6 +9,15 @@ module Audition
       # resolution depth of every local reference, so captures are
       # detectable exactly: a reference whose depth reaches past the
       # Ractor block's own scope is an outer capture.
+      #
+      # Ractor.shareable_proc applies a weaker rule to any block at
+      # conversion time: a captured local may not hold an
+      # unshareable object and may not be assigned more than once.
+      # Rails converts the blocks handed to its callback macros the
+      # same way once unshareable_proc_action is set, so a callback
+      # whose capture is provably unshareable is reported too; a
+      # capture of unknown value stays silent, and the boot gate is
+      # its detector.
       class RactorIsolation < Base
         explain :outer_capture,
           severity: :error,
@@ -22,6 +31,105 @@ module Audition
                "Ractor.new(x) { |x| ... }, or send them " \
                "through a Ractor::Port."
 
+        CAPTURE_FIX =
+          "Capture a shareable value: freeze the local (a " \
+          "frozen literal or .freeze), inline it, or hoist a " \
+          "shareable leaf such as a Symbol into a fresh local " \
+          "assigned once before the block."
+
+        explain :shareable_proc_capture,
+          severity: :error,
+          message: "%{method} block captures %{what}",
+          why: "Ractor.shareable_proc refuses a block that can " \
+               "refer to an unshareable object through an outer " \
+               "local, or whose outer local is assigned more " \
+               "than once, with Ractor::IsolationError at " \
+               "conversion time.",
+          fix: CAPTURE_FIX
+
+        explain :callback_capture,
+          severity: :warning,
+          message: "block passed to %{method} captures %{what}",
+          why: "Rails stores the block as a callback and, with " \
+               "unshareable_proc_action set to :warn or :raise, " \
+               "runs it through Ractor.shareable_proc; a block " \
+               "that refers to an unshareable local, or to one " \
+               "assigned more than once, cannot be made " \
+               "shareable and stays an unshareable Proc, which " \
+               "raises Ractor::IsolationError once a non-main " \
+               "Ractor runs the callback.",
+          fix: CAPTURE_FIX
+
+        # Methods that keep their block for later, as a callback or
+        # boot hook; Rails runs each through try_shareable_proc.
+        CALLBACK_MACROS = %i[
+          validate validates_each set_callback on_load initializer
+          to_prepare rescue_from scope default_scope
+        ].freeze
+        CALLBACK_PREFIXES = %w[
+          before_ after_ around_ prepend_before_ prepend_after_
+          prepend_around_ append_before_ append_after_
+          append_around_
+        ].freeze
+        CONVERTERS = %i[shareable_proc shareable_lambda].freeze
+
+        # Classifications a captured value must have for the
+        # conversion to fail for certain.
+        UNSHAREABLE_KINDS = %i[
+          mutable_string mutable_container mutable_call
+          sync_primitive default_proc proc
+        ].freeze
+
+        def initialize(file)
+          super
+          @frames = []
+          @pending = []
+        end
+
+        # Captures are judged once the whole file is read: a local
+        # reassigned after the block is refused just the same.
+        def visit_program_node(node)
+          framed { super }
+          @pending.each { |entry| judge(entry) }
+        end
+
+        def visit_class_node(node) = framed { super }
+
+        def visit_module_node(node) = framed { super }
+
+        def visit_singleton_class_node(node) = framed { super }
+
+        def visit_def_node(node) = framed { super }
+
+        def visit_block_node(node) = framed { super }
+
+        def visit_lambda_node(node) = framed { super }
+
+        def visit_local_variable_write_node(node)
+          assign(node.name, node.depth, node.value)
+          super
+        end
+
+        def visit_local_variable_or_write_node(node)
+          assign(node.name, node.depth, nil)
+          super
+        end
+
+        def visit_local_variable_operator_write_node(node)
+          assign(node.name, node.depth, nil)
+          super
+        end
+
+        def visit_local_variable_and_write_node(node)
+          assign(node.name, node.depth, nil)
+          super
+        end
+
+        def visit_local_variable_target_node(node)
+          assign(node.name, node.depth, nil)
+          super
+        end
+
         def visit_call_node(node)
           examine(node)
           super
@@ -29,18 +137,37 @@ module Audition
 
         private
 
-        def examine(node)
-          return unless node.name == :new
-          return unless ractor_receiver?(node.receiver)
+        def framed
+          @frames.push({})
+          yield
+        ensure
+          @frames.pop
+        end
+
+        # Prism resolves a local write to the scope `depth` levels
+        # up; the frame at that level records every assignment so
+        # the capture judge can count them and classify the value.
+        def assign(name, depth, value)
+          frame = @frames[-1 - depth]
+          return unless frame
+
+          (frame[name.to_s] ||= []) << value
+        end
 
+        def examine(node)
           block = node.block
-          return unless block.is_a?(Prism::BlockNode)
-          return unless block.body
+          return unless block.is_a?(Prism::BlockNode) && block.body
 
-          names = CaptureScanner.scan(block.body)
-          return if names.empty?
+          if node.name == :new && ractor_receiver?(node.receiver)
+            names = CaptureScanner.scan(block.body)
+            return if names.empty?
 
-          flag(node, :outer_capture, names: names.join(", "))
+            flag(node, :outer_capture, names: names.join(", "))
+          elsif CONVERTERS.include?(node.name)
+            defer(node, :shareable_proc_capture)
+          elsif callback_macro?(node.name)
+            defer(node, :callback_capture)
+          end
         end
 
         def ractor_receiver?(receiver)
@@ -48,20 +175,90 @@ module Audition
             receiver.name == :Ractor
         end
 
-        # Walks the Ractor block's body tracking how many block
-        # scopes deep we are; a local reference with depth greater
-        # than that resolves outside the Ractor block.
+        def callback_macro?(name)
+          return true if CALLBACK_MACROS.include?(name)
+
+          text = name.to_s
+          CALLBACK_PREFIXES.any? { |prefix| text.start_with?(prefix) }
+        end
+
+        # The frames a capture resolves to are the ones open now;
+        # they keep filling as traversal continues, so the entry
+        # holds references and is judged at the end.
+        def defer(node, key)
+          captures = CaptureScanner.captures(node.block.body)
+          return if captures.empty?
+
+          resolved = captures.filter_map do |name, depth|
+            frame = @frames[-depth]
+            [name, frame] if frame
+          end
+          return if resolved.empty?
+
+          @pending << {node: node, key: key, captures: resolved}
+        end
+
+        def judge(entry)
+          what = entry[:captures].filter_map do |name, frame|
+            describe_capture(name, frame[name])
+          end
+          return if what.empty?
+
+          node = entry[:node]
+          flag(node, entry[:key],
+            method: method_display(node), what: what.join(", "))
+        end
+
+        def describe_capture(name, assignments)
+          return nil if assignments.nil? || assignments.empty?
+          return "reassigned local #{name}" if assignments.size > 1
+
+          value = assignments.first
+          return nil if value.nil?
+
+          if UNSHAREABLE_KINDS.include?(classifier.classify(value))
+            "unshareable local #{name}"
+          end
+        end
+
+        def method_display(node)
+          receiver = node.receiver
+          case receiver
+          when Prism::ConstantReadNode, Prism::ConstantPathNode
+            "#{receiver.location.slice}.#{node.name}"
+          else
+            node.name.to_s
+          end
+        end
+
+        def classifier
+          @classifier ||= LiteralClassifier.new(
+            frozen_string_literal: file.frozen_string_literal?
+          )
+        end
+
+        # Walks a block's body tracking how many block scopes deep
+        # we are; a local reference with depth greater than that
+        # resolves outside the block, `depth - level` scopes above
+        # it.
         class CaptureScanner < Prism::Visitor
           def self.scan(body)
+            captures(body).map(&:first)
+          end
+
+          # @return [Array<Array(String, Integer)>] each captured
+          #   name once, with how many scopes above the block it
+          #   lives
+          def self.captures(body)
             scanner = new
             scanner.visit(body)
-            scanner.names.uniq
+            scanner.captures.uniq(&:first)
           end
 
-          attr_reader :names
+          attr_reader :captures
 
           def initialize
-            @names = []
+            @captures = []
             @level = 0
             super
           end
@@ -126,7 +323,9 @@ module Audition
           private
 
           def note(node)
-            @names << node.name.to_s if node.depth > @level
+            return unless node.depth > @level
+
+            @captures << [node.name.to_s, node.depth - @level]
           end
         end
       end

data/lib/audition/static/checks/unsafe_calls.rb

@@ -48,10 +48,13 @@ module Audition
                "same way). Writes always need the main Ractor.",
           fix: "Give it a frozen default (default: [].freeze) " \
                "and write copy-on-write: self.x = (x | [v])" \
-               ".freeze, the idiom Rails applied across Action " \
-               "Pack and Active Record; do every write at boot " \
-               "on the main Ractor. The dynamic probe reports " \
-               "ground truth for the installed Rails."
+               ".freeze when every element is shareable, " \
+               "self.x = Ractor.make_shareable(x | [v]) when the " \
+               "additions may be unfrozen (Symbol#to_s returns " \
+               "an unfrozen String), since a plain freeze is " \
+               "shallow; do every write at boot on the main " \
+               "Ractor. The dynamic probe reports ground truth " \
+               "for the installed Rails."
 
         explain :objectspace_id2ref,
           severity: :warning,

data/lib/audition/static/checks/unshareable_reads.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module Audition
+  module Static
+    module Checks
+      # Constants known to hold unshareable objects. Their
+      # definitions live outside the scanned tree (or are swept
+      # from it at setup), so the read site is the only place a
+      # static pass can flag. Learned type aliases match only in
+      # Sorbet type positions, where a constant can only name a
+      # type—a class sharing a name stays quiet. Namespaces that
+      # build constants with const_set at boot get their constant
+      # reads flagged too: the values never pass through a literal
+      # the analyzer could classify.
+      class UnshareableReads < Base
+        explain :sorbet_type_alias,
+          severity: :warning,
+          message: "read of %{name}, a Sorbet type alias that " \
+                   "is not Ractor-shareable",
+          why: "T.type_alias wraps its block in an unfrozen " \
+               "T::Private::Types::TypeAlias that also memoizes " \
+               "on first use, so a non-main Ractor evaluating " \
+               "the reference raises Ractor::IsolationError. " \
+               "sig blocks evaluate lazily, on the first call " \
+               "of the method they annotate, so the raise can " \
+               "surface there too.",
+          fix: "Evaluate sigs at boot on the main Ractor " \
+               "(T::Utils.run_all_sig_blocks) and avoid runtime " \
+               "T.let casts against the alias on Ractor code " \
+               "paths, or rebind the constant to a deeply " \
+               "shareable equivalent at boot."
+
+        explain :dynamic_constant,
+          severity: :warning,
+          message: "read of %{name}, a constant its namespace " \
+                   "defines dynamically at boot",
+          why: "The owning namespace binds this constant with " \
+               "const_set from runtime data, so no literal ever " \
+               "reaches the analyzer; loaders of this shape " \
+               "typically bind unfrozen strings or hashes, which " \
+               "a non-main Ractor cannot read from a constant.",
+          fix: "Make each value shareable as it is bound " \
+               "(Ractor.make_shareable) or hold the data in a " \
+               "frozen registry instead of loose constants."
+
+        KNOWN = Ractor.make_shareable(
+          {"T::Boolean" => :sorbet_type_alias}
+        )
+
+        # Stub generators write rbi definitions fully qualified on
+        # one line, so a regex sweep is enough there.
+        ALIAS_DEFINITION =
+          /^\s*((?:[A-Z]\w*::)*[A-Z]\w*)\s*=\s*T\.type_alias\b/
+
+        VALUE_NAME = /\A[A-Z][A-Z0-9_]*\z/
+
+        class << self
+          attr_reader :learned, :dynamic
+
+          # Both hold names as segment arrays, written eagerly and
+          # kept shareable so parallel scans read them from
+          # non-main Ractors.
+          def learned=(names)
+            @learned = Ractor.make_shareable( # audition:disable
+              names.uniq.group_by(&:last)
+            )
+          end
+
+          def dynamic=(names)
+            @dynamic = Ractor.make_shareable( # audition:disable
+              names.uniq
+            )
+          end
+
+          # Sweeps the tree for type-alias assignments and for
+          # namespaces that const_set under a computed name.
+          # Ruby sources are parsed so definitions keep their
+          # nesting; rbi files are line-scanned.
+          def learn(paths, progress: Progress::SILENT)
+            aliases = []
+            owners = []
+            paths.each do |path|
+              progress.tick
+              source = begin
+                File.read(path)
+              rescue SystemCallError
+                next
+              end
+              if path.end_with?(".rbi")
+                source.scan(ALIAS_DEFINITION) do |(name)|
+                  aliases << name.split("::")
+                end
+              else
+                result = Prism.parse(source)
+                next unless result.success?
+
+                sweep(result.value, [], aliases, owners)
+              end
+            end
+            self.learned = aliases
+            self.dynamic = owners
+          end
+
+          private
+
+          def sweep(node, nesting, aliases, owners)
+            case node
+            when Prism::ClassNode, Prism::ModuleNode
+              nesting = [*nesting, *segments(node.constant_path)]
+            when Prism::ConstantWriteNode
+              if alias_value?(node.value)
+                aliases << [*nesting, node.name.to_s]
+              end
+            when Prism::ConstantPathWriteNode
+              if alias_value?(node.value)
+                aliases << [*nesting, *segments(node.target)]
+              end
+            when Prism::CallNode
+              if dynamic_definer?(node) &&
+                  (owner = owner_of(node, nesting))
+                owners << owner
+              end
+            end
+            node.compact_child_nodes.each do |child|
+              sweep(child, nesting, aliases, owners)
+            end
+          end
+
+          def segments(node)
+            node.location.slice.delete_prefix("::").split("::")
+          end
+
+          def alias_value?(value)
+            value.is_a?(Prism::CallNode) &&
+              value.name == :type_alias &&
+              value.receiver&.location&.slice
+                &.delete_prefix("::") == "T"
+          end
+
+          # A literal name would be classifiable on its own; the
+          # loader shape worth learning computes the name.
+          def dynamic_definer?(node)
+            return false unless node.name == :const_set
+
+            name = node.arguments&.arguments&.first
+            !(name.nil? ||
+              name.is_a?(Prism::SymbolNode) ||
+              name.is_a?(Prism::StringNode))
+          end
+
+          def owner_of(node, nesting)
+            owner = case node.receiver
+            when nil, Prism::SelfNode
+              nesting
+            when Prism::ConstantReadNode, Prism::ConstantPathNode
+              segments(node.receiver)
+            end
+            owner unless owner.nil? || owner.empty?
+          end
+        end
+
+        self.learned = []
+        self.dynamic = []
+
+        on :call_node do |node|
+          note_type_position(node)
+        end
+
+        on :constant_path_node, :constant_read_node do |node|
+          examine(node)
+        end
+
+        def initialize(file)
+          super
+          @typed = Set.new
+        end
+
+        private
+
+        def examine(node)
+          name = node.location.slice.delete_prefix("::")
+          if (key = KNOWN[name])
+            flag(node, key, name: name)
+          elsif @typed.include?(node.object_id) && alias_read?(name)
+            flag(node, :sorbet_type_alias, name: name)
+          elsif dynamic_read?(name)
+            flag(node, :dynamic_constant, name: name)
+          end
+        end
+
+        # The read has to line up with a definition's tail; a
+        # definition swept without nesting only pins its own name,
+        # a qualified one pins the namespace too.
+        def tail_match?(read, full)
+          overlap = [read.size, full.size].min
+          full.last(overlap) == read.last(overlap)
+        end
+
+        def alias_read?(name)
+          segments = name.split("::")
+          self.class.learned[segments.last]&.any? do |full|
+            tail_match?(segments, full)
+          end
+        end
+
+        # Only SCREAMING_CASE reads count: a loader binds values,
+        # and classes nested under the namespace stay quiet.
+        def dynamic_read?(name)
+          segments = name.split("::")
+          return false if segments.size < 2 ||
+            !segments.last.match?(VALUE_NAME)
+
+          parent = segments[0..-2]
+          self.class.dynamic.any? do |owner|
+            tail_match?(parent, owner)
+          end
+        end
+
+        # Constants under a sig block or a T type argument name
+        # types, so learned aliases may match there.
+        def note_type_position(node)
+          if node.name == :sig
+            mark(node.block)
+          elsif t_receiver?(node)
+            case node.name
+            when :let, :cast, :assert_type!
+              mark(node.arguments&.arguments&.dig(1))
+            when :nilable, :any, :all, :class_of, :type_alias
+              node.arguments&.arguments&.each { |arg| mark(arg) }
+              mark(node.block)
+            end
+          end
+        end
+
+        def t_receiver?(node)
+          receiver = node.receiver
+          case receiver
+          when Prism::ConstantReadNode
+            receiver.name == :T
+          when Prism::ConstantPathNode
+            receiver.location.slice.delete_prefix("::") == "T"
+          else
+            false
+          end
+        end
+
+        def mark(node)
+          return if node.nil?
+
+          case node
+          when Prism::ConstantReadNode, Prism::ConstantPathNode
+            return @typed << node.object_id
+          end
+          node.each_child_node { |child| mark(child) }
+        end
+      end
+    end
+  end
+end

data/lib/audition/static/checks.rb

@@ -1,18 +1,22 @@
 # frozen_string_literal: true
 
 require_relative "checks/base"
+require_relative "checks/dependency_class_state"
 require_relative "checks/global_variables"
+require_relative "checks/instance_memoization"
 require_relative "checks/mutable_constants"
 require_relative "checks/ractor_isolation"
 require_relative "checks/runtime_require"
 require_relative "checks/unsafe_calls"
+require_relative "checks/unshareable_reads"
 
 module Audition
   module Static
     module Checks
       BUILT_IN = [
-        GlobalVariables, MutableConstants, RactorIsolation,
-        RuntimeRequire, UnsafeCalls
+        DependencyClassState, GlobalVariables, InstanceMemoization,
+        MutableConstants, RactorIsolation, RuntimeRequire,
+        UnsafeCalls, UnshareableReads
       ].freeze
 
       # Expression-level checks, run per file. Class variables and