@aarock1234/slopscan 0.1.0

package/rules/any/hacky/duplication/copy-paste-block.md

@@ -0,0 +1,117 @@
+---
+severity: minor
+detect: judge
+ignore:
+    - '**/*.test.ts'
+    - '**/*.spec.ts'
+    - '**/*_test.go'
+falsePositives:
+    - table-driven tests and test fixtures, where repetition is the point
+    - generated code
+    - two or three short lines that happen to look alike, such as consecutive field assignments or switch arms
+    - blocks that look alike today but belong to different domains and are expected to diverge, when the code says so
+---
+
+## Why
+
+Two blocks that differ only in a name or a literal are one function with a parameter that has not been extracted yet. The next bug fix lands in one copy and not the other, and the reader has to diff them by eye to learn they are the same. Extract the block with the varying part as an argument, or loop over the values.
+
+## Message
+
+copy-pasted block differs in one identifier; extract a function or loop over the values
+
+## Bad
+
+```ts
+export async function exportReports(db: Db): Promise<void> {
+	// BAD: the second block is the first with 'sales' replaced by 'refunds'
+	const salesRows = await db.query('select * from sales where exported = false');
+	const salesCsv = toCsv(salesRows);
+	await storage.put(`exports/sales-${today()}.csv`, salesCsv);
+	await db.execute('update sales set exported = true where exported = false');
+	logger.info({ count: salesRows.length }, 'exported sales');
+
+	const refundRows = await db.query('select * from refunds where exported = false');
+	const refundCsv = toCsv(refundRows);
+	await storage.put(`exports/refunds-${today()}.csv`, refundCsv);
+	await db.execute('update refunds set exported = true where exported = false');
+	logger.info({ count: refundRows.length }, 'exported refunds');
+}
+```
+
+```go
+func ExportReports(ctx context.Context, db *sql.DB) error {
+	// BAD: the second block is the first with "sales" replaced by "refunds"
+	salesRows, err := query(ctx, db, "select * from sales where exported = false")
+	if err != nil {
+		return fmt.Errorf("querying sales: %w", err)
+	}
+	if err := storage.Put(ctx, "exports/sales-"+today()+".csv", toCSV(salesRows)); err != nil {
+		return fmt.Errorf("uploading sales: %w", err)
+	}
+	if _, err := db.ExecContext(ctx, "update sales set exported = true where exported = false"); err != nil {
+		return fmt.Errorf("marking sales: %w", err)
+	}
+
+	refundRows, err := query(ctx, db, "select * from refunds where exported = false")
+	if err != nil {
+		return fmt.Errorf("querying refunds: %w", err)
+	}
+	if err := storage.Put(ctx, "exports/refunds-"+today()+".csv", toCSV(refundRows)); err != nil {
+		return fmt.Errorf("uploading refunds: %w", err)
+	}
+	if _, err := db.ExecContext(ctx, "update refunds set exported = true where exported = false"); err != nil {
+		return fmt.Errorf("marking refunds: %w", err)
+	}
+
+	return nil
+}
+```
+
+## Good
+
+```ts
+const EXPORTED_TABLES = ['sales', 'refunds'] as const;
+
+export async function exportReports(db: Db): Promise<void> {
+	for (const table of EXPORTED_TABLES) {
+		await exportTable(db, table);
+	}
+}
+
+async function exportTable(db: Db, table: string): Promise<void> {
+	const rows = await db.query(`select * from ${table} where exported = false`);
+	await storage.put(`exports/${table}-${today()}.csv`, toCsv(rows));
+	await db.execute(`update ${table} set exported = true where exported = false`);
+	logger.info({ table, count: rows.length }, 'exported table');
+}
+```
+
+```go
+var exportedTables = []string{"sales", "refunds"}
+
+func ExportReports(ctx context.Context, db *sql.DB) error {
+	for _, table := range exportedTables {
+		if err := exportTable(ctx, db, table); err != nil {
+			return fmt.Errorf("exporting %s: %w", table, err)
+		}
+	}
+
+	return nil
+}
+
+func exportTable(ctx context.Context, db *sql.DB, table string) error {
+	rows, err := query(ctx, db, "select * from "+table+" where exported = false")
+	if err != nil {
+		return fmt.Errorf("querying: %w", err)
+	}
+	if err := storage.Put(ctx, "exports/"+table+"-"+today()+".csv", toCSV(rows)); err != nil {
+		return fmt.Errorf("uploading: %w", err)
+	}
+	if _, err := db.ExecContext(ctx, "update "+table+" set exported = true where exported = false"); err != nil {
+		return fmt.Errorf("marking: %w", err)
+	}
+
+	return nil
+}
+```

package/rules/any/hacky/types/stringly-typed-enum.md

