@aarock1234/slopscan 0.1.0

package/rules/ts/hacky/async/no-floating-promises.md

@@ -0,0 +1,52 @@
+---
+severity: major
+detect: judge
+falsePositives:
+    - a promise explicitly discarded with `void` and a comment saying why, such as fire-and-forget telemetry
+    - a promise stored in a variable or array and awaited later, including through `Promise.all`
+    - a call that returns something other than a promise, when the return type is visible in the diff or obvious from the name
+---
+
+## Why
+
+A promise nobody awaits or returns keeps running with nobody watching: its rejection is not caught by the surrounding `try`, the function returns before the work is done, and depending on the runtime the failure is either an unhandled rejection that kills the process or a warning nobody reads. Every promise should be awaited, returned, collected for a later `Promise.all`, or discarded on purpose with `void` and a reason.
+
+## Message
+
+promise is neither awaited nor returned; its rejection is lost
+
+## Bad
+
+```ts
+async function createUser(input: CreateUserInput): Promise<User> {
+	const user = await repository.insert(input);
+
+	// BAD: a failed email send rejects into the void
+	sendWelcomeEmail(user);
+
+	return user;
+}
+```
+
+## Good
+
+```ts
+async function createUser(input: CreateUserInput): Promise<User> {
+	const user = await repository.insert(input);
+
+	await sendWelcomeEmail(user);
+
+	return user;
+}
+```
+
+```ts
+async function createUser(input: CreateUserInput): Promise<User> {
+	const user = await repository.insert(input);
+
+	// the email is best-effort and failures are logged inside the mailer
+	void sendWelcomeEmail(user);
+
+	return user;
+}
+```

package/rules/ts/hacky/config/env-read-outside-config.md

@@ -0,0 +1,56 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        any:
+            - pattern: process.env.$NAME
+            - pattern: process.env[$NAME]
+            - pattern: import.meta.env.$NAME
+ignore:
+    - '**/config/**'
+    - '**/config.ts'
+    - '**/env.ts'
+    - '**/env/**'
+    - '**/*.config.ts'
+    - '**/*.config.mts'
+    - '**/*.test.ts'
+    - '**/*.spec.ts'
+    - '**/scripts/**'
+---
+
+## Why
+
+Reading `process.env` in the middle of a module scatters the list of variables the program needs across the codebase, so nobody can say what a deployment requires without grepping. Each read is an untyped, possibly undefined string that gets parsed and defaulted differently in every place. Read and validate the environment once in a config module and pass typed values from there.
+
+## Message
+
+environment read outside the config module; validate env once and pass typed config
+
+## Bad
+
+```ts
+export async function sendEmail(message: Message): Promise<void> {
+	// BAD: an untyped, unvalidated read buried in logic
+	const apiKey = process.env.SENDGRID_API_KEY;
+
+	await client.send(apiKey ?? '', message);
+}
+```
+
+```ts
+// BAD: the same variable is parsed differently in every module that reads it
+const timeoutMs = Number(process.env['HTTP_TIMEOUT_MS'] ?? 5000);
+```
+
+## Good
+
+```ts
+export async function sendEmail(config: EmailConfig, message: Message): Promise<void> {
+	await client.send(config.apiKey, message);
+}
+```
+
+```ts
+const timeoutMs = config.http.timeoutMs;
+```

package/rules/ts/hacky/errors/catch-param-typed-unknown.md

@@ -0,0 +1,67 @@
+---
+severity: major
+detect: ast
+ast:
+    rule:
+        any:
+            - kind: catch_clause
+              has:
+                  field: type
+                  regex: 'any'
+            - pattern: $E as Error
+              inside:
+                  kind: catch_clause
+                  stopBy: end
+---
+
+## Why
+
+Anything can be thrown in JavaScript, so a catch parameter is `unknown` and the only honest way to read `.message` is to check `instanceof Error` first. Typing the parameter as `any` or casting it with `as Error` skips that check, and the first time a string or a rejected fetch body is thrown the handler itself crashes on an undefined property. Narrow with `instanceof`, or normalize with `error instanceof Error ? error : new Error(String(error))`.
+
+## Message
+
+catch parameter treated as `Error` without a check; keep it `unknown` and narrow with `instanceof`
+
+## Bad
+
+```ts
+try {
+	await save(user);
+// BAD: any disables checking on whatever was thrown
+} catch (error: any) {
+	logger.error(error.message);
+}
+```
+
+```ts
+try {
+	await save(user);
+} catch (error) {
+	// BAD: the cast crashes the handler if a non-Error was thrown
+	logger.error((error as Error).message);
+}
+```
+
+## Good
+
+```ts
+try {
+	await save(user);
+} catch (error: unknown) {
+	if (error instanceof Error) {
+		logger.error(error.message);
+	}
+
+	throw error;
+}
+```
+
+```ts
+try {
+	await save(user);
+} catch (error: unknown) {
+	const cause = error instanceof Error ? error : new Error(String(error));
+
+	throw new SaveError('saving user failed', { cause });
+}
+```

