audition 0.1.0 → 0.2.0

data/lib/audition/rewriters.rb

@@ -15,10 +15,14 @@ module Audition
       FSL_LINE = "# frozen_string_literal: true\n"
 
       # `shareable_constant_value: literal` raises at load for
-      # non-literal constant values (verified on 4.0), so it is only
-      # planned when every constant assignment in the file
-      # classifies as a literal. Otherwise, if the flagged values
-      # are all strings, frozen_string_literal covers them.
+      # non-literal constant values (verified on 4.0), so it is
+      # only planned when every constant assignment in the file is
+      # a literal all the way down: an array literal holding a
+      # local or a call (Racc-generated parser tables are the
+      # canonical case) becomes an unshareable value that the
+      # magic comment rejects at load time. Otherwise, if the
+      # flagged values are all strings, frozen_string_literal
+      # covers them.
       def self.plan(file, findings)
         return nil if file.shareable_constants?
         return nil if findings.none? { |f| f.check == "mutable-constants" }
@@ -26,13 +30,13 @@ module Audition
         classifier = Static::LiteralClassifier.new(
           frozen_string_literal: file.frozen_string_literal?
         )
-        kinds = constant_values(file).map { |v| classifier.classify(v) }
+        values = constant_values(file)
+        kinds = values.map { |v| classifier.classify(v) }
         flagged = kinds.reject do |k|
           %i[shareable unknown].include?(k)
         end
-        scv_ok = kinds.all? do |k|
-          %i[shareable mutable_string mutable_container
-            shallow_freeze].include?(k)
+        scv_ok = values.all? do |value|
+          deep_literal?(value, classifier)
         end
 
         if scv_ok
@@ -43,6 +47,30 @@ module Audition
         end
       end
 
+      # Bare literals only: `[...].freeze` is a method call, and
+      # under the magic comment Ruby raises for it at assignment
+      # because the shallowly-frozen value is unshareable
+      # (verified on 4.0 with jwt's NAMED_CURVES).
+      def self.deep_literal?(node, classifier)
+        case node
+        when Prism::ArrayNode
+          node.elements.all? do |element|
+            deep_literal?(element, classifier)
+          end
+        when Prism::HashNode, Prism::KeywordHashNode
+          node.elements.all? do |element|
+            element.is_a?(Prism::AssocNode) &&
+              deep_literal?(element.key, classifier) &&
+              deep_literal?(element.value, classifier)
+          end
+        when Prism::CallNode
+          false
+        else
+          %i[shareable mutable_string]
+            .include?(classifier.classify(node))
+        end
+      end
+
       def self.comment_plan(file, line)
         offset = file.magic_insertion_offset
         {
@@ -74,7 +102,7 @@ module Audition
           visit_constant_path_write_node
           visit_constant_path_or_write_node
         ].each do |method|
-          define_method(method) do |node|
+          define_method(method) do |node| # audition:disable unsafe-calls
             @values << node.value
             super(node)
           end
@@ -84,15 +112,31 @@ module Audition
 
     # -- class-level memoization -------------------------------------
 
-    # Rewrites singleton-scope ivar state to Ractor-local storage:
+    # Rewrites singleton-scope memoization, both idioms:
+    #   @x ||= expr
+    #   return @x if defined?(@x); @x = expr
+    #
+    # Preferred strategy is freeze-on-memoize, the pattern Rails
+    # core applies to its own code: the memoization stays exactly
+    # as written and only the memoized value becomes shareable
+    # (`.freeze` appended; Ractor.make_shareable for containers).
+    # Non-main Ractors may then read the ivar once it has been
+    # computed; the first write must still happen on the main
+    # Ractor, which is a boot-warming concern the static check
+    # reports as an info note. Chosen when the value expression
+    # carries no block (a proxy for one-time side effects) and no
+    # writes exist outside the memo sites.
+    #
+    # Otherwise falls back to Ractor-local storage:
     #   @x ||= expr   ->  Ractor.store_if_absent(:"Klass/@x") { expr }
     #   @x = expr     ->  Ractor.current[:"Klass/@x"] = expr
     #   @x            ->  Ractor.current[:"Klass/@x"]
