rails-ai-context 5.30.2 → 5.32.0

data/lib/rails_ai_context/method_name.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  # Where a method name ends in source text, `ping` not `ping?`; no lookahead,
+  # so each fragment is a ripgrep pattern too.
+  module MethodName
+    # Ruby's `\w` and `\s` are ASCII and ripgrep's Unicode, so every class stays
+    # in ASCII; Ruby reads any other character as part of a name.
+    SPACE_CHARS = "\\t\\n\\v\\f\\r "
+    SPACE = "[#{SPACE_CHARS}]"
+
+    module_function
+
+    # After `def name`: `def ping = 1` is an endless `ping`.
+    def definition_end(name)
+      name_end?(name) ? "(?:[\\x00-\\x7F&&[^\\w?!=]]|[!=][=~]|=>|$)" : ""
+    end
+
+    # After a call of `name`: `obj.ping = 1` calls `ping=`, while `ping == 1`,
+    # `ping => x`, `ping ||= 1` and `ping arg` still read `ping`.
+    def call_end(name)
+      return "" unless name_end?(name)
+
+      "(?:[\\x00-\\x7F&&[^\\w?!=\\s]]|[!=][=~]|=>|$|#{SPACE}+(?:[^=#{SPACE_CHARS}]|=[=~>]|$))"
+    end
+
+    def name_end?(name)
+      name.to_s.match?(/(?:\w|[^\x00-\x7F])\z/)
+    end
+  end
+end

data/lib/rails_ai_context/migration_status.rb

@@ -12,20 +12,20 @@ module RailsAiContext
   # ActiveRecord version actually exposes instead of guessing from a version
   # number.
   module MigrationStatus
-    # @param migrate_dir [String] path to the migrations directory to check
+    # @param migrate_dir [String, Array<String>] the migrations directories to check
     # @return [Array<Hash>, nil] [{ version:, name: }, ...] in pending order,
     #   or nil when pending status can't be determined (no migrations
     #   directory, ActiveRecord not loaded, or the database is unreachable).
     def self.pending(migrate_dir)
-      return nil unless migrate_dir && Dir.exist?(migrate_dir)
-      return nil unless defined?(ActiveRecord::Base)
+      dirs = Array(migrate_dir).select { |dir| Dir.exist?(dir) }
+      return nil if dirs.empty? || !defined?(ActiveRecord::Base)
 
-      context = migration_context(migrate_dir)
+      context = migration_context(dirs)
       begin
         context.open.pending_migrations.map { |m| { version: m.version.to_s, name: m.name } }
       rescue ActiveRecord::MigrationError
         # A future or duplicate version stops Rails loading the directory; the applied set still answers.
-        PendingMigrations.for(migrate_dir: migrate_dir, applied: context.get_all_versions)
+        PendingMigrations.for(migrate_dir: dirs, applied: context.get_all_versions)
       end
     rescue => e
       RailsAiContext.debug_fail(e, nil, label: "MigrationStatus.pending")

data/lib/rails_ai_context/output_guard.rb

@@ -25,10 +25,12 @@ module RailsAiContext
     # re-execs itself while the quarantine is up.
     STDOUT_FD_ENV = "RAILS_AI_CONTEXT_STDOUT_FD"
 
-    def self.quarantine_stdout
+    # Yields the real stdout. across_exec: false keeps it from the children of
+    # a long-lived caller.
+    def self.quarantine_stdout(across_exec: true)
       original = $stdout
       saved_stdout = reopenable_target? ? saved_stdout_io : nil
-      if saved_stdout
+      if saved_stdout && across_exec
         # `exec` closes a dup'd descriptor unless close-on-exec is cleared,
         # and the new image would then save fd 1 - by then pointing at
         # stderr - as its "stdout" and write every MCP response there.
@@ -37,10 +39,10 @@ module RailsAiContext
         # names a different Bundler than the one running.
         saved_stdout.close_on_exec = false
         ENV[STDOUT_FD_ENV] = saved_stdout.fileno.to_s
-        STDOUT.reopen($stderr)
       end
