@use-the-fork/spindle 0.0.0-stage → 0.0.1

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/over-eng-premature-interface.md

@@ -0,0 +1,136 @@
+---
+title: Premature Interface (One Implementation, No Plan for a Second)
+impact: HIGH
+impactDescription: "Adds indirection nobody asked for; doubles the surface for every change"
+tags: over-engineering, interfaces, abstractions, ai-fingerprint
+---
+
+## Premature Interface (One Implementation, No Plan for a Second)
+
+**Impact: HIGH (Adds indirection nobody asked for; doubles the surface for every change)**
+
+AI defaults to "enterprise-grade" because its training distribution is enterprise-grade. The result: every service gets an interface and one implementation, with no second implementation in the foreseeable future. The interface is pure ceremony — every change updates two files, every test mocks the interface, every reader chases two clicks to find the actual code.
+
+**Interfaces earn their place when:**
+
+- There IS a second implementation (e.g., `StripeGateway` and `AdyenGateway`)
+- There IS a planned second implementation (in this quarter's roadmap)
+- The implementation is being swapped in tests with a fake (and even then, dependency injection of the concrete type is often fine)
+
+**Otherwise: write the concrete type. Add the interface when a second implementation actually shows up.** YAGNI is real.
+
+## Incorrect
+
+```php
+// ❌ Interface with exactly one implementation, no plan for a second
+
+interface UserRepositoryInterface
+{
+    public function find(int $id): ?User;
+    public function save(User $user): void;
+    public function delete(int $id): void;
+}
+
+final class UserRepository implements UserRepositoryInterface
+{
+    public function find(int $id): ?User { /* ... */ }
+    public function save(User $user): void { /* ... */ }
+    public function delete(int $id): void { /* ... */ }
+}
+
+// Binding in a service provider, mostly to satisfy the interface
+$this->app->bind(UserRepositoryInterface::class, UserRepository::class);
+```
+
+```typescript
+// ❌ Same TS pattern
+interface IOrderService {
+  placeOrder(payload: OrderPayload): Promise<Order>;
+  cancelOrder(orderId: string): Promise<void>;
+}
+
+class OrderService implements IOrderService {
+  async placeOrder(payload: OrderPayload): Promise<Order> {
+    /* ... */
+  }
+  async cancelOrder(orderId: string): Promise<void> {
+    /* ... */
+  }
+}
+```
+
+**Why it's slop:**
+
+- Every method declared in two files
+- `find` / `save` / `delete` change — both interface AND implementation must be updated; nothing prevents drift
+- Reader hits `UserRepositoryInterface` in a controller, has to navigate through to find the actual code
+- The `I*` prefix or `*Interface` suffix is itself a tell — clean naming uses domain words without the marker
+
+## Correct
+
+```php
+// ✅ Concrete class until you need a second implementation
+
+final class UserRepository
+{
+    public function find(int $id): ?User { /* ... */ }
+    public function save(User $user): void { /* ... */ }
+    public function delete(int $id): void { /* ... */ }
+}
+
+// Controller depends on the concrete class — Laravel auto-resolves it
+public function show(int $id, UserRepository $users): UserResource
+{
+    $user = $users->find($id) ?? throw new NotFoundException;
+    return new UserResource($user);
+}
+```
+
+```typescript
+// ✅ Concrete class
+class OrderService {
+  async placeOrder(payload: OrderPayload): Promise<Order> {
+    /* ... */
+  }
+  async cancelOrder(orderId: string): Promise<void> {
+    /* ... */
+  }
+}
+```
+
+**When a second implementation arrives** — e.g., you need a `CachedUserRepository` — _then_ extract the interface. By that point you'll know what shape it should have because you have two concrete examples.
+
+**Why it reads human:**
+
+- Concrete class is reachable in one click
+- No double-maintenance
+- Adding a second implementation is a deliberate refactor, not a default scaffold
+
+## Tests: don't create an interface just to mock
+
+If you need to swap the dependency in tests, prefer:
+
+1. **Inject the concrete class; instantiate with fakes** (e.g., `UserRepository` with an in-memory `Database` connection)
+2. **Use Laravel's container-bound fake** (`$this->mock(UserRepository::class, ...)`) — no interface needed
+3. **Method-level mocks** via PHPUnit / Vitest
+
+An interface created _only_ to mock the dependency in tests is also slop. Real interfaces serve production code paths.
+
+## Detection
+
+```bash
+# Interfaces in the codebase
+grep -rn '^interface\s\|^export interface' --include='*.php' --include='*.ts' app/ src/ \
+  | wc -l
+
+# For each interface, count implementations — flag interfaces with exactly 1
+# (manual review with `phpstorm` or VSCode Go to Implementation)
+
+# PHP heuristic: interfaces with 'Interface' suffix or 'I*' prefix
+grep -rEn '^interface\s+(I[A-Z]|[A-Z][a-zA-Z]+Interface)\b' --include='*.php' app/
+
+# TS heuristic
+grep -rEn '^export interface I[A-Z]|^interface I[A-Z]' --include='*.ts' --include='*.tsx' src/
+```
+
+Reference: [Martin Fowler — YAGNI](https://martinfowler.com/bliki/Yagni.html) · [Sandi Metz — The Wrong Abstraction](https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction) · Internal: [`over-eng-useless-wrapper`](over-eng-useless-wrapper.md), [`naming-suffix-abuse`](naming-suffix-abuse.md)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/over-eng-single-method-class.md

@@ -0,0 +1,161 @@
+---
+title: Single-Method Class That Should Be a Function
+impact: HIGH
+impactDescription: "Wraps a free function in class ceremony for no reason"
+tags: over-engineering, classes, ai-fingerprint
+---
+
+## Single-Method Class That Should Be a Function
+
+**Impact: HIGH (Wraps a free function in class ceremony for no reason)**
+
+A class with exactly one public method, no state, and no dependencies should usually be a function. AI generates these because its training data is enterprise Java/C# where classes are mandatory for everything. PHP and TypeScript both support free functions / static methods / single-purpose action classes — the wrapping ceremony is pure slop.
+
+The exception: **invokable action classes** (Laravel convention) using `__invoke()` are legitimate when they have constructor-injected dependencies and represent a named domain action. The slop variant is the class with no constructor, no state, one static method, and no clear domain identity.
+
+## Incorrect
+
+```php
+// ❌ Class wrapping a single pure function
+
+class StringFormatter
+{
+    public static function slugify(string $input): string
+    {
+        return Str::slug($input);
+    }
+}
+
+class EmailValidator
+{
+    public function isValid(string $email): bool
+    {
+        return filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
+    }
+}
+
+class TimestampHelper
+{
+    public static function toIso(DateTime $dt): string
+    {
+        return $dt->format(DateTimeInterface::ATOM);
+    }
+}
+```
+
+```typescript
+// ❌ Same in TS
+class StringUtil {
+  static capitalize(s: string): string {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+  }
+}
+
+class ResponseFormatter {
+  static format(data: unknown): ApiResponse {
+    return { data, timestamp: Date.now() };
+  }
+}
+```
+
+**Why it's slop:**
+
+- Callers write `StringFormatter::slugify(...)` instead of `slugify(...)`
+- `new EmailValidator()->isValid($email)` is six tokens for what should be one
+- The class adds no encapsulation (no state to encapsulate)
+- Importing/autoloading the class wastes bytes for zero benefit
+- Pattern is recognisably "Java port" — PHP and TS have first-class functions
+
+## Correct
+
+```php
+// ✅ Free function or method on the existing domain type
+
+// helpers.php (or composer autoload "files")
+function slugify(string $input): string
+{
+    return Str::slug($input);
+}
+
+function isValidEmail(string $email): bool
+{
+    return filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
+}
+
+// Or extension methods on Carbon
+class CustomCarbon extends Carbon
+{
+    public function toIso(): string { return $this->format(DateTimeInterface::ATOM); }
+}
+```
+
+```typescript
+// ✅ Free exported functions
+export function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+export function formatResponse<T>(data: T): ApiResponse<T> {
+  return { data, timestamp: Date.now() };
+}
+```
+
+**Why it reads human:**
+
+- Caller writes `slugify(input)` — one token, no ceremony
+- No autoloader hit, no class instantiation, no dependency to mock in tests
+- Functions are testable directly with no setup
+
+## Single-method class is OK when…
+
+These are legitimate, NOT slop:
+
+```php
+// ✅ Invokable action with injected dependencies — Laravel idiom
+final class PlaceOrder
+{
+    public function __construct(
+        private PaymentGateway $payments,
+        private InventoryService $inventory,
+    ) {}
+
+    public function __invoke(OrderRequest $request): Order { /* ... */ }
+}
+
+// ✅ Job / command — meant to be queued
+final class SendWeeklyDigest implements ShouldQueue
+{
+    public function handle(MailerService $mailer): void { /* ... */ }
+}
+
+// ✅ Form Request — Laravel pattern
+final class StoreUserRequest extends FormRequest { /* ... */ }
+```
+
+The test: **does it have state, dependencies, or a domain identity beyond "I wrap a function"?** If yes, it's a class. If no, it should be a function.
+
+## Detection
+
+```bash
+# PHP — classes with exactly one public method and no constructor injection
+# (rough heuristic: file has 'class X' + exactly one 'public function')
+for f in $(find app/ -name '*.php'); do
+  PUBLIC=$(grep -cE '^\s+public function ' "$f")
+  CTOR=$(grep -cE '^\s+public function __construct' "$f")
+  PROPS=$(grep -cE '^\s+(private|protected) (readonly )?[a-zA-Z]+ \$' "$f")
+  if [ "$PUBLIC" = "1" ] && [ "$CTOR" = "0" ] && [ "$PROPS" = "0" ]; then
+    echo "SUSPECT (single-method, no state): $f"
+  fi
+done
+
+# TS — classes with one method and no constructor or fields
+grep -rln 'class\s\+[A-Z]' --include='*.ts' src/ | while read f; do
+  METHODS=$(grep -cE '^\s+(public\s+|private\s+|protected\s+)?[a-zA-Z]+\s*\(' "$f")
+  CTOR=$(grep -c 'constructor' "$f")
+  if [ "$METHODS" = "1" ] && [ "$CTOR" = "0" ]; then
+    echo "SUSPECT: $f"
+  fi
+done
+```
+
+Reference: Internal: [`naming-suffix-abuse`](naming-suffix-abuse.md), [`over-eng-useless-wrapper`](over-eng-useless-wrapper.md)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/over-eng-useless-wrapper.md

@@ -0,0 +1,140 @@
+---
+title: Useless Wrapper Functions
+impact: HIGH
+impactDescription: "Adds indirection layer for no behavioral gain; callers chase one extra hop to find real code"
+tags: over-engineering, wrappers, indirection, ai-fingerprint
+---
+
+## Useless Wrapper Functions
+
+**Impact: HIGH (Adds indirection layer for no behavioral gain; callers chase one extra hop to find real code)**
+
+A function that exists only to delegate to another function, with no added validation, transformation, or context. AI generates these because it pattern-matches on "wrap external dependencies for testability" but applies it indiscriminately.
+
+A wrapper earns its place when it adds **something** the underlying call doesn't: validation, default arguments, error normalisation, logging, retry logic, type narrowing. A wrapper that just forwards arguments is pure indirection.
+
+## Incorrect
+
+```php
+// ❌ Wrappers that just delegate
+
+class UserService
+{
+    public function __construct(private UserRepository $repo) {}
+
+    public function findUser(int $id): ?User
+    {
+        return $this->repo->find($id);
+    }
+
+    public function deleteUser(int $id): void
+    {
+        $this->repo->delete($id);
+    }
+
+    public function createUser(array $data): User
+    {
+        return $this->repo->create($data);
+    }
+}
+```
+
+```typescript
+// ❌ Same TS pattern
+class StripeWrapper {
+  private stripe: Stripe;
+  constructor(stripe: Stripe) {
+    this.stripe = stripe;
+  }
+
+  charge(amount: number, token: string) {
+    return this.stripe.charges.create({ amount, source: token });
+  }
+
+  refund(chargeId: string) {
+    return this.stripe.refunds.create({ charge: chargeId });
+  }
+}
+```
+
+**Why it's slop:**
+
+- `UserService::findUser($id)` does exactly what `$repo->find($id)` does
+- Every caller now goes through TWO layers (`Service → Repo`) to find the actual logic
+- Adding a parameter requires touching both files
+- Tests of `UserService` mostly verify "did we call the repo correctly?" — they don't verify business Behavior
+
+## Correct
+
+```php
+// ✅ Drop the wrapper; use the underlying type directly
+
+// Controller depends on the Repository or Model directly
+public function show(int $id, UserRepository $users): UserResource
+{
+    return new UserResource($users->findOrFail($id));
+}
+```
+
+## When a wrapper IS worth keeping
+
+A wrapper earns its place when it adds something real:
+
+```php
+// ✅ Wrapper that normalises errors + adds retry — real value
+final class ResilientStripeGateway
+{
+    public function __construct(private Stripe $stripe) {}
+
+    public function charge(Money $amount, string $token): Charge
+    {
+        return retry(times: 3, sleepMs: 200, callback: function () use ($amount, $token) {
+            try {
+                return $this->stripe->charges->create([
+                    'amount' => $amount->cents(),
+                    'currency' => $amount->currency()->code(),
+                    'source' => $token,
+                ]);
+            } catch (CardException $e) {
+                throw new PaymentDeclined($e->getMessage(), $e);   // domain exception
+            }
+        });
+    }
+}
+```
+
+This wrapper adds:
+
+- Retry on transient failures
+- Domain-specific exception (`PaymentDeclined`, not `CardException`)
+- Type-safe `Money` input rather than raw cents + currency strings
+
+That's worth the file.
+
+**Why it reads human:**
+
+- Wrappers exist when they add value; non-wrappers don't pad the layer count
+- Caller can see "this charge call is resilient" because the type is `ResilientStripeGateway`
+- No mystery hops to chase
+
+## Detection
+
+```bash
+# Heuristic: methods that are one-liners and just call $this->dependency->method($args)
+# PHP — find public methods whose body is exactly one delegate call
+grep -rEn -A1 '^\s+public function [a-zA-Z]+\([^)]*\)' --include='*.php' app/ | \
+  awk '/public function/{name=$0; next} /^\s+return \$this->[a-zA-Z]+->[a-zA-Z]+\(/{print name; print $0; print "---"}'
+
+# TS — same heuristic
+grep -rEn -A1 '^\s+(public |async )?[a-zA-Z]+\([^)]*\):' --include='*.ts' src/ | \
+  awk '/[a-zA-Z]+\(/{name=$0; next} /return this\.[a-zA-Z]+\./{print name; print $0; print "---"}'
+```
+
+The cleanest signal: **call-sites**. If a wrapper is called from exactly one place, it's almost certainly slop. Inline it.
+
+```bash
+# For each public method in Service.php, count call sites
+# (rough — use phpstorm 'Find Usages' for accurate results)
+```
+
+Reference: [Sandi Metz — The Wrong Abstraction](https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction) · [Martin Fowler — Inline Function](https://refactoring.com/catalog/inlineFunction.html) · Internal: [`over-eng-single-method-class`](over-eng-single-method-class.md), [`over-eng-premature-interface`](over-eng-premature-interface.md)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/style-as-any-escape.md

@@ -0,0 +1,127 @@
+---
+title: as any / @ts-ignore Escape Hatches
+impact: HIGH
+impactDescription: "AI sprinkles these wherever inference is hard — defeats the type system in exactly the places it earns its value"
+tags: style, typescript, type-safety, ai-fingerprint
+---
+
+## as any / @ts-ignore Escape Hatches
+
+**Impact: HIGH (AI sprinkles these wherever inference is hard — defeats the type system in exactly the places it earns its value)**
+
+AI's common move when TypeScript types don't line up cleanly: cast to `any`, add `@ts-ignore`, or annotate with `: any`. The escape hatch silences the compiler — and silences the protection it was about to provide. Worst case: a real bug (wrong shape, missing field, wrong arg order) survives review because the compiler stopped warning.
+
+A reviewer should treat every `as any` / `@ts-ignore` / `@ts-expect-error` as **a request for justification**. Sometimes legitimate (third-party library with bad types, complex generics, runtime-validated unknowns). Often not.
+
+## Incorrect
+
+```typescript
+// ❌ as any sprinkled to silence the compiler
+
+async function processWebhook(payload: unknown): Promise<void> {
+  const event = (payload as any).event; // unknown → any without validation
+  const orderId = (payload as any).data.order.id; // chain of unsafe access
+  await db.orders.update({ where: { id: orderId }, data: { status: "paid" } });
+}
+
+// ❌ @ts-ignore over a real type mismatch
+function calculateTotal(items: Item[]): number {
+  // @ts-ignore — items.map sometimes returns undefined? not sure
+  return items.map((i) => i.price * i.quantity).reduce((a, b) => a + b, 0);
+}
+
+// ❌ : any in function signature
+function processData(data: any) {
+  // gives up on the input shape
+  return data.value;
+}
+
+// ❌ Mixing ts-ignore with no comment
+function send(): void {
+  // @ts-ignore
+  emailService.send(undefined); // why is undefined OK here?
+}
+```
+
+**Why it's slop:**
+
+- `as any` propagates — every subsequent access is also unchecked
+- A real bug (e.g., the payload's actual shape is `payload.event.data.order_id`, not `payload.data.order.id`) doesn't fail until production
+- `@ts-ignore` with no explanation is one of the most-cited AI tells in 2025 reviews
+- `: any` parameters defeat every downstream type check
+
+## Correct
+
+```typescript
+// ✅ Validate at the boundary; types flow through downstream
+
+import { z } from "zod";
+
+const WebhookPayload = z.object({
+  event: z.string(),
+  data: z.object({
+    order: z.object({ id: z.string() }),
+  }),
+});
+
+async function processWebhook(payload: unknown): Promise<void> {
+  const { event, data } = WebhookPayload.parse(payload); // typed from here on
+  await db.orders.update({ where: { id: data.order.id }, data: { status: "paid" } });
+}
+
+// ✅ Fix the real type issue rather than ignore it
+function calculateTotal(items: Item[]): number {
+  return items.reduce((sum, i) => sum + i.price * i.quantity, 0);
+}
+
+// ✅ Type the input
+function processData<T extends { value: string }>(data: T): string {
+  return data.value;
+}
+```
+
+## When the escape hatch IS warranted
+
+Legitimate use is narrow:
+
+- **Bad third-party types** — the lib's `.d.ts` is wrong; you've filed an upstream issue. Use `@ts-expect-error` (not `@ts-ignore`) with a comment naming the issue:
+
+  ```typescript
+  // @ts-expect-error: upstream types incorrectly require `id` — see https://github.com/lib/issues/420
+  ```
+
+- **Migration phase** — moving a JS file to TS gradually; mark debt and track removal
+- **Complex generic constraints** where the compiler can't prove correctness but humans can — annotate with a comment explaining why it's safe
+
+Every escape hatch in production code should have an explanatory comment. No bare `// @ts-ignore`.
+
+## Detection
+
+```bash
+# Count escape hatches in the diff / repo
+grep -rEn '\bas any\b' --include='*.ts' --include='*.tsx' src/ | wc -l
+grep -rEn '@ts-ignore|@ts-nocheck' --include='*.ts' --include='*.tsx' src/ | wc -l
+grep -rEn ': any\b' --include='*.ts' --include='*.tsx' src/ | wc -l
+
+# Bare @ts-ignore / @ts-expect-error without an explanatory comment
+grep -rEnA1 '@ts-(ignore|expect-error)\s*$' --include='*.ts' --include='*.tsx' src/
+```
+
+Add to the Oxlint configuration (`.oxlintrc.json`):
+
+```json
+{
+  "plugins": ["typescript"],
+  "rules": {
+    "typescript/no-explicit-any": "error",
+    "typescript/ban-ts-comment": [
+      "error",
+      { "ts-ignore": "allow-with-description", "ts-expect-error": "allow-with-description" }
+    ]
+  }
+}
+```
+
+**Bar:** zero `as any` / bare `@ts-ignore` in new code. Existing ones grandfathered but tracked.
+
+Reference: [TypeScript handbook — strict mode](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html) · [Oxlint typescript/no-explicit-any](https://oxc.rs/docs/guide/usage/linter/rules/typescript/no-explicit-any.html) · [Oxlint typescript/ban-ts-comment](https://oxc.rs/docs/guide/usage/linter/rules/typescript/ban-ts-comment.html) · [Zod](https://zod.dev/) · Internal: [`defensive-impossible-null`](defensive-impossible-null.md)