schema_sherlock 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5c7488ddd91bb0bb1721c72fc0d3e5045461274a68ce2fea71d0ebe280f1c627
+  data.tar.gz: 400b9b670b80856f543659a55e24e2d138509f578125af5b2821b96fd766d17f
+SHA512:
+  metadata.gz: 61fb4224786228806820ebf244672a8d493fa31a6561d8d9ce4f85ed9bdd03f9f16e869653a3dc0275d61b4c5d7e3fff083538fdd383c6887b2f05b793811221
+  data.tar.gz: 0234a850f322b90c9479542affc4ae8fae40df67c38395fd580f1f72ff683e2a17dee230d4fa918e336968a718cb4ad996165e59253adca3dc9f62b9acca0afe

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## [0.1.0] - 2025-01-23
+
+### Added
+- Smart association detection based on foreign keys
+- Usage-based filtering with configurable thresholds
+- Codebase scanning for foreign key usage patterns
+- CLI interface with analyze command
+- Configurable minimum usage threshold
+
+### Features
+- Detects missing `belongs_to` associations from foreign key columns
+- Validates foreign key references against existing tables
+- Tracks foreign key usage across Rails application
+- Filters suggestions based on actual usage frequency
+- Provides detailed analysis reports
+- Supports complex foreign key types (integer, bigint, UUID, string)
+- Smart table and model inference

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"

data/Gemfile.lock

