schema_reaper 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89431a69d7cd997b743e0a7996ce1bae64244946dbea4d0683f8beb477ad1498
-  data.tar.gz: d43309fe35f2f6b4c669e21413c300997fdabf03f3d77f3295a6742de5f3cea2
+  metadata.gz: 65c5a4cc1857d1fbf940b5907cbb7d8e48de74cebb7b69eb6dd1b8e2a0c26bfa
+  data.tar.gz: 679e01d41a797c37dfd94858464127b1ce8789bda1d92cb905f011a2369fe1c8
 SHA512:
-  metadata.gz: 6d2c527fc15a64ce62680a96a989c1ba0fbda445fd216afe590dd95e3344b1a8c2ef271a102eed01626b1cac1b0e9400874c8cc177f71d1d27efa32fda79e6fb
-  data.tar.gz: 777a1561b89af7d5795a326d9c30d6764190b14f6a3dbb1af5f22d2fb525f3959d73e2f3beaa25262a9508f94958a1c1cad42d908f879855f1643f0206bc1208
+  metadata.gz: ef8476dfea36578ef5c97c43fc97c7334371ce38aa14f0d736028d57e42d370b43363922511676af417d76f5fd9b9b35536e98168253efc9c6a663230c56d8c6
+  data.tar.gz: cf4f22deed425352ac3d0553deefb34495e4c234170f402167866fa445b4b4bf707fc3d078a3a612fc99477ed39b9c152f96f4cdfb45555ecfa7a0eaaab9cd82

data/.rubocop.yml

@@ -31,6 +31,7 @@ Metrics/BlockLength:
     - "*.gemspec"
 
 Metrics/ParameterLists:
+  CountKeywordArgs: false # keyword args name themselves at every call site
   Exclude:
     - "spec/**/*"
 
@@ -45,6 +46,8 @@ Metrics/MethodLength:
 
 Metrics/ClassLength:
   Max: 135
+  Exclude:
+    - "lib/schema_reaper/introspect/postgres.rb" # mostly SQL heredocs, one per catalog query
 
 Metrics/CyclomaticComplexity:
   Max: 12

data/.schema_reaper.yml.example

@@ -2,6 +2,13 @@
 ---
 # database_url: postgres://localhost/myapp_development   # else ENV["DATABASE_URL"]
 
+# PostgreSQL schemas to scan. Tables outside public are reported as schema.table.
+schemas:
+  - public
+
+# Hide findings below this confidence on every command (the CLI flag overrides).
+min_confidence: 0.0
+
 scan_paths:
   - app
   - lib
@@ -33,11 +40,21 @@ gem_awareness: true
 
 # Runtime usage log written by the tracker (see README > Runtime signal).
 runtime_log: .schema_reaper/runtime.jsonl
+# Rotate it to runtime.jsonl.1 past this many bytes; both are read. null: never.
+runtime_log_max_bytes: 52428800
 
 # Append-only snapshot log for `schema_reaper trend`.
 history_log: .schema_reaper/history.jsonl
 
 baseline: .schema_reaper/baseline.json
 
+# Per-file cache of scan results; repeat scans re-parse only changed files.
+scan_cache: .schema_reaper/scan_cache.json
+
+# global: a column name anywhere in code counts as use on every table.
+# model:  a name only in an app/models file counts for that model's table and
+#         the tables it mentions. Stricter; review its findings before acting.
+column_scope: global
+
 # Extra Ruby files to load before analysis -- register custom analyzers here.
 require: []

data/CHANGELOG.md

@@ -1,5 +1,107 @@
 # Changelog
 
