schema_reaper 1.0.3 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22245618558de174144cf3732fbced500e89726cafdec2ab14bdefe35d535287
-  data.tar.gz: 95a26a72863e7f603d1d6894aed3f89948f34d85959359863db83e9d01cc5d1b
+  metadata.gz: 162d87ba1d2536d8db97d20dd2df6af8675529e2d967a1271d5c25ff9f1f5549
+  data.tar.gz: 33fa30c1d35e8f1b8cbcbd5af0e4724389462bf77921470152c9403965f4f574
 SHA512:
-  metadata.gz: f98dcbc99cf5a8527ecdfbce06dfce99f6f678971c9d60ee96a030ba0b71eeac731e39f0e8dc87e697a9d74dcfec95d1fb1cfe06549a5b3db55a36580da42a7c
-  data.tar.gz: dbcb412469b0bb09c2676706b5a11a6fb085649411d9af3c29d8e633fd208a9e83315905886cf9bc065af4d85a148cdab11101b9dc6ff09380887effbee17493
+  metadata.gz: 7c4e72d7cd3b050d21261bde44581525aff0e81190610edbff6891a8bed844d40401aa41ae8fb82e4d77781ad68b61dd75c2618d22fba625ef0ebbc0999bd6d9
+  data.tar.gz: 610286a554f314bc296fed9ef239a4c78946b4ea5d53ab3e2b9b9eaeb3e8e5d995b33ebd2cffdff587a7e311cbf0fc00e3463f35d776a53e4dcebfc3a49f84ff

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [1.0.5] - 2026-09-04
+
+Fixes found by running the gem against a live PostgreSQL database.
+
+### Fixed
+- **Duplicate findings for one object.** When several analyzers flagged the
+  same physical column (e.g. `dead_column` + `always_null_column`) or index
+  (`unused_index` + `duplicate_index`), each was reported separately *and* its
+  reclaimable bytes were counted more than once, inflating the run total.
+  Findings are now collapsed to the highest-confidence one per target; the
+  others are noted as `also flagged by: ...` in its evidence.
+- **`generate-migration` output.** The generated STEP 1 migration contained a
+  fragile multi-line string (heredoc line-continuation) that rendered with a
+  stray gap. It is now a single clean string. Both files are verified valid
+  Ruby.
+- **Migration schema version.** Generated migrations now inherit the host
+  app's Rails minor version (`ActiveRecord::Migration[X.Y]`) when ActiveRecord
+  is loaded, instead of a hard-coded `7.1`.
+
+### Added
+- Specs covering target collapsing and migration generation, exercised end to
+  end through `Runner` with an injected schema.
+
+## [1.0.4] - 2026-09-04
+
+### Changed
+- Rewrote `description` as a single tight paragraph. RubyGems collapses
+  description whitespace, so the previous multi-line bulleted text rendered as
+  an unreadable blob on the gem page. Full analyzer list and usage stay in the
+  README. Link metadata from 1.0.3 unchanged.
+
 ## [1.0.3] - 2026-09-04
 
 ### Changed

data/lib/schema_reaper/finding.rb

@@ -19,6 +19,19 @@ module SchemaReaper
       [type, table, column, index].compact.join("/")
     end
 
+    # The physical object this finding is about, ignoring which analyzer raised
+    # it. Two findings with the same target_key are the same underlying problem
+    # (e.g. dead_column + always_null_column on one column) -- keep the strongest.
+    def target_key
+      if index
+        ["index", table, index]
+      elsif column
+        ["column", table, column]
+      else
+        ["table", table]
+      end
+    end
+
     def reclaimable_bytes
       self[:reclaimable_bytes] || 0
     end

data/lib/schema_reaper/migration_generator.rb

@@ -19,35 +19,38 @@ module SchemaReaper
     private
 
     def stage_one
+      note = "Add `self.ignored_columns += %w[#{@column}]` to the #{model} model, " \
+             "then deploy STEP 2 after a soak period."
       write "ignore_#{@table}_#{@column}", <<~RUBY
         # frozen_string_literal: true
 
         # STEP 1 of 2. Deploy this alone and let it soak. It only tells
         # ActiveRecord to stop selecting the column; nothing is dropped.
-        class Ignore#{camel}Column < ActiveRecord::Migration[7.1]
+        class Ignore#{camel}Column < ActiveRecord::Migration[#{migration_version}]
           def up
-            say "Add `self.ignored_columns += %w[#{@column}]` to the #{model} model, " \
-                "then deploy STEP 2 after a soak period."
+            say #{note.inspect}
           end
 
