Gocognit

https://pkg.go.dev/github.com/uudashr/gocognit
Admin
Gocognit is a Go tool that calculates cognitive complexity of functions and methods to measure how...
Tokens:4,664
Snippets:69
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install gocognit using go get

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Installs the gocognit command-line tool using 'go get'. This is an alternative method for installation.

```bash
go get github.com/uudashr/gocognit/cmd/gocognit

```

--------------------------------

### GoCognit Examples

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Provides various examples of how to use the gocognit command-line tool with different flags and targets.

```bash
$ gocognit .

```

```bash
$ gocognit main.go

```

```bash
$ gocognit -top 10 src/

```

```bash
$ gocognit -over 25 docker

```

```bash
$ gocognit -avg .

```

```bash
$ gocognit -ignore "_test|testdata" .

```

--------------------------------

### Install gocognit using go install

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Installs the gocognit command-line tool using 'go install'. Ensure your Go environment is set up correctly.

```bash
go install github.com/uudashr/gocognit/cmd/gocognit@latest

```

--------------------------------

### Cognitive Complexity Example 2

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Calculates the cognitive complexity for the same function as Example 2, demonstrating a higher score due to nesting and control flow.

```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 Example 1

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Calculates the cognitive complexity of a switch statement. This example shows a lower score compared to cyclomatic complexity.

```go
func GetWords(number int) {
    switch number {
        case 1:
            return "one"
        case 2:
            return "a couple"
        case 3:
            return "a few"
        default:
            return "lots"
    }
} // Cognitive complexity = 1

```

--------------------------------

### Cyclomatic Complexity Example 1

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Calculates the cyclomatic complexity of a switch statement. This serves as a baseline for comparison with cognitive 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

```

--------------------------------

### Cyclomatic Complexity Example 2

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Calculates the cyclomatic complexity for a function with nested loops and conditional statements. This highlights a scenario where cyclomatic complexity might be lower.

```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

```

--------------------------------

### Switch Statement Cognitive Complexity Example

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Shows a refactored version of the previous example using a switch statement, resulting in a lower cognitive complexity score.

```go
func GetWords(number int) string {
    switch number {
        case 1:
            return "one"
        case 2:
            return "a couple"
        case 3:
            return "a few"
        default:
            return "lots"
    }
} // Cognitive complexity = 1

```

--------------------------------

### Diagnostic JSON Output

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Example of the JSON output when diagnostic mode is enabled, detailing complexity, function information, and diagnostic steps.

```json
[
    {
        "PkgName": "prime",
        "FuncName": "SumOfPrimes",
        "Complexity": 7,
        "Pos": {
            "Filename": "prime.go",
            "Offset": 15,
            "Line": 3,
            "Column": 1
        },
        "Diagnostics": [
            {
                "Inc": 1,
                "Text": "for",
                "Pos": {
                    "Offset": 69,
                    "Line": 7,
                    "Column": 2
                }
            },
            {
                "Inc": 2,
                "Nesting": 1,
                "Text": "for",
                "Pos": {
                    "Offset": 104,
                    "Line": 8,
                    "Column": 3
                }
            },
            {
                "Inc": 3,
                "Nesting": 2,
                "Text": "if",
                "Pos": {
                    "Offset": 152,
                    "Line": 9,
                    "Column": 4
                }
            },
            {
                "Inc": 1,
                "Text": "continue",
                "Pos": {
                    "Offset": 190,
                    "Line": 10,
                    "Column": 5
                }
            }
        ]
    }
]

```

--------------------------------

### CountDown

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Generates a sequence of integers counting down from a given start value.

```APIDOC
## CountDown

### Description
Generates a sequence of integers counting down from a given start value.

### Signature
```go
func CountDown(start int) iter.Seq[int]
```

### Added in version
1.2.1
```

--------------------------------

### If-Else If Cognitive Complexity Example

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Demonstrates a function with if-else if statements, illustrating a higher cognitive complexity score due to conditional branching.