+    #
     # Only when every reference in singleton scope is visible in
     # this file, none sit directly in the class body, and no
-    # compound writes exist. Caveat (why this is unsafe): each
-    # Ractor computes its own copy, and store_if_absent treats a
-    # stored nil as present where ||= would recompute.
+    # compound writes exist. Caveat (why this is unsafe): freezing
+    # changes value mutability, and each Ractor computes its own
+    # copy under store_if_absent.
     module Memoization
       def self.plan(file, findings)
         return [] if findings.none? { |f| f.check == "class-level-state" }
@@ -104,42 +148,267 @@ module Audition
           next if namespace.empty?
 
           kinds = ops.map { |op| op[:kind] }
-          next unless kinds.include?(:or_write)
           next if kinds.include?(:other)
           next if ops.any? { |op| op[:body] }
 
-          key = %(:"#{namespace}/#{name}")
-          ops.each { |op| edits << edit_for(op, key) }
+          memos = memo_sites(ops)
+          next if memos.empty?
+          next if orphan_guards?(ops, memos)
+          next if guarded_with_strays?(ops, memos)
+          # `@x ||= {}` is a lazily-built accumulator, mutated
+          # through the accessor after memoization (jwt's
+          # algorithm registry). Freezing it breaks registration
+          # and Ractor-local copies would leave other Ractors an
+          # empty registry; the copy-on-write refactor is human
+          # work, so no edit is offered.
+          next if memos.any? { |m| accumulator?(m[:op][:node].value) }
+
+          if freezable?(ops, memos)
+            edits.concat(freeze_edits(file, memos))
+          else
+            key = %(:"#{namespace}/#{name}")
+            edits.concat(ractor_edits(file, ops, memos, key))
+          end
         end
         edits
       end
 
