@aarock1234/slopscan 0.1.0

package/rules/any/futureproof/structure/wide-function.md

@@ -0,0 +1,138 @@
+---
+severity: minor
+detect: ast
+ast:
+    ts:
+        utils:
+            param:
+                any:
+                    - kind: required_parameter
+                    - kind: optional_parameter
+        rule:
+            any:
+                - all:
+                      - any:
+                            - kind: function_declaration
+                            - kind: method_definition
+                            - kind: function_expression
+                            - kind: arrow_function
+                      - regex: '^(?:[^\n]*\n){60}'
+                - kind: formal_parameters
+                  has:
+                      matches: param
+                      follows:
+                          matches: param
+                          stopBy: end
+                          follows:
+                              matches: param
+                              stopBy: end
+                              follows:
+                                  matches: param
+                                  stopBy: end
+                                  follows:
+                                      matches: param
+                                      stopBy: end
+                                      follows:
+                                          matches: param
+                                          stopBy: end
+    go:
+        utils:
+            param:
+                kind: parameter_declaration
+        rule:
+            any:
+                - all:
+                      - any:
+                            - kind: function_declaration
+                            - kind: method_declaration
+                            - kind: func_literal
+                      - regex: '^(?:[^\n]*\n){60}'
+                - kind: parameter_list
+                  not:
+                      follows:
+                          kind: parameter_list
+                  has:
+                      matches: param
+                      follows:
+                          matches: param
+                          stopBy: end
+                          follows:
+                              matches: param
+                              stopBy: end
+                              follows:
+                                  matches: param
+                                  stopBy: end
+                                  follows:
+                                      matches: param
+                                      stopBy: end
+                                      follows:
+                                          matches: param
+                                          stopBy: end
+ignore:
+    - '**/*.test.ts'
+    - '**/*.spec.ts'
+    - '**/*_test.go'
+---
+
+## Why
+
+A function with six or more parameters or more than sixty lines is doing several jobs, and each new requirement makes it longer and its call sites more fragile, since positional arguments are easy to swap and impossible to read. Group related parameters into a typed options object or struct, and split the body along the steps it already performs. The pieces get names, tests, and a chance of being reused.
+
+## Message
+
+function is too wide: more than 5 parameters or over 60 lines; group parameters into a struct and split the body
+
+## Bad
+
+```ts
+// BAD: six positional arguments nobody can order from memory
+export function createInvoice(
+	customerId: string,
+	items: LineItem[],
+	currency: string,
+	dueDate: Date,
+	notes: string,
+	sendEmail: boolean
+): Invoice {
+	return build(customerId, items, currency, dueDate, notes, sendEmail);
+}
+```
+
+```go
+// BAD: six positional arguments nobody can order from memory
+func CreateInvoice(customerID string, items []LineItem, currency string, dueDate time.Time, notes string, sendEmail bool) Invoice {
+	return build(customerID, items, currency, dueDate, notes, sendEmail)
+}
+```
+
+## Good
+
+```ts
+type CreateInvoiceInput = {
+	customerId: string;
+	items: LineItem[];
+	currency: string;
+	dueDate: Date;
+	notes?: string;
+	sendEmail?: boolean;
+};
+
+export function createInvoice(input: CreateInvoiceInput): Invoice {
+	return build(input);
+}
+```
+
+```go
+type CreateInvoiceInput struct {
+	CustomerID string
+	Items      []LineItem
+	Currency   string
+	DueDate    time.Time
+	Notes      string
+	SendEmail  bool
+}
+
+func CreateInvoice(in CreateInvoiceInput) Invoice {
+	return build(in)
+}
+```

package/rules/any/futureproof/testing/test-asserts-implementation.md

