Introduced support for resolving orphaned relationships

When doing an import, an issue can occur where `topic.Relationships` and `topic.DerivedTopic`s point to new topics that haven't yet been `Import()`ed as part of the tree traversal and, therefore, cannot be resolved. Traditionally, this has required calling `Import()` a _second_ time to ensure that these are resolved.

This shouldn't be necessary. This commit introduces internal handling of this scenario as part of `Import()` by creating a cache of unresolved relationships which is then evaluated after the initial `Import()` is complete. This ensures that any relationships that were initially missed due to the topics being `Import()`ed later are resolved. This should address the majority of scenarios.

It's worth noting that there are two scenarios where this will still fail. First, if the relationship is outside of the `ExportOptions.ExportScope` and the target relationship doesn't already exist in the target repository. Second, if the relationship is an implicit topic pointer (i.e., an attribute ending with `Id`), since that necessitates that the target topic be saved in order to persist the relationship as a meaningful attribute value.

The latter scenario still mandates the `Import()` be called twice. But as this must happen _after_ it has been `Save()`d, it's not practical for us to handle that scenario internally. As such, when importing topic graphs that (might) contain implicit topic pointers, callers will still need to call:

1. `Import()` (to establish the topic graph)
2. `Save()` (to populate `topic.Id`s)
3. `Import()` (to resolve implicit topic pointers to newly imported topics)
4. `Save()` (to save those newly resolved topic pointers)

That remains an unfortunate necessity, but at least this won't be necessary for explicit topic pointers in the form of relationships and `DerivedTopic`s.

Finally, this will mitigate an issue where attribute deriving from later attribute references (e.g., in `Root:Configuration:Attributes`) might be saved in the wrong location due to an unresolved inheritance of `StoreInBlob`, and then immediately moved on the second `Save()`. Since that `DerivedTopic` will not be resolved during the initial `Import()`, it will have immediate access to the inherited `StoreInBlob` value. This occurred, notably, with the `Title` attribute when importing the reference configuration.

This includes a unit test to validate this functionality.

Author: JeremyCaney

OnTopic.Data.Transfer.Tests/TopicExtensionsTest.cs

@@ -332,6 +332,41 @@ public void Import_DerivedTopicKey_MapsDerivedTopic() {
 
     }
 
+    /*==========================================================================================================================
+    | TEST: IMPORT: DERIVED TOPIC KEY: MAPS NEWLY DERIVED TOPIC
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Creates a <see cref="TopicData"/> with a <see cref="TopicData.DerivedTopicKey"/> that points to a newly imported
+    ///   topic that is later in the tree traversal, and ensures that the <see cref="Topic.DerivedTopic"/> is set correctly.
+    /// </summary>
+    [TestMethod]
+    public void Import_DerivedTopicKey_MapsNewlyDerivedTopic() {
+
+      var rootTopic             = TopicFactory.Create("Root", "Container");
+      var topic                 = TopicFactory.Create("Test", "Container", rootTopic);
+
+      var topicData             = new TopicData() {
+        Key                     = topic.Key,
+        UniqueKey               = topic.GetUniqueKey(),
+        ContentType             = topic.ContentType,
+        DerivedTopicKey         = "Root:Test:Child"
+      };
+
+      var childTopicData        = new TopicData() {
+        Key                     = "Child",
+        UniqueKey               = $"{topicData.UniqueKey}:Child",
+        ContentType             = "Container"
+      };
+
+      topicData.Children.Add(childTopicData);
+
+      topic.Import(topicData);
+
+      Assert.IsNotNull(topic.DerivedTopic);
+      Assert.AreEqual<string>(childTopicData.Key, topic.DerivedTopic?.Key);
+
+    }
+
     /*==========================================================================================================================
     | TEST: IMPORT: INVALID DERIVED TOPIC KEY: MAINTAINS EXISTING VALUE
     \-------------------------------------------------------------------------------------------------------------------------*/

OnTopic.Data.Transfer/Interchange/TopicExtensions.cs

@@ -4,11 +4,13 @@
 | Project       Topics Library
 \=============================================================================================================================*/
 using System;
+using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Globalization;
 using System.Linq;
 using OnTopic.Attributes;
 using OnTopic.Internal.Diagnostics;
