rails-ai-context 5.30.2 → 5.32.0

data/lib/rails_ai_context/introspectors/listeners/constructor_macro_listener.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Introspectors
+    module Listeners
+      # Class-body macros that define a constructor: T::Struct's const/prop,
+      # Dry::Struct's attribute, dry-initializer's param/option and the
+      # attr_extras initializers. Each record carries the parameters the macro
+      # adds, as [kind, name, default source], and the class it is written in.
+      # Whether the macro is that library's is the consumer's call: `attribute`
+      # is also ActiveModel's.
+      class ConstructorMacroListener < GenericMacroListener
+        include OwnerScope
+
+        STRUCT_MACROS = %i[const prop attribute attribute?].freeze
+        DRY_INITIALIZER_MACROS = %i[param option].freeze
+        ATTR_EXTRAS_MACROS = %i[
+          attr_initialize pattr_initialize vattr_initialize rattr_initialize aattr_initialize
+          attr_private_initialize attr_value_initialize attr_reader_initialize attr_accessor_initialize
+          method_object static_facade
+        ].freeze
+
+        def initialize
+          super(STRUCT_MACROS + DRY_INITIALIZER_MACROS + ATTR_EXTRAS_MACROS + %i[extend])
+        end
+
+        def on_call_node_enter(node)
+          count = @results.size
+          super
+          @results[count..].each do |record|
+            record[:owner] = @owner_stack.dup
+            record[:source] = one_line_source(node)
+            record[:params] = params_for(node)
+          end
+        end
+
+        private
+
+        def params_for(node)
+          args = Array(node.arguments&.arguments)
+          case node.name
+          when :const, :prop then struct_param(args, extract_keyword_nodes(node))
+          when :attribute, :attribute? then dry_struct_param(node.name, args)
+          when :param, :option then dry_initializer_param(node.name, args, extract_keyword_nodes(node))
+          when :extend then []
+          else attr_extras_params(node.name == :static_facade ? args.drop(1) : args)
+          end
+        end
+
+        # A T::Struct prop is optional with a default, a factory, or a nilable type.
+        def struct_param(args, options)
+          name = literal_string(args.first) or return []
+          default = options[:default] || options[:factory]
+          return [ [ :key, name, default_text(default) ] ] if default
+          return [ [ :key, name, "nil" ] ] if args[1] && !args[1].is_a?(Prism::KeywordHashNode) && args[1].slice.start_with?("T.nilable(")
+
+          [ [ :keyreq, name, nil ] ]
+        end
+
+        def dry_struct_param(macro, args)
+          name = literal_string(args.first) or return []
+          return [ [ :key, name, "nil" ] ] if macro == :attribute?
+
+          default = type_default(args[1])
+          default ? [ [ :key, name, default ] ] : [ [ :keyreq, name, nil ] ]
+        end
+
+        # `Types::String.default("USD")`, anywhere in the type's call chain.
+        def type_default(node)
+          while node.is_a?(Prism::CallNode)
+            return default_text(node.arguments&.arguments&.first) || "..." if node.name == :default
+
+            node = node.receiver
+          end
+          nil
+        end
+
+        def dry_initializer_param(macro, args, options)
+          name = literal_string(args.first) or return []
+          default = (default_text(options[:default]) if options[:default]) ||
+                    ("nil" if options[:optional].is_a?(Prism::TrueNode))
+          positional = macro == :param
+          kind = positional ? (default ? :opt : :req) : (default ? :key : :keyreq)
+          [ [ kind, name, default ] ]
+        end
+
+        # Symbols are positional; an array holds keywords, `name!` required.
+        def attr_extras_params(args)
+          args.flat_map do |arg|
+            if arg.is_a?(Prism::ArrayNode)
+              arg.elements.flat_map { |element| attr_extras_keywords(element) }
+            else
+              name = literal_string(arg)
+              name ? [ [ :req, name, nil ] ] : []
+            end
+          end
+        end
+
+        def attr_extras_keywords(element)
+          if element.is_a?(Prism::KeywordHashNode) || element.is_a?(Prism::HashNode)
+            return element.elements.grep(Prism::AssocNode).filter_map do |assoc|
+              key = literal_string(assoc.key)
+              [ :key, key, assoc.value.slice ] if key
+            end
+          end
+
+          name = literal_string(element) or return []
+          name.end_with?("!") ? [ [ :keyreq, name.delete_suffix("!"), nil ] ] : [ [ :key, name, "nil" ] ]
+        end
+
+        # A lambda default reads as the value it returns.
+        def default_text(node)
+          return nil unless node
+
+          body = node.body if node.is_a?(Prism::LambdaNode)
+          body = node.block.body if node.is_a?(Prism::CallNode) && %i[lambda proc].include?(node.name) && node.block.is_a?(Prism::BlockNode)
+          statements = body.is_a?(Prism::StatementsNode) ? body.body : []
+          statements.size == 1 ? statements.first.slice : node.slice
+        end
+      end
+    end
+  end
+end

