rails-ai-context 1.3.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d83d1237d476138591f50c4723cb10a4864aed5ed2e84b7059e53bff287af1db
-  data.tar.gz: 3791bba4e68364ea507050f2605096ce8dff2cacf943ddd111753b768c8152cf
+  metadata.gz: 34ef5e454a22f9719cf4439c70867a4e2f9dc900d34e1cca0f4ecd723e3a3308
+  data.tar.gz: d7545c9afd73831f0f32e0808f82856e1cf48c3763308049f5ba54d453f3f452
 SHA512:
-  metadata.gz: 4e3ceb93281e5d3674aab290728357ef75d9d0c24a7d3cee05c9380333ba4d5209b13fdad85a7f015185697d09b9c9093fafc10e628d4dbc1bb897280eb5c388
-  data.tar.gz: 4a0240af3fc7a4ecc303c72107b62f5f5df88fafc189be1f3b19096895dccdd7242ce6e640f7d0f6f148aaed45af7e74f4bf717f773aee3b8cd77107f393c6b0
+  metadata.gz: f29724289bcf91b5aeb776cfac4eec673a8bb8b02016108bab7a52f9f6f52b4fe5f3045cee43053a4b6e660619800dc8ea6f0141ed5bdd812d00898d00f9d7ef
+  data.tar.gz: 3178d4a6347de30aaf92e13b5db4d976fe6d2c0888de60b451bc187e9ae71518186c204c97f74e37d159431c2ea149d9fc19db00ab338bce44ffda6c33ef6da3

data/CHANGELOG.md

@@ -5,6 +5,51 @@ 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).
 
