Add first-class Python gRPC support (servicer binding + client detection)

enola already produced gRPC server routes from .proto files (language-agnostic)
and detected the client side + bound server routes to handlers for Go and
TypeScript. Python had neither: a servicer was a plain class and a stub.Method()
call produced no route, so Python dropped out of cross-repo gRPC graphs, impact
analysis, and unused-route detection. This brings Python to parity.

Detection works from hand-written source + the .proto, not from generated
*_pb2_grpc.py stubs — real repos (vosk-server, airflow) build those at build time
and never commit them, so scanning generated stubs finds nothing.

Client side:
- New pythonextractor/grpcpy.go detects `stub = mod._pb2_grpc.FooStub(channel)`
  bindings and `stub.Method()` calls, emitting client-role routes. Binding is
  positional (interleaved by source offset), so a stub var rebound to a second
  service — the vosk pattern — resolves each call to the right service.
- Python source only knows the short service name, so routes are emitted with a
  provisional short Name; a new engine pass resolvePyGRPCClientRoutes rewrites
  them to the fully-qualified wire path (from the proto's server routes) BEFORE
  linkCrossRepo, which matches routes by Name. Remove-then-add keeps the store's
  name index consistent. Unresolved (no proto / ambiguous short name) routes are
  left provisional.

Server side:
- Generalize bindGRPCHandlers/implShortName to bind a proto server route to a
  Python servicer method via the `class X(mod._pb2_grpc.FooServicer)` convention
  (in addition to Go's Unimplemented<Service>Server embed), indexing Python
  classes alongside Go structs. The existing per-repo scoping and ambiguity guard
  are unchanged — two impls of one service in a repo (vosk grpc/ + grpc-wav2vec/)
  correctly stay unbound.

Also: classify python-grpc-client in crossrepo handWrittenClientSources; bump
cacheVersion v87 -> v88 (Python extractor now emits new facts); register cachecov
coverage for v88 and for v87 (the resolveCall fix, whose registration was missing).

Tests: unit tests for client detection (incl. positional rebinding + adversarial
GrpcHook/no-import negatives) and for servicer binding + FQ resolution; a golden
py_grpc_multirepo fixture (trimmed from real vosk-server) exercising the full
pipeline — proto server routes, handler binding, client FQ resolution, cross-repo
link, and an unmatched RPC. Verified live via MCP against real vosk-server and
against airflow (no regression).

Author: dejo1307

internal/cachecov/coverage_test.go

@@ -116,8 +116,10 @@ var versionCoverage = map[int][]string{
 	82: {"TestAST_RegistrationDecoratorsMarkUsed", "TestAST_AttributeArgValueRef", "TestAST_DictValueRef", "TestAST_ListOfLocalsNoFalseRef"},                                                                                                                                                      // Python registration decorators + attribute/collection value-refs
 	83: {"TestPyComplexity_ScalingLoopDepth_BoundedInnerDiscounted", "TestPyComplexity_ScalingLoopDepth_FullyBounded", "TestPyComplexity_ScalingLoopDepth_WhileTrueBounded", "TestPyComplexity_IODirect", "TestPyComputePerformsIO_Transitive", "TestExtract_ScalingLoopDepth_BoundedDiscounted"}, // scaling_loop_depth (Python/Go) + Python io_direct/performs_io
 	84: {"TestPyComplexity_CallsInScalingLoop_BoundedExcluded", "TestExtract_CallsInScalingLoop_BoundedExcluded", "TestTsComplexity_CallsInScalingLoop_BoundedExcluded"},                                                                                                                          // calls_in_scaling_loop (Python/Go/TS)
-	85: {"TestAST_DataClassAndEnumProps", "TestAST_InformalAbstractDetection"},                                                                                                                                                                                                                   // Python enum/data_class props + informal-abstract (raise NotImplementedError)
-	86: {"TestAST_DataClassAndEnumProps"},                                                                                                                                                                                                                                                        // Python data_class broadened to RootModel/*BaseModel subclasses (StrictBaseModel)
+	85: {"TestAST_DataClassAndEnumProps", "TestAST_InformalAbstractDetection"},                                                                                                                                                                                                                    // Python enum/data_class props + informal-abstract (raise NotImplementedError)
+	86: {"TestAST_DataClassAndEnumProps"},                                                                                                                                                                                                                                                         // Python data_class broadened to RootModel/*BaseModel subclasses (StrictBaseModel)
+	87: {"TestAST_ParamCall_NoEdge", "TestAST_LocalCallable_NoEdge", "TestAST_LoopVarCall_NoEdge", "TestAST_SameModuleCall_StillResolves"},                                                                                                                                                        // Python resolveCall no longer fabricates same-module edges for params/locals/loop vars
+	88: {"TestPyGRPC_ClientStubCall_EmitsRoute", "TestPyGRPC_StubRebinding_PositionalBinding", "TestPyGRPC_DynamicStubClass_NoRoute", "TestPyGRPC_NoStubImport_NoRoute"},                                                                                                                          // Python gRPC client-role routes from stub.Method() call sites
 }
 
 func TestCacheVersionCoverage(t *testing.T) {

internal/engine/cache.go

@@ -226,7 +226,10 @@ import (
 // parameters, locals, and loop variables — it now resolves a bare callee only when the name
 // is a known module-level def and not shadowed by a parameter (mirrors valueRefTarget). Drops
 // spurious call edges; bump so cached Python snapshots re-extract with the tightened resolver.
-const cacheVersion = "v87"
+// v88: Python extractor now emits gRPC client-role routes (source=python-grpc-client) for
+// stub.Method(...) call sites, detected from source. New facts, so cached Python snapshots must
+// re-extract to pick them up.
+const cacheVersion = "v88"
 
 // extractorCache holds per-extractor facts keyed by a content hash of the files
 // the extractor depends on. It is loaded from disk at the start of a snapshot and

internal/engine/engine.go

@@ -245,6 +245,7 @@ func (e *Engine) GenerateSnapshot(ctx context.Context, repoPath string, appendMo
 	// import/shared-lib references. Recomputed from scratch each run (prior
 	// synthetic facts are dropped first) so it stays idempotent across appends.
 	tStage = time.Now()
+	e.resolvePyGRPCClientRoutes()
 	e.linkCrossRepo()
 	e.flagUnmatchedRoutes()
 	e.bindGRPCHandlers()

internal/engine/golden_test.go

@@ -58,6 +58,7 @@ var fixtures = []fixture{
 	{name: "multirepo", subRepos: []string{"repoA", "repoB"}},
 	{name: "php_multirepo", subRepos: []string{"provider", "consumer"}},
 	{name: "go_grpc_multirepo", subRepos: []string{"server", "client"}},
+	{name: "py_grpc_multirepo", subRepos: []string{"server", "client"}},
 }
 
 func TestGolden(t *testing.T) {

internal/engine/grpcbind.go

@@ -14,6 +14,12 @@ import (
 // alias-qualified) — capturing the service short name ("UserService").
 var unimplementedEmbed = regexp.MustCompile(`^(?:.*\.)?Unimplemented(.+)Server$`)
 
+// servicerBase matches the target of the `implements` edge a Python gRPC servicer
+// carries by subclassing its generated base — e.g.
+// "stt_service_pb2_grpc.SttServiceServicer" — capturing the service short name
+// ("SttService"). grpc_python_out always names the base "<Service>Servicer".
+var servicerBase = regexp.MustCompile(`^(?:.*\.)?(.+)Servicer$`)
+
 // bindGRPCHandlers connects each gRPC server route (emitted from a .proto by the
 // grpc extractor) to the Go method that implements it, so route → handler is
 // traversable by impact_analysis and find_path.
@@ -41,7 +47,7 @@ func (e *Engine) bindGRPCHandlers() {
 	for _, s := range symbols {
 		kind, _ := s.Props["symbol_kind"].(string)
 		switch kind {
-		case facts.SymbolStruct:
+		case facts.SymbolStruct, facts.SymbolClass:
 			short := implShortName(s)
 			if short == "" {
 				continue
@@ -99,8 +105,96 @@ func (e *Engine) bindGRPCHandlers() {
 	}
 }
 
-// implShortName returns the gRPC service short name a struct implements by
-// embedding Unimplemented<Service>Server, or "" if it embeds no such type.
+// resolvePyGRPCClientRoutes rewrites provisional Python gRPC client routes to their
+// fully-qualified wire path. The Python extractor only sees the short service name
+// (e.g. "SttService"), so it emits Name = "/SttService/StreamingRecognize" plus a
+// grpc_service_short prop; the fully-qualified name ("vosk.stt.v1.SttService") lives
+// only in the .proto. This pass resolves short → fq from the gRPC server routes in
+// the store and rewrites the Name to "/vosk.stt.v1.SttService/StreamingRecognize"
+// so it matches the server route at cross-repo link time.
+//
+// It MUST run before linkCrossRepo (which matches routes by Name). It re-resolves
+// from the preserved grpc_service_short prop each run, so it is idempotent across
+// appends. A client route whose service has no proto in the snapshot (or an
+// ambiguous short name) is left provisional.
+func (e *Engine) resolvePyGRPCClientRoutes() {
+	// Proto index from server routes: short service name → fq, plus per-fq method
+	// sets and an ambiguity guard (two packages sharing a short service name).
+	fqOf := map[string]string{}
+	ambiguous := map[string]bool{}
+	methodsOf := map[string]map[string]bool{}
+	for _, r := range e.store.ByKind(facts.KindRoute) {
+		if valProp(r, "type") != "grpc" || valProp(r, "role") != "server" {
+			continue
+		}
+		fq := valProp(r, "rpc_service")
+		if fq == "" {
+			continue
+		}
+		short := lastDotSegment(fq)
+		if prev, ok := fqOf[short]; ok && prev != fq {
+			ambiguous[short] = true
+		} else {
+			fqOf[short] = fq
+		}
+		if methodsOf[fq] == nil {
+			methodsOf[fq] = map[string]bool{}
+		}
+		if m := valProp(r, "rpc_method"); m != "" {
+			methodsOf[fq][m] = true
+		}
+	}
+
+	// Collect + resolve client routes, then remove-and-re-add so the store's name
+	// index stays consistent (in-place Name mutation would desync byName).
+	var replaced []facts.Fact
+	found := false
+	for _, r := range e.store.ByKind(facts.KindRoute) {
+		if valProp(r, "source") != "python-grpc-client" {
+			continue
+		}
+		found = true
+		short := valProp(r, "grpc_service_short")
+		method := valProp(r, "rpc_method")
+		fq := fqOf[short]
+		if short != "" && method != "" && fq != "" && !ambiguous[short] && methodsOf[fq][method] {
+			r.Props = cloneProps(r.Props)
+			r.Name = "/" + fq + "/" + method
+			r.Props["rpc_service"] = fq
+		}
+		replaced = append(replaced, r)
+	}
+	if !found {
+		return
+	}
+	e.store.RemoveWhere(func(f facts.Fact) bool {
+		return f.Kind == facts.KindRoute && valProp(f, "source") == "python-grpc-client"
+	})
+	e.store.Add(replaced...)
+}
+
+// valProp reads a string prop from a value Fact, tolerating a nil Props map.
+func valProp(f facts.Fact, key string) string {
+	if f.Props == nil {
+		return ""
+	}
+	v, _ := f.Props[key].(string)
+	return v
+}
+
+// cloneProps returns a shallow copy of a props map so a rewritten fact does not
+// mutate the shared original.
+func cloneProps(p map[string]any) map[string]any {
+	out := make(map[string]any, len(p)+1)
+	for k, v := range p {
+		out[k] = v
+	}
+	return out
+}
+
+// implShortName returns the gRPC service short name a symbol implements — a Go
+// struct embedding Unimplemented<Service>Server, or a Python class subclassing a
+// generated <Service>Servicer base — or "" if it implements no such type.
 func implShortName(s facts.Fact) string {
 	for _, r := range s.Relations {
 		if r.Kind != facts.RelImplements {
@@ -109,6 +203,9 @@ func implShortName(s facts.Fact) string {
 		if m := unimplementedEmbed.FindStringSubmatch(r.Target); m != nil {
 			return m[1]
 		}
+		if m := servicerBase.FindStringSubmatch(r.Target); m != nil {
+			return m[1]
+		}
 	}
 	return ""
 }

internal/engine/grpcbind_test.go

@@ -65,6 +65,100 @@ func TestBindGRPCHandlers_BindsViaEmbedConvention(t *testing.T) {
 	}
 }
 
+// pyGRPCClientRoute builds a provisional (short-name) Python gRPC client route like
+// the Python extractor emits before the engine resolves it to the FQ wire path.
+func pyGRPCClientRoute(short, method string) facts.Fact {
+	return facts.Fact{
+		Kind: facts.KindRoute,
+		Name: "/" + short + "/" + method,
+		Props: map[string]any{
+			"role": "client", "method": "POST", "framework": "grpc",
+			"language": "python", "source": "python-grpc-client", "type": "grpc",
+			"rpc_method": method, "grpc_service_short": short,
+		},
+	}
+}
+
+// TestBindGRPCHandlers_BindsPythonServicer: a Python servicer class subclassing a
+// generated <Service>Servicer base binds the proto route to its handler method,
+// exactly as the Go embed convention does.
+func TestBindGRPCHandlers_BindsPythonServicer(t *testing.T) {
+	eng, _ := New(config.Default())
+	eng.Store().Add(
+		grpcServerRoute("vosk.stt.v1.SttService", "StreamingRecognize"),
+		facts.Fact{
+			Kind: facts.KindSymbol, Name: "grpc/stt_server.SttServiceServicer",
+			Props: map[string]any{"symbol_kind": facts.SymbolClass},
+			Relations: []facts.Relation{
+				{Kind: facts.RelImplements, Target: "stt_service_pb2_grpc.SttServiceServicer"},
+			},
+		},
+		facts.Fact{
+			Kind: facts.KindSymbol, Name: "grpc/stt_server.SttServiceServicer.StreamingRecognize",
+			Props: map[string]any{"symbol_kind": facts.SymbolMethod},
+		},
+	)
+
+	eng.bindGRPCHandlers()
+
+	routes, _ := eng.Store().QueryAdvanced(facts.QueryOpts{Kind: facts.KindRoute, Name: "/vosk.stt.v1.SttService/StreamingRecognize"})
+	if len(routes) != 1 {
+		t.Fatalf("route lookup = %d, want 1", len(routes))
+	}
+	target, ok := routeHandledBy(routes[0])
+	want := "grpc/stt_server.SttServiceServicer.StreamingRecognize"
+	if !ok || target != want {
+		t.Errorf("handled_by = %q (ok=%v), want %q", target, ok, want)
+	}
+	if routes[0].Props["handler"] != want {
+		t.Errorf("handler prop = %v, want %q", routes[0].Props["handler"], want)
+	}
+}
+
+// TestResolvePyGRPCClientRoutes_RewritesToFQ: a provisional short client route is
+// rewritten to the fully-qualified wire path (matching the proto server route) and
+// the short route no longer exists.
+func TestResolvePyGRPCClientRoutes_RewritesToFQ(t *testing.T) {
+	eng, _ := New(config.Default())
+	eng.Store().Add(
+		grpcServerRoute("vosk.stt.v1.SttService", "StreamingRecognize"),
+		pyGRPCClientRoute("SttService", "StreamingRecognize"),
+	)
+
+	eng.resolvePyGRPCClientRoutes()
+
+	if got, _ := eng.Store().QueryAdvanced(facts.QueryOpts{Kind: facts.KindRoute, Name: "/SttService/StreamingRecognize"}); len(got) != 0 {
+		t.Errorf("short client route still present: %d", len(got))
+	}
+	routes, _ := eng.Store().QueryAdvanced(facts.QueryOpts{Kind: facts.KindRoute, Name: "/vosk.stt.v1.SttService/StreamingRecognize"})
+	foundClient := false
+	for _, r := range routes {
+		if r.Props["source"] == "python-grpc-client" {
+			foundClient = true
+			if r.Props["rpc_service"] != "vosk.stt.v1.SttService" {
+				t.Errorf("rpc_service = %v, want vosk.stt.v1.SttService", r.Props["rpc_service"])
+			}
+		}
+	}
+	if !foundClient {
+		t.Error("client route was not rewritten to the fully-qualified name")
+	}
+}
+
+// TestResolvePyGRPCClientRoutes_UnresolvedLeftShort: with no proto in the snapshot,
+// the client route stays provisional (short) rather than being dropped or corrupted.
+func TestResolvePyGRPCClientRoutes_UnresolvedLeftShort(t *testing.T) {
+	eng, _ := New(config.Default())
+	eng.Store().Add(pyGRPCClientRoute("SttService", "StreamingRecognize"))
+
+	eng.resolvePyGRPCClientRoutes()
+
+	routes, _ := eng.Store().QueryAdvanced(facts.QueryOpts{Kind: facts.KindRoute, Name: "/SttService/StreamingRecognize"})
+	if len(routes) != 1 {
+		t.Errorf("unresolved client route should be left short, got %d routes", len(routes))
+	}
+}
+
 func TestBindGRPCHandlers_NoEmbedNoBind(t *testing.T) {
 	eng, _ := New(config.Default())
 	eng.Store().Add(