Add .go-version support for the linter configuration (#12)

rdner · web-flow · commit 9240234eff8b · 2022-02-24T10:44:20.000+01:00
* Added the linter config template to
`dev-tools/templates/.golangci.yml`
* Added the `UpdateGoVersion` target to the magefile in order to apply
required Go Version changes
* Added assertion before linting that makes sure the linter config
does not have uncommitted changes

In order to change the Go version in the future, it's enough to edit
in the `.go-version` file and then run `mage -v UpdateGoVersion` and
commit the changes.
diff --git a/.golangci.yml b/.golangci.yml
@@ -1,3 +1,6 @@
+# DO NOT EDIT!
+# This file is a rendered template, the source can be found in "./dev-tools/templates/.golangci.yml"
+#
 # options for analysis running
 run:
   # timeout for analysis, e.g. 30s, 5m, default is 1m
@@ -100,7 +103,7 @@ linters-settings:
 
   gosimple:
     # Select the Go version to target. The default is '1.13'.
-    go: "1.17"
+    go: "1.17.6"
 
   misspell:
     # Correct spellings using locale preferences for US or UK.
@@ -135,11 +138,11 @@ linters-settings:
 
   staticcheck:
     # Select the Go version to target. The default is '1.13'.
-    go: "1.17"
+    go: "1.17.6"
 
   stylecheck:
     # Select the Go version to target. The default is '1.13'.
-    go: "1.17"
+    go: "1.17.6"
 
   unparam:
     # Inspect exported functions, default is false. Set to true if no external program/library imports your code.
@@ -150,4 +153,4 @@ linters-settings:
 
   unused:
     # Select the Go version to target. The default is '1.13'.
-    go: "1.17"
+    go: "1.17.6"
diff --git a/dev-tools/templates/.golangci.yml b/dev-tools/templates/.golangci.yml
@@ -0,0 +1,153 @@
+# options for analysis running
+run:
+  # timeout for analysis, e.g. 30s, 5m, default is 1m
+  timeout: 1m
+
+issues:
+  # Maximum count of issues with the same text.
+  # Set to 0 to disable.
+  # Default: 3
+  max-same-issues: 0
+  # Maximum issues count per one linter.
+  # Set to 0 to disable.
+  # Default: 50
+  max-issues-per-linter: 0
+
+output:
+  sort-results: true
+
+# Uncomment and add a path if needed to exclude
+# skip-dirs:
+#   - some/path
+# skip-files:
+#   - ".*\\.my\\.go$"
+#   - lib/bad.go
+
+# Find the whole list here https://golangci-lint.run/usage/linters/
+linters:
+  disable-all: true
+  enable:
+    - deadcode # finds unused code
+    - errcheck # checking for unchecked errors in go programs
+    - errorlint # errorlint is a linter for that can be used to find code that will cause problems with the error wrapping scheme introduced in Go 1.13.
+    - goconst # finds repeated strings that could be replaced by a constant
+    - dupl # tool for code clone detection
+    - forbidigo # forbids identifiers	matched by reg exps
+    - gomoddirectives # manage the use of 'replace', 'retract', and 'excludes' directives in go.mod.
+    - gosimple # linter for Go source code that specializes in simplifying a code
+    - misspell # finds commonly misspelled English words in comments
+    - nakedret # finds naked returns in functions greater than a specified function length
+    - prealloc # finds slice declarations that could potentially be preallocated
+    - nolintlint # reports ill-formed or insufficient nolint directives
+    - staticcheck # Staticcheck is a go vet on steroids, applying a ton of static analysis checks
+    - stylecheck # a replacement for golint
+    - unparam # reports unused function parameters
+    - unused # checks Go code for unused constants, variables, functions and types
+
+    - govet # Vet examines Go source code and reports suspicious constructs, such as Printf calls whose arguments do not align with the format string
+    - ineffassign # detects when assignments to existing variables are not used
+    - structcheck # finds unused struct fields
+    - typecheck # Like the front-end of a Go compiler, parses and type-checks Go code
+    - varcheck # Finds unused global variables and constants
+    - asciicheck # simple linter to check that your code does not contain non-ASCII identifiers
+    - bodyclose # checks whether HTTP response body is closed successfully
+    - durationcheck # check for two durations multiplied together
+    - exportloopref # checks for pointers to enclosing loop variables
+    - goimports # Goimports does everything that gofmt does. Additionally it checks unused imports
+    - gosec # inspects source code for security problems
+    - importas # enforces consistent import aliases
+    - nilerr # finds the code that returns nil even if it checks that the error is not nil.
+    - noctx # noctx finds sending http request without context.Context
+    - unconvert # Remove unnecessary type conversions
+    - wastedassign # wastedassign finds wasted assignment statements.
+    - godox # tool for detection of FIXME, TODO and other comment keywords
+
+# all available settings of specific linters
+linters-settings:
+  errcheck:
+    # report about not checking of errors in type assertions: `a := b.(MyStruct)`;
+    # default is false: such cases aren't reported by default.
+    check-type-assertions: true
+
+  errorlint:
+    # Check whether fmt.Errorf uses the %w verb for formatting errors. See the readme for caveats
+    errorf: true
+    # Check for plain type assertions and type switches
+    asserts: true
+    # Check for plain error comparisons
+    comparison: true
+
+  goconst:
+    # minimal length of string constant, 3 by default
+    min-len: 3
+    # minimal occurrences count to trigger, 3 by default
+    min-occurrences: 2
+
+  dupl:
+    # tokens count to trigger issue, 150 by default
+    threshold: 100
+
+  forbidigo:
+    # Forbid the following identifiers
+    forbid:
+      - fmt.Print.* # too much log noise
+    # Exclude godoc examples from forbidigo checks.  Default is true.
+    exclude_godoc_examples: true
+
+  gomoddirectives:
+    # Allow local `replace` directives. Default is false.
+    replace-local: false
+
+  gosimple:
+    # Select the Go version to target. The default is '1.13'.
+    go: "{{.GoVersion}}"
+
+  misspell:
+    # Correct spellings using locale preferences for US or UK.
+    # Default is to use a neutral variety of English.
+    # Setting locale to US will correct the British spelling of 'colour' to 'color'.
+    # locale: US
+    # ignore-words:
+    #   - IdP
+
+  nakedret:
+    # make an issue if func has more lines of code than this setting and it has naked returns; default is 30
+    max-func-lines: 0
+
+  prealloc:
+    # Report preallocation suggestions only on simple loops that have no returns/breaks/continues/gotos in them.
+    # True by default.
+    simple: true
+    range-loops: true # Report preallocation suggestions on range loops, true by default
+    for-loops: false # Report preallocation suggestions on for loops, false by default
+
+  nolintlint:
+    # Enable to ensure that nolint directives are all used. Default is true.
+    allow-unused: false
+    # Disable to ensure that nolint directives don't have a leading space. Default is true.
+    allow-leading-space: true
+    # Exclude following linters from requiring an explanation.  Default is [].
+    allow-no-explanation: []
+    # Enable to require an explanation of nonzero length after each nolint directive. Default is false.
+    require-explanation: true
+    # Enable to require nolint directives to mention the specific linter being suppressed. Default is false.
+    require-specific: true
+
+  staticcheck:
+    # Select the Go version to target. The default is '1.13'.
+    go: "{{.GoVersion}}"
+
+  stylecheck:
+    # Select the Go version to target. The default is '1.13'.
+    go: "{{.GoVersion}}"
+
+  unparam:
+    # Inspect exported functions, default is false. Set to true if no external program/library imports your code.
+    # XXX: if you enable this setting, unparam will report a lot of false-positives in text editors:
+    # if it's called for subdir of a project it can't find external interfaces. All text editor integrations
+    # with golangci-lint call it on a directory with the changed file.
+    check-exported: false
+
+  unused:
+    # Select the Go version to target. The default is '1.13'.
+    go: "{{.GoVersion}}"
diff --git a/magefile.go b/magefile.go
@@ -26,20 +26,26 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"io/ioutil"
 	"log"
 	"net/http"
 	"os"
 	"path/filepath"
+	"strings"
+	"text/template"
 
 	"github.com/magefile/mage/mg"
 	"github.com/magefile/mage/sh"
 )
 
 const (
-	linterInstallURL      = "https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh"
-	linterInstallFilename = "./build/intall-golang-ci.sh"
-	linterBinaryFilename  = "./build/golangci-lint"
-	linterVersion         = "v1.44.0"
+	linterInstallURL             = "https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh"
+	linterInstallFilename        = "./build/intall-golang-ci.sh"
+	linterBinaryFilename         = "./build/golangci-lint"
+	linterVersion                = "v1.44.0"
+	linterConfigFilename         = "./.golangci.yml"
+	linterConfigTemplateFilename = "./dev-tools/templates/.golangci.yml"
+	goVersionFilename            = "./.go-version"
 )
 
 // Aliases are shortcuts to long target names.
