audition 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1605ecba3ed080146001f514aabd1d5b1754ac94623205f9e47500011b3a0894
+  data.tar.gz: acd2a8e10e2c487bfc56b53960b23051795bd2c0274f065146e5d497bc4e11be
+SHA512:
+  metadata.gz: 9135eecfc64dbdac1dc3aef23a449f707384d41adb018d634a2940ef1a3eb93cebf0836e333f3d6a6bcb47d4eff9f1efdf219406379202e5a10bd0624785d39f
+  data.tar.gz: 2111276ebb2d9006c1fdcd8bafcac5086cb00bcd3fbcb6c57f5a9f30c4e388181f523be0b5839ca35d4d64bb2ebeb60a1332d41286befc13c84e7166f20a1468

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yaroslav Markin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,290 @@
+# Audition
+
+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.
+
+[![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.
+- **Explains, not just flags.** Every finding carries a `why`
+  (which rule of the Ractor model it violates) and a `fix`
+  (what to write instead).
+- **`--fix` like RuboCop, in two tiers.** Safe corrections:
+  `.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.
+- **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.
+- **Terminal-native output.** Colors, glyphs, and OSC 8 hyperlinks;
+  `path:line` is clickable in supporting terminals. JSON output for
+  CI.
+
+```console
+$ audition worker.rb
+* audition 0.1.0 ruby 4.0.6 · script at .
+
+  worker.rb
+    x raises inside a Ractor: Ractor::IsolationError: can not
+      access global variable $jobs from non-main Ractor
+      why: The script ran fine on the main Ractor but failed under
+      Ractor.new; the static findings usually pinpoint the line.
+    x worker.rb:1  write to global variable $jobs
+      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].
+    x worker.rb:4  read of global variable $jobs
+      ...
+
+  dynamic probes
+    x script probe failed (details above)
+
+  summary: 3 errors
+  verdict: x not ractor-ready
+$ echo $?
+1
+```
+
+And the whole-bundle view:
+
+```console
+$ audition Gemfile.lock --static-only
+╭───────────────┬─────────┬───────────┬────────┬──────────┬─────────╮
+│ gem           │ version │ verdict   │ errors │ warnings │ fixable │
+├───────────────┼─────────┼───────────┼────────┼──────────┼─────────┤
+│ activesupport │ 8.1.0   │ not ready │    157 │       97 │      77 │
+│ i18n          │ 1.14.7  │ not ready │     48 │       40 │      45 │
+│ mail          │ 2.9.1   │ not ready │     27 │        4 │      13 │
+│ rack          │ 3.2.6   │ not ready │     23 │       45 │      60 │
+│ ...           │         │           │        │          │         │
+╰───────────────┴─────────┴───────────┴────────┴──────────┴─────────╯
+0 of 11 gems ractor-ready
+```
+
+**Requires Ruby 4.0 or newer**, strictly: the tool targets the modern
+Ractor API (`Ractor::Port`, `Ractor#value`, main-Ractor `require`
+proxying) and its verified semantics.
+
+> [!WARNING]
+> The entire codebase was written by Claude Fable 5 (Anthropic).
+> It has a thorough spec suite and was validated against real
+> gems, but no human has reviewed every line. Be wary; read before
+> you trust, especially `--fix` rewrites.
+
+## Table of contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [Adopting incrementally](#adopting-incrementally)
+- [What it catches](#what-it-catches)
+- [Field notes](#field-notes)
+- [Extending](#extending)
+- [Development](#development)
+- [License](#license)
+
+## Installation
+
+```console
+gem install audition
+```
+
+Or in a Gemfile:
+
+```ruby
+gem "audition", require: false
+```
+
+## Usage
+
+```console
+audition worker.rb            # a script: static + run inside Ractor
+audition my_gem               # an installed gem, by name
+audition path/to/gem-checkout # a gem working copy (*.gemspec)
+audition path/to/rack-app     # a config.ru directory
+audition path/to/rails-root   # a Rails application
+audition lib                  # any directory, static-only
+audition Gemfile.lock         # sweep every gem in the bundle
+audition path/to/app --deps   # same, from the app root
+```
+
+Useful flags:
+
+| Flag | Effect |
+| --- | --- |
+| `--deps` | sweep the target's Gemfile.lock gem by gem |
+| `--write-baseline` / `--no-baseline` | record / ignore known findings |
+| `--fix` | apply safe corrections, then re-check |
+| `--fix-unsafe` | also apply semantics-affecting corrections |
+| `--dry-run` | with a fix flag: preview edits, change nothing |
+| `--format json` | machine-readable report for CI |
+| `--format github` | GitHub Actions annotations on PR diffs |
+| `--compare old.json` | delta vs a previous report: fixed/introduced |
+| `--static-only` / `--dynamic-only` | pick one probe layer |
+| `--fail-on warning` | stricter CI gate (default: error) |
+| `--capabilities` | table of what this Ruby allows in Ractors |
+| `--timeout 60` | dynamic probe budget in seconds |
+| `--plain` | no colors or hyperlinks (also via NO_COLOR, pipes) |
+
+Exit codes: `0` clean, `1` findings at or above the `--fail-on`
+threshold (or a failed dynamic probe), `2` usage error.
+
+## Adopting incrementally
+
+Nobody goes from 150 findings to zero in one commit. Three tools
+keep the gate useful from day one:
+
+**Baseline.** Record today's findings, then fail CI only on new
+ones:
+
+```console
+audition . --write-baseline    # writes .audition-baseline.json
+audition .                     # exit 0; summary shows "N baselined"
+```
+
+The ledger stores per-check-per-file counts, so line drift never
+invalidates it. `--no-baseline` shows everything again.
+
+**Inline pragmas.** Silence a single line, rubocop-style:
+
+```ruby
+$legacy_flag = true # audition:disable global-variables
+risky_call          # audition:disable
+```
+
+**Project config.** `.audition.yml` at the target root
+(CLI flags always win):
+
+```yaml
+fail_on: warning
+timeout: 60
+exclude:
+  - legacy/**
+  - db/schema.rb
+checks:
+  disable:
+    - at-exit
+```
+
+## What it catches
+
+Static, with file:line precision:
+
+- **Global variables**, with a verified allowlist: `$stdout`, `$~`,
+  `$!`, `$VERBOSE` writes and friends stay legal.
+- **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.
+- **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).
+- **Runtime require and autoload** (serializes all Ractors through
+  the main-Ractor proxy).
+- **`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_*`,
+  `include Singleton`, `fork`, `ObjectSpace._id2ref`, ENV mutation.
+
+Dynamic, on the live object graph:
+
+- Runs scripts inside a real Ractor (via `load`, which is not
+  proxied) and reports the actual exception.
+- Requires a library, then sweeps every constant it introduced with
+  `Ractor.shareable?`, and inspects every class and module for
+  class-level ivars and class variables, with
+  `const_source_location` attribution.
+- Boots `config.ru` and serves one GET / entirely inside a Ractor,
+  the per-worker model of Ractor web servers; then hammers it from
+  4 Ractors x 25 requests to surface failures that only appear
+  under concurrency.
+- 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
+from outside the gem:
+
+```ruby
+class NoSleep < Audition::Static::Checks::Base
+  check_name "no-sleep"
+
+  explain :sleepy,
+          severity: :warning,
+          message: "sleep inside potential Ractor code",
+          why: "Blocking one Ractor blocks its whole OS thread.",
+          fix: "Prefer Ractor::Port#receive with a timeout."
+
+  on :call_node do |node|
+    flag(node, :sleepy) if node.name == :sleep && !node.receiver
+  end
+end
+
+Audition::Static::Checks.register(NoSleep)
+```
+
+`on` generates the Prism visitor and always continues traversal;
+`explain` entries are a message catalog with `%{placeholders}`.
+
+## Development
+
+```console
+bundle install
+bundle exec rake spec       # RSpec suite
+bundle exec rake standard   # standardrb lint
+lefthook install            # pre-commit lint hook
+bundle exec exe/audition --capabilities
+```
+
+Static scanning is Ractor-parallel on large targets (one worker
+per core, minus one for the main Ractor); audition's own `lib/`
+passes `audition lib` clean.
+
+The design notes in `docs/design.md` include the empirically
+verified Ruby 4.0 Ractor semantics table that the checks are
+calibrated against.
+
+## Assisted by
+
+Claude Fable 5.
+
+## License
+
+MIT. See LICENSE.txt.

data/exe/audition

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "audition"
+
+exit Audition::CLI.run(ARGV)

data/lib/audition/baseline.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Audition
+  # Incremental-adoption ledger (.audition-baseline.json): known
+  # findings recorded as counts per "check|relative/path" so line
+  # drift never invalidates it. Present findings up to the recorded
+  # count are hidden; anything beyond is new and fails as usual.
+  class Baseline
+    FILE = ".audition-baseline.json"
+
+    def self.path_for(root)
+      File.join(root.to_s, FILE)
+    end
+
+    def self.write(root, findings)
+      counts = Hash.new(0)
+      findings.each { |f| counts[key(f, root)] += 1 }
+      File.write(
+        path_for(root),
+        JSON.pretty_generate(counts.sort.to_h) << "\n"
+      )
+      counts.values.sum
+    end
+
+    def self.load(root)
+      path = path_for(root)
+      return nil unless File.file?(path)
+
+      new(JSON.parse(File.read(path)))
+    rescue JSON::ParserError => e
+      raise Error, "#{path}: #{e.message}"
+    end
+
+    def self.key(finding, root)
+      relative =
+        finding.path.to_s.delete_prefix("#{root}/")
+      "#{finding.check}|#{relative}"
+    end
+
+    def initialize(counts)
+      @counts = counts
+    end
+
+    # Budget per key is consumed in finding order.
+    #
+    # @param findings [Array<Finding>]
+    # @param root [String] target root for relative paths
+    # @return [Array(Array<Finding>, Integer)] visible findings
+    #   and the hidden count
+    def filter(findings, root:)
+      budget = @counts.dup
+      hidden = 0
+      visible = findings.reject do |finding|
+        key = self.class.key(finding, root)
+        next false unless budget.fetch(key, 0).positive?
+
+        budget[key] -= 1
+        hidden += 1
+        true
+      end
+      [visible, hidden]
+    end
+  end
+end

data/lib/audition/bundle_sweep.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "bundler"
+
+module Audition
+  # Audits every gem in a Gemfile.lock and ranks the results:
+  # the "can my whole app move to Ractors" view. Static analysis
+  # runs in worker threads; dynamic probes are subprocesses, so
+  # they genuinely parallelize.
+  class BundleSweep
+    CONCURRENCY = 4
+
+    Row = Data.define(:name, :version, :verdict, :errors,
+      :dep_errors, :warnings, :fixable, :status)
+
+    VERDICT_ORDER = {
+      :not_ready => 0, :blocked => 1, :risky => 2, :ready => 3, nil => 4
+    }.freeze
+
+    # @param lockfile [String] path to a Gemfile.lock
+    # @param static_only [Boolean] skip dynamic probes
+    # @param timeout [Integer] per-probe timeout in seconds
+    # @param concurrency [Integer] worker thread count
+    def initialize(lockfile:, static_only: false, timeout: 30,
+      concurrency: CONCURRENCY)
+      @lockfile = lockfile
+      @static_only = static_only
+      @timeout = timeout
+      @concurrency = concurrency
+    end
+
+    # Audits every locked gem and ranks the results, worst first.
+    #
+    # @param progress [Proc, nil] called with (row, done, total)
+    #   as each gem finishes
+    # @return [Array<Row>]
+    def rows(progress: nil)
+      gems = locked_gems
+      queue = Thread::Queue.new
+      gems.each { |g| queue << g }
+      queue.close
+
+      collected = []
+      mutex = Thread::Mutex.new
+      @concurrency.times.map do
+        Thread.new do
+          while (name, version = queue.pop)
+            row = audit_gem(name, version)
+            mutex.synchronize do
+              collected << row
+              progress&.call(row, collected.size, gems.size)
+            end
+          end
+        end
+      end.each(&:join)
+
+      collected.sort_by do |row|
+        [VERDICT_ORDER.fetch(row.verdict), -row.errors, row.name]
+      end
+    end
+
+    private
+
+    def locked_gems
+      parser = Bundler::LockfileParser.new(File.read(@lockfile))
+      parser.specs.map { |s| [s.name, s.version.to_s] }.uniq
+    end
+
+    def audit_gem(name, version)
+      target = Target.detect(name)
+      findings = static_findings(target)
+      results = dynamic_results(target)
+      report = Report.new(
+        target_type: :gem,
+        target_root: target.root,
+        findings: findings + results.flat_map(&:findings),
+        dynamic_results: results
+      )
+      counts = report.counts
+      Row.new(
+        name: name, version: version, verdict: report.verdict,
+        errors: counts[:error], dep_errors: counts[:dep_error],
+        warnings: counts[:warning], fixable: counts[:fixable],
+        status: "ok"
+      )
+    rescue Error
+      Row.new(
+        name: name, version: version, verdict: nil, errors: 0,
+        dep_errors: 0, warnings: 0, fixable: 0,
+        status: "not installed"
+      )
+    end
+
+    # Worker threads already parallelize across gems; per-gem
+    # scanning stays serial to avoid a Ractor storm.
+    def static_findings(target)
+      per_file = Static::Analyzer.new
+        .analyze_paths(target.ruby_files, workers: 1)
+      per_file + Static::GraphAudit.new
+        .analyze_paths(target.ruby_files)
+    end
+
+    def dynamic_results(target)
+      return [] if @static_only || target.entry.nil?
+
+      prober = Dynamic::Prober.new(timeout: @timeout)
+      [prober.probe(target.entry)]
+    end
+  end
+end