audition 0.3.0 → 0.4.1

data/lib/audition/dynamic/prober.rb

@@ -12,17 +12,17 @@ module Audition
     #   @return [Symbol] `:script`, `:require`, `:rack`, `:rails`,
     #     or `:capabilities`
     # @!attribute [r] raw
-    #   @return [Hash] the harness's parsed JSON, verbatim
+    #   @return [Hash] the harness's document, 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.
+    # Spawns the harness subprocess per probe mode, loads the
+    # document it prints, and converts observations into findings.
     class Prober
-      HARNESS = File.expand_path("harness.rb", __dir__)
+      HARNESS = File.expand_path("harness.rb", __dir__).freeze
 
       RUNTIME_WHY =
         "Observed on the live object graph after loading the " \
@@ -60,13 +60,13 @@ module Audition
 
       def probe_script(entry)
         path = entry[:path]
-        ractor = run("script_ractor", "path" => 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)
+        main = run("script_main", {"path" => path})
         finding = script_finding(path, ractor, main)
         Result.new(mode: :script,
           raw: {"ractor" => ractor, "main" => main},
@@ -76,6 +76,7 @@ module Audition
       def script_finding(path, ractor, main)
         if main["ok"]
           error = describe(ractor)
+          site = failure_site(ractor, prefix: "#{path}:")
           Finding.new(
             check: "dynamic-script",
             severity: :error,
@@ -84,11 +85,12 @@ module Audition
                  "failed under Ractor.new; the static findings " \
                  "usually pinpoint the exact line.",
             fix: "Fix the static findings for this file, then " \
-                 "re-audition.",
+                 "re-run Audition.",
             path: path,
-            line: nil
+            line: site&.last
           )
         else
+          site = failure_site(main, prefix: "#{path}:")
           Finding.new(
             check: "dynamic-script",
             severity: :error,
@@ -97,7 +99,7 @@ module Audition
                  "Ractor, so Ractor-readiness cannot be assessed.",
             fix: "Make the script run standalone first.",
             path: path,
-            line: nil
+            line: site&.last
           )
         end
       end
@@ -105,42 +107,144 @@ module Audition
       def probe_require(entry)
         feature = entry[:feature]
         raw = run("require",
-          "feature" => feature,
-          "load_paths" => Array(entry[:load_paths]),
-          "root" => entry[:root],
-          "known_compiled" => Array(entry[:compiled_files]))
-        findings = runtime_findings(raw, feature)
+          {"feature" => feature,
+           "load_paths" => Array(entry[:load_paths]),
+           "root" => entry[:root],
+           "known_compiled" => Array(entry[:compiled_files]),
+           "max_constants" => entry[:max_constants]})
+        findings = runtime_findings(raw, feature,
+          root: entry[:root])
         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],
-          "known_compiled" => Array(entry[:compiled_files]))
+          {"environment" => entry[:environment],
+           "root" => entry[:root],
+           "known_compiled" => Array(entry[:compiled_files]),
+           "max_constants" => entry[:max_constants]},
+          root: entry[:root])
         boot = raw["boot"]
+        findings = runtime_findings(raw, entry[:environment],
+          root: entry[:root])
         if boot && !boot["ok"]
-          finding = Finding.new(
+          # The sweep of whatever loaded before the failure stays:
+          # a partial dynamic result beats none.
+          why = "Ractor-readiness cannot be fully assessed " \
+                "until the application boots."
+          if raw["scanned"].to_i.positive?
+            why += " Findings below cover what loaded before " \
+                   "the failure."
+          end
+          site = failure_site(boot, prefix: own_prefix(entry[:root]))
+          findings.unshift(Finding.new(
             check: "dynamic-rails",
             severity: :error,
             message: "Rails failed to boot: #{describe(boot)}",
-            why: "Ractor-readiness cannot be assessed until the " \
-                 "application boots.",
+            why: why,
             fix: "Boot the app (bin/rails runner 1) and fix " \
-                 "whatever breaks, then re-audition.",
-            path: entry[:environment],
-            line: nil
-          )
+                 "whatever breaks, then re-run Audition.",
+            path: site&.first || entry[:environment],
+            line: site&.last
+          ))
           return Result.new(mode: :rails, raw: raw,
-            findings: [finding], passed: false)
+            findings: findings, passed: false)
         end
 
-        findings = runtime_findings(raw, entry[:environment])
+        findings.concat(ractorize_findings(raw["ractorize"], entry))
         Result.new(mode: :rails, raw: raw, findings: findings,
           passed: own_clean?(findings))
       end
 
