docyard 0.6.0 → 0.8.0

data/lib/docyard/components/processors/callout_processor.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "../../rendering/icons"
+require_relative "../../rendering/renderer"
+require_relative "../base_processor"
+require "kramdown"
+require "kramdown-parser-gfm"
+
+module Docyard
+  module Components
+    module Processors
+      class CalloutProcessor < BaseProcessor
+        self.priority = 10
+
+        CALLOUT_TYPES = {
+          "note" => { title: "Note", icon: "info", color: "note" },
+          "tip" => { title: "Tip", icon: "lightbulb", color: "tip" },
+          "important" => { title: "Important", icon: "warning-circle", color: "important" },
+          "warning" => { title: "Warning", icon: "warning", color: "warning" },
+          "danger" => { title: "Danger", icon: "siren", color: "danger" }
+        }.freeze
+
+        GITHUB_ALERT_TYPES = {
+          "NOTE" => "note",
+          "TIP" => "tip",
+          "IMPORTANT" => "important",
+          "WARNING" => "warning",
+          "CAUTION" => "danger"
+        }.freeze
+
+        def preprocess(markdown)
+          process_container_syntax(markdown)
+        end
+
+        def postprocess(html)
+          process_github_alerts(html)
+        end
+
+        private
+
+        def process_container_syntax(markdown)
+          markdown.gsub(/^:::[ \t]*(\w+)(?:[ \t]+([^\n]+?))?[ \t]*\n(.*?)^:::[ \t]*$/m) do
+            process_callout_match(Regexp.last_match(0), Regexp.last_match(1), Regexp.last_match(2),
+                                  Regexp.last_match(3))
+          end
+        end
+
+        def process_callout_match(original_match, type_raw, custom_title, content_markdown)
+          type = type_raw.downcase
+          return original_match unless CALLOUT_TYPES.key?(type)
+
+          config = CALLOUT_TYPES[type]
+          title = determine_title(custom_title, config[:title])
+          content_html = render_markdown_content(content_markdown.strip)
+
+          wrap_in_nomarkdown(render_callout_html(type, title, content_html, config[:icon]))
+        end
+
+        def determine_title(custom_title, default_title)
+          title = custom_title&.strip
+          title.nil? || title.empty? ? default_title : title
+        end
+
+        def render_markdown_content(content_markdown)
+          return "" if content_markdown.empty?
+
+          Kramdown::Document.new(
+            content_markdown,
+            input: "GFM",
+            hard_wrap: false,
+            syntax_highlighter: "rouge"
+          ).to_html
+        end
+
+        def wrap_in_nomarkdown(html)
+          "{::nomarkdown}\n#{html}\n{:/nomarkdown}"
+        end
+
+        def process_github_alerts(html)
+          github_alert_regex = %r{
+            <blockquote>\s*
+            <p>\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*
+            (?:<br\s*/>)?\s*
+            (.*?)</p>
+            (.*?)
+            </blockquote>
+          }mx
+
+          html.gsub(github_alert_regex) do
+            process_github_alert_match(Regexp.last_match(1), Regexp.last_match(2), Regexp.last_match(3))
+          end
+        end
+
+        def process_github_alert_match(alert_type, first_para, rest_content)
+          type = GITHUB_ALERT_TYPES[alert_type]
+          config = CALLOUT_TYPES[type]
+          content_html = combine_alert_content(first_para.strip, rest_content.strip)
+
+          render_callout_html(type, config[:title], content_html, config[:icon])
+        end
+
+        def combine_alert_content(first_para, rest_content)
+          return "<p>#{first_para}</p>" if rest_content.empty?
+
+          "<p>#{first_para}</p>#{rest_content}"
+        end
+
+        def render_callout_html(type, title, content_html, icon_name)
+          icon_svg = Icons.render(icon_name, "duotone") || ""
+          renderer = Renderer.new
+
+          renderer.render_partial(
+            "_callout", {
+              type: type,
+              title: title,
+              content_html: content_html,
+              icon_svg: icon_svg
+            }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/processors/code_block_diff_preprocessor.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+require_relative "../support/code_block/patterns"
+
+module Docyard
+  module Components
+    module Processors
+      class CodeBlockDiffPreprocessor < BaseProcessor
+        include Support::CodeBlock::Patterns
+
+        self.priority = 6
+
+        CODE_BLOCK_REGEX = /^```(\w*).*?\n(.*?)^```/m
+        TABS_BLOCK_REGEX = /^:::[ \t]*tabs[ \t]*\n.*?^:::[ \t]*$/m
+
+        def preprocess(content)
+          context[:code_block_diff_lines] ||= []
+          context[:code_block_error_lines] ||= []
+          context[:code_block_warning_lines] ||= []
+          @block_index = 0
+          @tabs_ranges = find_tabs_ranges(content)
+
+          content.gsub(CODE_BLOCK_REGEX) { |_| process_code_block(Regexp.last_match) }
+        end
+
+        private
+
+        def process_code_block(match)
+          return match[0] if inside_tabs?(match.begin(0))
+
+          result = extract_all_markers(match[2])
+          store_extracted_markers(result)
+          @block_index += 1
+          match[0].sub(match[2], result[:cleaned_content])
+        end
+
+        def store_extracted_markers(result)
+          context[:code_block_diff_lines][@block_index] = result[:diff_lines]
+          context[:code_block_error_lines][@block_index] = result[:error_lines]
+          context[:code_block_warning_lines][@block_index] = result[:warning_lines]
+        end
+
+        def extract_all_markers(code_content)
+          diff_info = extract_diff_lines(code_content)
+          error_info = extract_error_lines(diff_info[:cleaned_content])
+          warning_info = extract_warning_lines(error_info[:cleaned_content])
+
+          {
+            diff_lines: diff_info[:lines],
+            error_lines: error_info[:lines],
+            warning_lines: warning_info[:lines],
+            cleaned_content: warning_info[:cleaned_content]
+          }
+        end
+
+        def extract_diff_lines(code_content)
+          extract_marker_lines(code_content, DIFF_MARKER_PATTERN) do |match|
+            diff_type = match.captures.compact.first
+            diff_type == "++" ? :addition : :deletion
+          end
+        end
+
+        def extract_error_lines(code_content)
+          extract_marker_lines(code_content, ERROR_MARKER_PATTERN) { true }
+        end
+
+        def extract_warning_lines(code_content)
+          extract_marker_lines(code_content, WARNING_MARKER_PATTERN) { true }
+        end
+
+        def extract_marker_lines(code_content, pattern)
+          lines = code_content.lines
+          marker_lines = {}
+          cleaned_lines = []
+
+          lines.each_with_index do |line, index|
+            line_num = index + 1
+
+            if (match = line.match(pattern))
+              marker_lines[line_num] = yield(match)
+              cleaned_lines << line.gsub(pattern, "")
+            else
+              cleaned_lines << line
+            end
+          end
+
+          { lines: marker_lines, cleaned_content: cleaned_lines.join }
+        end
+
+        def inside_tabs?(position)
+          @tabs_ranges.any? { |range| range.cover?(position) }
+        end
+
+        def find_tabs_ranges(content)
+          ranges = []
+          content.scan(TABS_BLOCK_REGEX) do
+            match = Regexp.last_match
+            ranges << (match.begin(0)...match.end(0))
+          end
+          ranges
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/processors/code_block_focus_preprocessor.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+
+module Docyard
+  module Components
+    module Processors
+      class CodeBlockFocusPreprocessor < BaseProcessor
+        self.priority = 7
+
+        FOCUS_MARKER_PATTERN = %r{
+          (?:
+            //\s*\[!code\s+focus\]              |
+            \#\s*\[!code\s+focus\]              |
+            /\*\s*\[!code\s+focus\]\s*\*/       |
+            --\s*\[!code\s+focus\]              |
+            <!--\s*\[!code\s+focus\]\s*-->      |
+            ;\s*\[!code\s+focus\]
+          )[^\S\n]*
+        }x
+
+        CODE_BLOCK_REGEX = /^```(\w*).*?\n(.*?)^```/m
+        TABS_BLOCK_REGEX = /^:::[ \t]*tabs[ \t]*\n.*?^:::[ \t]*$/m
+
+        def preprocess(content)
+          context[:code_block_focus_lines] ||= []
+          @block_index = 0
+          @tabs_ranges = find_tabs_ranges(content)
+
+          content.gsub(CODE_BLOCK_REGEX) { |_| process_code_block(Regexp.last_match) }
+        end
+
+        private
+
+        def process_code_block(match)
+          return match[0] if inside_tabs?(match.begin(0))
+
+          focus_info = extract_focus_lines(match[2])
+          context[:code_block_focus_lines][@block_index] = focus_info[:lines]
+          @block_index += 1
+          match[0].sub(match[2], focus_info[:cleaned_content])
+        end
+
+        def extract_focus_lines(code_content)
+          lines = code_content.lines
+          focus_lines = {}
+          cleaned_lines = []
+
+          lines.each_with_index do |line, index|
+            line_num = index + 1
+
+            if line.match?(FOCUS_MARKER_PATTERN)
+              focus_lines[line_num] = true
+              cleaned_line = line.gsub(FOCUS_MARKER_PATTERN, "")
+              cleaned_lines << cleaned_line
+            else
+              cleaned_lines << line
+            end
+          end
+
+          { lines: focus_lines, cleaned_content: cleaned_lines.join }
+        end
+
+        def inside_tabs?(position)
+          @tabs_ranges.any? { |range| range.cover?(position) }
+        end
+
+        def find_tabs_ranges(content)
+          ranges = []
+          content.scan(TABS_BLOCK_REGEX) do
+            match = Regexp.last_match
+            ranges << (match.begin(0)...match.end(0))
+          end
+          ranges
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/processors/code_block_options_preprocessor.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+
+module Docyard
+  module Components
+    module Processors
+      class CodeBlockOptionsPreprocessor < BaseProcessor
+        self.priority = 5
+
+        CODE_FENCE_REGEX = /^```(\w+)(?:\s*\[([^\]]+)\])?(:\S+)?(?:\s*\{([^}\n]+)\})?/
+        TABS_BLOCK_REGEX = /^:::[ \t]*tabs[ \t]*\n.*?^:::[ \t]*$/m
+
+        def preprocess(content)
+          context[:code_block_options] ||= []
+          @tabs_ranges = find_tabs_ranges(content)
+
+          process_code_fences(content)
+        end
+
+        private
+
+        def process_code_fences(content)
+          result = +""
+          last_end = 0
+
+          content.scan(CODE_FENCE_REGEX) do
+            match = Regexp.last_match
+            result << content[last_end...match.begin(0)]
+            result << process_fence_match(match)
+            last_end = match.end(0)
+          end
+
+          result << content[last_end..]
+        end
+
+        def process_fence_match(match)
+          store_code_block_options(match) unless inside_tabs?(match.begin(0))
+          "```#{match[1]}"
+        end
+
+        def store_code_block_options(match)
+          context[:code_block_options] << {
+            lang: match[1],
+            title: match[2],
+            option: match[3],
+            highlights: parse_highlights(match[4])
+          }
+        end
+
+        def inside_tabs?(position)
+          @tabs_ranges.any? { |range| range.cover?(position) }
+        end
+
+        def find_tabs_ranges(content)
+          ranges = []
+          content.scan(TABS_BLOCK_REGEX) do
+            match = Regexp.last_match
+            ranges << (match.begin(0)...match.end(0))
+          end
+          ranges
+        end
+
+        def parse_highlights(highlights_str)
+          return [] if highlights_str.nil? || highlights_str.strip.empty?
+
+          highlights_str.split(",").flat_map { |part| parse_highlight_part(part.strip) }.uniq.sort
+        end
+
+        def parse_highlight_part(part)
+          return (part.split("-")[0].to_i..part.split("-")[1].to_i).to_a if part.include?("-")
+
+          [part.to_i]
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/processors/code_block_processor.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require_relative "../../rendering/icons"
+require_relative "../../rendering/language_mapping"
+require_relative "../../rendering/renderer"
+require_relative "../base_processor"
+require_relative "../support/code_block/icon_detector"
+require_relative "../support/code_block/line_wrapper"
+require_relative "../support/tabs/range_finder"
+
+module Docyard
+  module Components
+    module Processors
+      class CodeBlockProcessor < BaseProcessor
+        include Support::CodeBlock::LineWrapper
+        include Utils::HtmlHelpers
+
+        self.priority = 20
+
+        CodeBlockIconDetector = Support::CodeBlock::IconDetector
+        TabsRangeFinder = Support::Tabs::RangeFinder
+
+        def postprocess(html)
+          return html unless html.include?('<div class="highlight">')
+
+          initialize_postprocess_state(html)
+          process_all_highlight_blocks(html)
+        end
+
+        private
+
+        def initialize_postprocess_state(html)
+          @block_index = 0
+          @options = context[:code_block_options] || []
+          @diff_lines = context[:code_block_diff_lines] || []
+          @focus_lines = context[:code_block_focus_lines] || []
+          @error_lines = context[:code_block_error_lines] || []
+          @warning_lines = context[:code_block_warning_lines] || []
+          @global_line_numbers = context.dig(:config, "markdown", "lineNumbers") || false
+          @tabs_ranges = TabsRangeFinder.find_ranges(html)
+        end
+
+        def process_all_highlight_blocks(html)
+          result = +""
+          last_end = 0
+
+          html.scan(%r{<div class="highlight">(.*?)</div>}m) do
+            match = Regexp.last_match
+            result << html[last_end...match.begin(0)]
+            result << process_highlight_match(match)
+            last_end = match.end(0)
+          end
+
+          result << html[last_end..]
+        end
+
+        def process_highlight_match(match)
+          if inside_tabs?(match.begin(0))
+            match[0]
+          else
+            processed = process_code_block(match[0], match[1])
+            @block_index += 1
+            processed
+          end
+        end
+
+        def process_code_block(original_html, inner_html)
+          block_data = extract_block_data(inner_html)
+          processed_html = process_html_for_highlighting(original_html, block_data)
+
+          render_code_block_with_copy(block_data.merge(html: processed_html))
+        end
+
+        def extract_block_data(inner_html)
+          opts = current_block_options
+          code_text = extract_code_text(inner_html)
+          start_line = extract_start_line(opts[:option])
+          show_line_numbers = determine_line_numbers(opts[:option])
+          title_data = CodeBlockIconDetector.detect(opts[:title], opts[:lang])
+
+          build_block_data(code_text, opts, show_line_numbers, start_line, title_data)
+        end
+
+        def current_block_options
+          block_opts = @options[@block_index] || {}
+          {
+            option: block_opts[:option],
+            title: block_opts[:title],
+            lang: block_opts[:lang],
+            highlights: block_opts[:highlights] || []
+          }
+        end
+
+        def build_block_data(code_text, opts, show_line_numbers, start_line, title_data)
+          {
+            text: code_text,
+            highlights: opts[:highlights],
+            diff_lines: @diff_lines[@block_index] || {},
+            focus_lines: @focus_lines[@block_index] || {},
+            error_lines: @error_lines[@block_index] || {},
+            warning_lines: @warning_lines[@block_index] || {},
+            show_line_numbers: show_line_numbers,
+            line_numbers: show_line_numbers ? generate_line_numbers(code_text, start_line) : [],
+            start_line: start_line,
+            title: title_data[:title],
+            icon: title_data[:icon],
+            icon_source: title_data[:icon_source]
+          }
+        end
+
+        def process_html_for_highlighting(original_html, block_data)
+          needs_wrapping = block_data[:highlights].any? || block_data[:diff_lines].any? ||
+                           block_data[:focus_lines].any? || block_data[:error_lines].any? ||
+                           block_data[:warning_lines].any?
+          return original_html unless needs_wrapping
+
+          wrap_code_block(original_html, block_data)
+        end
+
+        def determine_line_numbers(block_option)
+          return false if block_option == ":no-line-numbers"
+          return true if block_option&.start_with?(":line-numbers")
+
+          @global_line_numbers
+        end
+
+        def extract_start_line(block_option)
+          return 1 unless block_option&.include?("=")
+
+          block_option.split("=").last.to_i
+        end
+
+        def generate_line_numbers(code_text, start_line)
+          line_count = code_text.lines.count
+          line_count = 1 if line_count.zero?
+          (start_line...(start_line + line_count)).to_a
+        end
+
+        def inside_tabs?(position)
+          @tabs_ranges.any? { |range| range.cover?(position) }
+        end
+
+        def extract_code_text(html)
+          text = html.gsub(/<[^>]+>/, "")
+          text = CGI.unescapeHTML(text)
+          text.strip
+        end
+
+        def render_code_block_with_copy(block_data)
+          Renderer.new.render_partial("_code_block", template_locals(block_data))
+        end
+
+        def template_locals(block_data)
+          base_locals(block_data).merge(line_feature_locals(block_data)).merge(title_locals(block_data))
+        end
+
+        def base_locals(block_data)
+          { code_block_html: block_data[:html], code_text: escape_html_attribute(block_data[:text]),
+            copy_icon: Icons.render("copy", "regular") || "", show_line_numbers: block_data[:show_line_numbers],
+            line_numbers: block_data[:line_numbers], start_line: block_data[:start_line] }
+        end
+
+        def line_feature_locals(block_data)
+          { highlights: block_data[:highlights], diff_lines: block_data[:diff_lines],
+            focus_lines: block_data[:focus_lines], error_lines: block_data[:error_lines],
+            warning_lines: block_data[:warning_lines] }
+        end
+
+        def title_locals(block_data)
+          { title: block_data[:title], icon: block_data[:icon], icon_source: block_data[:icon_source] }
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/processors/code_snippet_import_preprocessor.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+
+module Docyard
+  module Components
+    module Processors
+      class CodeSnippetImportPreprocessor < BaseProcessor
+        EXTENSION_MAP = {
+          "rb" => "ruby",
+          "js" => "javascript",
+          "ts" => "typescript",
+          "py" => "python",
+          "yml" => "yaml",
+          "md" => "markdown",
+          "sh" => "bash",
+          "zsh" => "bash",
+          "jsx" => "jsx",
+          "tsx" => "tsx"
+        }.freeze
+
+        IMPORT_PATTERN = %r{^<<<\s+@/([^\s{#]+)(?:#([\w-]+))?(?:\{([^}]+)\})?\s*$}
+
+        self.priority = 1
+
+        def preprocess(content)
+          @docs_root = context[:docs_root] || "docs"
+          content.gsub(IMPORT_PATTERN) { |_| process_import(Regexp.last_match) }
+        end
+
+        private
+
+        def process_import(match)
+          filepath = match[1]
+          region = match[2]
+          options = match[3]
+
+          file_content = read_file(filepath)
+          return import_error(filepath, "File not found") unless file_content
+
+          file_content = extract_region(file_content, region) if region
+          return import_error(filepath, "Region '#{region}' not found") unless file_content
+
+          build_code_block(file_content, filepath, options)
+        end
+
+        def read_file(filepath)
+          full_path = File.join(@docs_root, filepath)
+          return nil unless File.exist?(full_path)
+
+          File.read(full_path)
+        end
+
+        def extract_region(content, region_name)
+          region_start = %r{^[ \t]*(?://|#|/\*)\s*#region\s+#{Regexp.escape(region_name)}\b.*$}
+          region_end = %r{^[ \t]*(?://|#|/\*|\*/)\s*#endregion\s*#{Regexp.escape(region_name)}?\b.*$}
+
+          lines = content.lines
+          start_index = lines.find_index { |line| line.match?(region_start) }
+          return nil unless start_index
+
+          end_index = lines[(start_index + 1)..].find_index { |line| line.match?(region_end) }
+          return nil unless end_index
+
+          end_index += start_index + 1
+          lines[(start_index + 1)...end_index].join
+        end
+
+        def build_code_block(content, filepath, options)
+          lang = detect_language(filepath)
+          highlights = nil
+
+          if options
+            parsed = parse_options(options)
+            lang = parsed[:lang] if parsed[:lang]
+            highlights = parsed[:highlights] if parsed[:highlights]
+          end
+
+          content = extract_line_range(content, highlights) if highlights&.include?("-") && !highlights.include?(",")
+
+          meta = build_meta_string(highlights, filepath)
+
+          "```#{lang}#{meta}\n#{content.chomp}\n```"
+        end
+
+        def parse_options(options)
+          parts = options.strip.split(/\s+/)
+          result = { highlights: nil, lang: nil }
+
+          parts.each do |part|
+            if part.match?(/^[\d,-]+$/)
+              result[:highlights] = part
+            else
+              result[:lang] = part
+            end
+          end
+
+          result
+        end
+
+        def extract_line_range(content, range_str)
+          return content unless range_str&.match?(/^\d+-\d+$/)
+
+          start_line, end_line = range_str.split("-").map(&:to_i)
+          lines = content.lines
+          lines[(start_line - 1)..(end_line - 1)]&.join || content
+        end
+
+        def build_meta_string(highlights, filepath)
+          parts = []
+          parts << " [#{File.basename(filepath)}]" if filepath
+          parts << " {#{highlights}}" if highlights && !highlights.match?(/^\d+-\d+$/)
+          parts.join
+        end
+
+        def detect_language(filepath)
+          ext = File.extname(filepath).delete_prefix(".")
+          EXTENSION_MAP[ext] || ext
+        end
+
+        def import_error(filepath, message)
+          "```\nError importing #{filepath}: #{message}\n```"
+        end
+      end
+    end
+  end
+end