infodocs 0.3.0

data/lib/infodocs/renderer.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "commonmarker"
+require "rouge"
+require "cgi"
+require_relative "rails_lexer"
+
+module Infodocs
+  # Markdown -> HTML (GFM) with Rouge highlighting, heading anchors, a TOC and
+  # relative `.md` links rewritten to docs routes. ```mermaid blocks are left
+  # as <pre class="mermaid"> for the client.
+  class Renderer
+    Result = Struct.new(:html, :toc, :mermaid, :links, :assets, :headings, :embeds_missing, keyword_init: true)
+    Heading = Struct.new(:level, :text, :id, keyword_init: true)
+
+    def initialize(page, mount_path: "/docs")
+      @page = page
+      @mount_path = mount_path.to_s.chomp("/")
+      @links = []
+      @assets = []
+      @embeds_missing = []
+    end
+
+    def call
+      doc = Commonmarker.parse(@page.body, options: { render: { header_ids: nil }, extension: { table: true, strikethrough: true, autolink: true, tasklist: true, footnotes: true } })
+      headings = []
+      seen = Hash.new(0)
+      mermaid = false
+
+      nodes = []
+      doc.walk { |node| nodes << node }
+
+      nodes.each do |node|
+        case node.type
+        when :heading
+          text = plain_text(node)
+          id = unique_id(slugify(text), seen)
+          headings << Heading.new(level: node.header_level, text: text, id: id)
+          inner = node.each.map { |child| child.to_html.chomp }.join
+          anchor = %(<a class="infodocs-anchor" href="##{id}" aria-label="Link to this section">#</a>)
+          node.replace(raw_html(%(<h#{node.header_level} id="#{id}">#{inner}#{anchor}</h#{node.header_level}>\n)))
+        when :link
+          node.url = rewrite(node.url)
+        when :image
+          node.url = rewrite_asset(node.url)
+        when :code_block
+          lang, file, marks = parse_fence(node.fence_info)
+          if lang == "mermaid"
+            mermaid = true
+            node.replace(raw_html(%(<pre class="mermaid">#{CGI.escapeHTML(node.string_content.chomp)}</pre>\n)))
+          else
+            code = node.string_content
+            if marks[:embed]
+              code, lang, file = embedded_source(marks[:embed], lang, file, marks)
+            end
+            node.replace(raw_html(highlight(code, lang, file, marks)))
+          end
+        end
+      end
+
+      # Docs come from the host's own repo, so inline HTML is trusted.
+      Result.new(html: admonitions(doc.to_html(options: { render: { unsafe: true } })),
+                 toc: headings.select { |h| h.level.between?(2, 3) }, mermaid: mermaid,
+                 links: @links, assets: @assets, headings: headings.map(&:id), embeds_missing: @embeds_missing)
+    end
+
+    private
+
+    ADMONITIONS = %w[note tip important warning caution].freeze
+    ADMONITION = %r{<blockquote>\s*<p>\[!(#{ADMONITIONS.join('|')})\][ \t]*(?:<br />)?\s*(.*?)</blockquote>}mi
+
+    # GitHub-style alerts: `> [!NOTE]` turns the blockquote into a callout.
+    def admonitions(html)
+      html.gsub(ADMONITION) do
+        kind = Regexp.last_match(1).downcase
+        body = Regexp.last_match(2).sub(%r{\A</p>\s*}, "<p>").sub(/\A(?!<p>)/, "<p>")
+        %(<div class="infodocs-alert infodocs-alert-#{kind}"><p class="infodocs-alert-title">#{kind.capitalize}</p>#{body}</div>)
+      end
+    end
+
+    # Visible text of a heading, including inline code and emphasis.
+    def plain_text(node)
+      node.each.map { |child| %i[text code].include?(child.type) ? child.string_content.to_s : plain_text(child) }.join
+    end
+
+    def raw_html(html)
+      Commonmarker::Node.new(:html_block).tap { |node| node.literal = html }
+    end
+
+    # Fence tags people write that Rouge does not know by that name.
+    LANGUAGE_ALIASES = {
+      "ruby" => "rails", "rb" => "rails", "rails" => "rails", "ruby-on-rails" => "rails",
+      "stimulus" => "javascript", "importmap" => "ruby",
+      "html+erb" => "erb", "html.erb" => "erb", "zsh" => "shell", "sh" => "shell", "env" => "shell"
+    }.freeze
+
+    LANGUAGE_LABELS = { "javascript" => "JavaScript", "erb" => "ERB", "html" => "HTML", "css" => "CSS", "json" => "JSON", "yaml" => "YAML",
+                        "sql" => "SQL", "shell" => "Shell", "rails" => "Ruby", "ruby" => "Ruby", "plaintext" => "Text" }.freeze
+
+    # "ruby {2,4-6} showLineNumbers app/models/note.rb" -> lang, file, marks
+    def parse_fence(info)
+      words = info.to_s.split
+      lang = words.shift
+      marks = { numbers: false, lines: [], embed: nil }
+      file = []
+      if lang&.start_with?("file=")
+        words.unshift(lang)
+        lang = nil
+      end
+      words.each do |word|
+        if word.start_with?("file=")
+          marks[:embed] = word.delete_prefix("file=")
+        elsif word == "showLineNumbers"
+          marks[:numbers] = true
+        elsif (match = word.match(/\A\{([\d,\-]+)\}\z/))
+          marks[:lines] = match[1].split(",").flat_map { |part| a, b = part.split("-").map(&:to_i); (a..(b || a)).to_a }
+        else
+          file << word
+        end
+      end
+      [lang, file.join(" ").presence, marks]
+    end
+
+    EMBED_LIMIT = 200_000
+    EMBED_BLOCKED = %r{(\A|/)(\.|credentials|master\.key|secrets?\b)|\.(pem|key|p12)\z}i
+
+    # `file=app/models/note.rb#L3-12`: the (excerpt of the) file replaces the block body.
+    # Only files inside Rails.root are readable; secrets and dotfiles are refused.
+    def embedded_source(spec, lang, label, marks)
+      path, range = spec.split("#", 2)
+      file = embed_file(path)
+      unless file
+        @embeds_missing << path
+        return ["# Cannot embed #{path}: file not found or not allowed\n", lang || "plaintext", label || path]
+      end
+
+      lines = file.read(EMBED_LIMIT).to_s.lines
+      first, last = range.to_s.match(/\AL(\d+)(?:-L?(\d+))?\z/)&.captures&.map { |n| n&.to_i }
+      if first
+        last ||= first
+        lines = lines[(first - 1)...last].to_a
+        marks[:start] = first
+      end
+      lang ||= Rouge::Lexer.guess_by_filename(file.basename.to_s).tag
+      [lines.join, lang, label || path]
+    rescue Rouge::Guesser::Ambiguous, Rouge::Guesser::Ambiguous::NoMatch, StandardError
+      [lines&.join.to_s, lang || "plaintext", label || path]
+    end
+
+    def embed_file(path)
+      return unless defined?(Rails) && Rails.root && path.present?
+      return if path.match?(EMBED_BLOCKED) || path.include?("..")
+
+      file = Rails.root.join(path)
+      return unless file.file?
+
+      real = file.realpath
+      root = Rails.root.realpath
+      real if real.to_s.start_with?("#{root}/") && !real.to_s.match?(EMBED_BLOCKED)
+    rescue SystemCallError
+      nil
+    end
+
+    # Highlighted HTML with one <span class="line"> per source line.
+    def highlight_lines(lexer, code, highlighted)
+      lines = [+""]
+      lexer.lex(code).each do |token, value|
+        value.split(/(\n)/).each do |piece|
+          if piece == "\n"
+            lines << +""
+          elsif !piece.empty?
+            lines.last << Rouge::Formatters::HTML.new.format([[token, piece]])
+          end
+        end
+      end
+      lines.pop if lines.last.empty?
+      lines.each_with_index.map do |html, index|
+        css = highlighted.include?(index + 1) ? "line line-hl" : "line"
+        %(<span class="#{css}">#{html}\n</span>)
+      end.join
+    end
+
+    def highlight(code, lang, file = nil, marks = { numbers: false, lines: [] })
+      name = LANGUAGE_ALIASES.fetch(lang.to_s.downcase, lang)
+      lexer = (name && Rouge::Lexer.find(name)) || Rouge::Lexers::PlainText
+      body = highlight_lines(lexer, code, marks[:lines])
+      label = LANGUAGE_LABELS.fetch(lexer.tag, lexer.tag.capitalize)
+      bar = %(<span class="infodocs-code-lang">#{CGI.escapeHTML(label)}</span>)
+      bar += %(<span class="infodocs-code-file">#{CGI.escapeHTML(file)}</span>) if file.present?
+      bar += %(<button type="button" class="infodocs-code-copy" data-infodocs-copy>Copy</button>)
+      %(<div class="infodocs-code"><div class="infodocs-code-bar">#{bar}</div><pre class="highlight#{' infodocs-numbers' if marks[:numbers]}"#{%( style="counter-reset:line #{marks[:start] - 1}") if marks[:start] && marks[:start] > 1}><code class="language-#{CGI.escapeHTML(lexer.tag)}">#{body}</code></pre></div>\n)
+    end
+
+    def rewrite(url)
+      return url if url.nil? || url.empty? || url.match?(%r{\A([a-z][a-z0-9+.-]*:|//|#)}i)
+
+      path, anchor = url.split("#", 2)
+      return rewrite_asset(url) unless path.end_with?(".md")
+
+      target = Pathname([@page.directory_slug, path.delete_suffix(".md")].reject(&:empty?).join("/")).cleanpath.to_s.delete_prefix("./")
+      target = target.sub(%r{/?(index|readme)\z}i, "")
+      @links << [target, anchor]
+      [File.join(@mount_path, target), anchor].compact.join("#")
+    end
+
+    # Relative files next to the page (images, PDFs) are served by the engine.
+    def rewrite_asset(url)
+      return url if url.nil? || url.empty? || url.match?(%r{\A([a-z][a-z0-9+.-]*:|//|#|/)}i)
+
+      path = url.split(/[?#]/, 2).first
+      return url unless Tree::ASSET_TYPES.key?(File.extname(path).downcase)
+
+      target = Pathname([@page.directory_slug, path].reject(&:empty?).join("/")).cleanpath.to_s.delete_prefix("./")
+      return url if target.start_with?("..")
+
+      @assets << target
+      File.join(@mount_path, "_asset", target)
+    end
+
+    def slugify(text)
+      text.downcase.gsub(/[^\p{L}\p{N}\s_-]/, "").strip.gsub(/\s+/, "-")
+    end
+
+    def unique_id(base, seen)
+      base = "section" if base.empty?
+      count = seen[base]
+      seen[base] += 1
+      count.zero? ? base : "#{base}-#{count}"
+    end
+  end
+end

data/lib/infodocs/search.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "sqlite3"
+require "fileutils"
+require "cgi"
+
+module Infodocs
+  # SQLite FTS5 index over all pages. Rebuilt incrementally by file mtime.
+  class Search
+    Result = Struct.new(:slug, :title, :snippet, :score, keyword_init: true)
+
+    def initialize(tree, db_path:)
+      @tree = tree
+      FileUtils.mkdir_p(File.dirname(db_path)) unless db_path == ":memory:"
+      @db = SQLite3::Database.new(db_path.to_s)
+      @db.execute(<<~SQL)
+        CREATE VIRTUAL TABLE IF NOT EXISTS docs USING fts5(
+          slug UNINDEXED, path, title, headings, body, mtime UNINDEXED,
+          tokenize = 'porter unicode61 remove_diacritics 2'
+        )
+      SQL
+    end
+
+    def reindex!
+      known = @db.execute("SELECT slug, mtime FROM docs").to_h
+      current = @tree.pages.to_h { |page| [page.slug, page] }
+
+      @db.transaction do
+        (known.keys - current.keys).each { |slug| @db.execute("DELETE FROM docs WHERE slug = ?", [slug]) }
+        current.each do |slug, page|
+          next if known[slug] == page.mtime.to_f.to_s
+
+          @db.execute("DELETE FROM docs WHERE slug = ?", [slug])
+          @db.execute("INSERT INTO docs (slug, path, title, headings, body, mtime) VALUES (?, ?, ?, ?, ?, ?)",
+                      [slug, slug.tr("/", " "), fold(page.title), fold(headings(page)), fold(page.body), page.mtime.to_f.to_s])
+        end
+      end
+    end
+
+    # Query syntax: words (AND), "phrase", OR, -exclude, prefix*, title:x, path:x.
+    def search(query, limit: 20)
+      tags = Page.normalize_tags(query.to_s.scan(/(?<!\S)tag:(\S+)/).flatten)
+      query = query.to_s.gsub(/(?<!\S)tag:\S+/, " ").strip
+      return tagged_results(tags, limit) if query.empty? && tags.any?
+      return filter_tags(search_text(query, limit: tags.any? ? 200 : limit), tags).first(limit) if tags.any?
+
+      search_text(query, limit: limit)
+    end
+
+    def search_text(query, limit:)
+      match = Query.new(fold(query)).to_fts
+      return [] if match.empty?
+
+      sql = <<~SQL
+        SELECT slug, title, bm25(docs, 0, 2.0, 10.0, 4.0, 1.0)
+        FROM docs WHERE docs MATCH ? ORDER BY 3 LIMIT ?
+      SQL
+      terms = fold(query).scan(/(?<![-:])\b[\p{L}\p{N}]{2,}/).uniq
+      @db.execute(sql, [match, limit]).filter_map do |slug, title, score|
+        page = @tree.find(slug) or next
+        Result.new(slug: slug, title: page.title, snippet: snippet(page.body, terms), score: score)
+      end
+    rescue SQLite3::SQLException
+      []
+    end
+
+    private
+
+    def tagged_results(tags, limit)
+      pages = @tree.pages.select { |page| (tags - page.tags).empty? }.first(limit)
+      pages.map { |page| Result.new(slug: page.slug, title: page.title, snippet: CGI.escapeHTML(page.description), score: 0) }
+    end
+
+    def filter_tags(results, tags)
+      results.select { |result| (tags - (@tree.find(result.slug)&.tags || [])).empty? }
+    end
+
+    # unicode61 folds most diacritics but not ł/Ł; fold it ourselves (same
+    # length, so offsets in the folded text map onto the original).
+    def fold(text)
+      text.to_s.tr("łŁ", "lL")
+    end
+
+    def snippet(body, terms, width: 160)
+      folded = fold(body).downcase
+      hit = terms.filter_map { |term| folded.index(term) }.min || 0
+      from = [hit - width / 4, 0].max
+      excerpt = body[from, width]
+      html = CGI.escapeHTML(excerpt)
+      terms.each { |term| html = html.gsub(/#{Regexp.escape(CGI.escapeHTML(term))}/i) { |m| "<mark>#{m}</mark>" } }
+      "#{'…' if from.positive?}#{html}…"
+    end
+
+    def headings(page)
+      page.body.scan(/^\#{1,6}\s+(.+)$/).flatten.join("\n")
+    end
+
+    class Query
+      FIELDS = { "title" => "title", "path" => "path", "heading" => "headings" }.freeze
+
+      def initialize(raw)
+        @raw = raw.to_s
+      end
+
+      def to_fts
+        tokens = @raw.scan(/-?(?:\w+:)?"[^"]*"|\S+/)
+        parts = []
+        tokens.each do |token|
+          negate = token.start_with?("-")
+          token = token.delete_prefix("-")
+          if token.upcase == "OR"
+            parts << "OR"
+            next
+          end
+          field, term = token.include?(":") && FIELDS.key?(token.split(":", 2).first) ? token.split(":", 2) : [nil, token]
+          term = term.delete('"') unless term.start_with?('"')
+          prefix = term.end_with?("*")
+          term = term.delete_suffix("*")
+          next if term.delete('"').strip.empty?
+
+          quoted = term.start_with?('"') ? term : %("#{term.gsub('"', '')}")
+          quoted += "*" if prefix
+          quoted = "#{FIELDS[field]} : #{quoted}" if field
+          parts << (negate ? "NOT #{quoted}" : quoted)
+        end
+        parts.shift while parts.first == "OR" || parts.first&.start_with?("NOT")
+        parts.join(" ")
+      end
+    end
+  end
+end

data/lib/infodocs/source.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Infodocs
+  # One docs directory. Plain paths take slug/title from the directory name;
+  # `{ path:, slug:, title: }` overrides them.
+  Source = Struct.new(:path, :slug, :title, keyword_init: true) do
+    SLUG = /\A[\p{L}\p{N}][\p{L}\p{N}_-]*\z/
+
+    def self.wrap(value)
+      return value if value.is_a?(Source)
+
+      if value.respond_to?(:to_hash)
+        options = value.to_hash.transform_keys(&:to_sym)
+        path = options.fetch(:path) { raise Error, "Infodocs source needs a :path, got #{value.inspect}" }
+        new(path: Pathname(path.to_s), slug: options[:slug]&.to_s, title: options[:title]&.to_s).validate!
+      else
+        new(path: Pathname(value.to_s)).validate!
+      end
+    end
+
+    def validate!
+      raise Error, "Infodocs source slug #{slug.inspect} may only contain letters, digits, - and _" if slug && !slug.match?(SLUG)
+
+      self
+    end
+
+    # Explicit slug/title put the directory in its own folder even when it is
+    # the only source.
+    def explicit? = !slug.nil? || !title.nil?
+
+    def key = slug || path.basename.to_s
+  end
+end

data/lib/infodocs/tree.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+
+module Infodocs
+  # Docs hierarchy built from directories of .md files. Each directory may hold
+  # a `_tree.yml`:
+  #
+  #   title: Guides          # folder title in the sidebar
+  #   order: [intro, setup]  # entry names (file without .md, or subfolder)
+  #   hidden: [drafts]       # not shown in the sidebar, still routable
+  #
+  # Entries not listed in `order` follow alphabetically. `index.md` (or
+  # `README.md`) in a directory is that folder's landing page.
+  class Tree
+    MANIFEST = "_tree.yml"
+    INDEX_NAMES = %w[index readme].freeze
+
+    Node = Struct.new(:name, :title, :slug, :page, :children, :hidden, :path, keyword_init: true) do
+      def folder? = !children.nil?
+      def leaf? = !folder?
+    end
+
+    attr_reader :root, :sources
+
+    def self.build(paths, drafts: true)
+      sources = (paths.is_a?(Array) ? paths : [paths]).map { |entry| Source.wrap(entry) }.select { |source| source.path.directory? }
+      new(sources, drafts: drafts)
+    end
+
+    def initialize(sources, drafts: true)
+      @sources = sources
+      @drafts = drafts
+      @root = build_root
+      @pages = {}
+      index_pages(@root)
+      @redirects = @pages.values.each_with_object({}) { |page, map| page.redirect_from.each { |old| map[old] ||= page.slug } }
+    end
+
+    def children
+      root.children
+    end
+
+    # Several sources, or one with an explicit slug/title, appear as folders.
+    # First readable page inside a folder (depth first), for folders without a landing page.
+    def first_page_under(node)
+      node.children.to_a.reject(&:hidden).each do |child|
+        return child.page if child.leaf?
+
+        found = first_page_under(child) || child.page
+        return found if found
+      end
+      nil
+    end
+
+    ASSET_TYPES = {
+      ".png" => "image/png", ".jpg" => "image/jpeg", ".jpeg" => "image/jpeg", ".gif" => "image/gif",
+      ".webp" => "image/webp", ".avif" => "image/avif", ".svg" => "image/svg+xml",
+      ".pdf" => "application/pdf", ".mp4" => "video/mp4", ".webm" => "video/webm"
+    }.freeze
+
+    # Non-markdown file (image, pdf, ...) addressed like a page slug plus the
+    # file name. Only whitelisted types inside a source, never `_`/`.` entries.
+    def asset(path)
+      parts = path.to_s.split("/")
+      return if parts.empty? || parts.any? { |part| part.empty? || part.start_with?("_", ".") }
+
+      source, inner = multiple_roots? ? [@sources.find { |s| s.key == parts.first }, parts.drop(1)] : [@sources.first, parts]
+      return if source.nil? || inner.empty?
+
+      file = source.path.join(*inner)
+      return unless file.file? && ASSET_TYPES.key?(file.extname.downcase)
+      return unless file.realpath.to_s.start_with?("#{source.path.realpath}/")
+
+      file
+    end
+
+    def multiple_roots?
+      @sources.size > 1 || @sources.first&.explicit? || false
+    end
+
+    def node(slug)
+      slug = slug.to_s.delete_prefix("/").delete_suffix("/")
+      return root if slug.empty?
+
+      find_path(root, slug)&.last
+    end
+
+    # { "tag" => number of visible pages }, alphabetical.
+    def tags
+      pages.flat_map(&:tags).tally.sort.to_h
+    end
+
+    def tagged(tag)
+      tag = Page.normalize_tags(tag).first
+      pages.select { |page| page.tags.include?(tag) }
+    end
+
+    # Every page, hidden ones included.
+    def all_pages
+      @pages.values
+    end
+
+    # Pages in sidebar order (hidden ones excluded); drives prev/next.
+    def pages
+      @ordered ||= flatten(root).reject(&:hidden).map(&:page)
+    end
+
+    # Current slug for an old URL listed in some page's `redirect_from`, unless a page lives there now.
+    def redirect_for(path)
+      path = path.to_s.delete_prefix("/").delete_suffix("/")
+      return if @pages.key?(path)
+
+      @redirects[path]
+    end
+
+    def find(slug)
+      @pages[slug.to_s.delete_prefix("/").delete_suffix("/")]
+    end
+
+    # Nodes from the top level down to the one with `slug` (for breadcrumbs).
+    def trail(slug)
+      slug = slug.to_s.delete_prefix("/").delete_suffix("/")
+      find_path(root, slug) || []
+    end
+
+    def neighbours(page)
+      index = pages.index(page)
+      return [nil, nil] unless index
+
+      [index.positive? ? pages[index - 1] : nil, pages[index + 1]]
+    end
+
+    private
+
+    def build_root
+      if multiple_roots?
+        folders = @sources.map { |source| build_folder(source.path, slug: source.key, name: source.key, title: source.title) }
+        Node.new(name: "", title: nil, slug: "", page: nil, children: folders, hidden: false, path: nil)
+      else
+        build_folder(@sources.first.path, slug: "", name: "", title: nil)
+      end
+    end
+
+    def build_folder(dir, slug:, name:, title:)
+      manifest = read_manifest(dir)
+      tag_map = manifest["tags"].is_a?(Hash) ? manifest["tags"].transform_keys(&:to_s) : {}
+      entries = {}
+      landing = nil
+
+      dir.children.sort.each do |entry|
+        base = entry.basename.to_s
+        next if base.start_with?("_", ".")
+
+        if entry.directory?
+          child_slug = [slug, base].reject(&:empty?).join("/")
+          node = build_folder(entry, slug: child_slug, name: base, title: nil)
+          entries[base] = node if node.children.any? || node.page || entry.join(MANIFEST).file?
+        elsif entry.extname == ".md"
+          stem = entry.basename(".md").to_s
+          if INDEX_NAMES.include?(stem.downcase) && landing.nil?
+            candidate = Page.new(file: entry, slug: slug, root: dir)
+            landing = candidate if @drafts || !candidate.draft?
+            next
+          end
+          page_slug = [slug, stem].reject(&:empty?).join("/")
+          page = Page.new(file: entry, slug: page_slug, root: dir, manifest_tags: tag_map[stem])
+          next if page.draft? && !@drafts
+          entries[stem] = Node.new(name: stem, title: page.title, slug: page_slug, page: page, children: nil, hidden: false, path: entry)
+        end
+      end
+
+      hidden = Array(manifest["hidden"]).map(&:to_s)
+      order = Array(manifest["order"]).map(&:to_s)
+      sorted = order.filter_map { |key| entries[key] } + (entries.keys - order).sort.map { |key| entries[key] }
+      sorted.each { |node| node.hidden = hidden.include?(node.name) }
+
+      Node.new(name: name, title: title || manifest["title"] || landing&.title || name.tr("-_", "  ").capitalize,
+               slug: slug, page: landing, children: sorted, hidden: false, path: dir)
+    end
+
+    def read_manifest(dir)
+      file = dir.join(MANIFEST)
+      return {} unless file.file?
+
+      data = YAML.safe_load(file.read)
+      data.is_a?(Hash) ? data.transform_keys(&:to_s) : {}
+    end
+
+    def index_pages(node)
+      @pages[node.slug] = node.page if node.page && !(node.slug.empty? && node.page.nil?)
+      node.children&.each { |child| index_pages(child) }
+    end
+
+    def find_path(node, slug)
+      return [] if node.slug.empty? && slug.empty?
+      return [node] if node.slug == slug
+
+      node.children&.each do |child|
+        found = find_path(child, slug)
+        return (node.slug.empty? ? [] : [node]) + found if found
+      end
+      nil
+    end
+
+    def flatten(node)
+      list = []
+      list << node if node.page && !node.hidden
+      node.children&.each { |child| list.concat(flatten(child)) unless child.hidden }
+      list
+    end
+  end
+end
+