audition 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 334e1fbfc5a78984722aad73810af312279f67f72bae4b5e60bbbf9433b0f404
-  data.tar.gz: 26c3023a7cdeeee748b61619277c8e749b5a0204b82474b4f06220e9c0fd737d
+  metadata.gz: e82f1a081cebcd3209cfbced17ecb539949cf4590c785e1b6873535473090756
+  data.tar.gz: 7d6c4358bae0e8514e15452c0f0dba8bde7a53a9dd342ec9b96e9cf53a4c853f
 SHA512:
-  metadata.gz: 4c91b4b8ff157e2ff268533657c9dab0c61dc5cc2c0e568790f6c45bee16dfee05f7b0ff830b90aeff43d150278292b967a52dd8ce9baff926b33b23b0bc4992
-  data.tar.gz: 9e639f1a77f804fcc79a196d109fc967a683b07c30411a6832ac9b5315428c30338e1e31b44c7ee448c724fd8a48ce7f7fb6a42411bf0194531b25597cb8e66a
+  metadata.gz: e1ddb8750389aa6734d895a4a84e32fb8a0cb0feca7d26c83e0803e8f28abfd6f16fd3255f352ba3e4d3534192636da3d6f73f651fd90dff8d18654384f779bf
+  data.tar.gz: dfe09ec14b4f3058f2df766129a78d6cfed1dfd65bd72ce512a6cfeea65e1ae42ef01bf0cb9d0c9f1d890973dcbcc052396dbca9cf445e0bf79d08676d8f3c45

data/README.md

@@ -113,6 +113,7 @@ proxying) and its verified semantics.
 - [Usage](#usage)
 - [Adopting incrementally](#adopting-incrementally)
 - [What it catches](#what-it-catches)
+- [Agent skill](#agent-skill)
 - [Extending](#extending)
 - [Development](#development)
 - [License](#license)
@@ -245,6 +246,28 @@ Dynamic, on the live object graph:
 - Boots Rails (`config/environment.rb`), eager-loads, and sweeps
   the application's namespaces.
 
+## Agent skill
+
+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).
+
+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
 
 Checks are written in a small declarative DSL and can be registered

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
 

data/lib/audition/dynamic/prober.rb

@@ -334,8 +334,13 @@ module Audition
 
       # -- subprocess plumbing -------------------------------------
 
+      # Harness output can carry arbitrary target bytes; force
+      # valid UTF-8 before any string work or a binary exception
+      # message crashes the whole run.
       def run(mode, payload = {})
         out, err, timed_out = execute(mode, payload)
+        out = sanitize(out)
+        err = sanitize(err)
         if timed_out
           return {"error" => {
             "class" => "AuditionTimeout",
@@ -346,29 +351,68 @@ module Audition
       rescue JSON::ParserError
         {"error" => {
           "class" => "HarnessFailure",
-          "message" => (err || "").split("\n").last(5).join("; ")
+          "message" => err.split("\n").last(5).join("; ")
         }}
       end
 
+      def sanitize(text)
+        (text || "").dup.force_encoding(Encoding::UTF_8).scrub
+      end
+
+      # The harness leads its own process group so a timeout kills
+      # every descendant, and the pipe readers are bounded: a
+      # child the target spawned inherits our pipes and would
+      # otherwise hold the read until it exits, defeating the
+      # timeout and leaving orphans behind.
       def execute(mode, payload)
         cmd = [@ruby, "-W0", HARNESS, mode]
-        Open3.popen3(*cmd) do |stdin, stdout, stderr, wait|
+        Open3.popen3(*cmd, pgroup: true) do |stdin, stdout, stderr, wait|
           stdin.write(JSON.generate(payload))
           stdin.close
-          out_reader = Thread.new { stdout.read }
-          err_reader = Thread.new { stderr.read }
-          if wait.join(@timeout)
-            [out_reader.value, err_reader.value, false]
-          else
-            begin
-              Process.kill("KILL", wait.pid)
-            rescue Errno::ESRCH
-              nil
+          out_reader = reader(stdout)
+          err_reader = reader(stderr)
+          timed_out = wait.join(@timeout).nil?
+          kill_group(wait.pid) if timed_out
+          unless drain(out_reader, err_reader)
+            kill_group(wait.pid)
+            unless drain(out_reader, err_reader)
+              close_quietly(stdout)
+              close_quietly(stderr)
             end
-            [out_reader.value.to_s, err_reader.value.to_s, true]
           end
+          [out_reader.value.to_s, err_reader.value.to_s, timed_out]
+        end
+      end
+
+      # Accumulates chunks so a forced close still yields what
+      # arrived before it; a plain IO#read would lose everything.
+      def reader(io)
+        Thread.new do
+          buffer = String.new(encoding: Encoding::BINARY)
+          begin
+            loop { buffer << io.readpartial(65_536) }
+          rescue IOError
+            buffer
+          end
+          buffer
         end
       end
+
+      def drain(*threads)
+        threads.all? { |thread| thread.join(2) }
+      end
+
+      def kill_group(pid)
+        Process.kill("KILL", -pid)
+      rescue Errno::ESRCH, Errno::EPERM
+        nil
+      end
+
+      def close_quietly(io)
+        io.close
+      rescue IOError
+        nil
+      end
     end
   end
 end

data/lib/audition/fixer.rb

@@ -61,8 +61,12 @@ module Audition
         edits = build_edits(path, source, group)
         next if edits.empty?
 
-        Plan.new(path: path, source: source,
-          edits: edits.sort_by { |e| -e.start_offset })
+        # Applied bottom-up; the explicit index keeps same-offset
+        # inserts in plan order (sort_by is not stable).
+        ordered = edits.each_with_index.sort_by do |edit, index|
+          [-edit.start_offset, index]
+        end.map(&:first)
+        Plan.new(path: path, source: source, edits: ordered)
       end
     end
 
@@ -75,8 +79,10 @@ module Audition
         file = Static::SourceFile.new(source: source, path: path)
         if file.valid_syntax?
           magic = Rewriters::MagicComments.plan(file, group)
-          planned += Rewriters::Memoization.plan(file, group)
-          planned += Rewriters::WriteOnce.plan(file, group)
+          planned = Rewriters.resolve(
+            Rewriters::Memoization.plan(file, group) +
+            Rewriters::WriteOnce.plan(file, group)
+          )
         end
       end