schema_reaper 1.0.11 → 1.0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5039780ddae77f5851cbc16afb53bea80df2eb7328253e18b89c2495feb66218
-  data.tar.gz: e88e86f0cb4d723256505d9a4d7e89010c7cc532df86b57a1190713d71339a90
+  metadata.gz: 920a3c80a9b99271cfb1152f9a4682dd42c03516934fbd6971c56ef0af06882f
+  data.tar.gz: 63567586bef79cb15f27be238def5882fe3119955bb45bea346b4f979599e8ff
 SHA512:
-  metadata.gz: c4b095e2cc73c98f8415136810c3c00218b741cce186d3ff1d2d4e0063cd1658963aa60d296595bc4a2adc8dffaee982be49b750a8f7280993cc4e68a85fa4e0
-  data.tar.gz: d7437c7dbeb2e0c96f4671c89b0e07e89e0e327bdd741cf6b6ee9c128eedf8c2bf96f58c3d925efe742b94de4632c6204ff363e5a23ddc1d6130aa38eeace44c
+  metadata.gz: fa80aecb2dacdbf843f03734818d739b7d5d386ba4096fc69163dacbc55ef52fb92a1b93adc1c4f5f4bf14bb5a1dc3a449fab647101d5a4b43a9922fa7088469
+  data.tar.gz: 410917c5ece25227dbcfeb0b32128b8d0105770631c10a4175da273c3c36744b4bed428857db38b2b621fb4d5ffd03fce89e70d4599bae9c66676371ce42687f

data/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## [1.0.13] - 2026-09-18
+
+### Fixed
+- **Expression key columns were silently dropped from an index's column
+  list.** `indexes_for` joined `pg_index.indkey` entries against
+  `pg_attribute` by `attnum`; an expression column's `indkey` entry is
+  `0`, which matches no real column, so the join dropped it instead of
+  erroring. An index on `((data ->> 'type')), ((data ->> 'id')), user_id,
+  created_at` came back as just `user_id,created_at`, which then made a
+  plain index on `:user_id` look like a genuine leading-edge duplicate of
+  a key it was not actually a prefix of -- `duplicate_index` recommended
+  dropping an index that ordinary `WHERE user_id = ?` lookups depended
+  on. Rewritten to use `pg_get_indexdef(indexrelid, column_no, pretty)`,
+  which is keyed by column position rather than table attnum and renders
+  a plain column and an expression the same way. Also switched the
+  internal column separator from `,` to a control byte, since an
+  expression can legitimately contain a comma (`COALESCE(a, b)`) that a
+  comma-delimited split would have cut in half. (#9, mitkush)
+- **A table a gem creates and owns outright could be reported as dead.**
+  `dead_table` never consulted `GemAwareness`, so a table only ever
+  referenced through a gem's own internal classes -- never named in app
+  code -- looked exactly like real dead weight. Confirmed on a real app:
+  all of that app's `dead_table` findings were gem-owned tables
+  (`active_admin_comments`, `devise_api_tokens`, `friendly_id_slugs`),
+  and `drop_table :devise_api_tokens` would have deleted its mobile
+  session storage. `GemAwareness.owned_tables` now feeds `dead_table` the
+  same way it already fed the `dead_column` exemption. Also added
+  `activeadmin` and `devise-api` to the gem map, verified against each
+  gem's own migration template. (#10, mitkush)
+
+## [1.0.12] - 2026-09-15
+
+### Fixed
+- **`--format markdown` claimed `0 B reclaimable` when the row count was
+  unknown.** `Table` learned in 1.0.11 that `reclaimable_bytes` is `nil`
+  both when the true value is zero and when the row count has never been
+  measured, and that a report should say which. `Markdown` summed the raw
+  bytes directly and always printed a total, so on an unanalysed database
+  it stated there was nothing to reclaim — the exact claim the 1.0.11 fix
+  was written to stop, just in the one format meant for an unattended PR
+  comment or CI job summary. The per-row `Reclaims` column had the same
+  bug: an unmeasured finding showed `0.0 B`, indistinguishable from one
+  that genuinely frees nothing. The summary/unmeasured logic now lives in
+  one shared `Reporters::Reclaim` module used by both reporters, so the
+  two formats cannot answer the same question differently again. (#7,
+  mitkush)
+
 ## [1.0.11] - 2026-09-15
 
 Everything below landed after 1.0.10 was cut, so 1.0.10 on RubyGems contains

data/lib/schema_reaper/analyzers/base.rb

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
+require "set"
+
 module SchemaReaper
   module Analyzers
     # Context passed to every analyzer's #call.
-    #   schema       - DatabaseSchema
-    #   used_tokens  - Set<String> from the static scan
-    #   runtime      - Runtime::Report (may be empty)
-    #   gem_columns  - Hash{table_name => Set<column_name>} reserved by gems
-    #   config       - Config
-    Context = Struct.new(:schema, :used_tokens, :runtime, :gem_columns, :config, keyword_init: true) do
+    #   schema           - DatabaseSchema
+    #   used_tokens      - Set<String> from the static scan
+    #   runtime          - Runtime::Report (may be empty)
+    #   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,
+                         keyword_init: true) do
       def runtime
         self[:runtime] || Runtime::Report.empty
       end