```go
func GetWords(number int) string {
    if number == 1 {
        return "one"
    } else if number == 2 {
        return "a couple"
    } else if number == 3 {
        return "a few"
    } else {
        return "lots"
    }
} // Cognitive complexity = 4

```

--------------------------------

### GoCognit CLI Usage

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Demonstrates the basic command-line usage of the gocognit tool. Use this to calculate cognitive complexities of Go functions in specified files or directories.

```bash
$ gocognit
Calculate cognitive complexities of Go functions.

Usage:

  gocognit [<flag> ...] <Go file or directory> ...

Flags:

  -over N       show functions with complexity > N only
                and return exit code 1 if the output 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
  -test         indicates whether test files should be included
  -json         encode the output as JSON
  -d 	        enable diagnostic output
  -f format     string the format to use
                (default "{{.Complexity}} {{.PkgName}} {{.FuncName}} {{.Pos}}")
  -ignore expr  ignore files matching the given regexp

The (default) output fields for each line are:

  <complexity> <package> <function> <file:row:column>

The (default) output fields for each line are:

  {{.Complexity}} {{.PkgName}} {{.FuncName}} {{.Pos}}

or equal to <complexity> <package> <function> <file:row:column>

The struct being passed to the template is:

  type Stat struct {
    PkgName     string
    FuncName    string
    Complexity  int
    Pos         token.Position
    Diagnostics []Diagnostics
  }

  type Diagnostic struct {
    Inc     string
    Nesting int
    Text    string
    Pos     DiagnosticPosition
  }

  type DiagnosticPosition struct {
    Offset int
    Line   int
    Column int
  }

```

--------------------------------

### gocognit Usage

Source: https://pkg.go.dev/github.com/uudashr/gocognit/cmd/gocognit

Basic command-line usage for gocognit. Specify flags and the Go file or directory to analyze.

```bash
gocognit [<flag> ...] <Go file or directory> ...
```

--------------------------------

### GoCognit Output Format

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Illustrates the default output format for GoCognit, showing complexity, package, function name, and file position.

```text
<complexity> <package> <function> <file:row:column>

```

--------------------------------

### Build Complexity Statistics with Diagnostics

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Builds complexity statistics for a Go file, with an option to enable detailed diagnostics.

```go
func ComplexityStatsWithDiagnostic(f *ast.File, fset *token.FileSet, stats []Stat, enableDiagnostics bool) []Stat
```

--------------------------------

### Build Complexity Statistics

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Builds complexity statistics for a given Go file using provided statistics.

```go
func ComplexityStats(f *ast.File, fset *token.FileSet, stats []Stat) []Stat
```

--------------------------------

### Enable Diagnostic Output

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Demonstrates enabling diagnostic output with the `-d` flag and JSON format for detailed complexity calculation insights.

```bash
$ gocognit -json -d .

```

--------------------------------

### gocognit Template Output Fields

Source: https://pkg.go.dev/github.com/uudashr/gocognit/cmd/gocognit

The default template used for formatting output, specifying the fields to be displayed.

```go
{{.Complexity}} {{.PkgName}} {{.FuncName}} {{.Pos}}
```

--------------------------------

### gocognit Default Output Fields

Source: https://pkg.go.dev/github.com/uudashr/gocognit/cmd/gocognit

The default fields displayed for each analyzed function. Includes complexity, package name, function name, and file position.

```text
<complexity> <package> <function> <file:row:column>
```

--------------------------------

### ComplexityStats

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Builds the complexity statistics for a given AST file.

```APIDOC
## ComplexityStats

### Description
Builds the complexity statistics for a given AST file.

### Signature
```go
func ComplexityStats(f *ast.File, fset *token.FileSet, stats []Stat) []Stat
```
```

--------------------------------

### gocognit Flags

Source: https://pkg.go.dev/github.com/uudashr/gocognit/cmd/gocognit

