rails-ai-context 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdd226d739429a34c2ea8cedc8faf12e854d0220de60f5ffb08fe8fed5459f71
-  data.tar.gz: 7b609ca0007e97206b168cbda0937fb9fb581888491464619ba727a8a1b2d945
+  metadata.gz: c2116ee4ebdfbdfeeef7e91c6a4ebd9d618a84ed182cdc1d012b90c362b2a6cf
+  data.tar.gz: e1a084f0f348a1c549c123aa305e75c51eb45632c1c46dec396c1e6f36b3dc4e
 SHA512:
-  metadata.gz: b54b6354d0236f8f46f813593a5472fcca35dd4ceb1aefc4631479829c541b53d8a34509602b2f5903ff1af4b34b3d43d758e41f2c8e84cb5498b3212011541a
-  data.tar.gz: 0ddd8d1b1d413c3313a3189168c790dbbe776de2d573be006163867732287e939c0c8ea4490b39d1b86239f6940cfd923fcfab27ce24f6d9ba9bc3cda0c750fb
+  metadata.gz: 2d919dc0670b50c31496866b354f215413828af302cd4d63089577d64a3253f1e5150a326ef29de16d32a29a30b3ada440a16ca1500284109e92aceb4904014b
+  data.tar.gz: f12682e40ce7733d1dd068fd47055ba74b40e474735dea7633ae38ae6b403d8027cfae89eb5ab3eab4e3d44f9acc10253148b467267305a22bd2e482f39b177d

data/CLAUDE.md

