Introspectors
40 modules that extract structured data from your Rails application.
How introspectors work
Each introspector:
- Subclasses
Introspectors::Base, taking theapphandle - Examines a specific aspect of your Rails app (schema, models, routes, etc.)
- Returns a Hash with structured data, and raises on failure:
Introspector#callturns a raised section into{ error: msg }and logs a warning - Results are cached with TTL + SHA256 fingerprint invalidation
- Runs as part of a preset (
:standardor:full) or can be configured individually
Presets
:full (default) - all 40 introspectors
Full AI context. Covers every aspect of your app.
:standard - 17 introspectors
Lightweight subset for faster generation:
schema, models, routes, jobs, gems, conventions, controllers,
tests, migrations, stimulus, view_templates, config, components,
turbo, auth, performance, i18n
Preset comparison
graph LR
subgraph standard["Standard Preset - 17 introspectors"]
direction TB
S1["schema"] ~~~ S2["models"] ~~~ S3["routes"]
S4["controllers"] ~~~ S5["jobs"] ~~~ S6["gems"]
S7["conventions"] ~~~ S8["tests"] ~~~ S9["migrations"]
S10["stimulus"] ~~~ S11["view_templates"] ~~~ S12["config"]
S13["components"] ~~~ S14["turbo"] ~~~ S15["auth"]
S16["performance"] ~~~ S17["i18n"]
end
subgraph full_only["Full Preset adds +23"]
direction TB
F1["views"] ~~~ F2["database_stats"] ~~~ F3["api"]
F4["active_storage"] ~~~ F5["action_text"] ~~~ F6["action_mailbox"]
F7["rake_tasks"] ~~~ F8["assets"] ~~~ F9["devops"]
F10["seeds"] ~~~ F11["middleware"] ~~~ F12["engines"]
F13["multi_database"] ~~~ F14["frontend_frameworks"]
F15["initializers"] ~~~ F16["autoload"] ~~~ F17["connection_pool"]
F18["active_support"] ~~~ F19["credentials"] ~~~ F20["security"]
F21["observability"] ~~~ F22["env"] ~~~ F23["env_config"]
end
standard --> full_only
style standard fill:#3498db,stroke:#2980b9,color:#fff
style full_only fill:#9b59b6,stroke:#8e44ad,color:#fff
Custom list
RailsAiContext.configure do |config|
config.introspectors = %i[schema models routes controllers views]
end
All 40 introspectors
Core
| Introspector | Key | What it extracts |
|---|---|---|
| SchemaIntrospector | :schema |
Database tables, columns, types, indexes, defaults, check constraints, enum types, extensions |
| ModelIntrospector | :models |
Associations, validations, scopes, enums, concerns (AST-based). Both tiers merge what the included concerns declare, tagged from_concern:; a concern whose file could not be read is listed in concerns_unread, a base class whose file could not be read in bases_unread, and the number of concerns excluded_concerns hid in concerns_hidden |
| RouteIntrospector | :routes |
Routes with helpers, HTTP methods, constraints |
| ControllerIntrospector | :controllers |
Actions, filters, strong params, concerns, rescue_from handlers, rate limits |
| ViewIntrospector | :views |
View files, layouts, partials |
| ViewTemplateIntrospector | :view_templates |
Each template with its line count, ivars, rendered partials and Stimulus refs; each partial with its line count, model fields and helper calls |
Models & Data
| Introspector | Key | What it extracts |
|---|---|---|
| MigrationIntrospector | :migrations |
Migration files, versions, the schema actions each one takes. recent and pending entries are { version:, name: }, and the name is the migration class (CreatePosts) in both tiers |
| SeedsIntrospector | :seeds |
Seed file analysis |
| DatabaseStatsIntrospector | :database_stats |
Approximate row counts per table, plus dead rows on PostgreSQL |
| MultiDatabaseIntrospector | :multi_database |
Multi-database configuration |
Frontend
| Introspector | Key | What it extracts |
|---|---|---|
| StimulusIntrospector | :stimulus |
Controllers, targets, values, actions |
| TurboIntrospector | :turbo |
Turbo wiring with each entry's file and line: turbo_frames, model_broadcasts, explicit_broadcasts, stream_subscriptions |
| AssetPipelineIntrospector | :assets |
Asset pipeline configuration, manifests |
| FrontendFrameworkIntrospector | :frontend_frameworks |
React/Vue/Svelte/Angular detection |
| ComponentIntrospector | :components |
ViewComponent/Phlex: props, slots, previews |
Config & Infrastructure
| Introspector | Key | What it extracts |
|---|---|---|
| ConfigIntrospector | :config |
Cache store, session store, time zone, queue adapter, mailer settings, middleware stack, initializers, Current attributes, error monitoring |
| GemIntrospector | :gems |
Notable gems with versions and categories |
| ConventionIntrospector | :conventions |
Architecture markers (service objects, Hotwire, GraphQL and others), model patterns (STI, soft delete, state machines and others), directory structure, config files |
| I18nIntrospector | :i18n |
Locale files, translation keys |
| MiddlewareIntrospector | :middleware |
Rack middleware stack. The static tier declares an alternate source rather than an empty stack: without a booted app it answers only the file facts it can read. config.ru's top-level use and map calls (rackup) are read on both tiers with ConditionalMacroListener, each with the if it sits under; a map whose block runs the app itself is a path prefix, so the use calls inside it are listed instead of the map |
| EngineIntrospector | :engines |
Mounted engines |
| EnvConfigIntrospector | :env_config |
Per-environment config files: notable toggles (force_ssl, eager_load, caching, queue adapter), assigned config keys, plus the keys config/application.rb sets and each config_for file's keys |
| DevOpsIntrospector | :devops |
Puma config, Procfile, health check, Dockerfile, deployment tool |
Jobs & Services
| Introspector | Key | What it extracts |
|---|---|---|
| JobIntrospector | :jobs |
Background jobs and Sidekiq workers, read from app/jobs, app/workers and app/sidekiq, and mailers (anywhere under app/, by parent chain): queue, retries, sidekiq_options, any sidekiq_throttle, schedules, and the file: each one is defined in |
| RakeTaskIntrospector | :rake_tasks |
Custom rake tasks from the Rakefile, lib/tasks and rakelib; the app's generators (lib/generators), generator template overrides (lib/templates) and Railties under lib/ |
Security & Auth
| Introspector | Key | What it extracts |
|---|---|---|
| AuthIntrospector | :auth |
Authentication framework (Devise, etc.) |
| ApiIntrospector | :api |
API configuration, versioning, serializers |
Rails Features
| Introspector | Key | What it extracts |
|---|---|---|
| ActiveStorageIntrospector | :active_storage |
Attachments, variants, services |
| ActionTextIntrospector | :action_text |
Rich text attributes |
| ActionMailboxIntrospector | :action_mailbox |
Mailbox routing rules |
Analysis
| Introspector | Key | What it extracts |
|---|---|---|
| TestIntrospector | :tests |
Test framework, file counts, coverage hints |
| PerformanceIntrospector | :performance |
N+1 risks, missing indexes, counter_cache hints |
Runtime & Framework Internals
These introspectors map directly onto the internal RAILS_NERVOUS_SYSTEM checklist sections and capture framework-level surface that :config, :auth, and :middleware don't.
| Introspector | Key | Nervous-system § | What it extracts |
|---|---|---|---|
| InitializerIntrospector | :initializers |
§2 | Rails.application.initializers graph: name, owner, before:/after: edges, block source_location, per-file config/initializers/*.rb summary |
| AutoloadIntrospector | :autoload |
§3 | Zeitwerk presence, autoloaders (:main / :once) with collapsed + ignored dirs, autoload_paths, eager_load_paths, the root directories each loader holds (other engines' and push_dir roots, with the namespace they load under), custom inflections (acronym, plural, singular, irregular, uncountable, human) |
| ConnectionPoolIntrospector | :connection_pool |
§10 | Per-database adapter config: pool size, checkout_timeout, reaping_frequency, prepared_statements, advisory_locks, replica flag, connection-handler roles, automatic shard selector detection |
| ActiveSupportIntrospector | :active_support |
§17 | Concerns in app/**/concerns/ (ActiveSupport::Concern flags, included do/class_methods do blocks, each read from its own module with the modules it nests left out, a X = Module.new do block included; a namespace's file lists the modules it holds, not the namespace, and a file naming a class lists the concerns defined beside it, not the class), deprecators registry, MessageEncryptor/Verifier usage, notification subscriptions read from source (subscribe, monotonic_subscribe, attach_to), TaggedLogging config, common on-load hooks, cache store options |
| CredentialsIntrospector | :credentials |
§30 | Default + per-env encrypted files, master-key source (env:RAILS_MASTER_KEY vs file:config/master.key vs missing), require_master_key flag, arbitrary encrypted configs (config/*.yml.enc), top-level key names only (never values) |
| SecurityIntrospector | :security |
§32 | force_ssl, SSL options (HSTS expires/subdomains/preload), host_authorization hosts, ContentSecurityPolicy directives + report_only, PermissionsPolicy directives, CSRF config (protect_from_forgery, per_form_csrf_tokens, origin_check), cookie session options, Rails 7.2+ allow_browser usage |
| ObservabilityIntrospector | :observability |
§34 + §38 | ActiveSupport::LogSubscriber.log_subscribers catalog, AS::Notifications subscriber registry (pattern + count + sample class), ActionDispatch::ServerTiming middleware detection, Rails 8.1 event_reporter availability, log level + tags, canonical Rails event-name catalog (10 subsystems) |
| EnvIntrospector | :env |
§36 | Catalog of 30+ Rails-related ENV vars partitioned into set / unset; safe vars (RAILS_ENV, RAILS_MAX_THREADS, etc.) return values, sensitive vars (SECRET_KEY_BASE, DATABASE_URL, RAILS_MASTER_KEY, etc.) return redacted: true only; scans config//app//lib/ for app-specific ENV["X"] references |
AST-based introspection
The SourceIntrospector uses Prism AST parsing for model analysis. It is infrastructure shared by the introspectors above rather than an introspector you can enable: there is no :source key for config.introspectors.
It runs a single-pass Dispatcher that walks the AST once and feeds events to all registered listeners simultaneously. Model analysis uses the eight below by default; the rest are used through targeted walks (schema dumps, migrations, Gemfiles, rake tasks, initializers, components, and so on).
The 8 default Prism listeners
| Listener | What it detects |
|---|---|
| AssociationsListener | belongs_to, has_many, has_one, has_and_belongs_to_many, the polymorphic belongs_to of delegated_type, the belongs_to of acts_as_tenant (tenant defaults to :account), under the options of an enclosing with_options block; each record names its owner, the class or module it is written in |
| ValidationsListener | validates, validates_*_of, custom validate :method, under the options of an enclosing with_options block; each record names its owner, the class or module it is written in |
| ScopesListener | scope :name, -> { ... }, lambda { ... } and the block form; a scope declared in an each over a literal list, inline or a constant the file assigns (KINDS.each { \|k\| scope k, -> { ... } }), as one scope per element, tagged [INFERRED] |
| EnumsListener | Rails 7+ and legacy enum syntax, prefix/suffix options; each record names its owner, the class or module it is written in |
| CallbacksListener | All AR callback types including around_*, after_touch, after_initialize and after_find; after_commit with on: resolution; a callback object as the source wrote it (Normalizer, Normalizer.new), a block as [inline_block] with its declaration as written; if:/unless: kept as the source wrote them, and the options of an enclosing with_options block; the commit callbacks turbo-rails' broadcasts, broadcasts_to, broadcasts_refreshes and broadcasts_refreshes_to declare, each with the method it runs; before_/after_/around_<event> on a chain define_model_callbacks makes, kept when the same file defines it (honouring only:), and for a chain a library defines elsewhere (Paperclip's before_<attachment>_validate, after_post_process) only when the model walk asks, so the booted tier keeps the ones whose chain the model's __callbacks holds |
| MacrosListener | (each attribute macro and has_secure_password with its keyword options as written, under written) encrypts, normalizes, delegate, has_secure_password, serialize, store, has_one_attached, has_many_attached, has_rich_text, generates_token_for, attribute, alias_attribute, store_accessor, self.ignored_columns, has_secure_token, accepts_nested_attributes_for, attr_readonly, query_constraints, the turbo-rails broadcast macros (broadcasts, broadcasts_to, broadcasts_refreshes, broadcasts_refreshes_to), connects_to as written (a child carries its base's, with the base's name under declared_in), establish_connection (on the static tier a model whose class or base calls it is on a connection of its own), the class settings self.inheritance_column/store_full_sti_class/strict_loading_by_default/implicit_order_column/locking_column = as written, an aasm block's states, initial state, events and transitions, and model gems' class macros (GEM_MACROS: has_paper_trail, friendly_id, mount_uploader, monetize, pg_search_scope, acts_as_list and others) as written, without their block (Paperclip's has_attached_file by its name and attachment only) |
| MethodsListener | def/def self., visibility tracking, parameter extraction, class << self, the methods delegate and Forwardable's def_delegators/def_delegator define (public unless private: true, and with no end_location, since a delegation has no body), and the methods alias, alias_method, attr_*, define_method with a literal name, class_attribute and cattr_*/mattr_* define (an alias keeps its original's visibility and parameters; Active Support's accessors are public on the class and, unless an option turns them off, on instances); each def carries offset/end_offset, which SourceIntrospector.outside_defs pairs against a call's offset to tell a call on the same line as a def from one inside it; a Struct.new/Class.new/Module.new/Data.define block assigned to a constant is that constant's body (an ||= that finds the constant already defined assigns nothing, so its block is no one's body and what it holds is left out), and a def self.x in included do is marked class_methods_block like a def x in class_methods do; include_initialize: true adds the constructor a caller reports on its own |
| MixinsListener | include, prepend, extend, singleton_class.include and singleton_class.prepend (singleton_class.extend is not read), flagging the ones that reach the ancestor chain, as reflection reports them. ConcernMembership.owned_by credits Note.prepend X to Note |
The targeted-walk listeners
Passed to SourceIntrospector.walk(path, key => Listener) when a specific file needs reading. Several take arguments, so one class serves many callers.
| Listener | What it detects |
|---|---|
| ForeignEvalsListener | A class body's blocks evaluated on another receiver (translation_class.class_eval do, other.instance_eval do), outside any def, with every outermost call inside by the line it starts on, an if/unless condition left out. The model walk passes it beside the default listeners (ModelIntrospector::MODEL_LISTENERS) and moves what the blocks declare to "Declared on another class" |
| GenericMacroListener | Any receiver-less macro you name: GenericMacroListener.new(:devise, :rate_limit); any_receiver: true also counts base.macro, as a mixin's self.included(base) hook writes it. Returns args, values (with a source-slice fallback), options, option values and option nodes, proc_lines (the line each block, ->, lambda {}, proc {} or Proc.new {} argument opens on, as Proc#source_location gives it), plus the nesting: parent_offset is the offset of the target macro call whose block this one sits in, paired against each call's own offset rather than its line; each record names its owner, the class or module it is written in |
| ConditionalMacroListener | GenericMacroListener plus condition, the if/unless/case branches the call sits under (BranchConditions), as if Rails.env.test?. Controller filters read it through FilterMacroListener, so before_action :x if Rails.env.test? is listed with its condition |
| FilterMacroListener | ConditionalMacroListener plus callbacks, what each positional argument adds, named at its node: [:name, x] for a symbol, string or class, [:object, Klass] for an instance (Class for an anonymous class), [:lambda] for -> {} or lambda {}, [:block] for a proc, [:unread, source] for anything else. Used by ControllerFilters, so the static tier names each callback as the booted tier does |
| ConstructorMacroListener | Class-body macros that define a constructor: T::Struct const/prop, Dry::Struct attribute/attribute?, dry-initializer param/option (with extend recorded so a consumer can check for Dry::Initializer), and the attr_extras initializers, method_object and static_facade. Each record adds owner, the one-line source, and params as [kind, name, default] with lambda defaults read as the value they return. Used by rails_get_service_pattern, which keeps a record only when the class is that library's |
| GrapeApiListener | A Grape API class body: each class with its superclass, version (with using:) and prefix, each verb endpoint with the namespaces around it (namespace, resource(s), group, segment, route_param as :id) and the requires/optional names of the params block before it, and each mount. Calls inside an endpoint body are skipped. Used by GrapeEndpoints, which decides which classes reach Grape::API and builds each path the way Grape does, for rails_get_routes |
| ChainedCallListener | Calls on a receiver: ChainedCallListener.new(:includes), or receiver: :config to pin the receiver. Reports the receiver name |
| InflectionsListener | The acronym, plural, singular, irregular, uncountable and human rules an initializer gives ActiveSupport's inflector: called on the object ActiveSupport::Inflector.inflections(locale) yields (whatever the block names it, it and _1 included), on that call's result, a local assigned from it, or inside its instance_eval. Each rule carries values, its locale, and literals (nil when an argument is computed). Used by AppInflections, which applies the literal :en rules to a static run, and by the autoload introspector |
| ConfigAssignmentListener | config.key = value and config.a.b = value in initializers and config/environments/*.rb, plus bare config.jwt do ... end section references and settings written without = (<<, a call with arguments, +=/||=/&&=, a block), tagged write:. An assignment whose value is a config_for call carries config_for: (the YAML file it reads and its env:). An assignment whose value is a string or symbol written as one carries literal: true. An assignment whose value is not redacted carries the same arguments:, computed: and constants: MethodCallListener reports for the value as one argument. Takes a root name (:config by default, e.g. :DatabaseCleaner); the root on_load(:active_record) reads self.x = and base.x = for the block's first param inside that ActiveSupport.on_load block (not inside a nested class or def; inside Foo.class_eval self.x = is not read while base.x = still is; a class_eval on that self, that param or a root constant keeps the root), and a root named Receiver.method (Apartment.configure) binds that block's first param |
| ClassDefinitionListener | Class definitions with their superclass and the nesting a bare superclass is read in |
| NestedConstantsListener | The offset ranges of the modules and classes a class body nests, so a filter declared inside one is not read as the outer class's own. Used by ControllerFilters |
| ComponentStructureListener | ViewComponent and Phlex structure: renders_one/renders_many, slot methods, hash/array constant tables, case @ivar variant branching, CONST[@ivar] indexing |
| MiddlewareConfigListener | The app's own stack, reached through its config (config.middleware, Rails.configuration.middleware, app.config.middleware), through the app (Rails.application.middleware, app.middleware) or through the app's own application class (MyApp::Application.config.middleware, given as app_class:), never another rack stack: any other constant anywhere in the chain (MyEngine.config.middleware, GoodJob::Engine.middleware) is an engine's. Reads use, insert, insert_before, insert_after, unshift, swap, move_before, move_after, delete, and config.exceptions_app = as its own exceptions_app action |
| RouteFilesListener | The route files config/application.rb puts in config.paths["config/routes.rb"]: an assignment (a list, .mapped or not), <</push/concat, unshift/prepend, Rails.root.join and literal Dir[...] globs, each as set/append/prepend. A list the app computes is recorded as computed |
| AutoloadPathsListener | Autoload roots config/application.rb adds by hand: autoload_paths/eager_load_paths/autoload_once_paths appends, autoload_lib, and config.paths.add with eager_load:. Literal paths under the app root only |
| AutoloadIgnoreListener | The lib subdirectories autoload_lib(ignore:) and autoload_lib_once(ignore:) keep out of autoloading, as lib/<name>. Literal strings and symbols only |
| PreviewPathsListener | ViewComponent preview directories the config sets: view_component.previews.paths, preview_paths, preview_path, in the same literal forms as AutoloadPathsListener; with framework: :action_mailer, the mailer preview directories action_mailer.preview_paths and preview_path set |
| I18nLoadPathListener | Locale files config.i18n.load_path or I18n.load_path adds: +=, <<, push, append, concat, with Dir[]/Dir.glob around the same literal forms as AutoloadPathsListener |
| FixturePathsListener | Fixture directories a test helper sets: fixture_paths =/<</+=/push and the older fixture_path =, on self, config or a constant (<</push with no receiver too), in the same literal forms as AutoloadPathsListener plus File.expand_path("x", __dir__), File.expand_path("x", __FILE__) and File.join(__dir__, "x") when given the helper's file; a write whose path it cannot read records :unread |
| DefinitionFilePathsListener | Where a test helper points factory_bot: FactoryBot.definition_file_paths = (replaces the defaults) and <</+=/push/concat (adds), each write as { replace:, paths: } in the same forms as FixturePathsListener (unread: true when it cannot read every path, with paths holding those it could), and each FactoryBot.find_definitions/FactoryBot.reload as { load: }, in source order; ::FactoryBot counts |
| ViewPathsListener | View roots config/application.rb adds to config.paths["app/views"]: unshift puts one before app/views, <</push/concat after it, in the same literal forms as AutoloadPathsListener; a write whose path it cannot read is left out |
| NamespacedRootsListener | Roots config/application.rb or an initializer hands Zeitwerk under a namespace: push_dir(path, namespace: Const), as phlex:install writes, in the same literal forms as AutoloadPathsListener; a write whose path it cannot read is left out |
| SchemaDslListener | schema.rb: create_table, t.string, t.column, t.index, add_foreign_key, create_enum, create_schema, create_view, create_virtual_table, the ActiveRecord::Schema[x.y] version stamp (a nil one for the unstamped Schema.define of Rails before 7.0), and the comment the dumper writes for a table it could not describe. Names drop public. unless raw_names: is set, which SchemaReader uses to name them against the search path |
| MigrationDslListener | Migration DSL: create_table, add_column, add_index, add_reference, and friends |
| MigrationReplayListener | What a replay needs beside the DSL: def down, down/revert blocks, and t.timestamps |
| RoutesDslListener | config/routes.rb, resolving namespace/scope/resources nesting into flat routes (a controller: with a leading slash is absolute, as in Rails); routing concerns (concern definitions replayed at each concerns: site), with_options defaults merged under each inner call, match ... via: (or the via: of an enclosing scope) as one route answering each verb it names (GET|POST, and ANY for via: :all, as the booted table has it), the controller a scope(controller:) or a route's own controller: names (with Rails' a/b shorthand when no action is given), and the as:, param:, module:, path:, shallow_path:, shallow_prefix: (a resource's own ones too, as the scope Rails draws it in) and only:/except: options. A block Ruby runs more than once and the walk does not unroll (2.times, LOC.each_key, an each over a list it cannot read) counts each routing or file-method call in it as unexpanded, except a Rack app it attaches, which MountListener lists; tap, then and yield_self blocks on the mapper draw in place, and a call such a block makes on the parameter Ruby hands the mapper (tap { |m| m.get "x" }, an optional |m = 1| too) draws as a receiverless one. A mount takes the route name Rails gives it, so a later route at that name is unnamed: its as:, else an engine's railtie name read from its file or its app class underscored; a constant ending in Engine whose file the app does not hold takes none, since only that file names it. as: nil takes no name on Rails 8.1 and the default one before it, and an app with no Rails version known takes 8.1's rule. A block drawn through an app class (ApiRouteSet::V1.draw(self) do) takes the path and as: prefixes that class's self.prefix and mapper_prefix return as literals, or a literal prefix argument; a class whose prefix is not a literal, and that class's own resources, are counted as unexpanded. Routes drawn into an engine's table (Shop::Core::Engine.routes.draw) sit under the engine's namespace and carry engine:, which the route introspector files under that engine's mount, apart from the app's count. A file pulled in by draw is walked inside the scope its draw sits in, once per scope that draws it, so draw :api under namespace :api and scope module: :v1 routes to api/v1/... at /api/.... A resource's nested do block draws under the parent's nested path, as a direct child would. A block from any other method draws in place only for constraints, defaults, Devise's devise_scope/as/authenticate/authenticated/unauthenticated and route_translator's localized; any other block that holds routes (an app's api_v1 do, versionist's api_version) may scope them in a way the walk cannot see, so its routes are left out and the block is counted once as unexpanded |
| MountListener | mount Sidekiq::Web, at: "/sidekiq", the hash form, and a Rack app attached with match "/metrics", to: MetricsApp - mount is that call with a name derived. It walks beside the RoutesDslListener of the same file and asks it where a resource scope attaches an app. Paths carry the enclosing namespace/scope prefix; a scope whose own name is an expression yields no path rather than an unprefixed one, and scope path: nil or scope nil adds no segment. A mounted app built by a call on a constant (Flipper::UI.app(Flipper)) is named by that call, arguments off; a mount of a value a constant holds (mount APPS[:admin] => "/admin") is listed at its path with an [INFERRED] app. A bare class name reads as the constant Ruby finds through Module.nesting among those the file declares (mount UI inside module Admin that declares UI is Admin::UI). A constant the routes file assigns once (with =, or an ||= that assigns it) reads as its value wherever Ruby's lookup reaches it (Module.nesting where it is read, then the top level; a path through the module its head names): TO = "posts#index" makes get "a", to: TO a route, ALIAS = HealthCheck names the app HealthCheck, and a lambda is no app. An app built with .new is named as the booted tier names it: an instance (BUILT = Rack::Builder.new { }, mount HealthCheck.new, AL.new with AL = HealthCheck) by its class, a Class.new or ::Class.new by the constant. A constant holding any other call reads as that call written in place: a verb route to it ("posts#index".freeze, ENV.fetch(...)) is dynamic; a mount of it is named by what builds it (FAPP = HealthCheck.app(1) as HealthCheck.app), lists an [INFERRED] app for one another constant holds (APPS[:a]), and is counted as unexpanded for a call with a block (Rack::Builder.app do) or on a value ("x".freeze). A verb route to a bare all-caps constant the file does not assign (to: TARGET), which may hold a "controller#action" string, is not listed as an app; a path such as to: Api::V1 is. An app attached inside a resource, member or collection is listed at the path the routes walk draws there (/posts/:post_id/hc); one inside a resource the walk cannot read (resources RES do), or a block in a resource that does not draw in place, has no path, since Rails attaches it where the walk cannot see. An app in a body the routes walk replays is listed once per replay at that site's path, as Rails draws it: a concern's at each concerns call and concerns: option, a routes-file method's at each call, a literal list's each block once per element and a resources :a, :b block once per name; a path, scope or as: a loop binds (mount X, at: v, as: "x_#{v}") is read through it. A site replays each definition of the name that may be in force there, as Rails runs the last one defined: one per arm of an if/else or case that defines it in each, a later definition replacing an earlier one when every branch it is written under is one the earlier one is written under (a branch counts by its text, so a second if ENV["A"] block is the same branch). An earlier one a later one under one other if/unless may replace carries the opposite of that branch, the run where it stays in force; a case, an &&/|| guard or nested ifs add no opposite. Each definition replayed there takes route names from those taken before the site, as the run that draws it does, and a later route finds taken any name one of them took. A definition the walk never replays (a concern the file never applies or applies only in a file another draw reads, one a later definition replaced before any call) and a method called with arguments are listed once where they are written, the concern's apps with no path. A mount under if/unless/case carries that condition; one a replay draws carries the site's conditions, then those its definition is written under (one the site states counts once), then its own |
| GemfileDslListener | gem "name", "version", group :development do ... end and eval_gemfile "path" (a literal or File.expand_path("x", __dir__)) with the groups around it; ruby "3.3.6" with its engine: and engine_version:; an :unknown_gems entry for gemspec and for a gem or eval_gemfile whose argument is not a literal |
| RakeTaskDslListener | namespace (with the span its block covers), desc, task, multitask in .rake files |
| EnvAccessListener | ENV["KEY"], ENV.fetch("KEY"), ENV.fetch("KEY", default), and the ENV name Rails 8.2's Rails.app.creds or Rails.app.envs require/option reads (option(:database, :host) is DATABASE__HOST) |
| MailboxRoutingListener | Action Mailbox routing and processing callbacks |
| ModelReferenceListener | Model constants used in controllers: Post.find, params.require(:post), ivar writes |
| VariantCallListener | variant calls (ChainedCallListener with :variant preset) |
| ProcLiteralListener | Proc literals: line, source, assigned constant |
| QueueAssignmentListener | A queue a class body assigns outside any method: Resque's @queue = :name, Que's self.queue = "name", or a def self.queue returning one, a literal as its value, anything else as source |
| RequestCallListener | The requests a test sends: get, post, put, patch, delete, head and visit with a literal path, an interpolated path or a route helper, and a "GET /posts" group name. TestFramework::Suite matches them against the route table in draw order |
| HttpClientCallListener | Calls on an HTTP client constant (Faraday, Net::HTTP, HTTParty, RestClient, HTTP, Excon, Typhoeus, URI.open) with a literal URL, bare, wrapped in URI(...)/URI.parse(...) or as url:, and the host Net::HTTP.start/.new takes. The env section of rails_get_config names external services from it |
| ConstantReferenceListener | References to constants by last name, qualified or not (ActiveSupport::MessageVerifier), skipping one that only qualifies a nested constant (MessageVerifier::InvalidSignature) and mentions in comments or strings. Used by the ActiveSupport introspector for message verifier and encryptor usage |
| MethodCallListener | Call sites by name or pattern anywhere in a file, inside a def, a lambda or a block included, with arguments, options, receiver, line, offset, the owning class or module, and constants: (each argument that is a constant, or builds one with .new, mapped to the constant's name). Used by the Turbo introspector for broadcast calls, the ActiveSupport introspector for notification subscriptions, and others |
GenericMacroListener.new(*names, block_source: [:name]) adds block, the
one-line source of the block those macros are given. call_source: [:name]
adds text, the one-line source of the whole call (the Mongoid index reader). ProcLiteralListener is
what the job introspector reads a queue_as Proc with.
Adding a listener
- Subclass
BaseListenerinlib/rails_ai_context/introspectors/listeners/. Use its helpers rather than re-reading nodes:extract_symbol_args,extract_keyword_options,extract_arg_values(source-slice fallback for expressions like2.hours),extract_keyword_sources,extract_keyword_nodes,keyword_hash,constant_path_string. - Implement the
on_*_node_enterhooks you need and push plain hashes onto@results. Never return Prism nodes as the result itself;option_nodesis the one deliberate exception, for callers that must inspect an expression's shape. - Nothing to register.
ListenerRegistrationreads the events off theon_*methods you defined, inherited ones included, and raises if one names an event prism never dispatches. - Add a spec of the same name under
spec/lib/rails_ai_context/introspectors/listeners/. - Add a row to the table above.
Choosing between AST and regex
Use the AST when the thing you want is a Ruby construct: a macro call and its arguments, a method definition, a class and its superclass, an assignment, a constant, a case. If you find yourself running a regex over text you already parsed, that is a parse of a parse. Fix it at the node.
Regex is the right tool, and stays, for:
- Files that are not Ruby.
Gemfile.lock, YAML (database.yml,sidekiq.yml, fixtures),structure.sql, Dockerfiles, ERB, HAML, Slim, JavaScript. - Mixed-extension globs. A view scan spanning ERB and Phlex
.rbneeds one matcher, or the two halves drift apart. - Vocabulary classification. "Does this middleware body talk about auth?" is about words, not structure; no node carries it.
- A prefilter before the parse. Parsing every
.rbunderapp/to find the handful that declare something costs more than a line match that ends the read; the AST still decides, on the files the match keeps. - Anything the listeners cannot scope. Tying a call to the enclosing action or
namespaceblock needs block scope the listeners do not track, so those fall back to line scanning.
A regex kept over Ruby source runs on the text RubySource gives it, so a comment or a string cannot match. RubySource.without_comments blanks comments, =begin blocks and the __END__ section; RubySource.code_only also blanks string, heredoc, backtick and regex bodies. Both keep every line and character offset, so a match still points at the file. To capture a string a call takes (render "posts/form"), match the without_comments text and keep a match only where the same offset in the code_only text is not blank. A template's Ruby comes from ErbSource (tag_bodies, or masked to keep the template's offsets).
Every remaining regex over .rb content carries a one-line comment saying which of these it is. If you add one without a reason, convert it instead.
Readers built on the listeners
Some questions take more than one walk to answer, and the answer has to be the
same wherever it is asked. Those live as their own modules under
Introspectors/, and a tool calls one rather than repeating the walk. The
last two rows, RubySource and ErbSource, are the text readers in
lib/rails_ai_context/ that a regex over Ruby or ERB reads through:
| Module | What it answers |
|---|---|
DeclaredConstant |
The constant a source file calls its own class, against the one its path camelizes to, and the static tier's one rule for naming a written class, module or constant: the full name each open or write gives (declare, full_name), Module.nesting inside a body or at a listener record (body_nesting, record_nesting), the names Ruby tries for a reference (candidate_names), and the innermost class or module a line sits in, as written (enclosing; a class << self body is its class's), which rails_search_code and rails_get_edit_context name a line by |
ActionPresence |
Whether a controller has an action: the public methods and define_method names of the controller, its ancestors up to Rails' base and the modules they include, the templates at each ancestor's view prefix, and the ancestors or modules no app source holds, which leave a missing action unverified. rails_validate and rails_generate_test both ask it |
ControllerSettings |
The layout a controller renders in (declared on it or an ancestor, else the layouts/<controller_path> file Rails finds by name, walking up the chain) and the allow_browser, protect_from_forgery, add_flash_types, default_form_builder and wrap_parameters calls it and its ancestors make. rails_get_controllers and rails_get_view both ask it |
TableName |
The table a model reads, from its own declarations |
ActiveRecordSettings |
What config/application.rb, the environment file and the initializers set on Active Record: the table affixes, pluralize_table_names and schema_format, in the order Rails applies them, and which of them an assignment gives a value only the running app computes. Read once per introspection run or tool call |
HabtmJoinTables |
The join tables every has_and_belongs_to_many under the app's code and lib names, lib patches and engines included, for the schema's model-less table warning |
SuperclassChain |
What a class inherits from, followed through the app's own sources: the chain from a file's class up to a named base, and the constant-to-source lookup over the app's autoload roots that walks it |
CallSiteExpansion |
What one call of a mixin's macro-declaring method declares. attachable :receipt, has_one: true runs def attachable(name, opts = {}), whose body declares has_one name or has_many name by opts[:has_one]: the parameters bind to the call's literal arguments, and a branch (if, unless, case) the literals decide is taken alone. Where they cannot decide, what every way through declares alike is listed once; the rest, a lone if's body included, comes back under :conditional with its condition and is not counted. A block the method evaluates on another receiver (other.instance_eval) comes back under :foreign, named with the receiver and any condition it runs under |
Includers |
Which classes and modules mix a module in, by include, prepend or extend: a written name resolves from the includer's namespace outward, and the nearest module the app declares decides. rails_get_concern's "Included by", the service listing and the HABTM join-table owners all ask it |
RetryPolicy |
What a job does when it raises, as a reader would write it: the macro, its exceptions, then attempts: and wait: whatever order the source put them in |
SourceCalls |
Which other classes a file hands work to, off the call nodes: the verb list, the framework receivers left out, and the call or the class alone |
ServiceClasses |
Which classes under app/services, app/interactions and app/interactors are services and which are only the base of one, for the tool's listing and the generated files' line alike |
EnvReferences |
Every ENV name the app's source reads, file by file, for rails_get_config's env section and the context file's env section alike: app, config and lib Ruby, ERB and config YAML, config.ru, db/seeds and the bin/ scripts whose shebang is Ruby, with config YAML on sensitive_patterns read for the names in its ERB tags only. fetch_default gives what an ENV.fetch falls back to (a second argument, or a block's one statement), which the puma settings and a database.yml adapter read as the value with the variable unset |
AnywayConfigs |
Each Anyway::Config class under config/configs and app/configs, every class in a file, with the attributes its own body declares (a nested class keeps its macros) and the env name anyway_config reads each from: env_prefix, else config_name, else the name before Config. rails_get_config(section:"env") lists them |
GemfileGems |
The one Gemfile read, off GemfileDslListener: its entries with options and groups (the gems section's local gems and groups) and the gem names (every other asker), so a commented-out gem line is no gem anywhere; a file named by eval_gemfile is followed when it is inside the bundle's directory (the app root, or the directory of the Gemfile config/boot.rb points at), and one it cannot read is an :unknown_gems entry. GemLock takes the declared Ruby and the gem names from it once the gem is loaded; the walk is kept until one of the files changes. Before the boot, GemLock walks the one Gemfile with AstWalk instead and leaves eval_gemfile unread |
ModuleAliases |
Which app file a bare JS import specifier names: tsconfig/jsconfig compilerOptions.paths followed through extends (relative files and installed packages), and a vite/webpack/rspack resolve.alias written as a literal object. The Stimulus scan uses it to tie a registration or a base class to the controller file it imports |
RenderCalls |
A template's render calls read as RenderingHelper#render reads them: each call's argument text, the partial it names, the folder a bare name is looked up in (the view's own, then application/), and the locals it hands over, a collection: or object: record among them. In an ERB or Ruby template a call counts only where the template's Ruby makes it (code_text, through ErbSource.masked for ERB), so a render in a comment, a string or page text is none; HAML and Slim are read whole. The view introspector, rails_get_view and rails_get_partial_interface all read them here |
HelperNames |
The helper methods a view can call: every method the app's helper modules define in every code root, and those of a module they include, found through the app's autoload roots (lib among them) or in its enclosing namespace's file (CanonicalURL::Helpers in canonical_url.rb). rails_get_partial_interface uses it so a helper call is not read as a local |
Interaction |
Whether a class runs as an ActiveInteraction, following its superclass chain through the app's own sources, and the filters it takes - inherited ones first, one per name, each carrying the filters nested inside its block. See the Interaction filter entry in GLOSSARY.md |
RecurringSchedules |
The recurring tasks each scheduler reads from its own file: Solid Queue's config/recurring.yml, sidekiq-cron's config/schedule.yml, sidekiq-scheduler's section of each config/sidekiq*.yml, GoodJob's config.good_job.cron and whenever's config/schedule.rb. The job introspector hands it its own config walk, so a file it also reads for queue or mailer settings is walked once |
AdminResources |
The models an admin gem exposes (ActiveAdmin, Trestle, Administrate, Avo, Madmin), from the folder each gem's generator writes to, with ActiveAdmin's permit_params. rails_get_config(section:"conventions") and rails_analyze_feature both ask it |
SchemaDumpPath |
The primary database's dump file as DatabaseTasks.schema_dump_path names it: database.yml's schema_dump in the configured schema_format, then each format's default file, and the secondary databases' dumps. Every schema reader, the doctor and the pending-migration check ask it |
ApartmentConfig |
The models an Apartment initializer keeps in the shared schema (excluded_models), or the source of a list the file computes. The model introspector asks it to say which models get one table per tenant |
SchemaReader |
What a schema.rb dump declares: tables, columns, defaults, indexes, foreign keys, enum types and check constraints. SchemaReader.for(root) answers from whichever source the app committed: schema.rb, structure.sql, or a migration replay |
StructureSqlReader |
A structure.sql dump (PostgreSQL, MySQL or SQLite) as the same table shape the other static schema sources produce |
MigrationReplay |
The tables of an app with no schema dump, replayed from its migrations in the dump readers' shape |
SchemaConventions |
The Rails schema conventions every static source must agree on: the implicit id key and its type per adapter, what a reference declares, what t.timestamps expands to |
PgNaming |
How Rails' PostgreSQL connection and schema.rb dumper name extensions, enum types and relations, by Rails version, so the static tier names them as the booted app does |
RailsVersion |
The app's Rails version (the running one when booted, else the lockfile's), which picks the rules every static schema source answers by |
SqliteVirtualTables |
SQLite's virtual tables and their shadow tables, read from sqlite_master. The schema and database stats introspectors ask it |
RenderedRecord |
The records a bare render @post.comments hands to Rails, and the partial Rails renders for them. rails_get_partial_interface and the view template introspector ask it |
NodeSource |
A node's source with the bodies of the heredocs it opens, which Prism's slice leaves out |
RubySource |
Ruby source with what Ruby never runs blanked to spaces, every line and character offset kept: without_comments blanks comments, =begin blocks and __END__, and code_only also blanks string, heredoc, backtick and regex bodies, keeping their delimiters and the code in #{}. It loads Prism, so code that runs before the app boots must not call it |
ErbSource |
The Ruby in a template's tags, read as Erubi reads them (<%% is text, <%# a comment): tag_bodies joins the code tags with their Ruby comments blanked, and masked keeps the whole template in place with its text, delimiters and comments blanked and each tag read as code_only reads it |
Confidence tagging
Every AST result carries a confidence tag:
[VERIFIED]- All arguments are static literals (strings, symbols, numbers). Ground truth.[INFERRED]- Arguments contain dynamic expressions (variables, method calls). Requires runtime verification.
has_many :posts → [VERIFIED]
has_many :posts, class_name: name → [INFERRED] (name is a variable)
AstCache
Thread-safe parse cache using Concurrent::Map:
- Keyed by: the SHA256 hash of the file's content, so a changed file is parsed again
- A file whose stat (mtime, size, inode) matches the last read answers without reading or hashing it, but only once that file was already two seconds older than the read, so a same-size rewrite within one mtime tick is still read
- Bounded at 500 parses; a recorded stat is dropped with its parse
- Shared by all AST-based introspectors
- Cleared on
reset_all_caches!(when a server sees the files change: live reload, or the check at each call)
RunCache
Answers kept for one introspection run and dropped when it ends: the file list for a source kind, each file's stat, the directories a kind lives in, concern directories and listings. A section asking again inside the run gets the first answer; the next run, and any tool called after it, asks the filesystem again.
Cache invalidation
Introspection results are cached at three levels:
- Introspection cache - Full context hash, invalidated by TTL (
config.cache_ttl, default: 60s) and, in a server, as soon as the fingerprint changes - AST cache - Per-file parse results, invalidated by file content change (SHA256), with a stat shortcut for a file older than the read
- Run cache - File lists, stats and directory answers for one introspection run, dropped when it ends
The Fingerprinter reads one set of files: all watched directories (app/, config/, db/, lib/, rakelib/, test/, spec/), the Gemfile and Gemfile.lock (or gems.rb and gems.locked), package.json, tsconfig.json, config.ru, the Rakefile, the scripts in bin/, and the other root files a reader opens or checks for (Dockerfile, Procfile, docker-compose.yml, CI and deploy configs, JS lockfiles and bundler configs, Ruby version files). Each file counts by its path and its mtime, so a rename is a change too. When one of them changes, a server drops the introspection cache even if the TTL hasn't expired, and in the booted tier reloads the app's code first, so what reflection reads (an association, an enum) is current too, wherever the app can reload. Under RAILS_ENV=test, or in production with eager loading, config.enable_reloading is off and Rails keeps the code it booted with: what reflection reads stays as of boot (validations and callbacks are read off the source, so they still follow the edit), and once a file under the app's autoload paths changes, every answer ends with a note naming it and asking for a restart.
- Every server - stdio, HTTP, or the endpoints mounted inside the app - checks before each tool call and resource read, so an answer sees every edit made before the call began.
Fingerprinter::Snapshotstats each watched directory and file and lists a directory again only when its stat moved: about a millisecond on a small app, about 30 ms at 10,000 files. Only a check that began after a call arrived stands in for that call's own, so calls one after another each check and calls made at once wait for one check together. Inside a request the app serves, Rails' own reloader has already reloaded the code. - Live Reload (the
listengem: the app's bundle's, or for the standalone binary one installed beside it) watches these directories and notifies connected MCP clients vianotify_resources_list_changed. It loads none of the app's code and drops no cache: a change reaches it after the 1.5-second debounce, and by then the call that followed the edit has checked the files itself.