deprecool 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8979f5deb74f90a5e9e6061319b79a1d920c6153bf3a32d378293514c6f5c547
+  data.tar.gz: 7a17ed36ecfb88aab21b1032a1fa74ae2165e8126826bae9cff2a341c5ae47a7
+SHA512:
+  metadata.gz: d61efb1f6c1a4b36570040aa91dbf20b856fa63b8564390732e3ef14de6ee704f899d6aace163c338db6bec7511f2d189e158d5819f80b75a9002709a1214c4c
+  data.tar.gz: 62ada454736be50a5ff349562d2500d8266ecbe23829cd5a078446abd768fb7677e21e676201da08c4b6f9e1e6329afa0a5a3e3c4b2891c0355777de10166bd4

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Deprecool
+
+## [0.1.0] - 2026-08-13
+
+- Initial Release

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Zac Radford
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,35 @@
+# Deprecool
+
+A static ruby code analyzer to find your deprecated code!
+
+For any developer who has ever ignored a gem's warning and then ran into an error when they went to update
+
+## Usage
+
+Add to your gemfile: `gem 'deprecool'`
+Or directly `gem install deprecool`
+
+Then you can run `deprecool` in the command line to get:
+
+```
+Commands:
+  deprecool list                     # Display which finders are used in this version
+  deprecool scan [PATHS]             # Scan files or directories for known deprecations
+  deprecool version                  # Print the deprecool version
+```
+
+### Scan
+
+`deprecool scan` has several options that can be passed, or it can be run in a folder with a `Gemfile.lock` to automatically look for deprecations based on the currently installed gems.
+
+- `--gem` takes a comma separated list of gems to scan for:
+
+```
+deprecool scan --gem=rails,ruby
+```
+_(make sure there are no spaces between the gem names)_
+
+- `--format=json` if you want the output as json instead of the default text
+- `--lockfile` takes a path to your `Gemfile.lock`, it defaults to using the current directory
+- `--all` run every finder regardless of applicability
+- `--paths` an array of the files or directories to look for ruby file in, defaults to `'.'`

data/exe/deprecool

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'deprecool'
+
+Deprecool::CLI.start(ARGV)

