hecks 3.4.2 → 3.6.0

data/lib/hecks/tools/regeneration_run.rb

@@ -21,6 +21,12 @@ module Hecks
     #
     # `--check` never writes the working tree: it runs beside the parallel suite.
     module RegenerationRun
+      # The refusal when no domain is found.
+      NO_DOMAINS = "hecks regenerate_corpus: discovered ZERO domains with committed rust/src/generated/ " \
+                   "output in Hecks::Corpus — that almost certainly means this script is running from the " \
+                   "wrong directory, or something upstream deleted rust/src/generated/ entirely. Refusing " \
+                   "to silently treat that as \"nothing to regenerate.\""
+
       module_function
 
       # Regenerates the corpus, or checks it.
@@ -35,21 +41,31 @@ module Hecks
           # A check projects into a scratch copy of the crate; the forked children inherit
           # HECKS_RUST_DIR.
           scratch = argv.include?("--check") && scratch_crate(root)
-          saved = ENV.fetch("HECKS_RUST_DIR", nil)
-          ENV["HECKS_RUST_DIR"] = scratch if scratch
-          begin
-            begin
-              regenerate(domains)
-            ensure
-              saved ? ENV["HECKS_RUST_DIR"] = saved : ENV.delete("HECKS_RUST_DIR")
-            end
-            scratch ? verdict(scratch) : 0
-          ensure
-            FileUtils.rm_rf(scratch) if scratch
-          end
+          run_plan(domains, scratch)
         end
       end
 
+      # Regenerates the domains, then judges the scratch crate when there is one.
+      #
+      # @param domains [Array<String>] the domains, in run order
+      # @param scratch [String, false] the scratch crate of a check, removed here
+      # @return [Integer] 0, or 1 when a check finds a difference
+      def run_plan(domains, scratch)
+        with_rust_dir(scratch) { regenerate(domains) }
+        scratch ? verdict(scratch) : 0
+      ensure
+        FileUtils.rm_rf(scratch) if scratch
+      end
+
+      # Points `HECKS_RUST_DIR` at `scratch` while the block runs, then puts it back.
+      def with_rust_dir(scratch)
+        saved = ENV.fetch("HECKS_RUST_DIR", nil)
+        ENV["HECKS_RUST_DIR"] = scratch if scratch
+        yield
+      ensure
+        saved ? ENV["HECKS_RUST_DIR"] = saved : ENV.delete("HECKS_RUST_DIR")
+      end
+
       # `meta` is never in the list: `Hecks::Corpus::RUST_ELSEWHERE` routes it to the check that
       # owns it instead.
       #
@@ -59,12 +75,7 @@ module Hecks
       def plan(root)
         domains = Hecks::Corpus.rust_regen_order.map { |domain| domain.dir.delete_prefix("#{root}/") }
 
-        if domains.empty?
-          abort "hecks regenerate_corpus: discovered ZERO domains with committed rust/src/generated/ " \
-                "output in Hecks::Corpus — that almost certainly means this script is running from the " \
-                "wrong directory, or something upstream deleted rust/src/generated/ entirely. Refusing " \
-                "to silently treat that as \"nothing to regenerate.\""
-        end
+        abort NO_DOMAINS if domains.empty?
 
         puts "hecks regenerate_corpus: regenerating #{domains.size} domain(s), in this fixed order:"
         domains.each { |d| puts "  #{d}" }
@@ -115,18 +126,21 @@ module Hecks
         STDERR.reopen(writer) # rubocop:disable Style/GlobalStdStream
         $stdout = STDOUT
         $stderr = STDERR
-        status = begin
-          Hecks::RustBuild.run("project_rust", [domain], out: STDOUT, err: STDERR) # rubocop:disable Style/GlobalStdStream
-        rescue SystemExit => e
-          e.status
-        rescue StandardError => e
-          warn "#{e.class}: #{e.message}"
-          1
-        end
+        status = child_status(domain)
         $stdout.flush
         exit!(status)
       end
 
