audition 0.1.0

data/lib/audition/static/graph_audit.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "rubydex"
+
+module Audition
+  module Static
+    # Whole-program semantic checks backed by the rubydex graph.
+    # rubydex resolves state to its true owner, so an ivar written in
+    # the class body, in `def self.x`, and inside `class << self`,
+    # across several files, unifies into one declaration owned by the
+    # singleton class. Per-file AST visitors cannot see that.
+    class GraphAudit
+      CVAR_WHY =
+        "Class variables cannot be accessed from non-main Ractors " \
+        "at all; both reads and writes raise " \
+        "Ractor::IsolationError (\"can not access class variables " \
+        "from non-main Ractors\")."
+      CVAR_FIX =
+        "Replace with a deeply frozen constant, per-instance " \
+        "state, or Ractor-local storage (Ractor.current[:key], " \
+        "Ractor.store_if_absent)."
+      STATE_WHY =
+        "This instance variable lives on the class/module object, " \
+        "which is shared across Ractors; non-main Ractors raise " \
+        "Ractor::IsolationError when writing it, and when reading " \
+        "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]."
+
+      # @param sources [Hash{String => String}] path => source
+      # @return [Array<Finding>]
+      def analyze_sources(sources)
+        graph = Rubydex::Graph.new
+        sources.each do |path, code|
+          graph.index_source(path, code, "ruby")
+        end
+        @sources = sources
+        audit(graph)
+      end
+
+      # rubydex's index_all descends directories but skips bare file
+      # lists, so files are fed through index_source individually.
+      #
+      # @param paths [Array<String>] files to index and audit
+      # @return [Array<Finding>]
+      def analyze_paths(paths)
+        sources = {}
+        paths.each do |path|
+          sources[path] = File.read(path)
+        rescue SystemCallError
+          next
+        end
+        analyze_sources(sources)
+      end
+
+      private
+
+      def audit(graph)
+        graph.resolve
+        findings = []
+        graph.declarations.each do |decl|
+          case decl
+          when Rubydex::ClassVariable
+            findings.concat(class_variable_findings(decl))
+          when Rubydex::InstanceVariable
+            findings.concat(class_state_findings(decl))
+          end
+        end
+        findings.sort_by { |f| [f.path, f.line] }
+      end
+
+      def class_variable_findings(decl)
+        variable = decl.name.split("#").last
+        owner = display_owner(decl.owner)
+        each_local_definition(decl).map do |defn|
+          finding_at(
+            defn,
+            check: "class-variables",
+            message: "class variable #{variable} on #{owner}",
+            why: CVAR_WHY,
+            fix: CVAR_FIX
+          )
+        end
+      end
+
+      def class_state_findings(decl)
+        return [] unless decl.owner.is_a?(Rubydex::SingletonClass)
+
+        variable = decl.name.split("#").last
+        owner = display_owner(decl.owner)
+        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
+          )
+        end
+      end
+
+      def each_local_definition(decl)
+        decl.definitions.reject do |defn|
+          defn.location.uri.start_with?("rubydex:")
+        end
+      end
+
+      def finding_at(defn, check:, message:, why:, fix:)
+        path = path_from_uri(defn.location.uri)
+        line = defn.location.start_line + 1
+        Finding.new(
+          check: check,
+          severity: :error,
+          message: message,
+          why: why,
+          fix: fix,
+          path: path,
+          line: line,
+          source: source_line(path, line)
+        )
+      end
+
+      # "Payments::<Payments>" reads as noise; show "Payments".
+      def display_owner(owner)
+        (owner&.name || "?").sub(/::<[^>]+>\z/, "")
+      end
+
+      def path_from_uri(uri)
+        uri.delete_prefix("file://")
+      end
+
+      def source_line(path, line)
+        content = @sources[path]
+        content ||= File.read(path) if File.file?(path)
+        content&.lines&.[](line - 1)&.strip
+      end
+    end
+  end
+end

