rails-ai-context 5.30.2 → 5.32.0

data/lib/rails_ai_context/tools/get_model_details.rb

@@ -43,6 +43,9 @@ module RailsAiContext
             key = fuzzy_find_key(models.keys, model) || model
             data = models[key]
             unless data
+              reason = RailsAiContext::AppKind.without_active_record(rails_app.root)
+              return empty_response("No Active Record model named #{model}: #{reason}.") if reason && models.empty?
+
               return not_found_response("Model", model, models.keys.sort,
                 recovery_tool: "Call rails_get_model_details(detail:\"summary\") to see all models")
             end
@@ -131,6 +134,20 @@ module RailsAiContext
         lines
       end
 
+      private_class_method def self.sti_line(sti)
+        place = sti[:sti_parent] ? "subclass of `#{sti[:sti_parent]}`" : "base of #{sti[:sti_children].map { |c| "`#{c}`" }.join(', ')}"
+        "**STI:** #{place}#{", type column `#{sti[:type_column]}`" if sti[:type_column]}"
+      end
+
+      private_class_method def self.tenancy_line(tenancy)
+        file = tenancy[:declared_in]
+        case tenancy[:scope]
+        when "shared" then "**Tenancy:** shared schema: Apartment's `excluded_models` lists it (`#{file}`)"
+        when "per_tenant" then "**Tenancy:** one table in each tenant's schema: Apartment's `excluded_models` does not list it (`#{file}`)"
+        else "**Tenancy:** [INFERRED] Apartment computes `excluded_models` (`#{tenancy[:excluded_models]}` in `#{file}`), so whether this table is per tenant is not read"
+        end
+      end
+
       private_class_method def self.unavailable_row(name, data)
         Serializers::SectionFacts.unread_row("- **#{name}**", data)
       end
@@ -147,6 +164,12 @@ module RailsAiContext
         end
         lines = [ "# #{name}#{header_tag}", "" ]
         lines << "**Table:** `#{data[:table_name]}`" if data[:table_name]
