@aarock1234/slopscan 0.1.0

package/rules/ts/idiom/types/null-vs-undefined-convention.md

@@ -0,0 +1,43 @@
+---
+severity: info
+detect: judge
+falsePositives:
+    - values that come from an external API, database column, or library that itself uses `null`, where mirroring it is the honest type
+    - React state initialized with `null` to mean not yet loaded or no selection
+    - optional properties declared with `?`, which are `undefined` by definition
+---
+
+## Why
+
+`undefined` is what the language produces for structural absence: a missing property, a `Map.get` miss, an `Array.find` with no hit. `null` is a value a developer chooses to mean "explicitly nothing", such as no selection or no error. Returning `null` from a lookup, or writing `foo: string | undefined` where the author means a deliberate empty state, mixes the two and makes callers check for both.
+
+## Message
+
+null and undefined used interchangeably; undefined for absence, null for a deliberate empty value
+
+## Bad
+
+```ts
+// BAD: a lookup miss is structural absence, which the language already spells undefined
+function findUser(id: string): User | null {
+	const user = users.get(id);
+
+	return user === undefined ? null : user;
+}
+```
+
+## Good
+
+```ts
+function findUser(id: string): User | undefined {
+	return users.get(id);
+}
+```
+
+```ts
+type Form = {
+	selectedUser: User | null;
+};
+
+const [error, setError] = useState<string | null>(null);
+```

package/rules/ts/idiom/types/prefer-type-over-interface.md

@@ -0,0 +1,64 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: interface_declaration
+        not:
+            any:
+                - has:
+                      kind: extends_type_clause
+                - inside:
+                      kind: ambient_declaration
+                      stopBy: end
+                - has:
+                      kind: interface_body
+                      has:
+                          kind: method_signature
+---
+
+## Why
+
+A plain data shape is a `type`: it composes with unions, intersections, mapped types, and `z.infer` in one syntax, and it cannot be silently reopened by declaration merging somewhere else in the program. `interface` earns its place when you extend another shape, define a contract that classes implement, or deliberately augment a global. An interface with only properties and no `extends` is a `type` with an extra way to go wrong.
+
+## Message
+
+plain data shape declared as `interface`; use `type`
+
+## Bad
+
+```ts
+// BAD: a data shape that gains nothing from being an interface
+interface User {
+	id: string;
+	name: string;
+}
+```
+
+## Good
+
+```ts
+type User = {
+	id: string;
+	name: string;
+};
+```
+
+```ts
+interface Admin extends User {
+	role: 'admin';
+}
+
+interface Repository<T> {
+	findById(id: string): Promise<T | undefined>;
+	save(item: T): Promise<void>;
+}
+```
+
+```ts
+declare global {
+	interface Window {
+		analytics: Analytics;
+	}
+}
+```

package/rules/ts/idiom/types/satisfies-over-annotation.md

@@ -0,0 +1,43 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        pattern: 'const $NAME: Record<$K, $V> = $OBJ'
+    constraints:
+        OBJ:
+            kind: object
+---
+
+## Why
+
+Annotating an object literal with `Record<string, T>` throws away the keys the literal actually has, so `config.typo` compiles and every value is widened to `T`. `satisfies Record<string, T>` runs the same check while keeping the literal keys and values, so a misspelled key is an error and `keyof typeof config` is a useful union. The annotation form is only right when the object is genuinely open-ended.
+
+## Message
+
+object literal annotated with `Record` loses its keys; use `satisfies`
+
+## Bad
+
+```ts
+// BAD: the keys are gone and any string indexes without error
+const routes: Record<string, string> = {
+	home: '/',
+	users: '/users',
+};
+```
+
+## Good
+
+```ts
+const routes = {
+	home: '/',
+	users: '/users',
+} satisfies Record<string, string>;
+
+type RouteKey = keyof typeof routes;
+```
+
+```ts
+const cache: Record<string, User> = await loadCache();
+```

package/rules/ts/idiom/types/type-predicates-for-narrowing.md

@@ -0,0 +1,53 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - boolean functions that answer a business question rather than a type question, such as `isActive(user)` or `hasPermission(user, action)`
+    - a check that is used once, inline, and never followed by a cast
+    - functions that already declare `value is T` or `asserts value is T`
+---
+
+## Why
+
+A function that returns `boolean` after checking a value's shape tells the caller yes or no, but the compiler learns nothing, so the caller follows the check with `as T` and the two drift apart. Declaring the return as `value is T` ties the check to the narrowing: inside the `if`, the value is `T` with no cast, and `filter` returns the narrowed array. Assertion functions with `asserts value is T` do the same for throw-on-failure checks.
+
+## Message
+
+type check returns a plain boolean; declare a type predicate so callers narrow without casting
+
+## Bad
+
+```ts
+// BAD: callers learn nothing and cast right after the check
+function isUser(value: unknown): boolean {
+	return typeof value === 'object' && value !== null && 'id' in value;
+}
+
+function display(value: unknown): string {
+	if (isUser(value)) {
+		return (value as User).name;
+	}
+
+	return 'unknown';
+}
+```
+
+## Good
+
+```ts
+function isUser(value: unknown): value is User {
+	return typeof value === 'object' && value !== null && 'id' in value;
+}
+
+function display(value: unknown): string {
+	if (isUser(value)) {
+		return value.name;
+	}
+
+	return 'unknown';
+}
+```
+
+```ts
+const strings = mixed.filter((item): item is string => typeof item === 'string');
+```

package/rules/ts/idiom/variables/const-by-default.md

@@ -0,0 +1,41 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - a `let` that is assigned in more than one branch or reassigned later in its scope, including inside a loop body or a try block
+    - a `let` declared without an initializer and assigned exactly once further down, when merging it into a `const` would need a nested ternary or an IIFE
+    - loop counters in a classic `for` statement
+---
+
+## Why
+
+`const` tells the reader that a binding never changes, which removes one question from every later line that uses it. A `let` that is never reassigned makes the reader scan the rest of the scope looking for the mutation that is not there. Declare with `const` and switch to `let` only when there is a real second assignment.
+
+## Message
+
+`let` is never reassigned; declare it with `const`
+
+## Bad
+
+```ts
+// BAD: total is assigned once and never changes
+let total = items.reduce((sum, item) => sum + item.price, 0);
+
+return formatCurrency(total);
+```
+
+## Good
+
+```ts
+const total = items.reduce((sum, item) => sum + item.price, 0);
+
+return formatCurrency(total);
+```
+
+```ts
+let attempts = 0;
+
+while (attempts < MAX_RETRIES) {
+	attempts += 1;
+}
+```

package/rules/ts/idiom/variables/no-var.md

@@ -0,0 +1,36 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: variable_declaration
+---
+
+## Why
+
+`var` is function-scoped and hoisted, so a variable declared inside a loop or an `if` leaks into the whole function and can be read before its assignment. `const` and `let` are block-scoped, fail loudly when used early, and tell the reader whether the binding changes. There is no situation in modern TypeScript where `var` is the right choice.
+
+## Message
+
+`var` is function-scoped and hoisted; use `const` or `let`
+
+## Bad
+
+```ts
+// BAD: var leaks out of the block it was declared in
+var total = 0;
+
+for (var i = 0; i < items.length; i += 1) {
+	total += items[i];
+}
+```
+
+## Good
+
+```ts
+let total = 0;
+
+for (const item of items) {
+	total += item;
+}
+```