@sun-asterisk/sunlint 1.3.48 → 1.3.49

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV006-queue-heavy-tasks.md

@@ -0,0 +1,68 @@
+---
+title: Queue Heavy Tasks — Never Block the Request Cycle
+impact: HIGH
+impactDescription: synchronous email/external API calls cause request timeouts and degrade user experience under load
+tags: queues, jobs, email, performance, background, laravel
+---
+
+## Queue Heavy Tasks — Never Block the Request Cycle
+
+Any task over ~200ms (sending email, calling external APIs, generating reports, processing images) must be dispatched to a queue, not executed synchronously in the HTTP request.
+
+**Wrong:**
+
+```php
+// Request handler blocked for seconds
+public function register(StoreUserRequest $request)
+{
+    $user = User::create($request->validated());
+
+    // Blocks for 1-3 seconds — user waits, timeout risk
+    Mail::to($user)->send(new WelcomeEmail($user));
+
+    // Calls Slack API — blocks if Slack is slow
+    Http::post(config('services.slack.webhook'), ['text' => "New user: {$user->email}"]);
+
+    return response()->json($user, 201);
+}
+```
+
+**Correct:**
+
+```bash
+php artisan make:job SendWelcomeEmail
+php artisan make:job NotifySlackNewUser
+```
+
+```php
+public function register(StoreUserRequest $request)
+{
+    $user = User::create($request->validated());
+
+    // Dispatch to queue — returns immediately
+    SendWelcomeEmail::dispatch($user)->onQueue('emails');
+    NotifySlackNewUser::dispatch($user)->onQueue('notifications');
+
+    return response()->json($user, 201); // responds in <50ms
+}
+
+// Job class
+class SendWelcomeEmail implements ShouldQueue
+{
+    use Queueable, Dispatchable, InteractsWithQueue, SerializesModels;
+
+    public function __construct(private User $user) {}
+
+    public function handle(): void
+    {
+        Mail::to($this->user)->send(new WelcomeEmail($this->user));
+    }
+
+    public function failed(Throwable $e): void
+    {
+        Log::error('WelcomeEmail failed', ['user' => $this->user->id, 'error' => $e->getMessage()]);
+    }
+}
+```
+
+**Queue-worthy operations:** email, SMS, push notifications, Slack/webhook, PDF generation, image resize, CSV export, expensive calculations, third-party API calls.

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV007-hash-passwords.md

@@ -0,0 +1,51 @@
+---
+title: Use Hash::make() for Passwords — Never md5/sha1/bcrypt()
+impact: CRITICAL
+impactDescription: MD5/SHA1 are broken for passwords; Laravel's Hash facade uses bcrypt/argon2 with proper salting automatically
+tags: password, hashing, bcrypt, security, hash, laravel
+---
+
+## Use Hash::make() for Passwords
+
+Laravel's `Hash` facade automatically uses the configured driver (bcrypt by default, upgradeable to argon2id). Never use PHP's raw `password_hash()` directly without going through Laravel's config, and never use `md5()` or `sha1()`.
+
+**Wrong:**
+
+```php
+// md5/sha1 — broken, no salting, rainbow-table vulnerable
+$user->password = md5($request->password);
+$user->password = sha1($request->password);
+
+// Raw PHP without config — bypasses algorithm config
+$user->password = password_hash($request->password, PASSWORD_BCRYPT);
+```
+
+**Correct:**
+
+```php
+// Creating a user
+$user = User::create([
+    'name'     => $request->name,
+    'email'    => $request->email,
+    'password' => Hash::make($request->password), // salted + bcrypt/argon2
+]);
+
+// Verifying on login — NEVER compare raw strings
+if (!Hash::check($request->password, $user->password)) {
+    throw ValidationException::withMessages([
+        'email' => ['These credentials do not match our records.'],
+    ]);
+}
+
+// Rehash on login if algorithm changed
+if (Hash::needsRehash($user->password)) {
+    $user->update(['password' => Hash::make($request->password)]);
+}
+```
+
+**Config:** Change algorithm in `config/hashing.php`:
+```php
+'driver' => 'argon2id', // upgrade from default bcrypt for new projects
+```
+
+**In migrations:** password column must be `string(255)`, not `string(32)` — bcrypt hashes are 60 chars, argon2id up to 95.

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV008-route-model-binding.md