data/lib/rails_ai_context/introspectors/listeners/definition_file_paths_listener.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Introspectors
+    module Listeners
+      # Where a test helper points factory_bot, literal paths only:
+      #
+      #   FactoryBot.definition_file_paths = %w[custom/factories]  → { replace: true, paths: ["custom/factories"] }
+      #   FactoryBot.definition_file_paths << "lib/factories"      → { replace: false, paths: ["lib/factories"] }
+      #   FactoryBot.find_definitions / FactoryBot.reload           → { load: :find_definitions } / { load: :reload }
+      #
+      # The path forms are LiteralPaths'; a write with any path it cannot read records `unread: true`.
+      class DefinitionFilePathsListener < BaseListener
+        include LiteralPaths
+
+        LOADS = %i[find_definitions reload].freeze
+
+        def initialize(file: nil)
+          super()
+          @file = file
+        end
+
+        def on_call_node_enter(node)
+          if LOADS.include?(node.name) && factory_bot?(node.receiver)
+            @results << { load: node.name }
+          elsif node.name == :definition_file_paths= && factory_bot?(node.receiver)
+            record(true) { collect_arguments(node) }
+          elsif APPENDING.include?(node.name) && setting?(node.receiver)
+            record(false) { collect_arguments(node) }
+          end
+        end
+
+        def on_call_operator_write_node_enter(node)
+          return unless node.read_name == :definition_file_paths && node.binary_operator == :+ && factory_bot?(node.receiver)
+
+          record(false) { collect_paths(node.value) }
+        end
+
+        private
+
+        def collect_arguments(node)
+          Array(node.arguments&.arguments).map { |argument| collect_paths(argument) }.all?
+        end
+
+        def record(replace)
+          before = @results.size
+          read = yield
+          entry = { replace: replace, paths: @results.slice!(before..) }
+          @results << (read ? entry : entry.merge(unread: true))
+        end
+
+        def setting?(node)
+          node.is_a?(Prism::CallNode) && node.name == :definition_file_paths && factory_bot?(node.receiver)
+        end
+
+        def factory_bot?(node)
+          case node
+          when Prism::ConstantReadNode then node.name == :FactoryBot
+          when Prism::ConstantPathNode then node.parent.nil? && node.name == :FactoryBot
+          else false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails_ai_context/introspectors/listeners/enums_listener.rb