Available flags for customizing gocognit's analysis and output. Use -over or -top to filter results, -avg for average complexity, -test to include test files, -json for JSON output, -d for diagnostics, and -f for custom formatting.

```bash
-over N    show functions with complexity > N only and return exit code 1 if the output is non-empty
```

```bash
-top N     show the top N most complex functions only
```

```bash
-avg       show the average complexity over all functions, not depending on whether -over or -top are set
```

```bash
-test      indicates whether test files should be included
```

```bash
-json      encode the output as JSON
```

```bash
-d 	       enable diagnostic output
```

```bash
-f format  string the format to use (default "{{.Complexity}} {{.PkgName}} {{.FuncName}} {{.Pos}}")
```

--------------------------------

### ComplexityStatsWithDiagnostic

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Builds complexity statistics with optional diagnostics.

```APIDOC
## ComplexityStatsWithDiagnostic

### Description
Builds the complexity statistics with optional diagnostic information.

### Signature
```go
func ComplexityStatsWithDiagnostic(f *ast.File, fset *token.FileSet, stats []Stat, enableDiagnostics bool) []Stat
```

### Added in version
1.2.0
```

--------------------------------

### GoCognit Constant Definition

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Defines the 'Doc' constant used for documentation within the GoCognit package.

```go
const Doc = `` /* 169-byte string literal not displayed */

```

--------------------------------

### Ignore Function Directive

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Shows how to use the `//gocognit:ignore` directive to exclude specific functions from complexity analysis.

```go
//gocognit:ignore
func IgnoreMe() {
    // ...
}

```

--------------------------------

### String representation for DiagnosticPosition

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Provides a string representation for a DiagnosticPosition object.

```go
func (pos DiagnosticPosition) String() string
```

--------------------------------

### String representation for Diagnostic

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Provides a string representation for a Diagnostic object.

```go
func (d Diagnostic) String() string
```

--------------------------------

### String representation for Stat

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Provides a string representation for a Stat object.

```go
func (s Stat) String() string
```

--------------------------------

### Define Diagnostic Struct

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Represents information about how complexity increases within code. Includes nesting level and text.

```go
type Diagnostic struct {
	Inc     int
	Nesting int `json:",omitempty"`
	Text    string
	Pos     DiagnosticPosition
}
```

--------------------------------

### ScanComplexity

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Scans a function declaration and returns its complexity and diagnostics.

```APIDOC
## ScanComplexity

### Description
Scans the function declaration to calculate cognitive complexity and optionally collect diagnostics.

### Signature
```go
func ScanComplexity(fn *ast.FuncDecl, includeDiagnostics bool) ScanResult
```

### Added in version
1.2.0
```

--------------------------------

### DiagnosticPosition.String

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Returns a string representation of the DiagnosticPosition struct.

```APIDOC
## DiagnosticPosition.String

### Description
Returns a string representation of the DiagnosticPosition struct.

### Signature
```go
func (pos DiagnosticPosition) String() string
```

### Added in version
1.2.0
```

--------------------------------

### Stat.String

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Returns a string representation of the Stat struct.

```APIDOC
## Stat.String

### Description
Returns a string representation of the Stat struct.

### Signature
```go
func (s Stat) String() string
```
```

--------------------------------

### gocognit Diagnostic Struct

Source: https://pkg.go.dev/github.com/uudashr/gocognit/cmd/gocognit

The Go struct representing diagnostic information for a function, detailing issues and their positions.

```go
type Diagnostic struct {
  Inc     string
  Nesting int
  Text    string
  Pos     DiagnosticPosition
}
```

--------------------------------

### Diagnostic.String

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Returns a string representation of the Diagnostic struct.

```APIDOC
## Diagnostic.String

### Description
Returns a string representation of the Diagnostic struct.

### Signature
```go
func (d Diagnostic) String() string
```

### Added in version
1.2.0
```

--------------------------------

### gocognit Stat Struct

