@aarock1234/slopscan 0.1.0

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

@@ -0,0 +1,54 @@
+---
+severity: major
+detect: judge
+falsePositives:
+    - '`as const` on a literal, which narrows rather than widens'
+    - a cast inside a branded-type constructor such as `return id as UserId`, where the function is the single point that mints the brand
+    - a cast that follows a runtime check in the same block, such as after `typeof`, `in`, or `Array.isArray`
+    - a cast to `unknown` on its own, which discards type information rather than inventing it
+---
+
+## Why
+
+`value as T` does not check anything at runtime; it tells the compiler to stop looking. Used on data that came from outside the program, such as a request body, a parsed file, a database row, or an environment variable, it turns a type error into a crash or silent corruption somewhere downstream. Validate external data with a schema or a type guard and let the type come from the check.
+
+## Message
+
+type assertion on unvalidated data; validate with a schema or a type guard instead
+
+## Bad
+
+```ts
+app.post('/users', async (req, res) => {
+	// BAD: whatever the client sent is now a CreateUserInput as far as the compiler knows
+	const input = req.body as CreateUserInput;
+
+	res.json(await createUser(input));
+});
+```
+
+```ts
+// BAD: env vars may be undefined; the cast promises otherwise
+const apiKey = process.env.API_KEY as string;
+```
+
+## Good
+
+```ts
+app.post('/users', async (req, res) => {
+	const input = createUserSchema.parse(req.body);
+
+	res.json(await createUser(input));
+});
+```
+
+```ts
+const env = envSchema.parse(process.env);
+const apiKey = env.API_KEY;
+```
+
+```ts
+function UserId(id: string): UserId {
+	return id as UserId;
+}
+```

package/rules/ts/hacky/type-safety/validate-parsed-json.md

@@ -0,0 +1,48 @@
+---
+severity: major
+detect: ast
+ast:
+    rule:
+        any:
+            - pattern: JSON.parse($$$ARGS) as $T
+            - pattern: 'const $X: $T = JSON.parse($$$ARGS)'
+    constraints:
+        T:
+            not:
+                regex: '^unknown$'
+---
+
+## Why
+
+`JSON.parse` returns whatever the text contained, and a cast or annotation on the result is a promise the program cannot keep. The first malformed file or changed API payload then fails deep inside code that trusted the shape, with an error that says nothing about the real cause. Parse to `unknown` and run the result through a schema so the failure is caught at the boundary with a message that names the bad field.
+
+## Message
+
+`JSON.parse` result cast to a type without validation; parse it through a schema
+
+## Bad
+
+```ts
+// BAD: the shape of raw is asserted, not checked
+const config = JSON.parse(raw) as Config;
+```
+
+```ts
+// BAD: annotation is a cast in disguise
+const config: Config = JSON.parse(raw);
+```
+
+## Good
+
+```ts
+const config = configSchema.parse(JSON.parse(raw));
+```
+
+```ts
+const data: unknown = JSON.parse(raw);
+const result = configSchema.safeParse(data);
+
+if (!result.success) {
+	throw new ConfigError('invalid config', { cause: result.error });
+}
+```

package/rules/ts/idiom/async/no-promise-chains.md

@@ -0,0 +1,45 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        any:
+            - pattern: $P.then($$$ARGS)
+            - pattern: $P.catch($$$ARGS)
+            - pattern: $P.finally($$$ARGS)
+---
+
+## Why
+
+`async`/`await` reads top to bottom and keeps error handling in an ordinary `try`. Promise chains split the same logic across callbacks, lose stack context, and make the return value of the surrounding function harder to see.
+
+## Message
+
+promise chain; use async/await
+
+## Bad
+
+```ts
+function loadUser(id: string) {
+	// BAD: callback chain where a straight line would do
+	return fetchUser(id)
+		.then(user => enrich(user))
+		.catch(error => report(error));
+}
+```
+
+## Good
+
+```ts
+async function loadUser(id: string): Promise<User> {
+	try {
+		const user = await fetchUser(id);
+
+		return await enrich(user);
+	} catch (error) {
+		report(error);
+
+		throw error;
+	}
+}
+```

package/rules/ts/idiom/async/parallelize-independent-awaits.md

