audition 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1605ecba3ed080146001f514aabd1d5b1754ac94623205f9e47500011b3a0894
-  data.tar.gz: acd2a8e10e2c487bfc56b53960b23051795bd2c0274f065146e5d497bc4e11be
+  metadata.gz: 334e1fbfc5a78984722aad73810af312279f67f72bae4b5e60bbbf9433b0f404
+  data.tar.gz: 26c3023a7cdeeee748b61619277c8e749b5a0204b82474b4f06220e9c0fd737d
 SHA512:
-  metadata.gz: 9135eecfc64dbdac1dc3aef23a449f707384d41adb018d634a2940ef1a3eb93cebf0836e333f3d6a6bcb47d4eff9f1efdf219406379202e5a10bd0624785d39f
-  data.tar.gz: 2111276ebb2d9006c1fdcd8bafcac5086cb00bcd3fbcb6c57f5a9f30c4e388181f523be0b5839ca35d4d64bb2ebeb60a1332d41286befc13c84e7166f20a1468
+  metadata.gz: 4c91b4b8ff157e2ff268533657c9dab0c61dc5cc2c0e568790f6c45bee16dfee05f7b0ff830b90aeff43d150278292b967a52dd8ce9baff926b33b23b0bc4992
+  data.tar.gz: 9e639f1a77f804fcc79a196d109fc967a683b07c30411a6832ac9b5315428c30338e1e31b44c7ee448c724fd8a48ce7f7fb6a42411bf0194531b25597cb8e66a

data/README.md

@@ -3,18 +3,23 @@
 Point it at a Ruby script, a gem, a Rack app, or a Rails root and it
 tells you whether that code can run inside Ractors, why it cannot,
 and how to fix it. Unlike a linter, audition does not stop at