-      def self.edit_for(op, key)
-        node = op[:node]
-        case op[:kind]
-        when :or_write
-          value = node.value.location.slice
-          Autofix.new(
-            start_offset: node.location.start_offset,
-            end_offset: node.location.end_offset,
-            replacement:
-              "Ractor.store_if_absent(#{key}) { #{value} }",
-            safety: :unsafe
-          )
-        when :write
-          Autofix.new(
-            start_offset: node.name_loc.start_offset,
-            end_offset: node.name_loc.end_offset,
-            replacement: "Ractor.current[#{key}]",
-            safety: :unsafe
-          )
-        when :read
-          Autofix.new(
-            start_offset: node.location.start_offset,
-            end_offset: node.location.end_offset,
-            replacement: "Ractor.current[#{key}]",
-            safety: :unsafe
-          )
+      # A memo site is an ||= write, or a plain write paired with a
+      # defined? return guard inside the same method. A guarded
+      # method with more than one write is nobody's memoization;
+      # such groups are dropped by the orphan check below.
+      def self.memo_sites(ops)
+        guards = ops.select { |op| op[:kind] == :guard }
+        ops.filter_map do |op|
+          case op[:kind]
+          when :or_write
+            {op: op, guard: nil}
+          when :write
+            guard = guards.find { |g| g[:def_id] == op[:def_id] }
+            {op: op, guard: guard} if guard
+          end
+        end
+      end
+
+      def self.accumulator?(value)
+        (value.is_a?(Prism::ArrayNode) ||
+          value.is_a?(Prism::HashNode)) && value.elements.empty?
+      end
+
+      def self.guarded_with_strays?(ops, memos)
+        return false if memos.none? { |memo| memo[:guard] }
+
+        memo_ops = memos.map { |memo| memo[:op] }
+        ops.any? do |op|
+          op[:kind] == :write && !memo_ops.include?(op)
+        end
+      end
+
+      def self.orphan_guards?(ops, memos)
+        used = memos.filter_map { |m| m[:guard] }
+        guards = ops.select { |op| op[:kind] == :guard }
+        return true if guards.size != used.size
+
+        writes = ops.select { |op| op[:kind] == :write }
+        guards.any? do |guard|
+          writes.count { |w| w[:def_id] == guard[:def_id] } != 1
+        end
+      end
+
+      # Freeze-on-memoize applies when every write is a memo site
+      # (a stray write means cache invalidation; frozen values
+      # cannot support that) and no value needs a block to build.
+      def self.freezable?(ops, memos)
+        memo_ops = memos.map { |memo| memo[:op] }
+        writes = ops.select { |op| op[:kind] == :write }
+        return false unless (writes - memo_ops).empty?
+
+        memos.all? { |memo| blockless?(memo[:op][:node].value) }
+      end
+
+      def self.blockless?(node)
+        queue = [node]
+        until queue.empty?
+          current = queue.shift
+          if current.is_a?(Prism::BlockNode) ||
+              current.is_a?(Prism::LambdaNode)
+            return false
+          end
+          queue.concat(current.child_nodes.compact)
+        end
+        true
+      end
+
+      # One edit per memo site: make the memoized value shareable
+      # while leaving the memoization intact. Guards, sibling
+      # reads, and method shapes stay untouched.
+      def self.freeze_edits(file, memos)
+        classifier = Static::LiteralClassifier.new(
+          frozen_string_literal: file.frozen_string_literal?
+        )
+        memos.filter_map do |memo|
+          value = memo[:op][:node].value
+          freeze_value(value, classifier.classify(value))
+        end
+      end
+
+      # Plain `.freeze` only where the value is provably a string;
+      # everything unproven gets Ractor.make_shareable, which is a
+      # no-op for already-shareable values. This matters for
+      # memoized classes (multi_json memoizes adapter classes):
+      # `.freeze` on a Class freezes the class object and later
+      # ivar writes on it raise FrozenError.
+      def self.freeze_value(value, kind)
+        return nil if kind == :shareable
+        # Freezing or wrapping a sync primitive raises; leave the
+        # finding in place for a human.
+        return nil if kind == :sync_primitive
+        return nil if frozen_call?(value)
+
+        slice = value.location.slice
+        replacement =
+          if kind == :mutable_string
+            parens?(value) ? "(#{slice}).freeze" : "#{slice}.freeze"
+          else
+            "Ractor.make_shareable(#{slice})"
+          end
+        Autofix.new(
+          start_offset: value.location.start_offset,
+          end_offset: value.location.end_offset,
+          replacement: replacement,
+          safety: :unsafe
+        )
+      end
+
+      def self.frozen_call?(value)
+        value.is_a?(Prism::CallNode) &&
+          value.name == :freeze &&
+          value.receiver && value.arguments.nil?
+      end
+
+      # `.freeze` binds tighter than operators and ternaries, so
+      # compound expressions get wrapped; message sends and plain
+      # literals do not need it.
+      def self.parens?(value)
+        case value
+        when Prism::CallNode
+          !value.name.to_s.match?(/\A[a-z_]/i)
+        when Prism::StringNode, Prism::InterpolatedStringNode,
+             Prism::ArrayNode, Prism::HashNode,
+             Prism::ConstantReadNode, Prism::ConstantPathNode
+          false
+        else
+          true
+        end
+      end
+
+      # Two Ractor-local flavors. With stray writes present (cache
+      # invalidation, `@x = nil`), memo sites become
+      # `Ractor.current[key] ||= expr`: it recomputes after a nil
+      # reset exactly like the original `||=`, where
+      # store_if_absent would treat the stored nil as present and
+      # never recompute (this broke i18n's reserved_keys_pattern).
+      # Without strays, store_if_absent keeps its atomic lazy
+      # init. Guard-idiom groups with strays are skipped entirely
+      # in plan: the defined? guard caches nil deliberately and
+      # neither flavor reproduces that alongside invalidation.
+      def self.ractor_edits(file, ops, memos, key)
+        guarded = memos.filter_map { |m| m[:op] if m[:guard] }
+        memo_ops = memos.map { |memo| memo[:op] }
+        strays = ops.any? do |op|
+          op[:kind] == :write && !memo_ops.include?(op)
+        end
+        edits = memos.filter_map do |memo|
+          deletion(file.source, memo[:guard][:node]) if memo[:guard]
+        end
+        ops.each do |op|
+          node = op[:node]
+          edits <<
+            if op[:kind] == :or_write || guarded.include?(op)
+              replacement =
+                if strays
+                  value = node.value.location.slice
+                  "Ractor.current[#{key}] ||= #{value}"
+                else
+                  store_wrap(file.source, node, key)
+                end
+              Autofix.new(
+                start_offset: node.location.start_offset,
+                end_offset: node.location.end_offset,
+                replacement: replacement,
+                safety: :unsafe
+              )
+            elsif op[:kind] == :write
+              Autofix.new(
+                start_offset: node.name_loc.start_offset,
+                end_offset: node.name_loc.end_offset,
+                replacement: "Ractor.current[#{key}]",
+                safety: :unsafe
+              )
+            else
+              Autofix.new(
+                start_offset: node.location.start_offset,
+                end_offset: node.location.end_offset,
+                replacement: "Ractor.current[#{key}]",
+                safety: :unsafe
+              )
+            end
+        end
+        edits
+      end
+
+      # A single-line value keeps the brace form; a multi-line
+      # value becomes a do..end block with the body shifted one
+      # level right, so the rewrite stays idiomatic. When the write
+      # shares its line with other code, layout cannot be inferred
+      # and the brace form is kept as-is.
+      def self.store_wrap(source, node, key)
+        value = node.value.location.slice
+        call = "Ractor.store_if_absent(#{key})"
+        return "#{call} { #{value} }" unless value.include?("\n")
+
+        raw = source.dup.force_encoding(Encoding::BINARY)
+        from = node.location.start_offset
+        start = from.zero? ? 0 : (raw.rindex("\n", from - 1) || -1) + 1
+        indent = raw[start...from].force_encoding(source.encoding)
+        return "#{call} { #{value} }" unless indent.match?(/\A[ \t]*\z/)
+
+        body = value.lines.map.with_index do |line, index|
+          if index.zero?
+            "#{indent}  #{line}"
+          elsif line.match?(/\A\s*\z/)
+            line
+          else
+            "  #{line}"
+          end
+        end.join
+        "#{call} do\n#{body}\n#{indent}end"
+      end
+
+      # Deletes the guard statement together with its line and any
+      # blank lines that follow, so the method body does not open
+      # with a hole. Falls back to the bare node span when other
+      # code shares the line.
+      def self.deletion(source, node)
+        raw = source.dup.force_encoding(Encoding::BINARY)
+        from = node.location.start_offset
+        upto = node.location.end_offset
+        start = from.zero? ? 0 : (raw.rindex("\n", from - 1) || -1) + 1
+        if raw[start...from].match?(/\A[ \t]*\z/n)
+          newline = raw.index("\n", upto)
+          stop = newline ? newline + 1 : raw.length
+          loop do
+            newline = raw.index("\n", stop)
+            break unless newline
+            break unless raw[stop...newline].match?(/\A[ \t]*\z/n)
+
+            stop = newline + 1
+          end
+          Autofix.new(start_offset: start, end_offset: stop,
+            replacement: "", safety: :unsafe)
+        else
+          Autofix.new(start_offset: from, end_offset: upto,
+            replacement: "", safety: :unsafe)
         end
       end
 