@@ -16,6 +20,10 @@ module SchemaReaper
       def gem_columns
         self[:gem_columns] || {}
       end
+
+      def gem_owned_tables
+        self[:gem_owned_tables] || Set.new
+      end
     end
 
     # Shared plumbing for analyzers: schema access and token lookup helpers.
@@ -57,6 +65,10 @@ module SchemaReaper
         ctx.gem_columns.fetch(table, []).include?(column)
       end
 
+      def gem_owned_table?(table)
+        ctx.gem_owned_tables.include?(table)
+      end
+
       # Builds a Finding, filling in reclaimable_bytes from the row count.
       # An unknown row count leaves reclaimable_bytes nil: "we cannot say" is
       # not the same claim as "zero bytes", and reporters need to tell them

data/lib/schema_reaper/analyzers/dead_table.rb

@@ -24,7 +24,8 @@ module SchemaReaper
 
       def ignored?(table)
         config.ignore_tables.include?(table.name) ||
-          table.name.start_with?("active_storage_", "action_text_", "action_mailbox_")
+          table.name.start_with?("active_storage_", "action_text_", "action_mailbox_") ||
+          gem_owned_table?(table.name)
       end
 
       def dead(table)

data/lib/schema_reaper/gem_awareness.rb

@@ -33,9 +33,38 @@ module SchemaReaper
       "ahoy_matey" => {
         "ahoy_visits" => %w[visit_token visitor_token],
         "ahoy_events" => %w[visit_id name properties]
+      },
+      "activeadmin" => {
+        "active_admin_comments" => %w[namespace body resource_type resource_id author_type author_id]
+      },
+      "devise-api" => {
+        "devise_api_tokens" => %w[
+          resource_owner_type resource_owner_id access_token refresh_token
+          expires_in revoked_at previous_refresh_token
+        ]
       }
     }.freeze
 
+    # Table names an installed gem creates and owns outright -- as opposed to
+    # columns a gem adds onto a table the app itself defines. DeadTable
+    # consults this: the static scanner only reads app code, so a table a
+    # gem's own internal classes reference (ActiveAdmin::Comment,
+    # Devise::Api::Token, FriendlyId::Slug, ...) looks unreferenced and gets
+    # suggested for `drop_table`, which for something like devise_api_tokens
+    # -- mobile session storage -- is actively destructive.
+    #
+    # Only exact table_glob entries qualify: a "*" entry means "this gem adds
+    # these columns to whatever table has them", not "this gem owns this
+    # table", so it says nothing about whole-table ownership.
+    def self.owned_tables(installed:)
+      installed = installed.to_set
+      MAP.each_with_object(Set.new) do |(gem_name, table_map), owned|
+        next unless installed.include?(gem_name)
+
+        table_map.each_key { |glob| owned << glob unless glob == "*" }
+      end
+    end
+
     # @param installed [Enumerable<String>] gem names present in the bundle
     # @param tables [Enumerable<#name,#column_names>] or Enumerable<String>
     # @return [Hash{String => Set<String>}]

