Static analysis: gocognit (#10527)

* Add gocognit to static analyzers with a very high threshold

* edit readme and sort analyzers

tools/analyzers/gocognit/BUILD.bazel

@@ -0,0 +1,14 @@
+load("@prysm//tools/go:def.bzl", "go_library")
+
+go_library(
+    name = "go_default_library",
+    srcs = ["analyzer.go"],
+    importpath = "github.com/prysmaticlabs/prysm/tools/analyzers/gocognit",
+    visibility = ["//visibility:public"],
+    deps = [
+        "@com_github_uudashr_gocognit//:go_default_library",
+        "@org_golang_x_tools//go/analysis:go_default_library",
+        "@org_golang_x_tools//go/analysis/passes/inspect:go_default_library",
+        "@org_golang_x_tools//go/ast/inspector:go_default_library",
+    ],
+)

tools/analyzers/gocognit/README.md

@@ -0,0 +1,195 @@
+> Copied from https://github.com/uudashr/gocognit/blob/5bf67146515e79acd2a8d5728deafa9d91ad48db/README.md
+> License: MIT
+
+[![GoDoc](https://godoc.org/github.com/uudashr/gocognit?status.svg)](https://godoc.org/github.com/uudashr/gocognit)
+# Gocognit
+Gocognit calculates cognitive complexities of functions in Go source code. A measurement of how hard does the code is intuitively to understand.
+
+## Understanding the complexity
+
+Given code using `if` statement,
+```go
+func GetWords(number int) string {
+    if number == 1 {            // +1
+        return "one"
+    } else if number == 2 {     // +1
+        return "a couple"
+    } else if number == 3 {     // +1
+        return "a few"
+    } else {                    // +1
+        return "lots"
+    }
+} // Cognitive complexity = 4
+```
+
+Above code can be refactored using `switch` statement,
+```go
+func GetWords(number int) string {
+    switch number {             // +1
+        case 1:
+            return "one"
+        case 2:
+            return "a couple"
+        case 3:
+            return "a few"
+        default:
+            return "lots"
+    }
+} // Cognitive complexity = 1
+```
+
+As you see above codes are the same, but the second code are easier to understand, that is why the cognitive complexity score are lower compare to the first one.
+
+## Comparison with cyclometic complexity
+
+### Example 1
+#### Cyclometic complexity
+```go
+func GetWords(number int) string {      // +1
+    switch number {
+        case 1:                         // +1
+            return "one"
+        case 2:                         // +1
+            return "a couple"
+        case 3:                         // +1
+             return "a few"
+        default:
+             return "lots"
+    }
+} // Cyclomatic complexity = 4
+```
+
+####  Cognitive complexity
+```go
+func GetWords(number int) string {
+    switch number {                     // +1
+        case 1:
+            return "one"
+        case 2:
+            return "a couple"
+        case 3:
+            return "a few"
+        default:
+            return "lots"
+    }
+} // Cognitive complexity = 1
+```
+
+Cognitive complexity give lower score compare to cyclomatic complexity.
+
+### Example 2
+#### Cyclomatic complexity
+```go
+func SumOfPrimes(max int) int {         // +1
+    var total int
+
+OUT:
+    for i := 1; i < max; i++ {          // +1
+        for j := 2; j < i; j++ {        // +1
+            if i%j == 0 {               // +1
+                continue OUT
+            }
+        }
+        total += i
+    }
+
+    return total
+} // Cyclomatic complexity = 4
+```
+
+#### Cognitive complexity
+```go
+func SumOfPrimes(max int) int {
+    var total int
+
+OUT:
+    for i := 1; i < max; i++ {          // +1
+        for j := 2; j < i; j++ {        // +2 (nesting = 1)
+            if i%j == 0 {               // +3 (nesting = 2)
+                continue OUT            // +1
+            }
+        }
+        total += i
+    }
+
+    return total
+} // Cognitive complexity = 7
+```
+
+Cognitive complexity give higher score compare to cyclomatic complexity.
+
+## Rules
+
+The cognitive complexity of a function is calculated according to the
+following rules:
+> Note: these rules are specific for Go, please see the [original whitepaper](./CognitiveComplexity.pdf) for more complete reference.
+
+### Increments
+There is an increment for each of the following:
+1. `if`, `else if`, `else`
+2. `switch`, `select`
+3. `for`
+4. `goto` LABEL, `break` LABEL, `continue` LABEL
+5. sequence of binary logical operators
+6. each method in a recursion cycle
+
+### Nesting level
+The following structures increment the nesting level:
+1. `if`, `else if`, `else`
+2. `switch`, `select`
+3. `for`
+4. function literal or lambda
+
+### Nesting increments
+The following structures receive a nesting increment commensurate with their nested depth inside nesting structures:
+1. `if`
+2. `switch`, `select`
+3. `for`
+
+## Installation
+
+```
+$ go install github.com/uudashr/gocognit/cmd/gocognit@latest
+```
+
+or 
+
+```
+$ go get github.com/uudashr/gocognit/cmd/gocognit
+```
+
+## Usage
+
+```
+$ gocognit
+Calculate cognitive complexities of Go functions.
+Usage:
+        gocognit [flags] <Go file or directory> ...
+Flags:
+        -over N   show functions with complexity > N only and
+                  return exit code 1 if the set is non-empty
+        -top N    show the top N most complex functions only
+        -avg      show the average complexity over all functions,
+                  not depending on whether -over or -top are set
+The output fields for each line are:
+<complexity> <package> <function> <file:row:column>
+```
+
+Examples:
+
+```
+$ gocognit .
+$ gocognit main.go
+$ gocognit -top 10 src/
+$ gocognit -over 25 docker
+$ gocognit -avg .
+```
+
+The output fields for each line are:
+```
+<complexity> <package> <function> <file:row:column>
+```
+
+## Related project
+- [Gocyclo](https://github.com/fzipp/gocyclo) where the code are based on.
+- [Cognitive Complexity: A new way of measuring understandability](./CognitiveComplexity.pdf) white paper by G. Ann Campbell.

tools/analyzers/gocognit/analyzer.go

@@ -0,0 +1,90 @@
+package gocognit
+
+import (
+	"errors"
+	"fmt"
+	"go/ast"
+
+	"github.com/uudashr/gocognit"
+	"golang.org/x/tools/go/analysis"
+	"golang.org/x/tools/go/analysis/passes/inspect"
+	"golang.org/x/tools/go/ast/inspector"
+)
+
+// Doc explaining the tool.
+const Doc = "Tool to ensure go code does not have high cognitive complexity."
+
+// Analyzer runs static analysis.
+var Analyzer = &analysis.Analyzer{
+	Name:     "gocognit",
+	Doc:      Doc,
+	Requires: []*analysis.Analyzer{inspect.Analyzer},
+	Run:      run,
+}
+
+// Recommended thresholds according to the 2008 presentation titled
+// "Software Quality Metrics to Identify Risk" by Thomas McCabe Jr.
+//
+//  1 - 10 Simple procedure, little risk
+// 11 - 20 More complex, moderate risk
+// 21 - 50 Complex, high risk
+// > 50 Untestable code, very high risk
+//
+// This threshold should be lowered to 50 over time.
+const over = 130
+
+func run(pass *analysis.Pass) (interface{}, error) {
+	inspect, ok := pass.ResultOf[inspect.Analyzer].(*inspector.Inspector)
+	if !ok {
+		return nil, errors.New("analyzer is not type *inspector.Inspector")
+	}
+
+	nodeFilter := []ast.Node{
+		(*ast.FuncDecl)(nil),
+	}
+	inspect.Preorder(nodeFilter, func(n ast.Node) {
+		fnDecl, ok := n.(*ast.FuncDecl)
+		if !ok {
+			return
+		}
+
+		fnName := funcName(fnDecl)
+		fnComplexity := gocognit.Complexity(fnDecl)
+
+		if fnComplexity > over {
+			pass.Reportf(fnDecl.Pos(), "cognitive complexity %d of func %s is high (> %d)", fnComplexity, fnName, over)
+		}
+	})
+
+	return nil, nil
+}
+
+// funcName returns the name representation of a function or method:
+// "(Type).Name" for methods or simply "Name" for functions.
+//
+// Copied from https://github.com/uudashr/gocognit/blob/5bf67146515e79acd2a8d5728deafa9d91ad48db/gocognit.go
+// License: MIT
+func funcName(fn *ast.FuncDecl) string {
+	if fn.Recv != nil {
+		if fn.Recv.NumFields() > 0 {
+			typ := fn.Recv.List[0].Type
+			return fmt.Sprintf("(%s).%s", recvString(typ), fn.Name)
+		}
+	}
+	return fn.Name.Name
+}
+
+// recvString returns a string representation of recv of the
+// form "T", "*T", or "BADRECV" (if not a proper receiver type).
+//
+// Copied from https://github.com/uudashr/gocognit/blob/5bf67146515e79acd2a8d5728deafa9d91ad48db/gocognit.go
+// License: MIT
+func recvString(recv ast.Expr) string {
+	switch t := recv.(type) {
+	case *ast.Ident:
+		return t.Name
+	case *ast.StarExpr:
+		return "*" + recvString(t.X)
+	}
+	return "BADRECV"
+}