audition 0.1.0

data/lib/audition/dynamic/prober.rb

@@ -0,0 +1,362 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "rbconfig"
+
+module Audition
+  module Dynamic
+    # Outcome of one dynamic probe.
+    #
+    # @!attribute [r] mode
+    #   @return [Symbol] `:script`, `:require`, `:rack`, `:rails`,
+    #     or `:capabilities`
+    # @!attribute [r] raw
+    #   @return [Hash] the harness's parsed JSON, verbatim
+    # @!attribute [r] findings
+    #   @return [Array<Finding>] findings derived from `raw`
+    # @!attribute [r] passed
+    #   @return [Boolean] whether the target's own surface passed
+    Result = Data.define(:mode, :raw, :findings, :passed)
+
+    # Spawns the harness subprocess per probe mode, parses its JSON,
+    # and converts observations into findings.
+    class Prober
+      HARNESS = File.expand_path("harness.rb", __dir__)
+
+      RUNTIME_WHY =
+        "Observed on the live object graph after loading the " \
+        "target; this is ground truth, not a static guess."
+
+      # @param ruby [String] Ruby executable for the harness
+      # @param timeout [Integer] seconds before a probe subprocess
+      #   is killed
+      def initialize(ruby: RbConfig.ruby, timeout: 30)
+        @ruby = ruby
+        @timeout = timeout
+      end
+
+      # Runs the probe described by a {Target#entry} hash.
+      #
+      # @param entry [Hash] `:mode` plus mode-specific keys
+      # @return [Result]
+      # @raise [Audition::Error] on an unknown mode
+      def probe(entry)
+        case (entry[:mode] || entry["mode"]).to_sym
+        when :script then probe_script(entry)
+        when :require then probe_require(entry)
+        when :rack then probe_rack(entry)
+        when :rails then probe_rails(entry)
+        when :capabilities then probe_capabilities
+        else
+          raise Error, "unknown dynamic probe mode in #{entry}"
+        end
+      end
+
+      private
+
+      def probe_script(entry)
+        path = entry[:path]
+        ractor = run("script_ractor", "path" => path)
+        if ractor["ok"]
+          return Result.new(mode: :script, raw: ractor,
+            findings: [], passed: true)
+        end
+
+        main = run("script_main", "path" => path)
+        finding = script_finding(path, ractor, main)
+        Result.new(mode: :script,
+          raw: {"ractor" => ractor, "main" => main},
+          findings: [finding], passed: false)
+      end
+
+      def script_finding(path, ractor, main)
+        if main["ok"]
+          error = describe(ractor)
+          Finding.new(
+            check: "dynamic-script",
+            severity: :error,
+            message: "raises inside a Ractor: #{error}",
+            why: "The script ran fine on the main Ractor but " \
+                 "failed under Ractor.new; the static findings " \
+                 "usually pinpoint the exact line.",
+            fix: "Fix the static findings for this file, then " \
+                 "re-audition.",
+            path: path,
+            line: nil
+          )
+        else
+          Finding.new(
+            check: "dynamic-script",
+            severity: :error,
+            message: "fails outside Ractors too: #{describe(main)}",
+            why: "The script does not even run on the main " \
+                 "Ractor, so Ractor-readiness cannot be assessed.",
+            fix: "Make the script run standalone first.",
+            path: path,
+            line: nil
+          )
+        end
+      end
+
+      def probe_require(entry)
+        feature = entry[:feature]
+        raw = run("require",
+          "feature" => feature,
+          "load_paths" => Array(entry[:load_paths]),
+          "root" => entry[:root])
+        findings = runtime_findings(raw, feature)
+        Result.new(mode: :require, raw: raw, findings: findings,
+          passed: own_clean?(findings))
+      end
+
+      def probe_rails(entry)
+        raw = run("rails",
+          "environment" => entry[:environment],
+          "root" => entry[:root])
+        boot = raw["boot"]
+        if boot && !boot["ok"]
+          finding = Finding.new(
+            check: "dynamic-rails",
+            severity: :error,
+            message: "Rails failed to boot: #{describe(boot)}",
+            why: "Ractor-readiness cannot be assessed until the " \
+                 "application boots.",
+            fix: "Boot the app (bin/rails runner 1) and fix " \
+                 "whatever breaks, then re-audition.",
+            path: entry[:environment],
+            line: nil
+          )
+          return Result.new(mode: :rails, raw: raw,
+            findings: [finding], passed: false)
+        end
+
+        findings = runtime_findings(raw, entry[:environment])
+        Result.new(mode: :rails, raw: raw, findings: findings,
+          passed: own_clean?(findings))
+      end
+
+      # A probe passes when the target's own surface is clean;
+      # dependency errors surface in the findings and drive the
+      # blocked verdict instead.
+      def own_clean?(findings)
+        findings.none? { |f| f.error? && !f.dependency? }
+      end
+
+      def probe_rack(entry)
+        config_ru = entry[:config_ru]
+        raw = run("rack", "config_ru" => config_ru)
+        findings = rack_findings(raw, config_ru)
+        passed = raw.dig("ractor_boot_call", "ok") == true &&
+          raw.dig("concurrency", "failures").to_i.zero?
+        Result.new(mode: :rack, raw: raw, findings: findings,
+          passed: passed)
+      end
+
+      def probe_capabilities
+        raw = run("capabilities")
+        Result.new(mode: :capabilities, raw: raw, findings: [],
+          passed: raw.key?("capabilities"))
+      end
+
+      # -- findings builders ---------------------------------------
+
+      def runtime_findings(raw, label)
+        if raw["error"]
+          return [load_failure_finding(raw, label)]
+        end
+
+        findings = []
+        raw.fetch("unshareable_constants", []).each do |entry|
+          findings << runtime_finding(
+            entry, label,
+            check: "runtime-unshareable-constant",
+            severity: :error,
+            message: "constant #{entry["const"]} holds an " \
+                     "unshareable #{entry["class"]}",
+            why: "Reading it from a non-main Ractor raises " \
+                 "Ractor::IsolationError. #{RUNTIME_WHY}",
+            fix: "Freeze it deeply at definition time " \
+                 "(Ractor.make_shareable) or make it per-Ractor."
+          )
+        end
+        raw.fetch("class_state", []).each do |entry|
+          findings << class_state_finding(entry, label)
+        end
+        raw.fetch("class_variables", []).each do |entry|
+          findings << runtime_finding(
+            entry, label,
+            check: "runtime-class-variable",
+            severity: :error,
+            message: "class variable(s) " \
+                     "#{entry["cvars"].join(", ")} on " \
+                     "#{entry["const"]}",
+            why: "Class variables raise Ractor::IsolationError " \
+                 "on any access from a non-main Ractor. " \
+                 "#{RUNTIME_WHY}",
+            fix: "Replace with frozen constants, instance state, " \
+                 "or Ractor-local storage."
+          )
+        end
+        findings
+      end
+
+      def class_state_finding(entry, label)
+        unshareable = entry.fetch("unshareable", [])
+        hot = unshareable.any?
+        detail =
+          hot ? " (unshareable: #{unshareable.join(", ")})" : ""
+        runtime_finding(
+          entry, label,
+          check: "runtime-class-state",
+          severity: hot ? :error : :warning,
+          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}",
+          fix: "Precompute and freeze at load, use " \
+               "Ractor.store_if_absent, or keep per-Ractor state."
+        )
+      end
+
+      # Findings keep their true severity; those tracing to a
+      # dependency's source file carry dependency: true so the
+      # report can attribute them (and the verdict can distinguish
+      # not_ready from blocked). Unknown origins count as own.
+      def runtime_finding(entry, label, check:, severity:,
+        message:, why:, fix:)
+        Finding.new(
+          check: check,
+          severity: severity,
+          message: message,
+          why: why,
+          fix: fix,
+          path: entry["path"] || label,
+          line: entry["line"],
+          dependency: !entry.fetch("own", true)
+        )
+      end
+
+      def load_failure_finding(raw, label)
+        Finding.new(
+          check: "runtime-load",
+          severity: :error,
+          message: "could not load target: #{describe(raw)}",
+          why: "Ractor-readiness cannot be assessed until the " \
+               "target loads.",
+          fix: "Make `require` succeed on a bare Ruby first.",
+          path: label,
+          line: nil
+        )
+      end
+
+      def rack_findings(raw, config_ru)
+        if raw.dig("ractor_boot_call", "ok")
+          return concurrency_findings(raw, config_ru)
+        end
+
+        if raw["rack_available"] == false
+          return [Finding.new(
+            check: "dynamic-rack",
+            severity: :warning,
+            message: "rack gem not available in the probe process",
+            why: "The rack probe boots the app via Rack::Builder.",
+            fix: "Install rack next to audition and re-run.",
+            path: config_ru,
+            line: nil
+          )]
+        end
+
+        detail = describe(raw["ractor_boot_call"] || raw)
+        why =
+          if raw["main_boot_error"]
+            "config.ru does not even boot on the main Ractor " \
+            "(#{describe(raw["main_boot_error"])})."
+          else
+            "Ractor web servers boot the app once per Ractor; " \
+            "booting config.ru and serving one GET / inside a " \
+            "Ractor failed."
+          end
+        [Finding.new(
+          check: "dynamic-rack",
+          severity: :error,
+          message: "boot + call inside a Ractor failed: #{detail}",
+          why: "#{why} #{RUNTIME_WHY}",
+          fix: "Remove global/class-level state touched during " \
+               "boot and request handling; keep middleware config " \
+               "frozen; open connections per-Ractor.",
+          path: config_ru,
+          line: nil
+        )]
+      end
+
+      def concurrency_findings(raw, config_ru)
+        stats = raw["concurrency"] || {}
+        failures = stats["failures"].to_i
+        return [] if failures.zero?
+
+        [Finding.new(
+          check: "dynamic-rack-concurrency",
+          severity: :error,
+          message: "#{failures} of #{stats["workers"]} concurrent " \
+                   "Ractors failed: " \
+                   "#{describe(stats["first_error"])}",
+          why: "Single-Ractor serving worked; failures appeared " \
+               "only under concurrent load, which usually means " \
+               "shared state races. #{RUNTIME_WHY}",
+          fix: "Look for process-global state touched during " \
+               "request handling and boot.",
+          path: config_ru,
+          line: nil
+        )]
+      end
+
+      def describe(hash)
+        error = hash.is_a?(Hash) ? (hash["error"] || hash) : {}
+        klass = error["class"] || "UnknownError"
+        message = error["message"] || hash.inspect[0, 120]
+        "#{klass}: #{message}"
+      end
+
+      # -- subprocess plumbing -------------------------------------
+
+      def run(mode, payload = {})
+        out, err, timed_out = execute(mode, payload)
+        if timed_out
+          return {"error" => {
+            "class" => "AuditionTimeout",
+            "message" => "harness exceeded #{@timeout}s"
+          }}
+        end
+        JSON.parse(out)
+      rescue JSON::ParserError
+        {"error" => {
+          "class" => "HarnessFailure",
+          "message" => (err || "").split("\n").last(5).join("; ")
+        }}
+      end
+
+      def execute(mode, payload)
+        cmd = [@ruby, "-W0", HARNESS, mode]
+        Open3.popen3(*cmd) 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
+            end
+            [out_reader.value.to_s, err_reader.value.to_s, true]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/audition/finding.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Audition
+  # Severity ranks, higher is worse. Meanings:
+  #
+  # - `:error`: will raise `Ractor::IsolationError` (or equivalent)
+  #   if this code runs in a non-main Ractor
+  # - `:warning`: raises depending on the value or usage (e.g.
+  #   reading class-level ivars is fine for shareable values, fatal
+  #   for mutable ones)
+  # - `:info`: works on Ruby 4.0+, but with caveats worth knowing
+  #
+  # @return [Hash{Symbol => Integer}]
+  SEVERITIES = {error: 3, warning: 2, info: 1}.freeze
+
+  # A machine-applicable correction: replace source bytes
+  # `start_offset...end_offset` with `replacement`. Safety follows
+  # the RuboCop convention: `:safe` edits preserve semantics
+  # exactly; `:unsafe` edits trade a small semantic change for
+  # Ractor-readiness and only apply under `--fix-unsafe`.
+  #
+  # @!attribute [r] start_offset
+  #   @return [Integer] byte offset where the edit begins
+  # @!attribute [r] end_offset
+  #   @return [Integer] byte offset where the edit ends (exclusive)
+  # @!attribute [r] replacement
+  #   @return [String] text spliced over the range
+  # @!attribute [r] safety
+  #   @return [Symbol] `:safe` or `:unsafe`
+  Autofix = Data.define(
+    :start_offset, :end_offset, :replacement, :safety
+  ) do
+    def initialize(safety: :safe, **rest)
+      super
+    end
+
+    # @return [Boolean] whether this edit needs `--fix-unsafe`
+    def unsafe? = safety == :unsafe
+  end
+
+  # One diagnosed problem: what was found (`message`), the Ractor
+  # rule it violates (`why`), what to write instead (`fix`), where
+  # (`path`/`line`/`source`), and optionally a machine-applicable
+  # {Autofix}. Produced by static checks, the graph audit, and the
+  # dynamic prober alike.
+  #
+  # @!attribute [r] check
+  #   @return [String] kebab-case check identifier
+  # @!attribute [r] severity
+  #   @return [Symbol] `:error`, `:warning`, or `:info`
+  # @!attribute [r] message
+  #   @return [String] one-line statement of the problem
+  # @!attribute [r] why
+  #   @return [String] the Ractor rule behind the finding
+  # @!attribute [r] fix
+  #   @return [String] suggested remediation
+  # @!attribute [r] path
+  #   @return [String] file path, or a label for runtime findings
+  # @!attribute [r] line
+  #   @return [Integer, nil] 1-based line, nil for whole-target
+  # @!attribute [r] source
+  #   @return [String, nil] the offending source line, stripped
+  # @!attribute [r] autofix
+  #   @return [Autofix, nil] machine-applicable correction
+  # @!attribute [r] dependency
+  #   @return [Boolean] see {#dependency?}
+  Finding = Data.define(
+    :check, :severity, :message, :why, :fix,
+    :path, :line, :source, :autofix, :dependency
+  ) do
+    def initialize(source: nil, autofix: nil, dependency: false,
+      **rest)
+      super
+    end
+
+    # @return [Boolean] whether severity is `:error`
+    def error? = severity == :error
+
+    # True when the problem lives in a dependency's source, not the
+    # audited target: real, but not the target's bug to fix.
+    #
+    # @return [Boolean]
+    def dependency? = dependency
+
+    # @return [Boolean] whether an {Autofix} is attached
+    def fixable? = !autofix.nil?
+
+    # @return [Integer] rank from {SEVERITIES}, higher is worse
+    def severity_rank = SEVERITIES.fetch(severity)
+
+    # @return [String] "path:line", or just the path label
+    def location = line ? "#{path}:#{line}" : path
+  end
+end

