docyard 1.0.2 → 1.1.0

data/lib/docyard/config/type_validators.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Config
+    module TypeValidators
+      def validate_string(value, definition, field)
+        unless value.is_a?(String)
+          add_type_issue(field, "string", value)
+          return
+        end
+
+        validate_format(value, definition[:format], field) if definition[:format]
+      end
+
+      def validate_format(value, format, field)
+        case format
+        when :no_slashes
+          return unless value.include?("/") || value.include?("\\")
+
+          add_diagnostic(:error, field, "cannot contain slashes", got: value,
+                                                                  expected: "simple directory name like 'dist'")
+        when :starts_with_slash
+          return if value.start_with?("/")
+
+          add_diagnostic(:error, field, "must start with /", got: value,
+                                                             fix: { type: :replace, value: "/#{value}" })
+        end
+      end
+
+      def validate_boolean(value, field)
+        return if [true, false].include?(value)
+
+        fix = nil
+        if %w[true false yes no].include?(value.to_s.downcase)
+          fix = { type: :replace, value: %w[true yes].include?(value.to_s.downcase) }
+        end
+
+        add_diagnostic(:error, field, "must be true or false", got: value.inspect, fix: fix)
+      end
+
+      def validate_url(value, field)
+        return if value.nil?
+        return add_type_issue(field, "URL string", value) unless value.is_a?(String)
+        return if value.match?(%r{\Ahttps?://})
+
+        add_diagnostic(:warning, field, "should be a valid URL starting with http:// or https://", got: value)
+      end
+
+      def validate_enum(value, definition, field)
+        valid_values = definition[:values]
+        return if valid_values.include?(value)
+
+        suggestion = find_suggestion(value.to_s, valid_values)
+        fix = suggestion ? { type: :replace, value: suggestion } : nil
+
+        add_diagnostic(:error, field, "invalid value", got: value,
+                                                       expected: valid_values.join(", "), fix: fix)
+      end
+
+      def validate_hash(value, definition, field)
+        return add_type_issue(field, "hash/object", value) unless value.is_a?(Hash)
+        return unless definition[:keys]
+
+        validate_structure(value, definition[:keys], field)
+      end
+
+      def validate_array(value, definition, field)
+        return add_type_issue(field, "array", value) unless value.is_a?(Array)
+
+        validate_array_max_items(value, definition, field)
+        validate_array_items(value, definition, field)
+      end
+
+      def validate_array_max_items(value, definition, field)
+        return unless definition[:max_items] && value.size > definition[:max_items]
+
+        add_diagnostic(:error, field, "has too many items", got: "#{value.size} items",
+                                                            expected: "maximum #{definition[:max_items]} items")
+      end
+
+      def validate_array_items(value, definition, field)
+        return unless definition[:items]
+
+        value.each_with_index do |item, index|
+          validate_field(item, definition[:items], "#{field}[#{index}]")
+        end
+      end
+
+      def validate_file_or_url(value, field)
+        return if value.nil?
+        return add_type_issue(field, "file path or URL", value) unless value.is_a?(String)
+        return if value.match?(%r{\Ahttps?://})
+        return if File.exist?(value)
+
+        public_dir = File.join(@source_dir, "public")
+        file_path = File.join(public_dir, value)
+        return if File.exist?(file_path)
+
+        add_diagnostic(:error, field, "file not found", got: value,
+                                                        expected: "file in #{public_dir}/ or a URL")
+      end
+
+      def validate_hex_color(value, field)
+        return if value.nil?
+        return add_type_issue(field, "hex color string", value) unless value.is_a?(String)
+        return if value.match?(/\A#[0-9a-fA-F]{3}\z/) || value.match?(/\A#[0-9a-fA-F]{6}\z/)
+
+        add_diagnostic(:error, field, "invalid hex color format", got: value,
+                                                                  expected: "#RGB or #RRGGBB format (e.g., #3b82f6)")
+      end
+
+      def validate_color(value, field)
+        return if value.nil?
+        return if value.is_a?(String)
+        return if value.is_a?(Hash)
+
+        add_type_issue(field, "color string or {light:, dark:} hash", value)
+      end
+    end
+  end
+end

data/lib/docyard/config/validator.rb

@@ -1,102 +1,177 @@
 # frozen_string_literal: true
 
-require_relative "validation_helpers"
 require_relative "schema"
-require_relative "key_validator"
-require_relative "validators/section"
-require_relative "validators/navigation"
+require_relative "type_validators"
+require_relative "../diagnostic_context"
 
 module Docyard
   class Config
     class Validator
-      include ValidationHelpers
-      include Validators::Section
-      include Validators::Navigation
+      include TypeValidators
 
-      def initialize(config_data)
-        @config = config_data
-        @errors = []
-        @key_errors = []
+      VALIDATORS_WITH_DEFINITION = %i[string enum hash array].freeze
+      CONFIG_DOCS_URL = "https://docyard.dev/reference/configuration/"
+
+      attr_reader :diagnostics
+
+      def initialize(data, source_dir: "docs")
+        @data = data
+        @source_dir = source_dir
+        @config_path = File.join(source_dir, "docyard.yml")
+        @config_path = "docyard.yml" unless File.exist?(@config_path)
+        @diagnostics = []
+      end
+
+      def validate_all
+        @diagnostics = []
+        validate_unknown_keys(@data, Schema::DEFINITION, "docyard.yml")
+        validate_structure(@data, Schema::DEFINITION, "")
+        validate_cross_field_rules
+        @diagnostics
       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
+      def errors
+        @diagnostics.select(&:error?)
+      end
+
+      def warnings
+        @diagnostics.select(&:warning?)
+      end
 
-        raise_key_errors if @key_errors.any?
-        raise ConfigError, format_errors if @errors.any?
+      def fixable_issues
+        @diagnostics.select(&:fixable?)
       end
 
       private
 
-      def validate_unknown_keys
-        validate_top_level_keys
-        validate_section_keys
-        validate_array_item_keys
+      def validate_unknown_keys(data, schema, context, allow_extra: false)
+        return unless data.is_a?(Hash)
+
+        check_unknown_keys(data, schema, context, allow_extra)
+        validate_nested_hash_keys(data, schema, context)
       end
 
-      def validate_top_level_keys
-        @key_errors.concat(KeyValidator.validate(@config, Schema::TOP_LEVEL, context: "docyard.yml"))
+      def check_unknown_keys(data, schema, context, allow_extra)
+        return if allow_extra
+
+        valid_keys = schema.keys.map(&:to_s)
+        data.each_key do |key|
+          next if valid_keys.include?(key.to_s)
+
+          add_unknown_key_issue(context, key, valid_keys)
+        end
       end
 
-      def validate_section_keys
-        Schema::SECTIONS.each do |section, valid_keys|
-          next unless @config[section].is_a?(Hash)
+      def validate_nested_hash_keys(data, schema, context)
+        schema.each do |key, definition|
+          next unless nested_hash_definition?(definition)
+          next unless data[key.to_s].is_a?(Hash)
 
-          @key_errors.concat(KeyValidator.validate(@config[section], valid_keys, context: section))
+          nested_context = build_context(context, key)
+          nested_allow_extra = definition[:allow_extra_keys] || false
+          validate_unknown_keys(data[key.to_s], definition[:keys], nested_context, allow_extra: nested_allow_extra)
         end
       end
 
-      def validate_array_item_keys
-        validate_tabs_keys
-        validate_cta_keys
-        validate_announcement_button_keys
+      def nested_hash_definition?(definition)
+        definition.is_a?(Hash) && definition[:type] == :hash && definition[:keys]
       end
 
-      def validate_tabs_keys
-        tabs = @config["tabs"]
-        return unless tabs.is_a?(Array)
+      def build_context(prefix, key)
+        prefix.empty? || prefix == "docyard.yml" ? key.to_s : "#{prefix}.#{key}"
+      end
+
+      def validate_structure(data, schema, prefix)
+        schema.each do |key, definition|
+          field = build_context(prefix, key)
+          value = data.is_a?(Hash) ? data[key.to_s] : nil
+          validate_field(value, definition, field)
+        end
+      end
 
-        tabs.each_with_index do |tab, idx|
-          @key_errors.concat(KeyValidator.validate(tab, Schema::TAB, context: "tabs[#{idx}]"))
+      def validate_field(value, definition, field)
+        if value.nil? && definition[:required]
+          add_diagnostic(:error, field, "is required")
+          return
         end
+
+        return if value.nil?
+
+        validate_type(value, definition, field)
       end
 
-      def validate_cta_keys
-        cta = @config.dig("navigation", "cta")
-        return unless cta.is_a?(Array)
+      def validate_type(value, definition, field)
+        return if value.nil?
+
+        type = definition[:type]
+        validator_method = :"validate_#{type}"
+        return unless respond_to?(validator_method, true)
 
-        cta.each_with_index do |item, idx|
-          @key_errors.concat(KeyValidator.validate(item, Schema::CTA, context: "navigation.cta[#{idx}]"))
+        if VALIDATORS_WITH_DEFINITION.include?(type)
+          send(validator_method, value, definition, field)
+        else
+          send(validator_method, value, field)
         end
       end
 
-      def validate_announcement_button_keys
-        button = @config.dig("announcement", "button")
-        return unless button.is_a?(Hash)
+      def validate_cross_field_rules
+        validate_feedback_requires_analytics
+      end
+
+      def validate_feedback_requires_analytics
+        feedback = @data["feedback"]
+        return unless feedback.is_a?(Hash) && feedback["enabled"] == true
+
+        analytics = @data["analytics"]
+        return if analytics.is_a?(Hash) && analytics.values.any?
+
+        add_diagnostic(:error, "feedback.enabled", "requires analytics to be configured",
+                       expected: "configure google, plausible, fathom, or script in analytics section")
+      end
+
+      def add_diagnostic(severity, field, message, got: nil, expected: nil, fix: nil)
+        line = DiagnosticContext.find_yaml_key_line(@config_path, field)
+        source_context = DiagnosticContext.extract_source_context(@config_path, line) if line
+
+        @diagnostics << Diagnostic.new(
+          severity: severity,
+          category: :CONFIG,
+          code: "CONFIG_VALIDATION",
+          file: "docyard.yml",
+          line: line,
+          field: field,
+          message: message,
+          details: build_details(got, expected),
+          fix: fix,
+          doc_url: CONFIG_DOCS_URL,
+          source_context: source_context
+        )
+      end
 
-        @key_errors.concat(KeyValidator.validate(button, Schema::ANNOUNCEMENT_BUTTON, context: "announcement.button"))
+      def build_details(got, expected)
+        details = {}
+        details[:got] = got if got
+        details[:expected] = expected if expected
+        details.empty? ? nil : details
       end
 
-      def raise_key_errors
-        messages = @key_errors.map { |e| "#{e[:context]}: #{e[:message]}" }
-        raise ConfigError, "Error in docyard.yml:\n#{messages.join("\n")}"
+      def add_type_issue(field, expected_type, value)
+        add_diagnostic(:error, field, "must be a #{expected_type}", got: value.class.name)
+      end
+
+      def add_unknown_key_issue(context, key, valid_keys)
+        field = context == "docyard.yml" ? key.to_s : "#{context}.#{key}"
+        suggestion = find_suggestion(key.to_s, valid_keys.map(&:to_s))
+        message = "unknown key"
+        message += ", did you mean '#{suggestion}'?" if suggestion
+        fix = suggestion ? { type: :rename, from: key.to_s, to: suggestion } : nil
+
+        add_diagnostic(:error, field, message, fix: fix)
       end
 
-      def format_errors
-        errors_text = @errors.map do |err|
-          "   Field: #{err[:field]}\n   Error: #{err[:error]}\n   Got: #{err[:got]}\n   Fix: #{err[:fix]}"
-        end.join("\n\n")
-        "Error in docyard.yml:\n\n#{errors_text}"
+      def find_suggestion(key, valid_keys)
+        checker = DidYouMean::SpellChecker.new(dictionary: valid_keys)
+        checker.correct(key).first
       end
     end
   end

data/lib/docyard/config.rb

@@ -2,15 +2,12 @@
 
 require "yaml"
 require_relative "config/section"
-require_relative "config/schema"
 require_relative "config/validator"
 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" => "",
@@ -22,7 +19,7 @@ module Docyard
       "socials" => {},
       "tabs" => [],
       "sidebar" => "config",
-      "build" => { "output" => "dist", "base" => "/" },
+      "build" => { "output" => "dist", "base" => "/", "strict" => false },
       "search" => { "enabled" => true, "placeholder" => "Search...", "exclude" => [] },
       "navigation" => { "cta" => [], "breadcrumbs" => true },
       "announcement" => nil,
@@ -42,7 +39,6 @@ module Docyard
       @project_root = project_root
       @file_path = File.join(project_root, "docyard.yml")
       @data = load_config_data
-      validate!
     end
 
     def file_exists?
@@ -60,10 +56,6 @@ module Docyard
     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"])
@@ -96,9 +88,5 @@ module Docyard
       message += " at line #{error.line}" if error.respond_to?(:line)
       message
     end
-
-    def validate!
-      Validator.new(data).validate!
-    end
   end
 end

data/lib/docyard/diagnostic.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Diagnostic
+    CATEGORIES = %i[CONFIG SIDEBAR CONTENT COMPONENT SYNTAX LINK IMAGE ORPHAN].freeze
+    SEVERITIES = %i[error warning].freeze
+
+    attr_reader :severity, :category, :code, :message, :file, :line, :field, :details, :fix,
+                :doc_url, :source_context
+
+    def initialize(severity:, category:, code:, message:, file: nil, line: nil, field: nil,
+                   details: nil, fix: nil, doc_url: nil, source_context: nil)
+      validate_severity!(severity)
+      validate_category!(category)
+
+      @severity = severity.to_sym
+      @category = category.to_sym
+      @code = code.to_s
+      @message = message
+      @file = file
+      @line = line
+      @field = field
+      @details = details
+      @fix = fix
+      @doc_url = doc_url
+      @source_context = source_context
+
+      freeze
+    end
+
+    def error?
+      severity == :error
+    end
+
+    def warning?
+      severity == :warning
+    end
+
+    def fixable?
+      fix.is_a?(Hash) && !fix[:type].nil?
+    end
+
+    def location
+      return "#{file}:#{field}" if file && field
+      return "#{file}:#{line}" if file && line
+      return field if field
+      return file if file
+
+      nil
+    end
+
+    def format_line
+      loc = location&.ljust(26) || (" " * 26)
+      prefix = error? ? "error" : "warn "
+      suffix = fixable? ? " [fixable]" : ""
+      "    #{prefix}   #{loc} #{message}#{suffix}"
+    end
+
+    def to_h
+      {
+        severity: severity,
+        category: category,
+        code: code,
+        message: message,
+        file: file,
+        line: line,
+        field: field,
+        details: details,
+        fix: fix,
+        doc_url: doc_url,
+        source_context: source_context
+      }.compact
+    end
+
+    private
+
+    def validate_severity!(severity)
+      return if SEVERITIES.include?(severity.to_sym)
+
+      raise ArgumentError, "Invalid severity: #{severity}. Must be one of: #{SEVERITIES.join(', ')}"
+    end
+
+    def validate_category!(category)
+      return if CATEGORIES.include?(category.to_sym)
+
+      raise ArgumentError, "Invalid category: #{category}. Must be one of: #{CATEGORIES.join(', ')}"
+    end
+  end
+end

data/lib/docyard/diagnostic_context.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Docyard
+  module DiagnosticContext
+    CONTEXT_LINES = 2
+
+    class << self
+      def find_yaml_key_line(file_path, key_path)
+        return nil unless File.exist?(file_path)
+
+        lines = File.readlines(file_path)
+        target_key = key_path.to_s.split(".").last
+
+        lines.each_with_index do |line, index|
+          next if line.strip.empty? || line.strip.start_with?("#")
+
+          return index + 1 if line_contains_key?(line, target_key)
+        end
+
+        nil
+      end
+
+      def extract_source_context(file_path, line_number, context_lines: CONTEXT_LINES)
+        return nil unless file_path && line_number && File.exist?(file_path)
+
+        lines = File.readlines(file_path)
+        return nil if line_number < 1 || line_number > lines.length
+
+        start_line = [line_number - context_lines, 1].max
+        end_line = [line_number + context_lines, lines.length].min
+
+        (start_line..end_line).map do |num|
+          {
+            line: num,
+            content: lines[num - 1].chomp,
+            highlighted: num == line_number
+          }
+        end
+      end
+
+      private
+
+      def line_contains_key?(line, key)
+        line.match?(/^\s*#{Regexp.escape(key)}:/) || line.match?(/^\s*-\s*#{Regexp.escape(key)}:?(\s|$)/)
+      end
+    end
+  end
+end

data/lib/docyard/doctor/code_block_checker.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    class CodeBlockChecker
+      CODE_FENCE_START = /^(`{3,}|~{3,})(\w*)(.*)$/
+      CODE_FENCE_END = /^(`{3,}|~{3,})\s*$/
+      VALID_OPTIONS = %w[line-numbers no-line-numbers].freeze
+      OPTION_PATTERN = /:(\S+)/
+      HIGHLIGHT_PATTERN = /\{([^}]+)\}/
+      VALID_HIGHLIGHT = /^\d+(-\d+)?(,\s*\d+(-\d+)?)*$/
+      INLINE_MARKER_PATTERN = /\[!code\s+([^\]]+)\]/
+      VALID_INLINE_MARKERS = %w[++ -- focus error warning].freeze
+
+      CODE_BLOCKS_DOCS_URL = "https://docyard.dev/write-content/components/code-blocks/"
+
+      attr_reader :docs_path
+
+      def initialize(docs_path)
+        @docs_path = docs_path
+      end
+
+      def check_file(content, file_path)
+        relative_file = file_path.delete_prefix("#{docs_path}/")
+
+        [
+          check_fence_options(content, relative_file),
+          check_inline_markers(content, relative_file)
+        ].flatten
+      end
+
+      private
+
+      def check_fence_options(content, relative_file)
+        diagnostics = []
+        in_code_block = false
+
+        content.each_line.with_index(1) do |line, line_number|
+          if !in_code_block && (match = line.match(CODE_FENCE_START))
+            in_code_block = true
+            diagnostics.concat(validate_fence_line(match, relative_file, line_number))
+          elsif in_code_block && line.match?(CODE_FENCE_END)
+            in_code_block = false
+          end
+        end
+
+        diagnostics
+      end
+
+      def validate_fence_line(match, relative_file, line_number)
+        options_part = match[3]
+
+        [
+          validate_option(options_part, relative_file, line_number),
+          validate_highlights(options_part, relative_file, line_number)
+        ].flatten
+      end
+
+      def validate_option(options_part, relative_file, line_number)
+        match = options_part.match(OPTION_PATTERN)
+        return [] unless match
+
+        option = match[1]
+        base_option = option.split("=").first
+        return [] if valid_option?(base_option)
+
+        suggestion = suggest(base_option, VALID_OPTIONS)
+        message = "unknown code block option ':#{base_option}'"
+        message += ", did you mean ':#{suggestion}'?" if suggestion
+
+        [build_diagnostic("CODE_BLOCK_UNKNOWN_OPTION", message, relative_file, line_number)]
+      end
+
+      def valid_option?(option)
+        VALID_OPTIONS.include?(option) || option.match?(/^line-numbers=\d+$/)
+      end
+
+      def validate_highlights(options_part, relative_file, line_number)
+        match = options_part.match(HIGHLIGHT_PATTERN)
+        return [] unless match
+
+        highlight_content = match[1].gsub(/\s/, "")
+        return [] if highlight_content.match?(VALID_HIGHLIGHT)
+
+        [build_diagnostic("CODE_BLOCK_INVALID_HIGHLIGHT", "invalid highlight syntax '{#{match[1]}}'", relative_file,
+                          line_number)]
+      end
+
+      def check_inline_markers(content, relative_file)
+        diagnostics = []
+        in_code_block = false
+
+        content.each_line.with_index(1) do |line, line_number|
+          if !in_code_block && line.match?(CODE_FENCE_START)
+            in_code_block = true
+          elsif in_code_block && line.match?(CODE_FENCE_END)
+            in_code_block = false
+          elsif in_code_block
+            diagnostics.concat(validate_inline_markers(line, relative_file, line_number))
+          end
+        end
+
+        diagnostics
+      end
+
+      def validate_inline_markers(line, relative_file, line_number)
+        line.scan(INLINE_MARKER_PATTERN).filter_map do |match|
+          marker = match[0].strip
+          next if VALID_INLINE_MARKERS.include?(marker)
+
+          suggestion = suggest(marker, VALID_INLINE_MARKERS)
+          message = "unknown inline marker '[!code #{marker}]'"
+          message += ", did you mean '[!code #{suggestion}]'?" if suggestion
+
+          build_diagnostic("CODE_BLOCK_UNKNOWN_MARKER", message, relative_file, line_number)
+        end
+      end
+
+      def suggest(value, dictionary)
+        DidYouMean::SpellChecker.new(dictionary: dictionary).correct(value).first
+      end
+
+      def build_diagnostic(code, message, file, line)
+        Diagnostic.new(
+          severity: :warning,
+          category: :COMPONENT,
+          code: code,
+          message: message,
+          file: file,
+          line: line,
+          doc_url: CODE_BLOCKS_DOCS_URL
+        )
+      end
+    end
+  end
+end