audition 0.3.0 → 0.4.0

data/lib/audition/report.rb

@@ -9,7 +9,7 @@ module Audition
       not_ready: "not ractor-ready",
       blocked: "own code is ractor-ready; blocked by dependencies",
       risky: "risky: warnings only, no hard errors",
-      ready: "ractor-ready as far as audition can tell"
+      ready: "ractor-ready as far as Audition can tell"
     }.freeze
 
     attr_reader :target_type, :target_root, :findings,
@@ -60,13 +60,19 @@ module Audition
       counts[:dep_error].positive?
     end
 
+    # Test findings count apart at every severity: they are the
+    # target's code, but a production boot never loads them, so
+    # they never touch the verdict.
     def counts
       @counts ||= begin
         base = {error: 0, dep_error: 0, warning: 0, info: 0,
+                test_error: 0, test_warning: 0, test_info: 0,
                 fixable: 0}
         findings.each_with_object(base) do |f, acc|
           if f.error? && f.dependency?
             acc[:dep_error] += 1
+          elsif f.test?
+            acc[:"test_#{f.severity}"] += 1
           else
             acc[f.severity] += 1
           end
@@ -86,3 +92,4 @@ require_relative "report/style"
 require_relative "report/text"
 require_relative "report/json"
 require_relative "report/github"
+require_relative "report/sweep"

data/lib/audition/rewriters.rb

@@ -81,7 +81,10 @@ module Audition
         values = collector.values
         kinds = values.map { |v| classifier.classify(v) }
         flagged = kinds.reject do |k|
-          %i[shareable unknown].include?(k)
+          # A magic comment cannot fix opaque values, so they
+          # must not veto one either.
+          %i[shareable unknown instance_new opaque_call
+            shallow_opaque].include?(k)
         end
         scv_ok = values.any? &&
           values.all? { |value| deep_literal?(value, classifier) }

data/lib/audition/static/analyzer.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "etc"
+require_relative "work_split"
 
 module Audition
   module Static
@@ -27,6 +27,10 @@ module Audition
 
       PARALLEL_THRESHOLD = 16
 
+      # Workers report in batches: a port message per file would
+      # cost more than the redraw it feeds.
+      TICK_STRIDE = 25
+
       # Scans files across Ractors when there are enough of them to
       # be worth the spawn cost. Checks are plain shareable classes
       # with deeply frozen catalogs, findings copy back through
@@ -34,47 +38,112 @@ module Audition
       # serial path.
       #
       # @param paths [Array<String>] files to analyze
-      # @param workers [Integer] Ractor count (defaults to
-      #   processor count minus one)
+      # @param workers [Integer, nil] Ractor count (defaults to
+      #   {#default_workers})
       # @param threshold [Integer] minimum file count before
       #   Ractors are used at all
+      # @param progress [Progress] ticked per file
       # @return [Array<Finding>]
-      def analyze_paths(paths, workers: default_workers,
-        threshold: PARALLEL_THRESHOLD)
+      def analyze_paths(paths, workers: nil,
+        threshold: PARALLEL_THRESHOLD, progress: Progress::SILENT)
+        workers ||= default_workers
         if paths.size < threshold || workers <= 1
-          return paths.flat_map { |path| analyze_path(path) }
+          return serial_analyze(paths, progress)
         end
 
-        parallel_analyze(paths, workers)
+        parallel_analyze(paths, workers, progress)
       rescue Ractor::Error => e
         # The silent fallback would otherwise mask a check that is
         # itself Ractor-hostile; surface it under -w.
         if $VERBOSE
-          warn "audition: parallel scan fell back to serial: " \
+          warn "Audition: parallel scan fell back to serial: " \
                "#{e.class}: #{e.message}"
         end
-        paths.flat_map { |path| analyze_path(path) }
+        progress.ractors = nil
+        serial_analyze(paths, progress)
       end
 
       private
 
