@aarock1234/slopscan 0.1.0

package/rules/go/hacky/type-safety/no-map-string-any.md

@@ -0,0 +1,49 @@
+---
+severity: major
+detect: ast
+ignore:
+    - "**/*_test.go"
+ast:
+    rule:
+        any:
+            - pattern: map[string]any
+            - pattern: map[string]interface{}
+---
+
+## Why
+
+A `map[string]any` pushes every field access to runtime with a type assertion and a nil check, and the compiler can no longer tell you when a field is renamed. Decode JSON and config into a struct. Tests are excluded: decoding a payload into a map to inspect it is the honest way to assert on wire format. If the shape is genuinely open, a generic constrained by an interface still beats a bag of `any`.
+
+## Message
+
+map[string]any defers every field to runtime; decode into a struct
+
+## Bad
+
+```go
+func parse(raw []byte) error {
+	// BAD: every access is an assertion waiting to fail
+	var payload map[string]any
+
+	return json.Unmarshal(raw, &payload)
+}
+```
+
+## Good
+
+```go
+type Payload struct {
+	UserID string `json:"user_id"`
+	Amount int    `json:"amount"`
+}
+
+func parse(raw []byte) (Payload, error) {
+	var payload Payload
+
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		return Payload{}, fmt.Errorf("decoding payload: %w", err)
+	}
+
+	return payload, nil
+}
+```

package/rules/go/hacky/types/json-into-struct-not-map.md

@@ -0,0 +1,48 @@
+---
+severity: major
+detect: judge
+falsePositives:
+    - a genuinely dynamic shape such as user-defined metadata or plugin configuration
+    - map[string]json.RawMessage used for a two-phase decode on a discriminator field
+    - pass-through data that is never read by field name
+---
+
+## Why
+
+Decoding JSON into a map and then reading `m["name"]` moves every field name and type into runtime lookups, so a renamed field or a wrong type compiles fine and fails on the first request. A struct with tags gives the decoder the shape up front, validates types on unmarshal, and lets the compiler catch a misspelled field.
+
+## Message
+
+json decoded into a map; declare a struct with tags so fields are checked at compile time
+
+## Bad
+
+```go
+func parse(raw []byte) (string, error) {
+	// BAD: fields live in string keys that nothing checks
+	var payload map[string]string
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		return "", err
+	}
+
+	return payload["name"], nil
+}
+```
+
+## Good
+
+```go
+type Request struct {
+	Name  string `json:"name"`
+	Email string `json:"email,omitempty"`
+}
+
+func parse(raw []byte) (Request, error) {
+	var req Request
+	if err := json.Unmarshal(raw, &req); err != nil {
+		return Request{}, fmt.Errorf("decoding request: %w", err)
+	}
+
+	return req, nil
+}
+```

package/rules/go/hacky/types/no-any.md

@@ -0,0 +1,71 @@
+---
+severity: major
+detect: ast
+ast:
+    rule:
+        any:
+            - kind: type_identifier
+              regex: '^any$'
+            - kind: interface_type
+              regex: '^interface\s*\{\s*\}$'
+        not:
+            any:
+                - inside:
+                      kind: type_constraint
+                - inside:
+                      kind: variadic_parameter_declaration
+                - inside:
+                      kind: map_type
+                      regex: '^map\[(string|any|interface\{\})\]'
+---
+
+## Why
+
+A parameter, field, or return typed `any` pushes every use to a runtime assertion and hides the real shape from the compiler and the reader. Prefer a concrete type, then a type parameter with a constraint, then a small interface; `any` is the last resort for genuinely dynamic data. Type constraints (`[T any]`) and printf-style `...any` variadics are not flagged; maps of `any` are covered by their own rules.
+
+## Message
+
+any erases the type; use a concrete type, a type parameter, or a small interface
+
+## Bad
+
+```go
+// BAD: any erases the type and every caller pays with assertions
+func Process(data any) any {
+	return data
+}
+```
+
+```go
+type Event struct {
+	// BAD: payload has no shape the compiler can check
+	Payload interface{}
+}
+```
+
+## Good
+
+```go
+type Sizer interface {
+	Size() int
+}
+
+func Largest[T Sizer](items []T) (T, bool) {
+	var zero T
+	if len(items) == 0 {
+		return zero, false
+	}
+
+	return items[0], true
+}
+```
+
+```go
+type Event struct {
+	Payload Payload
+}
+
+func Logf(format string, args ...any) {
+	slog.Info(fmt.Sprintf(format, args...))
+}
+```

