audition 0.3.0 → 0.4.1

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

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Audition
+  module Static
+    module Checks
+      # Lazy memoization on an instance is harmless until the
+      # instance is frozen: Ractor.make_shareable freezes every
+      # object it reaches, and the next `@x ||=` raises FrozenError.
+      # Two shapes make the freeze provable from the class alone: an
+      # initialize that ends by freezing self (a value object), and a
+      # `freeze` override (the class expects to be frozen). In the
+      # first the memo can never run; in the second it must be
+      # warmed inside the override, before super, which is the
+      # compute-on-freeze pattern. Class-level memos belong to the
+      # graph audit.
+      class InstanceMemoization < Base
+        explain :memo_after_self_freeze,
+          severity: :error,
+          message: "instance memoization %{ivar} in #%{method} on " \
+                   "a class that freezes itself in initialize",
+          why: "The instance is frozen before any other method " \
+               "runs, so the first call writes an instance " \
+               "variable on a frozen object and raises " \
+               "FrozenError.",
+          fix: "Compute the value in initialize, before the " \
+               "freeze, and expose it with attr_reader; or drop " \
+               "the memo and recompute on each call."
+
+        explain :memo_not_warmed,
+          severity: :warning,
+          message: "freeze override leaves %{ivar} cold; " \
+                   "#%{method} memoizes it lazily",
+          why: "Ractor.make_shareable calls freeze, so an " \
+               "instance frozen through this override raises " \
+               "FrozenError the first time #%{method} runs " \
+               "afterwards.",
+          fix: "Warm it in the override: call #%{method} (or " \
+               "assign %{ivar}) before super, the " \
+               "compute-on-freeze pattern; or compute it in " \
+               "initialize."
+
+        def initialize(file)
+          super
+          @contexts = []
+          @sclass_depth = 0
+        end
+
+        def visit_class_node(node) = scoped { super }
+
+        def visit_module_node(node) = scoped { super }
+
+        def visit_singleton_class_node(node)
+          @sclass_depth += 1
+          super
+        ensure
+          @sclass_depth -= 1
+        end
+
+        # Only plain instance methods count; a def is not entered,
+        # so nothing inside a method body opens a context.
+        def visit_def_node(node)
+          context = @contexts.last
+          return unless context && node.receiver.nil? &&
+            @sclass_depth.zero?
+
+          record_method(context, node)
+        end
+
+        private
+
+        def scoped
+          @contexts.push(
+            {memos: {}, methods: {}, self_freeze: false, warm: nil}
+          )
+          saved = @sclass_depth
+          @sclass_depth = 0
+          yield
+        ensure
+          @sclass_depth = saved
+          report(@contexts.pop)
+        end
+
+        def record_method(context, node)
+          case node.name
+          when :initialize
+            context[:self_freeze] = self_freezing?(node)
+          when :freeze
+            context[:warm] = touched_by(node)
+          else
+            context[:methods][node.name] ||= touched_by(node)
+            memo_sites(node).each do |ivar, write|
+              context[:memos][ivar] ||= {method: node.name, node: write}
+            end
+          end
+        end
+
+        def report(context)
+          memos = context[:memos]
+          return if memos.empty?
+
+          if context[:self_freeze]
+            memos.each do |ivar, memo|
+              flag(memo[:node], :memo_after_self_freeze,
+                ivar: ivar, method: memo[:method])
+            end
+          elsif context[:warm]
+            reached, warmed = warmed_closure(context)
+            memos.each do |ivar, memo|
+              next if reached.include?(memo[:method]) ||
+                warmed.include?(ivar)
+
+              flag(memo[:node], :memo_not_warmed,
+                ivar: ivar, method: memo[:method])
+            end
+          end
+        end
+
+        # Everything the override reaches through the class's own
+        # instance methods: a memo is warm when its method runs on
+        # the way, or when any method on the way assigns its ivar.
+        def warmed_closure(context)
+          methods = context[:methods]
+          reached = []
+          warmed = context[:warm][:ivars].dup
+          queue = context[:warm][:calls].dup
+          until queue.empty?
+            name = queue.shift
+            next if reached.include?(name)
+
+            reached << name
+            touched = methods[name] or next
+
+            warmed.concat(touched[:ivars])
+            queue.concat(touched[:calls])
+          end
+          [reached, warmed]
+        end
+
+        # initialize ends with `freeze`, `self.freeze`, or
+        # `Ractor.make_shareable(self)`.
+        def self_freezing?(node)
+          last = statements_of(node.body)&.last
+          return false unless last.is_a?(Prism::CallNode)
+
+          receiver = last.receiver
+          if last.name == :freeze
+            (receiver.nil? || receiver.is_a?(Prism::SelfNode)) &&
+              last.arguments.nil?
+          elsif last.name == :make_shareable
+            last.arguments&.arguments&.first.is_a?(Prism::SelfNode)
+          else
+            false
+          end
+        end
+
+        def statements_of(body)
+          case body
+          when Prism::StatementsNode then body.body
+          when Prism::BeginNode then body.statements&.body
+          end
+        end
+
+        # The methods a body calls on self and the ivars it assigns.
+        def touched_by(node)
+          calls = []
+          ivars = []
+          each_descendant(node.body) do |child|
+            case child
+            when Prism::CallNode
+              receiver = child.receiver
+              if receiver.nil? || receiver.is_a?(Prism::SelfNode)
+                calls << child.name
+              end
+            when Prism::InstanceVariableWriteNode,
+                 Prism::InstanceVariableOrWriteNode
+              ivars << child.name.to_s
+            end
+          end
+          {calls: calls, ivars: ivars}
+        end
+
+        # `@x ||= v`, and `@x = v` guarded by `defined?(@x)` in the
+        # same method.
+        def memo_sites(node)
+          or_writes = []
+          writes = {}
+          guarded = []
+          each_descendant(node.body) do |child|
+            case child
+            when Prism::InstanceVariableOrWriteNode
+              or_writes << [child.name.to_s, child]
+            when Prism::InstanceVariableWriteNode
+              writes[child.name.to_s] ||= child
+            when Prism::DefinedNode
+              value = child.value
+              if value.is_a?(Prism::InstanceVariableReadNode)
+                guarded << value.name.to_s
+              end
+            end
+          end
+          guarded.each do |ivar|
+            or_writes << [ivar, writes[ivar]] if writes[ivar]
+          end
+          or_writes
+        end
+
+        # Blocks and lambdas inside a method still write self's
+        # ivars; a nested def or class does not.
+        def each_descendant(node)
+          queue = [node].compact
+          until queue.empty?
+            current = queue.shift
+            yield current
+            current.compact_child_nodes.each do |child|
+              next if child.is_a?(Prism::DefNode) ||
+                child.is_a?(Prism::ClassNode) ||
+                child.is_a?(Prism::ModuleNode)
+
+              queue << child
+            end
+          end
+        end
+      end
+    end
+  end
+end

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,
@@ -103,6 +134,44 @@ module Audition
                "or drop the default proc and fetch with a " \
                "literal default: hash.fetch(key, [])."
 
