@sun-asterisk/sunlint 1.3.47 → 1.3.49

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

package/skill-assets/sunlint-code-quality/rules/python/P002-specify-file-encoding.md

@@ -0,0 +1,45 @@
+---
+title: Specify Encoding When Opening Files
+impact: MEDIUM
+impactDescription: Omitting encoding when opening text files causes silent failures on systems with non-UTF-8 locale, resulting in UnicodeDecodeError or garbled data in production.
+tags: python, encoding, files, portability, quality
+---
+
+## Specify Encoding When Opening Files
+
+When calling `open()` in text mode without an explicit `encoding` argument, Python uses the OS's default locale encoding. This is typically UTF-8 on Linux/macOS, but `cp1252` or similar on Windows. Code that works locally can silently fail or corrupt data in other environments.
+
+Always pass `encoding="utf-8"` (or whatever the file format requires) explicitly.
+
+**Incorrect:**
+```python
+# Relies on OS default — breaks on Windows or non-UTF-8 systems
+with open("data.txt") as f:
+    content = f.read()
+
+with open("output.csv", "w") as f:
+    f.write("café,prix\n")
+```
+
+**Correct:**
+```python
+with open("data.txt", encoding="utf-8") as f:
+    content = f.read()
+
+with open("output.csv", "w", encoding="utf-8") as f:
+    f.write("café,prix\n")
+
+# When reading binary, no encoding needed
+with open("image.png", "rb") as f:
+    data = f.read()
+```
+
+**Pathlib equivalent (also requires explicit encoding):**
+```python
+from pathlib import Path
+
+content = Path("data.txt").read_text(encoding="utf-8")
+Path("output.txt").write_text("hello", encoding="utf-8")
+```
+
+**Tools:** Ruff `W1514` / `PLW1514` (unspecified-encoding), Pylint `W1514`, flake8-bugbear

package/skill-assets/sunlint-code-quality/rules/python/P003-context-manager-for-resources.md

@@ -0,0 +1,54 @@
+---
+title: Use Context Manager for File and Resource Handling
+impact: MEDIUM
+impactDescription: Not using with statement for file/network/lock resources causes resource leaks when exceptions are raised, leading to open file handles, locked databases, and memory exhaustion.
+tags: python, resources, context-manager, files, quality
+---
+
+## Use Context Manager for File and Resource Handling
+
+Python's `with` statement (context manager protocol) guarantees that resources are released even when exceptions occur. Always use `with` when dealing with files, network connections, database cursors, threading locks, and any object that implements `__enter__`/`__exit__`.
+
+**Incorrect:**
+```python
+# File handle not closed if exception occurs
+f = open("data.txt", encoding="utf-8")
+content = f.read()  # If this raises, f.close() is never called
+f.close()
+
+# Lock never released if exception raised inside
+lock = threading.Lock()
+lock.acquire()
+do_work()  # Exception here leaves lock permanently acquired
+lock.release()
+```
+
+**Correct:**
+```python
+# File is always closed, even on exception
+with open("data.txt", encoding="utf-8") as f:
+    content = f.read()
+
+# Lock always released
+import threading
+
+lock = threading.Lock()
+with lock:
+    do_work()
+
+# Multiple context managers in one with
+with open("input.txt", encoding="utf-8") as fin, \
+     open("output.txt", "w", encoding="utf-8") as fout:
+    fout.write(fin.read())
+```
+
+**contextlib.suppress as context manager:**
+```python
+import contextlib
+
+# Instead of try/except/pass
+with contextlib.suppress(FileNotFoundError):
+    os.remove("temp.txt")
+```
+
+**Tools:** Ruff `SIM115` (open-file-with-context-handler), `R1732` (consider-using-with), Pylint, flake8-simplify

package/skill-assets/sunlint-code-quality/rules/python/P004-no-bare-except.md

@@ -0,0 +1,65 @@
+---
+title: Never Use Bare except Clause
+impact: HIGH
+impactDescription: A bare except catches SystemExit and KeyboardInterrupt, making programs impossible to interrupt and hiding unrelated errors that should propagate.
+tags: python, exceptions, error-handling, pitfalls, quality
+---
+
+## Never Use Bare except Clause
+
+A bare `except:` clause (with no exception type specified) catches **every** exception, including `SystemExit` (raised by `sys.exit()`), `KeyboardInterrupt` (Ctrl+C), and `GeneratorExit`. This prevents programs from being terminated normally, swallows programming errors, and makes debugging extremely difficult.
+
+Always specify the exception type(s) you intend to handle.
+
+**Incorrect:**
+```python
+# Catches SystemExit and KeyboardInterrupt — program cannot be stopped
+try:
+    process_data()
+except:
+    print("Something went wrong")
+
+# Also problematic: too broad
+try:
+    connect_to_db()
+except Exception:
+    pass  # silently ignores all errors including programming mistakes
+```
+
+**Correct:**
+```python
+# Catch only what you expect and can handle
+try:
+    process_data()
+except ValueError as e:
+    logger.warning("Invalid data: %s", e)
+except OSError as e:
+    logger.error("I/O error during processing: %s", e)
+
+# If you need a catch-all, at least log it and re-raise
+try:
+    connect_to_db()
+except Exception as e:
+    logger.error("Unexpected error connecting to DB: %s", e, exc_info=True)
+    raise
+
+# Correct way to suppress a specific expected error
+import contextlib
+
+with contextlib.suppress(FileNotFoundError):
+    os.remove("temp.txt")
+```
+
+**Exception hierarchy to catch:**
+```python
+# Prefer specific → broad order
+try:
+    result = int(user_input)
+except ValueError:
+    result = 0  # handle invalid literal
+except (TypeError, OverflowError) as e:
+    logger.warning("Type issue: %s", e)
+    result = 0
+```
+
+**Tools:** Ruff `E722` (bare-except), `W0702` in Pylint, `BLE001` (blind-except), flake8, pyflakes

