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;
    }
}