hecks 2.9.0 → 3.0.0

data/lib/hecks/tools/rust_comment_style.rb

@@ -0,0 +1,642 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../tools"
+require_relative "comment_style"
+
+module Hecks
+  module Tools
+    # Checks Rust files against docs/COMMENT_STYLE_GUIDE_RUST.md, sharing its
+    # prose vocabulary with `CommentStyle`, the Ruby-side linter.
+    module RustCommentStyle
+      MAX_LINE = CommentStyle::MAX_LINE
+      MAX_HEADING_WORDS = CommentStyle::MAX_HEADING_WORDS
+
+      CATEGORIES = {
+        "missing_doc"        => "public item has no /// doc comment",
+        "missing_module_doc" => "file has no //! module doc at its top",
+        "all_caps"           => "all-caps emphasis",
+        "long_bold"          => "bold heading over #{MAX_HEADING_WORDS} words reads as shouting",
+        "bare_constant"      => "capitalised word names a const/static in this file: backtick or lowercase it",
+        "unknown_capitals"   => "capitalised token is not an English word: backtick it or list it as an acronym",
+        "design_history"     => "narrates design history instead of citing an ADR",
+        "long_line"          => "comment line exceeds #{MAX_LINE} characters"
+      }.freeze
+
+      FIXABLE = %w[all_caps long_bold long_line].freeze
+
+      MARKER = %r{\A/{2,3}!?\s*}
+      DOC_LINE = %r{\A\s*(?:///(?!/)|//!)}
+
+      # `// TMPL:name BEGIN`/`END` sentinels are parsed verbatim by
+      # `rust/project/exemplar.rb`; every prose rule skips them outright.
+      TMPL_MARKER = /\bTMPL:\S+\s+(?:BEGIN|END)\b/i
+      MOD_DOC_LINE = %r{\A\s*//!}
+      ATTR_LINE = /\A\s*#\[/
+      BOLD_HEADING = %r{\A(/{2,3}!?\s*(?:[-*]\s+)?)\*\*([^*]+)\*\*}
+      HEADING_END = CommentStyle::HEADING_END
+      GAP = CommentStyle::GAP
+      FILLER = CommentStyle::FILLER
+
+      # `main` is a pub fn entry point, not an API surface to document.
+      SELF_EVIDENT_FNS = %w[main].to_set.freeze
+
+      # Rust-specific acronyms beyond the Ruby linter's list.
+      RUST_ACRONYMS = %w[EOF RAII RHS SQS DLQ JIT LSP NFA DFA CR].to_set.freeze
+
+      RUST_PROPER_NOUNS = {
+        "EMBRYONAUT" => "Embryonaut"
+      }.freeze
+
+      RUST_EXTRA_WORDS = %w[
+        cardinality routability prepend safer diff diffed stats earliest unbracketed
+        variadic ordering orderings reenter dereference entrypoint wildcard
+        sandbox sandboxed unsandboxed expr enum codegen serialise serialises
+        preprocessing backslash
+      ].freeze
+
+      PUB_ITEM = /
+        \A\s*pub(?:\([^)]*\))?\s+
+        (?:async\s+|unsafe\s+|extern\s+"[^"]*"\s+|const\s+)*
+        (fn|struct|enum|trait|mod|type)\s+
+        ([A-Za-z_][A-Za-z0-9_]*)
+      /x
+
+      Violation = Struct.new(:path, :line, :category, :message)
+      Comment = Struct.new(:line, :col, :text, :full_line)
+
+      # Finds Rust source's line comments, distinguishing them from `//` inside
+      # code, strings, raw strings, and char literals. Block comments are not recognised.
+      class Tokenizer
+        # Lexes `source` for its line comments in one pass.
+        def self.comments(source)
+          new(source).run
+        end
+
+        def initialize(source)
+          @src = source
+          @len = source.length
+          @comments = []
+        end
+
+        # Walks the whole source once, collecting every line comment.
+        def run
+          pos = 0
+          line = 1
+          col = 0
+          while pos < @len
+            case @src[pos]
+            when "\n"
+              line += 1
+              col = 0
+              pos += 1
+            when "/" then pos, col = consume_slash(pos, col, line)
+            when '"' then pos, col, line = consume_string(pos, col, line)
+            when "'" then pos, col = consume_quote(pos, col)
+            when "r" then pos, col, line = consume_maybe_raw_string(pos, col, line)
+            else
+              pos += 1
+              col += 1
+            end
+          end
+          @comments
+        end
+
+        private
+
+        def consume_slash(pos, col, line)
+          return advance_plain(pos, col) unless @src[pos, 2] == "//"
+
+          finish = @src.index("\n", pos) || @len
+          text = @src[pos...finish]
+          last_newline = @src.rindex("\n", pos.zero? ? 0 : pos - 1)
+          prefix = last_newline && last_newline < pos ? @src[(last_newline + 1)...pos] : @src[0...pos]
+          full_line = prefix.strip.empty?
+          @comments << Comment.new(line, col, text, full_line)
+          [finish, col + text.length]
+        end
+
+        def consume_string(pos, col, line)
+          idx = pos + 1
+          idx += (@src[idx] == "\\" ? 2 : 1) while idx < @len && @src[idx] != '"'
+          advance_span(pos, idx + 1, col, line)
+        end
+
+        def consume_quote(pos, col)
+          match = @src[pos..].match(/\A'(?:\\.|[^'\\\n]){1}'/)
+          match ? [pos + match[0].length, col + match[0].length] : [pos + 1, col + 1]
+        end
+
+        def consume_maybe_raw_string(pos, col, line)
+          idx = pos + 1
+          hashes = 0
+          hashes += 1 while @src[idx + hashes] == "#"
+          return [pos + 1, col + 1, line] unless @src[idx + hashes] == '"'
+
+          close = @src.index("\"#{'#' * hashes}", idx + hashes + 1) || @len
+          advance_span(pos, close + 1 + hashes, col, line)
+        end
+
+        def advance_span(from, to, col, line)
+          segment = @src[from...to]
+          newlines = segment.count("\n")
+          if newlines.positive?
+            col = segment.length - segment.rindex("\n") - 1
+            line += newlines
+          else
+            col += segment.length
+          end
+          [to, col, line]
+        end
+
+        def advance_plain(pos, col)
+          [pos + 1, col + 1]
+        end
+      end
+
+      # Folds Rust jargon into the shared word list so `Dictionary.english?`
+      # already covers these words' plurals, gerunds, and past tense too.
+      CommentStyle::Dictionary.words&.merge(RUST_EXTRA_WORDS)
+
+      # One parsed `.rs` 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 = 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
+
+        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?(%r{\A/{2,3}!?\s*\z})
+            inside = false unless continues
+            open[comment.line] = inside
+            inside ^= comment.text.count("`").odd?
+          end
+        end
+
+        # 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
+
+        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 mask(comment)
+          text = comment.text
+          head = ""
+          if @open_spans[comment.line]
+            lead = text[MARKER].to_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(CommentStyle::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
+
+        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 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 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
+
+        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
+
+        def sql_keywords(comment, words)
+          bare = words.map { |w| w.sub(/'[A-Z]{1,2}\z/, "") } - ["A"]
+          strong = bare.select { |w| CommentStyle::SQL_STRONG.include?(w) }
+          weak = bare.select { |w| CommentStyle::SQL_WEAK.include?(w) }
+          database_file = path.match?(CommentStyle::SQL_PATH)
+          return bare.to_set if reads_as_sql?(bare, strong, weak, database_file)
+          return (strong + weak).to_set if comment.text.match?(CommentStyle::SQL_PHRASES)
+
+          database_file ? strong.to_set : Set.new
+        end
+
+        def reads_as_sql?(bare, strong, weak, database_file)
+          only_sql = bare.all? do |w|
+            [CommentStyle::SQL_STRONG, CommentStyle::SQL_WEAK, CommentStyle::SQL_NEUTRAL, CommentStyle::ACRONYMS].any? { |set| set.include?(w) }
+          end
+          return false unless only_sql
+
+          database_file ? (strong.any? || weak.any?) : (strong.any? && (strong + weak).size >= 2)
+        end
+
+        def possessives(masked)
+          found = []
+          masked.scan(/(?<=#{FILLER})'S\b/) { 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|
+            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
+
+        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}]/)
+          return true if before.match?(/\A\s*(?:[-*•]|─+|\d+[.)])\s+\z/)
+
+          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
+
+        def fix_line(line, number, wanted)
+          comment = @by_line[number]
+          return line if comment.nil? || comment.text.match?(TMPL_MARKER)
+
+          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
+
+        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
+
+          [run.first[0], finish]
+        end
+
+        def paragraph_start?(comment, masked, offset)
+          return false if masked[0, offset].sub(MARKER, "").match?(/[[:alnum:]#{FILLER}]/)
+
+          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 = 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
+
+        # `pub` items with no `///` doc above, and files with no `//!` module
+        # doc at the top. 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
+          violations = []
+          @lines.each_with_index do |line, index|
+            tracker.observe(line)
+            next if tracker.inside?
+
+            match = PUB_ITEM.match(line)
+            next unless match
+            next if match[1] == "fn" && SELF_EVIDENT_FNS.include?(match[2])
+
+            line_number = index + 1
+            next if doc_above?(line_number)
+
+            violations << Violation.new(path, line_number, "missing_doc", "#{match[1]} #{match[2]}")
+          end
+          violations
+        end
+
+        # 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
+
+        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
+
+      # 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
+
+      # 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_rust_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("--only LIST", Array, "limit to: #{CATEGORIES.keys.join(', ')}") { |list| options[:only] = list }
+          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, **)
+        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?
+
+        run = Run.new(paths, only: options[:only])
+        case options[:mode]
+        when :fix then puts("rewrote #{run.fix!} files") || 0
+        else render(run, options)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/sequence_script.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Prints one generated, valid dispatch sequence for a domain, using the generator `hecks fuzz`
+    # drives.
+    #
+    #   hecks generate_sequence <domain> [--seed N] [--steps N] [--adversarial fraction]
+    #
+    # `--adversarial` mutates the sequence as `hecks quality_control ask run` does; 0 (off) by
+    # default.
+    module SequenceScript
+      USAGE = "usage: hecks generate_sequence <domain> [--seed N] [--steps N] [--adversarial FRACTION]"
+
+      module_function
+
+      # Prints the sequence as a replayable script.
+      #
+      # @param argv [Array<String>] the domain, then the flags
+      # @param root [String] the checkout (unused: the domain is named by path)
+      # @return [Integer] 0
+      # @raise [SystemExit] with the usage line when an argument is missing or unknown
+      def main(argv, root: Tools::ROOT)
+        _ = root
+        require "hecks"
+        require "hecks/fuzzing"
+        args = argv.dup
+        domain = args.shift or abort USAGE
+        seed, steps, adversarial = flags(args)
+
+        generated = Hecks::Fuzzing::SequenceGenerator.generate(domain, seed: seed, steps: steps,
+                                                                       adversarial: adversarial)
+        puts JSON.pretty_generate(
+          name:  "#{File.basename(domain)}-generated",
+          note:  "generated by hecks generate_sequence — seed #{seed}, #{steps} steps requested (#{generated.length} produced)",
+          steps: generated
+        )
+        0
+      end
+
+      # @param args [Array<String>] the flags, consumed
+      # @return [Array(Integer, Integer, Float)] the seed, the step count and the fraction
+      def flags(args)
+        seed  = 1
+        steps = 30
+        adversarial = 0.0
+        until args.empty?
+          case args.shift
+          when "--seed"        then seed  = Integer(args.shift)
+          when "--steps"       then steps = Integer(args.shift)
+          when "--adversarial" then adversarial = Float(args.shift)
+          else abort USAGE
+          end
+        end
+        [seed, steps, adversarial]
+      end
+    end
+  end
+end