rails-ai-context 5.30.2 → 5.32.0

data/lib/rails_ai_context/concern_membership.rb

@@ -14,6 +14,8 @@ module RailsAiContext
       include: %w[included append_features], prepend: %w[prepended prepend_features], extend: %w[extended]
     }.freeze
     MIXIN_HOOKS = HOOKS_BY_MACRO.values.flatten.freeze
+    # The macros that give the class a module's methods as class methods.
+    SINGLETON_MACROS = %i[extend singleton_include singleton_prepend].freeze
     # The block ActiveSupport::Concern runs for each.
     CONCERN_BLOCKS = { include: :included, prepend: :prepended }.freeze
     FRAMEWORK_PREFIXES = %w[
@@ -60,12 +62,30 @@ module RailsAiContext
 
     # Matched on the last segment: `module Edition; module Featurable` and
     # `module Edition::Featurable` both write one constant.
-    def own_mixins(mixins, name)
-      return Array(mixins) if Array(mixins).none? { |mixin| mixin.key?(:owner) }
+    # An edition module (`prepend_mod_with`) counts only where `root` holds its file.
+    def owned_by(records, name, root: nil)
+      return Array(records) if Array(records).none? { |record| record.key?(:owner) }
 
-      own = own_owner(mixins, name)
-      # `Other.include X` written in the body mixes into Other.
-      Array(mixins).select { |mixin| own && !mixin[:receiver] && Array(mixin[:owner]).join("::") == own }
+      own = own_owner(records, name)
+      Array(records).filter_map do |record|
+        next if record[:edition] && !(root && ConcernPaths.find_file(root.to_s, record[:name]))
+
+        if record[:receiver]
+          mixed_into(record, name)
+        elsif own && Array(record[:owner]).join("::") == own
+          record
+        end
+      end
+    end
+
+    # `Note.prepend X` mixes into Note as `prepend X` in its body would; `Other.include X` is Other's.
+    def mixed_into(record, name)
+      receiver = record[:receiver].to_s
+      target = receiver.start_with?("::") ? receiver.delete_prefix("::") : [ *Array(record[:owner]), receiver ].join("::")
+      return unless target == name.to_s
+
+      own = record.except(:receiver)
+      record.key?(:ancestor) ? own.merge(ancestor: CONCERN_BLOCKS.key?(record[:macro])) : own
     end
 
     def own_owner(records, name)

data/lib/rails_ai_context/concern_paths.rb

@@ -133,22 +133,48 @@ module RailsAiContext
     #   bare `include DebugConcern` inside Fasp::Provider resolves at runtime
     #   to Fasp::Provider::DebugConcern, which the literal spelling misses.
     # @param dirs [Array<String>, nil] pre-resolved concern directories
-    def find_file(root, concern_name, prefer: nil, within: nil, dirs: nil)
-      # Wherever Zeitwerk would look, plus an in-repo path gem's lib. A lib the app does
-      # not add to its autoload paths holds nothing it autoloads, so it is skipped.
-      dirs = ordered_dirs(root, prefer, dirs) + PathResolver.app_roots(root) + PathResolver.declared_roots(root) +
-             PathResolver.path_gem_libs(root)
-
-      candidate_names(concern_name, within).each do |name|
-        underscore = name.underscore
-        next if underscore.empty? || underscore.include?("..")
-
-        found = dirs.find { |dir| file_exist?(dir, "#{underscore}.rb") }
-        path = found && File.join(found, "#{underscore}.rb")
-        return path if path
+    # @param outer [Boolean] whether a module with no file of its own is found in its outer constant's file
+    def find_file(root, concern_name, prefer: nil, within: nil, dirs: nil, outer: true)
+      found = find_named(root, concern_name, prefer: prefer, within: within, dirs: dirs)
+      (found || (outer_named(root, concern_name, within: within, dirs: dirs) if outer))&.last
+    end
+
+    # The source of the module a reference resolves to: its file, or its own node in its outer constant's file.
+    def module_source(root, concern_name, prefer: nil, within: nil)
+      path = find_file(root, concern_name, prefer: prefer, within: within, outer: false)
+      return SafeFile.read(path) if path
+
+      name, path = outer_named(root, concern_name, within: within)
+      path && Introspectors::DeclaredConstant.module_node(AstCache.parse(path).value, name)&.slice
+    end
+
+    # [`Outer::Inner`, Outer's file] for a module with no file of its own, which Zeitwerk loads with Outer.
+    def outer_named(root, concern_name, within: nil, dirs: nil)
+      RunCache.fetch([ :outer_named, root, concern_name, within, dirs ]) do
+        candidate_names(concern_name, within).lazy.filter_map do |name|
+          outer = name.rpartition("::").first
+          path = !outer.empty? && find_file(root, outer, dirs: dirs)
+          [ name, path ] if path && Introspectors::DeclaredConstant.module_node(AstCache.parse(path).value, name)
+        end.first
       end
+    end
+
+    # [the constant the reference resolves to, its file] for `find_file`'s file, or nil.
+    def find_named(root, concern_name, prefer: nil, within: nil, dirs: nil)
+      # Every model asks for the same few names, each across hundreds of directories.
+      RunCache.fetch([ :find_named, root, concern_name, prefer, within, dirs ]) do
+        # Wherever Zeitwerk would look, plus an in-repo path gem's lib. A lib the app does
+        # not add to its autoload paths holds nothing it autoloads, so it is skipped.
+        searched = ordered_dirs(root, prefer, dirs) + PathResolver.app_roots(root) + PathResolver.declared_roots(root) +
+                   PathResolver.path_gem_libs(root)
+        candidate_names(concern_name, within).lazy.filter_map do |name|
+          underscore = name.underscore
+          next if underscore.empty? || underscore.include?("..")
 
-      nil
+          found = searched.find { |dir| file_exist?(dir, "#{underscore}.rb") }
+          [ name, File.join(found, "#{underscore}.rb") ] if found
+        end.first
+      end
     end
 
     # Each directory is listed once per run and a candidate is walked down
@@ -166,9 +192,28 @@ module RailsAiContext
       end
       RunCache.fetch([ :exist, current ]) { File.exist?(current) }
     end
+    private_class_method :file_exist?
+
+    # `relative` as the disk spells it: an app acronym underscores `ActivityPub` to `activitypub`,
+    # where this process, which has none of the app's acronyms, writes `activity_pub`. Nil when absent.
+    def spelled(dir, relative)
+      return relative if file_exist?(dir, relative)
+
+      current = dir
+      segments = relative.split("/").map do |segment|
+        found = listing(current).squashed[segment.delete("_")] or return nil
+        current = File.join(current, found)
+        found
+      end
+      RunCache.fetch([ :exist, current ]) { File.exist?(current) } ? segments.join("/") : nil
+    end
 
     Listing = Struct.new(:names, :folded) do
       def include?(name) = names.include?(name)
+
+      def squashed
+        @squashed ||= names.each_with_object({}) { |name, found| found[name.delete("_")] ||= name }
+      end
     end
 
     def listing(dir)
@@ -189,7 +234,6 @@ module RailsAiContext
       File.identical?(File.join(dir, name), File.join(dir, name.swapcase))
     end
     private_class_method :case_insensitive?
-    private_class_method :file_exist?
 
     def ordered_dirs(root, prefer, dirs = nil)
       dirs ||= resolve(root)
@@ -201,10 +245,12 @@ module RailsAiContext
     # The enclosing namespaces from the innermost outward, then the reference
     # itself - Ruby's own constant lookup order, which reaches the top level
     # last. Bare-name-first would bind Fasp::Provider's `include DebugConcern`
-    # to a top-level DebugConcern the runtime never sees.
+    # to a top-level DebugConcern the runtime never sees. A qualified name's
+    # first segment is looked up the same way; only a leading `::` skips it.
     def candidate_names(concern_name, within)
       name = concern_name.to_s
-      return [ name ] if within.nil? || name.include?("::")
+      return [ name.delete_prefix("::") ] if name.start_with?("::")
+      return [ name ] if within.nil?
 
       scopes = within.to_s.split("::")
       scopes.size.downto(1).map { |n| "#{scopes.first(n).join('::')}::#{name}" } + [ name ]

data/lib/rails_ai_context/config_yaml.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "date"
+require "yaml"
+
+module RailsAiContext
+  # An app's config YAML read without running its ERB: string keys, and a failure
+  # logged under the caller's label and answered as nil.
+  module ConfigYaml
+    ERB_OUTPUT = "RAC_ERB_OUTPUT"
+
+    module_function
+
+    # With `marker` an output tag reads as that marker, which marked? finds; without it, as empty.
+    def read(root, file, label:, marker: nil)
+      content = SafePath.read(file, under: root.to_s).first or return nil
+      content = marker ? ErbSource.with_output_marked(content, marker) : ErbSource.without_tags(content)
+      stringify_keys(YAML.safe_load(content, aliases: true, permitted_classes: [ Symbol, Date, Time ]))
+    rescue StandardError, ScriptError => e
+      RailsAiContext.debug_fail(e, nil, label: "#{label} #{file}")
+    end
+
+    def marked?(value)
+      value.is_a?(String) && value.include?(ERB_OUTPUT)
+    end
+
+    # Each output tag reads as a numbered marker; shown, every one is `<%= ... %>` again.
+    def shown(text)
+      text.to_s.gsub(/#{ERB_OUTPUT}(?:_\d+_)?/o, "<%= ... %>")
+    end
+
+    def stringify_keys(value)
+      case value
+      when Hash then value.to_h { |key, inner| [ key.to_s.delete_prefix(":"), stringify_keys(inner) ] }
+      when Array then value.map { |inner| stringify_keys(inner) }
+      else value
+      end
+    end
+  end
+end

data/lib/rails_ai_context/configuration.rb

@@ -362,7 +362,7 @@ module RailsAiContext
     attr_accessor :concern_paths          # Where to look for concern source files (default: nil, discovers app/*/concerns)
 
     # Frontend framework detection (optional overrides - auto-detected if nil)
-    attr_accessor :frontend_paths         # User-declared frontend dirs (e.g. ["app/frontend", "../web-client"])
+    attr_accessor :frontend_paths         # User-declared frontend dirs (e.g. ["app/frontend", "../web-client"]; one outside the app root is read for manifests only)
 
     # Additional app-root-relative directories that also contain Rails app
     # code (e.g. ["src", "vendor/internal"]). Code discovery scans each
@@ -387,8 +387,8 @@ module RailsAiContext
       @server_name         = "rails-ai-context"
       @introspectors       = PRESETS[:full].dup
       @excluded_paths      = %w[node_modules tmp log vendor .git doc docs]
-      # Files each tool's own docs say to gitignore. The patterns leave the placeholder
-      # beside one (config/application.example.yml, .env.example) readable.
+      # Files each tool's own docs say to gitignore. A placeholder beside one
+      # (config/application.example.yml, .env.example) stays readable: see SafePath.sensitive?.
       @sensitive_patterns  = %w[
         .env .env.* *.env .envrc
         config/master.key

data/lib/rails_ai_context/data/docs/index.json

@@ -119,6 +119,7 @@
     "id": "active_record_encryption",
     "title": "Active Record Encryption",
     "source": "rails",
+    "since": "7.0",
     "summary": "Encrypt model attributes at rest with deterministic and non-deterministic encryption",
     "keywords": [
       "encryption",
@@ -502,6 +503,329 @@
     ],
     "category": "api"
   },
+  {
+    "id": "action_controller_advanced_topics",
+    "title": "Action Controller Advanced Topics",
+    "source": "rails",
+    "since": "8.0",
+    "summary": "CSRF protection, HTTP authentication, streaming, log parameter filtering, rescue_from, health check endpoint",
+    "keywords": [
+      "csrf",
+      "http authentication",
+      "streaming",
+      "send_data",
+      "filter parameters",
+      "rescue_from",
+      "health check"
+    ],
+    "category": "controllers"
+  },
+  {
+    "id": "active_model_basics",
+    "title": "Active Model Basics",
+    "source": "rails",
+    "summary": "Active Model modules for plain Ruby objects: attributes, validations, callbacks, serialization, naming",
+    "keywords": [
+      "active model",
+      "activemodel",
+      "plain ruby object",
+      "form object",
+      "attributes",
+      "serialization"
+    ],
+    "category": "models"
+  },
+  {
+    "id": "active_record_composite_primary_keys",
+    "title": "Composite Primary Keys",
+    "source": "rails",
+    "since": "7.1",
+    "summary": "Tables, queries, associations, forms and fixtures with composite primary keys",
+    "keywords": [
+      "composite primary key",
+      "primary_key",
+      "query_constraints",
+      "multi-column key"
+    ],
+    "category": "models"
+  },
+  {
+    "id": "active_record_postgresql",
+    "title": "Active Record and PostgreSQL",
+    "source": "rails",
+    "summary": "PostgreSQL datatypes, UUID keys, deferrable foreign keys, exclusion constraints, full text search, views",
+    "keywords": [
+      "postgresql",
+      "postgres",
+      "jsonb",
+      "uuid",
+      "array",
+      "full text search",
+      "exclusion constraint",
+      "database views"
+    ],
+    "category": "models"
+  },
+  {
+    "id": "active_support_core_extensions",
+    "title": "Active Support Core Extensions",
+    "source": "rails",
+    "summary": "Ruby language extensions Active Support adds: blank?, present?, try, String, Hash, Array, Date and Time helpers",
+    "keywords": [
+      "core extensions",
+      "core_ext",
+      "blank?",
+      "present?",
+      "try",
+      "string",
+      "hash",
+      "time"
+    ],
+    "category": "core"
+  },
+  {
+    "id": "active_support_instrumentation",
+    "title": "Active Support Instrumentation",
+    "source": "rails",
+    "summary": "ActiveSupport::Notifications: subscribing to hooks, the framework's instrumentation events, custom instrumentation",
+    "keywords": [
+      "instrumentation",
+      "notifications",
+      "subscribe",
+      "instrument",
+      "events",
+      "activesupport::notifications"
+    ],
+    "category": "core"
+  },
+  {
+    "id": "autoloading_and_reloading_constants",
+    "title": "Autoloading and Reloading Constants",
+    "source": "rails",
+    "summary": "Zeitwerk autoloading, reloading and eager loading, autoload paths, project structure, STI",
+    "keywords": [
+      "autoloading",
+      "autoload",
+      "zeitwerk",
+      "reloading",
+      "eager loading",
+      "autoload_paths",
+      "constants"
+    ],
+    "category": "core"
+  },
+  {
+    "id": "debugging_rails_applications",
+    "title": "Debugging Rails Applications",
+    "source": "rails",
+    "summary": "Debug helpers, the logger, the debug gem, breakpoints, stack traces, SQL query sources",
+    "keywords": [
+      "debugging",
+      "debug",
+      "debugger",
+      "logger",
+      "breakpoint",
+      "stack trace",
+      "byebug"
+    ],
+    "category": "core"
+  },
+  {
+    "id": "engines",
+    "title": "Getting Started with Engines",
+    "source": "rails",
+    "summary": "Generating and mounting engines, isolated namespaces, overriding engine code, load hooks",
+    "keywords": [
+      "engine",
+      "engines",
+      "mountable",
+      "isolate_namespace",
+      "mount",
+      "railtie"
+    ],
+    "category": "core"
+  },
+  {
+    "id": "error_reporting",
+    "title": "Error Reporting in Rails Applications",
+    "source": "rails",
+    "since": "7.1",
+    "summary": "Rails.error reporter: handle, record, report, and custom error subscribers",
+    "keywords": [
+      "error reporting",
+      "error reporter",
+      "rails.error",
+      "exceptions",
+      "subscriber",
+      "error tracking"
+    ],
+    "category": "core"
+  },
+  {
+    "id": "generators",
+    "title": "Rails Generators & Templates",
+    "source": "rails",
+    "summary": "Listing, creating and customizing generators, overriding scaffold templates, application templates",
+    "keywords": [
+      "generators",
+      "generator",
+      "rails generate",
+      "templates",
+      "scaffold templates",
+      "application template"
+    ],
+    "category": "core"
+  },
+  {
+    "id": "getting_started_with_devcontainer",
+    "title": "Getting Started with Dev Containers",
+    "source": "rails",
+    "since": "7.2",
+    "summary": "rails-new and running a Rails app inside a development container",
+    "keywords": [
+      "devcontainer",
+      "dev container",
+      "docker",
+      "rails-new",
+      "development environment"
+    ],
+    "category": "core"
+  },
+  {
+    "id": "initialization",
+    "title": "The Rails Initialization Process",
+    "source": "rails",
+    "summary": "The boot sequence: bin/rails, config/boot.rb, config/application.rb, Rails::Server",
+    "keywords": [
+      "initialization",
+      "boot",
+      "boot process",
+      "startup",
+      "rails server",
+      "config/application.rb"
+    ],
+    "category": "core"
+  },
+  {
+    "id": "plugins",
+    "title": "The Basics of Creating Rails Plugins",
+    "source": "rails",
+    "summary": "Creating a plugin gem, extending core classes, adding methods to ApplicationRecord, publishing",
+    "keywords": [
+      "plugins",
+      "plugin",
+      "gem",
+      "extend",
+      "acts_as"
+    ],
+    "category": "core"
+  },
+  {
+    "id": "product_reviews",
+    "title": "Product Reviews",
+    "source": "rails",
+    "since": "8.1",
+    "summary": "Getting Started tutorial series: collecting reviews, average ratings, filtering reviews",
+    "keywords": [
+      "reviews",
+      "ratings",
+      "tutorial",
+      "e-commerce"
+    ],
+    "category": "core"
+  },
+  {
+    "id": "rails_on_rack",
+    "title": "Rails on Rack",
+    "source": "rails",
+    "summary": "Rack, the middleware stack, configuring middleware, Rails as a Rack application",
+    "keywords": [
+      "rack",
+      "middleware",
+      "middleware stack",
+      "config.ru",
+      "rack app"
+    ],
+    "category": "core"
+  },
+  {
+    "id": "sign_up_and_settings",
+    "title": "Sign Up and Settings",
+    "source": "rails",
+    "since": "8.1",
+    "summary": "Getting Started tutorial series: user sign up, rate limiting, nested layouts, admin and user controllers",
+    "keywords": [
+      "sign up",
+      "signup",
+      "registration",
+      "settings",
+      "rate_limit",
+      "tutorial"
+    ],
+    "category": "core"
+  },
+  {
+    "id": "threading_and_code_execution",
+    "title": "Threading and Code Execution in Rails",
+    "source": "rails",
+    "summary": "Concurrency in Rails, the executor and reloader, wrapping application code, load interlock",
+    "keywords": [
+      "threading",
+      "threads",
+      "concurrency",
+      "executor",
+      "reloader",
+      "load interlock"
+    ],
+    "category": "core"
+  },
+  {
+    "id": "tuning_performance_for_deployment",
+    "title": "Tuning Performance for Deployment",
+    "source": "rails",
+    "since": "7.2",
+    "summary": "Puma workers and threads, YJIT, memory allocators, performance testing for production",
+    "keywords": [
+      "performance",
+      "puma",
+      "tuning",
+      "workers",
+      "threads",
+      "yjit",
+      "deployment"
+    ],
+    "category": "core"
+  },
+  {
+    "id": "upgrading_ruby_on_rails",
+    "title": "Upgrading Ruby on Rails",
+    "source": "rails",
+    "summary": "Steps and per-version changes when upgrading an app to a newer Rails",
+    "keywords": [
+      "upgrading",
+      "upgrade",
+      "rails update",
+      "new framework defaults",
+      "deprecations",
+      "migration path"
+    ],
+    "category": "core"
+  },
+  {
+    "id": "wishlists",
+    "title": "Wishlists",
+    "source": "rails",
+    "since": "8.1",
+    "summary": "Getting Started tutorial series: wishlists, counter caches, friendly URLs, filtering records",
+    "keywords": [
+      "wishlists",
+      "counter cache",
+      "friendly urls",
+      "to_param",
+      "tutorial"
+    ],
+    "category": "core"
+  },
   {
     "id": "turbo_handbook_introduction",
     "title": "Turbo Handbook: Introduction",