@aarock1234/slopscan 0.1.0

package/rules/go/idiom/errors/error-is-last-return-value.md

@@ -0,0 +1,53 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: parameter_declaration
+        all:
+            - has:
+                  field: type
+                  regex: '^error$'
+            - inside:
+                  kind: parameter_list
+                  inside:
+                      any:
+                          - kind: function_declaration
+                          - kind: method_declaration
+                          - kind: func_literal
+                      field: result
+            - precedes:
+                  kind: parameter_declaration
+                  stopBy: end
+---
+
+## Why
+
+Every Go API returns the error last, so `value, err := f()` is muscle memory for the reader. An error in any other position forces callers to look up the signature, and the mismatch shows up as swapped variables at the call site.
+
+## Message
+
+error is the last return value
+
+## Bad
+
+```go
+// BAD: error before the value
+func load(path string) (error, []byte) {
+	return nil, nil
+}
+```
+
+## Good
+
+```go
+func load(path string) ([]byte, error) {
+	return nil, nil
+}
+```
+
+```go
+func load(path string) (data []byte, err error) {
+	return nil, nil
+}
+```

package/rules/go/idiom/errors/no-log-and-return.md

@@ -0,0 +1,45 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - a handler that logs and then writes a sanitized response instead of returning the error
+    - a log line that adds details the caller cannot reconstruct (a debug dump of the request)
+    - the error is returned from a top-level run function where nothing above will log it
+---
+
+## Why
+
+An error is either handled or propagated, never both. Logging it and then returning it means every layer up the stack logs the same failure again, and the operator reads three stack-less copies of one event. Wrap it with context and return it; the layer that finally handles it logs once.
+
+## Message
+
+error is logged and returned; handle it or propagate it, not both
+
+## Bad
+
+```go
+func (s *Service) Get(ctx context.Context, id string) (*Item, error) {
+	item, err := s.repo.Get(ctx, id)
+	if err != nil {
+		// BAD: the caller will log this again
+		s.logger.Error("failed to get item", "error", err)
+
+		return nil, fmt.Errorf("get item %s: %w", id, err)
+	}
+
+	return item, nil
+}
+```
+
+## Good
+
+```go
+func (s *Service) Get(ctx context.Context, id string) (*Item, error) {
+	item, err := s.repo.Get(ctx, id)
+	if err != nil {
+		return nil, fmt.Errorf("get item %s: %w", id, err)
+	}
+
+	return item, nil
+}
+```

package/rules/go/idiom/formatting/blank-line-before-return.md

@@ -0,0 +1,48 @@
+---
+severity: info
+detect: judge
+falsePositives:
+    - a block whose only statement is the return
+    - a return that directly follows the opening brace of an if, else, or case body
+    - a one-line function body
+---
+
+## Why
+
+A blank line before `return` separates the work of a function from its result, so the eye lands on the exit without reading through the last loop or condition. When the return is glued to the statement above it, the two read as one unit and the function's shape is harder to scan.
+
+## Message
+
+return has a blank line before it unless it is the only statement in the block
+
+## Bad
+
+```go
+func total(items []Item) int {
+	sum := 0
+	for _, item := range items {
+		sum += item.Value
+	}
+	// BAD: return glued to the loop above it
+	return sum
+}
+```
+
+## Good
+
+```go
+func total(items []Item) int {
+	sum := 0
+	for _, item := range items {
+		sum += item.Value
+	}
+
+	return sum
+}
+```
+
+```go
+func name(item Item) string {
+	return item.Name
+}
+```

package/rules/go/idiom/formatting/multiline-struct-literals.md