+      STDOUT.reopen($stderr) if saved_stdout
       $stdout = $stderr
-      yield
+      yield(saved_stdout || original)
     ensure
       if saved_stdout
         STDOUT.reopen(saved_stdout)

data/lib/rails_ai_context/package_json.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "pathname"
 
 module RailsAiContext
   # Which npm packages an app depends on, read once per package.json, and the
@@ -13,11 +14,22 @@ module RailsAiContext
   # package.json for importmap and a whole Vue app under frontend/, so every
   # manifest is read and merged, the root one winning a version disagreement.
   # Callers ask what the app depends on, never which directory holds the file.
+  #
+  # Two kinds of directory outside the app root are read, for frontend
+  # manifests only: a `frontend_paths` entry the app declared, and the JS
+  # workspace root a lockfile sits in. Each is read with the sensitive-file
+  # and symlink rules applied relative to that directory.
   module PackageJson
     # Where a frontend app lives when it has not been declared through
     # `frontend_paths`. Same list the frontend introspector falls back to.
     FRONTEND_DIRS = %w[app/frontend app/javascript frontend client].freeze
 
+    # In the order a package manager is named when several lockfiles exist.
+    LOCKFILES = {
+      "bun.lock" => "bun", "bun.lockb" => "bun", "pnpm-lock.yaml" => "pnpm",
+      "yarn.lock" => "yarn", "package-lock.json" => "npm"
+    }.freeze
+
     MUTEX = Mutex.new
     CACHE = {}
     private_constant :MUTEX, :CACHE
@@ -25,9 +37,72 @@ module RailsAiContext
     module_function
 
     def deps(root)
-      manifest_dirs(root).reduce({}) do |merged, dir|
-        merged.merge(read(File.join(dir, "package.json")))
+      outside = configured_outside(root).filter_map { |dir| outside_file(dir[:dir], "package.json") }
+      inside = manifest_dirs(root).map { |dir| File.join(dir, "package.json") }
+      (outside + inside).reduce({}) { |merged, path| merged.merge(read(path)) }
+    end
+
+    # The first lockfile found in the app root, then in each frontend directory,
+    # with that directory's label (nil for the app root).
+    def package_manager(root)
+      root = root.to_s
+      name = LOCKFILES.find { |file, _| File.exist?(File.join(root, file)) }&.last
+      return [ name, nil ] if name
+
+      (frontend_roots(root) + [ workspace_root(root) ].compact).each do |dir|
+        name = LOCKFILES.find { |file, _| outside_file(dir[:dir], file) }&.last
+        return [ name, dir[:label] ] if name
+      end
+      nil
+    end
+
+    # Every directory besides the app root that holds frontend config: the
+    # frontend dirs inside it, then the declared ones outside it.
+    def frontend_roots(root)
+      root = root.to_s
+      inside = manifest_dirs(root)[0...-1].map { |dir| { dir: dir, label: dir.delete_prefix("#{root}/") } }
+      inside + configured_outside(root)
+    end
+
+    # Declared frontend_paths entries that resolve to a directory outside the
+    # app root, labelled as the app wrote them.
+    def configured_outside(root)
+      real_root = File.realpath(root.to_s)
+      declared_paths.filter_map do |path|
+        real = File.realpath(File.join(root.to_s, path.to_s))
+        next if SafePath.contained?(real, real_root) || !File.directory?(real)
+
+        { dir: real, label: path.to_s, source: "configuration" }
+      rescue SystemCallError
+        nil
       end
+    rescue SystemCallError
+      []
+    end
+
+    # The nearest ancestor that holds a lockfile or declares workspaces,
+    # never above the git root, and never outside a git repository: package
+    # managers write one lockfile at the workspace root.
+    def workspace_root(root)
+      real_root = File.realpath(root.to_s)
+      repo = SafePath.git_root(real_root) or return nil
+      candidates = []
+      dir = real_root
+      candidates << (dir = File.dirname(dir)) until dir == repo
+      found = candidates.find { |candidate| workspace?(candidate) }
+      return nil unless found
+
+      { dir: found, label: Pathname.new(found).relative_path_from(Pathname.new(real_root)).to_s, source: "workspace" }
+    rescue SystemCallError
+      nil
+    end
+
+    # The realpath of a file in a directory outside the app root, or nil when
+    # it is missing, sensitive or a symlink out of that directory. A lockfile
+    # past max_file_size still exists.
+    def outside_file(dir, name)
+      found = SafePath.locate(name, under: dir)
+      found.realpath if found.ok? || found.refusal == :too_large
     end
 
     def present?(root, name)
