rails-ai-context 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f762c8f111cca6b60293f4d3eb26ef68aeb9e1d0c97048b46dcf221ebf7d6069
-  data.tar.gz: 01b9e656715c47aa0a3e67cfb75fb6ac1a5fd7d6444b4ac96837c6202a093487
+  metadata.gz: 6fa5518e88de666f981967ae1557990aadea0804c192511c4cbf204d6b45f146
+  data.tar.gz: e39c7430277939e504aa3056ac0ac85f9f347dd008ff907627a032d7607ad21f
 SHA512:
-  metadata.gz: a5daa689b56aeee3225f0bfa983580adeabbc195c2184b669f5a3689d1cd2760d115afefcc2c925e14eefafea2b28729893b260f141acd00f5e89a6bcb4fc665
-  data.tar.gz: 7fba10086525e15044867dc4c1b5c5a44fd8eaf5f66c08ffbbd6468dfb1f2831d5b03231ec3e0ca02e2fec2a30a4558cd5567262642edf92c750a4bd8286fdc4
+  metadata.gz: d1709f1becfbe976d7cd7a62690e90b31dbe5d61b2d09d9c9001ec43d0ce2d344d840d310d42d65ad9c1bf86bba2a0eb3285cb88eb074e131a373904224f7813
+  data.tar.gz: 04714a3b181c91844c27b7b64ad2c2e9db963a16ae5ee037721f01afd518bad151b4d60dee8df78a69638b0fbd87af2c18288b70d14c62a72e72bd44f23f0c2d

data/.rubocop.yml

@@ -1,5 +1,5 @@
-require:
-  - rubocop-rails-omakase
+inherit_gem:
+  rubocop-rails-omakase: rubocop.yml
 
 AllCops:
   TargetRubyVersion: 3.2

data/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-03-18
+
+### Added
+
+- **Cache invalidation** — TTL + file fingerprinting for MCP tool cache (replaces permanent `||=` cache)
+- **MCP Resources** — Static resources (`rails://schema`, `rails://routes`, `rails://conventions`, `rails://gems`) and resource template (`rails://models/{name}`)
+- **Per-assistant serializers** — Claude gets behavioral rules, Cursor/Windsurf get compact rules, Copilot gets task-oriented GFM
+- **Stimulus introspector** — Extracts Stimulus controller targets, values, and actions from JS/TS files
+- **Database stats introspector** — Opt-in PostgreSQL approximate row counts via `pg_stat_user_tables`
+- **Auto-mount HTTP middleware** — Rack middleware for MCP endpoint when `config.auto_mount = true`
+- **Diff-aware regeneration** — Context file generation skips unchanged files
+- **`rails ai:doctor`** — Diagnostic command with AI readiness score (0-100)
+- **`rails ai:watch`** — File watcher that auto-regenerates context files on change (requires `listen` gem)
+
+### Fixed
+
+- **Shell injection in SearchCode** — Replaced backtick execution with `Open3.capture2` array form; added file_type validation, max_results cap, and path traversal protection
+- **Scope extraction** — Fixed broken `model.methods.grep(/^_scope_/)` by parsing source files for `scope :name` declarations
+- **Route introspector** — Fixed `route.internal?` compatibility with Rails 8.1
+
+### Changed
+
+- `generate_context` now returns `{ written: [], skipped: [] }` instead of flat array
+- Default introspectors now include `:stimulus`
+
 ## [0.2.0] - 2026-03-18
 
 ### Added

data/CLAUDE.md

