docyard 0.6.0 → 0.7.0

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

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../../rendering/renderer"
+require_relative "../base_processor"
+
+module Docyard
+  module Components
+    module Processors
+      class HeadingAnchorProcessor < BaseProcessor
+        self.priority = 30
+
+        def postprocess(html)
+          add_anchor_links(html)
+        end
+
+        private
+
+        def add_anchor_links(html)
+          html.gsub(%r{<(h[2-6])\s+id="([^"]+)">(.*?)</\1>}m) do |_match|
+            tag = Regexp.last_match(1)
+            id = Regexp.last_match(2)
+            content = Regexp.last_match(3)
+
+            anchor_html = render_anchor_link(id)
+
+            "<#{tag} id=\"#{id}\">#{content}#{anchor_html}</#{tag}>"
+          end
+        end
+
+        def render_anchor_link(id)
+          renderer = Renderer.new
+          renderer.render_partial("_heading_anchor", {
+                                    id: id
+                                  })
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../../rendering/icons"
+require_relative "../base_processor"
+
+module Docyard
+  module Components
+    module Processors
+      class IconProcessor < BaseProcessor
+        self.priority = 20
+
+        ICON_PATTERN = /:([a-z][a-z0-9-]*):(?:([a-z]+):)?/i
+
+        def postprocess(html)
+          segments = split_preserving_code_blocks(html)
+
+          segments.map do |segment|
+            segment[:type] == :code ? segment[:content] : process_segment(segment[:content])
+          end.join
+        end
+
+        private
+
+        def split_preserving_code_blocks(html)
+          segments = []
+          current_pos = 0
+
+          html.scan(%r{<(code|pre)[^>]*>.*?</\1>}m) do
+            match_start = Regexp.last_match.begin(0)
+            match_end = Regexp.last_match.end(0)
+
+            segments << { type: :text, content: html[current_pos...match_start] } if match_start > current_pos
+            segments << { type: :code, content: html[match_start...match_end] }
+
+            current_pos = match_end
+          end
+
+          segments << { type: :text, content: html[current_pos..] } if current_pos < html.length
+
+          segments.empty? ? [{ type: :text, content: html }] : segments
+        end
+
+        def process_segment(content)
+          content.gsub(ICON_PATTERN) do
+            icon_name = Regexp.last_match(1)
+            weight = Regexp.last_match(2) || "regular"
+            Icons.render(icon_name, weight) || Regexp.last_match(0)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+
+module Docyard
+  module Components
+    module Processors
+      class TableOfContentsProcessor < BaseProcessor
+        self.priority = 35
+
+        def postprocess(html)
+          headings = extract_headings(html)
+          context[:toc] = headings
+          html
+        end
+
+        private
+
+        def extract_headings(html)
+          headings = []
+
+          html.scan(%r{<(h[2-4])\s+id="([^"]+)">(.*?)</\1>}m) do
+            level = Regexp.last_match(1)[1].to_i
+            id = Regexp.last_match(2)
+            text = strip_html(Regexp.last_match(3))
+
+            headings << {
+              level: level,
+              id: id,
+              text: text
+            }
+          end
+
+          build_hierarchy(headings)
+        end
+
+        def build_hierarchy(headings)
+          return [] if headings.empty?
+
+          root = []
+          stack = []
+
+          headings.each do |heading|
+            heading[:children] = []
+
+            stack.pop while stack.any? && stack.last[:level] >= heading[:level]
+
+            if stack.empty?
+              root << heading
+            else
+              stack.last[:children] << heading
+            end
+
+            stack << heading
+          end
+
+          root
+        end
+
+        def strip_html(text)
+          text.gsub(%r{<a[^>]*class="heading-anchor"[^>]*>.*?</a>}, "")
+            .gsub(/<[^>]+>/, "")
+            .strip
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+
+module Docyard
+  module Components
+    module Processors
+      class TableWrapperProcessor < BaseProcessor
+        self.priority = 100
+
+        def postprocess(html)
+          wrapped = html.gsub(/<table([^>]*)>/) do
+            attributes = Regexp.last_match(1)
+            "<div class=\"table-wrapper\"><table#{attributes}>"
+          end
+
+          wrapped.gsub("</table>", "</table></div>")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "../../rendering/renderer"
+require_relative "../base_processor"
+require_relative "../support/tabs/parser"
+require "securerandom"
+
+module Docyard
+  module Components
+    module Processors
+      class TabsProcessor < BaseProcessor
+        self.priority = 15
+
+        TabsParser = Support::Tabs::Parser
+
+        def preprocess(content)
+          return content unless content.include?(":::tabs")
+
+          content.gsub(/^:::[ \t]*tabs[ \t]*\n(.*?)^:::[ \t]*$/m) do
+            process_tabs_block(Regexp.last_match(1))
+          end
+        end
+
+        private
+
+        def process_tabs_block(tabs_content)
+          tabs = TabsParser.parse(tabs_content)
+          return "" if tabs.empty?
+
+          wrap_in_nomarkdown(render_tabs(tabs))
+        end
+
+        def render_tabs(tabs)
+          Renderer.new.render_partial(
+            "_tabs", {
+              tabs: tabs,
+              group_id: SecureRandom.hex(4)
+            }
+          )
+        end
+
+        def wrap_in_nomarkdown(html)
+          "{::nomarkdown}\n#{html}\n{:/nomarkdown}"
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/support/code_block/feature_extractor.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative "patterns"
+
+module Docyard
+  module Components
+    module Support
+      module CodeBlock
+        module FeatureExtractor
+          include Patterns
+
+          CODE_FENCE_REGEX = /^```(\w+)(?:\s*\[([^\]]+)\])?(:\S+)?(?:\s*\{([^}\n]+)\})?[ \t]*\n(.*?)^```/m
+
+          module_function
+
+          def process_markdown(markdown)
+            blocks = []
+            cleaned = markdown.gsub(CODE_FENCE_REGEX) do
+              block_data = extract_block_data(Regexp.last_match)
+              blocks << block_data
+              "```#{block_data[:lang]}\n#{block_data[:cleaned_content]}```"
+            end
+            { cleaned_markdown: cleaned, blocks: blocks }
+          end
+
+          def extract_block_data(match)
+            code_content = match[5]
+            diff_info = extract_diff_lines(code_content)
+            focus_info = extract_focus_lines(diff_info[:cleaned_content])
+            error_info = extract_error_lines(focus_info[:cleaned_content])
+            warning_info = extract_warning_lines(error_info[:cleaned_content])
+
+            build_block_result(match, diff_info, focus_info, error_info, warning_info)
+          end
+
+          def build_block_result(match, diff_info, focus_info, error_info, warning_info)
+            {
+              lang: match[1],
+              title: match[2],
+              option: match[3],
+              highlights: parse_highlights(match[4]),
+              diff_lines: diff_info[:lines],
+              focus_lines: focus_info[:lines],
+              error_lines: error_info[:lines],
+              warning_lines: warning_info[:lines],
+              cleaned_content: warning_info[:cleaned_content]
+            }
+          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
+
+          def extract_diff_lines(code_content)
+            lines = code_content.lines
+            diff_lines = {}
+            cleaned_lines = []
+
+            lines.each_with_index do |line, index|
+              line_num = index + 1
+
+              if (match = line.match(DIFF_MARKER_PATTERN))
+                diff_type = match.captures.compact.first
+                diff_lines[line_num] = diff_type == "++" ? :addition : :deletion
+                cleaned_line = line.gsub(DIFF_MARKER_PATTERN, "")
+                cleaned_lines << cleaned_line
+              else
+                cleaned_lines << line
+              end
+            end
+
+            { lines: diff_lines, cleaned_content: cleaned_lines.join }
+          end
+
+          def extract_focus_lines(code_content)
+            extract_marker_lines(code_content, FOCUS_MARKER_PATTERN)
+          end
+
+          def extract_error_lines(code_content)
+            extract_marker_lines(code_content, ERROR_MARKER_PATTERN)
+          end
+
+          def extract_warning_lines(code_content)
+            extract_marker_lines(code_content, WARNING_MARKER_PATTERN)
+          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 line.match?(pattern)
+                marker_lines[line_num] = true
+                cleaned_lines << line.gsub(pattern, "")
+              else
+                cleaned_lines << line
+              end
+            end
+
+            { lines: marker_lines, cleaned_content: cleaned_lines.join }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/support/code_block/icon_detector.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "../../../rendering/language_mapping"
+
+module Docyard
+  module Components
+    module Support
+      module CodeBlock
+        module IconDetector
+          MANUAL_ICON_PATTERN = /^:([a-z0-9-]+):\s*(.+)$/i
+
+          module_function
+
+          def detect(title, language)
+            return { title: nil, icon: nil, icon_source: nil } if title.nil?
+
+            if (match = title.match(MANUAL_ICON_PATTERN))
+              return {
+                title: match[2].strip,
+                icon: match[1],
+                icon_source: "phosphor"
+              }
+            end
+
+            icon, icon_source = auto_detect_icon(language)
+            { title: title, icon: icon, icon_source: icon_source }
+          end
+
+          def auto_detect_icon(language)
+            return [nil, nil] if language.nil?
+
+            if LanguageMapping.terminal_language?(language)
+              %w[terminal-window phosphor]
+            elsif (ext = LanguageMapping.extension_for(language))
+              [ext, "file-extension"]
+            else
+              %w[file phosphor]
+            end
+          end
+        end
+      end
+    end
+  end
+end