add ProcessorValidator and ValidatableProcessor interfaces (#32)

* add size method

* feat: Normalize Interfaces

- Refined and standardized interface definitions across the project
- Applied Single Responsibility Principle (SRP) to ensure each interface has a clear, singular purpose
- Consistent naming conventions were implemented for better readability and maintainability
- Added thorough documentation for each interface, including method descriptions and expected behaviors
- Organized interfaces within appropriate namespaces to prevent naming collisions and maintain a logical structure
- Ensured parameter names in interface methods are consistent with implementing classes
- Avoided including constructors in interfaces to maintain flexibility

These changes enhance the overall clarity, maintainability, and professional quality of the codebase.

* Refactor and Normalize Collection Interface and Implementation

- Refactored `Collection` interface for consistency and adherence to best practices.
- Ensured all tests are comprehensive and validate the expected behavior.

* feat: Add BinaryHeap implementation and comprehensive tests

- Implemented BinaryHeap class with support for both min-heap and max-heap operations.
  - Methods include: add, poll, peek, size, isEmpty, heapifyUp, heapifyDown, swap, and compare.
- Created unit tests for BinaryHeap class ensuring 100% coverage.
  - Tested all key operations: add, poll, peek, heapifyUp, heapifyDown, swap, and compare.
  - Included edge case tests for min-heap and max-heap scenarios.
- Ensured compliance with type safety and PHP 8.0+ features.
- Added comprehensive documentation and examples for BinaryHeap usage.

This commit enhances the KaririCode Framework by providing a robust, type-safe, and efficient BinaryHeap data structure with extensive unit tests.

* docs: Update README files in English and Portuguese

- Enhanced the overview and key features sections for clarity and completeness.
- Added detailed descriptions for all implemented data structures:
  - TreeSet
  - ArrayDeque
  - ArrayQueue
  - TreeMap
  - LinkedList
  - BinaryHeap
  - HashMap
- Included complexity analysis and key methods for each data structure.
- Provided usage examples for each data structure to demonstrate functionality.
- Updated installation instructions and requirements.
- Updated acknowledgments and roadmap sections.

* style: Normalize code formatting and style

* feat: Create Container interface and add unit tests

- Define the Container interface with methods: `set`, `get`, and `has`.
- Implement unit tests for `set` method to ensure services are registered correctly.
- Add unit tests for `get` method to verify correct retrieval of services by identifier.
- Include unit tests for `has` method to check existence of services in the container.
- Normalize the `@category` comments in the interface documentation for consistency.

These changes establish a foundational contract for dependency injection within the KaririCode project and ensure robust and reliable functionality through comprehensive testing

* feat: Add logging interfaces and corresponding tests

- Created Configurable interface for managing configuration settings.
- Created Loggable interface to define logging methods for various log levels.
- Created ContextAware interface for managing context information in logs.
- Created FormatterAware interface for handling log formatter settings.
- Created HandlerAware interface for managing log handlers.
- Created ProcessorAware interface for managing log processors.
- Created LoggingManager interface that combines various logging functionalities.
- Created LogFormatter interface for defining log formatters.
- Created LogHandler interface for handling log records.
- Created LogLevel interface for defining log levels.
- Created LogProcessor interface for processing log records before handling.
- Created LogRotator interface for managing log file rotation.

- Added unit tests for each interface to ensure correct functionality:
  - ConfigurableTest: Tests for setConfig and getConfig methods.
  - LoggableTest: Tests for various logging level methods.
  - ContextAwareTest: Tests for withContext and getContext methods.
  - FormatterAwareTest: Tests for setFormatter and getFormatter methods.
  - HandlerAwareTest: Tests for addHandler, pushHandler, popHandler, and getHandlers methods.
  - ProcessorAwareTest: Tests for addProcessor and getProcessors methods.
  - LoggingManagerTest: Comprehensive tests for all LoggingManager methods.
  - LogFormatterTest: Test for the format method.
  - LogHandlerTest: Test for the handle method.
  - LogLevelTest: Test for the getLevel method.
  - LogProcessorTest: Test for the process method.
  - LogRotatorTest: Test for the rotate method.

* feat: Update logging interfaces Add tests for LoggerAware and LoggerConfigurable interfaces

- Revised and enhanced logging interfaces for better consistency and flexibility.
- Implemented new methods to support asynchronous logging.
- Improved documentation of the interfaces to facilitate integration.
- Added unit tests to ensure the robustness of the new implementations.
- Added unit test for LoggerAware interface to verify setLogger method.
- Added unit test for LoggerConfigurable interface to verify configure method.
- Ensured proper mock setup and expectations in tests.

* feat(logging): improve log rotation and update log handler

- Removed .phpcs-cache for cleaner repository
- Updated src/Logging/LogHandler.php to enhance log handling capabilities
- Modified src/Logging/LogLevel.php for better log level management
- Enhanced src/Logging/LogRotator.php with improved file rotation logic
- Updated src/Logging/Logger.php to integrate changes in log handling and rotation

* Refactor:Indexable interface and LogLevel class

- Modified the Indexable.php interface to enhance functionality.
- Updated the LogLevel.php class to add new log levels.
- Made lint adjustments in LogRotator class.

* feat(contract): Add Processor interfaces and tests

- Introduce new interfaces: Processor, ConfigurableProcessor, Pipeline
- Add comprehensive PHPUnit tests for each interface
- Enhance code documentation with detailed PHP DocBlocks
- Ensure consistency with existing KaririCode coding standards

* feat: add ProcessorRegistry interface and unit tests

- Introduced `ProcessorRegistry` interface to standardize processor registration and retrieval across contexts.
- Added `ProcessorRegistryTest` class to ensure correctness of the new interface, covering scenarios like processor registration, retrieval, and error handling.

* feat(processor): add ProcessorBuilder interface and test suite

- Add ProcessorBuilder interface in KaririCode\Contract\Processor namespace
  - Define build() method for constructing individual processors
  - Define buildPipeline() method for assembling processor pipelines

- Create ProcessorBuilderTest class in KaririCode\Contract\Tests\Processor namespace
  - Implement tests for build() and buildPipeline() methods
  - Cover success scenarios and exception handling
  - Ensure proper interaction with ProcessorRegistry

* feat(contract): add PHPDoc for ProcessableAttribute interface and create unit tests

- Add PHPDoc comments for ProcessableAttribute interface, including method descriptions and author/license information
- Create unit tests for ProcessableAttribute interface, testing `getProcessors` and `getFallbackValue` methods

* feat(contract): add Sanitizer, Serializer, and Validator interfaces with unit tests

- Add `Sanitizer` interface for sanitizing input data in `src/Sanitizer/`
- Add `Validator` interface for validating input data in `src/Validator/`
- Add `Serializer` interface for serializing and deserializing data in `src/Serializer/`
- Create unit tests for each interface to ensure expected behavior

* fix(validator): correct return type of Validator interface

* feat(contract): add CustomizableMessageAttribute interface

- Introduce CustomizableMessageAttribute interface in KaririCode\Contract\Processor\Attribute namespace
- Add method getMessage(string $validatorName): ?string to the interface
- Create unit tests for CustomizableMessageAttribute in CustomizableMessageAttributeTest
- Update existing ProcessableAttribute interface documentation for consistency

* feat: add BaseProcessorAttribute abstract class

* refactor: adjusty filterValidProcessors in BaseProcessorAttribute

* feat(processor): add ProcessorValidator and ValidatableProcessor interfaces with unit tests

- Added ProcessorValidator interface to define contract for validating processors in a pipeline.
- Added ValidatableProcessor interface to define contract for processors with validation capabilities.
- Created unit tests for ProcessorValidator and ValidatableProcessor to ensure proper validation behavior.

Author: walmir-silva

docker-compose.yml

@@ -1,5 +1,3 @@
-version: "3.8"
-
 services:
   php:
     container_name: kariricode-contract

src/Processor/ProcessorValidator.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Processor;
+
+/**
+ * Interface ProcessorValidator.
+ *
+ * Defines the contract for validating processors within the processing pipeline.
+ * A ProcessorValidator is responsible for ensuring that a processor is in a valid state
+ * before allowing it to proceed with its task. If validation fails, the validator returns
+ * an array containing error details, which can be used to handle the failure.
+ *
+ * This interface supports custom validation messages, allowing flexibility in
+ * error reporting based on the context or type of processor.
+ *
+ * @category  ProcessorPipeline
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface ProcessorValidator
+{
+    /**
+     * Validates a processor and returns any validation errors.
+     *
+     * This method checks whether the given processor meets the required validation
+     * criteria. If the processor is invalid, it returns an array containing the error
+     * details, including a custom error message if provided. Otherwise, it returns null.
+     *
+     * @param Processor $processor the processor to be validated
+     * @param string $processorName the unique name of the processor, used to identify it in the context of validation
+     * @param array $messages an array of custom messages for validation errors, keyed by processor name
+     *
+     * @return array|null the validation error details, or null if validation passes
+     */
+    public function validate(Processor $processor, string $processorName, array $messages): ?array;
+}