-pattern-matching your source: it also loads the target in a
-sandboxed subprocess and observes real `Ractor::IsolationError`s on
-the live object graph.
+pattern-matching your source: whole-program analysis is powered by
+[rubydex](https://github.com/Shopify/rubydex), Shopify's Ruby
+indexer, and the target is also loaded in a sandboxed subprocess
+to observe real `Ractor::IsolationError`s on the live object
+graph. Some of the checks and fixes were trained on how Rails
+core itself is being ractorized; see the
+[pattern study](docs/rails_core_best_practices.md).
 
 [![GitHub Release](https://img.shields.io/github/v/release/yaroslav/audition)](https://github.com/yaroslav/audition/releases)
 [![Docs](https://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/gems/audition)
 
 - **Three probes, one verdict.** Per-file Prism AST checks,
-  whole-program semantic analysis on the
-  [rubydex](https://github.com/Shopify/rubydex) graph (class-level
-  state is resolved across files and reopenings), and dynamic
-  in-Ractor execution of the actual target.
+  whole-program semantic analysis powered by
+  [rubydex](https://github.com/Shopify/rubydex) (Shopify's code
+  graph; class-level state is resolved across files and
+  reopenings), and dynamic in-Ractor execution of the actual
+  target.
 - **Explains, not just flags.** Every finding carries a `why`
   (which rule of the Ractor model it violates) and a `fix`
   (what to write instead).
@@ -22,14 +27,28 @@ the live object graph.
   `.freeze` on string constants, `Ractor.make_shareable(...)` for
   mutable and shallow-frozen containers and Proc constants, and
   boot-time hoisting of method-body requires. `--fix-unsafe` adds
-  semantics-affecting rewrites: magic-comment insertion, class
-  memoization to `Ractor.store_if_absent`, `autoload` to
-  `require`, and write-once globals/class variables to frozen
-  constants. `--dry-run` previews everything as a diff.
+  semantics-affecting rewrites: magic-comment insertion,
+  freeze-on-memoize for class-level memoization (both `@x ||=`
+  and `return @x if defined?(@x)` idioms keep their caching, the
+  memoized value becomes shareable, Rails-core style;
+  `Ractor.store_if_absent` only for block initializers and
+  invalidated caches), `autoload` to `require`, and write-once
+  globals/class variables to frozen constants. `--dry-run`
+  previews everything as a diff.
 - **Dependency-aware.** Runtime findings are attributed to their
   source via `const_source_location`; when your own code is clean
   but a dependency is not, the verdict is a distinct `blocked`
   state, so `globalid` is not blamed for ActiveSupport's state.
+- **Dogfooding.** The scanner for Ractor compatibility is built
+  using Ractors: static analysis fans out across CPU cores on
+  Ractor workers, and audition passes its own audit.
+- **Trained on Rails core.** Several checks and fix suggestions
+  come straight from studying the Rails ractorization effort
+  (about 75 substantive commits): `Hash.new` default procs,
+  in-place mutation of registry constants, closure-carrying
+  `define_method`, copy-on-write rewrites. The findings are
+  documented in
+  [docs/rails_core_best_practices.md](docs/rails_core_best_practices.md).
 - **Terminal-native output.** Colors, glyphs, and OSC 8 hyperlinks;
   `path:line` is clickable in supporting terminals. JSON output for
   CI.
@@ -94,7 +113,6 @@ proxying) and its verified semantics.
 - [Usage](#usage)
 - [Adopting incrementally](#adopting-incrementally)
 - [What it catches](#what-it-catches)
-- [Field notes](#field-notes)
 - [Extending](#extending)
 - [Development](#development)
 - [License](#license)
@@ -191,14 +209,19 @@ Static, with file:line precision:
 - **Class variables**, resolved on the rubydex graph.
 - **Class-level instance variables**, unified across the class
   body, `def self.`, and `class << self`, across files; the classic
-  `@cache ||= {}` memoization.
+  `@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.
 - **Sync primitives and Procs in constants** (Mutex, Queue,
-  lambdas).
+  lambdas), including `Hash.new { }` default procs, which stay
+  unshareable even after `.freeze`.
+- **Registry-style constant mutation** (`RENDERERS << key`,
+  `LOOKUP[k] = v`) and **`define_method` with a literal block**
+  (the method carries an unshareable Proc); both patterns and
+  their fixes come from the Rails core ractorization study.
 - **Runtime require and autoload** (serializes all Ractors through
   the main-Ractor proxy).
 - **`Ractor.new` blocks capturing outer locals** (the ArgumentError
@@ -222,21 +245,6 @@ Dynamic, on the live object graph:
 - Boots Rails (`config/environment.rb`), eager-loads, and sweeps
   the application's namespaces.
 
-## Field notes
-
-Findings from running audition on popular gems (July 2026,
-Ruby 4.0.6):
-
-- **rack 3.2**: `Rack::Builder.parse_file` cannot run inside a
-  Ractor at all; `Rack::BUILDER_TOPLEVEL_BINDING` holds an
-  unshareable Binding. audition's own rack probe rebuilds the app
-  with `Rack::Builder.new` + `instance_eval` to get around it.
-- **mail 2.9**: 28 hard findings, including `@@maximum_amount`,
-  `@@autoloads`, and unfrozen table constants like `FIELDS_MAP`.
-- **globalid 1.3**: only 6 findings of its own; the rest of its
-  report is ActiveSupport state, attributed as dependency errors
-  in the summary.
-
 ## Extending
 
 Checks are written in a small declarative DSL and can be registered

data/exe/audition

@@ -1,6 +1,14 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+# When run from a source checkout, prefer the sibling lib over any
+# installed audition gem; installed binstubs never hit this branch
+# because their lib is where they load from anyway.
+lib = File.expand_path("../lib", __dir__)
+if File.file?(File.join(lib, "audition.rb"))
+  $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+end
+
 require "audition"
 
 exit Audition::CLI.run(ARGV)

data/lib/audition/dynamic/prober.rb

@@ -201,21 +201,33 @@ module Audition
         findings
       end
 
+      # Class-level state holding only shareable values is the
+      # warmed frozen-memoization shape: reads are legal from any
+      # Ractor, so it rates an info note; unshareable values are
+      # hard errors.
       def class_state_finding(entry, label)
         unshareable = entry.fetch("unshareable", [])
         hot = unshareable.any?
         detail =
           hot ? " (unshareable: #{unshareable.join(", ")})" : ""
+        why =
+          if hot
+            "Writes raise Ractor::IsolationError from non-main " \
+            "Ractors; reads raise too while the value is " \
+            "unshareable. #{RUNTIME_WHY}"
+          else
+            "Every value observed here is shareable, so reads " \
+            "from non-main Ractors are legal; only late writes " \
+            "would raise Ractor::IsolationError. #{RUNTIME_WHY}"
+          end
         runtime_finding(
           entry, label,
           check: "runtime-class-state",
-          severity: hot ? :error : :warning,
+          severity: hot ? :error : :info,
           message: "class-level state " \
                    "#{entry["ivars"].join(", ")} on " \
                    "#{entry["const"]}#{detail}",
-          why: "Writes raise Ractor::IsolationError from non-main " \
-               "Ractors; reads raise too while the value is " \
-               "unshareable. #{RUNTIME_WHY}",
+          why: why,
           fix: "Precompute and freeze at load, use " \
                "Ractor.store_if_absent, or keep per-Ractor state."
         )

data/lib/audition/fixer.rb

@@ -105,37 +105,65 @@ module Audition
       accepted
     end
 
+    # Prism offsets are byte offsets; splicing must happen on a
+    # binary copy or every edit after the first multibyte
+    # character lands short (addressable's unicode tables were
+    # the crash test).
     def patched(plan)
-      source = plan.source.dup
+      encoding = plan.source.encoding
+      bytes = plan.source.dup.force_encoding(Encoding::BINARY)
       plan.edits.each do |edit|
-        source[edit.start_offset...edit.end_offset] =
-          edit.replacement
+        bytes[edit.start_offset...edit.end_offset] =
+          edit.replacement.dup.force_encoding(Encoding::BINARY)
       end
-      source
+      bytes.force_encoding(encoding)
     end
 
+    # Edits whose line windows overlap (a guard deletion runs into
+    # the write it pairs with) render as one hunk, so the preview
+    # never repeats a line in two half-applied states. All window
+    # math runs on a binary copy: the offsets are bytes.
     def hunks(plan)
-      plan.edits.sort_by(&:start_offset).map do |edit|
-        line_start =
-          if edit.start_offset.zero?
-            0
-          else
-            before = plan.source.rindex("\n", edit.start_offset - 1)
-            before ? before + 1 : 0
-          end
-        line_end = plan.source.index("\n", edit.end_offset) ||
-          plan.source.length
-        old = plan.source[line_start...line_end]
+      encoding = plan.source.encoding
+      raw = plan.source.dup.force_encoding(Encoding::BINARY)
+      groups = []
+      plan.edits.sort_by(&:start_offset).each do |edit|
+        from, upto = line_window(raw, edit)
+        if groups.any? && from <= groups.last[:upto]
+          last = groups.last
+          last[:upto] = [last[:upto], upto].max
+          last[:edits] << edit
+        else
+          groups << {from: from, upto: upto, edits: [edit]}
+        end
+      end
+      groups.map do |group|
+        old = raw[group[:from]...group[:upto]]
         updated = old.dup
-        span = ((edit.start_offset - line_start)...
-                (edit.end_offset - line_start))
-        updated[span] = edit.replacement
+        group[:edits].reverse_each do |edit|
+          span = ((edit.start_offset - group[:from])...
+                  (edit.end_offset - group[:from]))
+          updated[span] =
+            edit.replacement.dup.force_encoding(Encoding::BINARY)
+        end
         {
-          line: plan.source[0, edit.start_offset].count("\n") + 1,
-          old: old,
-          new: updated.chomp
+          line: raw[0, group[:from]].count("\n") + 1,
+          old: old.force_encoding(encoding),
+          new: updated.chomp.force_encoding(encoding)
         }
       end
     end
+
+    def line_window(raw, edit)
+      from =
+        if edit.start_offset.zero?
+          0
+        else
+          before = raw.rindex("\n", edit.start_offset - 1)
+          before ? before + 1 : 0
+        end
+      upto = raw.index("\n", edit.end_offset) || raw.length
+      [from, upto]
+    end
   end
 end

data/lib/audition/report.rb

@@ -39,7 +39,7 @@ module Audition
       end
 
       PAINTS.each do |name|
-        define_method(name) do |text|
+        define_method(name) do |text| # audition:disable unsafe-calls
           @pastel.public_send(name, text)
         end
       end
@@ -110,9 +110,10 @@ module Audition
       return :not_ready if own_errors?
       return :blocked if dependency_errors? ||
         dynamic_results.any? { |r| !r.passed }
-      return :risky if counts[:warning].positive? ||
-        counts[:info].positive?
+      return :risky if counts[:warning].positive?
 
+      # Info notes describe things that work on Ruby 4.0 and are
+      # only worth knowing; they do not taint the verdict.
       :ready
     end