rails-ai-context 5.27.0 → 5.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44038590682c51bc7722a4a5b587ee31b5b78f3842575b6386390a584038b81e
-  data.tar.gz: 4c7de07da1f44144291ba86e9bfc34ab3a3da893c0a159b8cfe99de284d3d3be
+  metadata.gz: f036023367c149fd14eb8bc96106167cbd0c4ec7f042673930c74472a7caf44e
+  data.tar.gz: 1289481c7e5749263b762ebb9cc41a25504b4355896fd2215d2916e669132b34
 SHA512:
-  metadata.gz: b581d96cb4ff655823a103c21527a53ddb71c3cb36d644a59485a796693001e247f6480b381d1f54ea8ec0995e175aa0389109fe1155bfbeea2dfeefd5566d9c
-  data.tar.gz: 61c4aa682dd49afaf780652300f41de2216a0bfbe0b6ed7e6ec188237c63eade5036fe2051ba6771f89e96803a0971811230e532a7c623d7a25d0bfb1f069df8
+  metadata.gz: 5ad0b4e2f8096894ceec5a5c9989472173e8fabd98c38b1e9fc5e4e0ac3b7d90ad49473d6808f592f5d5b0c6ca9c6a897d7d2d6d79a064bbff0b6a44da19a0aa
+  data.tar.gz: ea624bf293f2e40a49d0d62579ca10c224200ab9e0f6681cdeb3f62955a599024a9ced4179f701f907d0b6ab9c55d5240ba595243a428b7b3920d47aade0b8d2

data/CHANGELOG.md