data/lib/deprecool/cli.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'dry/cli'
+require 'debug'
+
+module Deprecool
+  # Command-line entry point. Scans the given files/directories and reports
+  # deprecations.
+  module CLI
+    module Commands
+      extend Dry::CLI::Registry
+
+      class Version < Dry::CLI::Command
+        desc 'Print the deprecool version'
+
+        def call(*)
+          puts "deprecool #{Deprecool::VERSION}"
+        end
+      end
+
+      class List < Dry::CLI::Command
+        desc 'Display which finders are used in this version'
+
+        option :gems, type: :array, desc: 'Specify gem name(s) to list which versions have deprecation tracking available'
+
+        def call(gems:)
+          CLI.list_finders(Finder.registry)
+
+          # TODO: REPL to filter through the available finders?
+        end
+      end
+
+      class Scan < Dry::CLI::Command
+        desc 'Scan files or directories for known deprecations'
+
+        argument :paths, type: :array, desc: 'Files or directories to scan'
+        option :lockfile, default: 'Gemfile.lock', desc: 'Path to Gemfile.lock, defaults to current directory'
+        option :gems, type: :array, desc: 'Gems to scan for: --gems=ruby,rails'
+        option :format, default: 'text', values: %w[text json], desc: 'Output format'
+        option :all, type: :boolean, default: false, desc: 'Run every finder regardless of version'
+
+        def call(paths:, format:, gems: [], all:, lockfile:, **)
+          json_output = format == 'json'
+          files   = CLI.ruby_files(paths)
+
+          if files.empty?
+            if paths.empty?
+              warn CLI.colorize('deprecool: please supply a path/to/file/or/directory', :red)
+              exit 2
+            end
+
+            warn CLI.colorize("deprecool: no Ruby files found in #{paths.join(', ')}", :red)
+            exit 2
+          end
+
+          if gems.any?
+            puts "Scanning for deprecations from: #{gems.join(', ')}" unless json_output
+            # we won't be scanning a lockfile
+            gem_versions = []
+          elsif all
+            gem_versions = []
+            gems = []
+          else
+            puts "Scanning #{lockfile}..." unless json_output
+            gem_versions = LockfileParser.parse!(lockfile)
+
+            # we don't need to look for individual gems when scanning gemfiles
+            gems = []
+          end
+
+          finders  = Registry.applicable(gems:, gem_versions:, include_all: all)
+          scanner  = Scanner.new(finders)
+          offenses = files.flat_map { |file| scanner.scan_file(file) }
+                          .sort_by  { |offense| [offense.file_path, offense.line, offense.column] }
+
+          offenses = offenses.group_by(&:id) unless json_output
+
+          CLI.report(offenses, format, finders)
+          exit(offenses.empty? ? 0 : 1)
+        end
+      end
+
+      register 'version', Version, aliases: %w[v -v --version]
+      register 'scan', Scan
+      register 'list', List, aliases: %w[l -l --list]
+    end
+
+    class << self
+      def start(argv)
+        Dry::CLI.new(Commands).call(arguments: argv)
+      end
+
+      def ruby_files(paths)
+        paths = paths.empty? ? ['.'] : paths
+
+        paths.flat_map do |path|
+          if File.directory?(path)
+            Dir[File.join(path, '**', '*.rb')]
+          elsif File.file?(path)
+            [path]
+          else
+            warn "deprecool: no such file or directory: #{path}"
+            []
+          end
+        end.uniq.sort
+      end
+
+      def report(offenses, format, finders)
+        if format == 'json'
+          puts JSON.pretty_generate(offenses.map(&:to_h))
+        else
+          text_report(offenses, finders)
+        end
+      end
+
+      def text_report(offenses, finders)
+        if offenses.empty?
+          puts colorize('No deprecations found.', :green)
+          puts "(#{finders.size} finder#{'s' unless finders.size == 1} active)"
+          return
+        end
+
+        offense_count = 0
+
+        offenses.each_value do |offense_array|
+          offense = offense_array.first
+
+          puts "\n#{colorize(offense.title, :bold)}\n"
+          puts " * #{offense.summary}"
+          puts "  #{colorize('fix:', :green)} #{offense.suggestion}" if offense.suggestion
+          puts "  #{colorize('source:', :green)} #{offense.reference}" if offense.reference
+          puts '  Found At:'
+          offense_array.each do |o|
+            offense_count   += 1
+            confidence       = o.confidence
+            confidence_color = confidence == :high ? :red : :yellow
+            badge            = colorize("(#{confidence} confidence)", confidence_color)
+
+            puts " (#{offense_count}) #{colorize(o.location, :cyan)} #{badge}"
+            puts "    #{o.source_line.strip}" if o.source_line
+            puts
+          end
+        end
+
+        puts colorize("#{offense_count} deprecation#{'s' unless offense_count == 1} found.", :red)
+      end
+
+      def list_finders(finders)
+        puts 'Active finders:'
+        finders.sort_by { [it.gem.to_s, it.deprecated_in.to_s, it.id.to_s] }.each do
+          puts " - #{it.classname.ljust(35)} (#{it.gem} #{it.deprecated_in.to_s}) — #{it.title}"
+        end
+        puts '  (none)' if finders.empty?
+      end
+
+      def colorize(text, color)
+        colors = { red: 31, green: 32, yellow: 33, cyan: 36, bold: 1 }
+
+        "\e[#{colors.fetch(color, nil)}m#{text}\e[0m"
+      end
+    end
+  end
+end