package/skill-assets/sunlint-code-quality/rules/python/P005-use-isinstance.md

@@ -0,0 +1,60 @@
+---
+title: Use isinstance() Instead of type() for Type Checking
+impact: MEDIUM
+impactDescription: Using type() == for type checks breaks polymorphism and inheritance, rejecting valid subclass instances that should be accepted by the contract.
+tags: python, typing, isinstance, quality, oop
+---
+
+## Use isinstance() Instead of type() for Type Checking
+
+The `type(x) == SomeClass` pattern performs an exact type match and does not account for subclasses. This violates the Liskov Substitution Principle: code that accepts a `list` should also accept `UserList` or any other list subclass.
+
+Use `isinstance()` which checks the full MRO (method resolution order) and correctly handles subclasses and abstract base classes.
+
+**Incorrect:**
+```python
+def process(data):
+    if type(data) == list:    # rejects OrderedList, UserList, etc.
+        for item in data:
+            handle(item)
+    if type(data) == dict:    # rejects defaultdict, OrderedDict, etc.
+        process_mapping(data)
+
+def serialize(value):
+    if type(value) == str:    # rejects str subclasses
+        return value.encode("utf-8")
+```
+
+**Correct:**
+```python
+def process(data):
+    if isinstance(data, list):    # accepts all list subclasses
+        for item in data:
+            handle(item)
+    if isinstance(data, dict):    # accepts defaultdict, OrderedDict, etc.
+        process_mapping(data)
+
+def serialize(value):
+    if isinstance(value, str):
+        return value.encode("utf-8")
+
+# Use abstract base classes for duck typing
+from collections.abc import Mapping, Sequence
+
+def process_generic(data):
+    if isinstance(data, Sequence):  # list, tuple, str, UserList, etc.
+        for item in data:
+            handle(item)
+    if isinstance(data, Mapping):   # dict, defaultdict, ChainMap, etc.
+        process_mapping(data)
+```
+
+**Exception — when exact type match IS needed:**
+```python
+# Only use type() == when you explicitly want to exclude subclasses
+# e.g., in a serialization library distinguishing bool from int:
+if type(value) is bool:  # True/False, not int subclasses
+    return str(value).lower()
+```
+
+**Tools:** Ruff `E721` (type-comparison), Pylint `C0123` (unidiomatic-typecheck), mypy, pyright

package/skill-assets/sunlint-code-quality/rules/python/P006-timezone-aware-datetime.md

@@ -0,0 +1,58 @@
+---
+title: Always Use Timezone-Aware Datetimes
+impact: HIGH
+impactDescription: Naive datetimes (without tzinfo) cause silent bugs when comparing times across timezones, leading to incorrect scheduling, expiry calculations, and audit logs.
+tags: python, datetime, timezone, bugs, quality
+---
+
+## Always Use Timezone-Aware Datetimes
+
+Python's `datetime` objects can be *naive* (no timezone) or *aware* (with timezone). Mixing naive and aware datetimes raises a `TypeError`, but naive datetimes used consistently silently produce wrong results when code runs in different timezones (CI server vs production, container vs host).
+
+Always create timezone-aware datetimes by passing `tz` or `tzinfo`.
+
+**Incorrect:**
+```python
+from datetime import datetime
+
+# Naive datetimes — "now" means different things in Tokyo vs London
+created_at = datetime.now()
+expires_at = datetime.utcnow()  # UTC but naive — still dangerous
+
+# Comparing naive datetimes assumes both are in same timezone (often wrong)
+if datetime.now() > token_expiry:  # fails if token_expiry is aware
+    raise TokenExpiredError()
+```
+
+**Correct:**
+```python
+from datetime import datetime, timezone
+
+# Python 3.11+: use datetime.UTC constant
+now = datetime.now(tz=timezone.utc)
+
+# Python 3.9+: use zoneinfo for local zones
+from zoneinfo import ZoneInfo
+
+jst_now = datetime.now(tz=ZoneInfo("Asia/Tokyo"))
+utc_now = datetime.now(tz=timezone.utc)
+
+# django/pytz style (pre-3.9)
+import pytz
+
+utc_now = datetime.now(tz=pytz.utc)
+
+# Always compare aware with aware
+token_expiry: datetime  # must be aware
+if datetime.now(tz=timezone.utc) > token_expiry:
+    raise TokenExpiredError()
+```
+
+**Converting naive to aware (migration):**
+```python
+# Assume a legacy naive datetime is UTC — localize it explicitly
+naive_dt = datetime(2024, 1, 15, 10, 30)
+aware_dt = naive_dt.replace(tzinfo=timezone.utc)
+```
+
+**Tools:** Ruff `DTZ001`–`DTZ012` (flake8-datetimez), Pylint `W1502`, mypy with `--strict-optional`

