docyard 1.0.2 → 1.1.0

data/lib/docyard/doctor/component_checkers/tabs_checker.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    module ComponentCheckers
+      class TabsChecker < Base
+        TAB_ITEM_PATTERN = /^==\s+.+/
+
+        private
+
+        def docs_url
+          "https://docyard.dev/write-content/components/tabs/"
+        end
+
+        def process_content(content, relative_file)
+          blocks = parse_blocks(content)
+
+          filter_blocks(blocks, "tabs").filter_map do |block|
+            validate_tabs(block, content, relative_file)
+          end
+        end
+
+        def validate_tabs(block, content, relative_file)
+          return build_unclosed_diagnostic("TABS", block, relative_file) unless block[:closed]
+
+          block_content = extract_block_content(content, block[:line])
+          return nil if block_content&.match?(TAB_ITEM_PATTERN)
+
+          build_diagnostic("TABS_EMPTY", "empty tabs block, add '== Tab Name' to define tabs", relative_file,
+                           block[:line])
+        end
+      end
+    end
+  end
+end

data/lib/docyard/doctor/component_checkers/tooltip_checker.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    module ComponentCheckers
+      class TooltipChecker < Base
+        TOOLTIP_PATTERN = /:tooltip\[([^\]]+)\]\{([^}]*)\}/
+        VALID_ATTRS = %w[description link link_text].freeze
+
+        private
+
+        def docs_url
+          "https://docyard.dev/write-content/components/tooltips/"
+        end
+
+        def process_content(content, relative_file)
+          each_line_outside_code_blocks(content).flat_map do |line, line_number|
+            check_tooltips_in_line(strip_inline_code(line), relative_file, line_number)
+          end
+        end
+
+        def check_tooltips_in_line(line, relative_file, line_number)
+          line.scan(TOOLTIP_PATTERN).flat_map do |_term, attrs_string|
+            validate_tooltip_attrs(attrs_string, relative_file, line_number)
+          end
+        end
+
+        def validate_tooltip_attrs(attrs_string, relative_file, line_number)
+          attrs = parse_attrs(attrs_string)
+          diagnostics = []
+
+          diagnostics << missing_description_diagnostic(relative_file, line_number) unless attrs.key?("description")
+          diagnostics.concat(check_unknown_attrs(attrs.keys, relative_file, line_number))
+
+          diagnostics
+        end
+
+        def parse_attrs(attrs_string)
+          attrs = {}
+          attrs_string.scan(/(\w+)="([^"]*)"/) do |key, value|
+            attrs[key] = value
+          end
+          attrs
+        end
+
+        def missing_description_diagnostic(relative_file, line_number)
+          build_diagnostic(
+            "TOOLTIP_MISSING_DESCRIPTION",
+            "tooltip missing required 'description' attribute",
+            relative_file,
+            line_number
+          )
+        end
+
+        def check_unknown_attrs(attr_names, relative_file, line_number)
+          (attr_names - VALID_ATTRS).map do |attr|
+            sug = suggest(attr, VALID_ATTRS)
+            msg = "unknown tooltip attribute '#{attr}'"
+            msg += ", did you mean '#{sug}'?" if sug
+            fix = sug ? { type: :line_replace, from: "#{attr}=", to: "#{sug}=" } : nil
+            build_diagnostic("TOOLTIP_UNKNOWN_ATTR", msg, relative_file, line_number, fix: fix)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docyard/doctor/component_checkers/unknown_type_checker.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    module ComponentCheckers
+      class UnknownTypeChecker < Base
+        CALLOUT_TYPES = %w[note tip important warning danger].freeze
+        KNOWN_COMPONENTS = %w[tabs cards steps code-group details].freeze
+        ALL_CONTAINER_TYPES = (CALLOUT_TYPES + KNOWN_COMPONENTS).freeze
+
+        private
+
+        def process_content(content, relative_file)
+          each_line_outside_code_blocks(content).filter_map do |line, line_number|
+            next unless (m = line.match(CONTAINER_PATTERN))
+
+            type = m[1].downcase
+            next if ALL_CONTAINER_TYPES.include?(type)
+
+            build_unknown_type_diagnostic(type, m[1], relative_file, line_number)
+          end
+        end
+
+        def build_unknown_type_diagnostic(type, original_type, relative_file, line_number)
+          sug = suggest(type, ALL_CONTAINER_TYPES)
+          msg = "unknown component ':::#{type}'"
+          msg += ", did you mean ':::#{sug}'?" if sug
+          fix = sug ? { type: :line_replace, from: ":::#{original_type}", to: ":::#{sug}" } : nil
+          build_diagnostic("COMPONENT_UNKNOWN_TYPE", msg, relative_file, line_number, fix: fix)
+        end
+      end
+    end
+  end
+end

