Enhancing cross repo edges for C++

Author: dejo1307

ARCHITECTURE.md

@@ -262,15 +262,16 @@ enola can analyze multiple repositories together. Use `append` mode to increment
 
 ### Linking, not just co-locating
 
-Appending several repos does more than pool their facts — a linking pass connects the per-repo graphs using two signals the extractors already capture:
+Appending several repos does more than pool their facts — a linking pass connects the per-repo graphs using three signals the extractors already capture:
 
 - **HTTP route role matching** — a route a repo *calls* (`role:"client"`, e.g. from a generated OpenAPI client) is matched to a route another repo *serves* (`role:"server"`, or a framework route) by normalized path + method. The caller is recorded as depending on the servee.
 - **Import / shared-lib references** — an import whose scope or leading segment names another loaded repo (e.g. `@app-web/lib-api`, `lib-core/money`) records a dependency on that repo.
+- **Shared symbol surface** — when two repos declare enough of the same distinctive types (e.g. a vendored protocol header copied between them — the `onelab::*` / `GmshClient` / `GmshServer` classes shared by *gmsh* and *getdp*), they are coupled. The match is on each type's portable identity (the namespace-qualified name with the repo-specific directory prefix stripped), filtered to type-like symbols (class/struct/interface/enum) and to distinctive names — namespaced identities always count; bare names must be non-generic and reasonably long. A pair links only above a small shared-type threshold, so an incidental `Config`/`JsonParser` collision can't fabricate a dependency. This relationship is symmetric, so it is emitted as a **bidirectional** pair of edges marked `via:"shared_symbols"`.
 
 These become real, queryable facts:
 
 - A `service` node per repo (`query_facts kind=service`), named by its repo label.
-- A cross-repo dependency edge per `consumer → provider` pair, carrying the matched endpoints and import samples.
+- A cross-repo dependency edge per `consumer → provider` pair, carrying the matched endpoints, import samples, and shared-symbol samples.
 
 Because they're ordinary graph nodes and edges, the traversal tools become cross-repo aware with no extra steps — `traverse`, `find_path`, and `impact_analysis` all reach across repo boundaries. The cross-repo dependencies also appear as a **Cross-Repo Dependencies** section in `llm_context.md`, so an agent reading the snapshot sees them without running a tool.
 

internal/explainers/crossrepo/crossrepo.go