-      def parallel_analyze(paths, workers)
+      def serial_analyze(paths, progress)
+        paths.flat_map do |path|
+          findings = analyze_path(path)
+          progress.tick
+          findings
+        end
+      end
+
+      # A port carries counts out of the workers while they run:
+      # the alternative is a status line frozen for the whole
+      # parallel phase, which is most of a large scan.
+      def parallel_analyze(paths, workers, progress)
         experimental = Warning[:experimental]
         Warning[:experimental] = false
-        slice = (paths.size / workers.to_f).ceil
         checks = @checks
-        paths.each_slice(slice).map do |chunk|
-          Ractor.new(chunk, checks) do |files, active_checks|
-            analyzer = Analyzer.new(checks: active_checks)
-            files.flat_map { |file| analyzer.analyze_path(file) }
+        port = progress.enabled? ? Ractor::Port.new : nil
+        chunks = balanced_chunks(paths, workers)
+        progress.ractors = chunks.size
+        ractors = chunks.map do |chunk|
+          # The sentinel goes out through `ensure` so a worker that
+          # raises still releases the drain loop; the exception
+          # itself still surfaces from `Ractor#value`.
+          Ractor.new(chunk, checks, port) do |files, active, tap|
+            analyzer = Analyzer.new(checks: active)
+            pending = 0
+            begin
+              files.flat_map do |file|
+                findings = analyzer.analyze_path(file)
+                pending += 1
+                if tap && pending >= TICK_STRIDE
+                  tap.send(pending)
+                  pending = 0
+                end
+                findings
+              end
+            ensure
+              tap&.send(pending)
+              tap&.send(:done)
+            end
           end
-        end.flat_map(&:value)
+        end
+        drain(port, ractors.size, progress) if port
+        ractors.flat_map(&:value)
       ensure
         Warning[:experimental] = experimental
       end
 
+      def drain(port, workers, progress)
+        done = 0
+        while done < workers
+          message = port.receive
+          if message == :done
+            done += 1
+          else
+            progress.tick(message)
+          end
+        end
+      rescue
+        # Narration is cosmetic; a closed port ends it quietly and
+        # `Ractor#value` still reports what went wrong.
+        nil
+      end
+
       def default_workers
-        [Etc.nprocessors - 1, 1].max
+        WorkSplit.workers
+      end
+
+      # Byte size stands in for parse cost, and the stat it costs
+      # is nothing beside the parse it schedules.
+      def balanced_chunks(paths, workers)
+        WorkSplit.chunks(
+          paths.map { |path| [path, file_size(path)] }, workers
+        )
+      end
+
+      def file_size(path)
+        File.size(path)
+      rescue SystemCallError
+        0
       end
 
       def analyze_file(file)

