audition 0.2.4 → 0.4.0

data/lib/audition/cli.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
+require "json"
 require "optparse"
 require "table_tennis"
 
 module Audition
   class CLI
-    USAGE = "usage: audition [options] TARGET " \
+    USAGE = "usage: audition [options] TARGET [FILE...] " \
             "(a .rb script, directory, config.ru dir, Rails root, " \
-            "gem dir, or installed gem name)"
+            "gem dir, installed gem name, or several .rb files)"
 
     # Entry point used by `exe/audition`.
     #
@@ -31,13 +32,20 @@ module Audition
 
       return print_capabilities(options) if options[:capabilities]
 
-      target_arg = options[:args].first
-      unless target_arg
-        @stderr.puts(USAGE)
+      args = options[:args]
+      if args.empty?
+        @stderr.puts(style(options, io: @stderr).dim(USAGE))
         return 2
       end
 
-      target = Target.detect(target_arg)
+      # A single argument keeps full detection (including the
+      # dynamic probe); several arguments are the git-hook shape,
+      # a plain list of staged .rb files audited statically.
+      target = if args.size == 1
+        Target.detect(args.first)
+      else
+        Target.for_files(args)
+      end
       target = deps_target(target) if options[:deps]
       if target.type == :bundle
         sweep(target, options)
@@ -45,7 +53,7 @@ module Audition
         audit(target, options)
       end
     rescue Error => e
-      @stderr.puts("audition: #{e.message}")
+      complain(e.message, options)
       2
     end
 
@@ -57,7 +65,7 @@ module Audition
         dynamic_only: false, fix: false, unsafe: false,
         dry_run: false, capabilities: false, plain: false,
         timeout: 30, write_baseline: false, no_baseline: false,
-        deps: false, explicit: []
+        deps: false, progress: nil, workers: nil, explicit: []
       }
       parser = OptionParser.new do |o|
         o.banner = USAGE
@@ -89,11 +97,18 @@ module Audition
           "with --fix: show planned edits, change nothing") do
           options[:dry_run] = true
         end
-        o.on("--fail-on LEVEL", %w[error warning info],
-          "exit 1 threshold (default: error)") do |v|
+        o.on("--fail-on LEVEL", %w[error warning info never],
+          "exit 1 threshold (default: error); never always " \
+          "exits 0") do |v|
           options[:fail_on] = v.to_sym
           options[:explicit] << :fail_on
         end
+        o.on("--exit-zero",
+          "report findings but exit 0 (same as " \
+          "--fail-on never)") do
+          options[:fail_on] = :never
+          options[:explicit] << :fail_on
+        end
         o.on("--write-baseline",
           "record current findings as the baseline") do
           options[:write_baseline] = true
@@ -114,9 +129,20 @@ module Audition
           options[:timeout] = v
           options[:explicit] << :timeout
         end
+        o.on("-j", "--workers COUNT", Integer,
+          "scan Ractors (default: cores, capped by " \
+          "RUBY_MAX_CPU)") do |v|
+          options[:workers] = v
+          options[:explicit] << :workers
+        end
         o.on("--plain", "disable colors and hyperlinks") do
           options[:plain] = true
         end
+        o.on("--[no-]progress",
+          "narrate scan phases on stderr (default: on for a " \
+          "large tree on a terminal)") do |v|
+          options[:progress] = v
+        end
         o.on("-v", "--version") do
           @stdout.puts(VERSION)
           return 0
@@ -129,11 +155,19 @@ module Audition
       options[:args] = parser.parse(argv)
       options
     rescue OptionParser::ParseError => e
-      @stderr.puts("audition: #{e.message}")
-      @stderr.puts(USAGE)
+      complain(e.message)
+      @stderr.puts(style(nil, io: @stderr).dim(USAGE))
       2
     end
 
+    def complain(message, options = nil)
+      s = style(options, io: @stderr)
+      @stderr.puts(
+        "#{s.red(s.glyph(:error))} #{s.bold("Audition")}: " \
+        "#{message}"
+      )
+    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.
@@ -143,14 +177,16 @@ module Audition
       directives = Directives.new
       findings = []
       unless options[:dynamic_only]
-        findings = filter(static_findings(target, config),
+        findings = filter(static_findings(target, config, options),
           directives, config)
         findings = run_fix(target, findings, options) if options[:fix]
       end
 
       results = []
       if target.entry && !options[:static_only]
-        results << prober(options).probe(target.entry)
+        results << prober(options).probe(
+          target.entry.merge(compiled_files: target.compiled_files)
+        )
       end
 
       all = findings +
@@ -158,9 +194,11 @@ module Audition
 
       if options[:write_baseline]
         recorded = Baseline.write(target.root, all)
+        s = style(options)
         @stdout.puts(
-          "baseline written: #{recorded} finding(s) recorded in " \
-          "#{Baseline.path_for(target.root)}"
+          "#{s.green(s.glyph(:pass))} baseline written: " \
+          "#{s.bold("#{recorded} finding(s)")} recorded in " \
+          "#{s.cyan(Baseline.path_for(target.root))}"
         )
         return 0
       end
@@ -222,7 +260,10 @@ module Audition
         "#{s.red("#{introduced.size} introduced")}"
       )
       introduced.each do |f|
