audition 0.1.0 → 0.2.1

data/lib/audition/static/graph_audit.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "rubydex"
+require_relative "../rewriters"
 
 module Audition
   module Static
@@ -26,9 +27,39 @@ module Audition
         "it while it holds a non-shareable value (verified on " \
         "Ruby 4.0)."
       STATE_FIX =
-        "Precompute and freeze the value at load time, use " \
-        "Ractor.store_if_absent for lazy initialization, or keep " \
-        "per-Ractor state in Ractor.current[:key]."
+        "Precompute and freeze the value at load time (for " \
+        "per-subclass values, in the inherited hook). For " \
+        "collections, rebuild and refreeze on write, " \
+        "Rails-style copy-on-write: self.list = " \
+        "(list + [item]).freeze; never mutate in place. As a " \
+        "last resort use Ractor.store_if_absent for lazy " \
+        "initialization or per-Ractor state in " \
+        "Ractor.current[:key]."
+      FROZEN_MEMO_WHY =
+        "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."
+      FROZEN_MEMO_FIX =
+        "Warm the cache at boot, before spawning Ractors: call " \
+        "the memoizing method from an initializer or on_load " \
+        "hook. If the value genuinely must be computed at " \
+        "runtime, proxy the write to the main Ractor or use " \
+        "Ractor.store_if_absent."
+      BEST_EFFORT_WHY =
+        "Writes wrap their value in Ractor.make_shareable with " \
+        "a rescue fallback: shareable values are deeply frozen " \
+        "and readable from any Ractor, while unshareable values " \
+        "keep their old (Ractor-hostile) behavior. Whether this " \
+        "state is actually safe depends on what the application " \
+        "assigns; the dynamic probe reports ground truth."
+      BEST_EFFORT_FIX =
+        "Assign only shareable values (strings, symbols, frozen " \
+        "containers) before spawning Ractors. Configuration " \
+        "that cannot be shareable needs per-Ractor state or a " \
+        "main-Ractor proxy instead."
 
       # @param sources [Hash{String => String}] path => source
       # @return [Array<Finding>]
@@ -38,6 +69,7 @@ module Audition
           graph.index_source(path, code, "ruby")
         end
         @sources = sources
+        @frozen_memos = frozen_memo_map(sources)
         audit(graph)
       end
 
@@ -91,15 +123,39 @@ module Audition
 
         variable = decl.name.split("#").last
         owner = display_owner(decl.owner)
+        verdict = @frozen_memos["#{owner}/#{variable}"]
         each_local_definition(decl).map do |defn|
-          finding_at(
-            defn,
-            check: "class-level-state",
-            message: "class-level instance variable #{variable} " \
-                     "on #{owner}",
-            why: STATE_WHY,
-            fix: STATE_FIX
-          )
+          case verdict
+          when :frozen
+            finding_at(
+              defn,
+              check: "class-level-state",
+              severity: :info,
+              message: "frozen memoization #{variable} on " \
+                       "#{owner}; warm it on the main Ractor",
+              why: FROZEN_MEMO_WHY,
+              fix: FROZEN_MEMO_FIX
+            )
+          when :best_effort
+            finding_at(
+              defn,
+              check: "class-level-state",
+              severity: :warning,
+              message: "best-effort frozen state #{variable} " \
+                       "on #{owner}",
+              why: BEST_EFFORT_WHY,
+              fix: BEST_EFFORT_FIX
+            )
+          else
+            finding_at(
+              defn,
+              check: "class-level-state",
+              message: "class-level instance variable " \
+                       "#{variable} on #{owner}",
+              why: STATE_WHY,
+              fix: STATE_FIX
+            )
+          end
         end
       end
 
@@ -109,12 +165,13 @@ module Audition
         end
       end
 
-      def finding_at(defn, check:, message:, why:, fix:)
+      def finding_at(defn, check:, message:, why:, fix:,
+        severity: :error)
         path = path_from_uri(defn.location.uri)
         line = defn.location.start_line + 1
         Finding.new(
           check: check,
-          severity: :error,
+          severity: severity,
           message: message,
           why: why,
           fix: fix,
@@ -124,9 +181,180 @@ module Audition
         )
       end
 
