Make density-based explainers Rails-aware (depth, god-class, surface, hotspots)

Follow-up to the layers/cycles tuning: three explainers still misfired on
autoloaded, framework-heavy, public-by-default codebases.

- dependency-depth: count an oversized coupling cluster (SCC) as one logical
  layer instead of its full size, so a giant autoload cluster no longer reports
  every chain through it as an extreme depth.
- god-class, hotspots: exclude framework/base scaffolding classes (Application*,
  *BaseController, *::Base) via a Ruby-gated helper -- high fan-in through
  inheritance isn't a god class.
- exported-surface: skip Ruby symbols; public-by-default makes the
  exported/total ratio ~100% and uninformative.
- explain hotspots: compute module blast radius over the module graph instead of
  an all-node reverse count that saturates in a densely-coupled graph.

Explainer-only, no extractor change, so no cacheVersion bump.

Author: dejo1307

internal/explainers/common/common.go

@@ -12,6 +12,15 @@ import (
 	"github.com/enola-labs/enola/internal/facts"
 )
 
+// OversizedClusterModules is the module-count above which a strongly-connected
+// component is treated as a coupling *cluster* rather than a discrete, actionable
+// tangle. In an autoloaded language (Ruby/Rails) mutual constant references across
+// many directories are the expected topology, so a large SCC is a coupling-density
+// signal, not a fixable cycle or a genuine deep layering. Shared by the cycles
+// explainer (softens such SCCs into a cluster note) and the depth explainer (counts
+// such an SCC as one logical layer instead of its full size).
+const OversizedClusterModules = 8
+
 // FileDir returns the directory portion of a file path, which enola uses as the
 // canonical module name. A path with no separator maps to ".".
 func FileDir(file string) string {
@@ -147,6 +156,48 @@ func BuildModuleGraphExcluding(store *facts.Store, excludeKinds ...string) map[s
 	return graph
 }
 
+// rubyFrameworkBaseClasses are exact Rails/framework base-class names whose high
+// fan-in comes from being inherited, not from being a god class.
+var rubyFrameworkBaseClasses = map[string]bool{
+	"ApplicationRecord": true, "ApplicationController": true, "ApplicationJob": true,
+	"ApplicationMailer": true, "ApplicationService": true, "ApplicationSerializer": true,
+	"ApplicationCable": true, "ApplicationPolicy": true, "ApplicationInteractor": true,
+	"ApplicationPresenter": true,
+}
+
+// rubyBaseClassSuffixes are naming conventions for user-defined base classes
+// (NotifierBase, ApiBaseController, Pusher::Base, ...). A class named like this is
+// a base others inherit from, so its inbound degree is inheritance, not coupling.
+var rubyBaseClassSuffixes = []string{
+	"BaseController", "BaseJob", "BaseService", "BaseMailer", "BaseSerializer",
+	"BasePolicy", "BasePresenter", "BaseInteractor", "Base",
+}
+
+// IsRubyFrameworkBaseSymbol reports whether a symbol is a Rails/framework base
+// class — one whose high fan-in is a product of inheritance (every subclass
+// "depends on" it) rather than a design smell. Gated on a .rb file so non-Ruby
+// symbols are never affected. Used by the god-class and hotspots explainers to keep
+// framework scaffolding (ApplicationRecord/Controller/Job, *BaseController, *::Base)
+// out of their findings while still surfacing genuine central domain types.
+func IsRubyFrameworkBaseSymbol(name, file string) bool {
+	if !strings.HasSuffix(file, ".rb") {
+		return false
+	}
+	seg := name
+	if i := strings.LastIndex(seg, "::"); i >= 0 {
+		seg = seg[i+2:]
+	}
+	if rubyFrameworkBaseClasses[seg] {
+		return true
+	}
+	for _, suffix := range rubyBaseClassSuffixes {
+		if strings.HasSuffix(seg, suffix) {
+			return true
+		}
+	}
+	return false
+}
+
 // SymbolModule returns the module a symbol belongs to. Symbol names encode the
 // module as the prefix before the first ".", e.g. "internal/auth.Login.Verify"
 // -> "internal/auth". Names without a "." are returned unchanged.

internal/explainers/cycles/cycles.go

@@ -16,8 +16,9 @@ import (
 // signal, not a defect. Such components are reported once as a softer,
 // lower-confidence "Highly coupled module cluster" note instead of an alarming
 // confidence-1.0 cycle with advice ("introduce an interface") that cannot
-// meaningfully be applied to a 99-node cluster.
-const maxCycleModules = 8
+// meaningfully be applied to a 99-node cluster. Shared with the depth explainer
+// via common.OversizedClusterModules.
+const maxCycleModules = common.OversizedClusterModules
 
 // maxClusterMembers caps how many representative members are listed as evidence
 // for an oversized coupling cluster.

internal/explainers/depth/depth.go

@@ -39,13 +39,17 @@ func (e *DepthExplainer) Name() string {
 //
 // Cycles are handled by collapsing each strongly-connected component to a single
 // super-node (the condensation), which is a DAG, then taking the longest path by
-// module count over that DAG. A component contributes its full size to any chain
-// passing through it. This is an intentional over-approximation: the exact
-// longest *simple* path is NP-hard, and inside a cycle every member is mutually
-// reachable, so counting the whole component is a safe cycle-safe upper bound
-// that never double-counts a module. A module's reported depth is its component's
-// depth; one insight is emitted per component (keyed by its smallest member),
-// so a cycle yields a single finding rather than one per entangled module.
+// module count over that DAG. A small component contributes its full size to any
+// chain passing through it (a genuine tangle deepens the chain). But an *oversized*
+// component (> common.OversizedClusterModules) is an autoload coupling cluster, not
+// deep layering — in Ruby/Rails mutual constant references collapse most of the app
+// into one giant SCC, and counting its full size would report every chain through it
+// as "depth ~100" (the cycle false-positive leaking into depth). Such a cluster is
+// therefore weighted as a single logical layer (componentWeight), so depth measures
+// real layering rather than cluster size; the cluster itself is already reported by
+// the cycles explainer. A module's reported depth is its component's depth; one
+// insight is emitted per component (keyed by its smallest member), so a cycle yields
+// a single finding rather than one per entangled module.
 func (e *DepthExplainer) Explain(ctx context.Context, store *facts.Store) ([]facts.Insight, error) {
 	graph := common.BuildModuleGraph(store)
 	if len(graph) == 0 {
@@ -109,7 +113,7 @@ func (e *DepthExplainer) Explain(ctx context.Context, store *facts.Store) ([]fac
 				best, bi = d, j
 			}
 		}
-		depth[i] = len(sccs[i]) + best
+		depth[i] = componentWeight(sccs[i]) + best
 		bestSucc[i] = bi
 		return depth[i]
 	}
@@ -170,13 +174,30 @@ func (e *DepthExplainer) Explain(ctx context.Context, store *facts.Store) ([]fac
 	return insights, nil
 }
 
+// componentWeight is how much a strongly-connected component contributes to a
+// dependency-chain's depth: its full member count for a small tangle, but just 1
+// for an oversized autoload cluster (which is one logical layer, not deep layering
+// — see the Explain doc comment).
+func componentWeight(scc []string) int {
+	if len(scc) > common.OversizedClusterModules {
+		return 1
+	}
+	return len(scc)
+}
+
 // chainFor reconstructs the deepest chain of distinct modules starting at
-// component i: all of i's (sorted) members, then the members of its best
-// successor component, and so on down the DAG.
+// component i: for a small component all of its (sorted) members, but for an
+// oversized cluster only a single representative (so the evidence chain length
+// stays consistent with the reported depth instead of dumping ~100 modules), then
+// its best successor component, and so on down the DAG.
 func chainFor(i int, sccs [][]string, bestSucc []int) []string {
 	var out []string
 	for i != -1 {
-		out = append(out, sccs[i]...)
+		if len(sccs[i]) > common.OversizedClusterModules {
+			out = append(out, sccs[i][0])
+		} else {
+			out = append(out, sccs[i]...)
+		}
 		i = bestSucc[i]
 	}
 	return out

internal/explainers/depth/depth_test.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/enola-labs/enola/internal/explainers/common"
 	"github.com/enola-labs/enola/internal/facts"
 )
 
@@ -223,6 +224,39 @@ func TestExplain_SelfImportDoesNotAddDepth(t *testing.T) {
 	}
 }
 
+// TestExplain_OversizedClusterNotDeep: a large autoload cluster (a ring of
+// OversizedClusterModules+3 modules) must count as ONE logical layer, not its full
+// size, so it does not masquerade as a deep dependency chain. With a short tail
+// below it the whole graph's real layering stays under minDepth and nothing is
+// reported — matching the cycles explainer already covering the cluster.
+func TestExplain_OversizedClusterNotDeep(t *testing.T) {
+	n := common.OversizedClusterModules + 3
+	mods := make([]string, 0, n+1)
+	deps := map[string][]string{}
+	ring := make([]string, n)
+	for i := 0; i < n; i++ {
+		ring[i] = fmt.Sprintf("c/m%02d", i)
+		mods = append(mods, ring[i])
+	}
+	for i := 0; i < n; i++ {
+		deps[ring[i]] = []string{ring[(i+1)%n]} // one big SCC
+	}
+	// A short 2-module tail hanging off the cluster: c/m00 -> t/t0 -> t/t1.
+	mods = append(mods, "t/t0", "t/t1")
+	deps["c/m00"] = append(deps["c/m00"], "t/t0")
+	deps["t/t0"] = []string{"t/t1"}
+
+	insights, err := New().Explain(context.Background(), makeStore(mods, deps))
+	if err != nil {
+		t.Fatalf("Explain: %v", err)
+	}
+	// Cluster weighted as 1 + tail(2) = depth 3 < minDepth(5) -> no findings, and
+	// crucially not a "depth ~N" report of the whole cluster.
+	if len(insights) != 0 {
+		t.Fatalf("oversized cluster should not produce a deep-chain finding, got %d: %v", len(insights), titles(insights))
+	}
+}
+
 func TestExplain_EmptyGraph(t *testing.T) {
 	insights, err := New().Explain(context.Background(), facts.NewStore())
 	if err != nil {

internal/explainers/godclass/godclass.go

@@ -90,6 +90,12 @@ func (e *GodClassExplainer) Explain(ctx context.Context, store *facts.Store) ([]
 	}
 	var candidates []candidate
 	for _, s := range distinct {
+		// A Rails/framework base class (ApplicationRecord, *BaseController, *::Base)
+		// has high fan-in purely because every subclass inherits from it — that is
+		// not a god class. Skip it (non-Ruby symbols are unaffected).
+		if common.IsRubyFrameworkBaseSymbol(s.Name, s.File) {
+			continue
+		}
 		n := fanIn[s.Name]
 		if n < minFanIn || float64(n) <= threshold {
 			continue

internal/explainers/godclass/godclass_test.go

@@ -98,6 +98,49 @@ func TestExplain_DedupReopenedSymbol(t *testing.T) {
 	}
 }
 
+// TestExplain_RubyBaseClassExcluded: a Rails framework base class (.rb) with high
+// fan-in-via-inheritance is not reported as a god class, while a same-fan-in domain
+// class is. Guards the base-class exclusion.
+func TestExplain_RubyBaseClassExcluded(t *testing.T) {
+	s := facts.NewStore()
+	s.Add(facts.Fact{Kind: facts.KindSymbol, Name: "ApplicationRecord", File: "app/models/application_record.rb"})
+	s.Add(facts.Fact{Kind: facts.KindSymbol, Name: "User", File: "app/models/user.rb"})
+	for i := 0; i < 12; i++ {
+		// Each caller subclasses ApplicationRecord and also references User.
+		s.Add(facts.Fact{
+			Kind: facts.KindSymbol, Name: fmt.Sprintf("app/models/m%d.Model", i),
+			File:      fmt.Sprintf("app/models/m%d.rb", i),
+			Relations: []facts.Relation{{Kind: facts.RelImplements, Target: "ApplicationRecord"}, {Kind: facts.RelCalls, Target: "User"}},
+		})
+	}
+	s.BuildGraph()
+
+	insights, err := New().Explain(context.Background(), s)
+	if err != nil {
+		t.Fatalf("Explain: %v", err)
+	}
+	for _, in := range insights {
+		if strings.Contains(in.Title, "ApplicationRecord") {
+			t.Errorf("framework base class should be excluded from god-class: %q", in.Title)
+		}
+	}
+	foundUser := false
+	for _, in := range insights {
+		if strings.Contains(in.Title, "User") {
+			foundUser = true
+		}
+	}
+	if !foundUser {
+		t.Errorf("real domain hotspot User should still be reported; got %v", func() []string {
+			out := make([]string, len(insights))
+			for i, in := range insights {
+				out[i] = in.Title
+			}
+			return out
+		}())
+	}
+}
+
 // TestExplain_CapsInsightCount: no more than maxInsights findings are emitted even
 // when many distinct symbols exceed the outlier threshold.
 func TestExplain_CapsInsightCount(t *testing.T) {

internal/explainers/hotspots/hotspots.go

@@ -89,6 +89,11 @@ func (e *HotspotExplainer) Explain(ctx context.Context, store *facts.Store) ([]f
 	}
 	var candidates []candidate
 	for _, s := range distinct {
+		// A Rails/framework base class has high fan-in via inheritance, not because
+		// it is a genuine pinch point — skip it (non-Ruby symbols are unaffected).
+		if common.IsRubyFrameworkBaseSymbol(s.Name, s.File) {
+			continue
+		}
 		in := len(reverse[s.Name])
 		out := len(forward[s.Name])
 		if in < minDegree || out < minDegree {

internal/explainers/hotspots/hotspots_test.go

@@ -87,6 +87,49 @@ func TestExplain_DedupReopenedSymbol(t *testing.T) {
 	}
 }
 
+// TestExplain_RubyBaseClassExcluded: a Rails base class (.rb) with high fan-in AND
+// fan-out is still excluded from hotspots (its inbound degree is inheritance), while
+// a same-degree domain type is reported.
+func TestExplain_RubyBaseClassExcluded(t *testing.T) {
+	s := facts.NewStore()
+	addHub := func(name, file string) {
+		calls := make([]facts.Relation, 0, 4)
+		for i := 0; i < 4; i++ {
+			tgt := fmt.Sprintf("%s_dep%d.Fn", name, i)
+			calls = append(calls, facts.Relation{Kind: facts.RelCalls, Target: tgt})
+			s.Add(facts.Fact{Kind: facts.KindSymbol, Name: tgt, File: "dep.rb"})
+		}
+		s.Add(facts.Fact{Kind: facts.KindSymbol, Name: name, File: file, Relations: calls})
+		for i := 0; i < 4; i++ {
+			s.Add(facts.Fact{Kind: facts.KindSymbol, Name: fmt.Sprintf("%s_caller%d.Fn", name, i),
+				File: "caller.rb", Relations: []facts.Relation{{Kind: facts.RelCalls, Target: name}}})
+		}
+	}
+	addHub("NotifierBase", "app/notifiers/notifier_base.rb")
+	addHub("User", "app/models/user.rb")
+	s.BuildGraph()
+
+	insights, err := New().Explain(context.Background(), s)
+	if err != nil {
+		t.Fatalf("Explain: %v", err)
+	}
+	var sawBase, sawUser bool
+	for _, in := range insights {
+		if strings.Contains(in.Title, "NotifierBase") {
+			sawBase = true
+		}
+		if strings.Contains(in.Title, "User") {
+			sawUser = true
+		}
+	}
+	if sawBase {
+		t.Errorf("framework base class should be excluded from hotspots")
+	}
+	if !sawUser {
+		t.Errorf("real domain hotspot User should still be reported")
+	}
+}
+
 func TestExplain_BelowDegreeFloor(t *testing.T) {
 	// High fan-out but fan-in below minDegree -> not a pinch point.
 	store := makeStore("core.Hub", 1, 10)

internal/explainers/surface/surface.go

@@ -77,6 +77,15 @@ func (e *SurfaceExplainer) Explain(ctx context.Context, store *facts.Store) ([]f
 
 	mods := make(map[string]*moduleSurface)
 	for _, s := range symbols {
+		// Ruby is public-by-default: every class/method is "exported", so the
+		// exported/total ratio is ~100% for every module and carries no signal (it
+		// floods with namespace modules like Core::V3, RailsAdmin, V2). Skip Ruby
+		// symbols so Ruby modules never become candidates; other languages in a
+		// multi-repo snapshot are unaffected. "Too big/central" is already covered by
+		// the god-class and complexity explainers.
+		if lang, _ := s.Props["language"].(string); lang == "ruby" {
+			continue
+		}
 		exported, ok := s.Props["exported"].(bool)
 		if !ok {
 			// Extractor didn't record visibility; ignore so it doesn't distort the ratio.

internal/explainers/surface/surface_test.go

@@ -42,6 +42,42 @@ func TestExplain_LargePublicSurface(t *testing.T) {
 	}
 }
 
+// TestExplain_RubySkipped: Ruby symbols are public-by-default, so the exported
+// ratio is uninformative and Ruby modules must never be flagged; other languages in
+// the same store still are.
+func TestExplain_RubySkipped(t *testing.T) {
+	s := facts.NewStore()
+	// A large, fully-"exported" Ruby namespace — must be skipped.
+	for i := 0; i < 30; i++ {
+		s.Add(facts.Fact{
+			Kind: facts.KindSymbol, Name: fmt.Sprintf("Core::V3.Sym%d", i),
+			File:  "app/controllers/core/v3/file.rb",
+			Props: map[string]any{"exported": true, "language": "ruby"},
+		})
+	}
+	// A non-Ruby over-exposed module — must still be reported.
+	addModuleSymbols(s, "pkg/leaky", 20, 19)
+
+	insights, err := New().Explain(context.Background(), s)
+	if err != nil {
+		t.Fatalf("Explain: %v", err)
+	}
+	for _, in := range insights {
+		if strings.Contains(in.Title, "Core::V3") {
+			t.Errorf("Ruby module should be skipped by exported-surface: %q", in.Title)
+		}
+	}
+	if len(insights) != 1 || !strings.Contains(insights[0].Title, "pkg/leaky") {
+		t.Errorf("non-Ruby module should still be flagged; got %v", func() []string {
+			out := make([]string, len(insights))
+			for i, in := range insights {
+				out[i] = in.Title
+			}
+			return out
+		}())
+	}
+}
+
 func TestExplain_BelowRatio(t *testing.T) {
 	s := facts.NewStore()
 	addModuleSymbols(s, "pkg/mid", 20, 15) // 75% exported, below minExportedRatio