schema_reaper 1.0.5 → 1.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 162d87ba1d2536d8db97d20dd2df6af8675529e2d967a1271d5c25ff9f1f5549
-  data.tar.gz: 33fa30c1d35e8f1b8cbcbd5af0e4724389462bf77921470152c9403965f4f574
+  metadata.gz: 2fc585e50326fe0b90f5ac697eb1211988ebc71e691f8a3253d427d611954adc
+  data.tar.gz: 84474703f7100d0b0055a3918ec611aa2032cf731ba86f27cb4ab7503a308178
 SHA512:
-  metadata.gz: 7c4e72d7cd3b050d21261bde44581525aff0e81190610edbff6891a8bed844d40401aa41ae8fb82e4d77781ad68b61dd75c2618d22fba625ef0ebbc0999bd6d9
-  data.tar.gz: 610286a554f314bc296fed9ef239a4c78946b4ea5d53ab3e2b9b9eaeb3e8e5d995b33ebd2cffdff587a7e311cbf0fc00e3463f35d776a53e4dcebfc3a49f84ff
+  metadata.gz: 2a54a044eb8d9f910ebef39cd172854101e23ba9e3f67dc91533fa197727bca0de60486cedc35a67e3f92940eabf000bd351f3c7ef27ebd76e4dd0e7689677a0
+  data.tar.gz: 85e194f2c74030c5df99a703dd523381e40bbfcf6507d37bf4249f42cd48abd0696db0473b6f36f007f61e4894c900b40ffd7c7185e44214589ce3e46f3ea175

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [1.0.7] - 2026-09-04
+
+Correctness fixes to introspection and analyzers, all contributed by @mitkush
+and verified against a live PostgreSQL database.
+
+### Fixed
+- **Index-key order** (#1). Index columns are now read in real key order via
+  `unnest(indkey) WITH ORDINALITY` instead of `attnum` order, so
+  `duplicate_index`'s prefix comparison is correct for composite indexes.
+- **`unused_index` false positives on quiet databases** (#2). If the whole
+  cluster has fewer recorded index scans than it has indexes, there is no
+  query history to judge by -- the analyzer now skips with an explanation
+  instead of flagging every index as unused.
+- **Polymorphic associations in `missing_fk_index`** (#3). A `*_id` column
+  paired with a `*_type` column is matched against the composite
+  `(type, id)` index Rails actually uses; a bare `*_id` index is no longer
+  demanded, and when the pair is unindexed the suggested fix is the composite
+  `add_index :t, %i[thing_type thing_id]`.
+- **`dead_table` plurals and route helpers** (#5). Tables whose model name
+  needs `-y -> -ies` (`categories` -> `Category`) and names referenced only
+  through route helpers are recognised as used.
+- **Composite primary keys** (#6). Introspection returns every primary-key
+  column in key order; `Table#primary_key?` / `#primary_key_columns` let
+  analyzers treat each part of a composite key as a key column.
+
+### Changed
+- `DatabaseSchema` carries `index_scan_total`; `Table#primary_key` may now be
+  an array. Test helpers updated accordingly.
+
+## [1.0.6] - 2026-09-04
+
+### Changed
+- Added `mitkush` (mitanshukushwah@gmail.com) as a gemspec author.
+
 ## [1.0.5] - 2026-09-04
 
 Fixes found by running the gem against a live PostgreSQL database.

data/lib/schema_reaper/analyzers/dead_column.rb

@@ -41,7 +41,7 @@ module SchemaReaper
       def keep?(table, col)
         config.always_keep_columns.include?(col.name) ||
           config.ignored_column?(col.name) ||
-          col.name == table.primary_key ||
+          table.primary_key?(col.name) ||
           table.foreign_keys.include?(col.name) ||
           col.name.end_with?("_id", "_type") ||
           gem_reserved?(table.name, col.name)

data/lib/schema_reaper/analyzers/dead_table.rb

@@ -7,6 +7,15 @@ module SchemaReaper
     class DeadTable < Base
       Registry.register(self)
 
+      # Enough of Rails' inflector for table names. A wrong guess only costs a
+      # redundant lookup -- every form is checked and any hit counts -- so the
+      # rules stay small rather than trying to be complete.
+      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 call
         schema.tables.reject { |t| ignored?(t) }.filter_map { |t| dead(t) }
       end
@@ -36,9 +45,26 @@ module SchemaReaper
 
       # Match the table name and its singular/camelized model form.
       def referenced?(table)
-        singular = table.name.sub(/s\z/, "")
-        [table.name, singular, camelize(table.name), camelize(singular)]
-          .any? { |form| used?(form) }
+        singular = singularize(table.name)
+        forms = [table.name, singular, camelize(table.name), camelize(singular)]
+        return true if forms.any? { |form| used?(form) }
+
+        embedded_in_identifier?(table.name)
+      end
+
+      def singularize(name)
+        rule = SINGULAR_RULES.find { |pattern, _| name.match?(pattern) }
+        rule ? name.sub(rule[0], rule[1]) : name
+      end
+
+      # Route helpers, i18n keys and CSS selectors bury a table name inside a
+      # longer identifier (admin_crm_activities_path), which the scanner
+      # tokenises as a single word. Count the name as referenced when it appears
+      # as a whole underscore-delimited run inside some token -- `logs` must not
+      # match `catalogs`, but must match `audit_logs_path`.
+      def embedded_in_identifier?(name)
+        pattern = /(?:\A|_)#{Regexp.escape(name)}(?:_|\z)/
+        ctx.used_tokens.any? { |token| token.include?(name) && pattern.match?(token) }
       end
 
       def confidence_for(table)

data/lib/schema_reaper/analyzers/missing_fk_index.rb

@@ -4,6 +4,11 @@ module SchemaReaper
   module Analyzers
     # A foreign-key column with no index: every parent delete/update scans the
     # child table. This is a repo-health nag, not dead weight.
+    #
+    # A `*_id` column paired with a `*_type` column is a polymorphic
+    # association. Rails never queries the id without the type, so the index
+    # that matters is the composite `(type, id)` -- a bare index on the id
+    # alone would go unused.
     class MissingFkIndex < Base
       Registry.register(self)
 
@@ -18,19 +23,38 @@ module SchemaReaper
         fk_columns(table).filter_map do |col|
           next if indexed?(table, col)
 
-          finding(
-            type: :missing_fk_index,
-            table: table.name,
-            column: col,
-            severity: :medium,
-            confidence: 0.9,
-            bytes_per_row: 0,
-            evidence: ["#{col} is a foreign key with no covering index"],
-            suggested_fix: "add_index :#{table.name}, :#{col}"
-          )
+          type_col = polymorphic_type_for(table, col)
+          next if type_col && polymorphic_indexed?(table, type_col, col)
+
+          finding_for(table, col, type_col)
         end
       end
 
+      def finding_for(table, col, type_col)
+        finding(
+          type: :missing_fk_index,
+          table: table.name,
+          column: col,
+          severity: :medium,
+          confidence: 0.9,
+          bytes_per_row: 0,
+          evidence: [evidence_for(col, type_col)],
+          suggested_fix: fix_for(table, col, type_col)
+        )
+      end
+
+      def evidence_for(col, type_col)
+        return "#{col} is a foreign key with no covering index" unless type_col
+
+        "#{col} is a polymorphic association with #{type_col} and has no (#{type_col}, #{col}) index"
+      end
+
+      def fix_for(table, col, type_col)
+        return "add_index :#{table.name}, :#{col}" unless type_col
+
+        "add_index :#{table.name}, %i[#{type_col} #{col}]"
+      end
+
       def fk_columns(table)
         (table.foreign_keys + table.column_names.grep(/_id\z/)).uniq
       end
@@ -38,6 +62,20 @@ module SchemaReaper
       def indexed?(table, col)
         table.indexes.any? { |ix| ix.columns.first == col }
       end
+
+      # The `*_type` column paired with a polymorphic `*_id`, when present.
+      def polymorphic_type_for(table, col)
+        return nil unless col.end_with?("_id")
+
+        type_col = "#{col[0..-4]}_type"
+        table.column_names.include?(type_col) ? type_col : nil
+      end
+
+      # Rails writes these as add_index :table, %i[thing_type thing_id], so the
+      # pair leads the index; trailing columns (version, name, ...) are fine.
+      def polymorphic_indexed?(table, type_col, id_col)
+        table.indexes.any? { |ix| ix.columns.first(2) == [type_col, id_col] }
+      end
     end
   end
 end

data/lib/schema_reaper/analyzers/single_value_column.rb

@@ -22,7 +22,7 @@ module SchemaReaper
 
         table.columns.filter_map do |col|
           next unless col.single_value?
-          next if col.name == table.primary_key
+          next if table.primary_key?(col.name)
           next if config.always_keep_columns.include?(col.name)
           next if gem_reserved?(table.name, col.name)
 

data/lib/schema_reaper/analyzers/unused_index.rb

@@ -9,6 +9,11 @@ module SchemaReaper
       Registry.register(self)
 
       def call
+        # Without query history every idx_scan is 0, so this analyzer would
+        # report every non-unique index in the database. Report nothing rather
+        # than burying the other analyzers' findings under that noise.
+        return [] unless schema.query_history?
+
         schema.tables.reject { |t| config.ignore_tables.include?(t.name) }
               .flat_map { |t| unused_in(t) }
       end

data/lib/schema_reaper/introspect/postgres.rb

@@ -20,11 +20,22 @@ module SchemaReaper
       end
 
       def call
-        DatabaseSchema.new(tables: table_names.map { |n| build_table(n) })
+        DatabaseSchema.new(
+          tables: table_names.map { |n| build_table(n) },
+          index_scan_total: index_scan_total
+        )
       end
 
       private
 
+      # Cluster-wide cumulative index scans. Lets the unused-index analyzer tell
+      # "this index is never used" apart from "this database has no query
+      # history", which look identical at the level of a single idx_scan = 0.
+      def index_scan_total
+        exec("SELECT COALESCE(sum(idx_scan), 0) AS total FROM pg_stat_user_indexes")
+          .first&.fetch("total")&.to_i
+      end
+
       def table_names
         exec(<<~SQL).map { |r| r["tablename"] }
           SELECT tablename FROM pg_tables WHERE schemaname = 'public' ORDER BY tablename
@@ -77,15 +88,19 @@ module SchemaReaper
         end
       end
 
+      # Columns must come back in index-key order, not table order: prefix
+      # comparisons (Index#covers?) are only meaningful on the real key order.
+      # unnest(indkey) WITH ORDINALITY preserves that; ORDER BY attnum does not.
       def indexes_for(table)
         exec(<<~SQL, [table]).map do |r|
           SELECT i.relname AS name, ix.indisunique AS "unique", ix.indisprimary AS "primary",
                  s.idx_scan AS scans,
-                 array_to_string(array_agg(a.attname ORDER BY a.attnum), ',') AS cols
+                 array_to_string(array_agg(a.attname ORDER BY k.ord), ',') AS cols
           FROM pg_class t
           JOIN pg_index ix ON t.oid = ix.indrelid
           JOIN pg_class i ON i.oid = ix.indexrelid
-          JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(ix.indkey)
+          JOIN LATERAL unnest(ix.indkey::int2[]) WITH ORDINALITY AS k(attnum, ord) ON TRUE
+          JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = k.attnum
           LEFT JOIN pg_stat_user_indexes s ON s.indexrelid = i.oid
           WHERE t.relname = $1
           GROUP BY i.relname, ix.indisunique, ix.indisprimary, s.idx_scan
@@ -98,12 +113,17 @@ module SchemaReaper
         end
       end
 
+      # Every primary-key column, in key order. A composite key needs the whole
+      # list: returning one arbitrary column leaves the rest looking like
+      # ordinary columns to the analyzers.
       def primary_key_for(table)
-        exec(<<~SQL, [table]).map { |r| r["attname"] }.first
+        exec(<<~SQL, [table]).map { |r| r["attname"] }
           SELECT a.attname
           FROM pg_index i
-          JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY(i.indkey)
+          JOIN LATERAL unnest(i.indkey::int2[]) WITH ORDINALITY AS k(attnum, ord) ON TRUE
+          JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum
           WHERE i.indrelid = $1::regclass AND i.indisprimary
+          ORDER BY k.ord
         SQL
       rescue PG::Error
         nil

data/lib/schema_reaper/runner.rb

@@ -17,6 +17,7 @@ module SchemaReaper
 
     def run
       db = schema
+      warn_missing_query_history(db)
       ctx = Analyzers::Context.new(
         schema: db,
         used_tokens: Static::Scanner.new(@config, root: @root).call,
@@ -31,6 +32,16 @@ module SchemaReaper
 
     private
 
+    # Silently reporting nothing would look like a clean bill of health, so say
+    # why the unused-index analyzer sat this run out.
+    def warn_missing_query_history(db)
+      return if db.query_history?
+
+      warn "schema_reaper: skipping unused_index -- only #{db.index_scan_total} index scan(s) " \
+           "recorded across #{db.index_count} index(es). Scan a database that has served " \
+           "production traffic, or check whether statistics were recently reset."
+    end
+
     def dedupe(findings)
       collapse_targets(drop_findings_on_dead_tables(findings))
     end

data/lib/schema_reaper/schema.rb

@@ -40,11 +40,40 @@ module SchemaReaper
     def index_on(cols)
       indexes.find { |i| i.columns == Array(cols) }
     end
+
+    # primary_key may be a single name or, for a composite key, the ordered
+    # list. Array() accepts both so introspectors that still return one name
+    # keep working.
+    def primary_key_columns
+      Array(primary_key)
+    end
+
+    def primary_key?(column_name)
+      primary_key_columns.include?(column_name)
+    end
   end
 
-  DatabaseSchema = Struct.new(:tables, keyword_init: true) do
+  DatabaseSchema = Struct.new(:tables, :index_scan_total, keyword_init: true) do
     def table(name)
       tables.find { |t| t.name == name }
     end
+
+    def index_count
+      tables.sum { |t| t.indexes.size }
+    end
+
+    # pg_stat counters are cumulative since the last reset, so idx_scan = 0 only
+    # means "unused" if the database has served enough traffic for a used index
+    # to have registered. A database that has taken real queries scans its
+    # indexes far more than once each; below that we are looking at a fresh,
+    # restored, or just-reset cluster where every zero is an artifact.
+    #
+    # nil means the introspector did not report a total -- assume stats are
+    # usable rather than silently dropping findings.
+    def query_history?
+      return true if index_scan_total.nil?
+
+      index_scan_total >= index_count
+    end
   end
 end

data/lib/schema_reaper/version.rb

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

data/schema_reaper.gemspec

@@ -5,8 +5,8 @@ require_relative "lib/schema_reaper/version"
 Gem::Specification.new do |spec|
   spec.name = "schema_reaper"
   spec.version = SchemaReaper::VERSION
-  spec.authors = ["aksshatt"]
-  spec.email = ["akshatpegwar5@gmail.com"]
+  spec.authors = %w[aksshatt mitkush]
+  spec.email = ["akshatpegwar5@gmail.com", "mitanshukushwah@gmail.com"]
 
   spec.summary = "Find and safely remove schema dead-weight in Rails + PostgreSQL apps."
   spec.description =

metadata

@@ -1,10 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: schema_reaper
 version: !ruby/object:Gem::Version
-  version: 1.0.5
+  version: 1.0.7
 platform: ruby
 authors:
 - aksshatt
+- mitkush
 autorequire: 
 bindir: exe
 cert_chain: []
@@ -88,6 +89,7 @@ description: 'schema_reaper finds schema dead-weight in Rails/ActiveRecord + Pos
   only for now; Ruby >= 2.7. See the README for full usage.'
 email:
 - akshatpegwar5@gmail.com
+- mitanshukushwah@gmail.com
 executables:
 - schema_reaper
 extensions: []