@@ -0,0 +1,56 @@
+---
+severity: info
+detect: ast
+ast:
+    rule:
+        kind: composite_literal
+        regex: '^[^\n]*$'
+        all:
+            - has:
+                  field: type
+                  any:
+                      - kind: type_identifier
+                      - kind: qualified_type
+                      - kind: generic_type
+            - has:
+                  field: body
+                  has:
+                      kind: keyed_element
+                      precedes:
+                          kind: keyed_element
+                          stopBy: end
+---
+
+## Why
+
+A struct literal with two or more fields goes one field per line, so gofmt aligns the values and a later field is a one-line diff instead of a rewrite of the whole literal. A single field can stay inline.
+
+## Message
+
+struct literal with several fields goes one field per line
+
+## Bad
+
+```go
+func build() Item {
+	// BAD: several fields crammed on one line
+	return Item{ID: "abc", Name: "example"}
+}
+```
+
+## Good
+
+```go
+func build() Item {
+	return Item{
+		ID:   "abc",
+		Name: "example",
+	}
+}
+```
+
+```go
+func build() Item {
+	return Item{ID: "abc"}
+}
+```

package/rules/go/idiom/imports/import-order-groups.md

@@ -0,0 +1,42 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - a file with a single import or a single group
+    - generated code
+    - an import block the diff did not touch
+---
+
+## Why
+
+Imports read as four groups separated by blank lines: standard library, external modules, this module's own packages, and side-effect imports. gofmt only sorts within a group, so an import dropped into the wrong group stays there and the reader has to scan every line to learn what the file depends on. Keep the groups in that order with one blank line between each.
+
+## Message
+
+imports are grouped stdlib, external, internal, side-effect with a blank line between groups
+
+## Bad
+
+```go
+import (
+	"context"
+	// BAD: external module mixed into the stdlib group
+	"github.com/google/uuid"
+	"fmt"
+
+	"project/pkg/client"
+)
+```
+
+## Good
+
+```go
+import (
+	"context"
+	"fmt"
+
+	"github.com/google/uuid"
+
+	"project/pkg/client"
+)
+```

package/rules/go/idiom/imports/side-effect-imports-own-group.md

@@ -0,0 +1,51 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: import_declaration
+        regex: '\n[ \t]*([^_\s][^\n]*)?"[^"\n]*"[ \t]*(//[^\n]*)?\n[ \t]*_[ \t]+"'
+---
+
+## Why
+
+A side-effect import (`_ "project/pkg/log"`) registers something at init time and is easy to miss when it sits inside the internal group, where gofmt sorts it by path. Give side-effect imports their own group after the internal one so the reader sees at a glance which imports exist only for their init.
+
+## Message
+
+side-effect imports go in their own group after the internal imports
+
+## Bad
+
+```go
+import (
+	"context"
+	"fmt"
+
+	"project/pkg/client"
+	// BAD: side-effect import glued to the internal group
+	_ "project/pkg/log"
+)
+```
+
+## Good
+
+```go
+import (
+	"context"
+	"fmt"
+
+	"project/pkg/client"
+
+	_ "project/pkg/log"
+)
+```
+
+```go
+import (
+	"embed"
+
+	_ "project/pkg/log"
+	_ "project/pkg/metrics"
+)
+```

package/rules/go/idiom/interfaces/accept-interfaces-return-concrete.md

@@ -0,0 +1,39 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - a factory that picks among several implementations at runtime
+    - returning error or a standard interface such as io.Reader where the concrete type is an implementation detail
+    - a parameter that needs unexported fields of the concrete type
+---
+
+## Why
+
+A function that accepts an interface can be called with any implementation and any test double, while a function that returns its concrete type lets the caller use every method and field and decide for itself which interface to view it through. Returning an interface from a constructor hides the type for no gain and forces an assertion on anyone who needs more than the interface offers.
+
+## Message
+
+accept interfaces and return concrete types
+
+## Bad
+
+```go
+// BAD: constructor hides the concrete type behind an interface
+func New(db *sql.DB) Repository {
+	return &PgRepo{db: db}
+}
+```
+
+## Good
+
+```go
+func New(db *sql.DB) *PgRepo {
+	return &PgRepo{db: db}
+}
+```
+
+```go
+func NewService(repo Repository) *Service {
+	return &Service{repo: repo}
+}
+```

package/rules/go/idiom/iterators/prefer-iter-seq.md