@@ -0,0 +1,46 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - awaits where a later call uses the result of an earlier one, or where order matters for side effects such as writes
+    - operations against a resource that must not see concurrent calls, such as a single database transaction or a rate-limited API
+    - a sequence deliberately kept serial with a comment explaining why
+---
+
+## Why
+
+Awaiting independent calls one after another makes the total latency the sum of the parts when it could be the slowest one. `Promise.all` runs them together and still gives typed results in order, and `Promise.allSettled` does the same when each result should be handled on its own. Serial awaits are right when one call feeds the next or when the resource cannot take concurrent calls; otherwise they are a slow habit.
+
+## Message
+
+independent awaits run one after another; run them together with `Promise.all`
+
+## Bad
+
+```ts
+// BAD: three round trips in sequence that share no data
+async function loadProfile(userId: string): Promise<Profile> {
+	const user = await getUser(userId);
+	const posts = await getPosts(userId);
+	const followers = await getFollowers(userId);
+
+	return { user, posts, followers };
+}
+```
+
+## Good
+
+```ts
+async function loadProfile(userId: string): Promise<Profile> {
+	const [user, posts, followers] = await Promise.all([getUser(userId), getPosts(userId), getFollowers(userId)]);
+
+	return { user, posts, followers };
+}
+```
+
+```ts
+async function moveFunds(from: string, to: string, amount: number): Promise<void> {
+	await debit(from, amount);
+	await credit(to, amount);
+}
+```

package/rules/ts/idiom/comments/doc-comment-above-declaration.md

@@ -0,0 +1,43 @@
+---
+severity: info
+detect: judge
+falsePositives:
+    - a short trailing comment on a single value inside an object or array literal, such as a unit or a magic number's meaning
+    - 'directive comments such as `eslint-disable` or `@ts-expect-error`, which must sit where the tool expects them'
+    - a comment on a line of its own inside a function body that explains the following statement
+---
+
+## Why
+
+A comment that documents a declaration belongs on the line directly above it, as a `//` or `/** */` block, so editors show it on hover and a reader finds it before the signature rather than after. A trailing comment at the end of a declaration line is easy to miss, wraps badly, and is not picked up as documentation. Explanations inside the body of a function describe the body, not the contract.
+
+## Message
+
+declaration documented in a trailing comment; put the comment on the line above
+
+## Bad
+
+```ts
+// BAD: the doc is a trailing comment the tooling cannot see
+export function parseDuration(input: string): number { // parses "5m", "2h" into milliseconds
+	return toMilliseconds(input);
+}
+```
+
+## Good
+
+```ts
+// parses "5m" or "2h" into milliseconds
+export function parseDuration(input: string): number {
+	return toMilliseconds(input);
+}
+```
+
+```ts
+/**
+ * retries the operation up to three times with exponential backoff, then rethrows
+ */
+export function retry<T>(operation: () => Promise<T>): Promise<T> {
+	return withBackoff(operation, 3);
+}
+```

package/rules/ts/idiom/constants/as-const-for-literal-config.md

@@ -0,0 +1,65 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        pattern: const $NAME = $OBJ
+        inside:
+            any:
+                - kind: program
+                - kind: export_statement
+    constraints:
+        NAME:
+            regex: '^[A-Z]'
+        OBJ:
+            kind: object
+            has:
+                kind: pair
+            not:
+                has:
+                    kind: pair
+                    has:
+                        field: value
+                        not:
+                            any:
+                                - kind: string
+                                - kind: number
+---
+
+## Why
+
+A PascalCase const object of literal values is meant to act as an enum, but without `as const` every value widens to `string` or `number`, so `typeof Status[keyof typeof Status]` is just `string` and the compiler cannot check a switch over it. Adding `as const` freezes the values to their literals, makes the derived union real, and marks the object as readonly at the type level. It is the difference between a named constant set and a bag of strings.
+
+## Message
+
+literal const object without `as const`; its values widen to `string`
+
+## Bad
+
+```ts
+// BAD: Status.PENDING is typed as string, not 'pending'
+const Status = {
+	PENDING: 'pending',
+	ACTIVE: 'active',
+};
+
+type Status = (typeof Status)[keyof typeof Status];
+```
+
+## Good
+
+```ts
+const Status = {
+	PENDING: 'pending',
+	ACTIVE: 'active',
+} as const;
+
+type Status = (typeof Status)[keyof typeof Status];
+```
+
+```ts
+const defaults = {
+	timeout: 5000,
+	retries: 3,
+};
+```

package/rules/ts/idiom/constants/no-enum.md

