test: add comprehensive unit tests for FrontmatterParser, MetaJson, and NavigationGraphBuilder. Validate parsing, handling of edge cases, and document structure resolution.

Author: Shewart

tests/ShellDocs.Tests/FrontmatterParserTests.cs

@@ -0,0 +1,70 @@
+using ShellDocs.Core;
+using Xunit;
+
+namespace ShellDocs.Tests;
+
+public class FrontmatterParserTests
+{
+    [Fact]
+    public void Parse_ExtractsFrontmatterAndBody()
+    {
+        var source = "---\ntitle: Button\ndescription: A clickable thing\norder: 5\n---\n# Button\n\nBody here.";
+
+        var result = FrontmatterParser.Parse(source);
+
+        Assert.Equal("Button", result.Frontmatter.GetValue<string>("title"));
+        Assert.Equal("A clickable thing", result.Frontmatter.GetValue<string>("description"));
+        Assert.Equal(5, result.Frontmatter.GetValue<int>("order"));
+        Assert.Contains("# Button", result.Body);
+        Assert.Contains("Body here.", result.Body);
+    }
+
+    [Fact]
+    public void Parse_HandlesMissingFrontmatter()
+    {
+        var source = "# No Frontmatter\n\nJust markdown.";
+        var result = FrontmatterParser.Parse(source);
+
+        Assert.Empty(result.Frontmatter);
+        Assert.Equal(source, result.Body);
+    }
+
+    [Fact]
+    public void Parse_HandlesEmptyDocument()
+    {
+        var result = FrontmatterParser.Parse("");
+
+        Assert.Empty(result.Frontmatter);
+        Assert.Equal("", result.Body);
+    }
+
+    [Fact]
+    public void Parse_HandlesUnclosedFrontmatter()
+    {
+        var source = "---\ntitle: Broken\n\n# Body";
+        var result = FrontmatterParser.Parse(source);
+
+        Assert.Empty(result.Frontmatter);
+        Assert.Equal(source, result.Body);
+    }
+
+    [Fact]
+    public void Parse_HandlesInvalidYaml()
+    {
+        var source = "---\ntitle: [unclosed\n---\n# Body";
+        var result = FrontmatterParser.Parse(source);
+
+        Assert.Empty(result.Frontmatter);
+        Assert.Contains("# Body", result.Body);
+    }
+
+    [Fact]
+    public void GetValue_CoercesTypes()
+    {
+        var source = "---\nage: 42\n---\n";
+        var result = FrontmatterParser.Parse(source);
+
+        Assert.Equal(42, result.Frontmatter.GetValue<int>("age"));
+        Assert.Equal("42", result.Frontmatter.GetValue<string>("age"));
+    }
+}

tests/ShellDocs.Tests/MetaJsonTests.cs

@@ -0,0 +1,71 @@
+using ShellDocs.Core;
+using Xunit;
+
+namespace ShellDocs.Tests;
+
+public class MetaJsonTests
+{
+    [Fact]
+    public void Parse_HandlesFlatSlugList()
+    {
+        var json = """
+        { "title": "Docs", "pages": ["intro", "installation", "theming"] }
+        """;
+
+        var meta = MetaJson.Parse(json);
+
+        Assert.NotNull(meta);
+        Assert.Equal("Docs", meta!.Title);
+        Assert.Equal(3, meta.Pages.Count);
+        Assert.All(meta.Pages, e => Assert.IsType<MetaJsonPageRef>(e));
+        Assert.Equal("intro", ((MetaJsonPageRef)meta.Pages[0]).Slug);
+    }
+
+    [Fact]
+    public void Parse_RecognizesDivider()
+    {
+        var json = """
+        { "pages": ["a", "---", "b"] }
+        """;
+
+        var meta = MetaJson.Parse(json);
+
+        Assert.NotNull(meta);
+        Assert.IsType<MetaJsonPageRef>(meta!.Pages[0]);
+        Assert.IsType<MetaJsonDivider>(meta.Pages[1]);
+        Assert.IsType<MetaJsonPageRef>(meta.Pages[2]);
+    }
+
+    [Fact]
+    public void Parse_HandlesSubsectionObject()
+    {
+        var json = """
+        {
+          "title": "Components",
+          "pages": [
+            "button",
+            {
+              "title": "Data Display",
+              "pages": ["table", "card"]
+            }
+          ]
+        }
+        """;
+
+        var meta = MetaJson.Parse(json);
+
+        Assert.NotNull(meta);
+        Assert.Equal(2, meta!.Pages.Count);
+        var sub = Assert.IsType<MetaJsonSubsection>(meta.Pages[1]);
+        Assert.Equal("Data Display", sub.Title);
+        Assert.Equal(2, sub.Pages.Count);
+        Assert.All(sub.Pages, e => Assert.IsType<MetaJsonPageRef>(e));
+    }
+
+    [Fact]
+    public void Parse_ReturnsNullForBlank()
+    {
+        Assert.Null(MetaJson.Parse(""));
+        Assert.Null(MetaJson.Parse("   "));
+    }
+}