@@ -0,0 +1,235 @@
+PATH
+  remote: .
+  specs:
+    schema_sherlock (0.1.0)
+      activerecord (>= 6.0)
+      rails (>= 6.0)
+      thor (~> 1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (8.0.2)
+      actionpack (= 8.0.2)
+      activesupport (= 8.0.2)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+      zeitwerk (~> 2.6)
+    actionmailbox (8.0.2)
+      actionpack (= 8.0.2)
+      activejob (= 8.0.2)
+      activerecord (= 8.0.2)
+      activestorage (= 8.0.2)
+      activesupport (= 8.0.2)
+      mail (>= 2.8.0)
+    actionmailer (8.0.2)
+      actionpack (= 8.0.2)
+      actionview (= 8.0.2)
+      activejob (= 8.0.2)
+      activesupport (= 8.0.2)
+      mail (>= 2.8.0)
+      rails-dom-testing (~> 2.2)
+    actionpack (8.0.2)
+      actionview (= 8.0.2)
+      activesupport (= 8.0.2)
+      nokogiri (>= 1.8.5)
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+      useragent (~> 0.16)
+    actiontext (8.0.2)
+      actionpack (= 8.0.2)
+      activerecord (= 8.0.2)
+      activestorage (= 8.0.2)
+      activesupport (= 8.0.2)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (8.0.2)
+      activesupport (= 8.0.2)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (8.0.2)
+      activesupport (= 8.0.2)
+      globalid (>= 0.3.6)
+    activemodel (8.0.2)
+      activesupport (= 8.0.2)
+    activerecord (8.0.2)
+      activemodel (= 8.0.2)
+      activesupport (= 8.0.2)
+      timeout (>= 0.4.0)
+    activestorage (8.0.2)
+      actionpack (= 8.0.2)
+      activejob (= 8.0.2)
+      activerecord (= 8.0.2)
+      activesupport (= 8.0.2)
+      marcel (~> 1.0)
+    activesupport (8.0.2)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    base64 (0.2.0)
+    benchmark (0.4.0)
+    bigdecimal (3.1.9)
+    builder (3.3.0)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.3)
+    crass (1.0.6)
+    date (3.4.1)
+    diff-lcs (1.6.2)
+    drb (2.2.3)
+    erb (5.0.1)
+    erubi (1.13.1)
+    globalid (1.2.1)
+      activesupport (>= 6.1)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.0)
+    irb (1.15.2)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    logger (1.7.0)
+    loofah (2.24.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.8.1)
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.0.4)
+    mini_mime (1.1.5)
+    minitest (5.25.5)
+    net-imap (0.5.8)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
+    nio4r (2.7.4)
+    nokogiri (1.18.8-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.8-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.8-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.8-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.8-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-linux-musl)
+      racc (~> 1.4)
+    pp (0.6.2)
+      prettyprint
+    prettyprint (0.2.0)
+    psych (5.2.6)
+      date
+      stringio
+    racc (1.8.1)
+    rack (3.1.15)
+    rack-session (2.1.1)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.2.1)
+      rack (>= 3)
+    rails (8.0.2)
+      actioncable (= 8.0.2)
+      actionmailbox (= 8.0.2)
+      actionmailer (= 8.0.2)
+      actionpack (= 8.0.2)
+      actiontext (= 8.0.2)
+      actionview (= 8.0.2)
+      activejob (= 8.0.2)
+      activemodel (= 8.0.2)
+      activerecord (= 8.0.2)
+      activestorage (= 8.0.2)
+      activesupport (= 8.0.2)
+      bundler (>= 1.15.0)
+      railties (= 8.0.2)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.6.2)
+      loofah (~> 2.21)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (8.0.2)
+      actionpack (= 8.0.2)
+      activesupport (= 8.0.2)
+      irb (~> 1.13)
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      zeitwerk (~> 2.6)
+    rake (13.2.1)
+    rdoc (6.14.0)
+      erb
+      psych (>= 4.0.0)
+    reline (0.6.1)
+      io-console (~> 0.5)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.3)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.4)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.4)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.3)
+    securerandom (0.4.1)
+    stringio (3.1.7)
+    thor (1.3.2)
+    timeout (0.4.3)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    uri (1.0.3)
+    useragent (0.16.11)
+    websocket-driver (0.7.7)
+      base64
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.7.3)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  schema_sherlock!
+
+BUNDLED WITH
+   2.6.3

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Schema Sherlock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,72 @@
+# SchemaSherlock
+
+Intelligent Rails model analysis and annotation tool that extends beyond traditional schema annotation to provide intelligent analysis and actionable suggestions for Rails model code quality, performance, and maintainability.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'schema_sherlock', group: :development
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install schema_sherlock
+
+## Usage
+
+### Basic Commands
+
+```bash
+# Analyze all models
+schema_sherlock analyze
+
+# Analyze specific model
+schema_sherlock analyze User
+
+# Override minimum usage threshold
+schema_sherlock analyze --min-usage 1
+
+# Use rake tasks instead
+rake schema_sherlock:analyze
+rake schema_sherlock:analyze_model[User]
+```
+
+### Configuration
+
+Create a configuration file in your Rails application:
+
+```ruby
+# config/initializers/schema_sherlock.rb
+SchemaSherlock.configure do |config|
+  config.exclude_models = ['ActiveRecord::Base']  # Models to exclude from analysis
+  config.min_usage_threshold = 3  # Minimum usage count for foreign key suggestions
+end
+```
+
+## Features
+
+- **Smart Association Detection**: Identifies missing associations based on foreign keys
+- **Usage-Based Filtering**: Only suggests associations for frequently used foreign keys
+- **Codebase Analysis**: Scans your code to track foreign key usage patterns
+- **Configurable Thresholds**: Set minimum usage requirements for suggestions
+- **Rails Integration**: Works via CLI, rake tasks, or directly in models
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/prateekkish/schema_sherlock.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: [:spec]

data/bin/schema_sherlock

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require_relative "../lib/schema_sherlock"
+require_relative "../lib/schema_sherlock/commands/analyze_command"
+
+SchemaSherlock::Commands::AnalyzeCommand.start(ARGV)

data/lib/schema_sherlock/analyzers/base_analyzer.rb

