rails-ai-context 0.1.0

data/lib/rails_ai_context/introspectors/convention_detector.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Introspectors
+    # Detects high-level Rails conventions and patterns in use,
+    # giving AI assistants critical context about the app's architecture.
+    class ConventionDetector
+      attr_reader :app
+
+      def initialize(app)
+        @app = app
+      end
+
+      # @return [Hash] detected conventions and patterns
+      def call
+        {
+          architecture: detect_architecture,
+          patterns: detect_patterns,
+          directory_structure: scan_directory_structure,
+          config_files: detect_config_files
+        }
+      end
+
+      private
+
+      def root
+        app.root.to_s
+      end
+
+      def detect_architecture
+        arch = []
+        arch << "api_only" if app.config.api_only
+        arch << "hotwire" if dir_exists?("app/javascript/controllers") || gem_present?("turbo-rails")
+        arch << "graphql" if dir_exists?("app/graphql")
+        arch << "grape_api" if dir_exists?("app/api")
+        arch << "service_objects" if dir_exists?("app/services")
+        arch << "form_objects" if dir_exists?("app/forms")
+        arch << "query_objects" if dir_exists?("app/queries")
+        arch << "presenters" if dir_exists?("app/presenters") || dir_exists?("app/decorators")
+        arch << "view_components" if dir_exists?("app/components")
+        arch << "stimulus" if dir_exists?("app/javascript/controllers")
+        arch << "importmaps" if file_exists?("config/importmap.rb")
+        arch << "docker" if file_exists?("Dockerfile") || file_exists?("docker-compose.yml")
+        arch << "kamal" if file_exists?("config/deploy.yml")
+        arch << "ci_github_actions" if dir_exists?(".github/workflows")
+        arch
+      end
+
+      def detect_patterns
+        patterns = []
+
+        # Check for common Rails patterns in model files
+        model_dir = File.join(root, "app/models")
+        if Dir.exist?(model_dir)
+          model_files = Dir.glob(File.join(model_dir, "**/*.rb"))
+          content = model_files.first(50).map { |f| File.read(f) rescue "" }.join("\n")
+
+          patterns << "sti" if content.match?(/self\.inheritance_column|type.*string/)
+          patterns << "polymorphic" if content.match?(/polymorphic:\s*true/)
+          patterns << "soft_delete" if content.match?(/acts_as_paranoid|discard|deleted_at/)
+          patterns << "versioning" if content.match?(/has_paper_trail|audited/)
+          patterns << "state_machine" if content.match?(/aasm|state_machine|workflow/)
+          patterns << "multi_tenancy" if content.match?(/acts_as_tenant|apartment/)
+          patterns << "searchable" if content.match?(/searchkick|pg_search|ransack/)
+          patterns << "taggable" if content.match?(/acts_as_taggable/)
+          patterns << "sluggable" if content.match?(/friendly_id|sluggable/)
+          patterns << "nested_set" if content.match?(/acts_as_nested_set|ancestry|closure_tree/)
+        end
+
+        patterns
+      end
+
+      def scan_directory_structure
+        important_dirs = %w[
+          app/models app/controllers app/views app/jobs
+          app/mailers app/channels app/services app/forms
+          app/queries app/presenters app/decorators
+          app/components app/graphql app/api
+          app/javascript/controllers
+          config/initializers db/migrate
+          spec test
+        ]
+
+        important_dirs.each_with_object({}) do |dir, hash|
+          full_path = File.join(root, dir)
+          next unless Dir.exist?(full_path)
+
+          count = Dir.glob(File.join(full_path, "**/*.rb")).size
+          count += Dir.glob(File.join(full_path, "**/*.js")).size if dir.include?("javascript")
+
+          hash[dir] = count if count > 0
+        end
+      end
+
+      def detect_config_files
+        configs = %w[
+          config/database.yml config/credentials.yml.enc
+          config/cable.yml config/storage.yml
+          config/sidekiq.yml config/deploy.yml
+          config/importmap.rb config/tailwind.config.js
+          Procfile Procfile.dev
+          .rubocop.yml .rspec
+          Dockerfile docker-compose.yml
+          .github/workflows/ci.yml
+        ]
+
+        configs.select { |f| file_exists?(f) }
+      end
+
+      def dir_exists?(relative_path)
+        Dir.exist?(File.join(root, relative_path))
+      end
+
+      def file_exists?(relative_path)
+        File.exist?(File.join(root, relative_path))
+      end
+
+      def gem_present?(name)
+        lock_path = File.join(root, "Gemfile.lock")
+        return false unless File.exist?(lock_path)
+        File.read(lock_path).include?("    #{name} (")
+      end
+    end
+  end
+end