@@ -5,6 +5,374 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.29.0] - 2026-09-23
+
+Twenty-three QA reports against v5.27.0, each one a wrong answer a reader
+could act on, plus what eight review rounds found in the fixes themselves.
+
+### Added
+
+- **Model payloads carry method counts and the model's own methods
+  uncapped.** `instance_method_count`, `class_method_count` and
+  `source_instance_methods` sit beside the capped `instance_methods` and
+  `class_methods` lists, on both tiers, so a reader can tell a cut list from
+  a whole one.
+- **The schema payload carries `declared_tables`**, what `db/schema.rb`
+  declares, on both tiers: nil for an app whose tables come from
+  `structure.sql` or the migrations.
+
+### Changed
+
+- **"Mounted Engines" is "Mounted Apps" everywhere it is printed**: the
+  `engines`, `routes` and `onboard` tools, the generated context files, and
+  the MCP `rails://engines` resource name. The stack overview line reads
+  `Mounted:` rather than `Engines:`. Half of what the list holds are plain
+  Rack apps. The payload key stays `mounted_engines`.
+- **A mount whose path the source does not spell out carries `path: nil`**
+  rather than the string `"unknown"`, and is printed without a path.
+- **`routes` reads a blank `controller` as no filter**, and a name that
+  normalizes to nothing (`_controller`) as matching nothing, where the empty
+  string used to match every route key.
+
+### Fixed
+
+- **A Sidekiq worker answers to its own name, and the bracket carries the
+  limit that governs it.** `job:"Billing::Invoices::CreateWorker"` answered
+  "No jobs found" for a worker the same tool had just listed, because the
+  single-job lookup read the ActiveJob list only. It reads both lists now, and
+  a name in neither is a not-found that names what exists. The listing prints
+  its "workers the introspector did not see" caveat whenever it prints
+  workers, rather than only when `config/sidekiq.yml` happens to exist, and a
+  `sidekiq_throttle` prints under the worker it throttles - 438 of 522 workers
+  on one app declared one and none of them showed it.
+- **onboard's async section reads the workers out of the hash it already
+  had.** The section counted jobs, mailers and channels, so an app whose
+  background work is 522 Sidekiq workers read as "4 mailers." and the section
+  disappeared entirely when workers were the only async code. The "not
+  covered" line no longer prints next to a worker list it contradicts.
+- **What an ActiveInteraction declares is read in one place.** A filter
+  declared inside another filter's block (`string :title` inside `hash
+  :order_params do`) is a key of that hash, not an input of the class:
+  `service_pattern` showed four inputs where `.filters` has two, and
+  `generate_test` passed the other two to `.run`, which drops them silently. A
+  subclass of the app's own base interaction is an interaction too, with its
+  parent's filters first, so `generate_test` stops emitting `.call`, which
+  `ActiveInteraction::Base` does not define. `GenericMacroListener` records
+  each call's own offset and its enclosing call's, which is what both tools
+  pair filters by.
+- **generate_test names the constant the file declares.** A path camelizes
+  through Ruby's inflector, which has not read the app's
+  `config/initializers/inflections.rb` on the static tier, so
+  `ai_reports/build.rb` gave `AiReports::Build` where the app defines
+  `AIReports::Build` - a constant nothing defines, in a spec that dies on
+  load.
+- **service_pattern looks for callers where the app keeps code.** The scan
+  named six `app/` directories, so a caller in `app/tools` or under `lib/` was
+  invisible. It reads every `app/` and `lib/` tree, plus whatever else a
+  booted app autoloads from, and says when the twenty-entry cap or its own
+  file ceiling left the list partial.
+- **schema tells a missing migration from a typo.** Booted, a table declared
+  in `db/schema.rb` and absent from the connected database answered "Did you
+  mean 'comments'?". The payload carries the declared tables beside the live
+  ones, so the answer names the migration that has not run, and the listing
+  header says the two counts disagree instead of pairing a live table count
+  with the file's version stamp.
+- **A validator under app/models/concerns is not a concern.** The type came
+  from the directory alone, so 37 `ActiveModel::Validator` subclasses on one
+  app were listed as model concerns used by nothing. They are listed as
+  validators - following the app's own validator base class, not one level of
+  compare - and looked up by the `validates_with`, or the validation option,
+  that wires them, in a model or in a concern's `included` block. The keys
+  `validates` reads for itself (`on:`, `if:` and the like) name no
+  validator.
+- **dependency_graph counts both header numbers over the same models.** The
+  model count was app-wide and the association count covered the fifty nodes
+  that survived the cap. Both are app-wide now, and the truncation note says
+  how many of the associations the cut graph draws.
+- **get_context reads the views Rails would resolve.** It handed `GetView`
+  the last segment of the controller path, so `Api::V1::Admin::OrdersController`
+  picked up `app/views/orders`, a directory of templates a background service
+  renders. The answer names the directory its views came from, and a
+  flat-directory fallback is labelled as one.
+- **analyze_feature finds a test by its path.** A spec whose feature word is a
+  directory (`spec/services/billing/invoices/create_spec.rb`) was dropped,
+  while the gap checker beside it already matched on the path. The suite's
+  own words stay out of the match - the `spec/` root, the type directory it
+  files a test under (`models/`, `requests/`), and the `_spec` suffix - so
+  `--feature models` is not every model spec.
+- **routes answers an exact controller key with its own routes.** A substring
+  filter returned a nested sibling's routes too (`api/v1/admin/orders` swept
+  in `api/v1/admin/orders/ai_data`), and `get_context` inherited it. A short
+  name still matches every controller that carries it.
+- **A template at the root of app/views is listed.** Its filename became a
+  directory group that matched nothing, so the header counted a file the body
+  never printed, and the controller-miss hint suggested a directory that does
+  not exist.
+- **A word in a quoted string is not an instance variable.** `view` reported
+  a chat handle inside a Ruby string literal as a template's ivar; the reader
+  strips string literals and keeps interpolation, in ERB tags and in the
+  Ruby template handlers (Jbuilder, Builder, `.ruby`), and `get_view`'s
+  hydrator reads through the same method. Whichever quote opens first owns
+  the literal, so an apostrophe inside `"Don't"` does not swallow the ivar
+  beside it.
+- **env_config tells a re-assignment from a tuple.** Two unconditional
+  assignments of one key rendered as `:file, :test`, which reads exactly like
+  `:mem_cache_store, { pool_size: 5 }`. The winner is named, with what it
+  overrode.
+- **env keeps one default per call site.** One label for every site said a
+  variable was optional while one of its reads was `ENV.fetch` with no
+  default, which raises `KeyError`. A fetch whose fallback is an expression
+  says its default is computed at runtime rather than claiming it has none,
+  and an `ENV["X"]` read says it is nil when unset, apart from the fetch
+  that raises.
+- **A Rack app attached with `match ... to:` is found.** `mount` is that call
+  with a name derived, and the exact-path form is what an app writes when an
+  unanchored mount would swallow a sibling path. It reaches `engines` and
+  `routes`, which names the mounted apps it counts instead of calling them
+  engine mounts, and the booted tier lists every Rack endpoint rather than
+  `Rails::Engine` subclasses alone. A mount inside a `namespace` or `scope`
+  carries that prefix; one whose enclosing scope, or its `path:`, is an expression is listed
+  with no path rather than an unprefixed one, and every list prints it
+  without one. `engines` follows every file `config/routes.rb` draws,
+  through the walk the static `routes` answer uses, so on the static tier
+  the two name one set of mounted apps; booted, `routes` reads the live
+  route table. `engines`, `onboard`, the MCP resource and the
+  generated context files head the same list "Mounted Apps", because half of
+  what it holds are not engines. On the static tier a `match ... to: SomeApp`
+  is counted once, as the mount it is, rather than also as a construct the
+  walk could not expand, and so are `get "/status" => StatusApp` and
+  `mount ActionCable.server => "/cable"`, which the walk did not see at all.
+- **config calls a zero-byte initializer empty** rather than "all commented
+  out".
+- **Smaller corrections in the same pass.** `validate_semantics` asks the
+  loaded model class before calling a callback method missing, and on the
+  static tier makes no claim once the payload's method list was cut at its
+  cap, so an inherited method past the cap is no longer reported as missing.
+  `get_controllers` points
+  `rails_get_view` at the controller's full path rather than its last segment,
+  which is the directory Rails resolves. The stack overview's `Engines:` line
+  is `Mounted:`, because half of what it lists are plain Rack apps.
+- **diagnose stops reading a display cap as a model's whole interface.** A
+  method past the thirtieth was reported as not existing, in the same answer
+  whose Method Trace printed its definition. Booted, diagnose asks the loaded
+  model class, which knows a concern's methods and a gem's as well as the
+  model's own. Statically, the model's own methods travel uncapped beside the
+  capped display list, and where a concern or a parent could define the
+  method the answer declines rather than guesses. `model_details` says how
+  many of the model's methods it is showing.
+- **A CamelCase controller name resolves everywhere.** The needle was
+  downcased without being underscored, so "GiftCards" never equalled the
+  route key's own "gift_cards": `Payload.find_controller` missed it, and every
+  tool that resolves a controller through it missed it too. One normalization
+  now serves the payload, the routes tool and the MCP resource, and the
+  resource answers a name that resolves to nothing with an error naming what
+  exists rather than a zero-route success document.
+- **security_scan runs the brakeman the machine has.** The app's bundle
+  narrows the load path, so a machine with brakeman installed was told to add
+  it to the Gemfile while the other tier scanned the same app. When the
+  in-process require fails and the gem is installed, the scan runs it as its
+  own process outside the bundle - reading the report from a file of its own,
+  since a gem manager's binstub can print to stdout first - and renders the
+  result the same way, with a line saying which brakeman answered and from
+  where. When the outside run writes no report, the answer carries the last
+  line brakeman printed about why. With no brakeman anywhere, the message
+  says that instead of guessing, and the availability answer is keyed by
+  tier rather than decided once per process.
+- **An exact search with a space keeps its context lines on ripgrep 13.**
+  The literal was escaped with Ruby's `\ `, which ripgrep 13 (Ubuntu 22.04,
+  Debian 12) rejects, so the search fell back to the Ruby scan and dropped
+  context lines and files with no listed extension. The space goes through
+  unescaped now, which both engines read the same way.
+
+## [5.28.0] - 2026-09-22
+
+Thirty-six changes an architecture survey of v5.27.0 asked for, nine of them
+defects where a user got a wrong answer, plus what three review rounds found in
+the fixes themselves.
+
+### Added
+
+- **Services, helpers, jobs and concerns are found wherever the app keeps
+  them.** The four tools globbed `app/<kind>` off the app root, so a packwerk
+  app whose services live under `packs/billing/app/services` was told it had no
+  services directory and may not use the pattern. Directory discovery reads
+  `PathResolver.dirs_for`, which already resolved packs, engines and
+  `extra_app_paths` for the payload side. `ConcernPaths.resolve` and
+  `ActiveSupportIntrospector` read the same resolver, so a concern's listing,
+  its lookup and its "Used By" line now agree on one app. Counts move on any
+  app with packs or engines. Each walk names the directory a file came from, so
+  two files of the same basename under different roots no longer collide, and a
+  tool that finds nothing names all three directory patterns it searched
+  instead of the conventional one alone.
+- **`RailsAiContext.debug_fail`.** About 258 rescue bodies in `lib/`
+  hand-rolled the same three lines: rescue the error, write a `DEBUG`-gated
+  warning to stderr, return a fallback. They call one method now, with every
+  message string and every fallback value unchanged. `exe/rails-ai-context`
+  shims it beside `log_warn`, because the standalone install path loads seven
+  files by hand and a converted rescue inside `install_mode.rb` would otherwise
+  raise `NoMethodError` after the removed-tool cleanup had already deleted
+  files.
+- **`PackageJson`.** GemLock's twin for the node side: `package.json` parsed
+  once per root, `dependencies` merged with `devDependencies`, capped by
+  `configuration.max_file_size` rather than by a constant no caller can reach,
+  and empty for anything it cannot read. A scope named after the package
+  counts, so an app reaching tailwind through `@tailwindcss/vite` keeps its
+  answer.
+
+### Removed
+
+- **`config.job_processor`, gone from `.ai-context.json` and from
+  `get_config`.** `ConfigIntrospector` parsed `config/sidekiq.yml` a second
+  time to publish it, and nothing read it: no renderer, no spec, no template.
+  The two readers disagreed, so a `:queues:` block written with weights,
+  `- [critical, 2]`, lost `critical` on the config side and kept it on the jobs
+  side, and one sidekiq.yml shipped two queue lists in one payload. The same
+  concurrency and queues stay under `jobs.sidekiq_config`, which
+  `get_job_pattern` already consumes, and `config.queue_adapter` still names
+  the adapter. Both sections sit in the standard and full presets, so no preset
+  loses the fact.
+- **`action_bindings` and `outlet_controllers`, gone from every Stimulus
+  controller entry.** Filling `action_bindings` read every ERB, HAML and Slim
+  file under `app/views` and `app/components` on every generation, and
+  `outlet_controllers` restated the outlets list one line above it. Nothing in
+  `lib/` read either key: `get_stimulus` renders outlets, and the compact
+  serializer touches the section through `controllers` and `total_controllers`.
+  Both keys leave the artifact, and one full pass over the view and component
+  trees leaves every generation.
+- **`Serializers::SectionGuard`, `DetailLevel::SCHEMA_ENUM` and
+  `Install::Program.select_tool_mode`.** SectionGuard was 15 lines forwarding
+  to `Tools::SectionFetch.usable?`; both callers sat in `SchemaAdapter`, which
+  is not a serializer, and `RouteCoverage` already called SectionFetch
+  directly. SCHEMA_ENUM went with its last reference when
+  `DetailLevel.schema(description)` replaced the same four-line input-schema
+  hash in 21 tools; every published schema is byte-identical, and
+  `rails_onboard` keeps its own literal because its levels are quick, standard
+  and full. `select_tool_mode` was a shim for `select_setup(surface).tool_mode`
+  with no caller left in `lib/`, and it cannot express the MCP-config-only
+  mode. `ModelIntrospector#sti_bases` and
+  `ControllerIntrospector#extract_permit_details` go with them; only their own
+  recursion and their own specs were calling them.
+
+### Changed
+
+- **`.github/instructions/rails-context.instructions.md` prints every gem
+  category.** `.first(6)` on the grouped Hash returned the first six pairs, so
+  the seventh category onward was dropped with nothing saying so, while
+  `.cursor/rules/rails-project.mdc` rendered the same grouping uncapped. One
+  payload, two gem lists.
+- **`.cursor/rules/rails-project.mdc` bolds `Global before_actions:`** like the
+  Claude and Copilot files. The three serializers each hand-wrote the same
+  ten-step overview and had drifted; `StackOverviewHelper#overview_lines`
+  states the body once and each renderer keeps only its frontmatter, title and
+  MCP hint.
+- **Puma settings are read inside blocks.** The hand-rolled recursion stopped
+  at the top level, so a `workers` line guarded by an environment conditional,
+  which is what the generated `puma.rb` ships, was invisible and the answer
+  read as no workers configured. `MethodCallListener` sees a receiverless call
+  at any depth. The cost of the widening is that nesting no longer hides a
+  setting, so a name set twice reports the last one wherever it sits. Also
+  `threads ENV.fetch("RAILS_MIN_THREADS") { 5 }, ENV.fetch("RAILS_MAX_THREADS")
+  { 5 }` reports 5 and 5 where it reported nothing, and the digit match is
+  anchored away from word characters, so `ENV.fetch("PORT_2", 3000)` no longer
+  reads as 2.
+- **`get_conventions`' frontend stack string reads parsed dependencies.**
+  `detect_frontend_stack` matched bare substrings against the raw file, with no
+  quotes at all, so `vite-plugin-ruby` on its own reported Vite. The markers
+  carry alternates where an exact name would have lost an answer the substring
+  caught: svelte or `@sveltejs/kit`, `@hotwired/turbo` or
+  `@hotwired/turbo-rails`.
+- **`api_introspector`'s codegen list reads parsed dependencies.** It searched
+  the file for the quoted tool name, so `openapi-typescript`, `orval` or
+  `@graphql-codegen/cli` named anywhere in `package.json`, an `overrides` block
+  included, counted as a client generator the app runs.
+- **`rails_generate_test` resolves a controller by the rule
+  `rails_get_controllers` uses.** It camelized the string and looked the result
+  up, so with `Admin::GiftCardsController` as the only gift-card controller,
+  `rails_get_controllers(controller: "gift_cards")` resolved and
+  `rails_generate_test(controller: "gift_cards")` answered "not found".
+  `Payload.find_controller` answers for both, with the camelize kept as the
+  fallback for a payload carrying no controllers at all.
+
+### Fixed
+
+Nine defects the survey confirmed against v5.27.0, and the defects three review
+rounds found in the work that fixed them.
+
+- **`onboard(detail: "quick")` no longer prints a guessed domain noun.** Eleven
+  ordered regexes read model, job and service names and stated the result as
+  plain fact with no confidence marker, so one model named `Message` made an
+  app "a messaging app". Quick mode now states what it measured: versions,
+  table, model and job counts, the frontend and the test framework.
+- **`api_namespaces` invented a namespace and missed one.** The two tiers
+  derived the list their own way. The booted regex kept a trailing slash on
+  `/api/users`, matched unanchored so `namespace :admin { namespace :api }`
+  reported `/api/v1` for an app that serves `/admin/api/v1`, and dropped a
+  route sitting at exactly `/api`. The static spelling got the segment boundary
+  wrong, so `/apidocs` reported `/api`. Both tiers read one anchored form.
+- **Turbo drive settings were double-counted for layouts.** `app/views/layouts`
+  was walked again after `app/views/**/*` had already reached it. The permanent
+  element pass threw its duplicate away through `uniq`; the drive settings did
+  not, so one attribute in a layout and one in a view printed as 3.
+- **The asset pipeline reported the wrong bundler and CSS framework.** Three
+  readers asked whether a package was present by searching the raw file for its
+  quoted name, so an app pinning CVE fixes in an `overrides` block was told
+  esbuild is its bundler and postcss its CSS framework, while the one reader
+  that parsed the file called the same app vite. Both answers landed in one
+  payload.
+- **`analyze_feature`'s Jobs, Mailers and Channels sections came from a glob.**
+  Each job's queue was read off its own `queue_as`, so a job inheriting the
+  queue from `ApplicationJob` was reported on a queue it does not use. The
+  three sections read the payload now, which carries what the booted tier
+  resolved, mailer actions and channel stream methods included. A section whose
+  payload entry is not there, because the `:jobs` introspector is off, is left
+  out rather than rendered from a directory walk.
+- **`performance_check` attributed queries to methods that are not actions.** A
+  `def` inside a nested class became a call site, and a one-line
+  `private def set_post` leaked its body into the action above it.
+  `ActionResolver` answers what an action is here, as it does everywhere else.
+  A second collision went with it: each body was found by searching the whole
+  file for the first `def <name>`, so a nested class defining the same name
+  earlier handed back its body and the real action was never scanned. The body
+  is cut from the lines the owner-filtered walk recorded, and `get_controllers`
+  and `get_context` share the seam. An empty owner filter falls back to the
+  line scan rather than answering nothing, and `def self.index` no longer
+  stands in for `def index`.
+- **A model whose only rule is `validate :method` printed its bullets under the
+  wrong heading.** `## Validations` was emitted only when the reflected list
+  had entries, and the custom bullets come from a second list that is disjoint
+  from it on both tiers, so they landed under Associations.
+- **Two ERB readers missed `<%== ... %>` and read a commented ivar as used.**
+  `check_instance_variable_usage` and `extract_local_variable_references` each
+  carried their own copy of the tag regex, byte for byte the same and neither
+  matching `ErbSource::TAG`. Both read `<%[=\-]?`, one optional character, so
+  `<%== title %>` parsed as a body of "= title" and the local never reached a
+  partial's expected locals. The comment skip was a second answer too:
+  `get_partial_interface` re-implemented it and `validate_semantics` never had
+  one, so `<%# @ghost %>` was reported as an ivar used in the view and not set
+  in the controller. Both readers ask `ErbSource` now.
+- **`rails_get_controllers` refused a name the VFS resource accepts.** VFS
+  resolved five ways, the tool two, so `controller: "gift_cards"` failed
+  against `Admin::GiftCardsController` while the resource answered off the same
+  payload. Both read `Payload.find_controller`, so a route key, an unambiguous
+  basename and the singularize and classify spellings now resolve in the tool
+  too.
+- **Two files behind one name no longer hide each other.** Once services,
+  helpers and concerns were read from packs and engines, a name could have more
+  than one file behind it. The ambiguous-service list printed
+  `app/services/<path>` for files that live under a pack, so two candidates
+  printed as two identical lines naming a file that exists in neither, and the
+  suggestion that followed handed back the name it had just refused. Paths
+  print from the app root, and a narrowing suggestion is offered only when some
+  candidate's relative path is unique. `rails_get_helper_methods` rendered the
+  first match as the whole module and listed the others under "Also defined
+  in" even when they declare different modules, so a file declaring
+  `Reports::DashboardHelper` was named under an `Admin::DashboardHelper`
+  heading; matches are split by the module each file declares.
+  `rails_get_concern` broke on the first directory that resolved, so an app
+  with both `app/models/concerns/trackable.rb` and
+  `app/controllers/concerns/trackable.rb` saw only the controller one. Every
+  "available" list is deduplicated where it is built.
+
 ## [5.27.0] - 2026-09-22
 
 ### Added

