audition 0.1.0

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Audition
+  module Static
+    module Checks
+      # Non-main Ractors cannot touch global variables: reads and
+      # writes raise Ractor::IsolationError. The exceptions below are
+      # ractor-local or frame-local and verified safe on Ruby 4.0.
+      # Regexp capture globals ($1, $&, $`, $', $+) are separate
+      # Prism node types and never flagged.
+      class GlobalVariables < Base
+        SAFE_READS = %w[
+          $stdin $stdout $stderr $! $? $~ $_ $DEBUG $VERBOSE $/ $$
+        ].freeze
+        SAFE_WRITES = %w[$DEBUG $VERBOSE].freeze
+        LOAD_PATH_GLOBALS = %w[$LOAD_PATH $: $LOADED_FEATURES $"].freeze
+
+        explain :access,
+          severity: :error,
+          message: "%{access} global variable %{name}",
+          why: "Non-main Ractors cannot access global " \
+               "variables; this raises Ractor::IsolationError " \
+               "the moment the line executes in a Ractor " \
+               "(verified on Ruby 4.0).",
+          fix: "Pass the value into the Ractor explicitly " \
+               "(Ractor.new(value) { |v| ... }) or over a " \
+               "Ractor::Port; for per-Ractor state use " \
+               "Ractor.current[:key]; do one-time process " \
+               "setup on the main Ractor before spawning."
+
+        explain :load_path,
+          severity: :error,
+          message: "%{access} global variable %{name}",
+          why: "The load path ($LOAD_PATH/$LOADED_FEATURES) " \
+               "is main-Ractor-only global state; touching " \
+               "it from a non-main Ractor raises " \
+               "Ractor::IsolationError.",
+          fix: "Adjust the load path on the main Ractor " \
+               "during boot, before any Ractors are spawned."
+
+        on :global_variable_read_node do |node|
+          unless SAFE_READS.include?(node.name.to_s)
+            gvar(node, "read of")
+          end
+        end
+
+        on :global_variable_write_node,
+          :global_variable_operator_write_node,
+          :global_variable_or_write_node,
+          :global_variable_and_write_node,
+          :global_variable_target_node do |node|
+          unless SAFE_WRITES.include?(node.name.to_s)
+            gvar(node, "write to")
+          end
+        end
+
+        private
+
+        def gvar(node, access)
+          name = node.name.to_s
+          key = LOAD_PATH_GLOBALS.include?(name) ? :load_path : :access
+          flag(node, key, access: access, name: name)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Audition
+  module Static
+    module Checks
+      # Reading a constant whose value is not *deeply* shareable from
+      # a non-main Ractor raises Ractor::IsolationError.
+      # Classification is deliberately conservative: values we cannot
+      # prove mutable statically (method calls, constant refs,
+      # splats) are left to the dynamic probe.
+      class MutableConstants < Base
+        CONSTANT_WHY =
+          "Reading a constant that holds a non-shareable object " \
+          "from a non-main Ractor raises Ractor::IsolationError " \
+          "(\"can not access non-shareable objects in constant\")."
+
+        explain :mutable_string,
+          severity: :error,
+          message: "constant %{name} holds an unfrozen " \
+                   "String literal",
+          why: CONSTANT_WHY,
+          fix: "Add `# frozen_string_literal: true` to the " \
+               "file, or append `.freeze`."
+
+        explain :mutable_container,
+          severity: :error,
+          message: "constant %{name} holds a mutable %{type} " \
+                   "literal",
+          why: CONSTANT_WHY,
+          fix: "Make it deeply shareable: " \
+               "`# shareable_constant_value: literal`, or " \
+               "wrap in Ractor.make_shareable(...). A bare " \
+               "`.freeze` is not enough when elements are " \
+               "themselves mutable."
+
+        explain :shallow_freeze,
+          severity: :error,
+          message: "constant %{name} is frozen only at the " \
+                   "top level",
+          why: "Ractor shareability is deep: the outer " \
+               "object is frozen but its elements are not, " \
+               "so a non-main Ractor still raises " \
+               "Ractor::IsolationError reading it (verified: " \
+               "[[1], [2]].freeze raises).",
+          fix: "Use Ractor.make_shareable(...) for a deep " \
+               "freeze, or `# shareable_constant_value: " \
+               "literal`."
+
+        explain :sync_primitive,
+          severity: :error,
+          message: "constant %{name} holds a %{klass}; sync " \
+                   "primitives are deliberately unshareable",
+          why: "Mutex/Queue/ConditionVariable coordinate " \
+               "threads inside one Ractor and can never be " \
+               "shared across Ractors; any non-main Ractor " \
+               "touching this constant raises " \
+               "Ractor::IsolationError.",
+          fix: "Use Ractor::Port for cross-Ractor " \
+               "coordination, keep a per-Ractor primitive " \
+               "via Ractor.store_if_absent, or use " \
+               "Ractor-safe structures (ractor_safe, ratomic " \
+               "gems)."
+
+        explain :proc_constant,
+          severity: :error,
+          message: "constant %{name} holds a Proc",
+          why: "Procs capture their creation environment and " \
+               "are not shareable; a non-main Ractor reading " \
+               "this constant raises Ractor::IsolationError.",
+          fix: "Wrap in Ractor.make_shareable(->(...) { ... }); " \
+               "it isolates self-contained lambdas; or " \
+               "promote the logic to a method."
+
+        on :constant_write_node, :constant_or_write_node do |node|
+          examine(node.name.to_s, node, node.value)
+        end
+
+        on :constant_path_write_node,
+          :constant_path_or_write_node do |node|
+          examine(node.target.location.slice, node, node.value)
+        end
+
+        private
+
+        def examine(name, node, value)
+          return if file.shareable_constants?
+
+          case classifier.classify(value)
+          when :mutable_string
+            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,
+              autofix: wrap_make_shareable(value))
+          when :shallow_freeze
+            flag(node, :shallow_freeze, name: name,
+              autofix: replace_with_make_shareable(value))
+          when :sync_primitive
+            flag(node, :sync_primitive, name: name,
+              klass: classifier.const_name(value.receiver))
+          when :proc
+            flag(node, :proc_constant, name: name,
+              autofix: wrap_make_shareable(value))
+          end
+        end
+
+        def classifier
+          @classifier ||= LiteralClassifier.new(
+            frozen_string_literal: file.frozen_string_literal?
+          )
+        end
+
+        def append_freeze(value)
+          offset = value.location.end_offset
+          Autofix.new(
+            start_offset: offset,
+            end_offset: offset,
+            replacement: ".freeze"
+          )
+        end
+
+        def wrap_make_shareable(value)
+          source = value.location.slice
+          Autofix.new(
+            start_offset: value.location.start_offset,
+            end_offset: value.location.end_offset,
+            replacement: "Ractor.make_shareable(#{source})"
+          )
+        end
+
+        # Replaces the whole `<literal>.freeze` call with a deep
+        # wrap of the literal.
+        def replace_with_make_shareable(call)
+          source = call.receiver.location.slice
+          Autofix.new(
+            start_offset: call.location.start_offset,
+            end_offset: call.location.end_offset,
+            replacement: "Ractor.make_shareable(#{source})"
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Audition
+  module Static
+    module Checks
+      # Ractor.new verifies block isolation at creation time: a
+      # block that touches locals from the enclosing scope raises
+      # ArgumentError before the Ractor ever runs. Prism records the
+      # resolution depth of every local reference, so captures are
+      # detectable exactly: a reference whose depth reaches past the
+      # Ractor block's own scope is an outer capture.
+      class RactorIsolation < Base
+        explain :outer_capture,
+          severity: :error,
+          message: "Ractor.new block captures outer local " \
+                   "variable(s) %{names}",
+          why: "Block isolation is checked when Ractor.new " \
+               "runs: touching locals of the enclosing scope " \
+               "raises ArgumentError (\"can not isolate a " \
+               "Proc because it accesses outer variables\").",
+          fix: "Pass the values in as arguments, " \
+               "Ractor.new(x) { |x| ... }, or send them " \
+               "through a Ractor::Port."
+
+        def visit_call_node(node)
+          examine(node)
+          super
+        end
+
+        private
+
+        def examine(node)
+          return unless node.name == :new
+          return unless ractor_receiver?(node.receiver)
+
+          block = node.block
+          return unless block.is_a?(Prism::BlockNode)
+          return unless block.body
+
+          names = CaptureScanner.scan(block.body)
+          return if names.empty?
+
+          flag(node, :outer_capture, names: names.join(", "))
+        end
+
+        def ractor_receiver?(receiver)
+          receiver.is_a?(Prism::ConstantReadNode) &&
+            receiver.name == :Ractor
+        end
+
+        # Walks the Ractor block's body tracking how many block
+        # scopes deep we are; a local reference with depth greater
+        # than that resolves outside the Ractor block.
+        class CaptureScanner < Prism::Visitor
+          def self.scan(body)
+            scanner = new
+            scanner.visit(body)
+            scanner.names.uniq
+          end
+
+          attr_reader :names
+
+          def initialize
+            @names = []
+            @level = 0
+            super
+          end
+
+          def visit_block_node(node)
+            @level += 1
+            super
+          ensure
+            @level -= 1
+          end
+
+          def visit_lambda_node(node)
+            @level += 1
+            super
+          ensure
+            @level -= 1
+          end
+
+          # Method definitions open fresh scopes; nothing inside
+          # them can capture the surrounding locals.
+          def visit_def_node(node)
+          end
+
+          %i[
+            visit_local_variable_read_node
+            visit_local_variable_write_node
+            visit_local_variable_operator_write_node
+            visit_local_variable_or_write_node
+            visit_local_variable_and_write_node
+            visit_local_variable_target_node
+          ].each do |method|
+            define_method(method) do |node|
+              @names << node.name.to_s if node.depth > @level
+              super(node)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Audition
+  module Static
+    module Checks
+      # `require` inside a non-main Ractor works on Ruby 4.0 by
+      # proxying the call to the main Ractor; but that serializes
+      # every Ractor through a single lock, and it means load-time
+      # side effects run mid-request. `autoload` is the same hazard
+      # in disguise: the require fires whenever the constant happens
+      # to be resolved first, possibly inside a Ractor.
+      class RuntimeRequire < Base
+        REQUIRE_METHODS = %i[require require_relative load].freeze
+
+        explain :runtime_require,
+          severity: :warning,
+          message: "%{method} at runtime (inside a method " \
+                   "body)",
+          why: "On Ruby 4.0, require inside a non-main " \
+               "Ractor is proxied to the main Ractor: it " \
+               "works, but all Ractors serialize on it and " \
+               "load-time side effects run at an arbitrary " \
+               "point.",
+          fix: "Require eagerly at boot, before Ractors are " \
+               "spawned."
+
+        explain :autoload,
+          severity: :warning,
+          message: "autoload registers a deferred require",
+          why: "The require fires when the constant is first " \
+               "resolved, which may happen inside a non-main " \
+               "Ractor, serializing Ractors through the " \
+               "main-Ractor require proxy.",
+          fix: "Require eagerly at boot, or resolve the " \
+               "constant once on the main Ractor before " \
+               "spawning."
+
+        on :call_node do |node|
+          if node.receiver.nil?
+            if REQUIRE_METHODS.include?(node.name) && inside_def?
+              unless hoisted_already?(node)
+                flag(node, :runtime_require, method: node.name,
+                  autofix: hoist_autofix(node))
+              end
+            elsif node.name == :autoload
+              flag(node, :autoload,
+                autofix: require_conversion_autofix(node))
+            end
+          end
+        end
+
+        def visit_def_node(node)
+          @def_depth = def_depth + 1
+          super
+        ensure
+          @def_depth -= 1
+        end
+
+        private
+
+        def def_depth = @def_depth ||= 0
+
+        def inside_def? = def_depth.positive?
+
+        def literal_feature(node)
+          return nil unless node.name == :require ||
+            node.name == :require_relative
+
+          arg = node.arguments&.arguments&.first
+          arg if arg.is_a?(Prism::StringNode) &&
+            node.arguments.arguments.size == 1
+        end
+
+        # A method-body require whose feature is already required at
+        # the top of the same file is a fast no-op; not worth a
+        # finding.
+        def hoisted_already?(node)
+          feature = literal_feature(node)
+          !feature.nil? &&
+            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.
+        def hoist_autofix(node)
+          feature = literal_feature(node)
+          return nil unless feature
+
+          insertion = file.boot_insertion
+          offset = insertion[:offset]
+          statement = "#{node.name} #{feature.location.slice}"
+          if insertion[:after_require]
+            Autofix.new(start_offset: offset, end_offset: offset,
+              replacement: "#{statement}\n")
+          else
+            offset += 1 if newline_at?(offset)
+            Autofix.new(start_offset: offset, end_offset: offset,
+              replacement: "#{statement}\n\n")
+          end
+        end
+
+        def newline_at?(offset)
+          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)
+          args = node.arguments&.arguments
+          return nil unless args&.size == 2 &&
+            args[0].is_a?(Prism::SymbolNode) &&
+            args[1].is_a?(Prism::StringNode)
+
+          Autofix.new(
+            start_offset: node.location.start_offset,
+            end_offset: node.location.end_offset,
+            replacement: "require #{args[1].location.slice}",
+            safety: :unsafe
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Audition
+  module Static
+    module Checks
+      # Knowledge base of APIs that are hostile (or noteworthy)
+      # under Ractors, expressed as catalog entries plus call-site
+      # matching rules. Severities reflect behavior verified on
+      # Ruby 4.0; several 3.x-era errors (ENV, trap,
+      # ObjectSpace.each_object) now work and are only
+      # informational.
+      class UnsafeCalls < Base
+        explain :ractor_yield_removed,
+          severity: :error,
+          message: "Ractor.%{method} was removed in Ruby 4.0",
+          why: "The yield/take rendezvous API was replaced " \
+               "by Ractor::Port in Ruby 4.0; calling it " \
+               "raises NoMethodError.",
+          fix: "Create a Ractor::Port, pass it into the " \
+               "Ractor, and use port.send/port.receive; " \
+               "collect results with Ractor#value."
+
+        explain :rails_class_state_macro,
+          severity: :error,
+          message: "%{method} stores state on the class " \
+                   "object",
+          why: "These ActiveSupport macros are backed by " \
+               "class-level instance variables or class " \
+               "variables; both raise Ractor::IsolationError " \
+               "when written (and class variables even when " \
+               "read) from a non-main Ractor.",
+          fix: "Compute the value at boot and store it in a " \
+               "deeply frozen constant, or keep per-Ractor " \
+               "state via Ractor.current[:key] / " \
+               "Ractor.store_if_absent."
+
+        explain :objectspace_id2ref,
+          severity: :warning,
+          message: "ObjectSpace._id2ref cannot resolve " \
+                   "objects across Ractors",
+          why: "Object IDs are only meaningful within the " \
+               "Ractor that created the object; _id2ref is " \
+               "also deprecated since Ruby 3.4.",
+          fix: "Pass objects (or their data) through " \
+               "Ractor::Port messages instead of smuggling " \
+               "object IDs."
+
+        explain :at_exit,
+          severity: :info,
+          message: "at_exit registers a process-global hook",
+          why: "Hooks run on the main Ractor at process " \
+               "exit; registering them from short-lived " \
+               "Ractors accumulates process-global state.",
+          fix: "Register exit hooks once, from the main " \
+               "Ractor, at boot."
+
+        explain :signal_trap,
+          severity: :info,
+          message: "%{receiver}trap installs a process-global " \
+                   "signal handler",
+          why: "Works on Ruby 4.0 even from a Ractor, but " \
+               "the handler is process-wide; Ractors " \
+               "installing competing handlers race.",
+          fix: "Install signal handlers once, on the main " \
+               "Ractor."
+
+        explain :env_write,
+          severity: :info,
+          message: "ENV mutation is process-global",
+          why: "Works on Ruby 4.0 (ENV access from Ractors " \
+               "no longer raises), but the environment is " \
+               "shared mutable state; concurrent Ractors " \
+               "race on it.",
+          fix: "Read configuration into frozen constants at " \
+               "boot instead of mutating ENV at runtime."
+
+        explain :fork,
+          severity: :warning,
+          message: "%{method} from a multi-Ractor process",
+          why: "fork only reproduces the calling thread; " \
+               "other Ractors' threads vanish in the child, " \
+               "leaving their state inconsistent.",
+          fix: "Fork before spawning Ractors, or use " \
+               "spawn/exec."
+
+        explain :singleton_include,
+          severity: :warning,
+          message: "include Singleton memoizes the instance " \
+                   "on the class",
+          why: "Singleton stores its instance in a " \
+               "class-level instance variable; the first " \
+               "access from a non-main Ractor raises " \
+               "Ractor::IsolationError when it tries to " \
+               "write it.",
+          fix: "Eagerly call .instance on the main Ractor " \
+               "at boot (freezing the instance if possible), " \
+               "or use Ractor.store_if_absent."
+
+        RULES = Ractor.make_shareable([
+          {key: :ractor_yield_removed, receiver: "Ractor",
+           methods: %i[yield take]},
+          {key: :rails_class_state_macro, receiver: nil,
+           methods: %i[class_attribute cattr_accessor cattr_reader
+             cattr_writer mattr_accessor mattr_reader
+             mattr_writer thread_mattr_accessor]},
+          {key: :objectspace_id2ref, receiver: "ObjectSpace",
+           methods: %i[_id2ref]},
+          {key: :at_exit, receiver: nil, methods: %i[at_exit]},
+          {key: :signal_trap, receiver: "Signal",
+           methods: %i[trap]},
+          {key: :signal_trap, receiver: nil, methods: %i[trap]},
+          {key: :env_write, receiver: "ENV",
+           methods: %i[[]= store delete update clear replace]},
+          {key: :fork, receiver: nil, methods: %i[fork]},
+          {key: :fork, receiver: "Process",
+           methods: %i[fork daemon]}
+        ])
+
+        on :call_node do |node|
+          apply_rules(node)
+          flag_singleton_include(node)
+        end
+
+        private
+
+        def apply_rules(node)
+          rule = RULES.find do |r|
+            r[:methods].include?(node.name) &&
+              receiver_matches?(r[:receiver], node.receiver)
+          end
+          return unless rule
+
+          receiver = rule[:receiver] ? "#{rule[:receiver]}." : ""
+          flag(node, rule[:key],
+            method: "#{receiver}#{node.name}",
+            receiver: receiver)
+        end
+
+        def receiver_matches?(expected, receiver)
+          return receiver.nil? if expected.nil?
+
+          case receiver
+          when Prism::ConstantReadNode
+            receiver.name.to_s == expected
+          when Prism::ConstantPathNode
+            receiver.location.slice == expected
+          else
+            false
+          end
+        end
+
+        def flag_singleton_include(node)
+          return unless node.name == :include && node.receiver.nil?
+
+          args = node.arguments&.arguments or return
+          singleton = args.any? do |a|
+            a.is_a?(Prism::ConstantReadNode) && a.name == :Singleton
+          end
+          return unless singleton
+
+          flag(node, :singleton_include)
+        end
+      end
+    end
+  end
+end

data/lib/audition/static/checks.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "checks/base"
+require_relative "checks/global_variables"
+require_relative "checks/mutable_constants"
+require_relative "checks/ractor_isolation"
+require_relative "checks/runtime_require"
+require_relative "checks/unsafe_calls"
+
+module Audition
+  module Static
+    module Checks
+      BUILT_IN = [
+        GlobalVariables, MutableConstants, RactorIsolation,
+        RuntimeRequire, UnsafeCalls
+      ].freeze
+
+      # Expression-level checks, run per file. Class variables and
+      # class-level instance variable state are covered semantically
+      # by the rubydex graph audit, not by per-file visitors.
+      #
+      # @return [Array<Class>] built-in plus registered checks
+      def self.all
+        BUILT_IN + registered
+      end
+
+      # Extension point: gems can subclass {Base} and register here.
+      #
+      # @param check [Class] a {Base} subclass
+      # @return [void]
+      def self.register(check)
+        registered << check
+      end
+
+      # @param check [Class] a previously registered check
+      # @return [void]
+      def self.deregister(check)
+        registered.delete(check)
+      end
+
+      def self.registered
+        @registered ||= [] # audition:disable class-level-state
+      end
+    end
+  end
+end