1// Copyright 2010 The Go Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file.
4
5// Package stdmethods defines an Analyzer that checks for misspellings
6// in the signatures of methods similar to well-known interfaces.
7package stdmethods
8
9import (
10	"bytes"
11	"fmt"
12	"go/ast"
13	"go/printer"
14	"go/token"
15	"go/types"
16	"strings"
17
18	"golang.org/x/tools/go/analysis"
19	"golang.org/x/tools/go/analysis/passes/inspect"
20	"golang.org/x/tools/go/ast/inspector"
21)
22
23const Doc = `check signature of methods of well-known interfaces
24
25Sometimes a type may be intended to satisfy an interface but may fail to
26do so because of a mistake in its method signature.
27For example, the result of this WriteTo method should be (int64, error),
28not error, to satisfy io.WriterTo:
29
30	type myWriterTo struct{...}
31        func (myWriterTo) WriteTo(w io.Writer) error { ... }
32
33This check ensures that each method whose name matches one of several
34well-known interface methods from the standard library has the correct
35signature for that interface.
36
37Checked method names include:
38	Format GobEncode GobDecode MarshalJSON MarshalXML
39	Peek ReadByte ReadFrom ReadRune Scan Seek
40	UnmarshalJSON UnreadByte UnreadRune WriteByte
41	WriteTo
42`
43
44var Analyzer = &analysis.Analyzer{
45	Name:     "stdmethods",
46	Doc:      Doc,
47	Requires: []*analysis.Analyzer{inspect.Analyzer},
48	Run:      run,
49}
50
51// canonicalMethods lists the input and output types for Go methods
52// that are checked using dynamic interface checks. Because the
53// checks are dynamic, such methods would not cause a compile error
54// if they have the wrong signature: instead the dynamic check would
55// fail, sometimes mysteriously. If a method is found with a name listed
56// here but not the input/output types listed here, vet complains.
57//
58// A few of the canonical methods have very common names.
59// For example, a type might implement a Scan method that
60// has nothing to do with fmt.Scanner, but we still want to check
61// the methods that are intended to implement fmt.Scanner.
62// To do that, the arguments that have a = prefix are treated as
63// signals that the canonical meaning is intended: if a Scan
64// method doesn't have a fmt.ScanState as its first argument,
65// we let it go. But if it does have a fmt.ScanState, then the
66// rest has to match.
67var canonicalMethods = map[string]struct{ args, results []string }{
68	// "Flush": {{}, {"error"}}, // http.Flusher and jpeg.writer conflict
69	"Format":        {[]string{"=fmt.State", "rune"}, []string{}},                      // fmt.Formatter
70	"GobDecode":     {[]string{"[]byte"}, []string{"error"}},                           // gob.GobDecoder
71	"GobEncode":     {[]string{}, []string{"[]byte", "error"}},                         // gob.GobEncoder
72	"MarshalJSON":   {[]string{}, []string{"[]byte", "error"}},                         // json.Marshaler
73	"MarshalXML":    {[]string{"*xml.Encoder", "xml.StartElement"}, []string{"error"}}, // xml.Marshaler
74	"ReadByte":      {[]string{}, []string{"byte", "error"}},                           // io.ByteReader
75	"ReadFrom":      {[]string{"=io.Reader"}, []string{"int64", "error"}},              // io.ReaderFrom
76	"ReadRune":      {[]string{}, []string{"rune", "int", "error"}},                    // io.RuneReader
77	"Scan":          {[]string{"=fmt.ScanState", "rune"}, []string{"error"}},           // fmt.Scanner
78	"Seek":          {[]string{"=int64", "int"}, []string{"int64", "error"}},           // io.Seeker
79	"UnmarshalJSON": {[]string{"[]byte"}, []string{"error"}},                           // json.Unmarshaler
80	"UnmarshalXML":  {[]string{"*xml.Decoder", "xml.StartElement"}, []string{"error"}}, // xml.Unmarshaler
81	"UnreadByte":    {[]string{}, []string{"error"}},
82	"UnreadRune":    {[]string{}, []string{"error"}},
83	"WriteByte":     {[]string{"byte"}, []string{"error"}},                // jpeg.writer (matching bufio.Writer)
84	"WriteTo":       {[]string{"=io.Writer"}, []string{"int64", "error"}}, // io.WriterTo
85}
86
87func run(pass *analysis.Pass) (interface{}, error) {
88	inspect := pass.ResultOf[inspect.Analyzer].(*inspector.Inspector)
89
90	nodeFilter := []ast.Node{
91		(*ast.FuncDecl)(nil),
92		(*ast.InterfaceType)(nil),
93	}
94	inspect.Preorder(nodeFilter, func(n ast.Node) {
95		switch n := n.(type) {
96		case *ast.FuncDecl:
97			if n.Recv != nil {
98				canonicalMethod(pass, n.Name, n.Type)
99			}
100		case *ast.InterfaceType:
101			for _, field := range n.Methods.List {
102				for _, id := range field.Names {
103					canonicalMethod(pass, id, field.Type.(*ast.FuncType))
104				}
105			}
106		}
107	})
108	return nil, nil
109}
110
111func canonicalMethod(pass *analysis.Pass, id *ast.Ident, t *ast.FuncType) {
112	// Expected input/output.
113	expect, ok := canonicalMethods[id.Name]
114	if !ok {
115		return
116	}
117
118	// Actual input/output
119	args := typeFlatten(t.Params.List)
120	var results []ast.Expr
121	if t.Results != nil {
122		results = typeFlatten(t.Results.List)
123	}
124
125	// Do the =s (if any) all match?
126	if !matchParams(pass, expect.args, args, "=") || !matchParams(pass, expect.results, results, "=") {
127		return
128	}
129
130	// Everything must match.
131	if !matchParams(pass, expect.args, args, "") || !matchParams(pass, expect.results, results, "") {
132		expectFmt := id.Name + "(" + argjoin(expect.args) + ")"
133		if len(expect.results) == 1 {
134			expectFmt += " " + argjoin(expect.results)
135		} else if len(expect.results) > 1 {
136			expectFmt += " (" + argjoin(expect.results) + ")"
137		}
138
139		var buf bytes.Buffer
140		if err := printer.Fprint(&buf, pass.Fset, t); err != nil {
141			fmt.Fprintf(&buf, "<%s>", err)
142		}
143		actual := buf.String()
144		actual = strings.TrimPrefix(actual, "func")
145		actual = id.Name + actual
146
147		pass.Reportf(id.Pos(), "method %s should have signature %s", actual, expectFmt)
148	}
149}
150
151func argjoin(x []string) string {
152	y := make([]string, len(x))
153	for i, s := range x {
154		if s[0] == '=' {
155			s = s[1:]
156		}
157		y[i] = s
158	}
159	return strings.Join(y, ", ")
160}
161
162// Turn parameter list into slice of types
163// (in the ast, types are Exprs).
164// Have to handle f(int, bool) and f(x, y, z int)
165// so not a simple 1-to-1 conversion.
166func typeFlatten(l []*ast.Field) []ast.Expr {
167	var t []ast.Expr
168	for _, f := range l {
169		if len(f.Names) == 0 {
170			t = append(t, f.Type)
171			continue
172		}
173		for range f.Names {
174			t = append(t, f.Type)
175		}
176	}
177	return t
178}
179
180// Does each type in expect with the given prefix match the corresponding type in actual?
181func matchParams(pass *analysis.Pass, expect []string, actual []ast.Expr, prefix string) bool {
182	for i, x := range expect {
183		if !strings.HasPrefix(x, prefix) {
184			continue
185		}
186		if i >= len(actual) {
187			return false
188		}
189		if !matchParamType(pass.Fset, pass.Pkg, x, actual[i]) {
190			return false
191		}
192	}
193	if prefix == "" && len(actual) > len(expect) {
194		return false
195	}
196	return true
197}
198
199// Does this one type match?
200func matchParamType(fset *token.FileSet, pkg *types.Package, expect string, actual ast.Expr) bool {
201	expect = strings.TrimPrefix(expect, "=")
202	// Strip package name if we're in that package.
203	if n := len(pkg.Name()); len(expect) > n && expect[:n] == pkg.Name() && expect[n] == '.' {
204		expect = expect[n+1:]
205	}
206
207	// Overkill but easy.
208	var buf bytes.Buffer
209	printer.Fprint(&buf, fset, actual)
210	return buf.String() == expect
211}
212