active_record_doctor 1.8.0 → 1.10.0

data/lib/active_record_doctor/detectors/undefined_table_references.rb

@@ -4,30 +4,27 @@ require "active_record_doctor/detectors/base"
 
 module ActiveRecordDoctor
   module Detectors
-    # Find models referencing non-existent database tables or views.
-    class UndefinedTableReferences < Base
-      @description = "Detect models referencing undefined tables or views"
+    class UndefinedTableReferences < Base # :nodoc:
+      @description = "detect models referencing undefined tables or views"
+      @config = {
+        ignore_models: {
+          description: "models whose underlying tables should not be checked for existence",
+          global: true
+        }
+      }
 
-      def run
-        eager_load!
+      private
 
-        # If we can't list views due to old Rails version or unsupported
-        # database then existing_views is nil. We inform the caller we haven't
-        # consulted views so that it can display an appropriate warning.
-        existing_views = views
+      def message(model:, table:)
+        "#{model} references a non-existent table or view named #{table}"
+      end
 
-        offending_models = models.select do |model|
-          model.table_name.present? &&
-            !tables.include?(model.table_name) &&
-            (
-              existing_views.nil? ||
-                !existing_views.include?(model.table_name)
-            )
-        end.map do |model|
-          [model.name, model.table_name]
-        end
+      def detect
+        models(except: config(:ignore_models)).each do |model|
+          next if model.table_exists? || views.include?(model.table_name)
 
-        problems(offending_models, views_checked: !existing_views.nil?)
+          problem!(model: model.name, table: model.table_name)
+        end
       end
     end
   end

data/lib/active_record_doctor/detectors/unindexed_deleted_at.rb

@@ -4,25 +4,50 @@ require "active_record_doctor/detectors/base"
 
 module ActiveRecordDoctor
   module Detectors