@@ -0,0 +1,37 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: enum_declaration
+---
+
+## Why
+
+TypeScript enums are a runtime construct with their own semantics: numeric enums accept any number, `const enum` behaves differently under isolated modules, and they do not compose with string literal unions or Zod. A const object with `as const` plus a derived union type gives the same ergonomics with plain objects and plain strings.
+
+## Message
+
+enum is a runtime construct; use a const object with `as const` and a derived union
+
+## Bad
+
+```ts
+// BAD: a runtime enum with numeric holes
+enum Status {
+	Active,
+	Inactive,
+}
+```
+
+## Good
+
+```ts
+// GOOD: a const object and its derived union
+export const Status = {
+	ACTIVE: 'active',
+	INACTIVE: 'inactive',
+} as const;
+
+export type Status = (typeof Status)[keyof typeof Status];
+```

package/rules/ts/idiom/control-flow/always-brace-if.md

@@ -0,0 +1,56 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        any:
+            - kind: if_statement
+              not:
+                  has:
+                      field: consequence
+                      kind: statement_block
+            - kind: else_clause
+              not:
+                  has:
+                      any:
+                          - kind: statement_block
+                          - kind: if_statement
+---
+
+## Why
+
+A braceless `if (x) return;` works until someone adds a second statement under it and only the first one stays conditional. Braces make the body a visible block, keep the diff small when a line is added, and remove a whole class of indentation bugs. The two extra characters cost nothing to read.
+
+## Message
+
+braceless `if` body; wrap it in a block
+
+## Bad
+
+```ts
+// BAD: a second statement added here would run unconditionally
+if (!user) return undefined;
+```
+
+```ts
+if (user.isActive) {
+	activate(user);
+// BAD: braceless else body
+} else deactivate(user);
+```
+
+## Good
+
+```ts
+if (!user) {
+	return undefined;
+}
+
+if (user.isActive) {
+	activate(user);
+} else if (user.isPending) {
+	remind(user);
+} else {
+	deactivate(user);
+}
+```

package/rules/ts/idiom/control-flow/guard-clauses-early-return.md

@@ -0,0 +1,52 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - a single `if` with an `else` where both branches are one or two lines and neither is an error path
+    - branches that must run cleanup or logging before returning, where flattening would duplicate that code
+    - a `switch` or a chain of `if` returning a value per case, which is already flat
+---
+
+## Why
+
+Nesting the happy path inside a pyramid of `if` blocks pushes the code the function exists for to the deepest indentation and makes every reader hold the whole condition stack in their head. Checking preconditions first and returning or throwing early keeps the main logic at the top level, reads in the order the cases are decided, and makes each failure case a self-contained line. The result is shorter, flatter, and easier to change.
+
+## Message
+
+nested conditionals wrap the happy path; check preconditions first and return early
+
+## Bad
+
+```ts
+// BAD: the update is buried two levels deep under checks that could exit early
+async function updateUser(id: string, input: UpdateUserInput): Promise<User> {
+	const user = await repository.find(id);
+	if (user) {
+		if (user.isActive) {
+			return repository.update(id, input);
+		} else {
+			throw new ForbiddenError(`user ${id} is deactivated`);
+		}
+	} else {
+		throw new NotFoundError(`user ${id}`);
+	}
+}
+```
+
+## Good
+
+```ts
+async function updateUser(id: string, input: UpdateUserInput): Promise<User> {
+	const user = await repository.find(id);
+
+	if (!user) {
+		throw new NotFoundError(`user ${id}`);
+	}
+
+	if (!user.isActive) {
+		throw new ForbiddenError(`user ${id} is deactivated`);
+	}
+
+	return repository.update(id, input);
+}
+```

package/rules/ts/idiom/control-flow/no-nested-ternary.md

@@ -0,0 +1,54 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: ternary_expression
+        inside:
+            kind: ternary_expression
+            stopBy:
+                not:
+                    kind: parenthesized_expression
+---
+
+## Why
+
+A ternary is readable when it has one condition and two outcomes. Nesting another inside turns it into a puzzle the reader has to unfold, and the precedence rules do not help. Use an if chain, a switch, or a lookup object.
+
+## Message
+
+nested ternary; use an if chain, a switch, or a lookup
+
+## Bad
+
+```ts
+// BAD: three outcomes folded into one expression
+const label = count === 0 ? 'none' : count === 1 ? 'one' : 'many';
+```
+
+## Good
+
+```ts
+// GOOD: a ternary inside a callback is its own expression, not a nested branch
+const handler = isEnabled ? () => (isDark ? darkTheme : lightTheme) : undefined;
+```
+
+```ts
+// GOOD: one condition, two outcomes
+const label = isEmpty ? 'none' : 'some';
+```
+
+```ts
+// GOOD: a function names the branching
+function describeCount(count: number): string {
+	if (count === 0) {
+		return 'none';
+	}
+
+	if (count === 1) {
+		return 'one';
+	}
+
+	return 'many';
+}
+```