data/CONTEXT.md

@@ -88,6 +88,43 @@ Three senses inside the gem, and the payload one is wider than either everyday R
 
 The callable interface of a class as this gem reports it: the class's own public instance methods - a class nested in the same file is a separate owner, not part of the interface - minus framework-shaped `_` names, read source-first, with reflection minus the app-owned base as the honest fallback. `ActionResolver` is the one answer; controller and mailer are configurations of it, and a channel's "stream methods" are a narrower selection of the same reading.
 
+## Mounted app
+
+A Rack app the routing table attaches at a path, engine or not. `mount App =>
+"/path"` is `match("/path", to: App, via: :all, anchor: false)` with a name
+derived, so both spellings build the same endpoint and both are this. The
+payload key is `mounted_engines` for the sections that predate the widening;
+what it holds is every controller-less, non-dynamic endpoint the route set
+carries, which is what the count beside it has always counted.
+
+Distinct from a **Rails engine**, which is a `Rails::Engine` subclass whether
+or not anything mounts it, and which `rails_get_engines` lists separately under
+its loaded classes. The record key is `engine:` for the same reason the section
+key is `mounted_engines:` - it predates the widening, and what it holds is the
+mounted app's constant, engine or not.
+
+## Interaction filter
+
+What an ActiveInteraction service declares as its interface, and not the
+**filter chain** above, which is controllers. `Interaction` is the one answer
+for both tools that read it (`rails_get_service_pattern`,
+`rails_generate_test`), because a static answer that differs from the booted
+one is the divergence the module exists to end.
+
+**A nested filter is not an input.** `string :title` inside `hash
+:order_params do ... end` is a key of that hash: it never reaches `.filters`,
+and handing it to `.run` as a keyword argument is dropped without a word. So
+nesting is kept on the record rather than flattened, and only the top level is
+an input.
+
+**The chain is the class's, not the file's.** An interaction is often a
+subclass of the app's own base interaction rather than of
+`ActiveInteraction::Base`, and its filters are then the parent's first and its
+own after, which is the order `.filters` answers in. Following that chain needs
+the parent's source, which only the caller can find, so it arrives as
+`lookup` - a callable from a constant name to that class's source, and nil to
+stop at the one file.
+
 ## Filter chain
 
 Which filters a controller runs, and which of them a given action runs. `ActionFilters` is the one answer, and every controller surface reads its filter line from there, so no two answers can disagree about what a class inherits or skips. `for_controller` answers about the class; `for` answers about one of its actions. Both return `own`, `inherited` and `skipped`.

