audition 0.1.0 → 0.2.1

data/lib/audition/static/analyzer.rb

@@ -46,7 +46,13 @@ module Audition
         end
 
         parallel_analyze(paths, workers)
-      rescue Ractor::Error
+      rescue Ractor::Error => e
+        # The silent fallback would otherwise mask a check that is
+        # itself Ractor-hostile; surface it under -w.
+        if $VERBOSE
+          warn "audition: parallel scan fell back to serial: " \
+               "#{e.class}: #{e.message}"
+        end
         paths.flat_map { |path| analyze_path(path) }
       end
 

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

@@ -39,12 +39,21 @@ module Audition
           # @return [String] kebab-case check identifier
           def check_name(value = nil)
             @check_name = -value if value # audition:disable class-level-state
-            @check_name || name.split("::").last
-              .gsub(/([a-z0-9])([A-Z])/, '\1-\2').downcase
+            @check_name || (name || "anonymous-check").split("::")
+              .last.gsub(/([a-z0-9])([A-Z])/, '\1-\2').downcase
           end
 
+          # Catalogs merge down the ancestry so a subclass of a
+          # concrete check inherits its handlers and messages
+          # instead of raising KeyError at visit time.
           def explanations
-            @explanations || EMPTY_CATALOG
+            own = @explanations || EMPTY_CATALOG
+            parent = superclass
+            if parent.respond_to?(:explanations)
+              parent.explanations.merge(own)
+            else
+              own
+            end
           end
 
           # Registers a message catalog entry. Strings may contain
@@ -67,7 +76,13 @@ module Audition
           end
 
           def handlers
-            @handlers || EMPTY_CATALOG
+            own = @handlers || EMPTY_CATALOG
+            parent = superclass
+            if parent.respond_to?(:handlers)
+              parent.handlers.merge(own)
+            else
+              own
+            end
           end
 
           # Methods born from define_method carry their block as a

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

@@ -11,8 +11,9 @@ module Audition
       class GlobalVariables < Base
         SAFE_READS = %w[
           $stdin $stdout $stderr $! $? $~ $_ $DEBUG $VERBOSE $/ $$
+          $-v $-d
         ].freeze
-        SAFE_WRITES = %w[$DEBUG $VERBOSE].freeze
+        SAFE_WRITES = %w[$DEBUG $VERBOSE $-v $-d].freeze
         LOAD_PATH_GLOBALS = %w[$LOAD_PATH $: $LOADED_FEATURES $"].freeze
 
         explain :access,

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

@@ -71,10 +71,47 @@ 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, node.receiver, node.name.to_s)
+        end
+
+        on :index_operator_write_node, :index_or_write_node,
+          :index_and_write_node, :index_target_node do |node|
+          flag_constant_mutation(node, node.receiver, "[]=")
+        end
+
         on :constant_path_write_node,
           :constant_path_or_write_node do |node|
           examine(node.target.location.slice, node, node.value)
@@ -85,23 +122,118 @@ module Audition
         def examine(name, node, value)
           return if file.shareable_constants?
 
+          # A constant this file itself mutates in place is a
+          # deliberate accumulator; freezing it would raise at
+          # the mutation site (sinatra's PARAMS_CONFIG). The
+          # finding stays, the autofix goes.
+          fix_ok = !mutated?(name)
           case classifier.classify(value)
           when :mutable_string
             flag(node, :mutable_string, name: name,
-              autofix: append_freeze(value))
+              autofix: fix_ok ? append_freeze(value) : nil)
           when :mutable_container
-            type = value.is_a?(Prism::HashNode) ? "Hash" : "Array"
-            flag(node, :mutable_container, name: name, type: type,
-              autofix: wrap_make_shareable(value))
+            flag(node, :mutable_container, name: name,
+              type: container_type(value),
+              autofix: fix_ok ? wrap_make_shareable(value) : nil)
           when :shallow_freeze
             flag(node, :shallow_freeze, name: name,
-              autofix: replace_with_make_shareable(value))
+              autofix:
+                fix_ok ? replace_with_make_shareable(value) : nil)
           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
