hecks 3.5.0 → 3.6.0

data/lib/hecks/tools/comment_style.rb

@@ -6,6 +6,13 @@ require "optparse"
 require "pathname"
 require "ripper"
 require_relative "../tools"
+require_relative "comment_style/vocabulary"
+require_relative "comment_style/patterns"
+require_relative "comment_style/dictionary"
+require_relative "comment_style/baseline"
+require_relative "comment_style/source_file"
+require_relative "comment_style/run"
+require_relative "comment_style/cli"
 
 module Hecks
   module Tools
@@ -42,158 +49,23 @@ module Hecks
 
       FIXABLE = %w[all_caps long_bold long_line].freeze
 
-      # Initialisms and keywords that are correctly written in capitals.
-      ACRONYMS = %w[
-        ARGV ARN AZ ECR ES FSM GVL IAM IGW IPC IRB LLM MB MVCC NAT OOM RDS SG SIGKILL SIGTERM STDIO TOML
-        UI VCS VM VPC WASI
-        ABC ACID ADR API ASC ASCII AST AWS BFS BYPASSRLS CAS CDN CEO CI CLI CPU CRUD CSRF CSS CSV CTE DB DBA DDD DDL
-        DELETE DESC DFS DML DNS DSL ENV ERB ERD FIFO FIXME FK FQN GC GET GIN HMAC HTML HTTP HTTPS ID INSERT IO IR ISO
-        JS JSON JSONB JSONL JWKS JWT LIFO LRU MCP MDN MRI MVP NAMEDATALEN NIL NULL OIDC OK ORM OS
-        PATCH PG PID PK PM POSIX POST PR PRAGMA PRD PUT QA QC RAM RBAC README REPL REST RLS RNG RPC RUBYOPT
-        SAM SAVEPOINT SDK SELECT SHA SME SQL SSH SSL SSM SW STDERR STDIN STDOUT TCP TLA TLS TOCTOU TODO TTL UID UL
-        URI URL UTC UTF UUID VO WASM XML YAML
-        ACL ALB BC GNU OAC WAF
-        CLOUDFRONT ECS HSM KMS
-      ].to_set.freeze
-
-      # Names whose correct spelling is neither all-caps nor all-lowercase.
-      PROPER_NOUNS = {
-        "CLOUDFLARE" => "Cloudflare", "OAUTH" => "OAuth", "RSPEC" => "RSpec", "JAVASCRIPT" => "JavaScript",
-        "GITHUB" => "GitHub", "GOOGLE" => "Google", "GRAPHVIZ" => "Graphviz", "HECKS" => "Hecks",
-        "POSTGRES" => "Postgres", "POSTGRESQL" => "PostgreSQL", "PUMA" => "Puma", "RAILS" => "Rails",
-        "RUBY" => "Ruby", "RUST" => "Rust", "SQLITE" => "SQLite"
-      }.freeze
-
-      # 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
-
-      # SQL keywords that are rarely English emphasis. Kept in capitals on a line
-      # that reads as SQL, and always kept in a file that talks to a database.
-      SQL_STRONG = %w[
-        ALTER ATTACH BEGIN CASCADE COMMIT CONCURRENTLY DETACH DISTINCT FORCE GRANT LIMIT MATERIALIZED
-        NULLS OFFSET PARTITION RETURNING REVOKE ROLLBACK SERIALIZABLE VACUUM
-      ].to_set.freeze
-
-      # SQL keywords that are also everyday emphasis targets (`FROM`, `FIRST`, `SET`).
-      SQL_WEAK = %w[
-        COLUMN CONSTRAINT CREATE DEFAULT DROP EXCLUSIVE EXISTS FIRST FROM INDEX JOIN LAST LOCK LOGIN
-        NOBYPASSRLS NOCREATEDB NOCREATEROLE NOLOGIN NOSUPERUSER OWNER POLICY
-        REFERENCES ROLE SCHEMA SET SHARE TABLE TRANSACTION TRIGGER UNION UNIQUE UPDATE VALUES VIEW WHERE
-      ].to_set.freeze
-
-      SQL_NEUTRAL = %w[ALL AND AS BY FOR IN IS NOT OF ON OR TO].to_set.freeze
-
-      SQL_PATH = %r{sql|postgres|/d1|_era|/era|lineage|outbox|schema|persistence}
-
-      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*\u2190)
-      /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:|!)/
-
-      SELF_EVIDENT = %w[
-        to_s to_str to_sym to_h to_a to_proc inspect hash eql? == === <=> method_missing
-        respond_to_missing? pretty_print
-      ].to_set.freeze
-
-      # Stands in for a protected span so it still reads as a word, not a gap.
-      FILLER = "\u00A7"
-
-      # 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
-
       Violation = Struct.new(:path, :line, :category, :message)
       MethodDef = Struct.new(:name, :line, :params, :visibility, :raises, :block_param, :type_fqn)
       TypeDef = Struct.new(:fqn, :line, :namespace_only)
       Comment = Struct.new(:line, :col, :text, :full_line)
       Block = Struct.new(:line, :lines, :key)
 
