rails-ai-context 5.1.0 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1edfff7102dd3dd9e07d8686bb62c6017ff79492a46c36645a453b7b39a4983c
-  data.tar.gz: 2e9bb943d9986b169de0c133cb4458bb9a8678a5b32608ebf92ba80b3637c406
+  metadata.gz: a1dd01df89a380a86e14436ae9275c5db3f88b0e4fc56ea6df7d308f2c468472
+  data.tar.gz: 6f2efe8319fa533b8ea19cc0ace32460b24cb9b96873af0956c4b126041cd14b
 SHA512:
-  metadata.gz: ff8184662fc4c3b181d199dc0a3085935bc545cef488361b4b4596a2941630a424cff14ba175e22db244234d6a448cb6d3352863a1ff9ce3a07c28b89d2279c0
-  data.tar.gz: 79ec7f4d524a581b5dff5f67c58c1271743fe708131e5223fc91b23799e0d803561b7b713aba080662fe8f79f6e0601d0ce233a2763ab6bee1f9f50eb5ca3898
+  metadata.gz: 1447735cb99e717f1fa43a1fa54cc89fe1d6e0a836fcf156a7a66cede53c321328fbe4088a0c72103d91fe9c49de88f537cb59cddcbe1782773416892f76c728
+  data.tar.gz: 57b9e93748454c414563d453661eb4b51f94a063f15ac12a7073d6695b3cbc1e7fb1db323be3972ac1f830c1b21d73fcc65dc8fc1d5f170c8787cd9c8031881d

data/CHANGELOG.md

@@ -5,6 +5,44 @@ 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).
 