data/lib/rails_ai_context/introspectors/gem_introspector.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Introspectors
+    # Analyzes Gemfile.lock to identify installed gems and
+    # map them to known patterns/frameworks the AI should know about.
+    class GemIntrospector
+      attr_reader :app
+
+      # Known gems that significantly affect how the app works.
+      # The AI needs to know about these to give accurate advice.
+      NOTABLE_GEMS = {
+        # Auth
+        "devise"          => { category: :auth, note: "Authentication via Devise. Check User model for devise modules." },
+        "omniauth"        => { category: :auth, note: "OAuth integration via OmniAuth." },
+        "pundit"          => { category: :auth, note: "Authorization via Pundit policies in app/policies/." },
+        "cancancan"       => { category: :auth, note: "Authorization via CanCanCan abilities." },
+        "rodauth-rails"   => { category: :auth, note: "Authentication via Rodauth." },
+
+        # Background jobs
+        "sidekiq"         => { category: :jobs, note: "Background jobs via Sidekiq. Check config/sidekiq.yml." },
+        "good_job"        => { category: :jobs, note: "Background jobs via GoodJob (Postgres-backed)." },
+        "solid_queue"     => { category: :jobs, note: "Background jobs via SolidQueue (Rails 8 default)." },
+        "delayed_job"     => { category: :jobs, note: "Background jobs via DelayedJob." },
+
+        # Frontend
+        "turbo-rails"     => { category: :frontend, note: "Hotwire Turbo for SPA-like navigation. Check Turbo Streams and Frames." },
+        "stimulus-rails"  => { category: :frontend, note: "Stimulus.js controllers in app/javascript/controllers/." },
+        "importmap-rails" => { category: :frontend, note: "Import maps for JS (no bundler). Check config/importmap.rb." },
+        "jsbundling-rails" => { category: :frontend, note: "JS bundling (esbuild/webpack/rollup). Check package.json." },
+        "cssbundling-rails" => { category: :frontend, note: "CSS bundling. Check package.json for Tailwind/PostCSS/etc." },
+        "tailwindcss-rails" => { category: :frontend, note: "Tailwind CSS integration." },
+        "react-rails"     => { category: :frontend, note: "React components in Rails views." },
+        "inertia_rails"   => { category: :frontend, note: "Inertia.js for SPA with Rails backend." },
+
+        # API
+        "grape"           => { category: :api, note: "API framework via Grape. Check app/api/." },
+        "graphql"         => { category: :api, note: "GraphQL API. Check app/graphql/ for types and mutations." },
+        "jsonapi-serializer" => { category: :api, note: "JSON:API serialization." },
+        "jbuilder"        => { category: :api, note: "JSON views via Jbuilder templates." },
+
+        # Database
+        "pg"              => { category: :database, note: "PostgreSQL adapter." },
+        "mysql2"          => { category: :database, note: "MySQL adapter." },
+        "sqlite3"         => { category: :database, note: "SQLite adapter." },
+        "redis"           => { category: :database, note: "Redis client. Used for caching/sessions/Action Cable." },
+        "solid_cache"     => { category: :database, note: "Database-backed cache (Rails 8)." },
+        "solid_cable"     => { category: :database, note: "Database-backed Action Cable (Rails 8)." },
+
+        # File handling
+        "activestorage"   => { category: :files, note: "Active Storage for file uploads." },
+        "shrine"          => { category: :files, note: "File uploads via Shrine." },
+        "carrierwave"     => { category: :files, note: "File uploads via CarrierWave." },
+
+        # Testing
+        "rspec-rails"     => { category: :testing, note: "RSpec test framework. Tests in spec/." },
+        "minitest"        => { category: :testing, note: "Minitest framework. Tests in test/." },
+        "factory_bot_rails" => { category: :testing, note: "Test fixtures via FactoryBot in spec/factories/." },
+        "faker"           => { category: :testing, note: "Fake data generation for tests." },
+        "capybara"        => { category: :testing, note: "Integration/system tests with Capybara." },
+
+        # Deployment
+        "kamal"           => { category: :deploy, note: "Deployment via Kamal. Check config/deploy.yml." },
+        "capistrano"      => { category: :deploy, note: "Deployment via Capistrano. Check config/deploy/." }
+      }.freeze
+
+      def initialize(app)
+        @app = app
+      end
+
+      # @return [Hash] gem analysis
+      def call
+        lock_path = File.join(app.root, "Gemfile.lock")
+        return { error: "No Gemfile.lock found" } unless File.exist?(lock_path)
+
+        specs = parse_lockfile(lock_path)
+
+        {
+          total_gems: specs.size,
+          ruby_version: specs["ruby"]&.first,
+          notable_gems: detect_notable_gems(specs),
+          categories: categorize_gems(specs)
+        }
+      end
+
+      private
+
+      def parse_lockfile(path)
+        gems = {}
+        in_gems = false
+
+        File.readlines(path).each do |line|
+          if line.strip == "GEM"
+            in_gems = true
+            next
+          elsif line.strip.empty? || line.match?(/^\S/)
+            in_gems = false if in_gems && line.match?(/^\S/) && !line.strip.start_with?("remote:", "specs:")
+          end
+
+          if in_gems && (match = line.match(/^\s{4}(\S+)\s+\((.+)\)/))
+            gems[match[1]] = match[2]
+          end
+        end
+
+        gems
+      end
+
+      def detect_notable_gems(specs)
+        NOTABLE_GEMS.filter_map do |gem_name, info|
+          next unless specs.key?(gem_name)
+
+          {
+            name: gem_name,
+            version: specs[gem_name],
+            category: info[:category].to_s,
+            note: info[:note]
+          }
+        end
+      end
+
+      def categorize_gems(specs)
+        found = detect_notable_gems(specs)
+        found.group_by { |g| g[:category] }
+             .transform_values { |gems| gems.map { |g| g[:name] } }
+      end
+    end
+  end
+end