src/Processor/ValidatableProcessor.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Processor;
+
+/**
+ * Interface ValidatableProcessor.
+ *
+ * Defines the contract for processors that include validation capabilities.
+ * A ValidatableProcessor is a specialized Processor that can perform validation
+ * during its execution, and may return specific error details if validation fails.
+ *
+ * This interface extends the basic Processor contract by adding methods to check
+ * for validity and retrieve validation error information.
+ *
+ * @category  ProcessorPipeline
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface ValidatableProcessor extends Processor
+{
+    /**
+     * Checks if the processor is in a valid state.
+     *
+     * This method determines whether the processor has met all required
+     * conditions and can continue processing. A processor that fails validation
+     * may halt the processing pipeline or trigger corrective actions.
+     *
+     * @return bool true if the processor is valid, false otherwise
+     */
+    public function isValid(): bool;
+
+    /**
+     * Retrieves the error key if the processor fails validation.
+     *
+     * When a processor is deemed invalid by the isValid method, this method
+     * returns a key that uniquely identifies the validation error. This key
+     * can be used for logging, error messages, or further handling within the
+     * processing pipeline.
+     *
+     * @return string|null the error key, or null if no validation error occurred
+     */
+    public function getErrorKey(): ?string;
+}

tests/Processor/ProcessorValidatorTest.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Tests\Processor;
+
+use KaririCode\Contract\Processor\Processor;
+use KaririCode\Contract\Processor\ProcessorValidator;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+final class ProcessorValidatorTest extends TestCase
+{
+    public function testValidateReturnsNullOnValidProcessor(): void
+    {
+        /** @var Processor|MockObject */
+        $processor = $this->createMock(Processor::class);
+        /** @var ProcessorValidator|MockObject */
+        $validator = $this->createMock(ProcessorValidator::class);
+
+        $validator->expects($this->once())
+            ->method('validate')
+            ->with($processor, 'testProcessor', [])
+            ->willReturn(null);
+
+        $this->assertNull($validator->validate($processor, 'testProcessor', []));
+    }
+
+    public function testValidateReturnsErrorDetailsOnInvalidProcessor(): void
+    {
+        /** @var Processor|MockObject */
+        $processor = $this->createMock(Processor::class);
+        /** @var ProcessorValidator|MockObject */
+        $validator = $this->createMock(ProcessorValidator::class);
+
+        $errorDetails = ['error' => 'Invalid processor'];
+
+        $validator->expects($this->once())
+            ->method('validate')
+            ->with($processor, 'testProcessor', [])
+            ->willReturn($errorDetails);
+
+        $this->assertSame($errorDetails, $validator->validate($processor, 'testProcessor', []));
+    }
+}

