schema_reaper 1.0.15 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b327fade324c6f2e9a871da57ae46814c1b077a1aca3aec64ca6681f270ffe6
-  data.tar.gz: d63156d86d7dc44e92204475c3d23ffa7e6b87730d0a436dc9aefd041ea8b843
+  metadata.gz: 27824319f6c1b0a06c833b1de1e6c9f627f042964f12920083899aebea81c3ee
+  data.tar.gz: 4a5a7b872774fbb6a4fad373206baa54878d2a1bf77e31f8d24232a45e8e65cb
 SHA512:
-  metadata.gz: cb3fe82c18f9f198ec544089305b183f2a413123093edd6f437a04c8d0b32879c123d1e4d1c338a1e03539a8eb16847406bb21f4eab5932ed6b4aba4fcdf461e
-  data.tar.gz: 1c1cf99e43ff66383f5b3bb0c42d5cfec209cbc8dab3bb986e734b6dcf75706c5ed1ecbf09d61f116ce2883957630f0ceeff7a102fb49793fe73cd93cd8283ad
+  metadata.gz: 95bfcabf3a810c80deab66508b5f75c04df8149f15e5d134c2977749a893b01e1ba5f471c9774dddad2d431dbe26e6178bb348d973c370b99bdb42f5e1249c18
+  data.tar.gz: 95f99230df34ab0f09f2ccf713552cf02c513d6c67d27715224283d2af107c60d0929c01a102232c468774766f644f1c831ed97db39d61675591a1aa4032244d

data/.rubocop.yml

@@ -44,7 +44,7 @@ Metrics/MethodLength:
   Max: 20
 
 Metrics/ClassLength:
-  Max: 130
+  Max: 135
 
 Metrics/CyclomaticComplexity:
   Max: 12

data/CHANGELOG.md

@@ -1,5 +1,101 @@
 # Changelog
 