package/skill-assets/sunlint-code-quality/rules/python/P007-use-pathlib.md

@@ -0,0 +1,62 @@
+---
+title: Use pathlib Instead of os.path for File Operations
+impact: MEDIUM
+impactDescription: os.path functions return plain strings that are easy to misuse; pathlib.Path provides an object-oriented, composable, and cross-platform API that eliminates common path manipulation bugs.
+tags: python, pathlib, os-path, files, quality, python3
+---
+
+## Use pathlib Instead of os.path for File Operations
+
+Python 3.4 introduced `pathlib.Path` as a modern, object-oriented replacement for `os.path`. Paths are represented as objects supporting `/` operator for joining, `.stem`, `.suffix`, `.parent` for decomposition, and `.read_text()` / `.write_text()` for content — with no risk of forgetting `os.path.join` and accidentally concatenating strings.
+
+**Incorrect:**
+```python
+import os
+
+# String concatenation — silent bugs on Windows with backslashes
+config_path = base_dir + "/config/" + "settings.json"
+
+# Verbose os.path usage
+import os.path
+
+full_path = os.path.join(base_dir, "config", "settings.json")
+file_name = os.path.basename(full_path)
+dir_name  = os.path.dirname(full_path)
+stem      = os.path.splitext(file_name)[0]
+ext       = os.path.splitext(file_name)[1]
+
+if os.path.exists(config_path):
+    with open(config_path, encoding="utf-8") as f:
+        content = f.read()
+
+os.makedirs(os.path.join(base_dir, "logs"), exist_ok=True)
+```
+
+**Correct:**
+```python
+from pathlib import Path
+
+base_dir = Path("/app")
+
+# / operator for joining — cross-platform and clear
+config_path = base_dir / "config" / "settings.json"
+
+# Readable decomposition
+file_name = config_path.name        # "settings.json"
+dir_name  = config_path.parent      # Path("/app/config")
+stem      = config_path.stem        # "settings"
+ext       = config_path.suffix      # ".json"
+
+# Built-in existence check and file reading
+if config_path.exists():
+    content = config_path.read_text(encoding="utf-8")
+
+# Directory creation
+(base_dir / "logs").mkdir(parents=True, exist_ok=True)
+
+# Glob for files
+for py_file in base_dir.rglob("*.py"):
+    print(py_file)
+```
+
+**Tools:** Ruff `PTH100`–`PTH208` (flake8-use-pathlib), pyupgrade, SonarQube Python rules

package/skill-assets/sunlint-code-quality/rules/python/P008-no-wildcard-import.md

@@ -0,0 +1,52 @@
+---
+title: Never Use Wildcard Imports
+impact: HIGH
+impactDescription: Wildcard imports pollute the namespace, make it impossible to trace where a name comes from, and can silently override existing names, causing hard-to-debug subtle bugs.
+tags: python, imports, namespace, quality, readability
+---
+
+## Never Use Wildcard Imports
+
+`from module import *` imports every public name from a module into the current namespace. This:
+- Makes it impossible to know where any name is defined without reading the imported module
+- Can silently override names from prior imports or `builtins`
+- Prevents static analysis tools from detecting undefined names
+- Breaks auto-complete and go-to-definition in IDEs
+
+The only acceptable use of `import *` is in a package's `__init__.py` to re-export a curated public API defined in `__all__`.
+
+**Incorrect:**
+```python
+from os.path import *      # which names are now in scope?
+from numpy import *        # overrides Python's built-in sum, any, all, etc.
+from models import *       # User? Order? both? neither?
+from utils import *
+
+# Now these silently shadow built-ins:
+result = sum([1, 2, 3])    # which sum? Python's or numpy's?
+```
+
+**Correct:**
+```python
+import os
+from os import path as osp                    # or use pathlib
+from pathlib import Path
+import numpy as np                            # conventional alias
+from models import User, Order, Product       # explicit names
+from utils import format_date, validate_email
+
+# Clear provenance for every name
+result = np.sum([1, 2, 3])
+full_path = Path("/data") / "file.txt"
+```
+
+**Acceptable use in `__init__.py`:**
+```python
+# package/__init__.py — re-export public API
+from .client import Client
+from .exceptions import APIError, RateLimitError
+
+__all__ = ["Client", "APIError", "RateLimitError"]
+```
+
+**Tools:** Ruff `F403` (undefined-local-with-import-star), `W0401` in Pylint (wildcard-import), flake8, isort