Address PR review feedback: add tests, validation, and docs improvements

Co-authored-by: PhenX <42170+PhenX@users.noreply.github.com>

Author: Copilot

docs/graph-insert.md

@@ -131,4 +131,7 @@ await dbContext.ExecuteBulkInsertAsync(new[] { blog }, o =>
 
 - **Shadow foreign keys**: Currently not supported. Add a CLR property for foreign keys.
 - **Circular references**: Handled gracefully by tracking visited entities, but may result in incomplete graphs.
+- **Owned entities**: Owned entity types are not included in graph traversal and are not inserted when using `IncludeGraph = true`.
+- **Self-referencing hierarchies**: Multi-level self-referencing hierarchies (e.g., Category → Children) require multiple insert operations. Root entities can be inserted, but nested children with FK references to other entities of the same type within the same batch are not supported.
+- **Many-to-many join tables**: Entities on both sides of many-to-many relationships are traversed and inserted. However, automatic join table population only works with explicit join entity types (not `Dictionary<string, object>` shared-type entities).
 - **OnConflict/Upsert**: Not currently supported with `IncludeGraph = true`.

src/PhenX.EntityFrameworkCore.BulkInsert/Extensions/PublicExtensions.DbSet.cs

@@ -160,6 +160,13 @@ public static async Task ExecuteBulkInsertAsync<T, TOptions>(
 
         if (options.IncludeGraph)
         {
+            if (onConflict != null)
+            {
+                throw new InvalidOperationException(
+                    "OnConflict options cannot be used together with IncludeGraph. " +
+                    "Either disable IncludeGraph or remove the onConflict parameter.");
+            }
+
             var orchestrator = new GraphBulkInsertOrchestrator();
             await orchestrator.InsertGraphAsync(context, entities, options, provider, cancellationToken);
             return;
@@ -214,6 +221,13 @@ public static void ExecuteBulkInsert<T, TOptions>(
 
         if (options.IncludeGraph)
         {
+            if (onConflict != null)
+            {
+                throw new InvalidOperationException(
+                    "OnConflict options cannot be used together with IncludeGraph. " +
+                    "Either disable IncludeGraph or remove the onConflict parameter.");
+            }
+
             var orchestrator = new GraphBulkInsertOrchestrator();
             orchestrator.InsertGraphAsync(context, entities, options, provider, CancellationToken.None)
                 .GetAwaiter().GetResult();

src/PhenX.EntityFrameworkCore.BulkInsert/Graph/GraphBulkInsertOrchestrator.cs

@@ -121,7 +121,6 @@ private static void PropagateParentForeignKeys(
         // For each FK relationship, propagate PK values from parent entities
         foreach (var fk in efEntityType.GetForeignKeys())
         {
-            var principalEntityType = fk.PrincipalEntityType;
             var dependentNavigation = fk.DependentToPrincipal;
 
             if (dependentNavigation == null)
@@ -300,14 +299,24 @@ private async Task InsertJoinRecordsAsync(
                     continue;
                 }
 
+                // Check if the join entity is a dictionary (shared-type entity)
+                var isDictionary = joinEntry is IDictionary<string, object>;
+
                 // Set FK values for left entity
                 for (var i = 0; i < fk.Properties.Count; i++)
                 {
                     var fkProp = fk.Properties[i];
                     var pkProp = fk.PrincipalKey.Properties[i];
 
                     var pkValue = GetPropertyValue(record.LeftEntity, pkProp.Name);
-                    SetPropertyValue(joinEntry, fkProp.Name, pkValue);
+                    if (isDictionary)
+                    {
+                        ((IDictionary<string, object>)joinEntry)[fkProp.Name] = pkValue!;
+                    }
+                    else
+                    {
+                        SetPropertyValue(joinEntry, fkProp.Name, pkValue);
+                    }
                 }
 
                 // Set FK values for right entity
@@ -317,7 +326,14 @@ private async Task InsertJoinRecordsAsync(
                     var pkProp = inverseFk.PrincipalKey.Properties[i];
 
                     var pkValue = GetPropertyValue(record.RightEntity, pkProp.Name);
-                    SetPropertyValue(joinEntry, fkProp.Name, pkValue);
+                    if (isDictionary)
+                    {
+                        ((IDictionary<string, object>)joinEntry)[fkProp.Name] = pkValue!;
+                    }
+                    else
+                    {
+                        SetPropertyValue(joinEntry, fkProp.Name, pkValue);
+                    }
                 }
 
                 joinEntities.Add(joinEntry);
@@ -353,7 +369,12 @@ private async Task InsertJoinEntitiesAsync(
             .GetMethod(nameof(IBulkInsertProvider.BulkInsert))!
             .MakeGenericMethod(joinEntityType);
 
-        var task = (Task)method.Invoke(provider, [false, context, tableInfo, joinEntities, options, null, ctk])!;
+        var result = method.Invoke(provider, [false, context, tableInfo, joinEntities, options, null, ctk]);
+        if (result is not Task task)
+        {
+            throw new InvalidOperationException(
+                $"The BulkInsert method for join entity type '{joinEntityType.Name}' did not return a Task as expected.");
+        }
         await task;
     }
 

src/PhenX.EntityFrameworkCore.BulkInsert/Metadata/GraphMetadata.cs

@@ -100,13 +100,9 @@ private void TopologicalSort(
 
         // Get dependencies (types that this type references via FKs)
         var navigations = GetNavigations(type);
-        foreach (var nav in navigations)
+        foreach (var nav in navigations.Where(n => n.IsDependentToPrincipal && validTypes.Contains(n.TargetType) && n.TargetType != type))
         {
-            // Only consider dependent-to-principal navigations (this entity has the FK)
-            if (nav.IsDependentToPrincipal && validTypes.Contains(nav.TargetType) && nav.TargetType != type)
-            {
-                TopologicalSort(nav.TargetType, validTypes, visited, visiting, result);
-            }
+            TopologicalSort(nav.TargetType, validTypes, visited, visiting, result);
         }
 
         visiting.Remove(type);

tests/PhenX.EntityFrameworkCore.BulkInsert.Tests/Tests/Graph/GraphTestsBase.cs

@@ -359,4 +359,79 @@ public async Task InsertGraph_SyncVariant_Works()
         var insertedPosts = _context.Posts.Where(p => p.TestRun == _run).ToList();
         insertedPosts.Should().HaveCount(1);
     }
+
+    [SkippableFact]
+    public async Task InsertGraph_SelfReferencing_InsertsRootOnly()
+    {
+        // Arrange - Self-referencing hierarchies require multiple inserts in order
+        // This test verifies that root entities without parents can be inserted
+        var rootCategory = new Category
+        {
+            TestRun = _run,
+            Name = $"{_run}_RootCategory",
+            Parent = null,
+            ParentId = null
+        };
+
+        // Act
+        await _context.ExecuteBulkInsertAsync(new[] { rootCategory }, options =>
+        {
+            options.IncludeGraph = true;
+        });
+
+        // Assert
+        var insertedCategories = _context.Categories.Where(c => c.TestRun == _run).ToList();
+        insertedCategories.Should().HaveCount(1);
+
+        var insertedRoot = insertedCategories.First();
+        insertedRoot.Id.Should().BeGreaterThan(0);
+        insertedRoot.ParentId.Should().BeNull();
+    }
+
+    [SkippableFact]
+    public async Task InsertGraph_ManyToMany_TraversesRelatedEntities()
+    {
+        // Note: Many-to-many join table insertion requires explicit join entity types.
+        // Dictionary<string, object> join entities are not supported by the bulk insert infrastructure.
+        // This test verifies that many-to-many navigations are traversed and related entities are collected.
+
+        // Arrange - Create a post with tags
+        var tag1 = new Tag { TestRun = _run, Name = $"{_run}_Tag1" };
+        var tag2 = new Tag { TestRun = _run, Name = $"{_run}_Tag2" };
+
+        var blog = new Blog
+        {
+            TestRun = _run,
+            Name = $"{_run}_BlogWithTaggedPost",
+            Posts = new List<Post>
+            {
+                new Post
+                {
+                    TestRun = _run,
+                    Title = $"{_run}_TaggedPost",
+                    Tags = new List<Tag> { tag1, tag2 }
+                }
+            }
+        };
+
+        // Act
+        await _context.ExecuteBulkInsertAsync(new[] { blog }, options =>
+        {
+            options.IncludeGraph = true;
+        });
+
+        // Assert - Verify the entities were inserted (even if join table wasn't populated)
+        var insertedBlog = _context.Blogs.FirstOrDefault(b => b.TestRun == _run);
+        insertedBlog.Should().NotBeNull();
+        insertedBlog!.Id.Should().BeGreaterThan(0);
+
+        var insertedPost = _context.Posts.FirstOrDefault(p => p.TestRun == _run);
+        insertedPost.Should().NotBeNull();
+        insertedPost!.Id.Should().BeGreaterThan(0);
+
+        // Tags should be inserted as they were traversed via many-to-many navigation
+        var insertedTags = _context.Tags.Where(t => t.TestRun == _run).ToList();
+        insertedTags.Should().HaveCount(2);
+        insertedTags.Should().AllSatisfy(t => t.Id.Should().BeGreaterThan(0));
+    }
 }