fix: add circular import detection and duplicate key validation

Detect circular YAML imports via a visited-path set to prevent stack
overflow. Validate yamlKeyMap values are unique in ModuleConfigDescriptor
to catch silent data loss from array_flip. Fix CLAUDE.md PHPStan level
to match phpstan.neon (10, not 8).

Author: kojiromike

CLAUDE.md

@@ -9,7 +9,7 @@ Shared configuration accessor library for OpenCoreEMR modules (`oce-module-*`).
 | Composer name | `opencoreemr/oce-lib-module-config` |
 | PHP | >= 8.2, `declare(strict_types=1)` everywhere |
 | Style | PSR-12 |
-| PHPStan | Level 8 |
+| PHPStan | Level 10 |
 
 ## Architecture
 

src/ModuleConfigDescriptor.php

@@ -43,6 +43,12 @@ public function __construct(
         public string $configFileEnvVar,
         public string $secretsFileEnvVar,
     ) {
-        $this->reverseKeyMap = array_flip($yamlKeyMap);
+        $reversed = array_flip($yamlKeyMap);
+        if (count($reversed) !== count($yamlKeyMap)) {
+            throw new \InvalidArgumentException(
+                'yamlKeyMap values must be unique — multiple YAML keys map to the same internal config key'
+            );
+        }
+        $this->reverseKeyMap = $reversed;
     }
 }

src/YamlConfigLoader.php

@@ -51,8 +51,9 @@ public function __construct(private readonly ?SecretProviderInterface $secretPro
     public function load(array $filePaths): array
     {
         $merged = [];
+        $visited = [];
         foreach ($filePaths as $filePath) {
-            $fileData = $this->loadFile($filePath);
+            $fileData = $this->loadFile($filePath, $visited);
             $merged = array_merge($merged, $fileData);
         }
 
@@ -168,17 +169,30 @@ private function getSecretProvider(string $provider): SecretProviderInterface
     /**
      * Load a single YAML file, processing any imports
      *
+     * @param array<string, true> $visited Real paths already loaded (cycle detection)
      * @return array<string, mixed>
-     * @throws ConfigurationException if file is not readable or contains invalid YAML
+     * @throws ConfigurationException if file is not readable, contains invalid YAML, or creates an import cycle
      */
-    private function loadFile(string $filePath): array
+    private function loadFile(string $filePath, array &$visited = []): array
     {
         if (!is_readable($filePath)) {
             throw new ConfigurationException(
                 sprintf('Configuration file is not readable: %s', $filePath)
             );
         }
 
+        $realPath = realpath($filePath);
+        if ($realPath === false) {
+            $realPath = $filePath;
+        }
+
+        if (isset($visited[$realPath])) {
+            throw new ConfigurationException(
+                sprintf('Circular import detected: %s', $filePath)
+            );
+        }
+        $visited[$realPath] = true;
+
         $contents = file_get_contents($filePath);
         if ($contents === false) {
             throw new ConfigurationException(
@@ -216,7 +230,7 @@ private function loadFile(string $filePath): array
                     continue;
                 }
                 $importPath = $baseDir . DIRECTORY_SEPARATOR . $resource;
-                $importedData = array_merge($importedData, $this->loadFile($importPath));
+                $importedData = array_merge($importedData, $this->loadFile($importPath, $visited));
             }
             unset($data['imports']);
         }

tests/Unit/ModuleConfigDescriptorTest.php

@@ -25,6 +25,22 @@ public function testReverseKeyMapIsDerivedFromYamlKeyMap(): void
         $this->assertSame('other', $descriptor->reverseKeyMap['internal_other']);
     }
 
+    public function testThrowsOnDuplicateYamlKeyMapValues(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('yamlKeyMap values must be unique');
+
+        new ModuleConfigDescriptor(
+            yamlKeyMap: ['key_a' => 'same_internal', 'key_b' => 'same_internal'],
+            envOverrideMap: ['same_internal' => 'ENV_VAR'],
+            envConfigVar: 'ENV_CONFIG',
+            conventionalConfigPath: '/etc/config.yaml',
+            conventionalSecretsPath: '/etc/secrets.yaml',
+            configFileEnvVar: 'CONFIG_FILE',
+            secretsFileEnvVar: 'SECRETS_FILE',
+        );
+    }
+
     public function testAllPropertiesAreAccessible(): void
     {
         $descriptor = TestDescriptor::create();

tests/Unit/YamlConfigLoaderTest.php

@@ -188,6 +188,30 @@ public function testLoadThrowsOnMalformedYaml(): void
         $loader->load([$path]);
     }
 
+    public function testLoadThrowsOnCircularImport(): void
+    {
+        $loader = new YamlConfigLoader();
+        $this->writeYaml('a.yaml', "imports:\n  - { resource: b.yaml }\nfrom_a: true\n");
+        $this->writeYaml('b.yaml', "imports:\n  - { resource: a.yaml }\nfrom_b: true\n");
+        $aPath = $this->tmpDir . '/a.yaml';
+
+        $this->expectException(ConfigurationException::class);
+        $this->expectExceptionMessage('Circular import detected');
+
+        $loader->load([$aPath]);
+    }
+
+    public function testLoadThrowsOnSelfImport(): void
+    {
+        $loader = new YamlConfigLoader();
+        $path = $this->writeYaml('self.yaml', "imports:\n  - { resource: self.yaml }\nkey: val\n");
+
+        $this->expectException(ConfigurationException::class);
+        $this->expectExceptionMessage('Circular import detected');
+
+        $loader->load([$path]);
+    }
+
     public function testLoadThrowsOnNonMappingYaml(): void
     {
         $loader = new YamlConfigLoader();