hecks 4.0.0 → 6.0.0

data/lib/hecks/tickets/bluebook/tickets.bluebook

@@ -1,4 +1,4 @@
-# The Tickets chapter: what a maintainer observed about Hecks that needs a decision or a fix, the
+# The Tickets bluebook: what a maintainer observed about Hecks that needs a decision or a fix, the
 # and the decisions that settle them.
 #
 # QualityControl has its own Ticket, the issue raised for a Bug in an outside tracker, and the
@@ -84,17 +84,12 @@ Hecks.bluebook "Tickets" do
     command "Report" do
       goal "Record something observed about Hecks as a finding"
 
-      attribute :finding,      FindingKey
-      attribute :title,       Title
-      attribute :body,        Body, optional: true
-      attribute :source,      Source
-      attribute :fingerprint, Fingerprint, optional: true
+      attribute :finding,      FindingKey, sets: true
+      attribute :title,       Title, sets: true
+      attribute :body,        Body, optional: true, sets: true
+      attribute :source,      Source, sets: true
+      attribute :fingerprint, Fingerprint, optional: true, sets: true
 
-      sets :finding
-      sets :title
-      sets :body
-      sets :source
-      sets :fingerprint
 
       emits "FindingReported"
     end
@@ -104,11 +99,9 @@ Hecks.bluebook "Tickets" do
     command "ReportFailedRun" do
       goal "Record a failed conformance or gate run as a finding"
 
-      attribute :finding, FindingKey
-      attribute :body,   Body
+      attribute :finding, FindingKey, sets: true
+      attribute :body,   Body, sets: true
 
-      sets :finding
-      sets :body
       sets :fingerprint, to: "run"
       sets :title,  to: "A Codebase run failed"
       sets :source, to: "qa_loop"
@@ -122,11 +115,9 @@ Hecks.bluebook "Tickets" do
     command "ReportLag" do
       goal "Record a lane that has stood behind the lane it follows too long as a finding"
 
-      attribute :finding, FindingKey
-      attribute :body,    Body
+      attribute :finding, FindingKey, sets: true
+      attribute :body,    Body, sets: true
 
-      sets :finding
-      sets :body
       sets :fingerprint, to: "lane-lag"
       sets :title,  to: "A lane is behind the lane it follows"
       sets :source, to: "qa_loop"
@@ -139,11 +130,9 @@ Hecks.bluebook "Tickets" do
       goal "Give a finding its kind and severity"
 
       reference_to Finding
-      attribute :kind,     Kind
-      attribute :severity, Severity
+      attribute :kind,     Kind, sets: true
+      attribute :severity, Severity, sets: true
 
-      sets :kind
-      sets :severity
 
       emits "FindingTriaged"
     end
@@ -153,9 +142,8 @@ Hecks.bluebook "Tickets" do
       goal "Record the pull request that fixes a triaged finding"
 
       reference_to Finding
-      attribute :fix_pr_number, Number
+      attribute :fix_pr_number, Number, sets: true
 
-      sets :fix_pr_number
 
       emits "FixLinked"
     end
@@ -174,9 +162,8 @@ Hecks.bluebook "Tickets" do
       goal "Close a finding without a fix, with the reason"
 
       reference_to Finding
-      attribute :dismissal, Body
+      attribute :dismissal, Body, sets: true
 
-      sets :dismissal
 
       emits "FindingDismissed"
     end
@@ -194,9 +181,8 @@ Hecks.bluebook "Tickets" do
       goal "Record the GitHub issue number once the issue is opened"
 
       reference_to Finding
-      attribute :issue_number, Number
+      attribute :issue_number, Number, sets: true
 
-      sets :issue_number
 
       emits "IssueRecorded"
     end
@@ -205,9 +191,8 @@ Hecks.bluebook "Tickets" do
       goal "Record that GitHub could not be driven, so a later run retries"
 
       reference_to Finding
-      attribute :sync_failure, Body
+      attribute :sync_failure, Body, sets: true
 
-      sets :sync_failure
 
       emits "SyncFailed"
     end
