hecks 3.5.0 → 3.6.0

data/lib/hecks/tools/comment_style/masking.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module CommentStyle
+      # Blanks the spans of a comment that must keep their capitals (code spans, quotes, SQL), and
+      # decides which capitalised SQL keywords on a line to leave alone.
+      module Masking
+        private
+
+        # The comment with every span that must keep its capitals blanked out. A
+        # backtick span can wrap across lines, so whether this line opens inside
+        # one comes from the lines above it.
+        def mask(comment)
+          head, text = open_span_head(comment)
+          body = text.gsub(PROTECTED_SPANS) { |span| quoted_heading?(span) ? span : FILLER * span.length }
+          head + blank_unclosed(body)
+        end
+
+        # Blanks the start of a line that continues a backtick span opened above it.
+        #
+        # @return [Array(String, String)] the blanked head, and the rest of the text
+        def open_span_head(comment)
+          text = comment.text
+          return ["", text] unless @open_spans[comment.line]
+
+          lead = text[/\A#+\s*/].length
+          close = text.index("`", lead)
+          cut = close ? close + 1 : text.length
+          [text[0, lead] + (FILLER * (cut - lead)), text[cut..]]
+        end
+
+        # Blanks a backtick span left open at the end of the line.
+        def blank_unclosed(body)
+          open = body.rindex("`")
+          open ? body[0, open] + (FILLER * (body.length - open)) : body
+        end
+
+        # Which lines begin inside a backtick span opened earlier in the paragraph.
+        def open_spans
+          inside = false
+          @comments.each_with_object({}) do |comment, open|
+            inside = false unless continues_paragraph?(comment)
+            open[comment.line] = inside
+            inside ^= comment.text.count("`").odd?
+          end
+        end
+
+        def continues_paragraph?(comment)
+          above = @by_line[comment.line - 1]
+          comment.full_line && above&.full_line && !above.text.match?(/\A#+\s*\z/)
+        end
+
+        # Capitalised SQL keywords to leave alone on this line. A keyword such as
+        # `FROM` or `SET` is only SQL when the rest of the line reads as SQL too.
+        def sql_keywords(comment, words)
+          bare, strong, weak = sql_classes(words)
+          return bare.to_set if reads_as_sql?(bare, strong, weak)
+          return (strong + weak).to_set if comment.text.match?(SQL_PHRASES)
+
+          database_file? ? strong.to_set : Set.new
+        end
+
+        def sql_classes(words)
+          bare = words.map { |word| word.sub(/'[A-Z]{1,2}\z/, "") } - ["A"]
+          [bare, bare.select { |word| SQL_STRONG.include?(word) }, bare.select { |word| SQL_WEAK.include?(word) }]
+        end
+
+        def database_file?
+          path.match?(SQL_PATH)
+        end
+
+        def reads_as_sql?(bare, strong, weak)
+          only_sql = bare.all? do |word|
+            [SQL_STRONG, SQL_WEAK, SQL_NEUTRAL, ACRONYMS].any? { |set| set.include?(word) }
+          end
+          return false unless only_sql
+
+          database_file? ? (strong.any? || weak.any?) : (strong.any? && (strong + weak).size >= 2)
+        end
+
+        # A quoted run of capitals is another comment's heading, not a literal.
+        def quoted_heading?(span)
+          return false unless span.start_with?('"') && !span.match?(SQL_PHRASES)
+
+          capitals = span.scan(/\b[A-Z]{2,}\b/).size
+          capitals >= 3 || (capitals == 2 && !span.match?(/[a-z]/))
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/comment_style/patterns.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    # The regular expressions the comment linters match comment text against.
+    module CommentStyle
+      # Multi-word SQL is protected as a phrase, because the individual keywords
+      # (`FROM`, `WHERE`, `TABLE`) are also ordinary English emphasis targets.
+      SQL_PHRASES = Regexp.union(
+        /\bINSERT INTO\b/, /\bSELECT\b.*?\bFROM\b/, /\bORDER BY\b/, /\bGROUP BY\b/,
+        /\bON CONFLICT\b(?: DO (?:NOTHING|UPDATE))?/, /\bDO NOTHING\b/, /\bFOR (?:UPDATE|SHARE)\b/,
+        /\bSKIP LOCKED\b/, /\b(?:PRIMARY|FOREIGN) KEY\b/, /\bIS(?: NOT)? NULL\b/, /\bNOT NULL\b/,
+        /\bCREATE (?:UNIQUE )?(?:TABLE|INDEX|POLICY|ROLE|SCHEMA|TRIGGER|FUNCTION)\b/,
+        /\bALTER (?:TABLE|ROLE|SCHEMA)\b/, /\bDROP (?:TABLE|COLUMN|INDEX|SCHEMA|POLICY)\b/,
+        /\bADD (?:COLUMN|CONSTRAINT)\b/, /\bDELETE FROM\b/, /\bUNION ALL\b/, /\bSET LOCAL\b/,
+        /\bBEGIN (?:IMMEDIATE|EXCLUSIVE|DEFERRED)\b/, /\bROW LEVEL SECURITY\b/,
+        /\bCREATE \.\.\. PARTITION OF\b/, /\bPARTITION OF\b/, /\bIF (?:NOT )?EXISTS\b/,
+        /\b(?:LEFT|INNER|OUTER|CROSS) JOIN\b/, /\bLIMIT \d+\b/, /\bOWNER TO\b/, /\b(?:on|in|onto) PATH\b/
+      ).freeze
+
+      PROTECTED_SPANS = Regexp.union(
+        /`[^`]*`/, /"[^"]*"/, /'[^'\s]*'/, %r{\b[a-z]+://\S+}, SQL_PHRASES,
+        /\b(?:NOTE|OPTIMIZE|HACK|REVIEW):/
+      ).freeze
+
+      CAPS_WORD = /
+        (?<![\w:.\#@$'])
+        (?:A|[A-Z]{2,}(?:'[A-Z]{1,2})?)
+        (?![\w(]|'(?!s\b|\s|$)|-[a-z](?<=POST-.)|::|\.\w|\#\d|\s*=(?![=~>])|\s*←)
+      /x
+
+      HISTORY = [
+        /\bused to\b/i, /\bwas originally\b/i, /\boriginally (?:was|were|used|lived|named|called)\b/i,
+        /\bpreviously\b/i, /\bformerly\b/i, /\bhistorically\b/i, /\bstale as of\b/i,
+        /\b(?:was|were|been|got) renamed\b/i, /\brenamed from\b/i, /\bhas since\b/i,
+        /\bbefore (?:this|the) (?:change|fix|refactor|split|rename|pr|commit|patch)\b/i, /\bBefore this, /,
+        /\ban? earlier (?:version|revision|draft|pass)\b/i, /\bwhen this was (?:written|added)\b/i,
+        /\b(?:in|since|by|after|before|until) (?:PR )?\#\d{2,}/i, /\bPR \#?\d{2,}\b/,
+        /\bno longer\b/i, /\bany more\b/i, /\banymore\b/i
+      ].freeze
+
+      DIRECTIVE = /\A#\s*(?:rubocop:|frozen_string_literal:|encoding:|coding:|shareable_constant|typed:|!)/
+
+      # Stands in for a protected span so it still reads as a word, not a gap.
+      FILLER = "§"
+
+      # What may sit between the words of one all-caps heading run.
+      GAP = %r{\A(?:[\s,/&'\-\d]|#{FILLER}|[A-Z]{2,})*\z}
+
+      # A bold phrase opening a comment line, after an optional bullet.
+      BOLD_HEADING = /\A(#+\s*(?:[-*]\s+)?)\*\*([^*]+)\*\*/
+
+      # What ends a heading run: an em dash, or sentence punctuation.
+      HEADING_END = /\A(?:\s+—|[.:!?](?:\s|\z))/
+
+      CODE_NOISE = %i[on_comment on_sp on_nl on_ignored_nl].freeze
+    end
+  end
+end

data/lib/hecks/tools/comment_style/run.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "English"
+require "pathname"
+require_relative "../../tools"
+require_relative "source_file"
+require_relative "baseline"
+require_relative "dictionary"
+
+module Hecks
+  module Tools
+    module CommentStyle
+      # Lints a set of paths and renders the result.
+      class Run
+        # @param paths [Array<String>] files or directories
+        # @param only [Array<String>, nil] categories to keep
+        # @param baseline [Hash{String => Hash{String => Integer}}] the long blocks to tolerate
+        def initialize(paths, only: nil, baseline: Baseline.load)
+          @files = paths.flat_map { |p| File.directory?(p) ? ruby_files(p) : [p] }.sort.uniq
+          @only = only
+          @baseline = baseline
+        end
+
+        # Every block over `MAX_BLOCK` lines in these files, in the baseline's own shape.
+        #
+        # @return [Hash{String => Hash{String => Integer}}] file path to block key to length
+        def long_block_baseline
+          @files.each_with_object({}) do |path, held|
+            blocks = SourceFile.new(path).long_blocks
+            held[path.delete_prefix("./")] = blocks.to_h { |block| [block.key, block.lines] } if blocks.any?
+          end
+        end
+
+        # Files whose code differs from `ref`, comments and whitespace aside.
+        #
+        # A file `ref` does not hold (new since `ref`, or outside the repository) counts as
+        # changed: what cannot be compared is not vouched for.
+        #
+        # @param ref [String] revision to compare the working tree against
+        # @return [Array<String>] paths whose non-comment token stream changed
+        # @raise [ArgumentError] when `ref` names no commit
+        def code_changed_since(ref)
+          top = vcs_output("rev-parse", "--show-toplevel", chdir: Dir.pwd)&.strip
+          raise ArgumentError, "not inside a checkout" if top.nil? || top.empty?
+          unless vcs_output("rev-parse", "--verify", "--quiet", "#{ref}^{commit}", chdir: top)
+            raise ArgumentError, "unknown ref #{ref.inspect}"
+          end
+
+          @files.select do |path|
+            before = committed_source(ref, path, top)
+            before.nil? || CommentStyle.code_tokens(before) != CommentStyle.code_tokens(File.read(path))
+          end
+        end
+
+        # Every violation across the whole file set, computed once.
+        #
+        # @return [Array<Violation>]
+        def violations
+          @violations ||= begin
+            sources = @files.map { |path| SourceFile.new(path) }
+            found = sources.flat_map { |source| source.violations(only: @only, baseline: @baseline) } +
+                    undocumented_types(sources)
+            @only ? found.select { |v| @only.include?(v.category) } : found
+          end
+        end
+
+        # Rewrites every file's fixable categories in place.
+        #
+        # @return [Integer] number of files rewritten
+        def fix!
+          wants_caps = @only.nil? || @only.include?("all_caps")
+          abort "fixing all_caps needs the word list at #{Dictionary::WORDS}" if wants_caps && !Dictionary.words
+
+          @files.count do |path|
+            original = File.read(path)
+            output = SourceFile.new(path, original).fixed(only: @only)
+            next false if output == original
+
+            File.write(path, output)
+            true
+          end
+        end
+
+        # Renders the summary tables `--report` prints.
+        #
+        # @param top [Integer] rows to show in the per-file table
+        # @return [String]
+        def report(top: 20)
+          by_file = violations.group_by(&:path)
+          [
+            "#{violations.size} violations in #{by_file.size} of #{@files.size} files\n",
+            "By category:", *category_rows,
+            "\nBy directory (top #{top}):", *directory_rows.first(top),
+            "\nWorst #{top} files:", *file_rows(by_file, top)
+          ].join("\n")
+        end
+
+        private
+
+        # `path`'s text at `ref`, or nil when the repository at `top` holds none there.
+        def committed_source(ref, path, top)
+          relative = Pathname.new(File.expand_path(path)).relative_path_from(Pathname.new(top)).to_s
+          return nil if relative == ".." || relative.start_with?("../")
+
+          vcs_output("show", "#{ref}:#{relative}", chdir: top)&.force_encoding(Encoding::UTF_8)
+        end
+
+        # What `git <args>` printed, or nil when it failed.
+        def vcs_output(*args, chdir:)
+          out = IO.popen(["git", *args], chdir: chdir, err: File::NULL, &:read)
+          $CHILD_STATUS.success? ? out : nil
+        end
+
+        # `.rb` files, plus extensionless scripts with a Ruby shebang. The first line is read as
+        # bytes, so an extensionless binary (a compiled test fixture's output) is passed over
+        # rather than refused for not being UTF-8.
+        def ruby_files(dir)
+          scripts = Dir[File.join(dir, "**", "*")].select do |path|
+            File.file?(path) && File.extname(path).empty? && File.open(path, "rb", &:gets).to_s.match?(/\A#!.*ruby/n)
+          end
+          Dir[File.join(dir, "**", "*.rb")] + scripts
+        end
+
+        def category_rows
+          counts = violations.group_by(&:category).transform_values(&:size)
+          CATEGORIES.map do |name, description|
+            suffix = FIXABLE.include?(name) ? " [fixable]" : ""
+            "  #{counts.fetch(name, 0).to_s.rjust(6)}  #{name.ljust(24)} #{description}#{suffix}"
+          end
+        end
+
+        def directory_rows
+          violations.group_by { |v| v.path.split("/")[0, 3].join("/") }
+                    .sort_by { |_, list| -list.size }
+                    .map { |dir, list| "  #{list.size.to_s.rjust(6)}  #{dir}" }
+        end
+
+        def file_rows(by_file, top)
+          by_file.sort_by { |_, list| -list.size }.first(top).map do |file, list|
+            category, worst = list.group_by(&:category).max_by { |_, group| group.size }
+            "  #{list.size.to_s.rjust(6)}  #{file}  (mostly #{category}: #{worst.size})"
+          end
+        end
+
+        # A type reopened across files counts as documented if any opening is.
+        def undocumented_types(sources)
+          openings = sources.flat_map { |s| s.types.reject(&:namespace_only).map { |t| [s, t] } }
+          openings.group_by { |_, type| type.fqn }.filter_map { |fqn, group| undocumented_opening(fqn, group) }
+        end
+
+        def undocumented_opening(fqn, group)
+          return unless CommentStyle.public_surface.include?(fqn.to_s.split("::").last)
+          return if group.any? { |source, type| source.documented?(type) }
+
+          source, type = group.first
+          Violation.new(source.path, type.line, "undocumented_class", fqn)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/comment_style/signature.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module CommentStyle
+      # Reads a method definition's Ripper nodes: the names of its parameters and whether its body
+      # raises.
+      module Signature
+        module_function
+
+        # @param params [Array, nil] the parameter node of a `def`
+        # @return [Array(Array<String>, String)] the parameter names, and the block parameter's name
+        def parameter_names(params)
+          params = params[1] if params.is_a?(Array) && params[0] == :paren
+          return [[], nil] unless params.is_a?(Array) && params[0] == :params
+
+          [positional_names(params) + keyword_names(params), splat_name(params[7]).first]
+        end
+
+        # @param node [Object] a Ripper node
+        # @return [Boolean] whether the node, outside any nested `def`, calls `raise`
+        def raises?(node)
+          return false unless node.is_a?(Array)
+          return false if %i[def defs].include?(node[0])
+
+          call = %i[command fcall vcall].include?(node[0]) && node[1].is_a?(Array) && node[1][1] == "raise"
+          call || node.any? { |child| raises?(child) }
+        end
+
+        # @return [Array<String>] required, optional, rest and post parameter names
+        def positional_names(params)
+          _, required, optional, rest, post = params
+          idents(required) + Array(optional).map { |pair| pair[0][1] } + splat_name(rest) + idents(post)
+        end
+
+        # @return [Array<String>] keyword and keyword-rest parameter names
+        def keyword_names(params)
+          keywords, keyrest = params.values_at(5, 6)
+          Array(keywords).map { |pair| pair[0][1].chomp(":") } + splat_name(keyrest)
+        end
+
+        # @return [Array<String>] the names in a list of identifier nodes
+        def idents(list)
+          Array(list).select { |item| item.is_a?(Array) && item[0] == :@ident }.map { |item| item[1] }
+        end
+
+        # `rest`/`keyrest`/`block` are each either nil, an unnamed splat (`*`, `**`, `&`), or a
+        # one-element `[:@ident, name, pos]` node wrapping the name.
+        #
+        # @return [Array<String>] the name, or nothing when the splat is unnamed
+        def splat_name(node)
+          node.is_a?(Array) && node[1].is_a?(Array) ? [node[1][1]] : []
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/comment_style/source_file.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "ripper"
+require_relative "../../tools"
+require_relative "long_blocks"
+require_relative "masking"
+require_relative "caps_words"
+require_relative "text_checks"
+require_relative "fixing"
+require_relative "structure_checks"
+
+module Hecks
+  module Tools
+    module CommentStyle
+      # One parsed source file and the violations found in it.
+      class SourceFile
+        include LongBlocks
+        include Masking
+        include CapsWords
+        include TextChecks
+        include Fixing
+        include StructureChecks
+
+        attr_reader :path, :lines, :comments
+
+        def initialize(path, source = nil)
+          @path = path
+          @source = source || File.read(path)
+          @lines = @source.lines
+          @comments = lex_comments
+          @by_line = @comments.to_h { |c| [c.line, c] }
+          @open_spans = open_spans
+          @constants = code_words
+        end
+
+        # Finds every place this file departs from the style guide.
+        def violations(only: nil, baseline: {})
+          return [] if generated?
+
+          found = text_violations + (test_file? ? [] : structure_violations) + long_block_violations(baseline)
+          found = found.select { |v| only.include?(v.category) } if only
+          found.sort_by { |v| [v.line, v.category] }
+        end
+
+        # Rewrites the mechanical categories; raises rather than write a change that alters code.
+        def fixed(only: nil)
+          return @source if generated?
+
+          wanted = (only || FIXABLE) & FIXABLE
+          output = @lines.map.with_index(1) { |line, number| fix_line(line, number, wanted) }.join
+          return @source if output == @source
+
+          unchanged = CommentStyle.code_tokens(@source) == CommentStyle.code_tokens(output)
+          raise "#{path}: fix would change code, refusing" unless unchanged
+
+          output
+        end
+
+        # Parses this file's structure once and caches it.
+        def types
+          test_file? || generated? ? [] : structure.last
+        end
+
+        # A generated file's comments belong to its generator, and its
+        # `GENERATED ... DO NOT EDIT` banner is a convention tools recognise.
+        def generated?
+          @lines.first(8).join.match?(/\bgenerated\b.*?\bdo not edit\b/im)
+        end
+
+        # Helpers defined inside a spec are test scaffolding, not API, so the
+        # doc-tag categories skip them. The prose categories still apply.
+        def test_file?
+          path.end_with?("_spec.rb")
+        end
+
+        # A `class`/`module` is documented only if a comment block sits directly above it.
+        def documented?(type)
+          !doc_above(type.line).empty?
+        end
+
+        private
+
+        def lex_comments
+          Ripper.lex(@source).filter_map do |(line, col), type, text, _|
+            next unless type == :on_comment
+
+            prefix = @lines[line - 1].byteslice(0, col)
+            Comment.new(line, col, text.chomp, prefix.strip.empty?)
+          end
+        end
+
+        # All-caps names in this file's code: constants, heredoc delimiters, and
+        # strings that are nothing but one such name (`ENV["PATH"]`).
+        def code_words
+          Ripper.lex(@source).each_with_object(Set.new) do |(_, type, text, _), words|
+            case type
+            when :on_const, :on_tstring_content then words << text if text.match?(/\A[A-Z][A-Z0-9_]+\z/)
+            when :on_heredoc_beg, :on_heredoc_end then words.merge(text.scan(/[A-Z][A-Z0-9_]+/))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/comment_style/structure_checks.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+require_relative "walker"
+
+module Hecks
+  module Tools
+    module CommentStyle
+      # The structural categories: the doc tags a public method carries and the shape of a long
+      # class doc.
+      module StructureChecks
+        private
+
+        def structure_violations
+          methods, types = structure
+          methods.flat_map { |m| method_violations(m) } + types.flat_map { |t| long_doc_violations(t) }
+        end
+
+        def structure
+          @structure ||= begin
+            walker = Walker.new
+            sexp = Ripper.sexp(@source)
+            walker.walk(sexp, Walker::Scope.new([], :public)) if sexp
+            [walker.methods, walker.types]
+          end
+        end
+
+        def doc_above(line)
+          block = []
+          cursor = line - 1
+          while (comment = @by_line[cursor]) && comment.full_line
+            block.unshift(comment.text)
+            cursor -= 1
+          end
+          block
+        end
+
+        def method_violations(method)
+          return [] unless method.visibility == :public
+          return [] unless CommentStyle.public_surface.include?(method.type_fqn.to_s.split("::").last)
+
+          doc = doc_above(method.line).join("\n")
+          return undocumented_violation(method) if doc.empty?
+          return [] if doc.match?(/@api private|@private|:nodoc:|\(see (?:`[^`]+`|#\w)[^)]*\)\W*\z/m)
+
+          tag_violations(method, doc)
+        end
+
+        def undocumented_violation(method)
+          return [] if SELF_EVIDENT.include?(method.name)
+
+          [Violation.new(path, method.line, "undocumented_method", "##{method.name}")]
+        end
+
+        def tag_violations(method, doc)
+          param_violations(method, doc) + summary_violations(method, doc) + outcome_violations(method, doc)
+        end
+
+        def param_violations(method, doc)
+          found = method.params.reject { |name| doc.match?(/@(?:param|option)\s+(?:\[[^\]\n]*\]\s*)?#{Regexp.escape(name)}\b/) }
+                        .map { |name| violation(method, "missing_param", "lacks @param #{name}") }
+          block = method.block_param
+          if block && !doc.match?(/@yield|@param\s+(?:\[[^\]\n]*\]\s*)?#{Regexp.escape(block)}\b/)
+            found << violation(method, "missing_param", "lacks @yield for &#{block}")
+          end
+          found
+        end
+
+        def summary_violations(method, doc)
+          found = []
+          found << violation(method, "missing_summary", "") if tags_only?(doc) && method.name != "initialize"
+          if heading_lead?(doc)
+            found << violation(method, "missing_summary",
+                               "opens with a bold heading: add a verb-first lead sentence above it")
+          end
+          found
+        end
+
+        def outcome_violations(method, doc)
+          found = []
+          returns = method.name == "initialize" || method.name.end_with?("=") || doc.include?("@return")
+          found << violation(method, "missing_return", "") unless returns
+          found << violation(method, "missing_raise", "") if method.raises && !doc.include?("@raise")
+          found
+        end
+
+        def tags_only?(doc)
+          lead_line(doc).start_with?("@")
+        end
+
+        # A bold heading is a paragraph title, not a sentence about the method.
+        def heading_lead?(doc)
+          lead_line(doc).start_with?("**")
+        end
+
+        def lead_line(doc)
+          doc.lines.map { |line| line.sub(/\A\s*#+\s?/, "").strip }.reject(&:empty?).first.to_s
+        end
+
+        def violation(method, category, detail)
+          Violation.new(path, method.line, category, "##{method.name} #{detail}".strip)
+        end
+
+        def long_doc_violations(type)
+          doc = doc_above(type.line)
+          return [] if doc.length <= LONG_CLASS_DOC || doc.any? { |l| l.match?(/\A#\s*##+ /) }
+
+          [Violation.new(path, type.line, "unstructured_class_doc", "#{type.fqn} (#{doc.length} lines)")]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/comment_style/text_checks.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module CommentStyle
+      # The prose categories: every check that reads one comment's text.
+      module TextChecks
+        private
+
+        def text_violations
+          @comments.flat_map do |comment|
+            next [] if comment.text.match?(DIRECTIVE)
+
+            caps_violations(comment) + constant_violations(comment) + unknown_violations(comment) +
+              bold_violations(comment) + history_violations(comment) + length_violations(comment)
+          end
+        end
+
+        def unknown_violations(comment)
+          words = mask(comment).scan(CAPS_WORD).uniq - ["A"]
+          words.reject { |word| keep_capitals?(word) }.select { |word| unknown?(word) }.map do |word|
+            Violation.new(path, comment.line, "unknown_capitals", word)
+          end
+        end
+
+        def bold_violations(comment)
+          heading = comment.text[BOLD_HEADING, 2]
+          return [] unless heading && heading.split.size > MAX_HEADING_WORDS
+
+          [Violation.new(path, comment.line, "long_bold", "#{heading.split.size} words")]
+        end
+
+        def caps_violations(comment)
+          caps_words(comment).map do |_, word, replacement|
+            Violation.new(path, comment.line, "all_caps", "#{word} -> #{replacement}")
+          end
+        end
+
+        # A capitalised word that is also a constant defined in this file could be
+        # either prose or a reference, so it is reported rather than rewritten.
+        def constant_violations(comment)
+          words = mask(comment).scan(CAPS_WORD).uniq
+          words.select { |word| @constants.include?(word) && !ACRONYMS.include?(word) }.map do |word|
+            Violation.new(path, comment.line, "bare_constant", word)
+          end
+        end
+
+        def history_violations(comment)
+          masked = comment.text.gsub(/`[^`]*`/) { |span| " " * span.length }
+          pattern = HISTORY.find { |candidate| masked.match?(candidate) }
+          return [] unless pattern
+
+          [Violation.new(path, comment.line, "design_history", %("#{masked[pattern]}"))]
+        end
+
+        def length_violations(comment)
+          length = @lines[comment.line - 1].chomp.length
+          return [] if length <= MAX_LINE
+
+          [Violation.new(path, comment.line, "long_line", "#{length} characters")]
+        end
+      end
+    end
+  end
+end