-      # Decides whether a capitalised token is an English word being shouted;
-      # anything else keeps its capitals and is reported for a person to look at.
-      module Dictionary
-        WORDS = "/usr/share/dict/words"
-
-        # Technical vocabulary the system word list lacks.
-        EXTRA = %w[
-          adversarial allowlist anymore app apps arg args arity async backend backtrace baseline
-          boolean bootable bootstrapping bluebook byte callee canonicalized changelog checklist
-          checkpoint codebase codemod config database dataset dedupe deduped enqueue evaluator
-          filename fixpoint formatting frontend glob grep handover hardcoded hecksagon heredoc held
-          hoc hostname idempotency idempotent inline keyword landmine lifecycle lookup mapping
-          memoised memoized memoizes metadata metaprogrammed monkeypatch monorepo multi mutex
-          namespace noop numeric op ops parameterized params pathname payload plugin postcondition
-          pre reachability reentrant refactor regex regexes rekey rekeyed repo restartable retrofit
-          reusable roadmap rollup runtime shortcut standalone stringified struct subprocess
-          subprocesses subroutine substring superuser symlink sync timestamp tmp tmpl touchpoint
-          trickiest triggerable tuple undecoded unsanitized untargeted upsert username webhook
-          widget workaround worklist worklists
-        ].freeze
-
-        SUFFIXES = [
-          ["", ""], ["s", ""], ["es", ""], ["ed", ""], ["d", ""], ["ing", ""], ["ing", "e"], ["ies", "y"],
-          ["ied", "y"], ["ly", ""], ["er", ""], ["est", ""], ["ier", "y"], ["ised", "ized"], ["ise", "ize"],
-          ["isation", "ization"], ["our", "or"], ["lling", "ling"], ["lled", "led"]
-        ].freeze
-
-        module_function
-
-        # Loads and memoizes the system word list, once per process.
-        def words
-          return @words if defined?(@words)
-
-          @words = File.exist?(WORDS) ? Set.new(File.foreach(WORDS, chomp: true).map(&:downcase)).merge(EXTRA) : nil
-        end
-
-        # Checks a capitalized token against the word list, stripped and stemmed.
-        # Always true when this machine has no word list to consult.
-        def english?(word)
-          return true unless words
-
-          bare = word.downcase.sub(/n't\z/, "").sub(/'.*\z/, "")
-          SUFFIXES.any? do |suffix, replacement|
-            next false unless bare.end_with?(suffix)
+      # Bare class/module names on Hecks's documented public surface (ADR 0075 ticket 01):
+      # an operator or a client calls these directly. The DSL itself (`aggregate`,
+      # `command`, `query`, ...) is invoked through the `Hecks.bluebook` block, not by
+      # naming a builder class, so its builder classes stay off this list.
+      #
+      # A method's structural checks (tags, `undocumented_method`) apply only when its
+      # innermost enclosing type's own name is here; everything else is internal and
+      # needs no doc unless it carries a real why.
+      PUBLIC_SURFACE = Set["Storehouse"].freeze
 
