rails-ai-context 5.32.0 → 5.32.2

data/docs/COMPATIBILITY.md

@@ -105,8 +105,8 @@ from the booted path:
 | `jobs` | `app/jobs`, `app/workers`, `app/sidekiq`, `app/mailers` and `app/channels` parsed for classes and their public methods, plus any class elsewhere under `app/` whose parent chain reaches `ActionMailer::Base` |
 | `i18n` | `config.i18n.available_locales` read from `config/`, or every top-level key across `config/locales` when the app never assigns it; the default locale read from `config/`. The backend and the fallbacks stay in the answer and are declared unanswered, being facts about the running process |
 | `api` | every detection but the mode is a file read and runs unchanged; `config.api_only` comes from the assignment in `config/application.rb` |
-| `engines` | `config/routes.rb` mounts, plus the Gemfile |
-| `active_support` | concern and core-extension use read from source |
+| `engines` | the mounts in `config/routes.rb` and the files it draws, plus the in-repo engines found in the tree; the loaded `Rails::Engine` classes are declared unavailable |
+| `active_support` | concerns, message verifier and encryptor use, notification subscriptions and a `TaggedLogging` initializer read from source; deprecators, load hooks and the cache store are declared unavailable |
 | `middleware` | `app/middleware`, `lib/middleware`, and the stack changes in `config/initializers`, `config/environments` and `config/application.rb`; the booted stack and its count are declared unavailable |
 
 **runtime-only** (8) report `{ unavailable: reason }` here, and only these:
@@ -174,14 +174,14 @@ a consumer must not join it to the app root. The gem's own readers ask
 ## Shape matrix
 
 Rows are app shapes; columns are schema, models, routes, and controllers
-(the four whose static behavior varies by shape), plus views for contrast.
+(the four whose static behavior varies by shape), plus views.
 `n/a` means the shape doesn't change that introspector's behavior - see
 the stock full-stack row for its baseline proof. Reference numbers point at
 the proof list below the table.
 
 | Shape | Schema | Models | Routes | Controllers | Views |
 |:---|:---|:---|:---|:---|:---|
-| Stock full-stack (`schema.rb`) | runtime + static [1] | runtime + static [1] | runtime + static [1] | runtime + static [1] | runtime only [2] |
+| Stock full-stack (`schema.rb`) | runtime + static [1] | runtime + static [1] | runtime + static [1] | runtime + static [1] | runtime [2] + static [8] |
 | API-only | runtime + static [1] | runtime + static [1] | runtime + static [1] | runtime + static [1] | runtime, "not applicable" [3] |
 | `structure.sql` - PostgreSQL dialect | static [4] | n/a | n/a | n/a | n/a |
 | `structure.sql` - MySQL/Trilogy dialect | static [4] | n/a | n/a | n/a | n/a |
@@ -191,7 +191,7 @@ the proof list below the table.
 | In-repo `engines/` | n/a | n/a | n/a | static [5] | n/a |
 | In-repo `plugins/`, `modules/`, `gems/plugins/` | n/a | static [5] | n/a | static [5] | n/a |
 | Mongoid | `[UNAVAILABLE]`, honest signal [6] | static (fields + embeds) [6] | n/a | n/a | n/a |
-| Broken-boot (any full-stack app) | static [7] | static, per-file isolation [7] | static [7] | static [7] | `[UNAVAILABLE]` [8] |
+| Broken-boot (any full-stack app) | static [7] | static, per-file isolation [7] | static [7] | static [7] | static [8] |
 | Packs + engines under `--no-boot` | n/a | static [5] | n/a | static [5] | n/a |
 | Empty/greenfield app (no scaffold) | graceful, no crash [9] | graceful, no crash [9] | graceful, no crash [9] | graceful, no crash [9] | graceful, no crash [9] |
 | Massive app (500 models/tables) | no crash at scale [10] | no crash at scale [10] | no crash at scale [10] | n/a | n/a |
