rails-ai-context 5.26.0 → 5.27.0

data/lib/rails_ai_context/action_filters.rb

@@ -55,7 +55,11 @@ module RailsAiContext
         .reject { |f| inherited_skips.include?(f[:name].to_s) && !f[:declared] }
       # Keyed by kind and name: `after_action :audit` and `before_action :audit`
       # are two entries in the chain and Rails runs both.
-      declared_on = parent.to_h { |f| [ entry_key(f), f[:from] ] }
+      # The whole ancestor entry, not only its `from:`: an entry the walk
+      # could not attribute carries `provenance` instead, and merging only
+      # `from` dropped that on the tier the label exists for.
+      attribution_of = parent.to_h { |f| [ entry_key(f), f.slice(:from, :provenance) ] }
+      declared_on = attribution_of
       declared_names = declared.map { |f| entry_key(f) }.to_set
 
       # A filter this body declares is its own, whatever an ancestor declares
@@ -66,7 +70,7 @@ module RailsAiContext
       inherited = mark_conditional_skips(
         parent.reject { |f| declared_names.include?(entry_key(f)) } +
           applicable.select(&inherited_here)
-            .map { |f| f.merge(from: declared_on[entry_key(f)]) }, conditions, action
+            .map { |f| f.except(:from, :provenance).merge(attribution_of[entry_key(f)]) }, conditions, action
       )
 
       { own: own,
@@ -178,11 +182,17 @@ module RailsAiContext
       attributed = Set.new
       conditions = {}
       declares = Set.new
+      # Where in the walk each entry was first seen, so the list can be
+      # emitted root first while the order inside one class is kept.
+      positions = {}
+      evidence = {}
+      depth = 0
       dropped = skipped.map(&:to_s).to_set
       name = Introspectors::ActionResolver.resolve_entry_name(controllers, parent_class, within)
 
       while name && !seen.include?(name)
         seen << name
+        depth += 1
         info = controllers[name]
         source = info.is_a?(Hash) ? nil : base_controller_source(name, root)
         info ||= { filters: Introspectors::ControllerFilters.from_source(source) } if source
@@ -201,29 +211,56 @@ module RailsAiContext
         # the walk did see is never mistaken for a skip of a declaration it
         # could not. A skip record is not a sighting, hence the reject above.
         declares.merge(carried.map { |f| f[:name].to_s })
+        # Whether this class's own body was read at all. Without that, an
+        # unmarked filter is a filter nobody could check, not one a gem
+        # installed - an engine's ApplicationController and a concern-only
+        # payload both land there, and dropping their attribution would lose
+        # the answer rather than correct it.
+        body_known = carried.any? { |f| f[:declared] }
         carried.select { |f| applies?(f, action) }
           .reject { |f| dropped.include?(f[:name].to_s) }
-          .each { |f| record_attribution(found, attributed, f, name) }
+          .each { |f| record_attribution(found, attributed, f, name, positions, depth, evidence, body_known) }
 
         name = Introspectors::ActionResolver.resolve_entry_name(controllers, info[:parent_class], name)
       end
 
-      [ found.values, dropped, conditions, declares ]
+      [ run_order(found, attributed, positions, evidence), dropped, conditions, declares ]
     end
 
     # The closest ancestor carrying a filter keeps its constraints, but a
     # booted ancestor carries names it only inherits, so `from:` moves on to
     # the first ancestor whose own body declared it.
-    def record_attribution(found, attributed, filter, ancestor)
+    def record_attribution(found, attributed, filter, ancestor, positions = {}, depth = 0,
+                           evidence = {}, body_known = false)
       key = entry_key(filter)
       if found.key?(key)
         found[key] = found[key].merge(from: ancestor) if filter[:declared] && !attributed.include?(key)
       else
         found[key] = filter.merge(from: ancestor)
+        positions[key] = depth
+        evidence[key] = body_known
       end
       attributed << key if filter[:declared]
     end
 
+    # Rails runs the root's callbacks first, so the inherited list reads that
+    # way: the walk's class order reversed, each class's own order kept. A
+    # filter no ancestor's body declares is installed from somewhere else -
+    # a gem's `on_load :action_controller` block, the framework, a concern -
+    # and crediting it to the nearest app class sent an agent to a file that
+    # never mentions it.
+    def run_order(found, attributed, positions, evidence = {})
+      found.keys
+        .each_with_index
+        .sort_by { |key, index| [ -positions.fetch(key, 0), index ] }
+        .map do |key, _|
+          entry = found[key]
+          next entry if attributed.include?(key) || !evidence[key]
+
+          entry.merge(from: nil, provenance: "not declared in the controller chain").compact
+        end
+    end
+
     # One entry in the chain. A skip names a filter by name, and a chain entry
     # is a kind and a name: a class can declare both `before_action :audit` and
     # `after_action :audit`, and both run.

data/lib/rails_ai_context/configuration.rb

@@ -13,7 +13,7 @@ module RailsAiContext
 
     # All YAML-supported keys (explicit allowlist for safety)
     YAML_KEYS = %i[
-      ai_tools tool_mode preset context_mode generate_root_files claude_max_lines
+      ai_tools tool_mode preset context_mode context_files generate_root_files claude_max_lines
       anti_hallucination_rules
       server_name cache_ttl max_tool_response_chars
       live_reload live_reload_debounce auto_mount http_path http_bind http_port
@@ -256,6 +256,12 @@ module RailsAiContext
     # for the security review that changed the default.
     attr_accessor :instrumentation_include_arguments
 
+    # Whether this gem writes context files at all. False is MCP-only: the
+    # server and the CLI still answer, and no CLAUDE.md, AGENTS.md, rules
+    # file or .ai-context.json is written or touched. Narrower than
+    # `generate_root_files`, which still writes the split rule files.
+    attr_accessor :context_files
+
     # Whether to generate root-level context files (CLAUDE.md, AGENTS.md, etc.)
     # When false, only generates split rule files (.claude/rules/, .cursor/rules/, etc.)
     attr_accessor :generate_root_files
@@ -408,6 +414,7 @@ module RailsAiContext
       @live_reload              = :auto
       @live_reload_debounce     = 1.5
       @instrumentation_include_arguments = false
+      @context_files            = true
       @generate_root_files      = true
       @anti_hallucination_rules = true
       @max_file_size            = 5_000_000

data/lib/rails_ai_context/doctor.rb

@@ -197,6 +197,10 @@ module RailsAiContext
     end
 
     def check_context_freshness
+      # An MCP-only install asked for no context files, so their absence is
+      # the configuration working, not something to fix.
+      return nil unless RailsAiContext.configuration.context_files
+
       ai_tools = configured_ai_tools
 
       # Find the first existing context file or split rule directory for configured tools

data/lib/rails_ai_context/erb_source.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  # The Ruby inside ERB tags. Two readers need it for different reasons - a
+  # template's ivars, and the ENV names a `.yml` or a view reads - and a
+  # second copy of the tag regex is a second answer to "what is a tag".
+  module ErbSource
+    TAG = /<%={0,2}-?(.*?)-?%>/m
+
+    module_function
+
+    # @return [Boolean] whether the source carries any ERB tag at all
+    def tagged?(source)
+      source.to_s.include?("<%")
+    end
+
+    # The tag bodies, joined. Order is kept; line numbers are not.
+    def tag_bodies(source)
+      source.to_s.scan(TAG).flatten.join("\n")
+    end
+
+    # The same Ruby with everything outside the tags blanked rather than
+    # dropped, so a line number in the result is still the line in the file.
+    # A `<%#` comment is blanked too.
+    def ruby_in_place(source)
+      text = source.to_s
+      out = +""
+      last = 0
+      text.to_enum(:scan, TAG).each do
+        match = Regexp.last_match
+        out << blank(text[last...match.begin(0)])
+        body = match[1].to_s
+        out << (body.lstrip.start_with?("#") ? blank(body) : body)
+        last = match.end(0)
+      end
+      out << blank(text[last..].to_s)
+      out
+    end
+
+    def blank(text)
+      text.gsub(/[^\n]/, " ")
+    end
+    private_class_method :blank
+  end
+end

data/lib/rails_ai_context/gem_lock.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "set"
 require_relative "safe_file"
 
 module RailsAiContext
@@ -13,6 +14,7 @@ module RailsAiContext
   module GemLock
     MAX_SIZE = 5 * 1024 * 1024
     SPEC_LINE = /\A {4}(\S+) \(([^)]+)\)\s*\z/
+    DEPENDENCY_LINE = /\A {2}(\S+?)!?(?: \(.*\))?\s*\z/
     RUBY_LINE = /\A\s+ruby (\S+)/
     GEMFILE_RUBY_LINE = /^\s*ruby\s+(["'])([^"']+)\1/
     PLAIN_VERSION = /\A\d+(?:\.\d+)*\S*\z/
@@ -20,11 +22,12 @@ module RailsAiContext
     class Spec
       attr_reader :ruby_version, :reason
 
-      def initialize(versions, ruby_version: nil, reason: nil, absent: false)
+      def initialize(versions, ruby_version: nil, reason: nil, absent: false, direct: nil)
         @versions = versions
         @ruby_version = ruby_version
         @reason = reason
         @absent = absent
+        @direct = direct || Set.new
       end
 
       # No lockfile, and a lockfile that named no gem, are both "the app's
@@ -49,6 +52,14 @@ module RailsAiContext
         @versions[name.to_s]
       end
 
+      # Named in the Gemfile, as opposed to resolved as some other gem's
+      # dependency. Every Rails app resolves minitest through activesupport,
+      # and reporting that as the app's test framework sent agents to a
+      # `test/` directory that does not exist.
+      def direct?(name)
+        @direct.include?(name.to_s)
+      end
+
       def any?(*names)
         names.flatten.any? { |name| present?(name) }
       end
@@ -99,12 +110,17 @@ module RailsAiContext
       return Spec.new({}, reason: "Gemfile.lock could not be read") unless content
 
       versions = {}
+      direct = Set.new
       ruby_version = nil
       in_specs = false
+      in_dependencies = false
       specs_section = false
       content.each_line do |line|
         if line.match?(/\A\S/)
           in_specs = false
+          in_dependencies = line.start_with?("DEPENDENCIES")
+        elsif in_dependencies && (match = line.match(DEPENDENCY_LINE))
+          direct << match[1]
         elsif line.strip == "specs:"
           in_specs = true
           specs_section = true
@@ -122,7 +138,7 @@ module RailsAiContext
       # and answering it as an app with no gems denies every gem it holds.
       return Spec.new({}, reason: "Gemfile.lock has no specs section") unless specs_section
 
-      Spec.new(versions, ruby_version: ruby_version || gemfile_ruby_version(gemfile))
+      Spec.new(versions, ruby_version: ruby_version || gemfile_ruby_version(gemfile), direct: direct)
     end
     private_class_method :parse
 

data/lib/rails_ai_context/hydrators/controller_hydrator.rb

@@ -14,8 +14,7 @@ module RailsAiContext
         model_names = detect_model_references(source_path)
         return HydrationResult.new if model_names.empty?
 
-        ModelHints.resolve(model_names, context: context,
-          describe: ->(name) { "Model '#{name}' referenced but not found in introspection data" })
+        ModelHints.resolve(model_names, context: context)
       rescue => e
         $stderr.puts "[rails-ai-context] ControllerHydrator failed: #{e.message}" if ENV["DEBUG"]
         HydrationResult.new

data/lib/rails_ai_context/hydrators/model_hints.rb

@@ -9,7 +9,10 @@ module RailsAiContext
     module ModelHints
       module_function
 
-      def resolve(names, context:, describe:)
+      # `describe` nil means a name that resolves to no model is simply not a
+      # model: a controller names services, serializers and plain constants,
+      # and every one of them read as a model the payload had lost.
+      def resolve(names, context:, describe: nil)
         max = RailsAiContext.configuration.hydration_max_hints
         hints = {}
         warnings = []
@@ -17,7 +20,7 @@ module RailsAiContext
           hint = SchemaHintBuilder.build(name, context: context)
           if hint
             hints[hint.model_name] ||= hint
-          else
+          elsif describe
             warnings << describe.call(name)
           end
         end

data/lib/rails_ai_context/install/program.rb

@@ -49,18 +49,40 @@ module RailsAiContext
         selected
       end
 
-      def select_tool_mode(surface)
+      # What this install writes. Answers 1 and 2 keep the meaning they have
+      # always had, so anything piping input into the installer still works.
+      Setup = Struct.new(:tool_mode, :context_files)
+
+      def select_setup(surface)
         surface.say ""
-        surface.say "Do you also want MCP server support?", :emph
+        surface.say "What should rails-ai-context write?", :emph
         surface.say ""
-        surface.say "  1. Yes - MCP primary + CLI fallback (generates per-tool MCP config files)"
-        surface.say "  2. No  - CLI only (no server needed)"
+        surface.say "  1. MCP config + context files   (default)"
+        surface.say "  2. Context files only           (CLI mode, no MCP server)"
+        surface.say "  3. MCP config only              (leaves CLAUDE.md, AGENTS.md and rules untouched)"
         surface.say ""
 
         input = surface.ask("Enter number (default: 1):").to_s.strip
-        mode = input == "2" ? :cli : :mcp
-        surface.say "Selected: #{mode == :mcp ? 'MCP + CLI fallback' : 'CLI only'}", :ok
-        mode
+        setup = case input
+        when "2" then Setup.new(:cli, true)
+        when "3" then Setup.new(:mcp, false)
+        else Setup.new(:mcp, true)
+        end
+        surface.say "Selected: #{setup_label(setup)}", :ok
+        setup
+      end
+
+      # The tool-mode half of the same question, for a caller that predates
+      # the setup struct. It cannot express "MCP config only", so every
+      # entry point in this gem calls `select_setup` instead.
+      def select_tool_mode(surface)
+        select_setup(surface).tool_mode
+      end
+
+      def setup_label(setup)
+        return "MCP config only (no context files)" unless setup.context_files
+
+        setup.tool_mode == :mcp ? "MCP + CLI fallback" : "CLI only"
       end
 
       # Offers to remove what a re-run dropped from the selection. `keeping:`
@@ -107,13 +129,15 @@ module RailsAiContext
         end
       end
 
-      def mark_gitignore(surface, root:)
+      # `context_files: false` never produces a .ai-context.json, so there is
+      # nothing to ignore.
+      def mark_gitignore(surface, root:, context_files: true)
         gitignore = File.join(root.to_s, ".gitignore")
         return unless File.exist?(gitignore)
 
         content = File.read(gitignore)
         lines = []
-        unless content.include?(".ai-context.json")
+        if context_files && !content.include?(".ai-context.json")
           lines << "" << "# rails-ai-context (JSON cache - markdown files should be committed)" << ".ai-context.json"
         end
         unless content.include?(".codex/config.toml")

data/lib/rails_ai_context/install/selection_record.rb

@@ -36,6 +36,10 @@ module RailsAiContext
 
       MODE_LINE = /^[ \t]*config\.tool_mode\s*=\s*:(\w+)/
 
+      # Only an uncommented assignment: the generated initializer ships the
+      # key commented out, and a comment is not a choice.
+      CONTEXT_FILES_LINE = /^[ \t]*config\.context_files\s*=\s*(true|false)/
+
       # Where a selection line goes when the initializer has none yet.
       CONFIGURE_BLOCK = /RailsAiContext\.configure do \|config\|\n/
 
@@ -56,6 +60,23 @@ module RailsAiContext
         mode_from_initializer(root) || mode_from_yaml(root)
       end
 
+      # Whether this install writes context files, initializer first, the
+      # same precedence the tools and the mode keep.
+      #
+      # @return [Boolean, nil] nil when nothing recorded it
+      def context_files(root:)
+        value = context_files_from_initializer(root)
+        return value unless value.nil?
+
+        context_files_from_yaml(root)
+      end
+
+      # @return [Symbol] :updated, :inserted, :unchanged or :absent
+      def write_context_files(value, root:)
+        write_config_line(root, "  config.context_files = #{value ? 'true' : 'false'}",
+                          CONTEXT_FILES_LINE, /^[ \t]*config\.context_files\s*=.*$/)
+      end
+
       # Rewrites (or inserts) the tool_mode line, the way `write` handles the
       # tools line. The rake task carried its own three-branch rewriter with a
       # duplicate of CONFIGURE_BLOCK; the file's shape belongs here. Only an
@@ -184,6 +205,57 @@ module RailsAiContext
         nil
       end
 
+      # One rewriter for the single-value keys this record owns, because the
+      # three branches (rewrite, insert beside the selection, insert into the
+      # configure block) are the file's shape, not the key's.
+      private_class_method def self.write_config_line(root, line, present, assignment)
+        path = File.join(root.to_s, INITIALIZER)
+        return :absent unless File.exist?(path)
+
+        content = File.read(path)
+        if content.match?(present)
+          updated = content.sub(assignment, line)
+          return :unchanged if updated == content
+
+          File.write(path, updated)
+          :updated
+        elsif content.match?(SELECTION_LINE)
+          File.write(path, content.sub(/^([ \t]*config\.ai_tools\s*=[^\n]*)$/) { "#{Regexp.last_match(1)}\n#{line}" })
+          :inserted
+        elsif content.match?(CONFIGURE_BLOCK)
+          File.write(path, content.sub(CONFIGURE_BLOCK) { "#{Regexp.last_match(0)}#{line}\n" })
+          :inserted
+        else
+          :absent
+        end
+      rescue StandardError => e
+        RailsAiContext.log_warn "[rails-ai-context] could not write #{INITIALIZER}: #{e.message}"
+        :unchanged
+      end
+
+      private_class_method def self.context_files_from_initializer(root)
+        path = File.join(root.to_s, INITIALIZER)
+        return nil unless File.exist?(path)
+
+        match = File.read(path)[CONTEXT_FILES_LINE, 1]
+        match.nil? ? nil : match == "true"
+      rescue StandardError => e
+        RailsAiContext.log_warn "[rails-ai-context] could not read #{INITIALIZER}: #{e.message}" if ENV["DEBUG"]
+        nil
+      end
+
+      private_class_method def self.context_files_from_yaml(root)
+        path = File.join(root.to_s, YAML_FILE)
+        return nil unless File.exist?(path)
+
+        data = YAML.safe_load_file(path, permitted_classes: PERMITTED_YAML) || {}
+        value = data["context_files"]
+        value.nil? ? nil : !!value
+      rescue StandardError => e
+        RailsAiContext.log_warn "[rails-ai-context] could not read #{YAML_FILE}: #{e.message}" if ENV["DEBUG"]
+        nil
+      end
+
       private_class_method def self.mode_from_initializer(root)
         path = File.join(root.to_s, INITIALIZER)
         return nil unless File.exist?(path)

data/lib/rails_ai_context/introspectors/active_support_introspector.rb

@@ -71,6 +71,15 @@ module RailsAiContext
             hits = ast[:concern_macros]
 
             entry = { name: mod_name, file: path.sub("#{root}/", "") }
+            # An app/models/concerns directory holds classes too - every
+            # validator in some apps - and a class is not a concern, let
+            # alone a "plain module".
+            declarations = DeclaredConstant.declarations(content)
+            declared = declarations.find { |d| d.name.split("::").last.casecmp?(mod_name) }
+            if declared
+              entry[:kind] = "class"
+              entry[:superclass] = declared.superclass
+            end
             entry[:uses_active_support_concern] = true if content.include?("ActiveSupport::Concern")
             entry[:included_blocks] = hits.count { |h| h[:macro] == :included }
             entry[:class_methods_block] = hits.any? { |h| h[:macro] == :class_methods }

data/lib/rails_ai_context/introspectors/api_introspector.rb

@@ -65,9 +65,30 @@ module RailsAiContext
           .map { |record| DeclaredConstant.resolve(record.source, record.path_name) }.uniq.sort
         result[:serializer_classes] = names if names.any?
 
+        # An app that keeps its own serializer layer somewhere else still has
+        # one, and "none detected" pushed an agent to add jbuilder or a second
+        # layer under app/serializers.
+        other = other_serializer_dirs
+        result[:serializer_dirs] = other if other.any?
+
         result
       end
 
+      # Any `serializers` directory under app/ other than app/serializers
+      # itself: `app/services/serializers/...` is the shape this missed.
+      def other_serializer_dirs
+        Dir.glob(File.join(root, "app", "**", "serializers"))
+          .select { |path| File.directory?(path) }
+          .map { |path| path.sub("#{root}/", "") }
+          .reject { |relative| relative == "app/serializers" }
+          .sort
+          .map { |relative| { path: relative, files: Dir.glob(File.join(root, relative, "**", "*.rb")).size } }
+          .reject { |entry| entry[:files].zero? }
+      rescue StandardError => e
+        $stderr.puts "[rails-ai-context] other_serializer_dirs failed: #{e.message}" if ENV["DEBUG"]
+        []
+      end
+
       def detect_graphql
         graphql_dir = File.join(root, "app/graphql")
         return nil unless Dir.exist?(graphql_dir)
@@ -103,25 +124,83 @@ module RailsAiContext
         []
       end
 
+      # Per `allow` block, because that is the unit rack-cors applies: one
+      # flat origin list read as though every origin reached every resource,
+      # and an environment branch read as though all of its arms were live at
+      # once.
       def detect_cors_config
         cors_path = File.join(root, "config/initializers/cors.rb")
         return nil unless File.exist?(cors_path)
 
-        ast_data = SourceIntrospector.walk(cors_path, {
-          origins: -> { Listeners::GenericMacroListener.new(:origins) }
-        })
-
-        origin_calls = ast_data[:origins]
-        return nil if origin_calls.empty?
+        source = RailsAiContext::SafeFile.read(cors_path)
+        node = source && AstCache.parse_string(source)&.value
+        return nil unless node
 
-        origins = origin_calls.flat_map { |macro| macro[:values].flatten.map(&:to_s) }
+        allows = []
+        collect_allow_blocks(node, allows)
+        origins = allows.flat_map { |allow| allow[:origins].map { |o| o[:value] } }.uniq
+        return nil if origins.empty?
 
-        { file: "config/initializers/cors.rb", origins: origins }
+        { file: "config/initializers/cors.rb", origins: origins, allows: allows }
       rescue => e
         $stderr.puts "[rails-ai-context] detect_cors_config failed: #{e.message}" if ENV["DEBUG"]
         nil
       end
 
+      def collect_allow_blocks(node, found)
+        return unless node.is_a?(Prism::Node)
+
+        if node.is_a?(Prism::CallNode) && node.name == :allow && node.block
+          entry = { origins: [], resources: [] }
+          collect_cors_calls(node.block, entry, nil)
+          found << entry if entry[:origins].any? || entry[:resources].any?
+          return
+        end
+
+        node.compact_child_nodes.each { |child| collect_allow_blocks(child, found) }
+      end
+
+      def collect_cors_calls(node, entry, condition)
+        return unless node.is_a?(Prism::Node)
+
+        case node
+        when Prism::IfNode
+          predicate = one_line_source(node.predicate)
+          collect_cors_calls(node.statements, entry, predicate)
+          collect_cors_calls(node.subsequent, entry, "else #{predicate}")
+          return
+        when Prism::UnlessNode
+          predicate = "not #{one_line_source(node.predicate)}"
+          collect_cors_calls(node.statements, entry, predicate)
+          collect_cors_calls(node.else_clause, entry, "else #{predicate}")
+          return
+        when Prism::CallNode
+          if node.receiver.nil? && %i[origins resource].include?(node.name)
+            values = Array(node.arguments&.arguments).flat_map { |arg| literal_strings(arg) }
+            if node.name == :origins
+              values.each { |value| entry[:origins] << { value: value, condition: condition }.compact }
+            else
+              entry[:resources] << values.first if values.first
+            end
+          end
+        end
+
+        node.compact_child_nodes.each { |child| collect_cors_calls(child, entry, condition) }
+      end
+
+      def literal_strings(node)
+        case node
+        when Prism::StringNode then [ node.unescaped ]
+        when Prism::SymbolNode then [ node.value.to_s ]
+        when Prism::ArrayNode  then node.elements.flat_map { |element| literal_strings(element) }
+        else []
+        end
+      end
+
+      def one_line_source(node)
+        node ? node.slice.gsub(/\s+/, " ").strip : nil
+      end
+
       def detect_api_client_generation
         package_path = File.join(root, "package.json")
         return [] unless File.exist?(package_path)

data/lib/rails_ai_context/introspectors/convention_introspector.rb

@@ -200,7 +200,10 @@ module RailsAiContext
           spec test
         ]
 
-        important_dirs.each_with_object({}) do |dir, hash|
+        # Plus whatever else the app keeps under app/. A fixed list left
+        # `app/workers` - 516 files on one app - out of the only section that
+        # carries file counts, so the biggest code area had no number anywhere.
+        (important_dirs | app_child_dirs).each_with_object({}) do |dir, hash|
           count = SourceScan.paths(root, kind: dir, skip_concerns: false).count
           count += Dir.glob(File.join(root, dir, "**/*.js")).size if dir.include?("javascript")
 
@@ -208,6 +211,19 @@ module RailsAiContext
         end
       end
 
+      def app_child_dirs
+        app_dir = File.join(root, "app")
+        return [] unless Dir.exist?(app_dir)
+
+        Dir.children(app_dir)
+          .select { |child| File.directory?(File.join(app_dir, child)) }
+          .map { |child| "app/#{child}" }
+          .sort
+      rescue StandardError => e
+        $stderr.puts "[rails-ai-context] app_child_dirs failed: #{e.message}" if ENV["DEBUG"]
+        []
+      end
+
       def detect_config_files
         configs = %w[
           config/database.yml config/credentials.yml.enc