audition 0.3.0 → 0.4.1

data/lib/audition/report/sweep.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "json"
+require "table_tennis"
+
+module Audition
+  class Report
+    # Renders a bundle sweep. Its unit is a gem rather than a
+    # finding, so it gets its own renderer instead of bending
+    # Report around a shape it does not have.
+    class Sweep
+      CELLS = {
+        :not_ready => "not ready", :blocked => "blocked",
+        :risky => "risky", :ready => "ready", nil => "-"
+      }.freeze
+
+      # The severity glyphs the text report uses, so a verdict
+      # reads the same in a cell as it does in a summary.
+      GLYPHS = {
+        not_ready: :error, blocked: :warning,
+        risky: :warning, ready: :pass
+      }.freeze
+
+      # Foreground only, and applied to the whole row: a
+      # background fill reads as a bar across the table, and a
+      # painted cell would widen its column by the invisible
+      # length of its own escape sequence. Ready gems keep the
+      # default color, so what is colored is what needs reading.
+      PAINTS = Ractor.make_shareable({
+        :not_ready => [:red], :blocked => [:magenta],
+        :risky => [:yellow], nil => [:faint]
+      })
+
+      TITLE = "Audition bundle sweep"
+
+      # @param rows [Array<BundleSweep::Row>] one per locked gem
+      # @param style [Style] palette for the text rendering
+      def initialize(rows, style)
+        @rows = rows
+        @style = style
+      end
+
+      # @param table_opts [Hash] what the terminal supports; see
+      #   the caller for why color cannot be detected here
+      # @return [String] the table plus a summary line
+      def render(**table_opts)
+        table = TableTennis.new(cells, title: TITLE, mark: paint,
+          **table_opts)
+        "#{table}\n#{summary}"
+      end
+
+      def json
+        JSON.pretty_generate(
+          "audition" => VERSION,
+          "ruby" => RUBY_VERSION,
+          "bundle" => @rows.map { |r| json_row(r) }
+        )
+      end
+
+      # Sweep rows carry no file or line, so annotations land on
+      # the run summary rather than a diff.
+      # @return [String] annotation lines plus a summary line
+      def annotations
+        lines = @rows.filter_map do |row|
+          level = annotation_level(row)
+          next unless level
+
+          "::#{level} title=Audition::gem #{row.name} " \
+          "#{row.version}: #{row.errors} errors, " \
+          "#{row.dep_errors} dependency errors, " \
+          "#{row.warnings} warnings (#{CELLS.fetch(row.verdict)})"
+        end
+        (lines << plain_summary).join("\n")
+      end
+
+      # @return [String] job summary page table for Actions
+      def markdown
+        lines = [
+          "## #{TITLE}", "",
+          "| gem | version | verdict | errors | dep errors " \
+          "| warnings | fixable |",
+          "| --- | --- | --- | --- | --- | --- | --- |"
+        ]
+        @rows.each do |r|
+          lines << "| #{r.name} | #{r.version} | " \
+            "#{CELLS.fetch(r.verdict)} | #{r.errors} | " \
+            "#{r.dep_errors} | #{r.warnings} | #{r.fixable} |"
+        end
+        lines.push("", plain_summary).join("\n")
+      end
+
+      private
+
+      def cells
+        @rows.map do |r|
+          {
+            "gem" => r.name,
+            "version" => r.version,
+            "verdict" => verdict_cell(r.verdict),
+            "errors" => clean_as_blank(r.errors),
+            "dep errors" => clean_as_blank(r.dep_errors),
+            "warnings" => clean_as_blank(r.warnings),
+            "fixable" => clean_as_blank(r.fixable),
+            "status" => r.status
+          }
+        end
+      end
+
+      def verdict_cell(verdict)
+        cell = CELLS.fetch(verdict)
+        glyph = GLYPHS[verdict]
+        glyph ? "#{@style.glyph(glyph)} #{cell}" : cell
+      end
+
+      # A clean count is the common case across hundreds of gems;
+      # leaving it to the table's placeholder keeps the eye on the
+      # rows that carry something.
+      def clean_as_blank(count)
+        count.positive? ? count : nil
+      end
+
+      # The table gem hands the lambda back the row it was given,
+      # which carries the gem but not the verdict symbol.
+      def paint
+        paints = @rows.to_h do |r|
+          [[r.name, r.version], PAINTS[r.verdict]]
+        end
+        ->(row) { paints[[row["gem"], row["version"]]] }
+      end
+
+      def summary
+        glyph, paint = if blockers.positive?
+          [:error, :red]
+        elsif ready == @rows.size
+          [:pass, :green]
+        else
+          [:warning, :yellow]
+        end
+        head = @style.public_send(paint,
+          "#{@style.glyph(glyph)} #{plain_summary}")
+        return head if blockers.zero?
+
+        "#{head} #{@style.dim("· #{blockers} not ready")}"
+      end
+
+      def plain_summary
+        "#{ready} of #{@rows.size} gems ractor-ready"
+      end
+
+      def ready
+        @ready ||= @rows.count { |r| r.verdict == :ready }
+      end
+
+      def blockers
+        @blockers ||= @rows.count { |r| r.verdict == :not_ready }
+      end
+
+      def annotation_level(row)
+        if row.verdict == :not_ready ||
+            (row.errors + row.dep_errors).positive?
+          "error"
+        elsif row.warnings.positive?
+          "warning"
+        end
+      end
+
+      def json_row(row)
+        {
+          "gem" => row.name,
+          "version" => row.version,
+          "verdict" => row.verdict&.to_s,
+          "errors" => row.errors,
+          "dependency_errors" => row.dep_errors,
+          "warnings" => row.warnings,
+          "infos" => row.infos,
+          "fixable" => row.fixable,
+          "status" => row.status
+        }
+      end
+    end
+  end
+end