@@ -0,0 +1,70 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - asserting that a collaborator at a boundary received the right call, such as the mailer being sent the right message, when that call is the observable outcome
+    - calling an unexported or private pure function directly and asserting on its return value
+    - reaching into unexported fields to set up state before exercising the public behavior
+    - asserting call counts for behavior the contract promises, such as a cache hitting the loader exactly once
+---
+
+## Why
+
+A test that spies on private methods or inspects unexported fields passes only while the code is written one particular way, so a refactor that keeps every behavior still turns the suite red and teaches people to delete tests. It also documents nothing a caller can rely on. Assert on what the caller sees: return values, thrown errors, persisted state, and calls to external systems.
+
+## Message
+
+test asserts on internals; assert on observable behavior instead
+
+## Bad
+
+```ts
+it('creates a user', async () => {
+	const service = new UserService(repo);
+	// BAD: the test is coupled to a private helper's name and arguments
+	const spy = vi.spyOn(service as never, 'normalizeEmail');
+
+	await service.create({ email: 'Ada@Example.com' });
+
+	expect(spy).toHaveBeenCalledWith('Ada@Example.com');
+});
+```
+
+```go
+func TestPutStoresEntry(t *testing.T) {
+	c := cache.New()
+
+	c.Put("k", []byte("v"))
+
+	// BAD: the test knows the map is called entries and breaks when storage changes
+	if len(c.entries) != 1 {
+		t.Fatalf("expected 1 entry, got %d", len(c.entries))
+	}
+}
+```
+
+## Good
+
+```ts
+it('creates a user with a normalized email', async () => {
+	const service = new UserService(repo);
+
+	const user = await service.create({ email: 'Ada@Example.com' });
+
+	expect(user.email).toBe('ada@example.com');
+	expect(await repo.findById(user.id)).toEqual(user);
+});
+```
+
+```go
+func TestPutThenGet(t *testing.T) {
+	c := cache.New()
+
+	c.Put("k", []byte("v"))
+
+	got, ok := c.Get("k")
+	if !ok || string(got) != "v" {
+		t.Fatalf("Get(k) = %q, %v; want v, true", got, ok)
+	}
+}
+```

package/rules/any/hacky/comments/comment-restates-code.md

@@ -0,0 +1,50 @@
+---
+severity: minor
+detect: judge
+falsePositives:
+    - doc comments on exported symbols that state the contract, even when short
+    - comments explaining why, a constraint, or a non-obvious consequence
+---
+
+## Why
+
+A comment that says what the next line already says is noise the reader has to check against the code, and it goes stale the first time the code changes. Comments earn their place by saying why, naming a constraint, or warning about a consequence the code cannot show.
+
+## Message
+
+comment restates the code; say why or delete it
+
+## Bad
+
+```ts
+// BAD: the comment is the line, in English
+// increment the counter
+counter += 1;
+```
+
+```go
+func total(orders []Order) int {
+	sum := 0
+	// BAD: the comment is the loop, in English
+	// loop over the orders and add up the amounts
+	for _, order := range orders {
+		sum += order.Amount
+	}
+
+	return sum
+}
+```
+
+## Good
+
+```ts
+// the API rejects batches over 100 items, so chunk before sending
+const batches = chunk(items, 100);
+```
+
+```go
+// Find returns ErrNotFound rather than a nil user so callers cannot forget the missing case.
+func Find(id string) (*User, error) {
+	return repo.Find(id)
+}
+```

package/rules/any/hacky/comments/shipped-todo-comment.md

@@ -0,0 +1,55 @@
+---
+severity: minor
+detect: ast
+ast:
+    ts:
+        rule:
+            kind: comment
+            regex: '^(//|/\*+)[\s*]*(TODO|FIXME|HACK|XXX)\b'
+    go:
+        rule:
+            kind: comment
+            regex: '^(//|/\*+)[\s*]*(TODO|FIXME|HACK|XXX)\b'
+---
+
+## Why
+
+A TODO in merged code is a known defect with no owner, no deadline, and no ticket, and it stays there until someone rediscovers the problem the hard way. Either do the work before merging, or open an issue and reference it so the gap is tracked where people actually look. A comment that explains a deliberate limitation and points at the issue is fine; a bare marker is not.
+
+## Message
+
+todo marker shipped in code; do the work or link the tracking issue
+
+## Bad
+
+```ts
+export function parsePrice(raw: string): number {
+	// BAD: known gap with no owner
+	// TODO: handle currencies other than USD
+	return Number(raw.replace('$', ''));
+}
+```
+
+```go
+func ParsePrice(raw string) (int, error) {
+	// BAD: known shortcut with no owner
+	// FIXME: this breaks on prices over 1000
+	return strconv.Atoi(strings.TrimPrefix(raw, "$"))
+}
+```
+
+## Good
+
+```ts
+// only USD is supported; other currencies are rejected upstream by the validator (see #482)
+export function parsePrice(raw: string): number {
+	return Number(raw.replace('$', ''));
+}
+```
+
+```go
+// ParsePrice accepts USD only; other currencies are rejected by the validator (see #482).
+func ParsePrice(raw string) (int, error) {
+	return strconv.Atoi(strings.TrimPrefix(raw, "$"))
+}
+```

package/rules/any/hacky/concurrency/sleep-based-sync.md

