hecks 3.5.0 → 3.6.0

data/lib/hecks/tools/rust_comment_style.rb

@@ -4,6 +4,9 @@ require "json"
 require "optparse"
 require_relative "../tools"
 require_relative "comment_style"
+require_relative "rust_comment_style/tokenizer"
+require_relative "rust_comment_style/source_file"
+require_relative "rust_comment_style/run"
 
 module Hecks
   module Tools
@@ -64,548 +67,37 @@ module Hecks
       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 }
+          opts.on("--fix", "rewrite fixable categories: #{FIXABLE.join(", ")}") { options[:mode] = :fix }
+          filter_options(opts, options)
         end
       end
 
+      # Registers the flags that narrow or reshape the output.
+      def self.filter_options(opts, options)
+        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
+
       # Prints `--report`, `--check`, or `--json` output for a finished run.
       def self.render(run, options)
         found = run.violations
+        print_run(run, found, options)
+        options[:mode] == :check && found.any? ? 1 : 0
+      end
+
+      # Prints the run in the shape the options ask for.
+      def self.print_run(run, found, options)
         if options[:json]
           puts JSON.pretty_generate(found.map(&:to_h))
         elsif options[:mode] == :check
@@ -613,27 +105,38 @@ module Hecks
         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, paths = parse_arguments(argv)
+        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
+
+      # Parses `argv`, refusing an unknown category, a missing path, or no path at all.
+      #
+      # @return [Array(Hash, Array<String>)] the options and the paths
+      def self.parse_arguments(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 "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?
+        refuse_missing_paths(paths)
+        [options, paths]
+      end
 
-        run = Run.new(paths, only: options[:only])
-        case options[:mode]
-        when :fix then puts("rewrote #{run.fix!} files") || 0
-        else render(run, options)
-        end
+      # Refuses a path that does not exist.
+      def self.refuse_missing_paths(paths)
+        missing = paths.reject { |path| File.exist?(path) }
+        abort "no such path: #{missing.join(", ")}" unless missing.empty?
       end
     end
   end

data/lib/hecks/tools/sequence_script.rb

@@ -31,31 +31,37 @@ module Hecks
         domain = args.shift or abort USAGE
         seed, steps, adversarial = flags(args)
 
+        puts JSON.pretty_generate(script_for(domain, seed, steps, adversarial))
+        0
+      end
+
+      # @return [Hash] the replayable script: its name, a note and the generated steps
+      def script_for(domain, seed, steps, adversarial)
         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
+        values = { seed: 1, steps: 30, adversarial: 0.0 }
+        apply_flag(values, args.shift, args) until args.empty?
+        values.values_at(:seed, :steps, :adversarial)
+      end
+
+      # Records one flag in `values`, taking its value from `rest`.
+      def apply_flag(values, flag, rest)
+        case flag
+        when "--seed"        then values[:seed] = Integer(rest.shift)
+        when "--steps"       then values[:steps] = Integer(rest.shift)
+        when "--adversarial" then values[:adversarial] = Float(rest.shift)
+        else abort USAGE
         end
-        [seed, steps, adversarial]
       end
     end
   end