@@ -0,0 +1,67 @@
+---
+title: Use Route Model Binding — No Manual find() in Controllers
+impact: MEDIUM
+impactDescription: eliminates repetitive find-or-404 boilerplate, centralizes authorization scope
+tags: route-model-binding, controller, eloquent, laravel, routing
+---
+
+## Use Route Model Binding
+
+Laravel resolves model instances automatically from route parameters. Writing `User::findOrFail($id)` manually in every controller method is redundant boilerplate.
+
+**Wrong:**
+
+```php
+// routes/api.php
+Route::get('/posts/{id}', [PostController::class, 'show']);
+
+// Controller
+public function show(int $id)
+{
+    $post = Post::findOrFail($id); // unnecessary boilerplate
+    $this->authorize('view', $post);
+    return PostResource::make($post);
+}
+```
+
+**Correct:**
+
+```php
+// routes/api.php — use the model name as parameter
+Route::get('/posts/{post}', [PostController::class, 'show']);
+
+// Controller — Laravel resolves Post automatically, throws 404 if not found
+public function show(Post $post)
+{
+    $this->authorize('view', $post);
+    return PostResource::make($post);
+}
+```
+
+**Custom binding key** (e.g. slug instead of id):
+
+```php
+// Model
+class Post extends Model
+{
+    public function getRouteKeyName(): string
+    {
+        return 'slug'; // /posts/my-post-slug
+    }
+}
+```
+
+**Scoped binding** (child must belong to parent):
+
+```php
+// /users/{user}/posts/{post} — post must belong to user
+Route::get('/users/{user}/posts/{post}', [PostController::class, 'show'])
+    ->scopeBindings();
+```
+
+**With eager loading:**
+
+```php
+// Customize resolution for eager-loading
+Route::bind('post', fn($value) => Post::with(['author', 'tags'])->findOrFail($value));
+```

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV009-api-resources.md

@@ -0,0 +1,72 @@
+---
+title: Use API Resources for Response Transformation
+impact: HIGH
+impactDescription: prevents over-exposure of model fields, decouples DB schema from API contract, enables versioning
+tags: api-resources, response, transformation, security, laravel
+---
+
+## Use API Resources for Response Transformation
+
+Returning `$model->toArray()` or `response()->json($model)` exposes all model attributes including sensitive fields (`password`, `remember_token`, internal flags). API Resources control exactly what is serialized.
+
+**Wrong:**
+
+```php
+// Exposes ALL columns including password, remember_token, internal flags
+return response()->json($user);
+return response()->json(User::all());
+return response()->json($user->toArray());
+```
+
+**Correct:**
+
+```bash
+php artisan make:resource UserResource
+php artisan make:resource UserCollection
+```
+
+```php
+// app/Http/Resources/UserResource.php
+class UserResource extends JsonResource
+{
+    public function toArray(Request $request): array
+    {
+        return [
+            'id'         => $this->id,
+            'name'       => $this->name,
+            'email'      => $this->email,
+            'avatar_url' => $this->avatar_url,
+            'created_at' => $this->created_at->toIso8601String(),
+
+            // Conditional fields
+            'phone' => $this->when(
+                $request->user()?->id === $this->id,
+                $this->phone
+            ),
+
+            // Nested resource
+            'posts_count' => $this->whenCounted('posts'),
+        ];
+    }
+}
+
+// Controller
+public function show(User $user): UserResource
+{
+    return UserResource::make($user);
+}
+
+public function index(): JsonResponse
+{
+    $users = User::with('profile')->paginate(20);
+    return UserResource::collection($users)->response();
+}
+```
+
+**Password and sensitive fields must be in `$hidden`:**
+```php
+class User extends Model
+{
+    protected $hidden = ['password', 'remember_token', 'two_factor_secret'];
+}
+```

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV010-chunk-large-datasets.md

