coatepec 0.7.0 → 0.9.0

data/lib/coatepec/introspection/bounded_options.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Introspection
+    # Caps the array-valued entries of a sanitized validator options hash (see SafeOptions) for rails_model output:
+    # 249 country codes just say "allow-list", and the count plus flag beside a cut list keep it self-describing.
+    module BoundedOptions
+      module_function
+
+      def call(options, max)
+        options.each_with_object({}) do |(key, value), bounded|
+          bounded[key] = value
+          next unless value.is_a?(Array) && value.size > max
+
+          bounded[key] = value.first(max)
+          bounded["#{key}_count"] = value.size
+          bounded["#{key}_truncated"] = true
+        end
+      end
+    end
+  end
+end

data/lib/coatepec/introspection/controller.rb

@@ -1,17 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "route_entries"
+
 module Coatepec
   module Introspection
     # Returns bounded ActionController class metadata for a single controller,
     # for the rails_controller MCP tool. Pure reflection over an already-loaded,
     # already-gated class -- no request dispatch, no action execution, and no
     # evaluation of app-authored callback conditions.
-    # rubocop:disable Metrics/ClassLength -- Task 3 (route cross-referencing)
-    # adds genuinely cohesive functionality: routes_by_action, grouped_routes,
-    # route_data, and rails_routes exist solely to serve this class's single
-    # responsibility (reflect on one controller). Splitting them into a
-    # separate collaborator class would fragment that one responsibility
-    # across files for no readability gain, only to satisfy a line count.
+    # rubocop:disable Metrics/ClassLength -- the route cross-referencing methods serve this class's
+    # one responsibility (reflect on one controller); splitting them out would only satisfy a line count.
     class Controller
       NAME_PATTERN = /\A[A-Z]\w*(?:::[A-Z]\w*)*\z/
       MAX_ITEMS = 200
@@ -101,25 +99,20 @@ module Coatepec
         end
       end
 
-      # controller_path is the public, correctly-namespaced key Rails itself
-      # stores in a route's defaults (Admin::ReportsController =>
-      # "admin/reports"), so matching on it needs no name munging.
-      #
-      # Only Rails.application.routes is read, so a controller mounted inside
-      # an engine will report its actions as unroutable even though the
-      # engine's own route set reaches them. Introspection::Routes has exactly
-      # the same boundary today; it is documented in the README rather than
-      # silently absorbed.
-      # A route whose defaults[:action] is nil or empty (a mount or redirect)
-      # is skipped, not recorded under an empty-string action.
+      # Matches on controller_path, Rails' own key in route defaults ("admin/reports"), through
+      # RouteEntries so engine controllers resolve too. Routes with no action (mounts, redirects) are skipped.
       def routes_by_action(klass)
-        grouped_routes(klass).transform_values { |list| list.first(MAX_ITEMS).map { |route| route_data(route) } }
+        grouped_routes(klass).transform_values { |list| list.first(MAX_ITEMS).map { |entry| route_data(entry) } }
       end
 
       def grouped_routes(klass)
-        path = klass.controller_path
-        matching = self.class.rails_routes.select { |route| route.defaults[:controller].to_s == path }
-        matching.group_by { |route| route.defaults[:action].to_s }.reject { |action, _| action.empty? }
+        entries = controller_entries(klass.controller_path)
+        entries.group_by { |entry| entry.route.defaults[:action].to_s }.reject { |action, _| action.empty? }
+      end
+
+      def controller_entries(path)
+        RouteEntries.call(self.class.rails_routes)
+                    .select { |entry| entry.route.defaults[:controller].to_s == path }
       end
 
       # Differenced against the controller's full action_methods set, not the
@@ -128,19 +121,17 @@ module Coatepec
       # have every route whose action fell past the truncation point reported
       # here as a false positive, in the field the README calls the tool's
       # most actionable output. Bounded to MAX_ITEMS like every other
-      # collection in this payload; `grouped_routes` itself caps each route
+      # collection in this payload; `routes_by_action` itself caps each route
       # *list* but not its key count, so this is where that cap belongs.
       def routes_without_action(klass, routes)
         defined_actions = klass.action_methods.map(&:to_s)
         (routes.keys - defined_actions).sort.first(MAX_ITEMS)
       end
 