-    # Find unindexed deleted_at columns.
-    class UnindexedDeletedAt < Base
-      PATTERN = [
-        "deleted_at",
-        "discarded_at"
-      ].join("|").freeze
-
-      @description = "Detect unindexed deleted_at columns"
-
-      def run
-        problems(connection.tables.select do |table|
-          connection.columns(table).any? { |column| column.name =~ /^#{PATTERN}$/ }
-        end.flat_map do |table|
-          connection.indexes(table).reject do |index|
-            index.where =~ /\b#{PATTERN}\s+IS\s+NULL\b/i
-          end.map do |index|
-            index.name
+    class UnindexedDeletedAt < Base # :nodoc:
+      @description = "detect indexes that exclude deletion timestamp columns"
+      @config = {
+        ignore_tables: {
+          description: "tables whose indexes should not be checked",
+          global: true
+        },
+        ignore_columns: {
+          description: "specific columns, written as table.column, that should not be reported as unindexed"
+        },
+        ignore_indexes: {
+          description: "specific indexes that should not be reported as excluding a timestamp column"
+        },
+        column_names: {
+          description: "deletion timestamp column names"
+        }
+      }
+
+      private
+
+      def message(index:, column_name:)
+        # rubocop:disable Layout/LineLength
+        "consider adding `WHERE #{column_name} IS NULL` or `WHERE #{column_name} IS NOT NULL` to #{index} - a partial index can speed lookups of soft-deletable models"
+        # rubocop:enable Layout/LineLength
+      end
+
+      def detect
+        tables(except: config(:ignore_tables)).each do |table|
+          timestamp_columns = connection.columns(table).reject do |column|
+            config(:ignore_columns).include?("#{table}.#{column.name}")
+          end.select do |column|
+            config(:column_names).include?(column.name)
+          end
+
+          next if timestamp_columns.empty?
+
+          timestamp_columns.each do |timestamp_column|
+            indexes(table, except: config(:ignore_indexes)).each do |index|
+              next if index.where =~ /\b#{timestamp_column.name}\s+IS\s+(NOT\s+)?NULL\b/i
+
+              problem!(index: index.name, column_name: timestamp_column.name)
+            end
           end
-        end)
+        end
       end
     end
   end

data/lib/active_record_doctor/detectors/unindexed_foreign_keys.rb

@@ -4,29 +4,40 @@ require "active_record_doctor/detectors/base"
 
 module ActiveRecordDoctor
   module Detectors
-    # Find foreign keys that lack indexes (usually recommended for performance reasons).
-    class UnindexedForeignKeys < Base
-      @description = "Detect foreign keys without an index on them"
-
-      def run
-        problems(hash_from_pairs(tables.reject do |table|
-          table == "schema_migrations"
-        end.map do |table|
-          [
-            table,
-            connection.columns(table).select do |column|
-              foreign_key?(column) &&
-                !indexed?(table, column) &&
-                !indexed_as_polymorphic?(table, column)
-            end.map(&:name)
-          ]
-        end.reject do |_table, columns|
-          columns.empty?
-        end))
-      end
+    class UnindexedForeignKeys < Base # :nodoc:
+      @description = "detect unindexed foreign keys"
+      @config = {
+        ignore_tables: {
+          description: "tables whose foreign keys should not be checked",
+          global: true
+        },
+        ignore_columns: {
+          description: "columns, written as table.column, that should not be checked"
+        }
+      }
 
       private
 
+      def message(table:, column:)
+        # rubocop:disable Layout/LineLength
+        "add an index on #{table}.#{column} - foreign keys are often used in database lookups and should be indexed for performance reasons"
+        # rubocop:enable Layout/LineLength
+      end
+
+      def detect
+        tables(except: config(:ignore_tables)).each do |table|
+          connection.columns(table).each do |column|
+            next if config(:ignore_columns).include?("#{table}.#{column.name}")
+
+            next unless foreign_key?(column)
+            next if indexed?(table, column)
+            next if indexed_as_polymorphic?(table, column)
+
+            problem!(table: table, column: column.name)
+          end
+        end
+      end
+
       def foreign_key?(column)
         column.name.end_with?("_id")
       end

data/lib/active_record_doctor/detectors.rb

@@ -3,11 +3,19 @@
 require "active_support"
 require "active_support/core_ext/class/subclasses"
 
-module ActiveRecordDoctor
+module ActiveRecordDoctor # :nodoc:
+  def self.detectors
+    @detectors ||=
+      begin
+        detectors = {}
+        ActiveRecordDoctor::Detectors::Base.subclasses.each do |detector|
+          detectors[detector.underscored_name] = detector
+        end
+        detectors
+      end
+  end
+
   # Container module for all detectors, implemented as separate classes.
   module Detectors
-    def self.all
-      ActiveRecordDoctor::Detectors::Base.subclasses
-    end
   end
 end

data/lib/active_record_doctor/errors.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module ActiveRecordDoctor # :nodoc:
+  def self.handle_exception
+    yield
+  rescue ActiveRecordDoctor::Error => e
+    $stderr.puts(e.user_message)
+    exit(1)
+  end
+
+  # Generic active_record_doctor exception class.
+  class Error < RuntimeError
+    attr_accessor :config_path
+
+    def self.[](*args)
+      new(*args)
+    end
+
+    def details
+      nil
+    end
+
+    def user_message
+      result =
+        <<-MESSAGE
+active_record_doctor aborted due to the following error:
+#{message}
+
+Configuration file:
+#{config_path_or_message}
+        MESSAGE
+
+      if details
+        result << (
+          <<-MESSAGE
+
+Additional information:
+#{details}
+          MESSAGE
+        )
+      end
+
+      result
+    end
+
+    private
+
+    def config_path_or_message
+      @config_path || "no configuration file in use (using default settings)"
+    end
+
+    def hyphenated_list(items)
+      items.map { |item| "  - #{item}" }.join("\n")
+    end
+  end
+
+  class Error
+    # We don't need extra documentation for error classes because of their
+    # extensive error messages.
+    # rubocop:disable Style/Documentation
+
+    class ConfigurationFileMissing < Error
+      def initialize
+        super("Configuration file not found")
+      end
+
+      def details
+        <<-MESSAGE
+active_record_doctor attempted to read a configuration file but could not find
+it. Please ensure the file exists and is readable (which includes correct
+permissions are set). If it does not exist or it's readable but you still get
+this error then consider filing a bug report as active_record_doctor should
+not attempt to load non-existent configuration files.
+        MESSAGE
+      end
+    end
+
+    class ConfigurationError < Error
+      def initialize(exc)
+        @exc = exc
+        super("Loading the configuration file resulted in an exception")
+      end
+
+      def details
+        <<-MESSAGE
+The information below comes from the exception raised when the configuration
+file was being evaluated. Please try using the details below to fix the error
+and retry.
+
+Error class:
+#{@exc.class.name}
+
+Error message:
+#{@exc.message}
+
+Backtrace:
+#{@exc.backtrace.join("\n")}
+        MESSAGE
+      end
+    end
+
+    class ConfigureNotCalled < Error
+      def initialize
+        super("The configuration file did not call ActiveRecordDoctor.configuration")
+      end
+
+      def details
+        <<-MESSAGE
+active_record_doctor configuration is a Ruby script that MUST call
+ActiveRecordDoctor.configuration exactly once. That method was NOT called by
+the configuration file in use. If you intend to provide custom configuration
+then please ensure that method is called. Otherwise, please delete the
+configuration file.
+        MESSAGE
+      end
+    end
+
+    class ConfigureCalledTwice < Error
+      def initialize
+        super("The configuration file called ActiveRecordDoctor.configuration multiple times")
+      end
+
+      def details
+        <<-MESSAGE
+The configuration file in use has called ActiveRecordDoctor.configure more than
+once but should do so EXACTLY ONCE. Please ensure that method is called exactly
+once and retry.
+        MESSAGE
+      end
+    end
+
+    class DetectorConfiguredTwice < Error
+      def initialize(detector)
+        super("Detector #{detector} was configured multiple times")
+      end
+
+      def details
+        <<-MESSAGE
+The configuration file configured the same detector more than once which is
+disallowed. Detector configuration should be either:
+
+- absent - to use the defaults
+- present exactly once - to override the defaults
+
+Please ensure the detector is configured at most once and retry.
+        MESSAGE
+      end
+    end
+
+    class UnrecognizedDetectorName < Error
+      def initialize(detector, recognized_detectors)
+        @recognized_detectors = recognized_detectors
+        super("Received configuration for an unrecognized detector named #{detector}")
+      end
+
+      def details
+        <<-MESSAGE
+The configuration file provided configuration for an unknown detector. Please
+ensure only valid detector names are used and retry.
+
+Currently, the following detectors are recognized:
+
+#{hyphenated_list(@recognized_detectors)}
+        MESSAGE
+      end
+    end
+
+    class UnrecognizedDetectorSettings < Error
+      def initialize(detector, unrecognized_settings, recognized_settings)
+        @detector = detector
+        @unrecognized_settings = unrecognized_settings
+        @recognized_settings = recognized_settings
+        super("Detector #{detector} received unrecognized settings")
+      end
+
+      def details
+        <<-MESSAGE
+The configuration file provided an unrecognized setting for a detector. Please
+ensure only recognized settings are used and retry.
+
+The following settings are not recognized by #{@detector}:
+
+#{hyphenated_list(@unrecognized_settings)}
+
+The complete of settings recognized by #{@detector} is:
+
+#{hyphenated_list(@recognized_settings)}
+        MESSAGE
+      end
+    end
+
+    class UnrecognizedGlobalSetting < Error
+      def initialize(name, recognized_settings)
+        @recognized_settings = recognized_settings
+        super("Global #{name} is unrecognized")
+      end
+
+      def details
+        <<-MESSAGE
+The configuration file set an unrecognized global setting. Please ensure that
+only recognized global settings are used and retry.
+
+Currently recognized global settings are:
+
+#{hyphenated_list(@recognized_settings)}
+        MESSAGE
+      end
+    end
+
+    class DuplicateGlobalSetting < Error
+      def initialize(name)
+        super("Global #{name} was set twice")
+      end
+
+      def details
+        <<-MESSAGE
+The configuration file set the same global setting twice. Each global setting
+must be set AT MOST ONCE. Please ensure all global settings are set at most once
+and retry.
+        MESSAGE
+      end
+    end
+
+    # rubocop:enable Style/Documentation
+  end
+end

data/lib/active_record_doctor/help.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ActiveRecordDoctor
+  # Turn a detector class into a human-readable help text.
+  class Help
+    def initialize(klass)
+      @klass = klass
+    end
+
+    def to_s
+      <<-HELP
+#{klass.underscored_name} - #{klass.description}
+
+Configuration options:
+#{config_to_s}
+      HELP
+    end
+
+    private
+
+    attr_reader :klass
+
+    GLOBAL_COMMENT = "local and global"
+    LOCAL_COMMENT = "local only"
+
+    def config_to_s
+      klass.config.map do |key, metadata|
+        type =
+          if metadata[:global]
+            GLOBAL_COMMENT
+          else
+            LOCAL_COMMENT
+          end
+
+        "  - #{key} (#{type}) - #{metadata.fetch(:description)}"
+      end.join("\n")
+    end
+  end
+end

data/lib/active_record_doctor/rake/task.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "rake/tasklib"
+
+module ActiveRecordDoctor
+  module Rake
+    # A Rake task for calling active_record_doctor detectors.
+    #
+    # The three supported attributes are:
+    #
+    #   - deps - project-specific Rake dependencies, e.g. :environment in Rails.
+    #   - config_path - active_record_doctor configuration file path.
+    #   - setup - a callable (responding to #call) responsible for finishing.
+    #     the setup process after deps are invoked, e.g. preloading models.
+    #
+    # The dependencies between Rake tasks are:
+    #
+    #    active_record_doctor:<detector> => active_record_doctor:setup => <deps>
+    #
+    # active_record_doctor:setup is where the setup callable is called.
+    class Task < ::Rake::TaskLib
+      attr_accessor :deps, :config_path, :setup
+
+      def initialize
+        super
+
+        @deps = []
+        @config_path = nil
+        @setup = nil
+
+        yield(self)
+
+        define
+      end
+
+      def define
+        namespace :active_record_doctor do
+          task :setup => deps do
+            @setup&.call
+            config
+          end
+
+          ActiveRecordDoctor.detectors.each do |name, detector|
+            desc detector.description
+            task name => :"active_record_doctor:setup" do
+              runner.run_one(name) or exit(1)
+            end
+
+            namespace name do
+              desc "Show help for #{name}"
+              task :help => :"active_record_doctor:setup" do
+                runner.help(name)
+              end
+            end
+          end
+        end
+
+        desc "Run all active_record_doctor detectors"
+        task :active_record_doctor => :"active_record_doctor:setup" do
+          runner.run_all or exit(1)
+        end
+      end
+
+      private
+
+      def runner
+        @runner ||= ActiveRecordDoctor::Runner.new(config)
+      end
+
+      def config
+        @config ||= begin
+          path = config_path && File.exist?(config_path) ? config_path : nil
+          ActiveRecordDoctor.load_config_with_defaults(path)
+        end
+      end
+    end
+  end
+end

data/lib/active_record_doctor/runner.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ActiveRecordDoctor # :nodoc:
+  # An excecution environment for active_record_doctor that provides a config
+  # and an output device for use by detectors.
+  class Runner
+    # io is injected via constructor parameters to facilitate testing.
+    def initialize(config, io = $stdout)
+      @config = config
+      @io = io
+    end
+
+    def run_one(name)
+      ActiveRecordDoctor.handle_exception do
+        ActiveRecordDoctor.detectors.fetch(name).run(config, io)
+      end
+    end
+
+    def run_all
+      success = true
+
+      # We can't use #all? because of its short-circuit behavior - it stops
+      # iteration and returns false upon the first falsey value. This
+      # prevents other detectors from running if there's a failure.
+      ActiveRecordDoctor.detectors.each do |name, _|
+        success = false if !run_one(name)
+      end
+
+      success
+    end
+
+    def help(name)
+      detector = ActiveRecordDoctor.detectors.fetch(name)
+      io.puts(ActiveRecordDoctor::Help.new(detector))
+    end
+
+    private
+
+    attr_reader :config, :io
+  end
+end

data/lib/active_record_doctor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveRecordDoctor
-  VERSION = "1.8.0"
+  VERSION = "1.10.0"
 end

data/lib/active_record_doctor.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "active_record_doctor/printers"
-require "active_record_doctor/printers/io_printer"
 require "active_record_doctor/railtie" if defined?(Rails) && defined?(Rails::Railtie)
 require "active_record_doctor/detectors"
 require "active_record_doctor/detectors/base"
@@ -9,14 +7,21 @@ require "active_record_doctor/detectors/missing_presence_validation"
 require "active_record_doctor/detectors/missing_foreign_keys"
 require "active_record_doctor/detectors/missing_unique_indexes"
 require "active_record_doctor/detectors/incorrect_boolean_presence_validation"
+require "active_record_doctor/detectors/incorrect_length_validation"
 require "active_record_doctor/detectors/extraneous_indexes"
 require "active_record_doctor/detectors/unindexed_deleted_at"
 require "active_record_doctor/detectors/undefined_table_references"
 require "active_record_doctor/detectors/missing_non_null_constraint"
 require "active_record_doctor/detectors/unindexed_foreign_keys"
 require "active_record_doctor/detectors/incorrect_dependent_option"
-require "active_record_doctor/task"
+require "active_record_doctor/detectors/short_primary_key_type"
+require "active_record_doctor/detectors/mismatched_foreign_key_type"
+require "active_record_doctor/errors"
+require "active_record_doctor/help"
+require "active_record_doctor/runner"
 require "active_record_doctor/version"
+require "active_record_doctor/config"
+require "active_record_doctor/config/loader"
 
 module ActiveRecordDoctor # :nodoc:
 end