+## [2.1.0] - 2026-10-14
+
+### Fixed
+- **Introspection no longer mixes up same-named objects across schemas.**
+  Row counts were read from `pg_class` by name alone, foreign keys were joined
+  on constraint name alone (constraint names are only unique per table), and
+  the primary-key lookup resolved the table through `search_path`. All three
+  are now qualified by schema. Foreign keys are read from `pg_constraint`, so
+  composite keys keep their columns together.
+- **`ignore.columns` now applies to every column analyzer.** It was only
+  honoured by `dead_column`; `always_null_column`, `single_value_column` and
+  `missing_fk_index` ignored it.
+- **Partitioned tables are reported once, as the parent.** Each partition used
+  to appear as its own table -- and, unreferenced by name, got a `dead_table`
+  finding. The parent's row count is now summed from its partitions, and its
+  indexes' usage from the partitions' indexes, so `unused_index` no longer
+  flags every index on a partitioned table (PostgreSQL 12+).
+- **Stats-based findings say when they are estimates.** On tables larger than
+  ANALYZE's 30,000-row sample, `always_null_column` (0.85 -> 0.7) and
+  `single_value_column` (0.6 -> 0.5) lower their confidence and say so, and
+  `single_value_column` no longer claims "the same value in every row" for a
+  column that also holds NULLs.
+- **`missing_fk_index`** finds the referenced table in a non-public table's own
+  schema.
+- **Runtime `observed_days` no longer depends on line order.** Several
+  processes append to one log, so the span is now min..max timestamp rather
+  than first..last line.
+
+### Added
+- `schemas:` config key to scan PostgreSQL schemas besides `public`. Tables
+  outside `public` are reported as `schema.table`; `public` tables keep their
+  bare names, so existing baselines and ignore lists still match.
+- `sequence_exhaustion` analyzer (CYCLE and descending sequences excluded): a serial/IDENTITY sequence past 50% (medium)
+  or 75% (high) of its column type's range -- e.g. an `integer` key fed by a
+  bigint sequence.
+- `duplicate_foreign_key` analyzer: two FK constraints on the same columns
+  referencing the same key, with the same ON UPDATE / ON DELETE, MATCH and
+  deferrability (anything else changes behaviour when dropped). A validated
+  copy is kept over a NOT VALID one.
+- `--only` / `--except` to choose analyzers (custom ones included), and a
+  `min_confidence` config key used by every command.
+- `generate-migration TABLE --index NAME` (concurrent `remove_index` with
+  `disable_ddl_transaction!`; the migration checks at run time whether the
+  index is partitioned, which PostgreSQL can't drop concurrently, and drops it
+  plainly then) and `generate-migration TABLE` (`drop_table`). The
+  `unused_index` / `duplicate_index` fixes say the same for partitioned
+  indexes.
+- The runtime tracker also samples tables read by executed SQL (`track_sql:`,
+  on by default; FROM / JOIN / UPDATE, not INSERT targets, so a write-only
+  table can still be found), so a table read only through raw SQL isn't
+  reported dead.
+- The runtime log rotates to `<path>.1` past `runtime_log_max_bytes` (default
+  50 MB), under a file lock so concurrent workers can't rotate twice; both
+  generations are read.
+- `schema_reaper doctor`: checks the connection, statistics age, tables never
+  `ANALYZE`d, query history, replica status, runtime log length, expired
+  baseline entries, the schema file and alert config.
+- `schema_reaper explain ID` (full or partial id): evidence, confidence,
+  reclaim, schema line, baseline status and the `generate-migration` command.
+- `# schema_reaper:keep TARGET -- reason` comments in code silence findings.
+- `column_scope: model` (opt-in): a column name seen only in a model file
+  counts for that model's table and the tables it mentions, not every table.
+  Models are identified by their full class path (`Admin::User` is not
+  `User`); STI subclasses map to their parent's table (resolved the way Ruby
+  resolves the constant), namespaced models to both possible defaults, and
+  abstract bases, POROs and concerns stay shared.
+- Baseline entries carry an optional reason and expiry (`baseline --reason
+  --expires YYYY-MM-DD`); `scan --ci` fails on expired ones again, and passing
+  `--reason` / `--expires` renews them. `baseline --prune` drops resolved
+  entries without accepting new findings. With `--only` / `--except`,
+  `baseline` replaces or prunes only those analyzers' entries. The 2.0
+  `{"ids": [...]}` file is still read, and the file keeps an `ids` key
+  (unexpired entries) so a 2.0.x gem sharing it still works -- though 2.0.x
+  ignores reasons and expiry, and rewrites the file in the old format if it
+  runs `baseline`.
+- Scheduled reports say what changed since the last one (via `Rails.cache`);
+  `config.alert_on = :changes` sends only then. A report only counts as sent
+  once a channel accepted it -- a non-2xx webhook response is a failure -- so
+  a failed delivery is retried next run instead of suppressed.
+- Slack webhooks get a Block Kit summary instead of a Markdown table Slack
+  can't render; other receivers keep the full `{"text": ...}` report
+  (`config.webhook_format`).
+- Gem awareness covers solid_queue, solid_cache, solid_cable, good_job,
+  delayed_job_active_record, flipper-active_record, acts-as-taggable-on,
+  doorkeeper, noticed, activerecord-session_store, discard, acts_as_list and
+  ancestry. Every analyzer now leaves a gem-owned table's columns alone.
+- Per-file scan cache (`scan_cache:`), so repeat scans only re-parse changed
+  files. Keyed by a SHA-256 digest, so it survives across processes.
+- SARIF results point at the defining line in `db/schema.rb` or
+  `db/structure.sql` instead of the top of `db/schema.rb`.
+- `--color` / `--no-color` works on every command.
+
+### Changed
+- Column byte estimates use `pg_stats.avg_width` scaled by the non-NULL share
+  when the table has been analysed, instead of a fixed per-type guess (16
+  bytes for text/jsonb) that also counted NULLs as full width. An all-NULL
+  column is estimated at ~0 bytes.
+- `unused_index` evidence notes that `idx_scan` is per server, so indexes used
+  only on read replicas look unused on the primary.
+- CI tests Ruby 3.4 and 4.0 too, and runs the live introspection specs against
+  a PostgreSQL 16 service.
+
 ## [2.0.1] - 2026-09-23
 
 ### Fixed

