audition 0.2.4 → 0.4.0

data/lib/audition/static/literal_classifier.rb

@@ -7,14 +7,19 @@ module Audition
     # Classifies a Prism expression node by Ractor shareability:
     #   :shareable         proven deeply shareable
     #   :mutable_string    unfrozen String literal
-    #   :mutable_container Array/Hash literal or constructor
-    #   :mutable_call      unfrozen String or Regexp returned by
-    #                      a call (`.tr`, `format`, `Regexp.new`)
+    #   :mutable_container Array/Hash/Set literal or constructor
+    #   :mutable_call      unfrozen String, Regexp, or sentinel
+    #                      Object returned by a call (`.tr`,
+    #                      `format`, `Regexp.new`, `Object.new`)
     #   :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
+    #   :instance_new      unfrozen instance of an arbitrary class
+    #   :opaque_call       method call with an unprovable return
+    #   :shallow_opaque    frozen at the top, but what it holds
+    #                      is an unprovable call result
     #   :unknown           cannot tell statically
     class LiteralClassifier
       SYNC_PRIMITIVES = %w[
@@ -23,11 +28,20 @@ module Audition
         Thread::ConditionVariable
       ].freeze
       SHAREABLE_FACTORIES = %w[Struct Class Module].freeze
+      # Sentinels: `NOT_GIVEN = Object.new` raises when read from
+      # a worker until frozen, and a frozen bare Object is
+      # shareable (verified on Ruby 4.0.6). BasicObject has no
+      # #freeze.
+      SENTINEL_FACTORIES = %w[Object BasicObject].freeze
+      # Concurrent::Map defines no #freeze, so make_shareable
+      # raises NoMethodError on it; a constant holding one can
+      # never be shared (verified on 4.0.6 with concurrent-ruby).
+      UNFREEZABLE_COLLECTIONS = %w[Concurrent::Map].freeze
 
       # Calls returning a fresh, unfrozen String or Regexp;
       # `# frozen_string_literal: true` covers literals only.
-      # Rails hit both shapes (`.tr` and `Regexp.new`) in
-      # constants during its ractorization. These names belong
+      # Both shapes (`.tr` and `Regexp.new`) turn up in
+      # constants in the wild. These names belong
       # to String alone in core, so any receiver qualifies.
       STRING_ONLY_METHODS = %i[
         tr tr_s gsub sub squeeze strip lstrip rstrip chomp chop
@@ -41,6 +55,18 @@ module Audition
       ].freeze
       FORMATTERS = %i[format sprintf].freeze
       REGEXP_FACTORIES = %i[new union compile].freeze
+      # File methods returning a fresh path String.
+      FILE_PATH_METHODS = %i[
+        expand_path join dirname basename absolute_path realpath
+      ].freeze
+
+      # Calls returning a shareable primitive on any receiver.
+      SHAREABLE_RETURNS = %i[
+        to_i to_int to_f to_r to_c to_sym size length count
+        bytesize ord hash
+      ].freeze
+      # Sorbet's inline casts, which return their value argument.
+      SORBET_CASTS = %i[let cast must].freeze
 
       # @param frozen_string_literal [Boolean] whether the file has
       #   the frozen_string_literal magic comment
@@ -51,6 +77,7 @@ module Audition
       # @param node [Prism::Node] an expression node
       # @return [Symbol] classification, see class docs
       def classify(node)
+        node = begin_value(node)
         case node
         when Prism::IntegerNode, Prism::FloatNode,
              Prism::RationalNode, Prism::ImaginaryNode,
@@ -84,6 +111,29 @@ module Audition
         end
       end
 
+      # The value an expression hands back once begin blocks
+      # and inline casts are peeled off.
+      def unwrap(node)
+        loop do
+          inner = begin_value(node)
+          inner = cast_value(inner) || inner
+          break node if inner.equal?(node)
+
+          node = inner
+        end
+      end
+
+      # A begin block's value is its last statement. A rescue,
+      # else, or ensure clause can supply a different one, so
+      # only the plain form resolves.
+      def begin_value(node)
+        return node unless node.is_a?(Prism::BeginNode) &&
+          node.rescue_clause.nil? && node.else_clause.nil? &&
+          node.ensure_clause.nil?
+
+        node.statements&.body&.last || node
+      end
+
       # `::Mutex` and `Mutex` are the same constant for matching
       # purposes; the leading colons are stripped.
       def const_name(node)
@@ -95,6 +145,34 @@ module Audition
         end
       end
 
