From dfacbbb683c3c271f08c934d483736a89041696e Mon Sep 17 00:00:00 2001
From: Dejan Menges <dejan.menges@gmail.com>
Date: Fri, 12 Jun 2026 07:53:19 +0200
Subject: [PATCH 1/6] Improving traverse and find_path

---
 internal/extractors/goextractor/go.go      |   7 +-
 internal/extractors/goextractor/go_test.go |  38 ++++
 internal/facts/graph.go                    |  84 ++++++--
 internal/facts/graph_test.go               |  86 +++++++-
 internal/facts/model.go                    |  25 +--
 internal/server/scopedquery.go             | 223 ++++++++++++++++++++
 internal/server/server.go                  | 224 +++++++++++++--------
 internal/server/server_test.go             | 175 +++++++++++++++-
 8 files changed, 748 insertions(+), 114 deletions(-)
 create mode 100644 internal/server/scopedquery.go

diff --git a/internal/extractors/goextractor/go.go b/internal/extractors/goextractor/go.go
index 57d3574..11282e7 100644
--- a/internal/extractors/goextractor/go.go
+++ b/internal/extractors/goextractor/go.go
@@ -521,6 +521,11 @@ func collectFieldTypes(files []*ast.File, pkgDir, modulePath string, pkgNames ma
 //   - 3+ elements: resolve root to a qualified "pkg.Type", walk intermediate fields via fieldTypes, produce qualifiedType.method
 //
 // Falls back to the raw joined string when resolution is not possible, so no call is dropped.
+//
+// Known limitation: calls through an interface value (e.g. iface.Method()) cannot be
+// statically bound to a concrete implementation without type-flow analysis, so the
+// resolved target may name an interface method that has no backing symbol fact. Such
+// edges surface as "unresolved" nodes during traversal rather than concrete callees.
 func resolveChain(chain []string, ctx resolveCtx) string {
 	switch len(chain) {
 	case 0:
@@ -549,7 +554,7 @@ func resolveChain(chain []string, ctx resolveCtx) string {
 		// 3+ elements: attempt field-chain resolution.
 		root := chain[0]
 		var qualType string // "pkgDir.TypeName" or "importedPkg.TypeName"
-		var fieldStart int   // index of the first intermediate field in chain
+		var fieldStart int  // index of the first intermediate field in chain
 
 		if root == ctx.recvVar && ctx.recvType != "" {
 			qualType = ctx.pkgDir + "." + ctx.recvType
diff --git a/internal/extractors/goextractor/go_test.go b/internal/extractors/goextractor/go_test.go
index f1d325a..fb8c2d0 100644
--- a/internal/extractors/goextractor/go_test.go
+++ b/internal/extractors/goextractor/go_test.go
@@ -656,3 +656,41 @@ func TestDetect(t *testing.T) {
 		t.Error("expected Detect=false for directory without go.mod")
 	}
 }
+
+// TestExtract_StructAndMethodAreSeparateFacts documents the contract the graph's
+// has_method synthesis relies on: a struct and each of its methods are emitted as
+// distinct sibling facts ("pkg.Type" and "pkg.Type.Method"), with no edge between
+// them at extraction time. If this ever changes, internal/facts.NewGraph's
+// has_method third pass must be revisited.
+func TestExtract_StructAndMethodAreSeparateFacts(t *testing.T) {
+	ff := extractAll(t, map[string]string{
+		"pkg/handler.go": `package pkg
+
+type AuthHandler struct{}
+
+func (h *AuthHandler) Login() {}
+`,
+	})
+
+	st, ok := findFact(ff, "pkg.AuthHandler")
+	if !ok {
+		t.Fatal("expected struct fact pkg.AuthHandler")
+	}
+	if st.Props["symbol_kind"] != facts.SymbolStruct {
+		t.Errorf("AuthHandler symbol_kind = %v, want struct", st.Props["symbol_kind"])
+	}
+	// The struct must NOT carry an edge to its method (the graph synthesizes it).
+	for _, rel := range st.Relations {
+		if rel.Target == "pkg.AuthHandler.Login" {
+			t.Errorf("struct should not declare its method directly, found relation %+v", rel)
+		}
+	}
+
+	m, ok := findFact(ff, "pkg.AuthHandler.Login")
+	if !ok {
+		t.Fatal("expected method fact pkg.AuthHandler.Login as a separate fact")
+	}
+	if m.Props["symbol_kind"] != facts.SymbolMethod {
+		t.Errorf("Login symbol_kind = %v, want method", m.Props["symbol_kind"])
+	}
+}
diff --git a/internal/facts/graph.go b/internal/facts/graph.go
index 35b2d04..cc2e70d 100644
--- a/internal/facts/graph.go
+++ b/internal/facts/graph.go
@@ -9,16 +9,16 @@ import (
 // It is a derived index rebuilt from the Store's facts after each snapshot generation.
 type Graph struct {
 	mu       sync.RWMutex
-	forward  map[string][]Edge    // fact name → outgoing edges
-	reverse  map[string][]Edge    // fact name → incoming edges
-	facts    []Fact               // reference to the store's facts (for metadata lookups)
-	factIdx  map[string]int       // fact name → first index in facts slice
-	edgeSeen map[string]struct{}  // deduplication: "source\x00kind\x00target"
+	forward  map[string][]Edge   // fact name → outgoing edges
+	reverse  map[string][]Edge   // fact name → incoming edges
+	facts    []Fact              // reference to the store's facts (for metadata lookups)
+	factIdx  map[string]int      // fact name → first index in facts slice
+	edgeSeen map[string]struct{} // deduplication: "source\x00kind\x00target"
 }
 
 // Edge represents a directed relationship between two facts.
 type Edge struct {
-	RelKind string // "imports", "calls", "declares", "implements", "depends_on"
+	RelKind string // "imports", "calls", "declares", "implements", "depends_on", "has_method"
 	Target  string // target fact name (forward) or source fact name (reverse)
 }
 
@@ -36,6 +36,12 @@ type TraversalNode struct {
 	File  string `json:"file,omitempty"`
 	Line  int    `json:"line,omitempty"`
 	Depth int    `json:"depth"`
+	// Unresolved marks a node whose name is the target of an edge but has no
+	// backing fact in the store. This happens for inferred call targets that
+	// could not be matched to a declared symbol (e.g. interface-method dispatch,
+	// or calls into packages that weren't analyzed). The edge is real; the
+	// destination symbol just isn't in the graph.
+	Unresolved bool `json:"unresolved,omitempty"`
 }
 
 // TraversalEdge is an edge traversed during traversal.
@@ -55,12 +61,12 @@ type TraversalStats struct {
 
 // ImpactResult holds depth-bucketed impact analysis results.
 type ImpactResult struct {
-	Target   string                    `json:"target"`
-	ByDepth  map[int][]TraversalNode   `json:"by_depth"`
-	Edges    []TraversalEdge           `json:"edges"`
-	Summary  string                    `json:"summary"`
-	Stats    TraversalStats            `json:"stats"`
-	Forward  *TraversalResult          `json:"forward_dependencies,omitempty"`
+	Target  string                  `json:"target"`
+	ByDepth map[int][]TraversalNode `json:"by_depth"`
+	Edges   []TraversalEdge         `json:"edges"`
+	Summary string                  `json:"summary"`
+	Stats   TraversalStats          `json:"stats"`
+	Forward *TraversalResult        `json:"forward_dependencies,omitempty"`
 }
 
 // PathResult holds a shortest-path result.
@@ -149,6 +155,25 @@ func NewGraph(ff []Fact) *Graph {
 		}
 	}
 
+	// Third pass: synthesize "has_method" edges linking an owner type symbol
+	// (struct/interface/class/type) to its method symbols. Extractors emit a
+	// method as a sibling fact named "<owner>.<method>" with no edge back to the
+	// owner, so forward traversal from a type would otherwise surface none of its
+	// methods (and transitively none of their calls). This is language-agnostic:
+	// any fact named "<knownType>.<member>" gets wired to its owner.
+	for _, f := range ff {
+		if f.Kind != KindSymbol {
+			continue
+		}
+		sk, _ := f.Props["symbol_kind"].(string)
+		if sk != SymbolMethod && sk != SymbolFunc {
+			continue
+		}
+		if owner := g.methodOwner(f.Name); owner != "" {
+			g.addEdge(owner, RelHasMethod, f.Name)
+		}
+	}
+
 	// edgeSeen is only needed during construction; release it so the GC can
 	// reclaim the O(edges × 3 strings) backing memory.
 	g.edgeSeen = nil
@@ -156,6 +181,30 @@ func NewGraph(ff []Fact) *Graph {
 	return g
 }
 
+// methodOwner returns the owner type name for a method fact name of the form
+// "<owner>.<method>", but only when <owner> is itself a known symbol fact whose
+// symbol_kind is a type (struct/interface/class/type). Returns "" otherwise.
+func (g *Graph) methodOwner(name string) string {
+	dot := strings.LastIndex(name, ".")
+	if dot <= 0 {
+		return ""
+	}
+	owner := name[:dot]
+	idx, ok := g.factIdx[owner]
+	if !ok || idx >= len(g.facts) {
+		return ""
+	}
+	of := g.facts[idx]
+	if of.Kind != KindSymbol {
+		return ""
+	}
+	switch sk, _ := of.Props["symbol_kind"].(string); sk {
+	case SymbolStruct, SymbolInterface, SymbolClass, SymbolType:
+		return owner
+	}
+	return ""
+}
+
 // Traverse performs a BFS traversal from the given start node.
 // direction is "forward" or "reverse".
 // relKinds filters to specific relation types (nil = all).
@@ -302,7 +351,7 @@ func (g *Graph) FindPath(from, to string, relKinds []string, maxDepth int) PathR
 	relSet := toSet(relKinds)
 
 	type queueItem struct {
-		name string
+		name  string
 		depth int
 	}
 
@@ -428,8 +477,8 @@ func (g *Graph) ImpactSet(target string, maxDepth, maxNodes int, includeForward
 // the consumer emits the full import path (e.g. "github.com/x/go-auth/adapters.Handler.Login")
 // but the provider's facts use the repo-relative path (e.g. "adapters.Handler.Login").
 //
-//   subpackage: "github.com/x/go-auth/adapters.Handler.Login" → "adapters.Handler.Login"
-//   root pkg:   "github.com/x/go-auth.SecurityHeaders"        → "..SecurityHeaders"
+//	subpackage: "github.com/x/go-auth/adapters.Handler.Login" → "adapters.Handler.Login"
+//	root pkg:   "github.com/x/go-auth.SecurityHeaders"        → "..SecurityHeaders"
 func normalizeExternalTarget(target string, modulePaths map[string]struct{}) string {
 	for modulePath := range modulePaths {
 		if !strings.HasPrefix(target, modulePath) {
@@ -555,6 +604,11 @@ func (g *Graph) nodeFor(name string, depth int) TraversalNode {
 		node.Kind = f.Kind
 		node.File = f.File
 		node.Line = f.Line
+	} else {
+		// No backing fact: this is a dangling edge target (e.g. an inferred call
+		// into an unanalyzed package or an interface method). Mark it honestly
+		// rather than emitting a silent kind-less node.
+		node.Unresolved = true
 	}
 	return node
 }
diff --git a/internal/facts/graph_test.go b/internal/facts/graph_test.go
index 6544a81..dd3dd45 100644
--- a/internal/facts/graph_test.go
+++ b/internal/facts/graph_test.go
@@ -651,7 +651,7 @@ func TestNormalizeExternalTarget(t *testing.T) {
 		{"github.com/dejo1307/go-auth/adapters.Handler.Login", "adapters.Handler.Login"},
 		{"github.com/dejo1307/go-auth.SecurityHeaders", "..SecurityHeaders"},
 		{"github.com/other/lib/pkg.Type.Method", ""}, // no matching module
-		{"github.com/dejo1307/go-auth", ""},           // no separator after module path
+		{"github.com/dejo1307/go-auth", ""},          // no separator after module path
 	}
 
 	for _, tc := range cases {
@@ -661,3 +661,87 @@ func TestNormalizeExternalTarget(t *testing.T) {
 		}
 	}
 }
+
+// buildTypeMethodStore models a Go type with a method that makes a call, plus a
+// dangling call into an unanalyzed package. The struct and method are separate
+// sibling facts with no edge between them, mirroring the goextractor output.
+func buildTypeMethodStore() (*Graph, *Store) {
+	s := NewStore()
+	s.Add(
+		Fact{Kind: KindSymbol, Name: "auth.AuthHandler", File: "auth/handler.go", Line: 1,
+			Props: map[string]any{"symbol_kind": SymbolStruct}},
+		Fact{Kind: KindSymbol, Name: "auth.AuthHandler.Login", File: "auth/handler.go", Line: 10,
+			Props: map[string]any{"symbol_kind": SymbolMethod},
+			Relations: []Relation{
+				{Kind: RelCalls, Target: "jwt.Sign"},
+				{Kind: RelCalls, Target: "external.Unknown"}, // no backing fact
+			}},
+		Fact{Kind: KindSymbol, Name: "jwt.Sign", File: "jwt/jwt.go", Line: 5,
+			Props: map[string]any{"symbol_kind": SymbolFunc}},
+	)
+	s.BuildGraph()
+	return s.Graph(), s
+}
+
+func TestNewGraph_StructToMethodEdges(t *testing.T) {
+	g, _ := buildTypeMethodStore()
+
+	var found bool
+	for _, e := range g.Forward()["auth.AuthHandler"] {
+		if e.RelKind == RelHasMethod && e.Target == "auth.AuthHandler.Login" {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("expected has_method edge auth.AuthHandler -> auth.AuthHandler.Login, got %+v", g.Forward()["auth.AuthHandler"])
+	}
+
+	// A package-level function whose owner ("jwt") is not a type must NOT get a
+	// has_method edge.
+	for _, e := range g.Forward()["jwt"] {
+		if e.RelKind == RelHasMethod {
+			t.Errorf("unexpected has_method edge from non-type owner: %+v", e)
+		}
+	}
+}
+
+func TestTraverse_ForwardFromStructSurfacesMethodCalls(t *testing.T) {
+	g, _ := buildTypeMethodStore()
+
+	result := g.Traverse("auth.AuthHandler", "forward", nil, nil, 5, 100)
+
+	names := nodeNames(result.Nodes)
+	for _, want := range []string{"auth.AuthHandler.Login", "jwt.Sign"} {
+		if !contains(names, want) {
+			t.Errorf("forward traverse from struct missing %q; got %v", want, names)
+		}
+	}
+}
+
+func TestTraverse_UnresolvedTargetMarked(t *testing.T) {
+	g, _ := buildTypeMethodStore()
+
+	result := g.Traverse("auth.AuthHandler.Login", "forward", nil, nil, 5, 100)
+
+	var sawUnresolved, sawResolved bool
+	for _, n := range result.Nodes {
+		switch n.Name {
+		case "external.Unknown":
+			sawUnresolved = true
+			if !n.Unresolved {
+				t.Error("external.Unknown should be marked Unresolved")
+			}
+		case "jwt.Sign":
+			sawResolved = true
+			if n.Unresolved {
+				t.Error("jwt.Sign is a real fact and must not be marked Unresolved")
+			}
+		}
+	}
+	if !sawUnresolved {
+		t.Error("expected an unresolved node external.Unknown in the result")
+	}
+	if !sawResolved {
+		t.Error("expected the resolved node jwt.Sign in the result")
+	}
+}
diff --git a/internal/facts/model.go b/internal/facts/model.go
index d16e015..64afedc 100644
--- a/internal/facts/model.go
+++ b/internal/facts/model.go
@@ -36,6 +36,7 @@ const (
 	RelDependsOn    = "depends_on"
 	RelInstantiates = "instantiates" // Source constructs an instance of target via a constructor call.
 	RelInjects      = "injects"      // Source declares target as a DI-injected constructor parameter.
+	RelHasMethod    = "has_method"   // Owner type (struct/interface/class) declares target as a method. Synthesized in NewGraph.
 )
 
 // Symbol kind property values.
@@ -69,9 +70,9 @@ type Evidence struct {
 
 // Artifact represents a generated output file.
 type Artifact struct {
-	Name    string `json:"name"`    // e.g. "llm_context.md"
-	Content []byte `json:"-"`       // Raw content
-	Type    string `json:"type"`    // MIME type hint
+	Name    string `json:"name"` // e.g. "llm_context.md"
+	Content []byte `json:"-"`    // Raw content
+	Type    string `json:"type"` // MIME type hint
 }
 
 // Snapshot holds the complete result of an analysis run.
@@ -84,15 +85,15 @@ type Snapshot struct {
 
 // SnapshotMeta contains metadata about a snapshot generation run.
 type SnapshotMeta struct {
-	RepoPath    string     `json:"repo_path"`
-	GeneratedAt string     `json:"generated_at"`
-	Duration    string     `json:"duration"`
-	Extractors  []string   `json:"extractors"`
-	Explainers  []string   `json:"explainers"`
-	Renderers   []string   `json:"renderers"`
-	FileHashes  []FileHash `json:"file_hashes,omitempty"`
-	FactCount   int        `json:"fact_count"`
-	InsightCount int       `json:"insight_count"`
+	RepoPath     string     `json:"repo_path"`
+	GeneratedAt  string     `json:"generated_at"`
+	Duration     string     `json:"duration"`
+	Extractors   []string   `json:"extractors"`
+	Explainers   []string   `json:"explainers"`
+	Renderers    []string   `json:"renderers"`
+	FileHashes   []FileHash `json:"file_hashes,omitempty"`
+	FactCount    int        `json:"fact_count"`
+	InsightCount int        `json:"insight_count"`
 }
 
 // FileHash tracks a file's content hash for incremental updates.
diff --git a/internal/server/scopedquery.go b/internal/server/scopedquery.go
new file mode 100644
index 0000000..0ac258b
--- /dev/null
+++ b/internal/server/scopedquery.go
@@ -0,0 +1,223 @@
+package server
+
+import (
+	"sort"
+	"strings"
+
+	"github.com/enola-labs/enola/internal/facts"
+)
+
+// scopedQuery is the parsed form of a node-resolution input that may carry
+// scoping prefixes (repo:, kind:, file:) to disambiguate an otherwise-ambiguous
+// substring term. A plain input with no recognized prefix yields a scopedQuery
+// whose Term equals the input and whose scope fields are empty, preserving the
+// legacy substring-match behavior.
+type scopedQuery struct {
+	Repo       string   // repo:<label>          — exact repo-label filter
+	Kinds      []string // kind:<fact-kind>      — fact-kind filter (module, symbol, ...)
+	SymbolKind string   // kind:<symbol-kind>    — post-filter on Props["symbol_kind"] (struct, interface, ...)
+	FilePrefix string   // file:<path-prefix>    — file path prefix filter
+	Term       string   // the remaining bare substring search term
+}
+
+// factKinds and symbolKinds classify a kind: value so it can be routed to the
+// right filter. Fact kinds map to QueryOpts.Kinds; symbol kinds additionally
+// constrain Props["symbol_kind"] (which QueryOpts has no dedicated field for).
+var factKinds = map[string]bool{
+	facts.KindModule: true, facts.KindSymbol: true, facts.KindRoute: true,
+	facts.KindStorage: true, facts.KindDependency: true, facts.KindService: true,
+}
+
+var symbolKinds = map[string]bool{
+	facts.SymbolFunc: true, facts.SymbolMethod: true, facts.SymbolStruct: true,
+	facts.SymbolInterface: true, facts.SymbolType: true, facts.SymbolClass: true,
+	facts.SymbolVariable: true, facts.SymbolConstant: true,
+}
+
+// parseScopedQuery splits an input into optional scope filters and a bare term.
+//
+// Two syntaxes are accepted (and may be mixed):
+//   - Keyword tokens, space-separated:   "repo:golf kind:struct Currency"
+//   - Slash sugar inside a value:        "repo:golf/subtenant", "kind:symbol/Currency",
+//     "file:/domain//Currency"
+//
+// A token is treated as scoped only when it begins with exactly "repo:", "kind:",
+// or "file:" followed by a non-empty value; anything else is part of the term.
+func parseScopedQuery(input string) scopedQuery {
+	var sq scopedQuery
+	var terms []string
+
+	for _, tok := range strings.Fields(input) {
+		key, val, ok := splitScopeToken(tok)
+		if !ok {
+			terms = append(terms, tok)
+			continue
+		}
+		switch key {
+		case "repo":
+			// "golf/subtenant" → repo "golf", remainder narrows the term.
+			label, rest := splitOnce(val, "/")
+			sq.Repo = label
+			if rest != "" {
+				terms = append(terms, rest)
+			}
+		case "kind":
+			// "symbol/Currency" → kind "symbol", remainder narrows the term.
+			k, rest := splitOnce(val, "/")
+			k = strings.ToLower(k)
+			if symbolKinds[k] {
+				sq.SymbolKind = k
+				sq.Kinds = append(sq.Kinds, facts.KindSymbol)
+			} else if k != "" {
+				sq.Kinds = append(sq.Kinds, k)
+			}
+			if rest != "" {
+				terms = append(terms, rest)
+			}
+		case "file":
+			// "/domain//Currency" → prefix "domain", remainder narrows the term.
+			prefix, rest := splitOnce(val, "//")
+			sq.FilePrefix = strings.TrimPrefix(prefix, "/")
+			if rest != "" {
+				terms = append(terms, rest)
+			}
+		}
+	}
+
+	sq.Term = strings.Join(terms, " ")
+	return sq
+}
+
+// splitScopeToken recognizes "<key>:<value>" where key is one of the scope
+// keywords and value is non-empty. Returns ok=false otherwise.
+func splitScopeToken(tok string) (key, val string, ok bool) {
+	colon := strings.IndexByte(tok, ':')
+	if colon <= 0 || colon == len(tok)-1 {
+		return "", "", false
+	}
+	key = strings.ToLower(tok[:colon])
+	switch key {
+	case "repo", "kind", "file":
+		return key, tok[colon+1:], true
+	}
+	return "", "", false
+}
+
+// splitOnce splits s on the first occurrence of sep, returning the left part and
+// the remainder (without sep). When sep is absent, rest is empty.
+func splitOnce(s, sep string) (left, rest string) {
+	if i := strings.Index(s, sep); i >= 0 {
+		return s[:i], s[i+len(sep):]
+	}
+	return s, ""
+}
+
+// scoredCandidate is a ranked resolution candidate surfaced when a name is
+// ambiguous, so callers can pick the right one or trust the auto-pick.
+type scoredCandidate struct {
+	Name  string  `json:"name"`
+	Kind  string  `json:"kind"`
+	Repo  string  `json:"repo,omitempty"`
+	File  string  `json:"file,omitempty"`
+	Score float64 `json:"score"`
+}
+
+// matchTier classifies how directly a fact's name answers the term, as a coarse
+// rank that dominates the finer per-kind tweaks in scoreCandidate. This is the
+// key intent signal: a symbol whose short name IS the term (suffix-exact) must
+// always outrank one that merely contains the term as a substring, regardless of
+// kind. 2 = whole-name exact, 1 = suffix-exact (last dotted segment), 0 = substring.
+func matchTier(name, term string) int {
+	if term == "" {
+		return 0
+	}
+	n := strings.ToLower(name)
+	if n == term {
+		return 2
+	}
+	if strings.ToLower(lastSegment(name)) == term {
+		return 1
+	}
+	return 0
+}
+
+// scoreCandidate assigns a heuristic relevance score (higher is better). The
+// match tier (whole-name/suffix/substring) dominates via a large weight, so kind
+// and scope bonuses only break ties WITHIN a tier — a struct that merely contains
+// the term can never outrank a method whose name exactly is the term.
+func scoreCandidate(f facts.Fact, sq scopedQuery) float64 {
+	term := strings.ToLower(sq.Term)
+	score := float64(matchTier(f.Name, term)) // 0, 1, or 2 — dominant term
+
+	// Within-tier tie-breakers (small relative to the tier step of 1.0).
+	switch sk, _ := f.Props["symbol_kind"].(string); sk {
+	case facts.SymbolStruct, facts.SymbolClass, facts.SymbolInterface, facts.SymbolType:
+		score += 0.15 // type-level: the usual target of a bare name
+	case facts.SymbolFunc, facts.SymbolMethod:
+		score -= 0.15 // members are slightly less likely for a bare name
+	}
+	if f.Kind == facts.KindModule {
+		score += 0.1
+	}
+	if sq.Repo != "" && strings.EqualFold(f.Repo, sq.Repo) {
+		score += 0.15
+	}
+	if sq.FilePrefix != "" && strings.HasPrefix(f.File, sq.FilePrefix) {
+		score += 0.1
+	}
+	return score
+}
+
+// rankCandidates scores and sorts facts by descending score (stable, so store
+// order breaks ties deterministically).
+func rankCandidates(results []facts.Fact, sq scopedQuery) []scoredCandidate {
+	ranked := make([]scoredCandidate, 0, len(results))
+	for _, r := range results {
+		ranked = append(ranked, scoredCandidate{
+			Name:  r.Name,
+			Kind:  r.Kind,
+			Repo:  r.Repo,
+			File:  r.File,
+			Score: scoreCandidate(r, sq),
+		})
+	}
+	sort.SliceStable(ranked, func(i, j int) bool {
+		return ranked[i].Score > ranked[j].Score
+	})
+	return ranked
+}
+
+// pickConfidence expresses how decisively the top candidate beats the runner-up
+// in [0,1]. A candidate in a strictly higher match tier than the runner-up is
+// decisive (the term names it more directly than anything else) → high
+// confidence. Within the same tier, confidence is top/(top+runnerUp): a lone
+// candidate scores 1.0, an even tie 0.5.
+func pickConfidence(ranked []scoredCandidate, term string) float64 {
+	if len(ranked) == 0 || ranked[0].Score <= 0 {
+		return 0
+	}
+	if len(ranked) == 1 {
+		return 1
+	}
+	term = strings.ToLower(term)
+	if matchTier(ranked[0].Name, term) > matchTier(ranked[1].Name, term) {
+		return 0.9 // sole highest-tier match: clearly the intended target
+	}
+	top, runnerUp := ranked[0].Score, ranked[1].Score
+	if runnerUp < 0 {
+		runnerUp = 0
+	}
+	denom := top + runnerUp
+	if denom <= 0 {
+		return 0
+	}
+	return top / denom
+}
+
+// lastSegment returns the substring after the final ".", or the whole string.
+func lastSegment(name string) string {
+	if i := strings.LastIndex(name, "."); i >= 0 {
+		return name[i+1:]
+	}
+	return name
+}
diff --git a/internal/server/server.go b/internal/server/server.go
index be0a28d..5375172 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -542,8 +542,10 @@ func (s *Server) registerTools() {
 		Name: "traverse",
 		Description: "Walk the dependency/call graph from a starting node. " +
 			"direction='forward' answers \"what does X depend on?\"; direction='reverse' answers \"what depends on X?\". " +
-			"start= accepts substring match; returns resolution info when ambiguous. " +
-			"relation_kinds filter: imports, calls, declares, implements, depends_on. " +
+			"start= accepts substring match plus scoped prefixes (repo:, kind:, file:) to disambiguate; returns ranked candidates with confidence when ambiguous. " +
+			"relation_kinds filter: imports, calls, declares, implements, depends_on, has_method. " +
+			"Forward traversal from a struct/interface follows has_method edges to its methods (and then their calls). " +
+			"Note: interface method calls cannot be statically bound to a concrete implementation, so such call edges may be absent or appear as unresolved nodes. " +
 			"node_kinds filters output (not traversal itself): module, symbol, dependency, route, storage. " +
 			"Defaults: depth=5, max_nodes=100. Use instead of repeated explore calls for transitive relationships.",
 	}, func(ctx context.Context, req *mcp.CallToolRequest, args traverseArgs) (*mcp.CallToolResult, any, error) {
@@ -597,8 +599,10 @@ func (s *Server) registerTools() {
 		Name: "find_path",
 		Description: "Find the shortest path (BFS, by hop count) between two nodes in the architectural graph. " +
 			"Answers \"how does X reach Y?\" or \"what is the call chain from A to B?\". " +
-			"from= and to= use substring match with smart disambiguation; when either name is ambiguous " +
-			"the response contains a resolution object listing candidates instead of a path. " +
+			"from= and to= use substring match with smart disambiguation, and accept scoped prefixes " +
+			"(repo:, kind:, file:) to pin down an ambiguous name, e.g. from=\"repo:go-auth Login\". " +
+			"When a name is ambiguous the response carries a resolution object with ranked candidates and a " +
+			"confidence score; one dominant candidate (>80% confidence) is auto-resolved so the path is still returned. " +
 			"Returns an ordered list of nodes and edges, or reports no path found within max_depth hops.",
 	}, func(ctx context.Context, req *mcp.CallToolRequest, args findPathArgs) (*mcp.CallToolResult, any, error) {
 		if s.toolCallback != nil {
@@ -701,126 +705,182 @@ const ambiguousMatchThreshold = 3
 // nameResolution so the response stays readable.
 const maxAlternatives = 10
 
+// maxCandidates caps how many ranked, scored candidates are surfaced in a
+// nameResolution.
+const maxCandidates = 3
+
+// autoPickConfidence is the pickConfidence threshold above which an ambiguous
+// resolution (at or above ambiguousMatchThreshold matches) is resolved
+// automatically to its top-scoring candidate instead of being refused.
+const autoPickConfidence = 0.80
+
 // nameResolution reports how a user-provided name was resolved to a concrete
 // fact name. It is surfaced in tool responses ONLY when the input matched more
 // than one fact (i.e. Ambiguous is true), so callers can detect and correct a
 // possibly-wrong pick. Matched is empty when the match count crossed
-// ambiguousMatchThreshold and the caller must re-invoke with an exact name.
+// ambiguousMatchThreshold and no candidate scored confidently enough to
+// auto-pick; the caller should then choose from Candidates (optionally using the
+// repo:/kind:/file: scope prefixes) or re-invoke with an exact name.
 type nameResolution struct {
-	Query        string   `json:"query"`
-	Matched      string   `json:"matched,omitempty"`
-	Alternatives []string `json:"alternatives,omitempty"`
-	Ambiguous    bool     `json:"ambiguous"`
+	Query        string            `json:"query"`
+	Matched      string            `json:"matched,omitempty"`
+	Alternatives []string          `json:"alternatives,omitempty"`
+	Candidates   []scoredCandidate `json:"candidates,omitempty"`
+	Confidence   float64           `json:"confidence,omitempty"`
+	AutoPicked   bool              `json:"auto_picked,omitempty"`
+	Ambiguous    bool              `json:"ambiguous"`
 }
 
 // resolveNodeName resolves a user-provided name to an exact fact name.
 //
-// It returns the resolved name and, when resolution was ambiguous (the input
-// substring-matched more than one fact and no confident pick existed), a
-// non-nil *nameResolution describing the ambiguity. For exact matches, single
-// substring matches, and confident suffix-exact matches the resolution is nil.
+// The input may carry scope prefixes — repo:<label>, kind:<k>, file:<prefix> —
+// to disambiguate an otherwise-ambiguous term (see parseScopedQuery). A plain
+// input keeps the legacy substring-match behavior.
+//
+// It returns the resolved name and, when resolution was ambiguous (more than one
+// fact matched and no confident pick existed), a non-nil *nameResolution
+// describing the ambiguity (ranked Candidates with scores + a Confidence). For
+// exact matches, single matches, and confident suffix-exact matches the
+// resolution is nil.
 //
-// When the candidate count reaches ambiguousMatchThreshold the method refuses
-// to guess: it returns an empty name together with a resolution whose Matched
-// is empty, signalling the caller to emit a resolution-only response and
-// require an exact re-invocation.
+// When the candidate count reaches ambiguousMatchThreshold the method picks the
+// top-scoring candidate only if its pickConfidence exceeds autoPickConfidence;
+// otherwise it returns an empty name with a resolution-only response so the
+// caller can choose from Candidates or re-invoke with a scoped/exact name.
 func (s *Server) resolveNodeName(store *facts.Store, input string) (string, *nameResolution, error) {
 	query := input
-	input = s.normalizeToRelative(input)
+	sq := parseScopedQuery(input)
+	scoped := sq.Repo != "" || len(sq.Kinds) > 0 || sq.FilePrefix != "" || sq.SymbolKind != ""
 
-	// Try exact match first
-	exact := store.LookupByExactName(input)
-	if len(exact) > 0 {
-		return exact[0].Name, nil, nil
+	term := s.normalizeToRelative(sq.Term)
+
+	// Try exact match first (unscoped only — a scope filter signals the caller
+	// wants the candidate set narrowed, not bypassed).
+	if !scoped {
+		if exact := store.LookupByExactName(term); len(exact) > 0 {
+			return exact[0].Name, nil, nil
+		}
 	}
 
-	// Try substring match
-	results := store.Query("", "", input, "")
+	results := s.gatherCandidates(store, sq, term)
 	if len(results) == 0 {
 		// Fallback 1: exact name match on KindService facts (service nodes are
 		// named after repo labels and are often missed by substring search).
 		for _, svc := range store.ByKind(facts.KindService) {
-			if strings.EqualFold(svc.Name, input) {
+			if strings.EqualFold(svc.Name, term) {
 				return svc.Name, nil, nil
 			}
 		}
 		// Fallback 2: input matches a known repo label whose service node may
 		// have an empty name (primary repo) or hasn't been loaded yet.
-		if name, ok := s.resolveRepoLabelToServiceNode(store, input); ok {
+		if name, ok := s.resolveRepoLabelToServiceNode(store, term); ok {
 			return name, nil, nil
 		}
-		return "", nil, fmt.Errorf("no facts matching %q", input)
+		return "", nil, fmt.Errorf("no facts matching %q", query)
 	}
 	if len(results) == 1 {
 		return results[0].Name, nil, nil
 	}
 
-	// Smart disambiguation: when multiple matches exist, try to find the
-	// most likely intended target rather than immediately erroring.
-
-	// 1. Prefer exact name suffix match (e.g., "AuthHandler" matching
-	//    "adapters.AuthHandler" over "adapters.AuthHandler.Login"). A unique
-	//    suffix-exact match is a confident pick, so no resolution is surfaced.
-	var suffixMatches []facts.Fact
-	for _, r := range results {
-		parts := strings.Split(r.Name, ".")
-		if len(parts) > 0 && parts[len(parts)-1] == input {
-			suffixMatches = append(suffixMatches, r)
+	// A service node whose name exactly matches the term is a confident pick.
+	for _, svc := range store.ByKind(facts.KindService) {
+		if strings.EqualFold(svc.Name, term) {
+			return svc.Name, nil, nil
 		}
 	}
-	if len(suffixMatches) == 1 {
-		return suffixMatches[0].Name, nil, nil
+
+	// Multiple matches: rank by relevance score and judge how decisively the top
+	// candidate wins.
+	ranked := rankCandidates(results, sq)
+	confidence := pickConfidence(ranked, sq.Term)
+	top := ranked[0].Name
+
+	// One candidate clearly dominates (e.g. a unique suffix-exact name among
+	// substring matches). Auto-resolve to it, but surface the resolution with its
+	// confidence and the alternatives so the caller can see — and override — the
+	// pick rather than it being silent.
+	if confidence > autoPickConfidence {
+		return top, &nameResolution{
+			Query:        query,
+			Matched:      top,
+			Alternatives: candidateNames(results, top),
+			Candidates:   topCandidates(ranked),
+			Confidence:   confidence,
+			AutoPicked:   true,
+			Ambiguous:    true,
+		}, nil
 	}
 
-	// Beyond this point the pick is a heuristic guess, so the result is
-	// ambiguous. If the candidate count crosses the threshold, refuse to guess
-	// and force an exact re-invocation — unless the input is the exact name of
-	// a service node, in which case we pick it confidently.
-	if len(results) >= ambiguousMatchThreshold {
-		for _, svc := range store.ByKind(facts.KindService) {
-			if strings.EqualFold(svc.Name, input) {
-				return svc.Name, nil, nil
-			}
-		}
-		return "", &nameResolution{
+	// Below the ambiguity threshold, return the best guess (flagged ambiguous),
+	// preserving the long-standing "small ambiguity → pick anyway" behavior.
+	if len(results) < ambiguousMatchThreshold {
+		return top, &nameResolution{
 			Query:        query,
-			Alternatives: candidateNames(results, ""),
+			Matched:      top,
+			Alternatives: candidateNames(results, top),
+			Candidates:   topCandidates(ranked),
+			Confidence:   confidence,
 			Ambiguous:    true,
 		}, nil
 	}
 
-	// Below threshold: pick the most likely candidate but flag the ambiguity.
+	// Too ambiguous to guess: surface ranked candidates and refuse to pick.
+	return "", &nameResolution{
+		Query:        query,
+		Alternatives: candidateNames(results, ""),
+		Candidates:   topCandidates(ranked),
+		Confidence:   confidence,
+		Ambiguous:    true,
+	}, nil
+}
 
-	// 2. Among suffix matches (or all results), prefer struct/class/interface
-	candidates := results
-	if len(suffixMatches) > 0 {
-		candidates = suffixMatches
+// gatherCandidates returns the facts matching a (possibly scoped) query. Unscoped
+// inputs use the legacy substring Query to preserve existing semantics. Scoped
+// inputs use QueryAdvanced with repo/kind/file-prefix filters (expanding the file
+// prefix across repos in multi-repo mode) and an optional symbol_kind post-filter.
+func (s *Server) gatherCandidates(store *facts.Store, sq scopedQuery, term string) []facts.Fact {
+	scoped := sq.Repo != "" || len(sq.Kinds) > 0 || sq.FilePrefix != "" || sq.SymbolKind != ""
+	if !scoped {
+		return store.Query("", "", term, "")
 	}
-	matched := results[0].Name
-	for _, r := range candidates {
-		sk, _ := r.Props["symbol_kind"].(string)
-		if sk == "struct" || sk == "class" || sk == "interface" {
-			matched = r.Name
-			break
-		}
+
+	prefixes := []string{""}
+	if sq.FilePrefix != "" {
+		prefixes = s.expandFilePrefix(sq.FilePrefix)
 	}
-	// 3. Prefer module-level facts over symbol-level (only if no struct/class/
-	//    interface was chosen above).
-	if matched == results[0].Name {
-		for _, r := range candidates {
-			if r.Kind == facts.KindModule {
-				matched = r.Name
-				break
+
+	seen := make(map[string]struct{})
+	var out []facts.Fact
+	for _, pfx := range prefixes {
+		res, _ := store.QueryAdvanced(facts.QueryOpts{
+			Repo:       sq.Repo,
+			Kinds:      sq.Kinds,
+			FilePrefix: pfx,
+			Name:       term,
+			Limit:      500,
+		})
+		for _, f := range res {
+			if sq.SymbolKind != "" {
+				if sk, _ := f.Props["symbol_kind"].(string); sk != sq.SymbolKind {
+					continue
+				}
 			}
+			if _, dup := seen[f.Name]; dup {
+				continue
+			}
+			seen[f.Name] = struct{}{}
+			out = append(out, f)
 		}
 	}
+	return out
+}
 
-	return matched, &nameResolution{
-		Query:        query,
-		Matched:      matched,
-		Alternatives: candidateNames(results, matched),
-		Ambiguous:    true,
-	}, nil
+// topCandidates returns up to maxCandidates ranked candidates.
+func topCandidates(ranked []scoredCandidate) []scoredCandidate {
+	if len(ranked) > maxCandidates {
+		return ranked[:maxCandidates]
+	}
+	return ranked
 }
 
 // resolveRepoLabelToServiceNode maps a user-supplied label to the corresponding
@@ -881,9 +941,9 @@ type exploreArgs struct {
 
 // traverseArgs are the arguments for the traverse tool.
 type traverseArgs struct {
-	Start         string   `json:"start" jsonschema:"required,Starting node name (fact name, module name, or symbol name). Substring match."`
+	Start         string   `json:"start" jsonschema:"required,Starting node name (fact name, module name, or symbol name). Substring match; supports scoped prefixes repo:/kind:/file: to disambiguate (e.g. 'repo:go-auth kind:struct AuthHandler')."`
 	Direction     string   `json:"direction,omitempty" jsonschema:"'forward' follows outgoing relations (what does X depend on?), 'reverse' follows incoming relations (what depends on X?). Default: forward."`
-	RelationKinds []string `json:"relation_kinds,omitempty" jsonschema:"Filter to specific relation types: imports, calls, declares, implements, depends_on. Default: all."`
+	RelationKinds []string `json:"relation_kinds,omitempty" jsonschema:"Filter to specific relation types: imports, calls, declares, implements, depends_on, has_method. Default: all."`
 	MaxDepth      int      `json:"max_depth,omitempty" jsonschema:"Maximum traversal depth (1-20). Default: 5."`
 	MaxNodes      int      `json:"max_nodes,omitempty" jsonschema:"Maximum nodes to return (1-500). Traversal stops when this limit is reached. Default: 100."`
 	NodeKinds     []string `json:"node_kinds,omitempty" jsonschema:"Filter results to specific fact kinds: module, symbol, dependency, route, storage. Default: all."`
@@ -891,15 +951,15 @@ type traverseArgs struct {
 
 // findPathArgs are the arguments for the find_path tool.
 type findPathArgs struct {
-	From          string   `json:"from" jsonschema:"required,Source node name (substring match)."`
-	To            string   `json:"to" jsonschema:"required,Target node name (substring match)."`
+	From          string   `json:"from" jsonschema:"required,Source node name. Substring match; supports scoped prefixes repo:/kind:/file: to disambiguate (e.g. 'repo:go-auth Login')."`
+	To            string   `json:"to" jsonschema:"required,Target node name. Substring match; supports scoped prefixes repo:/kind:/file: to disambiguate (e.g. 'kind:struct AuthMiddleware')."`
 	RelationKinds []string `json:"relation_kinds,omitempty" jsonschema:"Filter to specific relation types. Default: all."`
 	MaxDepth      int      `json:"max_depth,omitempty" jsonschema:"Maximum path length to search (1-20). Default: 10."`
 }
 
 // impactAnalysisArgs are the arguments for the impact_analysis tool.
 type impactAnalysisArgs struct {
-	Target         string `json:"target" jsonschema:"required,The node being changed (fact name, substring match)."`
+	Target         string `json:"target" jsonschema:"required,The node being changed (fact name, substring match). Supports scoped prefixes repo:/kind:/file: to disambiguate."`
 	MaxDepth       int    `json:"max_depth,omitempty" jsonschema:"How many hops of impact to compute (1-10). Default: 3."`
 	MaxNodes       int    `json:"max_nodes,omitempty" jsonschema:"Maximum impacted nodes to return (1-500). Default: 200."`
 	IncludeForward bool   `json:"include_forward,omitempty" jsonschema:"Include what the target depends on (what might break the target). Default: false."`
diff --git a/internal/server/server_test.go b/internal/server/server_test.go
index 1a03422..6ffce5a 100644
--- a/internal/server/server_test.go
+++ b/internal/server/server_test.go
@@ -1084,7 +1084,9 @@ func TestResolveNodeName_ConfidentSuffixExact(t *testing.T) {
 	srv := newTestServer(store)
 
 	// "Query" hits internal/facts.Store.Query and internal/server.handleQuery,
-	// but only the former's last segment equals "Query" — a confident pick.
+	// but only the former's last segment equals "Query" — a confident pick that is
+	// auto-resolved, with the resolution surfaced (Matched + high confidence) for
+	// transparency rather than silently.
 	name, res, err := srv.resolveNodeName(store, "Query")
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -1092,8 +1094,14 @@ func TestResolveNodeName_ConfidentSuffixExact(t *testing.T) {
 	if name != "internal/facts.Store.Query" {
 		t.Errorf("matched = %q, want internal/facts.Store.Query", name)
 	}
-	if res != nil {
-		t.Errorf("expected nil resolution for confident suffix match, got %+v", res)
+	if res == nil || res.Matched != "internal/facts.Store.Query" {
+		t.Fatalf("expected an auto-pick resolution naming the match, got %+v", res)
+	}
+	if !res.AutoPicked {
+		t.Error("a confident unique-suffix pick should be marked AutoPicked")
+	}
+	if res.Confidence <= autoPickConfidence {
+		t.Errorf("confidence = %v, want > %v", res.Confidence, autoPickConfidence)
 	}
 }
 
@@ -1309,3 +1317,164 @@ func TestCapitalize(t *testing.T) {
 		}
 	}
 }
+
+func TestParseScopedQuery(t *testing.T) {
+	cases := []struct {
+		in         string
+		repo       string
+		kinds      []string
+		symbolKind string
+		filePrefix string
+		term       string
+	}{
+		{"Currency", "", nil, "", "", "Currency"},
+		{"repo:golf kind:struct Currency", "golf", []string{"symbol"}, "struct", "", "Currency"},
+		{"kind:module internal/server", "", []string{"module"}, "", "", "internal/server"},
+		{"repo:golf/subtenant", "golf", nil, "", "", "subtenant"},
+		{"kind:symbol/Currency", "", []string{"symbol"}, "", "", "Currency"},
+		{"file:/domain//Currency", "", nil, "", "domain", "Currency"},
+		{"file:domain", "", nil, "", "domain", ""},
+		{"http://example.com", "", nil, "", "", "http://example.com"}, // not a scope keyword
+	}
+	for _, tc := range cases {
+		sq := parseScopedQuery(tc.in)
+		if sq.Repo != tc.repo {
+			t.Errorf("%q: Repo = %q, want %q", tc.in, sq.Repo, tc.repo)
+		}
+		if sq.SymbolKind != tc.symbolKind {
+			t.Errorf("%q: SymbolKind = %q, want %q", tc.in, sq.SymbolKind, tc.symbolKind)
+		}
+		if sq.FilePrefix != tc.filePrefix {
+			t.Errorf("%q: FilePrefix = %q, want %q", tc.in, sq.FilePrefix, tc.filePrefix)
+		}
+		if sq.Term != tc.term {
+			t.Errorf("%q: Term = %q, want %q", tc.in, sq.Term, tc.term)
+		}
+		if strings.Join(sq.Kinds, ",") != strings.Join(tc.kinds, ",") {
+			t.Errorf("%q: Kinds = %v, want %v", tc.in, sq.Kinds, tc.kinds)
+		}
+	}
+}
+
+func TestResolveNodeName_ScopedRepo(t *testing.T) {
+	store := facts.NewStore()
+	store.Add(
+		facts.Fact{Kind: facts.KindSymbol, Name: "domain.Currency", Repo: "golf",
+			File: "golf/domain/currency.go", Props: map[string]any{"symbol_kind": "struct"}},
+		facts.Fact{Kind: facts.KindSymbol, Name: "models.Currency", Repo: "golf-ui",
+			File: "golf-ui/models/currency.go", Props: map[string]any{"symbol_kind": "struct"}},
+	)
+	srv := newTestServer(store)
+
+	name, _, err := srv.resolveNodeName(store, "repo:golf Currency")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if name != "domain.Currency" {
+		t.Errorf("matched = %q, want domain.Currency", name)
+	}
+}
+
+func TestResolveNodeName_ScopedKindStruct(t *testing.T) {
+	store := facts.NewStore()
+	store.Add(
+		facts.Fact{Kind: facts.KindSymbol, Name: "models.Currency", File: "models/currency.go",
+			Props: map[string]any{"symbol_kind": "struct"}},
+		facts.Fact{Kind: facts.KindSymbol, Name: "models.Currency.Format", File: "models/currency.go",
+			Props: map[string]any{"symbol_kind": "method"}},
+		facts.Fact{Kind: facts.KindModule, Name: "internal/currency", Props: map[string]any{"language": "go"}},
+	)
+	srv := newTestServer(store)
+
+	name, _, err := srv.resolveNodeName(store, "kind:struct Currency")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if name != "models.Currency" {
+		t.Errorf("matched = %q, want models.Currency", name)
+	}
+}
+
+func TestResolveNodeName_ScopedFilePrefix(t *testing.T) {
+	store := facts.NewStore()
+	store.Add(
+		facts.Fact{Kind: facts.KindSymbol, Name: "a.Currency", File: "domain/currency.go",
+			Props: map[string]any{"symbol_kind": "struct"}},
+		facts.Fact{Kind: facts.KindSymbol, Name: "b.Currency", File: "api/currency.go",
+			Props: map[string]any{"symbol_kind": "struct"}},
+	)
+	srv := newTestServer(store)
+
+	name, _, err := srv.resolveNodeName(store, "file:domain Currency")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if name != "a.Currency" {
+		t.Errorf("matched = %q, want a.Currency", name)
+	}
+}
+
+func TestResolveNodeName_AutoPickAboveConfidence(t *testing.T) {
+	store := facts.NewStore()
+	store.Add(
+		// Suffix-exact match (tier 1) — its last segment IS the term.
+		facts.Fact{Kind: facts.KindSymbol, Name: "adapters.AuthHandler", File: "adapters/h.go",
+			Props: map[string]any{"symbol_kind": "struct"}},
+		// Substring-only peers (tier 0) — the term is buried in a longer name.
+		facts.Fact{Kind: facts.KindSymbol, Name: "adapters.AuthHandlerFactory", File: "adapters/f.go",
+			Props: map[string]any{"symbol_kind": "struct"}},
+		facts.Fact{Kind: facts.KindSymbol, Name: "middleware.NewAuthHandler", File: "mw/new.go",
+			Props: map[string]any{"symbol_kind": "function"}},
+	)
+	srv := newTestServer(store)
+
+	// Three matches (>= threshold) and no exact whole-name match, but exactly one
+	// has the term as its last segment — it dominates the substring-only peers, so
+	// it auto-picks instead of refusing.
+	name, res, err := srv.resolveNodeName(store, "AuthHandler")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if name != "adapters.AuthHandler" {
+		t.Errorf("matched = %q, want adapters.AuthHandler", name)
+	}
+	if res == nil {
+		t.Fatal("expected a non-nil resolution for an auto-picked match")
+	}
+	if !res.AutoPicked {
+		t.Error("resolution should be marked AutoPicked")
+	}
+	if res.Matched != "adapters.AuthHandler" {
+		t.Errorf("resolution.Matched = %q, want adapters.AuthHandler", res.Matched)
+	}
+	if res.Confidence <= autoPickConfidence {
+		t.Errorf("confidence = %v, want > %v", res.Confidence, autoPickConfidence)
+	}
+	if len(res.Candidates) == 0 {
+		t.Error("expected ranked candidates in the resolution")
+	}
+}
+
+func TestResolveNodeName_OverThresholdReturnsCandidates(t *testing.T) {
+	store := populateAmbiguousStore()
+	srv := newTestServer(store)
+
+	// Near-identical modules → no dominant candidate → refuse, but now with
+	// ranked candidates attached.
+	name, res, err := srv.resolveNodeName(store, "svc-beta")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if name != "" {
+		t.Errorf("expected empty match for ambiguous low-confidence input, got %q", name)
+	}
+	if res == nil || res.Matched != "" {
+		t.Fatalf("expected resolution with empty Matched, got %+v", res)
+	}
+	if len(res.Candidates) == 0 {
+		t.Error("expected ranked candidates to be surfaced")
+	}
+	if res.Confidence > autoPickConfidence {
+		t.Errorf("confidence = %v, should not exceed auto-pick threshold for near-ties", res.Confidence)
+	}
+}

From f8755314a5a7a43ef5ad20b45409ce95f83ea363 Mon Sep 17 00:00:00 2001
From: Dejan Menges <dejan.menges@gmail.com>
Date: Fri, 12 Jun 2026 08:23:36 +0200
Subject: [PATCH 2/6] Adding cross repo linker

---
 internal/extractors/kotlinextractor/kotlin.go |   1 +
 .../extractors/kotlinextractor/retrofit.go    |  75 +++++++++++
 .../kotlinextractor/retrofit_test.go          |  45 +++++++
 .../extractors/swiftextractor/httpclient.go   |  98 ++++++++++++++
 .../swiftextractor/httpclient_test.go         |  53 ++++++++
 internal/extractors/swiftextractor/swift.go   |   5 +-
 internal/extractors/tsextractor/httpclient.go | 125 ++++++++++++++++++
 .../extractors/tsextractor/httpclient_test.go |  51 +++++++
 internal/extractors/tsextractor/ts.go         |   3 +
 internal/linkers/crossrepo/crossrepo.go       |  81 ++++++++++--
 internal/linkers/crossrepo/crossrepo_test.go  | 111 ++++++++++++++--
 11 files changed, 625 insertions(+), 23 deletions(-)
 create mode 100644 internal/extractors/kotlinextractor/retrofit.go
 create mode 100644 internal/extractors/kotlinextractor/retrofit_test.go
 create mode 100644 internal/extractors/swiftextractor/httpclient.go
 create mode 100644 internal/extractors/swiftextractor/httpclient_test.go
 create mode 100644 internal/extractors/tsextractor/httpclient.go
 create mode 100644 internal/extractors/tsextractor/httpclient_test.go

diff --git a/internal/extractors/kotlinextractor/kotlin.go b/internal/extractors/kotlinextractor/kotlin.go
index 1c4bea5..db63380 100644
--- a/internal/extractors/kotlinextractor/kotlin.go
+++ b/internal/extractors/kotlinextractor/kotlin.go
@@ -75,6 +75,7 @@ func (e *KotlinExtractor) Extract(ctx context.Context, repoPath string, files []
 		}
 
 		allFacts = append(allFacts, extractFileAST(src, relFile, isAndroid, sourceRoot, basePackage)...)
+		allFacts = append(allFacts, extractRetrofitFacts(src, relFile)...)
 		modules[filepath.Dir(relFile)] = true
 	}
 
diff --git a/internal/extractors/kotlinextractor/retrofit.go b/internal/extractors/kotlinextractor/retrofit.go
new file mode 100644
index 0000000..1768521
--- /dev/null
+++ b/internal/extractors/kotlinextractor/retrofit.go
@@ -0,0 +1,75 @@
+package kotlinextractor
+
+import (
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/enola-labs/enola/internal/facts"
+)
+
+// retrofitAnnotation matches a Retrofit HTTP method annotation on an interface
+// method, capturing the verb and the path string literal, e.g.
+//
+//	@GET("/api/settings/entitlements/users/{userID}/active")
+//	@POST("auth/login")
+var retrofitAnnotation = regexp.MustCompile(`@(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\s*\(\s*"([^"]*)"`)
+
+// extractRetrofitFacts emits a client-route fact for every Retrofit endpoint
+// annotation in a Kotlin source file. These represent outbound HTTP calls the
+// app makes, so the cross-repo linker can match them (by method + path suffix)
+// to the backend route that serves them. Path prefixes are inconsistent across
+// services (some "/api/...", some base-relative) — suffix matching reconciles
+// that, so we emit the path as written.
+func extractRetrofitFacts(src []byte, relFile string) []facts.Fact {
+	var out []facts.Fact
+	dir := filepath.ToSlash(filepath.Dir(relFile))
+	api := apiHint(relFile)
+
+	for i, line := range strings.Split(string(src), "\n") {
+		m := retrofitAnnotation.FindStringSubmatch(line)
+		if m == nil {
+			continue
+		}
+		method := strings.ToUpper(m[1])
+		path := cleanClientPath(m[2])
+		if path == "" {
+			continue
+		}
+		out = append(out, facts.Fact{
+			Kind: facts.KindRoute,
+			Name: path,
+			File: relFile,
+			Line: i + 1,
+			Props: map[string]any{
+				"role":      "client",
+				"method":    method,
+				"framework": "retrofit",
+				"language":  "kotlin",
+				"source":    "retrofit",
+				"api":       api,
+			},
+			Relations: []facts.Relation{{Kind: facts.RelDeclares, Target: dir}},
+		})
+	}
+	return out
+}
+
+// cleanClientPath strips a query string from a client route path and trims
+// surrounding whitespace. Path parameters are left as written; the linker's
+// normalizePath collapses {x}/:x/<x> forms.
+func cleanClientPath(p string) string {
+	p = strings.TrimSpace(p)
+	if i := strings.IndexByte(p, '?'); i >= 0 {
+		p = p[:i]
+	}
+	return p
+}
+
+// apiHint returns the source file's base name without extension (e.g.
+// "EntitlementApiService"), used as the cross-repo linker's provider
+// disambiguation hint.
+func apiHint(relFile string) string {
+	base := filepath.Base(relFile)
+	return strings.TrimSuffix(base, filepath.Ext(base))
+}
diff --git a/internal/extractors/kotlinextractor/retrofit_test.go b/internal/extractors/kotlinextractor/retrofit_test.go
new file mode 100644
index 0000000..ff57206
--- /dev/null
+++ b/internal/extractors/kotlinextractor/retrofit_test.go
@@ -0,0 +1,45 @@
+package kotlinextractor
+
+import "testing"
+
+func TestExtractRetrofitFacts(t *testing.T) {
+	src := `package com.fairwayhub.mygolfjournal.data.api
+
+interface EntitlementApiService {
+    @GET("/api/settings/entitlements/users/{userID}/active")
+    suspend fun getActiveEntitlements(@Path("userID") userID: Int): Response<List<ActiveEntitlementDto>>
+
+    @POST("auth/login")
+    @Headers("X-Client-Type: mobile")
+    suspend fun login(@Body request: LoginRequest): Response<LoginResponse>
+}
+`
+	ff := extractRetrofitFacts([]byte(src), "data/api/EntitlementApiService.kt")
+	if len(ff) != 2 {
+		t.Fatalf("expected 2 client routes, got %d: %+v", len(ff), ff)
+	}
+
+	byName := map[string]map[string]any{}
+	for _, f := range ff {
+		if f.Kind != "route" {
+			t.Errorf("kind = %q, want route", f.Kind)
+		}
+		if f.Props["role"] != "client" {
+			t.Errorf("%s role = %v, want client", f.Name, f.Props["role"])
+		}
+		if f.Props["framework"] != "retrofit" {
+			t.Errorf("%s framework = %v, want retrofit", f.Name, f.Props["framework"])
+		}
+		if f.Props["api"] != "EntitlementApiService" {
+			t.Errorf("%s api hint = %v, want EntitlementApiService", f.Name, f.Props["api"])
+		}
+		byName[f.Name] = f.Props
+	}
+
+	if p, ok := byName["/api/settings/entitlements/users/{userID}/active"]; !ok || p["method"] != "GET" {
+		t.Errorf("missing GET entitlements route; got %+v", byName)
+	}
+	if p, ok := byName["auth/login"]; !ok || p["method"] != "POST" {
+		t.Errorf("missing POST auth/login route (relative path); got %+v", byName)
+	}
+}
diff --git a/internal/extractors/swiftextractor/httpclient.go b/internal/extractors/swiftextractor/httpclient.go
new file mode 100644
index 0000000..181b827
--- /dev/null
+++ b/internal/extractors/swiftextractor/httpclient.go
@@ -0,0 +1,98 @@
+package swiftextractor
+
+import (
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/enola-labs/enola/internal/facts"
+)
+
+// swiftPathComponent matches a URLRequest path built from a base URL, capturing
+// the path literal, e.g. baseURL.appendingPathComponent("settings/feedback").
+var swiftPathComponent = regexp.MustCompile(`appendingPathComponent\(\s*"([^"]*)"`)
+
+// swiftHTTPMethod matches an explicit method assignment, e.g.
+// request.httpMethod = "POST".
+var swiftHTTPMethod = regexp.MustCompile(`\.httpMethod\s*=\s*"([A-Za-z]+)"`)
+
+// swiftInterpolation matches Swift string interpolation, e.g. \(userID).
+var swiftInterpolation = regexp.MustCompile(`\\\([^)]*\)`)
+
+// methodWindow is how many lines after an appendingPathComponent call to scan
+// for the associated httpMethod assignment.
+const methodWindow = 5
+
+// extractURLSessionFacts emits a client-route fact for every URLSession request
+// in a Swift source file. The path comes from baseURL.appendingPathComponent("…")
+// and the HTTP method from a nearby `.httpMethod = "…"` assignment (defaulting
+// to GET when none is found within methodWindow lines). Paths are base-relative
+// (no /api prefix); the cross-repo linker's suffix matching reconciles that
+// against the backend's full path.
+func extractURLSessionFacts(src []byte, relFile string) []facts.Fact {
+	lines := strings.Split(string(src), "\n")
+	dir := filepath.ToSlash(filepath.Dir(relFile))
+	api := swiftAPIHint(relFile)
+
+	var out []facts.Fact
+	for i, line := range lines {
+		pm := swiftPathComponent.FindStringSubmatch(line)
+		if pm == nil {
+			continue
+		}
+		path := cleanSwiftPath(pm[1])
+		if path == "" {
+			continue
+		}
+		method := methodNear(lines, i)
+		out = append(out, facts.Fact{
+			Kind: facts.KindRoute,
+			Name: path,
+			File: relFile,
+			Line: i + 1,
+			Props: map[string]any{
+				"role":      "client",
+				"method":    method,
+				"framework": "urlsession",
+				"language":  "swift",
+				"source":    "urlsession",
+				"api":       api,
+			},
+			Relations: []facts.Relation{{Kind: facts.RelDeclares, Target: dir}},
+		})
+	}
+	return out
+}
+
+// methodNear returns the HTTP method assigned within methodWindow lines at or
+// after idx, or "GET" when none is found (the URLSession default).
+func methodNear(lines []string, idx int) string {
+	end := idx + methodWindow
+	if end >= len(lines) {
+		end = len(lines) - 1
+	}
+	for j := idx; j <= end; j++ {
+		if m := swiftHTTPMethod.FindStringSubmatch(lines[j]); m != nil {
+			return strings.ToUpper(m[1])
+		}
+	}
+	return "GET"
+}
+
+// cleanSwiftPath converts Swift interpolation to the {} placeholder the linker
+// understands and strips any query string.
+func cleanSwiftPath(p string) string {
+	p = swiftInterpolation.ReplaceAllString(p, "{}")
+	p = strings.TrimSpace(p)
+	if i := strings.IndexByte(p, '?'); i >= 0 {
+		p = p[:i]
+	}
+	return p
+}
+
+// swiftAPIHint returns the source file's base name without extension (e.g.
+// "EntitlementAPIService"), used as the cross-repo linker's disambiguation hint.
+func swiftAPIHint(relFile string) string {
+	base := filepath.Base(relFile)
+	return strings.TrimSuffix(base, filepath.Ext(base))
+}
diff --git a/internal/extractors/swiftextractor/httpclient_test.go b/internal/extractors/swiftextractor/httpclient_test.go
new file mode 100644
index 0000000..0d94845
--- /dev/null
+++ b/internal/extractors/swiftextractor/httpclient_test.go
@@ -0,0 +1,53 @@
+package swiftextractor
+
+import "testing"
+
+func TestExtractURLSessionFacts(t *testing.T) {
+	src := `import Foundation
+
+final class EntitlementAPIService {
+    func getDefinitions() async throws -> [EntitlementDto] {
+        var request = URLRequest(url: baseURL.appendingPathComponent("settings/entitlements/definitions"))
+        request.httpMethod = "GET"
+        return try await send(request)
+    }
+
+    func getActive(userID: Int) async throws -> [ActiveEntitlementDto] {
+        var request = URLRequest(url: baseURL.appendingPathComponent("settings/entitlements/users/\(userID)/active"))
+        return try await send(request)   // no explicit httpMethod -> default GET
+    }
+
+    func grant(userID: Int) async throws {
+        var urlRequest = URLRequest(url: baseURL.appendingPathComponent("settings/entitlements/users/\(userID)/grant"))
+        urlRequest.httpMethod = "POST"
+        _ = try await send(urlRequest)
+    }
+}
+`
+	ff := extractURLSessionFacts([]byte(src), "Data/Network/EntitlementAPIService.swift")
+	if len(ff) != 3 {
+		t.Fatalf("expected 3 client routes, got %d: %+v", len(ff), ff)
+	}
+
+	byName := map[string]string{} // name -> method
+	for _, f := range ff {
+		if f.Props["role"] != "client" || f.Props["framework"] != "urlsession" {
+			t.Errorf("%s wrong props: %+v", f.Name, f.Props)
+		}
+		if f.Props["api"] != "EntitlementAPIService" {
+			t.Errorf("%s api hint = %v", f.Name, f.Props["api"])
+		}
+		byName[f.Name] = f.Props["method"].(string)
+	}
+
+	if byName["settings/entitlements/definitions"] != "GET" {
+		t.Errorf("definitions: want GET, got %q", byName["settings/entitlements/definitions"])
+	}
+	// Interpolation collapsed to {}, no httpMethod line -> default GET.
+	if byName["settings/entitlements/users/{}/active"] != "GET" {
+		t.Errorf("active: want default GET on {}, got %+v", byName)
+	}
+	if byName["settings/entitlements/users/{}/grant"] != "POST" {
+		t.Errorf("grant: want POST, got %+v", byName)
+	}
+}
diff --git a/internal/extractors/swiftextractor/swift.go b/internal/extractors/swiftextractor/swift.go
index 3a0a2ec..4fd0348 100644
--- a/internal/extractors/swiftextractor/swift.go
+++ b/internal/extractors/swiftextractor/swift.go
@@ -72,8 +72,8 @@ func (e *SwiftExtractor) Extract(ctx context.Context, repoPath string, files []s
 	isiOS := detectiOSProject(repoPath)
 
 	modules := make(map[string]bool)
-	typeIndex := make(map[string]string)    // simple type name -> module (directory)
-	dirToFile := make(map[string]string)    // module dir -> a representative source file
+	typeIndex := make(map[string]string) // simple type name -> module (directory)
+	dirToFile := make(map[string]string) // module dir -> a representative source file
 	var swiftFiles []string
 	var manifestFiles []string // Package.swift manifests, parsed after the walk
 
@@ -105,6 +105,7 @@ func (e *SwiftExtractor) Extract(ctx context.Context, repoPath string, files []s
 
 		fileFacts := extractFileAST(src, relFile, isiOS)
 		allFacts = append(allFacts, fileFacts...)
+		allFacts = append(allFacts, extractURLSessionFacts(src, relFile)...)
 
 		dir := filepath.Dir(relFile)
 		modules[dir] = true
diff --git a/internal/extractors/tsextractor/httpclient.go b/internal/extractors/tsextractor/httpclient.go
new file mode 100644
index 0000000..9f91df5
--- /dev/null
+++ b/internal/extractors/tsextractor/httpclient.go
@@ -0,0 +1,125 @@
+package tsextractor
+
+import (
+	"bytes"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/enola-labs/enola/internal/facts"
+)
+
+// httpClientCall matches a fetch()/makeRequest() call whose first argument is a
+// string or template literal, capturing the URL literal into one of three
+// groups (double-quote, single-quote, or backtick — RE2 has no backreferences).
+// e.g. this.makeRequest<T>('/api/settings/feedback', { method: 'POST' })
+//
+//	fetch(`${API_BASE_URL}/api/user/current`, { method: 'GET' })
+var httpClientCall = regexp.MustCompile("(?:fetch|makeRequest)\\s*(?:<[^>]*>)?\\s*\\(\\s*(?:\"([^\"]*)\"|'([^']*)'|`([^`]*)`)")
+
+// httpClientMethod matches a `method: 'POST'` option within a call's options
+// object.
+var httpClientMethod = regexp.MustCompile(`method\s*:\s*['"]([A-Za-z]+)['"]`)
+
+// tsInterpolation matches a template-literal interpolation, e.g. ${id}.
+var tsInterpolation = regexp.MustCompile(`\$\{[^}]*\}`)
+
+// httpMethodWindow is how many bytes after the URL literal to scan for the
+// request's method option.
+const httpMethodWindow = 200
+
+// extractHTTPClientFacts emits a client-route fact for every hand-written
+// fetch()/makeRequest() call to the backend. The path is the call's first
+// string argument (its leading ${baseURL} token stripped) and the method comes
+// from a nearby `method:` option, defaulting to GET. Paths include the /api
+// prefix here; the cross-repo linker's suffix matching reconciles prefixes.
+func extractHTTPClientFacts(src []byte, relFile string) []facts.Fact {
+	dir := filepath.ToSlash(filepath.Dir(relFile))
+	api := tsAPIHint(relFile)
+
+	var out []facts.Fact
+	for _, m := range httpClientCall.FindAllSubmatchIndex(src, -1) {
+		raw := firstNonEmptyGroup(src, m, 1, 2, 3)
+		path, ok := cleanTSPath(raw)
+		if !ok {
+			continue
+		}
+		method := "GET"
+		end := m[1] + httpMethodWindow
+		if end > len(src) {
+			end = len(src)
+		}
+		if mm := httpClientMethod.FindSubmatch(src[m[1]:end]); mm != nil {
+			method = strings.ToUpper(string(mm[1]))
+		}
+		out = append(out, facts.Fact{
+			Kind: facts.KindRoute,
+			Name: path,
+			File: relFile,
+			Line: 1 + bytes.Count(src[:m[0]], []byte("\n")),
+			Props: map[string]any{
+				"role":      "client",
+				"method":    method,
+				"framework": "fetch",
+				"language":  "typescript",
+				"source":    "ts-http-client",
+				"api":       api,
+			},
+			Relations: []facts.Relation{{Kind: facts.RelDeclares, Target: dir}},
+		})
+	}
+	return out
+}
+
+// firstNonEmptyGroup returns the text of the first matched capture group among
+// the given group indices (FindAllSubmatchIndex layout).
+func firstNonEmptyGroup(src []byte, m []int, groups ...int) string {
+	for _, g := range groups {
+		s, e := m[2*g], m[2*g+1]
+		if s >= 0 && e > s {
+			return string(src[s:e])
+		}
+	}
+	return ""
+}
+
+// cleanTSPath turns a fetch/makeRequest URL literal into a matchable route path,
+// or returns ok=false when it is not a backend path (fully dynamic, external,
+// or empty). It strips a leading ${...} base-URL token, drops the query string,
+// and collapses interpolations to the {} placeholder.
+func cleanTSPath(raw string) (string, bool) {
+	p := strings.TrimSpace(raw)
+	// Strip a leading ${...} base-URL token (e.g. ${API_BASE_URL}).
+	if strings.HasPrefix(p, "${") {
+		if i := strings.IndexByte(p, '}'); i >= 0 {
+			p = p[i+1:]
+		}
+	}
+	// A remaining absolute URL points at a third-party API, not our backend.
+	if strings.HasPrefix(p, "http") {
+		return "", false
+	}
+	if i := strings.IndexByte(p, '?'); i >= 0 {
+		p = p[:i]
+	}
+	p = tsInterpolation.ReplaceAllString(p, "{}")
+	p = strings.TrimSpace(p)
+	if p == "" || p == "/" {
+		return "", false
+	}
+	// Require at least one concrete (non-placeholder) segment so a fully dynamic
+	// URL (e.g. just "${endpoint}") is skipped.
+	for _, seg := range strings.Split(p, "/") {
+		if seg != "" && seg != "{}" {
+			return p, true
+		}
+	}
+	return "", false
+}
+
+// tsAPIHint returns the source file's base name without extension (e.g.
+// "feedback"), used as the cross-repo linker's disambiguation hint.
+func tsAPIHint(relFile string) string {
+	base := filepath.Base(relFile)
+	return strings.TrimSuffix(base, filepath.Ext(base))
+}
diff --git a/internal/extractors/tsextractor/httpclient_test.go b/internal/extractors/tsextractor/httpclient_test.go
new file mode 100644
index 0000000..94f02f4
--- /dev/null
+++ b/internal/extractors/tsextractor/httpclient_test.go
@@ -0,0 +1,51 @@
+package tsextractor
+
+import "testing"
+
+func TestExtractHTTPClientFacts(t *testing.T) {
+	src := "class FeedbackApi {\n" +
+		"  async createFeedback(data: any) {\n" +
+		"    return this.makeRequest<any>('/api/settings/feedback', { method: 'POST' });\n" +
+		"  }\n" +
+		"  async respond(id: number) {\n" +
+		"    return this.makeRequest<any>(`/api/settings/feedback/${id}/respond`, {\n" +
+		"      method: 'PUT',\n" +
+		"    });\n" +
+		"  }\n" +
+		"  async stats() {\n" +
+		"    return this.makeRequest<any>('/api/settings/feedback/statistics');\n" + // default GET
+		"  }\n" +
+		"  async external() {\n" +
+		"    return fetch('https://third.party/v1/thing', { method: 'GET' });\n" + // skipped
+		"  }\n" +
+		"}\n"
+
+	ff := extractHTTPClientFacts([]byte(src), "src/lib/api/feedback.ts")
+
+	byName := map[string]string{} // name -> method
+	for _, f := range ff {
+		if f.Props["role"] != "client" || f.Props["framework"] != "fetch" {
+			t.Errorf("%s wrong props: %+v", f.Name, f.Props)
+		}
+		if f.Props["api"] != "feedback" {
+			t.Errorf("%s api hint = %v, want feedback", f.Name, f.Props["api"])
+		}
+		byName[f.Name] = f.Props["method"].(string)
+	}
+
+	if len(byName) != 3 {
+		t.Fatalf("expected 3 backend client routes (external skipped), got %d: %+v", len(byName), byName)
+	}
+	if byName["/api/settings/feedback"] != "POST" {
+		t.Errorf("createFeedback: want POST, got %+v", byName)
+	}
+	if byName["/api/settings/feedback/{}/respond"] != "PUT" {
+		t.Errorf("respond: want PUT with {} param, got %+v", byName)
+	}
+	if byName["/api/settings/feedback/statistics"] != "GET" {
+		t.Errorf("stats: want default GET, got %+v", byName)
+	}
+	if _, found := byName["https://third.party/v1/thing"]; found {
+		t.Errorf("external URL should have been skipped: %+v", byName)
+	}
+}
diff --git a/internal/extractors/tsextractor/ts.go b/internal/extractors/tsextractor/ts.go
index 4479c33..21c2b85 100644
--- a/internal/extractors/tsextractor/ts.go
+++ b/internal/extractors/tsextractor/ts.go
@@ -148,6 +148,9 @@ func (e *TSExtractor) extractFile(src []byte, relFile string, isNextJS bool, ali
 		result = append(result, openapiRoutes...)
 	}
 
+	// Hand-written fetch / makeRequest API calls are also client-role routes.
+	result = append(result, extractHTTPClientFacts(src, relFile)...)
+
 	lang := typescript.LanguageTypescript()
 	if strings.HasSuffix(relFile, ".tsx") {
 		lang = typescript.LanguageTSX()
diff --git a/internal/linkers/crossrepo/crossrepo.go b/internal/linkers/crossrepo/crossrepo.go
index 2c77c1c..136d89f 100644
--- a/internal/linkers/crossrepo/crossrepo.go
+++ b/internal/linkers/crossrepo/crossrepo.go
@@ -36,6 +36,13 @@ const SyntheticMarker = "crossrepo"
 // maxSamples bounds how many endpoint / import samples an edge fact carries.
 const maxSamples = 25
 
+// minSharedSegments is the fewest trailing path segments a client and server
+// route must share for a suffix match. Two segments (e.g. "settings/feedback")
+// keeps the join specific enough to avoid false positives while tolerating the
+// base-path/prefix differences between a server's full path ("/api/settings/...")
+// and a client's base-relative call ("settings/...").
+const minSharedSegments = 2
+
 // edge accumulates everything justifying one consumer -> provider dependency.
 type edge struct {
 	consumer  string
@@ -66,7 +73,18 @@ func ComputeLinks(all []facts.Fact) []facts.Fact {
 	linkHTTP(all, edges)
 	linkImports(all, normToLabel, edges)
 
-	return materialize(edges)
+	return materialize(edges, repoLabels(normToLabel))
+}
+
+// repoLabels returns the actual repo labels (the values of the
+// normalized-label lookup), sorted for deterministic output.
+func repoLabels(normToLabel map[string]string) []string {
+	out := make([]string, 0, len(normToLabel))
+	for _, label := range normToLabel {
+		out = append(out, label)
+	}
+	sort.Strings(out)
+	return out
 }
 
 // repoLabelLookup returns a map from normalized repo label to the actual label,
@@ -105,9 +123,15 @@ func linkHTTP(all []facts.Fact, edges map[string]*edge) {
 			continue
 		}
 		ref := routeRef{repo: f.Repo, method: method, path: f.Name}
+		// Index every trailing-segment suffix of each server path, so a client
+		// that calls a base-relative subpath ("settings/x") still matches a
+		// server serving the full path ("/api/settings/x"). serverPaths already
+		// returns normalized paths.
 		for _, p := range serverPaths(f) {
-			key := routeKey(p, method)
-			server[key] = append(server[key], ref)
+			for _, suf := range pathSuffixes(p) {
+				key := routeKey(suf, method)
+				server[key] = append(server[key], ref)
+			}
 		}
 	}
 
@@ -124,7 +148,9 @@ func linkHTTP(all []facts.Fact, edges map[string]*edge) {
 		if isGenericPath(np) {
 			continue
 		}
-		matches := server[routeKey(np, method)]
+		// Canonicalize the leading slash so a base-relative client path
+		// ("settings/x") matches the indexed suffix form ("/settings/x").
+		matches := server[routeKey(canonicalLeadingSlash(np), method)]
 		provider := pickProvider(f, matches)
 		if provider == "" || provider == f.Repo {
 			continue
@@ -259,11 +285,7 @@ func edgeFor(edges map[string]*edge, consumer, provider string) *edge {
 	return e
 }
 
-func materialize(edges map[string]*edge) []facts.Fact {
-	if len(edges) == 0 {
-		return nil
-	}
-
+func materialize(edges map[string]*edge, allRepos []string) []facts.Fact {
 	// Stable order over edges.
 	keys := make([]string, 0, len(edges))
 	for k := range edges {
@@ -310,6 +332,12 @@ func materialize(edges map[string]*edge) []facts.Fact {
 		})
 	}
 
+	// Every loaded repo becomes an addressable service node, even with no
+	// cross-repo edges, so find_path/traverse can resolve isolated repo labels.
+	for _, r := range allRepos {
+		repoSet[r] = true
+	}
+
 	// Service nodes first (sorted), then dependency edges. Each consumer's
 	// service node gets a depends_on relation per provider, which BuildGraph
 	// turns into the cross-repo graph edge.
@@ -387,6 +415,41 @@ func normalizePath(p string) string {
 	return strings.Join(segs, "/")
 }
 
+// pathSuffixes returns every trailing-segment suffix of a normalized path that
+// has at least minSharedSegments non-empty segments, longest first. Each suffix
+// is rendered leading-slash-canonical ("/seg/seg/..."), so a server path
+// "/api/settings/entitlements/definitions" yields:
+//
+//	/api/settings/entitlements/definitions
+//	/settings/entitlements/definitions
+//	/entitlements/definitions
+//
+// ("definitions" alone is dropped: below minSharedSegments). This lets a client
+// calling a base-relative subpath match the server serving the full path.
+func pathSuffixes(normPath string) []string {
+	var segs []string
+	for _, s := range strings.Split(normPath, "/") {
+		if s != "" {
+			segs = append(segs, s)
+		}
+	}
+	var out []string
+	for start := 0; start+minSharedSegments <= len(segs); start++ {
+		out = append(out, "/"+strings.Join(segs[start:], "/"))
+	}
+	return out
+}
+
+// canonicalLeadingSlash ensures a non-empty path starts with "/", so a
+// base-relative client path ("settings/x") compares equal to the indexed
+// suffix form ("/settings/x").
+func canonicalLeadingSlash(p string) string {
+	if p == "" || strings.HasPrefix(p, "/") {
+		return p
+	}
+	return "/" + p
+}
+
 // isGenericPath reports whether a path is too low-signal to safely link on
 // (e.g. /health, /status) — no path parameter and fewer than two segments.
 func isGenericPath(normPath string) bool {
diff --git a/internal/linkers/crossrepo/crossrepo_test.go b/internal/linkers/crossrepo/crossrepo_test.go
index 3346ad7..e71818a 100644
--- a/internal/linkers/crossrepo/crossrepo_test.go
+++ b/internal/linkers/crossrepo/crossrepo_test.go
@@ -79,16 +79,29 @@ func serviceNodes(out []facts.Fact) []string {
 	return names
 }
 
+// crossRepoEdges returns the consumer->provider dependency (evidence) facts —
+// the actual cross-repo edges. Service nodes (which now exist for every loaded
+// repo) are excluded, so this measures "did a link form?".
+func crossRepoEdges(out []facts.Fact) []facts.Fact {
+	var edges []facts.Fact
+	for _, f := range out {
+		if f.Kind == facts.KindDependency {
+			edges = append(edges, f)
+		}
+	}
+	return edges
+}
+
 // --- normalization ---
 
 func TestNormalizePath(t *testing.T) {
 	cases := map[string]string{
-		"/api/items/{id}":  "/api/items/{}",
-		"/api/items/:id":   "/api/items/{}",
-		"/api/items/<id>":  "/api/items/{}",
-		"/api/items/":      "/api/items",
-		"/api/items":       "/api/items",
-		"/":                "/",
+		"/api/items/{id}":         "/api/items/{}",
+		"/api/items/:id":          "/api/items/{}",
+		"/api/items/<id>":         "/api/items/{}",
+		"/api/items/":             "/api/items",
+		"/api/items":              "/api/items",
+		"/":                       "/",
 		"/users/{uid}/pets/{pid}": "/users/{}/pets/{}",
 	}
 	for in, want := range cases {
@@ -169,8 +182,8 @@ func TestComputeLinks_HTTPGenericPathSkipped(t *testing.T) {
 		clientRoute("svc-alpha", "/health", "GET", nil),
 		serverRoute("svc-beta", "/health", "GET"),
 	}
-	if out := ComputeLinks(in); len(out) != 0 {
-		t.Errorf("generic path produced links: %+v", out)
+	if edges := crossRepoEdges(ComputeLinks(in)); len(edges) != 0 {
+		t.Errorf("generic path produced edges: %+v", edges)
 	}
 }
 
@@ -244,12 +257,12 @@ func TestComputeLinks_ImportRubyStyle(t *testing.T) {
 
 func TestComputeLinks_ImportRelativeAndSelfIgnored(t *testing.T) {
 	in := []facts.Fact{
-		importDep("svc-alpha", "./local/thing"),      // relative — skip
-		importDep("svc-alpha", "svc-alpha/inner"),    // self — skip
+		importDep("svc-alpha", "./local/thing"),   // relative — skip
+		importDep("svc-alpha", "svc-alpha/inner"), // self — skip
 		facts.Fact{Kind: facts.KindModule, Name: "x", Repo: "lib-core"},
 	}
-	if out := ComputeLinks(in); len(out) != 0 {
-		t.Errorf("relative/self imports produced links: %+v", out)
+	if edges := crossRepoEdges(ComputeLinks(in)); len(edges) != 0 {
+		t.Errorf("relative/self imports produced edges: %+v", edges)
 	}
 }
 
@@ -287,3 +300,77 @@ func TestComputeLinks_SingleRepoNoLinks(t *testing.T) {
 		t.Errorf("single repo produced links: %+v", out)
 	}
 }
+
+// --- (A) suffix-aware HTTP matching ---
+
+func TestComputeLinks_HTTPSuffixMatch(t *testing.T) {
+	// golf serves the full /api/settings path; consumers call it with varying
+	// prefixes (Swift base-relative, Kotlin/TS with /api). All must link to golf.
+	in := []facts.Fact{
+		serverRoute("golf", "/api/settings/entitlements/definitions", "GET"),
+		clientRoute("ios", "settings/entitlements/definitions", "GET", nil), // base-relative, no slash
+		clientRoute("android", "/api/settings/entitlements/definitions", "GET", nil),
+		clientRoute("golf-ui", "/settings/entitlements/definitions", "GET", nil), // leading slash, no /api
+	}
+	out := ComputeLinks(in)
+	for _, consumer := range []string{"ios", "android", "golf-ui"} {
+		if findEdge(out, consumer, "golf") == nil {
+			t.Errorf("%s did not link to golf via suffix match; out=%+v", consumer, out)
+		}
+		if !hasServiceEdge(out, consumer, "golf") {
+			t.Errorf("%s service node missing depends_on golf", consumer)
+		}
+	}
+}
+
+func TestComputeLinks_HTTPSuffixMinSegments(t *testing.T) {
+	// A single trailing segment is below minSharedSegments → no link.
+	in := []facts.Fact{
+		serverRoute("golf", "/api/settings/definitions", "GET"),
+		clientRoute("ios", "definitions", "GET", nil),
+	}
+	if edges := crossRepoEdges(ComputeLinks(in)); len(edges) != 0 {
+		t.Errorf("single-segment suffix should not link: %+v", edges)
+	}
+}
+
+func TestComputeLinks_HTTPSuffixMethodMismatch(t *testing.T) {
+	in := []facts.Fact{
+		serverRoute("golf", "/api/settings/feedback", "GET"),
+		clientRoute("golf-ui", "settings/feedback", "POST", nil),
+	}
+	if edges := crossRepoEdges(ComputeLinks(in)); len(edges) != 0 {
+		t.Errorf("method mismatch should not link: %+v", edges)
+	}
+}
+
+// --- (A2) per-repo service nodes ---
+
+func TestComputeLinks_PerRepoServiceNodes(t *testing.T) {
+	// Five loaded repos but only one real edge (golf -> go-auth import). Every
+	// repo must still get an addressable service node; edgeless ones carry no
+	// depends_on relations.
+	in := []facts.Fact{
+		importDep("golf", "github.com/x/go-auth/adapters"),
+		facts.Fact{Kind: facts.KindModule, Name: "adapters", Repo: "go-auth"},
+		facts.Fact{Kind: facts.KindModule, Name: "src/ui", Repo: "golf-ui"},
+		facts.Fact{Kind: facts.KindModule, Name: "app", Repo: "android"},
+		facts.Fact{Kind: facts.KindModule, Name: "App", Repo: "ios"},
+	}
+	out := ComputeLinks(in)
+
+	got := serviceNodes(out)
+	want := []string{"android", "go-auth", "golf", "golf-ui", "ios"}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("service nodes = %v, want %v", got, want)
+	}
+	if findEdge(out, "golf", "go-auth") == nil {
+		t.Errorf("expected the golf -> go-auth import edge to remain")
+	}
+	// An edgeless repo's service node has no depends_on relations.
+	for _, f := range out {
+		if f.Kind == facts.KindService && f.Name == "golf-ui" && len(f.Relations) != 0 {
+			t.Errorf("isolated repo golf-ui should have no relations, got %+v", f.Relations)
+		}
+	}
+}

From fa766635dbd71e761bb34ef48732881eada8fce9 Mon Sep 17 00:00:00 2001
From: Dejan Menges <dejan.menges@gmail.com>
Date: Fri, 12 Jun 2026 14:12:58 +0200
Subject: [PATCH 3/6] Improving cross repo linking for impact analysis

---
 internal/facts/graph.go      | 114 +++++++++++++++++++++++++++++++----
 internal/facts/graph_test.go |  96 +++++++++++++++++++++++++++++
 2 files changed, 197 insertions(+), 13 deletions(-)

diff --git a/internal/facts/graph.go b/internal/facts/graph.go
index cc2e70d..ff0a448 100644
--- a/internal/facts/graph.go
+++ b/internal/facts/graph.go
@@ -1,6 +1,7 @@
 package facts
 
 import (
+	"sort"
 	"strings"
 	"sync"
 )
@@ -35,6 +36,7 @@ type TraversalNode struct {
 	Kind  string `json:"kind"`
 	File  string `json:"file,omitempty"`
 	Line  int    `json:"line,omitempty"`
+	Repo  string `json:"repo,omitempty"` // owning repo (multi-repo mode); makes cross-repo dependents legible
 	Depth int    `json:"depth"`
 	// Unresolved marks a node whose name is the target of an edge but has no
 	// backing fact in the store. This happens for inferred call targets that
@@ -61,12 +63,13 @@ type TraversalStats struct {
 
 // ImpactResult holds depth-bucketed impact analysis results.
 type ImpactResult struct {
-	Target  string                  `json:"target"`
-	ByDepth map[int][]TraversalNode `json:"by_depth"`
-	Edges   []TraversalEdge         `json:"edges"`
-	Summary string                  `json:"summary"`
-	Stats   TraversalStats          `json:"stats"`
-	Forward *TraversalResult        `json:"forward_dependencies,omitempty"`
+	Target          string                  `json:"target"`
+	ByDepth         map[int][]TraversalNode `json:"by_depth"`
+	Edges           []TraversalEdge         `json:"edges"`
+	Summary         string                  `json:"summary"`
+	Stats           TraversalStats          `json:"stats"`
+	Forward         *TraversalResult        `json:"forward_dependencies,omitempty"`
+	CrossRepoImpact []string                `json:"cross_repo_impact,omitempty"` // other repos with a dependent on the target
 }
 
 // PathResult holds a shortest-path result.
@@ -212,6 +215,14 @@ func (g *Graph) methodOwner(name string) string {
 // maxDepth limits traversal depth (0 = use default 5).
 // maxNodes limits total returned nodes (0 = use default 100).
 func (g *Graph) Traverse(start, direction string, relKinds, nodeKinds []string, maxDepth, maxNodes int) TraversalResult {
+	return g.traverseFrom([]string{start}, direction, relKinds, nodeKinds, maxDepth, maxNodes)
+}
+
+// traverseFrom is the multi-source BFS underlying Traverse. Every name in starts
+// is seeded at depth 0 (deduplicated), so a logical entity spread across several
+// fact nodes — e.g. a type plus its methods and constructor — can be traversed as
+// one origin. Single-source callers pass a one-element slice.
+func (g *Graph) traverseFrom(starts []string, direction string, relKinds, nodeKinds []string, maxDepth, maxNodes int) TraversalResult {
 	g.mu.RLock()
 	defer g.mu.RUnlock()
 
@@ -244,10 +255,16 @@ func (g *Graph) Traverse(start, direction string, relKinds, nodeKinds []string,
 		depth int
 	}
 
-	// Add start node
-	visited[start] = true
-	queue := []queueItem{{name: start, depth: 0}}
-	result.Nodes = append(result.Nodes, g.nodeFor(start, 0))
+	// Seed every start node at depth 0.
+	var queue []queueItem
+	for _, start := range starts {
+		if visited[start] {
+			continue
+		}
+		visited[start] = true
+		queue = append(queue, queueItem{name: start, depth: 0})
+		result.Nodes = append(result.Nodes, g.nodeFor(start, 0))
+	}
 
 	truncated := false
 	maxDepthReached := 0
@@ -443,8 +460,11 @@ func (g *Graph) ImpactSet(target string, maxDepth, maxNodes int, includeForward
 		maxNodes = 500
 	}
 
-	// Reverse traversal: who depends on target?
-	rev := g.Traverse(target, "reverse", nil, nil, maxDepth, maxNodes)
+	// Reverse traversal: who depends on target? When the target is a type, seed
+	// from its methods (via has_method) and constructor too, so callers that
+	// reference the type through those — not the bare type node — are included.
+	seeds := g.impactSeeds(target)
+	rev := g.traverseFrom(seeds, "reverse", nil, nil, maxDepth, maxNodes)
 
 	result := ImpactResult{
 		Target:  target,
@@ -453,15 +473,32 @@ func (g *Graph) ImpactSet(target string, maxDepth, maxNodes int, includeForward
 		Stats:   rev.Stats,
 	}
 
-	// Bucket nodes by depth (skip depth 0 which is the target itself)
+	// Bucket nodes by depth (skip depth 0, which holds the target entity's own
+	// seed nodes) and roll up which other repos contain a dependent.
+	targetRepo := g.repoOf(target)
+	repoSet := map[string]bool{}
 	for _, n := range rev.Nodes {
 		if n.Depth > 0 {
 			result.ByDepth[n.Depth] = append(result.ByDepth[n.Depth], n)
+			if n.Repo != "" && n.Repo != targetRepo {
+				repoSet[n.Repo] = true
+			}
+		}
+	}
+	if len(repoSet) > 0 {
+		repos := make([]string, 0, len(repoSet))
+		for r := range repoSet {
+			repos = append(repos, r)
 		}
+		sort.Strings(repos)
+		result.CrossRepoImpact = repos
 	}
 
 	// Build summary
 	result.Summary = g.buildImpactSummary(result.ByDepth)
+	if len(result.CrossRepoImpact) > 0 {
+		result.Summary += " — spans repos: " + strings.Join(result.CrossRepoImpact, ", ")
+	}
 
 	// Optionally include forward dependencies
 	if includeForward {
@@ -472,6 +509,56 @@ func (g *Graph) ImpactSet(target string, maxDepth, maxNodes int, includeForward
 	return result
 }
 
+// repoOf returns the repo label of the fact named name, or "" if absent.
+func (g *Graph) repoOf(name string) string {
+	g.mu.RLock()
+	defer g.mu.RUnlock()
+	if idx, ok := g.factIdx[name]; ok && idx < len(g.facts) {
+		return g.facts[idx].Repo
+	}
+	return ""
+}
+
+// impactSeeds returns the set of fact names that together represent the target
+// entity for impact analysis. For a type symbol (struct/class/interface/type)
+// this is the type plus its methods (via has_method edges) and its constructor
+// (the New<Type> function in the same package, when present), so reverse
+// traversal finds callers that reference the type through any of them. For any
+// other target it is just the target itself.
+func (g *Graph) impactSeeds(target string) []string {
+	g.mu.RLock()
+	defer g.mu.RUnlock()
+
+	seeds := []string{target}
+	idx, ok := g.factIdx[target]
+	if !ok || idx >= len(g.facts) {
+		return seeds
+	}
+	if g.facts[idx].Kind != KindSymbol {
+		return seeds
+	}
+	switch sk, _ := g.facts[idx].Props["symbol_kind"].(string); sk {
+	case SymbolStruct, SymbolClass, SymbolInterface, SymbolType:
+	default:
+		return seeds
+	}
+
+	// Methods: has_method edges point from the type to each of its methods.
+	for _, e := range g.forward[target] {
+		if e.RelKind == RelHasMethod {
+			seeds = append(seeds, e.Target)
+		}
+	}
+	// Constructor: "<pkg>.New<Type>" in the same package, when it exists.
+	if dot := strings.LastIndex(target, "."); dot >= 0 {
+		ctor := target[:dot+1] + "New" + target[dot+1:]
+		if _, ok := g.factIdx[ctor]; ok {
+			seeds = append(seeds, ctor)
+		}
+	}
+	return seeds
+}
+
 // normalizeExternalTarget strips a known Go module path prefix from a call
 // target that doesn't match any fact. This bridges cross-repo call edges where
 // the consumer emits the full import path (e.g. "github.com/x/go-auth/adapters.Handler.Login")
@@ -604,6 +691,7 @@ func (g *Graph) nodeFor(name string, depth int) TraversalNode {
 		node.Kind = f.Kind
 		node.File = f.File
 		node.Line = f.Line
+		node.Repo = f.Repo
 	} else {
 		// No backing fact: this is a dangling edge target (e.g. an inferred call
 		// into an unanalyzed package or an interface method). Mark it honestly
diff --git a/internal/facts/graph_test.go b/internal/facts/graph_test.go
index dd3dd45..681f931 100644
--- a/internal/facts/graph_test.go
+++ b/internal/facts/graph_test.go
@@ -1,6 +1,7 @@
 package facts
 
 import (
+	"reflect"
 	"testing"
 )
 
@@ -745,3 +746,98 @@ func TestTraverse_UnresolvedTargetMarked(t *testing.T) {
 		t.Error("expected the resolved node jwt.Sign in the result")
 	}
 }
+
+// buildCrossRepoTypeStore models a go-auth library type (struct + method +
+// constructor) consumed by a golf caller, mirroring how the cross-repo call
+// normalisation lands golf's calls onto go-auth's local symbol names.
+func buildCrossRepoTypeStore() (*Graph, *Store) {
+	s := NewStore()
+	s.Add(
+		// go-auth: the AuthHandler type, one method, and its constructor.
+		Fact{Kind: KindSymbol, Name: "adapters.AuthHandler", File: "adapters/h.go", Line: 1, Repo: "go-auth",
+			Props: map[string]any{"symbol_kind": SymbolStruct}},
+		Fact{Kind: KindSymbol, Name: "adapters.AuthHandler.Login", File: "adapters/h.go", Line: 10, Repo: "go-auth",
+			Props: map[string]any{"symbol_kind": SymbolMethod}},
+		Fact{Kind: KindSymbol, Name: "adapters.NewAuthHandler", File: "adapters/h.go", Line: 30, Repo: "go-auth",
+			Props: map[string]any{"symbol_kind": SymbolFunc}},
+		// golf: a setup function that calls the constructor and a method.
+		Fact{Kind: KindSymbol, Name: "pkg/auth.Setup", File: "pkg/auth/setup.go", Line: 28, Repo: "golf",
+			Props: map[string]any{"symbol_kind": SymbolFunc}, Relations: []Relation{
+				{Kind: RelCalls, Target: "adapters.NewAuthHandler"},
+				{Kind: RelCalls, Target: "adapters.AuthHandler.Login"},
+			}},
+	)
+	s.BuildGraph()
+	return s.Graph(), s
+}
+
+func TestImpactSet_TypeRollup(t *testing.T) {
+	g, _ := buildCrossRepoTypeStore()
+
+	// Impact on the bare struct must roll up its method + constructor and surface
+	// the cross-repo caller (previously this returned "no dependents").
+	res := g.ImpactSet("adapters.AuthHandler", 3, 100, false)
+
+	names := nodeNames(impactNodes(res))
+	if !contains(names, "pkg/auth.Setup") {
+		t.Errorf("type rollup did not surface cross-repo caller pkg/auth.Setup; got %v", names)
+	}
+	// Seeds (the type entity itself) must not appear as dependents.
+	for _, seed := range []string{"adapters.AuthHandler", "adapters.AuthHandler.Login", "adapters.NewAuthHandler"} {
+		if contains(names, seed) {
+			t.Errorf("seed %q should be excluded from dependents", seed)
+		}
+	}
+	if !reflect.DeepEqual(res.CrossRepoImpact, []string{"golf"}) {
+		t.Errorf("CrossRepoImpact = %v, want [golf]", res.CrossRepoImpact)
+	}
+}
+
+func TestImpactSet_CrossRepoImpactField(t *testing.T) {
+	g, _ := buildCrossRepoTypeStore()
+
+	// A plain function target (not a type) still reports cross-repo dependents and
+	// per-node repo.
+	res := g.ImpactSet("adapters.NewAuthHandler", 2, 100, false)
+
+	if !reflect.DeepEqual(res.CrossRepoImpact, []string{"golf"}) {
+		t.Fatalf("CrossRepoImpact = %v, want [golf]", res.CrossRepoImpact)
+	}
+	var sawRepo bool
+	for _, nodes := range res.ByDepth {
+		for _, n := range nodes {
+			if n.Name == "pkg/auth.Setup" {
+				sawRepo = true
+				if n.Repo != "golf" {
+					t.Errorf("dependent node repo = %q, want golf", n.Repo)
+				}
+			}
+		}
+	}
+	if !sawRepo {
+		t.Error("expected pkg/auth.Setup among dependents")
+	}
+}
+
+func TestImpactSet_NonTypeUnchanged(t *testing.T) {
+	// Single-repo graph (no Repo tags): rollup is inert and CrossRepoImpact stays nil.
+	g, _ := buildTestGraph()
+	res := g.ImpactSet("D", 5, 100, false)
+
+	if res.CrossRepoImpact != nil {
+		t.Errorf("CrossRepoImpact should be nil for same-repo graph, got %v", res.CrossRepoImpact)
+	}
+	// D is called by C (a module here) — at least one dependent is found, as before.
+	if len(impactNodes(res)) == 0 {
+		t.Error("expected at least one dependent for D")
+	}
+}
+
+// impactNodes flattens an ImpactResult's depth buckets into a node slice.
+func impactNodes(res ImpactResult) []TraversalNode {
+	var out []TraversalNode
+	for _, nodes := range res.ByDepth {
+		out = append(out, nodes...)
+	}
+	return out
+}

From fff32e54b96f27eab435a10b84631c108591a009 Mon Sep 17 00:00:00 2001
From: Dejan Menges <dejan.menges@gmail.com>
Date: Fri, 12 Jun 2026 17:51:00 +0200
Subject: [PATCH 4/6] Adding release flow

---
 .github/workflows/ci.yml      | 20 ++++++++
 .github/workflows/release.yml | 90 +++++++++++++++++++++++++++++++++++
 install.sh                    | 63 ++++++++++++++++++++++++
 internal/server/server.go     |  5 +-
 4 files changed, 177 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 .github/workflows/release.yml
 create mode 100755 install.sh

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..37de676
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.25.1"
+          cache: true
+
+      - name: Run tests
+        run: go test -race -count=1 ./...
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..4fe7d52
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,90 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.25.1"
+          cache: true
+
+      - name: Run tests
+        run: go test -race -count=1 ./...
+
+  build:
+    needs: test
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            goos: linux
+            goarch: amd64
+          - os: ubuntu-latest
+            goos: linux
+            goarch: arm64
+          - os: macos-latest
+            goos: darwin
+            goarch: amd64
+          - os: macos-latest
+            goos: darwin
+            goarch: arm64
+          - os: windows-latest
+            goos: windows
+            goarch: amd64
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.25.1"
+          cache: true
+
+      - name: Compute version
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Build binary
+        env:
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          CGO_ENABLED: 1
+        run: |
+          BINARY="enola-${{ steps.version.outputs.version }}-${{ matrix.goos }}-${{ matrix.goarch }}"
+          EXT=""
+          if [ "${{ matrix.goos }}" = "windows" ]; then
+            EXT=".exe"
+          fi
+          go build \
+            -ldflags "-s -w -X github.com/enola-labs/enola/internal/server.Version=${{ steps.version.outputs.version }}" \
+            -o "${BINARY}${EXT}" \
+            ./cmd/enola
+
+      - name: Create tarball
+        shell: bash
+        run: |
+          BINARY="enola-${{ steps.version.outputs.version }}-${{ matrix.goos }}-${{ matrix.goarch }}"
+          EXT=""
+          if [ "${{ matrix.goos }}" = "windows" ]; then
+            EXT=".exe"
+          fi
+          tar czf "${BINARY}.tar.gz" "${BINARY}${EXT}"
+          sha256sum "${BINARY}.tar.gz" > "${BINARY}.sha256"
+
+      - name: Upload to release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            enola-${{ steps.version.outputs.version }}-${{ matrix.goos }}-${{ matrix.goarch }}.tar.gz
+            enola-${{ steps.version.outputs.version }}-${{ matrix.goos }}-${{ matrix.goarch }}.sha256
diff --git a/install.sh b/install.sh
new file mode 100755
index 0000000..c2b1f6b
--- /dev/null
+++ b/install.sh
@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# install.sh — Install the latest enola release.
+# Usage: curl -fsSL https://raw.githubusercontent.com/enola-labs/enola/main/install.sh | sh
+
+set -euo pipefail
+
+# --- Detect OS ---
+OS="$(uname -s)"
+case "$OS" in
+  Linux)   OS=linux ;;
+  Darwin)  OS=darwin ;;
+  *)       echo "Unsupported OS: $OS" >&2; exit 1 ;;
+esac
+
+# --- Detect arch ---
+ARCH="$(uname -m)"
+case "$ARCH" in
+  x86_64)       ARCH=amd64 ;;
+  arm64|aarch64) ARCH=arm64 ;;
+  *)            echo "Unsupported arch: $ARCH" >&2; exit 1 ;;
+esac
+
+# --- Fetch latest version ---
+VERSION="$(curl -fsSL https://api.github.com/repos/enola-labs/enola/releases/latest | grep '"tag_name"' | sed -E 's/.*"v([^"]+)".*/\1/')"
+if [ -z "$VERSION" ]; then
+  echo "Failed to fetch latest version" >&2
+  exit 1
+fi
+
+ASSET="enola-${VERSION}-${OS}-${ARCH}.tar.gz"
+SHASUM="${ASSET}.sha256"
+URL="https://github.com/enola-labs/enola/releases/download/v${VERSION}/${ASSET}"
+SUM_URL="https://github.com/enola-labs/enola/releases/download/v${VERSION}/${SHASUM}"
+
+echo "==> Downloading enola v${VERSION} for ${OS}/${ARCH} ..."
+
+TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR"' EXIT
+
+curl -fsSL -o "$TMPDIR/$ASSET" "$URL"
+curl -fsSL -o "$TMPDIR/$SHASUM" "$SUM_URL"
+
+echo "==> Verifying checksum ..."
+(cd "$TMPDIR" && sha256sum -c "$SHASUM")
+
+echo "==> Extracting ..."
+tar xzf "$TMPDIR/$ASSET" -C "$TMPDIR"
+
+# --- Install ---
+BIN_NAME="enola-${VERSION}-${OS}-${ARCH}"
+if [ "$OS" = "windows" ]; then
+  BIN_NAME="${BIN_NAME}.exe"
+fi
+
+INSTALL_DIR="${ENOLA_INSTALL_DIR:-$HOME/.local/bin}"
+mkdir -p "$INSTALL_DIR"
+
+cp "$TMPDIR/$BIN_NAME" "$INSTALL_DIR/enola"
+
+echo "==> enola v${VERSION} installed to $INSTALL_DIR/enola"
+echo ""
+echo "If \$HOME/.local/bin is not in your PATH, add it:"
+echo "  export PATH=\"$HOME/.local/bin:\$PATH\""
diff --git a/internal/server/server.go b/internal/server/server.go
index 5375172..99d2253 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -16,6 +16,9 @@ import (
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
+// Version is set at build time via -ldflags.
+var Version = "dev"
+
 // Server wraps the MCP server and connects it to the snapshot engine.
 type Server struct {
 	mcp          *mcp.Server
@@ -34,7 +37,7 @@ func New(eng *engine.Engine, cfg *config.Config) (*Server, error) {
 
 	mcpServer := mcp.NewServer(&mcp.Implementation{
 		Name:    "enola",
-		Version: "0.1.0",
+		Version: Version,
 	}, nil)
 
 	s.mcp = mcpServer

From 605f9c86d0d5b96bfa0c21390849b1020d4420b7 Mon Sep 17 00:00:00 2001
From: Dejan Menges <dejan.menges@gmail.com>
Date: Fri, 12 Jun 2026 18:11:05 +0200
Subject: [PATCH 5/6] Fixing release workflow

---
 .github/workflows/release.yml | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 4fe7d52..05bee19 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -5,6 +5,9 @@ on:
     tags:
       - "v*"
 
+permissions:
+  contents: write
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -27,19 +30,19 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - os: ubuntu-latest
+          - os: ubuntu-latest      # linux/amd64
             goos: linux
             goarch: amd64
-          - os: ubuntu-latest
+          - os: ubuntu-24.04-arm   # linux/arm64 — native arm64 runner
             goos: linux
             goarch: arm64
-          - os: macos-latest
+          - os: macos-13           # darwin/amd64 — native Intel runner
             goos: darwin
             goarch: amd64
-          - os: macos-latest
+          - os: macos-latest       # darwin/arm64 — native Apple Silicon
             goos: darwin
             goarch: arm64
-          - os: windows-latest
+          - os: windows-latest     # windows/amd64
             goos: windows
             goarch: amd64
     steps:
@@ -53,9 +56,11 @@ jobs:
 
       - name: Compute version
         id: version
+        shell: bash
         run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
 
       - name: Build binary
+        shell: bash
         env:
           GOOS: ${{ matrix.goos }}
           GOARCH: ${{ matrix.goarch }}

From 9974f773a1070ea9d7cdb5a792a53bb0a215ae04 Mon Sep 17 00:00:00 2001
From: Dejan Menges <dejan.menges@gmail.com>
Date: Fri, 12 Jun 2026 18:41:09 +0200
Subject: [PATCH 6/6] Fixing install script on MacOS

---
 install.sh | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/install.sh b/install.sh
index c2b1f6b..8f702a8 100755
--- a/install.sh
+++ b/install.sh
@@ -27,8 +27,9 @@ if [ -z "$VERSION" ]; then
   exit 1
 fi
 
-ASSET="enola-${VERSION}-${OS}-${ARCH}.tar.gz"
-SHASUM="${ASSET}.sha256"
+BASE="enola-${VERSION}-${OS}-${ARCH}"
+ASSET="${BASE}.tar.gz"
+SHASUM="${BASE}.sha256"
 URL="https://github.com/enola-labs/enola/releases/download/v${VERSION}/${ASSET}"
 SUM_URL="https://github.com/enola-labs/enola/releases/download/v${VERSION}/${SHASUM}"
 
@@ -41,13 +42,17 @@ curl -fsSL -o "$TMPDIR/$ASSET" "$URL"
 curl -fsSL -o "$TMPDIR/$SHASUM" "$SUM_URL"
 
 echo "==> Verifying checksum ..."
-(cd "$TMPDIR" && sha256sum -c "$SHASUM")
+if command -v sha256sum >/dev/null 2>&1; then
+  (cd "$TMPDIR" && sha256sum -c "$SHASUM")
+else
+  (cd "$TMPDIR" && shasum -a 256 -c "$SHASUM")
+fi
 
 echo "==> Extracting ..."
 tar xzf "$TMPDIR/$ASSET" -C "$TMPDIR"
 
 # --- Install ---
-BIN_NAME="enola-${VERSION}-${OS}-${ARCH}"
+BIN_NAME="${BASE}"
 if [ "$OS" = "windows" ]; then
   BIN_NAME="${BIN_NAME}.exe"
 fi