rails_lens 0.5.4 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e504fa26391d500a945947795688a4a52a23922e0ea6a760762415c698d91fc
-  data.tar.gz: 800c91d7df514dc2c745235cf9f5423a7a68d6499cee7221d5cb89adaa95157b
+  metadata.gz: d3be7f4e3942405ae7fcd4d50998f62db251786490ebf01cf71637dd3715783a
+  data.tar.gz: 712440cb4e800e14b4c10739228144bcbf8308a79fb3b73593df8ccbb7e52b67
 SHA512:
-  metadata.gz: 0c17d650e862adcf76e32d7a4a5398cd8c4827b8dd0e0424f01e307a76285e18001c5431561807a049695fbe3c4eaf68960add7d139427b1fcabb36ef2692e06
-  data.tar.gz: 31bf7b191ec9f5dfedabf351798d38b217a71b85c9ceba7e458ed7b45d61662b367989a40b3e311f9fc1e21f270eacbf55e6998e5b28ff0114fa0b5b37b9ab80
+  metadata.gz: 3bcbf3d18443edeb680ab8fa4fd7a3be4c4d95dcf47566c421fb8d0f57ff63deb7ec42d4bf8298154a77093d1b1385213c476a61d5b1b0c37ff2f33a2e867e9f
+  data.tar.gz: 1af1394845cc4c6db4e15b2004379100f959b073abee2efab52d77ce3c88ada3939e61e74f458f1e36e4eedd92bb93ef2b3fbb2b30c2ad972584bcaebb2553d2

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.10.1](https://github.com/seuros/rails_lens/compare/rails_lens/v0.10.0...rails_lens/v0.10.1) (2026-10-15)
+
+
+### Bug Fixes
+
+* keep the WHERE clause of partial indexes in annotations ([#50](https://github.com/seuros/rails_lens/issues/50)) ([351476e](https://github.com/seuros/rails_lens/commit/351476e03d98e5fb0c506cf7c63e13680230a804))
+* pluralize model/file counts in CLI and rake output ([#47](https://github.com/seuros/rails_lens/issues/47)) ([d870c6c](https://github.com/seuros/rails_lens/commit/d870c6c5128177a6324bc2db17f32be1538e73da))
+
+## [0.10.0](https://github.com/seuros/rails_lens/compare/rails_lens/v0.5.4...rails_lens/v0.10.0) (2026-08-10)
+
+
+### Features
+
+* composite primary keys ([#45](https://github.com/seuros/rails_lens/issues/45)) ([8d934b5](https://github.com/seuros/rails_lens/commit/8d934b51b310252ce42f3db9aa85894161d562f3))
+
 ## [0.5.4](https://github.com/seuros/rails_lens/compare/rails_lens/v0.5.3...rails_lens/v0.5.4) (2026-06-26)
 
 

data/README.md

@@ -120,7 +120,7 @@ erDiagram
 ## Requirements
 
 - Ruby >= 3.4.0
-- Rails >= 7.2.0
+- Rails >= 8.0.0
 
 ## Installation
 

data/lib/rails_lens/analyzers/composite_keys.rb

@@ -4,22 +4,10 @@ module RailsLens
   module Analyzers
     class CompositeKeys < Base
       def analyze
-        # First try Rails native support
-        if model_class.respond_to?(:primary_keys) && model_class.primary_keys.is_a?(Array)
-          keys = model_class.primary_keys
-          return format_composite_keys(keys) if keys.length > 1
-        end
+        pk = model_class.primary_key
+        return nil unless pk.is_a?(Array)
 
-        # For PostgreSQL, check the actual database constraints
-        if adapter_name == 'PostgreSQL'
-          keys = detect_composite_primary_key_from_db
-          return format_composite_keys(keys) if keys && keys.length > 1
-        end
-
-        nil
-      rescue NoMethodError => e
-        RailsLens.logger.debug { "Failed to analyze composite keys for #{model_class.name}: #{e.message}" }
-        nil
+        format_composite_keys(pk)
       rescue ActiveRecord::ConnectionNotEstablished => e
         RailsLens.logger.debug { "No database connection for #{model_class.name}: #{e.message}" }
         nil
@@ -32,28 +20,6 @@ module RailsLens
         lines << "keys = #{TomlFormat.quoted_array(keys)}"
         lines.join("\n")
       end
-
-      def detect_composite_primary_key_from_db
-        # Query PostgreSQL system catalogs to find composite primary keys
-        sql = <<~SQL.squish
-          SELECT a.attname
-          FROM pg_index i
-          JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY(i.indkey)
-          WHERE i.indrelid = '#{table_name}'::regclass
-            AND i.indisprimary
-          ORDER BY array_position(i.indkey, a.attnum)
-        SQL
-
-        result = connection.execute(sql)
-        keys = result.pluck('attname')
-        keys.empty? ? nil : keys
-      rescue ActiveRecord::StatementInvalid => e
-        RailsLens.logger.debug { "Failed to detect composite keys from database for #{table_name}: #{e.message}" }
-        nil
-      rescue PG::Error => e
-        RailsLens.logger.debug { "PostgreSQL error detecting composite keys: #{e.message}" }
-        nil
-      end
     end
   end
 end

data/lib/rails_lens/analyzers/inheritance.rb

@@ -162,11 +162,10 @@ module RailsLens
                     else
                       []
                     end
-            if types.any?
-              "{ name = \"#{reflection.name}\", type_col = \"#{reflection.foreign_type}\", id_col = \"#{reflection.foreign_key}\", types = #{TomlFormat.quoted_array(types)} }"
-            else
-              "{ name = \"#{reflection.name}\", type_col = \"#{reflection.foreign_type}\", id_col = \"#{reflection.foreign_key}\" }"
-            end
+            fields = "name = \"#{reflection.name}\", type_col = \"#{reflection.foreign_type}\", " \
+                     "id_col = \"#{reflection.foreign_key}\""
+            fields += ", types = #{TomlFormat.quoted_array(types)}" if types.any?
+            "{ #{fields} }"
           end
           lines << "references = [#{refs.join(', ')}]"
         end

data/lib/rails_lens/analyzers/notes.rb

@@ -222,7 +222,8 @@ module RailsLens
         end
 
         # Check for STI without index
-        if model_class.inheritance_column && column_exists?(model_class.inheritance_column) && !has_index?(model_class.inheritance_column)
+        if model_class.inheritance_column && column_exists?(model_class.inheritance_column) &&
+           !has_index?(model_class.inheritance_column)
           notes << NoteCodes.note(model_class.inheritance_column, NoteCodes::STI_INDEX)
         end
 
@@ -327,7 +328,8 @@ module RailsLens
       def associations_needing_counter_cache
         belongs_to_associations.select do |association|
           # Check if the inverse association exists and is commonly counted
-          inverse = association.klass.reflect_on_association(association.inverse_of&.name || model_class.name.underscore.pluralize)
+          inverse_name = association.inverse_of&.name || model_class.name.underscore.pluralize
+          inverse = association.klass.reflect_on_association(inverse_name)
           inverse && inverse.macro == :has_many && !association.options[:counter_cache]
         rescue NameError => e
           RailsLens.logger.debug { "Failed to check counter cache for association: #{e.message}" }

data/lib/rails_lens/cli.rb

@@ -21,7 +21,8 @@ module RailsLens
     desc 'annotate', 'Annotate Rails models with schema information'
     option :models, type: :array, desc: 'Specific models to annotate'
     option :include_abstract, type: :boolean, desc: 'Include abstract classes'
-    option :include_database_objects, type: :boolean, default: true, desc: 'Include database objects (functions, etc.) in abstract classes'
+    option :include_database_objects, type: :boolean, default: true,
+                                      desc: 'Include database objects (functions, etc.) in abstract classes'
     option :position, type: :string, enum: %w[before after top bottom], desc: 'Annotation position'
     option :routes, type: :boolean, desc: 'Annotate controller routes'
     option :mailers, type: :boolean, desc: 'Annotate mailer methods'

data/lib/rails_lens/commands.rb

@@ -14,8 +14,8 @@ module RailsLens
     def annotate_models(options = {})
       results = Schema::AnnotationManager.annotate_all(options)
 
-      output.say "Annotated #{results[:annotated].length} models", :green
-      report_skipped_and_failed(results, 'models')
+      output.say "Annotated #{count_of(results[:annotated], 'model')}", :green
+      report_skipped_and_failed(results, 'model')
 
       # Also annotate database-level objects (functions, etc.)
       if options[:include_database_objects]
@@ -29,39 +29,40 @@ module RailsLens
     def annotate_database_objects(options = {})
       results = Schema::DatabaseAnnotator.annotate_all(options)
 
-      output.say "Annotated #{results[:annotated].length} abstract base classes with database objects", :green
-      report_skipped_and_failed(results, 'abstract classes')
+      output.say "Annotated #{count_of(results[:annotated], 'abstract base class')} with database objects", :green
+      report_skipped_and_failed(results, 'abstract class')
 
       results
     end
 
     def annotate_routes(options = {})
-      annotate_files(Route::Annotator.new(dry_run: options[:dry_run]), 'controller files with routes', options)
+      annotate_files(Route::Annotator.new(dry_run: options[:dry_run]), 'controller file', options,
+                     suffix: 'with routes')
     end
 
     def annotate_mailers(options = {})
-      annotate_files(Mailer::Annotator.new(dry_run: options[:dry_run]), 'mailer files', options)
+      annotate_files(Mailer::Annotator.new(dry_run: options[:dry_run]), 'mailer file', options)
     end
 
     def remove_models(options = {})
       results = Schema::AnnotationManager.remove_all(options)
-      output.say "Removed annotations from #{results[:removed].length} models", :green
+      output.say "Removed annotations from #{count_of(results[:removed], 'model')}", :green
       results
     end
 
     def remove_routes(options = {})
-      remove_files(Route::Annotator.new(dry_run: options[:dry_run]), 'route', 'controller files')
+      remove_files(Route::Annotator.new(dry_run: options[:dry_run]), 'route', 'controller file')
     end
 
     def remove_mailers(options = {})
-      remove_files(Mailer::Annotator.new(dry_run: options[:dry_run]), 'mailer', 'mailer files')
+      remove_files(Mailer::Annotator.new(dry_run: options[:dry_run]), 'mailer', 'mailer file')
     end
 
     def generate_erd(options = {})
       visualizer = ERD::Visualizer.new(options: options)
-      filename = visualizer.generate
-      output.say "Entity Relationship Diagram generated at #{filename}", :green
-      filename
+      filenames = Array(visualizer.generate)
+      filenames.each { |filename| output.say "Entity Relationship Diagram generated at #{filename}", :green }
+      filenames.length == 1 ? filenames.first : filenames
     end
 
     def lint(options = {})
@@ -195,27 +196,33 @@ module RailsLens
 
     private
 
+    # "1 model" / "0 models" — count plus the correctly inflected noun.
+    def count_of(countable, singular)
+      count = countable.respond_to?(:length) ? countable.length : countable
+      "#{count} #{singular.pluralize(count)}"
+    end
+
     # Report skipped/failed counts for a model-annotation results hash.
     def report_skipped_and_failed(results, noun)
-      output.say "Skipped #{results[:skipped].length} #{noun}", :yellow if results[:skipped].any?
+      output.say "Skipped #{count_of(results[:skipped], noun)}", :yellow if results[:skipped].any?
       return unless results[:failed].any?
 
-      output.say "Failed to annotate #{results[:failed].length} #{noun}:", :red
+      output.say "Failed to annotate #{count_of(results[:failed], noun)}:", :red
       results[:failed].each do |failure|
         output.say "  - #{failure[:model]}: #{failure[:error]}", :red
       end
     end
 
-    def annotate_files(annotator, label, options)
+    def annotate_files(annotator, singular, options, suffix: nil)
       changed_files = annotator.annotate_all
-      output.say "Annotated #{changed_files.length} #{label}", :green
+      output.say ["Annotated #{count_of(changed_files, singular)}", suffix].compact.join(' '), :green
       changed_files.each { |file| output.say "  - #{file}", :blue } if options[:verbose] && changed_files.any?
       { changed_files: changed_files }
     end
 
-    def remove_files(annotator, kind, target)
+    def remove_files(annotator, kind, singular)
       changed_files = annotator.remove_all
-      output.say "Removed #{kind} annotations from #{changed_files.length} #{target}", :green
+      output.say "Removed #{kind} annotations from #{count_of(changed_files, singular)}", :green
       { changed_files: changed_files }
     end
 
@@ -255,8 +262,10 @@ module RailsLens
               # Use RailsLens directly if available
               if defined?(RailsLens)
                 results = RailsLens::Schema::AnnotationManager.annotate_all
-                puts "Rails Lens: Annotated \#{results[:annotated].length} models"
-                puts "Rails Lens: Skipped \#{results[:skipped].length} models" if results[:skipped].any?
+                annotated = results[:annotated].length
+                skipped = results[:skipped].length
+                puts "Rails Lens: Annotated \#{annotated} \#{'model'.pluralize(annotated)}"
+                puts "Rails Lens: Skipped \#{skipped} \#{'model'.pluralize(skipped)}" if skipped.positive?
               else
                 # Fallback to CLI
                 system('bundle exec rails_lens annotate --quiet')

data/lib/rails_lens/erd/column_type_formatter.rb

@@ -24,7 +24,12 @@ module RailsLens
         when :binary then 'blob'
         when :json, :jsonb then 'json'
         else
-          @column.type.to_s
+          # column.type is nil for types the adapter can't resolve (e.g. a
+          # PostGIS geometry column without activerecord-postgis loaded);
+          # the diagram gem rejects empty attribute types.
+          fallback = @column.type.to_s
+          fallback = @column.sql_type.to_s if fallback.empty?
+          fallback.empty? ? 'unknown' : fallback
         end
       end
     end

data/lib/rails_lens/erd/visualizer.rb

@@ -20,7 +20,13 @@ module RailsLens
 
       def generate
         models = load_models
-        generate_mermaid(models)
+        if config[:group_by_database]
+          group_models_by_database(models).map do |db_name, group|
+            generate_mermaid(group, basename: "erd_#{db_name}")
+          end
+        else
+          generate_mermaid(models)
+        end
       end
 
       private
@@ -29,11 +35,15 @@ module RailsLens
         ModelDetector.detect_models(options)
       end
 
-      def generate_mermaid(models)
+      def group_models_by_database(models)
+        models.group_by { |model| model.connection_pool.db_config.name }
+      end
+
+      def generate_mermaid(models, basename: 'erd')
         if models.blank?
           # Still need to save the output even if no models found
           mermaid_output = "erDiagram\n  %% No models found"
-          return save_output(mermaid_output, 'mmd')
+          return save_output(mermaid_output, 'mmd', basename: basename)
         end
 
         # Create new ERDiagram using mermaid-ruby gem
@@ -41,25 +51,15 @@ module RailsLens
 
         # Process models and add them to the diagram
         models.each do |model|
-          # Skip abstract models
-          next if model.abstract_class?
-
-          # Skip models without valid tables/views or columns
-          is_view = ModelDetector.view_exists?(model)
-          has_data_source = is_view || (model.table_exists? && model.columns.present?)
-          next unless has_data_source
+          next unless renderable?(model)
 
           begin
             # Create attributes for the entity
-            attributes = []
-            model.columns.each do |column|
-              type_str = format_column_type(column)
-              keys = determine_keys(model, column)
-
-              attributes << {
-                type: type_str,
+            attributes = model.columns.map do |column|
+              {
+                type: format_column_type(column),
                 name: column.name,
-                keys: keys
+                keys: determine_keys(model, column)
               }
             end
 
@@ -74,26 +74,31 @@ module RailsLens
             RailsLens.logger.debug { "Warning: Could not add entity #{model.name}: #{e.message}" }
           end
 
-          # Add relationships
-          next if model.abstract_class?
-
-          is_view = ModelDetector.view_exists?(model)
-          has_data_source = is_view || (model.table_exists? && model.columns.present?)
-          next unless has_data_source
-
-          add_model_relationships(diagram, model, models)
+          # Relationships require both entities to exist in the diagram
+          add_model_relationships(diagram, model, models) if diagram.entities.key?(model.name)
         end
 
         # Generate mermaid syntax using the gem
         mermaid_output = diagram.to_mermaid
 
         # Save output
-        filename = save_output(mermaid_output, 'mmd')
+        filename = save_output(mermaid_output, 'mmd', basename: basename)
 
         RailsLens.logger.debug 'ERD generated successfully!'
         filename # Return the filename instead of content
       end
 
+      # A model renders when it is concrete and its table/view is reachable;
+      # an unavailable connection just drops the model from the diagram.
+      def renderable?(model)
+        return false if model.abstract_class?
+
+        ModelDetector.view_exists?(model) || (model.table_exists? && model.columns.present?)
+      rescue ActiveRecord::ActiveRecordError => e
+        RailsLens.logger.debug { "Skipping #{model.name}: #{e.message}" }
+        false
+      end
+
       def format_column_type(column)
         formatter_class = case column.sql_type
                           when /jsonb|uuid|inet|array|tsvector/i
@@ -109,13 +114,10 @@ module RailsLens
 
       def determine_keys(model, column)
         keys = []
-        keys << :PK if column.name == model.primary_key
-
-        # Check foreign keys
-        if model.respond_to?(:reflect_on_all_associations)
-          model.reflect_on_all_associations(:belongs_to).each do |assoc|
-            keys << :FK if assoc.foreign_key.to_s == column.name
-          end
+        # primary_key and foreign_key are arrays for composite keys
+        keys << :PK if Array(model.primary_key).include?(column.name)
+        keys << :FK if model.reflect_on_all_associations(:belongs_to).any? do |assoc|
+          Array(assoc.foreign_key).map(&:to_s).include?(column.name)
         end
 
         # Check unique indexes - use UK which will be automatically quoted as comment
@@ -143,9 +145,9 @@ module RailsLens
 
           next unless target_model && models.include?(target_model)
 
-          # Skip relationships to abstract models
-          next if target_model.abstract_class?
-          next unless target_model.table_exists? && target_model.columns.present?
+          # Skip targets whose entity was not added to the diagram
+          # (abstract, unreachable connection, or add_entity failed)
+          next unless diagram.entities.key?(target_model.name)
 
           add_association_relationship(diagram, model, association, target_model)
         end
@@ -181,11 +183,11 @@ module RailsLens
         end
       end
 
-      def save_output(content, extension)
+      def save_output(content, extension, basename: 'erd')
         output_dir = config[:output_dir] || 'doc/erd'
         FileUtils.mkdir_p(output_dir)
 
-        filename = File.join(output_dir, "erd.#{extension}")
+        filename = File.join(output_dir, "#{basename}.#{extension}")
         File.write(filename, content)
 
         RailsLens.logger.debug { "ERD saved to: #{filename}" }

data/lib/rails_lens/errors.rb

@@ -42,7 +42,7 @@ module RailsLens
   class ErrorReporter
     class << self
       def report(error, context = {})
-        return unless RailsLens.verbose || RailsLens.debug
+        return unless RailsLens.config.verbose || RailsLens.config.debug
 
         message = build_error_message(error, context)
 
@@ -50,7 +50,7 @@ module RailsLens
         RailsLens.logger.error message
 
         # Use kernel output for debug mode to ensure visibility
-        return unless RailsLens.debug
+        return unless RailsLens.config.debug
 
         RailsLens.logger.debug message
       end
@@ -59,7 +59,7 @@ module RailsLens
         yield
       rescue StandardError => e
         report(e, context)
-        raise if RailsLens.raise_on_error
+        raise if RailsLens.config.raise_on_error
 
         nil
       end

data/lib/rails_lens/mailer/annotator.rb

@@ -201,6 +201,7 @@ module RailsLens
       # @return [void]
       def write_content_to_file(path:, content:)
         return if @dry_run
+        return if File.exist?(path) && File.read(path) == content
 
         File.write(path, content)
         @changed_files << path

data/lib/rails_lens/model_detector.rb

@@ -32,7 +32,9 @@ module RailsLens
       end
 
       def sti_child_models
-        concrete_models.select { |model| model.superclass != ActiveRecord::Base && concrete_models.include?(model.superclass) }
+        concrete_models.select do |model|
+          model.superclass != ActiveRecord::Base && concrete_models.include?(model.superclass)
+        end
       end
 
       def view_backed_models
@@ -96,7 +98,6 @@ module RailsLens
         false # If we can't check, assume it's not a view
       end
 
-      # rubocop:disable Naming/PredicateMethod
       def check_postgresql_view(connection, table_name)
         # Handle schema-qualified table names (e.g., 'audit.audit_logs')
         if table_name.include?('.')
@@ -153,7 +154,6 @@ module RailsLens
         SQL
         result.rows.any?
       end
-      # rubocop:enable Naming/PredicateMethod
 
       def eager_load_models
         # Zeitwerk is always available in Rails 7+

data/lib/rails_lens/providers/extension_notes_provider.rb

@@ -9,7 +9,8 @@ module RailsLens
 
       def applicable?(model_class)
         # Only applicable to tables, not views
-        RailsLens.config.extensions[:enabled] && model_has_table?(model_class) && !ModelDetector.view_exists?(model_class)
+        RailsLens.config.extensions[:enabled] && model_has_table?(model_class) &&
+          !ModelDetector.view_exists?(model_class)
       end
 
       def process(model_class, connection = nil)

data/lib/rails_lens/route/annotator.rb

@@ -243,6 +243,7 @@ module RailsLens
       # @return [void]
       def write_content_to_file(path:, content:)
         return if @dry_run
+        return if File.exist?(path) && File.read(path) == content
 
         File.write(path, content)
         @changed_files << path

data/lib/rails_lens/schema/adapters/base.rb

@@ -164,11 +164,12 @@ module RailsLens
         end
 
         def primary_key?(column)
-          column.name == primary_key_name
+          primary_key_names.include?(column.name)
         end
 
-        def primary_key_name
-          @primary_key_name ||= connection.primary_key(unqualified_table_name)
+        # The singular connection.primary_key returns nil for composite keys.
+        def primary_key_names
+          @primary_key_names ||= connection.primary_keys(unqualified_table_name)
         end
 
         def column_name_width
@@ -336,6 +337,7 @@ module RailsLens
             attrs << "columns = #{TomlFormat.quoted_array(Array(index.columns))}"
             attrs << 'unique = true' if index.unique
             attrs << "type = \"#{index.type}\"" if index.respond_to?(:type) && index.type
+            attrs << "where = \"#{index.where}\"" if index.respond_to?(:where) && index.where
             line += attrs.join(', ')
             line += ' }'
             line += ',' if i < indexes.length - 1

data/lib/rails_lens/schema/adapters/database_info.rb

@@ -62,9 +62,13 @@ module RailsLens
         def database_encoding
           case adapter_name
           when 'PostgreSQL'
-            connection.select_value('SELECT pg_encoding_to_char(encoding) FROM pg_database WHERE datname = current_database()')
+            connection.select_value(
+              'SELECT pg_encoding_to_char(encoding) FROM pg_database WHERE datname = current_database()'
+            )
           when 'Mysql2'
-            connection.select_value('SELECT DEFAULT_CHARACTER_SET_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = DATABASE()')
+            connection.select_value(
+              'SELECT DEFAULT_CHARACTER_SET_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = DATABASE()'
+            )
           end
         rescue StandardError
           nil
@@ -75,7 +79,9 @@ module RailsLens
           when 'PostgreSQL'
             connection.select_value('SELECT datcollate FROM pg_database WHERE datname = current_database()')
           when 'Mysql2'
-            connection.select_value('SELECT DEFAULT_COLLATION_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = DATABASE()')
+            connection.select_value(
+              'SELECT DEFAULT_COLLATION_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = DATABASE()'
+            )
           end
         rescue StandardError
           nil

data/lib/rails_lens/schema/adapters/postgresql.rb

@@ -112,9 +112,9 @@ module RailsLens
           end
         end
 
-        def primary_key_name
-          @primary_key_name ||= with_schema_in_search_path do
-            connection.primary_key(unqualified_table_name)
+        def primary_key_names
+          @primary_key_names ||= with_schema_in_search_path do
+            connection.primary_keys(unqualified_table_name)
           end
         end
 

data/lib/rails_lens/schema/annotation_manager.rb

@@ -104,19 +104,33 @@ module RailsLens
         results = { annotated: [], skipped: [], failed: [] }
 
         begin
-          models = source.models(options)
+          models = filter_models_by_names(source.models(options), options[:models])
           puts "  Found #{models.size} #{source.source_name} models" if options[:verbose]
 
           models.each do |model|
             record_result(results, source.annotate_model(model, options))
           end
         rescue StandardError => e
-          puts "  Error processing #{source.source_name} source: #{e.message}" if options[:verbose]
+          results[:failed] << { model: "#{source.source_name} (source)", error: e.message }
         end
 
         results
       end
 
+      # Enforce the models filter for every source, including sources whose
+      # own #models implementation ignores options[:models].
+      def self.filter_models_by_names(models, names)
+        names = Array(names)
+        return models if names.empty?
+
+        models.select do |model|
+          names.any? do |name|
+            model.name == name ||
+              (model.respond_to?(:table_name) && model.table_name == name)
+          end
+        end
+      end
+
       # Merge source results into main results. +primary_key+ is the
       # source-specific success bucket (:annotated or :removed).
       def self.merge_results(main, source, primary_key)

data/lib/rails_lens/tasks/annotate.rake

@@ -11,20 +11,29 @@ namespace :rails_lens do
 
     results = RailsLens::Schema::AnnotationManager.annotate_all(options)
 
-    if results[:by_source]&.any?
-      results[:by_source].each do |source_name, count|
-        puts "Annotated #{count} #{source_name} models" if count.positive?
+    # Only report sources that actually produced annotations; a registered source with
+    # nothing to annotate is noise, not news.
+    annotated_by_source = (results[:by_source] || {}).select { |_source_name, count| count.positive? }
+
+    if annotated_by_source.any?
+      annotated_by_source.each do |source_name, count|
+        puts "Annotated #{count} #{source_name} #{'model'.pluralize(count)}"
       end
     else
-      puts "Annotated #{results[:annotated].length} models"
+      puts "Annotated #{results[:annotated].length} #{'model'.pluralize(results[:annotated].length)}"
     end
-    puts "Skipped #{results[:skipped].length} models" if results[:skipped].any?
+    puts "Skipped #{results[:skipped].length} #{'model'.pluralize(results[:skipped].length)}" if results[:skipped].any?
     if results[:failed].any?
-      puts "Failed to annotate #{results[:failed].length} models:"
+      puts "Failed to annotate #{results[:failed].length} #{'model'.pluralize(results[:failed].length)}:"
       results[:failed].each do |failure|
         puts "  - #{failure[:model]}: #{failure[:error]}"
       end
     end
+    if options[:models] && results.values_at(:annotated, :skipped, :failed).all?(&:empty?)
+      warn "No models matched '#{options[:models].join(', ')}'. The task argument is a " \
+           'comma-separated list of model class names, e.g. rails_lens:annotate[User,Admin::Account]. ' \
+           'Run rails_lens:annotate without arguments to annotate everything.'
+    end
   end
 
   desc 'Remove all annotations from models'
@@ -33,16 +42,20 @@ namespace :rails_lens do
 
     results = RailsLens::Schema::AnnotationManager.remove_all
 
-    if results[:by_source]&.any?
-      results[:by_source].each do |source_name, count|
-        puts "Removed annotations from #{count} #{source_name} models" if count.positive?
+    removed_by_source = (results[:by_source] || {}).select { |_source_name, count| count.positive? }
+
+    if removed_by_source.any?
+      removed_by_source.each do |source_name, count|
+        puts "Removed annotations from #{count} #{source_name} #{'model'.pluralize(count)}"
       end
     elsif results[:removed].any?
-      puts "Removed annotations from #{results[:removed].length} models"
+      puts "Removed annotations from #{results[:removed].length} #{'model'.pluralize(results[:removed].length)}"
+    end
+    if results[:skipped].any?
+      puts "Skipped #{results[:skipped].length} #{'model'.pluralize(results[:skipped].length)} (no annotations)"
     end
-    puts "Skipped #{results[:skipped].length} models (no annotations)" if results[:skipped].any?
     if results[:failed].any?
-      puts "Failed to remove annotations from #{results[:failed].length} models:"
+      puts "Failed to remove annotations from #{results[:failed].length} #{'model'.pluralize(results[:failed].length)}:"
       results[:failed].each do |failure|
         puts "  - #{failure[:model]}: #{failure[:error]}"
       end

data/lib/rails_lens/tasks/mailers.rake

@@ -9,7 +9,7 @@ namespace :rails_lens do
       annotator = RailsLens::Mailer::Annotator.new
       changed_files = annotator.annotate_all
 
-      puts "Annotated #{changed_files.length} mailer files with mailer information"
+      puts "Annotated #{changed_files.length} #{'mailer file'.pluralize(changed_files.length)} with mailer information"
       changed_files.each { |file| puts "  - #{file}" }
     end
 
@@ -20,7 +20,7 @@ namespace :rails_lens do
       annotator = RailsLens::Mailer::Annotator.new
       changed_files = annotator.remove_all
 
-      puts "Removed mailer annotations from #{changed_files.length} mailer files"
+      puts "Removed mailer annotations from #{changed_files.length} #{'mailer file'.pluralize(changed_files.length)}"
       changed_files.each { |file| puts "  - #{file}" }
     end
   end

data/lib/rails_lens/tasks/routes.rake

@@ -9,7 +9,8 @@ namespace :rails_lens do
       annotator = RailsLens::Route::Annotator.new
       changed_files = annotator.annotate_all
 
-      puts "Annotated #{changed_files.length} controller files with route information"
+      puts "Annotated #{changed_files.length} #{'controller file'.pluralize(changed_files.length)} " \
+           'with route information'
       changed_files.each { |file| puts "  - #{file}" }
     end
 
@@ -20,7 +21,7 @@ namespace :rails_lens do
       annotator = RailsLens::Route::Annotator.new
       changed_files = annotator.remove_all
 
-      puts "Removed route annotations from #{changed_files.length} controller files"
+      puts "Removed route annotations from #{changed_files.length} #{'controller file'.pluralize(changed_files.length)}"
       changed_files.each { |file| puts "  - #{file}" }
     end
   end

data/lib/rails_lens/tasks/schema.rake

@@ -20,14 +20,16 @@ namespace :rails_lens do
       results = RailsLens.annotate_models(options)
 
       if results[:annotated].any?
-        puts "Annotated #{results[:annotated].length} models"
+        puts "Annotated #{results[:annotated].length} #{'model'.pluralize(results[:annotated].length)}"
         puts '(including abstract classes)' if options[:include_abstract]
       end
 
-      puts "\nSkipped #{results[:skipped].length} models (no changes needed)" if results[:skipped].any?
+      if results[:skipped].any?
+        puts "\nSkipped #{results[:skipped].length} #{'model'.pluralize(results[:skipped].length)} (no changes needed)"
+      end
 
       if results[:failed].any?
-        puts "\nFailed to annotate #{results[:failed].length} models:"
+        puts "\nFailed to annotate #{results[:failed].length} #{'model'.pluralize(results[:failed].length)}:"
         results[:failed].each do |failure|
           puts "  ✗ #{failure[:model]}: #{failure[:error]}"
         end
@@ -42,14 +44,17 @@ namespace :rails_lens do
       results = RailsLens.remove_annotations
 
       if results[:removed].any?
-        puts "Removed annotations from #{results[:removed].length} models:"
+        puts "Removed annotations from #{results[:removed].length} #{'model'.pluralize(results[:removed].length)}:"
         results[:removed].each { |model| puts "  ✓ #{model}" }
       end
 
-      puts "\nSkipped #{results[:skipped].length} models (no annotations found)" if results[:skipped].any?
+      if results[:skipped].any?
+        puts "\nSkipped #{results[:skipped].length} #{'model'.pluralize(results[:skipped].length)} " \
+             '(no annotations found)'
+      end
 
       if results[:failed].any?
-        puts "\nFailed to process #{results[:failed].length} models:"
+        puts "\nFailed to process #{results[:failed].length} #{'model'.pluralize(results[:failed].length)}:"
         results[:failed].each do |failure|
           puts "  ✗ #{failure[:model]}: #{failure[:error]}"
         end

data/lib/rails_lens/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsLens
-  VERSION = '0.5.4'
+  VERSION = '0.10.1'
 end

data/lib/rails_lens.rb

@@ -31,6 +31,9 @@ module RailsLens
   extend Configuration
 
   class << self
+    # Path of the loaded config file, nil when running on defaults.
+    attr_reader :config_file
+
     def logger
       @logger ||= config.logger || default_logger
     end
@@ -52,6 +55,7 @@ module RailsLens
     def load_config_file(path = '.rails-lens.yml')
       return unless File.exist?(path)
 
+      @config_file = path
       yaml = YAML.load_file(path)
 
       yaml.each do |section, settings|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_lens
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.10.1
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.2.0
+        version: 8.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.2.0
+        version: 8.0.0
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.2.0
+        version: 8.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.2.0
+        version: 8.0.0
 - !ruby/object:Gem::Dependency
   name: ostruct
   requirement: !ruby/object:Gem::Requirement
@@ -85,14 +85,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.2.0
+        version: 8.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.2.0
+        version: 8.0.0
 - !ruby/object:Gem::Dependency
   name: dotenv
   requirement: !ruby/object:Gem::Requirement
@@ -149,7 +149,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-description: Rails Lens provides unified visualization and annotation for Rails 7.2+
+description: Rails Lens provides unified visualization and annotation for Rails 8.0+
   applications, integrating ERD generation and model annotations.
 email:
 - terminale@gmail.com
@@ -273,7 +273,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Comprehensive Rails application visualization and annotation
 test_files: []