@@ -225,7 +210,7 @@ Hecks.bluebook "Tickets" do
     attribute :adr,       AdrNumber
     attribute :title,     AdrTitle
     attribute :supersedes, AdrNumber, optional: true
-    attribute :settles,   FindingKey, optional: true
+    reference_to Finding, as: :settles, optional: true
     identified_by :adr
 
     value_object "AdrNumber" do
@@ -238,25 +223,20 @@ Hecks.bluebook "Tickets" do
       invariant("a decision has a title") { !value.to_s.empty? }
     end
 
-    value_object "FindingKey" do
-      attribute :value, String, matches: :present
-    end
-
     lifecycle :status, default: "draft" do
       transition "Accept"    => "accepted",   from: "draft"
       transition "Supersede" => "superseded", from: "accepted"
+      mark :terminal, "superseded"
     end
 
     command "Draft" do
       role "Maintainer"
       goal "Open a decision record, optionally for the finding it settles"
 
-      attribute :adr,       AdrNumber
-      attribute :title,     AdrTitle
-      attribute :settles,   FindingKey, optional: true
+      attribute :adr,       AdrNumber, sets: true
+      attribute :title,     AdrTitle, sets: true
+      reference_to Finding, as: :settles, optional: true
 
-      sets :adr
-      sets :title
       sets :settles
 
       emits "AdrDrafted"
@@ -276,9 +256,8 @@ Hecks.bluebook "Tickets" do
       goal "Record that a later decision replaces this one"
 
       reference_to Adr
-      attribute :supersedes, AdrNumber
+      attribute :supersedes, AdrNumber, sets: true
 
-      sets :supersedes
 
       emits "AdrSuperseded"
     end
@@ -293,42 +272,42 @@ Hecks.bluebook "Tickets" do
   # Each lifecycle event drives GitHub. A finding's own state never waits on the answer.
   policy "OpenIssueWhenReported" do
     on      "Finding.FindingReported"
-    trigger Finding::GitHubIssues::OpenIssue, with: { finding: :finding }
+    ask     :open_issue, with: { finding: :finding }
   end
 
   policy "OpenIssueWhenRunReported" do
     on      "Finding.RunFindingReported"
-    trigger Finding::GitHubIssues::OpenIssue, with: { finding: :finding }
+    ask     :open_issue, with: { finding: :finding }
   end
 
   policy "OpenIssueWhenLagReported" do
     on      "Finding.LagFindingReported"
-    trigger Finding::GitHubIssues::OpenIssue, with: { finding: :finding }
+    ask     :open_issue, with: { finding: :finding }
   end
 
   policy "LabelIssueWhenTriaged" do
     on      "Finding.FindingTriaged"
-    trigger Finding::GitHubIssues::LabelIssue, with: { finding: :finding }
+    ask     :label_issue, with: { finding: :finding }
   end
 
   policy "CommentWhenFixLinked" do
     on      "Finding.FixLinked"
-    trigger Finding::GitHubIssues::CommentOnIssue, with: { finding: :finding }
+    ask     :comment_on_issue, with: { finding: :finding }
   end
 
   policy "CloseIssueWhenResolved" do
     on      "Finding.FindingResolved"
-    trigger Finding::GitHubIssues::CloseIssue, with: { finding: :finding }
+    ask     :close_issue, with: { finding: :finding }
   end
 
   policy "CloseIssueWhenDismissed" do
     on      "Finding.FindingDismissed"
-    trigger Finding::GitHubIssues::CloseIssue, with: { finding: :finding }
+    ask     :close_issue, with: { finding: :finding }
   end
 
   policy "ReopenIssueWhenReopened" do
     on      "Finding.FindingReopened"
-    trigger Finding::GitHubIssues::ReopenIssue, with: { finding: :finding }
+    ask     :reopen_issue, with: { finding: :finding }
   end
 
   # A conformance or gate run that faults files its own finding.

data/lib/hecks/tickets/bluebook/tickets.hecksagon