data/docs/ARCHITECTURE.md

@@ -110,11 +110,12 @@ flowchart LR
 
 The `Introspector` orchestrator runs configured introspectors and merges results.
 
-Three modules answer questions every introspector used to answer for itself:
+Four modules answer questions every introspector used to answer for itself:
 
 - **SourceScan** - one walk over a kind of app source, across every directory `PathResolver` resolves: `paths` stats, `each` reads, `classes` names by the declared constant
 - **EagerLoad** - loads a directory's constants for a booted-tier walk, one file at a time, so an unloadable file costs only itself
 - **GemLock** - which gems the app resolved and at what version, read once per lockfile and matched by exact name across GEM, GIT and PATH
+- **PackageJson** - which npm packages the app depends on, read once per `package.json`: present means named in `dependencies` or `devDependencies`, so an `overrides` pin is not a dependency, and `@tailwindcss/vite` counts as tailwindcss
 
 Two more answer a question a tool asks:
 
@@ -198,7 +199,6 @@ Result: controller and view tools automatically include relevant schema informat
 | `ToolGuideHelper` | MCP/CLI tool reference sections |
 | `TestCommandDetection` | Test framework detection |
 | `SectionFacts` | The facts every surface states about an app - auth, assets, associations, the filter chain, an unread entry's row, the static-tier notice - each rendered in one place |