+      # What happened once the booted application was frozen: no
+      # entry point on this Rails, the first object it could not
+      # share, a request that broke on the frozen graph, or one
+      # that only broke inside a worker.
+      def ractorize_findings(info, entry)
+        return [] unless info.is_a?(Hash)
+
+        environment = entry[:environment]
+        prefix = own_prefix(entry[:root])
+        unless info["available"]
+          return [Finding.new(
+            check: "dynamic-rails",
+            severity: :info,
+            message: "Rails #{info["rails"]} has no ractorize!; " \
+                     "the application graph was not frozen",
+            why: "Rails 8.2 adds Rails::Application#ractorize!, " \
+                 "which deep-freezes the application and " \
+                 "everything it reaches; a lazy memoization on " \
+                 "any object in that graph raises FrozenError " \
+                 "afterwards. Without it the probe can only " \
+                 "sweep constants and class-level state.",
+            fix: "Upgrade to Rails 8.2 so the probe can freeze " \
+                 "the application and serve a request through it.",
+            path: environment,
+            line: nil
+          )]
+        end
+
+        unless info["ok"]
+          site = failure_site(info, prefix: prefix)
+          return [Finding.new(
+            check: "dynamic-rails",
+            severity: :error,
+            message: "ractorize! failed: #{describe(info)}",
+            why: "Rails::Application#ractorize! deep-freezes the " \
+                 "application and everything it reaches (routes, " \
+                 "middleware, configuration); the object the " \
+                 "error names is the first one that cannot be " \
+                 "shared. #{RUNTIME_WHY}",
+            fix: "Make the named object shareable: freeze it, " \
+                 "drop the Proc, Mutex, or IO it holds, or keep " \
+                 "it per-Ractor; then re-run.",
+            path: site&.first || environment,
+            line: site&.last
+          )]
+        end
+
+        main = info["main_request"] || {}
+        unless main["ok"]
+          site = failure_site(main, prefix: prefix)
+          return [Finding.new(
+            check: "dynamic-rails",
+            severity: :error,
+            message: "GET / after ractorize! failed on the main " \
+                     "Ractor: #{describe(main)}",
+            why: "The application is frozen, so a lazy " \
+                 "memoization on any object the request touches " \
+                 "writes an instance variable on a frozen object " \
+                 "and raises FrozenError. #{RUNTIME_WHY}",
+            fix: "Compute the value eagerly in initialize, warm " \
+                 "it in a freeze override that calls the reader " \
+                 "before super, or drop the memo and recompute.",
+            path: site&.first || environment,
+            line: site&.last
+          )]
+        end
+
+        ractor = info["ractor_request"] || {}
+        return [] if ractor["ok"]
+
+        site = failure_site(ractor, prefix: prefix)
+        [Finding.new(
+          check: "dynamic-rails",
+          severity: :error,
+          message: "GET / inside a Ractor after ractorize! " \
+                   "failed: #{describe(ractor)}",
+          why: "Serving on the main Ractor after ractorize! " \
+               "worked; inside a worker the request touched " \
+               "state a non-main Ractor cannot reach. " \
+               "#{RUNTIME_WHY}",
+          fix: "Remove global and class-level state touched " \
+               "during request handling; keep per-Ractor state " \
+               "in Ractor.store_if_absent.",
+          path: site&.first || environment,
+          line: site&.last
+        )]
+      end
+
       # A probe passes when the target's own surface is clean;
       # dependency errors surface in the findings and drive the
       # blocked verdict instead.
@@ -150,10 +254,18 @@ module Audition
 
       def probe_rack(entry)
         config_ru = entry[:config_ru]
-        raw = run("rack", "config_ru" => config_ru)
-        findings = rack_findings(raw, config_ru)
+        root = entry[:root] || File.dirname(config_ru)
+        raw = run("rack",
+          {"config_ru" => config_ru,
+           "root" => root,
+           "known_compiled" => Array(entry[:compiled_files]),
+           "max_constants" => entry[:max_constants]},
+          root: root)
+        findings = rack_findings(raw, config_ru, root)
+        findings += runtime_findings(raw, config_ru, root: root) unless raw["error"]
         passed = raw.dig("ractor_boot_call", "ok") == true &&
-          raw.dig("concurrency", "failures").to_i.zero?
+          raw.dig("concurrency", "failures").to_i.zero? &&
+          own_clean?(findings)
         Result.new(mode: :rack, raw: raw, findings: findings,
           passed: passed)
       end
@@ -166,19 +278,28 @@ module Audition
 
       # -- findings builders ---------------------------------------
 
-      def runtime_findings(raw, label)
+      def runtime_findings(raw, label, root: nil)
         if raw["error"]
-          return [load_failure_finding(raw, label)]
+          return [load_failure_finding(raw, label, root)]
         end
 
         findings = []
         raw.fetch("unshareable_constants", []).each do |entry|
