docyard 0.8.0 → 1.0.0

data/lib/docyard/navigation/sidebar/auto_builder.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "item"
+
+module Docyard
+  module Sidebar
+    class AutoBuilder
+      attr_reader :docs_path, :current_path
+
+      def initialize(docs_path, current_path: "/")
+        @docs_path = docs_path
+        @current_path = Utils::PathResolver.normalize(current_path)
+      end
+
+      def build
+        return [] unless File.directory?(docs_path)
+
+        scan_directory("").map(&:to_h)
+      end
+
+      private
+
+      def scan_directory(relative_path, depth: 1)
+        full_path = File.join(docs_path, relative_path)
+        return [] unless File.directory?(full_path)
+
+        entries = sorted_entries(full_path, relative_path)
+        entries.map { |entry| build_item(entry, relative_path, depth) }.compact
+      end
+
+      def sorted_entries(full_path, relative_path)
+        Dir.children(full_path)
+          .reject { |entry| ignored_entry?(entry, relative_path) }
+          .sort_by(&:downcase)
+      end
+
+      def build_item(entry, relative_path, depth)
+        entry_relative_path = build_relative_path(relative_path, entry)
+        entry_full_path = File.join(docs_path, entry_relative_path)
+
+        if File.directory?(entry_full_path)
+          build_directory_item(entry, entry_relative_path, depth)
+        elsif entry.end_with?(".md")
+          build_file_item(entry, entry_relative_path)
+        end
+      end
+
+      def build_relative_path(relative_path, entry)
+        relative_path.empty? ? entry : File.join(relative_path, entry)
+      end
+
+      def build_directory_item(name, relative_path, depth)
+        children = scan_directory(relative_path, depth: depth + 1)
+        return nil if children.empty?
+
+        url_path = "/#{relative_path}"
+        has_index = File.file?(File.join(docs_path, relative_path, "index.md"))
+
+        Item.new(
+          slug: name,
+          text: Utils::TextFormatter.titleize(name),
+          path: has_index ? url_path : nil,
+          type: :directory,
+          section: depth == 1,
+          collapsed: depth > 1 && !child_active?(children),
+          has_index: has_index,
+          active: has_index && current_path == url_path,
+          items: children
+        )
+      end
+
+      def build_file_item(filename, relative_path)
+        slug = filename.delete_suffix(".md")
+        url_path = "/#{relative_path.delete_suffix('.md')}"
+
+        Item.new(
+          slug: slug,
+          text: Utils::TextFormatter.titleize(slug),
+          path: url_path,
+          type: :file,
+          section: false,
+          active: current_path == url_path,
+          items: []
+        )
+      end
+
+      def ignored_entry?(entry, relative_path)
+        entry.start_with?(".") ||
+          entry.start_with?("_") ||
+          root_index?(entry, relative_path) ||
+          public_folder?(entry, relative_path)
+      end
+
+      def root_index?(entry, relative_path)
+        entry == "index.md" && relative_path.empty?
+      end
+
+      def public_folder?(entry, relative_path)
+        entry == "public" && relative_path.empty?
+      end
+
+      def child_active?(children)
+        children.any? { |child| child.active || child_active?(child.items) }
+      end
+    end
+  end
+end