@@ -0,0 +1,47 @@
+# CLAUDE.md — rails-ai-context development guide
+
+This is a Ruby gem that auto-introspects Rails applications and exposes their
+structure to AI assistants via the Model Context Protocol (MCP).
+
+## Architecture
+
+- `lib/rails_ai_context.rb` — Main entry point, public API
+- `lib/rails_ai_context/introspector.rb` — Orchestrates sub-introspectors
+- `lib/rails_ai_context/introspectors/` — Individual introspectors (schema, models, routes, jobs, gems, conventions, stimulus, database_stats)
+- `lib/rails_ai_context/tools/` — MCP tools using the official mcp SDK
+- `lib/rails_ai_context/serializers/` — Output formatters (claude, rules, copilot, markdown, JSON)
+- `lib/rails_ai_context/resources.rb` — MCP resources (static data AI clients read directly)
+- `lib/rails_ai_context/server.rb` — MCP server configuration (stdio + HTTP transports)
+- `lib/rails_ai_context/middleware.rb` — Rack middleware for auto-mounting MCP HTTP endpoint
+- `lib/rails_ai_context/fingerprinter.rb` — SHA256 file fingerprinting for cache invalidation
+- `lib/rails_ai_context/doctor.rb` — Diagnostic checks and AI readiness scoring
+- `lib/rails_ai_context/watcher.rb` — File watcher for auto-regenerating context files
+- `lib/rails_ai_context/engine.rb` — Rails Engine for auto-integration
+
+## Key Design Decisions
+
+1. **Built on official mcp SDK** — not a custom protocol implementation
+2. **Zero-config** — Railtie auto-registers at boot, introspects without setup
+3. **Graceful degradation** — works without DB by parsing schema.rb as text
+4. **Read-only tools only** — all MCP tools are annotated as non-destructive
+5. **Dual output** — static files (CLAUDE.md) + live MCP server (stdio/HTTP)
+6. **Diff-aware** — context regeneration skips unchanged files
+7. **Per-assistant serializers** — each AI tool gets tailored output format
+
+## Testing
+
+```bash
+bundle exec rspec           # Run specs
+bundle exec rubocop         # Lint
+```
+
+Uses combustion gem for testing Rails engine behavior in isolation.
+
+## Conventions
+
+- Ruby 3.2+ features OK (pattern matching, etc.)
+- Follow rubocop-rails-omakase style
+- Every introspector returns a Hash, never raises (wraps errors in `{ error: msg }`)
+- MCP tools return `MCP::Tool::Response` objects per SDK convention
+- All tools prefixed with `rails_` per MCP naming best practices
+- `generate_context` returns `{ written: [], skipped: [] }` hash

data/README.md

@@ -26,12 +26,13 @@ bundle add rails-ai-context
 
 That's it. Now your AI assistant knows:
 
-- 📦 **Every table, column, index, and foreign key** in your database
-- 🏗️ **Every model** with its associations, validations, scopes, enums, and callbacks
-- 🛤️ **Every route** with HTTP verbs, paths, and controller actions
-- ⚡ **Every background job**, mailer, and Action Cable channel
-- 💎 **Every notable gem** and what it means (Devise → auth, Sidekiq → jobs, Turbo → Hotwire)
-- 🏛️ **Your architecture patterns**: service objects, STI, polymorphism, state machines, multi-tenancy
+- **Every table, column, index, and foreign key** in your database
+- **Every model** with its associations, validations, scopes, enums, and callbacks
+- **Every route** with HTTP verbs, paths, and controller actions
+- **Every background job**, mailer, and Action Cable channel
+- **Every notable gem** and what it means (Devise = auth, Sidekiq = jobs, Turbo = Hotwire)
+- **Your architecture patterns**: service objects, STI, polymorphism, state machines, multi-tenancy
+- **Stimulus controllers** with targets, values, and actions
 
 ---
 
@@ -51,12 +52,12 @@ rails ai:context
 ```
 
 This creates:
-- `CLAUDE.md` — for Claude Code
-- `.cursorrules` — for Cursor
-- `.windsurfrules` — for Windsurf
-- `.github/copilot-instructions.md` — for GitHub Copilot
+- `CLAUDE.md` — for Claude Code (with behavioral rules)
+- `.cursorrules` — for Cursor (compact rules format)
+- `.windsurfrules` — for Windsurf (compact rules format)
+- `.github/copilot-instructions.md` — for GitHub Copilot (task-oriented)
 
-**Commit these files.** Your entire team gets smarter AI assistance.
+Each file is tailored to the AI assistant's preferred format. **Commit these files.** Your entire team gets smarter AI assistance.
 
 ### 3. Start the MCP Server
 
@@ -97,6 +98,18 @@ The gem exposes 6 tools via MCP that AI clients can call:
 
 All tools are **read-only** — they never modify your application or database.
 
+## MCP Resources
+
+In addition to tools, the gem registers MCP resources that AI clients can read directly:
+
+| Resource | Description |
+|----------|-------------|
+| `rails://schema` | Full database schema (JSON) |
+| `rails://routes` | All routes (JSON) |
+| `rails://conventions` | Detected patterns and architecture (JSON) |
+| `rails://gems` | Notable gems with categories (JSON) |
+| `rails://models/{name}` | Per-model details (resource template) |
+
 ---
 
 ## How It Works
