audition 0.1.0 → 0.2.0

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

@@ -39,12 +39,15 @@ module Audition
           if node.receiver.nil?
             if REQUIRE_METHODS.include?(node.name) && inside_def?
               unless hoisted_already?(node)
+                autofix = rescued? ? nil : hoist_autofix(node)
                 flag(node, :runtime_require, method: node.name,
-                  autofix: hoist_autofix(node))
+                  autofix: autofix)
               end
             elsif node.name == :autoload
-              flag(node, :autoload,
-                autofix: require_conversion_autofix(node))
+              unless eagerly_loaded?(node)
+                flag(node, :autoload,
+                  autofix: require_conversion_autofix(node))
+              end
             end
           end
         end
@@ -56,12 +59,40 @@ module Audition
           @def_depth -= 1
         end
 
+        # A require under a rescue is conditional by construction
+        # (optional dependencies, tzinfo's tzinfo-data); hoisting
+        # it to an unguarded top-level require breaks every
+        # installation without the feature.
+        def visit_begin_node(node)
+          if node.rescue_clause
+            @rescue_depth = rescue_depth + 1
+            begin
+              super
+            ensure
+              @rescue_depth -= 1
+            end
+          else
+            super
+          end
+        end
+
+        def visit_rescue_modifier_node(node)
+          @rescue_depth = rescue_depth + 1
+          super
+        ensure
+          @rescue_depth -= 1
+        end
+
         private
 
         def def_depth = @def_depth ||= 0
 
         def inside_def? = def_depth.positive?
 
+        def rescue_depth = @rescue_depth ||= 0
+
+        def rescued? = rescue_depth.positive?
+
         def literal_feature(node)
           return nil unless node.name == :require ||
             node.name == :require_relative
@@ -80,10 +111,12 @@ module Audition
             file.top_level_requires.include?(feature.unescaped)
         end
 
-        # Requiring is idempotent, so inserting a boot-time
-        # duplicate preserves semantics exactly while removing the
-        # runtime serialization. `load` is excluded: it re-executes
-        # on every call.
+        # Requiring is idempotent, so a boot-time duplicate leaves
+        # the method's behavior alone; but it does load the feature
+        # in every context, and files can be deliberately lazy
+        # (optional dependencies, i18n's test-DSL mixins), so this
+        # is unsafe tier. `load` is excluded: it re-executes on
+        # every call.
         def hoist_autofix(node)
           feature = literal_feature(node)
           return nil unless feature
@@ -93,11 +126,11 @@ module Audition
           statement = "#{node.name} #{feature.location.slice}"
           if insertion[:after_require]
             Autofix.new(start_offset: offset, end_offset: offset,
-              replacement: "#{statement}\n")
+              replacement: "#{statement}\n", safety: :unsafe)
           else
             offset += 1 if newline_at?(offset)
             Autofix.new(start_offset: offset, end_offset: offset,
-              replacement: "#{statement}\n\n")
+              replacement: "#{statement}\n\n", safety: :unsafe)
           end
         end
 
@@ -105,18 +138,68 @@ module Audition
           file.source.byteslice(offset, 1) == "\n"
         end
 
-        # Eager require is exactly the trade a Ractor deployment
-        # wants, but it changes load timing: unsafe tier.
-        def require_conversion_autofix(node)
+        # The eager conversion is only offered when the autoloaded
+        # feature resolves to a file inside the target itself and
+        # that file carries no optional-dependency guard: a
+        # `rescue LoadError` means the file is deliberately lazy
+        # (i18n's key_value backend), and a feature that does not
+        # resolve locally may not even be installed.
+        def convertible_feature?(feature)
+          candidate = resolve_locally(feature)
+          !candidate.nil? &&
+            !File.read(candidate).include?("rescue LoadError")
+        rescue SystemCallError
+          false
+        end
+
+        def resolve_locally(feature)
+          roots = [File.dirname(file.path)]
+          if (index = file.path.rindex("/lib/"))
+            roots << file.path[0, index + 4]
+          end
+          roots.filter_map { |root|
+            candidate = File.join(root, "#{feature}.rb")
+            candidate if File.file?(candidate)
+          }.first
+        end
+
+        def autoload_feature(node)
           args = node.arguments&.arguments
           return nil unless args&.size == 2 &&
             args[0].is_a?(Prism::SymbolNode) &&
             args[1].is_a?(Prism::StringNode)
 
