audition 0.2.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76a1b0c57c7a373182f7b9f88f765fa8e0167a492e28d028998335bc246c10d9
-  data.tar.gz: 2c5ecb49ed0a63ebd7a58cb3db9e8b5e8f9893953198d1c3e9f0cc5ca74cfb3a
+  metadata.gz: 52c12c94d193fa6946553c81ab22b8c21272f269ad4f6f758e99fa4a1c05217e
+  data.tar.gz: 858d3ef4e5742ca430337656b9ecea865a89c3f3525ef990073499c8eb438bca
 SHA512:
-  metadata.gz: 633d141cdc23a3e2e24df8b983b9112ffa9a759194669c4f9a6f62f0bf07219b507bd72cea8235de3c7193ab934c60ca8c98ee2095eabe21fad2e80f682ea8e2
-  data.tar.gz: bfd863839b4d5fbea291d22282487de79d261fd55bba5662d82d285e013827290257ca61d5b637000581453ec8f3a0510b1571bf6492d1b9f6f9e7de9f3af225
+  metadata.gz: 60d78e8622cfe35764e7dd30be43ba7e1ceda4f0faf10796230dd6ddb85d952736b345bd380b58823cf97c6687209f6c0fe709193f58326464b61950af1c8a70
+  data.tar.gz: 8edc6f7ba79f531317e26f5f1866540ec784d3791db0b6a43ae56d990b22bd173b5234a05618a8b75ba4c5bf1d95bb06a9898c726b493456c36604cdb7c90b66

data/README.md

@@ -2,7 +2,7 @@
 
 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
+and how to fix it. Unlike a linter, Audition does not stop at
 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
@@ -11,6 +11,10 @@ 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).
 