@@ -124,9 +137,10 @@ All tools are **read-only** — they never modify your application or database.
     (reads file)   any MCP client
 ```
 
-**Two modes:**
+**Three modes:**
 1. **Static files** (`rails ai:context`) — generates markdown files that AI tools read as project context. Zero runtime cost. Works everywhere.
 2. **MCP server** (`rails ai:serve`) — live introspection tools that AI clients call on-demand. Richer, always up-to-date.
+3. **Watch mode** (`rails ai:watch`) — auto-regenerates context files when your code changes.
 
 ---
 
@@ -145,20 +159,50 @@ RailsAiContext.configure do |config|
   config.auto_mount = true
   config.http_path  = "/mcp"
   config.http_port  = 6029
+
+  # Cache TTL for MCP tool responses (seconds)
+  config.cache_ttl = 30
+
+  # Enable Postgres row count stats (opt-in)
+  # config.introspectors += [:database_stats]
 end
 ```
 
 ---
 
+## Diagnostics
+
+Check your app's AI readiness:
+
+```bash
+rails ai:doctor
+```
+
+Reports pass/warn/fail for schema, models, routes, gems, context files, MCP server, and ripgrep. Includes fix suggestions and an AI readiness score (0-100).
+
+---
+
+## Stimulus Support
+
+The gem automatically detects Stimulus controllers and extracts:
+- Controller names (derived from filenames)
+- Static targets
+- Static values
+- Action methods
+
+This gives AI assistants context about your frontend JavaScript alongside your backend Ruby.
+
+---
+
 ## Supported AI Assistants
 
-| AI Assistant | Context File | Command |
-|--------------|-------------|---------|
-| Claude Code | `CLAUDE.md` | `rails ai:context:claude` |
-| Cursor | `.cursorrules` | `rails ai:context:cursor` |
-| Windsurf | `.windsurfrules` | `rails ai:context:windsurf` |
-| GitHub Copilot | `.github/copilot-instructions.md` | `rails ai:context:copilot` |
-| JSON (generic) | `.ai-context.json` | `rails ai:context:json` |
+| AI Assistant | Context File | Format | Command |
+|--------------|-------------|--------|---------|
+| Claude Code | `CLAUDE.md` | Verbose + behavioral rules | `rails ai:context:claude` |
+| Cursor | `.cursorrules` | Compact imperative rules | `rails ai:context:cursor` |
+| Windsurf | `.windsurfrules` | Compact imperative rules | `rails ai:context:windsurf` |
+| GitHub Copilot | `.github/copilot-instructions.md` | Task-oriented GFM | `rails ai:context:copilot` |
+| JSON (generic) | `.ai-context.json` | Structured JSON | `rails ai:context:json` |
 
 ---
 
@@ -166,7 +210,7 @@ end
 
 | Command | Description |
 |---------|-------------|
-| `rails ai:context` | Generate all context files (CLAUDE.md, .cursorrules, etc.) |
+| `rails ai:context` | Generate all context files (skips unchanged) |
 | `rails ai:context:claude` | Generate CLAUDE.md only |
 | `rails ai:context:cursor` | Generate .cursorrules only |
 | `rails ai:context:windsurf` | Generate .windsurfrules only |
@@ -175,6 +219,8 @@ end
 | `rails ai:serve` | Start MCP server (stdio, for Claude Code) |
 | `rails ai:serve_http` | Start MCP server (HTTP, for remote clients) |
 | `rails ai:inspect` | Print introspection summary to stdout |
+| `rails ai:doctor` | Run diagnostics and report AI readiness score |
+| `rails ai:watch` | Watch for changes and auto-regenerate context files |
 
 > **zsh users:** The bracket syntax `rails ai:context_for[claude]` requires quoting in zsh (`rails 'ai:context_for[claude]'`). The named tasks above (`rails ai:context:claude`) work without quoting in any shell.
 