+## [2.0.0] - 2026-03-24
+
+### Added
+
+- **9 new MCP tools (16→25)** — `rails_get_concern` (concern methods + includers), `rails_get_callbacks` (execution order + source), `rails_get_helper_methods` (app + framework helpers + view refs), `rails_get_service_pattern` (interface, deps, side effects), `rails_get_job_pattern` (queue, retries, guards, broadcasts), `rails_get_env` (env vars, credentials keys, external services), `rails_get_partial_interface` (locals contract + usage), `rails_get_turbo_map` (stream/frame wiring + mismatch warnings), `rails_get_context` (composite cross-layer tool).
+- **Phase 1 improvements** — scope definitions include lambda body, controller actions show instance variables + private methods called inline, Stimulus shows HTML data-attributes + reverse view lookup.
+- **3 new validation rules** — instance variable consistency (view uses @foo but controller never sets it), Turbo Stream channel matching (broadcast without subscriber), respond_to template existence.
+- **`rails_security_scan` tool** — Brakeman static security analysis via MCP. Detects SQL injection, XSS, mass assignment, and more. Optional dependency — returns install instructions if Brakeman isn't present. Supports file filtering, confidence levels (high/medium/weak), specific check selection, and three detail levels (summary/standard/full).
+- **`config.skip_tools`** — users can now exclude specific built-in tools: `config.skip_tools = %w[rails_security_scan]`. Defaults to empty (all 25 tools active).
+- **Schema index hints** — `get_schema` standard detail now shows `[indexed]`/`[unique]` on columns, saving a round-trip to full detail.
+- **Enum backing types** — `get_model_details` now shows integer vs string backing: `status: pending(0), active(1) [integer]`.
+- **Search context lines default 2** — `search_code` now returns 2 lines of context by default (was 0). Eliminates follow-up calls for context.
+- **`match_type` parameter for search** — `search_code` supports `match_type:"definition"` (only `def` lines) and `match_type:"class"` (only `class`/`module` lines).
+- **Controller respond_to formats** — `get_controllers` surfaces `respond_to` formats (html, json) already collected by introspector.
+- **Config database/auth/assets detection** — `get_config` now shows database adapter, auth framework (Devise/Rodauth/etc), and assets stack (Tailwind/esbuild/etc).
+- **Frontend stack detection** — `get_conventions` detects frontend dependencies from package.json (Tailwind, React, TypeScript, Turbo, etc).
+- **Validate fix suggestions** — semantic warnings now include actionable fix hints (migration commands, `dependent:` options, index commands).
+- **Prism fallback indicator** — `validate` reports when Prism is unavailable so agents know semantic checks may be skipped.
+- **Factory attributes/traits** — `get_test_info` full detail parses factory files to show attributes and traits, not just names.
+- **Partial render locals** — `get_view` standard detail shows what locals each partial receives based on render call scanning.
+- **Edit context header** — `get_edit_context` shows enclosing class/method name in response header.
+- **Gem config location hints** — `get_gems` shows config file paths for 17 common gems (Devise, Sidekiq, Pundit, etc).
+- **Stimulus lifecycle detection** — `get_stimulus` detects connect/disconnect/initialize lifecycle methods.
+- **Route params inline** — `get_routes` standard detail shows required params: `[id]`, `[user_id, id]`.
+- **Feature test coverage gaps** — `analyze_feature` reports which models/controllers/jobs lack test files.
+- **Model macros surfaced** — `get_model_details` now shows `has_secure_password`, `encrypts`, `normalizes`, `generates_token_for`, `serialize`, `store`, `broadcasts`, attachments — all previously collected but hidden.
+- **Model delegations and constants** — `get_model_details` shows `delegate :x, to: :y` and constants like `STATUSES = %w[pending completed]`.
+- **Association FK column hints** — `get_model_details` shows `(fk: user_id)` on belongs_to associations.
+- **Schema model references** — `get_schema` full detail shows which ActiveRecord models reference each table.
+- **Schema column comments** — `get_schema` full detail shows database column comments when present.
+- **Action Cable adapter detection** — `get_config` detects Action Cable adapter from cable.yml.
+- **Gem version display** — `get_gems` shows version numbers from Gemfile.lock.
+- **Package manager detection** — `get_conventions` detects npm/yarn/pnpm/bun from lock files.
+- **Exact match search** — `search_code` supports `exact_match:true` for whole-word matching with `\b` boundaries.
+- **Scaled defaults for big apps** — increased `max_tool_response_chars` (120K→200K), `max_search_results` (100→200), `max_validate_files` (20→50), `cache_ttl` (30→60s), `max_file_size` (2MB→5MB), `max_test_file_size` (500KB→1MB), `max_view_total_size` (5MB→10MB), `max_view_file_size` (500KB→1MB). Schema standard pagination 15→25, full 5→10. Methods shown per model 15→25. Routes standard 100→150.
+- **AI-optimal tool ordering** — schema standard sorts tables by column count (complex first), model listing sorts by association count (central models first). Stops AI from missing important tables/models buried alphabetically.
+- **Cross-reference navigation hints** — schema single-table suggests `rails_get_model_details`, model detail suggests `rails_get_controllers` + `rails_get_schema` + `rails_analyze_feature`, controller detail suggests `rails_get_routes` + `rails_get_view`. Reduces AI round-trips.
+- **Schema adapter in summary** — `get_schema` summary shows database adapter (postgresql/mysql/sqlite3) so AI knows query syntax immediately.
+- **App size detection** — `BaseTool.app_size` returns `:small`/`:medium`/`:large` based on model/table count for auto-tuning.
+- **Doctor checks for Prism and Brakeman** — `rails ai:doctor` now reports availability of Prism parser and Brakeman security scanner.
+
+### Fixed
+
+- **JS fallback validator false-positives** — escaped backslashes before string-closing quotes (`"path\\"`) no longer cause false bracket mismatch errors. Replaced `prev_char` check with proper `escaped` toggle flag.
+
 ## [1.3.1] - 2026-03-23
 
 ### Fixed

data/CLAUDE.md

@@ -9,7 +9,7 @@ structure to AI assistants via the Model Context Protocol (MCP).
 - `lib/rails_ai_context/configuration.rb` — User-facing config with presets (:standard, :full)
 - `lib/rails_ai_context/introspector.rb` — Orchestrates sub-introspectors
 - `lib/rails_ai_context/introspectors/` — 29 introspectors (schema, models, routes, jobs, gems, conventions, stimulus, database_stats, controllers, views, view_templates, design_tokens, turbo, i18n, config, active_storage, action_text, auth, api, tests, rake_tasks, assets, devops, action_mailbox, migrations, seeds, middleware, engines, multi_database)