-          def down; end
+          def down
+          end
         end
       RUBY
     end
 
     def stage_two
+      down_msg = "recreate :#{@column} on :#{@table} manually if you need it back"
       write "drop_#{@table}_#{@column}", <<~RUBY
         # frozen_string_literal: true
 
-        # STEP 2 of 2. Run only after STEP 1 has been deployed and verified.
-        class Drop#{camel}Column < ActiveRecord::Migration[7.1]
+        # STEP 2 of 2. Run only after STEP 1 has been deployed and verified in
+        # production (nothing reads the column, no errors).
+        class Drop#{camel}Column < ActiveRecord::Migration[#{migration_version}]
           def up
             remove_column :#{@table}, :#{@column}
           end
 
           def down
-            raise ActiveRecord::IrreversibleMigration,
-                  "recreate :#{@column} on :#{@table} manually if you need it back"
+            raise ActiveRecord::IrreversibleMigration, #{down_msg.inspect}
           end
         end
       RUBY
@@ -61,6 +64,14 @@ module SchemaReaper
       path
     end
 
+    # Match the host app's Rails minor version when ActiveRecord is loaded,
+    # otherwise a sane recent default the developer can edit.
+    def migration_version
+      return "7.1" unless defined?(ActiveRecord::VERSION::STRING)
+
+      ActiveRecord::VERSION::STRING.split(".").first(2).join(".")
+    end
+
     def camel
       "#{@table}_#{@column}".split("_").map(&:capitalize).join
     end

data/lib/schema_reaper/runner.rb

@@ -5,6 +5,8 @@ require "set"
 module SchemaReaper
   # Ties introspection + scanning + runtime data + analyzers together.
   class Runner
+    SEVERITY_RANK = { high: 0, medium: 1, low: 2 }.freeze
+
     def initialize(config: Config.load, root: Dir.pwd, introspector: nil, runtime: nil)
       @config = config
       @root = root
@@ -29,13 +31,30 @@ module SchemaReaper
 
     private
 
+    def dedupe(findings)
+      collapse_targets(drop_findings_on_dead_tables(findings))
+    end
+
     # When a whole table is dead, its per-column and per-index findings are
     # noise -- keep only the table-level finding for that table.
-    def dedupe(findings)
+    def drop_findings_on_dead_tables(findings)
       dead_tables = findings.select { |f| f.type == :dead_table }.to_set(&:table)
       findings.reject { |f| f.type != :dead_table && dead_tables.include?(f.table) }
     end
 
+    # Several analyzers can flag the same physical column or index (e.g.
+    # dead_column + always_null_column). Keep the highest-confidence finding per
+    # target so it is reported -- and its bytes counted -- exactly once, but note
+    # the other analyzers that agreed.
+    def collapse_targets(findings)
+      findings.group_by(&:target_key).map do |_key, group|
+        winner = group.max_by { |f| [f.confidence, -SEVERITY_RANK.fetch(f.severity, 9)] }
+        also = group.map(&:type).uniq - [winner.type]
+        winner.evidence += ["also flagged by: #{also.join(", ")}"] if also.any?
+        winner
+      end
+    end
+
     def schema
       return @introspector.call if @introspector
 

data/lib/schema_reaper/version.rb

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

data/schema_reaper.gemspec

@@ -8,39 +8,16 @@ Gem::Specification.new do |spec|
   spec.authors = ["aksshatt"]
   spec.email = ["akshatpegwar5@gmail.com"]
 