@@ -5,7 +5,7 @@ Hecks.hecksagon "Tickets" do
   persisted_by "Memory"
 end
 
-# The anti-corruption layer for Governance, which the chapter's roles are checked against.
+# The anti-corruption layer for Governance, which the bluebook's roles are checked against.
 Hecks.hecksagon "Governance" do
   persisted_by "Memory"
 end

data/lib/hecks/tickets/bluebook/tickets.ports.hecksagon

@@ -1,4 +1,4 @@
-# The port Tickets declares, for every hecksagon that attaches the chapter (`Chapters` loads this
+# The port Tickets declares, for every hecksagon that attaches the bluebook (`Bluebooks` loads this
 # file with it). Each lifecycle event of a finding asks the GitHubIssues port, which the Hecks domain
 # binds (lib/hecks/hecks/adapters/finding_github.rb): the outside a finding reaches. The ask is
 # answered with the record's own arguments or refused with a reason, and a refusal is recorded on the

data/lib/hecks/tools/argument_gate_matrix/dispatching.rb

@@ -55,7 +55,7 @@ module Hecks
           dispatch_row(runtime, row, args)
           [nil, nil, nil]
         rescue *Hecks::Runtime::DOMAIN_REFUSALS => e
-          [e.class.name.split("::").last, e.message, refused_step(kind)]
+          [Hecks::Naming.demodulise(e.class), e.message, refused_step(kind)]
         end
 
         def dispatch_row(runtime, row, args)

data/lib/hecks/tools/argument_gate_matrix/rows.rb

@@ -92,24 +92,24 @@ module Hecks
           Violations::MISMATCHED_ROLE if [earlier, later].include?("refuse_role_mismatch")
         end
 
-        def candidates(runtime, chapter)
-          bluebook = runtime.registry.bluebook(chapter)
+        def candidates(runtime, declaration)
+          bluebook = runtime.bluebook(declaration)
           random = SteadyRandom.new(20_260_918)
           bluebook.aggregates.flat_map do |aggregate|
-            aggregate_rows(aggregate, chapter, random) + entity_rows(aggregate, chapter, random)
+            aggregate_rows(aggregate, declaration, random) + entity_rows(aggregate, declaration, random)
           end
         end
 
-        def aggregate_rows(aggregate, chapter, random)
+        def aggregate_rows(aggregate, declaration, random)
           aggregate.commands.flat_map do |command|
-            rows_for(command, aggregate, "#{chapter}::#{aggregate.hecks_name}.#{command.hecks_name}", "aggregate", random)
+            rows_for(command, aggregate, "#{declaration}::#{aggregate.hecks_name}.#{command.hecks_name}", "aggregate", random)
           end
         end
 
-        def entity_rows(aggregate, chapter, random)
+        def entity_rows(aggregate, declaration, random)
           aggregate.entities.flat_map do |entity|
             entity.commands.flat_map do |command|
-              verb = "#{chapter}::#{aggregate.hecks_name}.#{entity.hecks_name}.#{command.hecks_name}"
+              verb = "#{declaration}::#{aggregate.hecks_name}.#{entity.hecks_name}.#{command.hecks_name}"
               rows = rows_for(command, aggregate, verb, "entity", random)
               rows.each { |row| row[:args] = identity_args(entity, aggregate, random).merge(row[:args]) }
             end

data/lib/hecks/tools/argument_gate_matrix/violations.rb

@@ -99,7 +99,7 @@ module Hecks
         def violate_reference!(args, command)
           reference = command.attributes.find(&:reference?) or return nil
 
-          args[reference.name.to_s] = "no-such-#{reference.type.target_name.to_s.downcase}"
+          args[reference.name.to_s] = "no-such-#{reference.target_name.to_s.downcase}"
           reference.name.to_s
         end
       end

data/lib/hecks/tools/argument_gate_matrix.rb

@@ -85,9 +85,9 @@ module Hecks
 
       # Files each candidate row of one booted domain under `kept` or `dropped`.
       def sweep_domain(runtime, domain, kept, dropped)