-| `SectionGuard` | Whether a section resolved, so a refused one is not rendered |
 | `SectionMarkerWriter` | Writes a managed section into a file the user also owns |
 | `ContextModeDispatch` | Picks full or compact rendering for a run |
 

data/docs/INTROSPECTORS.md

@@ -126,7 +126,7 @@ end
 
 | Introspector | Key | What it extracts |
 |:-------------|:----|:-----------------|
-| JobIntrospector | `:jobs` | Background jobs, Sidekiq workers under `app/workers`, and mailers: queue, retries, `sidekiq_options`, schedules, and the `file:` each one is defined in |
+| JobIntrospector | `:jobs` | Background jobs, Sidekiq workers under `app/workers`, and mailers: queue, retries, `sidekiq_options`, any `sidekiq_throttle`, schedules, and the `file:` each one is defined in |
 | RakeTaskIntrospector | `:rake_tasks` | Custom rake tasks |
 
 ### Security & Auth
@@ -193,7 +193,7 @@ Passed to `SourceIntrospector.walk(path, key => Listener)` when a specific file
 
 | Listener | What it detects |
 |:---------|:---------------|
-| GenericMacroListener | Any receiver-less macro you name: `GenericMacroListener.new(:devise, :rate_limit)`. Returns args, values (with a source-slice fallback), options, option values and option nodes |
+| GenericMacroListener | Any receiver-less macro you name: `GenericMacroListener.new(:devise, :rate_limit)`. Returns args, values (with a source-slice fallback), options, option values and option nodes, 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 |
 | ChainedCallListener | Calls on a receiver: `ChainedCallListener.new(:includes)`, or `receiver: :inflect` to pin the receiver. Reports the receiver name |
 | ConfigAssignmentListener | `config.key = value` and `config.a.b = value` in initializers and `config/environments/*.rb`, plus bare `config.jwt do ... end` section references. Takes a root name (`:config` by default, e.g. `:DatabaseCleaner`) |
 | ClassDefinitionListener | Class definitions with their superclass, namespaces resolved |