package/rules/go/hacky/types/no-map-any-any.md

@@ -0,0 +1,35 @@
+---
+severity: major
+detect: ast
+ast:
+    rule:
+        kind: map_type
+        has:
+            field: key
+            regex: '^(any|interface\{\s*\})$'
+---
+
+## Why
+
+A map keyed by `any` says nothing about what goes in or comes out, so both the lookup and the value need runtime assertions and a typo in a key type compiles fine. Give the map a concrete key type and, where the values vary, a small interface or a typed union such as a string enum.
+
+## Message
+
+map[any]any is fully untyped; give the map concrete key and value types
+
+## Bad
+
+```go
+type Registry struct {
+	// BAD: neither keys nor values have a checkable type
+	handlers map[any]any
+}
+```
+
+## Good
+
+```go
+type Registry struct {
+	handlers map[string]HandlerFunc
+}
+```

package/rules/go/idiom/comments/doc-comment-on-exported.md

@@ -0,0 +1,81 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        any:
+            - kind: function_declaration
+              has:
+                  field: name
+                  regex: '^[A-Z]'
+            - kind: method_declaration
+              has:
+                  field: name
+                  regex: '^[A-Z]'
+            - kind: type_declaration
+              inside:
+                  kind: source_file
+              has:
+                  kind: type_spec
+                  has:
+                      field: name
+                      regex: '^[A-Z]'
+        not:
+            follows:
+                kind: comment
+ignore:
+    - '**/*_test.go'
+    - '**/*.pb.go'
+    - '**/*_gen.go'
+---
+
+## Why
+
+An exported name is the package's contract, and its doc comment is what `go doc` and every editor show at the call site. Without one the reader opens the source to learn what the function promises, and the omission tends to spread to the next export. One sentence starting with the name is enough.
+
+## Message
+
+exported declaration has no doc comment
+
+## Bad
+
+```go
+// BAD: exported function with no doc comment
+func Process(ctx context.Context, item Item) error {
+	return nil
+}
+```
+
+```go
+// BAD: exported type with no doc comment
+type Service struct {
+	repo Repository
+}
+```
+
+```go
+// BAD: exported method with no doc comment
+func (s *Service) Process(ctx context.Context, item Item) error {
+	return nil
+}
+```
+
+## Good
+
+```go
+// Process validates and persists item.
+func Process(ctx context.Context, item Item) error {
+	return nil
+}
+```
+
+```go
+// Service processes items according to business rules.
+type Service struct {
+	repo Repository
+}
+
+func (s *Service) process(ctx context.Context, item Item) error {
+	return nil
+}
+```

package/rules/go/idiom/comments/doc-comment-starts-with-name.md

@@ -0,0 +1,36 @@
+---
+severity: info
+detect: judge
+falsePositives:
+    - a package comment, which starts with "Package name"
+    - a deprecation notice starting with "Deprecated:"
+    - a comment on a declaration inside a grouped var or const block
+---
+
+## Why
+
+A doc comment begins with the name it documents and reads as a complete sentence: `// Process validates and persists the item.` That form is what `go doc` and editors index, and it keeps the comment attached to the thing it describes when the file is skimmed. A comment that opens with "This function" or a bare description does not identify its subject.
+
+## Message
+
+doc comment does not start with the name it documents
+
+## Bad
+
+```go
+// BAD: doc comment does not begin with the name it documents
+// This function validates and persists the item.
+func Process(ctx context.Context, item Item) error {
+	return nil
+}
+```
+
+## Good
+
+```go
+// Process validates and persists item. It returns an error if the item
+// fails validation or cannot be saved.
+func Process(ctx context.Context, item Item) error {
+	return nil
+}
+```