@@ -59,7 +59,7 @@ module RailsAiContext
 
             @results << {
               name:       key.to_s,
-              values:     enum_values(assoc.value),
+              values:     normalize_enum_values(enum_values(assoc.value)),
               options:    options,
               location:   node.location.start_line,
               confidence: confidence_for(node)
@@ -104,7 +104,7 @@ module RailsAiContext
         end
 
         def enum_modifier_key?(key)
-          %i[prefix suffix _prefix _suffix default scopes].include?(key)
+          %i[prefix suffix _prefix _suffix default _default scopes _scopes].include?(key)
         end
       end
     end

data/lib/rails_ai_context/introspectors/listeners/env_access_listener.rb

@@ -7,6 +7,7 @@ module RailsAiContext
       # ENV["KEY"], ENV.fetch("KEY"), ENV.fetch("KEY", "default")
       class EnvAccessListener < BaseListener
         def on_call_node_enter(node)
+          return extract_creds(node) if creds_receiver?(node.receiver)
           return unless env_receiver?(node.receiver)
 
           case node.name
@@ -19,6 +20,36 @@ module RailsAiContext
 
         private
 
+        # Rails 8.2's `Rails.app.creds` checks ENV before the encrypted
+        # credentials, and `Rails.app.envs` reads only ENV.
+        def creds_receiver?(receiver)
+          return false unless receiver.is_a?(Prism::CallNode) && %i[creds envs].include?(receiver.name)
+
+          app = receiver.receiver
+          app.is_a?(Prism::CallNode) && %i[app application].include?(app.name) &&
+            app.receiver.is_a?(Prism::ConstantReadNode) && app.receiver.name == :Rails
+        end
+
+        # `require(:database, :host)` reads ENV["DATABASE__HOST"].
+        def extract_creds(node)
+          return unless %i[require option].include?(node.name)
+
+          args = node.arguments&.arguments || []
+          parts = args.reject { |arg| arg.is_a?(Prism::KeywordHashNode) }
+          keys = parts.map { |arg| literal_string(arg) }
+          return if keys.empty? || keys.any?(&:nil?)
+
+          default = extract_keyword_nodes(node)[:default]
+          optional = node.name == :option
+          @results << {
+            method:      optional && default.nil? ? "[]" : "fetch",
+            key:         keys.map(&:upcase).join("__"),
+            has_default: !default.nil?,
+            default:     literal_value(default),
+            location:    node.location.start_line
+          }
+        end
+
         def env_receiver?(receiver)
           receiver.is_a?(Prism::ConstantReadNode) && receiver.name == :ENV
         end

data/lib/rails_ai_context/introspectors/listeners/filter_macro_listener.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Introspectors
+    module Listeners
+      # ConditionalMacroListener plus `callbacks`: what each positional argument of a filter macro
+      # adds, named at the node as the booted tier names the callback it reflects.
+      class FilterMacroListener < ConditionalMacroListener
+        def on_call_node_enter(node)
+          count = @results.size
+          super
+          @results.last[:callbacks] = callbacks(node) if @results.size > count
+        end
+
+        private
+
+        # [:name, "x"] for a symbol, string or class; [:object, "Klass"] for an instance;
+        # [:lambda] for `-> {}` or `lambda {}`, [:block] for a proc; [:unread, source] for anything else.
+        def callbacks(node)
+          Array(node.arguments&.arguments).reject { |arg| arg.is_a?(Prism::KeywordHashNode) }.map do |arg|
+            if (text = literal_string(arg)) then [ :name, text ]
+            elsif proc_argument?(arg) then [ arg.is_a?(Prism::LambdaNode) || arg.name == :lambda ? :lambda : :block ]
+            elsif (const = constant_name(arg)) then [ :name, const ]
+            elsif (klass = object_name(arg)) then [ :object, klass ]
+            else [ :unread, one_line_source(arg) ]
+            end
+          end
+        end
+
+        # The class the booted tier names an object filter by: `Class` for an anonymous class,
+        # an instance's nearest named class (`Class.new(Base) {}.new` is Base's, `Class.new {}.new` Object's).
+        def object_name(node)
+          return nil unless node.is_a?(Prism::CallNode) && node.name == :new && node.receiver
+          return "Class" if %w[Class Struct].include?(constant_name(node.receiver))
+
+          named_class(node.receiver)
+        end
+
+        def named_class(node)
+          return constant_name(node) unless node.is_a?(Prism::CallNode) && node.name == :new
+
+          case constant_name(node.receiver)
+          when "Class" then (superclass = node.arguments&.arguments&.first) ? named_class(superclass) : "Object"
+          when "Struct" then "Struct"
+          end
+        end
+
+        def constant_name(node)
+          constant_path_string(node) if node.is_a?(Prism::ConstantReadNode) || node.is_a?(Prism::ConstantPathNode)
+        end
+      end
+    end
+  end
+end

data/lib/rails_ai_context/introspectors/listeners/fixture_paths_listener.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Introspectors
+    module Listeners
+      # Fixture directories a test helper sets, literal paths only:
+      #
+      #   config.fixture_paths = [Rails.root.join("spec/fixtures")]
+      #   self.fixture_paths << "#{Rails.root}/test/fixtures/"
+      #   self.fixture_path = "#{::Rails.root}/spec/fixtures"
+      #   ActiveSupport::TestCase.fixture_paths << File.expand_path("../extra_fx", __dir__)
+      #
+      # A path built from __dir__ or __FILE__ is read only when the walk is given the helper's
+      # `file`, relative to the app root.
+      # The path forms are LiteralPaths'. A write with any path it cannot read records :unread,
+      # so a caller still knows the setting is set.
+      class FixturePathsListener < BaseListener
+        include LiteralPaths
+
+        SETTINGS = %i[fixture_paths fixture_path].to_set.freeze
+        ASSIGNING = %i[fixture_paths= fixture_path=].to_set.freeze
+
+        def initialize(file: nil)
+          super()
+          @file = file
+        end
+
+        def on_call_node_enter(node)
+          if ASSIGNING.include?(node.name)
+            return unless setting_receiver?(node.receiver)
+          else
+            return unless APPENDING.include?(node.name) && fixture_setting?(node.receiver)
+          end
+
+          record_write { Array(node.arguments&.arguments).map { |argument| collect_paths(argument) }.all? }
+        end
+
+        def on_call_operator_write_node_enter(node)
+          return unless SETTINGS.include?(node.read_name) && node.binary_operator == :+ && setting_receiver?(node.receiver)
+
+          record_write { collect_paths(node.value) }
+        end
+
+        private
+
+        def record_write
+          @results << :unread unless yield
+        end
+
+        def fixture_setting?(node)
+          node.is_a?(Prism::CallNode) && SETTINGS.include?(node.name) && setting_receiver?(node.receiver)
+        end
+
+        # The test case class itself, named or as self, or RSpec's `config` (the block parameter `RSpec.configure` yields).
+        def setting_receiver?(node)
+          node.nil? || node.is_a?(Prism::SelfNode) || node.is_a?(Prism::ConstantReadNode) || node.is_a?(Prism::ConstantPathNode) ||
+            ((node.is_a?(Prism::CallNode) || node.is_a?(Prism::LocalVariableReadNode)) && node.name == :config)
+        end
+      end
+    end
+  end
+end

data/lib/rails_ai_context/introspectors/listeners/gemfile_dsl_listener.rb

@@ -6,6 +6,7 @@ module RailsAiContext
       # Detects Gemfile DSL patterns via Prism AST:
       # gem "name", "version", options...
       # group :development, :test do ... end
+      # ruby "3.3.6", and an :unknown_gems entry for each call that adds gems the file does not name.
       class GemfileDslListener < BaseListener
         def initialize
           super
@@ -20,6 +21,12 @@ module RailsAiContext
             extract_gem(node)
           when :source
             extract_source(node)
+          when :eval_gemfile
+            extract_eval_gemfile(node)
+          when :ruby
+            extract_ruby(node)
+          when :gemspec
+            unknown_gems(node)
           when :group
             return unless node.block
 
@@ -47,7 +54,7 @@ module RailsAiContext
           return if args.empty?
 
           name_arg = args.first
-          return unless name_arg.is_a?(Prism::StringNode)
+          return unknown_gems(node) unless name_arg.is_a?(Prism::StringNode)
 
           name = name_arg.unescaped
           version = nil
@@ -78,6 +85,40 @@ module RailsAiContext
           }
         end
 
