fix: implement recursive extension context validation in FHIRValidationService

- Updated `validateExtensionContexts` to support recursive validation across nested resource trees.
- Added cycle detection using `spl_object_id` to prevent infinite loops during validation.
- Improved filtering logic to defer type-hierarchy resolution for non-matching or foreign-root contexts.
- Updated invariant and extension validation to capture violations with detailed paths.

Author: Ardenexal

src/Component/Validation/src/FHIRValidationService.php

@@ -47,7 +47,8 @@ public function validate(
             }
         }
 
-        foreach ($this->validateExtensionContexts($resource) as $contextViolation) {
+        $contextVisited = [];
+        foreach ($this->validateExtensionContexts($resource, $this->getResourceFhirType($resource), '', $contextVisited) as $contextViolation) {
             $violations[] = $contextViolation;
         }
 
@@ -315,76 +316,142 @@ private function validateModifierExtensions(object $resource, string $path, arra
     }
 
     /**
-     * Pass 2 (v1: top-level walk only): check extension context and contextInvariant
-     * constraints for all extensions attached directly to $resource.
+     * Pass 2: check extension context and contextInvariant constraints for all extensions
+     * throughout the resource tree. Walks nested sub-elements recursively.
      *
-     * Recursive sub-element walking and FHIR type-hierarchy resolution are deferred to v2.
+     * At sub-element level (path contains a dot), only extensions whose context expression
+     * is a dotted path sharing the current root resource type are checked. Bare type-name
+     * contexts (e.g. "HumanName") and foreign-root paths (e.g. "ElementDefinition.binding"
+     * inside StructureDefinition) require FHIR type-hierarchy resolution — deferred.
+     *
+     * @param array<int, true> $visited spl_object_id keys of already-visited objects (cycle guard)
      *
      * @return list<FHIRValidationViolation>
      */
-    private function validateExtensionContexts(object $resource): array
+    private function validateExtensionContexts(object $resource, string $fhirPath, string $relPath, array &$visited): array
     {
-        if (!method_exists($resource, 'getExtensions')) {
+        $id = spl_object_id($resource);
+
+        if (isset($visited[$id])) {
             return [];
         }
 
-        $elementPath = $this->getResourceFhirType($resource);
-        $violations  = [];
-
-        /** @var list<object> $extensions */
-        $extensions = $resource->getExtensions();
-
-        foreach ($extensions as $extension) {
-            $ref          = new \ReflectionClass($extension);
-            $contextAttrs = array_map(
-                static fn (\ReflectionAttribute $a): FHIRExtensionContext => $a->newInstance(),
-                $ref->getAttributes(FHIRExtensionContext::class),
-            );
+        $visited[$id] = true;
+        $violations   = [];
 
-            if ($contextAttrs !== [] && !$this->contextPermitsPath($contextAttrs, $elementPath)) {
-                $url          = method_exists($extension, 'getExtensionUrl') ? ($extension->getExtensionUrl() ?? '') : '';
-                $violations[] = new FHIRValidationViolation(
-                    severity: 'error',
-                    path: 'extension',
-                    message: sprintf(
-                        'Extension "%s" is not permitted on element "%s".',
-                        $url,
-                        $elementPath,
-                    ),
-                    constraintClass: FHIRExtensionContext::class,
-                    profileGroup: null,
-                    invariantKey: null,
+        if (method_exists($resource, 'getExtensions')) {
+            $extViolationPath = $relPath !== '' ? $relPath . '.extension' : 'extension';
+
+            // At sub-element level, determine the root resource type so that only context
+            // expressions explicitly targeting this resource's path hierarchy are evaluated.
+            // Contexts without a dot or with a different root type require type-hierarchy
+            // resolution and are deferred. At root level ($rootType === null) all
+            // expressions are checked as before.
+            $dotPos   = strpos($fhirPath, '.');
+            $rootType = $dotPos !== false ? substr($fhirPath, 0, $dotPos) : null;
+
+            /** @var list<object> $extensions */
+            $extensions = $resource->getExtensions();
+
+            foreach ($extensions as $extension) {
+                $ref          = new \ReflectionClass($extension);
+                $contextAttrs = array_map(
+                    static fn (\ReflectionAttribute $a): FHIRExtensionContext => $a->newInstance(),
+                    $ref->getAttributes(FHIRExtensionContext::class),
                 );
-            }
-
-            $invariantAttrs = array_map(
-                static fn (\ReflectionAttribute $a): FHIRContextInvariant => $a->newInstance(),
-                $ref->getAttributes(FHIRContextInvariant::class),
-            );
 
-            foreach ($invariantAttrs as $invariant) {
-                try {
-                    $result = $this->pathService->evaluate($invariant->expression, $resource);
-                    $passed = $result->count() === 1 && $result->first() === true;
-                } catch (\Throwable) {
-                    $passed = false;
+                // Sub-element filter: skip extensions whose context expressions cannot be
+                // evaluated against a structural path without FHIR type-hierarchy resolution.
+                if ($rootType !== null && $contextAttrs !== []) {
+                    $hasCheckable = false;
+                    foreach ($contextAttrs as $ctx) {
+                        if ($ctx->type === 'element'
+                            && str_contains($ctx->expression, '.')
+                            && str_starts_with($ctx->expression, $rootType . '.')
+                        ) {
+                            $hasCheckable = true;
+                            break;
+                        }
+                    }
+                    if (!$hasCheckable) {
+                        continue;
+                    }
                 }
 
-                if (!$passed) {
+                if ($contextAttrs !== [] && !$this->contextPermitsPath($contextAttrs, $fhirPath)) {
                     $url          = method_exists($extension, 'getExtensionUrl') ? ($extension->getExtensionUrl() ?? '') : '';
                     $violations[] = new FHIRValidationViolation(
                         severity: 'error',
-                        path: 'extension',
+                        path: $extViolationPath,
                         message: sprintf(
-                            'Extension "%s" contextInvariant failed: %s',
+                            'Extension "%s" is not permitted on element "%s".',
                             $url,
-                            $invariant->expression,
+                            $fhirPath,
                         ),
-                        constraintClass: FHIRContextInvariant::class,
+                        constraintClass: FHIRExtensionContext::class,
                         profileGroup: null,
                         invariantKey: null,
                     );
                 }
+
+                $invariantAttrs = array_map(
+                    static fn (\ReflectionAttribute $a): FHIRContextInvariant => $a->newInstance(),
+                    $ref->getAttributes(FHIRContextInvariant::class),
+                );
+
+                foreach ($invariantAttrs as $invariant) {
+                    try {
+                        $result = $this->pathService->evaluate($invariant->expression, $resource);
+                        $passed = $result->count() === 1 && $result->first() === true;
+                    } catch (\Throwable) {
+                        $passed = false;
+                    }
+
+                    if (!$passed) {
+                        $url          = method_exists($extension, 'getExtensionUrl') ? ($extension->getExtensionUrl() ?? '') : '';
+                        $violations[] = new FHIRValidationViolation(
+                            severity: 'error',
+                            path: $extViolationPath,
+                            message: sprintf(
+                                'Extension "%s" contextInvariant failed: %s',
+                                $url,
+                                $invariant->expression,
+                            ),
+                            constraintClass: FHIRContextInvariant::class,
+                            profileGroup: null,
+                            invariantKey: null,
+                        );
+                    }
+                }
+            }
+        }
+
+        $ref = new \ReflectionClass($resource);
+
+        foreach ($ref->getProperties(\ReflectionProperty::IS_PUBLIC) as $prop) {
+            if (in_array($prop->getName(), ['extension', 'modifierExtension'], true)) {
+                continue;
+            }
+            if ($prop->isInitialized($resource) === false) {
+                continue;
+            }
+
+            $value       = $prop->getValue($resource);
+            $subFhirPath = $fhirPath . '.' . $prop->getName();
+            $subRelPath  = $relPath !== '' ? $relPath . '.' . $prop->getName() : $prop->getName();
+
+            if (is_object($value)) {
+                foreach ($this->validateExtensionContexts($value, $subFhirPath, $subRelPath, $visited) as $v) {
+                    $violations[] = $v;
+                }
+            } elseif (is_array($value)) {
+                foreach ($value as $i => $item) {
+                    if (is_object($item)) {
+                        foreach ($this->validateExtensionContexts($item, $subFhirPath, $subRelPath . '[' . $i . ']', $visited) as $v) {
+                            $violations[] = $v;
+                        }
+                    }
+                }
             }
         }
 

src/Component/Validation/tests/Unit/FHIRExtensionContextNestedValidationTest.php

@@ -0,0 +1,94 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ardenexal\FHIRTools\Component\Validation\Tests\Unit;
+
+use Ardenexal\FHIRTools\Component\FHIRPath\Service\FHIRPathService;
+use Ardenexal\FHIRTools\Component\Metadata\Attribute\Validation\FHIRExtensionContext;
+use Ardenexal\FHIRTools\Component\Validation\FHIRValidationService;
+use Ardenexal\FHIRTools\Component\Validation\Tests\Unit\Fixture\NestedContactWithExtensionsFixture;
+use Ardenexal\FHIRTools\Component\Validation\Tests\Unit\Fixture\PatientContactOnlyExtensionFixture;
+use Ardenexal\FHIRTools\Component\Validation\Tests\Unit\Fixture\PatientNameOnlyExtensionFixture;
+use Ardenexal\FHIRTools\Component\Validation\Tests\Unit\Fixture\PatientPermittedExtensionFixture;
+use Ardenexal\FHIRTools\Component\Validation\Tests\Unit\Fixture\PatientWithContactResourceFixture;
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Validator\ConstraintViolationList;
+use Symfony\Component\Validator\Validator\ValidatorInterface;
+
+final class FHIRExtensionContextNestedValidationTest extends TestCase
+{
+    private FHIRValidationService $service;
+
+    protected function setUp(): void
+    {
+        $validator = $this->createStub(ValidatorInterface::class);
+        $validator->method('validate')->willReturn(new ConstraintViolationList());
+
+        $this->service = new FHIRValidationService($validator, new FHIRPathService());
+    }
+
+    public function testNestedExtensionRestrictedToSiblingPathProducesError(): void
+    {
+        // PatientNameOnlyExtensionFixture context is "Patient.name".
+        // Placed on Patient.contact — a sibling path — it must produce a violation.
+        $contact  = new NestedContactWithExtensionsFixture([new PatientNameOnlyExtensionFixture()]);
+        $resource = new PatientWithContactResourceFixture(contact: [$contact]);
+
+        $report = $this->service->validate($resource);
+
+        self::assertCount(1, $report->errors(), 'Extension restricted to Patient.name must fail on Patient.contact');
+
+        $violation = $report->errors()[0];
+        self::assertSame('error', $violation->severity);
+        self::assertSame('contact[0].extension', $violation->path);
+        self::assertSame(FHIRExtensionContext::class, $violation->constraintClass);
+        self::assertStringContainsString('Patient.contact', $violation->message);
+        self::assertStringContainsString('http://example.org/ext/patient-name-only', $violation->message);
+    }
+
+    public function testNestedExtensionMatchingContactPathProducesNoViolation(): void
+    {
+        // PatientContactOnlyExtensionFixture context is "Patient.contact".
+        // Placed on Patient.contact — it must be permitted.
+        $contact  = new NestedContactWithExtensionsFixture([new PatientContactOnlyExtensionFixture()]);
+        $resource = new PatientWithContactResourceFixture(contact: [$contact]);
+
+        $report = $this->service->validate($resource);
+
+        self::assertCount(0, $report->errors(), 'Extension permitted on Patient.contact must produce no violation');
+    }
+
+    public function testNestedExtensionWithBareResourceTypeContextIsDeferredProducesNoViolation(): void
+    {
+        // PatientPermittedExtensionFixture context is "Patient" (no dot).
+        // Bare-type contexts at sub-element level are deferred (require type-hierarchy resolution).
+        $contact  = new NestedContactWithExtensionsFixture([new PatientPermittedExtensionFixture()]);
+        $resource = new PatientWithContactResourceFixture(contact: [$contact]);
+
+        $report = $this->service->validate($resource);
+
+        self::assertCount(0, $report->errors(), 'Bare resource-type contexts at sub-element level must be deferred');
+    }
+
+    public function testMultipleContactsOnlyForbiddenOneProducesOneErrorWithCorrectIndex(): void
+    {
+        $permitted = new NestedContactWithExtensionsFixture([new PatientContactOnlyExtensionFixture()]);
+        $forbidden = new NestedContactWithExtensionsFixture([new PatientNameOnlyExtensionFixture()]);
+        $resource  = new PatientWithContactResourceFixture(contact: [$permitted, $forbidden]);
+
+        $report = $this->service->validate($resource);
+
+        self::assertCount(1, $report->errors());
+        self::assertSame('contact[1].extension', $report->errors()[0]->path);
+    }
+
+    public function testResourceWithEmptyContactArrayProducesNoViolations(): void
+    {
+        $resource = new PatientWithContactResourceFixture();
+
+        $report = $this->service->validate($resource);
+
+        self::assertCount(0, $report->errors());
+    }
+}

src/Component/Validation/tests/Unit/Fixture/NestedContactWithExtensionsFixture.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ardenexal\FHIRTools\Component\Validation\Tests\Unit\Fixture;
+
+use Ardenexal\FHIRTools\Component\Metadata\Contract\FHIRExtensionInterface;
+use Ardenexal\FHIRTools\Component\Metadata\Traits\FHIRExtensionsTrait;
+
+final class NestedContactWithExtensionsFixture
+{
+    use FHIRExtensionsTrait;
+
+    /** @param list<FHIRExtensionInterface> $extension */
+    public function __construct(
+        private readonly array $extension = [],
+    ) {
+    }
+}

src/Component/Validation/tests/Unit/Fixture/PatientContactOnlyExtensionFixture.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ardenexal\FHIRTools\Component\Validation\Tests\Unit\Fixture;
+
+use Ardenexal\FHIRTools\Component\Metadata\Attribute\Validation\FHIRExtensionContext;
+use Ardenexal\FHIRTools\Component\Metadata\Contract\FHIRExtensionInterface;
+
+#[FHIRExtensionContext(type: 'element', expression: 'Patient.contact')]
+final class PatientContactOnlyExtensionFixture implements FHIRExtensionInterface
+{
+    public function getExtensionUrl(): ?string
+    {
+        return 'http://example.org/ext/patient-contact-only';
+    }
+}

src/Component/Validation/tests/Unit/Fixture/PatientNameOnlyExtensionFixture.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ardenexal\FHIRTools\Component\Validation\Tests\Unit\Fixture;
+
+use Ardenexal\FHIRTools\Component\Metadata\Attribute\Validation\FHIRExtensionContext;
+use Ardenexal\FHIRTools\Component\Metadata\Contract\FHIRExtensionInterface;
+
+#[FHIRExtensionContext(type: 'element', expression: 'Patient.name')]
+final class PatientNameOnlyExtensionFixture implements FHIRExtensionInterface
+{
+    public function getExtensionUrl(): ?string
+    {
+        return 'http://example.org/ext/patient-name-only';
+    }
+}

src/Component/Validation/tests/Unit/Fixture/PatientWithContactResourceFixture.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ardenexal\FHIRTools\Component\Validation\Tests\Unit\Fixture;
+
+use Ardenexal\FHIRTools\Component\Metadata\Attribute\FhirResource;
+use Ardenexal\FHIRTools\Component\Metadata\Contract\FHIRExtensionInterface;
+use Ardenexal\FHIRTools\Component\Metadata\Traits\FHIRExtensionsTrait;
+
+#[FhirResource(type: 'Patient', version: '4.0.1', url: 'http://hl7.org/fhir/StructureDefinition/Patient', fhirVersion: 'R4')]
+final class PatientWithContactResourceFixture
+{
+    use FHIRExtensionsTrait;
+
+    /**
+     * @param list<object>                 $contact
+     * @param list<FHIRExtensionInterface> $extension
+     */
+    public function __construct(
+        public readonly array $contact = [],
+        private readonly array $extension = [],
+    ) {
+    }
+}