data/lib/deprecool/finder.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+# requiring this here so we don't have to remember to add
+# it in individual finders
+require_relative 'helpers/prism_helpers'
+
+module Deprecool
+  # Base class for every deprecation finder.
+  #
+  # A finder is responsible for detecting a single deprecation.
+  # Subclasses of Finder describe the deprecation with the class-level DSL and
+  # then implement one or more Prism visit hooks (e.g. `on_call_node`).
+  #
+  # A Scanner then follows the AST a single time and dispatches each node to the
+  # finders that have a relevant method, which call `add_offense` when a match is found.
+  #
+  # Example child class
+  #
+  #   class MyFinder < Deprecool::Finder
+  #     gem           :ruby
+  #     deprecated_in '4.0.0'
+  #     removed_in    '4.1.0'
+  #     title         'some_method will be removed'
+  #     summary       'some_method was causing a problem and will be removed soon'
+  #     suggestion    'remove some_method'
+  #     reference     'https://link_to_pr_or_relevant_info'
+  #     effort        :medium
+  #
+  #     def on_call_node(node)
+  #       add_offense(node, confidence: :high) if node.name == :some_method
+  #     end
+  #   end
+  class Finder
+    include PrismHelpers
+
+    @registry = []
+
+    class << self
+      # All finder subclasses, in definition order.
+      attr_reader :registry
+
+      def inherited(subclass)
+        Finder.registry << subclass
+        super
+      end
+
+      # defines class methods that set instance variables
+      %i[gem title summary suggestion reference].each do |attribute|
+        define_method(attribute) do |value = (getter = true)|
+          return instance_variable_get("@#{attribute}") if getter
+
+          instance_variable_set("@#{attribute}", value)
+        end
+      end
+
+      # Stored as a Gem::Version so it can be compared against the app's
+      # detected version.
+      %i[deprecated_in removed_in].each do |attribute|
+        define_method(attribute) do |value = (getter = true)|
+          return instance_variable_get("@#{attribute}") if getter
+
+          instance_variable_set("@#{attribute}", Gem::Version.new(value))
+        end
+      end
+
+      # how much work is this to fix?
+      # low    => Rails::v7_1_0::SerializerPositionalClassArgument just changes a method signature to have kwarg
+      # medium => Ruby::v4_0_0::ObjectSpaceId2ref to keep same functionality you need to remove the method
+      #           and minor refactor to use WeakMap or something
+      # high   => you're gonna need to make some changes to preserve the same functionality
+      def effort(value = (getter = true))
+        return @effort if getter
+
+        values = %i[low medium high]
+
+        raise "Please use a standardized effort value, i.e #{values}" unless values.include?(value)
+
+        @effort = value
+      end
+
+      def affected_version_range
+        [deprecated_in, removed_in]
+      end
+
+      # return just the class name without all the modules, for displaying
+      def classname
+        name.split('::').last
+      end
+
+      # this is used internally to sort Finders
+      # so we might as well not sort the part thats repeated for every finder
+      def id
+        name.delete_prefix('Deprecool::Finders::')
+      end
+
+      # This is what the Scanner class calls to see what methods are
+      # defined on the child classes,
+      #
+      # child classes should define the methods with 'on' in place of 'visit'
+      # so that we can differentiate them from the default implementation
+      # provided by Prism::Visitor
+      #
+      # (see https://docs.ruby-lang.org/en/master/Prism/Visitor.html for the full list of
+      # Prism compatible methods)
+      # some examples of prism compatible 'on_node' methods for a finder:
+      # Prism::VisitClassNode  => on_class_node
+      # Prism::VisitDefNode    => on_def_node
+      # Prism::VisitModuleNode => on_module_node
+      # Prism::
+      def hook_methods
+        instance_methods(false).grep(/\Aon_\w+_node\z/)
+      end
+    end
+
+    attr_reader :file_path, :source
+
+    def initialize(file_path, source, offenses)
+      @file_path = file_path
+      @source    = source # the result of Prism.parse
+      @offenses  = offenses
+    end
+
+    Offense = Struct.new(:file_path, :line, :column, :end_line, :end_column,
+                         :id, :title, :summary, :suggestion, :reference,
+                         :effort, :confidence, :gem, :deprecated_in,
+                         :removed_in, :snippet, :source_line) do
+      def location
+        "#{file_path}:#{line}:#{column + 1}"
+      end
+    end
+
+    private
+
+    # Record a deprecation at the given node's location.
+    #
+    # confidence - [:high, :low], but currently the only check for this is
+    #              from the CLI outputting red or yellow depending on confidence
+    def add_offense(node, confidence: :high)
+      location = node.location # a Prism::Location
+
+      @offenses << Offense.new(
+        file_path:     file_path,
+        line:          location.start_line,
+        column:        location.start_column,
+        end_line:      location.end_line,
+        end_column:    location.end_column,
+        id:            self.class.id,
+        title:         self.class.title,
+        summary:       self.class.summary,
+        suggestion:    self.class.suggestion,
+        reference:     self.class.reference,
+        effort:        self.class.effort,
+        confidence:    confidence,
+        gem:           self.class.gem,
+        deprecated_in: self.class.deprecated_in.to_s,
+        removed_in:    self.class.removed_in.to_s,
+        snippet:       location.slice,
+        source_line:   source.lines[location.start_line - 1]&.chomp
+      )
+    end
+  end
+end