@@ -45,12 +120,28 @@ module RailsAiContext
     end
 
     def frontend_dirs(root)
+      declared = declared_paths
+      (declared.any? ? declared : FRONTEND_DIRS).map { |dir| File.join(root, dir.to_s) }
+    end
+    private_class_method :frontend_dirs
+
+    def declared_paths
       configured = RailsAiContext.configuration.respond_to?(:frontend_paths) &&
                    RailsAiContext.configuration.frontend_paths
-      declared = configured.is_a?(Array) && configured.any? ? configured : FRONTEND_DIRS
-      declared.map { |dir| File.join(root, dir.to_s) }
+      configured.is_a?(Array) ? configured : []
     end
-    private_class_method :frontend_dirs
+    private_class_method :declared_paths
+
+    def workspace?(dir)
+      return true if LOCKFILES.keys.any? { |file| outside_file(dir, file) }
+
+      content, = SafePath.read("package.json", under: dir)
+      data = content && JSON.parse(content)
+      data.is_a?(Hash) && data.key?("workspaces")
+    rescue JSON::ParserError
+      false
+    end
+    private_class_method :workspace?
 
     def contained?(dir, root)
       SafePath.contained?(File.realpath(dir), File.realpath(root))

data/lib/rails_ai_context/path_resolver.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "concurrent"
+require "pathname"
 
 module RailsAiContext
   # Resolves where a kind of Rails app code can live for a given app root.
@@ -26,6 +27,7 @@ module RailsAiContext
     DECLARED_ROOTS = Concurrent::Map.new
     APP_ROOTS = Concurrent::Map.new
     PATH_GEM_LIBS = Concurrent::Map.new
+    NAMESPACED_ROOTS = Concurrent::Map.new
 
     module_function
 
@@ -33,14 +35,36 @@ module RailsAiContext
 
     def controller_dirs(root) = dirs_for(root, "app/controllers")
 
-    def view_dirs(root) = dirs_for(root, "app/views")
+    # Rails searches config.paths["app/views"] in order, so a root the app
+    # unshifts wins over app/views even when it is nested inside it.
+    def view_dirs(root)
+      prepended, appended = declared(root)[:views].partition { |direction, _dir| direction == :prepend }
+      spelled = ->(list) { list.map { |_direction, dir| File.join(root.to_s, dir) } }
+      engines = RunCache.fetch([ :engine_view_dirs, root.to_s ]) do
+        enclosing_engine_roots(root).map { |engine| File.join(engine, "app/views") }.select { |dir| Dir.exist?(dir) }
+      end
+      (spelled.(prepended) + dirs_for(root, "app/views") + spelled.(appended) + engines).uniq.freeze
+    end
+
+    # Every initializer Rails loads: railties globs config/initializers with **/*.rb, in path order.
+    # A symlink that resolves outside the app root, or nowhere, is left out.
+    def initializer_paths(root)
+      real_root = File.realpath(root.to_s)
+      Dir.glob(File.join(root.to_s, "config", "initializers", "**", "*.rb")).sort.select do |path|
+        SafePath.contained?(File.realpath(path), real_root)
+      rescue SystemCallError
+        false
+      end
+    rescue SystemCallError
+      []
+    end
 
     # The initializers an app spells for `name`, however it spells them: a
     # load-order prefix (`009-omniauth.rb`), a hyphen where the gem uses an
     # underscore (`rack-attack.rb`), or a compound name (`custom_devise.rb`).
     def initializer_files(root, name)
       target = normalize_initializer_name(name)