@@ -74,6 +74,9 @@ func edgeDetail(d facts.Fact) string {
 	if n := propInt(d, "import_count"); n > 0 {
 		parts = append(parts, fmt.Sprintf("%d import(s)", n))
 	}
+	if n := propInt(d, "symbol_count"); n > 0 {
+		parts = append(parts, fmt.Sprintf("%d shared symbol(s)", n))
+	}
 	if len(parts) == 0 {
 		return "cross-repo dependency"
 	}

internal/linkers/crossrepo/crossrepo.go

@@ -12,6 +12,11 @@
 //   - Import / shared-lib references: a dependency whose import target names
 //     another loaded repo (by @scope or leading path segment) means the
 //     importer depends on that repo.
+//   - Shared symbol surface: when two repos declare enough of the same
+//     distinctive types (a vendored/shared protocol header, e.g. the onelab
+//     GmshClient/GmshServer classes copied between repos), they are coupled.
+//     This signal is symmetric, so it is emitted as a bidirectional pair of
+//     edges marked via="shared_symbols".
 //
 // The result is expressed as synthetic facts: one KindService node per repo and
 // one KindDependency edge per (consumer -> provider) pair. Because these are
@@ -47,9 +52,10 @@ const minSharedSegments = 2
 type edge struct {
 	consumer  string
 	provider  string
-	via       map[string]bool // "http", "import"
+	via       map[string]bool // "http", "import", "shared_symbols"
 	endpoints map[string]bool // "METHOD /path"
 	imports   map[string]bool // sample import targets
+	symbols   map[string]bool // sample shared type identities
 }
 
 func (e *edge) note(via string) {
@@ -72,6 +78,7 @@ func ComputeLinks(all []facts.Fact) []facts.Fact {
 	edges := map[string]*edge{}
 	linkHTTP(all, edges)
 	linkImports(all, normToLabel, edges)
+	linkSharedSymbols(all, edges)
 
 	return materialize(edges, repoLabels(normToLabel))
 }
@@ -273,6 +280,152 @@ func importCandidates(target string) []string {
 	return out
 }
 
+// --- signal (C): shared symbol surface ---
+
+// minSharedSymbols is the fewest distinct distinctive type identities two repos
+// must share before a shared-symbol edge is drawn. Set above 2 so an incidental
+// name collision (a `JsonParser` both repos happen to define) cannot fabricate a
+// dependency, while genuinely shared/vendored code (a protocol header copied
+// between repos) shares many.
+const minSharedSymbols = 3
+
+// genericTypeNames are common unqualified type names too generic to link on by
+// themselves. Namespaced identities (e.g. "onelab::number") bypass this list —
+// sharing a namespace across repos is itself meaningful.
+var genericTypeNames = map[string]bool{
+	"config": true, "error": true, "manager": true, "options": true,
+	"result": true, "base": true, "impl": true, "utils": true, "util": true,
+	"common": true, "exception": true, "context": true, "data": true,
+	"info": true, "item": true, "node": true, "entry": true, "helper": true,
+	"settings": true, "logger": true, "test": true, "main": true, "model": true,
+	"request": true, "response": true, "status": true, "value": true,
+}
+
+// linkSharedSymbols connects repos that declare enough of the same distinctive
+// types. The relationship is symmetric (shared/vendored code, not a one-way
+// dependency), so qualifying pairs get a bidirectional pair of edges.
+func linkSharedSymbols(all []facts.Fact, edges map[string]*edge) {
+	repoModules := moduleNamesByRepo(all)
+
+	// identity -> set of repos that declare a type with that identity.
+	idToRepos := map[string]map[string]bool{}
+	for _, f := range all {
+		if f.Kind != facts.KindSymbol || f.Repo == "" || !isTypeSymbol(f) {
+			continue
+		}
+		id := typeIdentity(f.Name, repoModules[f.Repo])
+		if !isDistinctiveIdentity(id) {
+			continue
+		}
+		if idToRepos[id] == nil {
+			idToRepos[id] = map[string]bool{}
+		}
+		idToRepos[id][f.Repo] = true
+	}
+
+	// For each identity shared by 2+ repos, record it against every repo pair.
+	// pairShared["a\x00b"] (a<b) -> set of shared identities.
+	pairShared := map[string]map[string]bool{}
+	for id, repos := range idToRepos {
+		if len(repos) < 2 {
+			continue
+		}
+		rs := make([]string, 0, len(repos))
+		for r := range repos {
+			rs = append(rs, r)
+		}
+		sort.Strings(rs)
+		for i := 0; i < len(rs); i++ {
+			for j := i + 1; j < len(rs); j++ {
+				key := rs[i] + "\x00" + rs[j]
+				if pairShared[key] == nil {
+					pairShared[key] = map[string]bool{}
+				}
+				pairShared[key][id] = true
+			}
+		}
+	}
+
+	// Materialize a bidirectional edge for each pair over the threshold.
+	for key, ids := range pairShared {
+		if len(ids) < minSharedSymbols {
+			continue
+		}
+		a, b, _ := strings.Cut(key, "\x00")
+		for _, pair := range [2][2]string{{a, b}, {b, a}} {
+			e := edgeFor(edges, pair[0], pair[1])
+			e.note("shared_symbols")
+			if e.symbols == nil {
+				e.symbols = map[string]bool{}
+			}
+			for id := range ids {
+				e.symbols[id] = true
+			}
+		}
+	}
+}
+
+// isTypeSymbol reports whether a symbol fact is a type-like declaration (the
+// portable "contract surface"), excluding functions, methods, variables, etc.
+func isTypeSymbol(f facts.Fact) bool {
+	switch propString(f, "symbol_kind") {
+	case facts.SymbolClass, facts.SymbolStruct, facts.SymbolInterface, facts.SymbolEnum:
+		return true
+	}
+	return false
+}
+
+// moduleNamesByRepo returns, per repo, the module (directory) names sorted
+// longest-first, so the longest matching prefix can be stripped from a symbol.
+func moduleNamesByRepo(all []facts.Fact) map[string][]string {
+	byRepo := map[string][]string{}
+	for _, f := range all {
+		if f.Kind != facts.KindModule || f.Repo == "" {
+			continue
+		}
+		byRepo[f.Repo] = append(byRepo[f.Repo], f.Name)
+	}
+	for r := range byRepo {
+		ms := byRepo[r]
+		sort.Slice(ms, func(i, j int) bool { return len(ms[i]) > len(ms[j]) })
+	}
+	return byRepo
+}
+
+// typeIdentity strips the repo-specific "<module>." directory prefix from a
+// symbol's name, returning the portable namespace/type-qualified remainder that
+// is shared across repos (e.g. "src/common.onelab::Foo" -> "onelab::Foo",
+// "Common.onelab::Foo" -> "onelab::Foo"). The repo's own module names are used so
+// the differing directory layouts of two repos do not defeat the match.
+func typeIdentity(name string, modules []string) string {
+	for _, m := range modules { // longest first
+		if len(name) > len(m)+1 && strings.HasPrefix(name, m+".") {
+			return name[len(m)+1:]
+		}
+	}
+	// Fallback: strip up to the first "." when no module matched.
+	if i := strings.IndexByte(name, '.'); i >= 0 && i+1 < len(name) {
+		return name[i+1:]
+	}
+	return name
+}
+
+// isDistinctiveIdentity filters out identities too generic to safely link on. A
+// namespaced identity (containing "::" or ".") is always kept; an unqualified one
+// is kept only if it is reasonably long and not a common generic type name.
+func isDistinctiveIdentity(id string) bool {
+	if id == "" {
+		return false
+	}
+	if strings.Contains(id, "::") || strings.Contains(id, ".") {
+		return true
+	}
+	if len(id) < 5 {
+		return false
+	}
+	return !genericTypeNames[strings.ToLower(id)]
+}
+
 // --- materialization ---
 
 func edgeFor(edges map[string]*edge, consumer, provider string) *edge {
@@ -323,6 +476,11 @@ func materialize(edges map[string]*edge, allRepos []string) []facts.Fact {
 			props["import_count"] = len(imps)
 			props["import_samples"] = cap25(imps)
 		}
+		if len(e.symbols) > 0 {
+			syms := sortedKeys(e.symbols)
+			props["symbol_count"] = len(syms)
+			props["symbol_samples"] = cap25(syms)
+		}
 
 		depFacts = append(depFacts, facts.Fact{
 			Kind:  facts.KindDependency,

internal/linkers/crossrepo/crossrepo_test.go

@@ -374,3 +374,102 @@ func TestComputeLinks_PerRepoServiceNodes(t *testing.T) {
 		}
 	}
 }
+
+// --- (C) shared symbol surface ---
+
+func module(repo, name string) facts.Fact {
+	return facts.Fact{Kind: facts.KindModule, Name: name, Repo: repo}
+}
+
+func typeSym(repo, name, kind string) facts.Fact {
+	return facts.Fact{
+		Kind:  facts.KindSymbol,
+		Name:  name,
+		Repo:  repo,
+		Props: map[string]any{"symbol_kind": kind},
+	}
+}
+
+func TestComputeLinks_SharedSymbolsMatch(t *testing.T) {
+	// getdp and gmsh both declare the vendored onelab/GmshSocket types, under
+	// different directory prefixes (src/common vs Common). Enough distinctive
+	// shared types must link them, bidirectionally and via shared_symbols.
+	in := []facts.Fact{
+		module("getdp", "src/common"),
+		typeSym("getdp", "src/common.GmshClient", facts.SymbolClass),
+		typeSym("getdp", "src/common.GmshServer", facts.SymbolClass),
+		typeSym("getdp", "src/common.onelab::remoteNetworkClient", facts.SymbolClass),
+		module("gmsh", "Common"),
+		typeSym("gmsh", "Common.GmshClient", facts.SymbolClass),
+		typeSym("gmsh", "Common.GmshServer", facts.SymbolClass),
+		typeSym("gmsh", "Common.onelab::remoteNetworkClient", facts.SymbolClass),
+	}
+	out := ComputeLinks(in)
+
+	for _, pair := range [][2]string{{"getdp", "gmsh"}, {"gmsh", "getdp"}} {
+		e := findEdge(out, pair[0], pair[1])
+		if e == nil {
+			t.Fatalf("missing shared-symbol edge %s -> %s; out=%+v", pair[0], pair[1], out)
+		}
+		if via, _ := e.Props["via"].([]string); !reflect.DeepEqual(via, []string{"shared_symbols"}) {
+			t.Errorf("via = %v, want [shared_symbols]", e.Props["via"])
+		}
+		if c, _ := e.Props["symbol_count"].(int); c != 3 {
+			t.Errorf("symbol_count = %v, want 3", e.Props["symbol_count"])
+		}
+		if !hasServiceEdge(out, pair[0], pair[1]) {
+			t.Errorf("%s service node missing depends_on %s", pair[0], pair[1])
+		}
+	}
+}
+
+func TestComputeLinks_SharedSymbolsBelowThreshold(t *testing.T) {
+	// Only one distinctive shared type (below minSharedSymbols) → no link.
+	in := []facts.Fact{
+		module("alpha", "core"),
+		typeSym("alpha", "core.WidgetRegistry", facts.SymbolClass),
+		module("beta", "lib"),
+		typeSym("beta", "lib.WidgetRegistry", facts.SymbolClass),
+	}
+	if edges := crossRepoEdges(ComputeLinks(in)); len(edges) != 0 {
+		t.Errorf("single shared type should not link: %+v", edges)
+	}
+}
+
+func TestComputeLinks_SharedSymbolsGenericNamesIgnored(t *testing.T) {
+	// Common generic/short unqualified type names are not distinctive enough to
+	// link two otherwise-unrelated repos, even at count >= threshold.
+	in := []facts.Fact{
+		module("alpha", "core"),
+		typeSym("alpha", "core.Config", facts.SymbolClass),
+		typeSym("alpha", "core.Error", facts.SymbolStruct),
+		typeSym("alpha", "core.Node", facts.SymbolClass),
+		typeSym("alpha", "core.Item", facts.SymbolClass),
+		module("beta", "lib"),
+		typeSym("beta", "lib.Config", facts.SymbolClass),
+		typeSym("beta", "lib.Error", facts.SymbolStruct),
+		typeSym("beta", "lib.Node", facts.SymbolClass),
+		typeSym("beta", "lib.Item", facts.SymbolClass),
+	}
+	if edges := crossRepoEdges(ComputeLinks(in)); len(edges) != 0 {
+		t.Errorf("generic shared names should not link: %+v", edges)
+	}
+}
+
+func TestComputeLinks_SharedSymbolsNonTypesIgnored(t *testing.T) {
+	// Functions/methods/variables are not the contract surface; sharing them
+	// (even many) must not link repos.
+	in := []facts.Fact{
+		module("alpha", "core"),
+		typeSym("alpha", "core.processRequest", facts.SymbolFunc),
+		typeSym("alpha", "core.parseHeader", facts.SymbolFunc),
+		typeSym("alpha", "core.computeChecksum", facts.SymbolFunc),
+		module("beta", "lib"),
+		typeSym("beta", "lib.processRequest", facts.SymbolFunc),
+		typeSym("beta", "lib.parseHeader", facts.SymbolFunc),
+		typeSym("beta", "lib.computeChecksum", facts.SymbolFunc),
+	}
+	if edges := crossRepoEdges(ComputeLinks(in)); len(edges) != 0 {
+		t.Errorf("shared non-type symbols should not link: %+v", edges)
+	}
+}

internal/renderers/llmcontext/llm.go

@@ -224,6 +224,9 @@ func crossRepoDetail(e facts.Fact) string {
 	if n := propInt(e, "import_count"); n > 0 {
 		parts = append(parts, fmt.Sprintf("%d import(s): %s", n, samplePreview(propStrSlice(e, "import_samples"))))
 	}
+	if n := propInt(e, "symbol_count"); n > 0 {
+		parts = append(parts, fmt.Sprintf("%d shared symbol(s): %s", n, samplePreview(propStrSlice(e, "symbol_samples"))))
+	}
 	if len(parts) == 0 {
 		return "cross-repo dependency"
 	}