rails-ai-context 5.30.2 → 5.32.0

data/lib/rails_ai_context/tools/analyze_feature.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "pathname"
+
 module RailsAiContext
   module Tools
     class AnalyzeFeature < BaseTool
@@ -58,6 +60,7 @@ module RailsAiContext
         discover_controllers(ctx, pattern, lines)
         discover_routes(ctx, pattern, lines)
         discover_services(root, pattern, lines)
+        discover_admin(root, pattern, lines)
         discover_jobs(ctx, pattern, lines)
         discover_views(ctx, root, pattern, lines)
         discover_stimulus(ctx, pattern, lines)
@@ -126,6 +129,15 @@ module RailsAiContext
           end
         end
 
+        def discover_admin(root, pattern, lines)
+          matched = Introspectors::AdminResources.call(root).select { |r| feature_word_match?(r[:model], pattern) }
+          return if matched.empty?
+
+          lines << "## Admin Resources (#{matched.size})"
+          matched.each { |resource| lines << "- #{Introspectors::AdminResources.line(resource)}" }
+          lines << ""
+        end
+
         # --- AF: Models ---
         def discover_models(ctx, pattern, lines)
           models = Payload.models(ctx)
@@ -147,11 +159,10 @@ module RailsAiContext
               lines << "**Table:** `#{data[:table_name]}`" if data[:table_name]
 
               table_name = data[:table_name]
-              if table_name && (tables = ctx.dig(:schema, :tables))
-                table_data = tables[table_name]
+              if table_name && (table_data = RailsAiContext::Payload.model_table(ctx[:schema], data))
                 if table_data&.dig(:columns)&.any?
                   cols = table_data[:columns].reject { |c| %w[id created_at updated_at].include?(c[:name]) }
-                  col_strs = cols.map { |c| col_type = c[:array] ? "#{c[:type]}[]" : c[:type]; "#{c[:name]}:#{col_type}" }
+                  col_strs = cols.map { |c| col_type = c[:array] ? "#{c[:type]}[]" : c[:type]; [ c[:name], col_type ].compact.join(":") }
                   lines << "**Columns:** #{col_strs.join(', ')}" if cols.any?
                 end
               end
@@ -376,26 +387,27 @@ module RailsAiContext
         end
 
         def discover_tests(root, pattern, lines)
-          test_dirs = [ File.join(root, "spec"), File.join(root, "test") ]
           real_root = File.realpath(root).to_s
           found = []
           truncated = false
 
-          test_dirs.each do |dir|
+          base = RailsAiContext::PathResolver.test_root(root)
+          real_base = File.realpath(base).to_s
+          [ File.join(base, "spec"), File.join(base, "test") ].each do |dir|
             next unless Dir.exist?(dir)
-            suffix_glob = safe_glob(dir, "**/*_{test,spec}.rb", real_root).first(MAX_SCAN_FILES)
+            suffix_glob = safe_glob(dir, "**/*_{test,spec}.rb", real_base).first(MAX_SCAN_FILES)
             truncated = true if suffix_glob.size == MAX_SCAN_FILES
             # The path, not the basename: the gap checker below matches this
             # way for the same reason, and a spec whose feature word is a
             # directory (billing/invoices/create_spec.rb) is the normal shape
             # of a namespaced suite.
             suffix_glob.each do |path|
-              found << path if feature_word_match?(relative_test_name(path, real_root), pattern)
+              found << path if feature_word_match?(relative_test_name(path, real_base), pattern)
             end
-            prefix_glob = safe_glob(dir, "**/{test,spec}_*.rb", real_root).first(MAX_SCAN_FILES)
+            prefix_glob = safe_glob(dir, "**/{test,spec}_*.rb", real_base).first(MAX_SCAN_FILES)
             truncated = true if prefix_glob.size == MAX_SCAN_FILES
             prefix_glob.each do |path|
-              found << path if feature_word_match?(relative_test_name(path, real_root), pattern)
+              found << path if feature_word_match?(relative_test_name(path, real_base), pattern)
             end
           end
           found.uniq!
