Ruby/Rails autoloader-aware import resolution — graph is ~95% edge-starved on Rails projects

[kimadactyl]

Summary

On Rails (and any Zeitwerk-autoloaded Ruby project) the import resolver finds almost nothing, which collapses the entire downstream graph: cross-file imports/depends_on edges are missing, layer assignment falls back to path heuristics, and the LLM batch agents have no neighborMap data to work with. Run /understand on a non-trivial Rails monolith and you'll see roughly one edge per node — a fraction of the real connection density.

Repro

Run /understand on any Rails 6/7/8 app. I tested on a ~1,200-file Rails 8 codebase (PlaceCal):

Metric	Value
Files analyzed	1,158
imports edges emitted	22
calls edges emitted	4
inherits edges emitted	68 (before LLM review pass)
Total non-contains/exports edges	~150

By comparison, the same project's actual ActiveRecord association graph alone has hundreds of cross-file relationships.

Root cause

packages/core/src/languages/configs/ruby.js defines the Ruby language config but provides no resolver for class-name → file-path mapping. The structural extractor reads tree-sitter output and looks for explicit require/require_relative statements, of which a Rails app has almost none — Zeitwerk autoloads everything.

So when a controller references a constant:

class PartnersController < ApplicationController
  def show
    @partner = Partner.find(params[:id])  # <-- this is a cross-file reference
  end
end

the scanner sees Partner as a free identifier and emits no edge. The downstream effect is that batchImportData is empty for ~99% of Ruby files, so file-analyzer subagents have no inter-batch signal and the architecture-analyzer falls back to path patterns.

Proposal

A Rails-aware (or more generally, Zeitwerk-aware) resolver bundled with the Ruby plugin. Two concrete pieces:

1. Constant → file resolver. At scan time, build an index of ClassName::ChildClass → app/models/class_name/child_class.rb using Zeitwerk's standard inflection rules (app/, lib/, plus configurable load paths). When tree-sitter sees a constant reference, look it up in the index and emit an imports (or depends_on) edge. The lookup is fast and entirely deterministic.

2. ActiveRecord DSL recognizer. belongs_to, has_many, has_one, has_and_belongs_to_many are first-class structural facts. A small tree-sitter query over each model file can emit them as depends_on (or a new associates edge type) to the singularized target. Similarly validates_* and scope are noise; delegate :foo, to: :bar is signal worth surfacing.

Stretch:

3. config/routes.rb resolver. Parse the routes DSL and emit routes edges from URL patterns to controller actions. This is the single biggest grouping signal in any Rails app and is currently invisible.
4. RSpec convention pairings. spec/models/partner_spec.rb tests app/models/partner.rb. Filename mirroring is a strong enough heuristic to emit tested_by edges without LLM intervention — the LLM review pass currently does this manually 60+ times per project.

Workarounds I've tried

• /understand --review (the LLM graph-reviewer pass) recovered ~270 edges by reading whole files and pattern-matching, which is the right shape but the wrong layer — this should be a deterministic scanner job, not an LLM tax paid on every run.
• Tightening .understandignore to pack each batch with more related files helps the in-batch LLM but does nothing for cross-batch edges.

Why this matters

Rails is one of the most-deployed server frameworks in the world and the second-most-common language in your languages/configs/ directory. The current output for Rails projects is misleading enough that the dashboard and tour underrepresent how the app actually fits together — and the gap isn't visible to users unless they happen to know what edges should be there.

[thejesh23]

Agree with the diagnosis, broadly agree with the proposal — but flagging up front: @Lum1104 wrote the RubyExtractor and the original language configs (feat: add RubyExtractor for tree-sitter Ruby structural analysis), so worth waiting on his read before locking in an approach. He's likely already weighed pros/cons of constant-resolver shapes vs DSL recognition vs LLM review and could shortcut a lot of this discussion.

Verification of the diagnosis

Walked the code; the claims hold up:

• packages/core/src/languages/configs/ruby.ts is purely declarative (extensions, concepts, file patterns) — no resolver.
• packages/core/src/plugins/extractors/ruby-extractor.ts:9, :188-208 only treats require/require_relative as imports. The extractor sees Partner.find (records Partner as receiver text) but nothing resolves the receiver to a file.
• skills/understand/extract-import-map.mjs:1036-1052, :1572 routes Ruby through a dedicated parseRubyImports / resolveRubyImport pathway with three load-path probes (lib/, app/, root). No Zeitwerk inflection, no constant index.
• packages/core/src/languages/frameworks/rails.ts is detection + layerHints only.

So the ~95% edge starvation is structurally believable on any Zeitwerk app.

Architecture fit

The repo already has the exact pattern needed — buildResolutionContext (extract-import-map.mjs:344-406) loads per-language project metadata once and indexes files, with per-language resolvers dispatched at :1420. Edge types imports, depends_on, inherits, tested_by are already in schema.ts:5-8. A Zeitwerk resolver slots in cleanly alongside Go (go.mod), PHP (PSR-4), and Java/Kotlin/C# (suffix indices).

Where I'd push back / refine

1. Constant resolution must be lookup-aware, not just FQN-based. The repro case (Partner.find(...)) is a bare constant; the proposed ClassName::ChildClass → path rule only covers fully-qualified refs. Pragmatic shape: build a project-wide ConstantName → filePath index once (mirrors buildSuffixIndex at extract-import-map.mjs:906-924). Resolve bare Foo via the index, Admin::Foo via inflected path. On collision, leave unresolved.

2. Parse config/application.rb autoload paths. Real Rails apps add engine dirs, lib/, Packwerk packs. Without this, monolith engines stay edge-starved. Fallback gracefully to Zeitwerk defaults if the config can't be parsed.

3. Don't introduce an associates edge type. It would touch schema.ts, types.ts, normalize-graph.ts, and dashboard legend/colors. Comment belongs_to :post is exactly the semantic of Comment depends_on Post — reuse depends_on. Keep the DSL recognizer; drop the new edge type.

4. config/routes.rb is a rabbit hole — scope it down for v1. The routes DSL is procedural Ruby (namespace, scope, constraints, nested resources, mount). Concrete v1 cut: top-level get/post/put/patch/delete '<path>', to: 'ctrl#action' + bare resources/resource :name. Defer nested/scoped blocks.

5. Cover Minitest too, not just RSpec. Rails ships with Minitest by default — test/models/partner_test.rb ↔ app/models/partner.rb. RSpec is a popular but optional gem.

6. Extend the constant resolver to include/extend/concerns. include Trackable → inherits (or implements) edge via the same resolver. Cheap once the index exists.

7. Sequence into PRs, add a regression fixture. Different review surfaces:

   • PR1: Zeitwerk constant resolver + AR DSL → depends_on (biggest signal, smallest schema risk)
   • PR2: routes.rb top-level DSL
   • PR3: Minitest/RSpec pairings → tested_by

   Pin a small Rails fixture and assert edge counts so the "150 → ~270" improvement is testable, not eyeballed. The graph-reviewer LLM pass is the natural reference baseline.

Bottom line

Diagnosis is correct, architecture fit is good, proposal is ~90% right. Main asks: reuse depends_on instead of a new edge type, make constant resolution scope-aware via a project-wide index, parse config/application.rb (with safe fallback), scope routes DSL down, cover Minitest, ship as 3 PRs with a fixture test.

But — deferring to @Lum1104 before anyone starts implementing, since he's been closest to the Ruby pipeline.