fix: resolve module-level classmethod aliases in stdlib type inference (shivasurya#616)

Python stdlib modules like tarfile expose classmethods at module level
(tarfile.open is actually TarFile.open). The type inference engine's
Phase A resolver only checked GetFunction and GetClass, missing these
aliases entirely. Variables assigned from such calls stayed unresolved
as "call:tarfile.open", breaking downstream type-aware rule matching.

Add FindClassMethodAlias to StdlibRegistryRemote that searches all
classes in a module for a matching method name. Uses GetClassMethod
internally to also check inherited methods. Prefers the class whose
name matches the module (e.g., TarFile in tarfile) for determinism.

Resolves "Self" return types (e.g., tarfile.Self → tarfile.TarFile)
so Phase B can chain method calls on the resolved type.

Before: 1 detection (only tarfile.TarFile constructor path)
After:  4 detections (module alias + constructor + extract + safe_extract)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: shivasurya

sast-engine/graph/callgraph/builder/builder.go

@@ -1934,6 +1934,25 @@ func resolveStdlibVariableBindings(typeEngine *resolution.TypeInferenceEngine, l
 						scope.Variables[varName][i].AssignedFrom = funcName
 						continue
 					}
+
+					// Try as module-level alias to a classmethod.
+					// Handles patterns like tarfile.open which is TarFile.open.
+					if method, className := loader.FindClassMethodAlias(moduleName, name, logger); method != nil {
+						returnType := method.ReturnType
+						if returnType != "" && returnType != "unknown" {
+							// Resolve "Self" return types to the owning class
+							if returnType == "Self" || returnType == moduleName+".Self" {
+								returnType = moduleName + "." + className
+							}
+							scope.Variables[varName][i].Type = &core.TypeInfo{
+								TypeFQN:    returnType,
+								Confidence: binding.Type.Confidence * method.Confidence * 0.95,
+								Source:     "stdlib",
+							}
+							scope.Variables[varName][i].AssignedFrom = funcName
+							continue
+						}
+					}
 				}
 
 			}

sast-engine/graph/callgraph/builder/stdlib_resolve_test.go

@@ -309,3 +309,115 @@ func TestResolveStdlibVariableBindings_NoKnownModule(t *testing.T) {
 	assert.NotNil(t, binding)
 	assert.Equal(t, "call:unknownmod.func1", binding.Type.TypeFQN) // unchanged
 }
+
+func TestResolveStdlibVariableBindings_PhaseA_ClassMethodAlias(t *testing.T) {
+	// tarfile.open is a module-level alias for TarFile.open (classmethod).
+	// GetFunction("tarfile", "open") returns nil because it's not in Functions.
+	// GetClass("tarfile", "open") returns nil because "open" is not a class.
+	// FindClassMethodAlias should find TarFile.open and resolve its return type.
+	loader := newTestStdlibLoader(map[string]*core.StdlibModule{
+		"tarfile": {
+			Module:    "tarfile",
+			Functions: map[string]*core.StdlibFunction{},
+			Classes: map[string]*core.StdlibClass{
+				"TarFile": {
+					Type: "class",
+					Methods: map[string]*core.StdlibFunction{
+						"open": {
+							ReturnType: "tarfile.Self",
+							Confidence: 0.95,
+						},
+						"extractall": {
+							ReturnType: "builtins.NoneType",
+							Confidence: 0.95,
+						},
+					},
+				},
+			},
+		},
+	})
+
+	typeEngine := resolution.NewTypeInferenceEngine(nil)
+	typeEngine.StdlibRemote = loader
+
+	scope := resolution.NewFunctionScope("app.extract_archive")
+	typeEngine.Scopes["app.extract_archive"] = scope
+	scope.AddVariable(&resolution.VariableBinding{
+		VarName: "tar",
+		Type: &core.TypeInfo{
+			TypeFQN:    "call:tarfile.open",
+			Confidence: 0.5,
+		},
+	})
+
+	logger := output.NewLogger(output.VerbosityDefault)
+	resolveStdlibVariableBindings(typeEngine, logger)
+
+	binding := scope.GetVariable("tar")
+	assert.NotNil(t, binding)
+	// "tarfile.Self" should be resolved to "tarfile.TarFile"
+	assert.Equal(t, "tarfile.TarFile", binding.Type.TypeFQN)
+	assert.Equal(t, "tarfile.open", binding.AssignedFrom)
+	assert.Equal(t, "stdlib", binding.Type.Source)
+}
+
+func TestResolveStdlibVariableBindings_PhaseA_ClassMethodAlias_ChainToPhaseB(t *testing.T) {
+	// Full chain: tarfile.open() → TarFile, then tar.extractall() via Phase B.
+	loader := newTestStdlibLoader(map[string]*core.StdlibModule{
+		"tarfile": {
+			Module:    "tarfile",
+			Functions: map[string]*core.StdlibFunction{},
+			Classes: map[string]*core.StdlibClass{
+				"TarFile": {
+					Type: "class",
+					Methods: map[string]*core.StdlibFunction{
+						"open": {
+							ReturnType: "tarfile.Self",
+							Confidence: 0.95,
+						},
+						"extractall": {
+							ReturnType: "builtins.NoneType",
+							Confidence: 0.95,
+						},
+					},
+				},
+			},
+		},
+	})
+
+	typeEngine := resolution.NewTypeInferenceEngine(nil)
+	typeEngine.StdlibRemote = loader
+
+	scope := resolution.NewFunctionScope("app.extract_archive")
+	typeEngine.Scopes["app.extract_archive"] = scope
+
+	// tar = tarfile.open(...)
+	scope.AddVariable(&resolution.VariableBinding{
+		VarName: "tar",
+		Type: &core.TypeInfo{
+			TypeFQN:    "call:tarfile.open",
+			Confidence: 0.5,
+		},
+	})
+	// result = tar.extractall(...)
+	scope.AddVariable(&resolution.VariableBinding{
+		VarName: "result",
+		Type: &core.TypeInfo{
+			TypeFQN:    "call:tar.extractall",
+			Confidence: 0.5,
+		},
+	})
+
+	logger := output.NewLogger(output.VerbosityDefault)
+	resolveStdlibVariableBindings(typeEngine, logger)
+
+	// Phase A: tar → tarfile.TarFile
+	tarBinding := scope.GetVariable("tar")
+	assert.Equal(t, "tarfile.TarFile", tarBinding.Type.TypeFQN)
+
+	// Phase B: result → builtins.NoneType (via TarFile.extractall)
+	resultBinding := scope.GetVariable("result")
+	assert.NotNil(t, resultBinding)
+	assert.Equal(t, "builtins.NoneType", resultBinding.Type.TypeFQN)
+	assert.Equal(t, "tarfile.TarFile.extractall", resultBinding.AssignedFrom)
+}