+            # make_shareable on a proc raises when the proc
+            # captures locals or its self is unshareable (any
+            # top-level lambda); only capture-free lambdas inside
+            # a class or module body get the wrap.
+            body = proc_body(value)
+            wrappable = fix_ok && namespaced?(node) &&
+              (body.nil? ||
+                RactorIsolation::CaptureScanner
+                  .scan(body).empty?)
             flag(node, :proc_constant, name: name,
-              autofix: wrap_make_shareable(value))
+              autofix: wrappable ? wrap_make_shareable(value) : nil)
+          when :default_proc
+            flag(node, :hash_default_proc, name: name)
+          end
+        end
+
+        def mutated?(name)
+          bare = name.split("::").last
+          file.mutated_constants.any? do |mutated|
+            mutated == name || mutated.split("::").last == bare
+          end
+        end
+
+        # A proc value is a LambdaNode (`->`) or a CallNode
+        # (`proc { }`, `lambda { }`, `Proc.new { }`); the body
+        # lives in different places (rspec-expectations crashed
+        # the CallNode path).
+        def proc_body(value)
+          case value
+          when Prism::LambdaNode then value.body
+          when Prism::CallNode then value.block&.body
+          end
+        end
+
+        def namespaced?(node)
+          offset = node.location.start_offset
+          module_ranges.any? { |range| range.cover?(offset) }
+        end
+
+        def module_ranges
+          @module_ranges ||= begin
+            ranges = []
+            queue = [file.root]
+            until queue.empty?
+              current = queue.shift
+              queue.concat(current.child_nodes.compact)
+              case current
+              when Prism::ClassNode, Prism::ModuleNode,
+                   Prism::SingletonClassNode
+                location = current.location
+                ranges <<
+                  (location.start_offset..location.end_offset)
+              end
+            end
+            ranges
+          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(
+          SourceFile::CONST_MUTATORS
+        )
+
+        def flag_constant_mutation(node, receiver, method)
+          if node.is_a?(Prism::CallNode)
+            return unless MUTATORS.include?(node.name)
+          end
+
+          name = classifier.const_name(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: method)
+        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,21 +243,41 @@ 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
 
+        # `X = :a, :b` is an array literal without brackets; the
+        # slice must gain them or the wrap becomes a multi-arg
+        # call (mail's ATTRIBUTES).
         def wrap_make_shareable(value)
           source = value.location.slice
+          if value.is_a?(Prism::ArrayNode) && value.opening_loc.nil?
+            source = "[#{source}]"
+          end
           Autofix.new(
             start_offset: value.location.start_offset,
             end_offset: value.location.end_offset,
-            replacement: "Ractor.make_shareable(#{source})"
+            replacement: "Ractor.make_shareable(#{source})",
+            safety: :unsafe
           )
         end
 
@@ -136,7 +288,8 @@ module Audition
           Autofix.new(
             start_offset: call.location.start_offset,
             end_offset: call.location.end_offset,
-            replacement: "Ractor.make_shareable(#{source})"
+            replacement: "Ractor.make_shareable(#{source})",
+            safety: :unsafe
           )
         end
       end

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

@@ -82,7 +82,11 @@ module Audition
 
           # Method definitions open fresh scopes; nothing inside
           # them can capture the surrounding locals.
+          # A def opens a fresh scope, but its receiver
+          # expression (`def x.foo`) evaluates in the enclosing
+          # one and can capture an outer local.
           def visit_def_node(node)
+            visit(node.receiver) if node.receiver
           end
 
           %i[
@@ -93,7 +97,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

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
@@ -143,12 +160,22 @@ module Audition
           when Prism::ConstantReadNode
             receiver.name.to_s == expected
           when Prism::ConstantPathNode
-            receiver.location.slice == expected
+            receiver.location.slice.delete_prefix("::") == expected
           else
             false
           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?