+        if (database = data[:database])
+          lines << "**Database:** `#{database[:connects_to]}`#{" (only #{database[:condition]})" if database[:condition]}" \
+                   "#{", inherited from `#{database[:declared_in]}`" if database[:declared_in]}"
+        end
+        lines << tenancy_line(data[:tenancy]) if data[:tenancy].is_a?(Hash)
+        lines << sti_line(data[:sti]) if data[:sti].is_a?(Hash) && (data[:sti][:sti_parent] || data[:sti][:sti_children])
         # A base class is not a concern, and the child may have no concerns at
         # all, so this stands outside that section.
         bases_unread = data[:bases_unread]
@@ -157,25 +180,38 @@ module RailsAiContext
         if structure
           lines << "**File:** `#{structure[:path]}` (#{count_phrase(structure[:total_lines], "line")})"
           map = structure[:sections].map { |s| "#{s[:label]}(#{s[:start]}-#{s[:end]})" }.join(" → ")
-          lines << "**Structure:** #{map}"
+          lines << "**Structure:** #{map}" unless map.empty?
         end
 
         # Schema columns - inline from schema introspection
         if data[:table_name]
-          schema = Payload.section(cached_context, :schema)
-          if schema && schema[:tables]&.key?(data[:table_name])
-            table_data = schema[:tables][data[:table_name]]
-            cols = table_data[:columns] || []
+          (source, table_data), *others = Payload.model_tables(Payload.section(cached_context, :schema), data)
+          if table_data
+            ignored = Array(data[:ignored_columns])
+            cols = (table_data[:columns] || []).reject { |c| ignored.include?(c[:name].to_s) }
+            if (key = data[:primary_key] || table_data[:primary_key])
+              line = "**Primary key:** `#{Introspectors::SchemaConventions.primary_key_label(key)}`"
+              table_key = table_data[:primary_key]
+              line += " (the table's is `#{Introspectors::SchemaConventions.primary_key_label(table_key)}`)" if table_key && Array(table_key).map(&:to_s) != Array(key).map(&:to_s)
+              lines << line
+            end
             if cols.any?
               lines << "" << "## Columns"
               cols.each do |c|
-                parts = [ "**#{c[:name]}**", c[:type] ]
+                parts = [ "**#{c[:name]}**", c[:type] ].compact
+                parts << "primary key" if c[:primary_key]
                 parts << "NOT NULL" if c[:null] == false
                 parts << "default: #{c[:default]}" if c[:default] && !c[:default].to_s.empty?
                 parts << "array" if c[:array]
                 lines << "- #{parts.join(' | ')}"
               end
+              differ = others.reject { |_, other| other[:columns] == table_data[:columns] }.map(&:first)
+              if differ.any?
+                lines << "" << "Columns of `#{data[:table_name]}` in #{source}; the table differs in #{differ.join(", ")}: " \
+                               "`rails_get_schema(table:\"#{data[:table_name]}\")` lists each."
+              end
             end
+            lines << ignored_columns_line(ignored) if ignored.any?
           end
         end
 
@@ -186,10 +222,15 @@ module RailsAiContext
             lines << "" << "## Fields"
             data[:fields].each do |f|
               type_str = f[:type] ? ": #{f[:type]}" : ""
-              lines << "- `#{f[:name]}`#{type_str}"
+              lines << "- `#{f[:name]}`#{type_str}#{", default: #{f[:default]}" if f.key?(:default)}"
             end
           end
 
+          if data[:indexes]&.any?
+            lines << "" << "## Indexes"
+            data[:indexes].each { |index| lines << "- `#{index}`" }
+          end
+
           # embeds_many and embeds_one are listed under Associations too.
           listed = Array(data[:associations]).map { |a| a[:name].to_s }
           embeds = Array(data[:embeds]).reject { |e| listed.include?(e[:name].to_s) }
@@ -213,6 +254,10 @@ module RailsAiContext
             detail += " [polymorphic]" if a[:polymorphic]
             detail += (a[:optional] == true ? " [optional]" : " [optional: #{a[:optional]}]") if a[:optional]
             detail += " dependent: #{a[:dependent]}" if a[:dependent]
+            detail += option_pairs(a[:declared_options])
+            detail += " (delegated types: #{a[:delegated_types].join(', ')})" if a[:delegated_types]&.any?
+            detail += " (delegated types: from `#{a[:delegated_types_source]}`, not read statically)" if a[:delegated_types_source]
+            detail += " extension methods: #{a[:extension_methods].join(', ')}" if a[:extension_methods]&.any?
             detail += " (fk: #{Introspectors::SchemaConventions.key_text(a[:foreign_key])})" if a[:foreign_key] && a[:type] == "belongs_to"
             detail += " [UNAVAILABLE: #{a[:unavailable]}]" if a[:unavailable]
             lines << detail
@@ -272,26 +317,32 @@ module RailsAiContext
         end
 
         # Custom validate methods (business rules) - show method body when possible
-        if data[:custom_validates]&.any?
+        if data[:custom_validates]&.any? || data[:custom_validate_blocks]&.any?
           lines << "" << "## Validations" unless data[:validations]&.any?
-          bodies = extract_custom_validate_bodies(name, data[:custom_validates])
+          custom = Array(data[:custom_validates])
+          bodies = custom.any? ? extract_custom_validate_bodies(name, custom) : {}
           conditions = data[:custom_validate_conditions] || {}
-          data[:custom_validates].each do |v|
+          custom.each do |v|
             tail = callback_condition_tail(conditions[v.to_s] || conditions[v.to_sym])
             lines << "- **Custom:** `#{v}`#{tail}#{" → #{bodies[v]}" if bodies[v]}"
           end
+          Array(data[:custom_validate_blocks]).each do |b|
+            lines << "- **Custom:** block#{callback_condition_tail(b[:conditions])}#{" → #{b[:body]}" unless b[:body].to_s.empty?}"
+          end
         end
 
         # Enums
         if data[:enums]&.any?
           lines << "" << "## Enums"
+          enum_options = data[:enum_options] || {}
           data[:enums].each do |attr, values|
+            options = enum_options[attr.to_s] || enum_options[attr.to_sym] || {}
             if values.is_a?(Hash)
               backing = values.values.first.is_a?(Integer) ? "integer" : "string"
               entries = values.map { |k, v| "#{k}(#{v})" }.join(", ")
-              lines << "- `#{attr}`: #{entries} [#{backing}]"
+              lines << "- `#{attr}`: #{entries} [#{backing}]#{enum_options_text(attr, values.keys, options)}"
             else
-              lines << "- `#{attr}`: #{Serializers::SectionFacts.enum_values(values)}"
+              lines << "- `#{attr}`: #{Serializers::SectionFacts.enum_values(values)}#{enum_options_text(attr, nil, options)}"
             end
           end
         end
@@ -299,9 +350,13 @@ module RailsAiContext
         # Scopes - show lambda body so AI can chain correctly. Each carries
         # the AST confidence: [VERIFIED] literal bodies vs [INFERRED] dynamic
         # expressions the parser can't fully resolve.
-        if data[:scopes]&.any?
+        if data[:scopes]&.any? || data[:default_scopes]&.any?
           lines << "" << "## Scopes"
-          data[:scopes].each do |s|
+          Array(data[:default_scopes]).each do |s|
+            tail = s[:all_queries] ? " (all_queries: #{s[:all_queries]})" : ""
+            lines << "- `default_scope` → #{s[:body] || Confidence::INFERRED}#{tail} _(applies to every query on #{name})_"
+          end
+          Array(data[:scopes]).each do |s|
             if s.is_a?(Hash)
               tag = s[:confidence] ? " #{s[:confidence]}" : ""
               lines << "- `#{s[:name]}` → #{s[:body]}#{tag}"
@@ -322,16 +377,28 @@ module RailsAiContext
             end
             lines << "- `#{callback_type_label(type)}`: #{targets.join(', ')}"
           end
+          lines << "" << commit_order_note([ name ]) if data[:commit_order_unread]
         end
 
         # Macros - surface hidden introspector data
         macro_lines = []
-        macro_lines << "- `has_secure_password`" if data[:has_secure_password]
+        if data[:secure_passwords]&.any?
+          data[:secure_passwords].each { |pw| macro_lines << "- `has_secure_password` :#{pw[:attribute]}#{option_pairs(pw[:options])}" }
+        elsif data[:has_secure_password]
+          macro_lines << "- `has_secure_password`"
+        end
+        macro_lines << "- `has_secure_token` #{data[:has_secure_token].map { |f| ":#{f}" }.join(', ')}" if data[:has_secure_token]&.any?
+        Array(data[:nested_attributes]).each do |nested|
+          macro_lines << "- `accepts_nested_attributes_for` #{nested[:names].map { |n| ":#{n}" }.join(', ')}#{option_pairs(nested[:options])}"
+        end
         macro_lines << "- `encrypts` #{data[:encrypts].map { |f| ":#{f}" }.join(', ')}" if data[:encrypts]&.any?
         macro_lines << "- `normalizes` #{data[:normalizes].map { |f| ":#{f}" }.join(', ')}" if data[:normalizes]&.any?
         macro_lines << "- `generates_token_for` #{data[:generates_token_for].map { |f| ":#{f}" }.join(', ')}" if data[:generates_token_for]&.any?
-        macro_lines << "- `serialize` #{data[:serialize].map { |f| ":#{f}" }.join(', ')}" if data[:serialize]&.any?
-        macro_lines << "- `store` #{data[:store].map { |f| ":#{f}" }.join(', ')}" if data[:store]&.any?
+        if data[:serialize]&.any?
+          serialized = data[:serialize].map { |f| ":#{f}#{option_pairs(data[:serialize_options]&.dig(f))}" }
+          macro_lines << "- `serialize` #{serialized.join(', ')}"
+        end
+        macro_lines << "- `store` #{data[:store].map { |f| store_column_text(f, data[:store_accessors]) }.join(', ')}" if data[:store]&.any?
         macro_lines << "- `broadcasts` #{data[:broadcasts].join(', ')}" if data[:broadcasts]&.any?
         if data[:has_one_attached]&.any?
           macro_lines << "- `has_one_attached` #{data[:has_one_attached].map { |f| ":#{f}" }.join(', ')}"
@@ -339,11 +406,35 @@ module RailsAiContext
         if data[:has_many_attached]&.any?
           macro_lines << "- `has_many_attached` #{data[:has_many_attached].map { |f| ":#{f}" }.join(', ')}"
         end
+        macro_lines << "- `has_rich_text` #{data[:has_rich_text].map { |f| ":#{f}" }.join(', ')}" if data[:has_rich_text]&.any?
+        if data[:attributes]&.any?
+          macro_lines << "- `attribute` #{data[:attributes].map { |a| attribute_api_text(a) }.join(', ')}"
+        end
+        if data[:alias_attributes]&.any?
+          macro_lines << "- `alias_attribute` #{data[:alias_attributes].map { |a| ":#{a[:name]} → :#{a[:target]}" }.join(', ')}"
+        end
+        (data[:model_settings] || {}).each { |setting, value| macro_lines << "- `self.#{setting} = #{value}`" }
+        macro_lines << "- `attr_readonly` #{data[:attr_readonly].map { |f| ":#{f}" }.join(', ')}" if data[:attr_readonly]&.any?
+        macro_lines << "- `query_constraints` #{data[:query_constraints].map { |f| ":#{f}" }.join(', ')}" if data[:query_constraints]&.any?
+        Array(data[:gem_macros]).each do |gem_macro|
+          adds = Array(gem_macro[:adds]).map { |name| "`#{name}`" }
+          macro_lines << "- `#{gem_macro[:text]}`#{" (adds #{adds.join(', ')})" if adds.any?}"
+        end
         if macro_lines.any?
           lines << "" << "## Macros"
           lines.concat(macro_lines)
         end
 
+        Array(data[:state_machines]).each do |machine|
+          lines << "" << "## State machine (aasm, column `#{machine[:column]}`)"
+          states = machine[:states].map { |state| "`#{state}`#{" (initial)" if state == machine[:initial]}" }
+          lines << "- states: #{states.join(', ')}" if states.any?
+          machine[:events].each do |event|
+            moves = event[:transitions].map { |t| "#{t[:from].any? ? t[:from].join(' | ') : 'any'} -> #{t[:to]}" }
+            lines << "- event `#{event[:name]}`#{": #{moves.join(', ')}" if moves.any?}"
+          end
+        end
+
         # Encryption details (expanded from encrypts)
         if data[:encryption_details]&.any?
           lines << "" << "## Encryption Details"
@@ -364,7 +455,7 @@ module RailsAiContext
         if data[:token_generation]&.any?
           lines << "" << "## Token Generation"
           data[:token_generation].each do |tg|
-            detail_str = tg.is_a?(Hash) ? "**#{tg[:purpose]}** (expires_in: #{tg[:expires_in] || 'default'})" : tg.to_s
+            detail_str = tg.is_a?(Hash) ? "**#{tg[:purpose]}** (expires_in: #{tg[:expires_in] || 'never'})" : tg.to_s
             lines << "- #{detail_str}"
           end
         end
@@ -373,7 +464,11 @@ module RailsAiContext
         if data[:delegations]&.any?
           lines << "" << "## Delegations"
           data[:delegations].each do |d|
-            lines << "- delegate #{d[:methods].map { |m| ":#{m}" }.join(', ')} to: :#{d[:to]}"
+            line = "- delegate #{d[:methods].map { |m| ":#{m}" }.join(', ')} to: :#{d[:to]}"
+            line += " → #{d[:defines].join(', ')}" if d[:defines]
+            line += " → #{RailsAiContext::Confidence::INFERRED} (the prefix is computed)" if d[:prefix_computed]
+            line += " (private)" if d[:private]
+            lines << line
           end
         end
         lines << "- `delegate_missing_to` :#{data[:delegate_missing_to]}" if data[:delegate_missing_to]
@@ -409,9 +504,9 @@ module RailsAiContext
           lines << "_#{count_phrase(hidden, "concern")} hidden by `excluded_concerns`._" if hidden.positive?
         end
 
-        # Declared only under a condition the source does not decide, or by a
-        # called method on another receiver: named, and left out of every count above.
-        { conditional_declarations: "Only under a condition the source does not decide",
+        # A declaration whose method name or condition the source does not decide, or one
+        # a called method makes on another receiver: named, and left out of every count above.
+        { conditional_declarations: "Not decided from the source (the method name or a condition)",
           foreign_declarations: "Declared on another class" }.each do |key, heading|
           next unless data[key]&.any?
 
@@ -455,6 +550,14 @@ module RailsAiContext
           end
         end
 
+        async = Array(Payload.section(cached_context, :jobs)&.dig(:async_methods)).select { |m| m[:owner] == name }
+        if async.any?
+          lines << "" << "## Runs in the background (delayed_job)"
+          async.each do |m|
+            lines << "- `#{m[:method]}`#{" [#{m[:options]}]" if m[:options]}: every call is queued by `handle_asynchronously` (`#{m[:file]}`)"
+          end
+        end
+
         # Cross-reference hints - guide AI to related tools
         hints = []
         hints << "`rails_get_schema(table:\"#{data[:table_name]}\")` for columns/indexes" if data[:table_name]
@@ -492,6 +595,44 @@ module RailsAiContext
         pairs.any? ? "**#{ed[:field]}** (#{pairs.join(', ')})" : "**#{ed[:field]}**"
       end
 
+      # Rails names each value's methods "#{prefix}#{label}#{suffix}", so the
+      # bare label is wrong once either is set.
+      private_class_method def self.enum_options_text(attr, labels, options)
+        text = options[:default].nil? ? "" : " default: #{options[:default]}"
+        prefix, suffix = options.values_at(:prefix, :suffix)
+        return text unless prefix || suffix
+        if [ prefix, suffix ].include?(Confidence::INFERRED)
+          return "#{text} methods: #{Confidence::INFERRED} (the prefix or suffix is computed)"
+        end
+        return "#{text} methods: #{Confidence::INFERRED} (the values are computed)" unless labels
+
+        prefix = "#{prefix == true ? attr : prefix}_" if prefix
+        suffix = "_#{suffix == true ? attr : suffix}" if suffix
+        methods = labels.map { |label| "#{prefix}#{label.to_s.gsub(/[\W&&[:ascii:]]+/, '_')}#{suffix}?" }
+        "#{text} methods: #{methods.join(', ')}"
+      end
+
+      private_class_method def self.ignored_columns_line(ignored)
+        inferred = RailsAiContext::Confidence::INFERRED
+        return "\n**Ignored columns:** #{inferred} (computed in the source)" if ignored.include?(inferred)
+
+        "\n**Ignored columns:** #{ignored.map { |c| "`#{c}`" }.join(', ')} _(the model cannot read or write them)_"
+      end
+
+      private_class_method def self.store_column_text(column, accessors)
+        names = Array(accessors&.dig(column))
+        return ":#{column}" if names.empty?
+
+        inferred = RailsAiContext::Confidence::INFERRED
+        names = names.map { |n| n == inferred ? "#{inferred}: the prefix or suffix is computed" : n }
+        ":#{column} (#{names.join(', ')})"
+      end
+
+      private_class_method def self.attribute_api_text(attribute)
+        facts = [ attribute[:type], ("default: #{attribute[:default]}" if attribute[:default]) ].compact
+        ":#{attribute[:name]}#{" (#{facts.join(', ')})" if facts.any?}"
+      end
+
       # A transformation the parser could not resolve is a marker, not the
       # name of a transformation, so it never follows the dash.
       private_class_method def self.normalization_line(nd)
@@ -501,7 +642,11 @@ module RailsAiContext
         return "**#{nd[:field]}** #{RailsAiContext::Confidence::INFERRED}" if transformation.nil? ||
           transformation == RailsAiContext::Confidence::INFERRED
 
-        "**#{nd[:field]}** - #{transformation}"
+        "**#{nd[:field]}** - #{transformation}#{option_pairs(nd[:options])}"
+      end
+
+      private_class_method def self.option_pairs(options)
+        options&.any? ? " (#{options.map { |k, v| "#{k}: #{option_text(v)}" }.join(', ')})" : ""
       end
 
       # Extract bodies of custom validate methods (single-line or first meaningful line)
@@ -534,7 +679,9 @@ module RailsAiContext
 
       private_class_method def self.extract_method_signatures(model_name)
         source = model_source(model_name) or return nil
-        Introspectors::ActionResolver.public_methods_from_source(source, owner: model_name)
+        # A def carries an end line; delegate and attr_* names do not, and they lead a model, so they go after the cap's defs.
+        written, generated = Introspectors::ActionResolver.public_methods_in(source, owner: model_name).partition { |m| m[:end_location] }
+        (written + generated).map { |m| Introspectors::ActionResolver.signature(m) }.uniq
       end
 
       # On the booted tier reflection has already answered associations,
@@ -588,13 +735,18 @@ module RailsAiContext
         source = RailsAiContext::SafeFile.read(full_path) or return nil
 
         source_lines = source.lines
+        # A def's kind comes from the walk: a regex cannot see `class << self`,
+        # `def Name.x`, or a def that only extends a scope.
+        def_scopes = Introspectors::ActionResolver.methods_in(source).to_h { |m| [ m[:location], m[:scope] ] }
         sections = []
         current_section = nil
         current_start = nil
 
         source_lines.each_with_index do |line, idx|
+          # Anything the listeners cannot scope: a section is a run of lines, which no node carries.
           label = case line
-          when /\A\s*class\s/ then "class definition"
+          when /\A\s*(?:[a-z_]+\s+)*def\s/ then { class: "class methods", instance: "instance methods" }[def_scopes[idx + 1]]
+          when /\A\s*class\s+(?!<<)/, /\A\s*[A-Z][\w:]*\s*=\s*Class\.new\b/ then "class definition"
           when /\A\s*(include|extend|prepend)\s/ then "includes"
           when /\A\s*[A-Z_]+\s*=/ then "constants"
           when /\A\s*(belongs_to|has_many|has_one|has_and_belongs_to_many)\s/ then "associations"
@@ -602,13 +754,11 @@ module RailsAiContext
           when /\A\s*scope\s/ then "scopes"
           when /\A\s*(enum|encrypts|normalizes|has_secure_password|has_one_attached|has_many_attached)\s/ then "macros"
           when /\A\s*(before_|after_|around_)/ then "callbacks"
-          when /\A\s*def\s+self\./ then "class methods"
-          when /\A\s*def\s/ then "instance methods"
           when /\A\s*private\s*$/ then "private"
           end
 
           if label && label != current_section
-            sections << { start: current_start, end: idx + 1, label: current_section } if current_section
+            sections << { start: current_start, end: idx, label: current_section } if current_section
             current_section = label
             current_start = idx + 1
           end