sast-engine/graph/callgraph/registry/stdlib_remote.go

@@ -295,6 +295,42 @@ func (r *StdlibRegistryRemote) GetClassMethod(moduleName, className, methodName
 	return nil
 }
 
+// FindClassMethodAlias searches all classes in a module for a method matching
+// the given name. This handles module-level aliases like tarfile.open which is
+// actually TarFile.open (a classmethod exposed at module level).
+//
+// When multiple classes have a method with the same name, the class whose name
+// matches the module (e.g., TarFile in tarfile) is preferred for determinism.
+// Also checks inherited methods via GetClassMethod.
+//
+// Returns the matching StdlibFunction and the owning class name, or nil/"" if
+// no match is found.
+func (r *StdlibRegistryRemote) FindClassMethodAlias(moduleName, functionName string, logger *output.Logger) (*core.StdlibFunction, string) {
+	module, err := r.GetModule(moduleName, logger)
+	if err != nil || module == nil {
+		return nil, ""
+	}
+
+	var bestMethod *core.StdlibFunction
+	var bestClassName string
+
+	for className := range module.Classes {
+		method := r.GetClassMethod(moduleName, className, functionName, logger)
+		if method == nil {
+			continue
+		}
+		if bestMethod == nil {
+			bestMethod = method
+			bestClassName = className
+		} else if strings.EqualFold(className, moduleName) {
+			// Prefer the class matching the module name (e.g., TarFile in tarfile)
+			bestMethod = method
+			bestClassName = className
+		}
+	}
+	return bestMethod, bestClassName
+}
+
 // ModuleCount returns the number of modules in the manifest.
 //
 // Returns:

sast-engine/graph/callgraph/registry/stdlib_remote_test.go

@@ -857,3 +857,127 @@ func TestStdlibRegistryRemote_GetModule_HTTPError(t *testing.T) {
 	assert.Contains(t, err.Error(), "module download failed with status: 404")
 	assert.Nil(t, module)
 }