data/README.md

@@ -75,7 +75,7 @@ gem "schema_reaper"
 | requirement | notes |
 |---|---|
 | Ruby >= 2.7 | CI-tested on 2.7 – 3.3 |
-| PostgreSQL + the `pg` gem | uses your app's own `pg` (every Rails + PostgreSQL app already bundles it); add `gem "pg"` for standalone CLI use. Tables in the `public` schema are scanned. MySQL is on the [roadmap](#roadmap). |
+| PostgreSQL + the `pg` gem | uses your app's own `pg` (every Rails + PostgreSQL app already bundles it); add `gem "pg"` for standalone CLI use. Partitioned tables are reported once, as the parent. Tables in the `public` schema are scanned by default; list others under `schemas:` in the [config](#configuration). MySQL is on the [roadmap](#roadmap). |
 | Rails | optional for the CLI; the rake tasks and production automation need it, and the runtime tracker needs ActiveRecord |
 
 > [!IMPORTANT]
@@ -110,9 +110,16 @@ bundle exec schema_reaper scan --format sarif     # GitHub code scanning
 bundle exec schema_reaper scan --format json
 bundle exec schema_reaper scan --ci               # exit 1 on findings not in the baseline
 bundle exec schema_reaper scan --min-confidence 0.8
+bundle exec schema_reaper scan --only dead_column unused_index   # or --except ...
 bundle exec schema_reaper baseline                # accept current findings
+bundle exec schema_reaper baseline --reason "billing ETL" --expires 2027-03-31
+bundle exec schema_reaper baseline --prune        # drop entries that no longer occur
+bundle exec schema_reaper explain users/legacy_api_token   # one finding in full + next step
+bundle exec schema_reaper doctor                  # is the setup good enough to trust a scan?
 bundle exec schema_reaper trend                   # snapshot + progress delta
