@aarock1234/slopscan 0.1.0

package/rules/go/idiom/naming/package-name-single-lowercase-word.md

@@ -0,0 +1,40 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: package_identifier
+        regex: '[A-Z_]'
+        not:
+            regex: '^[a-z0-9]+_test$'
+---
+
+## Why
+
+A package name is typed at every call site, so it is short, lowercase, and a single word: `rotate`, `auth`, `client`. Mixed case or underscores in a package name break that rhythm, and the Go toolchain and most linters assume the lowercase form. Only the `_test` suffix on an external test package is conventional.
+
+## Message
+
+package names are one short lowercase word
+
+## Bad
+
+```go
+// BAD: mixed case package name
+package httpHelpers
+```
+
+```go
+// BAD: underscore in package name
+package user_service
+```
+
+## Good
+
+```go
+package client
+```
+
+```go
+package client_test
+```

package/rules/go/idiom/receivers/consistent-receiver-kind-per-type.md

@@ -0,0 +1,40 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - generated code
+    - a method that must have a value receiver to satisfy an interface on the value type, with a comment saying so
+---
+
+## Why
+
+When some methods on a type use a pointer receiver and others a value receiver, the method set differs between `T` and `*T`, so whether a value satisfies an interface depends on how it was declared, and a reader cannot tell from one method whether calls see shared state. If any method needs a pointer receiver, give every method on that type a pointer receiver.
+
+## Message
+
+type mixes pointer and value receivers; use one kind for every method
+
+## Bad
+
+```go
+func (s *Service) Process(ctx context.Context, id string) error {
+	return nil
+}
+
+// BAD: value receiver on a type that already uses pointer receivers
+func (s Service) Name() string {
+	return s.name
+}
+```
+
+## Good
+
+```go
+func (s *Service) Process(ctx context.Context, id string) error {
+	return nil
+}
+
+func (s *Service) Name() string {
+	return s.name
+}
+```

package/rules/go/idiom/receivers/no-this-receiver.md

@@ -0,0 +1,37 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: parameter_declaration
+        regex: '^(this|self)\b'
+        inside:
+            kind: parameter_list
+            inside:
+                kind: method_declaration
+---
+
+## Why
+
+Go receivers are ordinary parameters and the convention is a one or two letter abbreviation of the type, used consistently across all methods on that type. `this` and `self` import another language's model and stand out as a tell that the author was not writing Go.
+
+## Message
+
+receiver named this/self; use a short abbreviation of the type
+
+## Bad
+
+```go
+// BAD: receiver named like an object-oriented keyword
+func (this *Server) Start() error {
+	return this.listener.Listen()
+}
+```
+
+## Good
+
+```go
+func (s *Server) Start() error {
+	return s.listener.Listen()
+}
+```

package/rules/go/idiom/receivers/pointer-vs-value-receiver-choice.md

@@ -0,0 +1,49 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - small immutable value types such as enums and thin wrappers on value receivers
+    - a type that is deliberately copied on every call and documented as such
+    - methods on named map, slice, or channel types
+---
+
+## Why
+
+A value receiver works on a copy, so a method that assigns to a field on a value receiver silently changes nothing, and a large struct is copied on every call. Use a pointer receiver when the method mutates state or the struct is large; use a value receiver for small immutable types such as a string enum with a `String` method.
+
+## Message
+
+receiver kind does not fit the method: mutation or a large struct needs a pointer receiver
+
+## Bad
+
+```go
+type Counter struct {
+	n int
+}
+
+// BAD: value receiver mutates a copy, so the increment is lost
+func (c Counter) Inc() {
+	c.n++
+}
+```
+
+## Good
+
+```go
+type Counter struct {
+	n int
+}
+
+func (c *Counter) Inc() {
+	c.n++
+}
+```
+
+```go
+type Status string
+
+func (s Status) String() string {
+	return string(s)
+}
+```

package/rules/go/idiom/receivers/short-receiver-names.md