@@ -0,0 +1,34 @@
+module SchemaSherlock
+  module Analyzers
+    class BaseAnalyzer
+      attr_reader :model_class, :results
+
+      def initialize(model_class)
+        @model_class = model_class
+        @results = {}
+      end
+
+      def analyze
+        raise NotImplementedError, "Subclasses must implement #analyze"
+      end
+
+      private
+
+      def model_name
+        @model_class.name
+      end
+
+      def table_name
+        @model_class.table_name
+      end
+
+      def columns
+        @model_class.columns
+      end
+
+      def associations
+        @model_class.reflect_on_all_associations
+      end
+    end
+  end
+end

data/lib/schema_sherlock/analyzers/foreign_key_detector.rb

@@ -0,0 +1,180 @@
+require_relative "base_analyzer"
+require_relative "../usage_tracker"
+
+module SchemaSherlock
+  module Analyzers
+    class ForeignKeyDetector < BaseAnalyzer
+      # Common integer types that can reference each other
+      INTEGER_TYPES = %w[integer bigint].freeze
+      # UUID types that can reference each other
+      UUID_TYPES = %w[uuid].freeze
+      # String types that might be used for UUIDs
+      STRING_TYPES = %w[string text].freeze
+
+      def analyze
+        @results = {
+          missing_associations: find_missing_associations,
+          orphaned_foreign_keys: find_orphaned_foreign_keys,
+          usage_stats: get_usage_stats
+        }
+      end
+
+      private
+
+      def find_missing_associations
+        usage_stats = get_usage_stats
+        min_threshold = SchemaSherlock.configuration.min_usage_threshold
+
+        foreign_key_columns.reject do |column|
+          has_association_for_column?(column)
+        end.select do |column|
+          # Only suggest if usage meets minimum threshold
+          usage_count = usage_stats[column.name] || 0
+          usage_count >= min_threshold
+        end.map do |column|
+          {
+            column: column.name,
+            suggested_association: suggest_association_name(column),
+            type: :belongs_to,
+            usage_count: usage_stats[column.name] || 0
+          }
+        end
+      end
+
+      def find_orphaned_foreign_keys
+        # Find foreign key columns that don't have corresponding tables
+        foreign_key_columns.select do |column|
+          referenced_table = infer_table_name(column)
+          !table_exists?(referenced_table)
+        end.map do |column|
+          {
+            column: column.name,
+            inferred_table: infer_table_name(column),
+            issue: "Referenced table does not exist"
+          }
+        end
+      end
+
+      def foreign_key_columns
+        columns.select { |col| col.name.end_with?('_id') && col.name != 'id' && valid_foreign_key?(col) }
+      end
+
+      def has_association_for_column?(column)
+        association_name = column.name.gsub(/_id$/, '')
+        associations.any? do |assoc|
+          assoc.name.to_s == association_name ||
+          assoc.foreign_key == column.name
+        end
+      end
+
+      def suggest_association_name(column)
+        column.name.gsub(/_id$/, '')
+      end
+
+      def infer_table_name(column)
+        association_name = suggest_association_name(column)
+        association_name.pluralize
+      end
+
+      def table_exists?(table_name)
+        ActiveRecord::Base.connection.table_exists?(table_name)
+      end
+
+      def valid_foreign_key?(column)
+        # Check if the column actually references an existing table's primary key
+        referenced_table = infer_table_name(column)
+
+        # First check if the table exists
+        return false unless table_exists?(referenced_table)
+
+        # Then check if the referenced table has a primary key that matches the column type
+        begin
+          referenced_model_class = referenced_table.classify.constantize
+          primary_key_column = referenced_model_class.columns.find { |col| col.name == referenced_model_class.primary_key }
+
+          # Compare column types to ensure they're compatible
+          return false unless primary_key_column
+
+          # Check if the types are compatible (both should be integer-like for _id columns)
+          compatible_types?(column, primary_key_column)
+        rescue NameError
+          # If we can't find the model class, check if table has an 'id' column
+          check_table_primary_key(referenced_table, column)
+        end
+      end
+
+      private
+
+      def compatible_types?(foreign_key_column, primary_key_column)
+        fk_type = foreign_key_column.type.to_s
+        pk_type = primary_key_column.type.to_s
+
+        # Check for integer compatibility
+        return true if INTEGER_TYPES.include?(fk_type) && INTEGER_TYPES.include?(pk_type)
+
+        # Check for UUID compatibility
+        return true if UUID_TYPES.include?(fk_type) && UUID_TYPES.include?(pk_type)
+
+        # Check for string-based UUID compatibility (common when using string columns for UUIDs)
+        return true if STRING_TYPES.include?(fk_type) && STRING_TYPES.include?(pk_type) &&
+                      likely_uuid_column?(foreign_key_column, primary_key_column)
+
+        # Cross-compatibility: string foreign key referencing UUID primary key (or vice versa)
+        return true if (STRING_TYPES.include?(fk_type) && UUID_TYPES.include?(pk_type)) ||
+                      (UUID_TYPES.include?(fk_type) && STRING_TYPES.include?(pk_type))
+
+        false
+      end
+
+      def likely_uuid_column?(foreign_key_column, primary_key_column)
+        # Check if string columns are likely to be UUIDs based on common patterns
+        # This helps when applications use string columns to store UUIDs
+
+        # Check column limits (UUIDs are typically 36 characters with dashes, 32 without)
+        fk_limit = foreign_key_column.respond_to?(:limit) ? foreign_key_column.limit : nil
+        pk_limit = primary_key_column.respond_to?(:limit) ? primary_key_column.limit : nil
+
+        # Common UUID string lengths
+        uuid_lengths = [32, 36]
+
+        # If both columns have limits that match UUID lengths, likely UUIDs
+        return true if fk_limit && pk_limit &&
+                      uuid_lengths.include?(fk_limit) && uuid_lengths.include?(pk_limit)
+
+        # Check column names for UUID patterns
+        uuid_name_patterns = %w[uuid guid]
+        fk_name_lower = foreign_key_column.name.downcase
+        pk_name_lower = primary_key_column.name.downcase
+
+        uuid_name_patterns.any? do |pattern|
+          fk_name_lower.include?(pattern) || pk_name_lower.include?(pattern)
+        end
+      end
+
+      def check_table_primary_key(table_name, foreign_key_column)
+        # Fallback method when model class is not available
+        # Check if the table has an 'id' column with compatible type
+        begin
+          connection = ActiveRecord::Base.connection
+          primary_key_name = connection.primary_key(table_name)
+
+          return false unless primary_key_name
+
+          table_columns = connection.columns(table_name)
+          primary_key_column = table_columns.find { |col| col.name == primary_key_name }
+
+          return false unless primary_key_column
+
+          compatible_types?(foreign_key_column, primary_key_column)
+        rescue
+          # If there's any error accessing the table structure, be conservative and return false
+          false
+        end
+      end
+
+      def get_usage_stats
+        @usage_stats ||= UsageTracker.track_foreign_key_usage(@model_class)
+      end
+    end
+  end
+end