@@ -0,0 +1,86 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - a string literal compared in exactly one place
+    - a value from an external protocol or wire format compared once at the boundary where it is parsed into a typed value
+    - discriminant literals of a union or sum type that already declares the allowed values, such as `if (event.kind === 'created')` where `kind` is typed as a union of literals
+    - map keys, header names, and env variable names, which are identifiers rather than a closed set of states
+---
+
+## Why
+
+Comparing the same handful of string literals in several places means the set of valid values lives nowhere: a typo in one comparison is a silent false branch, and adding a value means finding every switch by hand. Declare the set once as a const object with a derived union type in TypeScript, or a named string type with typed constants in Go, and let the compiler enforce exhaustiveness and spelling.
+
+## Message
+
+string literals used as an enum; declare the set once as typed constants
+
+## Bad
+
+```ts
+export function canShip(order: Order): boolean {
+	// BAD: the valid statuses exist only as scattered literals, and a typo compiles
+	return order.status === 'paid' || order.status === 'packed';
+}
+
+export function label(order: Order): string {
+	// BAD: same set, spelled again, with 'shiped' waiting to happen
+	if (order.status === 'shipped') {
+		return 'On its way';
+	}
+
+	return order.status === 'paid' ? 'Preparing' : 'Pending';
+}
+```
+
+```go
+func CanShip(o Order) bool {
+	// BAD: the valid statuses exist only as scattered literals
+	return o.Status == "paid" || o.Status == "packed"
+}
+
+func Label(o Order) string {
+	// BAD: same set, spelled again by hand
+	switch o.Status {
+	case "shipped":
+		return "On its way"
+	case "paid":
+		return "Preparing"
+	default:
+		return "Pending"
+	}
+}
+```
+
+## Good
+
+```ts
+export const OrderStatus = {
+	PENDING: 'pending',
+	PAID: 'paid',
+	PACKED: 'packed',
+	SHIPPED: 'shipped',
+} as const;
+
+export type OrderStatus = (typeof OrderStatus)[keyof typeof OrderStatus];
+
+export function canShip(order: Order): boolean {
+	return order.status === OrderStatus.PAID || order.status === OrderStatus.PACKED;
+}
+```
+
+```go
+type Status string
+
+const (
+	StatusPending Status = "pending"
+	StatusPaid    Status = "paid"
+	StatusPacked  Status = "packed"
+	StatusShipped Status = "shipped"
+)
+
+func CanShip(o Order) bool {
+	return o.Status == StatusPaid || o.Status == StatusPacked
+}
+```

package/rules/any/idiom/comments/no-section-banners.md

@@ -0,0 +1,47 @@
+---
+severity: minor
+detect: ast
+ast:
+    ts:
+        rule:
+            kind: comment
+            regex: '^//\s*[-=*#]{4,}'
+    go:
+        rule:
+            kind: comment
+            regex: '^//\s*[-=*#]{4,}'
+---
+
+## Why
+
+Banner comments and decorative separators are a sign the file has grown past one responsibility. They do not help navigation, editors fold on declarations rather than dashes, and they drift out of place as code moves. Split the file, or let the declarations speak for themselves.
+
+## Message
+
+banner comments signal a file doing too much; split it instead of decorating it
+
+## Bad
+
+```ts
+// BAD: decorative separator
+// ----------------------------------------
+export function createUser(): void {}
+```
+
+```go
+// BAD: decorative section header
+// ==== Handlers ====
+func handle() {}
+```
+
+## Good
+
+```ts
+// creates the user and returns its persisted form
+export function createUser(): void {}
+```
+
+```go
+// handle serves the health endpoint.
+func handle() {}
+```

package/rules/go/futureproof/constants/string-enums-when-serialized.md

@@ -0,0 +1,47 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - an enum that never leaves the process (not stored, logged, or sent on the wire)
+    - protobuf or database enums with a fixed, documented numbering
+    - a hot path where the integer is a deliberate optimization and a String method covers logs
+---
+
+## Why
+
+An `iota` enum that is stored, logged, or sent over the wire serializes as a bare number, so inserting a constant renumbers everything that was already saved and a log line shows `status=2` to whoever is debugging it. Back an enum that crosses a boundary with a string; the value stays stable when the list changes and is readable everywhere it appears.
+
+## Message
+
+iota enum is serialized as a bare integer; back it with a string
+
+## Bad
+
+```go
+type Status int
+
+const (
+	StatusPending Status = iota
+	StatusCompleted
+)
+
+type Item struct {
+	// BAD: inserting a constant above StatusCompleted changes every stored record
+	Status Status `json:"status"`
+}
+```
+
+## Good
+
+```go
+type Status string
+
+const (
+	StatusPending   Status = "pending"
+	StatusCompleted Status = "completed"
+)
+
+type Item struct {
+	Status Status `json:"status"`
+}
+```

