docscribe 1.4.1 → 1.4.2

data/lib/docscribe/inline_rewriter/source_helpers.rb

@@ -52,44 +52,17 @@ module Docscribe
       # @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
+        lines = buffer.source.lines
+        def_line_idx = (buffer.source[0...def_bol_pos] || '').count("\n")
+        block_range = find_comment_block_range(lines, def_line_idx)
+        return nil unless block_range
 
-        # 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])
+        start_idx = block_range[:start_idx]
+        end_idx = block_range[:end_idx]
+        preserved_start_idx = find_preserved_start_idx(lines, start_idx, end_idx)
+        return nil unless doc_marker?(lines, preserved_start_idx..end_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
-        }
+        build_block_info(lines, start_idx, preserved_start_idx, end_idx)
       end
 
       # Compute the removable range for an existing doc-like block above a method.
@@ -104,35 +77,109 @@ module Docscribe
       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")
+        def_line_idx = (src[0...def_bol_pos] || '').count("\n")
+        block_range = find_comment_block_range(lines, def_line_idx)
+        return nil unless block_range
+
+        preserved_start_idx = find_preserved_start_idx(lines, block_range[:start_idx], block_range[:end_idx])
+        return nil unless doc_marker?(lines, preserved_start_idx..block_range[:end_idx])
+
+        compute_removal_range(buffer, lines, preserved_start_idx, def_bol_pos)
+      end
+
+      # Find the range of a contiguous comment block directly above a method definition.
+      #
+      # Walks upward from def_line_idx, skipping blank lines, then includes all
+      # contiguous comment lines.
+      #
+      # @note module_function: when included, also defines #find_comment_block_range (instance visibility: private)
+      # @param [Array<String>] lines
+      # @param [Integer] def_line_idx
+      # @return [Hash{start_idx: Integer, end_idx: Integer}, nil]
+      def find_comment_block_range(lines, def_line_idx)
         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])
+        { start_idx: start_idx, end_idx: i }
+      end
 
-        # If the whole block is preserved directives, there is nothing to remove
-        return nil if removable_start_idx > i
+      # Find the first index in a comment block after preserved directive-style lines.
+      #
+      # Preserved lines include RuboCop directives and Ruby magic comments.
+      #
+      # @note module_function: when included, also defines #find_preserved_start_idx (instance visibility: private)
+      # @param [Array<String>] lines
+      # @param [Integer] start_idx
+      # @param [Integer] end_idx
+      # @return [Integer]
+      def find_preserved_start_idx(lines, start_idx, end_idx)
+        idx = start_idx
+        idx += 1 while idx <= end_idx && preserved_comment_line?(lines[idx])
+        idx
+      end
 
-        # 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) }
+      # Whether a comment block range contains documentation markers.
+      #
+      # @note module_function: when included, also defines #doc_marker? (instance visibility: private)
+      # @param [Array<String>] lines
+      # @param [Range] range line index range
+      # @return [Boolean]
+      def doc_marker?(lines, range)
+        (lines[range] || []).any? { |line| doc_marker_line?(line) }
+      end
 
-        start_pos = removable_start_idx.positive? ? lines[0...removable_start_idx].join.length : 0
+      # Build block info hash from computed line ranges.
+      #
+      # @note module_function: when included, also defines #build_block_info (instance visibility: private)
+      # @param [Array<String>] lines
+      # @param [Integer] start_idx
+      # @param [Integer] preserved_start_idx
+      # @param [Integer] end_idx
+      # @return [Hash]
+      def build_block_info(lines, start_idx, preserved_start_idx, end_idx)
+        positions = compute_positions(lines, start_idx, preserved_start_idx, end_idx)
+        {
+          lines: lines[start_idx..end_idx],
+          preserved_lines: lines[start_idx...preserved_start_idx],
+          doc_lines: lines[preserved_start_idx..end_idx],
+          **positions
+        }
+      end
+
+      # Compute the removal range for preserved start position.
+      #
+      # @note module_function: when included, also defines #compute_removal_range (instance visibility: private)
+      # @param [Parser::Source::Buffer] buffer
+      # @param [Array<String>] lines
+      # @param [Integer] preserved_start_idx
+      # @param [Integer] def_bol_pos
+      # @return [Parser::Source::Range]
+      def compute_removal_range(buffer, lines, preserved_start_idx, def_bol_pos)
+        start_pos = preserved_start_idx.positive? ? (lines[0...preserved_start_idx] || []).join.length : 0
         Parser::Source::Range.new(buffer, start_pos, def_bol_pos)
       end
 
+      # Compute source positions for a comment block.
+      #
+      # @note module_function: when included, also defines #compute_positions (instance visibility: private)
+      # @param [Array<String>] lines
+      # @param [Integer] start_idx
+      # @param [Integer] doc_start_idx
+      # @param [Integer] end_pos_idx
+      # @return [Hash{start_pos: Integer, doc_start_pos: Integer, end_pos: Integer}]
+      def compute_positions(lines, start_idx, doc_start_idx, end_pos_idx)
+        start_pos = start_idx.positive? ? (lines[0...start_idx] || []).join.length : 0
+        doc_start_pos = doc_start_idx.positive? ? (lines[0...doc_start_idx] || []).join.length : 0
+        end_pos = (lines[0..end_pos_idx] || []).join.length
+        { start_pos: start_pos, doc_start_pos: doc_start_pos, end_pos: end_pos }
+      end
+
       # Whether a comment line should be preserved during aggressive replacement.
       #
       # Preserved lines include:
@@ -191,14 +238,15 @@ module Docscribe
       #
       # This helper is retained for compatibility/legacy behavior checks.
       #
-      # @note module_function: when included, also defines #already_has_doc_immediately_above? (instance visibility: private)
+      # @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")
+        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?

data/lib/docscribe/inline_rewriter/tag_sorter.rb

@@ -64,26 +64,45 @@ module Docscribe
       # @param [Array<String>] lines
       # @return [Array<Hash>]
       def parse_segments(lines)
-        segments = []
+        segments = [] #: Array[untyped]
         i = 0
 
-        while i < lines.length
-          line = lines[i]
+        i = advance_parse(lines, i, segments) while i < lines.length
+
+        segments
+      end
 
-          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
+      # Parse the next line as either a tag run or non-tag content, appending to segments.
+      #
+      # @note module_function: when included, also defines #advance_parse (instance visibility: private)
+      # @param [Array<String>] lines comment block lines
+      # @param [Integer] idx current parse index
+      # @param [Array<Hash>] segments accumulated parsed segments
+      # @return [Integer] new index after processing
+      def advance_parse(lines, idx, segments)
+        if top_level_tag_line?(lines[idx])
+          consume_tag_run(lines, idx, segments)
+        else
+          segments << { type: :other, lines: [lines[idx]] }
+          idx + 1
         end
+      end
 
-        segments
+      # Consume a contiguous tag run and append to segments.
+      #
+      # @note module_function: when included, also defines #consume_tag_run (instance visibility: private)
+      # @param [Array<String>] lines
+      # @param [Integer] idx current index
+      # @param [Array<Hash>] segments accumulated segments
+      # @return [Integer] new index after consuming the run
+      def consume_tag_run(lines, idx, segments)
+        entries = [] #: Array[untyped]
+        while idx < lines.length && top_level_tag_line?(lines[idx])
+          entry, idx = consume_entry(lines, idx)
+          entries << entry
+        end
+        segments << { type: :tag_run, entries: entries }
+        idx
       end
 
       # Sort one parsed segment if it is a tag run.
@@ -124,29 +143,51 @@ module Docscribe
       def consume_entry(lines, start_idx)
         first = lines[start_idx]
         tag = extract_tag_name(first)
-        entry_lines = [first]
-        i = start_idx + 1
+        entry_lines = collect_continuation_lines(lines, start_idx + 1)
+        i = entry_lines.length + start_idx
 
-        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 = build_entry(tag, entry_lines, first, start_idx)
 
-          entry_lines << line
-          i += 1
-        end
+        [entry, i]
+      end
 
-        entry = Entry.new(
+      # Build an Entry struct from parsed tag name, lines, and source line metadata.
+      #
+      # @note module_function: when included, also defines #build_entry (instance visibility: private)
+      # @param [String, nil] tag the extracted tag name
+      # @param [Array<String>] entry_lines all lines belonging to this entry
+      # @param [String] first the first (tag) line
+      # @param [Integer] start_idx original index of the first line
+      # @return [Entry]
+      def build_entry(tag, entry_lines, first, start_idx)
+        Entry.new(
           tag: tag,
           lines: entry_lines,
           param_name: extract_param_name(first),
           option_owner: extract_option_owner(first),
           index: start_idx
         )
+      end
 
-        [entry, i]
+      # Collect continuation lines following a top-level tag entry.
+      #
+      # @note module_function: when included, also defines #collect_continuation_lines (instance visibility: private)
+      # @param [Array<String>] lines
+      # @param [Integer] start_idx
+      # @return [Array<String>]
+      def collect_continuation_lines(lines, start_idx)
+        result = [] #: Array[String]
+        i = start_idx
+
+        while i < lines.length
+          line = lines[i]
+          break if top_level_tag_line?(line) || blank_comment_line?(line) || !comment_line?(line)
+
+          result << line
+          i += 1
+        end
+
+        result
       end
 
       # Group entries so `@option` tags remain attached to their owning `@param`.
@@ -155,34 +196,54 @@ module Docscribe
       # @param [Array<Entry>] entries
       # @return [Array<Array<Entry>>]
       def group_entries(entries)
-        groups = []
+        groups = [] #: Array[untyped]
         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
+          groups << group_entry(entries, i)
+          i += 1
         end
 
         groups
       end
 
+      # Group a single entry, attaching any subsequent @option entries if it is a @param.
+      #
+      # @note module_function: when included, also defines #group_entry (instance visibility: private)
+      # @param [Array<Entry>] entries parsed tag entries
+      # @param [Integer] idx index of the entry to group
+      # @return [Array<Entry>] the entry group
+      def group_entry(entries, idx)
+        entry = entries[idx]
+        if entry.tag == 'param'
+          [entry] + collect_option_entries(entries, idx + 1, entry.param_name)
+        else
+          [entry]
+        end
+      end
+
+      # Collect `@option` entries belonging to the given param name.
+      #
+      # @note module_function: when included, also defines #collect_option_entries (instance visibility: private)
+      # @param [Array<Entry>] entries
+      # @param [Integer] start_idx
+      # @param [String] param_name
+      # @return [Array<Entry>]
+      def collect_option_entries(entries, start_idx, param_name)
+        result = [] #: Array[untyped]
+        i = start_idx
+
+        while i < entries.length &&
+              entries[i].tag == 'option' &&
+              entries[i].option_owner &&
+              entries[i].option_owner == param_name
+          result << entries[i]
+          i += 1
+        end
+
+        result
+      end
+
       # Whether a line begins a top-level tag entry.
       #
       # @note module_function: when included, also defines #top_level_tag_line? (instance visibility: private)