@@ -8,8 +8,8 @@ structure to AI assistants via the Model Context Protocol (MCP).
 - `lib/rails_ai_context.rb` — Main entry point, public API (Zeitwerk autoloaded)
 - `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/` — 28 introspectors (schema, models, routes, jobs, gems, conventions, stimulus, database_stats, controllers, views, view_templates, 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/` — 11 MCP tools using the official mcp SDK
+- `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/` — 12 MCP tools using the official mcp SDK
 - `lib/rails_ai_context/serializers/` — Output formatters (claude, claude_rules, opencode, cursor_rules, windsurf, windsurf_rules, copilot, copilot_instructions, rules, markdown, JSON)
 - `lib/rails_ai_context/resources.rb` — MCP resources (static data AI clients read directly)
 - `lib/rails_ai_context/server.rb` — MCP server configuration (stdio + HTTP transports)
@@ -32,7 +32,7 @@ structure to AI assistants via the Model Context Protocol (MCP).
 6. **Diff-aware** — context regeneration skips unchanged files
 7. **Per-assistant serializers** — each AI tool gets tailored output format
 8. **Zeitwerk autoloading** — files loaded on-demand, not all upfront
-9. **Introspector presets** — `:standard` (11 core) default, `:full` (28) for power users
+9. **Introspector presets** — `:standard` (12 core) default, `:full` (28) for power users
 10. **MCP auto-discovery** — `.mcp.json` generated by install generator
 11. **Compact by default** — context files ≤150 lines, MCP tools use `detail` parameter (summary/standard/full)
 12. **Per-tool split rules** — `.claude/rules/`, `.cursor/rules/`, `.windsurf/rules/`, `.github/instructions/`
@@ -42,7 +42,7 @@ structure to AI assistants via the Model Context Protocol (MCP).
 ## Testing
 
 ```bash
-bundle exec rspec           # Run specs (468 examples)
+bundle exec rspec           # Run specs (481 examples)
 bundle exec rubocop         # Lint
 ```
 

data/CONTRIBUTING.md

@@ -18,8 +18,8 @@ The test suite uses [Combustion](https://github.com/pat/combustion) to boot a mi
 
 ```
 lib/rails_ai_context/
-├── introspectors/     # 28 introspectors (schema, models, routes, etc.)
-├── tools/             # 11 MCP tools with detail levels and pagination
+├── introspectors/     # 29 introspectors (schema, models, routes, etc.)
+├── tools/             # 12 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

@@ -27,7 +27,7 @@ Same task — *"Add status and date range filters to the Cooks index page"* —
 
 | Setup | Tokens | Saved | What it knows |
 |-------|--------|-------|---------------|
-| **rails-ai-context (full)** | **28,834** | **37%** | 11 MCP tools + generated docs + rules |
+| **rails-ai-context (full)** | **28,834** | **37%** | 12 MCP tools + generated docs + rules |
 | rails-ai-context CLAUDE.md only | 33,106 | 27% | Generated docs + rules, no MCP tools |
 | Normal Claude `/init` | 40,700 | 11% | Generic CLAUDE.md only |
 | No rails-ai-context at all | 45,477 | baseline | Nothing — discovers everything from scratch |
@@ -95,9 +95,9 @@ The install generator creates `.mcp.json` for auto-discovery — Claude Code and
 
 ---
 
-## 11 Live MCP Tools
+## 12 Live MCP Tools
 
-The gem exposes **11 read-only tools** via MCP that AI clients call on-demand:
+The gem exposes **12 read-only tools** via MCP that AI clients call on-demand:
 
 | Tool | What it returns |
 |------|----------------|
@@ -112,6 +112,7 @@ The gem exposes **11 read-only tools** via MCP that AI clients call on-demand:
 | `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 |
 
 ### Smart Detail Levels
 
@@ -201,7 +202,7 @@ Root files (CLAUDE.md, AGENTS.md, etc.) use **section markers** — your custom
 | **DevOps** | Puma, Procfile, Docker, deployment tools, asset pipeline |
 | **Architecture** | Service objects, STI, polymorphism, state machines, multi-tenancy, engines |
 
-28 introspectors total. The `:standard` preset runs 11 core ones by default; use `:full` for 27 (`database_stats` is opt-in, PostgreSQL only).
+29 introspectors total. The `:standard` preset runs 12 core ones by default; use `:full` for 28 (`database_stats` is opt-in, PostgreSQL only).
 
 ---
 
@@ -255,7 +256,7 @@ end
 ```ruby
 # config/initializers/rails_ai_context.rb
 RailsAiContext.configure do |config|
-  # Presets: :standard (11 introspectors, default) or :full (all 28)
+  # Presets: :standard (12 introspectors, default) or :full (all 28)
   config.preset = :standard
 
   # Cherry-pick on top of a preset
@@ -289,7 +290,7 @@ end
 | Option | Default | Description |
 |--------|---------|-------------|
 | `preset` | `:standard` | Introspector preset (`:standard` or `:full`) |
-| `introspectors` | 11 core | Array of introspector symbols |
+| `introspectors` | 12 core | Array of introspector symbols |
 | `context_mode` | `:compact` | `:compact` (≤150 lines) or `:full` (dump everything) |
 | `claude_max_lines` | `150` | Max lines for CLAUDE.md in compact mode |
 | `max_tool_response_chars` | `120_000` | Safety cap for MCP tool responses |
@@ -350,7 +351,7 @@ Works with every Rails architecture — auto-detects what's relevant:
 
 | Setup | Coverage | Notes |
 |-------|----------|-------|
-| Rails full-stack (ERB + Hotwire) | 28/28 | All introspectors relevant |
+| Rails full-stack (ERB + Hotwire) | 29/29 | All introspectors relevant |
 | Rails + Inertia.js (React/Vue) | ~22/27 | Views/Turbo partially useful, backend fully covered |
 | Rails API + React/Next.js SPA | ~20/27 | Schema, models, routes, API, auth, jobs — all covered |
 | Rails API + mobile app | ~20/27 | Same as SPA — backend introspection is identical |
@@ -389,7 +390,7 @@ The gem parses `db/schema.rb` as text when no database is connected. Works in CI
 ```bash
 git clone https://github.com/crisnahine/rails-ai-context.git
 cd rails-ai-context && bundle install
-bundle exec rspec       # 468 examples
+bundle exec rspec       # 481 examples
 bundle exec rubocop     # Lint
 ```
 

data/demo_script.sh

@@ -8,7 +8,7 @@ echo 'Fetching gem metadata from https://rubygems.org...'
 sleep 0.3
 echo 'Resolving dependencies...'
 sleep 0.3
-echo 'Installing rails-ai-context 0.11.0'
+echo 'Installing rails-ai-context 0.12.0'
 echo ''
 sleep 1
 

data/docs/GUIDE.md

@@ -246,7 +246,7 @@ rails ai:context:claude           # Use this instead (no quoting needed)
 
 ## MCP Tools — Full Reference
 
-All 11 tools are **read-only** and **idempotent** — they never modify your application or database.
+All 12 tools are **read-only** and **idempotent** — they never modify your application or database.
 
 ### rails_get_schema
 
@@ -568,7 +568,7 @@ RailsAiContext.configure do |config|
 end
 ```
 
-Both transports are **read-only** — they expose the same 11 tools and never modify your app.
+Both transports are **read-only** — they expose the same 12 tools and never modify your app.
 
 ---
 
@@ -579,7 +579,7 @@ Both transports are **read-only** — they expose the same 11 tools and never mo
 RailsAiContext.configure do |config|
   # --- Introspectors ---
 
-  # Presets: :standard (11 core, default) or :full (all 28)
+  # Presets: :standard (12 core, default) or :full (all 28)
   config.preset = :standard
 
   # Cherry-pick on top of a preset
@@ -636,7 +636,7 @@ end
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `preset` | Symbol | `:standard` | Introspector preset (`:standard` or `:full`) |
-| `introspectors` | Array | 11 core symbols | Which introspectors to run |
+| `introspectors` | Array | 12 core symbols | Which introspectors to run |
 | `context_mode` | Symbol | `:compact` | `:compact` or `:full` |
 | `claude_max_lines` | Integer | `150` | Max lines for CLAUDE.md in compact mode |
 | `max_tool_response_chars` | Integer | `120_000` | Safety cap for MCP tool responses |
@@ -689,7 +689,7 @@ These run by default. Fast and cover core Rails structure.
 | `tests` | Test framework (rspec/minitest), factories/fixtures with locations and counts, system tests, CI config files, coverage tool, test helpers, VCR cassettes. |
 | `migrations` | Total count, schema version, pending migrations, recent migration history with detected actions (create_table, add_column, etc.), migration statistics. |
 
-### Full preset (28 introspectors)
+### Full preset (29 introspectors)
 
 Includes all standard introspectors plus:
 
@@ -812,7 +812,7 @@ OpenCode uses **per-directory lazy-loading**: when the agent reads a file, it wa
 
 | Setup | Coverage | Notes |
 |-------|----------|-------|
-| Rails full-stack (ERB + Hotwire) | 28/28 | All introspectors relevant |
+| Rails full-stack (ERB + Hotwire) | 29/29 | All introspectors relevant |
 | Rails + Inertia.js (React/Vue) | ~22/27 | Views/Turbo partially useful, backend fully covered |
 | Rails API + React/Next.js SPA | ~20/27 | Schema, models, routes, API, auth, jobs — all covered |
 | Rails API + mobile app | ~20/27 | Same as SPA — backend introspection is identical |

data/lib/rails_ai_context/configuration.rb

@@ -3,8 +3,8 @@
 module RailsAiContext
   class Configuration
     PRESETS = {
-      standard: %i[schema models routes jobs gems conventions controllers tests migrations stimulus view_templates],
-      full: %i[schema models routes jobs gems conventions stimulus controllers views view_templates turbo
+      standard: %i[schema models routes jobs gems conventions controllers tests migrations stimulus view_templates design_tokens],
+      full: %i[schema models routes jobs gems conventions stimulus 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]
     }.freeze

data/lib/rails_ai_context/introspector.rb

@@ -58,6 +58,7 @@ module RailsAiContext
       when :controllers    then Introspectors::ControllerIntrospector.new(app)
       when :views          then Introspectors::ViewIntrospector.new(app)
       when :view_templates then Introspectors::ViewTemplateIntrospector.new(app)
+      when :design_tokens  then Introspectors::DesignTokenIntrospector.new(app)
       when :turbo          then Introspectors::TurboIntrospector.new(app)
       when :i18n           then Introspectors::I18nIntrospector.new(app)
       when :config         then Introspectors::ConfigIntrospector.new(app)

data/lib/rails_ai_context/introspectors/design_token_introspector.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Introspectors
+    # Extracts design tokens from CSS/SCSS files across ALL Rails CSS setups:
+    # - Tailwind v4 @theme blocks
+    # - Tailwind v4 built CSS :root variables
+    # - Tailwind v3 tailwind.config.js (simple key-values only)
+    # - Bootstrap/Sass $variable definitions
+    # - Plain CSS :root custom properties
+    # - Webpacker-era stylesheets
+    # - ViewComponent sidecar CSS
+    #
+    # Returns a framework-agnostic hash of design tokens.
+    # No external dependencies — pure regex parsing.
+    class DesignTokenIntrospector
+      attr_reader :app
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call
+        root = app.root.to_s
+        tokens = {}
+
+        # Priority order: check each source, merge found tokens
+        extract_built_css_vars(root, tokens)
+        extract_tailwind_v4_theme(root, tokens)
+        extract_tailwind_v3_config(root, tokens)
+        extract_scss_variables(root, tokens)
+        extract_css_custom_properties(root, tokens)
+        extract_webpacker_styles(root, tokens)
+        extract_component_css(root, tokens)
+
+        return { skipped: true, reason: "No design tokens found" } if tokens.empty?
+
+        {
+          framework: detect_framework(root),
+          tokens: tokens
+        }
+      rescue => e
+        { error: e.message }
+      end
+
+      private
+
+      def detect_framework(root)
+        gemfile = File.join(root, "Gemfile")
+        return "unknown" unless File.exist?(gemfile)
+        content = File.read(gemfile, encoding: "UTF-8", invalid: :replace, undef: :replace)
+
+        if content.include?("tailwindcss-rails")
+          "tailwind"
+        elsif content.include?("bootstrap")
+          "bootstrap"
+        elsif content.include?("dartsass-rails") || content.include?("sassc-rails") || content.include?("sass-rails")
+          "sass"
+        elsif content.include?("cssbundling-rails")
+          "cssbundling"
+        else
+          "plain_css"
+        end
+      rescue
+        "unknown"
+      end
+
+      # 1. Built CSS output (Tailwind v4, cssbundling-rails, dartsass-rails)
+      def extract_built_css_vars(root, tokens)
+        Dir.glob(File.join(root, "app", "assets", "builds", "*.css")).each do |path|
+          content = File.read(path, encoding: "UTF-8", invalid: :replace, undef: :replace) rescue next
+          extract_root_vars(content, tokens)
+        end
+      end
+
+      # 2. Tailwind v4 @theme blocks in source CSS
+      def extract_tailwind_v4_theme(root, tokens)
+        %w[app/assets/tailwind app/assets/stylesheets].each do |dir|
+          Dir.glob(File.join(root, dir, "**", "*.css")).each do |path|
+            content = File.read(path, encoding: "UTF-8", invalid: :replace, undef: :replace) rescue next
+            content.scan(/@theme\s*(?:inline)?\s*\{([^}]+)\}/m).each do |match|
+              match[0].scan(/--([a-zA-Z0-9-]+):\s*([^;]+);/).each do |name, value|
+                tokens["--#{name}"] = value.strip
+              end
+            end
+          end
+        end
+      end
+
+      # 3. Tailwind v3 config (regex on JS — handles nested color palettes)
+      def extract_tailwind_v3_config(root, tokens) # rubocop:disable Metrics/MethodLength
+        path = File.join(root, "config", "tailwind.config.js")
+        path = File.join(root, "tailwind.config.js") unless File.exist?(path)
+        return unless File.exist?(path)
+
+        content = File.read(path, encoding: "UTF-8", invalid: :replace, undef: :replace) rescue return
+
+        # Extract ALL hex/rgb/hsl color values with their context
+        # Pattern: 'key': '#hex' or "key": "rgb(...)" anywhere in file
+        content.scan(/['"]([\w-]+)['"]\s*:\s*['"]([#][\da-fA-F]{3,8})['"]/).each do |name, value|
+          tokens["tw3-#{name}"] = value
+        end
+
+        # Extract color shades: number keys with hex values (inside palette objects)
+        content.scan(/['"]?(\d{2,3})['"]?\s*:\s*['"]([#][\da-fA-F]{3,8})['"]/).each do |shade, value|
+          tokens["tw3-shade-#{shade}"] = value
+        end
+
+        # Extract named color strings: surface: '#ffffff'
+        content.scan(/(\w+)\s*:\s*['"]([#][\da-fA-F]{3,8})['"]/).each do |name, value|
+          next if name.match?(/\A\d/)
+          tokens["tw3-#{name}"] = value
+        end
+
+        # Extract fontFamily arrays
+        content.scan(/(\w+)\s*:\s*\[['"]([^'"]+)['"]/).each do |name, font|
+          tokens["tw3-font-#{name}"] = font if name.match?(/font|sans|serif|mono|display|heading/)
+        end
+      end
+
+      # 4. Bootstrap/Sass variable definitions
+      def extract_scss_variables(root, tokens)
+        %w[app/assets/stylesheets app/assets/stylesheets/config].each do |dir|
+          Dir.glob(File.join(root, dir, "**", "*.{scss,sass}")).each do |path|
+            content = File.read(path, encoding: "UTF-8", invalid: :replace, undef: :replace) rescue next
+            content.scan(/^\$([a-zA-Z][\w-]*)\s*:\s*([^;!]+)/).each do |name, value|
+              value = value.strip
+              # Skip computed values (references to other variables, functions)
+              next if value.match?(/\$\w|lighten|darken|mix|adjust|scale|rgba\(\$/)
+              tokens["$#{name}"] = value
+            end
+          end
+        end
+      end
+
+      # 5. CSS custom properties in stylesheet files
+      def extract_css_custom_properties(root, tokens)
+        %w[app/assets/stylesheets].each do |dir|
+          Dir.glob(File.join(root, dir, "**", "*.css")).each do |path|
+            content = File.read(path, encoding: "UTF-8", invalid: :replace, undef: :replace) rescue next
+            extract_root_vars(content, tokens)
+          end
+        end
+      end
+
+      # 6. Webpacker-era stylesheets (Rails 6)
+      def extract_webpacker_styles(root, tokens)
+        %w[app/javascript/stylesheets app/javascript/css].each do |dir|
+          full_dir = File.join(root, dir)
+          next unless Dir.exist?(full_dir)
+
+          Dir.glob(File.join(full_dir, "**", "*.{scss,sass,css}")).each do |path|
+            content = File.read(path, encoding: "UTF-8", invalid: :replace, undef: :replace) rescue next
+            # Sass variables
+            content.scan(/^\$([a-zA-Z][\w-]*)\s*:\s*([^;!]+)/).each do |name, value|
+              value = value.strip
+              next if value.match?(/\$\w|lighten|darken|mix/)
+              tokens["$#{name}"] = value
+            end
+            # CSS custom properties
+            extract_root_vars(content, tokens)
+          end
+        end
+      end
+
+      # 7. ViewComponent sidecar CSS
+      def extract_component_css(root, tokens)
+        dir = File.join(root, "app", "components")
+        return unless Dir.exist?(dir)
+
+        Dir.glob(File.join(dir, "**", "*.css")).each do |path|
+          content = File.read(path, encoding: "UTF-8", invalid: :replace, undef: :replace) rescue next
+          extract_root_vars(content, tokens)
+        end
+      end
+
+      # Helper: extract :root { --var: value } from CSS content
+      def extract_root_vars(content, tokens)
+        content.scan(/:root\s*(?:,\s*:host)?\s*\{([^}]+)\}/m).each do |match|
+          match[0].scan(/--([a-zA-Z0-9-]+):\s*([^;]+);/).each do |name, value|
+            tokens["--#{name}"] = value.strip
+          end
+        end
+      end
+    end
+  end
+end