data/lib/schema_sherlock/commands/analyze_command.rb

@@ -0,0 +1,111 @@
+require_relative "base_command"
+require_relative "../analyzers/foreign_key_detector"
+
+module SchemaSherlock
+  module Commands
+    class AnalyzeCommand < BaseCommand
+      desc "analyze [MODEL]", "Analyze models for missing associations and optimization opportunities"
+      option :output, type: :string, desc: "Output file for analysis results"
+      option :min_usage, type: :numeric, desc: "Minimum usage threshold for suggestions (overrides config)"
+
+      def analyze(model_name = nil)
+        load_rails_environment
+
+        # Override configuration if min_usage option provided
+        if options[:min_usage]
+          original_threshold = SchemaSherlock.configuration.min_usage_threshold
+          SchemaSherlock.configuration.min_usage_threshold = options[:min_usage]
+        end
+
+        models = model_name ? [find_model(model_name)] : all_models
+
+        puts "Analyzing #{models.length} model(s)..."
+
+        results = {}
+
+        models.each do |model|
+          puts "  Analyzing #{model.name}..."
+          analysis = analyze_model(model)
+
+          # Only include models with issues in results
+          if has_issues?(analysis)
+            results[model.name] = analysis
+          end
+        end
+
+        display_results(results, models.length)
+        save_results(results) if options[:output]
+      rescue SchemaSherlock::Error => e
+        say e.message, :red
+        exit 1
+      ensure
+        # Restore original threshold if it was overridden
+        if options[:min_usage] && defined?(original_threshold)
+          SchemaSherlock.configuration.min_usage_threshold = original_threshold
+        end
+      end
+
+      private
+
+      def analyze_model(model)
+        {
+          foreign_key_analysis: run_foreign_key_analysis(model)
+        }
+      end
+
+      def run_foreign_key_analysis(model)
+        analyzer = SchemaSherlock::Analyzers::ForeignKeyDetector.new(model)
+        analyzer.analyze
+        analyzer.results
+      end
+
+      def has_issues?(analysis)
+        foreign_key_analysis = analysis[:foreign_key_analysis]
+        missing = foreign_key_analysis[:missing_associations]
+        orphaned = foreign_key_analysis[:orphaned_foreign_keys]
+
+        missing.any? || orphaned.any?
+      end
+
+      def display_results(results, total_models)
+        puts "\n" + "="*50
+        puts "Schema Sherlock Investigation Report"
+        puts "="*50
+
+        results.each do |model_name, analysis|
+          puts "\n#{model_name}:"
+
+          missing = analysis[:foreign_key_analysis][:missing_associations]
+          if missing.any?
+            puts "  Missing Associations:"
+            missing.each do |assoc|
+              usage_info = assoc[:usage_count] ? " (used #{assoc[:usage_count]} times)" : ""
+              puts "    belongs_to :#{assoc[:suggested_association]} # #{assoc[:column]} foreign key exists#{usage_info}"
+            end
+          end
+
+          orphaned = analysis[:foreign_key_analysis][:orphaned_foreign_keys]
+          if orphaned.any?
+            puts "  Orphaned Foreign Keys:"
+            orphaned.each do |key|
+              puts "    #{key[:column]} -> #{key[:issue]}"
+            end
+          end
+        end
+
+        puts "\n" + "="*50
+        puts "SUMMARY"
+        puts "="*50
+        puts "Models Analyzed: #{total_models}"
+        puts "Models with Issues: #{results.length}"
+        puts "Models without Issues: #{total_models - results.length}"
+        puts "Usage Threshold: #{SchemaSherlock.configuration.min_usage_threshold} occurrences"
+      end
+
+      def save_results(results)
+        File.write(options[:output], results.to_json)
+        puts "\nResults saved to #{options[:output]}"
+      end
+    end
+  end
+end

