audition 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffdbe2eefef3af0a17fba242519ba4816609fe9447869c39e71a48a7737dbd0d
-  data.tar.gz: 84c792ede67f91c87253f73a8e55d4ca6d7bd08eef4cf7c7aa0d742cefb6aa51
+  metadata.gz: 76a1b0c57c7a373182f7b9f88f765fa8e0167a492e28d028998335bc246c10d9
+  data.tar.gz: 2c5ecb49ed0a63ebd7a58cb3db9e8b5e8f9893953198d1c3e9f0cc5ca74cfb3a
 SHA512:
-  metadata.gz: 45393085ad096c90da3218561537b6dd0825eecb82a03f08c22757ab4abd7e1f765936e2dc81015501285b1348272e87830f6af60a00dc46ac05599c7096d6d0
-  data.tar.gz: f587211f3f9e4a4c72b4719611359ae32a6219271183a17fa2a5be5f8ba80195e0aa7233c435e793bdf5e9eee23da49ce4f0261c6dc6d68111d87aa4b504c158
+  metadata.gz: 633d141cdc23a3e2e24df8b983b9112ffa9a759194669c4f9a6f62f0bf07219b507bd72cea8235de3c7193ab934c60ca8c98ee2095eabe21fad2e80f682ea8e2
+  data.tar.gz: bfd863839b4d5fbea291d22282487de79d261fd55bba5662d82d285e013827290257ca61d5b637000581453ec8f3a0510b1571bf6492d1b9f6f9e7de9f3af225

data/README.md

