audition 0.4.0 → 0.4.1

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

@@ -37,6 +37,33 @@ module Audition
                "BasicObject has no #freeze: use " \
                "Object.new.freeze for such a sentinel."
 
+        explain :fresh_container,
+          severity: :error,
+          message: "constant %{name} holds an unfrozen %{type} " \
+                   "returned by %{method}",
+          why: "The call allocates a new %{type} on every core " \
+               "receiver that defines it, and " \
+               "`# frozen_string_literal: true` covers literals " \
+               "only, so the constant holds an unfrozen object " \
+               "and a non-main Ractor reading it raises " \
+               "Ractor::IsolationError.",
+          fix: "Make the value deeply shareable at definition " \
+               "time with Ractor.make_shareable(...), or append " \
+               "`.freeze` when every element is itself shareable, " \
+               "since a bare `.freeze` is shallow."
+
+        explain :unshareable_object,
+          severity: :error,
+          message: "constant %{name} holds a Method object from " \
+                   "%{method}, which is never shareable",
+          why: "Method and UnboundMethod objects are not " \
+               "Ractor-shareable and freezing one does not help " \
+               "(verified on Ruby 4.0); a non-main Ractor reading " \
+               "this constant raises Ractor::IsolationError.",
+          fix: "Store the method name as a Symbol and look the " \
+               "method up where it is called, or keep the Method " \
+               "object per-Ractor with Ractor.store_if_absent."
+
         explain :mutable_container,
           severity: :error,
           message: "constant %{name} holds a mutable %{type} " \
@@ -46,7 +73,11 @@ module Audition
                "shareable; otherwise make it deeply shareable with " \
                "`# shareable_constant_value: literal` or " \
                "Ractor.make_shareable(...), since a bare " \
-               "`.freeze` is shallow."
+               "`.freeze` is shallow. A public constant that " \
+               "applications mutate keeps its name and is read " \
+               "through an initialize keyword default into an " \
+               "ivar, so a shareable instance carries a frozen " \
+               "copy; mutating the constant is then deprecated."
 
         explain :shallow_freeze,
           severity: :error,
@@ -153,12 +184,16 @@ module Audition
                "freeze it (each_with_object then .freeze), " \
                "or move the registry behind a writer that " \
                "rebuilds and refreezes on each change " \
-               "(copy-on-write). A " \
+               "(copy-on-write; Ractor.make_shareable when the " \
+               "additions may be unfrozen). A " \
                "registry that plugins extend during boot is " \
                "frozen in the last boot hook (after_initialize) " \
                "rather than at definition, and writes after the " \
                "freeze merge into a fresh frozen copy with a " \
-               "deprecation instead of raising."
+               "deprecation instead of raising. A public " \
+               "constant that applications mutate keeps its " \
+               "name and is read through an initialize keyword " \
+               "default into an ivar; mutating it is deprecated."
 
         on :constant_write_node, :constant_or_write_node do |node|
           examine(node.name.to_s, node, node.value)
@@ -213,6 +248,19 @@ module Audition
             flag(node, :mutable_container, name: name,
               type: container_type(value),
               autofix: fix_ok ? freeze_container(value) : nil)
