rails_lens 0.5.4 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e504fa26391d500a945947795688a4a52a23922e0ea6a760762415c698d91fc
-  data.tar.gz: 800c91d7df514dc2c745235cf9f5423a7a68d6499cee7221d5cb89adaa95157b
+  metadata.gz: 0f010a15d0d3afdf64754e866cac571fcb1c91e4bd3981c8aa9bdece8d30f85a
+  data.tar.gz: 11e8b6ad7da6461bdc846952151537d3495d67cd812cd9f7e4b3ca40dbc37fbb
 SHA512:
-  metadata.gz: 0c17d650e862adcf76e32d7a4a5398cd8c4827b8dd0e0424f01e307a76285e18001c5431561807a049695fbe3c4eaf68960add7d139427b1fcabb36ef2692e06
-  data.tar.gz: 31bf7b191ec9f5dfedabf351798d38b217a71b85c9ceba7e458ed7b45d61662b367989a40b3e311f9fc1e21f270eacbf55e6998e5b28ff0114fa0b5b37b9ab80
+  metadata.gz: 22963fce37978c1a4157d9c1ffe236a3ca41c0a97d8b492a832729b467c91923810cc70126c4717c17cbbac9596dfbcd620a34cdb482092b34a8692a37351c23
+  data.tar.gz: 4c5bd10154b4d44b4dfda08ec21ebcd3632b6a740e7a9d28ddd7d5a35289fec248fcf76b61bc19db8a53f548691a5597df326bda48f25ad0cc200c94468f94bf

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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/commands.rb

@@ -59,9 +59,9 @@ module RailsLens
 
     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 = {})

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/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

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

@@ -13,7 +13,7 @@ namespace :rails_lens do
 
     if results[:by_source]&.any?
       results[:by_source].each do |source_name, count|
-        puts "Annotated #{count} #{source_name} models" if count.positive?
+        puts "Annotated #{count} #{source_name} models"
       end
     else
       puts "Annotated #{results[:annotated].length} models"
@@ -25,6 +25,11 @@ namespace :rails_lens do
         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'

data/lib/rails_lens/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsLens
-  VERSION = '0.5.4'
+  VERSION = '0.10.0'
 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.0
 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: []