data/lib/rails_ai_context/introspectors/job_introspector.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Introspectors
+    # Discovers background jobs (ActiveJob/Sidekiq), mailers,
+    # and Action Cable channels.
+    class JobIntrospector
+      attr_reader :app
+
+      def initialize(app)
+        @app = app
+      end
+
+      # @return [Hash] async workers, mailers, and channels
+      def call
+        {
+          jobs: extract_jobs,
+          mailers: extract_mailers,
+          channels: extract_channels
+        }
+      end
+
+      private
+
+      def extract_jobs
+        return [] unless defined?(ActiveJob::Base)
+
+        ActiveJob::Base.descendants.filter_map do |job|
+          next if job.name.nil? || job.name == "ApplicationJob" ||
+                  job.name.start_with?("ActionMailer", "ActiveStorage::", "ActionMailbox::", "Turbo::", "Sentry::")
+
+          queue = job.queue_name
+          queue = queue.call rescue queue.to_s if queue.is_a?(Proc)
+
+          {
+            name: job.name,
+            queue: queue.to_s,
+            priority: job.priority
+          }.compact
+        end.sort_by { |j| j[:name] }
+      rescue
+        []
+      end
+
+      def extract_mailers
+        return [] unless defined?(ActionMailer::Base)
+
+        ActionMailer::Base.descendants.filter_map do |mailer|
+          next if mailer.name.nil?
+
+          actions = mailer.instance_methods(false).map(&:to_s).sort
+          next if actions.empty?
+
+          {
+            name: mailer.name,
+            actions: actions,
+            delivery_method: mailer.delivery_method.to_s
+          }
+        end.sort_by { |m| m[:name] }
+      rescue
+        []
+      end
+
+      def extract_channels
+        return [] unless defined?(ActionCable::Channel::Base)
+
+        ActionCable::Channel::Base.descendants.filter_map do |channel|
+          next if channel.name.nil? || channel.name == "ApplicationCable::Channel"
+
+          {
+            name: channel.name,
+            stream_methods: channel.instance_methods(false)
+              .select { |m| m.to_s.start_with?("stream_") || m == :subscribed }
+              .map(&:to_s)
+          }
+        end.sort_by { |c| c[:name] }
+      rescue
+        []
+      end
+    end
+  end
+end