package/rules/go/futureproof/constants/typed-constants-for-enums.md

@@ -0,0 +1,45 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - unrelated constants grouped for convenience, such as defaults or configuration keys
+    - a single constant
+    - values only ever used as map keys or labels, never as a parameter or field type
+---
+
+## Why
+
+A set of untyped string or int constants that stand for the states of one thing is an enum without a type, so any string is accepted where a status is expected and a typo compiles. Declare a named type and make the constants that type; the compiler then rejects a raw value and a `String` or `MarshalText` method has a type to hang on.
+
+## Message
+
+related constants form an enum but have no named type; declare one
+
+## Bad
+
+```go
+// BAD: untyped strings, so any string passes where a status is expected
+const (
+	StatusPending   = "pending"
+	StatusCompleted = "completed"
+)
+
+func Transition(status string) error {
+	return nil
+}
+```
+
+## Good
+
+```go
+type Status string
+
+const (
+	StatusPending   Status = "pending"
+	StatusCompleted Status = "completed"
+)
+
+func Transition(status Status) error {
+	return nil
+}
+```

package/rules/go/futureproof/interfaces/compile-time-impl-assertion.md

@@ -0,0 +1,43 @@
+---
+severity: info
+detect: judge
+falsePositives:
+    - the type is passed to a function taking the interface in the same package, which already checks it
+    - an unexported helper type with a single local use
+    - the interface is not known to the implementing package
+---
+
+## Why
+
+A type that is meant to satisfy an interface but never checked against it breaks only at the distant call site that first assigns it, and the compiler error points there instead of at the missing method. `var _ Repository = (*PgRepo)(nil)` next to the type turns that into an error on the type itself the moment the interface changes.
+
+## Message
+
+type meant to satisfy an interface is not checked; add var _ Iface = (*T)(nil)
+
+## Bad
+
+```go
+type PgRepo struct {
+	db *sql.DB
+}
+
+// BAD: nothing checks PgRepo against Repository until a distant caller fails to compile
+func (r *PgRepo) Get(ctx context.Context, id string) (*Item, error) {
+	return nil, nil
+}
+```
+
+## Good
+
+```go
+type PgRepo struct {
+	db *sql.DB
+}
+
+var _ Repository = (*PgRepo)(nil)
+
+func (r *PgRepo) Get(ctx context.Context, id string) (*Item, error) {
+	return nil, nil
+}
+```

package/rules/go/futureproof/interfaces/define-interfaces-at-consumer.md

@@ -0,0 +1,47 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - an interface a package exports for plugin authors to implement, where the package is the consumer
+    - a widely shared interface in the style of io.Reader
+    - a package that both defines and consumes the interface
+---
+
+## Why
+
+An interface declared next to its implementation is shaped by what the implementation offers, not by what a caller needs, so it grows with the implementation and every consumer depends on the implementing package to use it. Declare the interface in the package that calls it, with only the methods that package uses; the implementing package exports a concrete type and satisfies the interface implicitly.
+
+## Message
+
+interface declared beside its implementation; define it where it is consumed
+
+## Bad
+
+```go
+package postgres
+
+// BAD: the implementation dictates the interface, so every consumer imports postgres
+type Repository interface {
+	Get(ctx context.Context, id string) (*Item, error)
+	Save(ctx context.Context, item *Item) error
+}
+
+type Repo struct {
+	db *sql.DB
+}
+```
+
+## Good
+
+```go
+package service
+
+type Repository interface {
+	Get(ctx context.Context, id string) (*Item, error)
+	Save(ctx context.Context, item *Item) error
+}
+
+type Service struct {
+	repo Repository
+}
+```

package/rules/go/futureproof/interfaces/keep-interfaces-small.md

@@ -0,0 +1,53 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: interface_type
+        has:
+            kind: method_elem
+            nthChild:
+                position: 5
+                ofRule:
+                    kind: method_elem
+---
+
+## Why
+
+Every method on an interface is a method every implementation and every test double must provide, so a five-method interface makes the next fake and the next adapter five times the work of a one-method one. Small interfaces compose: declare `Reader` and `Writer` and embed them into `ReadWriter` where a consumer needs both.
+
+## Message
+
+interface with five or more methods; split it and compose smaller interfaces
+
+## Bad
+
+```go
+// BAD: every fake and adapter must implement all of these
+type Storage interface {
+	Get(ctx context.Context, id string) ([]byte, error)
+	Put(ctx context.Context, id string, data []byte) error
+	Delete(ctx context.Context, id string) error
+	List(ctx context.Context, prefix string) ([]string, error)
+	Stat(ctx context.Context, id string) (Info, error)
+}
+```
+
+## Good
+
+```go
+type Reader interface {
+	Get(ctx context.Context, id string) ([]byte, error)
+	List(ctx context.Context, prefix string) ([]string, error)
+}
+
+type Writer interface {
+	Put(ctx context.Context, id string, data []byte) error
+	Delete(ctx context.Context, id string) error
+}
+
+type ReadWriter interface {
+	Reader
+	Writer
+}
+```