package/rules/ts/hacky/errors/custom-error-class-instanceof.md

@@ -0,0 +1,66 @@
+---
+severity: minor
+detect: ast
+ignore:
+    - '**/*.test.ts'
+    - '**/*.spec.ts'
+ast:
+    rule:
+        any:
+            - pattern: $E.message === $S
+            - pattern: $E.message == $S
+            - pattern: $E.message.includes($$$ARGS)
+            - pattern: $E.message.startsWith($$$ARGS)
+            - pattern: $E.message.match($$$ARGS)
+---
+
+## Why
+
+Branching on the text of an error message couples the caller to a string that was written for humans and will be reworded without anyone checking the callers. A custom error class gives the failure a name, an `instanceof` check that survives rewording, and a place to hang structured fields such as a status code or the offending id. Expected failures get their own class; message matching is left for logs.
+
+## Message
+
+branching on error message text; throw a custom error class and check `instanceof`
+
+## Bad
+
+```ts
+try {
+	await getUser(id);
+} catch (error: unknown) {
+	// BAD: a reworded message silently turns this into a 500
+	if (error instanceof Error && error.message === 'user not found') {
+		res.status(404).end();
+	}
+}
+```
+
+```ts
+try {
+	await connect();
+} catch (error: unknown) {
+	// BAD: substring matching on prose
+	if (error instanceof Error && error.message.includes('timeout')) {
+		return retry();
+	}
+}
+```
+
+## Good
+
+```ts
+class NotFoundError extends Error {
+	constructor(resource: string) {
+		super(`${resource} not found`);
+		this.name = 'NotFoundError';
+	}
+}
+
+try {
+	await getUser(id);
+} catch (error: unknown) {
+	if (error instanceof NotFoundError) {
+		res.status(404).end();
+	}
+}
+```

package/rules/ts/hacky/errors/empty-catch.md

@@ -0,0 +1,52 @@
+---
+severity: critical
+detect: ast
+ast:
+    rule:
+        kind: catch_clause
+        has:
+            kind: statement_block
+            regex: '^\{\s*\}$'
+---
+
+## Why
+
+An empty catch swallows the failure and lets the program continue in a state nobody designed for. The bug surfaces later, somewhere else, with no stack trace pointing home. Handle the error, rethrow it with context, or let it propagate. If ignoring it really is correct, the block needs a comment saying why, which makes it non-empty.
+
+## Message
+
+empty catch swallows the error; handle it, rethrow with context, or let it propagate
+
+## Bad
+
+```ts
+try {
+	await save(record);
+	// BAD: the failure vanishes
+} catch {}
+```
+
+```ts
+try {
+	await save(record);
+	// BAD: binding the error and dropping it is still swallowing
+} catch (error) {}
+```
+
+## Good
+
+```ts
+try {
+	await save(record);
+} catch (error) {
+	throw new PersistenceError(`saving record ${record.id}`, { cause: error });
+}
+```
+
+```ts
+try {
+	await removeTempFile(path);
+} catch {
+	// the file is already gone, which is the state we wanted
+}
+```

package/rules/ts/hacky/errors/log-and-swallow.md