-        chapters = runtime.registry.bluebooks.keys
-        chapter = chapters.find { |name| candidates(runtime, name).any? } || chapters.first
-        candidates(runtime, chapter).each do |row|
+        declarations = runtime.bluebooks.keys
+        declaration = declarations.find { |name| candidates(runtime, name).any? } || declarations.first
+        candidates(runtime, declaration).each do |row|
           verdict, judged = judge(runtime, row, domain)
           (verdict == :kept ? kept : dropped) << judged
         end

data/lib/hecks/tools/ci_gate_decision.rb

@@ -10,7 +10,7 @@ require_relative "release_only"
 module Hecks
   module Tools
     # Answers whether a change touches what a gated CI job covers: the decision a `CiGate` row of
-    # the Vocabulary chapter names, made by `hecks decide_ci_gate gate=<name>` in the detector job
+    # the Vocabulary bluebook names, made by `hecks decide_ci_gate gate=<name>` in the detector job
     # `hecks project_ci_gates` writes into each workflow.
     #
     # The change is read from the run's own event (`GITHUB_EVENT_PATH`) and head (`GITHUB_SHA`),
@@ -20,6 +20,9 @@ module Hecks
     module CiGateDecision
       NO_COMMIT = "0" * 40
 
+      # A `gate=<name>` argument, capturing the name.
+      GATE_ARG = /\Agate=(.+)\z/
+
       module_function
 
       # @param argv [Array<String>] `gate=<name>`, a `CiGate` row's name
@@ -28,7 +31,7 @@ module Hecks
       # @return [Integer] 0 once an answer is given
       # @raise [SystemExit] when no row has that name
       def main(argv, root: Tools::ROOT, env: ENV)
-        name = argv.filter_map { |arg| arg[/\Agate=(.+)\z/, 1] }.first
+        name = argv.filter_map { |arg| arg[GATE_ARG, 1] }.first
         abort "decide_ci_gate: name a gate, gate=<name>" unless name
         gate = CiGates.gates.find { |row| row["name"] == name }
         abort "decide_ci_gate: no CiGate row named #{name}" unless gate

data/lib/hecks/tools/ci_gates.rb

@@ -5,7 +5,7 @@ require_relative "../tools"
 
 module Hecks
   module Tools
-    # Projects the `CiGate` rows of the Vocabulary chapter into the workflows: each row becomes a
+    # Projects the `CiGate` rows of the Vocabulary bluebook into the workflows: each row becomes a
     # detector job between a pair of marker comments in its `workflow`. The job runs
     # `hecks decide_ci_gate gate=<name>` (`CiGateDecision`), so the decision is made by the binary
     # from the same row, never by shell the workflow carries.

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

@@ -7,6 +7,9 @@ module Hecks
     module CommentStyle
       # Finds the all-caps words in a comment and decides how each should be written instead.
       module CapsWords
+        # A comment indented past its hash, as a code sample or continuation is.
+        INDENTED_COMMENT = /\A#\s{3,}/
+
         private
 
         # @return [Array<Array>] each shouted word as `[offset, word, replacement]`, in text order
@@ -75,17 +78,17 @@ module Hecks
         end
 
         def keep_capitals?(word)