@@ -196,6 +242,8 @@ The gem gracefully degrades when no database is connected — it parses `db/sche
 - Ruby >= 3.2
 - Rails >= 7.1
 - [mcp](https://github.com/modelcontextprotocol/ruby-sdk) (official MCP SDK, installed automatically)
+- Optional: `listen` gem for watch mode
+- Optional: `ripgrep` for fast code search (falls back to Ruby)
 
 ---
 
@@ -225,6 +273,10 @@ bundle exec rspec
 
 Bug reports and pull requests welcome at https://github.com/crisnahine/rails-ai-context.
 
+## Sponsorship
+
+If rails-ai-context helps your workflow, consider supporting the project — [become a monthly sponsor or buy me a coffee](https://github.com/sponsors/crisnahine).
+
 ## License
 
 [MIT License](LICENSE)

data/exe/rails-ai-context

@@ -28,8 +28,9 @@ module RailsAiContext
 
       format = options[:format].to_sym
       $stderr.puts "Introspecting Rails app..."
-      files = RailsAiContext.generate_context(format: format)
-      files.each { |f| $stderr.puts "  Written: #{f}" }
+      result = RailsAiContext.generate_context(format: format)
+      result[:written].each { |f| $stderr.puts "  Written: #{f}" }
+      result[:skipped].each { |f| $stderr.puts "  Skipped: #{f} (unchanged)" }
     end
 
     desc "inspect", "Print introspection summary"
@@ -42,6 +43,33 @@ module RailsAiContext
       puts JSON.pretty_generate(context)
     end
 
+    desc "watch", "Watch for changes and auto-regenerate context files"
+    def watch
+      boot_rails!
+      require "rails_ai_context"
+
+      RailsAiContext::Watcher.new.start
+    end
+
+    desc "doctor", "Run diagnostic checks and report AI readiness score"
+    def doctor
+      boot_rails!
+      require "rails_ai_context"
+
+      result = RailsAiContext::Doctor.new.run
+      result[:checks].each do |check|
+        icon = case check.status
+        when :pass then "PASS"
+        when :warn then "WARN"
+        when :fail then "FAIL"
+        end
+        $stderr.puts "  [#{icon}] #{check.name}: #{check.message}"
+        $stderr.puts "         Fix: #{check.fix}" if check.fix
+      end
+      $stderr.puts ""
+      $stderr.puts "AI Readiness Score: #{result[:score]}/100"
+    end
+
     desc "version", "Print version"
     def version
       require_relative "../rails_ai_context/version"

data/lib/rails_ai_context/configuration.rb

@@ -26,10 +26,13 @@ module RailsAiContext
     # Maximum depth for association traversal
     attr_accessor :max_association_depth
 
+    # TTL in seconds for cached introspection (default: 30)
+    attr_accessor :cache_ttl
+
     def initialize
       @server_name         = "rails-ai-context"
       @server_version      = RailsAiContext::VERSION
-      @introspectors       = %i[schema models routes jobs gems conventions]
+      @introspectors       = %i[schema models routes jobs gems conventions stimulus]
       @excluded_paths      = %w[node_modules tmp log vendor .git]
       @auto_mount          = false
       @http_path           = "/mcp"
@@ -43,6 +46,7 @@ module RailsAiContext
         ActionMailbox::InboundEmail ActionMailbox::Record
       ]
       @max_association_depth = 2
+      @cache_ttl            = 30
     end
 
     def output_dir_for(app)

data/lib/rails_ai_context/doctor.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  # Diagnostic checker that validates the environment and reports
+  # AI readiness with pass/warn/fail checks and a readiness score.
+  class Doctor
+    Check = Data.define(:name, :status, :message, :fix)
+
+    CHECKS = %i[
+      check_schema
+      check_models
+      check_routes
+      check_gems
+      check_context_files
+      check_mcp_buildable
+      check_ripgrep
+    ].freeze
+
+    attr_reader :app
+
+    def initialize(app = nil)
+      @app = app || Rails.application
+    end
+
+    def run
+      results = CHECKS.map { |check| send(check) }
+      score = compute_score(results)
+      { checks: results, score: score }
+    end
+
+    private
+
+    def check_schema
+      schema_path = File.join(app.root, "db/schema.rb")
+      if File.exist?(schema_path)
+        Check.new(name: "Schema", status: :pass, message: "db/schema.rb found", fix: nil)
+      else
+        Check.new(name: "Schema", status: :warn, message: "db/schema.rb not found", fix: "Run `rails db:schema:dump` to generate it")
+      end
+    end
+
+    def check_models
+      models_dir = File.join(app.root, "app/models")
+      if Dir.exist?(models_dir) && Dir.glob(File.join(models_dir, "**/*.rb")).any?
+        count = Dir.glob(File.join(models_dir, "**/*.rb")).size
+        Check.new(name: "Models", status: :pass, message: "#{count} model files found", fix: nil)
+      else
+        Check.new(name: "Models", status: :warn, message: "No model files found in app/models/", fix: "Generate models with `rails generate model`")
+      end
+    end
+
+    def check_routes
+      routes_path = File.join(app.root, "config/routes.rb")
+      if File.exist?(routes_path)
+        Check.new(name: "Routes", status: :pass, message: "config/routes.rb found", fix: nil)
+      else
+        Check.new(name: "Routes", status: :fail, message: "config/routes.rb not found", fix: "Ensure you're in a Rails app root directory")
+      end
+    end
+
+    def check_gems
+      lock_path = File.join(app.root, "Gemfile.lock")
+      if File.exist?(lock_path)
+        Check.new(name: "Gems", status: :pass, message: "Gemfile.lock found", fix: nil)
+      else
+        Check.new(name: "Gems", status: :warn, message: "Gemfile.lock not found", fix: "Run `bundle install` to generate it")
+      end
+    end
+
+    def check_context_files
+      claude_path = File.join(app.root, "CLAUDE.md")
+      if File.exist?(claude_path)
+        Check.new(name: "Context files", status: :pass, message: "CLAUDE.md exists", fix: nil)
+      else
+        Check.new(name: "Context files", status: :warn, message: "No context files generated yet", fix: "Run `rails ai:context` to generate them")
+      end
+    end
+
+    def check_mcp_buildable
+      Server.new(app).build
+      Check.new(name: "MCP server", status: :pass, message: "MCP server builds successfully", fix: nil)
+    rescue => e
+      Check.new(name: "MCP server", status: :fail, message: "MCP server failed to build: #{e.message}", fix: "Check mcp gem installation: `bundle info mcp`")
+    end
+
+    def check_ripgrep
+      if system("which rg > /dev/null 2>&1")
+        Check.new(name: "ripgrep", status: :pass, message: "rg available for code search", fix: nil)
+      else
+        Check.new(name: "ripgrep", status: :warn, message: "ripgrep not installed (code search will use slower Ruby fallback)", fix: "Install with `brew install ripgrep` or `apt install ripgrep`")
+      end
+    end
+
+    def compute_score(results)
+      total = results.size * 10
+      earned = results.sum do |check|
+        case check.status
+        when :pass then 10
+        when :warn then 5
+        else 0
+        end
+      end
+      ((earned.to_f / total) * 100).round
+    end
+  end
+end

data/lib/rails_ai_context/engine.rb

@@ -8,6 +8,14 @@ module RailsAiContext
       Rails.application.config.rails_ai_context = RailsAiContext.configuration
     end
 
+    # Auto-mount MCP HTTP middleware when configured
+    initializer "rails_ai_context.middleware" do |app|
+      if RailsAiContext.configuration.auto_mount
+        require_relative "middleware"
+        app.middleware.use RailsAiContext::Middleware
+      end
+    end
+
     # Register Rake tasks
     rake_tasks do
       load File.expand_path("tasks/rails_ai_context.rake", __dir__)

data/lib/rails_ai_context/fingerprinter.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module RailsAiContext
+  # Computes a SHA256 fingerprint of key application files to detect changes.
+  # Used by BaseTool to invalidate cached introspection when files change.
+  class Fingerprinter
+    WATCHED_FILES = %w[
+      db/schema.rb
+      config/routes.rb
+      Gemfile.lock
+    ].freeze
+
+    WATCHED_DIRS = %w[
+      app/models
+    ].freeze
+
+    class << self
+      def compute(app)
+        root = app.root.to_s
+        digest = Digest::SHA256.new
+
+        WATCHED_FILES.each do |file|
+          path = File.join(root, file)
+          digest.update(File.mtime(path).to_f.to_s) if File.exist?(path)
+        end
+
+        WATCHED_DIRS.each do |dir|
+          full_dir = File.join(root, dir)
+          next unless Dir.exist?(full_dir)
+
+          Dir.glob(File.join(full_dir, "**/*.rb")).sort.each do |path|
+            digest.update(File.mtime(path).to_f.to_s)
+          end
+        end
+
+        digest.hexdigest
+      end
+
+      def changed?(app, previous)
+        compute(app) != previous
+      end
+    end
+  end
+end

data/lib/rails_ai_context/introspector.rb

@@ -53,6 +53,8 @@ module RailsAiContext
       when :jobs        then Introspectors::JobIntrospector.new(app)
       when :gems        then Introspectors::GemIntrospector.new(app)
       when :conventions then Introspectors::ConventionDetector.new(app)
+      when :stimulus       then Introspectors::StimulusIntrospector.new(app)
+      when :database_stats then Introspectors::DatabaseStatsIntrospector.new(app)
       else
         raise ConfigurationError, "Unknown introspector: #{name}"
       end

data/lib/rails_ai_context/introspectors/database_stats_introspector.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Introspectors
+    # Collects approximate row counts from PostgreSQL's pg_stat_user_tables.
+    # Only activates for PostgreSQL adapter; returns { skipped: true } otherwise.
+    class DatabaseStatsIntrospector
+      attr_reader :app
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call
+        return { skipped: true, reason: "ActiveRecord not available" } unless defined?(ActiveRecord::Base)
+
+        adapter = ActiveRecord::Base.connection.adapter_name.downcase
+        unless adapter.include?("postgresql")
+          return { skipped: true, reason: "Only available for PostgreSQL (current: #{adapter})" }
+        end
+
+        rows = ActiveRecord::Base.connection.select_all(<<~SQL)
+          SELECT relname AS table_name,
+                 n_live_tup AS approximate_row_count
+          FROM pg_stat_user_tables
+          ORDER BY n_live_tup DESC
+        SQL
+
+        tables = rows.map do |row|
+          { table: row["table_name"], approximate_rows: row["approximate_row_count"].to_i }
+        end
+
+        { adapter: "postgresql", tables: tables, total_tables: tables.size }
+      rescue => e
+        { error: e.message }
+      end
+    end
+  end
+end

data/lib/rails_ai_context/introspectors/model_introspector.rb

@@ -86,18 +86,20 @@ module RailsAiContext
       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
+        source_path = model_source_path(model)
+        return [] unless source_path && File.exist?(source_path)
+
+        File.read(source_path).scan(/^\s*scope\s+:(\w+)/).flatten
       rescue
         []
       end
 
+      def model_source_path(model)
+        root = app.root.to_s
+        underscored = model.name.underscore
+        File.join(root, "app", "models", "#{underscored}.rb")
+      end
+
       def extract_enums(model)
         return {} unless model.respond_to?(:defined_enums)
 

data/lib/rails_ai_context/introspectors/route_introspector.rb

@@ -27,7 +27,7 @@ module RailsAiContext
 
       def extract_routes
         app.routes.routes.filter_map do |route|
-          next if route.internal? # Skip Rails internal routes
+          next if route.respond_to?(:internal?) && route.internal?
           next if route.defaults[:controller].blank?
 
           {

data/lib/rails_ai_context/introspectors/stimulus_introspector.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Introspectors
+    # Scans Stimulus controllers and extracts targets, values, and actions.
+    class StimulusIntrospector
+      attr_reader :app
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call
+        root = app.root.to_s
+        controllers_dir = File.join(root, "app/javascript/controllers")
+        return { controllers: [] } unless Dir.exist?(controllers_dir)
+
+        controllers = Dir.glob(File.join(controllers_dir, "**/*_controller.{js,ts}")).sort.filter_map do |path|
+          parse_controller(path, controllers_dir)
+        end
+
+        { controllers: controllers }
+      rescue => e
+        { error: e.message }
+      end
+
+      private
+
+      def parse_controller(path, base_dir)
+        relative = path.sub("#{base_dir}/", "")
+        name = relative.sub(/_controller\.(js|ts)\z/, "").tr("/", "--")
+        content = File.read(path)
+
+        {
+          name: name,
+          file: relative,
+          targets: extract_targets(content),
+          values: extract_values(content),
+          actions: extract_actions(content)
+        }
+      rescue => e
+        { name: File.basename(path), error: e.message }
+      end
+
+      def extract_targets(content)
+        match = content.match(/static\s+targets\s*=\s*\[([^\]]*)\]/)
+        return [] unless match
+
+        match[1].scan(/["'](\w+)["']/).flatten
+      end
+
+      def extract_values(content)
+        match = content.match(/static\s+values\s*=\s*\{([^}]*)\}/m)
+        return {} unless match
+
+        match[1].scan(/(\w+)\s*:\s*(\w+)/).to_h
+      end
+
+      def extract_actions(content)
+        content.scan(/^\s*(\w+)\s*\(/).flatten
+               .reject { |m| %w[constructor connect disconnect initialize].include?(m) }
+      end
+    end
+  end
+end