+          blocker = entry["blocker"]
+          detail =
+            if blocker.nil? || blocker == entry["class"]
+              ""
+            elsif entry["blocker_nested"]
+              " (blocked by #{blocker} inside)"
+            else
+              " (just not frozen)"
+            end
           findings << runtime_finding(
             entry, label,
             check: "runtime-unshareable-constant",
             severity: :error,
             message: "constant #{entry["const"]} holds an " \
-                     "unshareable #{entry["class"]}",
+                     "unshareable #{entry["class"]}#{detail}",
             why: "Reading it from a non-main Ractor raises " \
                  "Ractor::IsolationError. #{RUNTIME_WHY}",
             fix: "Freeze it deeply at definition time " \
@@ -188,6 +309,24 @@ module Audition
         raw.fetch("class_state", []).each do |entry|
           findings << class_state_finding(entry, label)
         end
+        raw.fetch("unshareable_procs", []).each do |entry|
+          findings << runtime_finding(
+            entry, label,
+            check: "runtime-unshareable-proc",
+            severity: :warning,
+            message: "Rails could not make a callback block " \
+                     "Ractor-shareable: #{entry["proc"]}",
+            why: "With unshareable_proc_action set to :warn, " \
+                 "Rails ran Ractor.shareable_proc on this block " \
+                 "and it raised Ractor::IsolationError, so the " \
+                 "callback keeps an unshareable Proc; a non-main " \
+                 "Ractor running it raises. #{RUNTIME_WHY}",
+            fix: "Capture only shareable values: freeze the " \
+                 "local, inline it, or hoist a shareable leaf " \
+                 "such as a Symbol into a fresh local assigned " \
+                 "once before the block."
+          )
+        end
         raw.fetch("class_variables", []).each do |entry|
           findings << runtime_finding(
             entry, label,
@@ -208,6 +347,22 @@ module Audition
 
           findings << native_finding(entry, label)
         end
+        # A truncated sweep must never read as a clean one.
+        if raw["truncated"]
+          findings.unshift(Finding.new(
+            check: "runtime-scan",
+            severity: :warning,
+            message: "constant sweep truncated after " \
+                     "#{raw["scanned"]} constants " \
+                     "(limit #{raw["limit"]})",
+            why: "Constants beyond the limit were never probed, " \
+                 "so their absence from the findings proves " \
+                 "nothing.",
+            fix: "Raise the probe's max_constants and re-run.",
+            path: label,
+            line: nil
+          ))
+        end
         findings
       end
 
@@ -292,7 +447,8 @@ module Audition
         )
       end
 
-      def load_failure_finding(raw, label)
+      def load_failure_finding(raw, label, root = nil)
+        site = failure_site(raw, prefix: own_prefix(root))
         Finding.new(
           check: "runtime-load",
           severity: :error,
@@ -300,14 +456,14 @@ module Audition
           why: "Ractor-readiness cannot be assessed until the " \
                "target loads.",
           fix: "Make `require` succeed on a bare Ruby first.",
-          path: label,
-          line: nil
+          path: site&.first || label,
+          line: site&.last
         )
       end
 
-      def rack_findings(raw, config_ru)
+      def rack_findings(raw, config_ru, root = nil)
         if raw.dig("ractor_boot_call", "ok")
-          return concurrency_findings(raw, config_ru)
+          return concurrency_findings(raw, config_ru, root)
         end
 
         if raw["rack_available"] == false
@@ -316,7 +472,7 @@ module Audition
             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.",
+            fix: "Install rack next to Audition and re-run.",
             path: config_ru,
             line: nil
           )]
@@ -332,6 +488,10 @@ module Audition
             "booting config.ru and serving one GET / inside a " \
             "Ractor failed."
           end
+        site = failure_site(raw["ractor_boot_call"],
+          prefix: own_prefix(root)) ||
+          failure_site({"error" => raw["main_boot_error"]},
+            prefix: own_prefix(root))
         [Finding.new(
           check: "dynamic-rack",
           severity: :error,
@@ -340,16 +500,18 @@ module Audition
           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
+          path: site&.first || config_ru,
+          line: site&.last
         )]
       end
 
-      def concurrency_findings(raw, config_ru)
+      def concurrency_findings(raw, config_ru, root = nil)
         stats = raw["concurrency"] || {}
         failures = stats["failures"].to_i
         return [] if failures.zero?
 
+        site = failure_site({"error" => stats["first_error"]},
+          prefix: own_prefix(root))
         [Finding.new(
           check: "dynamic-rack-concurrency",
           severity: :error,
@@ -361,11 +523,43 @@ module Audition
                "shared state races. #{RUNTIME_WHY}",
           fix: "Look for process-global state touched during " \
                "request handling and boot.",
-          path: config_ru,
-          line: nil
+          path: site&.first || config_ru,
+          line: site&.last
         )]
       end
 
