docs(security): Improve nolint explanations

Author: YaCodesDevelopment

.golangci.yml

@@ -73,7 +73,7 @@ linters:
     forbidigo:
       forbid:
         - pattern: "^panic\\("
-          msg: "us panic() with caution, leave a comment explaining why it's necessary"
+          msg: "use panic() with caution, leave a comment explaining why it's necessary"
         - pattern: "unsafe\\."
           msg: "use unsafe with caution, leave a comment explaining why it's necessary"
 

yaautoflags/yaautoflags.go

@@ -74,7 +74,7 @@ func PackFlags[T any](instance *T) yaerrors.Error {
 				flagsField.Type().Size() * bitsInByte,
 			)
 
-			//nolint: exhaustive
+			//nolint:exhaustive // The flags field must be of an unsigned integer type, so only those types are handled
 			switch flagsField.Kind() {
 			case reflect.Uint64,
 				reflect.Uint32,
@@ -165,7 +165,7 @@ func UnpackFlags[T any](instance *T) yaerrors.Error {
 		)
 	}
 
-	//nolint: exhaustive
+	//nolint:exhaustive // The flags field must be of an unsigned integer type, so only those types are handled
 	switch flagsField.Kind() {
 	case reflect.Uint64,
 		reflect.Uint32,

yaerrors/yaerrors.go

@@ -66,8 +66,10 @@ func FromErrorWithLog(code int, cause error, wrap string, log yalogger.Logger) E
 // It creates a new Error instance with the provided code and message.
 func FromString(code int, msg string) Error {
 	return &yaError{
-		code:      code,
-		cause:     errors.New(msg), //nolint:err113
+		code: code,
+		cause: errors.New( //nolint:err113 // This is error constructor, error is not from library, no constants here
+			msg,
+		),
 		traceback: msg,
 	}
 }
@@ -79,8 +81,10 @@ func FromStringWithLog(code int, msg string, log yalogger.Logger) Error {
 	log.Error(msg)
 
 	return &yaError{
-		code:      code,
-		cause:     errors.New(msg), //nolint:err113
+		code: code,
+		cause: errors.New( //nolint:err113 // This is error constructor, error is not from library, no constants here
+			msg,
+		),
 		traceback: msg,
 	}
 }

yafsm/entityfsm.go

@@ -54,7 +54,7 @@ func (b *EntityFSMStorage) SetState(
 //	}
 func (b *EntityFSMStorage) GetState(
 	ctx context.Context,
-) (string, stateDataMarshalled, yaerrors.Error) { //nolint: revive
+) (string, stateDataMarshalled, yaerrors.Error) { //nolint:revive,lll // Unexported type used for safe encapsulation of marshalled state data
 	return b.storage.GetState(ctx, b.uid)
 }
 

yafsm/fsm.go

@@ -118,7 +118,7 @@ func (b *DefaultFSMStorage[T]) SetState(
 func (b *DefaultFSMStorage[T]) GetState(
 	ctx context.Context,
 	uid string,
-) (string, stateDataMarshalled, yaerrors.Error) { //nolint: revive
+) (string, stateDataMarshalled, yaerrors.Error) { //nolint:revive,lll // Unexported type used for safe encapsulation of marshalled state data
 	data, err := b.storage.Get(ctx, uid)
 	if err != nil {
 		return b.defaultState.StateName(), "", nil

yahash/yahash.go

@@ -80,7 +80,7 @@ type HashableType valueparser.ParsableType
 // used with `Hash`.
 //
 //   - *I* – the input type (usually `string`).
-//   - *O* – the output type **must** be `comparable` so that we can check equality
+//   - *O* – the output type **must** be `comparable` so that equality can be checked
 //     when validating.
 //
 // A hash function receives the main *data* plus zero or more *args* that are
@@ -264,7 +264,7 @@ func FNVStringToInt64(data string, args ...string) int64 {
 		hasher.Write([]byte(arg))
 	}
 
-	return int64( //nolint:gosec // We don't care about overflow here, as the result will remain deterministic
+	return int64( //nolint:gosec // It doesn't matter if it overflows here, as the result will remain deterministic
 		hasher.Sum64(),
 	)
 }
@@ -288,7 +288,7 @@ func FNVStringToInt32(data string, args ...string) int32 {
 		hasher.Write([]byte(arg))
 	}
 
-	return int32( //nolint:gosec // We don't care about overflow here, as the result will remain deterministic
+	return int32( //nolint:gosec // It doesn't matter if it overflows here, as the result will remain deterministic
 		hasher.Sum32(),
 	)
 }

yalocales/locales_test.go

@@ -121,7 +121,7 @@ func TestFormattedValueWithMap(t *testing.T) {
 		t.Fatalf("format value: %v", yaErr)
 	}
 
-	//nolint: goconst
+	//nolint:goconst // Who cares about consts in tests?
 	want := "This is a Formatable Locale Replacement"
 	if got != want {
 		t.Fatalf("unexpected formatted value: got %q want %q", got, want)

yalogger/logrus_logger.go

@@ -327,7 +327,7 @@ func (l *logrusAdapter) WithRequestID(id uint64) Logger {
 //	logger.WithRandomRequestID().Info("Generated random request ID")
 func (l *logrusAdapter) WithRandomRequestID() Logger {
 	return &logrusAdapter{
-		//nolint:gosec // We don't care about randomness quality here, as this is just for logging
+		//nolint:gosec // Randomness quality here could be neglected, as this is just for logging
 		entry: l.entry.WithField(KeyRequestID, rand.Uint64()),
 	}
 }

yarsa/key.go

@@ -10,8 +10,8 @@
 //     p and q to the top quarter of their ranges so the final modulus has the
 //     requested bit-length.
 //     - The stdlib rsa.GenerateKey is NOT guaranteed deterministic even with a
-//     deterministic io.Reader (due to internal jitter), so we implement our
-//     own prime generation.
+//     deterministic io.Reader (due to internal jitter), so custom prime generation
+//     is implemented here.
 //
 //  2. Private key parsing convenience:
 //     ParsePrivateKey(string) -> *rsa.PrivateKey
@@ -349,7 +349,7 @@ func StripCRLF(s string) string {
 
 // tryBase64URLAll attempts to decode s as URL-safe base64 in both variants:
 //   - RawURLEncoding (no '=' padding expected)
-//   - URLEncoding (padding expected; we add best-effort padding if missing)
+//   - URLEncoding (padding expected; add best-effort padding if missing)
 //
 // It returns decoded bytes or an error if neither variant works.
 func tryBase64URLAll(s string) ([]byte, yaerrors.Error) {

yatgbot/dispatcher.go

@@ -145,7 +145,7 @@ func (r *Dispatcher) checkFilters(
 		chain = append(chain, g)
 	}
 
-	// 2) Reverse so we run filters from root -> current.
+	// 2) Reverse so filters run from root -> current.
 	for i, j := 0, len(chain)-1; i < j; i, j = i+1, j-1 {
 		chain[i], chain[j] = chain[j], chain[i]
 	}