@aarock1234/slopscan 0.1.0

package/rules/ts/idiom/exports/no-default-export.md

@@ -0,0 +1,37 @@
+---
+severity: minor
+detect: ast
+ignore:
+    - '**/*.config.ts'
+    - '**/app/**'
+    - '**/pages/**'
+ast:
+    rule:
+        pattern: export default $X
+---
+
+## Why
+
+A default export has no name of its own, so every importer invents one and the same function ends up with three names across the codebase. Named exports keep one name, refactor safely, and autocomplete. Framework files that require a default export, such as config files and route modules, are excluded.
+
+## Message
+
+default export has no name of its own; use a named export
+
+## Bad
+
+```ts
+// BAD: importers will call this anything they like
+export default function createUser(input: CreateUserInput): Promise<User> {
+	return repository.insert(input);
+}
+```
+
+## Good
+
+```ts
+// GOOD: one name everywhere
+export function createUser(input: CreateUserInput): Promise<User> {
+	return repository.insert(input);
+}
+```

package/rules/ts/idiom/formatting/multiline-object-literals.md

@@ -0,0 +1,46 @@
+---
+severity: info
+detect: ast
+ast:
+    rule:
+        kind: object
+        has:
+            nthChild: 2
+        regex: '^[^\n]*$'
+---
+
+## Why
+
+An object literal with two or more properties squeezed onto one line hides the key/value pairs in a wall of punctuation and turns every added property into a diff on the same line. One property per line lets the reader scan keys down the left edge and makes each change a one-line diff. Single-property objects such as `{ id }` are fine inline.
+
+## Message
+
+object with several properties on one line; put one property per line
+
+## Bad
+
+```ts
+// BAD: two properties squeezed onto one line
+const options = { timeout: 5000, retries: 3 };
+```
+
+```ts
+// BAD: inline argument object with several properties
+await db.user.update({ where: { id }, data: input });
+```
+
+## Good
+
+```ts
+const options = {
+	timeout: 5000,
+	retries: 3,
+};
+```
+
+```ts
+await db.user.update({
+	where: { id },
+	data: input,
+});
+```

package/rules/ts/idiom/functions/arrow-for-callbacks.md

@@ -0,0 +1,44 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: function_expression
+        inside:
+            kind: arguments
+        not:
+            has:
+                kind: this
+                stopBy: end
+---
+
+## Why
+
+A `function` expression passed as a callback carries its own `this`, which is almost never what the surrounding code wants, and the keyword adds noise to what is usually a one-line transform. An arrow keeps the outer `this`, reads as an expression, and is the form every reader expects inside `map`, `filter`, event handlers, and route definitions. Callbacks that deliberately use their own `this`, such as some test framework hooks, are left alone.
+
+## Message
+
+`function` expression as a callback; use an arrow function
+
+## Bad
+
+```ts
+// BAD: function expression where an arrow is expected
+const activeUsers = users.filter(function (user) {
+	return user.isActive;
+});
+```
+
+## Good
+
+```ts
+const activeUsers = users.filter(user => user.isActive);
+
+app.get('/health', (req, res) => res.json({ status: 'ok' }));
+```
+
+```ts
+describe('parser', function () {
+	this.timeout(10_000);
+});
+```

package/rules/ts/idiom/functions/function-declaration-for-top-level.md

@@ -0,0 +1,56 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: lexical_declaration
+        has:
+            kind: variable_declarator
+            has:
+                kind: arrow_function
+                field: value
+        inside:
+            any:
+                - kind: program
+                - kind: export_statement
+---
+
+## Why
+
+A top-level function written as `const f = () => {}` is not hoisted, so callers above it in the file break, and it shows up in stack traces and debuggers as an anonymous arrow bound to a variable. A `function` declaration is hoisted, carries its name, and stands out visually as a unit of the module. Arrows are for callbacks and inline expressions, where lexical `this` and brevity actually help.
+
+## Message
+
+top-level arrow function; use a `function` declaration
+
+## Bad
+
+```ts
+// BAD: exported arrow is not hoisted and is anonymous in stack traces
+export const createUser = async (input: CreateUserInput): Promise<User> => {
+	return repository.insert(input);
+};
+```
+
+```ts
+// BAD: module-level helper written as an arrow
+const toSlug = (title: string) => title.toLowerCase().replaceAll(' ', '-');
+```
+
+## Good
+
+```ts
+export async function createUser(input: CreateUserInput): Promise<User> {
+	return repository.insert(input);
+}
+```
+
+```ts
+function toSlug(title: string): string {
+	return title.toLowerCase().replaceAll(' ', '-');
+}
+
+export function slugs(titles: readonly string[]): string[] {
+	return titles.map(title => toSlug(title));
+}
+```