package/rules/go/idiom/concurrency/mutex-over-channels-for-state.md

@@ -0,0 +1,47 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - a channel that hands off ownership or coordinates goroutines, such as a work queue or cancellation
+    - a semaphore channel that bounds concurrency rather than guarding a value
+    - an actor loop that owns the state by design and is documented as such
+---
+
+## Why
+
+Guarding a plain value with a channel used as a lock, or with a goroutine that serializes closures, hides a mutex behind extra machinery that the reader has to decode before they can see it is just mutual exclusion. Channels are for moving data between goroutines; a `sync.Mutex` next to the field it protects says exactly what is guarded and is what the race detector and every Go reader expect.
+
+## Message
+
+channel used as a lock around plain state; use a sync.Mutex next to the field
+
+## Bad
+
+```go
+type Cache struct {
+	lock  chan struct{}
+	items map[string]string
+}
+
+func (c *Cache) Set(key, value string) {
+	// BAD: a one-slot channel standing in for a mutex
+	c.lock <- struct{}{}
+	c.items[key] = value
+	<-c.lock
+}
+```
+
+## Good
+
+```go
+type Cache struct {
+	mu    sync.Mutex
+	items map[string]string
+}
+
+func (c *Cache) Set(key, value string) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.items[key] = value
+}
+```

package/rules/go/idiom/constructors/constructor-named-new.md

@@ -0,0 +1,37 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - a package that constructs several types, where NewX disambiguates
+    - package main
+    - a constructor for a secondary type when New is already taken by the primary one
+---
+
+## Why
+
+The package name already says what is being built, so `service.NewService(...)` says it twice while `service.New(...)` reads cleanly. Name the constructor of a package's primary type `New`; reserve `NewX` for secondary types that need to be told apart.
+
+## Message
+
+constructor for the package's primary type is named New, not NewX
+
+## Bad
+
+```go
+package service
+
+// BAD: service.NewService repeats the package name
+func NewService(repo Repository) *Service {
+	return &Service{repo: repo}
+}
+```
+
+## Good
+
+```go
+package service
+
+func New(repo Repository) *Service {
+	return &Service{repo: repo}
+}
+```

package/rules/go/idiom/context/context-is-first-param.md

@@ -0,0 +1,47 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: parameter_declaration
+        all:
+            - has:
+                  field: type
+                  regex: '^context\.Context$'
+            - inside:
+                  kind: parameter_list
+                  inside:
+                      any:
+                          - kind: function_declaration
+                          - kind: method_declaration
+                          - kind: func_literal
+                      field: parameters
+            - follows:
+                  kind: parameter_declaration
+                  stopBy: end
+---
+
+## Why
+
+The context is the first parameter of every function that takes one, named `ctx`, across the standard library and the ecosystem. Putting it anywhere else makes call sites read differently from every other function and is the first thing a reviewer will ask to move.
+
+## Message
+
+context.Context is the first parameter
+
+## Bad
+
+```go
+// BAD: context after the id
+func (s *Service) Get(id string, ctx context.Context) (*Item, error) {
+	return s.repo.Get(ctx, id)
+}
+```
+
+## Good
+
+```go
+func (s *Service) Get(ctx context.Context, id string) (*Item, error) {
+	return s.repo.Get(ctx, id)
+}
+```

package/rules/go/idiom/context/io-takes-context.md

@@ -0,0 +1,50 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - pure computation with no network, disk, or database access
+    - a method satisfying an interface that has no context, such as http.Handler where r.Context() is used inside
+    - test helpers
+---
+
+## Why
+
+A function that talks to the network, a database, or another process without a `context.Context` cannot be cancelled or bounded by a deadline, so a hung dependency hangs every caller and the request that started it. Take `ctx` as the first parameter and pass it through to the call that does the I/O.
+
+## Message
+
+function does I/O without a context; take ctx and pass it to the call
+
+## Bad
+
+```go
+// BAD: a network call with no way to cancel or bound it
+func (c *Client) Fetch(id string) (*Item, error) {
+	resp, err := c.http.Get(c.baseURL + "/items/" + id)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	return decode(resp.Body)
+}
+```
+
+## Good
+
+```go
+func (c *Client) Fetch(ctx context.Context, id string) (*Item, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+"/items/"+id, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	return decode(resp.Body)
+}
+```