@@ -404,7 +416,7 @@ module RailsAiContext
           header = "## Tests (#{found.size}#{truncated ? " - first #{MAX_SCAN_FILES} per glob scanned" : ""})"
           lines << header
           found.each do |path|
-            relative = path.sub("#{real_root}/", "")
+            relative = Pathname.new(path).relative_path_from(Pathname.new(real_root)).to_s
             source = RailsAiContext::SafeFile.read(path) or next
             test_count = source.each_line.count do |line|
               line.match?(/^\s*(?:test|it|specify)\s+["']/) || line.match?(/^\s*def\s+test_/)

data/lib/rails_ai_context/tools/base_tool.rb

@@ -133,7 +133,13 @@ module RailsAiContext
         # Cache introspection results with TTL + fingerprint invalidation.
         # Uses SHARED_CACHE so all tool subclasses share one introspection
         # result instead of each caching independently.
+        # One copy per tool call: a tool reads the context from many helpers,
+        # and each copy deep-dups every section.
         def cached_context
+          RunCache.fetch([ :tool_context ]) { shared_context_copy }
+        end
+
+        private def shared_context_copy
           SHARED_CACHE[:mutex].synchronize do
             now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
             ttl = RailsAiContext.configuration.cache_ttl
@@ -182,7 +188,6 @@ module RailsAiContext
           session_reset!
           AstCache.clear
           PathResolver.clear_code_roots
-          Introspectors::TableName.clear_namespace_prefixes
         end
 
         # ── Session context helpers ──────────────────────────────────────
@@ -299,7 +304,7 @@ module RailsAiContext
 
         # Structured not-found error with fuzzy suggestion and recovery hint.
         # Helps AI agents self-correct without retrying blind.
-        def not_found_response(type, name, available, recovery_tool: nil)
+        def not_found_response(type, name, available, recovery_tool: nil, note: nil)
           # Don't suggest the exact same string the user typed - that's useless
           suggestions = find_closest_matches(name, available) - [ name ]
           lines = [ "#{type} '#{name}' not found." ]
@@ -310,9 +315,18 @@ module RailsAiContext
           end
           lines << "Available: #{available.first(20).join(', ')}#{"..." if available.size > 20}" if available.any?
           lines << "_Recovery: #{recovery_tool}_" if recovery_tool
+          lines << "" << note if note
           empty_response(lines.join("\n"))
         end
 
+        # Unbooted, a test/dummy's enclosing engine is not a views root.
+        def static_engine_views_note
+          root = rails_app.root.to_s
+          return nil unless RailsAiContext.static_tier? && RailsAiContext::PathResolver.test_root(root) != root
+
+          "_The views of the engine this app runs in are read only with the app booted._"
+        end
+
         # A tool ran, answered honestly, and found nothing. Renders exactly
         # like text_response - the mark rides in `_meta`, where a composing
         # tool can read it and a reader never sees it.
@@ -438,8 +452,10 @@ module RailsAiContext
         # an API-only app, or nil when the app has a view layer. Tools check
         # this before rendering "no X found" copy so a legitimately absent
         # surface never reads as "not built yet".
-        def api_only_note(section_label)
+        def api_only_note(section_label, dir: nil)
           return nil unless api_only_app?
+          # rails new --api keeps app/views when it keeps Action Mailer.
+          return nil if dir && File.directory?(File.join(rails_app.root.to_s, dir))
 
           "Not applicable: this is an API-only app (config.api_only), so #{section_label} does not exist."
         end
@@ -594,26 +610,17 @@ module RailsAiContext
           pattern.match?(/\w\z/) ? "\\b" : ""
         end
 
-        # Extract method source from a source string via indentation-based matching.
-        # Returns { code:, start_line:, end_line: } or nil. Shared by get_callbacks, get_concern.
+        # "self.x" asks for the class method; the file's own class answers before a nested
+        # module (a concern's ClassMethods), which answers only when the class has none.
         def extract_method_source_from_string(source, method_name)
-          source_lines = source.lines
           name = method_name.to_s
-          pattern = /\A\s*def\s+#{Regexp.escape(name)}#{trailing_boundary(name)}/
-          start_idx = source_lines.index { |l| l.match?(pattern) }
-          return nil unless start_idx
-
-          def_indent = source_lines[start_idx][/\A\s*/].length
-          result = []
-          end_idx = start_idx
-
-          source_lines[start_idx..].each_with_index do |line, i|
-            result << line.rstrip
-            end_idx = start_idx + i
-            break if i > 0 && line.match?(/\A\s{#{def_indent}}end\b/)
-          end
-
-          { code: result.join("\n"), start_line: start_idx + 1, end_line: end_idx + 1 }
+          scope = name.start_with?("self.") ? :class : :instance
+          bare = name.delete_prefix("self.")
+          resolver = Introspectors::ActionResolver
+          methods = resolver.methods_in(source)
+          named = methods.select { |m| m[:name] == bare && m[:scope] == scope }
+          method = resolver.own_methods(named, resolver.default_owner(source, methods)).first || named.first
+          method && resolver.body_of(source, method)
         rescue => e
           RailsAiContext.debug_fail(e, nil, label: "extract_method_source_from_string")
         end
@@ -636,15 +643,16 @@ module RailsAiContext
             return named if named
           end
 
-          fixture_file = File.join(rails_app.root, "test", "fixtures", "#{table}.yml")
+          real_root = File.realpath(rails_app.root.to_s)
+          fixture_file = File.join(real_root, "test", "fixtures", "#{table}.yml")
           return nil unless File.exist?(fixture_file)
 
-          # The disk read keeps its own filter: it reads raw YAML that no
-          # introspector has been through.
-          content = RailsAiContext::SafeFile.read(fixture_file)
-          content&.scan(/^([a-z_]\w*):/i)
-                 &.flatten
-                 &.find { |key| RailsAiContext::FixtureKeys.name?(key) }
+          real = safe_glob_realpath(fixture_file, real_root, real_root) or return nil
+          content = RailsAiContext::SafeFile.read(real) or return nil
+          labels = RailsAiContext::FixtureKeys.parse(content)&.keys || content.scan(/^([a-z_]\w*):/i).flatten
+          labels.find { |key| RailsAiContext::FixtureKeys.name?(key) }
+        rescue SystemCallError => e
+          RailsAiContext.debug_fail(e, nil, label: "fixture_key_for")
         end
 
         # Fixture set from `set_fixture_class`, then the table name, then the pluralized class
@@ -704,8 +712,9 @@ module RailsAiContext
           method.to_s == RailsAiContext::Introspectors::Listeners::CallbacksListener::INLINE_BLOCK
         end
 
+        # A constant (`AuditTrail`) is a callback object, not a method.
         def method_name?(method)
-          method.to_s.match?(/\A\w+[?!=]?\z/)
+          method.to_s.match?(/\A[a-z_]\w*[?!=]?\z/)
         end
 
         # A callback type as a reader can write it. `after_commit_on_create`
@@ -713,14 +722,28 @@ module RailsAiContext
         # `after_commit on: [...]`; Rails has no macro by that name, so an
         # agent that copies it gets a NoMethodError.
         def callback_type_label(type)
-          event = type.to_s[/\Aafter_commit_on_(\w+)\z/, 1]
+          event = RailsAiContext::Introspectors::Listeners::CallbacksListener.event(type)
           event ? "after_commit (on: :#{event})" : type.to_s
         end
 
+        # Statically, a config that does not say how Rails orders after_commit
+        # and after_rollback leaves those lists in declaration order.
+        def commit_order_note(unread)
+          return nil if unread.empty?
+
+          "_after_commit and after_rollback for #{unread.sort.join(', ')} are in declaration order: the config does not say " \
+            "whether `run_after_transaction_callbacks_in_order_defined` is on, and when it is off Rails runs them last declared first._"
+        end
+
         # One callback record rendered as the line the file declares. The
         # declared macro, not the resolved type: `after_commit_on_create` is
         # a key this gem synthesizes, not something the source says.
         def callback_declaration(callback)
+          if callback[:skip]
+            kind, event = callback[:type].to_s.split("_", 2)
+            return "skip_callback :#{event}, :#{kind}, #{callback_target(callback[:method])}#{callback_options_tail(callback[:options])}"
+          end
+
           name = callback[:name] || callback[:type]
           method = callback[:method].to_s
           target = inline_block_callback?(method) ? "do" : callback_target(method)
@@ -841,6 +864,22 @@ module RailsAiContext
 
         private
 
+        # The locale and variant a view file renders for, reading the locales the app makes available.
+        def view_alternate_of(path)
+          RailsAiContext::ViewFile.alternate_of(path, RailsAiContext::RunCache.fetch([ :view_locales ]) { available_locales })
+        end
+
+        def booted_app?
+          !RailsAiContext.static_tier? && !rails_app.is_a?(RailsAiContext::StaticApp)
+        end
+
+        # Booted, as I18n holds them; unbooted, as the i18n section read them from config or the locale files.
+        def available_locales
+          return I18n.available_locales.map(&:to_s) if booted_app? && defined?(I18n)
+
+          Array(RailsAiContext::Payload.section(cached_context, :i18n)&.dig(:available_locales)).map(&:to_s)
+        end
+
         # English units whatever the locale, unless the app offers no English at all.
         def human_size(bytes)
           ActiveSupport::NumberHelper.number_to_human_size(bytes.to_i, locale: :en)

data/lib/rails_ai_context/tools/diagnose.rb

@@ -363,7 +363,7 @@ module RailsAiContext
           names += Array(model_data[:scopes]).filter_map { |s| s.is_a?(Hash) ? (s[:name] || s["name"])&.to_s : s.to_s }
 
           table = model_data[:table_name].to_s
-          columns = cached_context.dig(:schema, :tables, table, :columns)
+          columns = RailsAiContext::Payload.schema_table(cached_context[:schema], table)&.dig(:columns)
           names += Array(columns).filter_map { |c| (c[:name] || c["name"])&.to_s }
 
           names.uniq

data/lib/rails_ai_context/tools/generate_test.rb

@@ -121,7 +121,7 @@ module RailsAiContext
         # the subject's existing test, so the answer can point there instead of a new file.
         def test_path(base, kind, stem, fallback_dir, fallback_suffix)
           framework = RailsAiContext::TestFramework
-          root = rails_app.root.to_s
+          root = RailsAiContext::PathResolver.test_root(rails_app.root.to_s)
           dir, suffix = framework.layout(root, base, kind, framework.subject_stems(cached_context, kind))
           dir ||= fallback_dir
           suffix ||= fallback_suffix
@@ -131,7 +131,9 @@ module RailsAiContext
             full = File.expand_path(rel, root)
             RailsAiContext::SafePath.contained?(full, root) && File.file?(full)
           end
-          [ "#{dir}/#{stem}#{suffix}", existing, dir ]
+          app_root = rails_app.root.to_s
+          [ RailsAiContext::PathResolver.suite_relative(app_root, "#{dir}/#{stem}#{suffix}"),
+            existing && RailsAiContext::PathResolver.suite_relative(app_root, existing), dir ]
         rescue => e
           RailsAiContext.debug_fail(e, [ "#{fallback_dir}/#{stem}#{fallback_suffix}", nil, fallback_dir ], label: "test_path")
         end
@@ -643,7 +645,7 @@ module RailsAiContext
           file_path, existing, dir = test_path("test", :controller, snake, "test/controllers", "_controller_test.rb")
           return existing_test_response(existing) if existing
 
-          style = RailsAiContext::TestFramework.test_style(rails_app.root, dir)
+          style = RailsAiContext::TestFramework.test_style(RailsAiContext::PathResolver.test_root(rails_app.root.to_s), dir)
           res = res.merge(test_case: style[:test_case] == true)
           res[:factory] = find_factory_name(res[:model], tests_data) if style[:factories] && res[:model]
           res[:parents] = route_parents(routes, res, tests_data, ref: "@") if res[:factory]
@@ -1392,14 +1394,12 @@ module RailsAiContext
         end
 
         def schema_content_columns(table)
-          tables = (cached_context[:schema] || {})[:tables] || {}
-          cols = (tables[table] || tables[table.to_sym] || {})[:columns] || []
+          cols = (RailsAiContext::Payload.schema_table(cached_context[:schema], table) || {})[:columns] || []
           cols.map { |c| c[:name].to_s } - %w[id created_at updated_at]
         end
 
         def schema_column_type(table, column)
-          tables = (cached_context[:schema] || {})[:tables] || {}
-          cols = (tables[table] || tables[table.to_sym] || {})[:columns] || []
+          cols = (RailsAiContext::Payload.schema_table(cached_context[:schema], table) || {})[:columns] || []
           col = cols.find { |c| c[:name].to_s == column }
           (col && col[:type]).to_s
         end
@@ -1408,8 +1408,7 @@ module RailsAiContext
         # own value for one of these raises RecordNotUnique even when the
         # model declares no uniqueness validation.
         def unique_index_columns(table)
-          tables = (cached_context[:schema] || {})[:tables] || {}
-          indexes = (tables[table] || tables[table.to_sym] || {})[:indexes] || []
+          indexes = (RailsAiContext::Payload.schema_table(cached_context[:schema], table) || {})[:indexes] || []
           indexes.select { |i| i[:unique] }.flat_map { |i| Array(i[:columns]).map(&:to_s) }
         end
 

data/lib/rails_ai_context/tools/get_active_support.rb

@@ -4,7 +4,7 @@ module RailsAiContext
   module Tools
     class GetActiveSupport < BaseTool
       tool_name "rails_get_active_support"
-      description "Get ActiveSupport surface: concern modules across app/**/concerns, registered deprecators, MessageVerifier/MessageEncryptor usage, tagged logging, subscribed on_load hooks, and cache store. " \
+      description "Get ActiveSupport surface: concern modules across app/**/concerns, registered deprecators, MessageVerifier/MessageEncryptor usage, the ActiveSupport::Notifications events the app subscribes to and where, tagged logging, subscribed on_load hooks, and cache store. " \
         "Use when: checking framework-level wiring, finding where crypto helpers are used, or understanding boot-time hooks."
 
       input_schema(properties: {})
@@ -12,7 +12,7 @@ module RailsAiContext
       guide_row(
         order: 44,
         mcp: "rails_get_active_support",
-        summary: "Concerns registry, deprecators, MessageVerifier usage, on_load hooks, cache store"
+        summary: "Concerns registry, deprecators, MessageVerifier usage, notification subscriptions, on_load hooks, cache store"
       )
 
       annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
@@ -24,6 +24,7 @@ module RailsAiContext
           render_concerns(lines, active_support[:concerns])
           render_simple_list(lines, "Deprecators", active_support[:deprecators])
           render_verifier_usage(lines, active_support[:message_verifier_usage])
+          render_subscriptions(lines, active_support[:notification_subscriptions])
           render_tagged_logging(lines, active_support[:tagged_logging])
           render_on_load_hooks(lines, active_support[:on_load_hooks])
           render_cache(lines, active_support[:cache_usage])
@@ -109,12 +110,26 @@ module RailsAiContext
           end
         end
 
+        def render_subscriptions(lines, subscriptions)
+          subscriptions = Array(subscriptions)
+          return if subscriptions.empty?
+
+          lines << "" << "## Notification Subscriptions (#{subscriptions.size})"
+          subscriptions.each { |s| lines << "- `#{s[:event]}` - #{s[:via]} (`#{s[:file]}:#{s[:line]}`)" }
+        end
+
         def render_tagged_logging(lines, tagged)
           tagged = tagged || {}
-          return unless tagged[:configured]
+          tags = tagged[:tags]
+          unavailable = tags[:unavailable] if tags.is_a?(Hash)
+          return unless tagged[:configured] || unavailable
 
           lines << "" << "## Tagged Logging"
-          lines << "- **Tags:** #{Array(tagged[:tags]).join(', ')}" if tagged[:tags]&.any?
+          if unavailable
+            lines << "- **Tags:** #{RailsAiContext::Confidence.unavailable(unavailable)}"
+          elsif tags&.any?
+            lines << "- **Tags:** #{Array(tags).join(', ')}"
+          end
           lines << "- **Configured in:** `#{tagged[:initializer]}`" if tagged[:initializer]
         end
 

data/lib/rails_ai_context/tools/get_api.rb

@@ -52,6 +52,17 @@ module RailsAiContext
         end
       end
 
+      # What serializes responses, or nil when the app has no serializer layer.
+      def self.serialization_found(data)
+        return serialization_label(data[:serializers]) if serializers?(data)
+
+        dirs = Array(data.dig(:serializers, :serializer_dirs))
+        return if dirs.empty?
+
+        "no serializer framework detected; the app has its own layer in " +
+          dirs.map { |dir| "#{dir[:path]} (#{count_phrase(dir[:files], "file")})" }.join(", ")
+      end
+
       class << self
         private
 
@@ -103,7 +114,7 @@ module RailsAiContext
             source = dirs.any? ? dirs.join(", ") : "app/controllers/api/"
             return "#{data[:api_versioning].join(', ')} (#{source})"
           end
-          "not detected (no api/v* directories under app/controllers, app/api or lib/api)"
+          "not detected (no api/v* directory with Ruby code under app/controllers, app/api or lib/api)"
         end
 
         def rate_limiting_line(data)
@@ -171,7 +182,7 @@ module RailsAiContext
         def serializers?(data)
           serializers = data[:serializers]
           return false unless serializers.is_a?(Hash)
-          serializers[:jbuilder].to_i > 0 || (serializers[:serializer_classes].is_a?(Array) && serializers[:serializer_classes].any?)
+          serializers[:jbuilder].to_i > 0 || serializers[:rabl].to_i > 0 || (serializers[:serializer_classes].is_a?(Array) && serializers[:serializer_classes].any?)
         end
 
         def versioning?(data)
@@ -186,6 +197,8 @@ module RailsAiContext
           parts = []
           jbuilder = serializers[:jbuilder].to_i
           parts << "Jbuilder (#{count_phrase(jbuilder, "template")})" if jbuilder > 0
+          rabl = serializers[:rabl].to_i
+          parts << "RABL (#{count_phrase(rabl, "template")})" if rabl > 0
 
           classes = serializers[:serializer_classes]
           if classes.is_a?(Array) && classes.any?
@@ -198,15 +211,8 @@ module RailsAiContext
         end
 
         def serialization_line(data)
-          return serialization_label(data[:serializers]) if serializers?(data)
-
-          dirs = Array(data.dig(:serializers, :serializer_dirs))
-          if dirs.any?
-            return "no serializer framework detected; the app has its own layer in " +
-                   dirs.map { |dir| "#{dir[:path]} (#{count_phrase(dir[:files], "file")})" }.join(", ")
-          end
-
-          "none detected (no .jbuilder templates, no app/serializers classes)"
+          serialization_found(data) ||
+            "none detected (no .jbuilder or .rabl templates, no serializer classes in app/serializers, app/blueprints or app/resources)"
         end
 
         def graphql_label(graphql)

data/lib/rails_ai_context/tools/get_autoload.rb

@@ -36,12 +36,14 @@ module RailsAiContext
               lines << "  - [error: #{l[:error]}]" if l[:error]
               lines << "  - collapsed: #{l[:collapsed].join(', ')}" if l[:collapsed]&.any?
               lines << "  - ignored: #{l[:ignored].join(', ')}" if l[:ignored]&.any?
+              lines << "  - not eager loaded: #{l[:not_eager_loaded].join(', ')}" if l[:not_eager_loaded]&.any?
             end
           end
 
-          render_paths(lines, "Autoload paths", autoload[:autoload_paths])
-          render_paths(lines, "Autoload-once paths", autoload[:autoload_once_paths])
-          render_paths(lines, "Eager-load paths", autoload[:eager_load_paths])
+          namespaces = autoload[:autoload_namespaces] || {}
+          render_paths(lines, "Autoload paths", autoload[:autoload_paths], namespaces)
+          render_paths(lines, "Autoload-once paths", autoload[:autoload_once_paths], namespaces)
+          render_paths(lines, "Eager-load paths", autoload[:eager_load_paths], namespaces)
 
           inflections = autoload[:custom_inflections] || []
           if inflections.any?
@@ -59,12 +61,15 @@ module RailsAiContext
         # Custom autoload paths (beyond Rails' defaults) matter most, but the
         # full list is what AI needs for "where can this constant live" - cap
         # long framework lists rather than hiding them.
-        def render_paths(lines, title, paths)
+        def render_paths(lines, title, paths, namespaces)
           paths = Array(paths)
           return if paths.empty?
 
           lines << "" << "## #{title} (#{paths.size})"
-          paths.first(MAX_PATHS_SHOWN).each { |p| lines << "- `#{p}`" }
+          paths.first(MAX_PATHS_SHOWN).each do |p|
+            namespace = namespaces[p] || namespaces[p.to_sym]
+            lines << "- `#{p}`#{" (namespace `#{namespace}`)" if namespace}"
+          end
           lines << "_... #{paths.size - MAX_PATHS_SHOWN} more_" if paths.size > MAX_PATHS_SHOWN
         end
       end

data/lib/rails_ai_context/tools/get_callbacks.rb

@@ -7,7 +7,8 @@ module RailsAiContext
       description "Get ActiveRecord model callbacks grouped by type, in Rails event order: before/after/around for validation, save, create, update, destroy. " \
         "Use when: understanding side effects, debugging callback chains, or checking what happens on save/create/destroy. " \
         "Specify model:\"User\" for one model's callbacks. detail:\"full\" includes callback method source code. " \
-        "The list is what the model file and its concerns declare, and within one type the order is declaration order."
+        "The list is what the model, its base classes and its concerns declare, and within one type the order is the order Rails runs them, " \
+        "a before_ or around_ callback with prepend: true first, and after_commit in the order the app's setting gives."
 
       # `after_create_commit :x` and `after_commit :y, on: :create` run at the
       # same point and keep their own declared spellings, so the two sit
@@ -87,11 +88,18 @@ module RailsAiContext
 
       private_class_method def self.format_model_callbacks(name, data, detail, ctx)
         callbacks = data[:callbacks] || {}
-        if callbacks.empty?
+        association_lines = association_callback_lines(data)
+        if callbacks.empty? && association_lines.empty?
           return "# #{name}\n\nNo callbacks defined.\n\n_Next: `rails_get_model_details(model:\"#{name}\")` for full model detail._"
         end
 
         lines = [ "# #{name} - Callbacks", "" ]
+        if callbacks.empty?
+          lines << "No record callbacks defined."
+          lines.concat(association_section(association_lines))
+          lines << "" << "_Next: `rails_get_model_details(model:\"#{name}\")` for associations and validations_"
+          return lines.join("\n")
+        end
 
         # Organize callbacks by type, in Rails event order
         ordered = order_callbacks(callbacks)
@@ -126,6 +134,9 @@ module RailsAiContext
           end
         end
 
+        note = commit_order_note([ name ]) if data[:commit_order_unread]
+        lines << "" << note if note
+
         # Which concern declared what. The callbacks themselves are already in
         # the execution-order list above, with their bodies at detail:full, so
         # repeating either here prints the same declaration twice.
@@ -139,6 +150,8 @@ module RailsAiContext
           end
         end
 
+        lines.concat(association_section(association_lines))
+
         # Cross-reference hints
         lines << ""
         lines << "_Next: `rails_get_model_details(model:\"#{name}\")` for associations and validations"
@@ -147,40 +160,74 @@ module RailsAiContext
         lines.join("\n")
       end
 
-      private_class_method def self.list_all_callbacks(models, detail, ctx)
-        # Filter to models that have callbacks
-        models_with_callbacks = models.select do |_name, data|
-          data.is_a?(Hash) && !data[:error] && data[:callbacks].is_a?(Hash) && data[:callbacks].any?
+      ASSOCIATION_CALLBACKS = %w[before_add after_add before_remove after_remove].freeze
+
+      private_class_method def self.association_section(association_lines)
+        return [] if association_lines.empty?
+
+        [ "", "## Association callbacks", "_Run when a record is added to or removed from the collection:_", *association_lines ]
+      end
+
+      private_class_method def self.association_callback_lines(data)
+        hooked_associations(data).map do |a, hooks|
+          "- **#{a[:name]}** #{hooks.map { |hook, target| "#{hook} → #{target}" }.join(', ')}"
         end
+      end
+
+      private_class_method def self.association_list(data)
+        hooked = association_callback_lines(data)
+        hooked.any? ? [ "_Association callbacks:_", *hooked ] : []
+      end
+
+      private_class_method def self.hooked_associations(data)
+        Array(data[:associations]).filter_map do |a|
+          hooks = (a[:declared_options] || {}).slice(*ASSOCIATION_CALLBACKS)
+          [ a, hooks ] if hooks.any?
+        end
+      end
+
+      private_class_method def self.list_all_callbacks(models, detail, ctx)
+        models_with_callbacks = models.filter_map do |name, data|
+          next unless data.is_a?(Hash) && !data[:error]
+
+          data = data.merge(callbacks: data[:callbacks].is_a?(Hash) ? data[:callbacks] : {})
+          [ name, data ] if data[:callbacks].any? || hooked_associations(data).any?
+        end.to_h
 
         if models_with_callbacks.empty?
           return text_response("No models with callbacks found.")
         end
 
         lines = [ "# Model Callbacks (#{count_phrase(models_with_callbacks.size, "model")})", "" ]
+        # By name within a count, so a model gaining a callback moves only its own section.
+        by_count = models_with_callbacks.sort_by { |name, data| [ -data[:callbacks].values.flatten.size, name.to_s ] }
 
         case detail
         when "summary"
-          models_with_callbacks.sort_by { |_name, data| -(data[:callbacks]&.values&.flatten&.size || 0) }.each do |name, data|
+          by_count.each do |name, data|
             total = data[:callbacks].values.flatten.size
             types = data[:callbacks].keys.map { |t| callback_type_label(t) }.join(", ")
-            lines << "- **#{name}** - #{count_phrase(total, "callback")} (#{types})"
+            parts = []
+            parts << "#{count_phrase(total, "callback")} (#{types})" if total.positive?
+            hooked = hooked_associations(data).map { |a, _| a[:name] }
+            parts << "association callbacks on #{hooked.join(", ")}" if hooked.any?
+            lines << "- **#{name}** - #{parts.join("; ")}"
           end
           lines << "" << "_Use `model:\"Name\"` for callbacks by type._"
 
         when "standard"
-          models_with_callbacks.sort_by { |_name, data| -(data[:callbacks]&.values&.flatten&.size || 0) }.each do |name, data|
+          by_count.each do |name, data|
             ordered = order_callbacks(data[:callbacks])
             lines << "## #{name}"
             ordered.each do |type, methods|
               lines << "- **#{callback_type_label(type)}** → #{format_targets(methods, data, type)}"
             end
-            lines << ""
+            lines.concat(association_list(data)) << ""
           end
           lines << "_Use `model:\"Name\"` with `detail:\"full\"` for callback source code._"
 
         when "full"
-          models_with_callbacks.sort_by { |_name, data| -(data[:callbacks]&.values&.flatten&.size || 0) }.each do |name, data|
+          by_count.each do |name, data|
             ordered = order_callbacks(data[:callbacks])
             lines << "## #{name}"
             ordered.each do |type, methods|
@@ -194,10 +241,13 @@ module RailsAiContext
                 end
               end
             end
-            lines << ""
+            lines.concat(association_list(data)) << ""
           end
         end
 
+        unread = models_with_callbacks.select { |_, data| data[:commit_order_unread] }.keys
+        note = commit_order_note(unread) unless detail == "summary"
+        lines << "" << note if note
         text_response(lines.join("\n"))
       end
 
@@ -253,11 +303,12 @@ module RailsAiContext
       # that is not the model file.
       private_class_method def self.source_location(source)
         prefix = source[:from_concern] ? "#{source[:from_concern]} " : ""
+        return "#{prefix}line #{source[:start_line]}" if source[:start_line] == source[:end_line]
+
         "#{prefix}lines #{source[:start_line]}-#{source[:end_line]}"
       end
 
-      # The conditions arrive in step with the names, one entry per
-      # occurrence, so the same method declared twice keeps its own condition.
+      # The conditions arrive in step with the names, one entry per callback.
       private_class_method def self.format_targets(methods, data = nil, type = nil)
         per_type = Array(((data && data[:callback_conditions]) || {})[type.to_s])
         methods.each_with_index.map do |m, i|