+      # The value inside a Sorbet inline cast, or nil. The cast
+      # returns its argument, so fixes and type names belong on
+      # the value, not the cast.
+      def cast_value(node)
+        return nil unless node.is_a?(Prism::CallNode)
+        return nil unless const_name(node.receiver) == "T" &&
+          SORBET_CASTS.include?(node.name)
+
+        node.arguments&.arguments&.first
+      end
+
+      # What `value.freeze` would classify as, for the check to
+      # choose a plain `.freeze` over a deep wrap: :shareable
+      # when every element is provably shareable, :shallow_freeze
+      # when one is provably mutable, :unknown otherwise.
+      def frozen_kind(value)
+        case value
+        when Prism::ArrayNode, Prism::HashNode,
+             Prism::KeywordHashNode
+          deep_classify(value.elements)
+        when Prism::CallNode
+          elements = set_elements(value)
+          elements ? deep_classify(elements) : :unknown
+        else
+          :unknown
+        end
+      end
+
       private
 
       # Adjacent literals ("a" "b") parse as interpolation but
@@ -121,18 +199,28 @@ module Audition
           classify_freeze(node, receiver)
         when :new
           name = const_name(receiver)
-          return :sync_primitive if SYNC_PRIMITIVES.include?(name)
+          return :sync_primitive if SYNC_PRIMITIVES.include?(name) ||
+            UNFREEZABLE_COLLECTIONS.include?(name)
           return :shareable if SHAREABLE_FACTORIES.include?(name)
           return :proc if name == "Proc" && node.block
           # 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
+          return set_kind(node) if name == "Set"
+          if SENTINEL_FACTORIES.include?(name)
+            bare = node.arguments.nil? && node.block.nil?
+            return bare ? :mutable_call : :unknown
+          end
 
           if %w[Hash Array].include?(name)
             return :mutable_container
           end
 
-          :unknown
+          name ? :instance_new : :opaque_call
+        when :to_set
+          set_kind(node)
+        when :[]
+          index_kind(node)
         when :define
           (const_name(receiver) == "Data") ? :shareable : :unknown
         when :make_shareable
@@ -140,14 +228,46 @@ module Audition
         when :lambda, :proc
           (receiver.nil? && node.block) ? :proc : :unknown
         else
-          :unknown
+          opaque_kind(node)
         end
       end
 
+      # Catch-all for unrecognized calls: shareable returns pass,
+      # predicates stay silent, everything else is opaque.
+      def opaque_kind(node)
+        return :shareable if SHAREABLE_RETURNS.include?(node.name)
+        return :unknown if node.name.end_with?("?")
+
+        if (value = cast_value(node))
+          return classify(value)
+        end
+
+        :opaque_call
+      end
+
+      # Indexing into a constant, another call's result, or a
+      # fresh instance returns a value of unprovable shareability.
+      # Sorbet type constructors and ENV, whose values are frozen
+      # strings, stay silent.
+      def index_kind(node)
+        owner = const_name(node.receiver)
+        return set_kind(node) if owner == "Set"
+        if owner.nil?
+          receiver_kind = classify(node.receiver)
+          return :opaque_call if %i[opaque_call instance_new]
+            .include?(receiver_kind)
+          return :unknown
+        end
+        return :unknown if owner == "ENV" ||
+          owner == "T" || owner.start_with?("T::")
+
+        :opaque_call
+      end
+
       def classify_freeze(node, receiver)
         return :unknown unless node.arguments.nil? && receiver
 
-        case receiver
+        case (receiver = begin_value(receiver))
         when Prism::StringNode
           :shareable
         when Prism::ArrayNode, Prism::HashNode
@@ -158,6 +278,8 @@ module Audition
           case classify(receiver)
           when :default_proc then :default_proc
           when :mutable_call then :shareable
+          when :mutable_container then frozen_kind(receiver)
+          when :instance_new, :opaque_call then :shallow_opaque
           else :unknown
           end
         else
@@ -178,6 +300,7 @@ module Audition
           owner = const_name(receiver)
           (name == :new && owner == "String") ||
             (owner == "Kernel" && FORMATTERS.include?(name)) ||
+            (owner == "File" && FILE_PATH_METHODS.include?(name)) ||
             STRING_ONLY_METHODS.include?(name)
         else
           false
@@ -194,7 +317,11 @@ module Audition
       # 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|
+        elements_kind(node.elements)
+      end
+
+      def elements_kind(elements)
+        sync = elements.any? do |element|
           element_children(element).any? do |child|
             classify(child) == :sync_primitive
           end
@@ -202,6 +329,37 @@ module Audition
         sync ? :sync_primitive : :mutable_container
       end
 