+<div align="center">
+  <img src="https://raw.githubusercontent.com/yaroslav/audition/refs/heads/main/assets/images/audition.png" width="512" height="512" alt="gem audition" title="gem audition">
+</div>
+
 [![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)
 
@@ -24,8 +28,10 @@ core itself is being ractorized; see the
   (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
+  `.freeze` on string constants, sentinels, and containers whose
+  elements are all shareable, `Ractor.make_shareable(...)` for
+  the remaining mutable and shallow-frozen containers and for
+  Proc constants, and
   boot-time hoisting of method-body requires. `--fix-unsafe` adds
   semantics-affecting rewrites: magic-comment insertion,
   freeze-on-memoize for class-level memoization (both `@x ||=`
@@ -41,35 +47,35 @@ core itself is being ractorized; see the
   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.
+  Ractor workers, and Audition passes its own audit. It runs on
+  itself on every commit (a lefthook pre-commit over the staged
+  files) and on every push (a full self-audit in CI).
 - **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
+  (some two hundred commits and pull requests): `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.
+  `path:line` is clickable in supporting terminals. Long scans
+  narrate their phases on stderr. JSON output for CI.
 
 ```console
 $ audition worker.rb
-* audition 0.1.0 ruby 4.0.6 · script at .
+* Audition 0.3.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
+    x worker.rb:1  write to global variable $jobs global-variables
+      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.
+    x worker.rb:1  raises inside a Ractor: Ractor::IsolationError ...
+    x worker.rb:4  read of global variable $jobs global-variables
       ...
 
   dynamic probes
@@ -85,16 +91,29 @@ 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
+╭───────────────────────────────────────────────────────────────────────────────────────╮
+│                                 Audition bundle sweep                                 │
+├──────────┬──────────┬─────────────┬────────┬────────────┬──────────┬─────────┬────────┤
+│ gem      │ version  │ verdict     │ errors │ dep errors │ warnings │ fixable │ status │
+├──────────┼──────────┼─────────────┼────────┼────────────┼──────────┼─────────┼────────┤
+│ rubocop  │ 1.88.2   │ x not ready │    194 │ -          │      203 │      28 │ ok     │
+│ parser   │ 3.3.12.0 │ x not ready │    154 │ -          │       26 │      26 │ ok     │
+│ rack     │ 3.2.7    │ x not ready │     31 │ -          │       61 │      13 │ ok     │
+│ rake     │ 13.4.2   │ x not ready │     30 │ -          │       24 │       5 │ ok     │
+│ prism    │ 1.9.0    │ x not ready │     16 │ -          │       88 │      15 │ ok     │
+│ json     │ 2.21.2   │ x not ready │      7 │ -          │        5 │       - │ ok     │
+│ pastel   │ 0.8.0    │ x not ready │      2 │ -          │        1 │       - │ ok     │
+│ tty-link │ 0.2.0    │ x not ready │      1 │ -          │        1 │       - │ ok     │
+╰──────────┴──────────┴─────────────┴────────┴────────────┴──────────┴─────────┴────────╯
+
+x 0 of 8 gems ractor-ready · 8 not ready
+```
+
+Verdicts are colored by severity, clean counts are left blank, and
+the sweep names each gem as it finishes:
+
+```console
+◆ Audition sweep rubocop 8/8 (100%) 5.8s
 ```
 
 **Requires Ruby 4.0 or newer**, strictly: the tool targets the modern
@@ -112,6 +131,7 @@ proxying) and its verified semantics.
 - [Installation](#installation)
 - [Usage](#usage)
 - [Adopting incrementally](#adopting-incrementally)
+- [CI and git hooks](#ci-and-git-hooks)
 - [What it catches](#what-it-catches)
 - [Agent skill](#agent-skill)
 - [Extending](#extending)
@@ -140,6 +160,7 @@ 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 a.rb b.rb c.rb       # several files at once, statically
 audition Gemfile.lock         # sweep every gem in the bundle
 audition path/to/app --deps   # same, from the app root
 ```
@@ -154,16 +175,33 @@ Useful flags:
 | `--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 |
+| `--format github` | GitHub Actions annotations + job summary |
 | `--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) |
+| `--exit-zero` | report findings but never fail the build |
 | `--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) |
+| `--progress` / `--no-progress` | force / suppress the stderr narration |
+| `-j 4` / `--workers 4` | scan Ractors (default: cores, capped by `RUBY_MAX_CPU`) |
+
+Long runs narrate themselves on stderr, so stdout stays pipeable:
+a rewriting status line on a terminal, one line per phase off it.
+
+```
+◆ Audition checking 50/919 5% (0.2s, on 8 ractors)
+```
+
+A phase running in Ractors says how many. The narration turns on
+by itself for a large tree or a bundle sweep and stays off for
+`--format json` and `--format github`; the flags force either
+way.
 
 Exit codes: `0` clean, `1` findings at or above the `--fail-on`
 threshold (or a failed dynamic probe), `2` usage error.
+`--exit-zero` (alias for `--fail-on never`) always exits `0`
+unless the invocation itself is broken.
 
 ## Adopting incrementally
 
@@ -197,11 +235,85 @@ timeout: 60
 exclude:
   - legacy/**
   - db/schema.rb
+test_dirs:
+  - qa
 checks:
   disable:
     - at-exit
 ```
 
+`test_dirs` names the directories that hold tests rather than
+code a production boot loads; findings in them are tagged
+`test` and rated as test code. It defaults to `test`, `spec`,
+`features`, and replaces that list rather than adding to it—the
+`_test.rb` and `_spec.rb` suffixes always count, whatever it
+says.
+
+## CI and git hooks
+
+**GitHub Actions.** `--format github` turns findings into
+workflow-command annotations that land right on the PR diff, and
+appends a verdict-plus-counts markdown table to the job summary
+page. A blocking gate:
+
+```yaml
+- uses: ruby/setup-ruby@v1
+  with:
+    ruby-version: "4.0"
+- run: gem install audition
+- run: audition --format github .
+```
+
+To surface findings without failing the build while you adopt
+(the flag other linters call `--exit-zero` too, so it keeps its
+name here):
+
+```yaml
+- run: audition --format github --exit-zero .
+```
+
+`--fail-on never` is the long form, and works from
+`.audition.yml` as well; GitHub's own `continue-on-error: true`
+on the step is the workflow-level equivalent.
+
+**Git hooks.** Passing several `.rb` files audits exactly those
+files statically, which is the shape hook managers hand over.
+With [lefthook](https://github.com/evilmartians/lefthook):
+
+```yaml
+pre-commit:
+  commands:
+    audition:
+      glob: "*.rb"
+      run: audition --static-only --plain {staged_files}
+```
+
+With [pre-commit](https://pre-commit.com):
+
+```yaml
+- repo: local
+  hooks:
+    - id: audition
+      name: Audition
+      language: system
+      entry: audition --static-only --plain
+      types: [ruby]
+```
+
+Config, pragmas, and the baseline resolve against the working
+directory, so a hook run from the repository root honors the
+same `.audition.yml` as a full audit.
+
+**This repository eats its own dog food.** Every commit runs
+`audition --static-only` over the staged files through lefthook
+(next to standardrb), and every push and pull request gets a
+full self-audit in CI with annotations and a job summary,
+non-blocking via `--exit-zero`
+([audit.yml](.github/workflows/audit.yml)). Current state: own
+code audits `ready`; the full dynamic probe reports the terminal
+dev-dependencies as `blocked`, which is exactly the distinction
+the verdict system exists to make.
+
 ## What it catches
 
 Static, with file:line precision:
@@ -214,7 +326,7 @@ Static, with file:line precision:
   `@cache ||= {}` and `return @x if defined?(@x)` memoizations.
 - **Constants that are not deeply shareable**: bare mutable
   literals, interpolated strings, the subtle shallow freeze
-  (`[[1], [2]].freeze` still raises; audition explains why), and
+  (`[[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:`
@@ -235,6 +347,25 @@ Static, with file:line precision:
   `class_attribute` migration Rails itself made) and
   `class_attribute` without copy-on-write writes,
   `include Singleton`, `fork`, `ObjectSpace._id2ref`, ENV mutation.
+- **Native extensions that never declare Ractor safety**: a byte
+  scan of every compiled `.bundle`/`.so` for the
+  `rb_ext_ractor_safe` import, which also covers precompiled
+  platform gems that ship no sources; an unbuilt checkout is
+  scanned at the source level instead (C, Rust, or Zig sources
+  beside their `extconf.rb`, `Cargo.toml` or `build.zig`).
+  A silent extension raises `Ractor::UnsafeError` on every call
+  from a non-main Ractor, so it rates a warning; a declared one
+  gets an info note, because the declaration is the maintainer's
+  assertion, not a proof.
+- **The static pass's own blind spots**: where rubydex reports an
+  expression it could not resolve and the shape could hide what
+  the checks above look for, the hole is reported rather than
+  read as a clean line — a singleton opened on a runtime receiver
+  that writes class-level state, a superclass or `include`
+  argument computed at runtime, a constant assigned through an
+  unresolved path. A clean report for such a class covers only
+  what the class itself declares; the dynamic probe reaches the
+  rest.
 
 Dynamic, on the live object graph:
 
@@ -244,6 +375,11 @@ Dynamic, on the live object graph:
   `Ractor.shareable?`, and inspects every class and module for
   class-level ivars and class variables, with
   `const_source_location` attribution.
+- Records every compiled extension the load pulled in,
+  dependencies included, and byte-scans each for the
+  `rb_ext_ractor_safe` import; silent ones are reported against
+  the dependency that ships them. Ruby's own extensions are left
+  to Ruby.
 - 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
@@ -254,7 +390,7 @@ Dynamic, on the live object graph:
 ## Agent skill
 
 This repository ships a `ractor-readiness` skill that teaches
-coding agents (Claude Code and friends) the full audition
+coding agents (Claude Code and friends) the full Audition
 workflow: audit, fix tiers, suite-parity verification, and
 incremental adoption. It lives in
 [skills/ractor-readiness/SKILL.md](skills/ractor-readiness/SKILL.md).
@@ -305,12 +441,12 @@ Audition::Static::Checks.register(NoSleep)
 bundle install
 bundle exec rake spec       # RSpec suite
 bundle exec rake standard   # standardrb lint
-lefthook install            # pre-commit lint hook
+lefthook install            # pre-commit standardrb + audition
 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/`
+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
@@ -321,7 +457,7 @@ calibrated against.
 
 The whole-program checks stand on
 [rubydex](https://github.com/Shopify/rubydex), Shopify's
-high-performance static analysis suite for Ruby: audition feeds
+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),

data/lib/audition/bundle_sweep.rb

@@ -31,10 +31,10 @@ module Audition
 
     # Audits every locked gem and ranks the results, worst first.
     #
-    # @param progress [Proc, nil] called with (row, done, total)
-    #   as each gem finishes
+    # @param progress [Progress] named per gem as each finishes,
+    #   which is the only unit a sweep has
     # @return [Array<Row>]
-    def rows(progress: nil)
+    def rows(progress: Progress::SILENT)
       gems = locked_gems
       queue = Thread::Queue.new
       gems.each { |g| queue << g }
@@ -42,17 +42,19 @@ module Audition
 
       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)
+      progress.phase("sweep", total: gems.size, unit: "gems") do
+        @concurrency.times.map do
+          Thread.new do
+            while (name, version = queue.pop)
+              row = audit_gem(name, version)
+              mutex.synchronize do
+                collected << row
+                progress.item(row.name)
+              end
             end
           end
-        end
-      end.each(&:join)
+        end.each(&:join)
+      end
 
       collected.sort_by do |row|
         [VERDICT_ORDER.fetch(row.verdict), -row.errors, row.name]
@@ -115,7 +117,10 @@ module Audition
         ruby_files: spec.require_paths.flat_map do |rp|
           ruby_files_under(File.join(root, rp))
         end,
-        entry: {mode: :require, feature: spec.name, root: root}
+        entry: {mode: :require, feature: spec.name,
+                load_paths: spec.full_require_paths, root: root},
+        compiled_files: Target.compiled_for(spec),
+        stub_files: Target.stubs(root)
       )
     end
 
@@ -142,16 +147,28 @@ module Audition
       files = target.ruby_files.reject do |file|
         config.excluded?(file.delete_prefix("#{target.root}/"))
       end
+      compiled = target.compiled_files.reject do |file|
+        config.excluded?(file.delete_prefix("#{target.root}/"))
+      end
       per_file = Static::Analyzer.new
         .analyze_paths(files, workers: 1)
-      per_file + Static::GraphAudit.new.analyze_paths(files)
+      gem_calls = Static::GemCalls
+        .new(root: target.root, stubs: target.stub_files)
+        .analyze_paths(files)
+      per_file + gem_calls + Static::GraphAudit.new
+        .analyze_paths(files, constant_findings: per_file + gem_calls,
+          workers: 1) +
+        Static::NativeExtensions.new.analyze(target,
+          compiled_files: compiled)
     end
 
     def dynamic_results(target)
       return [] if @static_only || target.entry.nil?
 
       prober = Dynamic::Prober.new(timeout: @timeout)
-      [prober.probe(target.entry)]
+      [prober.probe(
+        target.entry.merge(compiled_files: target.compiled_files)
+      )]
     end
   end
 end