+      # Frozen memoization, the shape Rails core ships: 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.
+      # Such state is read-safe from any Ractor once warmed, so
+      # the finding downgrades to an info note. Any stray write
+      # or unproven value keeps the error. Keys are
+      # "Owner::Path/@name"; a dirty verdict in any file wins.
+      def frozen_memo_map(sources)
+        map = {}
+        sources.each do |path, code|
+          file = SourceFile.new(source: code, path: path)
+          next unless file.valid_syntax?
+
+          collector = Rewriters::Memoization::SingletonIvars.new
+          collector.visit(file.root)
+          classifier = LiteralClassifier.new(
+            frozen_string_literal: file.frozen_string_literal?
+          )
+          collector.groups.each do |(namespace, name), ops|
+            key = "#{namespace}/#{name}"
+            verdict = group_verdict(ops, classifier)
+            map[key] = weaker_verdict(map[key], verdict)
+          end
+          mark_singleton_reopenings(file, map)
+        end
+        map
+      end
+
+      # `class << Foo` bodies write ivars on Foo's singleton
+      # class outside the collector's `class << self` tracking;
+      # any such write taints the group so a reopening in one
+      # file can never be shadowed by a clean memo in another.
+      def mark_singleton_reopenings(file, map)
+        queue = [file.root]
+        until queue.empty?
+          node = queue.shift
+          queue.concat(node.child_nodes.compact)
+          next unless node.is_a?(Prism::SingletonClassNode)
+
+          owner =
+            case node.expression
+            when Prism::ConstantReadNode
+              node.expression.name.to_s
+            when Prism::ConstantPathNode
+              node.expression.location.slice
+            end
+          next unless owner
+
+          ivar_names_in(node).each do |ivar|
+            map["#{owner}/#{ivar}"] = :dirty
+          end
+        end
+      end
+
+      IVAR_NODES = [
+        Prism::InstanceVariableReadNode,
+        Prism::InstanceVariableWriteNode,
+        Prism::InstanceVariableOrWriteNode,
+        Prism::InstanceVariableOperatorWriteNode,
+        Prism::InstanceVariableAndWriteNode,
+        Prism::InstanceVariableTargetNode
+      ].freeze
+
+      def ivar_names_in(node)
+        names = []
+        queue = [node]
+        until queue.empty?
+          current = queue.shift
+          queue.concat(current.child_nodes.compact)
+          if IVAR_NODES.any? { |type| current.is_a?(type) }
+            names << current.name.to_s
+          end
+        end
+        names.uniq
+      end
+
+      # Cross-file merge keeps the weakest promise: any dirty file
+      # taints the group, and best-effort beats fully frozen.
+      VERDICT_RANK = {dirty: 0, best_effort: 1, frozen: 2}.freeze
+
+      def weaker_verdict(existing, verdict)
+        return verdict unless existing
+
+        [existing, verdict].min_by { |v| VERDICT_RANK[v] }
+      end
+
+      def group_verdict(ops, classifier)
+        return :dirty if ops.any? { |op| op[:body] }
+        return :dirty if ops.any? { |op| op[:kind] == :other }
+
+        memos = Rewriters::Memoization.memo_sites(ops)
+        if memos.any?
+          return group_frozen?(ops, classifier) ? :frozen : :dirty
+        end
+
+        writes = ops.select { |op| op[:kind] == :write }
+        return :dirty if writes.empty?
+
+        all_safe = writes.all? do |w|
+          value = w[:node].value
+          best_effort_value?(value) ||
+            Rewriters::Memoization.frozen_call?(value) ||
+            classifier.classify(value) == :shareable
+        end
+        wrapped = writes.any? do |w|
+          best_effort_value?(w[:node].value)
+        end
+        (all_safe && wrapped) ? :best_effort : :dirty
+      end
+
+      # Matches the emitted setter recipe:
+      #   (Ractor.make_shareable(value) rescue value)
+      def best_effort_value?(node)
+        inner = node
+        if inner.is_a?(Prism::ParenthesesNode)
+          body = inner.body&.body
+          return false unless body && body.size == 1
+
+          inner = body[0]
+        end
+        return false unless inner.is_a?(Prism::RescueModifierNode)
+
+        call = inner.expression
+        call.is_a?(Prism::CallNode) &&
+          call.name == :make_shareable &&
+          call.receiver.is_a?(Prism::ConstantReadNode) &&
+          call.receiver.name == :Ractor
+      end
+
+      def group_frozen?(ops, classifier)
+        return false if ops.any? { |op| op[:body] }
+        return false if ops.any? { |op| op[:kind] == :other }
+
+        memos = Rewriters::Memoization.memo_sites(ops)
+        return false if memos.empty?
+        return false if
+          Rewriters::Memoization.orphan_guards?(ops, memos)
+
+        memo_ops = memos.map { |memo| memo[:op] }
+        writes = ops.select { |op| op[:kind] == :write }
+        return false unless (writes - memo_ops).empty?
+
+        memos.all? do |memo|
+          value = memo[:op][:node].value
+          frozen_memo_value?(value, classifier)
+        end
+      end
+
+      # A bare `.freeze` on a container literal is shallow: the
+      # elements stay mutable and the cross-Ractor read still
+      # raises, so it must not count as frozen. A `.freeze` on a
+      # call result is accepted as the memo recipe (the dynamic
+      # probe verifies the value); provably shareable values pass.
+      def frozen_memo_value?(value, classifier)
+        return true if classifier.classify(value) == :shareable
+        return false unless Rewriters::Memoization.frozen_call?(value)
+
+        case value.receiver
+        when Prism::ArrayNode, Prism::HashNode,
+             Prism::KeywordHashNode
+          false
+        else
+          true
+        end
+      end
+
       # "Payments::<Payments>" reads as noise; show "Payments".
