@aarock1234/slopscan 0.1.0

package/rules/any/futureproof/abstraction/single-impl-interface.md

@@ -0,0 +1,83 @@
+---
+severity: minor
+detect: judge
+confirm: implCount
+falsePositives:
+    - a port at an architecture boundary whose second implementation is a fake or mock in tests
+    - a small consumer-side interface in Go, one or two methods declared next to the code that uses them, which narrows a dependency rather than mirroring it
+    - an interface that is part of a published library's contract, where implementations live outside this repository
+    - an interface with several implementations, or one whose second implementation arrives in the same change
+---
+
+## Why
+
+An interface with one implementation and no test double is a copy of a type's method list that has to be edited every time the type changes, and it forces readers through an extra jump to find the code that runs. It does not decouple anything, because nothing else plugs in. Use the concrete type until a second implementation or a test fake exists; extracting an interface then is a mechanical change.
+
+## Message
+
+interface has a single implementation and no test double; use the concrete type until a second one exists
+
+## Bad
+
+```ts
+// BAD: the interface mirrors the only class that implements it
+export interface UserRepository {
+	findById(id: string): Promise<User | undefined>;
+	insert(input: CreateUserInput): Promise<User>;
+	delete(id: string): Promise<void>;
+}
+
+export class PostgresUserRepository implements UserRepository {
+	async findById(id: string): Promise<User | undefined> {
+		return this.db.selectOne(usersTable, { id });
+	}
+
+	async insert(input: CreateUserInput): Promise<User> {
+		return this.db.insert(usersTable, input);
+	}
+
+	async delete(id: string): Promise<void> {
+		await this.db.delete(usersTable, { id });
+	}
+}
+```
+
+```go
+// BAD: the interface mirrors the whole method set of the only type that satisfies it
+type UserStore interface {
+	FindByID(ctx context.Context, id string) (User, error)
+	Insert(ctx context.Context, in CreateUserInput) (User, error)
+	Delete(ctx context.Context, id string) error
+}
+
+var _ UserStore = (*PostgresUserStore)(nil)
+
+type PostgresUserStore struct {
+	db *sql.DB
+}
+```
+
+## Good
+
+```ts
+export class PostgresUserRepository {
+	async findById(id: string): Promise<User | undefined> {
+		return this.db.selectOne(usersTable, { id });
+	}
+
+	async insert(input: CreateUserInput): Promise<User> {
+		return this.db.insert(usersTable, input);
+	}
+}
+```
+
+```go
+// UserFinder is the one method the notifier needs; any store that can find users satisfies it.
+type UserFinder interface {
+	FindByID(ctx context.Context, id string) (User, error)
+}
+
+type Notifier struct {
+	users UserFinder
+}
+```

package/rules/any/futureproof/exports/dead-export.md

@@ -0,0 +1,62 @@
+---
+severity: minor
+detect: judge
+confirm: refCount
+ignore:
+    - '**/index.ts'
+    - '**/*.test.ts'
+    - '**/*.spec.ts'
+    - '**/*_test.go'
+falsePositives:
+    - the public API of a library package or a package entry point, where callers live outside this repository
+    - CLI binaries, `main`, `init`, and framework entry points such as route or plugin registrations
+    - symbols reached by reflection, templates, serialization tags, or generated code
+    - methods that exist to satisfy an interface, such as `String()` or `MarshalJSON()`
+    - types and constants that describe a wire format or database schema, which are referenced by name only in data
+---
+
+## Why
+
+An exported symbol that nothing references is code that must still compile, be reviewed, and be kept consistent with every refactor, while offering nothing in return. Exporting it also signals to readers that something depends on it, so they leave it alone. Delete it; version control remembers it if it is ever needed.
+
+## Message
+
+exported symbol is referenced nowhere; delete it or make it private
+
+## Bad
+
+```ts
+// BAD: exported but no caller in the repository
+export function formatLegacyDate(date: Date): string {
+	return `${date.getDate()}/${date.getMonth() + 1}/${date.getFullYear()}`;
+}
+
+export function formatDate(date: Date): string {
+	return date.toISOString().slice(0, 10);
+}
+```
+
+```go
+// BAD: exported but no caller in the repository
+func FormatLegacyDate(t time.Time) string {
+	return t.Format("2/1/2006")
+}
+
+func FormatDate(t time.Time) string {
+	return t.Format(time.DateOnly)
+}
+```
+
+## Good
+
+```ts
+export function formatDate(date: Date): string {
+	return date.toISOString().slice(0, 10);
+}
+```
+
+```go
+func FormatDate(t time.Time) string {
+	return t.Format(time.DateOnly)
+}
+```