+          args[1]
+        end
+
+        # An autoload whose feature is also required at the top
+        # level of the same file is eagerly loaded; the remaining
+        # registration is a harmless safety net.
+        def eagerly_loaded?(node)
+          feature = autoload_feature(node)
+          !feature.nil? &&
+            file.top_level_requires.include?(feature.unescaped)
+        end
+
+        # Eager require is exactly the trade a Ractor deployment
+        # wants, but it changes load timing: unsafe tier. The
+        # autoload line stays and the require lands at the end of
+        # the file, after every registration in it: requiring in
+        # registration order breaks mutual references (file A
+        # loads first, references B, whose registration was
+        # converted away), while a kept registration resolves any
+        # constant the eager load path touches.
+        def require_conversion_autofix(node)
+          feature = autoload_feature(node)
+          return nil unless feature
+          return nil unless convertible_feature?(feature.unescaped)
+
+          eof = file.source.bytesize
+          statement = "require #{feature.location.slice}\n"
           Autofix.new(
-            start_offset: node.location.start_offset,
-            end_offset: node.location.end_offset,
-            replacement: "require #{args[1].location.slice}",
+            start_offset: eof,
+            end_offset: eof,
+            replacement: statement,
             safety: :unsafe
           )
         end

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

@@ -83,6 +83,22 @@ module Audition
           fix: "Fork before spawning Ractors, or use " \
                "spawn/exec."
 
+        explain :define_method_closure,
+          severity: :warning,
+          message: "define_method carries its block as a Proc",
+          why: "Methods born from define_method keep the " \
+               "defining block; calling one from a non-main " \
+               "Ractor raises Ractor::IsolationError " \
+               "(\"defined with an un-shareable Proc\") " \
+               "unless the block was made shareable first.",
+          fix: "Generate the method with class_eval and a " \
+               "source string (how Rails fixed its autosave " \
+               "callbacks), or pass an isolated block: " \
+               "define_method(:x, " \
+               "&Ractor.make_shareable(proc { ... })). " \
+               "Isolated blocks cannot capture outer locals " \
+               "or use super."
+
         explain :singleton_include,
           severity: :warning,
           message: "include Singleton memoizes the instance " \
@@ -119,6 +135,7 @@ module Audition
         on :call_node do |node|
           apply_rules(node)
           flag_singleton_include(node)
+          flag_define_method(node)
         end
 
         private
@@ -149,6 +166,16 @@ module Audition
           end
         end
 
+        # Only literal blocks are flagged: `&SOMETHING` block
+        # pass-throughs are how isolated, pre-shared procs get
+        # attached, which is the sanctioned form.
+        def flag_define_method(node)
+          return unless node.name == :define_method
+          return unless node.block.is_a?(Prism::BlockNode)
+
+          flag(node, :define_method_closure)
+        end
+
         def flag_singleton_include(node)
           return unless node.name == :include && node.receiver.nil?
 

data/lib/audition/static/graph_audit.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "rubydex"
+require_relative "../rewriters"
 
 module Audition
   module Static
@@ -26,9 +27,27 @@ module Audition
         "it while it holds a non-shareable value (verified on " \
         "Ruby 4.0)."
       STATE_FIX =
-        "Precompute and freeze the value at load time, use " \
-        "Ractor.store_if_absent for lazy initialization, or keep " \
-        "per-Ractor state in Ractor.current[:key]."
+        "Precompute and freeze the value at load time (for " \
+        "per-subclass values, in the inherited hook). For " \
+        "collections, rebuild and refreeze on write, " \
+        "Rails-style copy-on-write: self.list = " \
+        "(list + [item]).freeze; never mutate in place. As a " \
+        "last resort use Ractor.store_if_absent for lazy " \
+        "initialization or per-Ractor state in " \
+        "Ractor.current[:key]."
+      FROZEN_MEMO_WHY =
+        "Every write memoizes a shareable (frozen) value, so " \
+        "non-main Ractors can read it once it has been " \
+        "computed; only the first write must happen on the " \
+        "main Ractor, or it raises Ractor::IsolationError. " \
+        "This is the pattern Rails core uses for its own " \
+        "memoized class state."
+      FROZEN_MEMO_FIX =
+        "Warm the cache at boot, before spawning Ractors: call " \
+        "the memoizing method from an initializer or on_load " \
+        "hook. If the value genuinely must be computed at " \
+        "runtime, proxy the write to the main Ractor or use " \
+        "Ractor.store_if_absent."
 
       # @param sources [Hash{String => String}] path => source
       # @return [Array<Finding>]
@@ -38,6 +57,7 @@ module Audition
           graph.index_source(path, code, "ruby")
         end
         @sources = sources
+        @frozen_memos = frozen_memo_map(sources)
         audit(graph)
       end
 
@@ -91,15 +111,28 @@ module Audition
 
         variable = decl.name.split("#").last
         owner = display_owner(decl.owner)
+        frozen = @frozen_memos["#{owner}/#{variable}"] == :frozen
         each_local_definition(decl).map do |defn|