data/lib/docyard/navigation/sidebar/cache.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "config_builder"
+require_relative "auto_builder"
+require_relative "distributed_builder"
+require_relative "local_config_loader"
+
+module Docyard
+  module Sidebar
+    class Cache
+      attr_reader :docs_path, :config, :tree, :built_at
+
+      def initialize(docs_path:, config:)
+        @docs_path = docs_path
+        @config = config
+        @tree = nil
+        @built_at = nil
+      end
+
+      def build
+        @tree = build_tree
+        @built_at = Time.now
+        @tree
+      end
+
+      def get(current_path: "/")
+        return nil unless @tree
+
+        mark_active_items(@tree, current_path)
+      end
+
+      def invalidate
+        @tree = nil
+        @built_at = nil
+      end
+
+      def valid?
+        !@tree.nil?
+      end
+
+      private
+
+      def build_tree
+        case config.sidebar
+        when "auto"
+          AutoBuilder.new(docs_path, current_path: "/").build
+        when "distributed"
+          DistributedBuilder.new(docs_path, current_path: "/").build
+        else
+          build_config_tree
+        end
+      end
+
+      def build_config_tree
+        config_items = LocalConfigLoader.new(docs_path).load
+        return [] unless config_items
+
+        ConfigBuilder.new(config_items, current_path: "/").build
+      end
+
+      def mark_active_items(items, current_path)
+        deep_copy_with_active(items, current_path)
+      end
+
+      def deep_copy_with_active(items, current_path)
+        items.map do |item|
+          copied = item.dup
+          copied[:active] = path_matches?(copied[:path], current_path)
+          copied[:children] = deep_copy_with_active(item[:children] || [], current_path)
+          copied[:collapsed] = determine_collapsed_for_copy(copied)
+          copied
+        end
+      end
+
+      def path_matches?(item_path, current_path)
+        return false if item_path.nil?
+
+        normalized_item = Utils::PathResolver.normalize(item_path)
+        normalized_current = Utils::PathResolver.normalize(current_path)
+        normalized_item == normalized_current
+      end
+
+      def determine_collapsed_for_copy(item)
+        return false if item[:section]
+        return false if item[:active]
+        return false if child_active?(item[:children] || [])
+
+        item[:collapsed]
+      end
+
+      def child_active?(children)
+        children.any? { |child| child[:active] || child_active?(child[:children] || []) }
+      end
+    end
+  end
+end

data/lib/docyard/navigation/sidebar/config_builder.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require_relative "item"
+
+module Docyard
+  module Sidebar
+    class ConfigBuilder
+      attr_reader :config_items, :current_path, :start_depth
+
+      def initialize(config_items, current_path: "/", start_depth: 1)
+        @config_items = config_items || []
+        @current_path = Utils::PathResolver.normalize(current_path)
+        @start_depth = start_depth
+      end
+
+      def build
+        parse_items(config_items, base_path: "", depth: start_depth).map(&:to_h)
+      end
+
+      private
+
+      def parse_items(items, base_path:, depth:)
+        items.map { |item| parse_item(item, base_path: base_path, depth: depth) }.compact
+      end
+
+      def parse_item(item_config, base_path:, depth:)
+        case item_config
+        when String
+          build_page_item(item_config, base_path: base_path)
+        when Hash
+          parse_hash_item(item_config, base_path: base_path, depth: depth)
+        end
+      end
+
+      def parse_hash_item(config, base_path:, depth:)
+        return build_external_link(config) if external_link?(config)
+
+        slug, options = extract_slug_and_options(config)
+        return build_page_item(slug, base_path: base_path, options: options) if leaf_item?(options)
+
+        build_group_item(slug, options: options, base_path: base_path, depth: depth)
+      end
+
+      def external_link?(config)
+        config.key?("link") || config.key?(:link)
+      end
+
+      def extract_slug_and_options(config)
+        if config.keys.first.is_a?(String) && !external_link?(config)
+          [config.keys.first.to_s, config.values.first || {}]
+        else
+          [nil, config]
+        end
+      end
+
+      def leaf_item?(options)
+        return true if options.nil?
+        return false if options.is_a?(Hash) && (options.key?("items") || options.key?(:items))
+
+        true
+      end
+
+      def build_page_item(slug, base_path:, options: {})
+        options = normalize_options(options)
+        url_path = build_url_path(base_path, slug)
+
+        Item.new(
+          slug: slug,
+          text: options[:text] || titleize_slug(slug),
+          path: url_path,
+          icon: options[:icon],
+          badge: options[:badge],
+          badge_type: options[:badge_type],
+          active: current_path == url_path,
+          type: :file,
+          section: false,
+          items: []
+        )
+      end
+
+      def build_group_item(slug, options:, base_path:, depth:)
+        options = normalize_options(options)
+        context = build_group_context(slug, options, base_path, depth)
+        children = parse_items(options[:items] || [], base_path: context[:new_base_path], depth: depth + 1)
+
+        create_group_item(slug, options, context, children)
+      end
+
+      def build_group_context(slug, options, base_path, depth)
+        is_section = section_at_depth?(options, depth)
+        is_virtual_group = options[:group] == true
+        has_index = options[:index] == true
+        new_base_path = compute_new_base_path(slug, base_path, is_virtual_group)
+        url_path = has_index && !is_section ? build_url_path(base_path, slug) : nil
+
+        { is_section: is_section, has_index: has_index, new_base_path: new_base_path, url_path: url_path }
+      end
+
+      def compute_new_base_path(slug, base_path, is_virtual_group)
+        return base_path if is_virtual_group
+        return base_path unless slug
+
+        File.join(base_path, slug)
+      end
+
+      def create_group_item(slug, options, context, children)
+        Item.new(
+          slug: slug,
+          text: options[:text] || titleize_slug(slug),
+          path: context[:url_path],
+          icon: options[:icon],
+          badge: options[:badge],
+          badge_type: options[:badge_type],
+          active: context[:has_index] && current_path == context[:url_path],
+          type: :directory,
+          section: context[:is_section],
+          collapsed: determine_collapsed_state(context[:is_section], options, children),
+          has_index: context[:has_index],
+          items: children
+        )
+      end
+
+      def build_external_link(config)
+        config = normalize_options(config)
+        url = config[:link]
+
+        Item.new(
+          slug: nil,
+          text: config[:text],
+          path: url,
+          link: url,
+          icon: config[:icon],
+          target: config[:target] || "_blank",
+          type: :external,
+          section: false,
+          items: []
+        )
+      end
+
+      def section_at_depth?(options, depth)
+        return false if options[:collapsible] == true
+        return false if options[:group] == true
+
+        depth == 1
+      end
+
+      def determine_collapsed_state(is_section, options, children)
+        return false if is_section
+        return false if child_active?(children)
+        return options[:collapsed] if options.key?(:collapsed)
+
+        true
+      end
+
+      def child_active?(children)
+        children.any? { |child| child.active || child_active?(child.items) }
+      end
+
+      def build_url_path(base_path, slug)
+        base_path = base_path.to_s.sub(%r{^/+}, "")
+        return base_path.empty? ? "/" : "/#{base_path}" if slug == "index"
+
+        path = [base_path, slug].reject(&:empty?).join("/")
+        "/#{path}"
+      end
+
+      def titleize_slug(slug)
+        Utils::TextFormatter.titleize(slug.to_s)
+      end
+
+      def normalize_options(options)
+        return {} if options.nil?
+        return options if options.is_a?(Hash) && options.keys.all? { |k| k.is_a?(Symbol) }
+
+        options.transform_keys(&:to_sym)
+      end
+    end
+  end
+end