@@ -116,6 +116,7 @@ proxying) and its verified semantics.
 - [Agent skill](#agent-skill)
 - [Extending](#extending)
 - [Development](#development)
+- [Acknowledgements](#acknowledgements)
 - [License](#license)
 
 ## Installation
@@ -212,10 +213,12 @@ Static, with file:line precision:
   body, `def self.`, and `class << self`, across files; the classic
   `@cache ||= {}` and `return @x if defined?(@x)` memoizations.
 - **Constants that are not deeply shareable**: bare mutable
-  literals, interpolated strings, and the subtle shallow freeze
-  (`[[1], [2]].freeze` still raises; audition explains why).
-  Honors `# frozen_string_literal:` and
-  `# shareable_constant_value:` magic comments.
+  literals, interpolated strings, the subtle shallow freeze
+  (`[[1], [2]].freeze` still raises; audition explains why), and
+  call results the magic comment never covers (`X.tr(":", "")`,
+  `Regexp.new`, `Regexp.union`, `format`), the shapes Rails fixed
+  last in its own ractorization. Honors `# frozen_string_literal:`
+  and `# shareable_constant_value:` magic comments.
 - **Sync primitives and Procs in constants** (Mutex, Queue,
   lambdas), including `Hash.new { }` default procs, which stay
   unshareable even after `.freeze`.
@@ -228,7 +231,9 @@ Static, with file:line precision:
 - **`Ractor.new` blocks capturing outer locals** (the ArgumentError
   at creation time), resolved through Prism's exact scope depths.
 - **Hostile or removed APIs**: `Ractor.yield`/`take` (gone in 4.0),
-  ActiveSupport `class_attribute`/`cattr_*`/`mattr_*`,
+  ActiveSupport `cattr_*`/`mattr_*` class variables (with the
+  `class_attribute` migration Rails itself made) and
+  `class_attribute` without copy-on-write writes,
   `include Singleton`, `fork`, `ObjectSpace._id2ref`, ENV mutation.
 
 Dynamic, on the live object graph:
@@ -312,6 +317,19 @@ The design notes in `docs/design.md` include the empirically
 verified Ruby 4.0 Ractor semantics table that the checks are
 calibrated against.
 
+## Acknowledgements
+
+The whole-program checks stand on
+[rubydex](https://github.com/Shopify/rubydex), Shopify's
+high-performance static analysis suite for Ruby: audition feeds
+every file into its graph and reads state ownership back out.
+Thanks to its authors, in particular the top five contributors:
+[Alexandre Terrasa](https://github.com/Morriar),
+[Vinicius Stock](https://github.com/vinistock),
+[Alex Rocha](https://github.com/alexcrocha),
+[Stan Lo](https://github.com/st0012), and
+[Soutaro Matsumoto](https://github.com/soutaro).
+
 ## Assisted by
 
 Claude Fable 5.

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

@@ -22,6 +22,19 @@ module Audition
           fix: "Add `# frozen_string_literal: true` to the " \
                "file, or append `.freeze`."
 
+        explain :mutable_call,
+          severity: :error,
+          message: "constant %{name} holds an unfrozen %{type} " \
+                   "returned by %{method}",
+          why: "`# frozen_string_literal: true` freezes " \
+               "literals only; a method call returns a fresh " \
+               "unfrozen object, so a non-main Ractor reading " \
+               "this constant raises Ractor::IsolationError. " \
+               "Rails hit this with `.tr` and `Regexp.new` " \
+               "during its ractorization.",
+          fix: "Append `.freeze` to the call; a frozen String " \
+               "or Regexp is deeply shareable."
+
         explain :mutable_container,
           severity: :error,
           message: "constant %{name} holds a mutable %{type} " \
@@ -56,8 +69,10 @@ module Audition
                "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 " \
+               "coordination; keep a per-Ractor primitive " \
+               "via Ractor.store_if_absent when the state it " \
+               "guards is per-Ractor too (Rails moved its " \
+               "template digest mutex this way); or use " \
                "Ractor-safe structures (ractor_safe, ratomic " \
                "gems)."
 
@@ -97,7 +112,12 @@ module Audition
                "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."
+               "copy-on-write style Rails registries use. A " \
+               "registry that plugins extend during boot is " \
+               "frozen in the last boot hook (after_initialize) " \
+               "rather than at definition, and writes after the " \
+               "freeze merge into a fresh frozen copy with a " \
+               "deprecation instead of raising."
 
         on :constant_write_node, :constant_or_write_node do |node|
           examine(node.name.to_s, node, node.value)
@@ -131,6 +151,10 @@ module Audition
           when :mutable_string
             flag(node, :mutable_string, name: name,
               autofix: fix_ok ? append_freeze(value) : nil)
+          when :mutable_call
+            flag(node, :mutable_call, name: name,
+              type: call_type(value), method: call_display(value),
+              autofix: fix_ok ? append_freeze(value) : nil)
           when :mutable_container
             flag(node, :mutable_container, name: name,
               type: container_type(value),
@@ -151,6 +175,7 @@ module Audition
             # a class or module body get the wrap.
             body = proc_body(value)
             wrappable = fix_ok && namespaced?(node) &&
+              !opaque_proc?(value) &&
               (body.nil? ||
                 RactorIsolation::CaptureScanner
                   .scan(body).empty?)
@@ -175,10 +200,16 @@ module Audition
         def proc_body(value)
           case value
           when Prism::LambdaNode then value.body
-          when Prism::CallNode then value.block&.body
+          when Prism::CallNode
+            block = value.block
+            block.body if block.is_a?(Prism::BlockNode)
           end
         end
 
+        def opaque_proc?(value)
+          value.is_a?(Prism::CallNode) && value.block.is_a?(Prism::BlockArgumentNode)
+        end
+
         def namespaced?(node)
           offset = node.location.start_offset
           module_ranges.any? { |range| range.cover?(offset) }
@@ -245,10 +276,36 @@ module Audition
 
         # Ternaries classify as strings when both branches are;
         # `.freeze` binds tighter than `?:`, so they get parens.
+        def call_type(call)
+          owner = classifier.const_name(call.receiver)
+          (owner == "Regexp") ? "Regexp" : "String"
+        end
+
+        def call_display(call)
+          return call.name.to_s if call.receiver.nil?
+
+          owner = classifier.const_name(call.receiver)
+          owner ? "#{owner}.#{call.name}" : "String##{call.name}"
+        end
+
+        # `.freeze` binds tighter than an operator: `"a" + "b".freeze`
+        # freezes only "b", so operator calls get parentheses while
+        # literals and parenthesized or argument-free calls take
+        # the bare suffix.
+        def bare_freezable?(value)
+          case value
+          when Prism::StringNode, Prism::InterpolatedStringNode
+            true
+          when Prism::CallNode
+            !value.opening_loc.nil? ||
+              (!value.receiver.nil? && value.arguments.nil?)
+          else
+            false
+          end
+        end
+
         def append_freeze(value)
-          string = value.is_a?(Prism::StringNode) ||
-            value.is_a?(Prism::InterpolatedStringNode)
-          if string
+          if bare_freezable?(value)
             offset = value.location.end_offset
             Autofix.new(
               start_offset: offset,

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

@@ -20,19 +20,36 @@ module Audition
                "Ractor, and use port.send/port.receive; " \
                "collect results with Ractor#value."
 
-        explain :rails_class_state_macro,
+        explain :rails_class_variable_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."
+          message: "%{method} stores state in a class variable",
+          why: "The cattr_* and mattr_* macros define @@ class " \
+               "variables; reads and writes alike raise " \
+               "Ractor::IsolationError from a non-main Ractor, " \
+               "whatever the value holds.",
+          fix: "Rails itself migrated these to class_attribute " \
+               "(a class-level ivar whose frozen value any " \
+               "Ractor may read) or to a module ivar behind a " \
+               "reader; give it a frozen default and rebuild " \
+               "and refreeze on write, at boot on the main " \
+               "Ractor."
+
+        explain :rails_class_attribute,
+          severity: :warning,
+          message: "%{method} stores state on the class object",
+          why: "The value lives in a class-level instance " \
+               "variable. Rails 8.2 made the reader Ractor-safe, " \
+               "so a frozen value is readable from any Ractor; " \
+               "earlier readers are define_method closures that " \
+               "raise on the first call from a non-main Ractor " \
+               "(thread_mattr_accessor memoized its key the " \
+               "same way). Writes always need the main Ractor.",
+          fix: "Give it a frozen default (default: [].freeze) " \
+               "and write copy-on-write: self.x = (x | [v])" \
+               ".freeze, the idiom Rails applied across Action " \
+               "Pack and Active Record; do every write at boot " \
+               "on the main Ractor. The dynamic probe reports " \
+               "ground truth for the installed Rails."
 
         explain :objectspace_id2ref,
           severity: :warning,
@@ -91,13 +108,15 @@ module Audition
                "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."
+          fix: "Pass a shareable lambda instead of a block: " \
+               "define_method(:x, Ractor.shareable_lambda " \
+               "{ ... }), as Rails did for its date selectors " \
+               "and url helpers. Captured locals must be " \
+               "shareable (strings become symbols) and assigned " \
+               "before the lambda is created, and super is " \
+               "unavailable. When the captures are literals, " \
+               "generate the method with class_eval and a " \
+               "source string instead."
 
         explain :singleton_include,
           severity: :warning,
@@ -115,10 +134,11 @@ module Audition
         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: :rails_class_variable_macro, receiver: nil,
+           methods: %i[cattr_accessor cattr_reader cattr_writer
+             mattr_accessor mattr_reader mattr_writer]},
+          {key: :rails_class_attribute, receiver: nil,
+           methods: %i[class_attribute thread_mattr_accessor]},
           {key: :objectspace_id2ref, receiver: "ObjectSpace",
            methods: %i[_id2ref]},
           {key: :at_exit, receiver: nil, methods: %i[at_exit]},

data/lib/audition/static/graph_audit.rb

@@ -27,14 +27,18 @@ module Audition
         "it while it holds a non-shareable value (verified on " \
         "Ruby 4.0)."
       STATE_FIX =
-        "Precompute and freeze the value at load time (for " \
-        "per-subclass values, in the inherited hook). For " \
+        "Precompute and freeze the value at load time: a memo " \
+        "that needs no configuration becomes a frozen private " \
+        "constant (EMPTY = new(nil, nil).freeze), a cheap " \
+        "derivation drops its memo altogether, and " \
+        "per-subclass values compute in the inherited hook " \
+        "(guard on subclass.name for anonymous classes). For " \
         "collections, rebuild and refreeze on write, " \
         "Rails-style copy-on-write: self.list = " \
         "(list + [item]).freeze; never mutate in place. As a " \
-        "last resort use Ractor.store_if_absent for lazy " \
-        "initialization or per-Ractor state in " \
-        "Ractor.current[:key]."
+        "last resort use Ractor.store_if_absent for " \
+        "per-Ractor state, or read the ivar first and proxy " \
+        "the write to the main Ractor."
       FROZEN_MEMO_WHY =
         "Every write memoizes a shareable (frozen) value, so " \
         "non-main Ractors can read it once it has been " \
@@ -44,10 +48,13 @@ module Audition
         "memoized class state."
       FROZEN_MEMO_FIX =
         "Warm the cache at boot, before spawning Ractors: call " \
-        "the memoizing method from an initializer or on_load " \
-        "hook. If the value genuinely must be computed at " \
-        "runtime, proxy the write to the main Ractor or use " \
-        "Ractor.store_if_absent."
+        "the memoizing method from an initializer, an on_load " \
+        "hook, an eager_load! override, or the inherited hook. " \
+        "A value that can be nil or false never sticks under " \
+        "||=, so guard it with defined? instead. If the value " \
+        "genuinely must be computed at runtime, read the ivar " \
+        "first and proxy only the write to the main Ractor, or " \
+        "use Ractor.store_if_absent."
       BEST_EFFORT_WHY =
         "Writes wrap their value in Ractor.make_shareable with " \
         "a rescue fallback: shareable values are deeply frozen " \

data/lib/audition/static/literal_classifier.rb

@@ -8,6 +8,8 @@ module Audition
     #   :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`)
     #   :shallow_freeze    frozen container with mutable elements
     #   :sync_primitive    Mutex/Queue/... constructor
     #   :proc              lambda or proc
@@ -22,6 +24,24 @@ module Audition
       ].freeze
       SHAREABLE_FACTORIES = %w[Struct Class Module].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
+      # to String alone in core, so any receiver qualifies.
+      STRING_ONLY_METHODS = %i[
+        tr tr_s gsub sub squeeze strip lstrip rstrip chomp chop
+        center ljust rjust encode scrub unicode_normalize
+      ].freeze
+      # Unambiguous only on a String literal receiver: Symbols
+      # and numbers define these too and return shareable values.
+      STRING_LITERAL_METHODS = %i[
+        + * % upcase downcase capitalize swapcase reverse dup
+        succ next
+      ].freeze
+      FORMATTERS = %i[format sprintf].freeze
+      REGEXP_FACTORIES = %i[new union compile].freeze
+
       # @param frozen_string_literal [Boolean] whether the file has
       #   the frozen_string_literal magic comment
       def initialize(frozen_string_literal:)
@@ -92,6 +112,9 @@ module Audition
       end
 
       def classify_call(node)
+        return :mutable_call if fresh_string?(node) ||
+          fresh_regexp?(node)
+
         receiver = node.receiver
         case node.name
         when :freeze
@@ -130,13 +153,42 @@ module Audition
         when Prism::ArrayNode, Prism::HashNode
           deep_classify(receiver.elements)
         when Prism::CallNode
-          # A default proc survives freezing the Hash.
-          (classify(receiver) == :default_proc) ? :default_proc : :unknown
+          # A default proc survives freezing the Hash; a frozen
+          # String or Regexp from a call is deeply shareable.
+          case classify(receiver)
+          when :default_proc then :default_proc
+          when :mutable_call then :shareable
+          else :unknown
+          end
         else
           :unknown
         end
       end
 
+      def fresh_string?(node)
+        receiver = node.receiver
+        name = node.name
+        case receiver
+        when nil
+          FORMATTERS.include?(name)
+        when Prism::StringNode, Prism::InterpolatedStringNode
+          STRING_ONLY_METHODS.include?(name) ||
+            STRING_LITERAL_METHODS.include?(name)
+        when Prism::ConstantReadNode, Prism::ConstantPathNode
+          owner = const_name(receiver)
+          (name == :new && owner == "String") ||
+            (owner == "Kernel" && FORMATTERS.include?(name)) ||
+            STRING_ONLY_METHODS.include?(name)
+        else
+          false
+        end
+      end
+
+      def fresh_regexp?(node)
+        REGEXP_FACTORIES.include?(node.name) &&
+          const_name(node.receiver) == "Regexp"
+      end
+
       # A container holding a sync primitive can never become
       # shareable; Ractor.make_shareable raises on it (multi_json
       # keeps a frozen Hash of Mutexes). The classification

data/lib/audition/version.rb

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

metadata

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