-bundle exec schema_reaper generate-migration users legacy_api_token
+bundle exec schema_reaper generate-migration users legacy_api_token   # column: staged pair
+bundle exec schema_reaper generate-migration users --index index_users_on_legacy_token
+bundle exec schema_reaper generate-migration old_audit_logs           # whole table
 ```
 
 <details>
@@ -124,9 +131,10 @@ bundle exec schema_reaper generate-migration users legacy_api_token
 |---|---|---|
 | `--format` | `table` | `table`, `json`, `markdown` or `sarif` |
 | `--ci` | off | exit 1 when a finding isn't in `.schema_reaper/baseline.json` |
-| `--min-confidence N` | `0.0` | hide findings below this confidence (0.0 – 1.0) |
+| `--min-confidence N` | `min_confidence` in config, else `0.0` | hide findings below this confidence (0.0 – 1.0) |
+| `--only A B` / `--except A B` | all | run only, or skip, these analyzers (also on `baseline` and `trend`) |
 | `--record` | off | also append this run to the history log used by `trend` |
-| `--color` / `--no-color` | auto | force colour on or off for the table report |
+| `--color` / `--no-color` | auto | force colour on or off (works on every command) |
 | `--config PATH` | `.schema_reaper.yml` | config file to load (works on every command) |
 
 Colour is automatic on a terminal, and off when output is piped or `NO_COLOR` is set.
@@ -194,8 +202,14 @@ end
 Both channels fire when both are set — not a fallback chain, but two audiences:
 a dev-facing chat channel, and an inbox record for people who don't watch chat.
 
-- **Webhook** — a Slack-compatible `{"text": "..."}` JSON POST carrying the
-  Markdown report, with a 10-second timeout.
+Every report says what changed since the previous one (remembered in
+`Rails.cache`). Set `config.alert_on = :changes` to send only when findings
+appeared or were resolved; the default, `:always`, sends every run.
+
+- **Webhook** — for a `hooks.slack.com` URL, a Slack Block Kit summary (counts,
+  the top or newly added findings, what was resolved); for any other URL, a
+  `{"text": "..."}` JSON POST carrying the full Markdown report. Force either
+  with `config.webhook_format = :slack` or `:text`. 10-second timeout.
 - **Email** — sent by `SchemaReaper::Mailer`, which inherits your app's
   `ApplicationMailer` (its `default from:`, delivery settings and so on), or
   `ActionMailer::Base` if you don't have one. Delivered with `deliver_later`.
@@ -295,17 +309,23 @@ for watching the real, live database.
 |---|---|---|
 | `dead_column` | column no code path references | static scan (+ runtime) |
 | `dead_table` | table with no model or query reference | static scan + row count |
-| `unused_index` | non-unique index with `idx_scan = 0` (needs query history) | `pg_stat_user_indexes` |
+| `unused_index` | non-unique index with `idx_scan = 0` (needs query history; stats are per server, so check replicas too) | `pg_stat_user_indexes` |
 | `duplicate_index` | index that exactly duplicates another, or is a prefix of a wider one | schema shape |
 | `missing_fk_index` | `*_id` / foreign-key column with no index (polymorphic pairs need a `(type, id)` index) | schema shape |
 | `always_null_column` | `null_frac = 1.0` — no data at all | `pg_stats` |
 | `single_value_column` | one distinct value on a table of 500+ rows | `pg_stats` |
+| `sequence_exhaustion` | serial / IDENTITY sequence past 50% of its column type's range (high at 75%) | `pg_sequences` |
+| `duplicate_foreign_key` | two FK constraints on the same columns to the same table | `pg_constraint` |
 
 Columns and tables owned by common gems are whitelisted automatically when the
 gem is in your bundle: **devise**, **devise-api**, **paper_trail**,
 **audited**, **friendly_id**, **paranoia** / **acts_as_paranoid**,
-**activestorage**, **actiontext**, **pg_search**, **ahoy_matey** and
-**activeadmin**.
+**activestorage**, **actiontext**, **pg_search**, **ahoy_matey**,
+**activeadmin**, **solid_queue**, **solid_cache**, **solid_cable**,
+**good_job**, **delayed_job_active_record**, **flipper-active_record**,
+**acts-as-taggable-on**, **doorkeeper**, **noticed**,
+**activerecord-session_store**, **discard**, **acts_as_list** and
+**ancestry**. A table a gem owns outright is left alone by every analyzer.
 
 ## Runtime signal (optional, raises confidence)
 
@@ -322,7 +342,11 @@ SchemaReaper::Runtime::Tracker.install!(
 ```
 
 or, in Rails, boot with `SCHEMA_REAPER_TRACK=1` (and optionally
-`SCHEMA_REAPER_SAMPLE=0.05` for the sample rate). Let it run in staging or
+`SCHEMA_REAPER_SAMPLE=0.05` for the sample rate). The tracker also samples
+the tables named in executed SQL (pass `track_sql: false` to opt out), so a
+table read only through raw SQL isn't reported as dead. The log rotates to
+`runtime.jsonl.1` past `runtime_log_max_bytes` (50 MB), and both generations
+are read. Let it run in staging or
 production for a couple of weeks. A column unseen in **both** code and
 ≥ 14 observed days of runtime data (`min_age_days` in
 [`.schema_reaper.yml`](#configuration)) reaches **0.9** confidence (0.8 if it's
@@ -406,6 +430,7 @@ override any of these defaults.
 ```yaml
 database_url:          # falls back to DATABASE_URL, then config/database.yml
 database_yml: config/database.yml
+schemas: [public]      # PostgreSQL schemas to scan; non-public tables appear as schema.table
 scan_paths: [app, lib, config]
 view_globs: ["app/**/*.erb", "app/**/*.haml", "app/**/*.slim", "app/**/*.jbuilder"]
 ignore:
@@ -414,14 +439,42 @@ ignore:
 always_keep_columns: [id, created_at, updated_at, type]
 gem_awareness: true    # auto-whitelist columns owned by known gems
 min_age_days: 14       # days of runtime data before dead_column trusts it
+min_confidence: 0.0    # hide findings below this on every command
+runtime_log_max_bytes: 52428800  # rotate the runtime log past this size (null: never)
 runtime_log: .schema_reaper/runtime.jsonl
 history_log: .schema_reaper/history.jsonl
 baseline: .schema_reaper/baseline.json
 require: []            # extra files to load, e.g. custom analyzers
+scan_cache: .schema_reaper/scan_cache.json  # per-file scan cache (null: off)
+column_scope: global   # or model -- see "Stricter column matching"
 ```
 
 </details>
 
+### Keeping a finding from code
+
+A `schema_reaper:keep` comment anywhere in scanned Ruby or view files silences
+matching findings, with the reason kept next to the code it's about:
+
+```ruby
+class User < ApplicationRecord
+  # schema_reaper:keep legacy_api_token, users.import_ref -- read by the billing ETL
+end
+```
+
+A target is a column (on any table), `table.column`, a table (every finding on
+it), or an index name.
+
+### Stricter column matching
+
+By default a column counts as used if its name appears anywhere in scanned
+code, so `status` in `Order` also hides a dead `status` on `users`. With
+`column_scope: model`, a name seen only in an `app/models` file counts for that
+model's table and for the tables the model mentions (associations, class
+names); names in controllers, views, jobs and so on still count everywhere.
+It finds more dead columns, at some risk of flagging one used through
+metaprogramming -- review before acting.
+
 ### Custom analyzers
 
 ```ruby
@@ -447,7 +500,7 @@ require:
 > ✅ Self-hosted scheduled scans + alerts shipped in **v2.0** — see
 > [Production automation](#production-automation).
 
-- Runtime verdict fusion for index and table findings
+- Runtime verdict fusion for index findings
 - Orphan-row and `schema.rb`↔DB drift analyzers
 - Disk/$ reclaim from real `pg_total_relation_size`
 - Mountable dashboard engine, trend charts

data/RELEASE_CHECKLIST.md

@@ -152,8 +152,19 @@ a throwaway PostgreSQL with a deliberately dirty schema.
 
 ## 6. Publish the gem
 
-RubyGems requires account MFA; `gem push` prompts for an OTP that only the
-maintainer can enter.
+Pushing the `vX.Y.Z` tag (§5) runs `.github/workflows/release.yml`: it checks
+the tag matches `VERSION`, is on `main`, has a CHANGELOG section and no AI
+trailers in history; runs the full suite against PostgreSQL; builds the gem
+and diffs the packaged `lib/` against `git ls-files`; then (after approval, if
+the `release` environment requires reviewers) pushes to RubyGems via Trusted
+Publishing and creates the GitHub release from the CHANGELOG section.
+
+One-time setup: rubygems.org -> schema_reaper -> Trusted publishers -> add
+repository `aksshatt/schema_reaper`, workflow `release.yml`, environment
+`release`.
+
+Manual fallback -- RubyGems requires account MFA; `gem push` prompts for an
+OTP that only the maintainer can enter.
 
 ```sh
 gem build schema_reaper.gemspec

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

@@ -15,4 +15,12 @@
 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"
+
+  # :changes sends a report only when findings appeared or were resolved
+  # since the last one (needs Rails.cache); :always sends every run.
+  # config.alert_on = :changes
+
+  # :auto uses Slack Block Kit for hooks.slack.com URLs and a plain
+  # {"text": <markdown>} body for anything else. Force with :slack or :text.
+  # config.webhook_format = :auto
 end

data/lib/schema_reaper/alert_config.rb

@@ -30,11 +30,31 @@ module SchemaReaper
       end
     end
 
-    attr_accessor :emails, :webhook_url
+    # alert_on:       :always  -- send every scheduled report (the 2.0 behaviour)
+    #                 :changes -- send only when findings appeared or were
+    #                             resolved since the last report
+    # webhook_format: :auto    -- Slack Block Kit for hooks.slack.com, plain
+    #                             {"text": <markdown>} for anything else
+    #                 :slack / :text to force one
+    attr_accessor :emails, :webhook_url, :alert_on, :webhook_format
 
     def initialize
       @emails = []
       @webhook_url = nil
+      @alert_on = :always
+      @webhook_format = :auto
+    end
+
+    def changes_only?
+      alert_on.to_s == "changes"
+    end
+
+    def slack_blocks?
+      case webhook_format.to_s
+      when "slack" then true
+      when "text" then false
+      else webhook_url.to_s.include?("hooks.slack.com")
+      end
     end
 
     def emails?

data/lib/schema_reaper/alert_state.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SchemaReaper
+  # Remembers which finding ids the last delivered report contained, so the
+  # next one can say what changed -- and, with alert_on: :changes, stay quiet
+  # when nothing did. Kept in Rails.cache (the manual trigger's cooldown
+  # already relies on it) because production filesystems are often
+  # ephemeral. Without a cache every report is treated as the first.
+  class AlertState
+    KEY = "schema_reaper:last_alert_ids"
+
+    def initialize(cache: default_cache)
+      @cache = cache
+    end
+
+    # @return [Array<String>, nil] nil when no earlier report is known
+    def previous_ids
+      @cache&.read(KEY)
+    rescue StandardError
+      nil
+    end
+
+    def remember(ids)
+      @cache&.write(KEY, ids.sort)
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def default_cache
+      defined?(Rails) && Rails.respond_to?(:cache) ? Rails.cache : nil
+    end
+  end
+end

data/lib/schema_reaper/analyzers/always_null_column.rb

@@ -20,6 +20,7 @@ module SchemaReaper
         table.columns.filter_map do |col|
           next unless col.always_null?
           next if config.always_keep_columns.include?(col.name)
+          next if ignored_column?(col.name)
           next if gem_reserved?(table.name, col.name)
 
           finding(
@@ -27,17 +28,23 @@ module SchemaReaper
             table: table.name,
             column: col.name,
             severity: :high,
-            confidence: 0.85,
+            confidence: sampled_stats?(table) ? 0.7 : 0.85,
             bytes_per_row: col.bytes,
-            evidence: [
-              "pg_stats.null_frac = 1.0 across ~#{table.row_count} row(s)",
-              "column carries no data"
-            ],
+            evidence: evidence_for(table),
             suggested_fix: "verify with `SELECT count(#{col.name}) FROM #{table.name}` " \
                            "then stage a removal"
           )
         end
       end
+
+      def evidence_for(table)
+        ev = ["pg_stats.null_frac = 1.0 across ~#{table.row_count} row(s)"]
+        ev << if sampled_stats?(table)
+                "estimated from a #{STATS_SAMPLE_ROWS}-row ANALYZE sample -- a few non-null rows could be missed"
+              else
+                "column carries no data"
+              end
+      end
     end
   end
 end

data/lib/schema_reaper/analyzers/base.rb

@@ -11,8 +11,14 @@ module SchemaReaper
     #   gem_columns      - Hash{table_name => Set<column_name>} reserved by gems
     #   gem_owned_tables - Set<table_name> created and owned outright by a gem
     #   config           - Config
-    Context = Struct.new(:schema, :used_tokens, :runtime, :gem_columns, :gem_owned_tables, :config,
+    #   scan             - Static::Result (optional; per-model detail
+    #                      for column_scope: model)
+    Context = Struct.new(:schema, :used_tokens, :runtime, :gem_columns, :gem_owned_tables, :config, :scan,
                          keyword_init: true) do
+      def scan
+        self[:scan] || Static::Result.from_tokens(used_tokens || [])
+      end
+
       def runtime
         self[:runtime] || Runtime::Report.empty
       end
@@ -28,6 +34,11 @@ module SchemaReaper
 
     # Shared plumbing for analyzers: schema access and token lookup helpers.
     class Base
+      # ANALYZE reads a sample of 300 x default_statistics_target rows (30,000
+      # at the default of 100). Above that, pg_stats' null_frac and n_distinct
+      # are estimates: a value held by a handful of rows can be missed.
+      STATS_SAMPLE_ROWS = 30_000
+
       def self.type
         name.split("::").last.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym
       end
@@ -61,8 +72,61 @@ module SchemaReaper
         ctx.used_tokens.include?(token.to_s.downcase)
       end
 
+      # Whether code references `column` on `table`. With column_scope: model,
+      # a name seen only in model files counts just for the tables those
+      # models are, or mention (an association, a class name), so Order's
+      # `status` no longer hides a dead `status` on users.
+      def column_used?(table, column)
+        return used?(column) unless config.column_scope == :model
+
+        name = column.to_s.downcase
+        scan = ctx.scan
+        return true if scan.shared.include?(name)
+
+        forms = table_forms(table)
+        scan.models.any? do |model|
+          model.tokens.include?(name) && (model.tables.include?(table) || forms.any? { |f| model.tokens.include?(f) })
+        end
+      end
+
+      def table_forms(table)
+        bare = table.to_s.split(".").last
+        singular = Inflect.singularize(bare)
+        [bare, singular, singular.delete("_")].uniq
+      end
+
+      # Every column of a table a gem owns outright is the gem's business.
       def gem_reserved?(table, column)
-        ctx.gem_columns.fetch(table, []).include?(column)
+        gem_owned_table?(table) || ctx.gem_columns.fetch(table, []).include?(column)
+      end
+
+      def sampled_stats?(table)
+        table.row_count.to_i > STATS_SAMPLE_ROWS
+      end
+
+      # The `ignore.columns` list (names or /regex/) applies to every
+      # column-level analyzer, not only dead_column.
+      def ignored_column?(name)
+        config.ignored_column?(name)
+      end
+
+      # The removal command for an index. DROP INDEX CONCURRENTLY is refused
+      # on a partitioned index ("cannot drop partitioned index ...
+      # concurrently"), and its per-partition indexes can't be dropped on
+      # their own while attached, so the only path is a plain drop, which
+      # takes an ACCESS EXCLUSIVE lock on the parent and every partition.
+      def remove_index_fix(table, index)
+        base = "remove_index #{sym(table.name)}, name: :#{index.name}"
+        return "#{base}  (use algorithm: :concurrently in production)" unless index.partitioned
+
+        "#{base}  (partitioned index: CONCURRENTLY is not possible -- this locks the table " \
+          "and all partitions while it runs, so schedule it for a quiet window)"
+      end
+
+      # A table name as a Ruby symbol literal for suggested fixes: :users, or
+      # :"billing.invoices" for a table outside the public schema.
+      def sym(name)
+        name.to_sym.inspect
       end
 
       def gem_owned_table?(table)

data/lib/schema_reaper/analyzers/dead_column.rb

@@ -21,7 +21,7 @@ module SchemaReaper
       def dead_in(table)
         table.columns.filter_map do |col|
           next if keep?(table, col)
-          next if used?(col.name)
+          next if column_used?(table.name, col.name)
           next if runtime.read?(table.name, col.name)
 
           finding(
@@ -33,7 +33,7 @@ module SchemaReaper
             bytes_per_row: col.bytes,
             evidence: evidence_for(table, col),
             suggested_fix: "Stage removal: `self.ignored_columns += %w[#{col.name}]` on the " \
-                           "model, deploy, then `remove_column :#{table.name}, :#{col.name}`."
+                           "model, deploy, then `remove_column #{sym(table.name)}, :#{col.name}`."
           )
         end
       end

data/lib/schema_reaper/analyzers/dead_table.rb

@@ -24,13 +24,13 @@ module SchemaReaper
 
       def ignored?(table)
         config.ignore_tables.include?(table.name) ||
-          table.name.start_with?("active_storage_", "action_text_", "action_mailbox_") ||
+          table.name.split(".").last.start_with?("active_storage_", "action_text_", "action_mailbox_") ||
           gem_owned_table?(table.name)
       end
 
       def dead(table)
         return if referenced?(table)
-        return if runtime.accessed.any? { |k| k.start_with?("#{table.name}.") }
+        return if runtime.table_accessed?(table.name)
 
         finding(
           type: :dead_table,
@@ -40,17 +40,21 @@ module SchemaReaper
           confidence: confidence_for(table),
           bytes_per_row: table.columns.sum(&:bytes),
           evidence: evidence_for(table),
-          suggested_fix: "confirm no external consumer, then `drop_table :#{table.name}`"
+          suggested_fix: "confirm no external consumer, then `drop_table #{sym(table.name)}`"
         )
       end
 
       # Match the table name and its singular/camelized model form.
+      # A table outside public ("billing.invoices") is still referenced by its
+      # bare name in code -- `self.table_name = "billing.invoices"` tokenises
+      # to billing + invoices, and the model is Invoice.
       def referenced?(table)
-        singular = singularize(table.name)
-        forms = [table.name, singular, camelize(table.name), camelize(singular)]
+        bare = table.name.split(".").last
+        singular = singularize(bare)
+        forms = [bare, singular, camelize(bare), camelize(singular)]
         return true if forms.any? { |form| used?(form) }
 
-        embedded_in_identifier?(table.name)
+        embedded_in_identifier?(bare)
       end
 
       def singularize(name)