+      # @return [Integer] the exit status of `hecks project_rust` for the domain
+      def child_status(domain)
+        Hecks::RustBuild.run("project_rust", [domain], out: STDOUT, err: STDERR) # rubocop:disable Style/GlobalStdStream
+      rescue SystemExit => e
+        e.status
+      rescue StandardError => e
+        warn "#{e.class}: #{e.message}"
+        1
+      end
+
       # A scratch crate: copies of the generated tree and Cargo.toml, all `hecks project_rust`
       # writes.
       #

data/lib/hecks/tools/rust_comment_style/caps_words.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module RustCommentStyle
+      # Finds the all-caps words in a Rust comment and decides how each should be written instead.
+      module CapsWords
+        private
+
+        def caps_words(comment)
+          masked = mask(comment)
+          matches = []
+          masked.scan(CommentStyle::CAPS_WORD) { matches << Regexp.last_match }
+          sql = sql_keywords(comment, matches.map { |m| m[0] })
+          found = matches.filter_map { |match| shouted_word(comment, masked, match, sql) }
+          (drop_stray_articles(found) + possessives(masked)).sort_by(&:first)
+        end
+
+        def shouted_word(comment, masked, match, sql)
+          word = match[0]
+          return if word != "A" && (keep_capitals?(word) || sql.include?(word) || unknown?(word))
+
+          [match.begin(0), word, recase(word, sentence_start?(comment, masked, match.begin(0)))]
+        end
+
+        def possessives(masked)
+          found = []
+          masked.scan(/(?<=#{FILLER})'S\b/o) { found << [Regexp.last_match.begin(0) + 1, "S", "s"] }
+          found
+        end
+
+        def drop_stray_articles(found)
+          found.each_with_index.reject do |(offset, word, _), index|
+            word == "A" && !beside_fixed_word?(found, index, offset)
+          end.map(&:first)
+        end
+
+        def beside_fixed_word?(found, index, offset)
+          before = index.positive? ? found[index - 1] : nil
+          after = found[index + 1]
+          follows_fixed?(before, offset) || precedes_fixed?(after, offset)
+        end
+
+        def follows_fixed?(before, offset)
+          before && before[0] + before[1].length + 1 == offset && before[1] != "A"
+        end
+
+        def precedes_fixed?(after, offset)
+          after && after[0] == offset + 2 && after[1] != "A"
+        end
+
+        def recase(word, sentence_start)
+          bare, suffix = word.split("'", 2)
+          proper = proper_name(bare)
+          return [proper, suffix&.downcase].compact.join("'") if proper
+
+          sentence_start ? word.capitalize : word.downcase
+        end
+
+        def proper_name(bare)
+          CommentStyle::PROPER_NOUNS[bare] || RUST_PROPER_NOUNS[bare]
+        end
+
+        def unknown?(word)
+          bare = word.split("'", 2).first
+          !CommentStyle::Dictionary.english?(word) && !proper_name(bare)
+        end
+
+        def keep_capitals?(word)
+          bare = word.sub(/'[A-Z]{1,2}\z/, "")
+          return false if CommentStyle::PROPER_NOUNS.key?(bare) || RUST_PROPER_NOUNS.key?(bare)
+
+          CommentStyle::ACRONYMS.include?(bare) || RUST_ACRONYMS.include?(bare) ||
+            @constants.include?(bare) || bare.match?(/\A[IVX]+\z/)
+        end
+
+        def sentence_start?(comment, masked, offset)
+          before = masked[0, offset].sub(MARKER, "")
+          return before.match?(/[.!?]["')\]]*\s+\z/) if before.match?(/[[:alnum:]#{FILLER}]/o)
+          return true if before.match?(/\A\s*(?:[-*•]|─+|\d+[.)])\s+\z/)
+
+          after_sentence_end?(comment)
+        end
+
+        # Whether the line above, in the same paragraph, ends a sentence (or there is none).
+        def after_sentence_end?(comment)
+          previous = comment.full_line ? @by_line[comment.line - 1] : nil
+          return true unless previous&.full_line
+
+          body = previous.text.sub(MARKER, "").strip
+          body.empty? || body.match?(/[.!?]["')\]]*\z/)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/rust_comment_style/fixing.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module RustCommentStyle
+      # The rewrites for the fixable categories: all-caps words, long bold headings, long lines.
+      module Fixing
+        private
+
+        def fix_line(line, number, wanted)
+          comment = @by_line[number]
+          return line if comment.nil? || comment.text.match?(TMPL_MARKER)
+
+          text = fixed_text(comment, wanted)
+          code = line.byteslice(0, comment.col)
+          return wrap(code, text) if wanted.include?("long_line") && comment.full_line
+
+          "#{code}#{text}#{"\n" if line.end_with?("\n")}"
+        end
+
+        def fixed_text(comment, wanted)
+          text = wanted.include?("all_caps") ? fix_caps(comment) : comment.text
+          wanted.include?("long_bold") ? unbold(text) : text
+        end
+
+        def unbold(text)
+          heading = text[BOLD_HEADING, 2]
+          return text unless heading && heading.split.size > MAX_HEADING_WORDS
+
+          text.sub(BOLD_HEADING) { "#{Regexp.last_match(1)}#{heading}" }
+        end
+
+        def fix_caps(comment)
+          text = comment.text.dup
+          found = caps_words(comment)
+          found.reverse_each { |offset, word, replacement| text[offset, word.length] = replacement }
+          first, last = heading_run(comment, found)
+          return text unless first
+
+          text.insert(last, "**").insert(first, "**")
+        end
+
+        def heading_run(comment, found)
+          masked = mask(comment)
+          return unless found.size >= 2 && paragraph_start?(comment, masked, found.first[0])
+
+          run_bounds(found, masked)
+        end
+
+        # @return [Array(Integer, Integer), nil] where the first run of shouted words starts and
+        #   ends, when it reads as a heading
+        def run_bounds(found, masked)
+          run = first_run(found, masked)
+          finish = run_end(run, masked)
+          return unless run.size >= 2 && masked[finish..].match?(HEADING_END)
+          return if masked[run.first[0]...finish].split.size > MAX_HEADING_WORDS
+
+          [run.first[0], finish]
+        end
+
+        # The leading shouted words with only a gap between them.
+        def first_run(found, masked)
+          found.slice_when { |(a, word, _), (b, _, _)| !masked[(a + word.length)...b].match?(GAP) }.first
+        end
+
+        # Where a run of shouted words ends, taking in a trailing possessive `'s`.
+        def run_end(run, masked)
+          finish = run.last[0] + run.last[1].length
+          masked[finish, 2] == "'s" ? finish + 2 : finish
+        end
+
+        def paragraph_start?(comment, masked, offset)
+          return false if masked[0, offset].sub(MARKER, "").match?(/[[:alnum:]#{FILLER}]/o)
+
+          above = comment.full_line ? @by_line[comment.line - 1] : nil
+          !above&.full_line || above.text.match?(%r{\A/{2,3}!?\s*\z})
+        end
+
+        # Splits one over-long prose comment line in two. Lines with no safe
+        # break point (a long URL, an unbroken code span) are left for a person.
+        def wrap(indent, text)
+          whole = "#{indent}#{text}\n"
+          return whole if whole.chomp.length <= MAX_LINE
+
+          lead = text[MARKER].to_s
+          cut = wrap_cut(indent, text, lead)
+          return whole unless cut
+
+          "#{indent}#{text[0, cut].rstrip}\n#{wrap(indent, "#{lead}#{text[cut..].strip}")}"
+        end
+
+        # @return [Integer, nil] the offset to break at, nil when there is no safe one
+        def wrap_cut(indent, text, lead)
+          cut = text[0, MAX_LINE - indent.length + 1].rindex(" ")
+          cut unless cut.nil? || cut <= lead.length || text[0, cut].count("`").odd?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module RustCommentStyle
+      # Blanks the spans of a Rust 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
+
+        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?(%r{\A/{2,3}!?\s*\z})
+        end
+
+        def mask(comment)
+          head, text = open_span_head(comment)
+          body = text.gsub(CommentStyle::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[MARKER].to_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
+
+        def quoted_heading?(span)
+          return false unless span.start_with?('"') && !span.match?(CommentStyle::SQL_PHRASES)
+
+          capitals = span.scan(/\b[A-Z]{2,}\b/).size
+          capitals >= 3 || (capitals == 2 && !span.match?(/[a-z]/))
+        end
+
+        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?(CommentStyle::SQL_PHRASES)
+
+          database_file? ? strong.to_set : Set.new
+        end
+
+        def sql_classes(words)
+          bare = words.map { |w| w.sub(/'[A-Z]{1,2}\z/, "") } - ["A"]
+          [bare, bare.select { |w| CommentStyle::SQL_STRONG.include?(w) }, bare.select { |w| CommentStyle::SQL_WEAK.include?(w) }]
+        end
+
+        def database_file?
+          path.match?(CommentStyle::SQL_PATH)
+        end
+
+        def reads_as_sql?(bare, strong, weak)
+          sql_sets = [CommentStyle::SQL_STRONG, CommentStyle::SQL_WEAK, CommentStyle::SQL_NEUTRAL, CommentStyle::ACRONYMS]
+          return false unless bare.all? { |w| sql_sets.any? { |set| set.include?(w) } }
+
+          database_file? ? (strong.any? || weak.any?) : (strong.any? && (strong + weak).size >= 2)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+require_relative "source_file"
+require_relative "tokenizer"
+
+module Hecks
+  module Tools
+    module RustCommentStyle
+      # 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
+        def initialize(paths, only: nil)
+          @files = paths.flat_map { |p| File.directory?(p) ? rust_files(p) : [p] }.sort.uniq
+          @only = only
+        end
+
+        # Every violation across the whole file set, computed once.
+        #
+        # @return [Array<Violation>]
+        def violations
+          @violations ||= begin
+            found = @files.flat_map { |path| SourceFile.new(path).violations(only: @only) }
+            @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!
+          if wants_caps? && !CommentStyle::Dictionary.words
+            abort "fixing all_caps needs the word list CommentStyle::Dictionary uses"
+          end
+
+          @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
+
+        def wants_caps?
+          @only.nil? || @only.include?("all_caps")
+        end
+
+        def rust_files(dir)
+          Dir[File.join(dir, "**", "*.rs")].reject { |p| p.include?("/target/") }
+        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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+require_relative "masking"
+require_relative "caps_words"
+require_relative "text_checks"
+require_relative "fixing"
+require_relative "structure"
+
+module Hecks
+  module Tools
+    module RustCommentStyle
+      # One parsed `.rs` file and the violations found in it.
+      class SourceFile
+        include Masking
+        include CapsWords
+        include TextChecks
+        include Fixing
+        include Structure
+
+        attr_reader :path, :lines, :comments
+
+        def initialize(path, source = nil)
+          @path = path
+          @source = source || File.read(path)
+          @lines = @source.lines
+          @comments = generated? ? [] : Tokenizer.comments(@source)
+          @by_line = @comments.to_h { |c| [c.line, c] }
+          @open_spans = open_spans
+          @constants = code_constants
+        end
+
+        # Finds every place this file departs from the style guide.
+        def violations(only: nil)
+          return [] if generated?
+
+          found = text_violations + structure_violations
+          found = found.select { |v| only.include?(v.category) } if only
+          found.sort_by { |v| [v.line, v.category] }
+        end
+
+        # Rewrites the mechanical categories.
+        def fixed(only: nil)
+          return @source if generated?
+
+          wanted = (only || FIXABLE) & FIXABLE
+          @lines.map.with_index(1) { |line, number| fix_line(line, number, wanted) }.join
+        end
+
+        # A generated file's comments belong to its generator: `hecks project_rust`
+        # and friends stamp this exact banner on line one.
+        def generated?
+          @lines.first.to_s.start_with?("// GENERATED by")
+        end
+
+        private
+
+        # SCREAMING_SNAKE names this file defines: `const`/`static` items, plus
+        # enum variants and macro-visible names that read the same way.
+        def code_constants
+          code_only = @source.dup
+          Tokenizer.comments(@source).each { |c| code_only[c.line - 1] ||= "" }
+          names = Set.new
+          code_only.scan(/\b(?:const|static)\s+(?:mut\s+)?([A-Z][A-Z0-9_]*)\b/) { |(n)| names << n }
+          code_only.scan(/"([A-Z][A-Z0-9_]{2,})"/) { |(n)| names << n }
+          names
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/rust_comment_style/structure.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module RustCommentStyle
+      # Tracks whether the line just observed sits inside a `#[cfg(test)]`
+      # module, by brace depth.
+      class TestCfgTracker
+        TEST_CFG = /\A\s*#\[cfg\(test\)\]/
+
+        # Starts outside every module, at brace depth zero.
+        def initialize
+          @depth = 0
+          @test_depth = nil
+        end
+
+        # Updates the tracked brace depth with one more source line.
+        def observe(line)
+          @depth += line.count("{") - line.count("}")
+          @test_depth = @depth if line.match?(TEST_CFG)
+          @test_depth = nil if @test_depth && @depth < @test_depth
+        end
+
+        # Answers whether the line just observed sits inside a test module.
+        def inside?
+          !@test_depth.nil?
+        end
+      end
+
+      # The structural categories: `pub` items with no `///` doc above, and files with no `//!`
+      # module doc at the top.
+      module Structure
+        private
+
+        # Attribute lines between the doc and item are skipped.
+        def structure_violations
+          (test_tree? ? [] : missing_doc_violations) + missing_module_doc_violation
+        end
+
+        def test_tree?
+          path.split("/").include?("tests")
+        end
+
+        def missing_doc_violations
+          tracker = TestCfgTracker.new
+          @lines.each_with_index.filter_map do |line, index|
+            tracker.observe(line)
+            missing_doc_violation(line, index + 1) unless tracker.inside?
+          end
+        end
+
+        def missing_doc_violation(line, line_number)
+          match = PUB_ITEM.match(line)
+          return unless match
+          return if match[1] == "fn" && SELF_EVIDENT_FNS.include?(match[2])
+          return if doc_above?(line_number)
+
+          Violation.new(path, line_number, "missing_doc", "#{match[1]} #{match[2]}")
+        end
+
+        def doc_above?(line_number)
+          cursor = line_number - 1
+          cursor -= 1 while cursor.positive? && @lines[cursor - 1].to_s.match?(ATTR_LINE)
+          @lines[cursor - 1].to_s.match?(DOC_LINE)
+        end
+
+        def missing_module_doc_violation
+          return [] if test_tree?
+          return [] unless ["mod.rs", "lib.rs", "main.rs"].include?(File.basename(path))
+          return [] if @lines.first(3).any? { |l| l.match?(MOD_DOC_LINE) }
+
+          [Violation.new(path, 1, "missing_module_doc", File.basename(path))]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module RustCommentStyle
+      # The prose categories: every check that reads one Rust comment's text.
+      module TextChecks
+        private
+
+        def text_violations
+          @comments.flat_map do |comment|
+            next [] if comment.text.match?(TMPL_MARKER)
+
+            caps_violations(comment) + constant_violations(comment) + unknown_violations(comment) +
+              bold_violations(comment) + history_violations(comment) + length_violations(comment)
+          end
+        end
+
+        def caps_violations(comment)
+          caps_words(comment).map do |_, word, replacement|
+            Violation.new(path, comment.line, "all_caps", "#{word} -> #{replacement}")
+          end
+        end
+
+        def constant_violations(comment)
+          words = mask(comment).scan(CommentStyle::CAPS_WORD).uniq
+          words.select { |w| @constants.include?(w) && !CommentStyle::ACRONYMS.include?(w) }
+               .map { |w| Violation.new(path, comment.line, "bare_constant", w) }
+        end
+
+        def unknown_violations(comment)
+          words = mask(comment).scan(CommentStyle::CAPS_WORD).uniq - ["A"]
+          words.reject { |w| keep_capitals?(w) }.select { |w| unknown?(w) }
+               .map { |w| Violation.new(path, comment.line, "unknown_capitals", w) }
+        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 history_violations(comment)
+          masked = comment.text.gsub(/`[^`]*`/) { |span| " " * span.length }
+          pattern = CommentStyle::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].to_s.chomp.length
+          return [] if length <= MAX_LINE
+
+          [Violation.new(path, comment.line, "long_line", "#{length} characters")]
+        end
+      end
+    end
+  end
+end