+      # A Set built from literals is a container of them:
+      # `Set.new([...])`, `Set[...]`, `%w[...].to_set`. A Set
+      # built from an opaque source or a mapping block is still
+      # a fresh unfrozen Set, mutable no matter its contents.
+      def set_kind(node)
+        elements = set_elements(node)
+        elements ? elements_kind(elements) : :mutable_container
+      end
+
+      def set_elements(node)
+        return nil if node.block
+
+        case node.name
+        when :new, :[]
+          return nil unless const_name(node.receiver) == "Set"
+
+          args = node.arguments&.arguments || []
+          return args if node.name == :[]
+          return [] if args.empty?
+          return nil unless args.size == 1
+
+          args[0].is_a?(Prism::ArrayNode) ? args[0].elements : nil
+        when :to_set
+          receiver = node.receiver
+          return nil unless node.arguments.nil? &&
+            receiver.is_a?(Prism::ArrayNode)
+
+          receiver.elements
+        end
+      end
+
       def element_children(element)
         case element
         when Prism::AssocNode then [element.key, element.value]
@@ -237,20 +395,33 @@ module Audition
         body && body.size == 1 && body[0]
       end
 
-      # Fold element classifications: everything provably shareable
-      # gives :shareable; anything provably mutable gives
-      # :shallow_freeze; a sync primitive poisons the whole
-      # container; anything unknowable gives :unknown (stay silent
-      # rather than guess).
+      # Fold element classifications by the strongest evidence:
+      # a sync primitive poisons the whole container; a provably
+      # mutable element makes it :shallow_freeze; an opaque call
+      # result makes it :shallow_opaque. A bare constant read is
+      # commonly a class or another frozen constant, so on its
+      # own it keeps the container silent (:unknown), but it
+      # cannot excuse a bad element elsewhere.
+      VERDICT_RANK = {
+        shareable: 0, unknown: 1, shallow_opaque: 2,
+        shallow_freeze: 3
+      }.freeze
+
       def deep_classify(elements)
         verdict = :shareable
         elements.each do |element|
           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
+            kind =
+              case classify(child)
+              when :shareable then :shareable
+              when :sync_primitive then return :sync_primitive
+              when :unknown then :unknown
+              when :instance_new, :opaque_call, :shallow_opaque
+                :shallow_opaque
+              else :shallow_freeze
+              end
+            if VERDICT_RANK[kind] > VERDICT_RANK[verdict]
+              verdict = kind
             end
           end
         end