package/rules/any/futureproof/layering/framework-type-in-domain.md

@@ -0,0 +1,83 @@
+---
+severity: major
+detect: judge
+ignore:
+    - '**/handlers/**'
+    - '**/handler/**'
+    - '**/api/**'
+    - '**/routes/**'
+    - '**/router/**'
+    - '**/controllers/**'
+    - '**/middleware/**'
+    - '**/transport/**'
+    - '**/http/**'
+    - '**/*.handler.ts'
+    - '**/*.controller.ts'
+    - '**/*.route.ts'
+    - '**/main.go'
+    - '**/cmd/**'
+    - '**/*.test.ts'
+    - '**/*.spec.ts'
+    - '**/*_test.go'
+---
+
+## Why
+
+A service function that takes the framework's request or response type can only be called by that framework: not from a job, a CLI, another transport, or a unit test without a fake request. It also pulls every HTTP concern, from headers to status codes, into the layer that should only know the domain. Give the service plain typed inputs and return plain typed results; the handler translates at the edge.
+
+## Message
+
+http framework type in a domain signature; take plain input and return a plain result
+
+## Bad
+
+```ts
+export class OrderService {
+	// BAD: the service can only be driven by express
+	async create(req: Request, res: Response): Promise<void> {
+		const input = createOrderSchema.parse(req.body);
+		const order = await this.repo.insert(input);
+		res.status(201).json(order);
+	}
+}
+```
+
+```go
+// BAD: the service can only be driven by net/http
+func (s *OrderService) Create(w http.ResponseWriter, r *http.Request) {
+	var in CreateOrderInput
+	if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	order, err := s.repo.Insert(r.Context(), in)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	writeJSON(w, http.StatusCreated, order)
+}
+```
+
+## Good
+
+```ts
+export class OrderService {
+	async create(input: CreateOrderInput): Promise<Order> {
+		return this.repo.insert(input);
+	}
+}
+```
+
+```go
+func (s *OrderService) Create(ctx context.Context, in CreateOrderInput) (Order, error) {
+	order, err := s.repo.Insert(ctx, in)
+	if err != nil {
+		return Order{}, fmt.Errorf("inserting order: %w", err)
+	}
+
+	return order, nil
+}
+```

package/rules/any/futureproof/layering/logic-in-handler.md