data/lib/schema_sherlock/commands/base_command.rb

@@ -0,0 +1,32 @@
+require "thor"
+require_relative "../model_loader"
+
+module SchemaSherlock
+  module Commands
+    class BaseCommand < Thor
+      protected
+
+      def load_rails_environment
+        unless defined?(Rails)
+          # Try to load Rails if not already loaded
+          config_path = File.expand_path("config/environment.rb", Dir.pwd)
+          if File.exist?(config_path)
+            require config_path
+          else
+            raise SchemaSherlock::Error, "Rails environment not found. Make sure you're running this from a Rails application root."
+          end
+        end
+      rescue LoadError => e
+        raise SchemaSherlock::Error, "Could not load Rails environment: #{e.message}"
+      end
+
+      def all_models
+        ModelLoader.all_models
+      end
+
+      def find_model(name)
+        ModelLoader.find_model(name)
+      end
+    end
+  end
+end

data/lib/schema_sherlock/configuration.rb

@@ -0,0 +1,11 @@
+module SchemaSherlock
+  class Configuration
+    attr_accessor :exclude_models,
+                  :min_usage_threshold
+
+    def initialize
+      @exclude_models = ['ActiveRecord::Base']
+      @min_usage_threshold = 3
+    end
+  end
+end

data/lib/schema_sherlock/model_loader.rb