-      Dir.glob(File.join(root.to_s, "config", "initializers", "*.rb")).sort.select do |path|
+      initializer_paths(root).select do |path|
         base = normalize_initializer_name(File.basename(path, ".rb"))
         base == target || base.end_with?("_#{target}")
       end
@@ -72,6 +96,23 @@ module RailsAiContext
       end
     end
 
+    # app/* directories Rails generates for code that is not a model; the model dirs are dropped by path.
+    # ponytail: skipped by name, so an app/<dir> of one of these names that does hold models is missed;
+    # read config.autoload_paths per dir if that bites.
+    NON_MODEL_APP_DIRS = %w[
+      assets javascript views controllers helpers mailers mailboxes jobs channels
+      components serializers policies decorators presenters workers graphql uploaders validators
+    ].freeze
+
+    # The autoload roots besides the model directories that can hold a model:
+    # every other app/* root and the roots config/application.rb adds.
+    def extra_model_roots(root)
+      models = model_dirs(root).map { |dir| root_key(dir) }
+      candidates = app_roots(root).reject { |dir| NON_MODEL_APP_DIRS.include?(File.basename(dir)) } + declared_roots(root)
+      candidates.reject { |dir| models.any? { |model_dir| SafePath.contained?(model_dir, root_key(dir)) } }
+                .uniq { |dir| root_key(dir) }
+    end
+
     # Only path gems inside the repo (`path "../gems" do` locks as `remote: gems`);
     # one outside is an installed gem as far as the app's source goes.
     def path_gem_libs(root)
@@ -79,15 +120,17 @@ module RailsAiContext
       PATH_GEM_LIBS.compute_if_absent(key) { read_path_gem_libs(key) }
     end
 
+    # Remotes are relative to the lockfile, which for a test/dummy is the engine's.
     def read_path_gem_libs(root)
-      lock = SafeFile.read(File.join(root, "Gemfile.lock"))
+      bundle = GemLock.bundle(root)
+      lock = bundle.lockfile && SafeFile.read(bundle.lockfile)
       return [] unless lock
 
-      real_root = File.realpath(root)
+      trusted = File.realpath(bundle.trusted)
       remotes = lock.scan(/^PATH\r?\n  remote: (.+?)\r?$/).flatten.map(&:strip)
       remotes.flat_map do |remote|
-        base = File.expand_path(remote, root)
-        next [] unless Dir.exist?(base) && SafePath.contained?(File.realpath(base), real_root)
+        base = File.expand_path(remote, bundle.dir)
+        next [] unless Dir.exist?(base) && SafePath.contained?(File.realpath(base), trusted)
 
         # Bundler's own glob for the gemspecs a path source holds.
         Dir.glob(File.join(base, "{,*,*/*}.gemspec")).map { |spec| File.join(File.dirname(spec), "lib") }
@@ -100,20 +143,42 @@ module RailsAiContext
     # The roots config/application.rb adds by hand, such as lib_static.
     def declared_roots(root)
       key = File.expand_path(root.to_s)
-      DECLARED_ROOTS.compute_if_absent(key) { read_declared_roots(key) }
+      declared(key)[:autoload].map { |relative| File.join(key, relative) }
     end
 
-    def read_declared_roots(root)
+    # The lib subdirectories `autoload_lib(ignore:)` keeps out of autoloading.
+    def ignored_dirs(root)
+      key = File.expand_path(root.to_s)
+      declared(key)[:ignored].map { |relative| File.join(key, relative) }
+    end
+
+    # One walk of config/application.rb for the autoload, ignored and view
+    # roots it adds, app-relative and kept only when they exist inside the app.
+    def declared(root)
+      key = File.expand_path(root.to_s)
+      DECLARED_ROOTS.compute_if_absent(key) { read_declared(key) }
+    end
+
+    NONE_DECLARED = { autoload: [].freeze, ignored: [].freeze, views: [].freeze }.freeze
+
+    def read_declared(root)
       path = File.join(root, "config", "application.rb")
-      return [] unless File.file?(path)
+      return NONE_DECLARED unless File.file?(path)
 