data/lib/rails_ai_context/introspectors/model_introspector.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Introspectors
+    # Extracts ActiveRecord model metadata: associations, validations,
+    # scopes, enums, callbacks, and class-level configuration.
+    class ModelIntrospector
+      attr_reader :app, :config
+
+      EXCLUDED_CALLBACKS = %w[autosave_associated_records_for].freeze
+
+      def initialize(app)
+        @app    = app
+        @config = RailsAiContext.configuration
+      end
+
+      # @return [Hash] model metadata keyed by model name
+      def call
+        eager_load_models!
+        models = discover_models
+
+        models.each_with_object({}) do |model, hash|
+          hash[model.name] = extract_model_details(model)
+        rescue => e
+          hash[model.name] = { error: e.message }
+        end
+      end
+
+      private
+
+      def eager_load_models!
+        Rails.application.eager_load! unless Rails.application.config.eager_load
+      rescue
+        # In some environments (CI, Claude Code) eager_load may partially fail
+        nil
+      end
+
+      def discover_models
+        return [] unless defined?(ActiveRecord::Base)
+
+        ActiveRecord::Base.descendants.reject do |model|
+          model.abstract_class? ||
+            model.name.nil? ||
+            config.excluded_models.include?(model.name)
+        end.sort_by(&:name)
+      end
+
+      def extract_model_details(model)
+        {
+          table_name: model.table_name,
+          associations: extract_associations(model),
+          validations: extract_validations(model),
+          scopes: extract_scopes(model),
+          enums: extract_enums(model),
+          callbacks: extract_callbacks(model),
+          concerns: extract_concerns(model),
+          class_methods: extract_public_class_methods(model),
+          instance_methods: extract_public_instance_methods(model)
+        }.compact
+      end
+
+      def extract_associations(model)
+        model.reflect_on_all_associations.map do |assoc|
+          detail = {
+            name: assoc.name.to_s,
+            type: assoc.macro.to_s, # :has_many, :belongs_to, :has_one, :has_and_belongs_to_many
+            class_name: assoc.class_name,
+            foreign_key: assoc.foreign_key.to_s
+          }
+          detail[:through]    = assoc.options[:through].to_s if assoc.options[:through]
+          detail[:polymorphic] = true if assoc.options[:polymorphic]
+          detail[:dependent]  = assoc.options[:dependent].to_s if assoc.options[:dependent]
+          detail[:optional]   = assoc.options[:optional] if assoc.options.key?(:optional)
+          detail.compact
+        end
+      end
+
+      def extract_validations(model)
+        model.validators.map do |validator|
+          {
+            kind: validator.kind.to_s,
+            attributes: validator.attributes.map(&:to_s),
+            options: sanitize_options(validator.options)
+          }
+        end
+      end
+
+      def extract_scopes(model)
+        model.defined_enums.keys # Enums create scopes too, but we track those separately
+        # Get actual named scopes
+        if model.respond_to?(:scope_names)
+          model.scope_names.map(&:to_s)
+        else
+          # Fallback: check for scope definitions via reflection
+          model.methods.grep(/^_scope_/).map { |m| m.to_s.sub("_scope_", "") }
+        end
+      rescue
+        []
+      end
+
+      def extract_enums(model)
+        return {} unless model.respond_to?(:defined_enums)
+
+        model.defined_enums.transform_values do |mapping|
+          mapping.keys
+        end
+      end
+
+      def extract_callbacks(model)
+        callback_types = %i[
+          before_validation after_validation
+          before_save after_save
+          before_create after_create
+          before_update after_update
+          before_destroy after_destroy
+          after_commit after_rollback
+        ]
+
+        callback_types.each_with_object({}) do |type, hash|
+          callbacks = model.send(:"_#{type}_callbacks").reject do |cb|
+            cb.filter.to_s.start_with?(*EXCLUDED_CALLBACKS) || cb.filter.is_a?(Proc)
+          end
+
+          next if callbacks.empty?
+
+          hash[type.to_s] = callbacks.map { |cb| cb.filter.to_s }
+        end
+      rescue
+        {}
+      end
+
+      def extract_concerns(model)
+        model.ancestors
+          .select { |mod| mod.is_a?(Module) && !mod.is_a?(Class) }
+          .reject { |mod| mod.name&.start_with?("ActiveRecord", "ActiveModel", "ActiveSupport") }
+          .map(&:name)
+          .compact
+      end
+
+      def extract_public_class_methods(model)
+        (model.methods - ActiveRecord::Base.methods - Object.methods)
+          .reject { |m| m.to_s.start_with?("_", "autosave") }
+          .sort
+          .first(30) # Cap to avoid noise
+          .map(&:to_s)
+      end
+
+      def extract_public_instance_methods(model)
+        (model.instance_methods - ActiveRecord::Base.instance_methods - Object.instance_methods)
+          .reject { |m| m.to_s.start_with?("_", "autosave", "validate_associated") }
+          .sort
+          .first(30)
+          .map(&:to_s)
+      end
+
+      def sanitize_options(options)
+        # Remove procs and complex objects that don't serialize well
+        options.reject { |_k, v| v.is_a?(Proc) || v.is_a?(Regexp) }
+               .transform_values(&:to_s)
+      end
+    end
+  end
+end