data/lib/audition/static/literal_classifier.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Audition
+  module Static
+    # Classifies a Prism expression node by Ractor shareability:
+    #   :shareable         proven deeply shareable
+    #   :mutable_string    unfrozen String literal
+    #   :mutable_container Array/Hash literal
+    #   :shallow_freeze    frozen container with mutable elements
+    #   :sync_primitive    Mutex/Queue/... constructor
+    #   :proc              lambda or proc
+    #   :unknown           cannot tell statically
+    class LiteralClassifier
+      SYNC_PRIMITIVES = %w[
+        Mutex Monitor Queue SizedQueue ConditionVariable
+        Thread::Mutex Thread::Queue Thread::SizedQueue
+        Thread::ConditionVariable
+      ].freeze
+      SHAREABLE_FACTORIES = %w[Struct Class Module].freeze
+
+      # @param frozen_string_literal [Boolean] whether the file has
+      #   the frozen_string_literal magic comment
+      def initialize(frozen_string_literal:)
+        @frozen_string_literal = frozen_string_literal
+      end
+
+      # @param node [Prism::Node] an expression node
+      # @return [Symbol] classification, see class docs
+      def classify(node)
+        case node
+        when Prism::IntegerNode, Prism::FloatNode,
+             Prism::RationalNode, Prism::ImaginaryNode,
+             Prism::SymbolNode, Prism::InterpolatedSymbolNode,
+             Prism::TrueNode, Prism::FalseNode, Prism::NilNode,
+             Prism::RegularExpressionNode,
+             Prism::InterpolatedRegularExpressionNode
+          :shareable
+        when Prism::StringNode
+          @frozen_string_literal ? :shareable : :mutable_string
+        when Prism::InterpolatedStringNode
+          classify_interpolated_string(node)
+        when Prism::ArrayNode, Prism::HashNode,
+             Prism::KeywordHashNode
+          :mutable_container
+        when Prism::RangeNode
+          ends = [node.left, node.right].compact
+          if ends.all? { |n| classify(n) == :shareable }
+            :shareable
+          else
+            :unknown
+          end
+        when Prism::LambdaNode
+          :proc
+        when Prism::CallNode
+          classify_call(node)
+        else
+          :unknown
+        end
+      end
+
+      def const_name(node)
+        case node
+        when Prism::ConstantReadNode then node.name.to_s
+        when Prism::ConstantPathNode then node.location.slice
+        end
+      end
+
+      private
+
+      # Adjacent literals ("a" "b") parse as interpolation but
+      # compile to one static string, frozen under the magic
+      # comment; real interpolation stays mutable.
+      def classify_interpolated_string(node)
+        static = node.parts.all? do |part|
+          part.is_a?(Prism::StringNode)
+        end
+        if static && @frozen_string_literal
+          :shareable
+        else
+          :mutable_string
+        end
+      end
+
+      def classify_call(node)
+        receiver = node.receiver
+        case node.name
+        when :freeze
+          classify_freeze(node, receiver)
+        when :new
+          name = const_name(receiver)
+          return :sync_primitive if SYNC_PRIMITIVES.include?(name)
+          return :shareable if SHAREABLE_FACTORIES.include?(name)
+
+          :unknown
+        when :define
+          (const_name(receiver) == "Data") ? :shareable : :unknown
+        when :make_shareable
+          (const_name(receiver) == "Ractor") ? :shareable : :unknown
+        when :lambda, :proc
+          (receiver.nil? && node.block) ? :proc : :unknown
+        else
+          :unknown
+        end
+      end
+
+      def classify_freeze(node, receiver)
+        return :unknown unless node.arguments.nil? && receiver
+
+        case receiver
+        when Prism::StringNode
+          :shareable
+        when Prism::ArrayNode, Prism::HashNode
+          deep_classify(receiver.elements)
+        else
+          :unknown
+        end
+      end
+
+      # Fold element classifications: everything provably shareable
+      # gives :shareable; anything provably mutable gives
+      # :shallow_freeze; 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|
+            case classify(child)
+            when :shareable then nil
+            when :unknown then return :unknown
+            else verdict = :shallow_freeze
+            end
+          end
+        end
+        verdict
+      end
+    end
+  end
+end

