schema_reaper 2.0.1 → 2.1.0

data/lib/schema_reaper/static/scanner.rb

@@ -5,10 +5,30 @@ require "set"
 
 module SchemaReaper
   module Static
+    # Everything a scan learned.
+    #   tokens       - Set<String>, every token in every scanned file
+    #   shared       - Set<String>, tokens from files that are not models
+    #   models       - Array<ModelFile>, one per ActiveRecord model file
+    #   keeps        - Hash{String => String}, `# schema_reaper:keep` targets
+    #                  => the reason given ("" when none)
+    Result = Struct.new(:tokens, :shared, :models, :keeps, keyword_init: true) do
+      def self.from_tokens(tokens)
+        new(tokens: tokens.to_set, shared: tokens.to_set, models: [], keeps: {})
+      end
+    end
+
+    # tables: every table this model file may be about -- one normally, two
+    # for a namespaced class (Admin::Report -> reports, or admin_reports with
+    # a table_name_prefix), the root model's for an STI subclass.
+    ModelFile = Struct.new(:path, :tables, :tokens, keyword_init: true)
+
     # Walks the project and collects every identifier/symbol/string token that
     # could name a database column. Over-collects on purpose: a false "used" is
     # safe, a false "dead" is not.
     class Scanner
+      # `# schema_reaper:keep legacy_token, users.api_key -- read by the billing ETL`
+      KEEP_RE = /#\s*schema_reaper:keep\s+(.+?)\s*(?:--\s*(.*?))?\s*$/.freeze
+
       RUBY_GLOB  = "**/*.rb"
       WORD_RE    = /[a-z_][a-z0-9_]*/i.freeze
 
@@ -59,14 +79,69 @@ module SchemaReaper
 
       # @return [Set<String>] lowercased tokens seen anywhere in the codebase
       def call
-        tokens = Set.new
-        ruby_files.each { |f| tokens.merge(ruby_tokens(f)) }
-        view_files.each { |f| tokens.merge(text_tokens(f)) }
-        tokens
+        scan.tokens
+      end
+
+      # @return [Result]
+      def scan
+        cache = Cache.new(@config.scan_cache && File.expand_path(@config.scan_cache, @root),
+                          key: [SchemaReaper::VERSION, MACRO_COLUMN_TEMPLATES.keys])
+        entries = ruby_files.map { |f| [f, cache.lookup(f, :ruby) { ruby_entry(f) }] } +
+                  view_files.map { |f| [f, cache.lookup(f, :view) { view_entry(f) }] }
+        cache.save(entries)
+        build_result(entries)
       end
 
       private
 
+      def build_result(entries)
+        tokens = Set.new
+        shared = Set.new
+        models = []
+        keeps = {}
+        tables = ModelResolver.new(entries.filter_map { |_, e| e["model"] }).tables
+        entries.each do |path, entry|
+          file_tokens = entry["tokens"].to_set
+          tokens.merge(file_tokens)
+          keeps.merge!(entry["keeps"])
+          model_tables = entry["model"] && tables[entry["model"]["path"]]
+          if model_tables
+            models << ModelFile.new(path: path, tables: model_tables, tokens: file_tokens)
+          else
+            shared.merge(file_tokens) # not a model we could place: its names count everywhere
+          end
+        end
+        Result.new(tokens: tokens, shared: shared, models: models, keeps: keeps)
+      end
+
+      def ruby_entry(path)
+        src = File.read(path)
+        {
+          "tokens" => ruby_tokens(path, src).to_a,
+          "model" => model_file?(path) ? ModelResolver.facts(src) : nil,
+          "keeps" => keeps_in(src)
+        }
+      rescue StandardError
+        view_entry(path)
+      end
+
+      def view_entry(path)
+        src = File.read(path)
+        { "tokens" => text_tokens(path).to_a, "model" => nil, "keeps" => keeps_in(src) }
+      rescue StandardError
+        { "tokens" => [], "model" => nil, "keeps" => {} }
+      end
+
+      def keeps_in(src)
+        src.scan(KEEP_RE).each_with_object({}) do |(targets, reason), out|
+          targets.split(/[\s,]+/).reject(&:empty?).each { |t| out[t.downcase] = reason.to_s }
+        end
+      end
+
+      def model_file?(path)
+        path.include?("/app/models/")
+      end
+
       def ruby_files
         @config.scan_paths.flat_map do |p|
           Dir.glob(File.join(@root, p, RUBY_GLOB))
@@ -77,8 +152,7 @@ module SchemaReaper
         @config.view_globs.flat_map { |g| Dir.glob(File.join(@root, g)) }.uniq
       end
 