package/rules/ts/idiom/imports/export-type-for-types.md

@@ -0,0 +1,34 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - re-exports of values such as functions, classes, const objects, or schemas
+    - a `type` or `interface` declared inline with `export type` or `export interface`
+    - re-exports that mix types and values and already mark the types with an inline `type` modifier
+---
+
+## Why
+
+Re-exporting a type through a plain `export { X } from` keeps a runtime edge to the module even though nothing from it survives compilation. `export type { X } from` is erased, keeps `isolatedModules` builds happy, and tells the reader that the module contributes only types. It mirrors `import type` so the two read the same way.
+
+## Message
+
+re-export is a type; use `export type`
+
+## Bad
+
+```ts
+// BAD: User is a type, but the re-export keeps a runtime edge to ./user
+export { User } from './user';
+```
+
+## Good
+
+```ts
+export type { User } from './user';
+export { createUser } from './user';
+```
+
+```ts
+export { type User, createUser } from './user';
+```

package/rules/ts/idiom/imports/import-order.md

@@ -0,0 +1,66 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: import_statement
+        any:
+            - has:
+                  field: source
+                  regex: '^.\.'
+              precedes:
+                  kind: import_statement
+                  stopBy: end
+                  has:
+                      field: source
+                      regex: '^.[^.]'
+            - has:
+                  field: source
+                  regex: '^.@/'
+              precedes:
+                  kind: import_statement
+                  stopBy: end
+                  has:
+                      field: source
+                      regex: '^.[^.]'
+                  not:
+                      has:
+                          field: source
+                          regex: '^.@/'
+---
+
+## Why
+
+Imports come in three groups, external packages, then internal `@/` modules, then relative paths, with a blank line between groups. A reader scans the top of a file to learn what it depends on, and a fixed order makes external dependencies and local coupling visible at a glance. Mixed groups force a line-by-line read and produce noisy diffs when imports are added.
+
+## Message
+
+imports out of order; external packages, then `@/` modules, then relative paths
+
+## Bad
+
+```ts
+// BAD: relative import placed before an external package
+import { formatDate } from './format';
+import { z } from 'zod';
+```
+
+```ts
+import { z } from 'zod';
+// BAD: internal module placed before an external package
+import { config } from '@/config';
+import { PrismaClient } from '@prisma/client';
+```
+
+## Good
+
+```ts
+import { PrismaClient } from '@prisma/client';
+import { z } from 'zod';
+
+import { config } from '@/config';
+import { logger } from '@/lib/logger';
+
+import { formatDate } from './format';
+import type { User } from './user';
+```

package/rules/ts/idiom/imports/import-type-for-types.md

@@ -0,0 +1,50 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - imports whose binding is used as a runtime value anywhere in the file, including in `instanceof`, `typeof`, decorators, or `satisfies`
+    - imports of a const object that doubles as a type through `typeof`
+    - files where every import in the statement is already marked with an inline `type` modifier
+---
+
+## Why
+
+A binding that is only ever used in type positions should be imported with `import type`, which is erased at compile time. A plain import of a type keeps a runtime dependency on the module, can drag a circular import into existence, and hides from the reader that nothing from that module runs. The distinction is cheap to write and tells the next person exactly what the file needs at runtime.
+
+## Message
+
+import is only used as a type; use `import type`
+
+## Bad
+
+```ts
+// BAD: User is only used in a type annotation
+import { User } from './user';
+
+export function displayName(user: User): string {
+	return user.name;
+}
+```
+
+## Good
+
+```ts
+import type { User } from './user';
+
+export function displayName(user: User): string {
+	return user.name;
+}
+```
+
+```ts
+import { UserService } from './user.service';
+import type { User } from './user';
+
+export function build(): UserService {
+	return new UserService();
+}
+
+export function displayName(user: User): string {
+	return user.name;
+}
+```

package/rules/ts/idiom/imports/side-effect-imports-last.md

@@ -0,0 +1,42 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: import_statement
+        not:
+            has:
+                kind: import_clause
+        precedes:
+            kind: import_statement
+            stopBy: end
+---
+
+## Why
+
+A side-effect import such as `import './polyfills'` runs code for its effect alone, so it stands apart from the imports that bind names. Placing it last, after a blank line, makes the effect visible instead of burying it among ordinary imports where a reader assumes nothing happens. A comment saying what the effect is helps the next person decide whether it can be removed.
+
+## Message
+
+side-effect import belongs after all named imports
+
+## Bad
+
+```ts
+// BAD: side-effect import hidden at the top of the list
+import './polyfills';
+import { z } from 'zod';
+
+import { config } from '@/config';
+```
+
+## Good
+
+```ts
+import { z } from 'zod';
+
+import { config } from '@/config';
+
+// registers the fetch polyfill for node 18
+import './polyfills';
+```