@@ -188,12 +457,28 @@ module Audition
         def visit_def_node(node)
           kind =
             node.receiver.is_a?(Prism::SelfNode) ? :self : :plain
-          @def_stack.push(kind)
+          @def_stack.push(
+            {kind: kind, id: node.object_id, name: node.name}
+          )
           super
         ensure
           @def_stack.pop
         end
 
+        # Matches the guard statement of the second memoization
+        # idiom: `return @x if defined?(@x)`. On a match the inner
+        # reads are not visited (they belong to the guard, not to
+        # the data flow) and the whole statement is recorded so the
+        # planner can delete it.
+        def visit_if_node(node)
+          name = guard_name(node)
+          if name
+            record(node, :guard, name)
+          else
+            super
+          end
+        end
+
         {
           visit_instance_variable_read_node: :read,
           visit_instance_variable_write_node: :write,
@@ -202,22 +487,46 @@ module Audition
           visit_instance_variable_and_write_node: :other,
           visit_instance_variable_target_node: :other
         }.each do |method, kind|
-          define_method(method) do |node|
-            record(node, kind)
+          define_method(method) do |node| # audition:disable unsafe-calls
+            record(node, kind, node.name)
             super(node)
           end
         end
 
         private
 
-        def record(node, kind)
+        def guard_name(node)
+          predicate = node.predicate
+          return unless predicate.is_a?(Prism::DefinedNode)
+
+          checked = predicate.value
+          return unless checked.is_a?(Prism::InstanceVariableReadNode)
+          return if node.subsequent
+
+          body = node.statements&.body
+          return unless body && body.size == 1
+          return unless body[0].is_a?(Prism::ReturnNode)
+
+          returned = body[0].arguments&.arguments
+          return unless returned && returned.size == 1
+          return unless returned[0]
+            .is_a?(Prism::InstanceVariableReadNode)
+          return unless returned[0].name == checked.name
+
+          checked.name
+        end
+
+        def record(node, kind, name)
           return if @namespace.empty?
 