+        # `eval_gemfile "Gemfile.local"`, or `File.expand_path("x", __dir__)`;
+        # Bundler reads the path from the evaluating file's directory.
+        def extract_eval_gemfile(node)
+          arg = node.arguments&.arguments&.first
+          if arg.is_a?(Prism::CallNode) && arg.name == :expand_path && file_constant?(arg.receiver)
+            inner = arg.arguments&.arguments || []
+            arg = inner.first if inner.size == 2 && dir_call?(inner.last)
+          end
+          return unknown_gems(node) unless arg.is_a?(Prism::StringNode)
+
+          @results << {
+            type:     :eval_gemfile,
+            path:     arg.unescaped,
+            groups:   @current_groups.flatten.uniq,
+            location: node.location.start_line
+          }
+        end
+
+        # Bundler takes `engine:` and `engine_version:` beside the version.
+        def extract_ruby(node)
+          options = extract_keyword_nodes(node)
+          @results << {
+            type:           :ruby,
+            version:        literal_string(node.arguments&.arguments&.first),
+            engine:         literal_string(options[:engine]),
+            engine_version: literal_string(options[:engine_version]),
+            location:       node.location.start_line
+          }
+        end
+
+        def unknown_gems(node)
+          @results << { type: :unknown_gems, call: node.name, location: node.location.start_line }
+        end
+
         def extract_source(node)
           args = node.arguments&.arguments || []
           url_arg = args.first