-          finding_at(
-            defn,
-            check: "class-level-state",
-            message: "class-level instance variable #{variable} " \
-                     "on #{owner}",
-            why: STATE_WHY,
-            fix: STATE_FIX
-          )
+          if frozen
+            finding_at(
+              defn,
+              check: "class-level-state",
+              severity: :info,
+              message: "frozen memoization #{variable} on " \
+                       "#{owner}; warm it on the main Ractor",
+              why: FROZEN_MEMO_WHY,
+              fix: FROZEN_MEMO_FIX
+            )
+          else
+            finding_at(
+              defn,
+              check: "class-level-state",
+              message: "class-level instance variable " \
+                       "#{variable} on #{owner}",
+              why: STATE_WHY,
+              fix: STATE_FIX
+            )
+          end
         end
       end
 
@@ -109,12 +142,13 @@ module Audition
         end
       end
 
-      def finding_at(defn, check:, message:, why:, fix:)
+      def finding_at(defn, check:, message:, why:, fix:,
+        severity: :error)
         path = path_from_uri(defn.location.uri)
         line = defn.location.start_line + 1
         Finding.new(
           check: check,
-          severity: :error,
+          severity: severity,
           message: message,
           why: why,
           fix: fix,
@@ -124,6 +158,56 @@ module Audition
         )
       end
 
