@sun-asterisk/sunlint 1.3.39 → 1.3.41

package/skill-assets/sunlint-code-quality/rules/php/C006-verb-noun-functions.md

@@ -0,0 +1,46 @@
+---
+title: Function Names Verb-Noun
+impact: LOW
+impactDescription: makes code self-documenting
+tags: naming, functions, readability, conventions, quality, php
+---
+
+## Function Names Verb-Noun
+
+Functions represent actions. Using "Verb-Noun" pattern makes the purpose of the function clear and the code self-documenting.
+
+**Incorrect (vague names):**
+
+```php
+function user() { }           // Noun only
+function userData() { }       // Noun only
+function process() { }        // Vague
+function handle() { }         // Vague
+function stuff() { }          // Noun only
+```
+
+**Correct (action verbs):**
+
+```php
+function getUser() { }
+function createUserAccount() { }
+function validateEmailFormat() { }
+function calculateTotalPrice() { }
+function sendConfirmationEmail() { }
+function convertCurrencyToUSD() { }
+function hasActiveSubscription(): bool { }
+```
+
+**Verb categories:**
+
+| Category | Verbs |
+|----------|-------|
+| Retrieval | `get`, `fetch`, `find`, `load`, `query` |
+| Creation | `create`, `build`, `make`, `generate` |
+| Modification | `set`, `update`, `modify`, `change`, `save` |
+| Deletion | `delete`, `remove`, `destroy`, `clear` |
+| Validation | `validate`, `verify`, `check`, `ensure` |
+| Computation | `calculate`, `compute`, `parse`, `format` |
+| Boolean | `is`, `has`, `can`, `should`, `will` |
+
+**Tools:** PR review, PHPStan, Psalm

package/skill-assets/sunlint-code-quality/rules/php/C013-no-dead-code.md

@@ -0,0 +1,53 @@
+---
+title: Do Not Use Dead Code
+impact: LOW
+impactDescription: reduces codebase noise and improves maintainability
+tags: dead-code, cleanup, maintenance, quality, php
+---
+
+## Do Not Use Dead Code
+
+Dead code (commented-out blocks, unused functions, unreachable logic) confuses developers and increases codebase noise. Git history already preserves deleted code, so there is no need to keep it in the active codebase.
+
+**Incorrect (keeping dead code):**
+
+```php
+function processOrder($order) {
+    // Old implementation - keeping for reference
+    /*
+    $total = 0;
+    foreach ($order->items as $item) {
+        $total += $item->price * $item->quantity;
+    }
+    */
+    
+    $total = $this->calculator->calculate($order);
+    return $total;
+}
+
+// Unused function - "someone might need it later"
+function legacyCalculation() {
+    // ...
+}
+```
+
+**Correct (clean code):**
+
+```php
+function processOrder($order) {
+    return $this->calculator->calculate($order);
+}
+
+// Delete unused functions - rely on Git history if needed later.
+// Delete commented-out code blocks.
+// Remove unused 'use' statements.
+```
+
+**Types of dead code:**
+- Commented-out code blocks.
+- Unused functions, methods, or classes.
+- Unused `use` (import) statements.
+- Unreachable code (logic after a `return` or `throw`).
+- Unused private properties or local variables.
+
+**Tools:** PHPStan, Psalm, PHP_CodeSniffer, PR review

package/skill-assets/sunlint-code-quality/rules/php/C014-dependency-injection.md