tests/ShellDocs.Tests/NavigationGraphBuilderTests.cs

@@ -0,0 +1,203 @@
+using ShellDocs.Core;
+using Xunit;
+
+namespace ShellDocs.Tests;
+
+public class NavigationGraphBuilderTests : IDisposable
+{
+    private readonly string _root;
+
+    public NavigationGraphBuilderTests()
+    {
+        _root = Path.Combine(Path.GetTempPath(), "shelldocs-test-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(_root);
+    }
+
+    public void Dispose()
+    {
+        try { Directory.Delete(_root, recursive: true); } catch { }
+    }
+
+    private void WriteMd(string relativePath, string title, int order = 0)
+    {
+        var full = Path.Combine(_root, relativePath);
+        Directory.CreateDirectory(Path.GetDirectoryName(full)!);
+        File.WriteAllText(full, $"---\ntitle: {title}\norder: {order}\n---\n# {title}\n");
+    }
+
+    private void WriteMeta(string folder, string json)
+    {
+        var full = Path.Combine(_root, folder, "meta.json");
+        Directory.CreateDirectory(Path.GetDirectoryName(full)!);
+        File.WriteAllText(full, json);
+    }
+
+    [Fact]
+    public void Build_SingleFile_ResolvesByUrl()
+    {
+        WriteMd("intro.md", "Introduction");
+
+        var graph = NavigationGraphBuilder.Build(_root);
+        var node = graph.ResolveByUrl("/intro");
+
+        Assert.NotNull(node);
+        Assert.Equal("Introduction", node!.Title);
+        Assert.Equal(NodeKind.Page, node.Kind);
+    }
+
+    [Fact]
+    public void Build_UsesFrontmatterTitle_FallsBackToSlug()
+    {
+        WriteMd("with-title.md", "Explicit");
+        var noFrontmatter = Path.Combine(_root, "no-title.md");
+        File.WriteAllText(noFrontmatter, "# Just markdown");
+
+        var graph = NavigationGraphBuilder.Build(_root);
+
+        Assert.Equal("Explicit", graph.ResolveByUrl("/with-title")!.Title);
+        Assert.Equal("No Title", graph.ResolveByUrl("/no-title")!.Title);
+    }
+
+    [Fact]
+    public void Build_NestedFolders_AreSections()
+    {
+        WriteMd("docs/introduction.md", "Introduction");
+        WriteMd("docs/installation.md", "Installation");
+        WriteMd("components/button.md", "Button");
+
+        var graph = NavigationGraphBuilder.Build(_root);
+
+        Assert.NotNull(graph.ResolveByUrl("/docs/introduction"));
+        Assert.NotNull(graph.ResolveByUrl("/docs/installation"));
+        Assert.NotNull(graph.ResolveByUrl("/components/button"));
+
+        var sections = graph.Root.Children.Where(c => c.Kind == NodeKind.Section).ToList();
+        Assert.Contains(sections, s => s.Title == "Components");
+        Assert.Contains(sections, s => s.Title == "Docs");
+    }
+
+    [Fact]
+    public void Build_UsesMetaJsonOrdering()
+    {
+        WriteMd("alpha.md", "Alpha");
+        WriteMd("bravo.md", "Bravo");
+        WriteMd("charlie.md", "Charlie");
+        WriteMeta("", """{ "pages": ["charlie", "alpha", "bravo"] }""");
+
+        var graph = NavigationGraphBuilder.Build(_root);
+        var titles = graph.Root.Children.Select(c => c.Title).ToList();
+
+        Assert.Equal(new[] { "Charlie", "Alpha", "Bravo" }, titles);
+    }
+
+    [Fact]
+    public void Build_MetaJsonDivider_ProducesDividerNode()
+    {
+        WriteMd("a.md", "A");
+        WriteMd("b.md", "B");
+        WriteMeta("", """{ "pages": ["a", "---", "b"] }""");
+
+        var graph = NavigationGraphBuilder.Build(_root);
+
+        var kinds = graph.Root.Children.Select(c => c.Kind).ToList();
+        Assert.Equal(new[] { NodeKind.Page, NodeKind.Divider, NodeKind.Page }, kinds);
+    }
+
+    [Fact]
+    public void Build_MetaJsonSubsection_CreatesNamedSection()
+    {
+        WriteMd("table.md", "Table");
+        WriteMd("card.md", "Card");
+        WriteMeta("", """
+        {
+          "pages": [
+            {
+              "title": "Data Display",
+              "pages": ["table", "card"]
+            }
+          ]
+        }
+        """);
+
+        var graph = NavigationGraphBuilder.Build(_root);
+        var section = Assert.Single(graph.Root.Children);
+
+        Assert.Equal("Data Display", section.Title);
+        Assert.Equal(NodeKind.Section, section.Kind);
+        Assert.Equal(new[] { "Table", "Card" }, section.Children.Select(c => c.Title));
+    }
+
+    [Fact]
+    public void Build_UnknownSlugInMetaJson_IsSilentlySkipped()
+    {
+        WriteMd("real.md", "Real");
+        WriteMeta("", """{ "pages": ["real", "does-not-exist"] }""");
+
+        var graph = NavigationGraphBuilder.Build(_root);
+        var titles = graph.Root.Children.Select(c => c.Title).ToList();
+
+        Assert.Equal(new[] { "Real" }, titles);
+    }
+
+    [Fact]
+    public void Build_ThrowsOnMissingContentRoot()
+    {
+        Assert.Throws<DirectoryNotFoundException>(
+            () => NavigationGraphBuilder.Build(Path.Combine(_root, "does-not-exist")));
+    }
+
+    [Fact]
+    public void GetPrevNext_ReturnsAdjacentPages()
+    {
+        WriteMd("first.md", "First", order: 1);
+        WriteMd("second.md", "Second", order: 2);
+        WriteMd("third.md", "Third", order: 3);
+
+        var graph = NavigationGraphBuilder.Build(_root);
+        var second = graph.ResolveByUrl("/second")!;
+
+        var (prev, next) = graph.GetPrevNext(second);
+
+        Assert.Equal("First", prev?.Title);
+        Assert.Equal("Third", next?.Title);
+    }
+
+    [Fact]
+    public void GetPrevNext_HandlesBoundaries()
+    {
+        WriteMd("only.md", "Only");
+
+        var graph = NavigationGraphBuilder.Build(_root);
+        var only = graph.ResolveByUrl("/only")!;
+
+        var (prev, next) = graph.GetPrevNext(only);
+
+        Assert.Null(prev);
+        Assert.Null(next);
+    }
+
+    [Fact]
+    public void GetBreadcrumb_WalksUpFromLeafToTopLevel()
+    {
+        WriteMd("docs/theming/tokens.md", "Tokens");
+
+        var graph = NavigationGraphBuilder.Build(_root);
+        var leaf = graph.ResolveByUrl("/docs/theming/tokens")!;
+        var trail = graph.GetBreadcrumb(leaf);
+
+        Assert.Equal(new[] { "Docs", "Theming", "Tokens" }, trail.Select(n => n.Title));
+    }
+
+    [Fact]
+    public void ResolveByUrl_IsCaseInsensitiveAndTrailingSlashTolerant()
+    {
+        WriteMd("Button.md", "Button");
+
+        var graph = NavigationGraphBuilder.Build(_root);
+
+        Assert.NotNull(graph.ResolveByUrl("/button"));
+        Assert.NotNull(graph.ResolveByUrl("/BUTTON"));
+        Assert.NotNull(graph.ResolveByUrl("/button/"));
+        Assert.NotNull(graph.ResolveByUrl("button"));
+    }
+}

tests/ShellDocs.Tests/ScaffoldingTests.cs

@@ -1,22 +1,11 @@
-using ShellDocs.Core;
 using ShellDocs.Markdown;
 using ShellDocs.Templates;
 using Xunit;
 
 namespace ShellDocs.Tests;
 
-// Smoke tests — verify each package's public surface loads and its trivial APIs behave.
-// Real tests land branch-by-branch.
 public class ScaffoldingTests
 {
-    [Fact]
-    public void NavigationNode_HoldsRequiredFields()
-    {
-        var node = new NavigationNode { Url = "/docs/hello", Title = "Hello" };
-        Assert.Equal("/docs/hello", node.Url);
-        Assert.Equal("Hello", node.Title);
-    }
-
     [Fact]
     public void MarkdownPipelineFactory_ProducesUsablePipeline()
     {