@@ -234,6 +234,17 @@ Proof sources:
    Sinatra and a plain gem); the lab regressions on SQLite in all three tiers,
    PostgreSQL and MySQL; and the unit suite on Ruby 3.1 with Rails 7.0 through
    Ruby 4.0 with Rails 8.1.
+   In the v5.32.1 release QA: a PostgreSQL 17 lab on Rails 8.1 and 8.0 with a
+   two-schema search path, answered booted and static from schema.rb and
+   structure.sql side by side; the small apps and the same private app
+   answering as v5.32.0 did; and the unit suite on Ruby 3.1 with Rails 7.0
+   through Ruby 4.0 with Rails 8.1.
+   In the v5.32.2 release QA: `rails_query` on the same private app's
+   PostgreSQL database, with comment markers inside string literals, E strings
+   and dollar quotes, a `#>>` that starts a line, and every spelling of a row
+   limit; the installer's cleanup on a small Rails 8.1 app holding hand-written
+   rule files; and the unit suite on Ruby 3.1 with Rails 7.0 through Ruby 4.0
+   with Rails 8.1.
 2. Non-crash coverage for every built-in tool including `get_view` in
    `spec/e2e/in_gemfile_install_spec.rb`'s full-tool sweep; output correctness
    (ivar cross-check, render-form detection, partial interfaces) verified
@@ -253,14 +264,16 @@ Proof sources:
    tier)" and "multi-database schema dumps".
 6. `spec/e2e/shapes_spec.rb`: "Mongoid app (bare directory, --app-path, no
    boot possible)".