data/lib/deprecool/finders/rails/v7.1.0/serializer_positional_class_argument.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Deprecool
+  module Finders
+    module Rails
+      module V7_1_0
+        class SerializerPositionalClassArgument < Deprecool::Finder
+          gem           :rails
+          deprecated_in '7.1.0'
+          removed_in    '7.2.0'
+          title         '"serialize" method singature change'
+          summary       'The serialize method in active_record no longer accepts a class as a positional argument ' \
+                        'the method signature now requires custom serializer classes to be ' \
+                        'passed with the `coder:` keword argument.'
+          suggestion    'add the keyword `coder:` to the method signature, i.e serialize :attr, coder: CustomJsonEncoder'
+          reference     'https://github.com/rails/rails/pull/47463'
+          effort        :low
+
+          # TODO: add check for the `serialize` method being called by a Rails model?,
+          # like add a on_constant_path_node for ActiveRecord::Base
+          # or a class_node with a superclass of ActiveRecord::Base
+          # def on_class_node node
+          #   node
+          # end
+
+          def on_call_node(node)
+            return unless node.name == :serialize
+
+            arguments_array = unwrap_arguments(node.arguments)
+            return unless arguments_array && arguments_array[1]
+
+            add_offense(node, confidence: :high) if arguments_array[1].is_a?(Prism::ConstantReadNode)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/deprecool/finders/rails/v8.2.0/redis_cache_store_default_redis_options.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Deprecool
+  module Finders
+    module Rails
+      module V8_2_0
+        class RedisCacheStoreDefaultRedisOptions < Deprecool::Finder
+          gem           :rails
+          deprecated_in '8.2.0'
+          removed_in    '9.0.0'
+          title         'RedisCacheStore::DEFAULT_REDIS_OPTIONS is deprecated'
+          summary       'The `redis-client` implementation no longer reads this constant.'
+          suggestion    'Pass timeout options to RedisCacheStore or a configured RedisClient instead.'
+          reference     'https://github.com/rails/rails/pull/58191 '
+          effort        :low
+
+          # constant_read is any constant, like `Foo`
+          def on_constant_read_node(node)
+            return unless node.name == :DEFAULT_REDIS_OPTIONS
+
+            add_offense(node, confidence: :high)
+          end
+
+          # a constant_path is like: ActiveSupport::Cache::RedisCacheStore::DEFAULT_REDIS_OPTIONS
+          def on_constant_path_node(node)
+            return unless node.name == :DEFAULT_REDIS_OPTIONS
+
+            add_offense(node, confidence: :high)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/deprecool/finders/rails/v8.2.0/to_sql_binds.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Deprecool
+  module Finders
+    module Rails
+      module V8_2_0
+        class ToSqlBinds < Deprecool::Finder
+          gem           :rails
+          deprecated_in '8.2.0'
+          removed_in    '8.3.0'
+          title         'Passing "binds" into "to_sql" is deprecated'
+          summary       'Since Rails 5.2, bind parameters live on the Arel AST ' \
+                        'to_sql_and_binds no longer uses binds for SQL construction, ' \
+                        'and to_sql discards the output binds either way'
+          suggestion    'Do not use the binds argument of the to_sql method'
+          reference     'https://github.com/rails/rails/pull/58310'
+          effort        :low
+
+          def on_call_node(node)
+            # to_sql is a method on an ActiveRecord::Base.connection
+            # the first argument should be a string of sql
+            # the second argument used to be an array of binds
+            # == the second argument is now deprecated ==
+            #
+            # the name of the connection is likely to be connection, but that's unreliable
+            # if a method called 'to_sql' is passed two arguments and the second is an
+            # array that's probably good enough
+            return unless node.name == :to_sql
+
+            arguments_array = unwrap_arguments(node.arguments)
+            return unless arguments_array && arguments_array[1]
+
+            add_offense(node, confidence: :high)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/deprecool/finders/ruby/v4.0.0/object_space_id2ref.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Deprecool
+  module Finders
+    module Ruby
+      module V4_0_0
+        class ObjectSpaceId2ref < Deprecool::Finder
+          gem           :ruby
+          deprecated_in '4.0.0'
+          removed_in    '4.1.0'
+          title         'Using ObjectSpace._id2ref is deprecated'
+          summary       'The object_id identifier does not guarantee that the id won\'t be reused ' \
+                        'after the original has been garbage collected, ' \
+                        'therefore _id2ref is unsafe and unreliable, and per matz: ' \
+                        '"Reviving arbitrary objects from integer IDs was never a sound API"'
+          suggestion    'Do not rely on this method'
+          reference     'original issue: https://bugs.ruby-lang.org/issues/15408' \
+                        'deprecated: https://github.com/ruby/ruby/pull/13157' \
+                        'removed: https://bugs.ruby-lang.org/issues/22135'
+          effort        :medium
+
+          def on_call_node(node)
+            return unless node.name == :_id2ref
+
+            # The method name '_id2ref' is quite unique, and
+            # the use case for this is specific enough that
+            # I don't think we need much more than this
+            # I'm open to be wrong though, maybe lots of people are subclassing
+            # ObjectSpace or defining '_id2ref' on custom classes
+            confidence = node.receiver.name == :ObjectSpace ? :high : nil
+
+            return unless confidence
+
+            add_offense node, confidence: confidence
+          end
+        end
+      end
+    end
+  end
+end