data/lib/audition/static/source_file.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Audition
+  module Static
+    # A parsed Ruby file plus the magic comments that change Ractor
+    # semantics.
+    class SourceFile
+      attr_reader :path, :source, :parse_result
+
+      def self.read(path)
+        new(source: File.read(path), path: path)
+      end
+
+      def initialize(source:, path:)
+        @source = source
+        @path = path
+        @parse_result = Prism.parse(source)
+      end
+
+      def valid_syntax? = parse_result.success?
+
+      def syntax_errors = parse_result.errors
+
+      def root = parse_result.value
+
+      def magic_comment(key)
+        comment = parse_result.magic_comments.find do |mc|
+          mc.key_loc.slice == key
+        end
+        comment&.value_loc&.slice
+      end
+
+      # String literals in this file are frozen (and therefore
+      # shareable when they contain no interpolation).
+      def frozen_string_literal?
+        magic_comment("frozen_string_literal") == "true"
+      end
+
+      # `# shareable_constant_value: literal|experimental_everything|
+      # experimental_copy` makes constant values deeply frozen and
+      # shareable at parse time, so constant checks are moot.
+      # (v1 treats the comment as file-wide.)
+      def shareable_constants?
+        value = magic_comment("shareable_constant_value")
+        !value.nil? && value != "none"
+      end
+
+      def line_at(number)
+        @lines ||= source.lines
+        @lines[number - 1]&.strip
+      end
+
+      # Literal feature strings required by top-level statements.
+      def top_level_requires
+        @top_level_requires ||= root.statements.body.filter_map do |s|
+          next unless s.is_a?(Prism::CallNode) && s.receiver.nil?
+          next unless %i[require require_relative].include?(s.name)
+
+          arg = s.arguments&.arguments&.first
+          arg.unescaped if arg.is_a?(Prism::StringNode)
+        end
+      end
+
+      # Where a hoisted `require` line can be inserted: right after
+      # the last existing top-level require, or after the leading
+      # comment block (shebang and magic comments), or at the top.
+      def boot_insertion
+        last_require = root.statements.body.rfind do |s|
+          s.is_a?(Prism::CallNode) && s.receiver.nil? &&
+            %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
+          {offset: offset, after_require: true}
+        else
+          {offset: leading_comments_end, after_require: false}
+        end
+      end
+
+      # 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
+        end
+        after_magic = parse_result.magic_comments.map do |mc|
+          newline = source.index("\n", mc.value_loc.end_offset)
+          newline ? newline + 1 : source.bytesize
+        end.max
+        [offset, after_magic || 0].max
+      end
+
+      def leading_comments_end
+        offset = 0
+        source.each_line do |line|
+          break unless line.start_with?("#")
+
+          offset += line.bytesize
+        end
+        offset
+      end
+    end
+  end
+end

