feat(injector/join): Introduce finalResultImplements for final return value interface matching

This update adds the `finalResultImplements` FunctionOption, enabling the matching of functions where the final return value implements a specified interface. The implementation includes methods for determining package and file match types, as well as evaluating the final return value against the target interface.

Additionally, the configuration YAML has been updated with test cases demonstrating the new functionality, including scenarios that illustrate the distinction between `result-implements` and `final-result-implements`.

Signed-off-by: Kemal Akkoyun <kemal.akkoyun@datadoghq.com>

Author: kakkoyun

internal/injector/aspect/join/function.go

@@ -428,6 +428,66 @@ func (fo *resultImplements) Hash(h *fingerprint.Hasher) error {
 	return h.Named("result-implements", fingerprint.String(fo.InterfaceName))
 }
 
+// finalResultImplements matches functions where specifically the final return value
+// implements the specified interface.
+type finalResultImplements struct {
+	InterfaceName string
+}
+
+// FinalResultImplements creates a FunctionOption that matches functions where the final
+// return value implements the named interface.
+func FinalResultImplements(interfaceName string) FunctionOption {
+	return &finalResultImplements{InterfaceName: interfaceName}
+}
+
+func (fo *finalResultImplements) impliesImported() []string {
+	pkgPath, _ := typed.SplitPackageAndName(fo.InterfaceName)
+	if pkgPath != "" {
+		return []string{pkgPath}
+	}
+	return nil
+}
+
+func (_ *finalResultImplements) packageMayMatch(_ *may.PackageContext) may.MatchType {
+	// Cannot reliably determine possibility of match based on package imports
+	// due to structural typing. A type can implement an interface without
+	// importing the interface's package.
+	return may.Unknown
+}
+
+func (_ *finalResultImplements) fileMayMatch(_ *may.FileContext) may.MatchType {
+	// Cannot reliably determine possibility of match based on file contents
+	// due to structural typing and type aliases.
+	return may.Unknown
+}
+
+func (fo *finalResultImplements) evaluate(info functionInformation) bool {
+	if info.Type.Results == nil || len(info.Type.Results.List) == 0 {
+		// No return values, no match.
+		return false
+	}
+
+	// Ensure the type resolver is available.
+	if info.typeResolver == nil {
+		return false
+	}
+
+	// Resolve the target interface name (e.g., "io.Reader", "error") to a types.Interface.
+	targetInterface, err := typed.ResolveInterfaceTypeByName(fo.InterfaceName)
+	if err != nil {
+		// If the interface name is invalid or cannot be resolved, we cannot match.
+		return false
+	}
+
+	// Check if the last field implements the interface.
+	lastField := info.Type.Results.List[len(info.Type.Results.List)-1]
+	return typed.ExprImplements(info.typeResolver, lastField.Type, targetInterface)
+}
+
+func (fo *finalResultImplements) Hash(h *fingerprint.Hasher) error {
+	return h.Named("final-result-implements", fingerprint.String(fo.InterfaceName))
+}
+
 func init() {
 	unmarshalers["function-body"] = func(ctx gocontext.Context, node ast.Node) (Point, error) {
 		up, err := FromYAML(ctx, node)
@@ -543,6 +603,16 @@ func (o *unmarshalFuncDeclOption) UnmarshalYAML(ctx gocontext.Context, node ast.
 		}
 		// NOTE: Validation happens later during type resolution.
 		o.FunctionOption = ResultImplements(ifaceName)
+	case "final-result-implements":
+		var ifaceName string
+		if err := yaml.NodeToValueContext(ctx, mapping.Values[0].Value, &ifaceName); err != nil {
+			return err
+		}
+		if ifaceName == "" {
+			return fmt.Errorf("line %d: 'final-result-implements' cannot be empty", node.GetToken().Position.Line)
+		}
+		// NOTE: Validation happens later during type resolution.
+		o.FunctionOption = FinalResultImplements(ifaceName)
 	default:
 		return fmt.Errorf("unknown FuncDeclOption name: %q", key)
 	}

internal/injector/testdata/injector/result-implements-join/config.yml

@@ -32,6 +32,67 @@ aspects:
           template: |
             fmt.Println("Success: instrumented returnsError implementer")
 
+  # Aspect 3: Target functions where the final return value implements io.Reader
+  - id: "instrument-final-reader-returns"
+    join-point:
+      function-body:
+        function:
+          - final-result-implements: "io.Reader" # ...of functions where the final return value implements io.Reader
+    advice:
+      - prepend-statements:
+          imports:
+            fmt: fmt
+          template: |
+            fmt.Println("Success: instrumented final returnsReader implementer")
+
+  # Aspect 4: Target functions where the final return value implements error
+  - id: "instrument-final-error-returns"
+    join-point:
+      function-body:
+        function:
+          - final-result-implements: "error" # ...of functions where the final return value implements error
+    advice:
+      - prepend-statements:
+          imports:
+            fmt: fmt
+          template: |
+            fmt.Println("Success: instrumented final returnsError implementer")
+
+  # Aspect 5: Demonstrate difference between result-implements and final-result-implements
+  - id: "demonstrate-difference"
+    join-point:
+      function-body:
+        function:
+          - name: returnsErrorThenString # Target specific function for clarity
+    advice:
+      - prepend-statements:
+          imports:
+            fmt: fmt
+          template: |
+            fmt.Println("Demonstrating difference between result-implements and final-result-implements:")
+            {{ $resultMatches := false }}
+            {{ $finalMatches := false }}
+
+            {{ with .Function.ResultThatImplements "error" }}
+              {{ $resultMatches = true }}
+            {{ end }}
+
+            {{ if .Function.FinalResultImplements "error" }}
+              {{ $finalMatches = true }}
+            {{ end }}
+
+            {{ if $resultMatches }}
+            fmt.Println("Success: result-implements finds error in non-final position")
+            {{ else }}
+            fmt.Println("Failure: result-implements didn't find error in function")
+            {{ end }}
+
+            {{ if not $finalMatches }}
+            fmt.Println("Success: final-result-implements correctly ignores non-final error")
+            {{ else }}
+            fmt.Println("Failure: final-result-implements incorrectly matched non-final error")
+            {{ end }}
+
 
 code: |-
   package main
@@ -145,5 +206,12 @@ code: |-
     return "neither implements", 5
   }
 