+
+func TestStdlibRegistryRemote_FindClassMethodAlias(t *testing.T) {
+	// tarfile.open is a module-level alias for TarFile.open (classmethod)
+	remote := &StdlibRegistryRemote{
+		ModuleCache: map[string]*core.StdlibModule{
+			"tarfile": {
+				Module:    "tarfile",
+				Functions: map[string]*core.StdlibFunction{},
+				Classes: map[string]*core.StdlibClass{
+					"TarFile": {
+						Type: "class",
+						Methods: map[string]*core.StdlibFunction{
+							"open":       {ReturnType: "tarfile.Self", Confidence: 0.95},
+							"extractall": {ReturnType: "builtins.NoneType", Confidence: 0.95},
+						},
+					},
+					"TarInfo": {
+						Type: "class",
+						Methods: map[string]*core.StdlibFunction{
+							"isdir": {ReturnType: "builtins.bool", Confidence: 0.9},
+						},
+					},
+				},
+			},
+		},
+	}
+	logger := newTestLogger()
+
+	// Found: tarfile.open → TarFile.open
+	method, className := remote.FindClassMethodAlias("tarfile", "open", logger)
+	require.NotNil(t, method, "should find TarFile.open as alias for tarfile.open")
+	assert.Equal(t, "TarFile", className)
+	assert.Equal(t, "tarfile.Self", method.ReturnType)
+	assert.InDelta(t, 0.95, method.Confidence, 0.001)
+
+	// Found: tarfile.extractall → TarFile.extractall
+	method2, className2 := remote.FindClassMethodAlias("tarfile", "extractall", logger)
+	require.NotNil(t, method2)
+	assert.Equal(t, "TarFile", className2)
+	assert.Equal(t, "builtins.NoneType", method2.ReturnType)
+
+	// Found: tarfile.isdir → TarInfo.isdir
+	method3, className3 := remote.FindClassMethodAlias("tarfile", "isdir", logger)
+	require.NotNil(t, method3)
+	assert.Equal(t, "TarInfo", className3)
+
+	// Not found: no class has "nonexistent"
+	method4, className4 := remote.FindClassMethodAlias("tarfile", "nonexistent", logger)
+	assert.Nil(t, method4)
+	assert.Equal(t, "", className4)
+
+	// Not found: module not in cache
+	method5, className5 := remote.FindClassMethodAlias("unknown", "open", logger)
+	assert.Nil(t, method5)
+	assert.Equal(t, "", className5)
+}
+
+func TestStdlibRegistryRemote_FindClassMethodAlias_PrefersModuleNameClass(t *testing.T) {
+	// When multiple classes have the same method name, prefer the class
+	// whose name matches the module (case-insensitive).
+	// Use many non-matching classes to increase chance the preferred one
+	// is not the first iterated (Go map order is random).
+	classes := map[string]*core.StdlibClass{
+		"MyMod": {
+			Type: "class",
+			Methods: map[string]*core.StdlibFunction{
+				"connect": {ReturnType: "mymod.MyMod", Confidence: 0.95},
+			},
+		},
+	}
+	// Add many non-matching classes with the same method to force iteration
+	for _, name := range []string{"Alpha", "Beta", "Gamma", "Delta", "Epsilon", "Zeta", "Eta", "Theta"} {
+		classes[name] = &core.StdlibClass{
+			Type: "class",
+			Methods: map[string]*core.StdlibFunction{
+				"connect": {ReturnType: "mymod." + name, Confidence: 0.8},
+			},
+		}
+	}
+
+	remote := &StdlibRegistryRemote{
+		ModuleCache: map[string]*core.StdlibModule{
+			"mymod": {
+				Module:    "mymod",
+				Functions: map[string]*core.StdlibFunction{},
+				Classes:   classes,
+			},
+		},
+	}
+
+	// Run multiple times to exercise different map iteration orders
+	for i := 0; i < 20; i++ {
+		method, className := remote.FindClassMethodAlias("mymod", "connect", newTestLogger())
+		require.NotNil(t, method, "iteration %d: should find connect", i)
+		assert.Equal(t, "MyMod", className, "iteration %d: should always prefer class matching module name", i)
+		assert.Equal(t, "mymod.MyMod", method.ReturnType, "iteration %d", i)
+	}
+}
+
+func TestStdlibRegistryRemote_FindClassMethodAlias_Inherited(t *testing.T) {
+	// FindClassMethodAlias uses GetClassMethod which checks inherited methods too.
+	remote := &StdlibRegistryRemote{
+		ModuleCache: map[string]*core.StdlibModule{
+			"mymod": {
+				Module:    "mymod",
+				Functions: map[string]*core.StdlibFunction{},
+				Classes: map[string]*core.StdlibClass{
+					"Base": {
+						Type:    "class",
+						Methods: map[string]*core.StdlibFunction{},
+						InheritedMethods: map[string]*core.InheritedMember{
+							"read": {ReturnType: "builtins.bytes", Confidence: 0.85, Source: "io.IOBase"},
+						},
+					},
+				},
+			},
+		},
+	}
+
+	method, className := remote.FindClassMethodAlias("mymod", "read", newTestLogger())
+	require.NotNil(t, method, "should find inherited method via GetClassMethod")
+	assert.Equal(t, "Base", className)
+	assert.Equal(t, "builtins.bytes", method.ReturnType)
+}