docscribe 1.0.0 → 1.2.0

data/lib/docscribe/inline_rewriter/source_helpers.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require 'parser/source/range'
+
+module Docscribe
+  module InlineRewriter
+    # Source-level helpers: ranges, insertion positions, indentation, and comment-block detection.
+    #
+    # These helpers operate on raw source text and parser source locations rather than Ruby semantics.
+    module SourceHelpers
+      module_function
+
+      # Extract the method name from a `:def` or `:defs` node.
+      #
+      # @note module_function: when included, also defines #node_name (instance visibility: private)
+      # @param [Parser::AST::Node] node
+      # @return [Symbol, nil]
+      def node_name(node)
+        case node.type
+        when :def then node.children[0]
+        when :defs then node.children[1]
+        end
+      end
+
+      # Return a zero-width range at the beginning of the line containing a node.
+      #
+      # Used as the insertion point for generated documentation.
+      #
+      # @note module_function: when included, also defines #line_start_range (instance visibility: private)
+      # @param [Parser::Source::Buffer] buffer
+      # @param [Parser::AST::Node] node
+      # @return [Parser::Source::Range]
+      def line_start_range(buffer, node)
+        start_pos = node.loc.expression.begin_pos
+        src = buffer.source
+        bol = start_pos <= 0 ? -1 : src.rindex("\n", start_pos - 1) || -1
+        Parser::Source::Range.new(buffer, bol + 1, bol + 1)
+      end
+
+      # Return structured information about a contiguous doc-like comment block above a method.
+      #
+      # Result includes:
+      # - all lines in the contiguous block
+      # - preserved directive prefix lines
+      # - editable doc lines
+      # - source positions for replacement
+      #
+      # Returns nil if no doc-like block is present.
+      #
+      # @note module_function: when included, also defines #doc_comment_block_info (instance visibility: private)
+      # @param [Parser::Source::Buffer] buffer
+      # @param [Integer] def_bol_pos beginning-of-line position of the target def
+      # @return [Hash, nil]
+      def doc_comment_block_info(buffer, def_bol_pos)
+        src = buffer.source
+        lines = src.lines
+        def_line_idx = src[0...def_bol_pos].count("\n")
+        i = def_line_idx - 1
+
+        # Skip blank lines directly above def
+        i -= 1 while i >= 0 && lines[i].strip.empty?
+
+        # Nearest non-blank line must be a comment
+        return nil unless i >= 0 && lines[i] =~ /^\s*#/
+
+        # Walk upward to include the entire contiguous comment block
+        end_idx = i
+        start_idx = i
+        start_idx -= 1 while start_idx >= 0 && lines[start_idx] =~ /^\s*#/
+        start_idx += 1
+
+        # Preserve leading directive-style comments
+        removable_start_idx = start_idx
+        removable_start_idx += 1 while removable_start_idx <= end_idx && preserved_comment_line?(lines[removable_start_idx])
+
+        return nil if removable_start_idx > end_idx
+
+        remaining = lines[removable_start_idx..end_idx]
+        return nil unless remaining.any? { |line| doc_marker_line?(line) }
+
+        start_pos = start_idx.positive? ? lines[0...start_idx].join.length : 0
+        doc_start_pos = removable_start_idx.positive? ? lines[0...removable_start_idx].join.length : 0
+        end_pos = lines[0..end_idx].join.length
+
+        {
+          lines: lines[start_idx..end_idx],
+          preserved_lines: lines[start_idx...removable_start_idx],
+          doc_lines: lines[removable_start_idx..end_idx],
+          start_pos: start_pos,
+          doc_start_pos: doc_start_pos,
+          end_pos: end_pos
+        }
+      end
+
+      # Compute the removable range for an existing doc-like block above a method.
+      #
+      # Preserved directive lines (such as RuboCop directives or magic comments) are excluded
+      # from the returned range.
+      #
+      # @note module_function: when included, also defines #comment_block_removal_range (instance visibility: private)
+      # @param [Parser::Source::Buffer] buffer
+      # @param [Integer] def_bol_pos beginning-of-line position of the target def
+      # @return [Parser::Source::Range, nil]
+      def comment_block_removal_range(buffer, def_bol_pos)
+        src = buffer.source
+        lines = src.lines
+        def_line_idx = src[0...def_bol_pos].count("\n")
+        i = def_line_idx - 1
+
+        # Skip blank lines directly above def
+        i -= 1 while i >= 0 && lines[i].strip.empty?
+
+        # Nearest non-blank line must be a comment to remove anything
+        return nil unless i >= 0 && lines[i] =~ /^\s*#/
+
+        # Walk upward to include the entire contiguous comment block
+        start_idx = i
+        start_idx -= 1 while start_idx >= 0 && lines[start_idx] =~ /^\s*#/
+        start_idx += 1
+
+        # Preserve leading directive-style comments (currently: rubocop directives)
+        removable_start_idx = start_idx
+        removable_start_idx += 1 while removable_start_idx <= i && preserved_comment_line?(lines[removable_start_idx])
+
+        # If the whole block is preserved directives, there is nothing to remove
+        return nil if removable_start_idx > i
+
+        # SAFETY: only remove if the remaining block looks like documentation
+        remaining = lines[removable_start_idx..i]
+        return nil unless remaining.any? { |line| doc_marker_line?(line) }
+
+        start_pos = removable_start_idx.positive? ? lines[0...removable_start_idx].join.length : 0
+        Parser::Source::Range.new(buffer, start_pos, def_bol_pos)
+      end
+
+      # Whether a comment line should be preserved during aggressive replacement.
+      #
+      # Preserved lines include:
+      # - RuboCop directives
+      # - Ruby magic comments
+      # - tool directives such as `:nocov:` / `:stopdoc:`
+      #
+      # @note module_function: when included, also defines #preserved_comment_line? (instance visibility: private)
+      # @param [String] line
+      # @return [Boolean]
+      def preserved_comment_line?(line)
+        # RuboCop directives
+        return true if line =~ /^\s*#\s*rubocop:(disable|enable|todo)\b/
+
+        # Ruby magic comments
+        return true if line =~ /^\s*#\s*(?:frozen_string_literal|warn_indent)\s*:\s*(?:true|false)\b/i
+        return true if line =~ /^\s*#.*\b(?:encoding|coding)\s*:\s*[\w.-]+\b/i
+
+        # Tool directives like:
+        #   # :nocov:
+        #   # :stopdoc:
+        #   # :nodoc:
+        return true if line =~ /^\s*#\s*:\s*[\w-]+\s*:(?=\s|\z)/i
+
+        false
+      end
+
+      # Whether a comment line looks like documentation content.
+      #
+      # Recognized forms include:
+      # - Docscribe header lines
+      # - YARD tags/directives beginning with `@`
+      #
+      # @note module_function: when included, also defines #doc_marker_line? (instance visibility: private)
+      # @param [String] line
+      # @return [Boolean]
+      def doc_marker_line?(line)
+        # Docscribe header line:
+        #   # +A#foo+ -> Integer
+        return true if line =~ /^\s*#\s*\+\S.*\+\s*->\s*\S/
+
+        # YARD tags and directives:
+        #   # @param ...
+        #   # @return ...
+        #   # @raise ...
+        #   # @private / @protected
+        #   # @!attribute ...
+        # also matches indented attribute tag lines like:
+        #   #   @return [Type]
+        return true if line =~ /^\s*#\s*@/
+
+        false
+      end
+
+      # Whether any comment exists immediately above the insertion point.
+      #
+      # This helper is retained for compatibility/legacy behavior checks.
+      #
+      # @note module_function: when included, also defines #already_has_doc_immediately_above? (instance visibility: private)
+      # @param [Parser::Source::Buffer] buffer
+      # @param [Integer] insert_pos
+      # @return [Boolean]
+      def already_has_doc_immediately_above?(buffer, insert_pos)
+        src = buffer.source
+        lines = src.lines
+        current_line_index = src[0...insert_pos].count("\n")
+        i = current_line_index - 1
+        i -= 1 while i >= 0 && lines[i].strip.empty?
+        return false if i.negative?
+
+        !!(lines[i] =~ /^\s*#/)
+      end
+
+      # Return the indentation prefix of a node's source line.
+      #
+      # Tabs and spaces are preserved exactly.
+      #
+      # @note module_function: when included, also defines #line_indent (instance visibility: private)
+      # @param [Parser::AST::Node] node
+      # @raise [StandardError]
+      # @return [String]
+      def line_indent(node)
+        line = node.loc.expression.source_line
+        return '' unless line
+
+        # Preserve tabs/spaces exactly.
+        line[/\A[ \t]*/] || ''
+      rescue StandardError
+        ''
+      end
+    end
+  end
+end

data/lib/docscribe/inline_rewriter/tag_sorter.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module InlineRewriter
+    # Older tag-sorting helper operating on comment-line segments.
+    #
+    # This module sorts contiguous runs of top-level tag entries and keeps related `@option`
+    # entries attached to their owning `@param`.
+    #
+    # If `DocBlock` fully supersedes this module in your codebase, consider removing it.
+    module TagSorter
+      module_function
+
+      # One sortable top-level tag entry plus its continuation lines.
+      # @!attribute [rw] tag
+      #   @return [Object]
+      #   @param [Object] value
+      #
+      # @!attribute [rw] lines
+      #   @return [Object]
+      #   @param [Object] value
+      #
+      # @!attribute [rw] param_name
+      #   @return [Object]
+      #   @param [Object] value
+      #
+      # @!attribute [rw] option_owner
+      #   @return [Object]
+      #   @param [Object] value
+      #
+      # @!attribute [rw] index
+      #   @return [Object]
+      #   @param [Object] value
+      Entry = Struct.new(:tag, :lines, :param_name, :option_owner, :index, keyword_init: true)
+
+      # Sort contiguous top-level tag runs according to configured tag order.
+      #
+      # Non-tag content is preserved as-is and acts as a sort boundary.
+      #
+      # @note module_function: when included, also defines #sort (instance visibility: private)
+      # @param [Array<String>] lines comment block lines
+      # @param [Array<String>] tag_order configured tag order
+      # @return [Array<String>]
+      def sort(lines, tag_order:)
+        priority = build_priority(tag_order)
+        segments = parse_segments(lines)
+        segments.flat_map { |seg| sort_segment(seg, priority: priority) }
+      end
+
+      # Build a tag priority map from configured tag order.
+      #
+      # @note module_function: when included, also defines #build_priority (instance visibility: private)
+      # @param [Array<String>] tag_order
+      # @return [Hash{String=>Integer}]
+      def build_priority(tag_order)
+        Array(tag_order).map { |t| t.to_s.sub(/\A@/, '') }
+                        .each_with_index
+                        .to_h
+      end
+
+      # Parse lines into sortable tag-run segments and non-sortable segments.
+      #
+      # @note module_function: when included, also defines #parse_segments (instance visibility: private)
+      # @param [Array<String>] lines
+      # @return [Array<Hash>]
+      def parse_segments(lines)
+        segments = []
+        i = 0
+
+        while i < lines.length
+          line = lines[i]
+
+          if top_level_tag_line?(line)
+            entries = []
+            while i < lines.length && top_level_tag_line?(lines[i])
+              entry, i = consume_entry(lines, i)
+              entries << entry
+            end
+            segments << { type: :tag_run, entries: entries }
+          else
+            segments << { type: :other, lines: [line] }
+            i += 1
+          end
+        end
+
+        segments
+      end
+
+      # Sort one parsed segment if it is a tag run.
+      #
+      # @note module_function: when included, also defines #sort_segment (instance visibility: private)
+      # @param [Hash] segment
+      # @param [Hash{String=>Integer}] priority
+      # @return [Array<String>]
+      def sort_segment(segment, priority:)
+        return segment[:lines] unless segment[:type] == :tag_run
+
+        groups = group_entries(segment[:entries])
+
+        groups
+          .each_with_index
+          .sort_by { |(group, idx)| [group_priority(group, priority), idx] }
+          .flat_map(&:first)
+          .flat_map(&:lines)
+      end
+
+      # Compute sort priority for a grouped tag entry.
+      #
+      # @note module_function: when included, also defines #group_priority (instance visibility: private)
+      # @param [Array<Entry>] group
+      # @param [Hash{String=>Integer}] priority
+      # @return [Integer]
+      def group_priority(group, priority)
+        first = group.first
+        priority.fetch(first.tag, priority.length)
+      end
+
+      # Consume one top-level tag entry and its continuation lines.
+      #
+      # @note module_function: when included, also defines #consume_entry (instance visibility: private)
+      # @param [Array<String>] lines
+      # @param [Integer] start_idx
+      # @return [Array<(Entry, Integer)>]
+      def consume_entry(lines, start_idx)
+        first = lines[start_idx]
+        tag = extract_tag_name(first)
+        entry_lines = [first]
+        i = start_idx + 1
+
+        while i < lines.length
+          line = lines[i]
+
+          break if top_level_tag_line?(line)
+          break if blank_comment_line?(line)
+          break unless comment_line?(line)
+
+          entry_lines << line
+          i += 1
+        end
+
+        entry = Entry.new(
+          tag: tag,
+          lines: entry_lines,
+          param_name: extract_param_name(first),
+          option_owner: extract_option_owner(first),
+          index: start_idx
+        )
+
+        [entry, i]
+      end
+
+      # Group entries so `@option` tags remain attached to their owning `@param`.
+      #
+      # @note module_function: when included, also defines #group_entries (instance visibility: private)
+      # @param [Array<Entry>] entries
+      # @return [Array<Array<Entry>>]
+      def group_entries(entries)
+        groups = []
+        i = 0
+
+        while i < entries.length
+          entry = entries[i]
+
+          if entry.tag == 'param'
+            group = [entry]
+            i += 1
+
+            while i < entries.length &&
+                  entries[i].tag == 'option' &&
+                  entries[i].option_owner &&
+                  entries[i].option_owner == entry.param_name
+              group << entries[i]
+              i += 1
+            end
+
+            groups << group
+          else
+            groups << [entry]
+            i += 1
+          end
+        end
+
+        groups
+      end
+
+      # Whether a line begins a top-level tag entry.
+      #
+      # @note module_function: when included, also defines #top_level_tag_line? (instance visibility: private)
+      # @param [String] line
+      # @return [Boolean]
+      def top_level_tag_line?(line)
+        !!(line =~ /^\s*#\s*@\w+/)
+      end
+
+      # Whether a line is any comment line.
+      #
+      # @note module_function: when included, also defines #comment_line? (instance visibility: private)
+      # @param [String] line
+      # @return [Boolean]
+      def comment_line?(line)
+        !!(line =~ /^\s*#/)
+      end
+
+      # Whether a line is a blank comment separator.
+      #
+      # @note module_function: when included, also defines #blank_comment_line? (instance visibility: private)
+      # @param [String] line
+      # @return [Boolean]
+      def blank_comment_line?(line)
+        !!(line =~ /^\s*#\s*$/)
+      end
+
+      # Extract tag name from a top-level tag line without the leading `@`.
+      #
+      # @note module_function: when included, also defines #extract_tag_name (instance visibility: private)
+      # @param [String] line
+      # @return [String, nil]
+      def extract_tag_name(line)
+        line[/^\s*#\s*@(\w+)/, 1]
+      end
+
+      # Extract parameter name from a `@param` line.
+      #
+      # @note module_function: when included, also defines #extract_param_name (instance visibility: private)
+      # @param [String] line
+      # @return [String, nil]
+      def extract_param_name(line)
+        return Regexp.last_match(1) if line =~ /^\s*#\s*@param\b\s+\[[^\]]+\]\s+(\S+)/
+        return Regexp.last_match(1) if line =~ /^\s*#\s*@param\b\s+(\S+)\s+\[[^\]]+\]/
+
+        nil
+      end
+
+      # Extract owning options-hash param name from an `@option` line.
+      #
+      # @note module_function: when included, also defines #extract_option_owner (instance visibility: private)
+      # @param [String] line
+      # @return [String, nil]
+      def extract_option_owner(line)
+        line[/^\s*#\s*@option\b\s+(\S+)/, 1]
+      end
+    end
+  end
+end