-        @stdout.puts("    + #{f.message} (#{f.location})")
+        @stdout.puts(
+          "    #{s.red("+")} #{f.message} " \
+          "#{s.cyan("(#{f.location})")}"
+        )
       end
     end
 
@@ -258,12 +299,55 @@ module Audition
       baseline.filter(findings, root: target.root)
     end
 
-    def static_findings(target, config)
+    def static_findings(target, config, options)
       files = target.ruby_files.reject do |file|
         config.excluded?(file.delete_prefix("#{target.root}/"))
       end
-      per_file = Static::Analyzer.new.analyze_paths(files)
-      per_file + Static::GraphAudit.new.analyze_paths(files)
+      compiled = target.compiled_files.reject do |file|
+        config.excluded?(file.delete_prefix("#{target.root}/"))
+      end
+      stubs = target.stub_files.reject do |file|
+        config.excluded?(file.delete_prefix("#{target.root}/"))
+      end
+      progress = Progress.for(units: files.size,
+        wanted: options[:progress], format: options[:format],
+        io: @stderr, style: options[:plain] ? plain_style : nil)
+      scan(target, files, stubs, compiled, progress,
+        workers: options[:workers]).map do |f|
+        if target.test_file?(f.path, dirs: config.test_dirs)
+          f.with(test: true)
+        else
+          f
+        end
+      end
+    end
+
+    # Phases are named for what a waiting reader wants to know;
+    # progress shares stderr with fix chatter, for the same reason.
+    def scan(target, files, stubs, compiled, progress, workers: nil)
+      progress.phase("learning", total: files.size + stubs.size) do |p|
+        Static::Checks::UnshareableReads.learn(files + stubs,
+          progress: p)
+        Static::Checks::DependencyClassState.learn(stubs)
+      end
+      per_file = progress.phase("checking", total: files.size) do |p|
+        Static::Analyzer.new.analyze_paths(files, workers: workers,
+          progress: p)
+      end
+      gem_calls = progress.phase("gem calls") do |p|
+        Static::GemCalls.new(root: target.root, stubs: stubs)
+          .analyze_paths(files, progress: p)
+      end
+      graph = progress.phase("graph") do |p|
+        Static::GraphAudit.new.analyze_paths(files,
+          constant_findings: per_file + gem_calls,
+          workers: workers, progress: p)
+      end
+      per_file + gem_calls + graph +
+        Static::NativeExtensions.new.analyze(target,
+          compiled_files: compiled)
+    ensure
+      progress.finish
     end
 
     # Fix chatter goes to stderr: stdout carries the report, which
@@ -277,16 +361,19 @@ module Audition
 
       applied = fixer.apply(findings)
       total = applied.values.sum
+      s = style(options, io: @stderr)
       if total.zero?
-        @stderr.puts("nothing to fix")
+        @stderr.puts(s.dim("nothing to fix"))
         return findings
       end
 
       @stderr.puts(
-        "fixed #{total} finding(s) in #{applied.size} file(s)"
+        "#{s.cyan(s.glyph(:fix))} #{s.green("fixed #{total} " \
+        "finding(s)")} in #{s.bold("#{applied.size} file(s)")}"
       )
-      filter(static_findings(target, Config.load(target.root)),
-        Directives.new, Config.load(target.root))
+      config = Config.load(target.root)
+      filter(static_findings(target, config, options),
+        Directives.new, config)
     end
 
     def render_preview(previews, options)
@@ -294,7 +381,7 @@ module Audition
       previews.each do |preview|
         @stderr.puts(s.bold(preview[:path]))
         preview[:hunks].each do |hunk|
-          @stderr.puts("  @ line #{hunk[:line]}")
+          @stderr.puts(s.cyan("  @ line #{hunk[:line]}"))
           hunk[:old].each_line do |line|
             @stderr.puts(s.red("  - #{line.chomp}"))
           end
@@ -303,7 +390,7 @@ module Audition
           end
         end
       end
-      @stderr.puts("dry run: no files were changed")
+      @stderr.puts(s.dim("dry run: no files were changed"))
     end
 
     def prober(options)
@@ -312,25 +399,54 @@ module Audition
 
     def emit(report, options)
       case options[:format]