-- `lib/rails_ai_context/tools/` — 15 MCP tools using the official mcp SDK
+- `lib/rails_ai_context/tools/` — 25 MCP tools using the official mcp SDK
 - `lib/rails_ai_context/serializers/` — Output formatters (claude, claude_rules, opencode, opencode_rules, cursor_rules, windsurf, windsurf_rules, copilot, copilot_instructions, rules, markdown, JSON, context_file_serializer, test_command_detection)
 - `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)
@@ -39,13 +39,15 @@ structure to AI assistants via the Model Context Protocol (MCP).
 13. **Per-tool split rules** — `.claude/rules/`, `.cursor/rules/`, `.windsurf/rules/`, `.github/instructions/`
 14. **Section markers** — root file content wrapped in `<!-- BEGIN/END rails-ai-context -->` to preserve user content
 15. **generate_root_files toggle** — when false, skip root files (CLAUDE.md, etc.), only generate split rules
-16. **custom_tools API** — `config.custom_tools` array lets users register additional MCP::Tool subclasses alongside the 15 built-in tools
+16. **custom_tools API** — `config.custom_tools` array lets users register additional MCP::Tool subclasses alongside the 25 built-in tools
 17. **Design system extraction** — view templates analyzed for canonical examples, color palette, typography, responsive patterns, interactive states, dark mode
+18. **skip_tools API** — `config.skip_tools` array lets users exclude specific built-in tools (e.g. `%w[rails_security_scan]`)
+19. **Security scanning** — optional Brakeman integration via `rails_security_scan` tool (graceful degradation if not installed)
 
 ## Testing
 
 ```bash
-bundle exec rspec           # Run specs (522 examples)
+bundle exec rspec           # Run specs (575 examples)
 bundle exec rubocop         # Lint
 ```
 

data/CONTRIBUTING.md

@@ -19,7 +19,7 @@ The test suite uses [Combustion](https://github.com/pat/combustion) to boot a mi
 ```
 lib/rails_ai_context/
 ├── introspectors/     # 29 introspectors (schema, models, routes, etc.)
-├── tools/             # 15 MCP tools with detail levels and pagination
+├── tools/             # 25 MCP tools with detail levels and pagination
 ├── serializers/       # Per-assistant formatters (claude, opencode, cursor, windsurf, copilot, JSON)
 ├── server.rb          # MCP server setup (stdio + HTTP)
 ├── live_reload.rb     # MCP live reload (file watcher + cache invalidation)

data/README.md

@@ -62,7 +62,7 @@ Agent: rails_validate(files:["app/models/cook.rb"], level:"rails") → catches c
 |-------|-----------------|---------------|------------|
 | **Static files** (CLAUDE.md, .cursorrules, etc.) | App overview: stack, models, gems, architecture, UI patterns, MCP tool reference | Automatically at session start | ~150 lines, zero tool calls |
 | **Split rules** (.claude/rules/, .cursor/rules/) | Deep reference: full schema with column types, all model associations/scopes, controller listings | Conditionally — only when editing relevant files | Zero when not needed |
-| **Live MCP tools** (15 tools) | Real-time queries: drill into any table, model, controller action, or view on demand. Semantic validation. Design system. | On-demand via agent tool calls | ~25-100 lines per call |
+| **Live MCP tools** (25 tools) | Real-time queries: drill into any table, model, controller action, or view on demand. Semantic validation. Design system. Security scanning. | On-demand via agent tool calls | ~25-100 lines per call |
 
 **Progressive disclosure:** the agent gets the map for free, reference guides when relevant, and live GPS when building.
 
@@ -72,7 +72,7 @@ Agent: rails_validate(files:["app/models/cook.rb"], level:"rails") → catches c
 
 | Setup | Tokens | What it knows |
 |-------|--------|---------------|
-| **rails-ai-context (full)** | **28,834** | 15 MCP tools + generated docs + split rules |
+| **rails-ai-context (full)** | **28,834** | 25 MCP tools + generated docs + split rules |
 | rails-ai-context CLAUDE.md only | 33,106 | Generated docs + rules, no MCP tools |
 | Normal Claude `/init` | 40,700 | Generic CLAUDE.md only |
 | No rails-ai-context | 45,477 | Nothing — discovers everything from scratch |
@@ -97,27 +97,37 @@ But token savings is the side effect. The real value:
 
 ---
 
-## 15 Live MCP Tools
+## 25 Live MCP Tools
 
-The gem exposes **15 read-only tools** via MCP that AI clients call on-demand:
+The gem exposes **25 read-only tools** via MCP that AI clients call on-demand:
 
 | Tool | What it returns |
 |------|----------------|