-            stem = bare.delete_suffix(suffix) + replacement
-            words.include?(stem) || words.include?(stem.sub(/(.)\1\z/, '\1'))
-          end
-        end
-      end
+      extend Cli
 
       # Class and module names defined under `lib/`, keyed by their shouted form.
       def self.class_names
@@ -209,864 +81,9 @@ module Hecks
         Ripper.lex(source).reject { |token| CODE_NOISE.include?(token[1]) }.map { |token| token[2] }
       end
 
-      # Bare class/module names on Hecks's documented public surface (ADR 0075 ticket 01):
-      # an operator or a client calls these directly. The DSL itself (`aggregate`,
-      # `command`, `query`, ...) is invoked through the `Hecks.bluebook` block, not by
-      # naming a builder class, so its builder classes stay off this list.
-      #
-      # A method's structural checks (tags, `undocumented_method`) apply only when its
-      # innermost enclosing type's own name is here; everything else is internal and
-      # needs no doc unless it carries a real why.
-      PUBLIC_SURFACE = Set["Storehouse"].freeze
-
       def self.public_surface
         PUBLIC_SURFACE
       end
-
-      # The checked-in list of comment blocks already over `MAX_BLOCK` lines.
-      #
-      # Keyed by first-line text, not line number, so edits above a block don't break its key.
-      module Baseline
-        FILE = ".standardize_comments_baseline.json"
-
-        # The checkout this file lives in: the baseline's home when no `root:` is given.
-        ROOT = File.expand_path("../../..", __dir__)
-
-        PATH = File.join(ROOT, FILE)
-
-        module_function
-
-        # The baseline's location inside a checkout.
-        #
-        # @param root [String] the checkout's root directory
-        # @return [String] the baseline file's path
-        def path_in(root) = File.join(root, FILE)
-
-        # Reads the baseline from disk.
-        def load(path = PATH)
-          File.exist?(path) ? JSON.parse(File.read(path, encoding: Encoding::UTF_8)) : {}
-        end
-
-        # Writes a baseline in a stable order, so a rewrite shows only real changes in a diff.
-        def dump(blocks, path = PATH)
-          sorted = blocks.sort.to_h { |file, keys| [file, keys.sort.to_h] }
-          File.write(path, "#{JSON.pretty_generate(sorted)}\n")
-        end
-      end
-
-      # One parsed source file and the violations found in it.
-      class SourceFile
-        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
-
-        # Finds every run of consecutive full-line comments longer than `MAX_BLOCK`.
-        def long_blocks
-          return [] if generated?
-
-          seen = Hash.new(0)
-          runs = @comments.select(&:full_line).slice_when { |above, below| below.line != above.line + 1 }
-          runs.select { |run| run.size > MAX_BLOCK }.map { |run| Block.new(run.first.line, run.size, block_key(run, seen)) }
-        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
-
-        # The text of a block's first line, without its `#`, is its key. A second block opened by
-        # the same text in this file gets a `#2` suffix, and so on.
-        def block_key(run, seen)
-          text = run.first.text.sub(/\A#+\s*/, "").strip[0, MAX_ANCHOR]
-          text = "(empty)" if text.empty?
-          seen[text] += 1
-          seen[text] == 1 ? text : "#{text} ##{seen[text]}"
-        end
-
-        # A block fails when it has no baseline entry, or has grown past the length recorded there.
-        def long_block_violations(baseline)
-          held = baseline.fetch(path.delete_prefix("./"), {})
-          long_blocks.filter_map do |block|
-            allowed = held[block.key]
-            next if allowed && block.lines <= allowed
-
-            detail = allowed ? "baselined at #{allowed}" : "over #{MAX_BLOCK}"
-            Violation.new(path, block.line, "long_block", "#{block.lines} lines, #{detail}: #{block.key}")
-          end
-        end
-
-        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
-
-        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
-
-        # 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
-
-        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
-
-        def caps_words(comment)
-          masked = mask(comment)
-          matches = []
-          masked.scan(CAPS_WORD) { matches << Regexp.last_match }
-          sql = sql_keywords(comment, matches.map { |match| match[0] })
-          found = matches.filter_map do |match|
-            word = match[0]
-            next 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
-          (drop_stray_articles(found) + possessives(masked)).sort_by(&:first)
-        end
-
-        # 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)
-          text = comment.text
-          head = ""
-          if @open_spans[comment.line]
-            lead = text[/\A#+\s*/].length
-            close = text.index("`", lead)
-            cut = close ? close + 1 : text.length
-            head = text[0, lead] + (FILLER * (cut - lead))
-            text = text[cut..]
-          end
-          body = text.gsub(PROTECTED_SPANS) { |span| quoted_heading?(span) ? span : FILLER * span.length }
-          open = body.rindex("`")
-          body = body[0, open] + (FILLER * (body.length - open)) if open
-          head + 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|
-            above = @by_line[comment.line - 1]
-            continues = comment.full_line && above&.full_line && !above.text.match?(/\A#+\s*\z/)
-            inside = false unless continues
-            open[comment.line] = inside
-            inside ^= comment.text.count("`").odd?
-          end
-        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 = words.map { |word| word.sub(/'[A-Z]{1,2}\z/, "") } - ["A"]
-          strong = bare.select { |word| SQL_STRONG.include?(word) }
-          weak = bare.select { |word| SQL_WEAK.include?(word) }
-          database_file = path.match?(SQL_PATH)
-          return bare.to_set if reads_as_sql?(bare, strong, weak, database_file)
-          return (strong + weak).to_set if comment.text.match?(SQL_PHRASES)
-
-          database_file ? strong.to_set : Set.new
-        end
-
-        def reads_as_sql?(bare, strong, weak, database_file)
-          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
-
-        # `Finding`'s: the capital follows a code span, so `CAPS_WORD` never sees it.
-        def possessives(masked)
-          found = []
-          masked.scan(/(?<=#{FILLER})'S\b/) { found << [Regexp.last_match.begin(0) + 1, "S", "s"] }
-          found
-        end
-
-        # An "A" is only emphasis when a word beside it is being fixed too.
-        def drop_stray_articles(found)
-          found.each_with_index.reject do |(offset, word, _), index|
-            before = index.positive? ? found[index - 1] : nil
-            after = found[index + 1]
-            beside = (before && before[0] + before[1].length + 1 == offset && before[1] != "A") ||
-                     (after && after[0] == offset + 2 && after[1] != "A")
-            word == "A" && !beside
-          end.map(&:first)
-        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
-
-        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
-
-        # A shouted product or class name (`POSTGRESERA`) gets its real spelling
-        # back. An English word that is also a class name (`VALUE`) stays prose.
-        def proper_name(bare)
-          PROPER_NOUNS[bare] || (CommentStyle.class_names[bare] unless Dictionary.english?(bare))
-        end
-
-        # Neither English nor a known name, so lowercasing it would be a guess.
-        def unknown?(word)
-          bare = word.split("'", 2).first
-          !Dictionary.english?(word) && !proper_name(bare)
-        end
-
-        def keep_capitals?(word)
-          bare = word.sub(/'[A-Z]{1,2}\z/, "")
-          return false if PROPER_NOUNS.key?(bare)
-
-          ACRONYMS.include?(bare) || @constants.include?(bare) || bare.match?(/\A[IVX]+\z/)
-        end
-
-        def sentence_start?(comment, masked, offset)
-          before = masked[0, offset].sub(/\A#+\s*/, "")
-          return before.match?(/[.!?]["')\]]*\s+\z/) if before.match?(/[[:alnum:]#{FILLER}]/)
-          return true if before.match?(/\A\s*(?:[-*•]|─+|\d+[.)])\s+\z/)
-          return false if masked[0, offset].match?(/\A#\s{3,}/)
-
-          previous = comment.full_line ? @by_line[comment.line - 1] : nil
-          return true unless previous&.full_line
-
-          body = previous.text.sub(/\A#+\s*/, "").strip
-          body.empty? || body.match?(/[.!?]["')\]]*\z/)
-        end
-
-        def fix_line(line, number, wanted)
-          comment = @by_line[number]
-          return line if comment.nil? || comment.text.match?(DIRECTIVE)
-
-          text = wanted.include?("all_caps") ? fix_caps(comment) : comment.text
-          text = unbold(text) if wanted.include?("long_bold")
-          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 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
-
-        # An all-caps run that opens a paragraph and stops at a dash or a full stop
-        # is that paragraph's heading, so it becomes bold rather than plain text.
-        def heading_run(comment, found)
-          masked = mask(comment)
-          return unless found.size >= 2 && paragraph_start?(comment, masked, found.first[0])
-
-          run = found.slice_when { |(a, word, _), (b, _, _)| !masked[(a + word.length)...b].match?(GAP) }.first
-          finish = run.last[0] + run.last[1].length
-          finish += 2 if masked[finish, 2] == "'s"
-          return unless run.size >= 2 && masked[finish..].match?(HEADING_END)
-          return if masked[run.first[0]...finish].split.size > MAX_HEADING_WORDS || documents_method?(comment)
-
-          [run.first[0], finish]
-        end
-
-        # The first line above a `def` has to be a sentence about the method, so a
-        # heading there stays plain text.
-        def documents_method?(comment)
-          line = comment.line
-          line += 1 while @by_line[line + 1]&.full_line
-          @lines[line].to_s.match?(/\A\s*(?:\w+\s+)?def\s/)
-        end
-
-        def paragraph_start?(comment, masked, offset)
-          return false if masked[0, offset].sub(/\A#+\s*/, "").match?(/[[:alnum:]#{FILLER}]/)
-
-          above = comment.full_line ? @by_line[comment.line - 1] : nil
-          !above&.full_line || above.text.match?(/\A#+\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[/\A#+\s*/]
-          lead += "  " if text.match?(/\A#+\s*@\w/)
-          cut = text[0, MAX_LINE - indent.length + 1].rindex(" ")
-          return whole if cut.nil? || cut <= lead.length || text[0, cut].count("`").odd?
-
-          "#{indent}#{text[0, cut].rstrip}\n#{wrap(indent, "#{lead}#{text[cut..].strip}")}"
-        end
-
-        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")
-          if doc.empty?
-            return [] if SELF_EVIDENT.include?(method.name)
-
-            return [Violation.new(path, method.line, "undocumented_method", "##{method.name}")]
-          end
-          return [] if doc.match?(/@api private|@private|:nodoc:|\(see (?:`[^`]+`|#\w)[^)]*\)\W*\z/m)
-
-          tag_violations(method, doc)
-        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
-
-      # Walks a Ripper s-expression collecting method and type definitions
-      # along with the visibility each method ends up with.
-      class Walker
-        Scope = Struct.new(:nesting, :visibility)
-
-        attr_reader :methods, :types
-
-        def initialize
-          @methods = []
-          @types = []
-          @private_names = Set.new
-        end
-
-        # Visits one Ripper node, recording any method or type it defines.
-        def walk(node, scope)
-          return unless node.is_a?(Array)
-
-          case node[0]
-          when :class then open_type(node[1], node[3], scope)
-          when :module then open_type(node[1], node[2], scope)
-          when :sclass then walk_body(node[2], Scope.new(scope.nesting, :public))
-          when :def then record(node[1], node[2], node[3], scope.visibility, scope.nesting)
-          when :defs then record(node[3], node[4], node[5], :public, scope.nesting)
-          when :vcall, :var_ref then switch_visibility(node, scope)
-          when :command, :method_add_arg then visibility_call?(node, scope) || walk_children(node, scope)
-          else walk_children(node, scope)
-          end
-        end
-
-        private
-
-        def walk_children(node, scope)
-          node.each { |child| walk(child, scope) if child.is_a?(Array) }
-        end
-
-        # `private :name` can follow the definition, so it is applied once the
-        # whole body has been seen.
-        def walk_body(body, scope)
-          first = @methods.length
-          outer = @private_names
-          @private_names = Set.new
-          walk_children(body, scope) if body.is_a?(Array)
-          @methods[first..].each { |m| m.visibility = :private if @private_names.include?(m.name) }
-          @private_names = outer
-        end
-
-        def open_type(const, body, scope)
-          nesting = scope.nesting + [const_name(const)]
-          statements = body.is_a?(Array) && body[0] == :bodystmt ? Array(body[1]) : []
-          namespace = statements.all? { |s| !s.is_a?(Array) || %i[class module void_stmt].include?(s[0]) }
-          @types << TypeDef.new(nesting.join("::"), line_of(const), namespace)
-          walk_body(body, Scope.new(nesting, :public))
-        end
-
-        def const_name(node)
-          node.flatten.grep(String).join("::")
-        end
-
-        def line_of(node)
-          position = node.flatten.each_cons(2).find { |a, b| a.is_a?(Integer) && b.is_a?(Integer) }
-          position ? position[0] : 0
-        end
-
-        def switch_visibility(node, scope)
-          case node[1].is_a?(Array) ? node[1][1] : nil
-          when "private", "protected" then scope.visibility = :private
-          when "public", "module_function" then scope.visibility = :public
-          end
-        end
-
-        def visibility_call?(node, scope)
-          head = node[0] == :command ? node[1] : node.dig(1, 1)
-          return false unless head.is_a?(Array) && head[0] == :@ident
-          return false unless %w[private protected private_class_method].include?(head[1])
-
-          arguments = node[0] == :command ? node[2] : node.dig(2, 1)
-          Array(arguments.is_a?(Array) ? arguments[1] : nil).each do |argument|
-            next unless argument.is_a?(Array)
-
-            case argument[0]
-            when :def then record(argument[1], argument[2], argument[3], :private, scope.nesting)
-            when :defs then record(argument[3], argument[4], argument[5], :private, scope.nesting)
-            when :symbol_literal, :dyna_symbol
-              @private_names << argument.flatten.grep(String).last
-            else walk(argument, scope)
-            end
-          end
-          true
-        end
-
-        def record(name_node, params, body, visibility, nesting)
-          names, block = parameter_names(params)
-          @methods << MethodDef.new(name_node[1], name_node[2][0], names, visibility, raises?(body), block,
-                                    nesting.join("::"))
-        end
-
-        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
-
-          _, required, optional, rest, post, keywords, keyrest, block = params
-          names = idents(required) + Array(optional).map { |pair| pair[0][1] } + splat_name(rest) +
-                  idents(post) + Array(keywords).map { |pair| pair[0][1].chomp(":") } + splat_name(keyrest)
-          [names, splat_name(block).first]
-        end
-
-        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.
-        def splat_name(node)
-          node.is_a?(Array) && node[1].is_a?(Array) ? [node[1][1]] : []
-        end
-
-        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
-      end
-
-      # 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 do |fqn, group|
-            next unless CommentStyle.public_surface.include?(fqn.to_s.split("::").last)
-            next if group.any? { |source, type| source.documented?(type) }
-
-            source, type = group.first
-            Violation.new(source.path, type.line, "undocumented_class", fqn)
-          end
-        end
-      end
-
-      # Builds the CLI's option parser, filling `options` as flags are seen.
-      def self.option_parser(options)
-        OptionParser.new do |opts|
-          opts.banner = "Usage: hecks check_comments [--report|--check|--fix] [--only a,b] PATH..."
-          opts.on("--report", "summary tables (default)") { options[:mode] = :report }
-          opts.on("--check", "list every violation, exit 1 if any") { options[:mode] = :check }
-          opts.on("--fix", "rewrite fixable categories: #{FIXABLE.join(', ')}") { options[:mode] = :fix }
-          opts.on("--write-baseline", "record every block over #{MAX_BLOCK} lines as tolerated") do
-            options[:mode] = :write_baseline
-          end
-          opts.on("--only LIST", Array, "limit to: #{CATEGORIES.keys.join(', ')}") { |list| options[:only] = list }
-          opts.on("--code-unchanged REF", "exit 1 if any file's code (not comments) differs from REF") do |ref|
-            options[:mode] = :code_unchanged
-            options[:ref] = ref
-          end
-          opts.on("--json", "machine-readable output") { options[:json] = true }
-          opts.on("--top N", Integer, "rows in the worst-files table") { |n| options[:top] = n }
-        end
-      end
-
-      # Prints `--report`, `--check`, or `--json` output for a finished run.
-      def self.render(run, options)
-        found = run.violations
-        if options[:json]
-          puts JSON.pretty_generate(found.map(&:to_h))
-        elsif options[:mode] == :check
-          found.each { |v| puts "#{v.path}:#{v.line}: [#{v.category}] #{v.message}" }
-        else
-          puts run.report(top: options[:top])
-        end
-        options[:mode] == :check && found.any? ? 1 : 0
-      end
-
-      # The CLI entry point: parses `argv` and runs the requested mode.
-      #
-      # Paths after a `--` are never read as flags, and a path that does not exist is refused.
-      def self.main(argv, root: Baseline::ROOT)
-        options = { mode: :report, top: 20 }
-        parser = option_parser(options)
-        paths = parser.parse(argv)
-        unknown = Array(options[:only]) - CATEGORIES.keys
-        abort "unknown categories: #{unknown.join(', ')}" unless unknown.empty?
-        abort parser.help if paths.empty?
-        missing = paths.reject { |path| File.exist?(path) }
-        abort "no such path: #{missing.join(', ')}" unless missing.empty?
-
-        baseline_path = Baseline.path_in(root)
-        run = Run.new(paths, only: options[:only], baseline: Baseline.load(baseline_path))
-        case options[:mode]
-        when :fix then puts("rewrote #{run.fix!} files") || 0
-        when :write_baseline then write_baseline(run, baseline_path)
-        when :code_unchanged then report_code_changes(changed_since(run, options[:ref]))
-        else render(run, options)
-        end
-      end
-
-      # Rewrites the baseline file from the blocks over `MAX_BLOCK` lines that `run` finds.
-      def self.write_baseline(run, path = Baseline::PATH)
-        held = run.long_block_baseline
-        Baseline.dump(held, path)
-        puts "recorded #{held.values.sum(&:size)} blocks in #{held.size} files at #{path}"
-        0
-      end
-
-      # The files `run` finds changed since `ref`, refusing a ref that names no commit.
-      def self.changed_since(run, ref)
-        run.code_changed_since(ref)
-      rescue ArgumentError => e
-        abort e.message
-      end
-
-      # Prints `--code-unchanged`'s verdict.
-      def self.report_code_changes(changed)
-        changed.each { |path| puts "#{path}: code changed, not just comments" }
-        puts "code unchanged" if changed.empty?
-        changed.empty? ? 0 : 1
-      end
     end
   end
 end