package/rules/ts/idiom/logging/structured-logging-lowercase.md

@@ -0,0 +1,45 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        any:
+            - pattern: $LOGGER.$METHOD($MSG)
+            - pattern: $LOGGER.$METHOD($MSG, $$$REST)
+    constraints:
+        METHOD:
+            regex: '^(log|info|warn|error|debug|trace|fatal)$'
+        MSG:
+            regex: '^.[A-Z][a-z]'
+---
+
+## Why
+
+Log lines are grepped and read in bulk, and a mix of `Starting server` and `connected to database` makes the stream look like it came from two systems. Messages are lowercase fragments, with proper nouns and acronyms kept as they are, and variable data goes in the structured fields rather than the sentence. A consistent shape makes the output scannable and the fields queryable.
+
+## Message
+
+log message starts with a capital letter; write it as a lowercase fragment
+
+## Bad
+
+```ts
+// BAD: capitalized sentence in a log line
+logger.info('Starting server on port 3000');
+```
+
+```ts
+// BAD: console output follows the same convention
+console.error('Failed to connect', error);
+```
+
+## Good
+
+```ts
+logger.info('starting server', { port: 3000 });
+logger.error('failed to connect', { error });
+```
+
+```ts
+logger.info('connecting to PostgreSQL');
+```

package/rules/ts/idiom/naming/boolean-name-question-prefix.md

@@ -0,0 +1,42 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - names that already read as a yes/no question with a prefix like `is`, `has`, `should`, `can`, `was`, `needs`, or `allows`
+    - boolean properties whose name is dictated by an external schema, framework prop, or API response
+    - loop or callback parameters of one or two letters in a very short scope
+---
+
+## Why
+
+A boolean whose name is a bare noun or verb, such as `valid`, `children`, or `retry`, forces the reader to look up its type before an `if` on it makes sense. Names that read as a yes/no question, such as `isValid`, `hasChildren`, or `shouldRetry`, carry the type in the name and make conditions read as prose. This applies to variables, properties, parameters, and functions that return a boolean.
+
+## Message
+
+boolean name does not read as a question; prefix with is, has, should, or can
+
+## Bad
+
+```ts
+// BAD: valid could be a noun, a verb, or an adjective
+const valid = schema.safeParse(data).success;
+
+// BAD: children sounds like a collection, not a flag
+const children = node.children.length > 0;
+
+// BAD: retry reads as an action, but it returns a yes/no answer
+function retry(attempt: number, error: Error): boolean {
+	return attempt < 3 && error instanceof TimeoutError;
+}
+```
+
+## Good
+
+```ts
+const isValid = schema.safeParse(data).success;
+const hasChildren = node.children.length > 0;
+
+function shouldRetry(attempt: number, error: Error): boolean {
+	return attempt < 3 && error instanceof TimeoutError;
+}
+```

package/rules/ts/idiom/naming/descriptive-identifier-quality.md

@@ -0,0 +1,48 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - conventional short names in tiny scopes, such as `i` in a counting loop, `e` in a catch, `x` in a one-line arrow, or `T` as a type parameter
+    - domain abbreviations that are standard in the codebase, such as `db`, `req`, `res`, `ctx`, `id`, or `url`
+    - names that match an external API or schema field the code has to mirror
+---
+
+## Why
+
+An identifier is read far more often than it is written, and a name like `data`, `tmp`, `res2`, or `handleStuff` tells the reader nothing they did not already know from the type. Good names say what the value is or what the function does, so the surrounding code needs fewer comments and a wrong assumption is caught on sight. Length is not the goal; precision is, and a short name in a short scope is fine.
+
+## Message
+
+identifier does not describe what it holds or does; use a descriptive name
+
+## Bad
+
+```ts
+// BAD: data, res, and tmp say nothing about what they hold
+async function process(data: string): Promise<string[]> {
+	const res = await fetchRows(data);
+	const tmp = res.filter(r => r.active);
+
+	return tmp.map(t => t.id);
+}
+```
+
+```ts
+// BAD: a numbered copy of a name is a sign the first name was wrong
+const user2 = await repository.find(managerId);
+```
+
+## Good
+
+```ts
+async function activeRowIds(tableName: string): Promise<string[]> {
+	const rows = await fetchRows(tableName);
+	const activeRows = rows.filter(row => row.active);
+
+	return activeRows.map(row => row.id);
+}
+```
+
+```ts
+const manager = await repository.find(managerId);
+```