data/lib/deprecool/finders/ruby/v4.0.0/to_set_arguments.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Deprecool
+  module Finders
+    module Ruby
+      module V4_0_0
+        class ToSetArguments < Deprecool::Finder
+          gem           :ruby
+          deprecated_in '4.0.0'
+          removed_in    '4.1.0'
+          title         'Passing arguments to #to_set is deprecated'
+          summary       'Since Ruby 4.0, passing arguments to Set#to_set / Enumerable#to_set ' \
+                        'is deprecated and will be removed.'
+          suggestion    'Call #to_set with no arguments. If you were building a ' \
+                        'Set subclass, construct it explicitly instead.'
+          reference     'https://bugs.ruby-lang.org/issues/21390 https://github.com/ruby/ruby/pull/13489'
+          effort        :low
+
+          def on_call_node(node)
+            return unless node.name == :to_set
+            return unless node.arguments
+
+            confidence = confidence_from_receiver_node(node.receiver)
+            return unless confidence
+
+            add_offense(node, confidence:)
+          end
+
+          private
+
+          def confidence_from_receiver_node(receiver)
+            case receiver
+            # these nodes all represent Enumerables
+            when Prism::ArrayNode, Prism::HashNode, Prism::RangeNode then :high
+            # a plain `to_set(x)` call to the current scope's own
+            # method. This is probably not Enumerable#to_set unless someone has
+            # monkeypatched Enumerable and is using to_set with an argument, I guess
+            when nil then nil
+            when Prism::ConstantReadNode, Prism::ConstantPathNode
+              # These nodes can constants like:
+              # MY_DATA.to_set(arg) => likely an array, but can't be sure so :low
+              # MyClass.to_set(arg) => has lowercase letters so it's a class method
+              receiver&.name&.match?(/[a-z]/) ? nil : :low
+            else
+              # this branch is when the receiver is some
+              # local var, instance variable, method chain, safe navigation, etc.
+              # could even be an a custom object — we can't really tell.
+              # but we do know enumerable methods like map, reduce, etc. so
+              # we can be more confident about that
+              return :high if Enumerable.method_defined?(receiver.name)
+
+              :low
+            end
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/deprecool/helpers/prism_helpers.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module PrismHelpers
+  # `(1..10)` parses as a ParenthesesNode wrapping the real expression.
+  def unwrap_parentheses(node)
+    return node unless node.is_a?(Prism::ParenthesesNode)
+
+    body = node.body&.body
+    body&.length == 1 ? body.first : node
+  end
+
+  # Method arguments are represented as:
+  # node.arguments returns a literal array of arguments
+  # https://docs.ruby-lang.org/en/master/Prism/ArgumentsNode.html
+  def unwrap_arguments(node)
+    return node unless node.is_a?(Prism::ArgumentsNode)
+
+    node.arguments
+  end
+
+  # https://docs.ruby-lang.org/en/master/Prism/ArrayNode.html
+  def unwrap_array(node)
+    return node unless node.is_a?(Prism::ArrayNode)
+
+    node.elements
+  end
+
+  def unwrap_class(node)
+    return node unless node.is_a?(Prism::ClassNode)
+
+    node.body
+  end
+
+  def unwrap_children(node)
+    return node unless node.respond_to?(:child_nodes)
+
+    node.child_nodes
+  end
+end