@@ -0,0 +1,58 @@
+---
+title: Use chunk()/cursor() for Large Datasets — Never Model::all()
+impact: HIGH
+impactDescription: Model::all() on a large table loads all rows into memory, causing OOM errors and PHP timeouts
+tags: chunk, cursor, memory, performance, eloquent, laravel
+---
+
+## Use chunk()/cursor() for Large Datasets
+
+`Model::all()` or `->get()` with no limit fetches every row into PHP memory. On a 100k-row table this causes memory exhaustion.
+
+**Wrong:**
+
+```php
+// Memory bomb — loads all rows into PHP array
+$users = User::all();
+foreach ($users as $user) {
+    $user->sendNewsletter();
+}
+
+// Slightly better but still: loads 50k orders at once
+$orders = Order::where('status', 'pending')->get();
+foreach ($orders as $order) {
+    ProcessOrder::dispatch($order);
+}
+```
+
+**Correct:**
+
+```php
+// chunk: fetches 200 rows at a time, re-queries per batch
+User::chunk(200, function ($users) {
+    foreach ($users as $user) {
+        $user->sendNewsletter();
+    }
+});
+
+// cursor: uses lazy collection (PHP generator), one row in memory at a time
+// Best for read-only iteration without modifying records
+foreach (User::cursor() as $user) {
+    $user->sendNewsletter();
+}
+
+// chunkById: safer than chunk for updates (avoids row-skip bug)
+User::where('status', 'inactive')
+    ->chunkById(500, function ($users) {
+        User::whereIn('id', $users->pluck('id'))->delete();
+    });
+
+// For commands/jobs that process everything
+User::select(['id', 'email', 'name']) // only needed columns
+    ->where('newsletter', true)
+    ->chunkById(1000, function ($batch) {
+        SendNewsletterJob::dispatch($batch->pluck('id')->all());
+    });
+```
+
+**Rule of thumb:** any query without `->limit()` or `->paginate()` in a loop or report command must use `chunk()` or `cursor()`.

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV011-db-transactions.md

@@ -0,0 +1,73 @@
+---
+title: Wrap Multi-Step Database Operations in Transactions
+impact: HIGH
+impactDescription: partial failures leave the database in an inconsistent state without transactions
+tags: transactions, database, atomicity, eloquent, laravel
+---
+
+## Wrap Multi-Step Database Operations in Transactions
+
+Any sequence of writes that must succeed or fail together (e.g. create order + deduct stock + charge payment) must run inside a `DB::transaction()`.
+
+**Wrong:**
+
+```php
+// If deductStock() succeeds but createTransaction() fails,
+// stock is deducted but no order exists — corrupted state
+public function placeOrder(Cart $cart, User $user): Order
+{
+    $order = Order::create([...]);
+    $this->deductStock($cart->items);    // can throw
+    $this->createTransaction($order);    // can throw — order exists, stock reduced
+    $this->clearCart($cart);
+    return $order;
+}
+```
+
+**Correct:**
+
+```php
+use Illuminate\Support\Facades\DB;
+
+public function placeOrder(Cart $cart, User $user): Order
+{
+    return DB::transaction(function () use ($cart, $user) {
+        $order = Order::create([
+            'user_id' => $user->id,
+            'total'   => $cart->total(),
+        ]);
+
+        $this->deductStock($cart->items);    // exception -> full rollback
+        $this->createTransaction($order);    // exception -> full rollback
+        $this->clearCart($cart);
+
+        return $order;
+    });
+    // Any Throwable inside auto-rolls back and re-throws
+}
+```
+
+**With custom exception handling:**
+
+```php
+DB::transaction(function () {
+    // ...
+}, attempts: 3); // retry on deadlock (3 attempts)
+```
+
+**Manual control when needed:**
+```php
+DB::beginTransaction();
+try {
+    // ...
+    DB::commit();
+} catch (Throwable $e) {
+    DB::rollBack();
+    throw $e;
+}
+```
+
+**Note:** Dispatching jobs inside a transaction should use `afterCommit()`:
+```php
+ProcessOrder::dispatch($order)->afterCommit(); // only dispatches if transaction commits
+```

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV012-service-layer.md

