audition 0.1.0 → 0.2.1

checksums.yaml

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

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,7 @@ proxying) and its verified semantics.
 - [Usage](#usage)
 - [Adopting incrementally](#adopting-incrementally)
 - [What it catches](#what-it-catches)
-- [Field notes](#field-notes)
+- [Agent skill](#agent-skill)
 - [Extending](#extending)
 - [Development](#development)
 - [License](#license)
@@ -191,14 +210,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,20 +246,27 @@ Dynamic, on the live object graph:
 - Boots Rails (`config/environment.rb`), eager-loads, and sweeps
   the application's namespaces.
 
-## Field notes
+## Agent skill
 
-Findings from running audition on popular gems (July 2026,
-Ruby 4.0.6):
+This repository ships a `ractor-readiness` skill that teaches
+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).
 
-- **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.
+Install into Claude Code as a plugin:
+
+```
+/plugin marketplace add yaroslav/audition
+/plugin install audition@audition
+```
+
+Or install the skill with the
+[skills CLI](https://github.com/vercel-labs/skills):
+
+```console
+$ npx skills add yaroslav/audition
+```
 
 ## Extending
 

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/bundle_sweep.rb

@@ -11,7 +11,7 @@ module Audition
     CONCURRENCY = 4
 
     Row = Data.define(:name, :version, :verdict, :errors,
-      :dep_errors, :warnings, :fixable, :status)
+      :dep_errors, :warnings, :infos, :fixable, :status)
 
     VERDICT_ORDER = {
       :not_ready => 0, :blocked => 1, :risky => 2, :ready => 3, nil => 4
@@ -66,38 +66,85 @@ module Audition
       parser.specs.map { |s| [s.name, s.version.to_s] }.uniq
     end
 
+    # Mirrors CLI#audit: the locked version's own spec is audited,
+    # and findings pass through the gem's inline pragmas and its
+    # .audition.yml (exclude plus checks.disable) so a sweep row
+    # agrees with a direct audit of the same gem.
     def audit_gem(name, version)
-      target = Target.detect(name)
-      findings = static_findings(target)
+      spec = Gem::Specification.find_by_name(name, version)
+      target = gem_target(spec)
+      config = Config.load(target.root)
+      directives = Directives.new
+      findings = filter(static_findings(target, config),
+        directives, config)
       results = dynamic_results(target)
+      findings += filter(results.flat_map(&:findings),
+        directives, config)
       report = Report.new(
         target_type: :gem,
         target_root: target.root,
-        findings: findings + results.flat_map(&:findings),
+        findings: 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"
+        warnings: counts[:warning], infos: counts[:info],
+        fixable: counts[:fixable], status: "ok"
       )
-    rescue Error
+    rescue Gem::MissingSpecError
+      failed_row(name, version, "not installed")
+    rescue => e
+      failed_row(name, version, "failed: #{e.class}")
+    end
+
+    def failed_row(name, version, status)
       Row.new(
         name: name, version: version, verdict: nil, errors: 0,
-        dep_errors: 0, warnings: 0, fixable: 0,
-        status: "not installed"
+        dep_errors: 0, warnings: 0, infos: 0, fixable: 0,
+        status: status
+      )
+    end
+
+    def gem_target(spec)
+      root = spec.gem_dir
+      Target.new(
+        type: :gem,
+        root: root,
+        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}
       )
     end
 
+    # Same glob discipline as Target: skip vendored trees and
+    # dotdirs.
+    def ruby_files_under(dir)
+      Dir[File.join(dir, "**", "*.rb")].reject do |path|
+        path.delete_prefix("#{dir}/").split("/").any? do |part|
+          Target::EXCLUDED_DIRS.include?(part) ||
+            part.start_with?(".")
+        end
+      end.sort
+    end
+
+    def filter(findings, directives, config)
+      directives.filter(findings).reject do |finding|
+        config.check_disabled?(finding.check)
+      end
+    end
+
     # Worker threads already parallelize across gems; per-gem
     # scanning stays serial to avoid a Ractor storm.
-    def static_findings(target)
+    def static_findings(target, config)
+      files = target.ruby_files.reject do |file|
+        config.excluded?(file.delete_prefix("#{target.root}/"))
+      end
       per_file = Static::Analyzer.new
-        .analyze_paths(target.ruby_files, workers: 1)
-      per_file + Static::GraphAudit.new
-        .analyze_paths(target.ruby_files)
+        .analyze_paths(files, workers: 1)
+      per_file + Static::GraphAudit.new.analyze_paths(files)
     end
 
     def dynamic_results(target)

data/lib/audition/cli.rb

@@ -135,6 +135,9 @@ module Audition
     end
 
     def audit(target, options)
+      # Read the comparison report up front: a missing or broken
+      # file should be a fast usage error, not a post-audit crash.
+      compare = load_compare(options[:compare])
       config = Config.load(target.root)
       options = apply_config(options, config)
       directives = Directives.new
@@ -162,6 +165,7 @@ module Audition
         return 0
       end
 
+      visible = all
       all, baselined = apply_baseline(all, target, options)
 
       report = Report.new(
@@ -173,34 +177,43 @@ module Audition
         baselined: baselined
       )
       emit(report, options)
-      if options[:compare] && options[:format] != :json
-        emit_comparison(report, options)
+      if compare && options[:format] != :json
+        emit_comparison(compare, visible, target, options)
       end
       exit_code(report, options)
     end
 
-    def emit_comparison(report, options)
-      old = begin
-        JSON.parse(File.read(options[:compare]))
-      rescue JSON::ParserError, SystemCallError => e
-        raise Error, "cannot read #{options[:compare]}: #{e.message}"
-      end
+    def load_compare(path)
+      return nil unless path
+
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError, SystemCallError => e
+      raise Error, "cannot read #{path}: #{e.message}"
+    end
 
+    # Fingerprints are root-relative on both sides, so an absolute
+    # old run compares cleanly against a relative new run. The
+    # comparison sees pre-baseline visible findings: a baselined
+    # finding still exists and must not count as fixed.
+    def emit_comparison(old, findings, target, options)
+      old_root = old.dig("target", "root").to_s
       budget = Hash.new(0)
       old.fetch("findings", []).each do |f|
-        budget[[f["check"], f["path"], f["message"]]] += 1
+        key = [f["check"], relativize(f["path"].to_s, old_root),
+          f["message"]]
+        budget[key] += 1
       end
       total_old = budget.values.sum
 
-      introduced = report.findings.reject do |f|
-        key = [f.check, f.path, f.message]
+      introduced = findings.reject do |f|
+        key = [f.check, relativize(f.path.to_s, target.root),
+          f.message]
         next false unless budget[key].positive?
 
         budget[key] -= 1
         true
       end
-      fixed = total_old -
-        (report.findings.size - introduced.size)
+      fixed = total_old - (findings.size - introduced.size)
 
       s = style(options)
       @stdout.puts(
@@ -213,6 +226,12 @@ module Audition
       end
     end
 
+    def relativize(path, root)
+      return path if root.empty?
+
+      path.delete_prefix("#{root}/")
+    end
+
     def apply_config(options, config)
       merged = options.dup
       if config.fail_on && !options[:explicit].include?(:fail_on)
@@ -247,6 +266,8 @@ module Audition
       per_file + Static::GraphAudit.new.analyze_paths(files)
     end
 
+    # Fix chatter goes to stderr: stdout carries the report, which
+    # must stay parseable under --format json.
     def run_fix(target, findings, options)
       fixer = Fixer.new(unsafe: options[:unsafe])
       if options[:dry_run]
@@ -256,30 +277,33 @@ module Audition
 
       applied = fixer.apply(findings)
       total = applied.values.sum
-      @stdout.puts(
+      if total.zero?
+        @stderr.puts("nothing to fix")
+        return findings
+      end
+
+      @stderr.puts(
         "fixed #{total} finding(s) in #{applied.size} file(s)"
       )
-      return findings unless total.positive?
-
       filter(static_findings(target, Config.load(target.root)),
         Directives.new, Config.load(target.root))
     end
 
     def render_preview(previews, options)
-      s = style(options)
+      s = style(options, io: @stderr)
       previews.each do |preview|
-        @stdout.puts(s.bold(preview[:path]))
+        @stderr.puts(s.bold(preview[:path]))
         preview[:hunks].each do |hunk|
-          @stdout.puts("  @ line #{hunk[:line]}")
+          @stderr.puts("  @ line #{hunk[:line]}")
           hunk[:old].each_line do |line|
-            @stdout.puts(s.red("  - #{line.chomp}"))
+            @stderr.puts(s.red("  - #{line.chomp}"))
           end
           hunk[:new].each_line do |line|
-            @stdout.puts(s.green("  + #{line.chomp}"))
+            @stderr.puts(s.green("  + #{line.chomp}"))
           end
         end
       end
-      @stdout.puts("dry run: no files were changed")
+      @stderr.puts("dry run: no files were changed")
     end
 
     def prober(options)
@@ -294,11 +318,11 @@ module Audition
       end
     end
 
-    def style(options)
+    def style(options, io: @stdout)
       if options[:plain]
         Report::Style.new(color: false, hyperlinks: false)
       else
-        Report::Style.detect(io: @stdout)
+        Report::Style.detect(io: io)
       end
     end
 
@@ -338,9 +362,21 @@ module Audition
       if options[:format] == :json
         emit_sweep_json(rows)
       else
-        emit_sweep_table(rows)
+        emit_sweep_table(rows, options)
       end
-      (rows.any? { |r| r.verdict == :not_ready }) ? 1 : 0
+      threshold = SEVERITIES.fetch(options[:fail_on])
+      (rows.any? { |r| row_failed?(r, threshold) }) ? 1 : 0
+    end
+
+    # Same contract as a direct audit: a row fails when it carries
+    # findings at or above --fail-on; not-ready rows always fail.
+    def row_failed?(row, threshold)
+      return true if row.verdict == :not_ready
+
+      hits = row.errors + row.dep_errors
+      hits += row.warnings if threshold <= SEVERITIES[:warning]
+      hits += row.infos if threshold <= SEVERITIES[:info]
+      hits.positive?
     end
 
     def sweep_progress
@@ -351,7 +387,19 @@ module Audition
       end
     end
 
-    def emit_sweep_table(rows)
+    # Cells arrive preformatted: coercion would render a version
+    # like "3.2" as 3.200. Color follows the CLI's own detection
+    # because the table gem reads the global $stdout and cannot
+    # see --plain. Autolayout only on ttys; pipes keep full width.
+    def table_opts(options)
+      tty = @stdout.respond_to?(:tty?) && @stdout.tty?
+      {
+        color: style(options).color?, coerce: false,
+        layout: tty, placeholder: "-"
+      }
+    end
+
+    def emit_sweep_table(rows, options)
       ready = rows.count { |r| r.verdict == :ready }
       table = rows.map do |r|
         {
@@ -365,7 +413,9 @@ module Audition
           "status" => r.status
         }
       end
-      @stdout.puts(TableTennis.new(table, layout: false).to_s)
+      @stdout.puts(TableTennis.new(
+        table, zebra: true, **table_opts(options)
+      ).to_s)
       @stdout.puts(
         "#{ready} of #{rows.size} gems ractor-ready"
       )
@@ -383,6 +433,7 @@ module Audition
             "errors" => r.errors,
             "dependency_errors" => r.dep_errors,
             "warnings" => r.warnings,
+            "infos" => r.infos,
             "fixable" => r.fixable,
             "status" => r.status
           }
@@ -408,7 +459,9 @@ module Audition
         }
       end
       @stdout.puts("ruby #{RUBY_VERSION} at #{RbConfig.ruby}")
-      @stdout.puts(TableTennis.new(rows, layout: false).to_s)
+      @stdout.puts(
+        TableTennis.new(rows, **table_opts(options)).to_s
+      )
       0
     end
   end

data/lib/audition/config.rb

@@ -23,16 +23,20 @@ module Audition
        disabled_checks: []}
     )
 
+    FAIL_ON_LEVELS = %w[error warning info].freeze
+
     attr_reader :fail_on, :timeout, :exclude, :disabled_checks
 
     # @param root [String] directory that may contain .audition.yml
     # @return [Config] empty config when the file is absent
-    # @raise [Audition::Error] on malformed YAML
+    # @raise [Audition::Error] on malformed YAML, a non-mapping
+    #   document, or an unknown fail_on level
     def self.load(root)
       path = File.join(root.to_s, FILE)
       return new(**EMPTY) unless File.file?(path)
 
       data = YAML.safe_load_file(path) || {}
+      validate!(path, data)
       new(
         fail_on: data["fail_on"]&.to_sym,
         timeout: data["timeout"],
@@ -44,6 +48,22 @@ module Audition
       raise Error, "#{path}: #{e.message}"
     end
 
+    def self.validate!(path, data)
+      unless data.is_a?(Hash)
+        raise Error,
+          "#{path}: expected a YAML mapping, got #{data.class}"
+      end
+
+      fail_on = data["fail_on"]
+      return if fail_on.nil? ||
+        FAIL_ON_LEVELS.include?(fail_on.to_s)
+
+      raise Error,
+        "#{path}: fail_on must be one of error, warning, or " \
+        "info (got #{fail_on.inspect})"
+    end
+    private_class_method :validate!
+
     def initialize(fail_on:, timeout:, exclude:, disabled_checks:)
       @fail_on = fail_on
       @timeout = timeout
@@ -51,9 +71,14 @@ module Audition
       @disabled_checks = disabled_checks
     end
 
+    # Globs follow .gitignore-style expectations: `*` stays within
+    # one directory level, `dir/**` covers the whole subtree, and a
+    # leading `./` is tolerated.
     def excluded?(relative_path)
-      exclude.any? do |pattern|
-        next true if File.fnmatch?(pattern, relative_path)
+      exclude.any? do |raw|
+        pattern = raw.delete_prefix("./")
+        next true if File.fnmatch?(pattern, relative_path,
+          File::FNM_PATHNAME | File::FNM_EXTGLOB)
 
         prefix = pattern[%r{\A(.+?)/\*\*(?:/\*+)?\z}, 1]
         prefix && relative_path.start_with?("#{prefix}/")

data/lib/audition/directives.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "prism"
+
 module Audition
   # Same-line suppression pragmas:
   #
@@ -8,9 +10,11 @@ module Audition
   #
   # A bare pragma silences every check on that line; otherwise only
   # the listed check names. Applied to any finding carrying a real
-  # path and line, including runtime findings.
+  # path and line, including runtime findings. Pragmas are read
+  # from Prism's comment list, never from raw lines: pragma-shaped
+  # text inside a string literal is data, not a directive.
   class Directives
-    PATTERN = /#\s*audition:disable\b[ \t]*(?<list>[^#\n]*)/
+    PATTERN = /#\s*audition:disable\b[ \t]*(?<list>[\w \t,-]*)/
 
     def initialize
       @by_path = {}
@@ -37,16 +41,30 @@ module Audition
       @by_path[path] ||= scan(path)
     end
 
+    # Every pragma comment on a line contributes; an explicit
+    # disable is never shadowed by an earlier pragma, and a bare
+    # pragma (empty list) wins over any list.
     def scan(path)
       return {} unless File.file?(path)
 
       directives = {}
-      File.foreach(path).with_index(1) do |line, number|
-        match = PATTERN.match(line)
-        next unless match
-
-        directives[number] =
-          match[:list].split(/[,\s]+/).reject(&:empty?)
+      Prism.parse_file(path).comments.each do |comment|
+        comment.slice.scan(PATTERN) do
+          line = comment.location.start_line
+          checks = Regexp.last_match[:list]
+            .split(/[,\s]+/).reject(&:empty?)
+          if directives.key?(line)
+            existing = directives[line]
+            directives[line] =
+              if existing.empty? || checks.empty?
+                []
+              else
+                existing | checks
+              end
+          else
+            directives[line] = checks
+          end
+        end
       end
       directives
     rescue SystemCallError

data/lib/audition/dynamic/harness.rb

@@ -55,13 +55,27 @@ module AuditionHarness
       end
     out.puts(JSON.generate(result))
   rescue Exception => e
-    out.puts(JSON.generate("error" => describe_error(e)))
+    begin
+      out.puts(JSON.generate("error" => describe_error(e)))
+    rescue Exception
+      out.puts('{"error":{"class":"HarnessFailure",' \
+               '"message":"unreportable error"}}')
+    end
   end
 
+  # Exception messages can carry arbitrary bytes (C extensions,
+  # binary filenames); unscrubbed they blow up JSON.generate
+  # inside the rescue and the harness dies without output.
   def describe_error(error)
     root = unwrap(error)
-    {"class" => root.class.name,
-     "message" => root.message.to_s[0, 500]}
+    {"class" => scrub(root.class.name.to_s),
+     "message" => scrub(root.message.to_s)[0, 500]}
+  end
+
+  def scrub(text)
+    text.dup.force_encoding(Encoding::UTF_8).scrub
+  rescue Exception
+    "(unprintable)"
   end
 
   def unwrap(error)
@@ -111,7 +125,17 @@ module AuditionHarness
       $LOAD_PATH.unshift(lp) # audition:disable global-variables
     end
     before = Object.constants
-    require payload.fetch("feature") # audition:disable runtime-require
+    feature = payload.fetch("feature")
+    begin
+      require feature # audition:disable runtime-require
+    rescue LoadError
+      # Dashed gem names conventionally ship slashed entry files
+      # (rspec-mocks provides rspec/mocks).
+      slashed = feature.tr("-", "/")
+      raise if slashed == feature
+
+      require slashed # audition:disable runtime-require
+    end
     scan(Object.constants - before, root: payload["root"])
   end
 
@@ -192,7 +216,9 @@ module AuditionHarness
     rescue Exception
       nil
     end
-    own = root.nil? || path.nil? || path.start_with?(root)
+    # The separator matters: /x/app must not claim /x/app-helpers.
+    own = root.nil? || path.nil? || path == root ||
+      path.start_with?(root + File::SEPARATOR)
     {"path" => path, "line" => line, "own" => own}
   end