rails-ai-context 5.1.0 → 5.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1edfff7102dd3dd9e07d8686bb62c6017ff79492a46c36645a453b7b39a4983c
-  data.tar.gz: 2e9bb943d9986b169de0c133cb4458bb9a8678a5b32608ebf92ba80b3637c406
+  metadata.gz: a9d802d024a373d0552ee2b70cf3d5d755fd79f951b8335da948563a7f488af4
+  data.tar.gz: fabf3246fb0df9a97294bca58dac86d4bccc7ffd881fb1da69dc262d03e43fba
 SHA512:
-  metadata.gz: ff8184662fc4c3b181d199dc0a3085935bc545cef488361b4b4596a2941630a424cff14ba175e22db244234d6a448cb6d3352863a1ff9ce3a07c28b89d2279c0
-  data.tar.gz: 79ec7f4d524a581b5dff5f67c58c1271743fe708131e5223fc91b23799e0d803561b7b713aba080662fe8f79f6e0601d0ce233a2763ab6bee1f9f50eb5ca3898
+  metadata.gz: 40fbc9d7455f857de366de800f91ddfa19b9b752cfced2905c2bedc0576a3d54ee4a4c89eccb701904b0eb6cb8babd106cb699182a5eab98981a02d60ff14d6f
+  data.tar.gz: e640c259017a222d43a32d15a8c7e70f9888eb3a8df3ad172159efa17371003196ade1f2bf561683a319fa4cebc6b16262f72aee56dea636d2be5fa0a5c7dba7

data/CHANGELOG.md

@@ -5,6 +5,73 @@ 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.3.0] — 2026-04-07
+
+### Added — Phase 2: Cross-Tool Semantic Hydration (Ground Truth Engine Blueprint #38)
+
+Controller and view tools now automatically inject schema hints for referenced models, eliminating the need for follow-up tool calls.
+
+- **SchemaHint** (`lib/rails_ai_context/schema_hint.rb`) — Immutable `Data.define` value object carrying model ground truth: table, columns, associations, validations, primary key, and `[VERIFIED]`/`[INFERRED]` confidence tag.
+
+- **HydrationResult** — Wraps hints + warnings for downstream formatting.
+
+- **SchemaHintBuilder** (`lib/rails_ai_context/hydrators/schema_hint_builder.rb`) — Resolves model names to `SchemaHint` objects from cached introspection context. Case-insensitive lookup, batch builder with configurable cap.
+
+- **HydrationFormatter** (`lib/rails_ai_context/hydrators/hydration_formatter.rb`) — Renders `SchemaHint` objects as compact Markdown `## Schema Hints` sections with columns (capped at 10), associations, and validations.
+
+- **ControllerHydrator** (`lib/rails_ai_context/hydrators/controller_hydrator.rb`) — Parses controller source via Prism AST to detect model references (constant receivers, `params.require` keys, ivar writes), then builds schema hints.
+
+- **ViewHydrator** (`lib/rails_ai_context/hydrators/view_hydrator.rb`) — Maps instance variable names to models by convention (`@post` → `Post`, `@posts` → `Post`). Filters framework ivars (page, query, flash, etc.).
+
+- **ModelReferenceListener** (`lib/rails_ai_context/introspectors/listeners/model_reference_listener.rb`) — Prism Dispatcher listener for controller-specific model detection. Not registered in `LISTENER_MAP` — used standalone by `ControllerHydrator`.
+
+- **Tool integrations:**
+  - `GetControllers` — schema hints injected into both action source and controller overview
+  - `GetContext` — hydrates combined controller+view ivars in action context mode
+  - `GetView` — hydrates instance variables from view templates in standard detail
+
+- **Configuration:** `hydration_enabled` (default: true), `hydration_max_hints` (default: 5). Both YAML-configurable.
+
+- **65 new specs** covering SchemaHint, HydrationResult, SchemaHintBuilder, HydrationFormatter, ModelReferenceListener, ControllerHydrator, ViewHydrator, tool-level hydration integration (GetControllers, GetView), and configuration (defaults, YAML loading, max_hints propagation).
+
+## [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-1731%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>
+1731 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:**
 
@@ -427,7 +431,7 @@ rails_get_routes(detail: "standard", limit: 20, offset: 100)
 
 ### rails_get_controllers
 
-Returns controller details: actions, filters, strong params, concerns.
+Returns controller details: actions, filters, strong params, concerns. Automatically includes **Schema Hints** for models referenced in the controller (via Prism AST detection).
 
 **Parameters:**
 
@@ -545,7 +549,7 @@ rails_get_stimulus(detail: "full")
 
 ### rails_get_view
 
-Returns view template contents, partials, and Stimulus controller references.
+Returns view template contents, partials, and Stimulus controller references. In standard detail, includes **Schema Hints** for models inferred from instance variables.
 
 **Parameters:**
 
@@ -942,7 +946,7 @@ rails_get_turbo_map(controller: "messages", detail: "full")
 
 ### rails_get_context
 
-Get cross-layer context in a single call — combines schema, model, controller, routes, views, stimulus, and tests. Use when you need full context for implementing a feature or modifying an action.
+Get cross-layer context in a single call — combines schema, model, controller, routes, views, stimulus, and tests. Automatically includes **Schema Hints** for models referenced in controller/view code. Use when you need full context for implementing a feature or modifying an action.
 
 **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
 ```
 
@@ -1267,6 +1275,8 @@ end
 | `server_version` | String | gem version | MCP server version |
 | `generate_root_files` | Boolean | `true` | Generate root files (CLAUDE.md, etc.) — set `false` for split rules only |
 | `anti_hallucination_rules` | Boolean | `true` | Embed 6-rule Anti-Hallucination Protocol in generated context files — set `false` to skip |
+| `hydration_enabled` | Boolean | `true` | Inject schema hints into controller/view tool responses |
+| `hydration_max_hints` | Integer | `5` | Max schema hints per tool response |
 | `max_file_size` | Integer | `5_000_000` | Per-file read limit for tools (5MB) |
 | `max_test_file_size` | Integer | `1_000_000` | Test file read limit (1MB) |
 | `max_schema_file_size` | Integer | `10_000_000` | schema.rb / structure.sql parse limit (10MB) |
@@ -1291,8 +1301,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 +1321,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 +1555,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(' ')}]"