@@ -0,0 +1,65 @@
+---
+severity: major
+detect: ast
+ast:
+    rule:
+        kind: catch_clause
+        has:
+            kind: statement_block
+            regex: '^\{\s*(?:(?:console|log|logger|this\.logger|this\.log)\.\w+\([^;]*\);?\s*)+\}$'
+---
+
+## Why
+
+Logging an error and carrying on is an empty catch with a paper trail: the caller gets a normal return and proceeds as if the operation succeeded, so the failure surfaces later as bad data or a confusing second error. The log line is rarely read until then. Rethrow with context, return an explicit failure the caller must handle, or, if continuing really is correct, say why in a comment so the choice is visible.
+
+## Message
+
+catch only logs and continues; rethrow with context or return an explicit failure
+
+## Bad
+
+```ts
+async function saveDraft(draft: Draft): Promise<void> {
+	try {
+		await repo.save(draft);
+		// BAD: the caller is told nothing and proceeds as if the save worked
+	} catch (error) {
+		console.error('failed to save draft', error);
+	}
+}
+```
+
+```ts
+async function saveDraft(draft: Draft): Promise<void> {
+	try {
+		await repo.save(draft);
+		// BAD: a structured logger does not change what the caller sees
+	} catch (error) {
+		logger.error({ error, draftId: draft.id }, 'failed to save draft');
+	}
+}
+```
+
+## Good
+
+```ts
+async function saveDraft(draft: Draft): Promise<void> {
+	try {
+		await repo.save(draft);
+	} catch (error) {
+		throw new PersistenceError(`saving draft ${draft.id}`, { cause: error });
+	}
+}
+```
+
+```ts
+async function warmCache(): Promise<void> {
+	try {
+		await cache.preload();
+	} catch (error) {
+		// a cold cache only costs latency, and the request path fills it on demand
+		logger.warn({ error }, 'cache preload failed, continuing cold');
+	}
+}
+```

package/rules/ts/hacky/errors/throw-typed-error-with-context.md

@@ -0,0 +1,64 @@
+---
+severity: minor
+detect: ast
+ignore:
+    - '**/*.test.ts'
+    - '**/*.spec.ts'
+ast:
+    rule:
+        pattern: throw new Error($MSG)
+    constraints:
+        MSG:
+            kind: string
+---
+
+## Why
+
+A bare `new Error('...')` with a fixed string gives the catcher nothing to branch on except the message text, and it carries no context about which record or input failed. A typed error class can be checked with `instanceof` and mapped to a status code at the boundary, and a message built from the inputs tells the on-call engineer what actually went wrong. Reserve plain `Error` for true invariants such as the `never` branch of an exhaustive switch, and even then include the value.
+
+## Message
+
+bare `Error` with a fixed message; throw a typed error that carries context
+
+## Bad
+
+```ts
+async function getUser(id: string): Promise<User> {
+	const user = await repository.find(id);
+
+	if (!user) {
+		// BAD: nothing to branch on and no hint of which user was missing
+		throw new Error('user not found');
+	}
+
+	return user;
+}
+```
+
+## Good
+
+```ts
+async function getUser(id: string): Promise<User> {
+	const user = await repository.find(id);
+
+	if (!user) {
+		throw new NotFoundError(`user ${id}`);
+	}
+
+	return user;
+}
+```
+
+```ts
+function label(status: Status): string {
+	switch (status) {
+		case Status.ACTIVE:
+			return 'running';
+		default: {
+			const exhaustive: never = status;
+
+			throw new Error(`unhandled status: ${String(exhaustive)}`);
+		}
+	}
+}
+```

package/rules/ts/hacky/operators/nullish-coalescing-over-or.md

@@ -0,0 +1,50 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: binary_expression
+        all:
+            - has:
+                  field: operator
+                  regex: '^\|\|$'
+            - has:
+                  field: right
+                  any:
+                      - kind: string
+                      - kind: number
+                      - kind: object
+                      - kind: array
+                      - kind: template_string
+---
+
+## Why
+
+`value || fallback` replaces every falsy value, so a legitimate `0`, empty string, or `false` is silently swapped for the default and the bug only shows up when someone sets a timeout to zero or clears a name. `??` falls back only on `null` and `undefined`, which is what a default is for. Use `||` only when a falsy value really should be treated as missing, and say so.
+
+## Message
+
+`||` with a default replaces 0, empty string, and false; use `??`
+
+## Bad
+
+```ts
+// BAD: a timeout of 0 becomes 5000
+const timeout = options.timeout || 5000;
+```
+
+```ts
+// BAD: an empty name becomes 'anonymous' even when it was set on purpose
+const name = user.name || 'anonymous';
+```
+
+## Good
+
+```ts
+const timeout = options.timeout ?? 5000;
+const name = user.name ?? 'anonymous';
+```
+
+```ts
+const canEdit = isOwner || isAdmin;
+```

package/rules/ts/hacky/state/exported-let.md