data/lib/docyard/navigation/sidebar/distributed_builder.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative "item"
+require_relative "local_config_loader"
+require_relative "config_builder"
+
+module Docyard
+  module Sidebar
+    class DistributedBuilder
+      attr_reader :docs_path, :current_path
+
+      def initialize(docs_path, current_path: "/")
+        @docs_path = docs_path
+        @current_path = Utils::PathResolver.normalize(current_path)
+      end
+
+      def build
+        root_config = load_root_config
+        return [] if root_config.empty?
+
+        root_config.map { |section_slug| build_section(section_slug) }
+      end
+
+      private
+
+      def load_root_config
+        loader = LocalConfigLoader.new(docs_path)
+        config = loader.load
+        raise_missing_root_config unless config
+
+        normalize_root_config(config)
+      end
+
+      def normalize_root_config(config)
+        config.map do |item|
+          case item
+          when String then item
+          when Hash then item.keys.first.to_s
+          end
+        end.compact
+      end
+
+      def build_section(section_slug)
+        section_path = File.join(docs_path, section_slug)
+        section_config = load_section_config(section_slug, section_path)
+
+        build_section_item(section_slug, section_config)
+      end
+
+      def load_section_config(section_slug, section_path)
+        loader = LocalConfigLoader.new(section_path)
+        raise_missing_section_config(section_slug) unless loader.config_file_exists?
+
+        raw_config = YAML.load_file(File.join(section_path, "_sidebar.yml"))
+        normalize_section_config(raw_config)
+      end
+
+      def normalize_section_config(config)
+        return { items: config } if config.is_a?(Array)
+
+        config.transform_keys(&:to_sym)
+      end
+
+      def build_section_item(section_slug, section_config)
+        items = section_config[:items] || []
+        children = build_section_children(items, section_slug)
+
+        Item.new(
+          slug: section_slug,
+          text: section_config[:text] || Utils::TextFormatter.titleize(section_slug),
+          path: nil,
+          icon: section_config[:icon],
+          type: :directory,
+          section: true,
+          collapsed: false,
+          has_index: false,
+          active: false,
+          items: children
+        ).to_h
+      end
+
+      def build_section_children(items, section_slug)
+        adjusted_current_path = adjust_current_path_for_section(section_slug)
+
+        builder = ConfigBuilder.new(items, current_path: adjusted_current_path, start_depth: 2)
+        tree = builder.build
+
+        prefix_paths(tree, section_slug)
+      end
+
+      def adjust_current_path_for_section(section_slug)
+        prefix = "/#{section_slug}"
+        return current_path unless current_path.start_with?(prefix)
+
+        relative = current_path.sub(prefix, "")
+        relative.empty? ? "/" : relative
+      end
+
+      def prefix_paths(items, prefix)
+        items.map do |item|
+          prefixed = prefix_item_path(item, prefix)
+          prefixed[:children] = prefix_paths(item[:children] || [], prefix) if item[:children]&.any?
+          prefixed
+        end
+      end
+
+      def prefix_item_path(item, prefix)
+        item = item.dup
+        return item if item[:path].nil? || external_path?(item[:path])
+
+        prefixed_path = "/#{prefix}#{item[:path]}"
+        item[:path] = prefixed_path.chomp("/")
+        item[:path] = "/" if item[:path].empty?
+        item[:active] = current_path == item[:path]
+        item
+      end
+
+      def external_path?(path)
+        path.start_with?("http://", "https://")
+      end
+
+      def raise_missing_root_config
+        raise SidebarConfigError, <<~MSG.strip
+          Distributed sidebar mode requires docs/_sidebar.yml
+
+          Either:
+            1. Create docs/_sidebar.yml listing your sections
+            2. Change to 'sidebar: config' in docyard.yml
+        MSG
+      end
+
+      def raise_missing_section_config(section_slug)
+        raise SidebarConfigError, <<~MSG.strip
+          Missing sidebar config for section '#{section_slug}'
+
+          Expected: docs/#{section_slug}/_sidebar.yml
+
+          Either:
+            1. Create docs/#{section_slug}/_sidebar.yml
+            2. Remove '#{section_slug}' from docs/_sidebar.yml
+        MSG
+      end
+    end
+  end
+end