@@ -0,0 +1,71 @@
+---
+title: Use Dependency Injection
+impact: HIGH
+impactDescription: enables testability and loose coupling
+tags: dependency-injection, testing, coupling, architecture, quality, php
+---
+
+## Use Dependency Injection
+
+Direct instantiation creates tight coupling, making testing difficult and changes risky. Dependency Injection (DI) allows for mockability, replaceability, and better overall architecture.
+
+**Incorrect (hardcoded dependencies):**
+
+```php
+class OrderService {
+    private Database $db;
+    private Mailer $mailer;
+
+    public function __construct() {
+        // Hardcoded dependencies - impossible to mock in unit tests
+        $this->db = new MySqlDatabase();
+        $this->mailer = new SmtpMailer();
+    }
+
+    public function createOrder($data) {
+        $this->db->save($data);
+        $this->mailer->send($data['email'], 'Order created');
+    }
+}
+```
+
+**Correct (injected dependencies via constructor):**
+
+```php
+interface DatabaseInterface {
+    public function save(array $data);
+}
+
+interface MailerInterface {
+    public function send(string $to, string $msg);
+}
+
+class OrderService {
+    // PHP 8+ Constructor Property Promotion
+    public function __construct(
+        private DatabaseInterface $db,
+        private MailerInterface $mailer
+    ) {}
+
+    public function createOrder(array $data) {
+        $this->db->save($data);
+        $this->mailer->send($data['email'], 'Order created');
+    }
+}
+
+// In production (using a DI Container like Laravel Service Container or Symfony)
+$service = $container->get(OrderService::class);
+
+// In Unit Tests
+$mockDb = $this->createMock(DatabaseInterface::class);
+$mockMailer = $this->createMock(MailerInterface::class);
+$testService = new OrderService($mockDb, $mockMailer);
+```
+
+**Benefits:**
+- **Testability**: Easily swap real services for mocks or stubs.
+- **Maintainability**: Centralized control over dependency lifetimes and configurations.
+- **Flexibility**: Change implementations (e.g., switch from SMTP to SendGrid) without modifying business logic.
+- **CLarity**: Class dependencies are explicitly declared in the constructor.
+
+**Tools:** PHPUnit, Mockery, Laravel/Symfony Containers, PHPStan

package/skill-assets/sunlint-code-quality/rules/php/C017-no-constructor-logic.md

@@ -0,0 +1,68 @@
+---
+title: No Business Logic In Constructors
+impact: HIGH
+impactDescription: ensures predictable object initialization
+tags: constructor, initialization, side-effects, patterns, quality, php
+---
+
+## No Business Logic In Constructors
+
+Constructors should be used exclusively for assigning dependencies and initializing basic object state. Including complex business logic, file I/O, or API calls in constructors makes code unpredictable, harder to test, and can lead to unexpected side effects during object instantiation.
+
+**Incorrect (heavy logic in constructor):**
+
+```php
+class UserService {
+    private array $config;
+
+    public function __construct(string $configPath) {
+        // BAD: File I/O in constructor
+        if (!file_exists($configPath)) {
+            throw new Exception("Config not found");
+        }
+        $this->config = json_decode(file_get_contents($configPath), true);
+
+        // BAD: Establishing connections or complex logic
+        $this->db = new PDO($this->config['dsn']);
+        
+        // BAD: Side effects
+        Log::info("UserService started");
+    }
+}
+```
+
+**Correct (assignments only or Factory pattern):**
+
+```php
+class UserService {
+    public function __construct(
+        private array $config,
+        private PDO $db
+    ) {
+        // Assignments only - no side effects
+    }
+
+    /**
+     * Factory method for controlled initialization
+     */
+    public static function create(string $configPath): self {
+        $config = json_decode(file_get_contents($configPath), true);
+        $db = new PDO($config['dsn']);
+        
+        Log::info("UserService initialized via factory");
+        
+        return new self($config, $db);
+    }
+}
+
+// Usage
+$service = UserService::create('/path/to/config.json');
+```
+
+**Why avoid logic in constructors?**
+- **Testability**: You cannot easily mock the behavior of a constructor.
+- **Predictability**: `new MyClass()` should be fast and side-effect free.
+- **Error Handling**: Exceptions in constructors can leave objects in an inconsistent state or be difficult to handle during DI container resolution.
+- **Coupling**: It often forces the class to know how to create its own dependencies.
+
+**Tools:** PHPStan, Psalm, PR review

package/skill-assets/sunlint-code-quality/rules/php/C018-generic-errors.md

