audition 0.2.4 → 0.3.0

data/lib/audition/report.rb

@@ -1,79 +1,10 @@
 # frozen_string_literal: true
 
-require "json"
-require "pastel"
-require "tty/link"
-
 module Audition
-  # Aggregates static findings and dynamic results into a verdict and
-  # renders them as npm-CLI-style text or JSON.
+  # Aggregates static findings and dynamic results into a verdict
+  # and the counts the renderers work from. Rendering lives in the
+  # Report::Text, Report::Json, and Report::Github classes.
   class Report
-    # ANSI + OSC 8 styling with graceful degradation. Color and
-    # hyperlinks are decided once, at construction; pass color: false
-    # for pipes, NO_COLOR, or dumb terminals.
-    class Style
-      GLYPHS = Ractor.make_shareable(
-        {
-          error: ["✖", "x"], warning: ["⚠", "!"],
-          info: ["ℹ", "i"], pass: ["✔", "ok"],
-          section: ["◆", "*"], fix: ["✎", "+"]
-        }
-      )
-
-      PAINTS = %i[red yellow green cyan magenta dim bold].freeze
-
-      def self.detect(io: $stdout)
-        on = io.respond_to?(:tty?) && io.tty? &&
-          !ENV.key?("NO_COLOR") && ENV["TERM"] != "dumb"
-        new(color: on, hyperlinks: on && TTY::Link.link?)
-      end
-
-      def initialize(color:, hyperlinks:)
-        @pastel = Pastel.new(enabled: color)
-        @color = color
-        @hyperlinks = hyperlinks
-      end
-
-      def color?
-        @color
-      end
-
-      def glyph(kind)
-        GLYPHS.fetch(kind)[@color ? 0 : 1]
-      end
-
-      PAINTS.each do |name|
-        define_method(name) do |text| # audition:disable unsafe-calls
-          @pastel.public_send(name, text)
-        end
-      end
-
-      def severity_color(severity, text)
-        case severity
-        when :error then red(text)
-        when :warning then yellow(text)
-        else cyan(text)
-        end
-      end
-
-      # OSC 8 hyperlink wrapping "path:line" display text in a
-      # file:// URI; supporting terminals make it clickable.
-      # tty-link emits when it detects support; when hyperlinks are
-      # forced on despite no detection (tests, --force scenarios)
-      # fall back to the raw OSC 8 template, since tty-link's
-      # fallback is "text -> url" prose.
-      def link(text, absolute_path)
-        return text unless @hyperlinks
-
-        uri = "file://#{absolute_path}"
-        if TTY::Link.link?
-          TTY::Link.link_to(text, uri)
-        else
-          "\e]8;;#{uri}\e\\#{text}\e]8;;\e\\"
-        end
-      end
-    end
-
     VERDICTS = {
       not_ready: "not ractor-ready",
       blocked: "own code is ractor-ready; blocked by dependencies",
@@ -148,227 +79,10 @@ module Audition
         end
       end
     end
-
-    # @param style [Style] rendering style (auto-detected default)
-    # @return [String] the human-facing terminal report
-    def to_text(style: Style.detect)
-      Text.new(self, style).render
-    end
-
-    GITHUB_LEVELS = {
-      error: "error", warning: "warning", info: "notice"
-    }.freeze
-
-    # GitHub Actions workflow commands: findings become inline PR
-    # annotations when this runs in CI.
-    #
-    # @return [String] one `::error`/`::warning`/`::notice` line
-    #   per finding plus a verdict line
-    def to_github
-      lines = findings.map do |f|
-        level = GITHUB_LEVELS.fetch(f.severity)
-        location = f.line ? ",line=#{f.line}" : ""
-        body = workflow_escape("#{f.message}. #{f.why}")
-        file = property_escape(f.path)
-        title = property_escape("audition #{f.check}")
-        "::#{level} file=#{file}#{location}," \
-        "title=#{title}::#{body}"
-      end
-      lines << "audition verdict: #{VERDICTS.fetch(verdict)}"
-      lines.join("\n")
-    end
-
-    def to_json(*)
-      JSON.pretty_generate(
-        "audition" => VERSION,
-        "ruby" => RUBY_VERSION,
-        "target" => {"type" => target_type.to_s,
-                     "root" => target_root},
-        "verdict" => verdict.to_s,
-        "summary" => {
-          "errors" => counts[:error],
-          "dependency_errors" => counts[:dep_error],
-          "warnings" => counts[:warning],
-          "infos" => counts[:info],
-          "fixable" => counts[:fixable]
-        },
-        "findings" => findings.map do |f|
-          {
-            "check" => f.check,
-            "severity" => f.severity.to_s,
-            "message" => f.message,
-            "why" => f.why,
-            "fix" => f.fix,
-            "path" => f.path,
-            "line" => f.line,
-            "source" => f.source,
-            "fixable" => f.fixable?,
-            "dependency" => f.dependency?
-          }
-        end,
-        "dynamic" => dynamic_results.map do |r|
-          {"mode" => r.mode.to_s, "passed" => r.passed,
-           "raw" => r.raw}
-        end
-      )
-    end
-
-    private
-
-    def workflow_escape(text)
-      text.gsub("%", "%25").gsub("\r", "%0D").gsub("\n", "%0A")
-    end
-
-    # Workflow command properties additionally reserve `:` and `,`;
-    # an unescaped comma in a path would end the property early.
-    def property_escape(text)
-      workflow_escape(text).gsub(":", "%3A").gsub(",", "%2C")
-    end
-
-    public
-
-    # Text renderer, kept separate from the data so styles stay
-    # injectable.
-    class Text
-      WRAP = 74
-
-      def initialize(report, style)
-        @report = report
-        @style = style
-      end
-
-      def render
-        [header, *file_sections, *dynamic_section, summary]
-          .join("\n")
-      end
-
-      private
-
-      def header
-        s = @style
-        title = s.bold("audition #{VERSION}")
-        meta = s.dim(
-          "ruby #{RUBY_VERSION} · #{@report.target_type} at " \
-          "#{@report.target_root}"
-        )
-        "#{s.glyph(:section)} #{title} #{meta}\n"
-      end
-
-      def file_sections
-        @report.findings.group_by(&:path).map do |path, findings|
-          lines = [@style.bold("  #{path}")]
-          findings.each { |f| lines.concat(finding_lines(f)) }
-          lines.join("\n") + "\n"
-        end
-      end
-
-      def finding_lines(finding)
-        s = @style
-        glyph = s.severity_color(finding.severity,
-          s.glyph(finding.severity))
-        loc = location_label(finding)
-        fix_mark = finding.fixable? ? " #{s.cyan(s.glyph(:fix))}" : ""
-        dep_mark =
-          finding.dependency? ? " #{s.dim("(dependency)")}" : ""
-        head = "    #{glyph} #{loc}#{finding.message}" \
-               "#{fix_mark}#{dep_mark} #{s.dim(finding.check)}"
-        [head,
-          *annotation("why", finding.why),
-          *annotation("fix", finding.fix)]
-      end
-
-      def location_label(finding)
-        return "" unless finding.line
-
-        s = @style
-        text = "#{finding.path}:#{finding.line}"
-        absolute = File.expand_path(finding.path, @report.target_root)
-        "#{s.cyan(s.link(text, absolute))}  "
-      end
-
-      def annotation(label, content)
-        return [] if content.nil? || content.empty?
-
-        wrapped = wrap("#{label}: #{content}", WRAP - 6)
-        wrapped.map { |line| "      #{@style.dim(line)}" }
-      end
-
-      # Tokens longer than the width (long URLs) cannot end before
-      # whitespace, so the first alternative would drop their head;
-      # the second hard-slices them instead.
-      def wrap(text, width)
-        text.scan(/\S.{0,#{width - 1}}(?=\s|\z)|\S{#{width}}/m)
-      end
-
-      def dynamic_section
-        return [] if @report.dynamic_results.empty?
-
-        s = @style
-        lines = [s.bold("  dynamic probes")]
-        @report.dynamic_results.each do |result|
-          lines << if result.passed
-            "    #{s.green(s.glyph(:pass))} " \
-            "#{result.mode} probe passed inside a Ractor"
-          else
-            "    #{s.red(s.glyph(:error))} " \
-            "#{result.mode} probe failed " \
-            "#{s.dim("(details above)")}"
-          end
-        end
-        [lines.join("\n") + "\n"]
-      end
-
-      def pluralize(count, noun)
-        (count == 1) ? "#{count} #{noun}" : "#{count} #{noun}s"
-      end
-
-      def summary
-        s = @style
-        c = @report.counts
-        parts = []
-        if c[:error].positive?
-          parts << s.red(pluralize(c[:error], "error"))
-        end
-        if c[:dep_error].positive?
-          parts << s.magenta(
-            pluralize(c[:dep_error], "dependency error")
-          )
-        end
-        if c[:warning].positive?
-          parts << s.yellow(pluralize(c[:warning], "warning"))
-        end
-        parts << s.cyan("#{c[:info]} info") if c[:info].positive?
-        if c[:fixable].positive?
-          parts << s.cyan(
-            "#{c[:fixable]} fixable #{s.glyph(:fix)} " \
-            "(run with --fix)"
-          )
-        end
-        if @report.unsafe_fixes.positive?
-          parts << s.cyan(
-            pluralize(@report.unsafe_fixes, "edit") +
-            " with --fix-unsafe"
-          )
-        end
-        if @report.baselined.positive?
-          parts << s.dim("#{@report.baselined} baselined")
-        end
-        parts << s.green("no findings") if parts.empty?
-
-        verdict = @report.verdict
-        glyph, paint =
-          case verdict
-          when :not_ready then [:error, :red]
-          when :blocked then [:warning, :magenta]
-          when :risky then [:warning, :yellow]
-          else [:pass, :green]
-          end
-        badge = s.public_send(paint,
-          "#{s.glyph(glyph)} " +
-          VERDICTS.fetch(verdict))
-        "  summary: #{parts.join(" · ")}\n" \
-        "  verdict: #{s.bold(badge)}\n"
-      end
-    end
   end
 end
+
+require_relative "report/style"
+require_relative "report/text"
+require_relative "report/json"
+require_relative "report/github"

data/lib/audition/rewriters.rb

@@ -190,9 +190,9 @@ module Audition
     #   @x ||= expr
     #   return @x if defined?(@x); @x = expr
     #
-    # Preferred strategy is freeze-on-memoize, the pattern Rails
-    # core applies to its own code: the memoization stays exactly
-    # as written and only the memoized value becomes shareable
+    # Preferred strategy is freeze-on-memoize: the memoization
+    # stays exactly as written and only the memoized value
+    # becomes shareable
     # (`.freeze` appended; Ractor.make_shareable for containers).
     # Non-main Ractors may then read the ivar once it has been
     # computed; the first write must still happen on the main
@@ -325,7 +325,7 @@ module Audition
       end
 
       # Config setters (`def self.backend=(value); @backend =
-      # value; end`) get the Rails try_make_shareable recipe in
+      # value; end`) get a try-make-shareable recipe in
       # plain Ruby: shareable values are deeply frozen so reads
       # from any Ractor become legal, unshareable values keep
       # today's behavior through the rescue. Only bare local reads

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

@@ -30,21 +30,23 @@ module Audition
                "literals only; a method call returns a fresh " \
                "unfrozen object, so a non-main Ractor reading " \
                "this constant raises Ractor::IsolationError. " \
-               "Rails hit this with `.tr` and `Regexp.new` " \
-               "during its ractorization.",
-          fix: "Append `.freeze` to the call; a frozen String " \
-               "or Regexp is deeply shareable."
+               "Typical shapes: `.tr`, `Regexp.new`, and " \
+               "`Object.new` sentinels.",
+          fix: "Append `.freeze` to the call; a frozen String, " \
+               "Regexp, or bare Object is deeply shareable. " \
+               "BasicObject has no #freeze: use " \
+               "Object.new.freeze for such a sentinel."
 
         explain :mutable_container,
           severity: :error,
           message: "constant %{name} holds a mutable %{type} " \
                    "literal",
           why: CONSTANT_WHY,
-          fix: "Make it deeply shareable: " \
-               "`# shareable_constant_value: literal`, or " \
-               "wrap in Ractor.make_shareable(...). A bare " \
-               "`.freeze` is not enough when elements are " \
-               "themselves mutable."
+          fix: "Append `.freeze` when every element is itself " \
+               "shareable; otherwise make it deeply shareable with " \
+               "`# shareable_constant_value: literal` or " \
+               "Ractor.make_shareable(...), since a bare " \
+               "`.freeze` is shallow."
 
         explain :shallow_freeze,
           severity: :error,
@@ -62,17 +64,19 @@ module Audition
         explain :sync_primitive,
           severity: :error,
           message: "constant %{name} holds a %{klass}; sync " \
-                   "primitives are deliberately unshareable",
+                   "primitives and concurrent collections are " \
+                   "deliberately unshareable",
           why: "Mutex/Queue/ConditionVariable coordinate " \
                "threads inside one Ractor and can never be " \
                "shared across Ractors; any non-main Ractor " \
                "touching this constant raises " \
-               "Ractor::IsolationError.",
+               "Ractor::IsolationError. A concurrent-ruby Map " \
+               "defines no #freeze at all, so make_shareable " \
+               "raises NoMethodError on it.",
           fix: "Use Ractor::Port for cross-Ractor " \
                "coordination; keep a per-Ractor primitive " \
                "via Ractor.store_if_absent when the state it " \
-               "guards is per-Ractor too (Rails moved its " \
-               "template digest mutex this way); or use " \
+               "guards is per-Ractor too; or use " \
                "Ractor-safe structures (ractor_safe, ratomic " \
                "gems)."
 
@@ -94,8 +98,7 @@ module Audition
                "Hash, and freezing the Hash does not make " \
                "the block shareable; a non-main Ractor " \
                "reading this constant raises " \
-               "Ractor::IsolationError. Rails removed this " \
-               "pattern twice during its ractorization.",
+               "Ractor::IsolationError.",
           fix: "Use a plain frozen Hash with explicit keys, " \
                "or drop the default proc and fetch with a " \
                "literal default: hash.fetch(key, [])."
@@ -111,8 +114,8 @@ module Audition
           fix: "Build the complete value at load time and " \
                "freeze it (each_with_object then .freeze), " \
                "or move the registry behind a writer that " \
-               "rebuilds and refreezes on each change, the " \
-               "copy-on-write style Rails registries use. A " \
+               "rebuilds and refreezes on each change " \
+               "(copy-on-write). A " \
                "registry that plugins extend during boot is " \
                "frozen in the last boot hook (after_initialize) " \
                "rather than at definition, and writes after the " \
@@ -144,21 +147,30 @@ module Audition
 
           # A constant this file itself mutates in place is a
           # deliberate accumulator; freezing it would raise at
-          # the mutation site (sinatra's PARAMS_CONFIG). The
+          # the mutation site (sinatra's PARAMS_CONFIG). One it
+          # gives singleton methods raises the same way. The
           # finding stays, the autofix goes.
-          fix_ok = !mutated?(name)
-          case classifier.classify(value)
+          fix_ok = !mutated?(name) && !customized?(name)
+          kind = classifier.classify(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.
+          if kind == :mutable_container && frozen_later?(name)
+            kind = classifier.frozen_kind(value)
+            fix_ok = false
+          end
+          case kind
           when :mutable_string
             flag(node, :mutable_string, name: name,
               autofix: fix_ok ? append_freeze(value) : nil)
           when :mutable_call
             flag(node, :mutable_call, name: name,
               type: call_type(value), method: call_display(value),
-              autofix: fix_ok ? append_freeze(value) : nil)
+              autofix: fix_ok ? freeze_call(value) : nil)
           when :mutable_container
             flag(node, :mutable_container, name: name,
               type: container_type(value),
-              autofix: fix_ok ? wrap_make_shareable(value) : nil)
+              autofix: fix_ok ? freeze_container(value) : nil)
           when :shallow_freeze
             flag(node, :shallow_freeze, name: name,
               autofix:
@@ -186,10 +198,18 @@ module Audition
           end
         end
 
-        def mutated?(name)
+        def mutated?(name) = named_in?(file.mutated_constants, name)
+
+        def customized?(name)
+          named_in?(file.customized_constants, name)
+        end
+
+        def frozen_later?(name) = named_in?(file.frozen_constants, name)
+
+        def named_in?(names, name)
           bare = name.split("::").last
-          file.mutated_constants.any? do |mutated|
-            mutated == name || mutated.split("::").last == bare
+          names.any? do |other|
+            other == name || other.split("::").last == bare
           end
         end
 
@@ -262,6 +282,8 @@ module Audition
           when Prism::HashNode, Prism::KeywordHashNode then "Hash"
           when Prism::ArrayNode then "Array"
           when Prism::CallNode
+            return "Set" if value.name == :to_set
+
             classifier.const_name(value.receiver) || "container"
           else
             "container"
@@ -277,8 +299,11 @@ module Audition
         # Ternaries classify as strings when both branches are;
         # `.freeze` binds tighter than `?:`, so they get parens.
         def call_type(call)
-          owner = classifier.const_name(call.receiver)
-          (owner == "Regexp") ? "Regexp" : "String"
+          case classifier.const_name(call.receiver)
+          when "Regexp" then "Regexp"
+          when "Object", "BasicObject" then "Object"
+          else "String"
+          end
         end
 
         def call_display(call)
@@ -294,8 +319,11 @@ module Audition
         # the bare suffix.
         def bare_freezable?(value)
           case value
-          when Prism::StringNode, Prism::InterpolatedStringNode
+          when Prism::StringNode, Prism::InterpolatedStringNode,
+               Prism::HashNode
             true
+          when Prism::ArrayNode
+            !value.opening_loc.nil?
           when Prism::CallNode
             !value.opening_loc.nil? ||
               (!value.receiver.nil? && value.arguments.nil?)
@@ -305,6 +333,16 @@ module Audition
         end
 
         def append_freeze(value)
+          # `X = :a, :b` has no brackets; it gains them so the
+          # suffix freezes the whole array.
+          if value.is_a?(Prism::ArrayNode) && value.opening_loc.nil?
+            return Autofix.new(
+              start_offset: value.location.start_offset,
+              end_offset: value.location.end_offset,
+              replacement: "[#{value.location.slice}].freeze"
+            )
+          end
+
           if bare_freezable?(value)
             offset = value.location.end_offset
             Autofix.new(
@@ -322,6 +360,31 @@ module Audition
           end
         end
 
+        # A frozen bare Object is shareable; BasicObject has no
+        # #freeze, so its sentinel becomes a frozen Object.
+        def freeze_call(value)
+          return append_freeze(value) unless
+            classifier.const_name(value.receiver) == "BasicObject"
+
+          Autofix.new(
+            start_offset: value.location.start_offset,
+            end_offset: value.location.end_offset,
+            replacement: "Object.new.freeze",
+            safety: :unsafe
+          )
+        end
+
+        # Plain `.freeze` where every element is provably
+        # shareable, the plain-Ruby shape; the deep wrap only
+        # where a shallow freeze would not be enough.
+        def freeze_container(value)
+          if classifier.frozen_kind(value) == :shareable
+            append_freeze(value)
+          else
+            wrap_make_shareable(value)
+          end
+        end
+
         # `X = :a, :b` is an array literal without brackets; the
         # slice must gain them or the wrap becomes a multi-arg
         # call (mail's ATTRIBUTES).

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

@@ -22,7 +22,10 @@ module Audition
                "load-time side effects run at an arbitrary " \
                "point.",
           fix: "Require eagerly at boot, before Ractors are " \
-               "spawned."
+               "spawned. For an optional dependency, the " \
+               "class-level macro that enables the feature is " \
+               "a boot-time scope; the request-time method is " \
+               "not."
 
         explain :autoload,
           severity: :warning,

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

@@ -27,10 +27,12 @@ module Audition
                "variables; reads and writes alike raise " \
                "Ractor::IsolationError from a non-main Ractor, " \
                "whatever the value holds.",
-          fix: "Rails itself migrated these to class_attribute " \
-               "(a class-level ivar whose frozen value any " \
-               "Ractor may read) or to a module ivar behind a " \
-               "reader; give it a frozen default and rebuild " \
+          fix: "Move the state to class_attribute (a " \
+               "class-level ivar whose frozen value any Ractor " \
+               "may read) or, for plain settings, to " \
+               "singleton_class.attr_accessor plus " \
+               "delegate(..., to: TheModule) for the instance " \
+               "readers; give it a frozen default and rebuild " \
                "and refreeze on write, at boot on the main " \
                "Ractor."
 
@@ -110,8 +112,7 @@ module Audition
                "unless the block was made shareable first.",
           fix: "Pass a shareable lambda instead of a block: " \
                "define_method(:x, Ractor.shareable_lambda " \
-               "{ ... }), as Rails did for its date selectors " \
-               "and url helpers. Captured locals must be " \
+               "{ ... }). Captured locals must be " \
                "shareable (strings become symbols) and assigned " \
                "before the lambda is created, and super is " \
                "unavailable. When the captures are literals, " \

data/lib/audition/static/graph_audit.rb

@@ -34,7 +34,7 @@ module Audition
         "per-subclass values compute in the inherited hook " \
         "(guard on subclass.name for anonymous classes). For " \
         "collections, rebuild and refreeze on write, " \
-        "Rails-style copy-on-write: self.list = " \
+        "copy-on-write: self.list = " \
         "(list + [item]).freeze; never mutate in place. As a " \
         "last resort use Ractor.store_if_absent for " \
         "per-Ractor state, or read the ivar first and proxy " \
@@ -43,9 +43,7 @@ module Audition
         "Every write memoizes a shareable (frozen) value, so " \
         "non-main Ractors can read it once it has been " \
         "computed; only the first write must happen on the " \
-        "main Ractor, or it raises Ractor::IsolationError. " \
-        "This is the pattern Rails core uses for its own " \
-        "memoized class state."
+        "main Ractor, or it raises Ractor::IsolationError."
       FROZEN_MEMO_FIX =
         "Warm the cache at boot, before spawning Ractors: call " \
         "the memoizing method from an initializer, an on_load " \
@@ -188,7 +186,7 @@ module Audition
         )
       end
 
-      # Frozen memoization, the shape Rails core ships: every
+      # Frozen memoization: every
       # write to the ivar is a memo site (`@x ||=` or a defined?
       # guard) whose value is provably shareable, either a frozen
       # literal, an explicit `.freeze` or make_shareable call.