@@ -0,0 +1,76 @@
+module SchemaSherlock
+  module ModelLoader
+    class << self
+      def all_models
+        ensure_rails_loaded!
+        load_application_models
+
+        ActiveRecord::Base.descendants.select do |klass|
+          includable_model?(klass)
+        end
+      end
+
+      def find_model(name)
+        ensure_rails_loaded!
+
+        klass = name.safe_constantize || name.camelize.safe_constantize
+
+        unless klass
+          raise SchemaSherlock::Error, "Could not find model: #{name}"
+        end
+
+        unless klass < ActiveRecord::Base
+          raise SchemaSherlock::Error, "#{name} is not an ActiveRecord model"
+        end
+
+        unless klass.table_exists?
+          raise SchemaSherlock::Error, "Table for #{name} does not exist"
+        end
+
+        klass
+      end
+
+      private
+
+      def ensure_rails_loaded!
+        unless defined?(Rails) && Rails.application
+          raise SchemaSherlock::Error, "Rails application not loaded"
+        end
+      end
+
+      def load_application_models
+        # Use Rails standard eager loading
+        Rails.application.eager_load!
+
+        # Also try to load models from common directories
+        %w[app/models app/models/concerns].each do |dir|
+          path = Rails.root.join(dir)
+          next unless path.exist?
+
+          Dir.glob(path.join("**/*.rb")).each do |file|
+            require_dependency file
+          rescue LoadError, NameError
+            # Skip files that can't be loaded
+          end
+        end
+      end
+
+      def includable_model?(klass)
+        return false unless klass.name
+        return false if klass.abstract_class?
+        return false if klass.name.start_with?("HABTM_")
+        return false unless klass.table_exists?
+        return false if excluded_model?(klass)
+
+        true
+      rescue => e
+        # Skip models that raise errors
+        false
+      end
+
+      def excluded_model?(klass)
+        SchemaSherlock.configuration.exclude_models.include?(klass.name)
+      end
+    end
+  end
+end

data/lib/schema_sherlock/usage_tracker.rb