data/lib/audition/report/text.rb

@@ -21,7 +21,7 @@ module Audition
 
       def header
         s = @style
-        title = s.bold("audition #{VERSION}")
+        title = s.bold("Audition #{VERSION}")
         meta = s.dim(
           "ruby #{RUBY_VERSION} · #{@report.target_type} at " \
           "#{@report.target_root}"
@@ -45,8 +45,10 @@ module Audition
         fix_mark = finding.fixable? ? " #{s.cyan(s.glyph(:fix))}" : ""
         dep_mark =
           finding.dependency? ? " #{s.dim("(dependency)")}" : ""
+        test_mark = finding.test? ? " #{s.dim("(tests)")}" : ""
         head = "    #{glyph} #{loc}#{finding.message}" \
-               "#{fix_mark}#{dep_mark} #{s.dim(finding.check)}"
+               "#{fix_mark}#{dep_mark}#{test_mark} " \
+               "#{s.dim(finding.check)}"
         [head,
           *annotation("why", finding.why),
           *annotation("fix", finding.fix)]
@@ -113,6 +115,15 @@ module Audition
           parts << s.yellow(pluralize(c[:warning], "warning"))
         end
         parts << s.cyan("#{c[:info]} info") if c[:info].positive?
+        test_total = c[:test_error] + c[:test_warning] +
+          c[:test_info]
+        if test_total.positive?
+          parts << s.dim(
+            pluralize(test_total, "test finding") +
+            " (#{c[:test_error]} error / " \
+            "#{c[:test_warning]} warning / #{c[:test_info]} info)"
+          )
+        end
         if c[:fixable].positive?
           parts << s.cyan(
             "#{c[:fixable]} fixable #{s.glyph(:fix)} " \

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) }
@@ -224,6 +227,9 @@ module Audition
           kinds = ops.map { |op| op[:kind] }
           next if kinds.include?(:other)
           next if ops.any? { |op| op[:body] }
+          # A memo written inside an on_main block already runs
+          # on the main Ractor; the audit rates the shape itself.
+          next if ops.any? { |op| op[:proxied] }
 
           memos = memo_sites(ops)
           if memos.empty?
@@ -617,9 +623,29 @@ module Audition
           @sclass_depth = 0
           @def_stack = []
           @defined_depth = 0
+          @proxy_depth = 0
           super
         end
 
+        # A block handed to `on_main` runs on the main Ractor by
+        # construction (the read-then-proxy escape hatch), so the
+        # ivar writes inside it are recorded as proxied.
+        def visit_call_node(node)
+          block = node.block
+          unless node.name == :on_main && block.is_a?(Prism::BlockNode)
+            return super
+          end
+
+          visit(node.receiver) if node.receiver
+          visit(node.arguments) if node.arguments
+          @proxy_depth += 1
+          begin
+            visit(block)
+          ensure
+            @proxy_depth -= 1
+          end
+        end
+
         def visit_class_node(node)
           scoped(node.constant_path.location.slice, :class) do
             super(node)
@@ -763,7 +789,8 @@ module Audition
             def_id: current_def && current_def[:id],
             def_name: current_def && current_def[:name],
             def_node: current_def && current_def[:node],
-            class_owner: @namespace.last[:kind] == :class
+            class_owner: @namespace.last[:kind] == :class,
+            proxied: @proxy_depth.positive?
           }
         end
       end

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