fix(explainers): fix 7 correctness/determinism bugs and harden test coverage (#73)

Bulletproof the explainer suite with unit tests and fix the bugs found while
doing so. Explainer output feeds query_insights and pkg/explain, so correctness
and byte-for-byte determinism matter.

Confirmed bugs fixed (each with a regression test proven to fail pre-fix):
- pkg/explain: metric parsing corrupted by digits in symbol/module names —
  allInts scanned the whole title, so a hotspot on "Sha256Hash" rendered
  "fan-in 256 / out 30" and a surface on "oauth2" rendered "2/40 (44%)". Parse
  only the metric section via metricInts(title, marker).
- cycles: nondeterministic cycle path / evidence order / insight order (map
  iteration + unsorted neighbors). Factored a deterministic
  common.StronglyConnectedComponents shared with depth.
- depth: under-counted chains hidden behind a cycle (a memoized chain truncated
  by the back-edge cut was reused globally). Rewrote over the SCC condensation
  (longest path on the DAG, cycle = its full member count as a cycle-safe upper
  bound).
- crossrepo: "via" detail dropped after a facts.jsonl round-trip (asserted
  []string only; JSON decodes arrays as []any). Handle both shapes.

layers fixes:
- deterministic pattern-insight evidence (was map iteration order)
- dedup layer violations by (source, target) module so the count isn't inflated
- resolve relative import targets (./x, ../y) before matching a layer

Tests: added threshold-boundary, determinism, float64/JSONL prop, evidence-cap,
and sort-order coverage across every explainer and common. Full suite green
under -race; engine golden/determinism gate unaffected (fixes touch insights,
not facts.jsonl).

Docs: refreshed the Apache Airflow --explain example in README.md (fact counts,
hotspots, and the now-corrected depth numbers).

Author: dejo1307

README.md

@@ -315,95 +315,97 @@ enola --explain /path/to/repo
 
 Every finding carries a confidence score, and it means something exact: `1.0` is a structural fact (a cycle exists; an export ratio measured), while anything below is a flagged heuristic for you to review (a god class is a statistical fan-in outlier, not a rule). The analyses are computed by graph algorithms — Tarjan's SCC for cycles, longest-path for dependency depth, mean+2σ outlier tests for the rest — so the same commit yields the same report.
 
-Here's the actual report for [Apache Airflow](https://github.com/apache/airflow) — a large polyglot codebase (Python, Java, TypeScript, and OpenAPI specs) analyzed in a single pass, 112,792 facts in ~3.5s (extraction parses files in parallel across cores; timing measured on a 16-core machine):
+Here's the actual report for [Apache Airflow](https://github.com/apache/airflow) — a large polyglot codebase (Python, Java, TypeScript, gRPC, and OpenAPI specs) analyzed in a single pass, 122,772 facts in ~2s (extraction parses files in parallel across cores):
 
 ```
 ════════════════════════════════════════════════════════════
  Repository explanation: apache/airflow
 ════════════════════════════════════════════════════════════
 
 Overview
-  Generated:           2026-06-24T11:28:08Z
-  Analysis time:       3.522345875s
-  Languages:           java, openapi, python, typescript
-  Total facts:         112792
+  Generated:           2026-07-07T20:51:51Z
+  Analysis time:       2.100326959s
+  Languages:           python, typescript, java, grpc
+  Total facts:         122772
 
 Architectural kinds
-  module                   2492
-  symbol                  64192
-  route                    6359
+  module                   2499
+  symbol                  64148
+  route                    6426
   storage                    64
-  dependency              39685
+  dependency              44371
 
 Symbol breakdown
-  method                  41127
-  function                12371
-  class                    8621
+  method                  40976
+  function                12409
+  class                    8583
   type                     1393
-  variable                  636
-  interface                  36
+  variable                  732
+  interface                  37
+  struct                     10
   enum                        6
   constant                    2
 
 API & data surface
-  routes                   6359
-    (unspecified)          6182
-    GET                     105
-    POST                     28
-    PATCH                    22
-    DELETE                   16
-    PUT                       6
+  routes                   6426
+    PATCH                  6038
+    GET                     247
+    POST                     74
+    DELETE                   46
+    PUT                      20
+    HEAD                      1
   storage                    64
 
 Dependencies
-  internal                17810
-  stdlib                  12430
-  external                 9445
+  internal                20905
+  stdlib                  12858
+  external                10607
+  unclassified                1
 
 Architecture
   Pattern:             (none detected)
-  cyclic dependencies        26
+  cyclic dependencies        27
   layer violations            0
 
 Impact analysis (hotspots)
-  coupled modules           840
-    high criticality        486
-    medium criticality      354
+  coupled modules           915
+    high criticality        547
+    medium criticality      368
   Top hotspots (by coupling):
     module                            fan-in  fan-out crit     blast radius
-    airflow-core/src/airflow/models     1396      315 high     56732
-    devel-common/src/tests_common/t…    1450       85 high     35780
-    providers/common/compat/src/air…    1214        1 high     51068
-    airflow-core/src/airflow/utils      1029       69 high     62870
-    airflow-core/src/airflow             871       39 high     67265
-    providers/common/compat/tests/u…     690        0 high     61945
-    providers/google/src/airflow/pr…     323      284 high     14305
-    providers/amazon/tests/system/a…       1      510 high     177
+    airflow-core/src/airflow/models     1661      380 high     66716
+    devel-common/src/tests_common/t…    1496      161 high     39422
+    providers/common/compat/src/air…    1295        2 high     59376
+    airflow-core/src/airflow/utils      1124      132 high     68653
+    airflow-core/src/airflow            1172       71 high     71697
+    providers/common/compat/tests/u…     776        0 high     65589
+    providers/google/src/airflow/pr…     327      329 high     14701
+    task-sdk/src/airflow/sdk             591       15 high     64026
 
 Code health
-  god classes (high fan-in)    298
-    airflow-core/src/airflow/ui/openapi-gen/req… 153 dependents
-    airflow-ctl/tests/airflow_ctl/api/test_oper… 79 dependents
-    providers/cncf/kubernetes/tests/unit/cncf/k… 71 dependents
-    airflow-core/tests/unit/ti_deps/deps/test_t… 49 dependents
-    providers/hashicorp/tests/unit/hashicorp/ho… 45 dependents
-  call-graph hotspots       133
-    airflow-core/src/airflow/ui/openapi-gen/req… fan-in 153 / out 12
-    providers/cncf/kubernetes/tests/unit/cncf/k… fan-in 71 / out 6
-    providers/openlineage/tests/unit/openlineag… fan-in 3 / out 21
-    providers/edge3/src/airflow/providers/edge3… fan-in 3 / out 3
-    providers/google/src/airflow/providers/goog… fan-in 10 / out 18
+  god classes (high fan-in)    254
+    chart/tests/chart_utils/helm_template_gener… 1193 dependents
+    devel-common/src/tests_common/test_utils/co… 557 dependents
+    devel-common/src/tests_common/test_utils/sy… 476 dependents
+    dev/breeze/src/airflow_breeze/utils/console… 376 dependents
+    airflow-core/src/airflow/utils/session.crea… 288 dependents
+  call-graph hotspots       152
+    chart/tests/chart_utils/helm_template_gener… fan-in 1193 / out 7
+    devel-common/src/tests_common/test_utils/co… fan-in 557 / out 10
+    task-sdk/src/airflow/sdk/execution_time/tas… fan-in 101 / out 37
+    airflow-core/src/airflow/utils/session.crea… fan-in 288 / out 6
+    dev/breeze/src/airflow_breeze/utils/run_uti… fan-in 179 / out 9
   deep dependency chains     10
-    airflow-core/tests/unit/api_fastapi/core_ap… depth 57
-    airflow-core/tests/unit/api_fastapi/core_ap… depth 56
-    airflow-core/tests/unit/assets               depth 56
-    airflow-core/tests/unit/jobs                 depth 56
-    providers/fab/tests/unit/fab/plugins         depth 56
+    chart/docs                                   depth 196
+    dev/breeze/tests                             depth 196
+    dev/breeze/tests/integration_tests           depth 196
+    scripts/tools                                depth 196
+    airflow-core/tests/unit/api_fastapi/core_ap… depth 195
   large public surfaces      20
-    airflow-core/src/airflow/ui/openapi-gen/req… 911/911 (100%)
     airflow-core/src/airflow/ui/openapi-gen/que… 864/864 (100%)
+    airflow-core/src/airflow/ui/openapi-gen/req… 720/720 (100%)
     task-sdk/src/airflow/sdk/execution_time/com… 119/129 (92%)
-    providers/edge3/src/airflow/providers/edge3… 3/3 (100%)
+    providers/edge3/src/airflow/providers/edge3… 100/100 (100%)
     task-sdk/src/airflow/sdk/definitions/mapped… 100/111 (90%)
   complexity outliers        15
     airflow-core/src/airflow/jobs/scheduler_job… complexity 69

internal/explainers/common/common.go

@@ -6,6 +6,7 @@ package common
 
 import (
 	"math"
+	"sort"
 	"strings"
 
 	"github.com/enola-labs/enola/internal/facts"
@@ -161,3 +162,78 @@ func OutlierThreshold(values []float64, k float64) float64 {
 	mean, std := MeanStdDev(values)
 	return mean + k*std
 }
+
+// StronglyConnectedComponents returns the strongly-connected components of a
+// directed graph (adjacency list: node -> successors) using Tarjan's algorithm.
+//
+// The result is deterministic regardless of Go's randomized map iteration: nodes
+// are visited in sorted order with sorted neighbor lists, each component's members
+// are sorted, and the component list is ordered by each component's smallest
+// member. Every key of graph appears in exactly one component (a node that appears
+// only as a neighbor is included as its own singleton). Shared by the cycles and
+// dependency-depth explainers, which both need a cycle-safe view of the module
+// graph — factoring it here keeps a single, tested implementation.
+func StronglyConnectedComponents(graph map[string][]string) [][]string {
+	nodes := make([]string, 0, len(graph))
+	for v := range graph {
+		nodes = append(nodes, v)
+	}
+	sort.Strings(nodes)
+
+	var (
+		index    int
+		stack    []string
+		onStack  = make(map[string]bool)
+		indices  = make(map[string]int)
+		lowlinks = make(map[string]int)
+		sccs     [][]string
+	)
+
+	var strongConnect func(v string)
+	strongConnect = func(v string) {
+		indices[v] = index
+		lowlinks[v] = index
+		index++
+		stack = append(stack, v)
+		onStack[v] = true
+
+		neighbors := append([]string(nil), graph[v]...)
+		sort.Strings(neighbors)
+		for _, w := range neighbors {
+			if _, visited := indices[w]; !visited {
+				strongConnect(w)
+				if lowlinks[w] < lowlinks[v] {
+					lowlinks[v] = lowlinks[w]
+				}
+			} else if onStack[w] {
+				if indices[w] < lowlinks[v] {
+					lowlinks[v] = indices[w]
+				}
+			}
+		}
+
+		if lowlinks[v] == indices[v] {
+			var scc []string
+			for {
+				w := stack[len(stack)-1]
+				stack = stack[:len(stack)-1]
+				onStack[w] = false
+				scc = append(scc, w)
+				if w == v {
+					break
+				}
+			}
+			sort.Strings(scc)
+			sccs = append(sccs, scc)
+		}
+	}
+
+	for _, v := range nodes {
+		if _, visited := indices[v]; !visited {
+			strongConnect(v)
+		}
+	}
+
+	sort.Slice(sccs, func(i, j int) bool { return sccs[i][0] < sccs[j][0] })
+	return sccs
+}

internal/explainers/common/common_test.go

@@ -2,6 +2,7 @@ package common
 
 import (
 	"math"
+	"strings"
 	"testing"
 
 	"github.com/enola-labs/enola/internal/facts"
@@ -148,3 +149,87 @@ func TestMeanStdDev(t *testing.T) {
 		t.Errorf("OutlierThreshold(vals, 2) = %v, want 9", got)
 	}
 }
+
+// TestOutlierThreshold_ZeroStdDev: with identical values the std dev is 0, so the
+// threshold equals the mean — every value is <= it, so nothing is a strict
+// outlier (why an all-equal fan-in/complexity distribution flags nothing).
+func TestOutlierThreshold_ZeroStdDev(t *testing.T) {
+	vals := []float64{7, 7, 7, 7}
+	mean, std := MeanStdDev(vals)
+	if std != 0 {
+		t.Errorf("std of identical values = %v, want 0", std)
+	}
+	if got := OutlierThreshold(vals, 2); got != mean {
+		t.Errorf("OutlierThreshold(identical, 2) = %v, want mean %v", got, mean)
+	}
+}
+
+// sccKey renders a component partition as a stable string for comparison.
+func sccKey(sccs [][]string) string {
+	parts := make([]string, len(sccs))
+	for i, scc := range sccs {
+		parts[i] = strings.Join(scc, ",")
+	}
+	return strings.Join(parts, " | ")
+}
+
+func TestStronglyConnectedComponents(t *testing.T) {
+	tests := []struct {
+		name  string
+		graph map[string][]string
+		want  string // sccKey of the expected (sorted) partition
+	}{
+		{"empty", map[string][]string{}, ""},
+		{"single isolated", map[string][]string{"a": nil}, "a"},
+		{"simple cycle", map[string][]string{"b": {"a"}, "a": {"b"}}, "a,b"},
+		{"triangle + tail", map[string][]string{"a": {"b"}, "b": {"c"}, "c": {"a", "d"}, "d": nil}, "a,b,c | d"},
+		{"two disjoint cycles", map[string][]string{"a": {"b"}, "b": {"a"}, "c": {"d"}, "d": {"c"}}, "a,b | c,d"},
+		{"self loop is singleton", map[string][]string{"a": {"a"}}, "a"},
+		{"neighbor-only node included", map[string][]string{"a": {"b"}}, "a | b"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := sccKey(StronglyConnectedComponents(tt.graph)); got != tt.want {
+				t.Errorf("SCC(%v) = %q, want %q", tt.graph, got, tt.want)
+			}
+		})
+	}
+}
+
+// TestStronglyConnectedComponents_Deterministic: repeated calls re-range the
+// graph map (Go randomizes iteration), but the sorted output must be identical.
+func TestStronglyConnectedComponents_Deterministic(t *testing.T) {
+	graph := map[string][]string{
+		"a": {"b"}, "b": {"c"}, "c": {"a", "d"},
+		"d": {"e"}, "e": {"d"},
+		"f": {"a"}, "g": nil,
+	}
+	want := sccKey(StronglyConnectedComponents(graph))
+	for i := 0; i < 50; i++ {
+		if got := sccKey(StronglyConnectedComponents(graph)); got != want {
+			t.Fatalf("non-deterministic SCC output on iteration %d:\nwant %q\ngot  %q", i, want, got)
+		}
+	}
+}
+
+// TestBuildModuleGraph_ExcludesTestRole: modules tagged module_role=test are
+// dropped as both nodes and edge endpoints.
+func TestBuildModuleGraph_ExcludesTestRole(t *testing.T) {
+	s := facts.NewStore()
+	s.Add(facts.Fact{Kind: facts.KindModule, Name: "src/app"})
+	s.Add(facts.Fact{Kind: facts.KindModule, Name: "src/apptest",
+		Props: map[string]any{facts.PropModuleRole: facts.ModuleRoleTest}})
+	// app imports the test module and vice versa; the test edges must not appear.
+	s.Add(facts.Fact{Kind: facts.KindDependency, File: "src/app/f.go",
+		Relations: []facts.Relation{{Kind: facts.RelImports, Target: "src/apptest"}}})
+	s.Add(facts.Fact{Kind: facts.KindDependency, File: "src/apptest/f.go",
+		Relations: []facts.Relation{{Kind: facts.RelImports, Target: "src/app"}}})
+
+	graph := BuildModuleGraph(s)
+	if _, ok := graph["src/apptest"]; ok {
+		t.Error("test-role module should not be a graph node")
+	}
+	if len(graph["src/app"]) != 0 {
+		t.Errorf("edge to a test-role module should be dropped, got %v", graph["src/app"])
+	}
+}