.config/coc/extensions/coc-go-data/tools/pkg/mod/golang.org/x/tools@v0.0.0-20201028153306-37f0764111ff/go/analysis/passes/stdmethods/stdmethods.go

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