@@ -52,6 +58,57 @@ var Aliases = map[string]interface{}{
 // Linter contains targets related to linting the Go code
 type Linter mg.Namespace
 
+// UpdateGoVersion updates the linter configuration with the new version of Go.
+func (Linter) UpdateGoVersion() error {
+	goVersionBytes, err := ioutil.ReadFile(goVersionFilename)
+	if err != nil {
+		return fmt.Errorf("failed to read the %q file: %w", goVersionFilename, err)
+	}
+	goVersion := strings.TrimSpace(string(goVersionBytes))
+	log.Printf("The Go version is %s\n", goVersion)
+
+	templateContext := struct{ GoVersion string }{GoVersion: goVersion}
+	template, err := template.ParseFiles(linterConfigTemplateFilename)
+	if err != nil {
+		return fmt.Errorf("failed to read the template file %q: %w", linterConfigTemplateFilename, err)
+	}
+
+	configFile, err := os.OpenFile(linterConfigFilename, os.O_TRUNC|os.O_CREATE|os.O_WRONLY, 0700)
+	if err != nil {
+		return fmt.Errorf("failed to create/replace the linter config %q: %w", linterConfigFilename, err)
+	}
+	defer configFile.Close()
+
+	warning := fmt.Sprintf("# DO NOT EDIT!\n# This file is a rendered template, the source can be found in %q\n#\n", linterConfigTemplateFilename)
+	_, err = configFile.WriteString(warning)
+	if err != nil {
+		return fmt.Errorf("failed to write into the linter config %q: %w", linterConfigFilename, err)
+	}
+
+	err = template.Execute(configFile, templateContext)
+	if err != nil {
+		return fmt.Errorf("failed to execute the template %q: %w", linterConfigTemplateFilename, err)
+	}
+
+	err = assertUnchanged(linterConfigFilename)
+	if err != nil {
+		log.Printf("Successfully updated the linter configuration %q to Go version %s, please commit the changes now", linterConfigFilename, goVersion)
+	} else {
+		log.Printf("The linter configuration %q is up to date, no changes made", linterConfigFilename)
+	}
+
+	return nil
+}
+
+// CheckConfig makes sure that the `.golangci.yml` does not have uncommitted changes
+func (Linter) CheckConfig() error {
+	err := assertUnchanged(linterConfigFilename)
+	if err != nil {
+		return fmt.Errorf("linter configuration has uncommitted changes: %w", err)
+	}
+	return nil
+}
+
 // Install installs golangci-lint (https://golangci-lint.run) to `./build`
 // using the official installation script downloaded from GitHub.
 // If the linter binary already exists does nothing.
@@ -64,22 +121,22 @@ func (Linter) Install() error {
 
 	_, err = os.Stat(linterBinaryFilename)
 	if err == nil {
-		log.Println("the linter has been already installed, skipping...")
+		log.Println("The linter has been already installed, skipping...")
 		return nil
 	}
 	if !errors.Is(err, os.ErrNotExist) {
 		return fmt.Errorf("failed check if file %q exists: %w", linterBinaryFilename, err)
 	}
 
-	log.Println("preparing the installation script file...")
+	log.Println("Preparing the installation script file...")
 
 	installScript, err := os.OpenFile(linterInstallFilename, os.O_TRUNC|os.O_CREATE|os.O_WRONLY, 0700)
 	if err != nil {
 		return fmt.Errorf("failed to create file %q: %w", linterInstallFilename, err)
 	}
 	defer installScript.Close()
 
-	log.Println("downloading the linter installation script...")
+	log.Println("Downloading the linter installation script...")
 	// nolint: noctx // valid use since there is no context
 	resp, err := http.Get(linterInstallURL)
 	if err != nil {
@@ -110,14 +167,14 @@ func (Linter) Install() error {
 
 // All runs the linter against the entire codebase
 func (l Linter) All() error {
-	mg.Deps(l.Install)
+	mg.Deps(l.Install, l.CheckConfig)
 	return runLinter()
 }
 
 // LastChange runs the linter against all files changed since the fork point from `main`.
 // If the current branch is `main` then runs against the files changed in the last commit.
 func (l Linter) LastChange() error {
-	mg.Deps(l.Install)
+	mg.Deps(l.Install, l.CheckConfig)
 
 	branch, err := sh.Output("git", "branch", "--show-current")
 	if err != nil {
@@ -146,6 +203,13 @@ func Check() error {
 	return nil
 }
 
+// UpdateGoVersion makes required changes in order to switch to a new version of Go set in `./.go-version`.
+// nolint: deadcode,unparam // it's used as a `mage` target and requires returning an error
+func UpdateGoVersion() error {
+	mg.Deps(Linter.UpdateGoVersion)
+	return nil
+}
+
 // Deps contains targets related to checking dependencies
 type Deps mg.Namespace
 
@@ -182,14 +246,23 @@ func (Deps) CheckModuleTidy() error {
 	if err != nil {
 		return err
 	}
-	err = sh.Run("git", "diff", "--exit-code", "go.mod")
+	err = assertUnchanged("go.mod")
 	if err != nil {
 		return fmt.Errorf("`go mod tidy` was not called before the last commit: %w", err)
 	}
 
 	return nil
 }
 
+func assertUnchanged(path string) error {
+	err := sh.Run("git", "diff", "--exit-code", path)
+	if err != nil {
+		return fmt.Errorf("failed to assert the unchanged file %q: %w", path, err)
+	}
+
+	return nil
+}
+
 // runWithStdErr runs a command redirecting its stderr to the console instead of discarding it
 func runWithStdErr(command string, args ...string) error {
 	_, err := sh.Exec(nil, os.Stdout, os.Stderr, command, args...)
@@ -207,6 +280,7 @@ func runLinter(runFlags ...string) error {
 
 	args = append(args, "run")
 	args = append(args, runFlags...)
+	args = append(args, "-c", linterConfigFilename)
 	args = append(args, "./...")
 
 	return runWithStdErr(linterBinaryFilename, args...)