data/lib/schema_reaper/introspect/postgres.rb

@@ -16,6 +16,12 @@ module SchemaReaper
                "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
+      # column list back apart in Ruby cannot be fooled by a comma the
+      # expression itself contains: COALESCE(a, b), ROUND(x, 2), etc.
+      COLUMN_SEPARATOR = 31.chr
+
       def initialize(url)
         require "pg" # load first so the PG::Error rescue below can resolve
         raise Error, NO_URL if url.nil? || url.empty?
@@ -96,23 +102,34 @@ module SchemaReaper
 
       # 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.
+      #
+      # pg_get_indexdef(indexrelid, column_no, pretty) is keyed by column
+      # *position* (1..indnkeyatts), not by table attnum, so it renders a
+      # plain column and an expression column uniformly. The previous query
+      # joined each indkey entry against pg_attribute by attnum; an expression
+      # column's indkey entry is 0, which matches no real column, so the join
+      # silently dropped it -- an index on (COALESCE(a, b), c) came back as
+      # just "c", which then looked like a genuine duplicate of any ordinary
+      # index on :c. indnkeyatts also excludes INCLUDE columns, which are
+      # payload only and never participate in Index#covers?'s prefix check.
       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 k.ord), ',') AS cols
+                 array_to_string(
+                   array_agg(pg_get_indexdef(ix.indexrelid, k.ord::int, true) ORDER BY k.ord),
+                   '#{COLUMN_SEPARATOR}'
+                 ) 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 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
+          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
           GROUP BY i.relname, ix.indisunique, ix.indisprimary, s.idx_scan
         SQL
           Index.new(
-            name: r["name"], columns: r["cols"].split(","),
+            name: r["name"], columns: r["cols"].split(COLUMN_SEPARATOR),
             unique: r["unique"] == "t", primary: r["primary"] == "t",
             scans: r["scans"]&.to_i
           )

data/lib/schema_reaper/reporters/markdown.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "bytes"
+require_relative "reclaim"
 
 module SchemaReaper
   module Reporters
@@ -18,8 +18,7 @@ module SchemaReaper
           return
         end
 
-        @io.puts "\n#{@findings.size} finding(s), " \
-                 "~**#{Bytes.human(total)}** reclaimable.\n\n"
+        @io.puts "\n#{summary_line}\n\n"
         @io.puts "| Severity | Confidence | Type | Target | Reclaims | Fix |"
         @io.puts "|---|---|---|---|---|---|"
         rows.each { |r| @io.puts r }
@@ -27,17 +26,23 @@ module SchemaReaper
 
       private
 
+      # "54 finding(s). **~93.8 KB reclaimable.**" -- or, when the row count is
+      # unknown or the estimate is genuinely zero, no reclaim clause at all,
+      # matching the terminal report rather than claiming a number it does not
+      # have.
+      def summary_line
+        text = Reclaim.summary(@findings)
+        line = "#{@findings.size} finding(s)."
+        line + (text ? " **#{text}.**" : "")
+      end
+
       def rows
         @findings.sort_by { |f| -f.confidence }.map do |f|
           target = [f.table, f.column, f.index].compact.join("`.`")
           "| #{f.severity} | #{(f.confidence * 100).round}% | `#{f.type}` | " \
-            "`#{target}` | #{Bytes.human(f.reclaimable_bytes)} | #{f.suggested_fix} |"
+            "`#{target}` | #{Reclaim.cell(f)} | #{f.suggested_fix} |"
         end
       end
-
-      def total
-        @findings.sum(&:reclaimable_bytes)
-      end
     end
   end
 end