data/lib/audition/static/native_extensions.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Audition
+  module Static
+    # Compiled extensions are invisible to the Ruby scanner, but the
+    # one fact that decides their Ractor behavior is visible from
+    # outside. Ruby marks every method an extension defines while
+    # Init_* runs without rb_ext_ractor_safe(true), and calling any
+    # of them from a non-main Ractor raises Ractor::UnsafeError. The
+    # declaration is a libruby import, so a compiled file names the
+    # symbol or does not, whatever language produced it; sources
+    # spell it as rb_ext_ractor_safe(true) or the
+    # RB_EXT_RACTOR_SAFE(true) macro (C, Rust via rb-sys, Zig).
+    #
+    # Compiled files win when present: they are what `require`
+    # loads. Sources are consulted only for a checkout that has not
+    # been built yet.
+    class NativeExtensions
+      CHECK = "native-extension"
+      SYMBOL = "rb_ext_ractor_safe"
+      DECLARATION = /rb_ext_ractor_safe\s*\(\s*true\s*\)/i
+      INIT = /\bInit_\w+\s*\(/
+      SOURCES = "*.{c,cc,cpp,cxx,m,mm,h,hpp,rs,zig}"
+      BUILD_FILES = %w[Cargo.toml build.zig extconf.rb].freeze
+      # Harness crates and test trees are not compiled into the
+      # extension; a fuzz target that links the VM itself may call
+      # rb_ext_ractor_safe without the extension doing so.
+      HARNESS_DIRS = %w[fuzz benches tests examples test spec].freeze
+
+      SILENT_WHY =
+        "Ruby marks every method an extension defines while " \
+        "Init_* runs without rb_ext_ractor_safe(true), and calling " \
+        "any of them from a non-main Ractor raises " \
+        "Ractor::UnsafeError (\"ractor unsafe method called from " \
+        "not main ractor\"), whether the extension is C, Rust, or " \
+        "Zig (verified on Ruby 4.0.6). "
+      # Tails appended to SILENT_WHY at finding time; a constant
+      # built with + would hold an unfrozen String.
+      COMPILED_TAIL =
+        "The declaration is a libruby import, so a compiled file " \
+        "that never names the symbol cannot have made it."
+      SOURCE_TAIL =
+        "These sources never call it, so the compiled extension " \
+        "will raise the same way."
+      SILENT_FIX =
+        "Audit the native code for process-global mutable state " \
+        "(statics, caches, VALUEs held outside Ruby objects), then " \
+        "call RB_EXT_RACTOR_SAFE(true) first thing in Init_* " \
+        "(rb_sys::rb_ext_ractor_safe(true) from Rust). Until then, " \
+        "keep every call into this extension on the main Ractor."
+      DECLARED_WHY =
+        "rb_ext_ractor_safe(true) is the maintainer's assertion " \
+        "that the extension keeps no process-global mutable state; " \
+        "Ruby does not verify it and neither can Audition. Its " \
+        "methods run from any Ractor, in parallel, on the strength " \
+        "of that assertion alone."
+      DECLARED_FIX =
+        "Exercise real calls from a non-main Ractor (a script " \
+        "probe, or the gem's test suite under Ractor.new) before " \
+        "relying on it."
+
+      # @param target [Target]
+      # @param compiled_files [Array<String>] compiled extension
+      #   files to inspect (defaults to the target's own list; the
+      #   CLI passes the config-filtered subset)
+      # @return [Array<Finding>]
+      def analyze(target, compiled_files: target.compiled_files)
+        if compiled_files.any?
+          return compiled_files.filter_map { |p| compiled_finding(p) }
+        end
+
+        extension_dirs(target.root).map do |dir|
+          source_finding(dir, target.root)
+        end
+      end
+
+      private
+
+      def compiled_finding(path)
+        name = File.basename(path)
+        if File.binread(path).include?(SYMBOL)
+          finding(:info, path, nil,
+            "compiled extension #{name} declares Ractor safety " \
+            "(imports #{SYMBOL})", DECLARED_WHY, DECLARED_FIX)
+        else
+          finding(:warning, path, nil,
+            "compiled extension #{name} does not declare Ractor " \
+            "safety", SILENT_WHY + COMPILED_TAIL, SILENT_FIX)
+        end
+      rescue SystemCallError
+        nil
+      end
+
+      # One finding per extension directory, anchored
+      # at the declaration when there is one, else at Init_* or the
+      # build file, where the declaration belongs.
+      def source_finding(dir, root)
+        sources = sources_under(dir)
+        label = if dir == root
+          File.basename(root)
+        else
+          dir.delete_prefix("#{root}/")
+        end
+        path, line = locate(sources, DECLARATION)
+        if path
+          return finding(:info, path, line,
+            "extension sources under #{label} declare Ractor " \
+            "safety (#{SYMBOL})", DECLARED_WHY, DECLARED_FIX)
+        end
+
+        path, line = locate(sources, INIT)
+        path ||= build_file(dir)
+        finding(:warning, path, line,
+          "extension sources under #{label} do not declare Ractor " \
+          "safety", SILENT_WHY + SOURCE_TAIL, SILENT_FIX)
+      end
+
+      # Directories holding native sources, found by the build file
+      # that compiles them rather than by convention: a gem is free
+      # to put its extension anywhere. A manifest above another one
+      # is dropped, so a workspace does not report the sources of
+      # the crates under it a second time.
+      def extension_dirs(root)
+        dirs = build_dirs(root).select { |dir| sources_under(dir).any? }
+        dirs.reject do |dir|
+          dirs.any? { |other| other.start_with?("#{dir}/") }
+        end
+      end
+
+      def build_dirs(root)
+        pattern = "{#{BUILD_FILES.join(",")}}"
+        Dir[File.join(root, "**", pattern)].filter_map do |path|
+          relative = path.delete_prefix("#{root}/").split("/")
+          next if relative[0..-2].any? { |part| skipped?(part) }
+
+          File.dirname(path)
+        end.uniq.sort
+      end
+
+      def sources_under(dir)
+        Dir[File.join(dir, "**", SOURCES)].sort.reject do |path|
+          path.delete_prefix("#{dir}/").split("/")[0..-2]
+            .any? { |part| skipped?(part) }
+        end
+      end
+
+      def skipped?(part)
+        Target::EXCLUDED_DIRS.include?(part) ||
+          Target::BUILD_DIRS.include?(part) ||
+          HARNESS_DIRS.include?(part) || part.start_with?(".")
+      end
+
+      def locate(sources, pattern)
+        sources.each do |path|
+          File.foreach(path, mode: "rb").with_index(1) do |text, n|
+            return [path, n] if text.match?(pattern)
+          end
+        end
+        nil
+      end
+
+      def build_file(dir)
+        BUILD_FILES.map { |name| File.join(dir, name) }
+          .find { |path| File.file?(path) } || dir
+      end
+
+      def finding(severity, path, line, message, why, fix)
+        Finding.new(
+          check: CHECK, severity: severity, message: message,
+          why: why, fix: fix, path: path, line: line
+        )
+      end
+    end
+  end
+end

data/lib/audition/static/source_file.rb

@@ -152,6 +152,76 @@ module Audition
       # shaped like `# key: value`, which sweeps up documentation
       # (`# I18n.t: 'date.formats.short'`); inserting after those
       # would land a magic comment mid-file.
+      # Constants frozen by a bare `NAME.freeze` statement at the
+      # same lexical level as a file, class, or module body: the
+      # build-then-freeze shape. A freeze inside a method does
+      # not count; nothing guarantees it runs before a Ractor
+      # reads the constant.
+      # @return [Array<String>]
+      def frozen_constants
+        @frozen_constants ||= begin
+          names = []
+          bodies = [root.statements]
+          until bodies.empty?
+            statements = bodies.shift
+            next unless statements.is_a?(Prism::StatementsNode)
+
+            statements.body.each do |node|
+              case node
+              when Prism::ModuleNode, Prism::ClassNode,
+                   Prism::SingletonClassNode
+                bodies << node.body
+              when Prism::CallNode
+                next unless node.name == :freeze &&
+                  node.arguments.nil? && node.block.nil?
+
+                name = constant_receiver(node.receiver)
+                names << name if name
+              end
+            end
+          end
+          names.uniq
+        end
+      end
+
+      # Calls that give a constant's object singleton behavior;
+      # freezing the object first makes them raise FrozenError
+      # (`NULL = Object.new; def NULL.to_s = "null"`).
+      CONST_CUSTOMIZERS = %i[
+        extend define_singleton_method instance_eval instance_exec
+        singleton_class instance_variable_set
+      ].freeze
+
+      # @return [Array<String>] names of constants that receive a
+      #   singleton method definition or a customizing call
+      def customized_constants
+        @customized_constants ||= begin
+          names = []
+          queue = [root]
+          until queue.empty?
+            node = queue.shift
+            queue.concat(node.child_nodes.compact)
+            receiver =
+              if node.is_a?(Prism::DefNode)
+                node.receiver
+              elsif node.is_a?(Prism::CallNode) &&
+                  CONST_CUSTOMIZERS.include?(node.name)
+                node.receiver
+              end
+            name = constant_receiver(receiver)
+            names << name if name
+          end
+          names.uniq
+        end
+      end
+
+      def constant_receiver(node)
+        case node
+        when Prism::ConstantReadNode then node.name.to_s
+        when Prism::ConstantPathNode then node.location.slice
+        end
+      end
+
       MAGIC_KEYS = %w[
         encoding coding frozen_string_literal
         shareable_constant_value warn_indent

data/lib/audition/static/work_split.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "etc"
+
+module Audition
+  module Static
+    # How a scan is divided between Ractor workers.
+    module WorkSplit
+      # Ractors run on a fixed pool of native threads sized by
+      # RUBY_MAX_CPU, which only the environment can set. Spawning
+      # past it buys no parallelism and costs a Ractor each.
+      RACTOR_CPU_DEFAULT = 8
+
+      module_function
+
+      # One worker per core the Ractor pool can actually run. The
+      # main Ractor only waits while workers scan, so no core is
+      # held back for it.
+      #
+      # @return [Integer]
+      def workers
+        Etc.nprocessors.clamp(1, ractor_cpu_limit)
+      end
+
+      def ractor_cpu_limit
+        limit = ENV["RUBY_MAX_CPU"].to_i
+        limit.positive? ? limit : RACTOR_CPU_DEFAULT
+      end
+
+      # Longest-processing-time-first: deal the heaviest item onto
+      # the lightest worker. Consecutive files are neighbors in the
+      # tree and so alike in size, so contiguous slices come out
+      # lopsided: one worker can draw a slice weighing several times
+      # the mean and still be running once the rest have finished.
+      # Greedy is enough here: LPT finishes within 4/3 of an
+      # optimal split.
+      #
+      # @param weighted [Array<Array>] `[item, weight]` pairs
+      # @param count [Integer] worker count
+      # @return [Array<Array>] one chunk of items per busy worker
+      def chunks(weighted, count)
+        chunks = Array.new(count) { [] }
+        loads = Array.new(count, 0)
+        weighted.sort_by { |item, weight| [-weight, item] }
+          .each do |item, weight|
+            lightest = loads.index(loads.min)
+            chunks[lightest] << item
+            loads[lightest] += weight
+          end
+        chunks.reject(&:empty?)
+      end
+    end
+  end
+end