-          bare = word.sub(/'[A-Z]{1,2}\z/, "")
+          bare = word.sub(SHOUTED_SUFFIX, "")
           return false if PROPER_NOUNS.key?(bare)
 
-          ACRONYMS.include?(bare) || @constants.include?(bare) || bare.match?(/\A[IVX]+\z/)
+          ACRONYMS.include?(bare) || @constants.include?(bare) || bare.match?(ROMAN_NUMERAL)
         end
 
         def sentence_start?(comment, masked, offset)
-          before = masked[0, offset].sub(/\A#+\s*/, "")
-          return before.match?(/[.!?]["')\]]*\s+\z/) if before.match?(/[[:alnum:]#{FILLER}]/o)
-          return true if before.match?(/\A\s*(?:[-*•]|─+|\d+[.)])\s+\z/)
-          return false if masked[0, offset].match?(/\A#\s{3,}/)
+          before = masked[0, offset].sub(COMMENT_MARKER, "")
+          return before.match?(SENTENCE_BREAK) if before.match?(/[[:alnum:]#{FILLER}]/o)
+          return true if before.match?(LIST_MARKER)
+          return false if masked[0, offset].match?(INDENTED_COMMENT)
 
           after_sentence_end?(comment)
         end
@@ -95,8 +98,8 @@ module Hecks
           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/)
+          body = previous.text.sub(COMMENT_MARKER, "").strip
+          body.empty? || body.match?(SENTENCE_END)
         end
       end
     end

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

@@ -10,6 +10,11 @@ module Hecks
       module Dictionary
         WORDS = "/usr/share/dict/words"
 
+        # An apostrophe and everything after it: the `'s` of a possessive.
+        APOSTROPHE_TAIL = /'.*\z/
+        # A word's last letter written twice, as in "stopp".
+        DOUBLED_LAST_LETTER = /(.)\1\z/
+
         # Technical vocabulary the system word list lacks.
         EXTRA = %w[
           adversarial allowlist anymore app apps arg args arity async backend backtrace baseline
@@ -46,12 +51,12 @@ module Hecks
         def english?(word)
           return true unless words
 
-          bare = word.downcase.delete_suffix("n't").sub(/'.*\z/, "")
+          bare = word.downcase.delete_suffix("n't").sub(APOSTROPHE_TAIL, "")
           SUFFIXES.any? do |suffix, replacement|
             next false unless bare.end_with?(suffix)
 
             stem = bare.delete_suffix(suffix) + replacement
-            words.include?(stem) || words.include?(stem.sub(/(.)\1\z/, '\1'))
+            words.include?(stem) || words.include?(stem.sub(DOUBLED_LAST_LETTER, '\1'))
           end
         end
       end

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

@@ -7,6 +7,11 @@ module Hecks
     module CommentStyle
       # The rewrites for the fixable categories: all-caps words, long bold headings, long lines.
       module Fixing
+        # A line that opens a method definition, after at most one modifier such as `private`.
+        DEF_LINE = /\A\s*(?:\w+\s+)?def\s/
+        # A comment line that opens with a doc tag such as `@param`.
+        TAG_LINE = /\A#+\s*@\w/
+
         private
 
         def fix_line(line, number, wanted)
@@ -79,14 +84,14 @@ module Hecks
         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/)
+          @lines[line].to_s.match?(DEF_LINE)
         end
 
         def paragraph_start?(comment, masked, offset)
-          return false if masked[0, offset].sub(/\A#+\s*/, "").match?(/[[:alnum:]#{FILLER}]/o)
+          return false if masked[0, offset].sub(COMMENT_MARKER, "").match?(/[[:alnum:]#{FILLER}]/o)
 
           above = comment.full_line ? @by_line[comment.line - 1] : nil
-          !above&.full_line || above.text.match?(/\A#+\s*\z/)
+          !above&.full_line || above.text.match?(EMPTY_COMMENT)
         end
 
         # Splits one over-long prose comment line in two. Lines with no safe
@@ -104,8 +109,8 @@ module Hecks
 
         # An `@tag` line continues, indented, under its tag.
         def wrap_lead(text)
-          lead = text[/\A#+\s*/]
-          text.match?(/\A#+\s*@\w/) ? "#{lead}  " : lead
+          lead = text[COMMENT_MARKER]
+          text.match?(TAG_LINE) ? "#{lead}  " : lead
         end
 
         # @return [Integer, nil] the offset to break at, nil when there is no safe one

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

@@ -28,7 +28,7 @@ module Hecks
         # 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 = run.first.text.sub(COMMENT_MARKER, "").strip[0, MAX_ANCHOR]
           text = "(empty)" if text.empty?
           seen[text] += 1
           seen[text] == 1 ? text : "#{text} ##{seen[text]}"

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

@@ -26,7 +26,7 @@ module Hecks
           text = comment.text
           return ["", text] unless @open_spans[comment.line]
 
-          lead = text[/\A#+\s*/].length
+          lead = text[COMMENT_MARKER].length
           close = text.index("`", lead)
           cut = close ? close + 1 : text.length
           [text[0, lead] + (FILLER * (cut - lead)), text[cut..]]
@@ -50,7 +50,7 @@ module Hecks
 
         def continues_paragraph?(comment)
           above = @by_line[comment.line - 1]
-          comment.full_line && above&.full_line && !above.text.match?(/\A#+\s*\z/)
+          comment.full_line && above&.full_line && !above.text.match?(EMPTY_COMMENT)
         end
 
         # Capitalised SQL keywords to leave alone on this line. A keyword such as
@@ -64,7 +64,7 @@ module Hecks
         end
 
         def sql_classes(words)
-          bare = words.map { |word| word.sub(/'[A-Z]{1,2}\z/, "") } - ["A"]
+          bare = words.map { |word| word.sub(SHOUTED_SUFFIX, "") } - ["A"]
           [bare, bare.select { |word| SQL_STRONG.include?(word) }, bare.select { |word| SQL_WEAK.include?(word) }]
         end
 
@@ -85,8 +85,8 @@ module Hecks
         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]/))
+          capitals = span.scan(SHOUTED_WORD).size
+          capitals >= 3 || (capitals == 2 && !span.match?(LOWERCASE))
         end
       end
     end

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

@@ -12,6 +12,9 @@ module Hecks
     module CommentStyle
       # Lints a set of paths and renders the result.
       class Run
+        # A shebang line that runs Ruby, matched as bytes.
+        RUBY_SHEBANG = /\A#!.*ruby/n
+
         # @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
@@ -116,7 +119,7 @@ module Hecks
         # 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)
+            File.file?(path) && File.extname(path).empty? && File.open(path, "rb", &:gets).to_s.match?(RUBY_SHEBANG)
           end
           Dir[File.join(dir, "**", "*.rb")] + scripts
         end

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

@@ -17,6 +17,13 @@ module Hecks
         # Raised when an automatic fix would change code rather than comments.
         class Error < RuntimeError; end
 
+        # A generator's banner: "generated", then "do not edit", in any case and across lines.
+        GENERATED_BANNER = /\bgenerated\b.*?\bdo not edit\b/im
+        # A whole token that is an all-caps name, such as `PATH` or `MAX_LINE`.
+        SHOUTED_NAME = /\A[A-Z][A-Z0-9_]+\z/
+        # An all-caps name anywhere in a token.
+        SHOUTED_NAME_IN = /[A-Z][A-Z0-9_]+/
+
         include LongBlocks
         include Masking
         include CapsWords
@@ -67,7 +74,7 @@ module Hecks
         # 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)
+          @lines.first(8).join.match?(GENERATED_BANNER)
         end
 
         # Helpers defined inside a spec are test scaffolding, not API, so the
@@ -97,8 +104,8 @@ module Hecks
         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_]+/))
+            when :on_const, :on_tstring_content then words << text if text.match?(SHOUTED_NAME)
+            when :on_heredoc_beg, :on_heredoc_end then words.merge(text.scan(SHOUTED_NAME_IN))
             end
           end
         end

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

@@ -2,6 +2,7 @@
 
 require_relative "../../tools"
 require_relative "walker"
+require "hecks/naming"
 
 module Hecks
   module Tools
@@ -9,6 +10,13 @@ module Hecks
       # The structural categories: the doc tags a public method carries and the shape of a long
       # class doc.
       module StructureChecks
+        # A doc that opts out of the tag checks: private, no-doc, or a closing "(see ...)" pointer.
+        TAGS_EXEMPT = /@api private|@private|:nodoc:|\(see (?:`[^`]+`|#\w)[^)]*\)\W*\z/m
+        # The indent, hashes and one space that open a doc line.
+        DOC_LINE_MARKER = /\A\s*#+\s?/
+        # A `##` section heading inside a class doc.
+        SECTION_HEADING = /\A#\s*##+ /
+
         private
 
         def structure_violations
@@ -37,11 +45,11 @@ module Hecks
 
         def method_violations(method)
           return [] unless method.visibility == :public
-          return [] unless CommentStyle.public_surface.include?(method.type_fqn.to_s.split("::").last)
+          return [] unless CommentStyle.public_surface.include?(Hecks::Naming.demodulise(method.type_fqn))
 
           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)
+          return [] if doc.match?(TAGS_EXEMPT)
 
           tag_violations(method, doc)
         end
@@ -94,7 +102,8 @@ module Hecks
         end
 
         def lead_line(doc)
-          doc.lines.map { |line| line.sub(/\A\s*#+\s?/, "").strip }.reject(&:empty?).first.to_s
+          lines = doc.lines.map { |line| line.sub(DOC_LINE_MARKER, "").strip }
+          lines.reject(&:empty?).first.to_s
         end
 
         def violation(method, category, detail)
@@ -103,7 +112,7 @@ module Hecks
 
         def long_doc_violations(type)
           doc = doc_above(type.line)
-          return [] if doc.length <= LONG_CLASS_DOC || doc.any? { |l| l.match?(/\A#\s*##+ /) }
+          return [] if doc.length <= LONG_CLASS_DOC || doc.any? { |l| l.match?(SECTION_HEADING) }
 
           [Violation.new(path, type.line, "unstructured_class_doc", "#{type.fqn} (#{doc.length} lines)")]
         end

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

@@ -48,7 +48,7 @@ module Hecks
         end
 
         def history_violations(comment)
-          masked = comment.text.gsub(/`[^`]*`/) { |span| " " * span.length }
+          masked = comment.text.gsub(CODE_SPAN) { |span| " " * span.length }
           pattern = HISTORY.find { |candidate| masked.match?(candidate) }
           return [] unless pattern
 

data/lib/hecks/tools/comment_style.rb

@@ -65,13 +65,36 @@ module Hecks
       # needs no doc unless it carries a real why.
       PUBLIC_SURFACE = Set["Storehouse"].freeze
 
+      # The hashes that open a comment and the space after them.
+      COMMENT_MARKER = /\A#+\s*/
+      # A comment line with nothing after its hashes: a paragraph break.
+      EMPTY_COMMENT = /\A#+\s*\z/
+      # A shouted contraction or possessive ending: `'S`, `'LL`, `'RE`.
+      SHOUTED_SUFFIX = /'[A-Z]{1,2}\z/
+      # A Roman numeral, which stays in capitals.
+      ROMAN_NUMERAL = /\A[IVX]+\z/
+      # Sentence punctuation, any closing quotes or brackets, then the space before a new word.
+      SENTENCE_BREAK = /[.!?]["')\]]*\s+\z/
+      # Sentence punctuation and any closing quotes or brackets, ending the text.
+      SENTENCE_END = /[.!?]["')\]]*\z/
+      # A list marker alone before the word: a bullet, a rule, or a number.
+      LIST_MARKER = /\A\s*(?:[-*•]|─+|\d+[.)])\s+\z/
+      # A whole word of two or more capitals.
+      SHOUTED_WORD = /\b[A-Z]{2,}\b/
+      # Any lowercase letter.
+      LOWERCASE = /[a-z]/
+      # A backtick code span.
+      CODE_SPAN = /`[^`]*`/
+      # A `class` or `module` line, capturing the type's own name.
+      TYPE_DEFINITION = /^\s*(?:class|module)\s+([A-Z]\w*)/
+
       extend Cli
 
       # Class and module names defined under `lib/`, keyed by their shouted form.
       def self.class_names
         @class_names ||= Dir["lib/**/*.rb"].each_with_object({}) do |file, names|
-          File.read(file).scan(/^\s*(?:class|module)\s+([A-Z]\w*)/) do |(name)|
-            names[name.upcase] ||= name if name.match?(/[a-z]/)
+          File.read(file).scan(TYPE_DEFINITION) do |(name)|
+            names[name.upcase] ||= name if name.match?(LOWERCASE)
           end
         end
       end