Refactor Test Structure: Add PHPUnit Tests for Interfaces with Strong Typing and Mocks (#9)

* add data structure contracts and tests

* feat: Add and configure PHP quality and testing libraries

- Added `friendsofphp/php-cs-fixer` for code style fixing.
- Added `nunomaduro/phpinsights` for code quality and insights.
- Updated `phpunit/phpunit` to version 10.5 for unit testing.
- Added `squizlabs/php_codesniffer` for code style checking.
- Added `mockery/mockery` for mocking objects in unit tests.
- Added `enlightn/security-checker` for checking security vulnerabilities in dependencies.

Configured these libraries to ensure code quality, consistency, and security.

### Changes Introduced
1. **Code Style Fixing**:
   - Added `friendsofphp/php-cs-fixer` (^3.58) to automatically fix PHP code to follow defined coding standards.

2. **Code Quality Insights**:
   - Added `nunomaduro/phpinsights` (^2.11) to provide code quality and performance insights.

3. **Unit Testing**:
   - Updated `phpunit/phpunit` to version ^10.5 to ensure robust and comprehensive testing of the codebase.

4. **Code Style Checking**:
   - Added `squizlabs/php_codesniffer` (^3.10) to detect violations of defined coding standards.

5. **Mocking in Unit Tests**:
   - Added `mockery/mockery` (^1.6) to provide an expressive and flexible API for mocking objects in unit tests.

6. **Security Vulnerability Checking**:
   - Added `enlightn/security-checker` (^2.0) to scan for known security vulnerabilities in project dependencies.

### Usage
- **Code Style Fixing**:
  ```sh
  vendor/bin/php-cs-fixer fix
  ```

- **Code Quality Insights**:
  ```sh
  vendor/bin/phpinsights
  ```

- **Unit Testing**:
  ```sh
  vendor/bin/phpunit
  ```

- **Code Style Checking**:
  ```sh
  vendor/bin/phpcs
  ```

- **Mocking in Unit Tests**:
  - Use Mockery within your PHPUnit tests to create mocks and set expectations.

- **Security Vulnerability Checking**:
  ```sh
  vendor/bin/security-checker security:check
  ```

### Benefits
- Ensures consistent code style across the project.
- Provides actionable insights to improve code quality.
- Enhances testing capabilities with updated PHPUnit and Mockery.
- Ensures project dependencies are free from known security vulnerabilities.

### Notes
- Ensure that the required binaries are executable in your environment.
- Integrate these tools into your CI/CD pipeline for automated checks.

* resolve style PSR

* add Translate README to Brazilian Portuguese

* update ci

* Update composer.json to exclude unnecessary files and directories for package distribution

* adjust lock composer

* adjust lock composer

* adjust .env.example

* update .env.example

* Add .phpcs-cache to .gitignore and remove from version control

* update url repository in composer file

* add git attributed file

* remove file exclud reference

* Adjust settings for composer

* normalize the semantic syntax of methods and interface names

* Refactor test structure: Add PHPUnit tests for interfaces with strong typing and mocks

- Add tests for Comparable interface
- Add tests for Countable interface
- Add tests for Indexable interface
- Add tests for Iterator interface
- Add tests for Sortable interface
- Add tests for Collection interface
- Add tests for Serializable interface
- Add tests for Heap interface
- Add tests for IterableCollection interface
- Add tests for Map interface
- Add tests for Queue interface
- Add tests for Stack interface
- Add tests for Tree interface

Organize test files into respective directories for Behavioral, DataStructure, Structural, and Structure

---------

Co-authored-by: Walmir Silva <walmir.silva@growthdev.com.br>

Author: walmir-silva

composer.lock

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\DataStructure\Behavioral;
+
+/**
+ * Interface Comparable.
+ *
+ * Defines the contract for objects that can be compared.
+ *
+ * @category  Interfaces
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface Comparable
+{
+    /**
+     * Compares this object with the specified object for order.
+     *
+     * @param mixed $other The object to compare with
+     *
+     * @return int a negative integer, zero, or a positive integer as this object
+     *             is less than, equal to, or greater than the specified object
+     */
+    public function compareTo(mixed $other): int;
+}

src/DataStructure/Behavioral/Comparable.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\DataStructure\Behavioral;
+
+/**
+ * Interface Countable.
+ *
+ * Defines the contract for counting elements.
+ *
+ * @category  Interfaces
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface Countable
+{
+    /**
+     * Counts the elements.
+     *
+     * @return int The number of elements
+     */
+    public function count(): int;
+}

src/DataStructure/Behavioral/Countable.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\DataStructure\Behavioral;
+
+/**
+ * Interface Indexable.
+ *
+ * Defines the contract for indexed access to elements.
+ *
+ * @category  Interfaces
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface Indexable
+{
+    /**
+     * Checks if an element exists at the given index.
+     *
+     * @param int $index The index to check
+     *
+     * @return bool True if the index exists, false otherwise
+     */
+    public function contains(int $index): bool;
+
+    /**
+     * Gets the element at the specified index.
+     *
+     * @param int $index The index of the element
+     *
+     * @return mixed The element at the specified index
+     */
+    public function get(int $index): mixed;
+
+    /**
+     * Sets the element at the specified index.
+     *
+     * @param int $index The index at which to set the element
+     * @param mixed $element The element to set
+     */
+    public function set(int $index, mixed $element): void;
+
+    /**
+     * Removes the element at the specified index.
+     *
+     * @param int $index The index of the element to remove
+     *
+     * @return bool True if the element was removed, false otherwise
+     */
+    public function remove(int $index): bool;
+}

src/DataStructure/Behavioral/Indexable.php

@@ -2,24 +2,25 @@
 
 declare(strict_types=1);
 
-namespace KaririCode\Contract\DataStructure;
+namespace KaririCode\Contract\DataStructure\Behavioral;
 
 /**
  * Interface IterableCollection.
  *
  * Provides the ability to iterate over a collection.
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
  *
  * @see      https://kariricode.org/
  */
-interface IterableCollection extends \IteratorAggregate
+interface IterableCollection extends \Traversable
 {
     /**
      * Gets an iterator for the collection.
      *
-     * @return \Traversable an iterator for the collection
+     * @return Iterator an iterator for the collection
      */
-    public function getIterator(): \Traversable;
+    public function getIterator(): Iterator;
 }