rubocop-prose 0.1.0

data/lib/rubocop/cop/markdown/ordered_list_numbering.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative '../../prose/list_rules'
+
+module RuboCop
+  module Cop
+    module Markdown
+      class OrderedListNumbering < Base
+        extend AutoCorrector
+        include RuboCop::Prose::ListRules
+
+        private
+
+        def investigate_document
+          list_groups do |list, marks, _parent|
+            next unless list.type == :ol
+
+            first = marks.first[:marker].to_i
+            marks.each_with_index do |mark, index|
+              expected = cop_config.fetch('EnforcedStyle', 'sequential') == 'ones' ? 1 : first + index
+              digits = mark[:marker][/\A\d+/]
+              next if digits == expected.to_s
+
+              range = document.range(mark[:line], mark[:column], mark[:line], mark[:column] + digits.length)
+              prose_offense(range, message: "Use #{expected} for this ordered list item.") do |corrector|
+                # Changing marker width can change continuation-block indentation.
+                corrector.replace(processed_range(range), expected.to_s) if digits.length == expected.to_s.length
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/markdown/outside_spacing.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative '../../prose/inline_rules'
+
+module RuboCop
+  module Cop
+    module Markdown
+      class OutsideSpacing < Base
+        WORD_CHARACTER = /[\p{L}\p{M}\p{N}]/u
+        AMBIGUOUS_SCRIPT = /[\p{Han}\p{Hiragana}\p{Katakana}\p{Hangul}\p{Thai}\p{Lao}\p{Khmer}\p{Myanmar}]/u
+
+        def investigate_document
+          candidates = code_spans + emphasis_spans
+          candidates.each do |first, last, content_first, content_last|
+            next unless adjacent_words?(first, content_first, content_last, last)
+
+            range = ::Parser::Source::Range.new(document.buffer, first, last)
+            prose_offense(range, message: 'Separate inline formatting from adjacent prose words.')
+          end
+        end
+
+        private
+
+        def code_spans
+          multiline = RuboCop::Prose::InlineRules.multiline_atoms(document)
+          RuboCop::Prose::InlineRules.lines(document).flat_map do |text, number, column|
+            line_start = document.line_range(number).begin_pos
+            RuboCop::Prose::InlineRules.spans(text).filter_map do |span|
+              next unless span.kind == :code && span.begin_pos >= column
+
+              first = line_start + span.begin_pos
+              last = line_start + span.end_pos
+              range = ::Parser::Source::Range.new(document.buffer, first, last)
+              next if multiline.any? { |atom| atom.overlaps?(range) }
+              next if protected_ranges(number, text, line_start).any? { |atom| atom.overlaps?(range) }
+
+              [first, last, first + span.delimiter.length, last - span.delimiter.length]
+            end
+          end
+        end
+
+        def emphasis_spans
+          %i[em strong].flat_map do |type|
+            document.emphasis_ranges(type).filter_map do |opening, closing, _delimiter|
+              next unless opening.line == closing.line
+
+              first = opening.begin_pos
+              last = closing.end_pos
+              number = opening.line
+              line_start = document.line_range(number).begin_pos
+              next if protected_ranges(number, document.line(number), line_start)
+                      .any? { |atom| atom.begin_pos < last && first < atom.end_pos }
+
+              [first, last, opening.end_pos, closing.begin_pos]
+            end
+          end
+        end
+
+        def protected_ranges(number, text, line_start)
+          @protected_ranges ||= {}
+          @protected_ranges[number] ||= RuboCop::Prose::InlineRules.spans(text).filter_map do |span|
+            next if span.kind == :code
+
+            ::Parser::Source::Range.new(document.buffer, line_start + span.begin_pos, line_start + span.end_pos)
+          end
+        end
+
+        def adjacent_words?(first, content_first, content_last, last)
+          source = document.buffer.source
+          left = [source[first - 1], source[content_first]]
+          right = [source[content_last - 1], source[last]]
+          [left, right].any? do |outside, inside|
+            word_character?(outside) && word_character?(inside) &&
+              !ambiguous_script?(outside) && !ambiguous_script?(inside)
+          end
+        end
+
+        def word_character?(character)
+          character&.match?(WORD_CHARACTER)
+        end
+
+        def ambiguous_script?(character)
+          character&.match?(AMBIGUOUS_SCRIPT)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/markdown/proper_names.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative '../../prose/inline_rules'
+
+module RuboCop
+  module Cop
+    module Markdown
+      class ProperNames < Base
+        extend AutoCorrector
+
+        def investigate_document
+          names = Array(cop_config['Names']).reject(&:empty?)
+          return if names.empty?
+
+          alternatives = names.sort_by { |name| -name.length }.map { |name| Regexp.escape(name) }.join('|')
+          pattern = /(?<![\p{L}\p{N}_])(?:#{alternatives})(?![\p{L}\p{N}_])/i
+          lines = RuboCop::Prose::InlineRules.lines(document)
+          if cop_config['CodeBlocks']
+            document.nodes(:codeblock).each do |node|
+              first = node.options.fetch(:code_start_line)
+              node.value.lines.each_index do |index|
+                number = first + index
+                lines << [document.line(number), number, 0] unless document.front_matter_line?(number)
+              end
+            end
+          end
+          lines.each do |text, number, column|
+            masked = if document.code_line?(number)
+                       text
+                     else
+                       RuboCop::Prose::InlineRules.mask(text, include_code: cop_config['CodeBlocks'],
+                                                              document: document, number: number)
+                     end
+            masked.to_enum(:scan, pattern).each do
+              match = Regexp.last_match
+              next if match.begin(0) < column
+
+              expected = names.find { |name| name.casecmp?(match[0]) }
+              next if match[0] == expected
+
+              range = document.range(number, match.begin(0), number, match.end(0))
+              prose_offense(range, message: "Use the capitalization `#{expected}`.") do |corrector|
+                corrector.replace(processed_range(range), expected)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/markdown/raw_html.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative '../../prose/inline_rules'
+
+module RuboCop
+  module Cop
+    module Markdown
+      class RawHtml < Base
+        def investigate_document
+          allowed = Array(cop_config['AllowedElements']).map(&:downcase)
+          offsets = Hash.new(0)
+          located = []
+          unlocated = []
+          descendants = ->(node) { [node] + node.children.flat_map { |child| descendants.call(child) } }
+          table_nodes = document.nodes(:table).flat_map { |table| descendants.call(table) }.to_set
+          document.nodes(:html_element).each do |node|
+            number = node.options[:location]
+            if !number || table_nodes.include?(node)
+              unlocated << node.value.to_s.downcase
+              next
+            end
+            next unless number && !document.front_matter_line?(number) && !document.code_line?(number)
+
+            text = document.line(number)
+            key = [number, node.value.to_s.downcase]
+            match = /<#{Regexp.escape(node.value.to_s)}\b[^>]*(?:>|\z)/i.match(text, offsets[key])
+            unless match
+              unlocated << node.value.to_s.downcase
+              next
+            end
+
+            offsets[key] = match.end(0)
+            located << [number, match.begin(0)]
+            next if allowed.include?(node.value.to_s.downcase)
+
+            prose_offense(document.range(number, match.begin(0), number, match.end(0)),
+                          message: "Raw HTML element <#{node.value}> is not allowed.")
+          end
+          # GFM table cell span locations are relative to the cell, not the document.
+          RuboCop::Prose::InlineRules.lines(document).each do |text, number, _|
+            protected = RuboCop::Prose::InlineRules.spans(text).reject { |span| span.kind == :html }
+            text.to_enum(:scan, /<([A-Za-z][\w:-]*)\b[^>]*>/).each do
+              match = Regexp.last_match
+              name = match[1].downcase
+              next unless unlocated.include?(name)
+              next if located.include?([number, match.begin(0)])
+              next if protected.any? { |span| match.begin(0) >= span.begin_pos && match.begin(0) < span.end_pos }
+
+              unlocated.delete_at(unlocated.index(name))
+              next if allowed.include?(name)
+
+              prose_offense(document.range(number, match.begin(0), number, match.end(0)),
+                            message: "Raw HTML element <#{match[1]}> is not allowed.")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/markdown/reference_definitions.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative '../../prose/link_rules'
+
+module RuboCop
+  module Cop
+    module Markdown
+      class ReferenceDefinitions < Base
+        private
+
+        def investigate_document
+          scanner = document.link_rules
+          used = scanner.links.filter_map(&:reference).to_set
+          ignored = cop_config.fetch('IgnoredDefinitions', ['//']).map { |label| scanner.normalize(label) }
+          seen = {}
+          scanner.definitions.each do |definition|
+            first = seen[definition.reference]
+            seen[definition.reference] ||= definition
+            duplicate = first && !(cop_config.fetch('AllowIdenticalDuplicates', false) &&
+              scanner.decode(first.destination) == scanner.decode(definition.destination) &&
+              first.title == definition.title)
+            next if ignored.include?(definition.reference)
+
+            message = if duplicate && cop_config.fetch('CheckDuplicates', true)
+                        'Remove or rename the duplicate reference definition.'
+                      elsif !used.include?(definition.reference) && cop_config.fetch('CheckUnused', false)
+                        'Reference definition is not used.'
+                      end
+            next unless message
+
+            prose_offense(scanner.range(definition.begin_pos, definition.end_pos), message: message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/markdown/reversed_link.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../../prose/link_rules'
+
+module RuboCop
+  module Cop
+    module Markdown
+      class ReversedLink < Base
+        MSG = 'Use [link text](destination), not (link text)[destination].'
+
+        private
+
+        def investigate_document
+          scanner = document.link_rules
+          scanner.reversed_links.each { |first, last| prose_offense(scanner.range(first, last)) }
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/markdown/shell_prompts.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative '../../prose/code_rules'
+
+module RuboCop
+  module Cop
+    module Markdown
+      class ShellPrompts < Base
+        extend AutoCorrector
+        include RuboCop::Prose::CodeRules
+
+        def validate_config
+          %w[ShellLanguages Prompts].each do |name|
+            value = cop_config[name]
+            next if value.is_a?(Array) && (name != 'Prompts' || !value.empty?) &&
+                    value.all? { |entry| entry.is_a?(String) && entry.match?(/\A\S+\z/) }
+
+            raise ValidationError, "Markdown/ShellPrompts: #{name} must be an array of nonempty strings " \
+                                   'without whitespace (and Prompts must contain at least one marker).'
+          end
+        end
+
+        private
+
+        def investigate_document
+          languages = cop_config.fetch('ShellLanguages')
+          code_blocks.each do |node|
+            next unless node.options[:fenced] && languages.include?(node.options[:lang])
+
+            commands = prompted_commands(node)
+            next if commands.nil? || commands.empty?
+
+            safe = prompt_correction_safe?(node, commands)
+            commands.each do |_, index, prompt|
+              range = code_content_range(node, index, prompt.length + 1)
+              next unless range
+
+              prose_offense(range, message: 'Omit shell prompts when the example contains no output.') do |corrector|
+                corrector.remove(processed_range(range)) if safe
+              end
+            end
+          end
+        end
+
+        def prompted_commands(node)
+          commands = []
+          node.value.lines.each_with_index do |line, index|
+            line = line.chomp
+            prompt = cop_config.fetch('Prompts').find { |marker| line.start_with?("#{marker} ") }
+            if prompt
+              commands << [line, index, prompt]
+            elsif !line.strip.empty? && !line.lstrip.start_with?('#')
+              return nil
+            end
+          end
+          commands
+        end
+
+        def prompt_correction_safe?(node, commands)
+          return false if commands.any? { |_, _, prompt| prompt.start_with?('#') }
+
+          details = fence_details(node)
+          return false unless details
+
+          fence = details[:opening][:fence]
+          closing = /\A[ \t]{0,3}#{Regexp.escape(fence[0])}{#{fence.length},}[ \t]*\z/
+          commands.none? { |command, _, prompt| command.delete_prefix("#{prompt} ").match?(closing) }
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/markdown/single_top_level_heading.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../../prose/heading_rules'
+
+module RuboCop
+  module Cop
+    module Markdown
+      class SingleTopLevelHeading < Base
+        include RuboCop::Prose::HeadingRules
+
+        def investigate_document
+          heading_entries.select { |heading| heading[:level] == cop_config.fetch('Level', 1) }.drop(1).each do |heading|
+            prose_offense(heading_range(heading), message: 'Use at most one top-level heading.')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/markdown/strong_style.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative '../../prose/inline_rules'
+
+module RuboCop
+  module Cop
+    module Markdown
+      class StrongStyle < Base
+        extend AutoCorrector
+
+        def investigate_document
+          expected = cop_config.fetch('Style', 'consistent')
+          document.emphasis_ranges(:strong).each do |opening, closing, char|
+            actual = char == '*' ? 'asterisk' : 'underscore'
+            expected = actual if expected == 'consistent'
+            next if actual == expected
+
+            replacement = expected == 'asterisk' ? '**' : '__'
+            before = opening.begin_pos.positive? ? document.source[opening.begin_pos - 1] : nil
+            after = document.source[closing.end_pos]
+
+            prose_offense(opening, message: "Use #{expected} strong emphasis.") do |corrector|
+              next if replacement == '__' && (before&.match?(/[[:alnum:]_]/) || after&.match?(/[[:alnum:]_]/))
+
+              corrector.replace(processed_range(opening), replacement)
+              corrector.replace(processed_range(closing), replacement)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/markdown/structural_line_length.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Markdown
+      class StructuralLineLength < Base
+        MSG = 'Markdown source line is too long. [%<length>d/%<max>d]'
+
+        def validate_config
+          %w[Max HeadingMax CodeBlockMax].each do |name|
+            value = cop_config[name]
+            next if name != 'Max' && value.nil?
+            next if value.is_a?(Integer) && value.positive?
+
+            raise ValidationError, "Markdown/StructuralLineLength: #{name} must be a positive integer."
+          end
+        end
+
+        private
+
+        def investigate_document
+          table_lines = document.nodes(:table).flat_map do |table|
+            first = table.options.fetch(:location)
+            rows = table.children.sum { |section| section.children.length }
+            (first..(first + rows)).to_a
+          end.to_set
+          headings = document.headings.to_set(&:last)
+          document.lines.each_with_index do |text, index|
+            number = index + 1
+            next if document.front_matter_line?(number)
+
+            limit = structural_limit(number, headings, table_lines)
+            next unless limit && text.length > limit
+
+            prose_offense(document.range(number, limit), message: format(MSG, length: text.length, max: limit))
+          end
+        end
+
+        def structural_limit(number, headings, tables)
+          if headings.include?(number) && cop_config['Headings']
+            cop_config['HeadingMax'] || cop_config['Max']
+          elsif document.code_line?(number) && cop_config['CodeBlocks']
+            cop_config['CodeBlockMax'] || cop_config['Max']
+          elsif tables.include?(number) && cop_config['Tables']
+            cop_config['Max']
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/markdown/syntax.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Markdown
+      class Syntax < Base
+        private
+
+        def investigate_document
+          document.warnings.reject { |warning| owned_elsewhere?(warning) }
+                  .group_by { |warning| warning_line(warning) }.each do |number, warnings|
+            prose_offense(document.line_range(number), message: warnings.join('; '))
+          end
+        end
+
+        def owned_elsewhere?(warning)
+          owner = if warning.start_with?('No link definition')
+                    'Markdown/UndefinedReference'
+                  elsif warning.start_with?('Duplicate link ID')
+                    'Markdown/ReferenceDefinitions'
+                  end
+          owner && config.cop_enabled?(owner) &&
+            processed_source.registry&.any? { |cop| cop.cop_name == owner }
+        end
+
+        def warning_line(warning)
+          number = warning.scan(/\bline (\d+)\b/).last&.first&.to_i || 1
+          number.clamp(1, document.lines.length)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/markdown/table_blank_lines.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative '../../prose/table_rules'
+
+module RuboCop
+  module Cop
+    module Markdown
+      class TableBlankLines < Base
+        extend AutoCorrector
+
+        def investigate_document
+          RuboCop::Prose::TableRules.tables(document).each do |table|
+            first = table.rows.first.number
+            last = table.rows.last.number
+            unless first == 1 || blank?(document.line(first - 1))
+              range = document.range(first, 0, first, 0)
+              prose_offense(document.line_range(first), message: 'Add a blank line before the table.') do |corrector|
+                corrector.insert_before(processed_range(range), blank_prefix(document.line(first)) + newline)
+              end
+            end
+            next if last == document.lines.length || blank?(document.line(last + 1))
+
+            range = document.range(last + 1, 0, last + 1, 0)
+            prose_offense(document.line_range(last), message: 'Add a blank line after the table.') do |corrector|
+              corrector.insert_before(processed_range(range), blank_prefix(document.line(last)) + newline)
+            end
+          end
+        end
+
+        private
+
+        def blank?(text)
+          text.match?(/\A[ \t]*(?:>[ \t]*)*\z/)
+        end
+
+        def blank_prefix(text)
+          text[/\A[ \t]*(?:>[ \t]*)+/].to_s.rstrip
+        end
+
+        def newline
+          document.source.include?("\r\n") ? "\r\n" : "\n"
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/markdown/table_columns.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative '../../prose/table_rules'
+
+module RuboCop
+  module Cop
+    module Markdown
+      class TableColumns < Base
+        def investigate_document
+          RuboCop::Prose::TableRules.tables(document).each do |table|
+            count = table.rows.first.cells.length
+            table.rows.drop(1).each do |row|
+              next if row.cells.length == count
+
+              prose_offense(document.range(row.number, row.begin_pos, row.number, row.end_pos),
+                            message: "Expected #{count} table columns, found #{row.cells.length}.")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/markdown/table_pipes.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative '../../prose/table_rules'
+
+module RuboCop
+  module Cop
+    module Markdown
+      class TablePipes < Base
+        extend AutoCorrector
+
+        def investigate_document
+          RuboCop::Prose::TableRules.tables(document).each do |table|
+            style = cop_config.fetch('Style', 'consistent')
+            expected = case style
+                       when 'leading_and_trailing' then [true, true]
+                       when 'leading_only' then [true, false]
+                       when 'trailing_only' then [false, true]
+                       when 'no_leading_or_trailing' then [false, false]
+                       else [table.rows.first.leading, table.rows.first.trailing]
+                       end
+            table.rows.each do |row|
+              next if [row.leading, row.trailing] == expected
+
+              range = document.range(row.number, row.begin_pos, row.number, row.end_pos)
+              prose_offense(range, message: 'Use consistent leading and trailing table pipes.') do |corrector|
+                replacement = row.text[row.begin_pos...row.end_pos].dup
+                replacement = replacement[1..] if row.leading && !expected[0]
+                replacement = replacement[0...-1] if row.trailing && !expected[1]
+                replacement = "|#{replacement}" if !row.leading && expected[0]
+                replacement = "#{replacement}|" if !row.trailing && expected[1]
+                # Without an outer pipe, an empty boundary cell is indistinguishable
+                # from an outer pipe; leaving it alone preserves the column count.
+                next if !expected[0] && row.cells.first.text.strip.empty?
+                next if !expected[1] && row.cells.last.text.strip.empty?
+                next if expected.none? && row.cells.length == 1
+
+                corrector.replace(processed_range(range), replacement)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end