@@ -0,0 +1,50 @@
+---
+title: Do Not Throw Generic Errors
+impact: HIGH
+impactDescription: enables proper error handling and monitoring
+tags: error-handling, exceptions, custom-errors, debugging, quality, php
+---
+
+## Do Not Throw Generic Errors
+
+Throwing generic exceptions like `\Exception`, `\Error`, or `\RuntimeException` with vague messages makes it impossible to distinguish between different types of failure. Proper error handling requires specific exception types that convey meaning and context.
+
+**Incorrect (generic errors):**
+
+```php
+if (!$user) {
+    throw new \Exception("error"); // Vague message, generic type
+}
+
+if ($amount < 0) {
+    throw new \RuntimeException("Invalid"); // Generic type
+}
+
+// In Laravel - avoid generic aborts without explanation
+abort(500); 
+```
+
+**Correct (specific exceptions with context):**
+
+```php
+if (!$user) {
+    throw new UserNotFoundException("User with ID {$userId} not found in database.");
+}
+
+if ($amount < 0) {
+    throw new InvalidTransactionAmountException("Transaction amount '{$amount}' cannot be negative.");
+}
+
+// Custom error with structured context (if supported by your base exception)
+throw new ValidationException([
+    'email' => 'The provided email is already in use.',
+    'code' => 'EMAIL_TAKEN'
+]);
+```
+
+**Custom errors should include:**
+- A descriptive message that explains **what** failed and **why**.
+- Relevant identifiers (IDs, keys) for easier debugging.
+- Specific exception types that allow for targeted `catch` blocks.
+
+**Tools:** PHPStan, Psalm, PR review

package/skill-assets/sunlint-code-quality/rules/php/C019-error-log-level.md

@@ -0,0 +1,54 @@
+---
+title: Do Not Use Error Log For Non-critical
+impact: HIGH
+impactDescription: prevents alert fatigue and log noise
+tags: logging, log-levels, error, observability, quality, php
+---
+
+## Do Not Use Error Log For Non-critical
+
+Using the `error` log level for non-critical or expected business events (like wrong passwords or validation failures) creates noise and causes alert fatigue. When too many non-critical events are logged as errors, real system failures may be overlooked.
+
+**Incorrect (overusing ERROR level):**
+
+```php
+// NOT an error - expected business behavior
+Log::error('User entered wrong password', ['user_id' => $id]);
+
+// NOT an error - validation failure
+Log::error('Validation failed for email format', ['email' => $email]);
+
+// NOT an error - temporary network retry
+Log::error('Retrying external API call... attempt 2');
+```
+
+**Correct (appropriate PSR-3 log levels):**
+
+```php
+// WARNING - Pathological but recoverable scenarios
+Log::warning('API timeout, retrying...', ['attempt' => 2, 'service' => 'payment-gateway']);
+
+// INFO - Significant business events
+Log::info('Login failed: invalid credentials', ['username' => $username, 'attempts' => 3]);
+
+// DEBUG - Information helpful for developers during troubleshooting
+Log::debug('Form validation failed', ['field' => 'email', 'error' => 'invalid_format']);
+
+// ERROR - Actual system failures that require attention
+Log::error('Database connection lost', ['host' => $host, 'exception' => $e->getMessage()]);
+
+// CRITICAL/EMERGENCY - System unusable or widespread failure
+Log::emergency('Server out of disk space!');
+```
+
+**Log Level Guide (PSR-3):**
+
+| Level | Use For | Action Required? |
+|-------|---------|------------------|
+| **EMERGENCY/CRITICAL** | System is unusable, widespread failure | Immediate wake-up call |
+| **ERROR** | Runtime errors that do not require immediate action but should be logged | Investigation within regular hours |
+| **WARNING** | Exceptional occurrences that are not errors (deprecations, retries) | Periodic review |
+| **INFO** | Interesting events (Logins, SQL logs in dev) | None (monitoring only) |
+| **DEBUG** | Detailed debug information | Temporary use |
+
+**Tools:** Monolog, Laravel/Symfony Logging, Sentry, New Relic