data/lib/rails_ai_context/introspectors/route_introspector.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Introspectors
+    # Extracts route information from the Rails router including
+    # HTTP verb, path, controller#action, and route constraints.
+    class RouteIntrospector
+      attr_reader :app
+
+      def initialize(app)
+        @app = app
+      end
+
+      # @return [Hash] routes grouped by controller
+      def call
+        routes = extract_routes
+
+        {
+          total_routes: routes.size,
+          by_controller: group_by_controller(routes),
+          api_namespaces: detect_api_namespaces(routes),
+          mounted_engines: detect_mounted_engines
+        }
+      end
+
+      private
+
+      def extract_routes
+        app.routes.routes.filter_map do |route|
+          next if route.internal? # Skip Rails internal routes
+          next if route.defaults[:controller].blank?
+
+          {
+            verb: route.verb.presence || "ANY",
+            path: route.path.spec.to_s.gsub("(.:format)", ""),
+            controller: route.defaults[:controller],
+            action: route.defaults[:action],
+            name: route.name,
+            constraints: extract_constraints(route)
+          }.compact
+        end
+      end
+
+      def extract_constraints(route)
+        constraints = route.constraints.to_s
+        constraints.empty? ? nil : constraints
+      rescue
+        nil
+      end
+
+      def group_by_controller(routes)
+        routes.group_by { |r| r[:controller] }.transform_values do |controller_routes|
+          controller_routes.map do |r|
+            { verb: r[:verb], path: r[:path], action: r[:action], name: r[:name] }.compact
+          end
+        end
+      end
+
+      def detect_api_namespaces(routes)
+        routes
+          .select { |r| r[:path].match?(%r{/api/}) }
+          .map { |r| r[:path].match(%r{(/api/v?\d*)})&.captures&.first }
+          .compact
+          .uniq
+      end
+
+      def detect_mounted_engines
+        app.routes.routes
+          .select { |r| r.app.respond_to?(:app) && r.app.app.is_a?(Class) }
+          .filter_map do |r|
+            engine_class = r.app.app
+            next unless engine_class < Rails::Engine
+            {
+              engine: engine_class.name,
+              path: r.path.spec.to_s
+            }
+          rescue
+            nil
+          end
+      end
+    end
+  end
+end