package/rules/ts/idiom/errors/error-message-lowercase.md

@@ -0,0 +1,56 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        any:
+            - pattern: new $CLS($MSG)
+            - pattern: new $CLS($MSG, $$$REST)
+    constraints:
+        CLS:
+            regex: 'Error$'
+        MSG:
+            regex: '^.[A-Z][a-z]'
+---
+
+## Why
+
+Error messages get wrapped and joined with other messages, as in `loading config: reading file: permission denied`, and a capitalized fragment in the middle of that chain reads like a new sentence. Messages are lowercase fragments without trailing punctuation so they compose cleanly and match the log lines around them. Acronyms and proper nouns at the start are fine.
+
+## Message
+
+error message starts with a capital letter; write it as a lowercase fragment
+
+## Bad
+
+```ts
+if (!config) {
+	// BAD: capitalized message reads wrong once it is wrapped
+	throw new Error('Config file is missing');
+}
+```
+
+```ts
+if (!user) {
+	// BAD: capitalized message in a custom error
+	throw new NotFoundError(`User ${id} does not exist`, 404);
+}
+```
+
+## Good
+
+```ts
+if (!config) {
+	throw new ConfigError('config file is missing');
+}
+```
+
+```ts
+if (!user) {
+	throw new NotFoundError(`user ${id} does not exist`);
+}
+```
+
+```ts
+throw new UpstreamError('HTTP 502 from payments service');
+```

package/rules/ts/idiom/errors/log-at-boundary-not-every-layer.md

@@ -0,0 +1,66 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - a catch that logs and then handles the error without rethrowing, such as falling back to a default or skipping one item in a batch
+    - the outermost handler, controller, job runner, or CLI entrypoint, which is the boundary and should log
+    - a catch that adds context by wrapping the error in a typed error before rethrowing, without logging
+---
+
+## Why
+
+When every layer catches an error, logs it, and rethrows, one failure produces a stack of near-identical log lines and the boundary that finally handles it logs it again. Errors should propagate untouched, or wrapped with context, until they reach the boundary, such as the request handler or the job runner, where they are logged once with full context and turned into a response. Inner layers that only log and rethrow are noise generators.
+
+## Message
+
+catch logs and rethrows in an inner layer; let it propagate and log once at the boundary
+
+## Bad
+
+```ts
+class UserService {
+	async getUser(id: string): Promise<User> {
+		try {
+			return await this.repository.find(id);
+		} catch (error) {
+			// BAD: the handler above will log this same error again
+			this.logger.error('get user failed', { error });
+
+			throw error;
+		}
+	}
+}
+```
+
+## Good
+
+```ts
+class UserService {
+	async getUser(id: string): Promise<User> {
+		const user = await this.repository.find(id);
+
+		if (!user) {
+			throw new NotFoundError(`user ${id}`);
+		}
+
+		return user;
+	}
+}
+```
+
+```ts
+async function handleGetUser(req: Request, res: Response): Promise<void> {
+	try {
+		res.json(await userService.getUser(req.params.id));
+	} catch (error: unknown) {
+		if (error instanceof NotFoundError) {
+			res.status(404).json({ error: error.message });
+
+			return;
+		}
+
+		logger.error('get user failed', { error, userId: req.params.id });
+		res.status(500).json({ error: 'internal error' });
+	}
+}
+```

package/rules/ts/idiom/exports/inline-export-at-declaration.md

@@ -0,0 +1,49 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: export_statement
+        has:
+            kind: export_clause
+        not:
+            has:
+                field: source
+                kind: string
+---
+
+## Why
+
+An export list at the bottom of a file separates the decision to export from the thing being exported, so a reader looking at a declaration cannot tell whether it is public without scrolling. Exporting at the declaration site keeps that intent next to the code and means a rename or removal touches one place instead of two. Re-exports from another module are a different construct and are fine.
+
+## Message
+
+export list detached from its declarations; export at the declaration site
+
+## Bad
+
+```ts
+const MAX_RETRIES = 3;
+
+function getUser(id: string): Promise<User> {
+	return repository.find(id);
+}
+
+// BAD: the export decision lives far from the declarations
+export { MAX_RETRIES, getUser };
+```
+
+## Good
+
+```ts
+export const MAX_RETRIES = 3;
+
+export function getUser(id: string): Promise<User> {
+	return repository.find(id);
+}
+```
+
+```ts
+export { createUser } from './user';
+export type { User } from './user';
+```