+        explain :unshareable_instance,
+          severity: :warning,
+          message: "constant %{name} holds an unfrozen %{klass} " \
+                   "instance",
+          why: "A fresh instance is unfrozen, so non-main " \
+               "Ractors raise Ractor::IsolationError reading " \
+               "it. A warning, not an error: .new can be " \
+               "overridden to return a shareable value.",
+          fix: "Freeze it when deeply immutable, wrap in " \
+               "Ractor.make_shareable, or keep a per-Ractor " \
+               "copy via Ractor.store_if_absent."
+
+        explain :shallow_opaque,
+          severity: :warning,
+          message: "constant %{name} is frozen at the top level " \
+                   "only; what it holds is unproven",
+          why: "Freezing is shallow: elements and instance " \
+               "variables stay as their calls returned them, and " \
+               "unless those are deeply frozen a non-main Ractor " \
+               "reading the constant raises " \
+               "Ractor::IsolationError. The dynamic probe settles " \
+               "it when the target boots.",
+          fix: "Build the value with Ractor.make_shareable for a " \
+               "deep freeze, or silence a known-shareable value " \
+               "with a disable comment."
+
+        explain :opaque_constant,
+          severity: :warning,
+          message: "constant %{name} holds the result of " \
+                   "%{method}; shareability unproven",
+          why: "Unless the call returns a deeply frozen value, " \
+               "non-main Ractors raise Ractor::IsolationError " \
+               "reading the constant. The dynamic probe settles " \
+               "it when the target boots.",
+          fix: "Freeze the result at definition time, or " \
+               "silence a known-shareable value with a disable " \
+               "comment."
+
         explain :constant_mutation,
           severity: :warning,
           message: "in-place %{method} on constant %{name}",
@@ -115,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)
@@ -152,6 +225,10 @@ module Audition
           # finding stays, the autofix goes.
           fix_ok = !mutated?(name) && !customized?(name)
           kind = classifier.classify(value)
+          # A Sorbet cast returns its argument and a begin
+          # block its last statement: fixes, type names and
+          # depth checks target the value inside.
+          value = classifier.unwrap(value)
           # Build-then-freeze: a bare `NAME.freeze` later in the
           # same body makes the literal as good as frozen, so
           # only provably mutable elements remain to report.
@@ -171,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:
@@ -195,6 +285,20 @@ module Audition
               autofix: wrappable ? wrap_make_shareable(value) : nil)
           when :default_proc
             flag(node, :hash_default_proc, name: name)
+          when :shallow_opaque
+            flag(node, :shallow_opaque, name: name)
+          # Build-then-freeze leaves depth unknown: stay silent.
+          when :instance_new
+            unless frozen_later?(name)
+              flag(node, :unshareable_instance, name: name,
+                klass:
+                  classifier.const_name(value.receiver) || "new")
+            end
+          when :opaque_call
+            unless frozen_later?(name)
+              flag(node, :opaque_constant, name: name,
+                method: opaque_display(value))
+            end
           end
         end
 
@@ -298,25 +402,72 @@ 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)
+          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
+        # fallback names only the method.
+        def opaque_display(call)
           owner = classifier.const_name(call.receiver)
-          owner ? "#{owner}.#{call.name}" : "String##{call.name}"
+          method =
+            if owner
+              "#{owner}.#{call.name}"
+            elsif call.receiver
+              ".#{call.name}"
+            else
+              call.name.to_s
+            end
+          "a #{method} call"
         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,
@@ -325,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
@@ -374,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.