-          in_def = !@def_stack.empty?
+          current_def = @def_stack.last
           singleton_method =
-            @def_stack.last == :self ||
-            (@def_stack.last == :plain && @sclass_depth.positive?)
-          if in_def
+            current_def && (
+              current_def[:kind] == :self ||
+              (current_def[:kind] == :plain &&
+                @sclass_depth.positive?)
+            )
+          if current_def
             return unless singleton_method
 
             body = false
@@ -225,8 +534,12 @@ module Audition
             body = true
           end
 
-          key = [@namespace.join("::"), node.name.to_s]
-          @groups[key] << {node: node, kind: kind, body: body}
+          key = [@namespace.join("::"), name.to_s]
+          @groups[key] << {
+            node: node, kind: kind, body: body,
+            def_id: current_def && current_def[:id],
+            def_name: current_def && current_def[:name]
+          }
         end
       end
     end
@@ -276,7 +589,10 @@ module Audition
           next unless (ops - writes).all? { |op| op[:kind] == :read }
 
           write = writes[0][:node]
-          shareable = classifier.classify(write.value) == :shareable
+          kind = classifier.classify(write.value)
+          next if kind == :sync_primitive
+
+          shareable = kind == :shareable
           # A mutable value that would get deep-frozen must never be
           # the receiver of a call afterwards: `X[k] = v`, `X << v`
           # and friends would raise FrozenError at runtime. Reads of
@@ -418,14 +734,14 @@ module Audition
         }.freeze
 
         GVAR_NODES.each do |method, kind|
-          define_method(method) do |node|
+          define_method(method) do |node| # audition:disable unsafe-calls
             record_gvar(node, kind) if @mode == :gvar
             super(node)
           end
         end
 
         CVAR_NODES.each do |method, kind|
-          define_method(method) do |node|
+          define_method(method) do |node| # audition:disable unsafe-calls
             record_cvar(node, kind) if @mode == :cvar
             super(node)
           end

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

@@ -71,10 +71,42 @@ module Audition
                "it isolates self-contained lambdas; or " \
                "promote the logic to a method."
 
+        explain :hash_default_proc,
+          severity: :error,
+          message: "constant %{name} holds a Hash with a " \
+                   "default proc",
+          why: "The default block is a Proc baked into the " \
+               "Hash, and freezing the Hash does not make " \
+               "the block shareable; a non-main Ractor " \
+               "reading this constant raises " \
+               "Ractor::IsolationError. Rails removed this " \
+               "pattern twice during its ractorization.",
+          fix: "Use a plain frozen Hash with explicit keys, " \
+               "or drop the default proc and fetch with a " \
+               "literal default: hash.fetch(key, [])."
+
+        explain :constant_mutation,
+          severity: :warning,
+          message: "in-place %{method} on constant %{name}",
+          why: "A constant mutated after load is shared " \
+               "mutable state: non-main Ractors raise " \
+               "Ractor::IsolationError reading it while " \
+               "unfrozen, and freezing it turns this call " \
+               "into a FrozenError.",
+          fix: "Build the complete value at load time and " \
+               "freeze it (each_with_object then .freeze), " \
+               "or move the registry behind a writer that " \
+               "rebuilds and refreezes on each change, the " \
+               "copy-on-write style Rails registries use."
+
         on :constant_write_node, :constant_or_write_node do |node|
           examine(node.name.to_s, node, node.value)
         end
 