package/rules/go/futureproof/naming/no-utils-helpers-common-package.md

@@ -0,0 +1,34 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: package_identifier
+        regex: '^(utils?|helpers?|common|misc|shared)$'
+---
+
+## Why
+
+A package called `utils` or `helpers` has no domain, so every unrelated function ends up there and the package grows into a dependency of everything. The name gives the reader no idea what `utils.Process` does or where the next function belongs. Name packages after the concept they own, such as `rotate` or `auth`, and split a grab-bag by what its functions act on.
+
+## Message
+
+package named as a grab-bag; name it after the concept it owns
+
+## Bad
+
+```go
+// BAD: no domain, will collect everything
+package utils
+```
+
+```go
+// BAD: no domain, will collect everything
+package common
+```
+
+## Good
+
+```go
+package rotate
+```

package/rules/go/futureproof/structs/zero-value-usable.md

@@ -0,0 +1,50 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - a type that wraps an external resource (connection, file) and is always built by a constructor
+    - a type whose constructor validates invariants that a zero value cannot satisfy
+    - a type that is unexported and only constructed in one place
+---
+
+## Why
+
+A struct whose zero value works can be declared as a field or a `var` and used immediately, the way `sync.Mutex` and `bytes.Buffer` are. When the zero value panics on first use, every caller has to remember the constructor, and forgetting it is a nil map write that only shows up at runtime. Initialize lazily inside the methods or make the zero state meaningful.
+
+## Message
+
+zero value panics on first use; make the type usable without a constructor
+
+## Bad
+
+```go
+type Cache struct {
+	mu    sync.Mutex
+	items map[string]string
+}
+
+// BAD: the zero Cache panics here because items is nil
+func (c *Cache) Set(key, value string) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.items[key] = value
+}
+```
+
+## 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()
+	if c.items == nil {
+		c.items = make(map[string]string)
+	}
+	c.items[key] = value
+}
+```

package/rules/go/futureproof/types/generics-over-any.md

@@ -0,0 +1,55 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - a collection that genuinely mixes unrelated types
+    - an interface used only for behavior, with no assertion back to a concrete type
+    - the caller never needs the concrete type again
+---
+
+## Why
+
+Returning an interface or `any` from a lookup and letting callers type-assert back to what they put in moves a compile-time fact to a runtime check at every call site. A type parameter keeps the caller's concrete type through the function, so the assertion and its failure branch disappear and adding a new element type needs no new code.
+
+## Message
+
+interface plus assertions where a type parameter would keep the caller's type
+
+## Bad
+
+```go
+type HasID interface {
+	GetID() string
+}
+
+// BAD: callers get an interface back and must assert to recover their own type
+func FindItem(items []HasID, id string) HasID {
+	for _, item := range items {
+		if item.GetID() == id {
+			return item
+		}
+	}
+
+	return nil
+}
+```
+
+## Good
+
+```go
+type HasID interface {
+	GetID() string
+}
+
+func FindItem[T HasID](items []T, id string) (T, bool) {
+	for _, item := range items {
+		if item.GetID() == id {
+			return item, true
+		}
+	}
+
+	var zero T
+
+	return zero, false
+}
+```

package/rules/go/hacky/concurrency/no-goroutine-without-wait.md

@@ -0,0 +1,44 @@
+---
+severity: major
+detect: judge
+falsePositives:
+    - a long-lived background loop started from main or a Start method that has a matching Stop
+    - a goroutine that reports through a channel the caller reads
+    - fire-and-forget by design with the error handled and logged inside the goroutine
+---
+
+## Why
+
+A bare `go f()` in a request path has no one waiting for it, so its errors vanish, its panics take the process down, and the function returns before the work is done. Bound the goroutines with an `errgroup` or a `sync.WaitGroup`, propagate the first error, and let the context cancel the rest.
+
+## Message
+
+goroutine started with nothing waiting for it or collecting its error
+
+## Bad
+
+```go
+func (s *Service) ProcessAll(ctx context.Context, items []Item) error {
+	for _, item := range items {
+		// BAD: nothing waits for these goroutines or sees their errors
+		go s.process(ctx, item)
+	}
+
+	return nil
+}
+```
+
+## Good
+
+```go
+func (s *Service) ProcessAll(ctx context.Context, items []Item) error {
+	g, ctx := errgroup.WithContext(ctx)
+	for _, item := range items {
+		g.Go(func() error {
+			return s.process(ctx, item)
+		})
+	}
+
+	return g.Wait()
+}
+```