+          when :fresh_container
+            # A later bare freeze settles the top level; only
+            # provably mutable elements are still worth a report.
+            unless frozen_later?(name) &&
+                classifier.fresh_elements(value) != :mutable
+              flag(node, :fresh_container, name: name,
+                type: classifier.fresh_type(value),
+                method: call_display(value),
+                autofix: fix_ok ? freeze_fresh(value) : nil)
+            end
+          when :unshareable_object
+            flag(node, :unshareable_object, name: name,
+              method: call_display(value))
           when :shallow_freeze
             flag(node, :shallow_freeze, name: name,
               autofix:
@@ -354,19 +402,50 @@ module Audition
 
         # Ternaries classify as strings when both branches are;
         # `.freeze` binds tighter than `?:`, so they get parens.
+        # `X + "s"` is a String or a Pathname, whatever X is; only
+        # a string literal receiver pins the type.
         def call_type(call)
           case classifier.const_name(call.receiver)
           when "Regexp" then "Regexp"
           when "Object", "BasicObject" then "Object"
-          else "String"
+          else
+            if call.name == :+ && !string_receiver?(call)
+              "object"
+            else
+              "String"
+            end
           end
         end
 
+        def string_receiver?(call)
+          receiver = call.receiver
+          receiver.is_a?(Prism::StringNode) ||
+            receiver.is_a?(Prism::InterpolatedStringNode)
+        end
+
         def call_display(call)
-          return call.name.to_s if call.receiver.nil?
+          name = call.name
+          return "the #{name} operator" if name.match?(/\A[^a-z_]/i)
+          return name.to_s if call.receiver.nil?
 
           owner = classifier.const_name(call.receiver)
-          owner ? "#{owner}.#{call.name}" : "String##{call.name}"
+          return "#{owner}.#{name}" if owner
+          return ".#{name}" unless literal_receiver?(call)
+
+          "#{classifier.fresh_string_owner(call)}##{name}"
+        end
+
+        def literal_receiver?(call)
+          receiver = call.receiver
+          receiver.is_a?(Prism::StringNode) ||
+            receiver.is_a?(Prism::InterpolatedStringNode) ||
+            receiver.is_a?(Prism::SymbolNode) ||
+            receiver.is_a?(Prism::RegularExpressionNode) ||
+            receiver.is_a?(Prism::ArrayNode) ||
+            receiver.is_a?(Prism::HashNode) ||
+            LiteralClassifier::NUMERIC_LITERALS
+              .any? { |type| receiver.is_a?(type) } ||
+            !classifier.array_root(receiver).nil?
         end
 
         # The receiver is arbitrary, often a chain, so the
@@ -385,9 +464,10 @@ module Audition
         end
 
         # `.freeze` binds tighter than an operator: `"a" + "b".freeze`
-        # freezes only "b", so operator calls get parentheses while
-        # literals and parenthesized or argument-free calls take
-        # the bare suffix.
+        # freezes only "b" and `+"a".freeze` dups the frozen
+        # literal back into a mutable one, so operator and unary
+        # calls get parentheses while literals and parenthesized
+        # or argument-free calls take the bare suffix.
         def bare_freezable?(value)
           case value
           when Prism::StringNode, Prism::InterpolatedStringNode,
@@ -396,6 +476,8 @@ module Audition
           when Prism::ArrayNode
             !value.opening_loc.nil?
           when Prism::CallNode
+            return false if value.name.end_with?("@")
+
             !value.opening_loc.nil? ||
               (!value.receiver.nil? && value.arguments.nil?)
           else
@@ -445,6 +527,16 @@ module Audition
           )
         end
 
+        # A fresh container's elements are unknown, so the deep
+        # wrap is the fix, except for arrays of Integers.
+        def freeze_fresh(value)
+          if classifier.fresh_elements(value) == :shareable
+            append_freeze(value)
+          else
+            wrap_make_shareable(value)
+          end
+        end
+
         # Plain `.freeze` where every element is provably
         # shareable, the plain-Ruby shape; the deep wrap only
         # where a shallow freeze would not be enough.

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.rb

@@ -3,6 +3,7 @@
 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"
@@ -13,9 +14,9 @@ module Audition
   module Static
     module Checks
       BUILT_IN = [
-        DependencyClassState, GlobalVariables, MutableConstants,
-        RactorIsolation, RuntimeRequire, UnsafeCalls,
-        UnshareableReads
+        DependencyClassState, GlobalVariables, InstanceMemoization,
+        MutableConstants, RactorIsolation, RuntimeRequire,
+        UnsafeCalls, UnshareableReads
       ].freeze
 
       # Expression-level checks, run per file. Class variables and

data/lib/audition/static/graph_audit.rb

@@ -35,11 +35,25 @@ module Audition
         "per-subclass values compute in the inherited hook " \
         "(guard on subclass.name for anonymous classes). For " \
         "collections, rebuild and refreeze on write, " \
-        "copy-on-write: self.list = " \
-        "(list + [item]).freeze; never mutate in place. As a " \
-        "last resort use Ractor.store_if_absent for " \
-        "per-Ractor state, or read the ivar first and proxy " \
-        "the write to the main Ractor."
+        "copy-on-write: self.list = (list + [item]).freeze " \
+        "when every element is shareable, self.list = " \
+        "Ractor.make_shareable(list + [item]) when the " \
+        "additions may be unfrozen, since a plain freeze is " \
+        "shallow; never mutate in place. As a last resort use " \
+        "Ractor.store_if_absent for per-Ractor state, or read " \
+        "the ivar first and proxy the write to the main Ractor."
+      PROXIED_WHY =
+        "The read is the lock-free fast path and the write runs " \
+        "on the main Ractor through on_main, so no non-main " \
+        "Ractor ever writes class state. Every worker waiting " \
+        "on main serializes there, and a worker's next read " \
+        "raises Ractor::IsolationError unless the memoized " \
+        "value is shareable."
+      PROXIED_FIX =
+        "Keep the hatch rare: delete the memo or warm it at " \
+        "boot where possible, and make the computed value " \
+        "deeply frozen inside the block (.freeze or " \
+        "Ractor.make_shareable) so workers can read it."
       FROZEN_MEMO_WHY =
         "Every write memoizes a shareable (frozen) value, so " \
         "non-main Ractors can read it once it has been " \