tests/Processor/ValidatableProcessorTest.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Tests\Processor;
+
+use KaririCode\Contract\Processor\ValidatableProcessor;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+final class ValidatableProcessorTest extends TestCase
+{
+    public function testIsValidReturnsTrueForValidProcessor(): void
+    {
+        /** @var ValidatableProcessor|MockObject */
+        $processor = $this->createMock(ValidatableProcessor::class);
+
+        $processor->expects($this->once())
+            ->method('isValid')
+            ->willReturn(true);
+
+        $this->assertTrue($processor->isValid());
+    }
+
+    public function testIsValidReturnsFalseForInvalidProcessor(): void
+    {
+        /** @var ValidatableProcessor|MockObject */
+        $processor = $this->createMock(ValidatableProcessor::class);
+
+        $processor->expects($this->once())
+            ->method('isValid')
+            ->willReturn(false);
+
+        $this->assertFalse($processor->isValid());
+    }
+
+    public function testGetErrorKeyReturnsNullForValidProcessor(): void
+    {
+        /** @var ValidatableProcessor|MockObject */
+        $processor = $this->createMock(ValidatableProcessor::class);
+
+        $processor->expects($this->once())
+            ->method('getErrorKey')
+            ->willReturn(null);
+
+        $this->assertNull($processor->getErrorKey());
+    }
+
+    public function testGetErrorKeyReturnsErrorKeyForInvalidProcessor(): void
+    {
+        /** @var ValidatableProcessor|MockObject */
+        $processor = $this->createMock(ValidatableProcessor::class);
+
+        $errorKey = 'error_key_123';
+
+        $processor->expects($this->once())
+            ->method('getErrorKey')
+            ->willReturn($errorKey);
+
+        $this->assertSame($errorKey, $processor->getErrorKey());
+    }
+}