-      declared = Introspectors::SourceIntrospector.walk(
-        path, { autoload: Introspectors::Listeners::AutoloadPathsListener }
-      )[:autoload]
+      found = Introspectors::SourceIntrospector.walk(
+        path, { autoload: Introspectors::Listeners::AutoloadPathsListener,
+                ignored: Introspectors::Listeners::AutoloadIgnoreListener,
+                views: Introspectors::Listeners::ViewPathsListener }
+      )
       real_root = File.realpath(root)
-      declared.uniq.map { |relative| File.join(root, relative) }.select { |dir| contained_dir?(dir, real_root) }
+      inside = ->(relative) { contained_dir?(File.join(root, relative), real_root) }
+      {
+        autoload: found[:autoload].uniq.select(&inside).freeze,
+        ignored: found[:ignored].uniq.select(&inside).freeze,
+        views: found[:views].uniq.select { |_direction, relative| inside.(relative) }.freeze
+      }.freeze
     rescue StandardError => e
-      RailsAiContext.debug_fail(e, [], label: "PathResolver.declared_roots")
+      RailsAiContext.debug_fail(e, NONE_DECLARED, label: "PathResolver.declared_roots")
     end
 
     # A declared root is still a path the file wrote: `#{config.root}/../shared`
@@ -130,9 +195,43 @@ module RailsAiContext
       return nil if relative.empty? || relative.include?("..")
 
       (roots || autoload_roots(root)).lazy
