NavigationGraphBuilder.cs

namespace ShellDocs.Core;

public static class NavigationGraphBuilder
{
 public static NavigationGraph Build(string contentRoot)
 {
 var abs = System.IO.Path.GetFullPath(contentRoot);
 if (!Directory.Exists(abs))
 {
 throw new DirectoryNotFoundException($"Content root not found: {contentRoot}");
 }

 var rootNode = new NavigationNode
 {
 Title = "",
 Url = "/",
 Kind = NodeKind.Section,
 Path = abs
 };

 var hidden = new List<NavigationNode>();
 var children = BuildFolder(abs, abs, urlPrefix: "", hidden);
 LinkChildren(rootNode, children);
 return new NavigationGraph(rootNode, hidden);
 }

 private static List<NavigationNode> BuildFolder(string folder, string root, string urlPrefix, List<NavigationNode> hidden)
 {
 var meta = ReadMeta(folder);
 var mdFiles = Directory.GetFiles(folder, "*.md", SearchOption.TopDirectoryOnly);
 var subfolders = Directory.GetDirectories(folder);

 var slugToNode = mdFiles.ToDictionary(
 path => SlugFrom(path),
 path => BuildPage(path, root, urlPrefix),
 StringComparer.OrdinalIgnoreCase);

 var folderNameToChildren = subfolders.ToDictionary(
 path => System.IO.Path.GetFileName(path),
 path => (folderPath: path, children: BuildFolder(path, root, CombineUrl(urlPrefix, System.IO.Path.GetFileName(path)), hidden)),
 StringComparer.OrdinalIgnoreCase);

 // No meta.json: alphabetical ordering, subfolders inline as sections.
 if (meta is null)
 {
 var ordered = new List<NavigationNode>();
 foreach (var (name, tuple) in folderNameToChildren.OrderBy(kv => kv.Key, StringComparer.OrdinalIgnoreCase))
 {
 var section = new NavigationNode
 {
 Title = TitleFromFolderName(name),
 Kind = NodeKind.Section,
 Path = tuple.folderPath
 };
 LinkChildren(section, tuple.children);
 ordered.Add(section);
 }
 ordered.AddRange(slugToNode.Values.OrderBy(n => n.Order).ThenBy(n => n.Title, StringComparer.OrdinalIgnoreCase));
 return ordered;
 }

 var result = new List<NavigationNode>();
 var consumedSlugs = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
 var consumedFolders = new HashSet<string>(StringComparer.OrdinalIgnoreCase);

 // Pages/folders in meta.hidden route (URLs still resolve) but never
 // appear in the sidebar tree. Seeded into consumed sets so both the
 // explicit-render loop and the auto-append loop skip them; the actual
 // nodes get pushed into `hidden` so the graph can still index their URLs.
 foreach (var slug in meta.Hidden)
 {
 consumedSlugs.Add(slug);
 consumedFolders.Add(slug);
 if (slugToNode.TryGetValue(slug, out var hiddenPage))
 hidden.Add(hiddenPage);
 if (folderNameToChildren.TryGetValue(slug, out var hiddenFolder))
 {
 // Wrap the folder's children in a section node so the graph's
 // Index() walk (which recurses .Children) reaches every page.
 var section = new NavigationNode
 {
 Title = TitleFromFolderName(slug),
 Kind = NodeKind.Section,
 Path = hiddenFolder.folderPath
 };
 LinkChildren(section, hiddenFolder.children);
 hidden.Add(section);
 }
 }

 foreach (var entry in meta.Pages)
 {
 var node = ResolveEntry(entry, slugToNode, folderNameToChildren, root, urlPrefix, consumedSlugs, consumedFolders);
 if (node is not null) result.Add(node);
 }

 /* meta.json controls ORDERING for anything it lists; presence is
 driven by the file tree. Files or subfolders the meta didn't
 mention get appended at the end (alphabetically) so a page dropped
 via `shelldocs add` or by hand appears immediately, without the
 consumer touching meta.json. */
 foreach (var (name, tuple) in folderNameToChildren.OrderBy(kv => kv.Key, StringComparer.OrdinalIgnoreCase))
 {
 if (consumedFolders.Contains(name)) continue;
 var section = new NavigationNode
 {
 Title = TitleFromFolderName(name),
 Kind = NodeKind.Section,
 Path = tuple.folderPath
 };
 LinkChildren(section, tuple.children);
 result.Add(section);
 }
 foreach (var page in slugToNode
 .Where(kv => !consumedSlugs.Contains(kv.Key))
 .Select(kv => kv.Value)
 .OrderBy(n => n.Order)
 .ThenBy(n => n.Title, StringComparer.OrdinalIgnoreCase))
 {
 result.Add(page);
 }

 return result;
 }