data/lib/docyard/doctor/config_checker.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    class ConfigChecker
+      attr_reader :config
+
+      def initialize(config)
+        @config = config
+      end
+
+      def check
+        validator = Config::Validator.new(config.data, source_dir: config.source)
+        validator.validate_all
+        validator.diagnostics
+      end
+    end
+  end
+end

data/lib/docyard/doctor/config_fixer.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    class ConfigFixer
+      attr_reader :fixed_issues
+
+      def initialize(config_path = "docyard.yml")
+        @config_path = config_path
+        @fixed_issues = []
+      end
+
+      def fix(issues)
+        fixable = issues.select(&:fixable?)
+        return if fixable.empty?
+        return unless File.exist?(@config_path)
+
+        lines = File.readlines(@config_path)
+        fixable.each { |issue| attempt_fix(lines, issue) }
+        File.write(@config_path, lines.join)
+      end
+
+      def fixed_count
+        @fixed_issues.size
+      end
+
+      private
+
+      def attempt_fix(lines, issue)
+        case issue.fix[:type]
+        when :replace then fix_replace(lines, issue)
+        when :rename then fix_rename(lines, issue)
+        end
+      end
+
+      def fix_replace(lines, issue)
+        key = issue.field.split(".").last
+        old_val = normalize_value(extract_got_value(issue))
+        new_val = format_value(issue.fix[:value])
+
+        index = find_line_index(lines, key, old_val)
+        return unless index
+
+        lines[index] = lines[index].sub(/:\s*.*$/, ": #{new_val}\n")
+        @fixed_issues << issue
+      end
+
+      def extract_got_value(diagnostic)
+        diagnostic.details&.dig(:got)
+      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(from_key, to_key)
+        @fixed_issues << issue
+      end
+
+      def find_line_index(lines, key, old_val)
+        lines.find_index do |line|
+          line =~ /^(\s*)#{Regexp.escape(key)}:\s*/ && line.include?(old_val.to_s)
+        end
+      end
+
+      def normalize_value(val)
+        return val unless val.is_a?(String)
+
+        val.gsub(/^"|"$/, "")
+      end
+
+      def format_value(val)
+        case val
+        when true then "true"
+        when false then "false"
+        when String
+          val.start_with?("/") ? "\"#{val}\"" : val
+        else
+          val.to_s
+        end
+      end
+    end
+  end
+end