package/skill-assets/sunlint-code-quality/rules/php/C020-no-unused-imports.md

@@ -0,0 +1,55 @@
+---
+title: Do Not Use Unused Classes or Namespaces
+impact: LOW
+impactDescription: reduces codebase noise and improves clarity
+tags: imports, use-statements, cleanup, quality, php
+---
+
+## Do Not Use Unused Classes or Namespaces
+
+Unused `use` statements (imports) add unnecessary noise to the code, making it harder for developers to see which dependencies are actually required.
+
+**Incorrect (unused imports):**
+
+```php
+namespace App\Services;
+
+use App\Models\User;
+use App\Models\Order;
+use App\Models\Product;
+use App\Models\Category;
+use Illuminate\Support\Str;
+use Carbon\Carbon;
+
+class UserService
+{
+    // Only User is actually used in this class
+    public function findUser($id)
+    {
+        return User::find($id);
+    }
+}
+```
+
+**Correct (only needed imports):**
+
+```php
+namespace App\Services;
+
+use App\Models\User;
+
+class UserService
+{
+    public function findUser($id)
+    {
+        return User::find($id);
+    }
+}
+```
+
+**Why remove unused imports?**
+- **Readability**: Quickly understand a file's dependencies.
+- **Maintenance**: Avoid confusion when refactoring or deleting classes.
+- **IDE Performance**: Slightly faster indexing and better suggestions.
+
+**Tools:** PHPStorm (Optimize Imports), PHP_CodeSniffer (`SlevomatCodingStandard.Namespaces.UnusedUses`), PHPStan, Psalm

package/skill-assets/sunlint-code-quality/rules/php/C022-no-unused-variables.md

@@ -0,0 +1,51 @@
+---
+title: Do Not Leave Unused Variables
+impact: LOW
+impactDescription: reduces code noise and prevents potential bugs
+tags: variables, cleanup, quality, php
+---
+
+## Do Not Leave Unused Variables
+
+Unused variables make the code harder to read and often indicate incomplete refactoring or accidental logic errors.
+
+**Incorrect (unused variables):**
+
+```php
+function processOrder($order) {
+    $user = $order->user;      // Declared but never used
+    $timestamp = time();       // Never used
+    $items = $order->items;
+    
+    return array_map(fn($item) => $item->name, $items);
+}
+
+// Unused method parameters
+function deleteUser($id, $force = false) {
+    // $force is never used in the logic
+    return User::destroy($id);
+}
+```
+
+**Correct (clean logic):**
+
+```php
+function processOrder($order) {
+    return array_map(fn($item) => $item->name, $order->items);
+}
+
+// Remove unused parameters if they aren't part of an interface
+function deleteUser($id) {
+    return User::destroy($id);
+}
+```
+
+**Common Scenarios:**
+- Variables assigned but never read.
+- Function parameters that are not used in the body.
+- Loop variables (like `$key => $value`) where the key is never used.
+
+**Exceptions:**
+- Implementing an interface where a method signature is fixed, but you don't need all parameters. In some tools, prefixing with an underscore (e.g., `$_param`) can signal intentional non-use.
+
+**Tools:** PHPStan, Psalm, PHP_CodeSniffer (`SlevomatCodingStandard.Variables.UnusedVariable`)

package/skill-assets/sunlint-code-quality/rules/php/C023-no-duplicate-names.md