-      # path keeps Rails' raw spec, `(.:format)` suffix included, so a path
-      # string here is byte-identical to the same route as reported by
-      # rails_routes. Stripping it would make the two tools disagree about the
-      # same route.
-      def route_data(route)
-        { verb: route.verb.to_s, path: route.path.spec.to_s, route_name: route.name&.to_s }
+      # path and engine come off the entry, so they are byte-identical to rails_routes' values for the
+      # same route. An engine route's name is engine-local: reach it as `<mount name>.<route_name>_path`.
+      def route_data(entry)
+        { verb: entry.route.verb.to_s, path: entry.path, route_name: entry.route.name&.to_s, engine: entry.engine }
       end
 
       # Isolated as a class method purely so unit tests can stub it without

data/lib/coatepec/introspection/model.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "model_resolver"
+
 module Coatepec
   module Introspection
     # Returns bounded ActiveRecord schema and class metadata for a single
@@ -7,45 +9,48 @@ module Coatepec
     # reflection, no method dispatch on the resolved class beyond pure
     # introspection APIs.
     class Model
-      NAME_PATTERN = /\A[A-Z]\w*(?:::[A-Z]\w*)*\z/
+      FIELDS = %w[columns associations validators enums].freeze
       MAX_ITEMS = 200
+      MAX_OPTION_VALUES = 20
       EMPTY_TABLE_METADATA = { table_name: nil, primary_key: nil, columns: [] }.freeze
 
-      def initialize(name)
+      # Counts are always returned; lists are opt-in, so an omitted fields costs a few dozen bytes.
+      def initialize(name, fields: nil)
         @name = name
+        @fields = validate_fields!(fields || [])
       end
 
       def call
-        validate_name!
-        klass = resolve!
-        validate_active_record!(klass)
+        klass = ModelResolver.call(@name)
         build_metadata(klass)
       end
 
       private
 
-      # An abstract class (e.g. ApplicationRecord) has no real table, so
-      # table_name/primary_key/columns all raise if called against it --
-      # report empty/nil table data instead of crashing. Validators aren't
-      # table-dependent, so those are always attempted.
+      # An abstract class (e.g. ApplicationRecord) has no real table, so table_name/primary_key/columns all raise
+      # if called against it -- report empty/nil table data instead. abstract_class? is nil (not false) for a
+      # concrete class on Rails 7.1 and false on 8.1, so normalize it for version-stable JSON. enums, like
+      # validators, are in-memory class metadata needing no connection, so they are always collected.
       def build_metadata(klass)
-        # abstract_class? is a plain attr_accessor-backed predicate that is
-        # never assigned on concrete subclasses -- on Rails 7.1 it returns
-        # nil (not false) in that case, while Rails 8.1 returns false.
-        # Normalize to a genuine Boolean so JSON output is version-stable.
         abstract = klass.abstract_class? || false
         table = abstract ? EMPTY_TABLE_METADATA : table_metadata(klass)
-        {
-          name: klass.name, table_name: table[:table_name], primary_key: table[:primary_key],
-          abstract_class: abstract, columns: table[:columns],
-          associations: abstract ? [] : associations_for(klass),
-          validators: validators_for(klass),
-          # enum declarations are pure in-memory class metadata (populated
-          # when the `enum` macro runs in the class body) -- unlike columns
-          # and associations, they need no DB connection or real table, so
-          # this is attempted unconditionally, the same way validators are.
-          enums: enums_for(klass)
-        }
+        sections = { columns: table[:columns], associations: abstract ? [] : associations_for(klass),
+                     validators: validators_for(klass), enums: enums_for(klass) }
+        { name: klass.name, table_name: table[:table_name], primary_key: table[:primary_key], abstract_class: abstract,
+          counts: sections.transform_values(&:size) }.merge(sections.slice(*(FIELDS & @fields).map(&:to_sym)))
+      end
+
+      # The MCP schema enforces the enum; this guards the worker command against any other caller.
+      def validate_fields!(fields)
+        unless fields.is_a?(Array)
+          raise Coatepec::Error.new(:invalid_model_fields, "fields must be an array, got #{fields.inspect}")
+        end
+
+        unknown = fields - FIELDS
+        return fields if unknown.empty?
+
+        raise Coatepec::Error.new(:invalid_model_fields,
+                                  "fields must be among #{FIELDS.join(", ")}, got #{unknown.inspect}")
       end
 
       # A concrete model can still name a table that isn't there: a checkout
@@ -68,23 +73,6 @@ module Coatepec
         )
       end
 