@@ -0,0 +1,94 @@
+---
+severity: major
+detect: judge
+falsePositives:
+    - parsing and validating the request, and mapping a service result or error to a status code, which is the handler's job
+    - a single guard clause such as checking authentication before delegating
+    - a small script, example, or prototype with no service layer at all
+    - middleware, which operates on the request itself rather than on domain state
+---
+
+## Why
+
+Business rules written inside an HTTP handler can only be reached through HTTP, so they cannot be reused by a CLI, a queue consumer, or a scheduled job, and they can only be tested by spinning up requests. The handler grows with every rule until nobody can see the request handling for the logic. Keep the handler to parsing input, calling one service function, and mapping the result to a response; the rules live in the service where they can be called from anywhere.
+
+## Message
+
+business logic inside an http handler; move it to a service the handler calls
+
+## Bad
+
+```ts
+router.post('/checkout', async (req, res) => {
+	const cart = await carts.find(req.session.cartId);
+	// BAD: pricing, stock, and persistence rules live in the route
+	let total = 0;
+	for (const line of cart.lines) {
+		const product = await products.find(line.productId);
+		if (product.stock < line.quantity) {
+			return res.status(409).json({ error: 'out of stock' });
+		}
+		total += product.price * line.quantity;
+	}
+	if (cart.coupon) {
+		total = total * (1 - cart.coupon.percent / 100);
+	}
+	const order = await orders.insert({ cartId: cart.id, total });
+	res.status(201).json(order);
+});
+```
+
+```go
+func (h *Handler) Checkout(w http.ResponseWriter, r *http.Request) {
+	cart, err := h.carts.Find(r.Context(), sessionCartID(r))
+	if err != nil {
+		http.Error(w, "cart not found", http.StatusNotFound)
+		return
+	}
+	// BAD: pricing, stock, and persistence rules live in the handler
+	var total int
+	for _, line := range cart.Lines {
+		product, err := h.products.Find(r.Context(), line.ProductID)
+		if err != nil || product.Stock < line.Quantity {
+			http.Error(w, "out of stock", http.StatusConflict)
+			return
+		}
+		total += product.Price * line.Quantity
+	}
+	if cart.Coupon != nil {
+		total = total * (100 - cart.Coupon.Percent) / 100
+	}
+	order, err := h.orders.Insert(r.Context(), Order{CartID: cart.ID, Total: total})
+	if err != nil {
+		http.Error(w, "internal error", http.StatusInternalServerError)
+		return
+	}
+	writeJSON(w, http.StatusCreated, order)
+}
+```
+
+## Good
+
+```ts
+router.post('/checkout', async (req, res) => {
+	const result = await checkout.run({ cartId: req.session.cartId });
+
+	if (!result.ok) {
+		return res.status(statusFor(result.error)).json({ error: result.error.message });
+	}
+
+	res.status(201).json(result.order);
+});
+```
+
+```go
+func (h *Handler) Checkout(w http.ResponseWriter, r *http.Request) {
+	order, err := h.checkout.Run(r.Context(), checkout.Input{CartID: sessionCartID(r)})
+	if err != nil {
+		writeError(w, err)
+		return
+	}
+
+	writeJSON(w, http.StatusCreated, order)
+}
+```

package/rules/any/futureproof/params/boolean-positional-param.md

@@ -0,0 +1,128 @@
+---
+severity: minor
+detect: ast
+ast:
+    ts:
+        utils:
+            param:
+                any:
+                    - kind: required_parameter
+                    - kind: optional_parameter
+        rule:
+            matches: param
+            any:
+                - has:
+                      kind: type_annotation
+                      has:
+                          kind: predefined_type
+                          regex: '^boolean$'
+                - all:
+                      - not:
+                            has:
+                                kind: type_annotation
+                      - has:
+                            field: value
+                            any:
+                                - kind: 'true'
+                                - kind: 'false'
+            all:
+                - any:
+                      - follows:
+                            matches: param
+                            stopBy: end
+                      - precedes:
+                            matches: param
+                            stopBy: end
+    go:
+        rule:
+            kind: parameter_declaration
+            has:
+                field: type
+                regex: '^bool$'
+            inside:
+                kind: parameter_list
+                not:
+                    follows:
+                        kind: parameter_list
+            any:
+                - follows:
+                      kind: parameter_declaration
+                      stopBy: end
+                - precedes:
+                      kind: parameter_declaration
+                      stopBy: end
+ignore:
+    - '**/*.test.ts'
+    - '**/*.spec.ts'
+    - '**/*_test.go'
+---
+
+## Why
+
+A boolean argument reads as `render(user, true)` at the call site, so every reader has to open the definition to learn what `true` means, and the second flag turns the function into four functions in a trench coat. Callers cannot add a third mode without touching every existing call. Take an options object or struct with named fields, or split the function into two named behaviors.
+
+## Message
+
+boolean positional parameter; use an options object or two functions
+
+## Bad
+
+```ts
+// BAD: render(user, true) says nothing at the call site
+export function render(user: User, compact: boolean): string {
+	return compact ? user.name : `${user.name} <${user.email}>`;
+}
+```
+
+```go
+// BAD: Render(user, true) says nothing at the call site
+func Render(user User, compact bool) string {
+	if compact {
+		return user.Name
+	}
+
+	return user.Name + " <" + user.Email + ">"
+}
+```
+
+## Good
+
+```ts
+type RenderOptions = {
+	compact?: boolean;
+};
+
+export function render(user: User, options: RenderOptions = {}): string {
+	return options.compact ? user.name : `${user.name} <${user.email}>`;
+}
+```
+
+```ts
+export function renderCompact(user: User): string {
+	return user.name;
+}
+
+export function renderFull(user: User): string {
+	return `${user.name} <${user.email}>`;
+}
+```
+
+```go
+type RenderOptions struct {
+	Compact bool
+}
+
+func Render(user User, opts RenderOptions) string {
+	if opts.Compact {
+		return user.Name
+	}
+
+	return user.Name + " <" + user.Email + ">"
+}
+```
+
+```go
+func IsAdmin(user User) bool {
+	return user.Role == RoleAdmin
+}
+```

