audition 0.2.4 → 0.3.0

data/lib/audition/static/literal_classifier.rb

@@ -7,9 +7,10 @@ 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
@@ -23,11 +24,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
@@ -95,6 +105,23 @@ module Audition
         end
       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 +148,26 @@ 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
+        when :[], :to_set
+          set_kind(node)
         when :define
           (const_name(receiver) == "Data") ? :shareable : :unknown
         when :make_shareable
@@ -158,6 +193,7 @@ module Audition
           case classify(receiver)
           when :default_proc then :default_proc
           when :mutable_call then :shareable
+          when :mutable_container then frozen_kind(receiver)
           else :unknown
           end
         else
@@ -194,7 +230,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 +242,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`. Anything
+      # else, such as `Set.new(compute)` or a mapping block,
+      # stays unknown.
+      def set_kind(node)
+        elements = set_elements(node)
+        elements ? elements_kind(elements) : :unknown
+      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]

data/lib/audition/static/native_extensions.rb

@@ -0,0 +1,163 @@
+# 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 under ext/ 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 (ext/<name>), 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 = dir.delete_prefix("#{root}/")
+        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
+
+      # ext/<name> directories holding native sources; ext/ itself
+      # when the sources sit directly in it.
+      def extension_dirs(root)
+        ext = File.join(root, "ext")
+        return [] unless File.directory?(ext)
+
+        dirs = Dir[File.join(ext, "*")].sort.select do |dir|
+          File.directory?(dir) && !skipped?(File.basename(dir)) &&
+            sources_under(dir).any?
+        end
+        dirs << ext if Dir[File.join(ext, SOURCES)].any?
+        dirs
+      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/target.rb

@@ -12,6 +12,14 @@ module Audition
       vendor node_modules tmp log coverage pkg .git .bundle
     ].freeze
 
+    # Cargo and Zig build output: full of .so/.dylib artifacts that
+    # are not the extension `require` loads.
+    BUILD_DIRS = %w[target zig-out].freeze
+
+    # What Ruby loads as a native extension (RbConfig DLEXT is
+    # "bundle" on macOS, "so" everywhere else, Windows included).
+    COMPILED = "*.{bundle,so}"
+
     # @return [Symbol] one of `:script`, `:gem`, `:rack`, `:rails`,
     #   `:directory`, `:bundle`
     attr_reader :type
@@ -22,6 +30,10 @@ module Audition
     # @return [Array<String>] Ruby files to scan statically
     attr_reader :ruby_files
 
+    # @return [Array<String>] compiled extension files (.bundle/.so)
+    #   shipped with the target; empty for scripts and file lists
+    attr_reader :compiled_files
+
     # @return [Hash, nil] dynamic probe entry (`:mode` plus
     #   mode-specific keys), nil for static-only targets
     attr_reader :entry
@@ -43,6 +55,30 @@ module Audition
       end
     end
 
+    # Builds a static-only target from an explicit file list, the
+    # shape git hooks hand over (lefthook's {staged_files},
+    # pre-commit's filename arguments). Config, pragmas, and the
+    # baseline resolve against the working directory, which is the
+    # repository root when a hook manager runs the command.
+    #
+    # @param paths [Array<String>] `.rb`/`.ru` files
+    # @return [Target] type `:files`, no dynamic entry
+    # @raise [Audition::Error] when a path is not a Ruby file
+    def self.for_files(paths)
+      paths.each do |path|
+        unless File.file?(path) && path.end_with?(".rb", ".ru")
+          raise Error, "#{path} is not a Ruby file"
+        end
+      end
+
+      new(
+        type: :files,
+        root: Dir.pwd,
+        ruby_files: paths,
+        entry: nil
+      )
+    end
+
     def self.from_file(path)
       if File.basename(path) == "Gemfile.lock"
         return new(
@@ -80,7 +116,8 @@ module Audition
           type: :directory,
           root: dir,
           ruby_files: glob(dir),
-          entry: nil
+          entry: nil,
+          compiled_files: compiled(dir)
         )
       end
     end
@@ -94,7 +131,8 @@ module Audition
           glob(File.join(spec.full_gem_path, rp))
         end,
         entry: {mode: :require, feature: name,
-                root: spec.full_gem_path}
+                root: spec.full_gem_path},
+        compiled_files: compiled_for(spec)
       )
     rescue Gem::MissingSpecError
       raise Error,
@@ -112,7 +150,8 @@ module Audition
           mode: :rails,
           environment: File.join(dir, "config", "environment.rb"),
           root: dir
-        }
+        },
+        compiled_files: compiled(dir)
       )
     end
 
@@ -121,7 +160,8 @@ module Audition
         type: :rack,
         root: dir,
         ruby_files: [config_ru] + glob(dir),
-        entry: {mode: :rack, config_ru: config_ru}
+        entry: {mode: :rack, config_ru: config_ru},
+        compiled_files: compiled(dir)
       )
     end
 
@@ -136,7 +176,8 @@ module Audition
           feature: File.basename(gemspec, ".gemspec"),
           load_paths: [lib],
           root: dir
-        }
+        },
+        compiled_files: compiled(dir)
       )
     end
 
@@ -149,24 +190,47 @@ module Audition
       raw.sub(%r{/+\z}, "")
     end
 
-    def self.glob(dir)
+    def self.glob(dir, pattern = "*.rb", skip: EXCLUDED_DIRS)
       dir = normalize(dir)
-      Dir[File.join(dir, "**", "*.rb")].reject do |path|
+      Dir[File.join(dir, "**", pattern)].reject do |path|
         relative = path.delete_prefix("#{dir}/")
         parts = relative.split("/")
-        parts.any? { |p| EXCLUDED_DIRS.include?(p) || p.start_with?(".") }
+        parts.any? { |p| skip.include?(p) || p.start_with?(".") }
       end.sort
     end
 
+    # macOS debug-symbol bundles (x.bundle.dSYM/...) carry a file
+    # with the extension's name that nothing ever loads.
+    def self.compiled(dir)
+      glob(dir, COMPILED, skip: EXCLUDED_DIRS + BUILD_DIRS).reject do |p|
+        p.split("/").any? { |part| part.end_with?(".dSYM") }
+      end
+    end
+
+    # Compiled extension files of an installed gem. RubyGems builds
+    # a source gem into its extension dir and also copies the result
+    # under lib/, so the same file shows up on two require paths;
+    # keep one per require-relative name.
+    #
+    # @param spec [Gem::Specification]
+    # @return [Array<String>]
+    def self.compiled_for(spec)
+      spec.full_require_paths.flat_map do |rp|
+        compiled(rp).map { |path| [path.delete_prefix("#{rp}/"), path] }
+      end.uniq(&:first).map(&:last)
+    end
+
     private_class_method :from_file, :from_directory, :from_gem_name,
       :rails_target, :rack_target, :gem_dir_target,
-      :glob, :normalize
+      :glob, :compiled, :normalize
 
-    def initialize(type:, root:, ruby_files:, entry:)
+    def initialize(type:, root:, ruby_files:, entry:,
+      compiled_files: [])
       @type = type
       @root = root
       @ruby_files = ruby_files
       @entry = entry
+      @compiled_files = compiled_files
     end
   end
 end

data/lib/audition/version.rb

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

data/lib/audition.rb

@@ -7,6 +7,7 @@ require_relative "audition/static/source_file"
 require_relative "audition/static/literal_classifier"
 require_relative "audition/static/checks"
 require_relative "audition/static/graph_audit"
+require_relative "audition/static/native_extensions"
 require_relative "audition/static/analyzer"
 require_relative "audition/dynamic/prober"
 require_relative "audition/report"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: audition
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Yaroslav Markin
@@ -103,6 +103,10 @@ files:
 - lib/audition/finding.rb
 - lib/audition/fixer.rb
 - lib/audition/report.rb
+- lib/audition/report/github.rb
+- lib/audition/report/json.rb
+- lib/audition/report/style.rb
+- lib/audition/report/text.rb
 - lib/audition/rewriters.rb
 - lib/audition/static/analyzer.rb
 - lib/audition/static/checks.rb
@@ -114,6 +118,7 @@ files:
 - lib/audition/static/checks/unsafe_calls.rb
 - lib/audition/static/graph_audit.rb
 - lib/audition/static/literal_classifier.rb
+- lib/audition/static/native_extensions.rb
 - lib/audition/static/source_file.rb
 - lib/audition/target.rb
 - lib/audition/version.rb