 private static NavigationNode? ResolveEntry(
 MetaJsonEntry entry,
 Dictionary<string, NavigationNode> slugToNode,
 Dictionary<string, (string folderPath, List<NavigationNode> children)> folderNameToChildren,
 string root,
 string urlPrefix,
 HashSet<string> consumedSlugs,
 HashSet<string> consumedFolders)
 {
 switch (entry)
 {
 case MetaJsonPageRef pageRef:
 // Hidden entries were pre-seeded into these sets; skip so a
 // slug listed in both `hidden` and `pages` stays hidden.
 if (consumedSlugs.Contains(pageRef.Slug) || consumedFolders.Contains(pageRef.Slug))
 return null;
 if (slugToNode.TryGetValue(pageRef.Slug, out var page))
 {
 consumedSlugs.Add(pageRef.Slug);
 return page;
 }
 if (folderNameToChildren.TryGetValue(pageRef.Slug, out var folder))
 {
 consumedFolders.Add(pageRef.Slug);
 var section = new NavigationNode
 {
 Title = TitleFromFolderName(pageRef.Slug),
 Kind = NodeKind.Section,
 Path = folder.folderPath
 };
 LinkChildren(section, folder.children);
 return section;
 }
 return null;

 case MetaJsonDivider:
 return new NavigationNode { Kind = NodeKind.Divider };

 case MetaJsonSubsection sub:
 var subNode = new NavigationNode
 {
 Title = sub.Title,
 Kind = NodeKind.Section
 };
 var subChildren = new List<NavigationNode>();
 foreach (var e in sub.Pages)
 {
 var child = ResolveEntry(e, slugToNode, folderNameToChildren, root, urlPrefix, consumedSlugs, consumedFolders);
 if (child is not null) subChildren.Add(child);
 }
 LinkChildren(subNode, subChildren);
 return subNode;

 default:
 return null;
 }
 }

 private static NavigationNode BuildPage(string path, string root, string urlPrefix)
 {
 var raw = File.ReadAllText(path);
 var parsed = FrontmatterParser.Parse(raw);
 var slug = SlugFrom(path);
 var url = slug == "index" ? EnsureLeadingSlash(urlPrefix) : CombineUrl(urlPrefix, slug);
 if (url == "") url = "/";

 return new NavigationNode
 {
 Url = url,
 Title = parsed.Frontmatter.GetValue<string>("title") ?? TitleFromSlug(slug),
 Description = parsed.Frontmatter.GetValue<string>("description"),
 Category = parsed.Frontmatter.GetValue<string>("category"),
 Order = parsed.Frontmatter.GetValue<int>("order"),
 Path = path,
 Kind = NodeKind.Page
 };
 }

 private static MetaJson? ReadMeta(string folder)
 {
 var metaPath = System.IO.Path.Combine(folder, "meta.json");
 return File.Exists(metaPath) ? MetaJson.Parse(File.ReadAllText(metaPath)) : null;
 }

 private static void LinkChildren(NavigationNode parent, IReadOnlyList<NavigationNode> children)
 {
 foreach (var child in children) child.Parent = parent;
 parent.Children = children;
 }

 private static string SlugFrom(string mdPath)
 => System.IO.Path.GetFileNameWithoutExtension(mdPath);

 private static string TitleFromSlug(string slug)
 => string.Join(' ', slug.Split('-').Select(w => w.Length == 0 ? w : char.ToUpper(w[0]) + w[1..]));

 private static string TitleFromFolderName(string name) => TitleFromSlug(name);

 private static string EnsureLeadingSlash(string s) => s.StartsWith('/') ? s : "/" + s;

 private static string CombineUrl(string prefix, string segment)
 {
 var p = prefix.TrimEnd('/');
 var s = segment.Trim('/');
 return string.IsNullOrEmpty(p) ? "/" + s : p + "/" + s;
 }
}