data/lib/docyard/doctor/content_checker.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    class ContentChecker
+      FRONTMATTER_REGEX = /\A---\s*\n(.*?\n)---\s*\n/m
+      INCLUDE_PATTERN = /<!--\s*@include:\s*([^\s]+)\s*-->/
+      SNIPPET_PATTERN = %r{^<<<\s+@/([^\s{#]+)(?:#([\w-]+))?(?:\{([^}]+)\})?\s*$}
+      CODE_FENCE_REGEX = /^(`{3,}|~{3,})/
+      MARKDOWN_EXTENSIONS = %w[.md .markdown .mdx].freeze
+
+      FRONTMATTER_DOCS_URL = "https://docyard.dev/reference/frontmatter/"
+      INCLUDES_DOCS_URL = "https://docyard.dev/write-content/includes/"
+      SNIPPETS_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_frontmatter(content, relative_file),
+          check_includes(content, file_path, relative_file),
+          check_snippets(content, relative_file)
+        ].flatten
+      end
+
+      private
+
+      def check_frontmatter(content, relative_file)
+        match = content.match(FRONTMATTER_REGEX)
+        return [] unless match
+
+        YAML.safe_load(match[1])
+        []
+      rescue Psych::SyntaxError => e
+        [build_frontmatter_diagnostic(relative_file, e)]
+      end
+
+      def build_frontmatter_diagnostic(file, error)
+        Diagnostic.new(
+          severity: :error,
+          category: :CONTENT,
+          code: "FRONTMATTER_INVALID_YAML",
+          message: "invalid YAML: #{error.problem}",
+          file: file,
+          line: error.line ? error.line + 1 : nil,
+          doc_url: FRONTMATTER_DOCS_URL
+        )
+      end
+
+      def check_includes(content, file_path, relative_file)
+        each_line_outside_code_blocks(content).filter_map do |line_content, line_number|
+          match = line_content.match(INCLUDE_PATTERN)
+          next unless match
+
+          validate_include(match[1], file_path, relative_file, line_number)
+        end
+      end
+
+      def each_line_outside_code_blocks(content)
+        return enum_for(__method__, content) unless block_given?
+
+        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 validate_include(include_path, file_path, relative_file, line_number)
+        full_path = resolve_include_path(include_path, file_path)
+
+        unless file_exists?(full_path)
+          return build_include_diagnostic(relative_file, line_number, include_path,
+                                          "file not found")
+        end
+        unless markdown_file?(include_path)
+          return build_include_diagnostic(relative_file, line_number, include_path,
+                                          "non-markdown file")
+        end
+
+        nil
+      end
+
+      def file_exists?(path)
+        path && File.exist?(path)
+      end
+
+      def resolve_include_path(include_path, current_file)
+        if include_path.start_with?("./", "../")
+          File.expand_path(include_path, File.dirname(current_file))
+        else
+          File.join(docs_path, include_path)
+        end
+      end
+
+      def markdown_file?(filepath)
+        MARKDOWN_EXTENSIONS.include?(File.extname(filepath).downcase)
+      end
+
+      def build_include_diagnostic(file, line, include_path, message)
+        Diagnostic.new(
+          severity: :error,
+          category: :CONTENT,
+          code: "INCLUDE_ERROR",
+          message: "include '#{include_path}': #{message}",
+          file: file,
+          line: line,
+          doc_url: INCLUDES_DOCS_URL
+        )
+      end
+
+      def check_snippets(content, relative_file)
+        each_line_outside_code_blocks(content).filter_map do |line_content, line_number|
+          match = line_content.match(SNIPPET_PATTERN)
+          next unless match
+
+          validate_snippet(match, relative_file, line_number)
+        end
+      end
+
+      def validate_snippet(match, relative_file, line_number)
+        filepath = match[1]
+        region = match[2]
+        full_path = File.join(docs_path, filepath)
+
+        unless File.exist?(full_path)
+          return build_snippet_diagnostic(relative_file, line_number, filepath,
+                                          "file not found")
+        end
+        if region && !region_exists?(
+          full_path, region
+        )
+          return build_snippet_diagnostic(relative_file, line_number, filepath,
+                                          "region '#{region}' not found")
+        end
+
+        nil
+      end
+
+      def region_exists?(file_path, region_name)
+        content = File.read(file_path)
+        content.match?(%r{^[ \t]*(?://|#|/\*)\s*#region\s+#{Regexp.escape(region_name)}\b})
+      end
+
+      def build_snippet_diagnostic(file, line, snippet_path, message)
+        Diagnostic.new(
+          severity: :error,
+          category: :CONTENT,
+          code: "SNIPPET_ERROR",
+          message: "snippet '#{snippet_path}': #{message}",
+          file: file,
+          line: line,
+          doc_url: SNIPPETS_DOCS_URL
+        )
+      end
+    end
+  end
+end

data/lib/docyard/doctor/file_scanner.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    class FileScanner
+      THREAD_COUNT = [Etc.nprocessors, 8].min
+
+      attr_reader :docs_path, :files_scanned, :links_checked, :images_checked
+
+      def initialize(docs_path)
+        @docs_path = docs_path
+        @files_scanned = 0
+        @links_checked = 0
+        @images_checked = 0
+        @mutex = Mutex.new
+      end
+
+      def scan
+        files = markdown_files
+        return [] if files.empty?
+
+        files.size < THREAD_COUNT ? scan_sequential(files) : scan_parallel(files)
+      end
+
+      private
+
+      def scan_sequential(files)
+        checkers = build_checkers
+        diagnostics = []
+
+        files.each do |file_path|
+          diagnostics.concat(process_file(file_path, checkers))
+        end
+
+        @files_scanned = files.size
+        collect_stats([checkers])
+        diagnostics
+      end
+
+      def scan_parallel(files)
+        queue = build_work_queue(files)
+        results = run_worker_threads(queue)
+
+        @files_scanned = files.size
+        collect_stats(results[:checkers])
+        results[:diagnostics]
+      end
+
+      def build_work_queue(files)
+        queue = Queue.new
+        files.each { |f| queue << f }
+        THREAD_COUNT.times { queue << :done }
+        queue
+      end
+
+      def run_worker_threads(queue)
+        all_checkers = []
+        all_diagnostics = []
+
+        threads = THREAD_COUNT.times.map { create_worker_thread(queue, all_checkers, all_diagnostics) }
+        threads.each(&:join)
+
+        { checkers: all_checkers, diagnostics: all_diagnostics }
+      end
+
+      def create_worker_thread(queue, all_checkers, all_diagnostics)
+        Thread.new do
+          checkers = build_checkers
+          thread_diagnostics = process_queue(queue, checkers)
+
+          @mutex.synchronize do
+            all_checkers << checkers
+            all_diagnostics.concat(thread_diagnostics)
+          end
+        end
+      end
+
+      def process_queue(queue, checkers)
+        diagnostics = []
+        while (file_path = queue.pop) != :done
+          diagnostics.concat(process_file(file_path, checkers))
+        end
+        diagnostics
+      end
+
+      def process_file(file_path, checkers)
+        content = File.read(file_path)
+        checkers.flat_map { |checker| checker.check_file(content, file_path) }
+      end
+
+      def markdown_files
+        Dir.glob(File.join(docs_path, "**", "*.md"))
+      end
+
+      def build_checkers
+        [
+          ContentChecker.new(docs_path),
+          ComponentChecker.new(docs_path),
+          CodeBlockChecker.new(docs_path),
+          LinkChecker.new(docs_path),
+          ImageChecker.new(docs_path)
+        ]
+      end
+
+      def collect_stats(checker_sets)
+        checker_sets.flatten.each do |checker|
+          @links_checked += checker.links_checked if checker.respond_to?(:links_checked)
+          @images_checked += checker.images_checked if checker.respond_to?(:images_checked)
+        end
+      end
+    end
+  end
+end

data/lib/docyard/doctor/image_checker.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "../diagnostic_context"
+
+module Docyard
+  class Doctor
+    class ImageChecker
+      MARKDOWN_IMAGE_REGEX = /!\[([^\]]*)\]\(([^)]+)\)/
+      HTML_IMAGE_REGEX = /<img[^>]+src=["']([^"']+)["']/
+      CODE_FENCE_REGEX = /^(`{3,}|~{3,})/
+      IMAGES_DOCS_URL = "https://docyard.dev/write-content/images-and-videos/"
+
+      attr_reader :docs_path, :images_checked
+
+      def initialize(docs_path)
+        @docs_path = docs_path
+        @images_checked = 0
+      end
+
+      def check_file(content, file_path)
+        relative_file = file_path.delete_prefix("#{docs_path}/")
+        file_dir = File.dirname(file_path)
+        diagnostics = []
+
+        each_line_outside_code_blocks(content) do |line, line_number|
+          diagnostics.concat(check_line_for_images(line, line_number, relative_file, file_dir))
+        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_images(line, line_number, relative_file, file_dir)
+        extract_image_paths(line).filter_map do |image_path|
+          next if external_url?(image_path)
+
+          @images_checked += 1
+          next if image_exists?(image_path, file_dir)
+
+          build_diagnostic(relative_file, line_number, image_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: :IMAGE,
+          code: "IMAGE_MISSING",
+          message: "Missing image '#{target}'",
+          file: file,
+          line: line,
+          field: target,
+          doc_url: IMAGES_DOCS_URL,
+          source_context: source_context
+        )
+      end
+
+      def extract_image_paths(line)
+        paths = []
+        line.scan(MARKDOWN_IMAGE_REGEX) { |_alt, src| paths << src }
+        line.scan(HTML_IMAGE_REGEX) { |src| paths << src.first }
+        paths
+      end
+
+      def external_url?(path)
+        path.start_with?("http://", "https://", "//")
+      end
+
+      def image_exists?(image_path, file_dir)
+        if image_path.start_with?("/")
+          absolute_image_exists?(image_path)
+        else
+          relative_image_exists?(image_path, file_dir)
+        end
+      end
+
+      def absolute_image_exists?(image_path)
+        clean_path = image_path.delete_prefix("/")
+        [
+          File.join(docs_path, clean_path),
+          File.join(docs_path, "public", clean_path)
+        ].any? { |f| File.exist?(f) }
+      end
+
+      def relative_image_exists?(image_path, file_dir)
+        File.exist?(File.expand_path(image_path, file_dir))
+      end
+    end
+  end
+end