package/rules/ts/idiom/naming/screaming-snake-module-constants.md

@@ -0,0 +1,58 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        pattern: const $NAME = $VALUE
+        inside:
+            any:
+                - kind: program
+                - kind: export_statement
+    constraints:
+        NAME:
+            regex: '^[a-z][a-zA-Z0-9]*$'
+        VALUE:
+            any:
+                - kind: number
+                - kind: string
+                - kind: 'true'
+                - kind: 'false'
+---
+
+## Why
+
+A module-level constant holding a literal value is a configuration knob, and SCREAMING_SNAKE_CASE marks it as one at every use site. A camelCase name such as `maxRetries` looks like a local variable, so a reader inside a function cannot tell whether it is a fixed limit or something computed nearby. Local constants stay camelCase; only the module-level literals get the loud name.
+
+## Message
+
+module-level literal constant is camelCase; use SCREAMING_SNAKE_CASE
+
+## Bad
+
+```ts
+// BAD: a fixed module-level limit dressed as a local variable
+const maxRetries = 3;
+```
+
+```ts
+// BAD: exported literal config in camelCase
+export const defaultTimeout = 10_000;
+```
+
+## Good
+
+```ts
+const MAX_RETRIES = 3;
+
+export const DEFAULT_TIMEOUT = 10_000;
+```
+
+```ts
+export const userSchema = z.object({
+	id: z.string(),
+});
+
+function retry(): void {
+	const attempts = 3;
+}
+```

package/rules/ts/idiom/strings/template-literals-over-concat.md

@@ -0,0 +1,51 @@
+---
+severity: minor
+detect: ast
+ast:
+    rule:
+        kind: binary_expression
+        all:
+            - has:
+                  field: operator
+                  regex: '^\+$'
+            - has:
+                  kind: string
+        not:
+            inside:
+                kind: augmented_assignment_expression
+---
+
+## Why
+
+Building a string with `+` scatters the literal parts and the values across quotes and operators, so the reader has to reassemble the final shape in their head and a missing space or quote is easy to miss. A template literal shows the string as it will appear with the values slotted in place. Incremental building in a loop with `+=` is a different pattern and is left alone.
+
+## Message
+
+string built with `+`; use a template literal
+
+## Bad
+
+```ts
+// BAD: the final shape is spread across three fragments and two operators
+const greeting = 'hello, ' + name + '!';
+```
+
+```ts
+// BAD: path assembled by concatenation
+const url = baseUrl + '/users/' + userId + '/posts';
+```
+
+## Good
+
+```ts
+const greeting = `hello, ${name}!`;
+const url = `${baseUrl}/users/${userId}/posts`;
+```
+
+```ts
+let csv = '';
+
+for (const row of rows) {
+	csv += row.join(',') + '\n';
+}
+```

package/rules/ts/idiom/types/interface-extends-over-intersection.md

@@ -0,0 +1,44 @@
+---
+severity: info
+detect: judge
+falsePositives:
+    - intersections in generic constraints such as `T extends Identifiable & Timestamped`
+    - 'branded types of the form `T & { readonly __brand: B }`'
+    - intersections with a union or a mapped type, which `extends` cannot express
+    - an intersection of two object literals that is used once and never extended again
+---
+
+## Why
+
+Extending a named object shape with `type Admin = User & { role: 'admin' }` is checked lazily on every use, and when two members conflict the intersection silently becomes `never` for that property instead of an error at the declaration. `interface Admin extends User` is checked once, rejects conflicting members where they are declared, and gives shorter error messages that name the interface rather than expanding the whole intersection. Intersections are for unions, brands, and generic constraints.
+
+## Message
+
+object shape extended with an intersection; use `interface extends`
+
+## Bad
+
+```ts
+// BAD: extending a named object shape through an intersection
+type Admin = User & {
+	role: 'admin';
+	permissions: readonly string[];
+};
+```
+
+## Good
+
+```ts
+interface Admin extends User {
+	role: 'admin';
+	permissions: readonly string[];
+}
+```
+
+```ts
+type UserId = string & { readonly __brand: 'UserId' };
+
+function sortByCreation<T extends Identifiable & Timestamped>(items: readonly T[]): T[] {
+	return [...items].sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+}
+```