+      # Frozen memoization, the shape Rails core ships: every
+      # write to the ivar is a memo site (`@x ||=` or a defined?
+      # guard) whose value is provably shareable, either a frozen
+      # literal, an explicit `.freeze` or make_shareable call.
+      # Such state is read-safe from any Ractor once warmed, so
+      # the finding downgrades to an info note. Any stray write
+      # or unproven value keeps the error. Keys are
+      # "Owner::Path/@name"; a dirty verdict in any file wins.
+      def frozen_memo_map(sources)
+        map = {}
+        sources.each do |path, code|
+          file = SourceFile.new(source: code, path: path)
+          next unless file.valid_syntax?
+
+          collector = Rewriters::Memoization::SingletonIvars.new
+          collector.visit(file.root)
+          classifier = LiteralClassifier.new(
+            frozen_string_literal: file.frozen_string_literal?
+          )
+          collector.groups.each do |(namespace, name), ops|
+            key = "#{namespace}/#{name}"
+            verdict =
+              group_frozen?(ops, classifier) ? :frozen : :dirty
+            map[key] =
+              (map[key] == :dirty) ? :dirty : verdict
+          end
+        end
+        map
+      end
+
+      def group_frozen?(ops, classifier)
+        return false if ops.any? { |op| op[:body] }
+        return false if ops.any? { |op| op[:kind] == :other }
+
+        memos = Rewriters::Memoization.memo_sites(ops)
+        return false if memos.empty?
+        return false if
+          Rewriters::Memoization.orphan_guards?(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? do |memo|
+          value = memo[:op][:node].value
+          Rewriters::Memoization.frozen_call?(value) ||
+            classifier.classify(value) == :shareable
+        end
+      end
+
       # "Payments::<Payments>" reads as noise; show "Payments".
       def display_owner(owner)
         (owner&.name || "?").sub(/::<[^>]+>\z/, "")

data/lib/audition/static/literal_classifier.rb

@@ -7,10 +7,12 @@ module Audition
     # Classifies a Prism expression node by Ractor shareability:
     #   :shareable         proven deeply shareable
     #   :mutable_string    unfrozen String literal
-    #   :mutable_container Array/Hash literal
+    #   :mutable_container Array/Hash literal or constructor
     #   :shallow_freeze    frozen container with mutable elements
     #   :sync_primitive    Mutex/Queue/... constructor
     #   :proc              lambda or proc
+    #   :default_proc      Hash.new with a block; the block
+    #                      survives .freeze and stays unshareable
     #   :unknown           cannot tell statically
     class LiteralClassifier
       SYNC_PRIMITIVES = %w[
@@ -43,7 +45,7 @@ module Audition
           classify_interpolated_string(node)
         when Prism::ArrayNode, Prism::HashNode,
              Prism::KeywordHashNode
-          :mutable_container
+          container_kind(node)
         when Prism::RangeNode
           ends = [node.left, node.right].compact
           if ends.all? { |n| classify(n) == :shareable }
@@ -55,6 +57,8 @@ module Audition
           :proc
         when Prism::CallNode
           classify_call(node)
+        when Prism::IfNode
+          ternary_kind(node)
         else
           :unknown
         end
@@ -92,6 +96,13 @@ module Audition
           name = const_name(receiver)
           return :sync_primitive if SYNC_PRIMITIVES.include?(name)
           return :shareable if SHAREABLE_FACTORIES.include?(name)
+          # Hash.new retains its block as the default proc;
+          # Array.new only uses its block to build elements.
+          return :default_proc if name == "Hash" && node.block
+
+          if %w[Hash Array].include?(name)
+            return :mutable_container
+          end
 
           :unknown
         when :define
@@ -113,26 +124,74 @@ module Audition
           :shareable
         when Prism::ArrayNode, Prism::HashNode
           deep_classify(receiver.elements)
+        when Prism::CallNode
+          # A default proc survives freezing the Hash.
+          (classify(receiver) == :default_proc) ? :default_proc : :unknown
+        else
+          :unknown
+        end
+      end
+
+      # A container holding a sync primitive can never become
+      # shareable; Ractor.make_shareable raises on it (multi_json
+      # keeps a frozen Hash of Mutexes). The classification
+      # propagates so no freeze or wrap is ever suggested.
+      def container_kind(node)
+        sync = node.elements.any? do |element|
+          element_children(element).any? do |child|
+            classify(child) == :sync_primitive
+          end
+        end
+        sync ? :sync_primitive : :mutable_container
+      end
+
+      def element_children(element)
+        case element
+        when Prism::AssocNode then [element.key, element.value]
+        else [element]
+        end
+      end
+
+      # A ternary of provable branches classifies as the worst
+      # branch: two string literals make a string, so a plain
+      # `.freeze` stays available for `cond ? ";" : ":"`.
+      def ternary_kind(node)
+        return :unknown unless node.subsequent
+          .is_a?(Prism::ElseNode)
+
+        branches = [
+          single_statement(node.statements),
+          single_statement(node.subsequent.statements)
+        ]
+        return :unknown unless branches.all?
+
+        kinds = branches.map { |branch| classify(branch) }
+        return :shareable if kinds.all?(:shareable)
+
+        if kinds.all? { |k| %i[shareable mutable_string].include?(k) }
+          :mutable_string
         else
           :unknown
         end
       end
 
+      def single_statement(statements)
+        body = statements&.body
+        body && body.size == 1 && body[0]
+      end
+
       # Fold element classifications: everything provably shareable
       # gives :shareable; anything provably mutable gives
-      # :shallow_freeze; anything unknowable gives :unknown (stay
-      # silent rather than guess).
+      # :shallow_freeze; a sync primitive poisons the whole
+      # container; anything unknowable gives :unknown (stay silent
+      # rather than guess).
       def deep_classify(elements)
         verdict = :shareable
         elements.each do |element|
-          children =
-            case element
-            when Prism::AssocNode then [element.key, element.value]
-            else [element]
-            end
-          children.each do |child|
+          element_children(element).each do |child|
             case classify(child)
             when :shareable then nil
+            when :sync_primitive then return :sync_primitive
             when :unknown then return :unknown
             else verdict = :shallow_freeze
             end

data/lib/audition/static/source_file.rb

@@ -72,25 +72,43 @@ module Audition
             %i[require require_relative].include?(s.name)
         end
         if last_require
-          newline = source.index("\n", last_require.location.end_offset)
-          offset = newline ? newline + 1 : source.bytesize
+          newline = raw.index("\n", last_require.location.end_offset)
+          offset = newline ? newline + 1 : raw.bytesize
           {offset: offset, after_require: true}
         else
           {offset: leading_comments_end, after_require: false}
         end
       end
 
+      # Prism reports byte offsets; index math against the source
+      # must run on a binary copy or multibyte content shifts
+      # every computed position.
+      def raw
+        @raw ||= source.dup.force_encoding(Encoding::BINARY)
+      end
+
+      # Keys Ruby actually honors. Prism reports every comment
+      # shaped like `# key: value`, which sweeps up documentation
+      # (`# I18n.t: 'date.formats.short'`); inserting after those
+      # would land a magic comment mid-file.
+      MAGIC_KEYS = %w[
+        encoding coding frozen_string_literal
+        shareable_constant_value warn_indent
+      ].freeze
+
       # Where a new magic comment can go: after the shebang and any
       # existing magic comments, before code.
       def magic_insertion_offset
         offset = 0
-        if source.start_with?("#!")
-          newline = source.index("\n")
-          offset = newline ? newline + 1 : source.bytesize
+        if raw.start_with?("#!")
+          newline = raw.index("\n")
+          offset = newline ? newline + 1 : raw.bytesize
         end
-        after_magic = parse_result.magic_comments.map do |mc|
-          newline = source.index("\n", mc.value_loc.end_offset)
-          newline ? newline + 1 : source.bytesize
+        after_magic = parse_result.magic_comments.filter_map do |mc|
+          next unless MAGIC_KEYS.include?(mc.key_loc.slice)
+
+          newline = raw.index("\n", mc.value_loc.end_offset)
+          newline ? newline + 1 : raw.bytesize
         end.max
         [offset, after_magic || 0].max
       end

data/lib/audition/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Audition
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: audition
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Yaroslav Markin