feat: silence unused_value on fluent-builder method returns (#218)

Author: ivov

bindgen/bindgen.stdlib.json

@@ -5,6 +5,10 @@
         "bytes": ["Buffer.WriteByte", "Buffer.WriteRune", "Buffer.WriteString"],
         "fmt": ["Print", "Printf", "Println", "Fprint", "Fprintf", "Fprintln"],
         "strings": ["Builder.WriteByte", "Builder.WriteRune", "Builder.WriteString"]
+      },
+      "deny_unused_value": {
+        "go/types": ["TypeParam.Underlying"],
+        "html/template": ["Template.New"]
       }
     },
     "types": {

bindgen/internal/config/config.go

@@ -21,6 +21,7 @@ type Overrides struct {
 // LintOverrides holds lint-suppression overrides.
 type LintOverrides struct {
 	AllowUnusedResult map[string][]string `json:"allow_unused_result"`
+	DenyUnusedValue   map[string][]string `json:"deny_unused_value"`
 }
 
 // TypeOverrides holds type-conversion overrides.
@@ -77,6 +78,18 @@ func (c *Config) ShouldAllowUnusedResult(pkg, funcName string) bool {
 	return matchesWildcard(funcs, funcName)
 }
 
+// ShouldDenyUnusedValue forces the AST fluent-method heuristic off for curated methods that match its shape but semantically return new values.
+func (c *Config) ShouldDenyUnusedValue(pkg, name string) bool {
+	if c == nil {
+		return false
+	}
+	names, ok := lookupWithGlob(c.Overrides.Lints.DenyUnusedValue, pkg)
+	if !ok {
+		return false
+	}
+	return matchesWildcard(names, name)
+}
+
 // ShouldWrapNilableReturn returns true if the given function or method in the given
 // package should be wrapped in Option<> because it can return nil.
 // Uses "Type.Method" dot notation for methods.

bindgen/internal/convert/converters.go

@@ -296,6 +296,118 @@ func (c *Converter) convertMethod(result *ConvertResult, symbolExport extract.Sy
 		return
 	}
 	result.TypeParams = methodSpecs
+
+	if isFluentBuilderCandidate(result, symbolExport, signature) {
+		if fn := c.findFuncDecl(symbolExport.Obj); fn != nil && isFluentMethod(fn, ncGetReceiverName(fn)) {
+			if c.cfg == nil || !c.cfg.ShouldDenyUnusedValue(c.currentPkgPath, qualifiedName) {
+				result.BuilderMethod = true
+			}
+		}
+	}
+}
+
+// isFluentBuilderCandidate gates AST inspection. Clone/Copy return new values despite the fluent shape.
+func isFluentBuilderCandidate(result *ConvertResult, exp extract.SymbolExport, sig *types.Signature) bool {
+	if result.Receiver == nil || !result.Receiver.IsPointer || exp.IsPromoted {
+		return false
+	}
+	if result.Name == "Clone" || result.Name == "Copy" {
+		return false
+	}
+	return returnIsReceiverShaped(sig)
+}
+
+// leftmostIdent walks `recv.A(...).B(...)` chains so the receiver can be detected at the head.
+func leftmostIdent(expr ast.Expr) *ast.Ident {
+	switch e := expr.(type) {
+	case *ast.Ident:
+		return e
+	case *ast.SelectorExpr:
+		return leftmostIdent(e.X)
+	case *ast.CallExpr:
+		return leftmostIdent(e.Fun)
+	}
+	return nil
+}
+
+// returnIsReceiverShaped filters out delegation that returns unrelated types (e.g. `*Alpha.At -> color.Color`) and Result/Option-wrapped returns where unused_value cannot fire.
+func returnIsReceiverShaped(sig *types.Signature) bool {
+	recv := sig.Recv()
+	if recv == nil {
+		return false
+	}
+	results := sig.Results()
+	if results.Len() != 1 {
+		return false
+	}
+	recvPtr, ok := recv.Type().(*types.Pointer)
+	if !ok {
+		return false
+	}
+	recvNamed, ok := recvPtr.Elem().(*types.Named)
+	if !ok {
+		return false
+	}
+
+	if retNamed := singlePointerReturnNamed(sig); retNamed != nil && retNamed == recvNamed {
+		return true
+	}
+	retNamed, ok := results.At(0).Type().(*types.Named)
+	if !ok {
+		return false
+	}
+	if retNamed == recvNamed {
+		return true
+	}
+	if iface, ok := retNamed.Underlying().(*types.Interface); ok && !iface.Empty() {
+		return types.Implements(recvPtr, iface)
+	}
+	return false
+}
+
+// isFluentMethod excludes trivial `return self` getters — real fluent setters either do work before returning or delegate via a method call on the receiver.
+func isFluentMethod(fn *ast.FuncDecl, recvName string) bool {
+	if fn == nil || fn.Body == nil || recvName == "" {
+		return false
+	}
+
+	hasReturn := false
+	allMatchRecv := true
+	anyCallOnRecv := false
+	ast.Inspect(fn.Body, func(n ast.Node) bool {
+		if _, ok := n.(*ast.FuncLit); ok {
+			return false
+		}
+		ret, ok := n.(*ast.ReturnStmt)
+		if !ok {
+			return true
+		}
+		if len(ret.Results) != 1 {
+			allMatchRecv = false
+			return true
+		}
+		hasReturn = true
+		switch r := ret.Results[0].(type) {
+		case *ast.Ident:
+			if r.Name != recvName {
+				allMatchRecv = false
+			}
+		case *ast.CallExpr:
+			if id := leftmostIdent(r); id != nil && id.Name == recvName {
+				anyCallOnRecv = true
+				return true
+			}
+			allMatchRecv = false
+		default:
+			allMatchRecv = false
+		}
+		return true
+	})
+
+	if !hasReturn || !allMatchRecv {
+		return false
+	}
+	return len(fn.Body.List) > 1 || anyCallOnRecv
 }
 
 func (c *Converter) convertType(result *ConvertResult, exp extract.SymbolExport) {

bindgen/internal/convert/dispatch.go

@@ -32,6 +32,8 @@ type ConvertResult struct {
 	// rewrites the return type to Option<int> and emits the matching
 	// flag-name annotation (e.g. `#[go(sentinel_minus_one)]`).
 	SentinelInt *int
+	// BuilderMethod suppresses unused_value on fluent-chain returns the caller typically discards.
+	BuilderMethod bool
 }
 
 type FunctionParameter struct {

bindgen/internal/emit/emitter.go

@@ -346,6 +346,9 @@ func (e *Emitter) emitMethodInImpl(result convert.ConvertResult) {
 			e.buf.WriteString("  #[allow(unused_result)]\n")
 		}
 	}
+	if result.BuilderMethod {
+		e.buf.WriteString("  #[allow(unused_value)]\n")
+	}
 
 	var methodSignature strings.Builder
 	methodSignature.WriteString("  fn ")

bindgen/tests/testdata/fixtures/builder_methods/builder_methods.go

@@ -0,0 +1,88 @@
+// Fixtures for the builder-method heuristic that emits #[allow(unused_value)]
+// when a pointer-receiver method's body returns the receiver itself or
+// delegates via a method call on the receiver.
+package builder_methods
+
+// Self-return on pointer receiver: classic fluent setter shape.
+type Config struct {
+	name string
+	tags []string
+}
+
+func (c *Config) WithName(n string) *Config { c.name = n; return c }
+func (c *Config) WithTag(k, v string)       {} // no return: not a builder
+func (c *Config) Name() string              { return c.name }
+
+// Interface self-return on a real fluent setter (mutates state, returns self).
+type Router interface {
+	Get(path string) Router
+	Post(path string) Router
+}
+
+type Server struct{ routes []string }
+
+func (s *Server) Get(path string) Router  { s.routes = append(s.routes, "GET "+path); return s }
+func (s *Server) Post(path string) Router { s.routes = append(s.routes, "POST "+path); return s }
+
+// Delegation: body returns a method call on the receiver. Common in Fiber's
+// `func (app *App) Get(...) Router { return app.Add(...) }` shape.
+type App struct{ server *Server }
+
+func (a *App) Add(method, path string) *App {
+	a.server.routes = append(a.server.routes, method+" "+path)
+	return a
+}
+func (a *App) GetRoute(path string) *App  { return a.Add("GET", path) }
+func (a *App) PostRoute(path string) *App { return a.Add("POST", path) }
+
+// Pointer receiver returning a *different* concrete type — must not be marked.
+type Group struct{}
+
+func (a *App) NewGroup() *Group { return &Group{} }
+
+// Value receiver returning same type — must not be marked (immutable update).
+type Coord struct{ X, Y int }
+
+func (c Coord) Translate(dx, dy int) Coord { return Coord{c.X + dx, c.Y + dy} }
+
+// Clone/Copy return a new value — must not be marked even though the body
+// returns the receiver name in some path; the Clone/Copy name exclusion catches
+// the common case before AST inspection runs.
+type Cfg struct{ tags []string }
+
+func (c *Cfg) Clone() *Cfg { return &Cfg{tags: append([]string(nil), c.tags...)} }
+func (c *Cfg) Copy() *Cfg  { return c.Clone() }
+
+// Trivial single-statement return-self getter — must not be marked. This is
+// the structural shape of interface-method implementations like
+// `func (b *BasicType) Basic() *BasicType { return b }` in go/debug/dwarf.
+type TypeLike interface {
+	Underlying() TypeLike
+	Self() TypeLike
+}
+
+type Box struct{}
+
+func (b *Box) Underlying() TypeLike { return b }
+func (b *Box) Self() TypeLike       { return b }
+
+// Copy-and-modify pattern (slog.Logger.With shape) — must not be marked.
+// Body assigns to a local and returns the local.
+type Logger struct{ attrs []string }
+
+func (l *Logger) With(attr string) *Logger {
+	clone := &Logger{attrs: append([]string(nil), l.attrs...)}
+	clone.attrs = append(clone.attrs, attr)
+	return clone
+}
+
+// Multi-path method where one return path is non-receiver (go/types Origin
+// shape) — must not be marked because not ALL returns are receiver-like.
+type Var struct{ origin *Var }
+
+func (v *Var) Origin() *Var {
+	if v.origin != nil {
+		return v.origin
+	}
+	return v
+}

bindgen/tests/testdata/fixtures/nullability_heuristics/nullability_heuristics.go

@@ -23,7 +23,10 @@ type Builder struct{ buf []byte }
 
 func (b *Builder) Reset() *Builder                 { b.buf = nil; return b }
 func (b *Builder) Append(data []byte) *Builder     { b.buf = append(b.buf, data...); return b }
-func (b *Builder) SetTag(key, val string) *Builder { return b }
+func (b *Builder) SetTag(key, val string) *Builder {
+	b.buf = append(b.buf, []byte(key+"="+val)...)
+	return b
+}
 
 var defaultBuilder = &Builder{}
 

bindgen/tests/testdata/snapshots/builder_methods.d.lis

@@ -0,0 +1,97 @@
+// Generated by Lisette bindgen
+// Source: ./testdata/fixtures/builder_methods (local)
+// Go: 0.0.0
+// Lisette: 0.0.0
+
+/// Delegation: body returns a method call on the receiver. Common in Fiber's
+/// `func (app *App) Get(...) Router { return app.Add(...) }` shape.
+pub type App
+
+pub type Box
+
+/// Clone/Copy return a new value — must not be marked even though the body
+/// returns the receiver name in some path; the Clone/Copy name exclusion catches
+/// the common case before AST inspection runs.
+pub type Cfg
+
+/// Self-return on pointer receiver: classic fluent setter shape.
+pub type Config
+
+/// Value receiver returning same type — must not be marked (immutable update).
+pub struct Coord {
+  pub X: int,
+  pub Y: int,
+}
+
+/// Pointer receiver returning a *different* concrete type — must not be marked.
+pub type Group
+
+/// Copy-and-modify pattern (slog.Logger.With shape) — must not be marked.
+/// Body assigns to a local and returns the local.
+pub type Logger
+
+/// Interface self-return on a real fluent setter (mutates state, returns self).
+pub interface Router {
+  fn Get(path: string) -> Router
+  fn Post(path: string) -> Router
+}
+
+pub type Server
+
+/// Trivial single-statement return-self getter — must not be marked. This is
+/// the structural shape of interface-method implementations like
+/// `func (b *BasicType) Basic() *BasicType { return b }` in go/debug/dwarf.
+pub interface TypeLike {
+  fn Self() -> TypeLike
+  fn Underlying() -> TypeLike
+}
+
+/// Multi-path method where one return path is non-receiver (go/types Origin
+/// shape) — must not be marked because not ALL returns are receiver-like.
+pub type Var
+
+impl App {
+  #[allow(unused_value)]
+  fn Add(self: Ref<App>, method: string, path: string) -> Ref<App>
+  #[allow(unused_value)]
+  fn GetRoute(self: Ref<App>, path: string) -> Ref<App>
+  fn NewGroup(self: Ref<App>) -> Ref<Group>
+  #[allow(unused_value)]
+  fn PostRoute(self: Ref<App>, path: string) -> Ref<App>
+}
+
+impl Box {
+  fn Self(self: Ref<Box>) -> TypeLike
+  fn Underlying(self: Ref<Box>) -> TypeLike
+}
+
+impl Cfg {
+  fn Clone(self: Ref<Cfg>) -> Ref<Cfg>
+  fn Copy(self: Ref<Cfg>) -> Ref<Cfg>
+}
+
+impl Config {
+  fn Name(self: Ref<Config>) -> string
+  #[allow(unused_value)]
+  fn WithName(self: Ref<Config>, n: string) -> Ref<Config>
+  fn WithTag(self: Ref<Config>, k: string, v: string)
+}
+
+impl Coord {
+  fn Translate(self, dx: int, dy: int) -> Coord
+}
+
+impl Logger {
+  fn With(self: Ref<Logger>, attr: string) -> Ref<Logger>
+}
+
+impl Server {
+  #[allow(unused_value)]
+  fn Get(self: Ref<Server>, path: string) -> Router
+  #[allow(unused_value)]
+  fn Post(self: Ref<Server>, path: string) -> Router
+}
+
+impl Var {
+  fn Origin(self: Ref<Var>) -> Ref<Var>
+}

bindgen/tests/testdata/snapshots/nullability_heuristics.d.lis

@@ -74,8 +74,11 @@ pub struct Widget {
 }
 
 impl Builder {
+  #[allow(unused_value)]
   fn Append(self: Ref<Builder>, data: Slice<uint8>) -> Ref<Builder>
+  #[allow(unused_value)]
   fn Reset(self: Ref<Builder>) -> Ref<Builder>
+  #[allow(unused_value)]
   fn SetTag(self: Ref<Builder>, key: string, val: string) -> Ref<Builder>
 }
 

crates/stdlib/typedefs/container/list.d.lis

@@ -30,6 +30,7 @@ impl List {
   fn Front(self: Ref<List>) -> Option<Ref<Element>>
 
   /// Init initializes or clears list l.
+  #[allow(unused_value)]
   fn Init(self: Ref<List>) -> Ref<List>
 
   /// InsertAfter inserts a new element e with value v immediately after mark and returns e.