+  // This function has an error but it's not the final return value
+  // Should match ResultImplements("error") but not FinalResultImplements("error")
+  func returnsErrorThenString() (error, string) {
+    fmt.Println("Executing returnsErrorThenString")
+    return errors.New("error in non-final position"), "final non-error value"
+  }
+
   // Main - needed for compilation by the test harness.
   func main() {}

internal/injector/testdata/injector/result-implements-join/modified.go.snap

@@ -18,6 +18,10 @@ type myCustomReaderImpl struct {
 
 func (cr myCustomReaderImpl) Read(p []byte) (int, error) {
 //line <generated>:1
+  {
+    fmt.Println("Success: instrumented final returnsError implementer")
+
+  }
   {
     fmt.Println("Success: instrumented returnsError implementer")
 
@@ -40,6 +44,10 @@ func (e myCustomError) Error() string {
 
 func returnsReader() io.Reader {
 //line <generated>:1
+  {
+    fmt.Println("Success: instrumented final returnsReader implementer")
+
+  }
   {
     fmt.Println("Success: instrumented returnsReader implementer")
 
@@ -51,6 +59,10 @@ func returnsReader() io.Reader {
 
 func returnsBuffer() *bytes.Buffer {
 //line <generated>:1
+  {
+    fmt.Println("Success: instrumented final returnsReader implementer")
+
+  }
   {
     fmt.Println("Success: instrumented returnsReader implementer")
 
@@ -62,6 +74,10 @@ func returnsBuffer() *bytes.Buffer {
 
 func returnsError() error {
 //line <generated>:1
+  {
+    fmt.Println("Success: instrumented final returnsError implementer")
+
+  }
   {
     fmt.Println("Success: instrumented returnsError implementer")
 
@@ -73,6 +89,10 @@ func returnsError() error {
 
 func returnsHttpError() error {
 //line <generated>:1
+  {
+    fmt.Println("Success: instrumented final returnsError implementer")
+
+  }
   {
     fmt.Println("Success: instrumented returnsError implementer")
 
@@ -85,6 +105,10 @@ func returnsHttpError() error {
 
 func returnsCustomReaderImpl() myCustomReaderImpl {
 //line <generated>:1
+  {
+    fmt.Println("Success: instrumented final returnsReader implementer")
+
+  }
   {
     fmt.Println("Success: instrumented returnsReader implementer")
 
@@ -96,6 +120,10 @@ func returnsCustomReaderImpl() myCustomReaderImpl {
 
 func returnsCustomError() myCustomError {
 //line <generated>:1
+  {
+    fmt.Println("Success: instrumented final returnsError implementer")
+
+  }
   {
     fmt.Println("Success: instrumented returnsError implementer")
 
@@ -120,6 +148,10 @@ func noReturn() {
 
 func returnsIntAndReader() (int, io.Reader) {
 //line <generated>:1
+  {
+    fmt.Println("Success: instrumented final returnsReader implementer")
+
+  }
   {
     fmt.Println("Success: instrumented returnsReader implementer")
 
@@ -142,6 +174,10 @@ func returnsReaderAndInt() (io.Reader, int) {
 
 func returnsIntAndError() (int, error) {
 //line <generated>:1
+  {
+    fmt.Println("Success: instrumented final returnsError implementer")
+
+  }
   {
     fmt.Println("Success: instrumented returnsError implementer")
 
@@ -164,6 +200,10 @@ func returnsErrorAndInt() (error, int) {
 
 func returnsMultipleReaders() (*bytes.Buffer, io.Reader) {
 //line <generated>:1
+  {
+    fmt.Println("Success: instrumented final returnsReader implementer")
+
+  }
   {
     fmt.Println("Success: instrumented returnsReader implementer")
 
@@ -175,6 +215,10 @@ func returnsMultipleReaders() (*bytes.Buffer, io.Reader) {
 
 func returnsMultipleErrors() (error, error) {
 //line <generated>:1
+  {
+    fmt.Println("Success: instrumented final returnsError implementer")
+
+  }
   {
     fmt.Println("Success: instrumented returnsError implementer")
 
@@ -189,5 +233,25 @@ func returnsStringAndInt() (string, int) {
   return "neither implements", 5
 }
 
+// This function has an error but it's not the final return value
+// Should match ResultImplements("error") but not FinalResultImplements("error")
+func returnsErrorThenString() (__result__0 error, _ string) {
+//line <generated>:1
+  {
+    fmt.Println("Demonstrating difference between result-implements and final-result-implements:")
+
+    fmt.Println("Success: result-implements finds error in non-final position")
+
+    fmt.Println("Success: final-result-implements correctly ignores non-final error")
+  }
+  {
+    fmt.Println("Success: instrumented returnsError implementer")
+
+  }
+//line input.go:115
+  fmt.Println("Executing returnsErrorThenString")
+  return errors.New("error in non-final position"), "final non-error value"
+}
+
 // Main - needed for compilation by the test harness.
 func main() {}