enforce explanation for necessary nolints and fix bugs (#34883)

Follows up https://github.com/go-gitea/gitea/pull/34851

---------

Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>

modules/auth/password/hash/common.go

@@ -18,7 +18,7 @@ func parseIntParam(value, param, algorithmName, config string, previousErr error
 	return parsed, previousErr // <- Keep the previous error as this function should still return an error once everything has been checked if any call failed
 }
 
-func parseUIntParam(value, param, algorithmName, config string, previousErr error) (uint64, error) { //nolint:unparam
+func parseUIntParam(value, param, algorithmName, config string, previousErr error) (uint64, error) { //nolint:unparam // algorithmName is always argon2
 	parsed, err := strconv.ParseUint(value, 10, 64)
 	if err != nil {
 		log.Error("invalid integer for %s representation in %s hash spec %s", param, algorithmName, config)

modules/cache/cache_redis.go

@@ -11,7 +11,7 @@ import (
 	"code.gitea.io/gitea/modules/graceful"
 	"code.gitea.io/gitea/modules/nosql"
 
-	"gitea.com/go-chi/cache" //nolint:depguard
+	"gitea.com/go-chi/cache" //nolint:depguard // we wrap this package here
 	"github.com/redis/go-redis/v9"
 )
 

modules/cache/cache_twoqueue.go

@@ -10,7 +10,7 @@ import (
 
 	"code.gitea.io/gitea/modules/json"
 
-	mc "gitea.com/go-chi/cache" //nolint:depguard
+	mc "gitea.com/go-chi/cache" //nolint:depguard // we wrap this package here
 	lru "github.com/hashicorp/golang-lru/v2"
 )
 

modules/cache/string_cache.go

@@ -11,7 +11,7 @@ import (
 	"code.gitea.io/gitea/modules/setting"
 	"code.gitea.io/gitea/modules/util"
 
-	chi_cache "gitea.com/go-chi/cache" //nolint:depguard
+	chi_cache "gitea.com/go-chi/cache" //nolint:depguard // we wrap this package here
 )
 
 type GetJSONError struct {

modules/graceful/manager_windows.go

@@ -41,8 +41,7 @@ func (g *Manager) start() {
 	// Make SVC process
 	run := svc.Run
 
-	//lint:ignore SA1019 We use IsAnInteractiveSession because IsWindowsService has a different permissions profile
-	isAnInteractiveSession, err := svc.IsAnInteractiveSession() //nolint:staticcheck
+	isAnInteractiveSession, err := svc.IsAnInteractiveSession() //nolint:staticcheck // must use IsAnInteractiveSession because IsWindowsService has a different permissions profile
 	if err != nil {
 		log.Error("Unable to ascertain if running as an Windows Service: %v", err)
 		return

modules/json/json.go

@@ -3,11 +3,10 @@
 
 package json
 
-// Allow "encoding/json" import.
 import (
 	"bytes"
 	"encoding/binary"
-	"encoding/json" //nolint:depguard
+	"encoding/json" //nolint:depguard // this package wraps it
 	"io"
 
 	jsoniter "github.com/json-iterator/go"

modules/log/logger.go

@@ -45,6 +45,6 @@ type Logger interface {
 	LevelLogger
 }
 
-type LogStringer interface { //nolint:revive
+type LogStringer interface { //nolint:revive // export stutter
 	LogString() string
 }

modules/markup/markdown/transform_blockquote.go

@@ -46,7 +46,7 @@ func (g *ASTTransformer) extractBlockquoteAttentionEmphasis(firstParagraph ast.N
 	if !ok {
 		return "", nil
 	}
-	val1 := string(node1.Text(reader.Source())) //nolint:staticcheck
+	val1 := string(node1.Text(reader.Source())) //nolint:staticcheck // Text is deprecated
 	attentionType := strings.ToLower(val1)
 	if g.attentionTypes.Contains(attentionType) {
 		return attentionType, []ast.Node{node1}

modules/markup/markdown/transform_codespan.go

@@ -68,7 +68,7 @@ func cssColorHandler(value string) bool {
 }
 
 func (g *ASTTransformer) transformCodeSpan(_ *markup.RenderContext, v *ast.CodeSpan, reader text.Reader) {
-	colorContent := v.Text(reader.Source()) //nolint:staticcheck
+	colorContent := v.Text(reader.Source()) //nolint:staticcheck // Text is deprecated
 	if cssColorHandler(string(colorContent)) {
 		v.AppendChild(v, NewColorPreview(colorContent))
 	}

modules/markup/markdown/transform_heading.go

@@ -19,7 +19,7 @@ func (g *ASTTransformer) transformHeading(_ *markup.RenderContext, v *ast.Headin
 			v.SetAttribute(attr.Name, fmt.Appendf(nil, "%v", attr.Value))
 		}
 	}
-	txt := v.Text(reader.Source()) //nolint:staticcheck
+	txt := v.Text(reader.Source()) //nolint:staticcheck // Text is deprecated
 	header := Header{
 		Text:  util.UnsafeBytesToString(txt),
 		Level: v.Level,

modules/markup/mdstripper/mdstripper.go

@@ -46,7 +46,7 @@ func (r *stripRenderer) Render(w io.Writer, source []byte, doc ast.Node) error {
 				coalesce := prevSibIsText
 				r.processString(
 					w,
-					v.Text(source), //nolint:staticcheck
+					v.Text(source), //nolint:staticcheck // Text is deprecated
 					coalesce)
 				if v.SoftLineBreak() {
 					r.doubleSpace(w)

modules/optional/serialization_test.go

@@ -4,7 +4,7 @@
 package optional_test
 
 import (
-	std_json "encoding/json" //nolint:depguard
+	std_json "encoding/json" //nolint:depguard // for testing purpose
 	"testing"
 
 	"code.gitea.io/gitea/modules/json"

modules/setting/config_env.go

@@ -97,7 +97,7 @@ func decodeEnvSectionKey(encoded string) (ok bool, section, key string) {
 
 // decodeEnvironmentKey decode the environment key to section and key
 // The environment key is in the form of GITEA__SECTION__KEY or GITEA__SECTION__KEY__FILE
-func decodeEnvironmentKey(prefixGitea, suffixFile, envKey string) (ok bool, section, key string, useFileValue bool) { //nolint:unparam
+func decodeEnvironmentKey(prefixGitea, suffixFile, envKey string) (ok bool, section, key string, useFileValue bool) {
 	if !strings.HasPrefix(envKey, prefixGitea) {
 		return false, "", "", false
 	}

modules/setting/config_env_test.go

@@ -73,6 +73,9 @@ func TestDecodeEnvironmentKey(t *testing.T) {
 	assert.Equal(t, "sec", section)
 	assert.Equal(t, "KEY", key)
 	assert.True(t, file)
+
+	ok, _, _, _ = decodeEnvironmentKey("PREFIX__", "", "PREFIX__SEC__KEY")
+	assert.True(t, ok)
 }
 
 func TestEnvironmentToConfig(t *testing.T) {

modules/setting/config_provider.go

@@ -15,7 +15,7 @@ import (
 	"code.gitea.io/gitea/modules/log"
 	"code.gitea.io/gitea/modules/util"
 
-	"gopkg.in/ini.v1" //nolint:depguard
+	"gopkg.in/ini.v1" //nolint:depguard // wrapper for this package
 )
 
 type ConfigKey interface {

modules/setting/security.go

@@ -111,7 +111,7 @@ func loadSecurityFrom(rootCfg ConfigProvider) {
 	if SecretKey == "" {
 		// FIXME: https://github.com/go-gitea/gitea/issues/16832
 		// Until it supports rotating an existing secret key, we shouldn't move users off of the widely used default value
-		SecretKey = "!#@FDEWREWR&*(" //nolint:gosec
+		SecretKey = "!#@FDEWREWR&*("
 	}
 
 	CookieRememberName = sec.Key("COOKIE_REMEMBER_NAME").MustString("gitea_incredible")

modules/setting/storage.go

@@ -158,7 +158,7 @@ const (
 	targetSecIsSec                                  // target section is from the name seciont [name]
 )
 
-func getStorageSectionByType(rootCfg ConfigProvider, typ string) (ConfigSection, targetSecType, error) { //nolint:unparam
+func getStorageSectionByType(rootCfg ConfigProvider, typ string) (ConfigSection, targetSecType, error) { //nolint:unparam // FIXME: targetSecType is always 0, wrong design?
 	targetSec, err := rootCfg.GetSection(storageSectionName + "." + typ)
 	if err != nil {
 		if !IsValidStorageType(StorageType(typ)) {
@@ -283,7 +283,7 @@ func getStorageForLocal(targetSec, overrideSec ConfigSection, tp targetSecType,
 	return &storage, nil
 }
 
-func getStorageForMinio(targetSec, overrideSec ConfigSection, tp targetSecType, name string) (*Storage, error) { //nolint:dupl
+func getStorageForMinio(targetSec, overrideSec ConfigSection, tp targetSecType, name string) (*Storage, error) { //nolint:dupl // duplicates azure setup
 	var storage Storage
 	storage.Type = StorageType(targetSec.Key("STORAGE_TYPE").String())
 	if err := targetSec.MapTo(&storage.MinioConfig); err != nil {
@@ -312,7 +312,7 @@ func getStorageForMinio(targetSec, overrideSec ConfigSection, tp targetSecType,
 	return &storage, nil
 }
 
-func getStorageForAzureBlob(targetSec, overrideSec ConfigSection, tp targetSecType, name string) (*Storage, error) { //nolint:dupl
+func getStorageForAzureBlob(targetSec, overrideSec ConfigSection, tp targetSecType, name string) (*Storage, error) { //nolint:dupl // duplicates minio setup
 	var storage Storage
 	storage.Type = StorageType(targetSec.Key("STORAGE_TYPE").String())
 	if err := targetSec.MapTo(&storage.AzureBlobConfig); err != nil {

modules/templates/htmlrenderer.go

@@ -42,7 +42,7 @@ var (
 
 var ErrTemplateNotInitialized = errors.New("template system is not initialized, check your log for errors")
 
-func (h *HTMLRender) HTML(w io.Writer, status int, tplName TplName, data any, ctx context.Context) error { //nolint:revive
+func (h *HTMLRender) HTML(w io.Writer, status int, tplName TplName, data any, ctx context.Context) error { //nolint:revive // we don't use ctx, only pass it to the template executor
 	name := string(tplName)
 	if respWriter, ok := w.(http.ResponseWriter); ok {
 		if respWriter.Header().Get("Content-Type") == "" {
@@ -57,7 +57,7 @@ func (h *HTMLRender) HTML(w io.Writer, status int, tplName TplName, data any, ct
 	return t.Execute(w, data)
 }
 
-func (h *HTMLRender) TemplateLookup(name string, ctx context.Context) (TemplateExecutor, error) { //nolint:revive
+func (h *HTMLRender) TemplateLookup(name string, ctx context.Context) (TemplateExecutor, error) { //nolint:revive // we don't use ctx, only pass it to the template executor
 	tmpls := h.templates.Load()
 	if tmpls == nil {
 		return nil, ErrTemplateNotInitialized

modules/templates/scopedtmpl/scopedtmpl.go

@@ -102,31 +102,28 @@ func escapeTemplate(t *template.Template) error {
 	return nil
 }
 
-//nolint:unused
 type htmlTemplate struct {
-	escapeErr error
-	text      *texttemplate.Template
+	_/*escapeErr*/ error
+	text *texttemplate.Template
 }
 
-//nolint:unused
 type textTemplateCommon struct {
-	tmpl   map[string]*template.Template // Map from name to defined templates.
-	muTmpl sync.RWMutex                  // protects tmpl
-	option struct {
+	_/*tmpl*/ map[string]*template.Template
+	_/*muTmpl*/ sync.RWMutex
+	_/*option*/ struct {
 		missingKey int
 	}
-	muFuncs    sync.RWMutex // protects parseFuncs and execFuncs
-	parseFuncs texttemplate.FuncMap
-	execFuncs  map[string]reflect.Value
+	muFuncs sync.RWMutex
+	_/*parseFuncs*/ texttemplate.FuncMap
+	execFuncs map[string]reflect.Value
 }
 
-//nolint:unused
 type textTemplate struct {
-	name string
+	_/*name*/ string
 	*parse.Tree
 	*textTemplateCommon
-	leftDelim  string
-	rightDelim string
+	_/*leftDelim*/ string
+	_/*rightDelim*/ string
 }
 
 func ptr[T, P any](ptr *P) *T {