package/rules/any/futureproof/params/positional-config-args.md

@@ -0,0 +1,135 @@
+---
+severity: minor
+detect: ast
+ast:
+    ts:
+        utils:
+            param:
+                any:
+                    - kind: required_parameter
+                    - kind: optional_parameter
+        rule:
+            kind: formal_parameters
+            inside:
+                kind: method_definition
+                has:
+                    field: name
+                    regex: '^constructor$'
+            has:
+                matches: param
+                follows:
+                    matches: param
+                    stopBy: end
+                    follows:
+                        matches: param
+                        stopBy: end
+                        follows:
+                            matches: param
+                            stopBy: end
+    go:
+        utils:
+            param:
+                kind: parameter_declaration
+        rule:
+            kind: parameter_list
+            not:
+                follows:
+                    kind: parameter_list
+            inside:
+                kind: function_declaration
+                has:
+                    field: name
+                    regex: '^(New|Must)[A-Z]?'
+            has:
+                matches: param
+                follows:
+                    matches: param
+                    stopBy: end
+                    follows:
+                        matches: param
+                        stopBy: end
+                        follows:
+                            matches: param
+                            stopBy: end
+ignore:
+    - '**/*.test.ts'
+    - '**/*.spec.ts'
+    - '**/*_test.go'
+---
+
+## Why
+
+A constructor with four positional arguments is called as `new Server('0.0.0.0', 8080, true, 30)`, which no reader can decode and no caller can extend without breaking every other caller. Constructors grow more often than any other signature, because every new dependency and setting lands there. Take one options object or config struct with named, defaultable fields, or use functional options in Go.
+
+## Message
+
+constructor takes 4+ positional arguments; take an options object or config struct
+
+## Bad
+
+```ts
+export class Server {
+	// BAD: new Server('0.0.0.0', 8080, true, 30) is unreadable and cannot grow
+	constructor(host: string, port: number, tls: boolean, timeoutSeconds: number) {
+		this.address = `${host}:${port}`;
+		this.tls = tls;
+		this.timeoutSeconds = timeoutSeconds;
+	}
+}
+```
+
+```go
+// BAD: NewServer("0.0.0.0", 8080, true, 30*time.Second) is unreadable and cannot grow
+func NewServer(host string, port int, tls bool, timeout time.Duration) *Server {
+	return &Server{addr: fmt.Sprintf("%s:%d", host, port), tls: tls, timeout: timeout}
+}
+```
+
+## Good
+
+```ts
+type ServerOptions = {
+	host: string;
+	port: number;
+	tls?: boolean;
+	timeoutSeconds?: number;
+};
+
+export class Server {
+	constructor(options: ServerOptions) {
+		this.address = `${options.host}:${options.port}`;
+		this.tls = options.tls ?? false;
+		this.timeoutSeconds = options.timeoutSeconds ?? 30;
+	}
+}
+```
+
+```go
+type Config struct {
+	Host    string
+	Port    int
+	TLS     bool
+	Timeout time.Duration
+}
+
+func NewServer(cfg Config) *Server {
+	return &Server{addr: fmt.Sprintf("%s:%d", cfg.Host, cfg.Port), tls: cfg.TLS, timeout: cfg.Timeout}
+}
+```
+
+```go
+type Option func(*Server)
+
+func WithTimeout(d time.Duration) Option {
+	return func(s *Server) { s.timeout = d }
+}
+
+func NewServer(addr string, opts ...Option) *Server {
+	s := &Server{addr: addr, timeout: 30 * time.Second}
+	for _, opt := range opts {
+		opt(s)
+	}
+
+	return s
+}
+```