.coderabbit.yaml

chat:
  auto_reply: false
reviews:
  review_status: true
  auto_review:
    enabled: true
    base_branches:
      - next
    drafts: true
  path_instructions:
    - path: "**/*"
      instructions: |
        Apply the following Clean Code guidelines to all files, as summarized by [wojteklu's Clean Code gist](https://gist.githubusercontent.com/wojteklu/73c6914cc446146b8b533c0988cf8d29/raw/c7a44d774fc3b09a0d5f0f58888550ba0ac694b9/clean_code.md):

        Code is clean if it can be understood easily – by everyone on the team. Clean code can be read and enhanced by a developer other than its original author. With understandability comes readability, changeability, extensibility and maintainability.

        ## General rules
        1. Follow standard conventions.
        2. Keep it simple stupid. Simpler is always better. Reduce complexity as much as possible.
        3. Boy scout rule. Leave the campground cleaner than you found it.
        4. Always find root cause. Always look for the root cause of a problem.

        ## Design rules
        1. Keep configurable data at high levels.
        2. Prefer polymorphism to if/else or switch/case.
        3. Separate multi-threading code.
        4. Prevent over-configurability.
        5. Use dependency injection.
        6. Follow Law of Demeter. A class should know only its direct dependencies.

        ## Understandability tips
        1. Be consistent. If you do something a certain way, do all similar things in the same way.
        2. Use explanatory variables.
        3. Encapsulate boundary conditions. Boundary conditions are hard to keep track of. Put the processing for them in one place.
        4. Prefer dedicated value objects to primitive type.
        5. Avoid logical dependency. Don't write methods which works correctly depending on something else in the same class.
        6. Avoid negative conditionals.

        ## Names rules
        1. Choose descriptive and unambiguous names.
        2. Make meaningful distinction.
        3. Use pronounceable names.
        4. Use searchable names.
        5. Replace magic numbers with named constants.
        6. Avoid encodings. Don't append prefixes or type information.

        ## Functions rules
        1. Small.
        2. Do one thing.
        3. Use descriptive names.
        4. Prefer fewer arguments.
        5. Have no side effects.
        6. Don't use flag arguments. Split method into several independent methods that can be called from the client without the flag.

        ## Comments rules
        1. Always try to explain yourself in code.
        2. Don't be redundant.
        3. Don't add obvious noise.
        4. Don't use closing brace comments.
        5. Don't comment out code. Just remove.
        6. Use as explanation of intent.
        7. Use as clarification of code.
        8. Use as warning of consequences.

        ## Source code structure
        1. Separate concepts vertically.
        2. Related code should appear vertically dense.
        3. Declare variables close to their usage.
        4. Dependent functions should be close.
        5. Similar functions should be close.
        6. Place functions in the downward direction.
        7. Keep lines short.
        8. Don't use horizontal alignment.
        9. Use white space to associate related things and disassociate weakly related.
        10. Don't break indentation.

        ## Objects and data structures
        1. Hide internal structure.
        2. Prefer data structures.
        3. Avoid hybrids structures (half object and half data).
        4. Should be small.
        5. Do one thing.
        6. Small number of instance variables.
        7. Base class should know nothing about their derivatives.
        8. Better to have many functions than to pass some code into a function to select a behavior.
        9. Prefer non-static methods to static methods.

        ## Tests
        1. One assert per test.
        2. Readable.
        3. Fast.
        4. Independent.
        5. Repeatable.

        ## Code smells
        1. Rigidity. The software is difficult to change. A small change causes a cascade of subsequent changes.
        2. Fragility. The software breaks in many places due to a single change.
        3. Immobility. You cannot reuse parts of the code in other projects because of involved risks and high effort.
        4. Needless Complexity.
        5. Needless Repetition.
        6. Opacity. The code is hard to understand.

    - path: "**/*.php"
      instructions: |
        Flag any usage of error_log() as it should be replaced with proper Monolog logging mechanisms provided by [zmsslim](https://github.com/it-at-m/eappointment/blob/b52b5d59c5013615d7fbfeaf595f3fdc047017d1/zmsslim/src/Slim/Bootstrap.php#L76) which should be setup in the App/Application of each module:
        1. For error handling: Use the proper Monolog logging framework with error levels
        2. For application info logs: Use the proper Monolog logging framework with info levels
        3. For debugging: Use a dedicated debug logger or remove debug statements
        4. For CLI output: Use a CLI output handler or symfony/console
        5. The application [log levels](https://github.com/it-at-m/eappointment/blob/b52b5d59c5013615d7fbfeaf595f3fdc047017d1/zmsslim/src/Slim/Bootstrap.php#L60) are as follows DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, and EMERGENCY

        Example replacement:
        ```php
        // Instead of:
        error_log("Import failed - " . $e->getMessage());
        
        // Use:
        $log->error("Import failed", ['error' => $e->getMessage()]);
        ```

        Flag specific logging violations:
        1. error_log(), var_dump(), print_r(), die(), exit() usage (except proper error logging in catch blocks)
        2. Any debug output that should use proper Monolog logging
        3. Debug constants like DEBUG = true
        4. Debug logging that should be removed in production
        5. Commented debug code that should be cleaned up

        Example replacements:
        ```php
        // Instead of:
        error_log("Error occurred");
        var_dump($data);
        die('debug point');
        
        // Use:
        $log->error("Error occurred", ['context' => 'processing']);
        $log->debug('Data dump', ['data' => $data]);
        // Remove die() statements entirely
        ```

        Exception handling should use proper logging:
        ```php
        // Instead of:
        try {
            $result = $this->process();
        } catch (Exception $e) {
            error_log("Processing failed: " . $e->getMessage());
        }
        
        // Use:
        try {
            $result = $this->process();
        } catch (Exception $e) {
            $log->error("Processing failed", ['error' => $e->getMessage(), 'trace' => $e->getTraceAsString()]);
        }
        ```

        Use appropriate log levels:
        ```php
        // Instead of:
        error_log("User logged in");
        error_log("Processing data...");
        
        // Use:
        $log->info("User logged in", ['user_id' => $userId, 'ip' => $ipAddress]);
        $log->debug("Processing data", ['data_size' => count($data), 'processor' => 'batch']);
        ```
        Use appropriate log levels:
        ```php
        // Instead of:
        var_dump($data);
        die('debug point');
        
        // Use:
        $log->debug('Data dump', ['data' => $data]);
        // Remove debug statements entirely
        ```

        Flag TODO/FIXME comments that indicate technical debt:
        1. TODO comments without clear action items
        2. FIXME comments indicating broken functionality
        3. HACK comments indicating temporary workarounds
        4. XXX comments indicating problematic code

        These should be converted to proper issues or addressed:
        ```php
        // Instead of:
        // TODO: fix this later
        // FIXME: this is broken
        
        // Use:
        // Create proper issue and reference it
        // @see Issue #123: Refactor validation logic
        ```

        Flag @SuppressWarnings annotations that may indicate code quality issues:
        1. Excessive use of @SuppressWarnings
        2. Suppressing warnings without proper justification
        3. Suppressing warnings that could be fixed with refactoring

        Consider refactoring instead of suppressing:
        ```php
        // Instead of:
        /**
         * @SuppressWarnings(Complexity)
         */
        public function complexMethod() { /* 200 lines */ }
        
        // Use:
        // Break down into smaller, focused methods
        public function processData() {
            $this->validateInput();
            $this->transformData();
            $this->saveResults();
        }
        ```

        Flag potential security vulnerabilities:
        1. Hardcoded passwords, secrets, or API keys
        2. Use of dangerous functions: eval(), exec(), system(), shell_exec()
        3. Dynamic includes/requires with user input
        4. SQL injection vulnerabilities (direct variable interpolation)
        5. XSS vulnerabilities (unfiltered output)

        Example fixes:
        ```php
        // Instead of:
        eval($userInput);
        include($_GET['file']);
        
        // Use:
        // Avoid eval() entirely
        // Use whitelist validation for includes
        $allowedFiles = ['config.php', 'template.php'];
        if (in_array($file, $allowedFiles)) {
            include($file);
        }
        ```

        Flag database security issues:
        1. Direct variable interpolation in SQL queries
        2. Missing parameter binding
        3. Use of deprecated mysql_* functions
        4. Unfiltered user input in database operations

        Example fixes:
        ```php
        // Instead of:
        $query = "SELECT * FROM users WHERE id = $userId";
        
        // Use:
        $query = "SELECT * FROM users WHERE id = ?";
        $stmt->bind_param('i', $userId);
        ```

        Flag code complexity issues:
        1. Methods longer than 50 lines
        2. Classes with too many responsibilities
        3. Deep nesting (more than 3 levels)
        4. Cyclomatic complexity > 10
        5. Missing type hints and return types

        Consider refactoring:
        ```php
        // Instead of:
        public function processEverything($data) {
            // 100+ lines of mixed logic
        }
        
        // Use:
        public function processData(array $data): Result {
            $this->validate($data);
            $transformed = $this->transform($data);
            return $this->save($transformed);
        }
        ```

        Flag configuration and environment issues:
        1. Hardcoded configuration values
        2. Missing environment variable checks
        3. Debug settings enabled in production code
        4. Inconsistent configuration patterns

        Example fixes:
        ```php
        // Instead of:
        const DEBUG = true;
        const DB_PASSWORD = 'hardcoded_password';
        
        // Use:
        const DEBUG = getenv('APP_DEBUG') === 'true';
        const DB_PASSWORD = getenv('DB_PASSWORD') ?: throw new Exception('DB_PASSWORD not set');
        ```

        Flag poor error handling:
        1. Empty catch blocks
        2. Generic exception catching
        3. Missing error logging
        4. Silent failures
        5. Inconsistent error response formats

        Example improvements:
        ```php
        // Instead of:
        try {
            $result = $this->process();
        } catch (Exception $e) {
            // Empty catch block
        }
        
        // Use:
        try {
            $result = $this->process();
        } catch (SpecificException $e) {
            $log->error('Processing failed', ['error' => $e->getMessage()]);
            throw new ProcessException('Failed to process data', 0, $e);
        }
        ```

        Flag performance issues:
        1. N+1 query problems
        2. Unnecessary database queries in loops
        3. Large data processing without pagination
        4. Missing caching opportunities
        5. Inefficient string concatenation in loops

        Example fixes:
        ```php
        // Instead of:
        foreach ($users as $user) {
            $profile = $this->getUserProfile($user->id); // N+1 query
        }
        
        // Use:
        $userIds = array_column($users, 'id');
        $profiles = $this->getUserProfiles($userIds); // Single query
        ```

        Flag deprecated/legacy code usage:
        1. Any usage of @deprecated methods, classes, or properties
        2. Calls to deprecated functions (look for @deprecated in docblocks or comments)
        3. Encourage migration to newer APIs or patterns

        Example:
        ```php
        // Instead of:
        /** @deprecated Use newMethod() instead */
        public function oldMethod() {}
        $this->oldMethod();
        // Use:
        $this->newMethod();
        ```

        Flag excessive function parameters:
        1. Functions/methods with more than 4-5 parameters (especially if many are optional)
        2. Suggest refactoring to use objects or associative arrays for complex parameter sets

        Example:
        ```php
        // Instead of:
        public function foo($a, $b, $c, $d, $e, $f) {}
        // Use:
        public function foo(FooOptions $options) {}
        ```

        Flag global/static state:
        1. Use of global variables
        2. Excessive use of static properties (except for constants)
        3. Encourage dependency injection or instance-based design

        Example:
        ```php
        // Instead of:
        global $myVar;
        // Use:
        $this->myVar;
        ```

        Flag anonymous functions in loops:
        1. Creation of closures inside loops (foreach, for, while)
        2. Suggest moving closure definition outside the loop

        Example:
        ```php
        // Instead of:
        foreach ($items as $item) {
            $callback = function($x) { return $x * 2; };
            $result[] = $callback($item);
        }
        // Use:
        $callback = function($x) { return $x * 2; };
        foreach ($items as $item) {
            $result[] = $callback($item);
        }
        ```

        Flag unnecessary type casting:
        1. Unnecessary or redundant type casts (e.g., (int)(int)$x)
        2. Type casts that can be avoided by using proper types

        Example:
        ```php
        // Instead of:
        $x = (int)(int)$y;
        // Use:
        $x = (int)$y;
        ```

        Flag unoptimized loops:
        1. Nested loops with potential for O(n^2) or worse complexity, especially if not commented
        2. Loops that can be replaced with built-in functions or more efficient algorithms

        Example:
        ```php
        // Instead of:
        foreach ($a as $x) {
            foreach ($b as $y) {
                if ($x === $y) { ... }
            }
        }
        // Use:
        $bSet = array_flip($b);
        foreach ($a as $x) {
            if (isset($bSet[$x])) { ... }
        }
        ```

    - path: "**/*.php"
      instructions: |
        # PHP Variables - Clean Code Rules
        Based on [piotrplenik/clean-code-php](https://github.com/piotrplenik/clean-code-php/):

        ## Use meaningful and pronounceable variable names
        ```php
        // Bad:
        $ymdstr = $moment->format('y-m-d');
        
        // Good:
        $currentDate = $moment->format('y-m-d');
        ```

        ## Use the same vocabulary for the same type of variable
        ```php
        // Bad:
        getUserInfo();
        getUserData();
        getUserRecord();
        getUserProfile();
        
        // Good:
        getUser();
        ```

        ## Use searchable names
        ```php
        // Bad:
        $result = $serializer->serialize($data, 448);
        
        // Good:
        $json = $serializer->serialize($data, JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
        ```

        ## Use explanatory variables
        ```php
        // Bad:
        $address = 'One Infinite Loop, Cupertino 95014';
        $cityZipCodeRegex = '/^[^,]+,\s*(.+?)\s*(\d{5})$/';
        preg_match($cityZipCodeRegex, $address, $matches);
        saveCityZipCode($matches[1], $matches[2]);
        
        // Good:
        $address = 'One Infinite Loop, Cupertino 95014';
        $cityZipCodeRegex = '/^[^,]+,\s*(?<city>.+?)\s*(?<zipCode>\d{5})$/';
        preg_match($cityZipCodeRegex, $address, $matches);
        saveCityZipCode($matches['city'], $matches['zipCode']);
        ```

        ## Avoid nesting too deeply and return early
        ```php
        // Bad:
        function isShopOpen($day): bool
        {
            if ($day) {
                if (is_string($day)) {
                    $day = strtolower($day);
                    if ($day === 'friday') {
                        return true;
                    } elseif ($day === 'saturday') {
                        return true;
                    } elseif ($day === 'sunday') {
                        return true;
                    }
                    return false;
                }
                return false;
            }
            return false;
        }
        
        // Good:
        function isShopOpen(string $day): bool
        {
            if (empty($day)) {
                return false;
            }
            $openingDays = ['friday', 'saturday', 'sunday'];
            return in_array(strtolower($day), $openingDays, true);
        }
        ```

        ## Avoid Mental Mapping
        ```php
        // Bad:
        $l = ['Austin', 'New York', 'San Francisco'];
        for ($i = 0; $i < count($l); $i++) {
            $li = $l[$i];
            doStuff();
            dispatch($li);
        }
        
        // Good:
        $locations = ['Austin', 'New York', 'San Francisco'];
        foreach ($locations as $location) {
            doStuff();
            dispatch($location);
        }
        ```

        ## Don't add unneeded context
        ```php
        // Bad:
        class Car
        {
            public $carMake;
            public $carModel;
            public $carColor;
        }
        
        // Good:
        class Car
        {
            public $make;
            public $model;
            public $color;
        }
        ```

    - path: "**/*.php"
      instructions: |
        # PHP Comparison - Clean Code Rules
        Based on [piotrplenik/clean-code-php](https://github.com/piotrplenik/clean-code-php/):

        ## Use identical comparison
        ```php
        // Bad:
        $a = '42';
        $b = 42;
        if ($a != $b) {
            // The expression will always pass
        }
        
        // Good:
        $a = '42';
        $b = 42;
        if ($a !== $b) {
            // The expression is verified
        }
        ```

        ## Null coalescing operator
        ```php
        // Bad:
        if (isset($_GET['name'])) {
            $name = $_GET['name'];
        } elseif (isset($_POST['name'])) {
            $name = $_POST['name'];
        } else {
            $name = 'nobody';
        }
        
        // Good:
        $name = $_GET['name'] ?? $_POST['name'] ?? 'nobody';
        ```

    - path: "**/*.php"
      instructions: |
        # PHP Functions - Clean Code Rules (Part 1)
        Based on [piotrplenik/clean-code-php](https://github.com/piotrplenik/clean-code-php/):

        ## Use default arguments instead of short circuiting or conditionals
        ```php
        // Bad:
        function createMicrobrewery($breweryName = 'Hipster Brew Co.'): void
        {
            // ...
        }
        
        // Good:
        function createMicrobrewery(string $breweryName = 'Hipster Brew Co.'): void
        {
            // ...
        }
        ```

        ## Function arguments (2 or fewer ideally)
        ```php
        // Bad:
        class Questionnaire
        {
            public function __construct(
                string $firstname,
                string $lastname,
                string $patronymic,
                string $region,
                string $district,
                string $city,
                string $phone,
                string $email
            ) {
                // ...
            }
        }
        
        // Good:
        class Name
        {
            private $firstname;
            private $lastname;
            private $patronymic;
            public function __construct(string $firstname, string $lastname, string $patronymic)
            {
                $this->firstname = $firstname;
                $this->lastname = $lastname;
                $this->patronymic = $patronymic;
            }
        }
        
        class Questionnaire
        {
            public function __construct(Name $name, City $city, Contact $contact)
            {
                // ...
            }
        }
        ```

        ## Function names should say what they do
        ```php
        // Bad:
        class Email
        {
            public function handle(): void
            {
                mail($this->to, $this->subject, $this->body);
            }
        }
        $message->handle();
        
        // Good:
        class Email
        {
            public function send(): void
            {
                mail($this->to, $this->subject, $this->body);
            }
        }
        $message->send();
        ```

    - path: "**/*.php"
      instructions: |
        # PHP Functions - Clean Code Rules (Part 2)
        Based on [piotrplenik/clean-code-php](https://github.com/piotrplenik/clean-code-php/):

        ## Functions should only be one level of abstraction
        ```php
        // Bad:
        function parseBetterPHPAlternative(string $code): void
        {
            $regexes = [/* ... */];
            $statements = explode(' ', $code);
            $tokens = [];
            foreach ($regexes as $regex) {
                foreach ($statements as $statement) {
                    // ...
                }
            }
            $ast = [];
            foreach ($tokens as $token) {
                // lex...
            }
            foreach ($ast as $node) {
                // parse...
            }
        }
        
        // Good:
        class Tokenizer
        {
            public function tokenize(string $code): array
            {
                // ...
            }
        }
        
        class BetterPHPAlternative
        {
            private $tokenizer;
            private $lexer;
            
            public function __construct(Tokenizer $tokenizer, Lexer $lexer)
            {
                $this->tokenizer = $tokenizer;
                $this->lexer = $lexer;
            }
            
            public function parse(string $code): void
            {
                $tokens = $this->tokenizer->tokenize($code);
                $ast = $this->lexer->lexify($tokens);
                foreach ($ast as $node) {
                    // parse...
                }
            }
        }
        ```

        ## Don't use flags as function parameters
        ```php
        // Bad:
        function createFile(string $name, bool $temp = false): void
        {
            if ($temp) {
                touch('./temp/' . $name);
            } else {
                touch($name);
            }
        }
        
        // Good:
        function createFile(string $name): void
        {
            touch($name);
        }
        
        function createTempFile(string $name): void
        {
            touch('./temp/' . $name);
        }
        ```

    - path: "**/*.php"
      instructions: |
        # PHP Functions - Clean Code Rules (Part 3)
        Based on [piotrplenik/clean-code-php](https://github.com/piotrplenik/clean-code-php/):

        ## Avoid Side Effects
        ```php
        // Bad:
        $name = 'Ryan McDermott';
        function splitIntoFirstAndLastName(): void
        {
            global $name;
            $name = explode(' ', $name);
        }
        splitIntoFirstAndLastName();
        
        // Good:
        function splitIntoFirstAndLastName(string $name): array
        {
            return explode(' ', $name);
        }
        $name = 'Ryan McDermott';
        $newName = splitIntoFirstAndLastName($name);
        ```

        ## Don't write to global functions
        ```php
        // Bad:
        function config(): array
        {
            return ['foo' => 'bar'];
        }
        
        // Good:
        class Configuration
        {
            private $configuration = [];
            
            public function __construct(array $configuration)
            {
                $this->configuration = $configuration;
            }
            
            public function get(string $key): ?string
            {
                return $this->configuration[$key] ?? null;
            }
        }
        ```

        ## Don't use a Singleton pattern
        ```php
        // Bad:
        class DBConnection
        {
            private static $instance;
            private function __construct(string $dsn) { /* ... */ }
            public static function getInstance(): self
            {
                if (self::$instance === null) {
                    self::$instance = new self();
                }
                return self::$instance;
            }
        }
        $singleton = DBConnection::getInstance();
        
        // Good:
        class DBConnection
        {
            public function __construct(string $dsn) { /* ... */ }
        }
        $connection = new DBConnection($dsn);
        ```

    - path: "**/*.php"
      instructions: |
        # PHP Functions - Clean Code Rules (Part 4)
        Based on [piotrplenik/clean-code-php](https://github.com/piotrplenik/clean-code-php/):

        ## Encapsulate conditionals
        ```php
        // Bad:
        if ($article->state === 'published') {
            // ...
        }
        
        // Good:
        if ($article->isPublished()) {
            // ...
        }
        ```

        ## Avoid negative conditionals
        ```php
        // Bad:
        function isDOMNodeNotPresent(DOMNode $node): bool
        {
            // ...
        }
        if (! isDOMNodeNotPresent($node)) {
            // ...
        }
        
        // Good:
        function isDOMNodePresent(DOMNode $node): bool
        {
            // ...
        }
        if (isDOMNodePresent($node)) {
            // ...
        }
        ```

        ## Avoid conditionals
        ```php
        // Bad:
        class Airplane
        {
            public function getCruisingAltitude(): int
            {
                switch ($this->type) {
                    case '777':
                        return $this->getMaxAltitude() - $this->getPassengerCount();
                    case 'Air Force One':
                        return $this->getMaxAltitude();
                    case 'Cessna':
                        return $this->getMaxAltitude() - $this->getFuelExpenditure();
                }
            }
        }
        
        // Good:
        interface Airplane
        {
            public function getCruisingAltitude(): int;
        }
        
        class Boeing777 implements Airplane
        {
            public function getCruisingAltitude(): int
            {
                return $this->getMaxAltitude() - $this->getPassengerCount();
            }
        }
        ```

        ## Avoid type-checking
        ```php
        // Bad:
        function travelToTexas($vehicle): void
        {
            if ($vehicle instanceof Bicycle) {
                $vehicle->pedalTo(new Location('texas'));
            } elseif ($vehicle instanceof Car) {
                $vehicle->driveTo(new Location('texas'));
            }
        }
        
        // Good:
        function travelToTexas(Vehicle $vehicle): void
        {
            $vehicle->travelTo(new Location('texas'));
        }
        ```

        ## Remove dead code
        ```php
        // Bad:
        function oldRequestModule(string $url): void { /* ... */ }
        function newRequestModule(string $url): void { /* ... */ }
        $request = newRequestModule($requestUrl);
        
        // Good:
        function requestModule(string $url): void { /* ... */ }
        $request = requestModule($requestUrl);
        ```

    - path: "**/*.php"
      instructions: |
        # PHP Objects and Data Structures - Clean Code Rules
        Based on [piotrplenik/clean-code-php](https://github.com/piotrplenik/clean-code-php/):

        ## Use object encapsulation
        ```php
        // Bad:
        class BankAccount
        {
            public $balance = 1000;
        }
        $bankAccount = new BankAccount();
        $bankAccount->balance -= 100;
        
        // Good:
        class BankAccount
        {
            private $balance;
            
            public function __construct(int $balance = 1000)
            {
                $this->balance = $balance;
            }
            
            public function withdraw(int $amount): void
            {
                if ($amount > $this->balance) {
                    throw new \Exception('Amount greater than available balance.');
                }
                $this->balance -= $amount;
            }
            
            public function getBalance(): int
            {
                return $this->balance;
            }
        }
        $bankAccount = new BankAccount();
        $bankAccount->withdraw($shoesPrice);
        ```

        ## Make objects have private/protected members
        ```php
        // Bad:
        class Employee
        {
            public $name;
            public function __construct(string $name)
            {
                $this->name = $name;
            }
        }
        echo 'Employee name: ' . $employee->name;
        
        // Good:
        class Employee
        {
            private $name;
            public function __construct(string $name)
            {
                $this->name = $name;
            }
            public function getName(): string
            {
                return $this->name;
            }
        }
        echo 'Employee name: ' . $employee->getName();
        ```

    - path: "**/*.php"
      instructions: |
        # PHP Classes - Clean Code Rules
        Based on [piotrplenik/clean-code-php](https://github.com/piotrplenik/clean-code-php/):

        ## Prefer composition over inheritance
        ```php
        // Bad:
        class Employee
        {
            private $name;
            private $email;
            public function __construct(string $name, string $email)
            {
                $this->name = $name;
                $this->email = $email;
            }
        }
        
        class EmployeeTaxData extends Employee
        {
            private $ssn;
            private $salary;
            public function __construct(string $name, string $email, string $ssn, string $salary)
            {
                parent::__construct($name, $email);
                $this->ssn = $ssn;
                $this->salary = $salary;
            }
        }
        
        // Good:
        class EmployeeTaxData
        {
            private $ssn;
            private $salary;
            public function __construct(string $ssn, string $salary)
            {
                $this->ssn = $ssn;
                $this->salary = $salary;
            }
        }
        
        class Employee
        {
            private $name;
            private $email;
            private $taxData;
            
            public function __construct(string $name, string $email)
            {
                $this->name = $name;
                $this->email = $email;
            }
            
            public function setTaxData(EmployeeTaxData $taxData): void
            {
                $this->taxData = $taxData;
            }
        }
        ```

        ## Avoid fluent interfaces
        ```php
        // Bad:
        class Car
        {
            private $make = 'Honda';
            private $model = 'Accord';
            private $color = 'white';
            
            public function setMake(string $make): self
            {
                $this->make = $make;
                return $this;
            }
            
            public function setModel(string $model): self
            {
                $this->model = $model;
                return $this;
            }
        }
        
        $car = (new Car())
            ->setColor('pink')
            ->setMake('Ford')
            ->setModel('F-150');
        
        // Good:
        class Car
        {
            private $make = 'Honda';
            private $model = 'Accord';
            private $color = 'white';
            
            public function setMake(string $make): void
            {
                $this->make = $make;
            }
            
            public function setModel(string $model): void
            {
                $this->model = $model;
            }
        }
        
        $car = new Car();
        $car->setColor('pink');
        $car->setMake('Ford');
        $car->setModel('F-150');
        ```

        ## Prefer final classes
        ```php
        // Bad:
        final class Car
        {
            private $color;
            public function __construct($color)
            {
                $this->color = $color;
            }
            public function getColor()
            {
                return $this->color;
            }
        }
        
        // Good:
        interface Vehicle
        {
            public function getColor();
        }
        
        final class Car implements Vehicle
        {
            private $color;
            public function __construct($color)
            {
                $this->color = $color;
            }
            public function getColor()
            {
                return $this->color;
            }
        }
        ```

    - path: "**/*.php"
      instructions: |
        # PHP SOLID Principles - Clean Code Rules
        Based on [piotrplenik/clean-code-php](https://github.com/piotrplenik/clean-code-php/):

        ## Single Responsibility Principle (SRP)
        ```php
        // Bad:
        class UserSettings
        {
            private $user;
            public function __construct(User $user)
            {
                $this->user = $user;
            }
            public function changeSettings(array $settings): void
            {
                if ($this->verifyCredentials()) {
                    // ...
                }
            }
            private function verifyCredentials(): bool
            {
                // ...
            }
        }
        
        // Good:
        class UserAuth
        {
            private $user;
            public function __construct(User $user)
            {
                $this->user = $user;
            }
            public function verifyCredentials(): bool
            {
                // ...
            }
        }
        
        class UserSettings
        {
            private $user;
            private $auth;
            public function __construct(User $user)
            {
                $this->user = $user;
                $this->auth = new UserAuth($user);
            }
            public function changeSettings(array $settings): void
            {
                if ($this->auth->verifyCredentials()) {
                    // ...
                }
            }
        }
        ```

        ## Open/Closed Principle (OCP)
        ```php
        // Bad:
        class HttpRequester
        {
            private $adapter;
            public function __construct(Adapter $adapter)
            {
                $this->adapter = $adapter;
            }
            public function fetch(string $url): Promise
            {
                $adapterName = $this->adapter->getName();
                if ($adapterName === 'ajaxAdapter') {
                    return $this->makeAjaxCall($url);
                } elseif ($adapterName === 'httpNodeAdapter') {
                    return $this->makeHttpCall($url);
                }
            }
        }
        
        // Good:
        interface Adapter
        {
            public function request(string $url): Promise;
        }
        
        class HttpRequester
        {
            private $adapter;
            public function __construct(Adapter $adapter)
            {
                $this->adapter = $adapter;
            }
            public function fetch(string $url): Promise
            {
                return $this->adapter->request($url);
            }
        }
        ```

    - path: "**/*.php"
      instructions: |
        # PHP SOLID Principles (Continued) - Clean Code Rules
        Based on [piotrplenik/clean-code-php](https://github.com/piotrplenik/clean-code-php/):

        ## Liskov Substitution Principle (LSP)
        ```php
        // Bad:
        class Rectangle
        {
            protected $width = 0;
            protected $height = 0;
            public function setWidth(int $width): void
            {
                $this->width = $width;
            }
            public function setHeight(int $height): void
            {
                $this->height = $height;
            }
            public function getArea(): int
            {
                return $this->width * $this->height;
            }
        }
        
        class Square extends Rectangle
        {
            public function setWidth(int $width): void
            {
                $this->width = $this->height = $width;
            }
            public function setHeight(int $height): void
            {
                $this->width = $this->height = $height;
            }
        }
        
        // Good:
        interface Shape
        {
            public function getArea(): int;
        }
        
        class Rectangle implements Shape
        {
            private $width = 0;
            private $height = 0;
            public function __construct(int $width, int $height)
            {
                $this->width = $width;
                $this->height = $height;
            }
            public function getArea(): int
            {
                return $this->width * $this->height;
            }
        }
        
        class Square implements Shape
        {
            private $length = 0;
            public function __construct(int $length)
            {
                $this->length = $length;
            }
            public function getArea(): int
            {
                return $this->length ** 2;
            }
        }
        ```

        ## Interface Segregation Principle (ISP)
        ```php
        // Bad:
        interface Employee
        {
            public function work(): void;
            public function eat(): void;
        }
        
        class RobotEmployee implements Employee
        {
            public function work(): void
            {
                //.... working much more
            }
            public function eat(): void
            {
                //.... robot can't eat, but it must implement this method
            }
        }
        
        // Good:
        interface Workable
        {
            public function work(): void;
        }
        
        interface Feedable
        {
            public function eat(): void;
        }
        
        interface Employee extends Feedable, Workable
        {
        }
        
        class RobotEmployee implements Workable
        {
            public function work(): void
            {
                // ....working
            }
        }
        ```

        ## Dependency Inversion Principle (DIP)
        ```php
        // Bad:
        class Employee
        {
            public function work(): void
            {
                // ....working
            }
        }
        
        class Robot extends Employee
        {
            public function work(): void
            {
                //.... working much more
            }
        }
        
        class Manager
        {
            private $employee;
            public function __construct(Employee $employee)
            {
                $this->employee = $employee;
            }
            public function manage(): void
            {
                $this->employee->work();
            }
        }
        
        // Good:
        interface Employee
        {
            public function work(): void;
        }
        
        class Human implements Employee
        {
            public function work(): void
            {
                // ....working
            }
        }
        
        class Robot implements Employee
        {
            public function work(): void
            {
                //.... working much more
            }
        }
        
        class Manager
        {
            private $employee;
            public function __construct(Employee $employee)
            {
                $this->employee = $employee;
            }
            public function manage(): void
            {
                $this->employee->work();
            }
        }
        ```

    - path: "**/*.php"
      instructions: |
        # PHP DRY Principle - Clean Code Rules
        Based on [piotrplenik/clean-code-php](https://github.com/piotrplenik/clean-code-php/):

        ## Don't repeat yourself (DRY)
        ```php
        // Bad:
        function showDeveloperList(array $developers): void
        {
            foreach ($developers as $developer) {
                $expectedSalary = $developer->calculateExpectedSalary();
                $experience = $developer->getExperience();
                $githubLink = $developer->getGithubLink();
                $data = [$expectedSalary, $experience, $githubLink];
                render($data);
            }
        }
        
        function showManagerList(array $managers): void
        {
            foreach ($managers as $manager) {
                $expectedSalary = $manager->calculateExpectedSalary();
                $experience = $manager->getExperience();
                $githubLink = $manager->getGithubLink();
                $data = [$expectedSalary, $experience, $githubLink];
                render($data);
            }
        }
        
        // Good:
        function showList(array $employees): void
        {
            foreach ($employees as $employee) {
                $expectedSalary = $employee->calculateExpectedSalary();
                $experience = $employee->getExperience();
                $githubLink = $employee->getGithubLink();
                $data = [$expectedSalary, $experience, $githubLink];
                render($data);
            }
        }
        
        // Very good:
        function showList(array $employees): void
        {
            foreach ($employees as $employee) {
                render([$employee->calculateExpectedSalary(), $employee->getExperience(), $employee->getGithubLink()]);
            }
        }
        ```

    - path: "**/*.{js,jsx,ts,tsx}"
      instructions: |
        Flag any usage of console.log() as it should be replaced with proper logging or removed:
        1. For development: console.debug()
        2. For production: Remove console.log() statements or use structured logging
        3. For errors: Use error console.error()

        Example replacement:
        ```javascript
        // Instead of:
        console.log('User data:', userData);
        
        // Use:
        console.debug('Processing user data', { userData });
        // or for development only:
        Remove the console.log entirely
        ```

        Flag specific logging violations:
        1. console.log(), console.debug(), console.warn() usage (except console.error in catch blocks)
        2. Any debug output that should use proper logging frameworks

        Example replacements:
        ```javascript
        // Instead of:
        console.log('User data:', userData);
        console.debug('Processing...');
        
        // Use:
        // Remove console.log entirely or use proper logging
        // Only console.error in catch blocks is acceptable
        try {
          processData(userData);
        } catch (error) {
          console.error('Processing failed:', error);
        }
        ```

        Flag JavaScript security and UX issues:
        1. alert(), confirm(), prompt() usage (poor UX)
        2. eval() usage (security risk)
        3. innerHTML with user input (XSS risk)
        4. Unfiltered user input in DOM manipulation

        Example replacements:
        ```javascript
        // Instead of:
        alert('Error occurred');
        eval(userInput);
        
        // Use:
        // Use proper error handling and UI components
        this.showErrorNotification('Error occurred');
        // Avoid eval() entirely
        ```

        Flag TODO/FIXME comments that indicate technical debt:
        1. TODO comments without clear action items
        2. FIXME comments indicating broken functionality
        3. HACK comments indicating temporary workarounds
        4. XXX comments indicating problematic code

        These should be converted to proper issues or addressed:
        ```javascript
        // Instead of:
        // TODO: fix this later
        // FIXME: this is broken
        
        // Use:
        // Create proper issue and reference it
        // @see Issue #123: Refactor validation logic
        ```

        Flag code complexity issues:
        1. Functions longer than 50 lines
        2. Deep nesting (more than 3 levels)
        3. Cyclomatic complexity > 10
        4. Missing type annotations (TypeScript)
        5. Inconsistent error handling

        Consider refactoring:
        ```javascript
        // Instead of:
        function processEverything(data) {
            // 100+ lines of mixed logic
        }
        
        // Use:
        function processData(data: UserData): Result {
            validateInput(data);
            const transformed = transformData(data);
            return saveResults(transformed);
        }
        ```

        Flag performance issues:
        1. Unnecessary DOM queries in loops
        2. Missing debouncing for frequent events
        3. Large data processing without pagination
        4. Memory leaks from event listeners
        5. Inefficient array operations

        Example fixes:
        ```javascript
        // Instead of:
        items.forEach(item => {
            document.querySelector(`#item-${item.id}`).textContent = item.name;
        });
        
        // Use:
        const container = document.querySelector('#items-container');
        items.forEach(item => {
            container.querySelector(`#item-${item.id}`).textContent = item.name;
        });
        ```

        Flag deprecated/legacy code usage:
        1. Any usage of deprecated APIs or methods (look for @deprecated in docblocks or comments)
        2. Calls to deprecated functions
        3. Encourage migration to newer APIs or patterns

        Flag excessive function parameters:
        1. Functions with more than 4-5 parameters (especially if many are optional)
        2. Suggest refactoring to use objects or destructured options

        Flag global/static state:
        1. Use of global variables (window, global, etc.)
        2. Excessive use of static properties
        3. Encourage module or instance-based design

        Flag anonymous functions in loops:
        1. Creation of closures inside loops (forEach, for, while)
        2. Suggest moving closure definition outside the loop

        Flag unnecessary type casting:
        1. Unnecessary or redundant type casts (e.g., Number(Number(x)), String(String(y)))
        2. Type casts that can be avoided by using proper types

        Flag unoptimized loops:
        1. Nested loops with potential for O(n^2) or worse complexity, especially if not commented
        2. Loops that can be replaced with built-in functions or more efficient algorithms