data/lib/schema_reaper/reporters/reclaim.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "bytes"
+
+module SchemaReaper
+  module Reporters
+    # Turns a set of findings' reclaimable-bytes into a human sentence, and a
+    # single finding's into a table cell. Shared by every reporter that states
+    # a reclaim total in prose, so the answer cannot drift between formats --
+    # which is how the terminal report learned to distinguish "no bytes" from
+    # "no idea" while the Markdown report kept treating them as the same 0.
+    module Reclaim
+      module_function
+
+      # A row count is required for a byte estimate, and pg reports
+      # reltuples = -1 for a table that has never been analysed. Printing 0.0 B
+      # for an unknown reads as "nothing to gain here", a different claim.
+      def summary(findings)
+        total = findings.sum(&:reclaimable_bytes)
+        return "~#{Bytes.human(total)} reclaimable" if total.positive?
+        return nil unless unmeasured?(findings)
+
+        "reclaim estimate unavailable — run ANALYZE to populate table statistics"
+      end
+
+      # True when some finding's byte estimate is unknown rather than zero.
+      # bytes_per_row.zero? findings (missing_fk_index, duplicate_index -- they
+      # add or drop an index, not data) always reclaim 0 regardless of row
+      # count, so an unknown row count does not make their answer unmeasured.
+      def unmeasured?(findings)
+        findings.any? { |f| f.bytes_per_row.to_i.positive? && !f.reclaim_known? }
+      end
+
+      # Per-finding cell for a table row: the human size, or a note that it is
+      # not known, using the same bytes_per_row-zero exception as summary.
+      def cell(finding)
+        return Bytes.human(finding.reclaimable_bytes) if measured?(finding)
+
+        "unknown"
+      end
+
+      def measured?(finding)
+        finding.bytes_per_row.to_i.zero? || finding.reclaim_known?
+      end
+    end
+  end
+end

data/lib/schema_reaper/reporters/table.rb

@@ -3,6 +3,7 @@
 require_relative "bytes"
 require_relative "ansi"
 require_relative "rollup"
+require_relative "reclaim"
 
 module SchemaReaper
   module Reporters
@@ -57,18 +58,8 @@ module SchemaReaper
                  .map { |t, n| "#{t} #{n}" }.join(" · ")
       end
 
-      # A reclaim estimate needs a row count, and pg reports reltuples = -1 for
-      # a table it has never analysed. Printing 0.0 B for an unknown reads as
-      # "nothing to gain here", which is a different claim entirely.
       def reclaim_text
-        return "~#{Bytes.human(total_reclaimable)} reclaimable" if total_reclaimable.positive?
-        return nil unless unmeasured?
-
-        "reclaim estimate unavailable — run ANALYZE to populate table statistics"
-      end
-
-      def unmeasured?
-        @findings.any? { |f| f.bytes_per_row.to_i.positive? && !f.reclaim_known? }
+        Reclaim.summary(@findings)
       end
 
       def rolled_up

data/lib/schema_reaper/runner.rb

@@ -23,6 +23,7 @@ module SchemaReaper
         used_tokens: Static::Scanner.new(@config, root: @root).call,
         runtime: runtime_report,
         gem_columns: gem_columns(db),
+        gem_owned_tables: gem_owned_tables,
         config: @config
       )
 
@@ -89,6 +90,12 @@ module SchemaReaper
       )
     end
 
+    def gem_owned_tables
+      return Set.new unless @config.gem_awareness?
+
+      GemAwareness.owned_tables(installed: GemAwareness.installed_gems)
+    end
+
     def load_plugins
       @config.require_paths.each do |path|
         require(File.expand_path(path, @root))

data/lib/schema_reaper/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schema_reaper
 version: !ruby/object:Gem::Version
-  version: 1.0.11
+  version: 1.0.13
 platform: ruby
 authors:
 - aksshatt
@@ -130,6 +130,7 @@ files:
 - lib/schema_reaper/reporters/console.rb
 - lib/schema_reaper/reporters/json.rb
 - lib/schema_reaper/reporters/markdown.rb
+- lib/schema_reaper/reporters/reclaim.rb
 - lib/schema_reaper/reporters/rollup.rb
 - lib/schema_reaper/reporters/sarif.rb
 - lib/schema_reaper/reporters/table.rb