data/lib/audition/static/checks/dependency_class_state.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Audition
+  module Static
+    module Checks
+      # Class-level state owned by a dependency. A gem's own source
+      # is outside the scanned tree, so the graph audit never sees
+      # the ivar and the call site is the only place left to flag.
+      # Generated type stubs in the target's tree record it: an
+      # attribute reader on a singleton class is a class-level ivar
+      # read by definition, and the generator marks those methods
+      # apart from ones that compute their answer.
+      class DependencyClassState < Base
+        explain :read,
+          severity: :warning,
+          message: "%{owner}.%{name} reads class-level state " \
+                   "owned by a dependency",
+          why: "The stub for %{owner} declares %{name} as an " \
+               "attribute on its singleton class, so the call " \
+               "returns a class-level instance variable. A " \
+               "non-main Ractor raises Ractor::IsolationError " \
+               "(\"can not get unshareable values from instance " \
+               "variables of classes/modules\") unless whatever " \
+               "the value happens to be is shareable.",
+          fix: "Read it once on the main Ractor and pass the " \
+               "value in, or make the dependency's assignment " \
+               "deeply shareable before any Ractor starts."
+
+        explain :write,
+          severity: :error,
+          message: "%{owner}.%{name}= writes class-level state " \
+                   "owned by a dependency",
+          why: "Assigning an attribute on %{owner}'s singleton " \
+               "class writes a class-level instance variable, " \
+               "which a non-main Ractor cannot do at all: it " \
+               "raises Ractor::IsolationError regardless of what " \
+               "the value is.",
+          fix: "Configure the dependency at boot on the main " \
+               "Ractor and leave it alone afterwards."
+
+        # The generator documents a reader it generated from an
+        # attribute; a hand-written method of the same shape gets
+        # its own prose and stays quiet.
+        STUB_READER = /Returns the value of attribute (\w+)/
+        STUB_SINGLETON = /\A\s*class\s+<<\s+self\b/
+        STUB_SCOPE = /\A\s*(?:class|module)\s+([A-Za-z0-9_:]+)/
+        STUB_DEF = /\A\s*def ([a-z_][A-Za-z0-9_]*)[(;]/
+        STUB_COMMENT = /\A\s*#/
+
+        class << self
+          attr_reader :attributes
+
+          # Owner name => set of attribute names, kept shareable
+          # for parallel scanning.
+          def attributes=(pairs)
+            grouped = pairs.group_by(&:first)
+              .transform_values { |v| v.map(&:last).uniq }
+            @attributes = Ractor.make_shareable( # audition:disable
+              grouped
+            )
+          end
+
+          # @param paths [Array<String>] scanned files; only
+          #   generated type stubs carry this evidence
+          # @return [void]
+          def learn(paths)
+            pairs = []
+            paths.each do |path|
+              next unless path.end_with?(".rbi")
+
+              read_stub(path, pairs)
+            end
+            self.attributes = pairs
+          end
+
+          private
+
+          # Stub indentation tracks nesting exactly, so the scope
+          # stack follows it rather than parsing the file.
+          def read_stub(path, pairs)
+            scope = []
+            singleton = []
+            indents = []
+            documented = nil
+            File.foreach(path) do |raw|
+              line = raw.rstrip
+              next if line.empty?
+
+              indent = line[/\A */].size
+              while indents.any? && indent <= indents.last
+                indents.pop
+                scope.pop
+                singleton.pop
+              end
+              documented =
+                step_stub(line, scope, singleton, indents,
+                  documented, pairs)
+            end
+          rescue SystemCallError
+            nil
+          end
+
+          def step_stub(line, scope, singleton, indents,
+            documented, pairs)
+            case line
+            when STUB_COMMENT
+              return STUB_READER.match(line)&.[](1) || documented
+            when STUB_SINGLETON
+              scope.push(scope.last)
+              singleton.push(true)
+              indents.push(line[/\A */].size)
+            when STUB_SCOPE
+              name = Regexp.last_match(1)
+              scope.push(scope.empty? ? name : "#{scope.last}::#{name}")
+              singleton.push(false)
+              indents.push(line[/\A */].size)
+            when STUB_DEF
+              name = Regexp.last_match(1)
+              if singleton.last && scope.last && documented == name
+                pairs << [scope.last, name]
+              end
+            end
+            nil
+          end
+        end
+
+        self.attributes = []
+
+        on :call_node do |node|
+          examine(node)
+        end
+
+        private
+
+        def examine(node)
+          owner = constant_name(node.receiver)
+          return unless owner
+
+          name = node.name.to_s
+          writer = name.end_with?("=")
+          attribute = writer ? name.chomp("=") : name
+          names = self.class.attributes[owner]
+          return unless names&.include?(attribute)
+
+          flag(node, writer ? :write : :read,
+            owner: owner, name: attribute)
+        end
+
+        def constant_name(node)
+          case node
+          when Prism::ConstantReadNode
+            node.name.to_s
+          when Prism::ConstantPathNode
+            node.location.slice.delete_prefix("::")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/audition/static/checks/mutable_constants.rb

@@ -103,6 +103,44 @@ module Audition
                "or drop the default proc and fetch with a " \
                "literal default: hash.fetch(key, [])."
 
+        explain :unshareable_instance,
+          severity: :warning,
+          message: "constant %{name} holds an unfrozen %{klass} " \
+                   "instance",
+          why: "A fresh instance is unfrozen, so non-main " \
+               "Ractors raise Ractor::IsolationError reading " \
+               "it. A warning, not an error: .new can be " \
+               "overridden to return a shareable value.",
+          fix: "Freeze it when deeply immutable, wrap in " \
+               "Ractor.make_shareable, or keep a per-Ractor " \
+               "copy via Ractor.store_if_absent."
+
+        explain :shallow_opaque,
+          severity: :warning,
+          message: "constant %{name} is frozen at the top level " \
+                   "only; what it holds is unproven",
+          why: "Freezing is shallow: elements and instance " \
+               "variables stay as their calls returned them, and " \
+               "unless those are deeply frozen a non-main Ractor " \
+               "reading the constant raises " \
+               "Ractor::IsolationError. The dynamic probe settles " \
+               "it when the target boots.",
+          fix: "Build the value with Ractor.make_shareable for a " \
+               "deep freeze, or silence a known-shareable value " \
+               "with a disable comment."
+
+        explain :opaque_constant,
+          severity: :warning,
+          message: "constant %{name} holds the result of " \
+                   "%{method}; shareability unproven",
+          why: "Unless the call returns a deeply frozen value, " \
+               "non-main Ractors raise Ractor::IsolationError " \
+               "reading the constant. The dynamic probe settles " \
+               "it when the target boots.",
+          fix: "Freeze the result at definition time, or " \
+               "silence a known-shareable value with a disable " \
+               "comment."
+
         explain :constant_mutation,
           severity: :warning,
           message: "in-place %{method} on constant %{name}",
@@ -152,6 +190,10 @@ module Audition
           # finding stays, the autofix goes.
           fix_ok = !mutated?(name) && !customized?(name)
           kind = classifier.classify(value)
+          # A Sorbet cast returns its argument and a begin
+          # block its last statement: fixes, type names and
+          # depth checks target the value inside.
+          value = classifier.unwrap(value)
           # Build-then-freeze: a bare `NAME.freeze` later in the
           # same body makes the literal as good as frozen, so
           # only provably mutable elements remain to report.
@@ -195,6 +237,20 @@ module Audition
               autofix: wrappable ? wrap_make_shareable(value) : nil)
           when :default_proc
             flag(node, :hash_default_proc, name: name)
+          when :shallow_opaque
+            flag(node, :shallow_opaque, name: name)
+          # Build-then-freeze leaves depth unknown: stay silent.
+          when :instance_new
+            unless frozen_later?(name)
+              flag(node, :unshareable_instance, name: name,
+                klass:
+                  classifier.const_name(value.receiver) || "new")
+            end
+          when :opaque_call
+            unless frozen_later?(name)
+              flag(node, :opaque_constant, name: name,
+                method: opaque_display(value))
+            end
           end
         end
 
@@ -313,6 +369,21 @@ module Audition
           owner ? "#{owner}.#{call.name}" : "String##{call.name}"
         end
 
+        # The receiver is arbitrary, often a chain, so the
+        # fallback names only the method.
+        def opaque_display(call)
+          owner = classifier.const_name(call.receiver)
+          method =
+            if owner
+              "#{owner}.#{call.name}"
+            elsif call.receiver
+              ".#{call.name}"
+            else
+              call.name.to_s
+            end
+          "a #{method} call"
+        end
+
         # `.freeze` binds tighter than an operator: `"a" + "b".freeze`
         # freezes only "b", so operator calls get parentheses while
         # literals and parenthesized or argument-free calls take