docyard 0.9.0 → 1.0.0

data/lib/docyard/config/validation_helpers.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Config
+    module ValidationHelpers
+      private
+
+      def validate_string(value, field_name)
+        return if value.nil? || value.is_a?(String)
+
+        add_error(field: field_name, error: "must be a string", got: value.class.name, fix: "Change to a string value")
+      end
+
+      def validate_boolean(value, field_name)
+        return if [true, false].include?(value)
+
+        add_error(field: field_name, error: "must be true or false", got: value.inspect, fix: "Change to true or false")
+      end
+
+      def validate_url(value, field_name)
+        return if value.nil? || value.is_a?(String)
+
+        add_error(field: field_name, error: "must be a URL string", got: value.class.name,
+                  fix: "Change to a URL string")
+      end
+
+      def validate_array(value, field_name)
+        return if value.nil? || value.is_a?(Array)
+
+        add_array_error(field_name)
+      end
+
+      def validate_file_path_or_url(value, field_name)
+        return if value.nil?
+        return add_type_error(field_name, "file path or URL (string)", value.class.name) unless value.is_a?(String)
+        return if url?(value)
+
+        public_dir = File.join(@config["source"] || "docs", "public")
+        file_path = File.absolute_path?(value) ? value : File.join(public_dir, value)
+        return if File.exist?(file_path)
+
+        add_error(field: field_name, error: "file not found", got: value,
+                  fix: "Place the file in #{public_dir}/ directory (e.g., 'logo.svg' for #{public_dir}/logo.svg)")
+      end
+
+      def validate_no_slashes(value, field_name)
+        return if value.nil? || !value.is_a?(String)
+        return unless value.include?("/") || value.include?("\\")
+
+        add_error(field: field_name, error: "cannot contain slashes", got: value,
+                  fix: "Use a simple directory name like 'dist' or '_site'")
+      end
+
+      def validate_starts_with_slash(value, field_name)
+        return if value.nil? || value.start_with?("/")
+
+        add_error(field: field_name, error: "must start with /", got: value, fix: "Change to '/#{value}'")
+      end
+
+      def url?(value)
+        value.match?(%r{\Ahttps?://})
+      end
+
+      def add_error(error_data)
+        @errors << error_data
+      end
+
+      def add_type_error(field, expected, got)
+        add_error(field: field, error: "must be a #{expected}", got: got, fix: "Change to a #{expected}")
+      end
+
+      def add_hash_error(field)
+        add_error(field: field, error: "must be a hash", got: @config[field].class.name,
+                  fix: "Change to a hash with platform names as keys and URLs as values")
+      end
+
+      def add_array_error(field)
+        value = field.split(".").reduce(@config) { |h, k| h&.[](k) }
+        add_error(field: field, error: "must be an array", got: value.class.name, fix: "Change to an array")
+      end
+    end
+  end
+end

data/lib/docyard/config/validator.rb

@@ -1,194 +1,95 @@
 # frozen_string_literal: true
 
+require_relative "validation_helpers"
+require_relative "schema"
+require_relative "key_validator"
+require_relative "validators/section"
+require_relative "validators/navigation"
+
 module Docyard
   class Config
     class Validator
+      include ValidationHelpers
+      include Validators::Section
+      include Validators::Navigation
+
       def initialize(config_data)
         @config = config_data
         @errors = []
+        @key_errors = []
       end
 
       def validate!
+        validate_unknown_keys
         validate_top_level
         validate_branding_section
         validate_socials_section
         validate_tabs_section
+        validate_sidebar_setting
         validate_build_section
         validate_search_section
         validate_navigation_section
+        validate_announcement_section
+        validate_feedback_section
 
+        raise_key_errors if @key_errors.any?
         raise ConfigError, format_errors if @errors.any?
       end
 
       private
 
-      def validate_top_level
-        validate_string(@config["title"], "title")
-        validate_string(@config["description"], "description")
+      def validate_unknown_keys
+        validate_top_level_keys
+        validate_section_keys
+        validate_array_item_keys
       end
 
-      def validate_branding_section
-        branding = @config["branding"]
-        return unless branding
-
-        validate_file_path_or_url(branding["logo"], "branding.logo")
-        validate_file_path_or_url(branding["favicon"], "branding.favicon")
-        validate_boolean(branding["credits"], "branding.credits") if branding.key?("credits")
+      def validate_top_level_keys
+        @key_errors.concat(KeyValidator.validate(@config, Schema::TOP_LEVEL, context: "docyard.yml"))
       end
 
-      def validate_socials_section
-        socials = @config["socials"]
-        return unless socials
-        return add_hash_error("socials") unless socials.is_a?(Hash)
+      def validate_section_keys
+        Schema::SECTIONS.each do |section, valid_keys|
+          next unless @config[section].is_a?(Hash)
 
-        socials.each { |platform, url| validate_url(url, "socials.#{platform}") unless platform == "custom" }
-        validate_custom_socials(socials["custom"]) if socials.key?("custom")
+          @key_errors.concat(KeyValidator.validate(@config[section], valid_keys, context: section))
+        end
       end
 
-      def validate_custom_socials(custom)
-        return if custom.nil?
-        return add_array_error("socials.custom") unless custom.is_a?(Array)
-
-        custom.each_with_index do |item, index|
-          validate_string(item["icon"], "socials.custom[#{index}].icon")
-          validate_url(item["href"], "socials.custom[#{index}].href")
-        end
+      def validate_array_item_keys
+        validate_tabs_keys
+        validate_cta_keys
+        validate_announcement_button_keys
       end
 
-      def validate_tabs_section
+      def validate_tabs_keys
         tabs = @config["tabs"]
-        return unless tabs
-        return add_array_error("tabs") unless tabs.is_a?(Array)
+        return unless tabs.is_a?(Array)
 
-        tabs.each_with_index do |tab, index|
-          validate_string(tab["text"], "tabs[#{index}].text")
-          validate_string(tab["href"], "tabs[#{index}].href")
-          validate_boolean(tab["external"], "tabs[#{index}].external") if tab.key?("external")
+        tabs.each_with_index do |tab, idx|
+          @key_errors.concat(KeyValidator.validate(tab, Schema::TAB, context: "tabs[#{idx}]"))
         end
       end
 
-      def validate_build_section
-        build = @config["build"]
-        return unless build
-
-        validate_string(build["output"], "build.output")
-        validate_no_slashes(build["output"], "build.output")
-        validate_string(build["base"], "build.base")
-        validate_starts_with_slash(build["base"], "build.base")
-      end
-
-      def validate_search_section
-        search = @config["search"]
-        return unless search
-
-        validate_boolean(search["enabled"], "search.enabled") if search.key?("enabled")
-        validate_string(search["placeholder"], "search.placeholder") if search.key?("placeholder")
-        validate_array(search["exclude"], "search.exclude") if search.key?("exclude")
-      end
-
-      def validate_navigation_section
+      def validate_cta_keys
         cta = @config.dig("navigation", "cta")
-        return if cta.nil?
-        return add_array_error("navigation.cta") unless cta.is_a?(Array)
+        return unless cta.is_a?(Array)
 
-        validate_cta_max_count(cta)
-        validate_cta_items(cta)
-      end
-
-      def validate_cta_items(cta)
         cta.each_with_index do |item, idx|
-          validate_string(item["text"], "navigation.cta[#{idx}].text")
-          validate_string(item["href"], "navigation.cta[#{idx}].href")
-          validate_cta_variant(item["variant"], idx) if item.key?("variant")
-          validate_boolean(item["external"], "navigation.cta[#{idx}].external") if item.key?("external")
+          @key_errors.concat(KeyValidator.validate(item, Schema::CTA, context: "navigation.cta[#{idx}]"))
         end
       end
 
-      def validate_cta_max_count(cta)
-        return if cta.length <= 2
-
-        add_error(field: "navigation.cta", error: "maximum 2 CTAs allowed",
-                  got: "#{cta.length} items", fix: "Remove extra CTA items to have at most 2")
-      end
-
-      def validate_cta_variant(variant, idx)
-        return if variant.nil? || %w[primary secondary].include?(variant)
-
-        add_error(field: "navigation.cta[#{idx}].variant", error: "must be 'primary' or 'secondary'",
-                  got: variant, fix: "Change to 'primary' or 'secondary'")
-      end
-
-      def validate_string(value, field_name)
-        return if value.nil? || value.is_a?(String)
-
-        add_error(field: field_name, error: "must be a string", got: value.class.name, fix: "Change to a string value")
-      end
-
-      def validate_boolean(value, field_name)
-        return if [true, false].include?(value)
-
-        add_error(field: field_name, error: "must be true or false", got: value.inspect, fix: "Change to true or false")
-      end
-
-      def validate_url(value, field_name)
-        return if value.nil? || value.is_a?(String)
-
-        add_error(field: field_name, error: "must be a URL string",
-                  got: value.class.name, fix: "Change to a URL string")
-      end
-
-      def validate_array(value, field_name)
-        return if value.nil? || value.is_a?(Array)
-
-        add_array_error(field_name)
-      end
-
-      def validate_file_path_or_url(value, field_name)
-        return if value.nil?
-        return add_type_error(field_name, "file path or URL (string)", value.class.name) unless value.is_a?(String)
-        return if url?(value)
-
-        file_path = File.absolute_path?(value) ? value : File.join("docs/public", value)
-        return if File.exist?(file_path)
-
-        add_error(field: field_name, error: "file not found", got: value,
-                  fix: "Place the file in docs/public/ directory (e.g., 'logo.svg' for docs/public/logo.svg)")
-      end
-
-      def validate_no_slashes(value, field_name)
-        return if value.nil? || !value.is_a?(String)
-        return unless value.include?("/") || value.include?("\\")
-
-        add_error(field: field_name, error: "cannot contain slashes", got: value,
-                  fix: "Use a simple directory name like 'dist' or '_site'")
-      end
-
-      def validate_starts_with_slash(value, field_name)
-        return if value.nil? || value.start_with?("/")
-
-        add_error(field: field_name, error: "must start with /", got: value, fix: "Change to '/#{value}'")
-      end
-
-      def url?(value)
-        value.match?(%r{\Ahttps?://})
-      end
-
-      def add_error(error_data)
-        @errors << error_data
-      end
-
-      def add_type_error(field, expected, got)
-        add_error(field: field, error: "must be a #{expected}", got: got, fix: "Change to a #{expected}")
-      end
+      def validate_announcement_button_keys
+        button = @config.dig("announcement", "button")
+        return unless button.is_a?(Hash)
 
-      def add_hash_error(field)
-        add_error(field: field, error: "must be a hash", got: @config[field].class.name,
-                  fix: "Change to a hash with platform names as keys and URLs as values")
+        @key_errors.concat(KeyValidator.validate(button, Schema::ANNOUNCEMENT_BUTTON, context: "announcement.button"))
       end
 
-      def add_array_error(field)
-        value = field.split(".").reduce(@config) { |h, k| h&.[](k) }
-        add_error(field: field, error: "must be an array", got: value.class.name, fix: "Change to an array")
+      def raise_key_errors
+        messages = @key_errors.map { |e| "#{e[:context]}: #{e[:message]}" }
+        raise ConfigError, "Error in docyard.yml:\n#{messages.join("\n")}"
       end
 
       def format_errors

data/lib/docyard/config/validators/navigation.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Config
+    module Validators
+      module Navigation
+        private
+
+        def validate_navigation_section
+          cta = @config.dig("navigation", "cta")
+          return if cta.nil?
+          return add_array_error("navigation.cta") unless cta.is_a?(Array)
+
+          validate_cta_max_count(cta)
+          validate_cta_items(cta)
+        end
+
+        def validate_cta_items(cta)
+          cta.each_with_index do |item, idx|
+            validate_string(item["text"], "navigation.cta[#{idx}].text")
+            validate_string(item["href"], "navigation.cta[#{idx}].href")
+            validate_cta_variant(item["variant"], idx) if item.key?("variant")
+            validate_boolean(item["external"], "navigation.cta[#{idx}].external") if item.key?("external")
+          end
+        end
+
+        def validate_cta_max_count(cta)
+          return if cta.length <= 2
+
+          add_error(field: "navigation.cta", error: "maximum 2 CTAs allowed",
+                    got: "#{cta.length} items", fix: "Remove extra CTA items to have at most 2")
+        end
+
+        def validate_cta_variant(variant, idx)
+          return if variant.nil? || %w[primary secondary].include?(variant)
+
+          add_error(field: "navigation.cta[#{idx}].variant", error: "must be 'primary' or 'secondary'",
+                    got: variant, fix: "Change to 'primary' or 'secondary'")
+        end
+      end
+    end
+  end
+end

data/lib/docyard/config/validators/section.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Config
+    module Validators
+      module Section
+        private
+
+        def validate_top_level
+          validate_string(@config["title"], "title")
+          validate_string(@config["description"], "description")
+        end
+
+        def validate_branding_section
+          branding = @config["branding"]
+          return unless branding
+
+          validate_file_path_or_url(branding["logo"], "branding.logo")
+          validate_file_path_or_url(branding["favicon"], "branding.favicon")
+          validate_boolean(branding["credits"], "branding.credits") if branding.key?("credits")
+        end
+
+        def validate_socials_section
+          socials = @config["socials"]
+          return unless socials
+          return add_hash_error("socials") unless socials.is_a?(Hash)
+
+          socials.each { |platform, url| validate_url(url, "socials.#{platform}") unless platform == "custom" }
+          validate_custom_socials(socials["custom"]) if socials.key?("custom")
+        end
+
+        def validate_custom_socials(custom)
+          return if custom.nil?
+          return add_array_error("socials.custom") unless custom.is_a?(Array)
+
+          custom.each_with_index do |item, index|
+            validate_string(item["icon"], "socials.custom[#{index}].icon")
+            validate_url(item["href"], "socials.custom[#{index}].href")
+          end
+        end
+
+        def validate_tabs_section
+          tabs = @config["tabs"]
+          return unless tabs
+          return add_array_error("tabs") unless tabs.is_a?(Array)
+
+          tabs.each_with_index do |tab, index|
+            validate_string(tab["text"], "tabs[#{index}].text")
+            validate_string(tab["href"], "tabs[#{index}].href")
+            validate_boolean(tab["external"], "tabs[#{index}].external") if tab.key?("external")
+          end
+        end
+
+        def validate_sidebar_setting
+          sidebar = @config["sidebar"]
+          return if sidebar.nil? || Config::SIDEBAR_MODES.include?(sidebar)
+
+          add_error(
+            field: "sidebar",
+            error: "must be one of: #{Config::SIDEBAR_MODES.join(', ')}",
+            got: sidebar.inspect,
+            fix: "Change to 'config', 'auto', or 'distributed'"
+          )
+        end
+
+        def validate_build_section
+          build = @config["build"]
+          return unless build
+
+          validate_string(build["output"], "build.output")
+          validate_no_slashes(build["output"], "build.output")
+          validate_string(build["base"], "build.base")
+          validate_starts_with_slash(build["base"], "build.base")
+        end
+
+        def validate_search_section
+          search = @config["search"]
+          return unless search
+
+          validate_boolean(search["enabled"], "search.enabled") if search.key?("enabled")
+          validate_string(search["placeholder"], "search.placeholder") if search.key?("placeholder")
+          validate_array(search["exclude"], "search.exclude") if search.key?("exclude")
+        end
+
+        def validate_announcement_section
+          announcement = @config["announcement"]
+          return unless announcement.is_a?(Hash)
+
+          validate_string(announcement["text"], "announcement.text") if announcement.key?("text")
+        end
+
+        def validate_feedback_section
+          feedback = @config["feedback"]
+          return unless feedback.is_a?(Hash) && feedback["enabled"] == true
+          return if analytics_configured?
+
+          add_error(
+            field: "feedback.enabled",
+            error: "requires analytics to be configured",
+            got: "feedback enabled without analytics",
+            fix: "Configure analytics (google, plausible, fathom, or script) to collect feedback responses"
+          )
+        end
+
+        def analytics_configured?
+          analytics = @config["analytics"]
+          return false unless analytics.is_a?(Hash)
+
+          analytics["google"] || analytics["plausible"] || analytics["fathom"] || analytics["script"]
+        end
+      end
+    end
+  end
+end

data/lib/docyard/config.rb

@@ -1,36 +1,35 @@
 # frozen_string_literal: true
 
 require "yaml"
+require_relative "config/section"
+require_relative "config/schema"
 require_relative "config/validator"
-require_relative "config/constants"
+require_relative "constants"
+require_relative "utils/hash_utils"
 
 module Docyard
   class Config
+    SIDEBAR_MODES = %w[config auto distributed].freeze
+
     DEFAULT_CONFIG = {
       "title" => Constants::DEFAULT_SITE_TITLE,
       "description" => "",
-      "branding" => {
-        "logo" => nil,
-        "favicon" => nil,
-        "credits" => true,
-        "copyright" => nil
-      },
+      "url" => nil,
+      "og_image" => nil,
+      "twitter" => nil,
+      "source" => "docs",
+      "branding" => { "logo" => nil, "favicon" => nil, "credits" => true, "copyright" => nil, "color" => nil },
       "socials" => {},
       "tabs" => [],
-      "build" => {
-        "output" => "dist",
-        "base" => "/"
-      },
-      "search" => {
-        "enabled" => true,
-        "placeholder" => "Search...",
-        "exclude" => []
-      },
-      "navigation" => {
-        "cta" => [],
-        "breadcrumbs" => true
-      },
-      "announcement" => nil
+      "sidebar" => "config",
+      "build" => { "output" => "dist", "base" => "/" },
+      "search" => { "enabled" => true, "placeholder" => "Search...", "exclude" => [] },
+      "navigation" => { "cta" => [], "breadcrumbs" => true },
+      "announcement" => nil,
+      "repo" => { "url" => nil, "branch" => "main", "edit_path" => nil, "edit_link" => true,
+                  "last_updated" => true },
+      "analytics" => { "google" => nil, "plausible" => nil, "fathom" => nil, "script" => nil },
+      "feedback" => { "enabled" => false, "question" => "Was this page helpful?" }
     }.freeze
 
     attr_reader :data, :file_path
@@ -50,87 +49,50 @@ module Docyard
       File.exist?(file_path)
     end
 
-    def title
-      data["title"]
-    end
-
-    def description
-      data["description"]
-    end
-
-    def branding
-      @branding ||= ConfigSection.new(data["branding"])
-    end
-
-    def socials
-      data["socials"]
-    end
-
-    def tabs
-      data["tabs"]
-    end
-
-    def build
-      @build ||= ConfigSection.new(data["build"])
-    end
-
-    def search
-      @search ||= ConfigSection.new(data["search"])
-    end
-
-    def navigation
-      @navigation ||= ConfigSection.new(data["navigation"])
-    end
+    def title = data["title"]
+    def description = data["description"]
+    def url = data["url"]
+    def og_image = data["og_image"]
+    def twitter = data["twitter"]
+    def source = data["source"]
+    def public_dir = File.join(source, "public")
+    def socials = data["socials"]
+    def tabs = data["tabs"]
+    def sidebar = data["sidebar"]
+
+    def sidebar_config? = sidebar == "config"
+    def sidebar_auto? = sidebar == "auto"
+    def sidebar_distributed? = sidebar == "distributed"
+
+    def branding = @branding ||= Section.new(data["branding"])
+    def build = @build ||= Section.new(data["build"])
+    def search = @search ||= Section.new(data["search"])
+    def navigation = @navigation ||= Section.new(data["navigation"])
+    def repo = @repo ||= Section.new(data["repo"])
+    def analytics = @analytics ||= Section.new(data["analytics"])
+    def feedback = @feedback ||= Section.new(data["feedback"])
 
     def announcement
-      @announcement ||= data["announcement"] ? ConfigSection.new(data["announcement"]) : nil
+      @announcement ||= data["announcement"] ? Section.new(data["announcement"]) : nil
     end
 
     private
 
     def load_config_data
-      if file_exists?
-        load_and_merge_config
-      else
-        deep_dup(DEFAULT_CONFIG)
-      end
+      file_exists? ? load_and_merge_config : Utils::HashUtils.deep_dup(DEFAULT_CONFIG)
     end
 
     def load_and_merge_config
       yaml_content = YAML.load_file(file_path)
-      deep_merge(deep_dup(DEFAULT_CONFIG), yaml_content || {})
+      Utils::HashUtils.deep_merge(Utils::HashUtils.deep_dup(DEFAULT_CONFIG), yaml_content || {})
     rescue Psych::SyntaxError => e
       raise ConfigError, build_yaml_error_message(e)
     rescue StandardError => e
       raise ConfigError, "Error loading docyard.yml: #{e.message}"
     end
 
-    def deep_merge(hash1, hash2)
-      hash1.merge(hash2) do |_key, v1, v2|
-        if v2.nil?
-          v1
-        elsif v1.is_a?(Hash) && v2.is_a?(Hash)
-          deep_merge(v1, v2)
-        else
-          v2
-        end
-      end
-    end
-
-    def deep_dup(hash)
-      hash.transform_values do |value|
-        case value
-        when Hash then deep_dup(value)
-        when Array then value.map { |v| v.is_a?(Hash) ? deep_dup(v) : v }
-        else value
-        end
-      end
-    end
-
     def build_yaml_error_message(error)
-      message = "Invalid YAML in docyard.yml:\n\n"
-      message += "  #{error.message}\n\n"
-      message += "Fix: Check YAML syntax"
+      message = "Invalid YAML in docyard.yml:\n\n  #{error.message}\n\nFix: Check YAML syntax"
       message += " at line #{error.line}" if error.respond_to?(:line)
       message
     end
@@ -139,22 +101,4 @@ module Docyard
       Validator.new(data).validate!
     end
   end
-
-  class ConfigSection
-    def initialize(data)
-      @data = data || {}
-    end
-
-    def method_missing(method, *args)
-      return @data[method.to_s] if args.empty?
-
-      super
-    end
-
-    def respond_to_missing?(method, include_private = false)
-      @data.key?(method.to_s) || super
-    end
-  end
-
-  class ConfigError < StandardError; end
 end