@@ -0,0 +1,61 @@
+---
+title: No Duplicate Variable Names In Scope
+impact: HIGH
+impactDescription: prevents variable shadowing bugs and improves code clarity
+tags: variables, shadowing, scope, quality, php
+---
+
+## No Duplicate Variable Names In Scope
+
+Variable shadowing occurs when a variable declared within a certain scope (like a function or a closure) has the same name as a variable in an outer scope. This can lead to subtle bugs and makes the code difficult to follow.
+
+**Incorrect (shadowed variables):**
+
+```php
+$user = Auth::user();
+
+function updateProfile($request) {
+    // Shadows the potentially global or outer $user
+    $user = $request->input('user_data'); 
+    
+    // Which $user is this?
+    $user->save();
+}
+
+// Shadowing in loops
+foreach ($orders as $order) {
+    $order = $this->repository->enhance($order); // Shadowing the loop variable
+}
+```
+
+**Correct (unique names):**
+
+```php
+$currentUser = Auth::user();
+
+function updateProfile($request) {
+    $profileData = $request->input('user_data');
+    
+    $profileData->save();
+}
+
+foreach ($orders as $order) {
+    $enhancedOrder = $this->repository->enhance($order);
+}
+```
+
+**Shadowing in Closures (PHP):**
+Be careful when using `use` in anonymous functions:
+```php
+$message = "Hello";
+
+$callback = function($input) use ($message) {
+    $message = $input; // Shadows the captured $message (only locally)
+};
+```
+
+**Why avoid shadowing?**
+- **Clarity**: Developers don't have to keep track of multiple meanings for the same variable name.
+- **Bug Prevention**: Avoids accidentally overwriting or reading the wrong value when scopes are nested or side effects occur.
+
+**Tools:** PHPStan, Psalm, PHP_CodeSniffer

package/skill-assets/sunlint-code-quality/rules/php/C024-centralize-constants.md

@@ -0,0 +1,60 @@
+---
+title: Centralize Constants
+impact: HIGH
+impactDescription: makes values easy to find, update, and manage
+tags: constants, magic-numbers, configuration, quality, php
+---
+
+## Centralize Constants
+
+Magic numbers or strings scattered throughout the codebase are difficult to maintain and understand. Centralizing constants in classes or using Enums makes the code self-documenting and provides a single source of truth.
+
+**Incorrect (magic values):**
+
+```php
+if (strlen($password) < 8) { ... }
+if ($retryCount > 3) { ... }
+if ($order->status === 1) { ... }
+sleep(300); // 5 minutes? 
+if ($user->role === 'admin') { ... }
+```
+
+**Correct (centralized constants and Enums):**
+
+```php
+/**
+ * Using Class Constants
+ */
+class AuthConfig {
+    public const PASSWORD_MIN_LENGTH = 8;
+    public const MAX_RETRY_ATTEMPTS = 3;
+    public const SESSION_TIMEOUT_SECONDS = 300;
+}
+
+/**
+ * Using PHP 8.1+ Enums (Recommended for categories)
+ */
+enum OrderStatus: int {
+    case PENDING = 1;
+    case APPROVED = 2;
+    case SHIPPED = 3;
+}
+
+enum UserRole: string {
+    case ADMIN = 'admin';
+    case USER = 'user';
+}
+
+// Usage
+if (strlen($password) < AuthConfig::PASSWORD_MIN_LENGTH) { ... }
+if ($order->status === OrderStatus::PENDING->value) { ... }
+if ($user->role === UserRole::ADMIN->value) { ... }
+```
+
+**Benefits:**
+- **Searchability**: Find all usages of a constant instantly.
+- **Self-Documentation**: `MAX_RETRY_ATTEMPTS` is clearer than `3`.
+- **Consistency**: Prevents typos (e.g., `'admn'` vs `'admin'`).
+- **Refactoring**: Change a value in one place to update the entire application.
+
+**Tools:** PHPStan (disallow magic numbers), Psalm, PR review

package/skill-assets/sunlint-code-quality/rules/php/C029-catch-log-root-cause.md