Source: https://pkg.go.dev/github.com/uudashr/gocognit/cmd/gocognit

The Go struct used to hold analysis statistics for a function, including complexity and diagnostic information.

```go
type Stat struct {
  PkgName    string
  FuncName   string
  Complexity int
  Diagnostics []Diagnostic
  Pos        token.Position
}
```

--------------------------------

### Scan Function Complexity

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Scans a function declaration to determine its cognitive complexity and generate diagnostics if requested.

```go
func ScanComplexity(fn *ast.FuncDecl, includeDiagnostics bool) ScanResult
```

--------------------------------

### DoCount

Source: https://pkg.go.dev/github.com/uudashr/gocognit

A simple function that performs a counting operation.

```APIDOC
## DoCount

### Description
A function that performs a counting operation.

### Signature
```go
func DoCount()
```

### Added in version
1.2.1
```

--------------------------------

### gocognit DiagnosticPosition Struct

Source: https://pkg.go.dev/github.com/uudashr/gocognit/cmd/gocognit

The Go struct defining the position of a diagnostic within the source code, including offset, line, and column.

```go
type DiagnosticPosition struct {
  Offset int
  Line   int
  Column int
}
```

--------------------------------

### Define DiagnosticPosition Struct

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Specifies the position of a diagnostic within the source code, including offset, line, and column.

```go
type DiagnosticPosition struct {
	Offset int // offset, starting at 0
	Line   int // line number, starting at 1
	Column int // column number, starting at 1 (byte count)
}
```

--------------------------------

### ForRangeIter

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Processes a sequence of integers using a range iterator.

```APIDOC
## ForRangeIter

### Description
Processes a sequence of integers using a range iterator.

### Signature
```go
func ForRangeIter(all iter.Seq[int])
```

### Added in version
1.2.1
```

--------------------------------

### GoCognit Analyzer Variable

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Defines the 'Analyzer' variable, which is an instance of analysis.Analyzer for the GoCognit tool.

```go
var Analyzer = &analysis.Analyzer{
	Name:     "gocognit",
	Doc:      Doc,
	Requires: []*analysis.Analyzer{inspect.Analyzer},
	Run:      run,
}

```

--------------------------------

### Define Stat Struct

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Contains statistical information about the complexity of a function, including its name, complexity score, position, and any associated diagnostics.

```go
type Stat struct {
	PkgName     string
	FuncName    string
	Complexity  int
	Pos         token.Position
	Diagnostics []Diagnostic `json:",omitempty"`
}
```

--------------------------------

### Calculate Function Complexity

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Calculates the cognitive complexity of a given function declaration.

```go
func Complexity(fn *ast.FuncDecl) int
```

--------------------------------

### Define ScanResult Struct

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Holds the results of a complexity scan, including a list of diagnostics and the total complexity score.

```go
type ScanResult struct {
	Diagnostics []diagnostic
	Complexity  int
}
```

--------------------------------

### Complexity

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Calculates the cognitive complexity of a given function declaration.

```APIDOC
## Complexity

### Description
Calculates the cognitive complexity of a function.

### Signature
```go
func Complexity(fn *ast.FuncDecl) int
```
```

--------------------------------

### DoFilter

Source: https://pkg.go.dev/github.com/uudashr/gocognit

A function that performs a filtering operation.

```APIDOC
## DoFilter

### Description
A function that performs a filtering operation.

### Signature
```go
func DoFilter()
```

### Added in version
1.2.1
```

--------------------------------

### FilteredMap

Source: https://pkg.go.dev/github.com/uudashr/gocognit

Applies a filter to a map and returns a sequence of key-value pairs.

```APIDOC
## FilteredMap

### Description
Applies a filter to a map and returns a sequence of key-value pairs.

### Signature
```go
func FilteredMap(m map[string]int, threshold int) iter.Seq2[string, int]
```

### Added in version
1.2.1
```
Tokens:
Raw