data/lib/rails_ai_context/introspectors/listeners/generic_macro_listener.rb

@@ -4,14 +4,18 @@ module RailsAiContext
   module Introspectors
     module Listeners
       class GenericMacroListener < BaseListener
-        def initialize(*target_methods)
+        # `any_receiver` also counts `base.macro`, the shape a mixin's `self.included(base)` hook writes.
+        def initialize(*target_methods, block_source: [], call_source: [], any_receiver: false)
           super()
+          @any_receiver = any_receiver
           @target_methods = target_methods.flatten.map(&:to_sym).to_set
           @enclosing = []
+          @block_source = block_source.to_set
+          @call_source = call_source.to_set
         end
 
         def on_call_node_enter(node)
-          return unless node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)
+          return unless @any_receiver || node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)
           return unless @target_methods.include?(node.name)
 
           @results << {
@@ -21,6 +25,9 @@ module RailsAiContext
             options:       extract_keyword_options(node),
             option_values: extract_keyword_sources(node),
             option_nodes:  extract_keyword_nodes(node),
+            block:         (one_line_source(node.block) if node.block.is_a?(Prism::BlockNode) && @block_source.include?(node.name)),
+            # Where a block or a lambda argument opens: the line Proc#source_location gives.
+            proc_lines:    proc_lines(node),
             # Offsets, not line numbers: a one-line block puts the parent and
             # its nested calls on one line, and a consumer pairing them by
             # line then attaches the second child to the first.
@@ -30,6 +37,9 @@ module RailsAiContext
             location:      node.location.start_line,
             confidence:    confidence_for(node)
           }
+          @results.last[:text] = one_line_source(node) if @call_source.include?(node.name)
+          condition = macro_condition
+          @results.last[:condition] = condition if condition
 
           # A target macro that takes a block encloses whatever the block
           # declares: `string :title` inside `hash :order_params do ... end`
@@ -40,6 +50,22 @@ module RailsAiContext
         def on_call_node_leave(node)
           @enclosing.pop if @enclosing.last.equal?(node)
         end
+
+        private
+
+        def macro_condition; end
+
+        # A def evaluates to its name, which is what `helper_method def foo` passes.
+        def extract_symbol_args(node)
+          Array(node.arguments&.arguments).filter_map { |arg| arg.is_a?(Prism::DefNode) ? arg.name : literal_string(arg)&.to_sym }
+        end
+
+        # A call's line is where it opens, as Proc#source_location gives it.
+        def proc_lines(node)
+          procs = Array(node.arguments&.arguments).select { |arg| proc_argument?(arg) }
+          procs << node.block if node.block.is_a?(Prism::BlockNode)
+          procs.map { |found| found.location.start_line }
+        end
       end
     end
   end