@@ -0,0 +1,78 @@
+---
+title: Use Service Layer — Controllers Must Not Contain Business Logic
+impact: HIGH
+impactDescription: fat controllers are untestable, unmaintainable, and couple HTTP concerns with domain logic
+tags: service-layer, architecture, clean-code, controller, laravel
+---
+
+## Use Service Layer — Controllers Must Not Contain Business Logic
+
+Controllers handle HTTP: parse request, call service, return response. Domain logic (calculations, business rules, orchestration) belongs in a dedicated Service class.
+
+**Wrong:**
+
+```php
+// OrderController doing everything — HTTP + business + DB
+public function store(StoreOrderRequest $request)
+{
+    $subtotal = 0;
+    foreach ($request->items as $item) {
+        $product = Product::find($item['product_id']);
+        if ($product->stock < $item['qty']) {
+            return response()->json(['error' => 'Insufficient stock'], 422);
+        }
+        $subtotal += $product->price * $item['qty'];
+    }
+
+    $discount = $request->user()->isPremium() ? $subtotal * 0.1 : 0;
+    $total = $subtotal - $discount + $this->calculateShipping($request->address);
+
+    $order = Order::create([...]);
+    foreach ($request->items as $item) { /* create OrderItem, deduct stock */ }
+
+    Mail::to($request->user())->send(new OrderConfirmation($order));
+    return OrderResource::make($order);
+}
+```
+
+**Correct:**
+
+```php
+// Service contains all business logic
+class OrderService
+{
+    public function __construct(
+        private readonly InventoryService $inventory,
+        private readonly PricingService   $pricing,
+    ) {}
+
+    public function placeOrder(User $user, array $items, Address $address): Order
+    {
+        $this->inventory->reserveItems($items);        // throws on insufficient stock
+        $total = $this->pricing->calculate($items, $user, $address);
+
+        return DB::transaction(function () use ($user, $items, $total) {
+            $order = Order::create(['user_id' => $user->id, 'total' => $total]);
+            $this->inventory->commitReservation($order, $items);
+            SendOrderConfirmation::dispatch($order);
+            return $order;
+        });
+    }
+}
+
+// Controller is just HTTP glue
+class OrderController
+{
+    public function __construct(private readonly OrderService $orderService) {}
+
+    public function store(StoreOrderRequest $request): JsonResponse
+    {
+        $order = $this->orderService->placeOrder(
+            $request->user(),
+            $request->validated('items'),
+            Address::fromRequest($request),
+        );
+        return OrderResource::make($order)->response()->setStatusCode(201);
+    }
+}
+```

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV013-testing-factories.md

@@ -0,0 +1,75 @@
+---
+title: Use RefreshDatabase + Factories in Tests — No Manual Inserts
+impact: MEDIUM
+impactDescription: manual DB inserts create brittle tests tightly coupled to schema; factories stay in sync with model changes
+tags: testing, factories, refresh-database, pest, phpunit, laravel
+---
+
+## Use RefreshDatabase + Factories in Tests
+
+Hardcoded `DB::table()->insert()` or `User::create([...])` with raw data creates brittle tests. Use model factories with `RefreshDatabase` for isolated, maintainable tests.
+
+**Wrong:**
+
+```php
+class OrderTest extends TestCase
+{
+    protected function setUp(): void
+    {
+        parent::setUp();
+        DB::table('users')->insert(['id' => 1, 'name' => 'Test', 'email' => 'test@test.com', 'password' => 'xxx']);
+        DB::table('products')->insert(['id' => 1, 'name' => 'Widget', 'price' => 100, 'stock' => 10]);
+        // Test fails when schema changes
+    }
+
+    public function test_can_place_order()
+    {
+        $response = $this->post('/orders', ['product_id' => 1, 'qty' => 2]);
+        $this->assertEquals(200, $response->getStatusCode());
+    }
+}
+```
+
+**Correct (PHPUnit):**
+
+```php
+class OrderTest extends TestCase
+{
+    use RefreshDatabase; // wraps each test in a transaction, rolled back after
+
+    public function test_authenticated_user_can_place_order(): void
+    {
+        $user    = User::factory()->create();
+        $product = Product::factory()->create(['price' => 100, 'stock' => 10]);
+
+        $response = $this->actingAs($user)
+            ->postJson('/api/orders', ['product_id' => $product->id, 'qty' => 2])
+            ->assertCreated()
+            ->assertJsonPath('data.total', 200);
+
+        $this->assertDatabaseHas('orders', ['user_id' => $user->id, 'total' => 200]);
+        $this->assertDatabaseHas('products', ['id' => $product->id, 'stock' => 8]);
+    }
+
+    public function test_order_fails_when_insufficient_stock(): void
+    {
+        $user    = User::factory()->create();
+        $product = Product::factory()->create(['stock' => 1]);
+
+        $this->actingAs($user)
+            ->postJson('/api/orders', ['product_id' => $product->id, 'qty' => 5])
+            ->assertUnprocessable()
+            ->assertJsonValidationErrors(['qty']);
+    }
+}
+```
+
+**Factory patterns:**
+```php
+// Specific state
+$admin  = User::factory()->admin()->create();
+$banned = User::factory()->banned()->unverified()->create();
+
+// With relations
+$post = Post::factory()->for($user)->hasComments(3)->create();
+```

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV014-service-container.md