-      when :json then @stdout.puts(report.to_json)
-      when :github then @stdout.puts(report.to_github)
-      else @stdout.puts(report.to_text(style: style(options)))
+      when :json
+        @stdout.puts(Report::Json.new(report).render)
+      when :github
+        github = Report::Github.new(report)
+        @stdout.puts(github.render)
+        append_step_summary(github.summary)
+      else
+        @stdout.puts(
+          Report::Text.new(report, style(options)).render
+        )
       end
     end
 
+    # GitHub Actions exposes the job summary as an appendable
+    # file; outside Actions the variable is absent and this is a
+    # no-op. A broken path must not fail the audit itself.
+    def append_step_summary(markdown)
+      path = ENV["GITHUB_STEP_SUMMARY"]
+      return if path.nil? || path.empty?
+
+      File.open(path, "a") { |f| f.puts(markdown) }
+    rescue SystemCallError => e
+      complain("cannot write step summary: #{e.message}")
+    end
+
+    # Diagnostics can precede option parsing, so --plain is
+    # honored only once there is something to honor it from.
     def style(options, io: @stdout)
-      if options[:plain]
-        Report::Style.new(color: false, hyperlinks: false)
+      if options&.fetch(:plain, false)
+        plain_style
       else
         Report::Style.detect(io: io)
       end
     end
 
+    def plain_style
+      Report::Style.new(color: false, hyperlinks: false)
+    end
+
     def exit_code(report, options)
+      return 0 if options[:fail_on] == :never
+
       threshold = SEVERITIES.fetch(options[:fail_on])
+      # Test findings never load in a production boot; they are
+      # reported but do not fail the run, matching the verdict.
       failed =
         report.findings.any? do |f|
-          f.severity_rank >= threshold
+          f.severity_rank >= threshold && !f.test?
         end || report.dynamic_results.any? { |r| !r.passed }
       failed ? 1 : 0
     end
@@ -346,28 +462,41 @@ module Audition
       Target.detect(lockfile)
     end
 
-    VERDICT_CELLS = {
-      :not_ready => "not ready", :blocked => "blocked",
-      :risky => "risky", :ready => "ready", nil => "-"
-    }.freeze
-
     def sweep(target, options)
       sweeper = BundleSweep.new(
         lockfile: target.entry[:lockfile],
         static_only: options[:static_only],
         timeout: options[:timeout]
       )
-      rows = sweeper.rows(progress: sweep_progress)
+      rows = sweep_rows(sweeper, options)
+      emit_sweep(Report::Sweep.new(rows, style(options)), options)
+      return 0 if options[:fail_on] == :never
 
-      if options[:format] == :json
-        emit_sweep_json(rows)
-      else
-        emit_sweep_table(rows, options)
-      end
       threshold = SEVERITIES.fetch(options[:fail_on])
       (rows.any? { |r| row_failed?(r, threshold) }) ? 1 : 0
     end
 
+    # No unit count: every gem is a scan of its own, so even a
+    # short lockfile runs long enough to narrate.
+    def sweep_rows(sweeper, options)
+      progress = Progress.for(wanted: options[:progress],
+        format: options[:format], io: @stderr,
+        style: options[:plain] ? plain_style : nil)
+      sweeper.rows(progress: progress)
+    ensure
+      progress.finish
+    end
+
+    def emit_sweep(sweep, options)
+      case options[:format]
+      when :json then @stdout.puts(sweep.json)
+      when :github
+        @stdout.puts(sweep.annotations)
+        append_step_summary(sweep.markdown)
+      else @stdout.puts(sweep.render(**table_opts(options)))
+      end
+    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)
@@ -379,14 +508,6 @@ module Audition
       hits.positive?
     end
 
-    def sweep_progress
-      return nil unless @stderr.respond_to?(:tty?) && @stderr.tty?
-
-      lambda do |row, done, total|
-        @stderr.puts("audited #{row.name} (#{done}/#{total})")
-      end
-    end
-
     # 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
@@ -399,69 +520,29 @@ module Audition
       }
     end
 