@@ -0,0 +1,60 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: export_statement
+        has:
+            any:
+                - kind: lexical_declaration
+                  regex: '^let\b'
+                - kind: variable_declaration
+ignore:
+    - '**/*.test.ts'
+    - '**/*.spec.ts'
+---
+
+## Why
+
+An exported `let` is global mutable state: any importer can reassign it, and no reader of the module can know its value at a given moment without tracing every import. Tests that touch it leak into each other, and reloading or running two instances in one process breaks. Keep the state inside a function, class, or factory and expose operations on it, or export a `const`.
+
+## Message
+
+exported let is global mutable state; expose functions over the state or export a const
+
+## Bad
+
+```ts
+// BAD: any importer can reassign this
+export let currentUser: User | undefined;
+
+export function login(user: User): void {
+	currentUser = user;
+}
+```
+
+```ts
+// BAD: var is hoisted and reassignable from anywhere
+export var requestCount = 0;
+```
+
+## Good
+
+```ts
+export function createSession(): Session {
+	let currentUser: User | undefined;
+
+	return {
+		login(user: User): void {
+			currentUser = user;
+		},
+		current(): User | undefined {
+			return currentUser;
+		},
+	};
+}
+```
+
+```ts
+export const DEFAULT_PAGE_SIZE = 50;
+```

package/rules/ts/hacky/type-safety/no-double-assertion.md

@@ -0,0 +1,34 @@
+---
+severity: major
+detect: ast
+ast:
+    rule:
+        pattern: $X as unknown as $T
+---
+
+## Why
+
+`x as unknown as T` exists to defeat the one check a single `as` still performs, that the two types overlap. It converts any value into any type with no runtime check and no compiler objection, which is `any` with extra steps. If the value really is a `T`, a type guard or a schema can prove it; if it is not, the cast just moves the crash somewhere harder to debug.
+
+## Message
+
+double assertion through `unknown` bypasses all checking; validate or narrow instead
+
+## Bad
+
+```ts
+// BAD: the compiler has been told to accept anything here
+const user = row as unknown as User;
+```
+
+## Good
+
+```ts
+const user = userSchema.parse(row);
+```
+
+```ts
+if (isUser(row)) {
+	return row;
+}
+```

package/rules/ts/hacky/type-safety/no-explicit-any.md

@@ -0,0 +1,48 @@
+---
+severity: major
+detect: ast
+ast:
+    rule:
+        kind: predefined_type
+        regex: ^any$
+---
+
+## Why
+
+`any` switches the type checker off for everything it touches, and the hole spreads through every call site. Prefer a real type, then a generic, then `Record<string, T>`, then `unknown` narrowed at the point of use. `any` is the last resort, and it needs a comment saying why.
+
+## Message
+
+`any` disables type checking; use a real type, a generic, or `unknown`
+
+## Bad
+
+```ts
+// BAD: any hides the shape of the payload
+function handle(payload: any) {
+	return payload.user.id;
+}
+```
+
+```ts
+// BAD: Record<string, any> is any with extra steps
+const cache: Record<string, any> = {};
+```
+
+## Good
+
+```ts
+// GOOD: unknown forces narrowing before use
+function handle(payload: unknown) {
+	const parsed = payloadSchema.parse(payload);
+
+	return parsed.user.id;
+}
+```
+
+```ts
+// GOOD: a generic keeps the caller's type
+function first<T>(items: readonly T[]): T | undefined {
+	return items[0];
+}
+```

package/rules/ts/hacky/type-safety/no-non-null-assertion.md

@@ -0,0 +1,43 @@
+---
+severity: major
+detect: ast
+ignore:
+    - '**/*.test.ts'
+    - '**/*.test.tsx'
+ast:
+    rule:
+        kind: non_null_expression
+---
+
+## Why
+
+The `!` operator tells the compiler to trust you and turns a compile-time question into a runtime crash. Narrow with a guard, use optional chaining with a default, or throw an error that says what was missing. Tests are excluded because a failing assertion there is the intended outcome.
+
+## Message
+
+non-null assertion trades a compile-time check for a runtime crash; narrow or throw
+
+## Bad
+
+```ts
+// BAD: crashes with a bare TypeError when the user is missing
+const name = users.find(user => user.id === id)!.name;
+```
+
+## Good
+
+```ts
+// GOOD: the missing case has a name and a message
+const user = users.find(candidate => candidate.id === id);
+
+if (user === undefined) {
+	throw new NotFoundError(`user ${id}`);
+}
+
+const name = user.name;
+```
+
+```ts
+// GOOD: optional chaining with a default when absence is fine
+const name = users.find(user => user.id === id)?.name ?? 'anonymous';
+```