audition 0.2.0 → 0.2.2

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

@@ -39,12 +39,21 @@ module Audition
           # @return [String] kebab-case check identifier
           def check_name(value = nil)
             @check_name = -value if value # audition:disable class-level-state
-            @check_name || name.split("::").last
-              .gsub(/([a-z0-9])([A-Z])/, '\1-\2').downcase
+            @check_name || (name || "anonymous-check").split("::")
+              .last.gsub(/([a-z0-9])([A-Z])/, '\1-\2').downcase
           end
 
+          # Catalogs merge down the ancestry so a subclass of a
+          # concrete check inherits its handlers and messages
+          # instead of raising KeyError at visit time.
           def explanations
-            @explanations || EMPTY_CATALOG
+            own = @explanations || EMPTY_CATALOG
+            parent = superclass
+            if parent.respond_to?(:explanations)
+              parent.explanations.merge(own)
+            else
+              own
+            end
           end
 
           # Registers a message catalog entry. Strings may contain
@@ -67,7 +76,13 @@ module Audition
           end
 
           def handlers
-            @handlers || EMPTY_CATALOG
+            own = @handlers || EMPTY_CATALOG
+            parent = superclass
+            if parent.respond_to?(:handlers)
+              parent.handlers.merge(own)
+            else
+              own
+            end
           end
 
           # Methods born from define_method carry their block as a

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

@@ -11,8 +11,9 @@ module Audition
       class GlobalVariables < Base
         SAFE_READS = %w[
           $stdin $stdout $stderr $! $? $~ $_ $DEBUG $VERBOSE $/ $$
+          $-v $-d
         ].freeze
-        SAFE_WRITES = %w[$DEBUG $VERBOSE].freeze
+        SAFE_WRITES = %w[$DEBUG $VERBOSE $-v $-d].freeze
         LOAD_PATH_GLOBALS = %w[$LOAD_PATH $: $LOADED_FEATURES $"].freeze
 
         explain :access,

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

@@ -104,7 +104,12 @@ module Audition
         end
 
         on :call_node do |node|
-          flag_constant_mutation(node)
+          flag_constant_mutation(node, node.receiver, node.name.to_s)
+        end
+
+        on :index_operator_write_node, :index_or_write_node,
+          :index_and_write_node, :index_target_node do |node|
+          flag_constant_mutation(node, node.receiver, "[]=")
         end
 
         on :constant_path_write_node,
@@ -117,50 +122,108 @@ module Audition
         def examine(name, node, value)
           return if file.shareable_constants?
 
+          # 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
+          # finding stays, the autofix goes.
+          fix_ok = !mutated?(name)
           case classifier.classify(value)
           when :mutable_string
             flag(node, :mutable_string, name: name,
-              autofix: append_freeze(value))
+              autofix: fix_ok ? append_freeze(value) : nil)
           when :mutable_container
             flag(node, :mutable_container, name: name,
               type: container_type(value),
-              autofix: wrap_make_shareable(value))
+              autofix: fix_ok ? wrap_make_shareable(value) : nil)
           when :shallow_freeze
             flag(node, :shallow_freeze, name: name,
-              autofix: replace_with_make_shareable(value))
+              autofix:
+                fix_ok ? replace_with_make_shareable(value) : nil)
           when :sync_primitive
             klass = value.is_a?(Prism::CallNode) &&
               classifier.const_name(value.receiver)
             flag(node, :sync_primitive, name: name,
               klass: klass || "sync primitive")
           when :proc
+            # make_shareable on a proc raises when the proc
+            # captures locals or its self is unshareable (any
+            # top-level lambda); only capture-free lambdas inside
+            # a class or module body get the wrap.
+            body = proc_body(value)
+            wrappable = fix_ok && namespaced?(node) &&
+              (body.nil? ||
+                RactorIsolation::CaptureScanner
+                  .scan(body).empty?)
             flag(node, :proc_constant, name: name,
-              autofix: wrap_make_shareable(value))
+              autofix: wrappable ? wrap_make_shareable(value) : nil)
           when :default_proc
             flag(node, :hash_default_proc, name: name)
           end
         end
 
+        def mutated?(name)
+          bare = name.split("::").last
+          file.mutated_constants.any? do |mutated|
+            mutated == name || mutated.split("::").last == bare
+          end
+        end
+
+        # A proc value is a LambdaNode (`->`) or a CallNode
+        # (`proc { }`, `lambda { }`, `Proc.new { }`); the body
+        # lives in different places (rspec-expectations crashed
+        # the CallNode path).
+        def proc_body(value)
+          case value
+          when Prism::LambdaNode then value.body
+          when Prism::CallNode then value.block&.body
+          end
+        end
+
+        def namespaced?(node)
+          offset = node.location.start_offset
+          module_ranges.any? { |range| range.cover?(offset) }
+        end
+
+        def module_ranges
+          @module_ranges ||= begin
+            ranges = []
+            queue = [file.root]
+            until queue.empty?
+              current = queue.shift
+              queue.concat(current.child_nodes.compact)
+              case current
+              when Prism::ClassNode, Prism::ModuleNode,
+                   Prism::SingletonClassNode
+                location = current.location
+                ranges <<
+                  (location.start_offset..location.end_offset)
+              end
+            end
+            ranges
+          end
+        end
+
         # Mutators that read as data mutation, not as class-level
         # method names (delete/update/store would collide with
         # Active Record class methods). Screaming-case receivers
         # only: `RENDERERS << x` is a registry mutation, while
         # `User << x` is a class method call.
         MUTATORS = Ractor.make_shareable(
-          %i[[]= << push unshift concat merge! replace]
+          SourceFile::CONST_MUTATORS
         )
 