@@ -0,0 +1,61 @@
+---
+title: Register Services in AppServiceProvider — Never new() in Controllers
+impact: MEDIUM
+impactDescription: direct instantiation prevents mocking in tests and creates hidden dependencies
+tags: service-container, dependency-injection, ioc, laravel, testing
+---
+
+## Register Services via Service Container — Never new() in Controllers
+
+Laravel's IoC container resolves dependencies automatically via constructor injection. Using `new MyService()` inside a controller or service bypasses the container, making tests hard and coupling impossible to break.
+
+**Wrong:**
+
+```php
+class OrderController extends Controller
+{
+    public function store(StoreOrderRequest $request)
+    {
+        // Hidden dependencies, impossible to mock
+        $service    = new OrderService(new InventoryService(), new PricingService());
+        $mailer     = new OrderMailer(new SmtpTransport());
+    }
+}
+```
+
+**Correct:**
+
+```php
+// 1. Bind in AppServiceProvider if needed (often not needed — auto-resolved)
+class AppServiceProvider extends ServiceProvider
+{
+    public function register(): void
+    {
+        $this->app->singleton(PaymentGateway::class, function () {
+            return new StripeGateway(config('services.stripe.secret'));
+        });
+
+        // Interface → concrete binding
+        $this->app->bind(NotifierInterface::class, SlackNotifier::class);
+    }
+}
+
+// 2. Controller receives via constructor — auto-resolved by container
+class OrderController extends Controller
+{
+    public function __construct(
+        private readonly OrderService    $orderService,
+        private readonly NotifierInterface $notifier,
+    ) {}
+
+    public function store(StoreOrderRequest $request): JsonResponse
+    {
+        $order = $this->orderService->placeOrder($request->user(), $request->validated());
+        $this->notifier->notify("New order #{$order->id}");
+        return OrderResource::make($order)->response()->setStatusCode(201);
+    }
+}
+
+// 3. In tests — swap the binding
+$this->app->instance(NotifierInterface::class, $mockNotifier);
+```

package/skill-assets/sunlint-code-quality/rules/python/P001-mutable-default-argument.md

@@ -0,0 +1,55 @@
+---
+title: Do Not Use Mutable Default Argument
+impact: HIGH
+impactDescription: Mutable default arguments are shared across all calls, causing subtle state bugs that are very hard to trace.
+tags: python, bugs, arguments, pitfalls, quality
+---
+
+## Do Not Use Mutable Default Argument
+
+In Python, default argument values are evaluated **once** at function definition time, not at each call. Using mutable objects (list, dict, set) as defaults causes all callers to share the same object, leading to unexpected side effects across calls.
+
+**Incorrect:**
+```python
+def add_item(item, collection=[]):
+    collection.append(item)
+    return collection
+
+print(add_item("a"))  # ["a"]
+print(add_item("b"))  # ["a", "b"]  ← bug: list persists between calls
+
+def create_user(name, roles={"admin": False}):
+    roles["user"] = True
+    return {"name": name, "roles": roles}
+```
+
+**Correct:**
+```python
+def add_item(item, collection=None):
+    if collection is None:
+        collection = []
+    collection.append(item)
+    return collection
+
+print(add_item("a"))  # ["a"]
+print(add_item("b"))  # ["b"]  ← each call gets a fresh list
+
+def create_user(name, roles=None):
+    if roles is None:
+        roles = {"admin": False}
+    roles["user"] = True
+    return {"name": name, "roles": roles}
+```
+
+**Dataclass alternative (Python 3.7+):**
+```python
+from dataclasses import dataclass, field
+from typing import List
+
+@dataclass
+class Task:
+    name: str
+    tags: List[str] = field(default_factory=list)  # safe: fresh list per instance
+```
+
+**Tools:** Ruff `B006` (mutable-argument-default), Pylint `W0102` (dangerous-default-value), flake8-bugbear, mypy