@@ -202,7 +202,7 @@ Passed to `SourceIntrospector.walk(path, key => Listener)` when a specific file
 | SchemaDslListener | `schema.rb`: `create_table`, `t.string`, `t.index`, `add_foreign_key`, `create_enum` |
 | MigrationDslListener | Migration DSL: `create_table`, `add_column`, `add_index`, `add_reference`, and friends |
 | RoutesDslListener | `config/routes.rb`, resolving namespace/scope/resources nesting into flat routes; routing concerns (`concern` definitions replayed at each `concerns:` site), `with_options` defaults merged under each inner call, and the `as:`, `param:`, `module:`, `path:` and `only:`/`except:` options |
-| MountListener | `mount Sidekiq::Web, at: "/sidekiq"` and the hash form |
+| 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. Paths carry the enclosing `namespace`/`scope` prefix; a scope whose own name is an expression yields no path rather than an unprefixed one |
 | GemfileDslListener | `gem "name", "version"` and `group :development do ... end` |
 | RakeTaskDslListener | `namespace`, `desc`, `task` in `.rake` files |
 | EnvAccessListener | `ENV["KEY"]`, `ENV.fetch("KEY")`, `ENV.fetch("KEY", default)` |
@@ -233,6 +233,19 @@ Regex is the right tool, and stays, for:
 
 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:
+
+| Module | What it answers |
+|:-------|:---------------|
+| `DeclaredConstant` | The constant a source file calls its own class, against the one its path camelizes to |
+| `TableName` | The table a model reads, from its own declarations |
+| `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 |
+| `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 `CONTEXT.md` |
+
 ### Confidence tagging
 
 Every AST result carries a confidence tag:

data/docs/TOOLS.md

@@ -116,7 +116,7 @@ Full-stack feature analysis: models + controllers + routes + services + jobs + v
 
 ### `rails_get_context`
 
-Composite context: schema + model + controller + routes + views for a resource.
+Composite context: schema + model + controller + routes + views for a resource. Views come from the directory Rails resolves for the controller; a flat-directory fallback is labelled.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -140,7 +140,10 @@ Narrative app walkthrough for getting up to speed.
 
 ### `rails_get_schema`
 
-Database schema with column types, indexes, defaults, encrypted hints.
+Database schema with column types, indexes, defaults, encrypted hints. Booted,
+a table `db/schema.rb` declares and the connected database does not have is
+named as a migration that has not run, and the listing header says when the
+two table counts disagree.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -149,7 +152,7 @@ Database schema with column types, indexes, defaults, encrypted hints.
 
 ### `rails_get_model_details`
 
-AST-parsed model internals. Every result carries `[VERIFIED]` or `[INFERRED]` confidence tag.
+AST-parsed model internals. Every result carries `[VERIFIED]` or `[INFERRED]` confidence tag. The method list says how many of the model's methods it is showing.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -176,7 +179,10 @@ its concerns), not the order Rails registered them in.
 
 ### `rails_get_concern`
 
-Concern methods, source code, and which models include it.
+Concern methods, source code, and which models include it. A class under
+`app/models/concerns` that subclasses `ActiveModel::Validator` is listed as a
+validator rather than a concern, and its users are the models that name it in
+`validates_with`.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -201,7 +207,11 @@ Controller actions with inherited filters, render map, strong params. Includes s
 
 ### `rails_get_routes`
 