data/lib/deprecool/lockfile_parser.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'bundler'
+
+module Deprecool
+  module LockfileParser
+    extend self
+
+    def parse!(path_to_gemfile_lock = 'Gemfile.lock', parser: Bundler::LockfileParser)
+      lockfile = File.read(path_to_gemfile_lock)
+
+      parsed = parser.new(lockfile)
+
+      versions = parsed.specs.map do |spec|
+        { gem: spec.name, version: spec.version.to_s }
+      end
+
+      gem, version = parsed.ruby_version.split
+      versions << { gem:, version: }
+    end
+  end
+end

data/lib/deprecool/registry.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Deprecool
+  # Selects which finders should run for a given application, based on the gems
+  # (and Ruby) it actually uses and at what versions.
+  module Registry
+    extend self
+
+    # Every registered finder.
+    def all_finders
+      Finder.registry
+    end
+
+    # Gets finders that apply to the given versions.
+    # gems - an array of gem names
+    # gem_versions - an array of hashes like: { gem:, version: }
+    def applicable(gems: [], gem_versions: [], include_all: false)
+      return all_finders if include_all
+      return finders_by_gem(gems) if gems.any?
+      return finders_by_gem_version(gem_versions) if gem_versions.any?
+    end
+
+    def finders_by_gem(gems)
+      targets = []
+      gems.each do |gem|
+        targets << all_finders.select { it.to_s.match(/#{gem.capitalize}/) }
+      end
+      targets.flatten
+    end
+
+    def finders_by_gem_version(gem_versions)
+      finder_targets = []
+
+      gem_versions.each do |gem_version|
+        jem     = gem_version[:gem].to_sym
+        version = Gem::Version.new(gem_version[:version])
+
+        # match when:
+        # 1) finder is for the current gem,
+        # 2) gem's version is higher than finder's deprecated,
+        # and 3) gems version is lower or equal to the removed_in
+        targets = all_finders.select do |finder|
+          (finder.gem == jem) &&
+            (finder.deprecated_in <= version) && (version <= finder.removed_in)
+        end
+
+        if !targets.empty?
+          finder_targets << targets
+        else
+          # this unfortunately floods the terminal for now, but one day maybe it won't
+          # puts "Oops, I don't have a Finder that applies to #{jem} v#{version}"
+        end
+      end
+
+      finder_targets.flatten
+    end
+  end
+end

data/lib/deprecool/scanner.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Deprecool
+  # Parses a source file with Prism and runs a set of finders against it in a
+  # single AST traversal.
+  class Scanner
+    def initialize(finders)
+      @finders = Array(finders)
+    end
+
+    def scan_file(path)
+      scan_source(File.read(path), path)
+    end
+
+    # Returns an Array<Offense>. Files that fail to parse yield no offenses;
+    # parse errors are surfaced separately via {#parse_errors}.
+    def scan_source(source, path = '(source)')
+      result = Prism.parse(source)
+      return [] unless result.success?
+
+      offenses  = []
+      # each finder has the path, the whole source of the file, and the offenses list
+      # so that they can build the offense warning themselves.
+      # we might be able to refactor this to only pass the source because the path
+      # and offenses are only needed for the add_offense method, not the actual
+      # searching for an offense?
+      instances = @finders.map { |finder| finder.new(path, source, offenses) }
+      DispatchVisitor.new(instances).visit(result.value)
+      offenses
+    end
+
+    # Combines the given Finder classes into one class by
+    #  defining one method per Prism::Visitor hook (e.g. visit_call_node)
+    #  based on all the given finders that define a method that matches that
+    #  hook method name
+    class DispatchVisitor < Prism::Visitor
+      # finder_instances is the array passed to the Scanner.new class,
+      # so this would be [Ruby::V4_0_0::ToSetArguments, ..]
+      def initialize(finder_instances)
+        super()
+
+        dispatch = Hash.new { |hash, key| hash[key] = [] }
+        finder_instances.each do |instance|
+          # find the hooks and add the instances to the hash of hook methods
+          # so { on_call_node: [ToSetArguments.new, ObjectSpaceId2ref.new,.. ], ... }
+          instance.class.hook_methods.each { |hook| dispatch[hook] << instance }
+        end
+
+        dispatch.each do |hook, finders|
+          # convert the instances' hooks to what prism::visitor expects
+          # so finder classes must use this pattern to name the visit_node methods
+          #
+          # 'on_call_node'   => good
+          # 'find_call_node' => bad
+          visit_method = hook.to_s.sub(/\Aon_/, 'visit_').to_sym
+
+          # define the prism::visitor hook to loop through each of the
+          # related finders and call the name of the hook like so:
+          #
+          # def visit_call_node(node)
+          #   [ToSetArguments.new, ObjectSpaceId2ref.new].each do |finder|
+          #     finder.send("on_call_node", node)
+          #   end
+          #
+          #   super(node)
+          # end
+          define_singleton_method(visit_method) do |node|
+            finders.each { |finder| finder.send(hook, node) }
+            super(node)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/deprecool/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Deprecool
+  VERSION = '0.1.0'
+end
+

data/lib/deprecool.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+module Deprecool
+  class Error < StandardError; end
+end
+
+require_relative 'deprecool/version'
+require_relative 'deprecool/finder'
+require_relative 'deprecool/registry'
+require_relative 'deprecool/scanner'
+require_relative 'deprecool/lockfile_parser'
+require_relative 'deprecool/cli'
+
+# TODO: Scan gemfiles and then only require relevant finders instead of all
+# of them
+Dir[File.join(__dir__, 'deprecool', 'finders', '**', '*.rb')].each do |finder|
+  require finder
+end
+

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: deprecool
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Zac Radford
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Static deprecation analysis tool to keep your code cool
+email:
+- zacnradford@gmail.com
+executables:
+- deprecool
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/deprecool
+- lib/deprecool.rb
+- lib/deprecool/cli.rb
+- lib/deprecool/finder.rb
+- lib/deprecool/finders/rails/v7.1.0/serializer_positional_class_argument.rb
+- lib/deprecool/finders/rails/v8.2.0/redis_cache_store_default_redis_options.rb
+- lib/deprecool/finders/rails/v8.2.0/to_sql_binds.rb
+- lib/deprecool/finders/ruby/v4.0.0/object_space_id2ref.rb
+- lib/deprecool/finders/ruby/v4.0.0/to_set_arguments.rb
+- lib/deprecool/helpers/prism_helpers.rb
+- lib/deprecool/lockfile_parser.rb
+- lib/deprecool/registry.rb
+- lib/deprecool/scanner.rb
+- lib/deprecool/version.rb
+homepage: https://github.com/zradford/deprecool
+licenses:
+- MIT
+metadata:
+  changelog_uri: https://github.com/zradford/deprecool/CHANGELOG.md
+  source_code_uri: https://github.com/zradford/deprecool
+  bug_tracker_uri: https://github.com/zradford/deprecool/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Static deprecation analysis tool to keep your code cool
+test_files: []