refactor(PropertyInspector): update return type and error handling

- Change PropertyInspector::inspect() to return PropertyAttributeHandler
- Update PropertyInspectorTest to reflect new return type and behavior
- Add additional tests for exception and error handling
- Remove obsolete test cases

Author: walmir-silva

src/Contract/PropertyInspector.php

@@ -16,7 +16,7 @@ interface PropertyInspector
      *
      * @throws PropertyInspectionException If there's an error inspecting the object
      *
-     * @return array<string, array<int, mixed>> The inspection results
+     * @return PropertyAttributeHandler The inspection results
      */
-    public function inspect(object $object, PropertyAttributeHandler $handler): array;
+    public function inspect(object $object, PropertyAttributeHandler $handler): PropertyAttributeHandler;
 }

src/Utility/PropertyInspector.php

@@ -15,26 +15,21 @@ public function __construct(private readonly AttributeAnalyzer $attributeAnalyze
     {
     }
 
-    public function inspect(object $object, PropertyAttributeHandler $handler): array
+    public function inspect(object $object, PropertyAttributeHandler $handler): PropertyAttributeHandler
     {
         try {
             $analysisResults = $this->attributeAnalyzer->analyzeObject($object);
-            $handledResults = [];
-
             foreach ($analysisResults as $propertyName => $propertyData) {
                 foreach ($propertyData['attributes'] as $attribute) {
-                    $result = $handler->handleAttribute($propertyName, $attribute, $propertyData['value']);
-                    if (null !== $result) {
-                        $handledResults[$propertyName][] = $result;
-                    }
+                    $handler->handleAttribute($propertyName, $attribute, $propertyData['value']);
                 }
             }
 
-            return $handledResults;
+            return $handler;
         } catch (\ReflectionException $e) {
             throw new PropertyInspectionException('Failed to analyze object: ' . $e->getMessage(), 0, $e);
         } catch (\Exception $e) {
-            throw new PropertyInspectionException('An error occurred during object analysis: ' . $e->getMessage(), 0, $e);
+            throw new PropertyInspectionException('An exception occurred during object analysis: ' . $e->getMessage(), 0, $e);
         } catch (\Error $e) {
             throw new PropertyInspectionException('An error occurred during object analysis: ' . $e->getMessage(), 0, $e);
         }

tests/Utility/PropertyInspectorTest.php

@@ -40,11 +40,11 @@ public function testInspect(): void
 
         $mockHandler->expects($this->once())
             ->method('handleAttribute')
-            ->willReturn('handled result');
+            ->with('property1', $this->isInstanceOf(\stdClass::class), 'value1');
 
         $result = $this->inspector->inspect($object, $mockHandler);
 
-        $this->assertEquals(['property1' => ['handled result']], $result);
+        $this->assertSame($mockHandler, $result);
     }
 
     public function testInspectWithNoResults(): void
@@ -56,9 +56,12 @@ public function testInspectWithNoResults(): void
             ->method('analyzeObject')
             ->willReturn([]);
 
+        $mockHandler->expects($this->never())
+            ->method('handleAttribute');
+
         $result = $this->inspector->inspect($object, $mockHandler);
 
-        $this->assertEmpty($result);
+        $this->assertSame($mockHandler, $result);
     }
 
     public function testInspectWithAnalyzerException(): void
@@ -76,7 +79,7 @@ public function testInspectWithAnalyzerException(): void
         $this->inspector->inspect($object, $mockHandler);
     }
 
-    public function testInspectWithHandlerReturningNull(): void
+    public function testInspectWithMultipleAttributes(): void
     {
         $object = new \stdClass();
         $mockHandler = $this->createMock(PropertyAttributeHandler::class);
@@ -86,39 +89,46 @@ public function testInspectWithHandlerReturningNull(): void
             ->willReturn([
                 'property1' => [
                     'value' => 'value1',
-                    'attributes' => [new \stdClass()],
+                    'attributes' => [new \stdClass(), new \stdClass()],
                 ],
             ]);
 
-        $mockHandler->expects($this->once())
+        $mockHandler->expects($this->exactly(2))
             ->method('handleAttribute')
-            ->willReturn(null);
+            ->with('property1', $this->isInstanceOf(\stdClass::class), 'value1');
 
         $result = $this->inspector->inspect($object, $mockHandler);
 
-        $this->assertEmpty($result);
+        $this->assertSame($mockHandler, $result);
     }
 
-    public function testInspectWithMultipleAttributes(): void
+    public function testInspectWithGeneralException(): void
     {
         $object = new \stdClass();
         $mockHandler = $this->createMock(PropertyAttributeHandler::class);
 
         $this->analyzer->expects($this->once())
             ->method('analyzeObject')
-            ->willReturn([
-                'property1' => [
-                    'value' => 'value1',
-                    'attributes' => [new \stdClass(), new \stdClass()],
-                ],
-            ]);
+            ->willThrowException(new \Exception('General exception'));
 
-        $mockHandler->expects($this->exactly(2))
-            ->method('handleAttribute')
-            ->willReturn('handled result');
+        $this->expectException(PropertyInspectionException::class);
+        $this->expectExceptionMessage('An exception occurred during object analysis: General exception');
 
-        $result = $this->inspector->inspect($object, $mockHandler);
+        $this->inspector->inspect($object, $mockHandler);
+    }
+
+    public function testInspectWithError(): void
+    {
+        $object = new \stdClass();
+        $mockHandler = $this->createMock(PropertyAttributeHandler::class);
+
+        $this->analyzer->expects($this->once())
+            ->method('analyzeObject')
+            ->willThrowException(new \Error('Fatal error'));
 
-        $this->assertEquals(['property1' => ['handled result', 'handled result']], $result);
+        $this->expectException(PropertyInspectionException::class);
+        $this->expectExceptionMessage('An error occurred during object analysis: Fatal error');
+
+        $this->inspector->inspect($object, $mockHandler);
     }
 }