@@ -0,0 +1,95 @@
+---
+severity: major
+detect: ast
+ast:
+    ts:
+        rule:
+            kind: new_expression
+            pattern: new Promise($$$ARGS)
+            has:
+                pattern: setTimeout($$$TIMER)
+                stopBy: end
+    go:
+        rule:
+            pattern:
+                context: 'func f() { time.Sleep($D) }'
+                selector: call_expression
+ignore:
+    - '**/*.test.ts'
+    - '**/*.spec.ts'
+    - '**/*_test.go'
+    - '**/main.go'
+    - '**/cmd/**'
+    - '**/e2e/**'
+---
+
+## Why
+
+A fixed delay is a guess about how long something else takes, and the guess is wrong on a slow CI runner, a loaded server, or a faster machine that now waits for nothing. The code passes locally and fails intermittently elsewhere, which is the most expensive kind of bug to chase. Wait on the actual signal: a promise, a channel, a readiness check, or a context-aware timer for a real backoff.
+
+## Message
+
+fixed sleep used as synchronization; wait on a promise, channel, or readiness signal instead
+
+## Bad
+
+```ts
+async function startWorker(worker: Worker): Promise<void> {
+	worker.start();
+	// BAD: hoping startup is done after two seconds
+	await new Promise(resolve => setTimeout(resolve, 2000));
+	worker.send(job);
+}
+```
+
+```go
+func startWorker(w *Worker) {
+	go w.Run()
+	// BAD: hoping the goroutine is ready after a fixed delay
+	time.Sleep(500 * time.Millisecond)
+	w.Send(job)
+}
+```
+
+## Good
+
+```ts
+async function startWorker(worker: Worker): Promise<void> {
+	await worker.start();
+	worker.send(job);
+}
+```
+
+```ts
+import { once } from 'node:events';
+
+async function startWorker(worker: Worker): Promise<void> {
+	worker.start();
+	await once(worker, 'ready');
+	worker.send(job);
+}
+```
+
+```go
+func startWorker(w *Worker) {
+	go w.Run()
+	<-w.Ready()
+	w.Send(job)
+}
+```
+
+```go
+func retry(ctx context.Context, delay time.Duration, attempt func() error) error {
+	for {
+		if err := attempt(); err == nil {
+			return nil
+		}
+
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-time.After(delay):
+		}
+	}
+}
+```

package/rules/any/hacky/config/hardcoded-url.md