-      def validate_name!
-        return if @name.is_a?(String) && NAME_PATTERN.match?(@name)
-
-        raise Coatepec::Error.new(:invalid_model_name, "#{@name.inspect} is not a valid constant name")
-      end
-
-      def resolve!
-        ::ActiveSupport::Inflector.safe_constantize(@name) ||
-          raise(Coatepec::Error.new(:model_not_found, "#{@name} could not be resolved"))
-      end
-
-      def validate_active_record!(klass)
-        return if klass.is_a?(Class) && klass < ::ActiveRecord::Base
-
-        raise Coatepec::Error.new(:not_active_record_model, "#{@name} is not an ActiveRecord model")
-      end
-
       def columns_for(klass)
         klass.columns.first(MAX_ITEMS).map do |column|
           { name: column.name, type: column.type.to_s, sql_type: column.sql_type, null: column.null,
@@ -159,12 +147,14 @@ module Coatepec
         nil
       end
 
+      # Rails instantiates one validator per declaration; a concern and the model body often declare the same one.
+      # De-duplicate on the raw validator: SafeOptions drops the Procs and Regexps that tell two apart.
       def validators_for(klass)
-        klass.validators.first(MAX_ITEMS).map do |validator|
+        klass.validators.uniq { |v| [v.class.name, v.attributes, v.options] }.first(MAX_ITEMS).map do |validator|
           {
             name: validator.class.name,
             attributes: validator.attributes.map(&:to_s),
-            options: SafeOptions.call(validator.options)
+            options: BoundedOptions.call(SafeOptions.call(validator.options), MAX_OPTION_VALUES)
           }
         end
       end

data/lib/coatepec/introspection/model_resolver.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Introspection
+    # Turns a rails_model name into an ActiveRecord class, or raises the structured error that says why not.
+    module ModelResolver
+      NAME_PATTERN = /\A[A-Z]\w*(?:::[A-Z]\w*)*\z/
+
+      module_function
+
+      def call(name)
+        validate_name!(name)
+        klass = ::ActiveSupport::Inflector.safe_constantize(name) ||
+                raise(Coatepec::Error.new(:model_not_found, "#{name} could not be resolved"))
+        validate_active_record!(name, klass)
+        klass
+      end
+
+      def validate_name!(name)
+        return if name.is_a?(String) && NAME_PATTERN.match?(name)
+
+        raise Coatepec::Error.new(:invalid_model_name, "#{name.inspect} is not a valid constant name")
+      end
+
+      def validate_active_record!(name, klass)
+        return if klass.is_a?(Class) && klass < ::ActiveRecord::Base
+
+        raise Coatepec::Error.new(:not_active_record_model, "#{name} is not an ActiveRecord model")
+      end
+    end
+  end
+end

data/lib/coatepec/introspection/route_entries.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Introspection
+    # Flattens a route set into application routes followed by one level of mounted-engine
+    # routes with the mount path prefixed, the way `bin/rails routes` shows them.
+    class RouteEntries
+      Entry = Struct.new(:route, :path, :engine)
+
+      def self.call(routes)
+        new(routes).call
+      end
+
+      def initialize(routes)
+        @routes = routes
+      end
+
+      def call
+        visible = @routes.reject { |route| internal?(route) }
+
+        visible.map { |route| Entry.new(route, path_of(route), nil) } +
+          visible.flat_map { |route| engine_entries(route) }
+      end
+
+      private
+
+      # Rails' own /rails/info routes; `bin/rails routes` hides them too. Guarded so unit-spec structs work.
+      def internal?(route)
+        route.respond_to?(:internal) && route.internal
+      end
+
+      # One level only, like RoutesInspector; an engine mounted at two paths appears under both.
+      def engine_entries(route)
+        return [] unless engine_mount?(route)
+
+        engine = route.app.rack_app
+        prefix = mount_prefix(route)
+        name = engine_name(engine)
+        inner_routes(engine).reject { |inner| internal?(inner) }
+                            .map { |inner| Entry.new(inner, prefix + path_of(inner), name) }
+      end
+
+      # `(.:format)` is on nearly every route and says nothing a caller acts on; `bin/rails routes` shows it, we don't.
+      def path_of(route)
+        route.path.spec.to_s.sub(/\(\.:format\)\z/, "")
+      end
+
+      # chomp only affects a mount at "/", whose junction is the one place a "//" could form.
+      def mount_prefix(route)
+        path_of(route).chomp("/")
+      end
+
+      # Only a ::Rails::Engine subclass is expanded or named; nothing else ever gets .name called on it.
+      def engine_mount?(route)
+        route.respond_to?(:app) && route.app.respond_to?(:engine?) && route.app.engine? &&
+          rails_engine?(route.app.rack_app)
+      end
+
+      def rails_engine?(rack_app)
+        defined?(::Rails::Engine) && rack_app.is_a?(Class) && rack_app < ::Rails::Engine
+      end
+
+      # Class.new(Rails::Engine) has a nil name; a fixed label keeps its routes tagged and boot-stable.
+      def engine_name(engine)
+        engine.name || "(anonymous engine)"
+      end
+
+      # engine.routes is a RouteSet whose .routes holds the Journey routes; anything else stays unflattened.
+      def inner_routes(engine)
+        return [] unless engine.respond_to?(:routes)
+
+        route_set = engine.routes
+        route_set.respond_to?(:routes) ? route_set.routes : []
+      end
+    end
+  end
+end

data/lib/coatepec/introspection/routes.rb

@@ -1,33 +1,69 @@
 # frozen_string_literal: true
 
+require_relative "route_entries"
+
 module Coatepec
   module Introspection
-    # Returns a bounded, filterable list of the target Rails app's routes,
-    # for the rails_routes MCP tool. Reads Rails.application.routes.routes
-    # only -- no console, no request dispatch.
+    # Returns a bounded, filterable list of the target app's routes for the rails_routes MCP tool: application
+    # routes by default, mounted-engine routes on request. Reads route tables only -- no console, no dispatch.
     class Routes
       MAX_LIMIT = 200
-      DEFAULT_LIMIT = 50
+      DEFAULT_LIMIT = 100
+      ENGINE_FILTERS = %w[include exclude only].freeze
+      COLUMNS = %w[name verb path controller action engine].freeze
+      COLUMN_KEYS = COLUMNS.map(&:to_sym).freeze
+      # Engine CRUD scaffolding was two thirds of a typical match; the payload states what the default withheld.
+      DEFAULT_ENGINES = "exclude"
 
-      def initialize(query: nil, limit: DEFAULT_LIMIT, offset: 0)
+      def initialize(query: nil, limit: DEFAULT_LIMIT, offset: 0, engines: DEFAULT_ENGINES)
         @query = query
         @limit = [limit || DEFAULT_LIMIT, MAX_LIMIT].min
         @offset = offset || 0
+        @engines = validate_engines!(engines || DEFAULT_ENGINES)
       end
 
       def call
-        matched = filtered_items
+        matched, excluded = partitioned_items
+        page(matched, excluded)
+      end
+
+      private
+
+      # Rows instead of one hash per route: the six key names were a third of every item's bytes.
+      def page(matched, excluded)
         {
-          items: matched[@offset, @limit] || [],
+          columns: COLUMNS,
+          rows: (matched[@offset, @limit] || []).map { |item| item.values_at(*COLUMN_KEYS) },
           matched: matched.size,
           limit: @limit,
-          offset: @offset
+          offset: @offset,
+          next_offset: next_offset_for(matched.size),
+          engines: @engines,
+          engines_excluded: excluded.size
         }
       end
 
-      private
+      # The MCP schema already enforces the enum; this guards the worker command against any other caller.
+      def validate_engines!(value)
+        return value if ENGINE_FILTERS.include?(value)
+
+        raise Coatepec::Error.new(:invalid_engines_filter,
+                                  "engines must be one of #{ENGINE_FILTERS.join(", ")}, got #{value.inspect}")
+      end
+
+      # Spelled out so a caller never has to infer a follow-up page from matched > limit.
+      # candidate > @offset guards limit 0, which would otherwise hand back the same offset forever.
+      def next_offset_for(matched_count)
+        candidate = @offset + @limit
+        candidate > @offset && candidate < matched_count ? candidate : nil
+      end
 
-      def filtered_items
+      # Query first, then the engine filter, so engines_excluded counts routes this exact query would have shown.
+      def partitioned_items
+        query_matches.partition { |item| engine_selected?(item) }
+      end
+
+      def query_matches
         items = all_items
         return items unless @query
 
@@ -35,19 +71,33 @@ module Coatepec
         items.select { |item| item.values.compact.any? { |v| v.to_s.downcase.include?(query_downcased) } }
       end
 
-      def all_items
-        self.class.rails_routes.map do |route|
-          defaults = route.defaults
-          {
-            name: route.name&.to_s,
-            verb: route.verb.to_s,
-            path: route.path.spec.to_s,
-            controller: defaults[:controller]&.to_s,
-            action: defaults[:action]&.to_s
-          }
+      # An engine's mount route has engine: nil -- it is an application route and stays under "exclude".
+      def engine_selected?(item)
+        case @engines
+        when "exclude" then item[:engine].nil?
+        when "only" then !item[:engine].nil?
+        else true
         end
       end
 
+      def all_items
+        RouteEntries.call(self.class.rails_routes).map { |entry| item_for(entry) }
+      end
+
+      # path comes off the entry: for an engine route it already carries the mount prefix.
+      def item_for(entry)
+        route = entry.route
+        defaults = route.defaults
+        {
+          name: route.name&.to_s,
+          verb: route.verb.to_s,
+          path: entry.path,
+          controller: defaults[:controller]&.to_s,
+          action: defaults[:action]&.to_s,
+          engine: entry.engine
+        }
+      end
+
       # Isolated as a class method purely so unit tests can stub it without
       # booting Rails -- Rails.application.routes.routes is otherwise only
       # reachable with a real, booted application.

data/lib/coatepec/mcp/defaults.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "../../coatepec"
+
+module Coatepec
+  module MCP
+    # Fills a tool's omitted inputs: call argument first, then .coatepec.yml, then the built-in.
+    module Defaults
+      BUILTIN = {
+        spec_run: { include_passing: false, include_stdout: "failures", timeout_seconds: 120 },
+        routes: { engines: Introspection::Routes::DEFAULT_ENGINES }
+      }.freeze
+
+      module_function
+
+      # Re-reads the file each call: a few hundred bytes, and an edit then applies to the next call.
+      def resolve(tool, project_root, **given)
+        configured = ProjectConfig.new(project_root).defaults_for(tool)
+        BUILTIN.fetch(tool).to_h do |key, builtin|
+          [key, given[key].nil? ? configured.fetch(key, builtin) : given[key]]
+        end
+      end
+    end
+  end
+end

data/lib/coatepec/mcp/response.rb

@@ -5,20 +5,17 @@ require "mcp"
 
 module Coatepec
   module MCP
-    # Builds the pretty-printed JSON `{ok: true, data:, meta:}` / `{ok: false,
-    # error:}` envelope that every Coatepec tool response wraps in a single
-    # text content block.
+    # Builds the compact JSON `{ok: true, data:, meta:}` / `{ok: false, error:}`
+    # envelope every tool response wraps in one text block.
     module Response
-      # Per-stream caps in Spec::Result bound stdout/stderr, but the fully
-      # assembled envelope (500 examples with long descriptions) can still
-      # exceed what an MCP client will accept, so cap it here -- the single
-      # place every tool response is built.
+      # Per-stream caps in Spec::Result bound stdout/stderr, but a fully assembled
+      # envelope can still exceed what an MCP client accepts, so cap it here.
       MAX_RESPONSE_BYTES = 1024 * 1024
 
       module_function
 
       def ok(data:, meta: {})
-        text = JSON.pretty_generate(ok: true, data: data, meta: meta)
+        text = generate(ok: true, data: data, meta: meta)
         return oversized_response if text.bytesize > MAX_RESPONSE_BYTES
 
         ::MCP::Tool::Response.new([{ type: "text", text: text }])
@@ -29,12 +26,22 @@ module Coatepec
           ok: false,
           error: { code: err.code.to_s, message: err.message, details: err.details }
         }
-        ::MCP::Tool::Response.new([{ type: "text", text: JSON.pretty_generate(payload) }], error: true)
+        ::MCP::Tool::Response.new([{ type: "text", text: generate(payload) }], error: true)
       end
 
       def oversized_response
         error(Coatepec::Error.new(:response_too_large, "Result exceeds the 1 MiB response limit"))
       end
+
+      # Compact by default: nothing downstream reads the indentation. COATEPEC_PRETTY=1 restores it for hand debugging.
+      def generate(payload)
+        ENV["COATEPEC_PRETTY"] == "1" ? JSON.pretty_generate(payload) : JSON.generate(payload)
+      end
+
+      # Per-call timing is the only per-call fact; project_root and environment live on rails_runtime_status.
+      def meta(started_at)
+        { duration_ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round }
+      end
     end
   end
 end