-Routes with code-ready helpers (`post_path(@record)`) and required params.
+Routes with code-ready helpers (`post_path(@record)`) and required params. A
+fully qualified controller key answers with its own routes only; a short name
+still matches every controller that carries it. Rack apps attached with `mount`
+or `match ... to:` are named with the path they answer on, when the source
+spells one out.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -216,7 +226,7 @@ Routes with code-ready helpers (`post_path(@record)`) and required params.
 
 ### `rails_get_view`
 
-View templates with instance variables, Turbo frames, Stimulus controllers, partial locals. Includes schema hints for detected ivars.
+View templates with instance variables, Turbo frames, Stimulus controllers, partial locals. Includes schema hints for detected ivars. A template directly under `app/views` is grouped as `(app/views root)`, which `path:` reaches and `controller:` does not.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -299,7 +309,9 @@ Brakeman static analysis: SQL injection, XSS, mass assignment, command injection
 |:----------|:-----|:--------|:------------|
 | `detail` | enum | `standard` | `summary`, `standard`, `full` |
 
-> Requires the `brakeman` gem. Gracefully reports "not installed" if missing.
+> Requires the `brakeman` gem. When it cannot be loaded, the answer says which
+> case it is: brakeman is nowhere on the machine, or it is installed and the
+> app's bundle does not carry it, which `--no-boot` scans around.
 
 ### `rails_performance_check`
 
@@ -349,7 +361,7 @@ Notable gems with versions, categories, and config file locations.
 
 ### `rails_get_env`
 
-Environment variables + credentials keys (values are never exposed). Scans `.rb`, `.rake`, ERB views and config YAML under `app`, `config` and `lib`; files matching `sensitive_patterns` (`config/database.yml`, credentials, keys) are never read, and the answer says so.
+Environment variables + credentials keys (values are never exposed). Scans `.rb`, `.rake`, ERB views and config YAML under `app`, `config` and `lib`; files matching `sensitive_patterns` (`config/database.yml`, credentials, keys) are never read, and the answer says so. A variable whose call sites pass different defaults is labelled as such rather than with one site's default; `detail:"full"` names each site's.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -365,7 +377,12 @@ Application and framework helpers with view cross-references.
 
 ### `rails_get_service_pattern`
 
-Service object interface, dependencies, side effects, callers.
+Service object interface, dependencies, side effects, callers. An
+ActiveInteraction's inputs include the ones it inherits, with the filters
+nested inside a `hash` filter shown under it. Callers are read from every
+`app/` and `lib/` tree, and on a booted app from any other directory it
+autoloads, and the page says when the twenty-caller display cap or the scan's
+own file ceiling left the list partial.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -376,7 +393,9 @@ Service object interface, dependencies, side effects, callers.
 
 Background job queue, retries, guard clauses, broadcasts, schedules. Sidekiq
 workers under `app/workers` are listed alongside the ActiveJob jobs, with
-their `sidekiq_options` and `perform` signature.
+their `sidekiq_options`, any `sidekiq_throttle`, and the `perform` signature. A
+worker that inherits its Sidekiq mixin from a base worker is one of them, and
+`job:` answers a worker name as well as a job name.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -414,7 +433,7 @@ ActionMailer mailers: every mailer class with its delivery actions and delivery
 
 ### `rails_get_engines`
 
-Rails engines: engines mounted in `config/routes.rb` (with known-engine descriptions) and loaded engine classes with route/model counts.
+What `config/routes.rb` mounts - engines and plain Rack apps alike, with known-engine descriptions, each with the path it answers on when the source spells one out - and loaded engine classes with route/model counts.
 
 *No parameters.*
 
@@ -506,7 +525,7 @@ Reverse file tail with level filtering and sensitive data redaction.
 
 ### `rails_diagnose`
 
-One-call error diagnosis with classification, context, git blame, and log correlation.
+One-call error diagnosis with classification, context, git blame, and log correlation. It does not call a method undefined when the model's method list could be missing one - a concern's, a parent's, or anything past the payload's own cap.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|

data/docs/TROUBLESHOOTING.md

@@ -256,6 +256,19 @@ bundle add brakeman --group development
 
 Without it, the tool reports "not installed" but the gem works fine otherwise.
 
+### "Installed on this machine but not in this app's bundle"
+
+The scan runs under the app's own bundle, so a brakeman installed globally is
+not on its load path. The tool falls back on its own: it runs the installed
+brakeman as a separate process outside the bundle and says so under the
+results. This message means that fallback produced no report either - the gem
+is there and the run failed. Run `brakeman` in the app directory to see what
+it hit, or add it to the Gemfile so the scan runs in-process:
+
+```bash
+bundle add brakeman --group development
+```
+
 ---
 
 ## Performance issues