data/lib/docyard/navigation/sidebar/item.rb

@@ -3,7 +3,8 @@
 module Docyard
   module Sidebar
     class Item
-      attr_reader :slug, :text, :icon, :link, :target, :collapsed, :items, :path, :active, :type, :has_index, :section
+      attr_reader :slug, :text, :icon, :link, :target, :collapsed, :items, :path, :active, :type, :has_index, :section,
+                  :badge, :badge_type
 
       DEFAULTS = {
         target: "_self",
@@ -27,6 +28,8 @@ module Docyard
         @text = options[:text]
         @icon = options[:icon]
         @link = options[:link]
+        @badge = options[:badge]
+        @badge_type = options[:badge_type]
       end
 
       def assign_optional_attributes(options)
@@ -88,6 +91,8 @@ module Docyard
           target: target,
           has_index: has_index,
           section: section,
+          badge: badge,
+          badge_type: badge_type,
           children: children.map(&:to_h)
         }
       end

data/lib/docyard/navigation/sidebar/local_config_loader.rb

@@ -11,6 +11,7 @@ module Docyard
 
       def initialize(docs_path)
         @docs_path = docs_path
+        @key_errors = []
       end
 
       def load
@@ -31,12 +32,17 @@ module Docyard
 
       def parse_config_file
         content = YAML.load_file(config_file_path)
-        normalize_config(content)
+        items = normalize_config(content)
+        validate_items(items) if items
+        report_key_errors
+        items
       rescue Psych::SyntaxError => e