-  spec.summary = "Find dead columns, dead tables, unused indexes and other schema dead-weight " \
-                 "in Rails/ActiveRecord apps -- then remove it safely."
-  spec.description = <<~DESC
-    schema_reaper reads your live PostgreSQL schema and planner statistics and
-    cross-references them against a Prism-AST static scan of your codebase
-    (models, views, SQL string literals). With an optional runtime signal -- a
-    sampled log of which columns are actually read in production -- it fuses
-    static and runtime evidence into a confidence score per finding.
-
-    Analyzers:
-      * dead_column         -- column no code path references
-      * dead_table          -- table with no model/query reference, zero rows
-      * unused_index        -- non-unique index, idx_scan = 0 in pg_stat
-      * duplicate_index     -- index that is a prefix of a wider index
-      * missing_fk_index    -- foreign-key / *_id column with no covering index
-      * always_null_column  -- pg_stats null_frac = 1.0, carries no data
-      * single_value_column -- one distinct value across a large table
-
-    Every finding carries a reclaimable-bytes estimate (from row counts) and a
-    concrete fix. `generate-migration` emits a staged, reversible pair:
-    ignored_columns first, remove_column after a soak. Nothing is dropped
-    automatically. Columns owned by common gems (devise, paper_trail,
-    activestorage, actiontext, friendly_id, audited, pg_search, ahoy_matey,
-    paranoia) are whitelisted when the gem is in your bundle.
-
-    Reporters: table, json, markdown (PR comments), SARIF 2.1.0 (GitHub code
-    scanning). `scan --ci` gates only findings absent from a committed baseline.
-    `trend` keeps an append-only history log for cleanup burndown. A Rails
-    railtie adds rake tasks and an opt-in runtime tracker. Custom analyzers
-    load through the `require:` config key.
-
-    PostgreSQL only for now (MySQL adapter on the roadmap). Ruby >= 2.7.
-  DESC
+  spec.summary = "Find and safely remove schema dead-weight in Rails + PostgreSQL apps."
+  spec.description =
+    "schema_reaper finds schema dead-weight in Rails/ActiveRecord + PostgreSQL apps: " \
+    "dead columns and tables, unused, duplicate and missing foreign-key indexes, and " \
+    "always-NULL or single-value columns. It cross-references the live schema and pg_stats " \
+    "against a static scan of your code, with an optional production runtime signal for " \
+    "higher confidence. Each finding is scored, carries a reclaimable-bytes estimate, and " \
+    "ships with a staged, reversible migration. Reporters for terminal, JSON, Markdown and " \
+    "SARIF; a CI baseline gate; a trend log; a Rails railtie. PostgreSQL only for now; " \
+    "Ruby >= 2.7. See the README for full usage."
   spec.homepage = "https://github.com/aksshatt/schema_reaper"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 2.7.0"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schema_reaper
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.5
 platform: ruby
 authors:
 - aksshatt
@@ -78,36 +78,14 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
-description: |
-  schema_reaper reads your live PostgreSQL schema and planner statistics and
-  cross-references them against a Prism-AST static scan of your codebase
-  (models, views, SQL string literals). With an optional runtime signal -- a
-  sampled log of which columns are actually read in production -- it fuses
-  static and runtime evidence into a confidence score per finding.
-
-  Analyzers:
-    * dead_column         -- column no code path references
-    * dead_table          -- table with no model/query reference, zero rows
-    * unused_index        -- non-unique index, idx_scan = 0 in pg_stat
-    * duplicate_index     -- index that is a prefix of a wider index
-    * missing_fk_index    -- foreign-key / *_id column with no covering index
-    * always_null_column  -- pg_stats null_frac = 1.0, carries no data
-    * single_value_column -- one distinct value across a large table
-
-  Every finding carries a reclaimable-bytes estimate (from row counts) and a
-  concrete fix. `generate-migration` emits a staged, reversible pair:
-  ignored_columns first, remove_column after a soak. Nothing is dropped
-  automatically. Columns owned by common gems (devise, paper_trail,
-  activestorage, actiontext, friendly_id, audited, pg_search, ahoy_matey,
-  paranoia) are whitelisted when the gem is in your bundle.
-
-  Reporters: table, json, markdown (PR comments), SARIF 2.1.0 (GitHub code
-  scanning). `scan --ci` gates only findings absent from a committed baseline.
-  `trend` keeps an append-only history log for cleanup burndown. A Rails
-  railtie adds rake tasks and an opt-in runtime tracker. Custom analyzers
-  load through the `require:` config key.
-
-  PostgreSQL only for now (MySQL adapter on the roadmap). Ruby >= 2.7.
+description: 'schema_reaper finds schema dead-weight in Rails/ActiveRecord + PostgreSQL
+  apps: dead columns and tables, unused, duplicate and missing foreign-key indexes,
+  and always-NULL or single-value columns. It cross-references the live schema and
+  pg_stats against a static scan of your code, with an optional production runtime
+  signal for higher confidence. Each finding is scored, carries a reclaimable-bytes
+  estimate, and ships with a staged, reversible migration. Reporters for terminal,
+  JSON, Markdown and SARIF; a CI baseline gate; a trend log; a Rails railtie. PostgreSQL
+  only for now; Ruby >= 2.7. See the README for full usage.'
 email:
 - akshatpegwar5@gmail.com
 executables:
@@ -188,6 +166,5 @@ requirements: []
 rubygems_version: 3.4.10
 signing_key: 
 specification_version: 4
-summary: Find dead columns, dead tables, unused indexes and other schema dead-weight
-  in Rails/ActiveRecord apps -- then remove it safely.
+summary: Find and safely remove schema dead-weight in Rails + PostgreSQL apps.
 test_files: []