@@ -0,0 +1,57 @@
+---
+title: All Catch Blocks Must Log Root Cause
+impact: HIGH
+impactDescription: enables debugging and incident response
+tags: error-handling, logging, debugging, observability, quality, php
+---
+
+## All Catch Blocks Must Log Root Cause
+
+Silent failures make debugging impossible. Without proper logging of the root cause and relevant context, you cannot trace issues in production or understand why a process failed.
+
+**Incorrect (silent or minimal logging):**
+
+```php
+try {
+    $this->paymentService->process($order);
+} catch (\Exception $e) {
+    // Empty catch - silent failure!
+}
+
+try {
+    $this->userRepository->save($user);
+} catch (\Exception $e) {
+    return false; // No logging, no context provided for the failure
+}
+```
+
+**Correct (comprehensive error logging):**
+
+```php
+try {
+    $this->paymentService->process($order);
+} catch (\Throwable $error) {
+    // Use a logger (e.g., Monolog, Laravel Log)
+    Log::error('Payment processing failed', [
+        'order_id' => $order->id,
+        'user_id' => $order->user_id,
+        'amount' => $order->amount,
+        'message' => $error->getMessage(),
+        'file' => $error->getFile(),
+        'line' => $error->getLine(),
+        'trace' => $error->getTraceAsString()
+    ]);
+    
+    // Rethrow or wrap in a custom exception with the original as the cause
+    throw new PaymentFailedException('Payment could not be processed', 0, $error);
+}
+```
+
+**Log context should include:**
+- Error message and stack trace (`$e->getMessage()`, `$e->getTraceAsString()`).
+- File and line number where the error occurred.
+- Relevant entity IDs (order, user, etc.).
+- Request/correlation ID (if available).
+- Input data that caused the error (careful with sensitive data).
+
+**Tools:** PHPStan, Psalm, SonarQube, PR review

package/skill-assets/sunlint-code-quality/rules/php/C030-custom-error-classes.md

@@ -0,0 +1,62 @@
+---
+title: Use Custom Error Classes
+impact: HIGH
+impactDescription: enables proper error categorization and handling
+tags: error-handling, custom-errors, exceptions, patterns, quality, php
+---
+
+## Use Custom Error Classes
+
+Defining your own exception classes allows you to categorize errors, attach relevant metadata, and implement specific handling strategies for different parts of your application. It provides a clear contract for the callers of your methods.
+
+**Incorrect (generic exceptions):**
+
+```php
+throw new \Exception("User not found");
+throw new \InvalidArgumentException("Invalid input data");
+throw new \RuntimeException("Database connection failed");
+```
+
+**Correct (custom exception hierarchy):**
+
+```php
+// Base application exception
+abstract class AppServiceException extends \Exception {
+    protected int $statusCode = 500;
+    protected string $errorCode = 'INTERNAL_ERROR';
+    protected array $context = [];
+
+    public function __construct(string $message, array $context = [], ?\Throwable $previous = null) {
+        parent::__construct($message, 0, $previous);
+        $this->context = $context;
+    }
+
+    public function getStatusCode(): int { return $this->statusCode; }
+    public function getErrorCode(): string { return $this->errorCode; }
+    public function getContext(): array { return $this->context; }
+}
+
+// Specific domain exceptions
+class UserNotFoundException extends AppServiceException {
+    protected int $statusCode = 404;
+    protected string $errorCode = 'USER_NOT_FOUND';
+}
+
+class InsufficientBalanceException extends AppServiceException {
+    protected int $statusCode = 422;
+    protected string $errorCode = 'INSUFFICIENT_BALANCE';
+}
+
+// Usage
+if (!$user) {
+    throw new UserNotFoundException("User {$userId} does not exist", ['id' => $userId]);
+}
+```
+
+**Benefits:**
+- **Granular Catching**: You can catch specific domain errors (e.g., `catch (UserNotFoundException $e)`) while letting others bubble up.
+- **Structured Metadata**: Attach request IDs, user IDs, or input data directly to the exception.
+- **HTTP Mapping**: Easily map exceptions to HTTP status codes in a global error handler (e.g., in Laravel `Handler.php` or Symfony `ExceptionSubscriber`).
+- **Observability**: Search logs for specific exception class names.
+
+**Tools:** PHPUnit (expectException), PHPStan, Psalm