+using OnTopic.Mapping.Annotations;
 using OnTopic.Querying;
 
 namespace OnTopic.Data.Transfer.Interchange {
@@ -161,6 +163,72 @@ public static TopicData Export(this Topic topic, [NotNull]ExportOptions? options
     /// <param name="options">An optional <see cref="ImportOptions"/> object to specify import settings.</param>
     public static void Import(this Topic topic, TopicData topicData, [NotNull]ImportOptions? options = null) {
 
+      /*------------------------------------------------------------------------------------------------------------------------
+      | Establish cache
+      \-----------------------------------------------------------------------------------------------------------------------*/
+      var unresolvedRelationships = new List<Tuple<Topic, string, string>>();
+
+      /*------------------------------------------------------------------------------------------------------------------------
+      | Handle first pass
+      \-----------------------------------------------------------------------------------------------------------------------*/
+      topic.Import(topicData, options, unresolvedRelationships);
+
+      /*------------------------------------------------------------------------------------------------------------------------
+      | Attempt to resolve outstanding relationships
+      \-----------------------------------------------------------------------------------------------------------------------*/
+      foreach (var relationship in unresolvedRelationships) {
+
+        //Attempt to find the target relationship
+        var source              = relationship.Item1;
+        var target              = topic.GetByUniqueKey(relationship.Item3);
+        var key                 = relationship.Item2;
+
+        //If the relationship STILL can't be resolved, skip it
+        if (target == null) {
+          continue;
+        }
+
+        //Wire up derived topics
+        if (key.Equals("DerivedTopic")) {
+          source.DerivedTopic = target;
+        }
+
+        //Wire up relationships
+        else {
+          source.Relationships.SetTopic(key, target);
+        }
+
+      }
+
+    }
+
+    /// <summary>
+    ///   Imports a <see cref="TopicData"/> data transfer object—and, potentially, its descendants—into an existing <see
+    ///   cref="Topic"/> entity. Track unmatched relationships.
+    /// </summary>
+    /// <remarks>
+    ///   <para>
+    ///     While traversing a topic graph with many new topics, scenarios emerge where the topic graph cannot be fully
+    ///     reconstructed since the relationships and derived topics may refer to new topics that haven't yet been imported. To
+    ///     mitigate that, this overload accepts and populates a cache of such relationships, so that they can be recreated
+    ///     afterwards.
+    ///   </para>
+    ///   <para>
+    ///     This does <i>not</i> address the scenario where implicit topic pointers (i.e., attributes ending in <c>Id</c>)
+    ///     cannot be resolved because the target topics haven't yet been saved—and, therefore, the <see
+    ///     cref="Topic.GetUniqueKey"/> cannot be translated to a <see cref="Topic.Id"/>. There isn't any obvious way to address
+    ///     this via <see cref="Import"/> directly.
+    ///   </para>
+    /// </remarks>
+    /// <param name="topic">The source <see cref="Topic"/> to operate off of.</param>
+    /// <param name="options">An optional <see cref="ImportOptions"/> object to specify import settings.</param>
+    private static void Import(
+      this Topic topic,
+      TopicData topicData,
+      [NotNull]ImportOptions? options,
+      List<Tuple<Topic, string, string>> unresolvedRelationships
+    ) {
+
       /*------------------------------------------------------------------------------------------------------------------------
       | Validate topic
       \-----------------------------------------------------------------------------------------------------------------------*/
@@ -194,7 +262,13 @@ public static void Import(this Topic topic, TopicData topicData, [NotNull]Import
       }
 
       if (topicData.DerivedTopicKey?.Length > 0) {
-        topic.DerivedTopic      = topic.GetByUniqueKey(topicData.DerivedTopicKey)?? topic.DerivedTopic;
+        var target = topic.GetByUniqueKey(topicData.DerivedTopicKey);
+        if (target != null) {
+          topic.DerivedTopic = target;
+        }
+        else {
+          unresolvedRelationships.Add(new Tuple<Topic, string, string>(topic, "DerivedTopic", topicData.DerivedTopicKey));
+        }
       }
 
       /*------------------------------------------------------------------------------------------------------------------------
@@ -272,7 +346,10 @@ public static void Import(this Topic topic, TopicData topicData, [NotNull]Import
           var relatedTopic = topic.GetByUniqueKey(relatedTopicKey);
           if (relationship.Key != null && relatedTopic != null) {
             topic.Relationships.SetTopic(relationship.Key, relatedTopic);
-          };
+          }
+          else {
+            unresolvedRelationships.Add(new Tuple<Topic, string, string>(topic, relationship.Key!, relatedTopicKey));
+          }
         }
       }