@@ -0,0 +1,43 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: parameter_declaration
+        all:
+            - inside:
+                  kind: parameter_list
+                  inside:
+                      kind: method_declaration
+                      field: receiver
+            - has:
+                  field: name
+                  regex: '^[a-zA-Z_]\w{2,}$'
+                  not:
+                      regex: '^(this|self)$'
+---
+
+## Why
+
+A receiver is named with one or two letters abbreviating the type, `s` for `Service`, `c` for `Client`, and the same letters on every method of that type. A long receiver name such as `service` reads like a parameter and pushes the method body to the right on every line that touches it.
+
+## Message
+
+receiver name longer than two letters; use a short abbreviation of the type
+
+## Bad
+
+```go
+// BAD: receiver named like a parameter
+func (service *Service) Get(ctx context.Context, id string) (*Item, error) {
+	return service.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/structs/new-expr-for-pointer-fields.md

@@ -0,0 +1,40 @@
+---
+severity: info
+detect: judge
+falsePositives:
+    - the variable is read again after its address is taken
+    - the module targets a Go version older than 1.26
+---
+
+## Why
+
+Since Go 1.26 `new` accepts an expression, so an optional pointer field can be set inline with `new(yearsSince(born))`. A throwaway local declared only so `&` has something to point at adds a name and a line that carry no meaning.
+
+## Message
+
+temporary declared only to take its address; use new(expr)
+
+## Bad
+
+```go
+func person(name string, born time.Time) Person {
+	// BAD: age exists only so its address can be taken
+	age := yearsSince(born)
+
+	return Person{
+		Name: name,
+		Age:  &age,
+	}
+}
+```
+
+## Good
+
+```go
+func person(name string, born time.Time) Person {
+	return Person{
+		Name: name,
+		Age:  new(yearsSince(born)),
+	}
+}
+```

package/rules/go/idiom/structure/main-delegates-to-run.md

@@ -0,0 +1,54 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - a main of a few lines with no resources to release
+    - example or generated programs
+    - a main that only parses flags and calls one function
+---
+
+## Why
+
+`os.Exit` and `log.Fatal` skip deferred calls, so a `main` that opens resources and exits on error leaks every one of them on the failure path. Move the body into `run() error`, let defers run on every exit, and keep `main` to calling `run`, logging the error, and exiting.
+
+## Message
+
+main does the wiring itself; move it into run() error so defers run on every exit
+
+## Bad
+
+```go
+func main() {
+	db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer db.Close()
+
+	if err := serve(db); err != nil {
+		// BAD: exits from the middle of the wiring, skipping the deferred close
+		log.Fatal(err)
+	}
+}
+```
+
+## Good
+
+```go
+func main() {
+	if err := run(); err != nil {
+		slog.Error("fatal error", "error", err)
+		os.Exit(1)
+	}
+}
+
+func run() error {
+	db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
+	if err != nil {
+		return fmt.Errorf("open database: %w", err)
+	}
+	defer func() { _ = db.Close() }()
+
+	return serve(db)
+}
+```

package/rules/ts/futureproof/classes/composition-over-abstract-base.md

@@ -0,0 +1,73 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - an abstract class that enforces a method contract across a family of implementations and holds real shared behavior such as a template method
+    - framework-required base classes, such as ORM entities, component classes, or error hierarchies extending `Error`
+    - a hierarchy that is one level deep and whose subclasses differ only in the abstract method they implement
+---
+
+## Why
+
+An abstract base class introduced to share a helper or two couples every subclass to a hierarchy, so the next feature that does not fit the base shape either bends the base or forks it. A shared function, or a dependency passed into a constructor, gives the same reuse without the inheritance tax and can be swapped or tested on its own. Reach for an abstract class only when there is a real contract to enforce across a family of implementations.
+
+## Message
+
+abstract base class used for code sharing; prefer a shared function or injected dependency
+
+## Bad
+
+```ts
+// BAD: the base exists only to share one helper with its subclasses
+abstract class BaseService {
+	protected logDuration(label: string, startedAt: number): void {
+		logger.info(`${label} took ${Date.now() - startedAt}ms`);
+	}
+}
+
+class UserService extends BaseService {
+	async getUser(id: string): Promise<User> {
+		const startedAt = Date.now();
+		const user = await repository.find(id);
+
+		this.logDuration('getUser', startedAt);
+
+		return user;
+	}
+}
+```
+
+## Good
+
+```ts
+function logDuration(label: string, startedAt: number): void {
+	logger.info(`${label} took ${Date.now() - startedAt}ms`);
+}
+
+class UserService {
+	constructor(private readonly repository: UserRepository) {}
+
+	async getUser(id: string): Promise<User> {
+		const startedAt = Date.now();
+		const user = await this.repository.find(id);
+
+		logDuration('getUser', startedAt);
+
+		return user;
+	}
+}
+```
+
+```ts
+abstract class BaseProcessor<TInput, TOutput> {
+	async process(input: TInput): Promise<TOutput> {
+		this.validate(input);
+
+		return this.execute(input);
+	}
+
+	protected abstract validate(input: TInput): void;
+
+	protected abstract execute(input: TInput): Promise<TOutput>;
+}
+```

package/rules/ts/futureproof/functions/explicit-return-type-on-exports.md

@@ -0,0 +1,50 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: function_declaration
+        inside:
+            kind: export_statement
+        not:
+            has:
+                field: return_type
+                regex: '.'
+---
+
+## Why
+
+An exported function is a contract, and an inferred return type lets that contract drift silently: a change deep in the body widens or narrows the type and the error surfaces at some distant call site instead of at the definition. Writing the return type pins the contract, produces errors where the change was made, and documents the function without a comment. Internal helpers and callbacks can keep inference where the type is obvious.
+
+## Message
+
+exported function has no return type; declare it so the contract cannot drift
+
+## Bad
+
+```ts
+// BAD: the return type is whatever the body happens to produce today
+export async function getUser(id: string) {
+	return repository.find(id);
+}
+```
+
+## Good
+
+```ts
+export async function getUser(id: string): Promise<User | undefined> {
+	return repository.find(id);
+}
+```
+
+```ts
+function buildWhere(filters: Filters) {
+	return {
+		...(filters.status && { status: filters.status }),
+	};
+}
+
+export function listUsers(filters: Filters): Promise<User[]> {
+	return repository.findMany(buildWhere(filters));
+}
+```

package/rules/ts/futureproof/structure/colocate-zod-schemas.md

@@ -0,0 +1,46 @@
+---
+severity: info
+detect: judge
+falsePositives:
+    - a schema shared by several modules and placed in a module named for the domain concept it describes, such as `user.schema.ts` next to `user.service.ts`
+    - schemas that are the public contract of a package and are grouped deliberately for export
+    - a schema moved into its own file because it is large, when it stays in the same feature directory
+---
+
+## Why
+
+A Zod schema is the definition of a shape the code around it consumes, so when it lives in a distant `schemas/` or `types.ts` dump the reader has to jump files to learn what a function accepts, and changes to the consumer and the schema land in different places. Keep the schema next to the code that parses with it and derive the type from it there. A shared schema belongs with the domain module it describes, not in a catch-all.
+
+## Message
+
+schema lives away from the code that uses it; colocate it with its consumer
+
+## Bad
+
+```ts
+// BAD: the request schema lives in a distant catch-all module
+import { createUserSchema } from '@/schemas';
+
+export async function handleCreateUser(req: Request, res: Response): Promise<void> {
+	const input = createUserSchema.parse(req.body);
+
+	res.json(await createUser(input));
+}
+```
+
+## Good
+
+```ts
+const createUserSchema = z.object({
+	name: z.string().min(1),
+	email: z.string().email(),
+});
+
+type CreateUserInput = z.infer<typeof createUserSchema>;
+
+export async function handleCreateUser(req: Request, res: Response): Promise<void> {
+	const input = createUserSchema.parse(req.body);
+
+	res.json(await createUser(input));
+}
+```

package/rules/ts/futureproof/types/exhaustive-switch-never-check.md

@@ -0,0 +1,52 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - switches over open types such as `string` or `number`, where a default branch is the only way to finish
+    - a switch whose default already assigns the value to `never` or calls an `assertNever` helper
+    - a switch that intentionally handles a subset and falls through to shared behavior for everything else
+---
+
+## Why
+
+A switch over a union or a const-object type with a plain `default` keeps compiling when a new variant is added, so the new case silently takes the default path at runtime. Assigning the switched value to `never` in the default branch makes the compiler reject any switch that forgot a case, turning a production bug into a build error at the moment the variant is introduced. The same applies to `if` chains that end in an unconditional fallback.
+
+## Message
+
+switch over a union without a `never` check; new variants will fall through silently
+
+## Bad
+
+```ts
+function label(status: Status): string {
+	switch (status) {
+		case Status.PENDING:
+			return 'waiting';
+		case Status.ACTIVE:
+			return 'running';
+		// BAD: adding Status.CANCELLED compiles and returns 'done'
+		default:
+			return 'done';
+	}
+}
+```
+
+## Good
+
+```ts
+function label(status: Status): string {
+	switch (status) {
+		case Status.PENDING:
+			return 'waiting';
+		case Status.ACTIVE:
+			return 'running';
+		case Status.COMPLETED:
+			return 'done';
+		default: {
+			const exhaustive: never = status;
+
+			throw new Error(`unhandled status: ${String(exhaustive)}`);
+		}
+	}
+}
+```

package/rules/ts/futureproof/types/readonly-for-immutable-data.md

@@ -0,0 +1,46 @@
+---
+severity: info
+detect: judge
+falsePositives:
+    - parameters or properties that the function or class genuinely mutates
+    - builder or accumulator objects whose whole purpose is to be filled in
+    - types generated from a schema or an ORM where the modifier is not under the author's control
+---
+
+## Why
+
+A parameter typed as `T[]` or a property typed without `readonly` invites the next author to push into it or reassign it, and the compiler will let them even when the caller never expected its data to change. `readonly` on arrays and on identity fields such as `id` and `createdAt` documents the intent, rejects the mutation at compile time, and costs nothing at runtime. Data that is meant to be shared is safer when it cannot be edited in place.
+
+## Message
+
+data that is never mutated is typed as mutable; mark it `readonly`
+
+## Bad
+
+```ts
+// BAD: nothing stops a caller from reassigning id or pushing into tags
+type User = {
+	id: string;
+	createdAt: Date;
+	tags: string[];
+};
+
+function tagNames(tags: string[]): string[] {
+	return tags.map(tag => tag.toLowerCase());
+}
+```
+
+## Good
+
+```ts
+type User = {
+	readonly id: string;
+	readonly createdAt: Date;
+	readonly tags: readonly string[];
+	name: string;
+};
+
+function tagNames(tags: readonly string[]): string[] {
+	return tags.map(tag => tag.toLowerCase());
+}
+```

package/rules/ts/futureproof/zod/enum-values-from-const-object.md

@@ -0,0 +1,37 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        pattern: z.enum([$$$VALUES])
+---
+
+## Why
+
+An inline string array in `z.enum(['pending', 'active'])` is a second copy of values that the code also needs as constants, so adding a variant means finding every literal list and hoping none is missed. Deriving the tuple from a const object keeps one definition that feeds the schema, the type, and every `Status.PENDING` reference. The schema then cannot drift from the constants it validates.
+
+## Message
+
+`z.enum` with inline string literals; derive the values from a const object
+
+## Bad
+
+```ts
+// BAD: the values live only here and cannot be referenced as constants
+const statusSchema = z.enum(['pending', 'active', 'completed']);
+```
+
+## Good
+
+```ts
+const Status = {
+	PENDING: 'pending',
+	ACTIVE: 'active',
+	COMPLETED: 'completed',
+} as const;
+
+type Status = (typeof Status)[keyof typeof Status];
+
+const statusValues = Object.values(Status) as [Status, ...Status[]];
+const statusSchema = z.enum(statusValues);
+```

package/rules/ts/futureproof/zod/no-z-native-enum.md

@@ -0,0 +1,36 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        pattern: z.nativeEnum($X)
+---
+
+## Why
+
+`z.nativeEnum` exists to wrap a TypeScript `enum`, and it is deprecated in Zod v4, so it ties the schema to a construct the codebase avoids and to an API that will be removed. A const object with `as const` plus `z.enum` over its values gives the same runtime check with a plain object that is grep-friendly, tree-shakeable, and stays valid across Zod upgrades. The type comes from the same object, so there is still one source of truth.
+
+## Message
+
+`z.nativeEnum` is deprecated; use `z.enum` over the values of a const object
+
+## Bad
+
+```ts
+// BAD: deprecated in Zod v4 and tied to a TypeScript enum
+const prioritySchema = z.nativeEnum(Priority);
+```
+
+## Good
+
+```ts
+const Priority = {
+	LOW: 'low',
+	HIGH: 'high',
+} as const;
+
+type Priority = (typeof Priority)[keyof typeof Priority];
+
+const priorityValues = Object.values(Priority) as [Priority, ...Priority[]];
+const prioritySchema = z.enum(priorityValues);
+```

package/rules/ts/futureproof/zod/schema-first-infer-type.md

@@ -0,0 +1,46 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - types that describe internal state, function options, or return shapes that are never validated at runtime
+    - a type that is deliberately narrower or wider than the schema, such as a branded id, with a comment saying why
+    - types generated by another tool, such as an ORM or an API client, that the schema merely mirrors
+---
+
+## Why
+
+Writing a `type` by hand and then a Zod schema that describes the same shape creates two definitions that agree today and drift the first time one of them is edited, with the compiler unable to notice. Define the schema once and derive the type with `z.infer`, so the runtime check and the static type cannot disagree. Input variants come from the schema too, through `omit`, `pick`, and `partial`.
+
+## Message
+
+hand-written type duplicates a schema; derive it with `z.infer`
+
+## Bad
+
+```ts
+// BAD: two definitions of the same shape that nothing keeps in sync
+type Item = {
+	id: string;
+	name: string;
+};
+
+const itemSchema = z.object({
+	id: z.string(),
+	name: z.string(),
+});
+```
+
+## Good
+
+```ts
+const itemSchema = z.object({
+	id: z.string(),
+	name: z.string(),
+});
+
+type Item = z.infer<typeof itemSchema>;
+
+const createItemSchema = itemSchema.omit({ id: true });
+
+type CreateItemInput = z.infer<typeof createItemSchema>;
+```