@@ -0,0 +1,47 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - a channel that moves work between goroutines rather than iterating a collection
+    - an API that must stay compatible with Go older than 1.23
+    - a callback that needs to return an error per element (iter.Seq2 with an error value)
+---
+
+## Why
+
+A generator built on a channel and a goroutine leaks the goroutine when the caller stops early, costs a context switch per element, and forces the caller into a manual `for range ch` with no way to break cleanly. `iter.Seq[T]` expresses the same sequence as a plain function, works with `for range`, and stops when the loop body does.
+
+## Message
+
+channel or callback generator; return an iter.Seq so callers can range and break
+
+## Bad
+
+```go
+// BAD: leaks the goroutine when the caller stops early
+func (s *Store) Items() <-chan Item {
+	ch := make(chan Item)
+	go func() {
+		defer close(ch)
+		for _, item := range s.items {
+			ch <- item
+		}
+	}()
+
+	return ch
+}
+```
+
+## Good
+
+```go
+func (s *Store) Items() iter.Seq[Item] {
+	return func(yield func(Item) bool) {
+		for _, item := range s.items {
+			if !yield(item) {
+				return
+			}
+		}
+	}
+}
+```

package/rules/go/idiom/logging/lowercase-log-messages.md

@@ -0,0 +1,80 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: call_expression
+        any:
+            - all:
+                  - has:
+                        field: function
+                        regex: '\.(Debug|Info|Warn|Error)$'
+                  - has:
+                        field: arguments
+                        has:
+                            kind: interpreted_string_literal
+                            nthChild: 1
+                            regex: '^"[A-Z][a-z]'
+            - all:
+                  - has:
+                        field: function
+                        regex: '\.(Debug|Info|Warn|Error)Context$'
+                  - has:
+                        field: arguments
+                        has:
+                            kind: interpreted_string_literal
+                            nthChild: 2
+                            regex: '^"[A-Z][a-z]'
+ignore:
+    - '**/*_test.go'
+---
+
+## Why
+
+Log messages are lowercase fragments, like error strings, so they read uniformly in a stream and can be grepped without guessing the case. A message that starts with a proper noun such as PostgreSQL will be flagged too; keep the noun and accept the finding, or lead with a lowercase word.
+
+## Message
+
+log messages are lowercase fragments
+
+## Bad
+
+```go
+func (s *Server) Start(port int) {
+	// BAD: capitalized log message
+	slog.Info("Starting server", "port", port)
+}
+```
+
+```go
+func (s *Service) Save(ctx context.Context, item Item) error {
+	if err := s.repo.Save(ctx, item); err != nil {
+		// BAD: capitalized log message
+		s.logger.ErrorContext(ctx, "Failed to save item", "error", err)
+
+		return err
+	}
+
+	return nil
+}
+```
+
+## Good
+
+```go
+func (s *Server) Start(port int) {
+	slog.Info("starting server", "port", port)
+}
+```
+
+```go
+func (s *Service) Save(ctx context.Context, item Item) error {
+	if err := s.repo.Save(ctx, item); err != nil {
+		s.logger.ErrorContext(ctx, "saving item", "error", err)
+
+		return err
+	}
+
+	return nil
+}
+```

package/rules/go/idiom/logging/use-slog.md

@@ -0,0 +1,46 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: call_expression
+        has:
+            field: function
+            regex: '^(log|fmt)\.Print(f|ln)?$'
+ignore:
+    - '**/main.go'
+    - '**/cmd/**'
+    - '**/*_test.go'
+---
+
+## Why
+
+`log.Printf` and `fmt.Println` produce unstructured text with no level and no fields, so nothing downstream can filter by severity or query by key. `log/slog` gives a level, a message, and typed attributes for the same line of code. Command entry points that print output for a user are exempt.
+
+## Message
+
+unstructured log call; use log/slog with a level and key-value attributes
+
+## Bad
+
+```go
+func (s *Service) Process(id string) {
+	// BAD: no level, no fields
+	log.Printf("processing item %s", id)
+}
+```
+
+```go
+func (s *Service) Process(id string) {
+	// BAD: output that is really a log line
+	fmt.Println("processing", id)
+}
+```
+
+## Good
+
+```go
+func (s *Service) Process(id string) {
+	slog.Info("processing item", "id", id)
+}
+```

package/rules/go/idiom/naming/acronyms-consistent-case.md

