chore: Fix internal exception on TOC loading

Author: filzrev

src/Docfx.Build/TableOfContents/TocHelper.cs

@@ -2,19 +2,17 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System.Collections.Immutable;
-
 using Docfx.Common;
 using Docfx.DataContracts.Common;
 using Docfx.Plugins;
+using YamlDotNet.Core;
+using YamlDotNet.Core.Events;
+using Constants = Docfx.DataContracts.Common.Constants;
 
 namespace Docfx.Build.TableOfContents;
 
 public static class TocHelper
 {
-    private static readonly YamlDeserializerWithFallback _deserializer =
-        YamlDeserializerWithFallback.Create<List<TocItemViewModel>>()
-        .WithFallback<TocItemViewModel>();
-
     internal static List<FileModel> ResolveToc(ImmutableList<FileModel> models)
     {
         var tocCache = new Dictionary<string, TocItemInfo>(FilePathComparer.OSPlatformSensitiveStringComparer);
@@ -56,21 +54,20 @@ public static TocItemViewModel LoadSingleToc(string file)
         var fileType = Utility.GetTocFileType(file);
         try
         {
-            if (fileType == TocFileType.Markdown)
-            {
-                return new()
-                {
-                    Items = MarkdownTocReader.LoadToc(EnvironmentContext.FileAbstractLayer.ReadAllText(file), file)
-                };
-            }
-            else if (fileType == TocFileType.Yaml)
+            switch (fileType)
             {
-                return _deserializer.Deserialize(file) switch
-                {
-                    List<TocItemViewModel> vm => new() { Items = vm },
-                    TocItemViewModel root => root,
-                    _ => throw new NotSupportedException($"{file} is not a valid TOC file."),
-                };
+                case TocFileType.Markdown:
+                    return new()
+                    {
+                        Items = MarkdownTocReader.LoadToc(EnvironmentContext.FileAbstractLayer.ReadAllText(file), file)
+                    };
+                case TocFileType.Yaml:
+                    {
+                        var yaml = EnvironmentContext.FileAbstractLayer.ReadAllText(file);
+                        return DeserializeYamlToc(yaml);
+                    }
+                default:
+                    throw new NotSupportedException($"{file} is not a valid TOC file, supported TOC files should be either \"{Constants.TableOfContents.MarkdownTocFileName}\" or \"{Constants.TableOfContents.YamlTocFileName}\".");
             }
         }
         catch (Exception e)
@@ -79,7 +76,18 @@ public static TocItemViewModel LoadSingleToc(string file)
             Logger.LogError(message, code: ErrorCodes.Toc.InvalidTocFile);
             throw new DocumentException(message, e);
         }
+    }
+
+    private static TocItemViewModel DeserializeYamlToc(string yaml)
+    {
+        // Parse yaml content to determine TOC type (`List<TocItemViewModel>` or TocItemViewModel).
+        var parser = new Parser(new Scanner(new StringReader(yaml), skipComments: true));
+        bool isListItems = parser.TryConsume<StreamStart>(out var _)
+                        && parser.TryConsume<DocumentStart>(out var _)
+                        && parser.TryConsume<SequenceStart>(out var _);
 
-        throw new NotSupportedException($"{file} is not a valid TOC file, supported TOC files should be either \"{Constants.TableOfContents.MarkdownTocFileName}\" or \"{Constants.TableOfContents.YamlTocFileName}\".");
+        return isListItems
+            ? new TocItemViewModel { Items = YamlUtility.Deserialize<List<TocItemViewModel>>(new StringReader(yaml)) }
+            : YamlUtility.Deserialize<TocItemViewModel>(new StringReader(yaml));
     }
 }

src/Docfx.Common/YamlDeserializerWithFallback.cs

@@ -0,0 +1,124 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Text;
+using Docfx.Common;
+using Docfx.DataContracts.Common;
+using FluentAssertions;
+using Xunit;
+
+namespace Docfx.Build.TableOfContents.Tests;
+
+public class TocHelperTest
+{
+    [Fact]
+    public void TestItemDeserialization()
+    {
+        // Arrange
+        var item = new TocItemViewModel
+        {
+            Items =
+            [
+                new TocItemViewModel { Uid = "item1" },
+                new TocItemViewModel { Uid = "item2" }
+            ],
+        };
+
+        var yaml = ToYaml(item);
+        var filePath = Path.Combine(Path.GetTempPath(), "toc.yml");
+        File.WriteAllText(filePath, yaml, new UTF8Encoding(false));
+
+        try
+        {
+            // Act
+            var result = TocHelper.LoadSingleToc(filePath);
+
+            // Assert
+            result.Should().BeEquivalentTo(item);
+        }
+        finally
+        {
+            File.Delete(filePath);
+        }
+    }
+
+    [Fact]
+    public void TestListDeserialization()
+    {
+        // Arrange
+        var items = new TocItemViewModel[]
+        {
+            new TocItemViewModel { Uid = "item1" },
+            new TocItemViewModel { Uid = "item2" },
+        };
+
+        var yaml = ToYaml(items);
+        var filePath = Path.Combine(Path.GetTempPath(), "toc.yml");
+        File.WriteAllText(filePath, yaml);
+
+        try
+        {
+            // Act
+            var result = TocHelper.LoadSingleToc(filePath);
+
+            // Assert
+            result.Uid.Should().BeNull();
+            result.Href.Should().BeNull();
+            result.Items.Should().BeEquivalentTo(items);
+        }
+        finally
+        {
+            File.Delete(filePath);
+        }
+    }
+
+    [Fact]
+    public void TestItemDeserializationWithEncoding()
+    {
+        // Arrange
+        var item = new TocItemViewModel
+        {
+            Items =
+            [
+                new TocItemViewModel { Uid = "item1" },
+                new TocItemViewModel { Uid = "item2" }
+            ],
+        };
+
+        var yaml = ToYaml(item);
+
+        foreach (var encoding in Encodings)
+        {
+            var filePath = Path.Combine(Path.GetTempPath(), "toc.yml");
+            File.WriteAllText(filePath, yaml, encoding);
+
+            try
+            {
+                // Act
+                var result = TocHelper.LoadSingleToc(filePath);
+
+                // Assert
+                result.Should().BeEquivalentTo(item);
+            }
+            finally
+            {
+                File.Delete(filePath);
+            }
+        }
+    }
+
+    private static readonly Encoding[] Encodings =
+    [
+        new UTF8Encoding(false),
+        new UTF8Encoding(true),
+        Encoding.Unicode,
+        Encoding.BigEndianUnicode,
+    ];
+
+    private static string ToYaml<T>(T model)
+    {
+        using StringWriter sw = new StringWriter();
+        YamlUtility.Serialize(sw, model);
+        return sw.ToString();
+    }
+}