-    def emit_sweep_table(rows, options)
-      ready = rows.count { |r| r.verdict == :ready }
-      table = rows.map do |r|
-        {
-          "gem" => r.name,
-          "version" => r.version,
-          "verdict" => VERDICT_CELLS.fetch(r.verdict),
-          "errors" => r.errors,
-          "dep errors" => r.dep_errors,
-          "warnings" => r.warnings,
-          "fixable" => r.fixable,
-          "status" => r.status
-        }
-      end
-      @stdout.puts(TableTennis.new(
-        table, zebra: true, **table_opts(options)
-      ).to_s)
-      @stdout.puts(
-        "#{ready} of #{rows.size} gems ractor-ready"
-      )
-    end
-
-    def emit_sweep_json(rows)
-      @stdout.puts(JSON.pretty_generate(
-        "audition" => VERSION,
-        "ruby" => RUBY_VERSION,
-        "bundle" => rows.map do |r|
-          {
-            "gem" => r.name,
-            "version" => r.version,
-            "verdict" => r.verdict&.to_s,
-            "errors" => r.errors,
-            "dependency_errors" => r.dep_errors,
-            "warnings" => r.warnings,
-            "infos" => r.infos,
-            "fixable" => r.fixable,
-            "status" => r.status
-          }
-        end
-      ))
-    end
-
     def print_capabilities(options)
       result = prober(options).probe(mode: :capabilities)
       caps = result.raw["capabilities"]
       unless caps
-        @stderr.puts(
-          "audition: capabilities probe failed: #{result.raw}"
-        )
+        complain("capabilities probe failed: #{result.raw}",
+          options)
         return 2
       end
 
+      s = style(options)
       rows = caps.map do |probe, info|
         {
           "works in Ractor" => probe,
-          "ok" => info["ok"] ? "yes" : "no",
-          "raises" => info["error"] || "-"
+          "ok" => s.glyph(info["ok"] ? :pass : :error),
+          "raises" => info["error"]
         }
       end
-      @stdout.puts("ruby #{RUBY_VERSION} at #{RbConfig.ruby}")
       @stdout.puts(
-        TableTennis.new(rows, **table_opts(options)).to_s
+        "#{s.glyph(:section)} #{s.bold("ruby #{RUBY_VERSION}")} " \
+        "#{s.dim("at #{RbConfig.ruby}")}"
       )
+      @stdout.puts(TableTennis.new(rows,
+        title: "Audition capabilities", **table_opts(options)).to_s)
       0
     end
   end

data/lib/audition/config.rb

@@ -10,6 +10,8 @@ module Audition
   #   exclude:
   #     - legacy/**
   #     - db/schema.rb
+  #   test_dirs:
+  #     - qa
   #   checks:
   #     disable:
   #       - at-exit
@@ -20,10 +22,10 @@ module Audition
 
     EMPTY = Ractor.make_shareable(
       {fail_on: nil, timeout: nil, exclude: [],
-       disabled_checks: []}
+       disabled_checks: [], test_dirs: nil}
     )
 
-    FAIL_ON_LEVELS = %w[error warning info].freeze
+    FAIL_ON_LEVELS = %w[error warning info never].freeze
 
     attr_reader :fail_on, :timeout, :exclude, :disabled_checks
 
@@ -42,7 +44,8 @@ module Audition
         timeout: data["timeout"],
         exclude: Array(data["exclude"]).map(&:to_s),
         disabled_checks:
-          Array(data.dig("checks", "disable")).map(&:to_s)
+          Array(data.dig("checks", "disable")).map(&:to_s),
+        test_dirs: data["test_dirs"]&.map(&:to_s)
       )
     rescue Psych::Exception => e
       raise Error, "#{path}: #{e.message}"
@@ -54,21 +57,44 @@ module Audition
           "#{path}: expected a YAML mapping, got #{data.class}"
       end
 
+      validate_test_dirs!(path, data["test_dirs"])
       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})"
+        "#{path}: fail_on must be one of error, warning, " \
+        "info, or never (got #{fail_on.inspect})"
     end
-    private_class_method :validate!
 
-    def initialize(fail_on:, timeout:, exclude:, disabled_checks:)
+    # Each name is matched against one path segment, so a nested
+    # path would silently match nothing.
+    def self.validate_test_dirs!(path, dirs)
+      return if dirs.nil? || (dirs.is_a?(Array) &&
+        dirs.none? { |dir| dir.to_s.include?("/") })
+
+      raise Error,
+        "#{path}: test_dirs must be a list of directory names " \
+        "without slashes (got #{dirs.inspect})"
+    end
+    private_class_method :validate!, :validate_test_dirs!
+
+    def initialize(fail_on:, timeout:, exclude:, disabled_checks:,
+      test_dirs: nil)
       @fail_on = fail_on
       @timeout = timeout
       @exclude = exclude
       @disabled_checks = disabled_checks
+      @test_dirs = test_dirs
+    end
+
+    # Directories whose findings are tagged as test code rather
+    # than code a production boot loads. An explicit empty list
+    # leaves only the `_test.rb`/`_spec.rb` suffixes.
+    #
+    # @return [Array<String>] Target::TEST_DIRS unless configured
+    def test_dirs
+      @test_dirs || Target::TEST_DIRS
     end
 
     # Globs follow .gitignore-style expectations: `*` stays within