+## [2.0.0] - 2026-09-23
+
+### Added
+- **`rails generate schema_reaper:install`** — one-time setup for running
+  `schema_reaper` unattended in production, with zero ongoing DevOps
+  dependency: a scheduled scan, results delivered automatically, and an
+  on-demand manual trigger, none of it gated behind infrastructure a given
+  project may not have (Slack, a CI pipeline with prod network access,
+  etc.).
+  - `SchemaReaper::AlertConfig` / `config/initializers/schema_reaper.rb` —
+    where reports go (`emails`, `webhook_url`). Plain committed config, not
+    secrets; commented out by default so an unfilled-in initializer is a
+    safe no-op.
+  - `SchemaReaper::Notifier` — delivers a scan's findings through whichever
+    channels are configured. Both fire when both are set (two audiences —
+    a dev-facing chat channel and a formal inbox record — not a fallback
+    chain). Webhook: a Slack-compatible `{"text": ...}` POST, with a 10s
+    timeout so a dead host can't hang a queue worker indefinitely. Email:
+    reuses the host app's own ActionMailer setup via `SchemaReaper::Mailer`
+    (inherits `ApplicationMailer` when the host app defines one, falls back
+    to a placeholder `default from:` otherwise so delivery degrades to a
+    normal SMTP rejection instead of a hard crash). Delivery failures are
+    logged, never raised, so a flaky endpoint can't fail the scan job.
+  - `SchemaReaper::ScanJob` / `rake schema_reaper:alert` — the one job both
+    the schedule and the manual trigger enqueue.
+  - Generated `app/controllers/schema_reaper_controller.rb` + a route for
+    the manual trigger — bearer-token protected via
+    `Rails.application.credentials` (decrypted with the `RAILS_MASTER_KEY`
+    every Rails app already has, so this introduces zero new production
+    configuration), checked with `ActiveSupport::SecurityUtils
+    .secure_compare`, and a shared 5-minute cooldown via `Rails.cache` so a
+    valid or leaked token can't be POSTed repeatedly to stack up scans
+    against production.
+  - A schedule entry in whichever of `config/schedule.rb` (`whenever`) or
+    `config/schedule.yml` (`sidekiq-cron`) the app's `Gemfile.lock` says it
+    has; prints manual instructions instead of guessing when neither gem is
+    present. Warns at install time if the Gemfile scopes `schema_reaper` to
+    `group: :development` (most production deploy pipelines strip dev/test
+    groups) or if no `ApplicationMailer` `default from:` is detected (email
+    reports would otherwise silently never arrive).
+  - Re-running the generator is safe — every step checks for its own
+    marker before writing, so nothing gets duplicated.
+
+  CI/SARIF stays a separate, already-documented path for PR/staging checks
+  — this is for production, where GitHub-hosted runners don't have prod
+  network access by default.
+
+  Verified against a real booted `Rails::Application` (not just specs):
+  the manual-trigger endpoint correctly rejects requests without hitting
+  Rails' CSRF protection, a valid token enqueues and a second one within
+  the cooldown 429s without enqueuing twice, and wrong-token requests
+  during the cooldown still 401 rather than being masked by the lock.
+  Reviewed by @aksshatt; three follow-up findings (a stale doc comment, the
+  mailer `from:` gap, and the missing rate limit) addressed and verified
+  the same way. (#20, mitkush)
+
+## [1.0.16] - 2026-09-22
+
+### Fixed
+- **A bare index on a polymorphic `*_id` column alone silently suppressed the
+  `missing_fk_index` finding it should have raised.** The check tested the
+  generic "is this column indexed at all" before checking whether the column
+  was part of a polymorphic pair, so an index on `commentable_id` by itself
+  — never sufficient, since Rails always queries the pair together — read as
+  "covered" and the analyzer's own doc comment went unenforced. Now gates on
+  the composite `(type, id)` check whenever a `*_type` column is present.
+  (#17, mitkush)
+- **`Postgres#indexes_for` was the one introspection query missing the
+  `public`-schema filter** every sibling query (`columns_for`,
+  `foreign_keys_for`, `table_names`) already has. In a database with more
+  than one schema containing a same-named table, it could pull in and union
+  indexes from the wrong table. Verified live against a two-schema database
+  with a colliding table name and a planted bogus index. (#17, mitkush)
+- **The `SCHEMA_REAPER_TRACK=1` runtime-tracker initializer could crash a
+  host app's entire boot**, not just disable the optional feature, on a
+  malformed `.schema_reaper.yml` or an unwritable log directory — nothing
+  in the initializer was rescued. Now rescues and logs a warning instead.
+  (#18, mitkush)
+- **`schema_reaper scan --format json` could not distinguish a genuinely
+  zero-byte reclaim estimate from an unmeasured one.** `Finding#to_h` read
+  the zero-defaulted accessor instead of the raw value, silently flattening
+  "unknown" into `0` for every CI/tooling consumer of the JSON output, even
+  though every other reporter already preserves that distinction. The
+  payload now carries the raw value plus an explicit `reclaim_known` flag.
+  Verified live: an unmeasured finding now serializes `reclaimable_bytes`
+  as `null` with `reclaim_known: false`. (#18, mitkush)
+- **A query-time Postgres error (anything past the initial connection)
+  propagated as a raw `PG::Error`** instead of the wrapped `SchemaReaper::Error`
+  every other failure path produces, leaking a Ruby backtrace instead of a
+  clean CLI error message. `primary_key_for`'s existing fallback-to-nil
+  rescue is updated to match. (#18, mitkush)
+- Cosmetic: `MigrationGenerator#model` mangled irregular plural table names
+  (`addresses` → "Addresse") in the generated migration's comment text;
+  `Reporters::Trend#bytes` printed `-0.0 B` instead of `+0.0 B` for a zero
+  delta. (#17, mitkush)
+
 ## [1.0.15] - 2026-09-18
 
 ### Fixed

data/lib/generators/schema_reaper/install/install_generator.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "securerandom"
+
+module SchemaReaper
+  module Generators
+    # `rails generate schema_reaper:install` -- one-time setup for unattended
+    # production scanning: an initializer for where reports go, a scheduled
+    # job (whenever or sidekiq-cron, whichever the app already uses), and a
+    # token-protected manual-trigger route. See the plan this implements:
+    # production automation with zero ongoing DevOps dependency -- a normal
+    # `git commit` + deploy is the only step after this generator runs.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/schema_reaper.rb"
+      end
+
+      def create_manual_trigger
+        template "schema_reaper_controller.rb.tt", "app/controllers/schema_reaper_controller.rb"
+
+        # `route` (unlike `template`/`create_file`) has no conflict
+        # detection of its own -- it unconditionally injects, so re-running
+        # this generator would duplicate the line every time without this
+        # guard.
+        routes_path = File.join(destination_root, "config/routes.rb")
+        if File.exist?(routes_path) && File.read(routes_path).include?("schema_reaper#trigger")
+          say_status :skip, "config/routes.rb already routes to schema_reaper#trigger -- not duplicating it", :yellow
+        else
+          route "post '/internal/schema_scan', to: 'schema_reaper#trigger'"
+        end
+      end
+
+      def add_schedule
+        case detected_scheduler
+        when :whenever then add_whenever_schedule
+        when :sidekiq_cron then add_sidekiq_cron_schedule
+        else
+          say_status :skip, "no `whenever` or `sidekiq-cron` gem detected -- add a cron entry yourself " \
+                            "that runs `rake schema_reaper:alert` on whatever cadence you want", :yellow
+        end
+      end
+
+      def warn_if_dev_scoped
+        return unless gemfile_scopes_schema_reaper_to_dev?
+
+        say_status :warning,
+                   "schema_reaper is Gemfile-scoped to group: :development. Most production deploy " \
+                   "pipelines strip dev/test groups (`bundle install --without development test`), so " \
+                   "the scheduled scan will not run in production until you remove that restriction.",
+                   :red
+      end
+
+      def warn_if_no_mailer_from
+        return if mailer_from_configured?
+
+        say_status :warning,
+                   "no ApplicationMailer default `from:` detected. SchemaReaper::Mailer falls back to a " \
+                   "placeholder sender in that case, which most real SMTP relays reject or spam-flag -- " \
+                   "email reports would silently fail to arrive. If you plan to use the email channel " \
+                   "(config.emails in the initializer this generator just wrote), set " \
+                   "`default from: \"...\"` on ApplicationMailer first.",
+                   :red
+      end
+
+      def print_token_instructions
+        token = "#{app_identifier}-#{SecureRandom.hex(32)}"
+
+        say ""
+        say "Manual trigger token (shown once -- store it now):", :green
+        say "  #{token}"
+        say ""
+        say "This is genuinely sensitive (it authorizes a production action), so it does not go in a " \
+            "committed file. Store it in encrypted credentials instead:"
+        say ""
+        say "  rails credentials:edit"
+        say ""
+        say "and add:"
+        say ""
+        say "  schema_reaper:"
+        say "    trigger_token: #{token}"
+        say ""
+        say "Trigger a scan on demand with:"
+        say ""
+        say "  curl -X POST https://your-app.example.com/internal/schema_scan \\"
+        say "    -H \"Authorization: Bearer #{token}\""
+        say ""
+      end
+
+      private
+
+      def detected_scheduler
+        return :whenever if gem_locked?("whenever")
+        return :sidekiq_cron if gem_locked?("sidekiq-cron")
+
+        nil
+      end
+
+      def gem_locked?(name)
+        Bundler.locked_gems&.specs&.any? { |s| s.name == name } || false
+      rescue StandardError
+        false
+      end
+
+      def add_whenever_schedule
+        path = "config/schedule.rb"
+        marker = 'rake "schema_reaper:alert"'
+        entry = <<~RUBY
+
+          every 3.months do
+            #{marker}
+          end
+        RUBY
+
+        full_path = File.join(destination_root, path)
+        if File.exist?(full_path) && File.read(full_path).include?(marker)
+          say_status :skip, "#{path} already has a schema_reaper entry -- not duplicating it", :yellow
+        elsif File.exist?(full_path)
+          append_to_file path, entry
+        else
+          # No `require "whenever"` here -- real wheneverize-generated files
+          # don't have one; whenever's own CLI evaluates this file through
+          # its DSL, not as a plain script that needs to load itself.
+          create_file path, entry.sub("\n\n", "")
+        end
+      end
+
+      def add_sidekiq_cron_schedule
+        path = "config/schedule.yml"
+        marker = "schema_reaper_scan:"
+        entry = <<~YAML
+
+          #{marker}
+            cron: "0 4 1 */3 *" # 4am on the 1st, every 3 months
+            class: "SchemaReaper::ScanJob"
+            queue: default
+            active_job: true # explicit, not relying on class-ancestry auto-detection
+        YAML
+
+        full_path = File.join(destination_root, path)
+        if File.exist?(full_path) && File.read(full_path).include?(marker)
+          say_status :skip, "#{path} already has a schema_reaper_scan entry -- not duplicating it", :yellow
+        elsif File.exist?(full_path)
+          append_to_file path, entry
+        else
+          create_file path, entry.sub("\n\n", "")
+        end
+      end
+
+      # `gem "schema_reaper", group: :development` (or the equivalent
+      # `group :development do ... end` block form) in the app's own Gemfile
+      # -- see README's current install snippet. A dev-scoped gem is absent
+      # from `bundle install --without development test`, which most
+      # production deploy pipelines run, so the scheduled scan silently
+      # never runs.
+      #
+      # Parsed with Bundler's own DSL rather than line-scanning for
+      # "group: :development" -- a regex over raw lines misses the block
+      # form entirely (the gem's own line never mentions :development; the
+      # `group :development do` line above it does), and that block form is
+      # the more common style in practice, not an edge case.
+      def gemfile_scopes_schema_reaper_to_dev?
+        gemfile = File.join(destination_root, "Gemfile")
+        return false unless File.exist?(gemfile)
+
+        dep = Bundler::Dsl.evaluate(gemfile, nil, {}).dependencies.find { |d| d.name == "schema_reaper" }
+        dep && !dep.groups.include?(:default)
+      rescue StandardError
+        false # a Gemfile we can't parse shouldn't block the rest of the generator
+      end
+
+      # Checked against ApplicationMailer specifically, not SchemaReaper::Mailer
+      # -- at generate time the app is already booted (ActionMailer, and
+      # ApplicationMailer if the app has one, are loaded), so this reads the
+      # same `default_params[:from]` chain SchemaReaper::Mailer itself will
+      # inherit from once it's loaded.
+      def mailer_from_configured?
+        return false unless defined?(::ApplicationMailer) # no mailer to inherit from at all
+
+        ::ApplicationMailer.default_params[:from].present?
+      rescue StandardError
+        true # can't determine -- don't nag over something we're unsure about
+      end
+
+      def app_identifier
+        Rails.application.class.module_parent_name.underscore
+      rescue StandardError
+        "app"
+      end
+    end
+  end
+end

data/lib/generators/schema_reaper/install/templates/initializer.rb.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# schema_reaper production automation.
+#
+# Neither of these is a secret -- leaking a teammate's email address or a
+# webhook URL isn't a meaningful security event -- so this file is meant to
+# be committed to git directly. The manual-trigger token is not: see the
+# instructions `rails generate schema_reaper:install` printed for that one
+# (it lives in Rails.application.credentials, not here).
+#
+# Uncomment and fill in at least one of these to start receiving reports.
+# Both fire on every scheduled run when both are set -- this isn't a
+# fallback, it's two audiences: a dev-facing chat channel and a formal inbox
+# record for people who don't watch chat.
+SchemaReaper::AlertConfig.configure do |config|
+  # config.emails = %w[dev1@example.com dev2@example.com]
+  # config.webhook_url = "https://hooks.slack.com/services/T000/B000/XXXX"
+end

data/lib/generators/schema_reaper/install/templates/schema_reaper_controller.rb.tt

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# Manual, on-demand trigger for the production schema_reaper scan -- enqueues
+# the exact same job the schedule uses, so there is one code path to keep
+# correct. Protected by a bearer token stored in encrypted credentials
+# (config/credentials.yml.enc, key schema_reaper.trigger_token) rather than a
+# DevOps-provisioned ENV var -- every Rails app already has the
+# RAILS_MASTER_KEY needed to decrypt it, so this introduces zero new
+# production configuration.
+#
+# Trigger it with (the token is printed once by the install generator --
+# store it somewhere your team can find it, e.g. a password manager. It is
+# deliberately NOT embedded in the scheduled report itself: that report goes
+# to Slack/email, and a bearer token that authorizes a production action
+# doesn't belong in either):
+#
+#   curl -X POST https://your-app.example.com/internal/schema_scan \
+#     -H "Authorization: Bearer <token>"
+class SchemaReaperController < ActionController::Base
+  # This is a token-authenticated API endpoint, not a session-backed form --
+  # Rails' CSRF protection is meant for the latter. Deliberately does NOT
+  # inherit from ::ApplicationController, and explicitly skips the
+  # authenticity-token check (`raise: false` so this doesn't itself blow up
+  # on an app where default_protect_from_forgery is off and the callback was
+  # never registered). Without this, a plain curl POST is rejected with
+  # ActionController::InvalidAuthenticityToken before the token check below
+  # even runs -- Rails wires `protect_from_forgery with: :exception` onto
+  # ActionController::Base itself for every app using Rails' post-5.2
+  # defaults, so every subclass inherits it, this one included.
+  skip_before_action :verify_authenticity_token, raise: false
+
+  # A valid (or leaked) token could otherwise be POSTed repeatedly, each hit
+  # enqueueing a full schema introspection against production. This is not
+  # per-caller rate limiting -- it's a single shared cooldown so a burst of
+  # triggers (accidental double-click, a leaked token being hammered) can't
+  # stack up scans faster than they can plausibly be useful. Rails.cache is
+  # whatever the app already has configured; on the default NullStore (no
+  # caching configured at all) this is a no-op, same as before this guard
+  # existed -- configure a real cache store to get actual protection.
+  TRIGGER_COOLDOWN = 5.minutes
+
+  def trigger
+    return head(:unauthorized) unless token_valid?
+    return head(:too_many_requests) unless acquire_trigger_lock
+
+    SchemaReaper::ScanJob.perform_later
+    head :accepted
+  end
+
+  private
+
+  def acquire_trigger_lock
+    Rails.cache.write("schema_reaper:manual_trigger_lock", true, unless_exist: true, expires_in: TRIGGER_COOLDOWN)
+  end
+
+  def token_valid?
+    expected = Rails.application.credentials.dig(:schema_reaper, :trigger_token)
+    return false if expected.blank?
+
+    provided = request.headers["Authorization"].to_s.delete_prefix("Bearer ").strip
+    return false if provided.empty?
+
+    ActiveSupport::SecurityUtils.secure_compare(provided, expected)
+  rescue ActiveSupport::EncryptedFile::MissingKeyError, ActiveSupport::MessageEncryptor::InvalidMessage
+    # RAILS_MASTER_KEY absent or credentials undecryptable in this
+    # environment -- fail closed (unauthorized), don't 500.
+    false
+  end
+end

data/lib/schema_reaper/alert_config.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module SchemaReaper
+  # Where the production scan's report goes. Set once from a Rails
+  # initializer (config/initializers/schema_reaper.rb), typically written by
+  # `rails generate schema_reaper:install`:
+  #
+  #   SchemaReaper::AlertConfig.configure do |config|
+  #     config.emails = %w[dev1@example.com dev2@example.com]
+  #     config.webhook_url = "https://hooks.slack.com/services/T000/B000/XXXX"
+  #   end
+  #
+  # Neither field is a secret -- leaking a teammate's email address or a
+  # webhook URL isn't a meaningful security event -- so this is meant to be
+  # committed to git directly. The manual-trigger token is not: that one
+  # lives in Rails.application.credentials (see the install generator).
+  class AlertConfig
+    class << self
+      def configure
+        yield instance
+      end
+
+      def instance
+        @instance ||= new
+      end
+
+      # Test helper -- config set in one example must not leak into the next.
+      def reset!
+        @instance = new
+      end
+    end
+
+    attr_accessor :emails, :webhook_url
+
+    def initialize
+      @emails = []
+      @webhook_url = nil
+    end
+
+    def emails?
+      !emails.to_a.empty?
+    end
+
+    def webhook?
+      !webhook_url.to_s.strip.empty?
+    end
+
+    # Whether Notifier has anywhere to send a report. A generator-scaffolded
+    # but unfilled-in config (both fields left commented out) is a safe
+    # no-op, not an error.
+    def configured?
+      emails? || webhook?
+    end
+  end
+end

data/lib/schema_reaper/analyzers/missing_fk_index.rb

@@ -32,11 +32,15 @@ module SchemaReaper
 
       def missing_in(table)
         fk_columns(table).filter_map do |col|
-          next if indexed?(table, col)
-          next if empty_column?(table, col) # never advise indexing a column with no data
-
           type_col = polymorphic_type_for(table, col)
-          next if type_col && polymorphic_indexed?(table, type_col, col)
+
+          # A bare index on the id alone doesn't cover a polymorphic pair --
+          # only the composite (type, id) index satisfies it. Check that
+          # instead of the generic `indexed?`, or a bare id-only index would
+          # wrongly suppress this finding.
+          covered = type_col ? polymorphic_indexed?(table, type_col, col) : indexed?(table, col)
+          next if covered
+          next if empty_column?(table, col) # never advise indexing a column with no data
 
           finding_for(table, col, type_col, declared: table.foreign_keys.include?(col))
         end

data/lib/schema_reaper/finding.rb

@@ -50,8 +50,12 @@ module SchemaReaper
       parts.empty? ? nil : parts.join(" · ")
     end
 
+    # Keeps the raw (possibly nil) reclaimable_bytes from Struct#to_h rather
+    # than the zero-defaulted accessor above, so JSON/SARIF consumers can tell
+    # "genuinely zero" apart from "unknown" the same way every other reporter
+    # does -- reclaim_known? makes that distinction explicit in the payload.
     def to_h
-      super.merge(id: id, reclaimable_bytes: reclaimable_bytes)
+      super.merge(id: id, reclaim_known: reclaim_known?)
     end
   end
 end

data/lib/schema_reaper/introspect/postgres.rb

@@ -8,13 +8,12 @@ module SchemaReaper
       AVG_TYPE_BYTES = {
         "boolean" => 1, "smallint" => 2, "integer" => 4, "bigint" => 8,
         "real" => 4, "double precision" => 8, "numeric" => 8,
-        "date" => 4, "timestamp without time zone" => 8,
-        "timestamp with time zone" => 8, "uuid" => 16
+        "date" => 4, "timestamp without time zone" => 8, "timestamp with time zone" => 8, "uuid" => 16
       }.freeze
 
       NO_URL = "no database connection found. schema_reaper looks, in order, for: " \
-               "database_url: in .schema_reaper.yml; the DATABASE_URL env var; " \
-               "config/database.yml for RAILS_ENV (default: development, Postgres only)."
+               "database_url: in .schema_reaper.yml; the DATABASE_URL env var; config/database.yml " \
+               "for RAILS_ENV (default: development, Postgres only)."
 
       # A record separator that cannot appear inside a plain identifier and is
       # exceedingly unlikely inside an expression, so splitting the aggregated
@@ -119,7 +118,7 @@ module SchemaReaper
           JOIN pg_class i ON i.oid = ix.indexrelid
           JOIN LATERAL generate_series(1, ix.indnkeyatts) AS k(ord) ON TRUE
           LEFT JOIN pg_stat_user_indexes s ON s.indexrelid = i.oid
-          WHERE t.relname = $1
+          WHERE t.relname = $1 AND t.relnamespace = 'public'::regnamespace
           GROUP BY i.relname, ix.indisunique, ix.indisprimary, ix.indpred, s.idx_scan
         SQL
           Index.new(
@@ -142,7 +141,7 @@ module SchemaReaper
           WHERE i.indrelid = $1::regclass AND i.indisprimary
           ORDER BY k.ord
         SQL
-      rescue PG::Error
+      rescue Error, PG::Error
         nil
       end
 
@@ -172,6 +171,8 @@ module SchemaReaper
 
       def exec(sql, params = nil)
         (params ? @conn.exec_params(sql, params) : @conn.exec(sql)).to_a
+      rescue PG::Error => e
+        raise Error, "query against the database failed: #{e.message.strip}"
       end
     end
   end

data/lib/schema_reaper/mailer.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module SchemaReaper
+  # Inherits ApplicationMailer when the host app defines one (the normal
+  # case), so it picks up the app's own `default from:`, layout and delivery
+  # settings automatically -- "reuse the app's already-configured mailer,
+  # don't require a new SMTP setup" is the whole point of the email channel.
+  # Falls back to ActionMailer::Base directly for apps that don't.
+  class Mailer < (defined?(::ApplicationMailer) ? ::ApplicationMailer : ActionMailer::Base)
+    # Only applied when nothing upstream (ApplicationMailer or its own
+    # ancestors) already set one. Without this, `mail()` raises "SMTP From
+    # address may not be blank" -- and Notifier's rescue never sees it:
+    # deliver_later only enqueues, the actual render/from-validation happens
+    # later inside ActionMailer::MailDeliveryJob#perform, so an app that
+    # hits this path gets a bare, unbranded ActiveJob failure with no
+    # `[schema_reaper]` log line anywhere near it. This placeholder isn't a
+    # real deliverable address -- most SMTP relays will still reject or
+    # spam-flag mail from an unconfigured sender -- it only turns a hard
+    # crash into a normal delivery failure. The install generator warns at
+    # setup time when this fallback would apply, so the real fix (configure
+    # a `default from:`) doesn't have to be discovered from a stack trace.
+    default from: "schema_reaper@localhost" unless default_params[:from]
+
+    def report_email(to:, report:)
+      @report = report
+      mail(to: to, subject: "[schema_reaper] scan report") do |format|
+        format.text { render plain: @report }
+      end
+    end
+  end
+end

data/lib/schema_reaper/migration_generator.rb

@@ -5,6 +5,14 @@ require "fileutils"
 module SchemaReaper
   # Emits a two-step, reversible migration pair for a dead column.
   class MigrationGenerator
+    # Enough of Rails' inflector for table names in this comment text -- a
+    # wrong guess doesn't break anything functional, just reads oddly.
+    SINGULAR_RULES = [
+      [/ies\z/, "y"],               # activities -> activity
+      [/(ss|sh|ch|x|z)es\z/, '\1'], # addresses  -> address, boxes -> box
+      [/s\z/, ""]                   # employees  -> employee
+    ].freeze
+
     def initialize(table:, column:, dir: "db/migrate")
       @table = table
       @column = column
@@ -77,7 +85,12 @@ module SchemaReaper
     end
 
     def model
-      @table.split("_").map(&:capitalize).join.sub(/s$/, "")
+      singular.split("_").map(&:capitalize).join
+    end
+
+    def singular
+      rule = SINGULAR_RULES.find { |pattern, _| @table.match?(pattern) }
+      rule ? @table.sub(rule[0], rule[1]) : @table
     end
   end
 end

data/lib/schema_reaper/notifier.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "stringio"
+require_relative "reporters/markdown"
+
+module SchemaReaper
+  # Delivers a completed scan's findings through whichever channels are
+  # configured in AlertConfig -- a Slack-compatible webhook POST and/or email
+  # via the host app's own ActionMailer setup. Both fire when both are
+  # configured; this isn't a fallback chain (schema reports aren't critical
+  # enough to need one), it's reaching two different audiences: a dev-facing
+  # chat channel and a more formal inbox record for people who don't watch
+  # chat.
+  #
+  # Delivery failures are logged, never raised -- a webhook endpoint being
+  # briefly down should not fail the scan job or retry-storm it.
+  class Notifier
+    # `mailer:` defaults to :auto rather than nil so an explicit
+    # `mailer: nil` (forcing "no mailer available", e.g. to test that path,
+    # or because a caller genuinely wants email delivery skipped) is
+    # respected rather than silently falling back to the auto-detected
+    # SchemaReaper::Mailer via `||`.
+    def initialize(findings, config: AlertConfig.instance, http: Net::HTTP, mailer: :auto)
+      @findings = findings
+      @config = config
+      @http = http
+      @mailer = mailer == :auto ? default_mailer : mailer
+    end
+
+    def deliver
+      return unless @config.configured?
+
+      deliver_webhook if @config.webhook?
+      deliver_email if @config.emails?
+    end
+
+    private
+
+    def default_mailer
+      defined?(Mailer) ? Mailer : nil
+    end
+
+    def report_text
+      @report_text ||= begin
+        io = StringIO.new
+        Reporters::Markdown.new(@findings, io: io).render
+        io.string
+      end
+    end
+
+    # Slack's incoming-webhook shape ({"text": ...}) is the most common
+    # receiver in practice; Discord's legacy webhook path also accepts a
+    # plain "content" body but that's a different key, and structured-alert
+    # services like PagerDuty need an entirely different schema (their
+    # Events API v2, not a text webhook) -- those need a different endpoint,
+    # not this one.
+    def deliver_webhook
+      uri = URI.parse(@config.webhook_url)
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request.body = JSON.generate(text: report_text)
+
+      client = @http.new(uri.host, uri.port)
+      client.use_ssl = uri.scheme == "https"
+      # A background job blocking indefinitely on a dead webhook host would
+      # back up the queue behind it -- bound the wait instead of relying on
+      # Net::HTTP's own (version-dependent) defaults.
+      client.open_timeout = 10
+      client.read_timeout = 10
+      client.request(request)
+    rescue StandardError => e
+      log_error("webhook delivery failed", e)
+    end
+
+    def deliver_email
+      unless @mailer
+        log_error("email delivery skipped", "SchemaReaper::Mailer is not loaded (ActionMailer not present?)")
+        return
+      end
+
+      @mailer.report_email(to: @config.emails, report: report_text).deliver_later
+    rescue StandardError => e
+      log_error("email delivery failed", e)
+    end
+
+    def log_error(message, error)
+      detail = error.is_a?(Exception) ? "#{error.class}: #{error.message}" : error.to_s
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.error("[schema_reaper] #{message}: #{detail}")
+      else
+        warn("[schema_reaper] #{message}: #{detail}")
+      end
+    end
+  end
+end

data/lib/schema_reaper/railtie.rb

@@ -12,10 +12,17 @@ module SchemaReaper
     initializer "schema_reaper.runtime_tracker" do
       next unless ENV["SCHEMA_REAPER_TRACK"] == "1"
 
-      config = SchemaReaper::Config.load
-      store = SchemaReaper::Runtime::Store.new(path: config.runtime_log)
-      rate = (ENV["SCHEMA_REAPER_SAMPLE"] || "0.05").to_f
-      SchemaReaper::Runtime::Tracker.install!(store: store, sample_rate: rate)
+      begin
+        config = SchemaReaper::Config.load
+        store = SchemaReaper::Runtime::Store.new(path: config.runtime_log)
+        rate = (ENV["SCHEMA_REAPER_SAMPLE"] || "0.05").to_f
+        SchemaReaper::Runtime::Tracker.install!(store: store, sample_rate: rate)
+      rescue StandardError => e
+        # Optional instrumentation must never take the host app down with it --
+        # a bad config file or an unwritable log directory disables tracking,
+        # it does not abort boot.
+        Rails.logger&.warn("[schema_reaper] runtime tracker disabled: #{e.class}: #{e.message}")
+      end
     end
   end
 end

data/lib/schema_reaper/reporters/trend.rb

@@ -47,7 +47,7 @@ module SchemaReaper
 
       def bytes
         delta = @d[:bytes_change_total].to_i
-        sign = delta.positive? ? "+" : "-"
+        sign = delta.negative? ? "-" : "+"
         @c.row("reclaimable", Bytes.human(@d.fetch(:latest_bytes, 0)),
                "#{sign}#{Bytes.human(delta.abs)} since first run")
       end

data/lib/schema_reaper/scan_job.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module SchemaReaper
+  # Runs a scan and delivers the report through whatever channels AlertConfig
+  # has configured. Enqueued two ways: on the schedule an app generates via
+  # `rails generate schema_reaper:install` (whenever/sidekiq-cron), and
+  # on-demand by the generated manual-trigger controller -- same job either
+  # way, so there is exactly one code path to keep correct.
+  class ScanJob < ActiveJob::Base
+    queue_as :default
+
+    def perform
+      findings = Runner.new.run
+      Notifier.new(findings).deliver
+    end
+  end
+end

data/lib/schema_reaper/tasks/schema_reaper.rake

@@ -23,4 +23,9 @@ namespace :schema_reaper do
     history.record(findings)
     pp history.trend
   end
+
+  desc "Enqueue the production scan+alert job (this is what the scheduled cron entry calls)"
+  task alert: :environment do
+    SchemaReaper::ScanJob.perform_later
+  end
 end

data/lib/schema_reaper/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SchemaReaper
-  VERSION = "1.0.15"
+  VERSION = "2.0.0"
 end

data/lib/schema_reaper.rb

@@ -29,6 +29,10 @@ require_relative "schema_reaper/baseline"
 require_relative "schema_reaper/history"
 require_relative "schema_reaper/migration_generator"
 require_relative "schema_reaper/runner"
+require_relative "schema_reaper/alert_config"
+require_relative "schema_reaper/notifier"
+require_relative "schema_reaper/mailer" if defined?(ActionMailer::Base)
+require_relative "schema_reaper/scan_job" if defined?(ActiveJob::Base)
 require_relative "schema_reaper/railtie" if defined?(Rails::Railtie)
 
 # Finds columns, indexes and tables that a Rails/ActiveRecord app no longer

data/schema_reaper.gemspec

@@ -47,6 +47,10 @@ Gem::Specification.new do |spec|
   spec.add_dependency "prism", ">= 0.19", "< 2.0"
   spec.add_dependency "thor", "~> 1.3"
 
+  spec.add_development_dependency "actionmailer", ">= 6.1", "< 9.0"
+  spec.add_development_dependency "activejob", ">= 6.1", "< 9.0"
   spec.add_development_dependency "activerecord", ">= 6.1", "< 9.0"
   spec.add_development_dependency "pg", "~> 1.5"
+  spec.add_development_dependency "railties", ">= 6.1", "< 9.0"
+  spec.add_development_dependency "simplecov", "~> 0.22"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schema_reaper
 version: !ruby/object:Gem::Version
-  version: 1.0.15
+  version: 2.0.0
 platform: ruby
 authors:
 - aksshatt
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -45,6 +45,46 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
@@ -79,6 +119,40 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
 description: |-
   schema_reaper scans a Rails + PostgreSQL app for schema debt that's easy to accumulate and hard to find by hand.
 
@@ -108,7 +182,11 @@ files:
 - RELEASE_CHECKLIST.md
 - Rakefile
 - exe/schema_reaper
+- lib/generators/schema_reaper/install/install_generator.rb
+- lib/generators/schema_reaper/install/templates/initializer.rb.tt
+- lib/generators/schema_reaper/install/templates/schema_reaper_controller.rb.tt
 - lib/schema_reaper.rb
+- lib/schema_reaper/alert_config.rb
 - lib/schema_reaper/analyzers/always_null_column.rb
 - lib/schema_reaper/analyzers/base.rb
 - lib/schema_reaper/analyzers/dead_column.rb
@@ -126,7 +204,9 @@ files:
 - lib/schema_reaper/gem_awareness.rb
 - lib/schema_reaper/history.rb
 - lib/schema_reaper/introspect/postgres.rb
+- lib/schema_reaper/mailer.rb
 - lib/schema_reaper/migration_generator.rb
+- lib/schema_reaper/notifier.rb
 - lib/schema_reaper/railtie.rb
 - lib/schema_reaper/reporters/ansi.rb
 - lib/schema_reaper/reporters/bytes.rb
@@ -140,6 +220,7 @@ files:
 - lib/schema_reaper/reporters/trend.rb
 - lib/schema_reaper/runner.rb
 - lib/schema_reaper/runtime.rb
+- lib/schema_reaper/scan_job.rb
 - lib/schema_reaper/schema.rb
 - lib/schema_reaper/static/scanner.rb
 - lib/schema_reaper/tasks/schema_reaper.rake