TASK: refactor API for findNodeAggregates

I forgot to change this after discussing in #4093
so this is the cleanup commit.

Author: skurfuerst

Neos.ContentGraph.DoctrineDbalAdapter/src/Domain/Repository/ContentGraph.php

@@ -121,10 +121,28 @@ public function findRootNodeAggregateByType(
         ContentStreamId $contentStreamId,
         NodeTypeName $nodeTypeName
     ): NodeAggregate {
-        return $this->findRootNodeAggregates(
+        $rootNodeAggregates = $this->findRootNodeAggregates(
             $contentStreamId,
             FindRootNodeAggregatesFilter::nodeTypeName($nodeTypeName)
-        )->first();
+        );
+
+        if ($rootNodeAggregates->count() === 0) {
+            throw new \RuntimeException('Root Node Aggregate not found');
+        }
+
+        if ($rootNodeAggregates->count() > 1) {
+            $ids = [];
+            foreach ($rootNodeAggregates as $rootNodeAggregate) {
+                $ids[] = $rootNodeAggregate->nodeAggregateId->value;
+            }
+            throw new \RuntimeException(sprintf(
+                'More than one root node aggregate of type "%s" found (IDs: %s).',
+                $nodeTypeName->value,
+                implode(', ', $ids)
+            ));
+        }
+
+        return $rootNodeAggregates->first();
     }
 
     public function findRootNodeAggregates(

Neos.ContentGraph.PostgreSQLAdapter/src/Domain/Repository/ContentHypergraph.php

@@ -108,10 +108,28 @@ public function findRootNodeAggregateByType(
         ContentStreamId $contentStreamId,
         NodeTypeName $nodeTypeName
     ): NodeAggregate {
-        return $this->findRootNodeAggregates(
+        $rootNodeAggregates = $this->findRootNodeAggregates(
             $contentStreamId,
             FindRootNodeAggregatesFilter::nodeTypeName($nodeTypeName)
-        )->first();
+        );
+
+        if ($rootNodeAggregates->count() === 0) {
+            throw new \RuntimeException('Root Node Aggregate not found');
+        }
+
+        if ($rootNodeAggregates->count() > 1) {
+            $ids = [];
+            foreach ($rootNodeAggregates as $rootNodeAggregate) {
+                $ids[] = $rootNodeAggregate->nodeAggregateId->value;
+            }
+            throw new \RuntimeException(sprintf(
+                'More than one root node aggregate of type "%s" found (IDs: %s).',
+                $nodeTypeName->value,
+                implode(', ', $ids)
+            ));
+        }
+
+        return $rootNodeAggregates->first();
     }
 
     public function findRootNodeAggregates(

Neos.ContentRepository.Core/Classes/Projection/ContentGraph/ContentGraphInterface.php

@@ -46,8 +46,9 @@ public function getSubgraph(
     ): ContentSubgraphInterface;
 
     /**
-     * @deprecated please use {@see findRootNodeAggregates} instead
-     * @internal
+     * @api
+     * Throws exception if no root aggregate found, because a Content Repository needs at least
+     * one root node to function.
      */
     public function findRootNodeAggregateByType(
         ContentStreamId $contentStreamId,

Neos.ContentRepository.Core/Classes/Projection/ContentGraph/NodeAggregates.php

@@ -74,17 +74,14 @@ public function count(): int
     }
 
     /**
-     * Throws exception if no root aggregate found, because a Content Repository needs at least
-     * one root node to function.
-     *
-     * @return NodeAggregate
+     * @return NodeAggregate|null
      */
-    public function first(): NodeAggregate
+    public function first(): ?NodeAggregate
     {
         if (count($this->nodeAggregates) > 0) {
             $array = $this->nodeAggregates;
             return reset($array);
         }
-        throw new \RuntimeException('Root Node Aggregate not found');
+        return null;
     }
 }