-| `rails_get_schema` | Tables, columns, indexes, foreign keys |
-| `rails_get_model_details` | Associations, validations, scopes, enums, callbacks |
-| `rails_get_routes` | HTTP verbs, paths, controller actions |
-| `rails_get_controllers` | Actions, filters, strong params, concerns |
-| `rails_get_config` | Cache, session, timezone, middleware, initializers |
-| `rails_get_test_info` | Test framework, factories, CI config, coverage |
-| `rails_get_gems` | Notable gems categorized by function |
-| `rails_get_conventions` | Architecture patterns, directory structure |
-| `rails_search_code` | Ripgrep-powered regex search across the codebase |
-| `rails_get_view` | View templates, partials, Stimulus references |
-| `rails_get_stimulus` | Stimulus controllers — targets, values, actions, outlets |
-| `rails_get_edit_context` | Surgical edit helper — returns code around a match with line numbers |
-| `rails_validate` | Batch syntax validation for Ruby, ERB, and JavaScript files. `level:"rails"` adds semantic checks (partials, route helpers, columns, strong params, callbacks, FK indexes, Stimulus) |
-| `rails_analyze_feature` | Full-stack feature analysis — models, controllers, routes, services, jobs, views, Stimulus, tests, related models, env deps |
+| `rails_get_schema` | Tables, columns with `[indexed]`/`[unique]` hints, indexes, foreign keys |
+| `rails_get_model_details` | Associations with `dependent:`, validations, scopes, enums with backing type, callbacks |
+| `rails_get_routes` | HTTP verbs, paths with `[params]`, controller actions |
+| `rails_get_controllers` | Actions, filters, strong params, respond_to formats |
+| `rails_get_config` | Database adapter, auth framework, assets stack, cache, session, timezone, middleware |
+| `rails_get_test_info` | Test framework, factory attributes/traits, fixtures, CI config, coverage |
+| `rails_get_gems` | Notable gems categorized by function with config location hints |
+| `rails_get_conventions` | Architecture patterns, frontend stack, directory structure |
+| `rails_search_code` | Ripgrep search with 2-line context default, `match_type:"definition"` for method defs only |
+| `rails_get_view` | View templates, partials with render locals, Stimulus references |
+| `rails_get_stimulus` | Stimulus controllers — targets, values, actions, outlets, lifecycle methods |
+| `rails_get_edit_context` | Surgical edit helper — returns code with class/method context and line numbers |
+| `rails_validate` | Syntax + semantic validation with fix suggestions (migrations, dependent options, index commands) |
+| `rails_analyze_feature` | Full-stack feature analysis — models, controllers, routes, services, jobs, views, Stimulus, tests, test coverage gaps |
 | `rails_get_design_system` | App design system — color palette, component patterns with real HTML examples, typography, layout, responsive breakpoints |
+| `rails_security_scan` | Brakeman static security analysis — SQL injection, XSS, mass assignment. Filter by file, confidence level, specific checks |
+| `rails_get_concern` | Concern public methods, signatures, which models/controllers include it |
+| `rails_get_callbacks` | Model callbacks in Rails execution order with source code |
+| `rails_get_helper_methods` | Application + framework helper methods with view usage cross-references |
+| `rails_get_service_pattern` | Service objects — interface, dependencies, side effects, error handling, calling convention |
+| `rails_get_job_pattern` | Background jobs — queue, retries, guard clauses, service calls, Turbo broadcasts, schedules |
+| `rails_get_env` | Environment variables, credentials keys (not values), external service dependencies |
+| `rails_get_partial_interface` | Partial locals contract — required variables, method calls on each, usage examples |
+| `rails_get_turbo_map` | Turbo Streams/Frames wiring — broadcasts, subscriptions, channel matching, mismatch warnings |
+| `rails_get_context` | Composite tool — assembles schema + model + controller + routes + views in one call |
 
 ### Smart Detail Levels
 
@@ -126,8 +136,8 @@ Schema, routes, models, and controllers tools support a `detail` parameter — c
 | Level | Returns | Default limit |
 |-------|---------|---------------|
 | `summary` | Names + counts | 50 |