@@ -0,0 +1,88 @@
+---
+severity: minor
+detect: ast
+ast:
+    ts:
+        rule:
+            any:
+                - kind: string
+                  regex: '^["'']https?://'
+                - kind: template_string
+                  regex: '^`https?://'
+            not:
+                regex: 'https?://(www\.)?w3\.org|https?://schemas\.|https?://json-schema\.org'
+    go:
+        rule:
+            any:
+                - kind: interpreted_string_literal
+                  regex: '^"https?://'
+                - kind: raw_string_literal
+                  regex: '^`https?://'
+            not:
+                regex: 'https?://(www\.)?w3\.org|https?://schemas\.|https?://json-schema\.org'
+ignore:
+    - '**/config/**'
+    - '**/config.ts'
+    - '**/config.go'
+    - '**/constants.ts'
+    - '**/constants.go'
+    - '**/*.config.ts'
+    - '**/*.test.ts'
+    - '**/*.spec.ts'
+    - '**/*_test.go'
+    - '**/testdata/**'
+    - '**/fixtures/**'
+    - '**/__mocks__/**'
+---
+
+## Why
+
+A URL written inline is an environment decision buried in logic: it points at production from a test run, at staging after a deploy, and at nothing once the host moves. Every environment change becomes a code change and a search across the repo. Read the base URL from configuration and build paths on top of it.
+
+## Message
+
+hardcoded url in logic; read the base url from config and build the path on it
+
+## Bad
+
+```ts
+export async function fetchUser(id: string): Promise<User> {
+	// BAD: the host is fixed in code
+	const response = await fetch(`https://api.example.com/users/${id}`);
+
+	return userSchema.parse(await response.json());
+}
+```
+
+```go
+func FetchUser(ctx context.Context, id string) (User, error) {
+	// BAD: the host is fixed in code
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.example.com/users/"+id, nil)
+	if err != nil {
+		return User{}, fmt.Errorf("building request: %w", err)
+	}
+
+	return doUser(req)
+}
+```
+
+## Good
+
+```ts
+export async function fetchUser(config: ApiConfig, id: string): Promise<User> {
+	const response = await fetch(new URL(`/users/${id}`, config.baseUrl));
+
+	return userSchema.parse(await response.json());
+}
+```
+
+```go
+func (c *Client) FetchUser(ctx context.Context, id string) (User, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL.JoinPath("users", id).String(), nil)
+	if err != nil {
+		return User{}, fmt.Errorf("building request: %w", err)
+	}
+
+	return c.doUser(req)
+}
+```

package/rules/any/hacky/constants/magic-number.md

@@ -0,0 +1,94 @@
+---
+severity: minor
+detect: judge
+ignore:
+    - '**/*.test.ts'
+    - '**/*.spec.ts'
+    - '**/*_test.go'
+    - '**/constants.ts'
+    - '**/constants.go'
+    - '**/testdata/**'
+    - '**/fixtures/**'
+falsePositives:
+    - the literals 0, 1, -1, 2, and 100, and small loop bounds or step sizes
+    - array, slice, or tuple indexes and offsets
+    - the right-hand side of a named constant declaration, which is where the number belongs
+    - a unit conversion factor next to a named constant, such as `const TIMEOUT_MS = 30 * 1000`
+    - well-known protocol values where the call name makes the meaning obvious, such as `res.status(404)` or `os.Exit(1)`
+    - numbers in a plain arithmetic formula whose surrounding function name explains them, such as a percentage or area calculation
+---
+
+## Why
+
+A bare `30000` in a call or a comparison forces every reader to guess what it means and whether the `30000` forty lines down is the same thing. When the value has to change, the search finds every unrelated occurrence too. Give the number a name that says what it is, and reuse that name so the two places cannot drift.
+
+## Message
+
+magic number in logic; name it as a constant that says what it means
+
+## Bad
+
+```ts
+async function pollJob(id: string): Promise<Job> {
+	let attempts = 0;
+
+	while (true) {
+		const job = await fetchJob(id);
+		// BAD: nobody knows why five, or whether the five below is the same five
+		if (job.done || attempts > 5) {
+			return job;
+		}
+
+		attempts += 1;
+		// BAD: a duration with no name
+		await delay(1500);
+	}
+}
+```
+
+```go
+func (s *Service) ListRecent(ctx context.Context) ([]Item, error) {
+	// BAD: nobody knows whether 250 is a page size, an API cap, or a guess
+	items, err := s.repo.List(ctx, 250)
+	if err != nil {
+		return nil, fmt.Errorf("listing items: %w", err)
+	}
+
+	return items, nil
+}
+```
+
+## Good
+
+```ts
+const MAX_POLL_ATTEMPTS = 5;
+const POLL_INTERVAL_MS = 1500;
+
+async function pollJob(id: string): Promise<Job> {
+	let attempts = 0;
+
+	while (true) {
+		const job = await fetchJob(id);
+		if (job.done || attempts > MAX_POLL_ATTEMPTS) {
+			return job;
+		}
+
+		attempts += 1;
+		await delay(POLL_INTERVAL_MS);
+	}
+}
+```
+
+```go
+// recentPageSize matches the upstream API's maximum page size.
+const recentPageSize = 250
+
+func (s *Service) ListRecent(ctx context.Context) ([]Item, error) {
+	items, err := s.repo.List(ctx, recentPageSize)
+	if err != nil {
+		return nil, fmt.Errorf("listing items: %w", err)
+	}
+
+	return items, nil
+}
+```

package/rules/any/hacky/debugging/debug-print.md

@@ -0,0 +1,73 @@
+---
+severity: minor
+detect: ast
+ast:
+    ts:
+        rule:
+            any:
+                - pattern: console.log($$$ARGS)
+                - pattern: console.debug($$$ARGS)
+                - pattern: console.dir($$$ARGS)
+                - pattern: console.table($$$ARGS)
+    go:
+        rule:
+            kind: call_expression
+            has:
+                field: function
+                regex: '^(fmt\.Print(ln|f)?|println|print)$'
+ignore:
+    - '**/*.test.ts'
+    - '**/*.spec.ts'
+    - '**/cli.ts'
+    - '**/scripts/**'
+    - '**/bin/**'
+    - '**/main.go'
+    - '**/cmd/**'
+    - '**/*_test.go'
+---
+
+## Why
+
+A print statement left in library code writes unstructured text to stdout with no level, no context, and no way to turn it off, and it pollutes the output of any program that embeds this code. Use the project's logger so the line carries a level and structured fields and can be filtered or shipped. If the line was for debugging, delete it.
+
+## Message
+
+debug print in library code; use the structured logger or remove it
+
+## Bad
+
+```ts
+export async function createUser(input: CreateUserInput): Promise<User> {
+	// BAD: unstructured stdout with no level
+	console.log('creating user', input.email);
+
+	return repo.insert(input);
+}
+```
+
+```go
+func CreateUser(ctx context.Context, in CreateUserInput) (User, error) {
+	// BAD: unstructured stdout with no level
+	fmt.Println("creating user", in.Email)
+
+	return repo.Insert(ctx, in)
+}
+```
+
+## Good
+
+```ts
+export async function createUser(input: CreateUserInput): Promise<User> {
+	logger.info({ email: input.email }, 'creating user');
+
+	return repo.insert(input);
+}
+```
+
+```go
+func CreateUser(ctx context.Context, in CreateUserInput) (User, error) {
+	slog.InfoContext(ctx, "creating user", "email", in.Email)
+
+	return repo.Insert(ctx, in)
+}
+```