+      # Nested singleton owners produce nested angle brackets, so
+      # the strip repeats until the tail is gone.
       def display_owner(owner)
-        (owner&.name || "?").sub(/::<[^>]+>\z/, "")
+        name = owner&.name || "?"
+        name = name.sub(/::<.*>\z/m, "") while name.match?(/::<.*>\z/m)
+        name
       end
 
       def path_from_uri(uri)

data/lib/audition/static/literal_classifier.rb

@@ -7,10 +7,12 @@ module Audition
     # Classifies a Prism expression node by Ractor shareability:
     #   :shareable         proven deeply shareable
     #   :mutable_string    unfrozen String literal
-    #   :mutable_container Array/Hash literal
+    #   :mutable_container Array/Hash literal or constructor
     #   :shallow_freeze    frozen container with mutable elements
     #   :sync_primitive    Mutex/Queue/... constructor
     #   :proc              lambda or proc
+    #   :default_proc      Hash.new with a block; the block
+    #                      survives .freeze and stays unshareable
     #   :unknown           cannot tell statically
     class LiteralClassifier
       SYNC_PRIMITIVES = %w[
@@ -43,7 +45,7 @@ module Audition
           classify_interpolated_string(node)
         when Prism::ArrayNode, Prism::HashNode,
              Prism::KeywordHashNode
-          :mutable_container
+          container_kind(node)
         when Prism::RangeNode
           ends = [node.left, node.right].compact
           if ends.all? { |n| classify(n) == :shareable }
@@ -55,15 +57,21 @@ module Audition
           :proc
         when Prism::CallNode
           classify_call(node)
+        when Prism::IfNode
+          ternary_kind(node)
         else
           :unknown
         end
       end
 
+      # `::Mutex` and `Mutex` are the same constant for matching
+      # purposes; the leading colons are stripped.
       def const_name(node)
         case node
-        when Prism::ConstantReadNode then node.name.to_s
-        when Prism::ConstantPathNode then node.location.slice
+        when Prism::ConstantReadNode
+          node.name.to_s
+        when Prism::ConstantPathNode
+          node.location.slice.delete_prefix("::")
         end
       end
 
@@ -92,6 +100,14 @@ module Audition
           name = const_name(receiver)
           return :sync_primitive if SYNC_PRIMITIVES.include?(name)
           return :shareable if SHAREABLE_FACTORIES.include?(name)
+          return :proc if name == "Proc" && node.block
+          # Hash.new retains its block as the default proc;
+          # Array.new only uses its block to build elements.
+          return :default_proc if name == "Hash" && node.block
+
+          if %w[Hash Array].include?(name)
+            return :mutable_container
+          end
 
           :unknown
         when :define
@@ -113,26 +129,74 @@ module Audition
           :shareable
         when Prism::ArrayNode, Prism::HashNode
           deep_classify(receiver.elements)
+        when Prism::CallNode
+          # A default proc survives freezing the Hash.
+          (classify(receiver) == :default_proc) ? :default_proc : :unknown
+        else
+          :unknown
+        end
+      end
+
+      # A container holding a sync primitive can never become
+      # shareable; Ractor.make_shareable raises on it (multi_json
+      # keeps a frozen Hash of Mutexes). The classification
+      # propagates so no freeze or wrap is ever suggested.
+      def container_kind(node)
+        sync = node.elements.any? do |element|
+          element_children(element).any? do |child|
+            classify(child) == :sync_primitive
+          end
+        end
+        sync ? :sync_primitive : :mutable_container
+      end
+
+      def element_children(element)
+        case element
+        when Prism::AssocNode then [element.key, element.value]
+        else [element]
+        end
+      end
+
+      # A ternary of provable branches classifies as the worst
+      # branch: two string literals make a string, so a plain
+      # `.freeze` stays available for `cond ? ";" : ":"`.
+      def ternary_kind(node)
+        return :unknown unless node.subsequent
+          .is_a?(Prism::ElseNode)
+
+        branches = [
+          single_statement(node.statements),
+          single_statement(node.subsequent.statements)
+        ]
+        return :unknown unless branches.all?
+
+        kinds = branches.map { |branch| classify(branch) }
+        return :shareable if kinds.all?(:shareable)
+
+        if kinds.all? { |k| %i[shareable mutable_string].include?(k) }
+          :mutable_string
         else
           :unknown
         end
       end
 
+      def single_statement(statements)
+        body = statements&.body
+        body && body.size == 1 && body[0]
+      end
+
       # Fold element classifications: everything provably shareable
       # gives :shareable; anything provably mutable gives
-      # :shallow_freeze; anything unknowable gives :unknown (stay
-      # silent rather than guess).
+      # :shallow_freeze; a sync primitive poisons the whole
+      # container; anything unknowable gives :unknown (stay silent
+      # rather than guess).
       def deep_classify(elements)
         verdict = :shareable
         elements.each do |element|
-          children =
-            case element
-            when Prism::AssocNode then [element.key, element.value]
-            else [element]
-            end
-          children.each do |child|
+          element_children(element).each do |child|
             case classify(child)
             when :shareable then nil
+            when :sync_primitive then return :sync_primitive
             when :unknown then return :unknown
             else verdict = :shallow_freeze
             end

data/lib/audition/static/source_file.rb

@@ -25,11 +25,22 @@ module Audition
 
       def root = parse_result.value
 
+      # Ruby matches magic-comment keys and values
+      # case-insensitively and ignores magic comments that appear
+      # after the first statement (verified on 4.0); Prism reports
+      # them all, so both rules are applied here.
       def magic_comment(key)
+        limit = first_statement_offset
         comment = parse_result.magic_comments.find do |mc|
-          mc.key_loc.slice == key
+          mc.key_loc.slice.downcase == key &&
+            mc.key_loc.start_offset < limit
         end
-        comment&.value_loc&.slice
+        comment&.value_loc&.slice&.downcase
+      end
+
+      def first_statement_offset
+        first = root.statements.body.first
+        first ? first.location.start_offset : source.bytesize
       end
 
       # String literals in this file are frozen (and therefore
@@ -48,7 +59,9 @@ module Audition
       end
 
       def line_at(number)
-        @lines ||= source.lines
+        @lines ||= source.lines.map do |line|
+          line.dup.force_encoding(Encoding::UTF_8).scrub
+        end
         @lines[number - 1]&.strip
       end
 
@@ -72,25 +85,93 @@ module Audition
             %i[require require_relative].include?(s.name)
         end
         if last_require
-          newline = source.index("\n", last_require.location.end_offset)
-          offset = newline ? newline + 1 : source.bytesize
+          newline = raw.index("\n", last_require.location.end_offset)
+          offset = newline ? newline + 1 : raw.bytesize
           {offset: offset, after_require: true}
         else
           {offset: leading_comments_end, after_require: false}
         end
       end
 
+      # Prism reports byte offsets; index math against the source
+      # must run on a binary copy or multibyte content shifts
+      # every computed position.
+      def raw
+        @raw ||= source.dup.force_encoding(Encoding::BINARY)
+      end
+
+      # Method names that read as in-place data mutation when
+      # sent to a constant. Shared by the mutable-constants check
+      # and the fixers: a constant this file mutates is a
+      # deliberate accumulator (sinatra's PARAMS_CONFIG) and must
+      # never be frozen by magic comment or wrap.
+      CONST_MUTATORS = %i[
+        []= << push unshift concat merge! replace
+      ].freeze
+
+      # Index writes are their own node types, not calls:
+      # `COUNTS[k] += 1` is IndexOperatorWriteNode and
+      # `CACHE[k] ||= v` is IndexOrWriteNode; missing them let a
+      # `.freeze` autofix produce FrozenError at runtime.
+      INDEX_WRITES = [
+        Prism::IndexOperatorWriteNode,
+        Prism::IndexOrWriteNode,
+        Prism::IndexAndWriteNode,
+        Prism::IndexTargetNode
+      ].freeze
+
+      # @return [Array<String>] names of constants that receive a
+      #   mutator call somewhere in this file
+      def mutated_constants
+        @mutated_constants ||= begin
+          names = []
+          queue = [root]
+          until queue.empty?
+            node = queue.shift
+            queue.concat(node.child_nodes.compact)
+            receiver =
+              if node.is_a?(Prism::CallNode) &&
+                  CONST_MUTATORS.include?(node.name)
+                node.receiver
+              elsif INDEX_WRITES.any? { |type| node.is_a?(type) }
+                node.receiver
+              end
+
+            case receiver
+            when Prism::ConstantReadNode
+              names << receiver.name.to_s
+            when Prism::ConstantPathNode
+              names << receiver.location.slice
+            end
+          end
+          names.uniq
+        end
+      end
+
+      # Keys Ruby actually honors. Prism reports every comment
+      # shaped like `# key: value`, which sweeps up documentation
+      # (`# I18n.t: 'date.formats.short'`); inserting after those
+      # would land a magic comment mid-file.
+      MAGIC_KEYS = %w[
+        encoding coding frozen_string_literal
+        shareable_constant_value warn_indent
+      ].freeze
+
       # Where a new magic comment can go: after the shebang and any
       # existing magic comments, before code.
       def magic_insertion_offset
         offset = 0
-        if source.start_with?("#!")
-          newline = source.index("\n")
-          offset = newline ? newline + 1 : source.bytesize
+        if raw.start_with?("#!")
+          newline = raw.index("\n")
+          offset = newline ? newline + 1 : raw.bytesize
         end
-        after_magic = parse_result.magic_comments.map do |mc|
-          newline = source.index("\n", mc.value_loc.end_offset)
-          newline ? newline + 1 : source.bytesize
+        limit = first_statement_offset
+        after_magic = parse_result.magic_comments.filter_map do |mc|
+          next unless MAGIC_KEYS.include?(mc.key_loc.slice.downcase)
+          next unless mc.key_loc.start_offset < limit
+
+          newline = raw.index("\n", mc.value_loc.end_offset)
+          newline ? newline + 1 : raw.bytesize
         end.max
         [offset, after_magic || 0].max
       end

data/lib/audition/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Audition
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: audition
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Yaroslav Markin
@@ -57,14 +57,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: tty-link
   requirement: !ruby/object:Gem::Requirement