-      def ruby_tokens(path)
-        src = File.read(path)
+      def ruby_tokens(path, src = File.read(path))
         out = Set.new
         result = Prism.parse(src)
         collect_from_node(result.value, out)
@@ -135,5 +209,99 @@ module SchemaReaper
         Set.new
       end
     end
+
+    # Maps model classes to the tables they read, from the facts the scanner
+    # collected. A class counts as a model only if it inherits from
+    # ApplicationRecord / ActiveRecord::Base / another abstract base, or from
+    # another model (STI); anything else in app/models -- a PORO, a Struct,
+    # a form object -- is not placed, so its names stay shared. Getting this
+    # wrong in the narrow direction would hide real use, so every doubt
+    # resolves to "shared".
+    class ModelResolver
+      AR_ROOTS = %w[ApplicationRecord ActiveRecord::Base].freeze
+
+      # What an app/models file says about the class it defines; ModelResolver
+      # turns these into tables once every file has been read (an STI
+      # subclass needs its parent's facts). A file with no `class X < Y` --
+      # a concern, a module -- has none and stays shared code.
+      def self.facts(src)
+        match = src.match(/^\s*class\s+((?:\w+::)*\w+)\s*<\s*((?:::)?[\w:]+)/)
+        return nil unless match
+
+        # `module Admin` wrapping the class namespaces it as much as `Admin::`
+        modules = src[0...match.begin(0)].scan(/^\s*module\s+([\w:]+)/).flatten.flat_map { |m| m.split("::") }
+        parts = modules + match[1].split("::")
+        {
+          "path" => parts.join("::"),          # Admin::User -- the identity
+          "class" => parts.last,
+          "namespace" => parts[0..-2].join("_"),
+          "superclass" => match[2],            # as written; resolved like Ruby would
+          "table" => src[/self\.table_name\s*=\s*["':]([\w.]+)/, 1],
+          "abstract" => src.match?(/self\.abstract_class\s*=\s*true/)
+        }
+      end
+
+      # Keyed by the full class path: User and Admin::User are different
+      # models, and keying by the bare name let one overwrite the other.
+      # A class reopened in a second file merges its facts.
+      def initialize(facts)
+        @by_path = facts.each_with_object({}) do |f, h|
+          h[f["path"]] = h.key?(f["path"]) ? h[f["path"]].merge(f) { |_, old, new| old || new } : f
+        end
+      end
+
+      # @return [Hash{String => Array<String>}] class path => tables; abstract
+      #   and unplaceable classes are absent
+      def tables
+        @by_path.each_key.with_object({}) do |path, out|
+          resolved = tables_for(path, Set.new)
+          out[path] = resolved if resolved&.any?
+        end
+      end
+
+      private
+
+      def tables_for(path, seen)
+        facts = @by_path[path]
+        return nil if facts.nil? || facts["abstract"] || seen.include?(path)
+
+        seen << path
+        return [facts["table"]] if facts["table"]
+        return own_tables(facts) if root?(facts)
+
+        parent = resolve(facts["superclass"], facts["path"])
+        tables_for(parent, seen) if parent # STI: the parent's table
+      end
+
+      def root?(facts)
+        sup = facts["superclass"].sub(/\A::/, "")
+        return true if AR_ROOTS.include?(sup) || AR_ROOTS.include?(sup.split("::").last)
+
+        base = @by_path[resolve(facts["superclass"], facts["path"])]
+        base && base["abstract"] && !base["table"]
+      end
+
+      # Ruby's constant lookup, approximately: `class Admin::Report < User`
+      # means Admin::User if that exists, else ::User. A leading :: skips
+      # straight to the top level. nil when no scanned model matches.
+      def resolve(name, from_path)
+        return @by_path.key?(name[2..]) ? name[2..] : nil if name.start_with?("::")
+
+        scope = from_path.split("::")[0..-2]
+        until scope.empty?
+          candidate = (scope + [name]).join("::")
+          return candidate if @by_path.key?(candidate)
+
+          scope = scope[0..-2]
+        end
+        @by_path.key?(name) ? name : nil
+      end
+
+      def own_tables(facts)
+        table = Inflect.tableize(facts["class"])
+        ns = facts["namespace"]
+        ns.empty? ? [table] : [table, "#{Inflect.underscore(ns)}_#{table}"]
+      end
+    end
   end
 end

data/lib/schema_reaper/version.rb

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

data/lib/schema_reaper.rb

@@ -2,11 +2,14 @@
 
 require_relative "schema_reaper/version"
 require_relative "schema_reaper/config"
+require_relative "schema_reaper/inflect"
 require_relative "schema_reaper/finding"
 require_relative "schema_reaper/schema"
+require_relative "schema_reaper/schema_locator"
 require_relative "schema_reaper/runtime"
 require_relative "schema_reaper/gem_awareness"
 require_relative "schema_reaper/introspect/postgres"
+require_relative "schema_reaper/static/cache"
 require_relative "schema_reaper/static/scanner"
 require_relative "schema_reaper/analyzers/base"
 require_relative "schema_reaper/analyzers/registry"
@@ -17,6 +20,8 @@ require_relative "schema_reaper/analyzers/duplicate_index"
 require_relative "schema_reaper/analyzers/missing_fk_index"
 require_relative "schema_reaper/analyzers/always_null_column"
 require_relative "schema_reaper/analyzers/single_value_column"
+require_relative "schema_reaper/analyzers/sequence_exhaustion"
+require_relative "schema_reaper/analyzers/duplicate_foreign_key"
 require_relative "schema_reaper/reporters/bytes"
 require_relative "schema_reaper/reporters/ansi"
 require_relative "schema_reaper/reporters/console"
@@ -31,6 +36,8 @@ 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/explain"
+require_relative "schema_reaper/doctor"
 require_relative "schema_reaper/scan_job" if defined?(ActiveJob::Base)
 require_relative "schema_reaper/railtie" if defined?(Rails::Railtie)
 

data/schema_reaper.gemspec

@@ -26,7 +26,6 @@ Gem::Specification.new do |spec|
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
   spec.metadata["homepage_uri"]      = spec.homepage
-  spec.metadata["source_code_uri"]   = spec.homepage
   spec.metadata["changelog_uri"]     = "#{spec.homepage}/blob/main/CHANGELOG.md"
   spec.metadata["bug_tracker_uri"]   = "#{spec.homepage}/issues"
   spec.metadata["documentation_uri"] = "#{spec.homepage}#readme"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schema_reaper
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - aksshatt
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-23 00:00:00.000000000 Z
+date: 2026-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -187,22 +187,29 @@ files:
 - lib/generators/schema_reaper/install/templates/schema_reaper_controller.rb.tt
 - lib/schema_reaper.rb
 - lib/schema_reaper/alert_config.rb
+- lib/schema_reaper/alert_state.rb
 - lib/schema_reaper/analyzers/always_null_column.rb
 - lib/schema_reaper/analyzers/base.rb
 - lib/schema_reaper/analyzers/dead_column.rb
 - lib/schema_reaper/analyzers/dead_table.rb
+- lib/schema_reaper/analyzers/duplicate_foreign_key.rb
 - lib/schema_reaper/analyzers/duplicate_index.rb
 - lib/schema_reaper/analyzers/missing_fk_index.rb
 - lib/schema_reaper/analyzers/registry.rb
+- lib/schema_reaper/analyzers/sequence_exhaustion.rb
 - lib/schema_reaper/analyzers/single_value_column.rb
 - lib/schema_reaper/analyzers/unused_index.rb
 - lib/schema_reaper/baseline.rb
 - lib/schema_reaper/cli.rb
+- lib/schema_reaper/cli/baseline_support.rb
 - lib/schema_reaper/config.rb
 - lib/schema_reaper/database_url.rb
+- lib/schema_reaper/doctor.rb
+- lib/schema_reaper/explain.rb
 - lib/schema_reaper/finding.rb
 - lib/schema_reaper/gem_awareness.rb
 - lib/schema_reaper/history.rb
+- lib/schema_reaper/inflect.rb
 - lib/schema_reaper/introspect/postgres.rb
 - lib/schema_reaper/mailer.rb
 - lib/schema_reaper/migration_generator.rb
@@ -216,12 +223,15 @@ files:
 - lib/schema_reaper/reporters/reclaim.rb
 - lib/schema_reaper/reporters/rollup.rb
 - lib/schema_reaper/reporters/sarif.rb
+- lib/schema_reaper/reporters/slack.rb
 - lib/schema_reaper/reporters/table.rb
 - 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/schema_locator.rb
+- lib/schema_reaper/static/cache.rb
 - lib/schema_reaper/static/scanner.rb
 - lib/schema_reaper/tasks/schema_reaper.rake
 - lib/schema_reaper/version.rb
@@ -233,7 +243,6 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/aksshatt/schema_reaper
-  source_code_uri: https://github.com/aksshatt/schema_reaper
   changelog_uri: https://github.com/aksshatt/schema_reaper/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/aksshatt/schema_reaper/issues
   documentation_uri: https://github.com/aksshatt/schema_reaper#readme
@@ -255,7 +264,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Find and safely remove schema dead-weight in Rails + PostgreSQL apps.