data/lib/audition/target.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Audition
+  # Figures out what the user pointed us at and what that means for
+  # scanning (which .rb files) and dynamic probing (which entry).
+  #
+  # Detection precedence for directories: Rails beats Rack (a Rails
+  # root always has a config.ru), Rack beats gem (an app may vendor a
+  # gemspec), gem beats plain directory.
+  class Target
+    EXCLUDED_DIRS = %w[
+      vendor node_modules tmp log coverage pkg .git .bundle
+    ].freeze
+
+    # @return [Symbol] one of `:script`, `:gem`, `:rack`, `:rails`,
+    #   `:directory`, `:bundle`
+    attr_reader :type
+
+    # @return [String] the target's root directory
+    attr_reader :root
+
+    # @return [Array<String>] Ruby files to scan statically
+    attr_reader :ruby_files
+
+    # @return [Hash, nil] dynamic probe entry (`:mode` plus
+    #   mode-specific keys), nil for static-only targets
+    attr_reader :entry
+
+    # Detects what `raw` points at and builds the target.
+    #
+    # @param raw [String] a `.rb`/`.ru` file, a directory, a
+    #   `Gemfile.lock`, or an installed gem name
+    # @return [Target]
+    # @raise [Audition::Error] when nothing matches
+    def self.detect(raw)
+      raw = normalize(raw)
+      if File.file?(raw)
+        from_file(raw)
+      elsif File.directory?(raw)
+        from_directory(raw)
+      else
+        from_gem_name(raw)
+      end
+    end
+
+    def self.from_file(path)
+      if File.basename(path) == "Gemfile.lock"
+        return new(
+          type: :bundle,
+          root: File.expand_path("..", path),
+          ruby_files: [],
+          entry: {mode: :bundle, lockfile: path}
+        )
+      end
+      unless path.end_with?(".rb", ".ru")
+        raise Error, "#{path} is not a Ruby file"
+      end
+
+      new(
+        type: :script,
+        root: File.dirname(path),
+        ruby_files: [path],
+        entry: {mode: :script, path: path}
+      )
+    end
+
+    def self.from_directory(dir)
+      application_rb = File.join(dir, "config", "application.rb")
+      config_ru = File.join(dir, "config.ru")
+      gemspec = Dir[File.join(dir, "*.gemspec")].first
+
+      if File.file?(application_rb)
+        rails_target(dir)
+      elsif File.file?(config_ru)
+        rack_target(dir, config_ru)
+      elsif gemspec
+        gem_dir_target(dir, gemspec)
+      else
+        new(
+          type: :directory,
+          root: dir,
+          ruby_files: glob(dir),
+          entry: nil
+        )
+      end
+    end
+
+    def self.from_gem_name(name)
+      spec = Gem::Specification.find_by_name(name)
+      new(
+        type: :gem,
+        root: spec.full_gem_path,
+        ruby_files: spec.require_paths.flat_map do |rp|
+          glob(File.join(spec.full_gem_path, rp))
+        end,
+        entry: {mode: :require, feature: name,
+                root: spec.full_gem_path}
+      )
+    rescue Gem::MissingSpecError
+      raise Error,
+        "#{name} is not a file, directory, or installed gem"
+    end
+
+    def self.rails_target(dir)
+      files = %w[app lib config].flat_map { |d| glob(File.join(dir, d)) }
+      files << File.join(dir, "config.ru")
+      new(
+        type: :rails,
+        root: dir,
+        ruby_files: files.select { |f| File.file?(f) },
+        entry: {
+          mode: :rails,
+          environment: File.join(dir, "config", "environment.rb"),
+          root: dir
+        }
+      )
+    end
+
+    def self.rack_target(dir, config_ru)
+      new(
+        type: :rack,
+        root: dir,
+        ruby_files: [config_ru] + glob(dir),
+        entry: {mode: :rack, config_ru: config_ru}
+      )
+    end
+
+    def self.gem_dir_target(dir, gemspec)
+      lib = File.join(dir, "lib")
+      new(
+        type: :gem,
+        root: dir,
+        ruby_files: glob(lib),
+        entry: {
+          mode: :require,
+          feature: File.basename(gemspec, ".gemspec"),
+          load_paths: [lib],
+          root: dir
+        }
+      )
+    end
+
+    # Trailing slashes would break the prefix-stripping in glob
+    # ("dir//" never matches), silently excluding every file of a
+    # relative target.
+    def self.normalize(raw)
+      return raw if raw == "/"
+
+      raw.sub(%r{/+\z}, "")
+    end
+
+    def self.glob(dir)
+      dir = normalize(dir)
+      Dir[File.join(dir, "**", "*.rb")].reject do |path|
+        relative = path.delete_prefix("#{dir}/")
+        parts = relative.split("/")
+        parts.any? { |p| EXCLUDED_DIRS.include?(p) || p.start_with?(".") }
+      end.sort
+    end
+
+    private_class_method :from_file, :from_directory, :from_gem_name,
+      :rails_target, :rack_target, :gem_dir_target,
+      :glob, :normalize
+
+    def initialize(type:, root:, ruby_files:, entry:)
+      @type = type
+      @root = root
+      @ruby_files = ruby_files
+      @entry = entry
+    end
+  end
+end

data/lib/audition/version.rb

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

data/lib/audition.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "audition/version"
+require_relative "audition/finding"
+require_relative "audition/target"
+require_relative "audition/static/source_file"
+require_relative "audition/static/literal_classifier"
+require_relative "audition/static/checks"
+require_relative "audition/static/graph_audit"
+require_relative "audition/static/analyzer"
+require_relative "audition/dynamic/prober"
+require_relative "audition/report"
+require_relative "audition/config"
+require_relative "audition/baseline"
+require_relative "audition/directives"
+require_relative "audition/fixer"
+require_relative "audition/bundle_sweep"
+require_relative "audition/cli"
+
+# Probes Ruby code for the ability to run inside Ractors: static
+# analysis (Prism per-file checks plus whole-program rubydex graph
+# checks), dynamic in-Ractor probing in subprocesses, explanations
+# and fixes for every finding, and a four-state verdict.
+#
+# The command line lives in {Audition::CLI}; library consumers
+# usually start from {Audition::Target.detect} and
+# {Audition::Static::Analyzer}.
+#
+# @example Audit one file programmatically
+#   analyzer = Audition::Static::Analyzer.new
+#   findings = analyzer.analyze_path("app/models/user.rb")
+#   findings.each { |f| puts "#{f.location}: #{f.message}" }
+module Audition
+  # Raised for user-facing failures: unknown targets, unreadable
+  # config, malformed baselines. The CLI converts it to exit code 2.
+  class Error < StandardError; end
+end