-| `standard` | Names + key details *(default)* | 15 |
-| `full` | Everything (indexes, FKs, constraints) | 5 |
+| `standard` | Names + key details *(default)* | 25 |
+| `full` | Everything (indexes, FKs, constraints) | 10 |
 
 ```ruby
 rails_get_schema(detail: "summary")           # → all tables with column counts
@@ -282,7 +292,7 @@ RailsAiContext.configure do |config|
   config.excluded_paths += %w[vendor/bundle]
 
   # Cache TTL for MCP tool responses (seconds)
-  config.cache_ttl = 30
+  config.cache_ttl = 60
 
   # Live reload: auto-invalidate MCP caches on file changes
   # :auto (default), true, or false
@@ -314,8 +324,8 @@ end
 | `http_path` | `"/mcp"` | HTTP endpoint path |
 | `http_port` | `6029` | HTTP server port |
 | `http_bind` | `"127.0.0.1"` | HTTP server bind address |
-| `cache_ttl` | `30` | Cache TTL in seconds |
-| `max_tool_response_chars` | `120_000` | Safety cap for MCP tool responses |
+| `cache_ttl` | `60` | Cache TTL in seconds |
+| `max_tool_response_chars` | `200_000` | Safety cap for MCP tool responses |
 | `live_reload` | `:auto` | `:auto`, `true`, or `false` — MCP live reload |
 | `live_reload_debounce` | `1.5` | Debounce interval in seconds |
 | **Filtering & Exclusions** | | |
@@ -328,18 +338,19 @@ end
 | `excluded_filters` | `verify_authenticity_token` etc. | Framework filter names hidden from controller output |
 | `excluded_middleware` | standard Rack/Rails middleware | Default middleware hidden from config output |
 | **File Size Limits** | | |
-| `max_file_size` | `2_000_000` | Per-file read limit for tools (bytes) |
-| `max_test_file_size` | `500_000` | Test file read limit (bytes) |
+| `max_file_size` | `5_000_000` | Per-file read limit for tools (bytes) |
+| `max_test_file_size` | `1_000_000` | Test file read limit (bytes) |
 | `max_schema_file_size` | `10_000_000` | schema.rb / structure.sql parse limit (bytes) |
-| `max_view_total_size` | `5_000_000` | Total aggregated view content for UI patterns (bytes) |
-| `max_view_file_size` | `500_000` | Per-view file during aggregation (bytes) |
-| `max_search_results` | `100` | Max search results per call |
-| `max_validate_files` | `20` | Max files per validate call |
+| `max_view_total_size` | `10_000_000` | Total aggregated view content for UI patterns (bytes) |
+| `max_view_file_size` | `1_000_000` | Per-view file during aggregation (bytes) |
+| `max_search_results` | `200` | Max search results per call |
+| `max_validate_files` | `50` | Max files per validate call |
 | **Search & Discovery** | | |
 | `search_extensions` | `rb js erb yml yaml json ts tsx vue svelte haml slim` | File extensions for Ruby fallback search |
 | `concern_paths` | `app/models/concerns app/controllers/concerns` | Where to look for concern source files |
 | **Extensibility** | | |
 | `custom_tools` | `[]` | Additional MCP tool classes to register alongside built-in tools |
+| `skip_tools` | `[]` | Built-in tool names to exclude (e.g. `%w[rails_security_scan]`) |
 </details>
 
 ---

data/SECURITY.md

@@ -4,9 +4,9 @@
 
 | Version | Supported          |
 |---------|--------------------|
-| 1.3.x   | :white_check_mark: |
-| 1.2.x   | :white_check_mark: |
-| < 1.2   | :x:                |
+| 2.0.x   | :white_check_mark: |
+| 1.4.x   | :white_check_mark: |
+| < 1.4   | :x:                |
 
 ## Reporting a Vulnerability
 
@@ -22,8 +22,12 @@ If you discover a security vulnerability in rails-ai-context, please report it r
 
 ## Security Design
 
-- All MCP tools are **read-only** and never modify your application or database.
-- Code search (`rails_search_code`) uses `Open3.capture2` with array arguments to prevent shell injection.
-- File paths are validated against path traversal attacks.
-- Credentials and secret values are **never** exposed — only a `credentials_configured` boolean is reported (key names and values are never introspected).
+- All 25 MCP tools are **read-only** and never modify your application or database.
+- **Sensitive file blocking** — configurable `sensitive_patterns` blocks access to `.env`, `*.key`, `*.pem`, `credentials.yml.enc` across all search and read tools. Patterns are checked in `rails_search_code`, `rails_get_edit_context`, and all new tools.
+- **Path traversal protection** — all file-reading tools validate paths with `File.realpath()` against `Rails.root` to prevent directory escape.
+- **Command injection prevention** — code search uses `Open3.capture2` with array arguments (never shell strings). The `--` flag separator prevents pattern injection.
+- **Regex DoS protection** — user-supplied regex patterns have 1-2 second timeouts via `Regexp.new(pattern, timeout:)`.
+- **Credential safety** — `rails_get_env` only reads `.env.example` (never `.env`), shows credential key names only (never values), and redacts secrets. `rails_get_config` exposes adapter/framework names, not connection strings.
+- **Brakeman integration** — optional `rails_security_scan` tool runs static security analysis. Graceful degradation if not installed. Users can exclude it via `config.skip_tools = %w[rails_security_scan]`.
+- **File size limits** — all tools enforce configurable `max_file_size` (default 5MB) to prevent memory exhaustion on large files.
 - The gem does not make any outbound network requests.