@@ -0,0 +1,79 @@
+module SchemaSherlock
+  class UsageTracker
+    class << self
+      def track_foreign_key_usage(model_class)
+        return {} unless SchemaSherlock.configuration.min_usage_threshold
+
+        scan_codebase_for_usage(model_class)
+      end
+
+
+      private
+
+      def scan_codebase_for_usage(model_class)
+        usage_counts = {}
+        table_name = model_class.table_name
+
+        foreign_key_columns(model_class).each do |column|
+          count = scan_for_column_usage(table_name, column.name)
+          usage_counts[column.name] = count if count > 0
+        end
+
+        usage_counts
+      end
+
+      def foreign_key_columns(model_class)
+        model_class.columns.select { |col| col.name.end_with?('_id') && col.name != 'id' }
+      end
+
+      def scan_for_column_usage(table_name, column_name)
+        count = 0
+
+        # Scan common Rails directories for usage patterns
+        scan_directories.each do |dir|
+          next unless Dir.exist?(dir)
+
+          Dir.glob("#{dir}/**/*.rb").each do |file|
+            content = File.read(file)
+            count += count_column_references(content, table_name, column_name)
+          rescue
+            # Skip files that can't be read
+          end
+        end
+
+        count
+      end
+
+      def scan_directories
+        return [] unless defined?(Rails) && Rails.root
+
+        [
+          Rails.root.join('app', 'controllers'),
+          Rails.root.join('app', 'models'),
+          Rails.root.join('app', 'services'),
+          Rails.root.join('app', 'jobs'),
+          Rails.root.join('lib')
+        ].map(&:to_s)
+      end
+
+
+      def count_column_references(content, table_name, column_name)
+        count = 0
+
+        # Count WHERE clauses using the foreign key
+        count += content.scan(/\.where\s*\(\s*['":]?#{column_name}['":]?\s*[=:]/i).length
+        count += content.scan(/\.find_by\s*\(\s*['":]?#{column_name}['":]?\s*[=:]/i).length
+
+        # Count joins using the foreign key
+        association_name = column_name.gsub(/_id$/, '')
+        count += content.scan(/\.joins\s*\(\s*['":]?#{association_name}['":]?\s*\)/i).length
+        count += content.scan(/\.includes\s*\(\s*['":]?#{association_name}['":]?\s*\)/i).length
+
+        # Count direct foreign key access
+        count += content.scan(/\.#{column_name}\b/i).length
+
+        count
+      end
+    end
+  end
+end

data/lib/schema_sherlock/version.rb

@@ -0,0 +1,3 @@
+module SchemaSherlock
+  VERSION = "0.1.0"
+end

data/lib/schema_sherlock.rb

@@ -0,0 +1,19 @@
+require_relative "schema_sherlock/version"
+require_relative "schema_sherlock/configuration"
+require_relative "schema_sherlock/railtie" if defined?(Rails)
+
+module SchemaSherlock
+  class Error < StandardError; end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.reset_configuration!
+    @configuration = Configuration.new
+  end
+end

data/schema_sherlock.gemspec

@@ -0,0 +1,36 @@
+require_relative "lib/schema_sherlock/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "schema_sherlock"
+  spec.version = SchemaSherlock::VERSION
+  spec.authors = ["Prateek Choudhary"]
+  spec.email = ["prateekkish@gmail.com"]
+
+  spec.summary = "Intelligent Rails model analysis and annotation tool"
+  spec.description = "Extends beyond traditional schema annotation to provide intelligent analysis and actionable suggestions for Rails model code quality, performance, and maintainability."
+  spec.homepage = "https://github.com/prateekkish/schema_sherlock"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/prateekkish/schema_sherlock"
+  spec.metadata["changelog_uri"] = "https://github.com/prateekkish/schema_sherlock/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.executables = ["schema_sherlock"]
+  spec.require_paths = ["lib"]
+
+  # Dependencies
+  spec.add_dependency "rails", ">= 6.0"
+  spec.add_dependency "thor", "~> 1.0"
+  spec.add_dependency "activerecord", ">= 6.0"
+
+  # Development dependencies
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: schema_sherlock
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Prateek Choudhary
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-05-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Extends beyond traditional schema annotation to provide intelligent analysis
+  and actionable suggestions for Rails model code quality, performance, and maintainability.
+email:
+- prateekkish@gmail.com
+executables:
+- schema_sherlock
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.md
+- README.md
+- Rakefile
+- bin/schema_sherlock
+- lib/schema_sherlock.rb
+- lib/schema_sherlock/analyzers/base_analyzer.rb
+- lib/schema_sherlock/analyzers/foreign_key_detector.rb
+- lib/schema_sherlock/commands/analyze_command.rb
+- lib/schema_sherlock/commands/base_command.rb
+- lib/schema_sherlock/configuration.rb
+- lib/schema_sherlock/model_loader.rb
+- lib/schema_sherlock/usage_tracker.rb
+- lib/schema_sherlock/version.rb
+- schema_sherlock.gemspec
+homepage: https://github.com/prateekkish/schema_sherlock
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/prateekkish/schema_sherlock
+  source_code_uri: https://github.com/prateekkish/schema_sherlock
+  changelog_uri: https://github.com/prateekkish/schema_sherlock/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Intelligent Rails model analysis and annotation tool
+test_files: []