-        .map { |dir| File.join(dir, "#{relative}.rb") }.find { |path| File.file?(path) }
+        .map { |dir| File.join(dir, "#{relative}.rb") }.find { |path| File.file?(path) } ||
+        namespaced_file(root, name.to_s)
+    end
+
+    def namespaced_file(root, name)
+      namespaced_roots(root).each do |dir, namespace|
+        next unless name.start_with?("#{namespace}::")
+
+        path = File.join(dir, "#{name.delete_prefix("#{namespace}::").underscore}.rb")
+        return path if File.file?(path)
+      end
+      nil
+    end
+    private_class_method :namespaced_file
+
+    # [dir, namespace] for each `push_dir(..., namespace: X)` in config/application.rb
+    # or an initializer. Only files that say push_dir are parsed.
+    def namespaced_roots(root)
+      key = File.expand_path(root.to_s)
+      NAMESPACED_ROOTS.compute_if_absent(key) { read_namespaced_roots(key) }
     end
 
+    def read_namespaced_roots(root)
+      real_root = File.realpath(root)
+      files = [ "config/application.rb", *initializer_paths(root).map { |path| path.delete_prefix(SafePath.dir_prefix(root)) } ]
+      sources = files.filter_map { |relative| SafePath.read(relative, under: root).first }.select { |source| source.include?("push_dir") }
+      sources.flat_map do |source|
+        Introspectors::SourceIntrospector.walk_source(source, { roots: Introspectors::Listeners::NamespacedRootsListener })[:roots]
+      end.uniq.filter_map do |relative, namespace|
+        dir = File.join(root, relative)
+        [ dir, namespace ] if contained_dir?(dir, real_root)
+      end.freeze
+    rescue StandardError => e
+      RailsAiContext.debug_fail(e, [], label: "PathResolver.namespaced_roots")
+    end
+    private_class_method :read_namespaced_roots
+
     # The files a constant can be declared in, its own first, then each enclosing
     # namespace's (`CanonicalURL::Helpers` lives in `canonical_url.rb`).
     def namespace_files(root, name, roots: nil)
@@ -156,6 +255,61 @@ module RailsAiContext
       end
     end
 
+    # Booted from an engine's test/dummy, the engine whose root holds the app
+    # root: its classes, views and tests are the project's own. Never this gem.
+    def enclosing_engine_roots(root)
+      return [] unless defined?(::Rails::Engine)
+
+      RunCache.fetch([ :enclosing_engine_roots, root.to_s ]) do
+        inside = "#{root_key(root.to_s)}#{File::SEPARATOR}"
+        ::Rails::Engine.subclasses.filter_map do |engine|
+          next if engine.root.nil? || (defined?(RailsAiContext::Engine) && engine.equal?(RailsAiContext::Engine))
+
+          dir = engine.root.to_s
+          dir if inside.start_with?("#{root_key(dir)}#{File::SEPARATOR}")
+        rescue StandardError
+          nil
+        end
+      end
+    end
+
+    # The root whose suite tests the app: an engine's test/dummy keeps none of its own.
+    def test_root(root)
+      root = root.to_s
+      return root if %w[test spec].any? { |dir| Dir.exist?(File.join(root, dir)) }
+
+      RunCache.fetch([ :test_root, root ]) { enclosing_engine_roots(root).first || bundle_engine_root(root) || root }
+    end
+
+    # Unbooted, the engine is the gemspec directory holding the bundle config/boot.rb
+    # names, which GemLock only resolves inside the app's git repository.
+    def bundle_engine_root(root)
+      dir = GemLock.bundle(root).dir
+      real_root = root_key(root)
+      return nil if dir == root || !real_root.start_with?("#{dir}#{File::SEPARATOR}") || Dir.glob(File.join(dir, "*.gemspec")).empty?
+
+      # In the root's own spelling, which every caller strips from the paths it prints.
+      depth = real_root.delete_prefix("#{dir}#{File::SEPARATOR}").split(File::SEPARATOR).size
+      depth.times.reduce(File.expand_path(root)) { |path, _| File.dirname(path) }
+    end
+
+    # A path under the suite root as the app root reads it: `../models/x_test.rb` from a test/dummy.
+    def suite_relative(root, relative)
+      suite = test_root(root)
+      return relative if suite == root.to_s
+
+      Pathname.new(File.join(root_key(suite), relative)).relative_path_from(Pathname.new(root_key(root))).to_s
+    end
+
+    # Inside the app root, or inside the engine its test/dummy runs in.
+    def project_file?(path, root)
+      real = File.realpath(path)
+      dirs = RunCache.fetch([ :project_dirs, root.to_s ]) { [ root.to_s, *enclosing_engine_roots(root) ].map { |dir| root_key(dir) } }
+      dirs.any? { |dir| SafePath.contained?(real, dir) }
+    rescue SystemCallError
+      false
+    end
+
     def root_key(root)
       File.realpath(root)
     rescue SystemCallError
@@ -210,6 +364,7 @@ module RailsAiContext
       DECLARED_ROOTS.clear
       APP_ROOTS.clear
       PATH_GEM_LIBS.clear
+      NAMESPACED_ROOTS.clear
     end
 
     def discover_code_roots(root)

data/lib/rails_ai_context/payload.rb

@@ -80,6 +80,54 @@ module RailsAiContext
       count.nil? ? " - model count unavailable" : " - #{CountPhrase.call(count, 'model')}"
     end
 
+    # Every table the schema section holds, as [database, name, data]: the primary's
+    # (database nil) first, then each secondary dump's.
+    def schema_tables(schema)
+      return [] unless schema.is_a?(Hash)
+
+      primary = (schema[:tables].is_a?(Hash) ? schema[:tables] : {}).map { |name, data| [ nil, name, data ] }
+      secondary = (schema[:secondary_databases].is_a?(Hash) ? schema[:secondary_databases] : {}).flat_map do |db, info|
+        tables = info.is_a?(Hash) && info[:tables].is_a?(Hash) ? info[:tables] : {}
+        tables.map { |name, data| [ db.to_s, name, data ] }
+      end
+      primary + secondary
+    end
+
+    # A name in two databases answers `database`'s when given, else the primary's.
+    def schema_table(schema, name, database: nil)
+      found = table_holders(schema, name)
+      (found.find { |db, _, _| database && db == database.to_s } || found.first)&.last
+    end
+
+    # The table a model reads, from the database its `connects_to` writes to.
+    def model_table(schema, model)
+      model_tables(schema, model).first&.last
+    end
+
+    # [database, table] for each database a model may read its table from: the one it writes
+    # to, or the primary without connects_to, when that holds the table; every holder otherwise (shards).
+    def model_tables(schema, model)
+      return [] unless model.is_a?(Hash) && model[:table_name]
+
+      found = table_holders(schema, model[:table_name]).map { |db, _, data| [ db || "primary", data ] }
+      writing = model.dig(:database, :writing)&.to_s || ("primary" unless model[:database])
+      written = found.select { |db, _| db == writing }.first(1)
+      written.any? ? written : found
+    end
+
+    def model_databases(schema, model)
+      model_tables(schema, model).map(&:first)
+    end
+
+    # Every database whose schema holds the table, "primary" for the primary's.
+    def schema_databases(schema, name)
+      table_holders(schema, name).map { |db, _, _| db || "primary" }
+    end
+
+    def table_holders(schema, name)
+      schema_tables(schema).select { |_, table, _| table.to_s == name.to_s }
+    end
+
     def models(ctx)
       value = ctx.is_a?(Hash) ? ctx[:models] : nil
       value.is_a?(Hash) && !value[:error] ? value : {}

data/lib/rails_ai_context/pending_migrations.rb

@@ -11,10 +11,10 @@ module RailsAiContext
     # applied: the applied versions, a single newest version, or nil when
     # nothing is known. Unknown answers nil - an empty Array is the different
     # claim that nothing has been applied, and every file is then pending.
-    def for(migrate_dir:, applied: nil)
+    def for(migrate_dir:, applied: nil, root: nil)
       return nil if applied.nil?
 
-      files = migration_files(migrate_dir)
+      files = migration_files(migrate_dir, root: root)
       unapplied = if applied.is_a?(Array)
         known = applied.map(&:to_i)
         files.reject { |m| known.include?(m[:version].to_i) }
@@ -31,29 +31,26 @@ module RailsAiContext
       RunCache.fetch([ :pending_migrations, migrate_dir.to_s ]) { MigrationStatus.pending(migrate_dir) }
     end
 
-    # Each secondary database keeps its own migrate directory, so a secondary
-    # dump compared against db/migrate would report the primary's files.
-    def migrate_dir_for(root, dump_path = nil)
-      base = if dump_path
-        File.basename(dump_path.to_s).sub(/\.(rb|sql)\z/, "").sub(/_?(schema|structure)\z/, "")
-      else
-        ""
-      end
-      File.join(root.to_s, "db", base.empty? ? "migrate" : "#{base}_migrate")
+    # The entry's migrations_paths, else db/migrate as Rails runs it; a dump with no entry here takes the generator's db/<name>_migrate.
+    # Only the dirs Rails migrates: an engine's renumbered copy in db/migrate would read as pending.
+    def migrate_dirs_for(root, dump_path = nil)
+      name = Introspectors::SchemaDumpPath.database_name(root, dump_path)
+      entry = RailsAiContext::DatabaseYml.entry(root, name)
+      Introspectors::MigrationReplay.configured_dirs(root, entry) ||
+        [ File.join(root.to_s, "db", name == "primary" || entry ? "migrate" : "#{name}_migrate") ]
     end
 
-    # Every versioned migration file in the directory. One file scan behind
+    # Every versioned migration file under the directory or directories. One file scan behind
     # both the pending derivation and the migrations listing, so the two
     # cannot disagree on which files count.
-    def migration_files(migrate_dir)
-      return [] unless migrate_dir && Dir.exist?(migrate_dir)
-
-      Dir.glob(File.join(migrate_dir, "*.rb")).sort.filter_map do |path|
+    def migration_files(migrate_dir, root: nil)
+      dirs = Array(migrate_dir).select { |dir| Dir.exist?(dir) }
+      Introspectors::MigrationReplay.migration_files(dirs, root: root).filter_map do |path|
         base = File.basename(path, ".rb")
         version = base[/\A\d+/] or next
         # The class name, so a static entry names the migration the way the
-        # connection's own pending list does.
-        name = base.sub(/\A\d+_/, "").camelize
+        # connection's own pending list does; Rails drops an engine's ".scope" suffix.
+        name = base.sub(/\A\d+_/, "").split(".", 2).first.to_s.camelize
         { version: version, name: name, path: path }
       end
     end