Enhance behaviour of duplicating storedObject to keep only the last "kept before conversion" version if any

Enhance the duplication service to selectively handle versions tagged with "KEEP_BEFORE_CONVERSION". Modify StoredObject to support retrieval and checking of such versions. Add relevant test cases to validate this behavior.

src/Bundle/ChillDocStoreBundle/Entity/StoredObject.php

@@ -18,6 +18,8 @@ use Chill\MainBundle\Doctrine\Model\TrackCreationInterface;
 use Chill\MainBundle\Doctrine\Model\TrackCreationTrait;
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\Common\Collections\Collection;
+use Doctrine\Common\Collections\Order;
+use Doctrine\Common\Collections\ReadableCollection;
 use Doctrine\Common\Collections\Selectable;
 use Doctrine\ORM\Mapping as ORM;
 use Ramsey\Uuid\Uuid;
@@ -257,11 +259,33 @@ class StoredObject implements Document, TrackCreationInterface
         return $this->template;
     }
 
+    /**
+     * @return Selectable<int, StoredObjectVersion>&Collection<int, StoredObjectVersion>
+     */
     public function getVersions(): Collection&Selectable
     {
         return $this->versions;
     }
 
+    /**
+     * Retrieves versions sorted by a given order.
+     *
+     * @param 'ASC'|'DESC' $order the sorting order, default is Order::Ascending
+     *
+     * @return readableCollection&Selectable The ordered collection of versions
+     */
+    public function getVersionsOrdered(string $order = 'ASC'): ReadableCollection&Selectable
+    {
+        $versions = $this->getVersions()->toArray();
+
+        match ($order) {
+            'ASC' => usort($versions, static fn (StoredObjectVersion $a, StoredObjectVersion $b) => $a->getVersion() <=> $b->getVersion()),
+            'DESC' => usort($versions, static fn (StoredObjectVersion $a, StoredObjectVersion $b) => $b->getVersion() <=> $a->getVersion()),
+        };
+
+        return new ArrayCollection($versions);
+    }
+
     public function hasCurrentVersion(): bool
     {
         return null !== $this->getCurrentVersion();
@@ -272,6 +296,47 @@ class StoredObject implements Document, TrackCreationInterface
         return null !== $this->template;
     }
 
+    /**
+     * Checks if there is a version kept before conversion.
+     *
+     * @return bool true if a version is kept before conversion, false otherwise
+     */
+    public function hasKeptBeforeConversionVersion(): bool
+    {
+        foreach ($this->getVersions() as $version) {
+            foreach ($version->getPointInTimes() as $pointInTime) {
+                if (StoredObjectPointInTimeReasonEnum::KEEP_BEFORE_CONVERSION === $pointInTime->getReason()) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Retrieves the last version of the stored object that was kept before conversion.
+     *
+     * This method iterates through the ordered versions and their respective points
+     * in time to find the most recent version that has a point in time with the reason
+     * 'KEEP_BEFORE_CONVERSION'.
+     *
+     * @return StoredObjectVersion|null the version that was kept before conversion,
+     *                                  or null if not found
+     */
+    public function getLastKeptBeforeConversionVersion(): ?StoredObjectVersion
+    {
+        foreach ($this->getVersionsOrdered('DESC') as $version) {
+            foreach ($version->getPointInTimes() as $pointInTime) {
+                if (StoredObjectPointInTimeReasonEnum::KEEP_BEFORE_CONVERSION === $pointInTime->getReason()) {
+                    return $version;
+                }
+            }
+        }
+
+        return null;
+    }
+
     public function setTemplate(?DocGeneratorTemplate $template): StoredObject
     {
         $this->template = $template;