+      # A backtrace frame inside the target names the failing
+      # line; frames outside it stay unattributed rather than
+      # pinning a finding to a dependency's file.
+      BACKTRACE_FRAME = /\A(.+?):(\d+):in /
+
+      def failure_site(hash, prefix:)
+        prefixes = Array(prefix)
+        return nil if prefixes.empty? || !hash.is_a?(Hash)
+
+        error = hash["error"].is_a?(Hash) ? hash["error"] : hash
+        frame = Array(error["backtrace"]).find do |f|
+          f.is_a?(String) && prefixes.any? { |p| f.start_with?(p) }
+        end
+        match = frame&.match(BACKTRACE_FRAME)
+        match && [match[1], Integer(match[2], 10)]
+      end
+
+      # require realpaths frames while eval keeps paths as given,
+      # so a symlinked root (macOS /var) must match both spellings.
+      def own_prefix(root)
+        return nil if root.nil?
+
+        [root + File::SEPARATOR,
+          realpath(root) + File::SEPARATOR].uniq
+      end
+
+      def realpath(path)
+        File.realpath(path)
+      rescue SystemCallError
+        path
+      end
+
       def describe(hash)
         error = hash.is_a?(Hash) ? (hash["error"] || hash) : {}
         klass = error["class"] || "UnknownError"
@@ -375,12 +569,12 @@ 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)
+      # The harness prints one Marshal document; anything else on
+      # its stdout (a crash before the document) is reported with
+      # the tail of its stderr. Stderr can carry arbitrary target
+      # bytes, so it is forced to valid UTF-8 first.
+      def run(mode, payload = {}, root: nil)
+        out, err, timed_out = execute(mode, payload, root: root)
         err = sanitize(err)
         if timed_out
           return {"error" => {
@@ -388,8 +582,11 @@ module Audition
             "message" => "harness exceeded #{@timeout}s"
           }}
         end
-        JSON.parse(out)
-      rescue JSON::ParserError
+        document = Marshal.load(out)
+        raise TypeError, "not a document" unless document.is_a?(Hash)
+
+        document
+      rescue TypeError, ArgumentError, EOFError
         {"error" => {
           "class" => "HarnessFailure",
           "message" => err.split("\n").last(5).join("; ")
@@ -405,10 +602,30 @@ module Audition
       # 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)
+      def execute(mode, payload, root: nil)
         cmd = [@ruby, "-W0", HARNESS, mode]
-        Open3.popen3(*cmd, pgroup: true) do |stdin, stdout, stderr, wait|
-          stdin.write(JSON.generate(payload))
+        # An app boots against its own bundle: the subprocess runs
+        # from the target root with the target's Gemfile. When
+        # Audition itself runs under bundle exec, the inherited
+        # Bundler environment (RUBYOPT's -rbundler/setup above all)
+        # would activate Audition's bundle inside the child before
+        # the harness starts, so it is scrubbed first.
+        env = {}
+        opts = {pgroup: true}
+        if root && File.directory?(root)
+          opts[:chdir] = root
+          gemfile = File.join(root, "Gemfile")
+          if File.file?(gemfile)
+            ENV.each_key do |key|
+              env[key] = nil if key.start_with?("BUNDLE") ||
+                %w[RUBYOPT RUBYLIB].include?(key)
+            end
+            env["BUNDLE_GEMFILE"] = gemfile
+          end
+        end
+        Open3.popen3(env, *cmd, **opts) do |stdin, stdout, stderr, wait|
+          stdin.binmode
+          stdin.write(Marshal.dump(payload))
           stdin.close
           out_reader = reader(stdout)
           err_reader = reader(stderr)

data/lib/audition/finding.rb

@@ -64,12 +64,18 @@ module Audition
   #   @return [Autofix, nil] machine-applicable correction
   # @!attribute [r] dependency
   #   @return [Boolean] see {#dependency?}
+  # @!attribute [r] test
+  #   @return [Boolean] see {#test?}
+  # @!attribute [r] subject
+  #   @return [String, nil] the object a finding is about, in a
+  #     form the dynamic probe can match ("Owner/@ivar"), so a
+  #     runtime proof of shareability can retire the static guess
   Finding = Data.define(
     :check, :severity, :message, :why, :fix,
-    :path, :line, :source, :autofix, :dependency
+    :path, :line, :source, :autofix, :dependency, :test, :subject
   ) do
     def initialize(source: nil, autofix: nil, dependency: false,
-      **rest)
+      test: false, subject: nil, **rest)
       super
     end
 
@@ -82,6 +88,12 @@ module Audition
     # @return [Boolean]
     def dependency? = dependency
 
+    # True when the problem lives in the target's test or spec
+    # code: real, but never loaded by the production boot.
+    #
+    # @return [Boolean]
+    def test? = test
+
     # @return [Boolean] whether an {Autofix} is attached
     def fixable? = !autofix.nil?