-        warn "Warning: Invalid YAML in #{config_file_path}: #{e.message}"
+        Docyard.logger.warn("Invalid YAML in #{config_file_path}: #{e.message}")
         nil
+      rescue ConfigError
+        raise
       rescue StandardError => e
-        warn "Warning: Error reading #{config_file_path}: #{e.message}"
+        Docyard.logger.warn("Error reading #{config_file_path}: #{e.message}")
         nil
       end
 
@@ -46,6 +52,66 @@ module Docyard
 
         content["items"] if content.is_a?(Hash)
       end
+
+      def validate_items(items, path_prefix: "")
+        return unless items.is_a?(Array)
+
+        items.each_with_index do |item, idx|
+          validate_item(item, "#{path_prefix}[#{idx}]")
+        end
+      end
+
+      def validate_item(item, context)
+        return unless item.is_a?(Hash)
+
+        if external_link?(item)
+          validate_external_link(item, context)
+        else
+          validate_sidebar_item(item, context)
+        end
+      end
+
+      def external_link?(item)
+        item.key?("link") || item.key?(:link)
+      end
+
+      def validate_external_link(item, context)
+        errors = Config::KeyValidator.validate(item, Config::Schema::SIDEBAR_EXTERNAL_LINK, context: context)
+        @key_errors.concat(errors)
+      end
+
+      def validate_sidebar_item(item, context)
+        slug, options = extract_slug_and_options(item)
+        return unless options.is_a?(Hash)
+
+        errors = Config::KeyValidator.validate(options, Config::Schema::SIDEBAR_ITEM, context: context)
+        @key_errors.concat(errors)
+        validate_nested_items(options, slug, context)
+      end
+
+      def extract_slug_and_options(item)
+        first_key = item.keys.first
+        if first_key.is_a?(String) && !external_link?(item)
+          [first_key, item[first_key]]
+        else
+          [nil, item]
+        end
+      end
+
+      def validate_nested_items(options, slug, context)
+        nested = options["items"] || options[:items]
+        return unless nested
+
+        nested_context = slug ? "#{context}.#{slug}" : context
+        validate_items(nested, path_prefix: nested_context)
+      end
+
+      def report_key_errors
+        return if @key_errors.empty?
+
+        messages = @key_errors.map { |e| "#{e[:context]}: #{e[:message]}" }
+        raise ConfigError, "Error in #{config_file_path}:\n#{messages.join("\n")}"
+      end
     end
   end
 end

data/lib/docyard/navigation/sidebar/renderer.rb

@@ -19,6 +19,8 @@ module Docyard
         @header_ctas = header_ctas
       end
 
+      VALID_IVAR_PATTERN = /\A[a-z_][a-z0-9_]*\z/i
+
       def render(tree)
         return "" if tree.empty?
 
@@ -32,12 +34,21 @@ module Docyard
         template_path = File.join(PARTIALS_PATH, "_#{name}.html.erb")
         template = File.read(template_path)
 
-        locals.each { |key, value| instance_variable_set("@#{key}", value) }
+        locals.each do |key, value|
+          validate_variable_name!(key)
+          instance_variable_set("@#{key}", value)
+        end
 
         erb_binding = binding
         ERB.new(template).result(erb_binding)
       end
 
+      def validate_variable_name!(name)
+        return if name.to_s.match?(VALID_IVAR_PATTERN)
+
+        raise ArgumentError, "Invalid variable name: #{name}"
+      end
+
       def render_tree_with_sections(items)
         filtered_items = items.reject { |item| item[:title]&.downcase == site_title.downcase }
         grouped = group_items_by_section(filtered_items)
@@ -112,7 +123,9 @@ module Docyard
           title: item[:title],
           active: item[:active],
           icon: item[:icon],
-          target: item[:target]
+          target: item[:target],
+          badge: item[:badge],
+          badge_type: item[:badge_type]
         )
       end
 
@@ -136,7 +149,9 @@ module Docyard
           children_html: children_html,
           icon: item[:icon],
           collapsed: item[:collapsed],
-          has_index: item[:has_index]
+          has_index: item[:has_index],
+          badge: item[:badge],
+          badge_type: item[:badge_type]
         )
       end
     end