+        on :call_node do |node|
+          flag_constant_mutation(node)
+        end
+
         on :constant_path_write_node,
           :constant_path_or_write_node do |node|
           examine(node.target.location.slice, node, node.value)
@@ -90,18 +122,55 @@ module Audition
             flag(node, :mutable_string, name: name,
               autofix: append_freeze(value))
           when :mutable_container
-            type = value.is_a?(Prism::HashNode) ? "Hash" : "Array"
-            flag(node, :mutable_container, name: name, type: type,
+            flag(node, :mutable_container, name: name,
+              type: container_type(value),
               autofix: wrap_make_shareable(value))
           when :shallow_freeze
             flag(node, :shallow_freeze, name: name,
               autofix: replace_with_make_shareable(value))
           when :sync_primitive
+            klass = value.is_a?(Prism::CallNode) &&
+              classifier.const_name(value.receiver)
             flag(node, :sync_primitive, name: name,
-              klass: classifier.const_name(value.receiver))
+              klass: klass || "sync primitive")
           when :proc
             flag(node, :proc_constant, name: name,
               autofix: wrap_make_shareable(value))
+          when :default_proc
+            flag(node, :hash_default_proc, name: name)
+          end
+        end
+
+        # Mutators that read as data mutation, not as class-level
+        # method names (delete/update/store would collide with
+        # Active Record class methods). Screaming-case receivers
+        # only: `RENDERERS << x` is a registry mutation, while
+        # `User << x` is a class method call.
+        MUTATORS = Ractor.make_shareable(
+          %i[[]= << push unshift concat merge! replace]
+        )
+
+        def flag_constant_mutation(node)
+          return unless MUTATORS.include?(node.name)
+
+          name = classifier.const_name(node.receiver)
+          return unless name
+          return if name == "ENV"
+          return unless name.split("::").last
+            .match?(/\A[A-Z][A-Z0-9_]*\z/)
+
+          flag(node, :constant_mutation, name: name,
+            method: node.name.to_s)
+        end
+
+        def container_type(value)
+          case value
+          when Prism::HashNode, Prism::KeywordHashNode then "Hash"
+          when Prism::ArrayNode then "Array"
+          when Prism::CallNode
+            classifier.const_name(value.receiver) || "container"
+          else
+            "container"
           end
         end
 
@@ -111,13 +180,26 @@ module Audition
           )
         end
 
+        # Ternaries classify as strings when both branches are;
+        # `.freeze` binds tighter than `?:`, so they get parens.
         def append_freeze(value)
-          offset = value.location.end_offset
-          Autofix.new(
-            start_offset: offset,
-            end_offset: offset,
-            replacement: ".freeze"
-          )
+          string = value.is_a?(Prism::StringNode) ||
+            value.is_a?(Prism::InterpolatedStringNode)
+          if string
+            offset = value.location.end_offset
+            Autofix.new(
+              start_offset: offset,
+              end_offset: offset,
+              replacement: ".freeze"
+            )
+          else
+            source = value.location.slice
+            Autofix.new(
+              start_offset: value.location.start_offset,
+              end_offset: value.location.end_offset,
+              replacement: "(#{source}).freeze"
+            )
+          end
         end
 
         def wrap_make_shareable(value)

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

@@ -93,7 +93,7 @@ module Audition
             visit_local_variable_and_write_node
             visit_local_variable_target_node
           ].each do |method|
-            define_method(method) do |node|
+            define_method(method) do |node| # audition:disable unsafe-calls
               @names << node.name.to_s if node.depth > @level
               super(node)
             end