@@ -0,0 +1,97 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        any:
+            - kind: identifier
+              any:
+                  - inside:
+                        kind: var_spec
+                  - inside:
+                        kind: const_spec
+                  - inside:
+                        kind: parameter_declaration
+                  - inside:
+                        kind: function_declaration
+                        field: name
+                  - inside:
+                        kind: expression_list
+                        inside:
+                            kind: short_var_declaration
+                            field: left
+            - kind: field_identifier
+              any:
+                  - inside:
+                        kind: field_declaration
+                  - inside:
+                        kind: method_declaration
+                        field: name
+                  - inside:
+                        kind: method_elem
+            - kind: type_identifier
+              inside:
+                  kind: type_spec
+                  field: name
+        regex: '(Id|Http|Https|Url|Uri|Json|Api|Sql|Uuid|Xml|Html|Grpc|Tls|Tcp|Udp|Ip|Db|Cpu|Ttl)([A-Z]|$)'
+---
+
+## Why
+
+Go keeps acronyms in one case: `userID`, `HTTPClient`, `parseURL`. Mixed-case forms like `userId` and `HttpClient` are the naming of other languages and stand out immediately in a Go codebase, and a mix of both spellings means the reader has to guess which one a given identifier uses. A leading acronym on an unexported name is lowercase as a whole (`httpClient`), which this rule does not flag.
+
+## Message
+
+acronyms keep one case in identifiers: userID, HTTPClient, parseURL
+
+## Bad
+
+```go
+type Client struct {
+	// BAD: acronym in mixed case
+	userId string
+}
+```
+
+```go
+// BAD: acronym in mixed case
+func parseUrl(raw string) (*url.URL, error) {
+	return url.Parse(raw)
+}
+```
+
+```go
+func (c *Client) fetch() error {
+	// BAD: acronym in mixed case
+	responseJson, err := c.read()
+	if err != nil {
+		return err
+	}
+
+	return c.store(responseJson)
+}
+```
+
+## Good
+
+```go
+type Client struct {
+	userID     string
+	httpClient *http.Client
+}
+
+func parseURL(raw string) (*url.URL, error) {
+	return url.Parse(raw)
+}
+```
+
+```go
+func (c *Client) fetch() error {
+	responseJSON, err := c.read()
+	if err != nil {
+		return err
+	}
+
+	return c.store(responseJSON)
+}
+```

package/rules/go/idiom/naming/interface-er-suffix.md

@@ -0,0 +1,33 @@
+---
+severity: info
+detect: judge
+falsePositives:
+    - multi-method interfaces, which are named for the role they play (Repository, Storage)
+    - a method name that does not form a natural er noun
+    - a name that matches an existing standard library interface
+---
+
+## Why
+
+A single-method interface is named for the action with an `er` suffix: `Reader`, `Processor`, `Saver`. The name then states the capability, reads naturally at the call site, and matches how the standard library names the same shapes. Names like `IStorage` or `StorageInterface` import other languages' conventions and say nothing about what the value can do.
+
+## Message
+
+single-method interface is named for its action with an er suffix
+
+## Bad
+
+```go
+// BAD: single-method interface named like a class instead of a capability
+type IStorage interface {
+	Save(ctx context.Context, item Item) error
+}
+```
+
+## Good
+
+```go
+type Saver interface {
+	Save(ctx context.Context, item Item) error
+}
+```

package/rules/go/idiom/naming/no-package-name-stutter.md

@@ -0,0 +1,37 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - a name that only coincidentally shares a prefix with the package
+    - exported names in package main
+    - a name that would become a keyword or ambiguous when the prefix is dropped
+---
+
+## Why
+
+The package name is read together with every export, so `rotate.FileRotator` and `auth.AuthToken` say the same word twice at every call site. Let the package carry the context and name the export for what remains: `rotate.File`, `auth.Token`. This is also why a package's primary constructor is plain `New`.
+
+## Message
+
+exported name repeats the package name; let the package carry the context
+
+## Bad
+
+```go
+package rotate
+
+// BAD: rotate.FileRotator repeats the package name
+type FileRotator struct {
+	path string
+}
+```
+
+## Good
+
+```go
+package rotate
+
+type File struct {
+	path string
+}
+```