docyard 1.0.2 → 1.1.0

data/lib/docyard/doctor/link_checker.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../diagnostic_context"
+
+module Docyard
+  class Doctor
+    class LinkChecker
+      MARKDOWN_LINK_REGEX = /\[([^\]]*)\]\(([^)]+)\)/
+      INTERNAL_LINK_REGEX = %r{^/[^/]}
+      IMAGE_EXTENSIONS = %w[.png .jpg .jpeg .gif .svg .webp .ico .bmp].freeze
+      CODE_FENCE_REGEX = /^(`{3,}|~{3,})/
+      LINKS_DOCS_URL = nil
+
+      attr_reader :docs_path, :links_checked
+
+      def initialize(docs_path)
+        @docs_path = docs_path
+        @links_checked = 0
+      end
+
+      def check_file(content, file_path)
+        relative_file = file_path.delete_prefix("#{docs_path}/")
+        diagnostics = []
+
+        each_line_outside_code_blocks(content) do |line, line_number|
+          diagnostics.concat(check_line_for_links(line, line_number, relative_file))
+        end
+
+        diagnostics
+      end
+
+      private
+
+      def each_line_outside_code_blocks(content)
+        in_code_block = false
+
+        content.each_line.with_index(1) do |line, line_number|
+          in_code_block = !in_code_block if line.match?(CODE_FENCE_REGEX)
+          yield(line, line_number) unless in_code_block
+        end
+      end
+
+      def check_line_for_links(line, line_number, relative_file)
+        line.scan(MARKDOWN_LINK_REGEX).filter_map do |_text, url|
+          next unless internal_link?(url)
+          next if image_path?(url)
+
+          @links_checked += 1
+          target_path = url.split("#").first
+          next if file_exists?(target_path)
+
+          build_diagnostic(relative_file, line_number, target_path)
+        end
+      end
+
+      def build_diagnostic(file, line, target)
+        full_path = File.join(docs_path, file)
+        source_context = DiagnosticContext.extract_source_context(full_path, line)
+
+        Diagnostic.new(
+          severity: :warning,
+          category: :LINK,
+          code: "LINK_BROKEN",
+          message: "Broken link to '#{target}'",
+          file: file,
+          line: line,
+          field: target,
+          doc_url: LINKS_DOCS_URL,
+          source_context: source_context
+        )
+      end
+
+      def internal_link?(url)
+        url.match?(INTERNAL_LINK_REGEX)
+      end
+
+      def image_path?(url)
+        IMAGE_EXTENSIONS.any? { |ext| url.downcase.end_with?(ext) }
+      end
+
+      def file_exists?(url_path)
+        clean_path = url_path.chomp("/")
+        [
+          File.join(docs_path, "#{clean_path}.md"),
+          File.join(docs_path, clean_path, "index.md"),
+          File.join(docs_path, "#{clean_path}.html")
+        ].any? { |f| File.exist?(f) }
+      end
+    end
+  end
+end

data/lib/docyard/doctor/markdown_fixer.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    class MarkdownFixer
+      attr_reader :fixed_issues
+
+      def initialize(docs_path)
+        @docs_path = docs_path
+        @fixed_issues = []
+      end
+
+      def fixed_count
+        @fixed_issues.size
+      end
+
+      def fix(diagnostics)
+        fixable = diagnostics.select(&:fixable?)
+        return if fixable.empty?
+
+        fixable.group_by(&:file).each do |file, file_diagnostics|
+          fix_file(file, file_diagnostics)
+        end
+      end
+
+      private
+
+      def fix_file(relative_file, diagnostics)
+        file_path = File.join(@docs_path, relative_file)
+        return unless File.exist?(file_path)
+
+        lines = File.readlines(file_path)
+        apply_all_fixes(lines, diagnostics)
+        File.write(file_path, lines.join)
+      end
+
+      def apply_all_fixes(lines, diagnostics)
+        diagnostics.group_by(&:line).each do |line_number, line_diagnostics|
+          next unless valid_line_number?(line_number, lines.size)
+
+          line_diagnostics.each { |d| apply_fix(lines, line_number, d) }
+        end
+      end
+
+      def valid_line_number?(line_number, total_lines)
+        line_number&.positive? && line_number <= total_lines
+      end
+
+      def apply_fix(lines, line_number, diagnostic)
+        fix = diagnostic.fix
+        return unless fix[:type] == :line_replace
+
+        index = line_number - 1
+        original_line = lines[index]
+        return unless original_line.include?(fix[:from])
+
+        lines[index] = original_line.sub(fix[:from], fix[:to])
+        @fixed_issues << diagnostic
+      end
+    end
+  end
+end

data/lib/docyard/doctor/orphan_checker.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    class OrphanChecker
+      attr_reader :docs_path, :config
+
+      def initialize(docs_path, config)
+        @docs_path = docs_path
+        @config = config
+      end
+
+      def check
+        return [] if auto_sidebar?
+
+        sidebar_pages = collect_sidebar_pages
+        return [] unless sidebar_pages
+
+        all_pages = collect_all_pages
+        orphans = all_pages - sidebar_pages
+
+        orphans.map { |file| build_diagnostic(file) }
+      end
+
+      private
+
+      def build_diagnostic(file)
+        Diagnostic.new(
+          severity: :warning,
+          category: :ORPHAN,
+          code: "ORPHAN_PAGE",
+          message: "not linked from sidebar",
+          file: file
+        )
+      end
+
+      def auto_sidebar?
+        config.sidebar == "auto"
+      end
+
+      def collect_all_pages
+        Dir.glob(File.join(docs_path, "**", "*.md"))
+          .map { |f| f.delete_prefix("#{docs_path}/") }
+          .reject { |f| f.start_with?("_") || f == "index.md" }
+      end
+
+      def collect_sidebar_pages
+        config_items = load_sidebar_config
+        return nil unless config_items
+
+        sidebar_tree = Sidebar::ConfigBuilder.new(config_items, current_path: "/").build
+        extract_paths_from_tree(sidebar_tree)
+      rescue StandardError
+        nil
+      end
+
+      def load_sidebar_config
+        Sidebar::LocalConfigLoader.new(docs_path, validate: false).load
+      end
+
+      def extract_paths_from_tree(items, collected = [])
+        items.each do |item|
+          path = item[:path]
+          collected << path_to_file(path) if path && !item[:link]
+          extract_paths_from_tree(item[:children] || [], collected)
+        end
+        collected
+      end
+
+      def path_to_file(url_path)
+        clean_path = url_path.delete_prefix("/").chomp("/")
+        return "index.md" if clean_path.empty?
+
+        if File.exist?(File.join(docs_path, clean_path, "index.md"))
+          "#{clean_path}/index.md"
+        else
+          "#{clean_path}.md"
+        end
+      end
+    end
+  end
+end

data/lib/docyard/doctor/reporter.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    class Reporter
+      CATEGORY_LABELS = {
+        CONFIG: "Configuration",
+        SIDEBAR: "Sidebar",
+        CONTENT: "Content",
+        COMPONENT: "Components",
+        SYNTAX: "Syntax",
+        LINK: "Broken links",
+        IMAGE: "Missing images",
+        ORPHAN: "Orphan pages"
+      }.freeze
+
+      CATEGORY_ORDER = %i[CONFIG SIDEBAR CONTENT COMPONENT LINK IMAGE ORPHAN SYNTAX].freeze
+
+      attr_reader :diagnostics, :stats, :fixed, :duration
+
+      def initialize(diagnostics, stats = {}, fixed: false, duration: nil)
+        @diagnostics = diagnostics
+        @stats = stats
+        @fixed = fixed
+        @duration = duration
+      end
+
+      def print
+        print_header
+        print_categories
+        print_summary
+      end
+
+      def exit_code
+        error_count.positive? ? 1 : 0
+      end
+
+      private
+
+      def print_header
+        puts
+        puts "  #{UI.bold('Docyard')} v#{VERSION}"
+        puts
+        puts "  Checking docs..."
+        puts
+      end
+
+      def print_categories
+        CATEGORY_ORDER.each do |category|
+          print_category(category)
+        end
+      end
+
+      def print_category(category)
+        items = diagnostics_for(category)
+        return if items.empty?
+
+        print_category_header(category, items)
+        items.each { |d| puts format_diagnostic(d) }
+        puts
+      end
+
+      def diagnostics_for(category)
+        diagnostics.select { |d| d.category == category }
+      end
+
+      def print_category_header(category, items)
+        label = CATEGORY_LABELS[category] || category.to_s
+        counts = issue_counts(items.count(&:error?), items.count(&:warning?))
+        puts "  #{UI.bold(label.ljust(28))} #{counts}"
+      end
+
+      def format_diagnostic(diagnostic)
+        prefix = diagnostic.error? ? UI.red("error") : UI.yellow("warn ")
+        location = diagnostic.location&.ljust(26) || (" " * 26)
+        suffix = diagnostic.fixable? ? " #{UI.cyan('[fixable]')}" : ""
+        "    #{prefix}   #{location} #{diagnostic.message}#{suffix}"
+      end
+
+      def print_summary
+        puts "  #{stats_summary}"
+
+        if error_count.zero? && warning_count.zero?
+          puts "  #{UI.success('No issues found')}"
+        else
+          puts "  #{build_issue_summary}"
+          print_fixable_hint
+        end
+
+        puts "  #{format_duration}" if duration
+        puts
+      end
+
+      def format_duration
+        if duration < 1
+          UI.dim("Finished in #{(duration * 1000).round}ms")
+        else
+          UI.dim("Finished in #{duration.round(2)}s")
+        end
+      end
+
+      def print_fixable_hint
+        return if fixed
+
+        fixable = diagnostics.count(&:fixable?)
+        return if fixable.zero?
+
+        puts
+        puts "  #{UI.cyan("Run with --fix to auto-fix #{pluralize(fixable, 'issue')}.")}"
+      end
+
+      def issue_counts(errors, warnings)
+        parts = []
+        parts << UI.red(pluralize(errors, "error")) if errors.positive?
+        parts << UI.yellow(pluralize(warnings, "warning")) if warnings.positive?
+        parts.join(", ")
+      end
+
+      def stats_summary
+        stats_parts = [
+          stat_part(:files, "file"),
+          stat_part(:links, "link"),
+          stat_part(:images, "image")
+        ].compact
+        "Checked #{stats_parts.join(', ')}"
+      end
+
+      def stat_part(key, word)
+        pluralize(stats[key], word) if stats[key]
+      end
+
+      def build_issue_summary
+        parts = []
+        parts << UI.red(pluralize(error_count, "error")) if error_count.positive?
+        parts << UI.yellow(pluralize(warning_count, "warning")) if warning_count.positive?
+        "Found #{parts.join(', ')}"
+      end
+
+      def pluralize(count, word)
+        count == 1 ? "#{count} #{word}" : "#{count} #{word}s"
+      end
+
+      def error_count
+        diagnostics.count(&:error?)
+      end
+
+      def warning_count
+        diagnostics.count(&:warning?)
+      end
+    end
+  end
+end

data/lib/docyard/doctor/sidebar_checker.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "../diagnostic_context"
+
+module Docyard
+  class Doctor
+    class SidebarChecker
+      SIDEBAR_DOCS_URL = "https://docyard.dev/customize/sidebar/"
+
+      attr_reader :docs_path
+
+      def initialize(docs_path)
+        @docs_path = docs_path
+        @sidebar_path = File.join(docs_path, "_sidebar.yml")
+      end
+
+      def check
+        loader = Sidebar::LocalConfigLoader.new(docs_path, validate: false)
+        items = loader.load
+        diagnostics = convert_key_errors(loader.key_errors)
+        diagnostics.concat(check_missing_files(items)) if items
+        diagnostics
+      end
+
+      private
+
+      def convert_key_errors(key_errors)
+        key_errors.map do |error|
+          Diagnostic.new(
+            severity: :error,
+            category: :SIDEBAR,
+            code: "SIDEBAR_VALIDATION",
+            field: "_sidebar.yml: #{error[:context]}",
+            message: error[:message],
+            fix: error[:fix]
+          )
+        end
+      end
+
+      def check_missing_files(items, path_prefix: "")
+        diagnostics = []
+        items.each do |item|
+          diagnostics.concat(check_item_file(item, path_prefix))
+        end
+        diagnostics
+      end
+
+      def check_item_file(item, path_prefix)
+        diagnostics = []
+        slug, options = extract_slug_and_options(item)
+        return diagnostics unless slug
+
+        if requires_file?(options)
+          file_path = build_file_path(path_prefix, slug, options)
+          diagnostics << build_missing_file_diagnostic(slug, path_prefix, file_path) unless file_exists?(file_path)
+        end
+
+        if options.is_a?(Hash) && options["items"]
+          nested_prefix = options["group"] ? path_prefix : File.join(path_prefix, slug)
+          diagnostics.concat(check_missing_files(options["items"], path_prefix: nested_prefix))
+        end
+
+        diagnostics
+      end
+
+      def requires_file?(options)
+        return true unless options.is_a?(Hash)
+        return true unless options["items"]
+
+        options["index"]
+      end
+
+      def extract_slug_and_options(item)
+        return [item, nil] if item.is_a?(String)
+        return [nil, nil] unless item.is_a?(Hash)
+        return [nil, nil] if external_link?(item)
+        return [nil, nil] if item.keys.size != 1
+
+        slug = item.keys.first
+        slug.is_a?(String) ? [slug, item[slug]] : [nil, nil]
+      end
+
+      def build_file_path(path_prefix, slug, options)
+        base = File.join(path_prefix, slug)
+        options.is_a?(Hash) && options["index"] ? File.join(base, "index") : base
+      end
+
+      def file_exists?(relative_path)
+        md_path = File.join(docs_path, "#{relative_path}.md")
+        index_path = File.join(docs_path, relative_path, "index.md")
+        File.exist?(md_path) || File.exist?(index_path)
+      end
+
+      def build_missing_file_diagnostic(slug, path_prefix, file_path)
+        context = path_prefix.empty? ? slug : "#{path_prefix}/#{slug}"
+        line = find_sidebar_line(slug)
+        source_context = DiagnosticContext.extract_source_context(@sidebar_path, line) if line
+
+        Diagnostic.new(
+          severity: :error,
+          category: :SIDEBAR,
+          code: "SIDEBAR_MISSING_FILE",
+          file: "_sidebar.yml",
+          line: line,
+          field: context,
+          message: "references missing file '#{file_path}.md'",
+          doc_url: SIDEBAR_DOCS_URL,
+          source_context: source_context
+        )
+      end
+
+      def find_sidebar_line(slug)
+        return nil unless File.exist?(@sidebar_path)
+
+        lines = File.readlines(@sidebar_path)
+        lines.each_with_index do |line, index|
+          return index + 1 if line.include?("- #{slug}") || line.include?("#{slug}:")
+        end
+        nil
+      end
+
+      def external_link?(item)
+        item.key?("link") || item.key?(:link)
+      end
+    end
+  end
+end

data/lib/docyard/doctor/sidebar_fixer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    class SidebarFixer
+      attr_reader :fixed_issues
+
+      def initialize(docs_path)
+        @sidebar_path = File.join(docs_path, "_sidebar.yml")
+        @fixed_issues = []
+      end
+
+      def fix(issues)
+        fixable = issues.select(&:fixable?)
+        return if fixable.empty?
+        return unless File.exist?(@sidebar_path)
+
+        lines = File.readlines(@sidebar_path)
+        fixable.each { |issue| attempt_fix(lines, issue) }
+        File.write(@sidebar_path, lines.join)
+      end
+
+      def fixed_count
+        @fixed_issues.size
+      end
+
+      private
+
+      def attempt_fix(lines, issue)
+        return unless issue.fix[:type] == :rename
+
+        fix_rename(lines, issue)
+      end
+
+      def fix_rename(lines, issue)
+        from_key = issue.fix[:from]
+        to_key = issue.fix[:to]
+
+        index = lines.find_index { |line| line =~ /^(\s*)#{Regexp.escape(from_key)}:/ }
+        return unless index
+
+        lines[index] = lines[index].sub(/#{Regexp.escape(from_key)}:/, "#{to_key}:")
+        @fixed_issues << issue
+      end
+    end
+  end
+end