data/lib/rails_ai_context/introspectors/listeners/grape_api_listener.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Introspectors
+    module Listeners
+      # What a Grape API class body declares: its superclass, version and
+      # prefix, each endpoint with the namespaces around it and the params
+      # block before it, and the APIs it mounts. Whether a class is a Grape API
+      # is the consumer's call, since a superclass can be another API class.
+      class GrapeApiListener < BaseListener
+        VERBS = %i[get post put patch delete head options query].freeze
+        NAMESPACES = %i[namespace group resource resources segment route_param].freeze
+        PARAMS = %i[requires optional].freeze
+
+        def initialize
+          super
+          @scopes = [ nil ]
+          @blocks = []
+          @pending = []
+        end
+
+        def on_class_node_enter(node)
+          name = scope_name(node)
+          superclass = node.superclass && (node.superclass.is_a?(Prism::ConstantReadNode) || node.superclass.is_a?(Prism::ConstantPathNode)) ? constant_path_string(node.superclass) : nil
+          @results << { kind: :class, owner: name, superclass: superclass }
+          @scopes.push(name)
+        end
+
+        def on_class_node_leave(_node)
+          @scopes.pop
+        end
+
+        def on_module_node_enter(node)
+          @scopes.push(scope_name(node))
+        end
+
+        def on_module_node_leave(_node)
+          @scopes.pop
+        end
+
+        def on_call_node_enter(node)
+          frame = frame_for(node)
+          @blocks.push(frame) if node.block.is_a?(Prism::BlockNode)
+        end
+
+        def on_call_node_leave(node)
+          return unless node.block.is_a?(Prism::BlockNode)
+
+          @pending = [] if @blocks.pop.first == :namespace
+        end
+
+        private
+
+        # Records what the call declares and returns the frame its block opens.
+        def frame_for(node)
+          owner = @scopes.last
+          return [ :body ] if owner.nil? || node.receiver || in_endpoint?
+
+          args = Array(node.arguments&.arguments)
+          case node.name
+          when *VERBS
+            @results << { kind: :endpoint, owner: owner, verb: node.name.to_s.upcase, path: literal_string(args.first) || "",
+                          namespace: namespace, params: inherited_params + @pending }
+            @pending = []
+            [ :endpoint ]
+          when *NAMESPACES
+            space = literal_string(args.first)
+            if node.name == :route_param && space
+              type = keyword(node, :type)
+              @pending += [ { name: space, type: type, required: true } ] if type
+              space = ":#{space}"
+            end
+            # Grape declares these on the setting the namespace inherits, so every endpoint inside gets them.
+            params, @pending = @pending, []
+            [ :namespace, space, params ]
+          when :params
+            [ :params ]
+          when *PARAMS
+            if @blocks.last&.first == :params
+              type = keyword(node, :type)
+              args.filter_map { |arg| literal_string(arg) }.each do |name|
+                @pending << { name: name, type: type, required: node.name == :requires }
+              end
+            end
+            [ :body ]
+          when :version, :prefix
+            value = literal_string(args.first)
+            @results << { kind: node.name, owner: owner, value: value, using: keyword(node, :using) || "path" } if value
+            [ :body ]
+          when :mount
+            mounts(args).each { |target, path| @results << { kind: :mount, owner: owner, target: target, path: path, namespace: namespace } }
+            [ :body ]
+          else
+            [ :body ]
+          end
+        end
+
+        def in_endpoint?
+          @blocks.any? { |frame| frame.first == :endpoint }
+        end
+
+        def namespace
+          @blocks.filter_map { |kind, space| space if kind == :namespace }
+        end
+
+        def inherited_params
+          @blocks.flat_map { |kind, _, params| kind == :namespace ? params : [] }
+        end
+
+        def keyword(node, key)
+          value = extract_keyword_nodes(node)[key]
+          value && (literal_string(value) || value.slice)
+        end
+
+        # `mount V1::Users`, `mount V1::Users => "/v1"` and the braced form.
+        def mounts(args)
+          args.flat_map do |arg|
+            case arg
+            when Prism::ConstantReadNode, Prism::ConstantPathNode then [ [ constant_path_string(arg), "/" ] ]
+            when Prism::KeywordHashNode, Prism::HashNode
+              arg.elements.grep(Prism::AssocNode).filter_map do |assoc|
+                next unless assoc.key.is_a?(Prism::ConstantReadNode) || assoc.key.is_a?(Prism::ConstantPathNode)
+
+                [ constant_path_string(assoc.key), literal_string(assoc.value) || "/" ]
+              end
+            else []
+            end
+          end
+        end
+
+        def scope_name(node)
+          nested_name(node.constant_path, @scopes.last)
+        end
+      end
+    end
+  end
+end