feat: implement -msg-style (#76)

Co-authored-by: ccoVeille <[email protected]>
Co-authored-by: Nik <[email protected]>

Author: 3 people

README.md

@@ -19,9 +19,10 @@ With `sloglint` you can enforce various rules for `log/slog` based on your prefe
 * Enforce using either key-value pairs only or attributes only (optional)
 * Enforce not using global loggers (optional)
 * Enforce using methods that accept a context (optional)
-* Enforce using static log messages (optional)
+* Enforce using static messages (optional)
+* Enforce message style (optional)
 * Enforce using constants instead of raw keys (optional)
-* Enforce a single key naming convention (optional)
+* Enforce key naming convention (optional)
 * Enforce not using specific keys (optional)
 * Enforce putting arguments on separate lines (optional)
 
@@ -110,6 +111,24 @@ The report can be fixed by moving dynamic values to arguments:
 slog.Info("a user has logged in", "user_id", 42)
 ```
 
+### Message style
+
+The `msg-style` option causes `sloglint` to check log messages for a particular style.
+
+Possible values are `lowercased` (report messages that begin with an uppercase letter)...
+
+```go
+slog.Info("Msg") // sloglint: message should be lowercased
+```
+
+...and `capitalized` (report messages that begin with a lowercase letter):
+
+```go
+slog.Info("msg") // sloglint: message should be capitalized
+```
+
+Special cases such as acronyms (e.g. `HTTP`, `U.S.`) are ignored.
+
 ### No raw keys
 
 To prevent typos, you may want to forbid the use of raw keys altogether.

sloglint.go

@@ -11,6 +11,7 @@ import (
 	"slices"
 	"strconv"
 	"strings"
+	"unicode"
 
 	"github.com/ettle/strcase"
 	"golang.org/x/tools/go/analysis"
@@ -26,9 +27,10 @@ type Options struct {
 	AttrOnly       bool     // Enforce using attributes only (overrides NoMixedArgs, incompatible with KVOnly).
 	NoGlobal       string   // Enforce not using global loggers ("all" or "default").
 	ContextOnly    string   // Enforce using methods that accept a context ("all" or "scope").
-	StaticMsg      bool     // Enforce using static log messages.
+	StaticMsg      bool     // Enforce using static messages.
+	MsgStyle       string   // Enforce message style ("lowercased" or "capitalized").
 	NoRawKeys      bool     // Enforce using constants instead of raw keys.
-	KeyNamingCase  string   // Enforce a single key naming convention ("snake", "kebab", "camel", or "pascal").
+	KeyNamingCase  string   // Enforce key naming convention ("snake", "kebab", "camel", or "pascal").
 	ForbiddenKeys  []string // Enforce not using specific keys.
 	ArgsOnSepLines bool     // Enforce putting arguments on separate lines.
 }
@@ -61,6 +63,12 @@ func New(opts *Options) *analysis.Analyzer {
 				return nil, fmt.Errorf("sloglint: Options.ContextOnly=%s: %w", opts.ContextOnly, errInvalidValue)
 			}
 
+			switch opts.MsgStyle {
+			case "", styleLowercased, styleCapitalized:
+			default:
+				return nil, fmt.Errorf("sloglint: Options.MsgStyle=%s: %w", opts.MsgStyle, errInvalidValue)
+			}
+
 			switch opts.KeyNamingCase {
 			case "", snakeCase, kebabCase, camelCase, pascalCase:
 			default:
@@ -101,9 +109,10 @@ func flags(opts *Options) flag.FlagSet {
 	boolVar(&opts.AttrOnly, "attr-only", "enforce using attributes only (overrides -no-mixed-args, incompatible with -kv-only)")
 	strVar(&opts.NoGlobal, "no-global", "enforce not using global loggers (all|default)")
 	strVar(&opts.ContextOnly, "context-only", "enforce using methods that accept a context (all|scope)")
-	boolVar(&opts.StaticMsg, "static-msg", "enforce using static log messages")
+	boolVar(&opts.StaticMsg, "static-msg", "enforce using static messages")
+	strVar(&opts.MsgStyle, "msg-style", "enforce message style (lowercased|capitalized)")
 	boolVar(&opts.NoRawKeys, "no-raw-keys", "enforce using constants instead of raw keys")
-	strVar(&opts.KeyNamingCase, "key-naming-case", "enforce a single key naming convention (snake|kebab|camel|pascal)")
+	strVar(&opts.KeyNamingCase, "key-naming-case", "enforce key naming convention (snake|kebab|camel|pascal)")
 	boolVar(&opts.ArgsOnSepLines, "args-on-sep-lines", "enforce putting arguments on separate lines")
 
 	fset.Func("forbidden-keys", "enforce not using specific keys (comma-separated)", func(s string) error {
@@ -155,6 +164,13 @@ var attrFuncs = map[string]struct{}{
 	"log/slog.Any":      {},
 }
 
+// message styles.
+const (
+	styleLowercased  = "lowercased"
+	styleCapitalized = "capitalized"
+)
+
+// key naming conventions.
 const (
 	snakeCase  = "snake"
 	kebabCase  = "kebab"
@@ -228,6 +244,15 @@ func visit(pass *analysis.Pass, opts *Options, node ast.Node, stack []ast.Node)
 		pass.Reportf(call.Pos(), "message should be a string literal or a constant")
 	}
 
+	if opts.MsgStyle != "" && msgPos >= 0 {
+		if msg, ok := call.Args[msgPos].(*ast.BasicLit); ok && msg.Kind == token.STRING {
+			msg.Value = msg.Value[1 : len(msg.Value)-1] // trim quotes/backticks.
+			if ok := isValidMsgStyle(msg.Value, opts.MsgStyle); !ok {
+				pass.Reportf(call.Pos(), "message should be %s", opts.MsgStyle)
+			}
+		}
+	}
+
 	// NOTE: we assume that the arguments have already been validated by govet.
 	args := call.Args[funcInfo.argsPos:]
 	if len(args) == 0 {
@@ -356,6 +381,33 @@ func isStaticMsg(msg ast.Expr) bool {
 	}
 }
 
+func isValidMsgStyle(msg, style string) bool {
+	runes := []rune(msg)
+	if len(runes) < 2 {
+		return true
+	}
+
+	first, second := runes[0], runes[1]
+
+	switch style {
+	case styleLowercased:
+		if unicode.IsLower(first) {
+			return true
+		}
+		if unicode.IsPunct(second) {
+			return true // e.g. "U.S.A."
+		}
+		return unicode.IsUpper(second) // e.g. "HTTP"
+	case styleCapitalized:
+		if unicode.IsUpper(first) {
+			return true
+		}
+		return unicode.IsUpper(second) // e.g. "iPhone"
+	default:
+		panic("unreachable")
+	}
+}
+
 func forEachKey(info *types.Info, keys, attrs []ast.Expr, fn func(key ast.Expr)) {
 	for _, key := range keys {
 		fn(key)

sloglint_internal_test.go

@@ -22,6 +22,10 @@ func TestOptions(t *testing.T) {
 			opts: Options{ContextOnly: "-"},
 			err:  errInvalidValue,
 		},
+		"MsgStyle: invalid value": {
+			opts: Options{MsgStyle: "-"},
+			err:  errInvalidValue,
+		},
 		"KeyNamingCase: invalid value": {
 			opts: Options{KeyNamingCase: "-"},
 			err:  errInvalidValue,

sloglint_test.go

@@ -69,4 +69,14 @@ func TestAnalyzer(t *testing.T) {
 		analyzer := sloglint.New(&sloglint.Options{ForbiddenKeys: []string{"foo_bar"}})
 		analysistest.Run(t, testdata, analyzer, "forbidden_keys")
 	})
+
+	t.Run("message style (lowercased)", func(t *testing.T) {
+		analyzer := sloglint.New(&sloglint.Options{MsgStyle: "lowercased"})
+		analysistest.Run(t, testdata, analyzer, "msg_style_lowercased")
+	})
+
+	t.Run("message style (capitalized)", func(t *testing.T) {
+		analyzer := sloglint.New(&sloglint.Options{MsgStyle: "capitalized"})
+		analysistest.Run(t, testdata, analyzer, "msg_style_capitalized")
+	})
 }

testdata/src/msg_style_capitalized/msg_style_capitalized.go

@@ -0,0 +1,26 @@
+package msg_style_capitalized
+
+import (
+	"context"
+	"log/slog"
+)
+
+func tests() {
+	ctx := context.Background()
+
+	slog.Info("")
+	slog.Info("Msg")
+	slog.InfoContext(ctx, "Msg")
+	slog.Log(ctx, slog.LevelInfo, "Msg")
+	slog.With("key", "value").Info("Msg")
+
+	slog.Info("msg")                      // want `message should be capitalized`
+	slog.InfoContext(ctx, "msg")          // want `message should be capitalized`
+	slog.Log(ctx, slog.LevelInfo, "msg")  // want `message should be capitalized`
+	slog.With("key", "value").Info("msg") // want `message should be capitalized`
+
+	// special cases:
+	slog.Info("U.S. dollar")
+	slog.Info("HTTP request")
+	slog.Info("iPhone 18")
+}

testdata/src/msg_style_lowercased/msg_style_lowercased.go

@@ -0,0 +1,26 @@
+package msg_style_lowercased
+
+import (
+	"context"
+	"log/slog"
+)
+
+func tests() {
+	ctx := context.Background()
+
+	slog.Info("")
+	slog.Info("msg")
+	slog.InfoContext(ctx, "msg")
+	slog.Log(ctx, slog.LevelInfo, "msg")
+	slog.With("key", "value").Info("msg")
+
+	slog.Info("Msg")                      // want `message should be lowercased`
+	slog.InfoContext(ctx, "Msg")          // want `message should be lowercased`
+	slog.Log(ctx, slog.LevelInfo, "Msg")  // want `message should be lowercased`
+	slog.With("key", "value").Info("Msg") // want `message should be lowercased`
+
+	// special cases:
+	slog.Info("U.S. dollar")
+	slog.Info("HTTP request")
+	slog.Info("iPhone 18")
+}

testdata/src/static_msg/static_msg.go

@@ -16,18 +16,20 @@ func tests() {
 	slog.Info("msg")
 	slog.InfoContext(ctx, "msg")
 	slog.Log(ctx, slog.LevelInfo, "msg")
+	slog.With("key", "value").Info("msg")
 
 	slog.Info(constMsg)
 	slog.InfoContext(ctx, constMsg)
 	slog.Log(ctx, slog.LevelInfo, constMsg)
-	slog.With("key", "value").Info("msg")
+	slog.With("key", "value").Info(constMsg)
 
 	slog.Info(fmt.Sprintf("msg"))                      // want `message should be a string literal or a constant`
 	slog.InfoContext(ctx, fmt.Sprintf("msg"))          // want `message should be a string literal or a constant`
 	slog.Log(ctx, slog.LevelInfo, fmt.Sprintf("msg"))  // want `message should be a string literal or a constant`
 	slog.With("key", "value").Info(fmt.Sprintf("msg")) // want `message should be a string literal or a constant`
 
-	slog.Info(varMsg)                     // want `message should be a string literal or a constant`
-	slog.InfoContext(ctx, varMsg)         // want `message should be a string literal or a constant`
-	slog.Log(ctx, slog.LevelInfo, varMsg) // want `message should be a string literal or a constant`
+	slog.Info(varMsg)                      // want `message should be a string literal or a constant`
+	slog.InfoContext(ctx, varMsg)          // want `message should be a string literal or a constant`
+	slog.Log(ctx, slog.LevelInfo, varMsg)  // want `message should be a string literal or a constant`
+	slog.With("key", "value").Info(varMsg) // want `message should be a string literal or a constant`
 }