-        def flag_constant_mutation(node)
-          return unless MUTATORS.include?(node.name)
+        def flag_constant_mutation(node, receiver, method)
+          if node.is_a?(Prism::CallNode)
+            return unless MUTATORS.include?(node.name)
+          end
 
-          name = classifier.const_name(node.receiver)
+          name = classifier.const_name(receiver)
           return unless name
           return if name == "ENV"
           return unless name.split("::").last
             .match?(/\A[A-Z][A-Z0-9_]*\z/)
 
-          flag(node, :constant_mutation, name: name,
-            method: node.name.to_s)
+          flag(node, :constant_mutation, name: name, method: method)
         end
 
         def container_type(value)
@@ -202,12 +265,19 @@ module Audition
           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).
         def wrap_make_shareable(value)
           source = value.location.slice
+          if value.is_a?(Prism::ArrayNode) && value.opening_loc.nil?
+            source = "[#{source}]"
+          end
           Autofix.new(
             start_offset: value.location.start_offset,
             end_offset: value.location.end_offset,
-            replacement: "Ractor.make_shareable(#{source})"
+            replacement: "Ractor.make_shareable(#{source})",
+            safety: :unsafe
           )
         end
 
@@ -218,7 +288,8 @@ module Audition
           Autofix.new(
             start_offset: call.location.start_offset,
             end_offset: call.location.end_offset,
-            replacement: "Ractor.make_shareable(#{source})"
+            replacement: "Ractor.make_shareable(#{source})",
+            safety: :unsafe
           )
         end
       end

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

@@ -82,21 +82,51 @@ module Audition
 
           # Method definitions open fresh scopes; nothing inside
           # them can capture the surrounding locals.
+          # A def opens a fresh scope, but its receiver
+          # expression (`def x.foo`) evaluates in the enclosing
+          # one and can capture an outer local.
           def visit_def_node(node)
+            visit(node.receiver) if node.receiver
           end
 
-          %i[
-            visit_local_variable_read_node
-            visit_local_variable_write_node
-            visit_local_variable_operator_write_node
-            visit_local_variable_or_write_node
-            visit_local_variable_and_write_node
-            visit_local_variable_target_node
-          ].each do |method|
-            define_method(method) do |node| # audition:disable unsafe-calls
-              @names << node.name.to_s if node.depth > @level
-              super(node)
-            end
+          # Plain defs, not a define_method loop: the parallel
+          # scan calls these from worker Ractors, and a method
+          # born from define_method carries an un-shareable Proc
+          # that raises when dispatched from another Ractor.
+          def visit_local_variable_read_node(node)
+            note(node)
+            super
+          end
+
+          def visit_local_variable_write_node(node)
+            note(node)
+            super
+          end
+
+          def visit_local_variable_operator_write_node(node)
+            note(node)
+            super
+          end
+
+          def visit_local_variable_or_write_node(node)
+            note(node)
+            super
+          end
+
+          def visit_local_variable_and_write_node(node)
+            note(node)
+            super
+          end
+
+          def visit_local_variable_target_node(node)
+            note(node)
+            super
+          end
+
+          private
+
+          def note(node)
+            @names << node.name.to_s if node.depth > @level
           end
         end
       end

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

@@ -160,7 +160,7 @@ module Audition
           when Prism::ConstantReadNode
             receiver.name.to_s == expected
           when Prism::ConstantPathNode
-            receiver.location.slice == expected
+            receiver.location.slice.delete_prefix("::") == expected
           else
             false
           end

data/lib/audition/static/graph_audit.rb

@@ -48,6 +48,18 @@ module Audition
         "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>]
@@ -111,9 +123,10 @@ module Audition
 
         variable = decl.name.split("#").last
         owner = display_owner(decl.owner)
-        frozen = @frozen_memos["#{owner}/#{variable}"] == :frozen
+        verdict = @frozen_memos["#{owner}/#{variable}"]
         each_local_definition(decl).map do |defn|
-          if frozen
+          case verdict
+          when :frozen
             finding_at(
               defn,
               check: "class-level-state",
@@ -123,6 +136,16 @@ module Audition
               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,
@@ -179,15 +202,115 @@ module Audition
           )
           collector.groups.each do |(namespace, name), ops|
             key = "#{namespace}/#{name}"
-            verdict =
-              group_frozen?(ops, classifier) ? :frozen : :dirty
-            map[key] =
-              (map[key] == :dirty) ? :dirty : verdict
+            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 }
@@ -203,14 +326,35 @@ module Audition
 
         memos.all? do |memo|
           value = memo[:op][:node].value
-          Rewriters::Memoization.frozen_call?(value) ||
-            classifier.classify(value) == :shareable
+          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

@@ -64,10 +64,14 @@ module Audition
         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
 
@@ -96,6 +100,7 @@ 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

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
 
@@ -87,6 +100,54 @@ module Audition
         @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
@@ -104,8 +165,10 @@ module Audition
           newline = raw.index("\n")
           offset = newline ? newline + 1 : raw.bytesize
         end
+        limit = first_statement_offset
         after_magic = parse_result.magic_comments.filter_map do |mc|
-          next unless MAGIC_KEYS.include?(mc.key_loc.slice)
+          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

data/lib/audition/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: audition
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 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