data/lib/audition/fixer.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "rewriters"
+
+module Audition
+  # Applies machine-generated corrections (rubocop-style --fix).
+  # Two tiers: safe inline autofixes attached to findings, and,
+  # under unsafe: true, file-level rewrites planned by
+  # Audition::Rewriters. Byte offsets come from Prism, so edits are
+  # applied bottom-up to keep earlier offsets valid.
+  class Fixer
+    Plan = Data.define(:path, :source, :edits)
+
+    # @param unsafe [Boolean] also apply `:unsafe` autofixes and
+    #   the multi-site rewriters
+    def initialize(unsafe: false)
+      @unsafe = unsafe
+    end
+
+    # Applies planned edits to the files on disk.
+    #
+    # @param findings [Array<Finding>]
+    # @return [Hash{String => Integer}] path => applied edit count
+    def apply(findings)
+      plans(findings).to_h do |plan|
+        File.write(plan.path, patched(plan))
+        [plan.path, plan.edits.size]
+      end
+    end
+
+    # For `--dry-run`: what would change, without touching anything.
+    #
+    # @param findings [Array<Finding>]
+    # @return [Array<Hash>] per file: `:path` and `:hunks`
+    #   (`:line`, `:old`, `:new`)
+    def preview(findings)
+      plans(findings).map do |plan|
+        {path: plan.path, hunks: hunks(plan)}
+      end
+    end
+
+    def edit_count(findings)
+      plans(findings).sum { |plan| plan.edits.size }
+    end
+
+    # How many additional edits the unsafe tier would unlock; used
+    # for the "N more with --fix-unsafe" summary hint.
+    #
+    # @param findings [Array<Finding>]
+    # @return [Integer]
+    def self.unsafe_gain(findings)
+      new(unsafe: true).edit_count(findings) -
+        new(unsafe: false).edit_count(findings)
+    end
+
+    def plans(findings)
+      findings.group_by(&:path).filter_map do |path, group|
+        next unless path && File.file?(path)
+
+        source = File.read(path)
+        edits = build_edits(path, source, group)
+        next if edits.empty?
+
+        Plan.new(path: path, source: source,
+          edits: edits.sort_by { |e| -e.start_offset })
+      end
+    end
+
+    private
+
+    def build_edits(path, source, group)
+      magic = nil
+      planned = []
+      if @unsafe
+        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)
+        end
+      end
+
+      inline = group.filter_map do |finding|
+        autofix = finding.autofix
+        next unless autofix
+        next if autofix.unsafe? && !@unsafe
+        next if magic && magic[:covers].include?(finding.check)
+
+        autofix
+      end
+      inline << magic[:edit] if magic
+      accept_non_overlapping(inline + planned)
+    end
+
+    # First edit wins on overlap.
+    def accept_non_overlapping(edits)
+      accepted = []
+      edits.each do |edit|
+        overlap = accepted.any? do |other|
+          edit.start_offset < other.end_offset &&
+            other.start_offset < edit.end_offset
+        end
+        accepted << edit unless overlap
+      end
+      accepted
+    end
+
+    def patched(plan)
+      source = plan.source.dup
+      plan.edits.each do |edit|
+        source[edit.start_offset...edit.end_offset] =
+          edit.replacement
+      end
+      source
+    end
+
+    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]
+        updated = old.dup
+        span = ((edit.start_offset - line_start)...
+                (edit.end_offset - line_start))
+        updated[span] = edit.replacement
+        {
+          line: plan.source[0, edit.start_offset].count("\n") + 1,
+          old: old,
+          new: updated.chomp
+        }
+      end
+    end
+  end
+end