docyard 1.0.2 → 1.1.0

data/lib/docyard/doctor/component_checker.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "component_checkers/base"
+require_relative "component_checkers/callout_checker"
+require_relative "component_checkers/tabs_checker"
+require_relative "component_checkers/cards_checker"
+require_relative "component_checkers/steps_checker"
+require_relative "component_checkers/code_group_checker"
+require_relative "component_checkers/details_checker"
+require_relative "component_checkers/badge_checker"
+require_relative "component_checkers/icon_checker"
+require_relative "component_checkers/tooltip_checker"
+require_relative "component_checkers/abbreviation_checker"
+require_relative "component_checkers/image_attrs_checker"
+require_relative "component_checkers/space_after_colons_checker"
+require_relative "component_checkers/unknown_type_checker"
+
+module Docyard
+  class Doctor
+    class ComponentChecker
+      CHECKER_CLASSES = [
+        ComponentCheckers::CalloutChecker,
+        ComponentCheckers::TabsChecker,
+        ComponentCheckers::CardsChecker,
+        ComponentCheckers::StepsChecker,
+        ComponentCheckers::CodeGroupChecker,
+        ComponentCheckers::DetailsChecker,
+        ComponentCheckers::BadgeChecker,
+        ComponentCheckers::IconChecker,
+        ComponentCheckers::TooltipChecker,
+        ComponentCheckers::AbbreviationChecker,
+        ComponentCheckers::ImageAttrsChecker,
+        ComponentCheckers::SpaceAfterColonsChecker,
+        ComponentCheckers::UnknownTypeChecker
+      ].freeze
+
+      attr_reader :docs_path
+
+      def initialize(docs_path)
+        @docs_path = docs_path
+        @checkers = CHECKER_CLASSES.map { |klass| klass.new(docs_path) }
+      end
+
+      def check_file(content, file_path)
+        @checkers.flat_map { |checker| checker.check_file(content, file_path) }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    module ComponentCheckers
+      class AbbreviationChecker < Base
+        DEFINITION_PATTERN = /^\*\[([^\]]+)\]:\s*(.+)$/
+
+        private
+
+        def docs_url
+          "https://docyard.dev/write-content/markdown/#abbreviations"
+        end
+
+        def process_content(content, relative_file)
+          content_outside_code = content_without_code_blocks(content)
+
+          definitions = extract_definitions(content_outside_code)
+          return [] if definitions.empty?
+
+          check_duplicates(definitions, relative_file) +
+            check_unused(definitions, content_outside_code, relative_file)
+        end
+
+        def content_without_code_blocks(content)
+          each_line_outside_code_blocks(content).map { |line, _| line }.join
+        end
+
+        def extract_definitions(content)
+          definitions = []
+          content.each_line.with_index(1) do |line, line_number|
+            next unless (match = line.match(DEFINITION_PATTERN))
+
+            definitions << { term: match[1], definition: match[2].strip, line: line_number }
+          end
+          definitions
+        end
+
+        def check_duplicates(definitions, relative_file)
+          seen = {}
+          definitions.filter_map do |defn|
+            if seen.key?(defn[:term])
+              build_diagnostic(
+                "ABBR_DUPLICATE",
+                "abbreviation '#{defn[:term]}' already defined on line #{seen[defn[:term]]}",
+                relative_file,
+                defn[:line]
+              )
+            else
+              seen[defn[:term]] = defn[:line]
+              nil
+            end
+          end
+        end
+
+        def check_unused(definitions, content, relative_file)
+          content_without_definitions = content.gsub(DEFINITION_PATTERN, "")
+
+          definitions.filter_map do |defn|
+            pattern = /(?<![<\w])#{Regexp.escape(defn[:term])}(?![>\w])/
+            next if content_without_definitions.match?(pattern)
+
+            build_diagnostic(
+              "ABBR_UNUSED",
+              "abbreviation '#{defn[:term]}' defined but never used",
+              relative_file,
+              defn[:line]
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    module ComponentCheckers
+      class BadgeChecker < Base
+        BADGE_PATTERN = /:badge\[([^\]]*)\](?:\{([^}]*)\})?/
+        VALID_TYPES = %w[default success warning danger].freeze
+        VALID_ATTRS = %w[type].freeze
+
+        private
+
+        def docs_url
+          "https://docyard.dev/write-content/components/badges/"
+        end
+
+        def process_content(content, relative_file)
+          each_line_outside_code_blocks(content).flat_map do |line, line_number|
+            check_badges_in_line(strip_inline_code(line), relative_file, line_number)
+          end
+        end
+
+        def check_badges_in_line(line, relative_file, line_number)
+          line.scan(BADGE_PATTERN).flat_map do |_text, attrs_string|
+            next [] if attrs_string.nil? || attrs_string.empty?
+
+            validate_badge_attrs(attrs_string, relative_file, line_number)
+          end
+        end
+
+        def validate_badge_attrs(attrs_string, relative_file, line_number)
+          attrs = parse_attrs(attrs_string)
+          diagnostics = []
+
+          diagnostics.concat(check_unknown_attrs(attrs, relative_file, line_number))
+          diagnostics.concat(check_unknown_type(attrs["type"], relative_file, line_number)) if attrs.key?("type")
+
+          diagnostics
+        end
+
+        def parse_attrs(attrs_string)
+          attrs = {}
+          attrs_string.scan(/(\w+)=["']([^"']*)["']/) do |key, value|
+            attrs[key] = value
+          end
+          attrs
+        end
+
+        def check_unknown_attrs(attrs, relative_file, line_number)
+          (attrs.keys - VALID_ATTRS).map do |attr|
+            sug = suggest(attr, VALID_ATTRS)
+            msg = "unknown badge attribute '#{attr}'"
+            msg += ", did you mean '#{sug}'?" if sug
+            fix = sug ? { type: :line_replace, from: "#{attr}=", to: "#{sug}=" } : nil
+            build_diagnostic("BADGE_UNKNOWN_ATTR", msg, relative_file, line_number, fix: fix)
+          end
+        end
+
+        def check_unknown_type(type_value, relative_file, line_number)
+          return [] if VALID_TYPES.include?(type_value)
+
+          sug = suggest(type_value, VALID_TYPES)
+          msg = "unknown badge type '#{type_value}'"
+          msg += ", did you mean '#{sug}'?" if sug
+          fix = sug ? { type: :line_replace, from: "type=\"#{type_value}\"", to: "type=\"#{sug}\"" } : nil
+          [build_diagnostic("BADGE_UNKNOWN_TYPE", msg, relative_file, line_number, fix: fix)]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "../../diagnostic_context"
+
+module Docyard
+  class Doctor
+    module ComponentCheckers
+      class Base
+        CONTAINER_PATTERN = /^:::(\w[\w-]*)/
+        CLOSE_PATTERN = /^:::\s*$/
+        CODE_FENCE_REGEX = /^(`{3,}|~{3,})/
+
+        COMPONENTS_DOCS_URL = "https://docyard.dev/write-content/components/"
+
+        attr_reader :docs_path
+
+        def initialize(docs_path)
+          @docs_path = docs_path
+        end
+
+        def check_file(content, file_path)
+          @current_file_path = file_path
+          relative_file = file_path.delete_prefix("#{docs_path}/")
+          process_content(content, relative_file)
+        end
+
+        private
+
+        def process_content(_content, _relative_file)
+          raise NotImplementedError
+        end
+
+        def parse_blocks(content)
+          blocks = []
+          open_blocks = []
+          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)
+            next if in_code_block
+
+            process_block_line(line, line_number, open_blocks, blocks)
+          end
+
+          open_blocks.each { |b| b[:closed] = false }
+          blocks + open_blocks
+        end
+
+        def process_block_line(line, line_number, open_blocks, blocks)
+          if (match = line.match(CONTAINER_PATTERN))
+            open_blocks.push({ type: match[1].downcase, line: line_number, closed: true })
+          elsif line.match?(CLOSE_PATTERN) && open_blocks.any?
+            blocks.push(open_blocks.pop)
+          end
+        end
+
+        def extract_block_content(content, start_line)
+          lines = content.lines
+          end_idx = lines[start_line..].find_index { |l| l.match?(CLOSE_PATTERN) }
+          end_idx ? lines[start_line...(start_line + end_idx)].join : nil
+        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 filter_blocks(blocks, type_filter)
+          blocks.select { |b| type_filter.is_a?(Array) ? type_filter.include?(b[:type]) : b[:type] == type_filter }
+        end
+
+        def suggest(value, dictionary)
+          DidYouMean::SpellChecker.new(dictionary: dictionary).correct(value).first
+        end
+
+        def strip_inline_code(line)
+          line.gsub(/`[^`]+`/, "")
+        end
+
+        def build_unclosed_diagnostic(prefix, block, relative_file)
+          build_diagnostic("#{prefix}_UNCLOSED", "unclosed :::#{block[:type]} block", relative_file, block[:line])
+        end
+
+        def build_diagnostic(code, message, file, line, fix: nil)
+          source_context = DiagnosticContext.extract_source_context(@current_file_path, line)
+
+          Diagnostic.new(
+            severity: :warning,
+            category: :COMPONENT,
+            code: code,
+            message: message,
+            file: file,
+            line: line,
+            fix: fix,
+            doc_url: docs_url,
+            source_context: source_context
+          )
+        end
+
+        def docs_url
+          COMPONENTS_DOCS_URL
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    module ComponentCheckers
+      class CalloutChecker < Base
+        CALLOUT_TYPES = %w[note tip important warning danger].freeze
+
+        private
+
+        def docs_url
+          "https://docyard.dev/write-content/components/callouts/"
+        end
+
+        def process_content(content, relative_file)
+          blocks = parse_blocks(content)
+
+          filter_blocks(blocks, CALLOUT_TYPES).filter_map do |block|
+            validate_callout(block, content, relative_file)
+          end
+        end
+
+        def validate_callout(block, content, relative_file)
+          return build_unclosed_diagnostic("CALLOUT", block, relative_file) unless block[:closed]
+
+          block_content = extract_block_content(content, block[:line])
+          return nil unless block_content&.strip&.empty?
+
+          build_diagnostic("CALLOUT_EMPTY", "empty callout block", relative_file, block[:line])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    module ComponentCheckers
+      class CardsChecker < Base
+        CARD_ITEM_PATTERN = /^::card\{/
+        CARD_ATTR_PATTERN = /^::card\{([^}]*)\}/
+        CARD_VALID_ATTRS = %w[title icon href].freeze
+
+        private
+
+        def docs_url
+          "https://docyard.dev/write-content/components/cards/"
+        end
+
+        def process_content(content, relative_file)
+          blocks = parse_blocks(content)
+
+          block_diagnostics = filter_blocks(blocks, "cards").filter_map do |block|
+            validate_cards(block, content, relative_file)
+          end
+
+          block_diagnostics + check_card_attributes(content, relative_file)
+        end
+
+        def validate_cards(block, content, relative_file)
+          return build_unclosed_diagnostic("CARDS", block, relative_file) unless block[:closed]
+
+          block_content = extract_block_content(content, block[:line])
+          return nil if block_content&.match?(CARD_ITEM_PATTERN)
+
+          build_diagnostic("CARDS_EMPTY", "empty cards block, add '::card{title=\"...\"}' to define cards",
+                           relative_file, block[:line])
+        end
+
+        def check_card_attributes(content, relative_file)
+          each_line_outside_code_blocks(content).flat_map do |line, line_number|
+            next [] unless (match = line.match(CARD_ATTR_PATTERN))
+
+            validate_attrs(match[1], relative_file, line_number)
+          end
+        end
+
+        def validate_attrs(attr_string, relative_file, line_number)
+          unknown = attr_string.scan(/(\w+)=/).flatten - CARD_VALID_ATTRS
+          unknown.map do |attr|
+            sug = suggest(attr, CARD_VALID_ATTRS)
+            msg = "unknown card attribute '#{attr}'"
+            msg += ", did you mean '#{sug}'?" if sug
+            build_diagnostic("CARD_UNKNOWN_ATTR", msg, relative_file, line_number)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    module ComponentCheckers
+      class CodeGroupChecker < Base
+        CODE_BLOCK_WITH_LABEL = /^```\w*\s*\[/
+        CODE_BLOCK_START = /^```(\w+)/
+
+        private
+
+        def docs_url
+          "https://docyard.dev/write-content/components/code-groups/"
+        end
+
+        def process_content(content, relative_file)
+          blocks = parse_blocks(content)
+
+          filter_blocks(blocks, "code-group").flat_map do |block|
+            validate_code_group(block, content, relative_file)
+          end.compact
+        end
+
+        def validate_code_group(block, content, relative_file)
+          return build_unclosed_diagnostic("CODE_GROUP", block, relative_file) unless block[:closed]
+
+          block_content = extract_block_content(content, block[:line])
+          unless block_content&.match?(CODE_BLOCK_WITH_LABEL)
+            return build_diagnostic("CODE_GROUP_EMPTY", "empty code-group, add code blocks with [labels]",
+                                    relative_file, block[:line])
+          end
+
+          check_unlabeled_code_blocks(block_content, relative_file, block[:line])
+        end
+
+        def check_unlabeled_code_blocks(block_content, relative_file, start_line)
+          block_content.each_line.with_index(1).filter_map do |line, offset|
+            next unless line.match?(CODE_BLOCK_START) && !line.match?(CODE_BLOCK_WITH_LABEL)
+
+            build_diagnostic("CODE_GROUP_MISSING_LABEL", "code block missing label", relative_file,
+                             start_line + offset)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    module ComponentCheckers
+      class DetailsChecker < Base
+        DETAILS_ATTR_PATTERN = /^:::details\{([^}]*)\}/
+        DETAILS_VALID_ATTRS = %w[title open].freeze
+
+        private
+
+        def docs_url
+          "https://docyard.dev/write-content/components/accordions/"
+        end
+
+        def process_content(content, relative_file)
+          blocks = parse_blocks(content)
+
+          unclosed = filter_blocks(blocks, "details").reject { |b| b[:closed] }.map do |block|
+            build_unclosed_diagnostic("DETAILS", block, relative_file)
+          end
+
+          unclosed + check_details_attributes(content, relative_file)
+        end
+
+        def check_details_attributes(content, relative_file)
+          each_line_outside_code_blocks(content).flat_map do |line, line_number|
+            next [] unless (match = line.match(DETAILS_ATTR_PATTERN))
+
+            validate_attrs(match[1], relative_file, line_number)
+          end
+        end
+
+        def validate_attrs(attr_string, relative_file, line_number)
+          attrs = extract_attr_names(attr_string) - DETAILS_VALID_ATTRS
+          attrs.map do |attr|
+            sug = suggest(attr, DETAILS_VALID_ATTRS)
+            msg = "unknown details attribute '#{attr}'"
+            msg += ", did you mean '#{sug}'?" if sug
+            build_diagnostic("DETAILS_UNKNOWN_ATTR", msg, relative_file, line_number)
+          end
+        end
+
+        def extract_attr_names(attr_string)
+          cleaned = attr_string.gsub(/"[^"]*"/, "")
+          cleaned.scan(/(\w+)(?:=|\s|$)/).flatten
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    module ComponentCheckers
+      class IconChecker < Base
+        ICON_PATTERN = /:([a-z][a-z0-9-]*):([a-z]+):/i
+        VALID_WEIGHTS = %w[regular bold fill light thin duotone].freeze
+
+        private
+
+        def docs_url
+          "https://docyard.dev/write-content/components/icons/"
+        end
+
+        def process_content(content, relative_file)
+          each_line_outside_code_blocks(content).flat_map do |line, line_number|
+            check_icons_in_line(strip_inline_code(line), relative_file, line_number)
+          end
+        end
+
+        def check_icons_in_line(line, relative_file, line_number)
+          line.scan(ICON_PATTERN).filter_map do |icon_name, weight|
+            next if VALID_WEIGHTS.include?(weight.downcase)
+
+            sug = suggest(weight.downcase, VALID_WEIGHTS)
+            msg = "unknown icon weight '#{weight}'"
+            msg += ", did you mean '#{sug}'?" if sug
+            fix = sug ? { type: :line_replace, from: ":#{icon_name}:#{weight}:", to: ":#{icon_name}:#{sug}:" } : nil
+            build_diagnostic("ICON_UNKNOWN_WEIGHT", msg, relative_file, line_number, fix: fix)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    module ComponentCheckers
+      class ImageAttrsChecker < Base
+        IMAGE_ATTRS_PATTERN = /!\[[^\]]*\]\([^)]+\)\{([^}]+)\}/
+        VALID_ATTRS = %w[caption width height nozoom].freeze
+
+        private
+
+        def docs_url
+          "https://docyard.dev/write-content/images-and-videos/"
+        end
+
+        def process_content(content, relative_file)
+          each_line_outside_code_blocks(content).flat_map do |line, line_number|
+            check_images_in_line(strip_inline_code(line), relative_file, line_number)
+          end
+        end
+
+        def check_images_in_line(line, relative_file, line_number)
+          line.scan(IMAGE_ATTRS_PATTERN).flat_map do |attrs_string,|
+            check_unknown_attrs(attrs_string, relative_file, line_number)
+          end
+        end
+
+        def check_unknown_attrs(attrs_string, relative_file, line_number)
+          attrs = extract_attr_names(attrs_string)
+          (attrs - VALID_ATTRS).map do |attr|
+            sug = suggest(attr, VALID_ATTRS)
+            msg = "unknown image attribute '#{attr}'"
+            msg += ", did you mean '#{sug}'?" if sug
+            fix = sug ? { type: :line_replace, from: "#{attr}=", to: "#{sug}=" } : nil
+            build_diagnostic("IMAGE_UNKNOWN_ATTR", msg, relative_file, line_number, fix: fix)
+          end
+        end
+
+        def extract_attr_names(attrs_string)
+          cleaned = attrs_string.gsub(/"[^"]*"/, "")
+          cleaned.scan(/(\w+)(?:=|\s|$)/).flatten
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Doctor
+    module ComponentCheckers
+      class SpaceAfterColonsChecker < Base
+        SPACE_AFTER_COLONS_PATTERN = /^(:::\s+)(\w[\w-]*)/
+
+        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 (match = line.match(SPACE_AFTER_COLONS_PATTERN))
+
+            component = match[2].downcase
+            build_space_diagnostic(component, match[1], relative_file, line_number)
+          end
+        end
+
+        def build_space_diagnostic(component, matched_prefix, relative_file, line_number)
+          if ALL_CONTAINER_TYPES.include?(component)
+            fix = { type: :line_replace, from: matched_prefix, to: ":::" }
+            build_diagnostic(
+              "COMPONENT_SPACE_AFTER_COLONS",
+              "invalid syntax '::: #{component}', did you mean ':::#{component}'?",
+              relative_file,
+              line_number,
+              fix: fix
+            )
+          else
+            sug = suggest(component, ALL_CONTAINER_TYPES)
+            msg = "unknown component '#{component}'"
+            msg += ", did you mean ':::#{sug}'?" if sug
+            fix = sug ? { type: :line_replace, from: "#{matched_prefix}#{component}", to: ":::#{sug}" } : nil
+            build_diagnostic("COMPONENT_UNKNOWN_TYPE", msg, relative_file, line_number, fix: fix)
+          end
+        end
+      end
+    end
+  end
+end

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

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