-7. `spec/e2e/boot_resilience_spec.rb` (four boot-failure modes: raises,
-   prints to stdout, writes via the `STDOUT` constant, hangs past the
-   timeout) plus `spec/e2e/static_tier_spec.rb` ("broken-boot app over the
+7. `spec/e2e/boot_resilience_spec.rb` (five boot-failure modes: raises,
+   prints to stdout, writes via the `STDOUT` constant, calls `exit`/`abort`,
+   hangs past the timeout) plus `spec/e2e/static_tier_spec.rb` ("broken-boot app over the
    CLI", "broken-boot app over MCP stdio", "syntax error in one model file").
-8. No introspector outside the six in the operating-tiers table defines
-   `static_call` (`lib/rails_ai_context/introspectors/view_introspector.rb`
-   has none); `Introspector#run_introspector` reports `{ unavailable: reason
-   }` for every such section regardless of shape.
+8. `views` is files-only
+   (`lib/rails_ai_context/introspectors/view_introspector.rb`), so its `call`
+   runs unchanged with nothing booted, proven against `spec/fixtures/static_app`
+   in `spec/lib/rails_ai_context/introspectors/static_tier_declarations_spec.rb`.
+   `Introspector#run_introspector` reports `{ unavailable: reason }` only for
+   the eight runtime-only sections, regardless of shape.
 9. `spec/e2e/empty_app_spec.rb` - all 45 built-in tools swept against an app
    with no scaffold, no models, no controllers beyond
    `ApplicationController`, no routes beyond root.
@@ -283,14 +296,16 @@ Postgres instance in `spec/e2e/postgres_install_spec.rb`, opt-in via
   `ApplicationRecord`, pass their concerns, scopes, callbacks and macros down
   the way Rails does. Only the table stops at an abstract base, because a child
   of one has its own. A concern's macro is tagged with the concern that
-  declared it. Both tiers stop at the same place: a superclass whose file is not
+  declared it. Both tiers leave out a superclass whose file is not
   under one of the app's model directories, a gem-owned base for example. The
   booted tier could read that file and deliberately does not, because an answer
-  the static tier can never match is two answers to one question. Reflection
+  the static tier can never match is two answers to one question. The static
+  tier ends the walk at such a base; the booted tier steps over it and still
+  reads an app base above it. Reflection
   still carries such a base's associations, validations and enums onto the
-  child. The validations Rails generates at boot
-  (implicit `belongs_to` presence, attachment validations) are runtime-only and
-  stay marked `[UNAVAILABLE]`. A concern whose file cannot be found, a gem's
+  child. The presence validation Rails adds for a required
+  `belongs_to` is listed in both tiers as implicit; without a boot it is worked
+  out from `optional:`/`required:` and `belongs_to_required_by_default`. A concern whose file cannot be found, a gem's
   module for example, is named under `Concerns` as not read.
 - **Callbacks are what the file declares.** In both tiers the callback list is
   what the model file, the app concerns it includes and the classes it inherits
@@ -312,36 +327,58 @@ Postgres instance in `spec/e2e/postgres_install_spec.rb`, opt-in via
   are invisible to ActiveRecord reflection, so `ModelIntrospector#call` falls
   back to the same source-parsing pass used in the static tier even when the
   app is booted (`lib/rails_ai_context/introspectors/model_introspector.rb`).
-  Fields or associations defined in an included concern module rather than
-  directly in the document class body are not resolved, in either tier.
-- **Static-tier API-only detection.** `Tools::BaseTool#api_only_app?` reads
-  `app.config.api_only`. `RailsAiContext::StaticApp` exposes no `config`
-  method, so this check is always false in the static tier - the "not
-  applicable" messaging for view/frontend tools on API-only apps only fires
-  once the app has actually booted.
+  A concern's fields, embedded relations, `store_in` and indexes are read. A
+  `belongs_to`/`has_many`, validation, scope or callback declared in a concern
+  rather than in the document class body is not resolved, in either tier.
+- **Static-tier API-only detection.** `RailsAiContext::StaticApp` exposes no
+  `config` method, so in the static tier `Tools::BaseTool.api_only_app?` reads
+  the `config.api_only = true` assignment in `config/application.rb`
+  (`AppKind.api_only?`). A value set anywhere else, or one that is not a
+  literal `true`, is missed, and the "not applicable" messaging for
+  view/frontend tools then only fires once the app has booted.
 - **Live multi-DB connections are not iterated, only dumps.**
   `MultiDatabaseIntrospector` reads `config/database.yml` and the model source
   in the static tier, so databases, replicas, sharding and `connects_to`
   declarations come from the files rather than from the live connection
   handlers. A database only a runtime `connects_to` names is missed.
+- **Rails 7.0 merges same-name enum types.** On Rails 7.0, two PostgreSQL enum
+  types with one name in different schemas come back from the connection as
+  one type holding both label lists; the static tier keeps the first type's
+  labels.
+- **A schema.rb from before Rails 8.1 does not say which schema holds a
+  table.** It names each table bare, whichever search path schema holds it,
+  so without a boot a schema-qualified name such as `app.users` finds a listed
+  table only when the search path has one schema. A Rails 7.0 schema.rb names
+  no schema at all, so the static tier takes every schema the search path
+  names as existing, except the one `"$user"` stands for.
+- **A dump made with a `schema_search_path` holds only those schemas.** By
+  default Rails passes each search path schema to pg_dump, so structure.sql
+  holds no other schema's tables and no extension, and a Rails 8.1 schema.rb
+  holds no other schema's tables. Without a boot those tables are not found and
+  the extension list is plpgsql alone. `config.active_record.dump_schemas =
+  :all` dumps everything.
 - **Inherited controller actions and filters are resolved by parent name, so
-  some walks end early.** A controller that defines no action of its own takes
-  the actions of the nearest app ancestor the listing holds, walked through the
+  some walks end early.** Every controller also takes the actions of each app
+  ancestor the listing holds, up to the app's base controller, walked through the
   `parent_class` each entry carries, and the filter chain is walked the same
   way. A superclass spelled relatively inside a `module` body (`module
   Settings; class ProfileController < BaseController`) is resolved against the
-  enclosing namespace first, the way Ruby resolves it. What still ends the walk
-  is a gem-owned parent such as `OAuth::AuthorizationsController <
-  Doorkeeper::AuthorizationsController`, which the payload cannot hold. A
-  booted run answers that one.
+  enclosing namespace first, the way Ruby resolves it. A gem-owned parent such as
+  `OAuth::AuthorizationsController < Doorkeeper::AuthorizationsController`,
+  which the payload cannot hold, still ends the inherited-actions walk. The
+  filter walk skips that class's own filters: for a Devise or Doorkeeper parent
+  it resumes at the base class the gem's initializer names, or the gem's
+  default, and for any other gem-owned parent it ends. A booted run answers
+  those.
 - **`ApplicationController` is not in the listing, but its filters are in the
   chain.** Every app has one and it would sit in every listing row, so the
   controller listing leaves it out. The chain walk reads its file anyway, by
   the one name Rails fixes, so a filter it declares is attributed to it in both
   tiers with its `only:`/`except:`/`if:` intact. A parent the listing does not
   hold and the app has no file for still ends the walk: reconstructing a path
-  from a class name breaks on an app inflection, and a gem-owned parent such as
-  `Doorkeeper::AuthorizationsController` has no file under the app root at all.
+  from a class name breaks on an app inflection, and a gem-owned parent has no file under the app
+  root at all (a Devise or Doorkeeper one resumes at its configured base, as
+  above).
   A booted run answers that one from reflection.
 - **Some route macros surface as a dynamic tally, not resolved entries.**
   `RouteIntrospector#static_call` counts routes behind `devise_for`, a `match`

data/docs/CONFIGURATION.md

@@ -16,7 +16,7 @@
 
 ```ruby
 # config/initializers/rails_ai_context.rb
-if defined?(RailsAiContext)
+if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
   RailsAiContext.configure do |config|
     config.ai_tools  = %i[claude cursor copilot opencode codex]
     config.tool_mode = :mcp
@@ -49,7 +49,7 @@ preset: full
 
 | Option | Type | Default | Description |
 |:-------|:-----|:--------|:------------|
-| `ai_tools` | Array of symbols | `[:claude]` | Which AI tools to generate context for. Options: `:claude`, `:cursor`, `:copilot`, `:opencode`, `:codex` |
+| `ai_tools` | Array of symbols | `nil` (all five) | Which AI tools to generate context for. Options: `:claude`, `:cursor`, `:copilot`, `:opencode`, `:codex`. Unset, it reads the selection the installer recorded, and all five when there is none |
 | `tool_mode` | Symbol | `:mcp` | `:mcp` (MCP server primary, CLI fallback) or `:cli` (CLI only, no MCP server) |
 | `context_files` | Boolean | `true` | Set `false` for MCP-only: the server and the CLI still answer, and no context file is written or touched |
 
@@ -76,8 +76,10 @@ nothing, and `rails ai:doctor` raises no context-file warning. A command that
 names a file still writes it: `rails ai:context:claude` and
 `rails-ai-context context --format claude`.
 
-`config.ai_tools = []` means no context files too, and still picks which MCP
-config file is written. Before v5.27.0 an empty list wrote every tool's files.
+`config.ai_tools = []` means no AI tool at all: no context files and no MCP
+config file are written, and `rails ai:context` does not ask which tools you
+use. The installer has no such choice, so set it by hand. Before v5.27.0 an
+empty list wrote every tool's files.
 
 ### Introspection
 
@@ -88,7 +90,7 @@ config file is written. Before v5.27.0 an empty list wrote every tool's files.
 | `introspectors` | Array of symbols | (from preset) | Override the introspector list directly |
 | `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only: no CLAUDE.md, AGENTS.md, .cursorrules or copilot-instructions.md (`.ai-context.json` is still written) |
 | `anti_hallucination_rules` | Boolean | `true` | Embed 6-rule verification protocol in generated context files |
-| `claude_max_lines` | Integer | `150` | Max non-blank lines in a compact context file's gem-managed block, the `<!-- BEGIN/END rails-ai-context -->` markers included. Over budget, data lines are cut and the Commands, Warnings, Rules and MCP-tools sections kept whole |
+| `claude_max_lines` | Integer | `150` | Max non-blank lines in a compact context file's gem-managed block, the `<!-- BEGIN/END rails-ai-context -->` markers included. Over budget, data lines are cut and the Commands, Warnings, Rules and MCP-tools sections kept whole. Must be positive |
 
 ### MCP Server
 
@@ -197,8 +199,8 @@ fits neither that shape nor the conventional one.
 |:-------|:-----|:--------|:-----------|:------------|
 | `query_timeout` | Integer | `5` | - | SQL query timeout in seconds |
 | `query_row_limit` | Integer | `100` | 1 to 1000 | Maximum rows returned |
-| `query_redacted_columns` | Array | 14 patterns | - | Column names that cause a query to be rejected |
-| `query_allowed_columns` | Array | `[]` | - | Column names exempted from the built-in sensitive list |
+| `query_redacted_columns` | Array | 14 patterns | - | Column names that cause a query to be rejected, on top of a fixed built-in list (see [SECURITY.md](SECURITY.md)) |
+| `query_allowed_columns` | Array | `[]` | - | Column names exempted from the built-in sensitive list and from `query_redacted_columns` |
 | `allow_query_in_production` | Boolean | `false` | - | Allow `rails_query` tool in production |
 
 ### Logs
@@ -252,7 +254,7 @@ Lightweight subset for faster generation:
 | Claude Code | `CLAUDE.md` | `.claude/rules/*.md` | `.mcp.json` |
 | Cursor | `.cursorrules` (legacy fallback) | `.cursor/rules/*.mdc` | `.cursor/mcp.json` |
 | GitHub Copilot | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | `.vscode/mcp.json` |
-| OpenCode | `AGENTS.md` | `app/*/AGENTS.md` | `opencode.json` |
+| OpenCode | `AGENTS.md` | `app/models/AGENTS.md`, `app/controllers/AGENTS.md` | `opencode.json` |
 | Codex CLI | (shares `AGENTS.md`) | (shares OpenCode rules) | `.codex/config.toml` |
 
 ---

data/docs/CUSTOM_TOOLS.md

@@ -19,6 +19,8 @@ Custom tools are subclasses of `MCP::Tool` that you register in your configurati
 
 ```ruby
 # app/mcp_tools/rails_get_business_metrics.rb
+require "mcp" # the gem loads the MCP SDK lazily, so a file read first needs it
+
 class RailsGetBusinessMetrics < MCP::Tool
   tool_name "rails_get_business_metrics"
   description "Returns key business metrics for the current environment"
@@ -33,7 +35,7 @@ class RailsGetBusinessMetrics < MCP::Tool
     }
   )
 
-  def call(period: "week")
+  def self.call(period: "week", server_context: nil)
     # Your logic here - full access to Rails models, services, etc.
     stats = {
       users: User.where("created_at > ?", period_start(period)).count,
@@ -46,9 +48,7 @@ class RailsGetBusinessMetrics < MCP::Tool
     ])
   end
 
-  private
-
-  def period_start(period)
+  def self.period_start(period)
     case period
     when "day" then 1.day.ago
     when "week" then 1.week.ago
@@ -56,7 +56,7 @@ class RailsGetBusinessMetrics < MCP::Tool
     end
   end
 
-  def format_stats(stats)
+  def self.format_stats(stats)
     <<~TEXT
       ## Business Metrics
       - New users: #{stats[:users]}
@@ -73,7 +73,7 @@ Add your tool classes to the configuration:
 
 ```ruby
 # config/initializers/rails_ai_context.rb
-if defined?(RailsAiContext)
+if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
   RailsAiContext.configure do |config|
     config.custom_tools = ["RailsGetBusinessMetrics"]
   end
@@ -98,7 +98,7 @@ class RailsGetDeployStatus < MCP::Tool
   tool_name "rails_get_deploy_status"
   description "Returns current deployment status"
 
-  def call
+  def self.call(server_context: nil)
     # Use SafeFile for safe reading
     version = RailsAiContext::SafeFile.read(Rails.root.join("REVISION"))
     deployed_at = File.mtime(Rails.root.join("tmp/restart.txt")) rescue nil
@@ -215,7 +215,7 @@ end
 - Custom tools have access to the full Rails environment - ActiveRecord, services, mailers, etc.
 - Keep tools read-only when possible. MCP tools annotated as non-destructive build more trust with AI clients.
 - Return `MCP::Tool::Response` objects with `type: "text"` content blocks.
-- Tool responses are automatically truncated at `config.max_tool_response_chars` (default: 200,000).
+- A response you build with `MCP::Tool::Response.new` is sent as written. The `config.max_tool_response_chars` cap (default: 200,000) is applied by the built-in tools' `text_response`, so keep a custom tool's output short yourself.
 
 ---
 

data/docs/FAQ.md

@@ -52,12 +52,13 @@ Yes, freely. Both generate identical context files and provide the same 45 tools
 ### Do I need to commit the generated files?
 
 **Yes, commit these:**
-- `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `opencode.json`, `.codex/config.toml` - so teammates get MCP auto-discovery
-- `CLAUDE.md`, `.cursor/rules/`, `.cursorrules`, `.github/instructions/`, `AGENTS.md` - so AI has context
+- `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `opencode.json` - so teammates get MCP auto-discovery
+- `CLAUDE.md`, `.claude/rules/`, `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`, `.github/instructions/`, `AGENTS.md` - so AI has context
 - `config/initializers/rails_ai_context.rb`, `.rails-ai-context.yml` - so config is shared
 
 **Don't commit:**
 - `.ai-context.json` - auto-added to .gitignore by the install generator
+- `.codex/config.toml` - it embeds this machine's Ruby PATH and GEM_HOME, so install adds it to .gitignore too and `rails ai:doctor` fails when it is not ignored
 
 ### Can I use only the MCP server?
 
@@ -141,7 +142,7 @@ Depends on your `ai_tools` config. For all tools:
 | Claude | CLAUDE.md, .claude/rules/*.md |
 | Cursor | .cursor/rules/*.mdc AND .cursorrules (legacy fallback for chat agent) |
 | Copilot | .github/copilot-instructions.md, .github/instructions/*.instructions.md |
-| OpenCode | AGENTS.md, app/*/AGENTS.md |
+| OpenCode | AGENTS.md, app/models/AGENTS.md, app/controllers/AGENTS.md |
 | Codex | Shares AGENTS.md and OpenCode rules |
 
 ### How do I regenerate context files?
@@ -175,7 +176,7 @@ Introspection results are cached with TTL (default: 60s) and fingerprint invalid
 
 ### Does this affect my app's performance?
 
-No. The gem only runs in development. Tools execute on demand (not continuously). The MCP server is a separate process (stdio) or a development-only endpoint (HTTP).
+No, as long as the gem sits in the Gemfile's `:development` group, where `bundle add rails-ai-context --group development` puts it: Bundler then never loads it in production. The gem itself does not check the environment, apart from `rails_query` refusing to run in production by default. Tools execute on demand (not continuously). The MCP server is a separate process (stdio), or an HTTP endpoint that exists only when you mount it or set `auto_mount`.
 
 ### How does live reload work?
 
@@ -187,7 +188,7 @@ The `listen` gem watches `app/`, `config/`, `db/`, `lib/`, `rakelib/`, `test/`,
 
 ### Can tools modify my database?
 
-No. The query tool uses `SET TRANSACTION READ ONLY` + rollback. Even if SQL validation were bypassed, the database layer prevents writes.
+No. The query tool uses `SET TRANSACTION READ ONLY` + rollback on PostgreSQL and MySQL, and a read-only connection on SQLite. Even if SQL validation were bypassed, the database layer prevents writes.
 
 ### Can tools read my .env or credentials?