@@ -760,6 +774,7 @@ module Audition
             finding_at(
               defn,
               check: "class-level-state",
+              subject: "#{owner}/#{variable}",
               severity: :info,
               message: "frozen memoization #{variable} on " \
                        "#{owner}; warm it on the main Ractor",
@@ -770,16 +785,29 @@ module Audition
             finding_at(
               defn,
               check: "class-level-state",
+              subject: "#{owner}/#{variable}",
               severity: :warning,
               message: "best-effort frozen state #{variable} " \
                        "on #{owner}",
               why: BEST_EFFORT_WHY,
               fix: BEST_EFFORT_FIX
             )
+          when :proxied, :proxied_frozen
+            finding_at(
+              defn,
+              check: "class-level-state",
+              subject: "#{owner}/#{variable}",
+              severity: (verdict == :proxied) ? :warning : :info,
+              message: "memoization #{variable} on #{owner} " \
+                       "proxied to the main Ractor",
+              why: PROXIED_WHY,
+              fix: PROXIED_FIX
+            )
           else
             finding_at(
               defn,
               check: "class-level-state",
+              subject: "#{owner}/#{variable}",
               message: "class-level instance variable " \
                        "#{variable} on #{owner}",
               why: STATE_WHY,
@@ -817,7 +845,8 @@ module Audition
               fix: STATE_FIX,
               path: path,
               line: line,
-              source: source_line(path, line)
+              source: source_line(path, line),
+              subject: "#{owner}/@#{ivar}"
             )
           end
         end
@@ -855,7 +884,8 @@ module Audition
               fix: STATE_FIX,
               path: path,
               line: line,
-              source: source_line(path, line)
+              source: source_line(path, line),
+              subject: "#{owner}/@#{name}"
             )
           end
         end
@@ -920,7 +950,8 @@ module Audition
               fix: STATE_FIX,
               path: path,
               line: line,
-              source: source_line(path, line)
+              source: source_line(path, line),
+              subject: "#{owner}/#{ivar}"
             )
           end
         end
@@ -958,7 +989,8 @@ module Audition
               fix: STATE_FIX,
               path: path,
               line: line,
-              source: source_line(path, line)
+              source: source_line(path, line),
+              subject: "#{owner}/#{ivar}"
             )
           end
         end
@@ -1214,7 +1246,7 @@ module Audition
       end
 
       def finding_at(defn, check:, message:, why:, fix:,
-        severity: :error)
+        severity: :error, subject: nil)
         path = path_from_uri(defn.location.uri)
         line = defn.location.start_line + 1
         Finding.new(
@@ -1225,7 +1257,8 @@ module Audition
           fix: fix,
           path: path,
           line: line,
-          source: source_line(path, line)
+          source: source_line(path, line),
+          subject: subject
         )
       end
 
@@ -1308,7 +1341,10 @@ module Audition
 
       # Cross-file merge keeps the weakest promise: any dirty file
       # taints the group, and best-effort beats fully frozen.
-      VERDICT_RANK = {dirty: 0, best_effort: 1, frozen: 2}.freeze
+      VERDICT_RANK = {
+        dirty: 0, best_effort: 1, proxied: 2, proxied_frozen: 3,
+        frozen: 4
+      }.freeze
 
       def weaker_verdict(existing, verdict)
         return verdict unless existing
@@ -1321,6 +1357,9 @@ module Audition
         return :dirty if ops.any? { |op| op[:kind] == :other }
 
         memos = Rewriters::Memoization.memo_sites(ops)
+        if memos.any? && memos.all? { |m| m[:op][:proxied] }
+          return proxied_verdict(ops, memos, classifier)
+        end
         if memos.any?
           return group_frozen?(ops, classifier) ? :frozen : :dirty
         end
@@ -1340,6 +1379,22 @@ module Audition
         (all_safe && wrapped) ? :best_effort : :dirty
       end
 
+      # The read-then-proxy hatch, `@x || on_main(self) { @x ||= v }`:
+      # every write is a memo site inside the block, so the main
+      # Ractor performs it by construction, and the value decides
+      # between a note and a warning. A plain write elsewhere
+      # (a reset) is a worker-side write again.
+      def proxied_verdict(ops, memos, classifier)
+        memo_ops = memos.map { |memo| memo[:op] }
+        writes = ops.select { |op| op[:kind] == :write }
+        return :dirty unless (writes - memo_ops).empty?
+
+        frozen = memos.all? do |memo|
+          frozen_memo_value?(memo[:op][:node].value, classifier)
+        end
+        frozen ? :proxied_frozen : :proxied
+      end
+
       # Matches the emitted setter recipe:
       #   (Ractor.make_shareable(value) rescue value)
       def best_effort_value?(node)