+## [5.2.0] — 2026-04-07
+
+### Added — Phase 1: Prism AST Foundation (Ground Truth Engine Blueprint #36)
+
+System-wide AST migration replacing all regex-based Ruby source parsing with Prism AST visitors. This is the foundation layer for the Ground Truth Engine transformation (#37).
+
+- **AstCache** (`lib/rails_ai_context/ast_cache.rb`) — Thread-safe Prism parse cache backed by `Concurrent::Map`. Keyed by path + SHA256 content hash + mtime. Invalidates automatically on file change. Shared by all AST-based introspectors.
+
+- **VERIFIED/INFERRED confidence contract** — `Confidence.for_node(node)` determines whether an AST node's arguments are all static literals (`[VERIFIED]`) or contain dynamic expressions (`[INFERRED]`). Called from listeners via `BaseListener#confidence_for(node)`. Every source-level introspection result now carries a confidence tag.
+
+- **7 Prism Listener classes** (`lib/rails_ai_context/introspectors/listeners/`):
+  - `AssociationsListener` — `belongs_to`, `has_many`, `has_one`, `has_and_belongs_to_many`
+  - `ValidationsListener` — `validates`, `validates_*_of`, custom `validate :method`
+  - `ScopesListener` — `scope :name, -> { ... }`
+  - `EnumsListener` — Rails 7+ and legacy enum syntax with prefix/suffix options
+  - `CallbacksListener` — all AR callback types including `after_commit` with `on:` resolution
+  - `MacrosListener` — `encrypts`, `normalizes`, `delegate`, `has_secure_password`, `serialize`, `store`, `has_one_attached`, `has_many_attached`, `has_rich_text`, `generates_token_for`, `attribute` API
+  - `MethodsListener` — `def`/`def self.` with visibility tracking, parameter extraction, `class << self` support
+
+- **SourceIntrospector** (`lib/rails_ai_context/introspectors/source_introspector.rb`) — Single-pass Prism Dispatcher that walks the AST once and feeds events to all 7 listeners simultaneously. Available as `SourceIntrospector.call(path)` for file-based introspection or `SourceIntrospector.from_source(string)` for in-memory parsing.
+
+- **73 new specs** covering AstCache, SourceIntrospector integration, and all 7 listener classes with edge cases (multi-line associations, legacy enums, visibility tracking, parameter extraction).
+
+### Changed
+
+- **ModelIntrospector** rewritten to use AST-based source parsing via `SourceIntrospector` instead of regex. Reflection-based extraction (associations via AR, validations via AR, enums via AR) preserved where it provides runtime accuracy. All `source.scan(...)`, `source.each_line`, and `line.match?(...)` patterns in model introspection eliminated.
+
+- **Install generator** now wraps `config/initializers/rails_ai_context.rb` in `if defined?(RailsAiContext)` so apps with the gem in `group :development` only don't crash in test/production. Re-install upgrades existing unguarded initializers and preserves indentation. All README and GUIDE initializer examples updated to the guarded form (#35).
+
+### Dependencies
+
+- Added `prism >= 0.28` (stdlib in Ruby 3.3+, gem for 3.2)
+- Added `concurrent-ruby >= 1.2` (thread-safe AST cache; already transitive via Rails)
+
+### Why
+
+Regex-based Ruby source parsing was the #3 critical finding in the architecture audit: it breaks on heredocs, multi-line DSL calls, `class << self` blocks, and metaprogrammed constructs. Prism AST provides 100% syntax-level accuracy. The single-pass Dispatcher pattern means parsing a 500-line model file runs all 7 listeners in one tree walk — no repeated I/O or re-parsing. The confidence tagging gives AI agents explicit signal about what data is ground truth vs. what requires runtime verification.
+
 ## [5.1.0] — 2026-04-06
 
 ### Fixed

data/CONTRIBUTING.md

@@ -44,6 +44,19 @@ lib/rails_ai_context/
 4. Register in `Server::TOOLS`
 5. Write specs in `spec/lib/rails_ai_context/tools/your_tool_spec.rb`
 
+## Adding a Prism Listener
+
+Listeners extract specific concerns (associations, validations, etc.) from the AST via `Prism::Dispatcher` events.
+
+1. Create `lib/rails_ai_context/introspectors/listeners/your_listener.rb` inheriting from `BaseListener`
+2. Implement `on_call_node_enter(node)` and/or `on_def_node_enter(node)` — only the events your concern needs
+3. Use `confidence_for(node)` from `BaseListener` to tag results `[VERIFIED]` or `[INFERRED]`
+4. Store results in `@results` (accessed via `#results`)
+5. Register the key/class pair in `SourceIntrospector::LISTENER_MAP`
+6. Write specs in `spec/lib/rails_ai_context/introspectors/listeners/your_listener_spec.rb`
+
+See existing listeners in `lib/rails_ai_context/introspectors/listeners/` for reference patterns.
+
 ## Adding a CLI Tool Interface
 
 The `ToolRunner` (`lib/rails_ai_context/cli/tool_runner.rb`) handles CLI execution of all MCP tools. It is tested in `spec/lib/rails_ai_context/cli/tool_runner_spec.rb`. If you add a new MCP tool, it is automatically available via CLI — no extra registration needed. Tool name resolution (`schema` → `get_schema` → `rails_get_schema`) works for all tools.

data/README.md

@@ -19,7 +19,7 @@
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-green)](https://registry.modelcontextprotocol.io)
 [![Ruby](https://img.shields.io/badge/Ruby-3.2%20%7C%203.3%20%7C%203.4-CC342D)](https://github.com/crisnahine/rails-ai-context)
 [![Rails](https://img.shields.io/badge/Rails-7.1%20%7C%207.2%20%7C%208.0-CC0000)](https://github.com/crisnahine/rails-ai-context)
-[![Tests](https://img.shields.io/badge/Tests-1565%20passing-brightgreen)](https://github.com/crisnahine/rails-ai-context/actions)
+[![Tests](https://img.shields.io/badge/Tests-1668%20passing-brightgreen)](https://github.com/crisnahine/rails-ai-context/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 </div>
@@ -62,11 +62,11 @@ rails-ai-context serve    # start MCP server
 
 <div align="center">
 
-![Install demo](demo.gif)
+![Install demo](demo/demo.gif)
 
 </div>
 
-Now your AI doesn't guess — it **asks your app directly.** 38 tools that query your schema, models, routes, controllers, views, and conventions on demand. It gets the right answer the first time.
+Now your AI doesn't guess — it **asks your app directly.** 38 tools that query your schema, models, routes, controllers, views, and conventions on demand. Model introspection uses Prism AST parsing — every result carries a `[VERIFIED]` or `[INFERRED]` confidence tag so AI knows what's ground truth and what needs runtime checking.
 
 <br>
 
@@ -74,7 +74,7 @@ Now your AI doesn't guess — it **asks your app directly.** 38 tools that query
 
 <div align="center">
 
-![Trace demo](demo-trace.gif)
+![Trace demo](demo/demo-trace.gif)
 
 </div>
 
@@ -263,7 +263,7 @@ Every tool is **read-only** and returns data verified against your actual app
 | Tool | What it does |
 |:-----|:------------|
 | `get_schema` | Columns with indexed/unique/encrypted/default hints |
-| `get_model_details` | Associations, validations, scopes, enums, macros, delegations |
+| `get_model_details` | AST-parsed associations, validations, scopes, enums, macros — each result tagged `[VERIFIED]` or `[INFERRED]` |
 | `get_callbacks` | Callbacks in Rails execution order with source |
 | `get_concern` | Concern methods + source + which models include it |
 
@@ -375,7 +375,7 @@ Enabled by default. Disable with `config.anti_hallucination_rules = false` if yo
                          ▼
 ┌─────────────────────────────────────────────────────────┐
 │  rails-ai-context                                        │
-│  Parses everything. Caches results. Sensible defaults.    │
+│  Prism AST parsing. Cached. Confidence-tagged results.    │
 └────────┬──────────────────┬──────────────┬──────────────┘
          │                  │              │
          ▼                  ▼              ▼
@@ -427,10 +427,12 @@ Both paths ask which AI tools you use and whether you want MCP or CLI mode. `.mc
 
 ```ruby
 # config/initializers/rails_ai_context.rb
-RailsAiContext.configure do |config|
-  config.ai_tools   = %i[claude cursor]   # Which AI tools to generate for
-  config.tool_mode   = :mcp               # :mcp (default) or :cli
-  config.preset      = :full              # :full (31 introspectors) or :standard (17)
+if defined?(RailsAiContext)
+  RailsAiContext.configure do |config|
+    config.ai_tools   = %i[claude cursor] # Which AI tools to generate for
+    config.tool_mode  = :mcp              # :mcp (default) or :cli
+    config.preset     = :full             # :full (31 introspectors) or :standard (17)
+  end
 end
 ```
 
@@ -470,7 +472,7 @@ end
 ## About
 
 Built by a Rails developer with 10+ years of production experience.<br>
-1565 tests. 38 tools. 31 introspectors. Standalone or in-Gemfile.<br>
+1668 tests. 38 tools. 31 introspectors. Standalone or in-Gemfile.<br>
 MIT licensed. [Contributions welcome.](CONTRIBUTING.md)
 
 <br>

data/docs/GUIDE.md

@@ -121,8 +121,10 @@ CONTEXT_MODE=full rails ai:context:copilot
 
 ```ruby
 # config/initializers/rails_ai_context.rb
-RailsAiContext.configure do |config|
-  config.context_mode = :full  # or :compact (default)
+if defined?(RailsAiContext)
+  RailsAiContext.configure do |config|
+    config.context_mode = :full # or :compact (default)
+  end
 end
 ```
 
@@ -306,10 +308,12 @@ Short names are resolved automatically:
 The `tool_mode` config controls how tool references appear in generated context files:
 
 ```ruby
-RailsAiContext.configure do |config|
-  # :mcp (default) — MCP primary, CLI as fallback
-  # :cli — CLI only, no MCP server needed
-  config.tool_mode = :mcp
+if defined?(RailsAiContext)
+  RailsAiContext.configure do |config|
+    # :mcp (default) — MCP primary, CLI as fallback
+    # :cli — CLI only, no MCP server needed
+    config.tool_mode = :mcp
+  end
 end
 ```
 
@@ -359,7 +363,7 @@ rails_get_schema(detail: "full", format: "json")
 
 ### rails_get_model_details
 
-Returns model details: associations, validations, scopes, enums, callbacks, concerns.
+Returns model details: associations, validations, scopes, enums, callbacks, concerns. Source parsing uses Prism AST — every result carries a `[VERIFIED]` (static literal arguments) or `[INFERRED]` (dynamic expressions) confidence tag.
 
 **Parameters:**
 
@@ -1110,11 +1114,13 @@ rails ai:serve_http
 Or auto-mount inside your Rails app (no separate process):
 
 ```ruby
-RailsAiContext.configure do |config|
-  config.auto_mount = true
-  config.http_path  = "/mcp"   # default
-  config.http_port  = 6029     # default
-  config.http_bind  = "127.0.0.1"  # default (localhost only)
+if defined?(RailsAiContext)
+  RailsAiContext.configure do |config|
+    config.auto_mount = true
+    config.http_path  = "/mcp"       # default
+    config.http_port  = 6029          # default
+    config.http_bind  = "127.0.0.1"  # default (localhost only)
+  end
 end
 ```
 
@@ -1126,116 +1132,118 @@ Both transports are **read-only** — they expose the same 38 tools and never mo
 
 ```ruby
 # config/initializers/rails_ai_context.rb
-RailsAiContext.configure do |config|
-  # --- Introspectors ---
+if defined?(RailsAiContext)
+  RailsAiContext.configure do |config|
+    # --- Introspectors ---
 
-  # Presets: :full (31 introspectors, default) or :standard (17)
-  config.preset = :full
+    # Presets: :full (31 introspectors, default) or :standard (17)
+    config.preset = :full
 
-  # Cherry-pick on top of a preset
-  config.introspectors += %i[views turbo auth api]
+    # Cherry-pick on top of a preset
+    config.introspectors += %i[views turbo auth api]
 
-  # --- Context files ---
+    # --- Context files ---
 
-  # Context mode: :compact (default) or :full
-  config.context_mode = :compact
+    # Context mode: :compact (default) or :full
+    config.context_mode = :compact
 
-  # Max lines for CLAUDE.md in compact mode
-  config.claude_max_lines = 150
+    # Max lines for CLAUDE.md in compact mode
+    config.claude_max_lines = 150
 
-  # Output directory for context files (default: Rails.root)
-  # config.output_dir = "/custom/path"
+    # Output directory for context files (default: Rails.root)
+    # config.output_dir = "/custom/path"
 
-  # --- MCP tools ---
+    # --- MCP tools ---
 
-  # Tool mode: :mcp (MCP primary + CLI fallback) or :cli (CLI only)
-  config.tool_mode = :mcp
+    # Tool mode: :mcp (MCP primary + CLI fallback) or :cli (CLI only)
+    config.tool_mode = :mcp
 
-  # Max response size for tool results (safety net)
-  config.max_tool_response_chars = 200_000
+    # Max response size for tool results (safety net)
+    config.max_tool_response_chars = 200_000
 
-  # Cache TTL for introspection results (seconds)
-  config.cache_ttl = 60
+    # Cache TTL for introspection results (seconds)
+    config.cache_ttl = 60
 
-  # Additional MCP tool classes to register alongside built-in tools
-  # config.custom_tools = [MyApp::Tools::CustomTool]
+    # Additional MCP tool classes to register alongside built-in tools
+    # config.custom_tools = [MyApp::Tools::CustomTool]
 
-  # Exclude specific built-in tools (e.g. if you don't use Brakeman)
-  # config.skip_tools = %w[rails_security_scan]
+    # Exclude specific built-in tools (e.g. if you don't use Brakeman)
+    # config.skip_tools = %w[rails_security_scan]
 
-  # --- Exclusions ---
+    # --- Exclusions ---
 
-  # Models to skip during introspection
-  config.excluded_models += %w[AdminUser InternalAuditLog]
+    # Models to skip during introspection
+    config.excluded_models += %w[AdminUser InternalAuditLog]
 
-  # Paths to exclude from code search
-  config.excluded_paths += %w[vendor/bundle]
+    # Paths to exclude from code search
+    config.excluded_paths += %w[vendor/bundle]
 
-  # Sensitive file patterns blocked from search and read tools
-  # config.sensitive_patterns += %w[config/my_secret.yml]
+    # Sensitive file patterns blocked from search and read tools
+    # config.sensitive_patterns += %w[config/my_secret.yml]
 
-  # Controllers hidden from listings (e.g. Devise internals)
-  # config.excluded_controllers += %w[MyInternalController]
+    # Controllers hidden from listings (e.g. Devise internals)
+    # config.excluded_controllers += %w[MyInternalController]
 
-  # Route prefixes hidden with app_only (e.g. admin frameworks)
-  # config.excluded_route_prefixes += %w[admin/]
+    # Route prefixes hidden with app_only (e.g. admin frameworks)
+    # config.excluded_route_prefixes += %w[admin/]
 
-  # Regex patterns for concerns to hide from model output
-  # config.excluded_concerns += [/MyInternal::/]
+    # Regex patterns for concerns to hide from model output
+    # config.excluded_concerns += [/MyInternal::/]
 
-  # Framework filter names hidden from controller output
-  # config.excluded_filters += %w[my_internal_filter]
+    # Framework filter names hidden from controller output
+    # config.excluded_filters += %w[my_internal_filter]
 
-  # Default middleware hidden from config output
-  # config.excluded_middleware += %w[MyMiddleware]
+    # Default middleware hidden from config output
+    # config.excluded_middleware += %w[MyMiddleware]
 
-  # --- File size limits ---
+    # --- File size limits ---
 
-  # Per-file read limit for tools (default: 5MB)
-  # config.max_file_size = 5_000_000
+    # Per-file read limit for tools (default: 5MB)
+    # config.max_file_size = 5_000_000
 
-  # Test file read limit (default: 1MB)
-  # config.max_test_file_size = 1_000_000
+    # Test file read limit (default: 1MB)
+    # config.max_test_file_size = 1_000_000
 
-  # schema.rb / structure.sql parse limit (default: 10MB)
-  # config.max_schema_file_size = 10_000_000
+    # schema.rb / structure.sql parse limit (default: 10MB)
+    # config.max_schema_file_size = 10_000_000
 
-  # Total aggregated view content for UI patterns (default: 10MB)
-  # config.max_view_total_size = 10_000_000
+    # Total aggregated view content for UI patterns (default: 10MB)
+    # config.max_view_total_size = 10_000_000
 
-  # Per-view file during aggregation (default: 1MB)
-  # config.max_view_file_size = 1_000_000
+    # Per-view file during aggregation (default: 1MB)
+    # config.max_view_file_size = 1_000_000
 
-  # Max search results per call (default: 200)
-  # config.max_search_results = 200
+    # Max search results per call (default: 200)
+    # config.max_search_results = 200
 
-  # Max files per validate call (default: 50)
-  # config.max_validate_files = 50
+    # Max files per validate call (default: 50)
+    # config.max_validate_files = 50
 
-  # --- Search and file discovery ---
+    # --- Search and file discovery ---
 
-  # File extensions for Ruby fallback search
-  # config.search_extensions = %w[rb js erb yml yaml json ts tsx vue svelte haml slim]
+    # File extensions for Ruby fallback search
+    # config.search_extensions = %w[rb js erb yml yaml json ts tsx vue svelte haml slim]
 
-  # Where to look for concern source files
-  # config.concern_paths = %w[app/models/concerns app/controllers/concerns]
+    # Where to look for concern source files
+    # config.concern_paths = %w[app/models/concerns app/controllers/concerns]
 
-  # --- Live reload ---
+    # --- Live reload ---
 
-  # Auto-invalidate MCP tool caches on file changes
-  # :auto — enable if `listen` gem is available (default)
-  # true  — enable, raise if `listen` is missing
-  # false — disable entirely
-  config.live_reload = :auto
-  config.live_reload_debounce = 1.5  # seconds
+    # Auto-invalidate MCP tool caches on file changes
+    # :auto — enable if `listen` gem is available (default)
+    # true  — enable, raise if `listen` is missing
+    # false — disable entirely
+    config.live_reload = :auto
+    config.live_reload_debounce = 1.5  # seconds
 
-  # --- HTTP MCP endpoint ---
+    # --- HTTP MCP endpoint ---
 
-  # Auto-mount Rack middleware for HTTP MCP
-  config.auto_mount = false
-  config.http_path  = "/mcp"
-  config.http_bind  = "127.0.0.1"
-  config.http_port  = 6029
+    # Auto-mount Rack middleware for HTTP MCP
+    config.auto_mount = false
+    config.http_path  = "/mcp"
+    config.http_bind  = "127.0.0.1"
+    config.http_port  = 6029
+  end
 end
 ```
 
@@ -1291,8 +1299,10 @@ By default, `rails ai:context` generates root files (CLAUDE.md, AGENTS.md, etc.)
 **Skip root files:** If you prefer to maintain root files yourself and only want split rules (`.claude/rules/`, `.cursor/rules/`, `.github/instructions/`):
 
 ```ruby
-RailsAiContext.configure do |config|
-  config.generate_root_files = false
+if defined?(RailsAiContext)
+  RailsAiContext.configure do |config|
+    config.generate_root_files = false
+  end
 end
 ```
 
@@ -1309,7 +1319,7 @@ Core Rails structure only. Use `config.preset = :standard` for a lighter footpri
 | Introspector | What it discovers |
 |-------------|-------------------|
 | `schema` | Tables, columns, types, indexes, foreign keys, primary keys. Falls back to `db/schema.rb` parsing when no DB connected. |
-| `models` | Associations, validations, scopes, enums, callbacks, concerns, instance methods, class methods. Source-level macros: `has_secure_password`, `encrypts`, `normalizes`, `delegate`, `serialize`, `store`, `generates_token_for`, `has_one_attached`, `has_many_attached`, `has_rich_text`, `broadcasts_to`. |
+| `models` | Associations, validations, scopes, enums, callbacks, concerns, instance methods, class methods. Source-level macros via Prism AST (single-pass, 7 listeners): `has_secure_password`, `encrypts`, `normalizes`, `delegate`, `serialize`, `store`, `generates_token_for`, `has_one_attached`, `has_many_attached`, `has_rich_text`, `broadcasts_to`. Every result tagged `[VERIFIED]` or `[INFERRED]`. |
 | `routes` | All routes with HTTP verbs, paths, controller actions, route names, API namespaces, mounted engines. |
 | `jobs` | ActiveJob classes with queue names. Mailers with action methods. Action Cable channels. |
 | `gems` | 70+ notable gems categorized: auth, background_jobs, admin, monitoring, search, pagination, forms, file_upload, testing, linting, security, api, frontend, utilities. |
@@ -1543,14 +1553,16 @@ Live reload is **enabled by default** when the `listen` gem is available. No con
 ### Configuration
 
 ```ruby
-RailsAiContext.configure do |config|
-  # :auto (default) — enable if `listen` gem is available, skip silently otherwise
-  # true  — enable, raise if `listen` gem is missing
-  # false — disable entirely
-  config.live_reload = :auto
-
-  # Debounce interval in seconds (default: 1.5)
-  config.live_reload_debounce = 1.5
+if defined?(RailsAiContext)
+  RailsAiContext.configure do |config|
+    # :auto (default) — enable if `listen` gem is available, skip silently otherwise
+    # true  — enable, raise if `listen` gem is missing
+    # false — disable entirely
+    config.live_reload = :auto
+
+    # Debounce interval in seconds (default: 1.5)
+    config.live_reload_debounce = 1.5
+  end
 end
 ```
 

data/lib/generators/rails_ai_context/install/install_generator.rb

@@ -310,6 +310,7 @@ module RailsAiContext
         end
 
         content += "end\n"
+        content, = ensure_initializer_guard(content)
 
         create_file path, content
         say "Created #{path} with all #{CONFIG_SECTIONS.size} config sections", :green
@@ -332,13 +333,16 @@ module RailsAiContext
           marker = "── #{name}"
           next if existing.include?(marker)
 
-          insert_point = existing.rindex(/^end\b/)
+          insert_point = configure_block_end_index(existing)
           if insert_point
-            existing = existing.insert(insert_point, "\n#{section_content}\n")
+            existing = existing.insert(insert_point, "\n#{reindent_section_content(section_content, existing)}\n")
             changes << "section: #{name}"
           end
         end
 
+        existing, changed = ensure_initializer_guard(existing)
+        changes << "guard" if changed
+
         if changes.any?
           File.write(full_path, existing)
           say "Updated #{full_path.relative_path_from(Rails.root)}: #{changes.join(', ')}", :green
@@ -350,9 +354,11 @@ module RailsAiContext
       # Replace or uncomment a config line. Returns [new_content, changed?]
       def update_config_line(content, key, new_line)
         # Match both commented and uncommented versions of this config key
-        pattern = /^[ \t]*#?\s*#{Regexp.escape(key)}\s*=.*$/
+        pattern = /^([ \t]*)#?\s*#{Regexp.escape(key)}\s*=.*$/
         if content.match?(pattern)
-          updated = content.sub(pattern, new_line)
+          updated = content.sub(pattern) do
+            "#{Regexp.last_match(1)}#{new_line.lstrip}"
+          end
           [ updated, updated != content ]
         else
           # Key not found at all — don't add (it's in a section that will be added)
@@ -360,6 +366,56 @@ module RailsAiContext
         end
       end
 
+      def configure_block_end_index(content)
+        end_positions = []
+        content.to_enum(:scan, /^[ \t]*end\b/).each do
+          end_positions << Regexp.last_match.begin(0)
+        end
+        return nil if end_positions.empty?
+
+        if guarded_initializer?(content) && end_positions.size >= 2
+          end_positions[-2]
+        else
+          end_positions[-1]
+        end
+      end
+
+      def ensure_initializer_guard(content)
+        return [ content, false ] if guarded_initializer?(content)
+
+        header_match = content.match(/\A# frozen_string_literal: true\n(?:\n)?/)
+        header = header_match ? "# frozen_string_literal: true\n\n" : ""
+        body = header_match ? content.delete_prefix(header_match[0]) : content
+        body = "#{body}\n" unless body.end_with?("\n")
+
+        wrapped = "#{header}if defined?(RailsAiContext)\n#{indent_content(body)}end\n"
+        [ wrapped, wrapped != content ]
+      end
+
+      def reindent_section_content(section_content, content)
+        indent = configure_body_indent(content)
+        section_content.lines.map do |line|
+          next line if line == "\n"
+
+          "#{indent}#{line.sub(/\A[ \t]{0,2}/, "")}"
+        end.join
+      end
+
+      def configure_body_indent(content)
+        match = content.match(/^([ \t]*)RailsAiContext\.configure do \|config\|$/)
+        return "  " unless match
+
+        "#{match[1]}  "
+      end
+
+      def guarded_initializer?(content)
+        content.match?(/^[ \t]*if defined\?\(RailsAiContext\)$/)
+      end
+
+      def indent_content(content)
+        content.lines.map { |line| line == "\n" ? line : "  #{line}" }.join
+      end
+
       def build_ai_tools_line
         # Always write uncommented so re-install can detect previous selection
         "  config.ai_tools = %i[#{@selected_formats.join(' ')}]"

data/lib/rails_ai_context/ast_cache.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "digest"
+require "concurrent"
+require "prism"
+
+module RailsAiContext
+  # Thread-safe AST parse cache backed by Concurrent::Map.
+  # Keyed by path + content hash + mtime — automatically invalidates
+  # when file content changes. Used by all Prism-based introspectors.
+  #
+  # Bounded: evicts oldest entries when MAX_SIZE is exceeded.
+  module AstCache
+    STORE = Concurrent::Map.new
+    MAX_SIZE = 500
+    EVICTION_MUTEX = Mutex.new
+
+    # Max file size for parsing (default: matches config.max_file_size).
+    # Public API — callers don't need to pre-check size.
+    MAX_PARSE_SIZE = 5_000_000
+
+    # Parse a Ruby source file and cache the result.
+    # Returns a Prism::ParseResult. Rejects files exceeding MAX_PARSE_SIZE.
+    #
+    # Reads content first, then checks size — avoids TOCTOU race where the
+    # file could change between File.size and File.read.
+    def self.parse(path)
+      content = File.read(path)
+      size = content.bytesize
+      raise ArgumentError, "File too large for AST parsing: #{path} (#{size} bytes, max #{MAX_PARSE_SIZE})" if size > MAX_PARSE_SIZE
+
+      mtime = File.mtime(path).to_i
+      key   = "#{path}:#{Digest::SHA256.hexdigest(content)}:#{mtime}"
+
+      cached = STORE[key]
+      return cached if cached
+
+      # Evict BEFORE inserting to avoid running inside compute_if_absent
+      evict_if_full
+
+      STORE.compute_if_absent(key) { Prism.parse(content) }
+    end
+
+    # Parse a Ruby source string (no caching).
+    # Returns a Prism::ParseResult.
+    def self.parse_string(source)
+      Prism.parse(source)
+    end
+
+    # Invalidate all cached entries for a given path.
+    def self.invalidate(path)
+      prefix = "#{path}:"
+      STORE.each_key do |k|
+        STORE.delete(k) if k.start_with?(prefix)
+      end
+    end
+
+    # Clear the entire cache.
+    def self.clear
+      STORE.clear
+    end
+
+    # Number of cached entries (for diagnostics).
+    def self.size
+      STORE.size
+    end
+
+    # Evict ~25% of entries when cache exceeds MAX_SIZE.
+    # Synchronized to prevent multiple threads from over-evicting simultaneously.
+    def self.evict_if_full
+      EVICTION_MUTEX.synchronize do
+        return if STORE.size < MAX_SIZE
+        keys = STORE.keys
+        keys.first(keys.size / 4).each { |k| STORE.delete(k) }
+      end
+    end
+    private_class_method :evict_if_full
+  end
+end