package/rules/go/idiom/errors/capitalized-error-message.md

@@ -0,0 +1,52 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        any:
+            - pattern:
+                  context: 'func f() { errors.New($MSG) }'
+                  selector: call_expression
+            - pattern:
+                  context: 'func f() { fmt.Errorf($MSG, $$$ARGS) }'
+                  selector: call_expression
+    constraints:
+        MSG:
+            regex: '^"[A-Z]'
+---
+
+## Why
+
+Error messages get wrapped: `reading config: opening file: permission denied`. A capitalized fragment in the middle of that chain reads wrong, and trailing punctuation doubles up. Error strings are lowercase fragments without a final period.
+
+## Message
+
+error strings are lowercase fragments so they read well when wrapped
+
+## Bad
+
+```go
+func load(path string) error {
+	// BAD: capitalized message
+	return errors.New("Config file is missing")
+}
+```
+
+```go
+func load(path string) error {
+	// BAD: capitalized wrapped message
+	return fmt.Errorf("Reading %s: %w", path, err)
+}
+```
+
+## Good
+
+```go
+func load(path string) error {
+	return fmt.Errorf("reading %s: %w", path, err)
+}
+```
+
+```go
+var ErrMissingConfig = errors.New("config file is missing")
+```

package/rules/go/idiom/errors/check-error-immediately.md

@@ -0,0 +1,45 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - the inline form `if err := f(); err != nil`
+    - an error deliberately collected and checked after a loop or a Wait
+    - a second call that does not depend on the first result
+---
+
+## Why
+
+An error is checked on the line after the call that produced it. Anything that runs in between operates on a value that may be the zero value, and the reader has to hold the pending error in their head while following unrelated work. The immediate `if err != nil` keeps the happy path and the failure path next to each other.
+
+## Message
+
+check the error on the line after the call that returned it
+
+## Bad
+
+```go
+func load(ctx context.Context, id string) (Item, error) {
+	item, err := repo.Get(ctx, id)
+	// BAD: works on item before err is checked
+	item.Normalize()
+	if err != nil {
+		return Item{}, fmt.Errorf("get item %s: %w", id, err)
+	}
+
+	return item, nil
+}
+```
+
+## Good
+
+```go
+func load(ctx context.Context, id string) (Item, error) {
+	item, err := repo.Get(ctx, id)
+	if err != nil {
+		return Item{}, fmt.Errorf("get item %s: %w", id, err)
+	}
+	item.Normalize()
+
+	return item, nil
+}
+```

package/rules/go/idiom/errors/defer-close-explicit-discard.md

@@ -0,0 +1,65 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: defer_statement
+        has:
+            kind: call_expression
+            has:
+                field: function
+                regex: '\.Close$'
+---
+
+## Why
+
+A bare `defer f.Close()` drops the returned error without saying so, which is also what `errcheck` flags. For read-only resources the error is not actionable, so discard it explicitly with `_ =` to record that decision; for anything that was written to, check the error, because a failed close can mean the data never reached disk.
+
+## Message
+
+bare defer Close ignores its error silently; discard it with _ = or check it
+
+## Bad
+
+```go
+func fetch(url string) error {
+	resp, err := http.Get(url)
+	if err != nil {
+		return err
+	}
+	// BAD: close error dropped without saying so
+	defer resp.Body.Close()
+
+	return nil
+}
+```
+
+## Good
+
+```go
+func fetch(url string) error {
+	resp, err := http.Get(url)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	return nil
+}
+```
+
+```go
+func write(path string) error {
+	f, err := os.Create(path)
+	if err != nil {
+		return err
+	}
+	defer func() {
+		if err := f.Close(); err != nil {
+			slog.Error("closing output file", "error", err)
+		}
+	}()
+
+	return nil
+}
+```