hecks 5.0.0 → 7.0.0

data/lib/hecks/command_names/check.rb

@@ -0,0 +1,39 @@
+require "hecks/adapters/driving/cli_runner"
+require_relative "index"
+require_relative "scan"
+require_relative "sources"
+
+module Hecks
+  module CommandNames
+    # The check that every launcher name a file invokes is one the launcher accepts.
+    #
+    # A renamed command leaves its old name in gate rows, workflows, specs and docs, and a gate that
+    # runs a name the launcher refuses runs nothing. This reads those places for `exe/hecks <name>`
+    # and `hecks <name>` and looks each up in the launcher's own name table, once.
+    module Check
+      # One invocation the launcher would refuse.
+      Finding = Struct.new(:path, :line, :text, :problem) do
+        # @return [String] `file:line`, the string, the fault and the nearest valid name
+        def to_s
+          near = problem.nearest ? "; nearest valid name: #{problem.nearest}" : ""
+          "#{path}:#{line}: #{text[0, 120]} -- #{problem.text}#{near}"
+        end
+      end
+
+      module_function
+
+      # @param root [String] the checkout
+      # @param scopes [Hash] `CliRunner.name_index`
+      # @return [Array<Finding>] every invocation the launcher would refuse, by file then line
+      def findings(root:, scopes:)
+        index = Index.new(scopes)
+        Sources.files(root).flat_map do |path|
+          Scan.new(path, File.read(File.join(root, path), encoding: "UTF-8")).calls.filter_map do |call|
+            problem = index.problem(call.words)
+            Finding.new(path, call.line, call.text, problem) if problem && !Sources.allowed?(call.text)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/command_names/extractor.rb

@@ -0,0 +1,67 @@
+module Hecks
+  module CommandNames
+    # The launcher invocations in a file's text: where each is, and the words typed after it.
+    class Extractor
+      # One invocation found.
+      Call = Struct.new(:line, :text, :words)
+
+      # `exe/hecks` names the launcher wherever it appears.
+      STRONG = %r{exe/hecks(?=\s)\s+(?<rest>[^`"'|;&)>\\]*)}
+      # `exe/hecks` as the head of an argument list.
+      LISTED = %r{exe/hecks["']\s*,\s*["'](?<rest>[^"']*)}
+      # A bare `hecks` counts when a backtick opens it, or a prompt precedes it.
+      QUOTED = /(?<=`)hecks\s+(?<rest>[^`"'|;&)>\\]*)/
+      PROMPT = /(?:\A|\s)\$\s+hecks\s+(?<rest>[^`"'|;&)>\\]*)/
+      # A bare `hecks` that opens a line of shell, in a fence or a shell file.
+      SHELL = /\A\s*(?:bundle exec\s+)?hecks\s+(?<rest>[^`"'|;&)>\\]*)/
+
+      # A word that can be a launcher name, with the punctuation prose puts after it cut off.
+      NAME = /\A[A-Za-z_][\w:]*(?:\.\w+)*!?\z/
+
+      # The punctuation prose puts after a name.
+      TRAILING = /[,.;:)\]]+\z/
+
+      # A name with a regex-escaped dot (`gate_run\.gate!`): a pattern, not a launcher call.
+      ESCAPED = /[\w:!]+(?:\\\.[\w!]*)+/
+
+      # The line marker that excuses an illustrative invocation, on its own line or the one before.
+      MARKER = "dead-name-check: skip".freeze
+
+      # @param shell [Boolean] whether a line may open with a bare `hecks` (a fence, a shell file)
+      # @param strong_only [Boolean] whether only `exe/hecks` counts, as in a code comment's prose
+      def initialize(shell: false, strong_only: false)
+        @shell = shell
+        @strong_only = strong_only
+      end
+
+      # @param line [String] one line of text
+      # @param number [Integer] its line number
+      # @return [Array<Call>] the invocations on it
+      def calls(line, number)
+        return [] unless line.include?("hecks")
+
+        text = line.gsub(ESCAPED, "")
+        patterns.flat_map { |pattern| text.scan(pattern).flatten }.filter_map { |rest| call(rest, number, line) }
+      end
+
+      private
+
+      def patterns
+        return [STRONG, LISTED] if @strong_only
+
+        [STRONG, LISTED, QUOTED, PROMPT, (SHELL if @shell)].compact
+      end
+
+      def call(rest, number, line)
+        words = words(rest)
+        Call.new(number, line.strip, words) unless words.empty?
+      end
+
+      # The leading words of a line that spell a launcher name, after the flags before it.
+      def words(rest)
+        tokens = rest.split.drop_while { |token| token.start_with?("-") }
+        tokens.map { |token| token.sub(TRAILING, "") }.take_while { |token| token.match?(NAME) }.first(3)
+      end
+    end
+  end
+end

data/lib/hecks/command_names/index.rb

@@ -0,0 +1,40 @@
+require "hecks/adapters/driving/cli_runner"
+require_relative "resolution"
+
+module Hecks
+  module CommandNames
+    # The launcher's accepted names, by scope, and what becomes of a typed line.
+    class Index
+      # Words the launcher answers before it looks a name up.
+      PROGRAM_WORDS = %w[help usage search tour completion resume].freeze
+
+      # @param scopes [Hash{String => Hash}] `CliRunner.name_index`
+      def initialize(scopes)
+        @scopes = scopes
+      end
+
+      # @param words [Array<String>] the words after the launcher's name
+      # @return [Problem, nil] what is wrong with the line, or nil when the launcher accepts it
+      def problem(words)
+        scope, rest = scope_of(words)
+        asking = Adapters::Driving::CliRunner::QUERY_WORDS.include?(rest.first)
+        typed = rest.drop(asking ? 1 : 0).first
+        return if typed.nil? || free?(scope, typed)
+
+        Resolution.new(scope, typed, asking).problem
+      end
+
+      private
+
+      # An attached bluebook's word hands the rest of the line to that bluebook.
+      def scope_of(words)
+        scope = words.first && !words.first.empty? && @scopes[words.first]
+        scope ? [scope, words.drop(1)] : [@scopes.fetch(""), words]
+      end
+
+      def free?(scope, typed)
+        PROGRAM_WORDS.include?(typed) || scope["modules"].include?(typed)
+      end
+    end
+  end
+end

data/lib/hecks/command_names/resolution.rb

@@ -0,0 +1,81 @@
+require "hecks/adapters/driving/cli_runner"
+
+module Hecks
+  module CommandNames
+    # What is wrong with a typed line.
+    Problem = Struct.new(:text, :nearest)
+
+    # One typed word looked up the way the launcher looks it up: every spelling through
+    # `canonical_name`, the bang rule of `BangRule`, the neighbours of `Suggestions`.
+    class Resolution
+      RUNNER = Adapters::Driving::CliRunner
+
+      # The marks a name carries that a plain English word does not.
+      NAME_MARKS = /[_.]/
+
+      # @param scope [Hash] one scope of `CliRunner.name_index`
+      # @param typed [String] the word, with its `!` if it has one
+      # @param asking [Boolean] whether `query` came before it
+      def initialize(scope, typed, asking)
+        @scope = scope
+        @cli = { names: { command: scope["command"], question: scope["question"] } }
+        @typed = typed.chomp("!")
+        @bang = typed.end_with?("!")
+        @asking = asking
+        @name = RUNNER.canonical_name(@cli, @typed)
+      end
+
+      # @return [Problem, nil] nil when the launcher would run the line
+      def problem
+        return unknown unless command || question
+
+        bare_command || banged_query || query_of_command
+      end
+
+      private
+
+      def command = @scope["command"][@name]
+
+      def question = @scope["question"][@name]
+
+      def bare_command
+        return unless command && !@asking && !@bang
+
+        Problem.new("#{@typed} is a command and writes; write it as #{@typed}!", "#{command}!")
+      end
+
+      def banged_query
+        return unless @bang && !@asking && !command && question
+
+        Problem.new("#{@typed}! is a query and reads; write it without the !", "query #{question}")
+      end
+
+      def query_of_command
+        return unless @asking && !question
+
+        Problem.new("#{@typed} is a command, not a query", "#{command}!")
+      end
+
+      def unknown
+        return if plain? && !homed?
+
+        near = RUNNER.near_names(@cli, RUNNER.snake_form(@name), @asking).first
+        Problem.new("#{@typed} is not a command or query", near && listed(near))
+      end
+
+      # A lone word with no underscore, dot or bang is as likely English as a name.
+      def plain? = !@bang && !@typed.match?(NAME_MARKS)
+
+      # Whether the word is the last part of some name, so a launcher once accepted it bare.
+      def homed?
+        (@cli[:names][:command].keys + @cli[:names][:question].keys).any? { |key| key.split(".").last == @name }
+      end
+
+      def listed(near)
+        return "#{@scope["command"][near]}!" if @scope["command"][near]
+
+        "query #{@scope["question"][near]}"
+      end
+    end
+  end
+end

data/lib/hecks/command_names/scan.rb

@@ -0,0 +1,54 @@
+require_relative "extractor"
+
+module Hecks
+  module CommandNames
+    # One file read for launcher invocations, leaving out the ones marked as illustrative.
+    class Scan
+      # A fence whose opening line says its content is shown and not meant to run.
+      EXCUSED_FENCE = /\b(?:skip|historical|illustrative)\b/
+
+      # @param path [String] the file's path, relative to the checkout
+      # @param text [String] its text
+      def initialize(path, text)
+        @path = path
+        @lines = text.scrub.lines
+        @markdown = path.end_with?(".md")
+        @ruby = path.end_with?(".rb")
+        @shell = !path.end_with?(".rb", ".md", ".bluebook")
+      end
+
+      # @return [Array<Extractor::Call>] the invocations, each as `calls` of the extractor
+      def calls
+        fence = nil
+        @lines.each_with_index.flat_map do |line, index|
+          fence = fence_after(fence, line)
+          next [] if skipped?(line, index, fence)
+
+          extractor(fence, line).calls(line, index + 1)
+        end
+      end
+
+      private
+
+      # The open fence after a line: nil outside one, else its opening line.
+      def fence_after(fence, line)
+        return fence unless @markdown && line.lstrip.start_with?("```")
+
+        fence ? nil : line
+      end
+
+      def skipped?(line, index, fence)
+        return true if line.lstrip.start_with?("```") || excused?(fence)
+
+        [line, (@lines[index - 1] if index.positive?)].compact.any? { |text| text.include?(Extractor::MARKER) }
+      end
+
+      def excused?(fence) = fence&.match?(EXCUSED_FENCE)
+
+      # A Ruby comment is prose, so only the launcher's path names a call in it.
+      def extractor(fence, line)
+        Extractor.new(shell: @shell || !fence.nil?, strong_only: @ruby && line.lstrip.start_with?("#"))
+      end
+    end
+  end
+end

data/lib/hecks/command_names/sources.rb

@@ -0,0 +1,73 @@
+module Hecks
+  module CommandNames
+    # The files whose text shells out to the launcher, and the ones left out.
+    module Sources
+      # Globs, relative to the checkout, of the files a line may invoke the launcher in.
+      INCLUDED = %w[
+        .github/workflows/*.yml .github/workflows/*.yaml .github/actions/**/* .githooks/*
+        lib/hecks/language/bluebook/vocabulary.bluebook Makefile scripts/**/* spec/**/*.rb
+        docs/implemented/**/*.md CLAUDE.md
+        lib/**/*.rb qa/**/*.rb qa/**/*.md qa/**/*.sh qa/**/*.yml
+        .claude/hooks/* .claude/settings.json .claude/skills/**/*.md .claude/agents/**/*.md
+      ].freeze
+
+      # Exact lines left unflagged. Each is a dead name kept on purpose until a person picks the
+      # command that replaces it; remove the entry when that command exists.
+      #
+      # The headers below are written into committed generated files (diagrams, the Rust syntax and
+      # phrase tables, the site routes, the kernel templates) and specs assert them, so renaming
+      # one is a regeneration of those files and its own change.
+      ALLOWED_LINES = [
+        # The mint plan's ledger line has no successor command yet.
+        "exe/hecks Maintenance.mint_era! run.value=<run-id>",
+        "hecks project_diagrams", "hecks project_parser_table", "hecks project_phrase_table",
+        "hecks measure_kernel_coverage",
+        # The installed gem's own `hecks vendor`, which a client runs outside this launcher.
+        "(the name `hecks vendor` accepts)", "`hecks site site_projection.project_site"
+      ].freeze
+
+      # Paths that record what was once true, so a retired name in them is history, not a fault.
+      HISTORICAL = %r{\A(?:docs/decisions/|docs/implemented/decisions/|docs/archive/|CHANGELOG\.md\z)}
+
+      # A banner in a document's first lines that says it records a moment.
+      SNAPSHOT = /\A(?:>\s*)?\*\*Historical snapshot\b/
+
+      # A line in a document's first lines that excuses the whole file, such as a page that lists
+      # the names a rename leaves behind.
+      SKIP_FILE = "dead-name-check: skip-file".freeze
+
+      # How many lines from the top count as "the first lines".
+      BANNER_WINDOW = 12
+
+      module_function
+
+      # @param root [String] the checkout
+      # @return [Array<String>] the paths to scan, relative to `root`, sorted
+      def files(root)
+        scanned(root).reject { |path| historical?(root, path) }
+      end
+
+      # @return [Array<String>] every file the globs reach, relative to `root`, sorted
+      def scanned(root)
+        paths = INCLUDED.flat_map { |glob| Dir.glob(File.join(root, glob), File::FNM_DOTMATCH) }
+        relative(root, paths.select { |path| File.file?(path) })
+      end
+
+      # @return [Array<String>] the paths below `root`, once each, sorted
+      def relative(root, paths) = paths.map { |path| path.delete_prefix("#{root}/") }.uniq.sort
+
+      # @return [Boolean] whether a path is history: a decision record, the changelog, an archive, a
+      #   document whose first lines call it a historical snapshot, or one that excuses itself
+      def historical?(root, path)
+        return true if path.match?(HISTORICAL)
+
+        File.foreach(File.join(root, path), encoding: "UTF-8").first(BANNER_WINDOW).any? { |line| excused?(line) }
+      end
+
+      # @return [Boolean] whether a line carries one of the allowed strings
+      def allowed?(text) = ALLOWED_LINES.any? { |allowed| text.include?(allowed) }
+
+      def excused?(line) = line.match?(SNAPSHOT) || line.include?(SKIP_FILE)
+    end
+  end
+end

data/lib/hecks/command_names.rb

@@ -0,0 +1,26 @@
+require_relative "command_names/check"
+
+module Hecks
+  # Reads the places that shell out to the launcher for names the launcher does not accept.
+  module CommandNames
+    # The clean verdict.
+    CLEAN = "every launcher name invoked in workflows, hooks, gate rows, specs and docs is one the launcher accepts".freeze
+
+    module_function
+
+    # @param root [String] the checkout
+    # @param runtime [#registry] what `Hecks.describe` answers
+    # @return [String] the clean verdict
+    # @raise [Failure] with a line for each name the launcher would refuse
+    def check(root:, runtime:)
+      scopes = Adapters::Driving::CliRunner.name_index(runtime: runtime)
+      found = Check.findings(root: root, scopes: scopes)
+      raise Failure, found.join("\n") unless found.empty?
+
+      CLEAN
+    end
+
+    # Raised with every finding.
+    class Failure < StandardError; end
+  end
+end

data/lib/hecks/composer/adapters/claude_composer.rb

@@ -2,6 +2,7 @@ require "json"
 require "open3"
 require "timeout"
 
+require_relative "../../text"
 require_relative "../agent"
 require_relative "jev"
 
@@ -22,7 +23,7 @@ module Hecks
               "for, write the bluebook first, then any hecksagon wiring it needs. Reply with one line " \
               "saying what you changed.".freeze
 
-      WIRE = "Change how the chapter in %<dir>s is wired, as the request below says: edit only its " \
+      WIRE = "Change how the bluebook in %<dir>s is wired, as the request below says: edit only its " \
              ".hecksagon and .world files, and bind adapters that already exist. Reply with one line " \
              "saying what you changed.".freeze
 
@@ -53,7 +54,7 @@ module Hecks
         stdout, status = run(root, message)
         raise Composer::Agent::Unavailable, "claude exited #{status.exitstatus}: #{stdout}" unless status.success?
 
-        { "note" => JSON.parse(stdout).fetch("result").to_s.lines.first.to_s.strip }
+        { "note" => Text.first_line(JSON.parse(stdout).fetch("result")) }
       rescue JSON::ParserError, KeyError => e
         raise Composer::Agent::ValidationError, "claude's reply was not the expected envelope: #{e.message}"
       end

data/lib/hecks/composer/agent.rb

@@ -40,7 +40,7 @@ module Hecks
         note(adapter(registry).draft(prompt: prompt, dir: dir))
       end
 
-      # Asks the agent to change how a workspace's chapter is wired, never what it declares.
+      # Asks the agent to change how a workspace's bluebook is wired, never what it declares.
       #
       # @param registry [Runtime::Registry] a registry holding the port and one adapter for it
       # @param prompt [String] what the author asked for

data/lib/hecks/composer/assistant.rb

@@ -45,8 +45,8 @@ module Hecks
       private
 
       def open_draft(slug, files)
-        chapter = Parse.bluebooks(@workspace).keys.first || "Workspace"
-        @session.open(slug: slug, chapter_name: chapter, text: files.values.first.to_s)
+        declaration = Parse.bluebooks(@workspace).keys.first || "Workspace"
+        @session.open(slug: slug, bluebook_name: declaration, text: files.values.first.to_s)
       end
 
       # The prompt's intent; a classifier that cannot answer leaves it an edit.

data/lib/hecks/composer/behavior_run.rb

@@ -26,12 +26,18 @@ module Hecks
       # @api private
       def report(stage, file)
         {
-          path:        file.path.to_s.delete_prefix("#{File.realpath(stage)}/").delete_prefix("#{stage}/"),
+          path:        relative_path(stage, file.path),
           parse_error: file.parse_error,
           runs:        file.runs.map { |run| run_hash(run) }
         }
       end
 
+      # The file's path inside the staged directory, whether given real or as staged.
+      # @api private
+      def relative_path(stage, path)
+        path.to_s.delete_prefix("#{File.realpath(stage)}/").delete_prefix("#{stage}/")
+      end
+
       # @api private
       def run_hash(run)
         { status: run.status.to_s, description: run.description, message: run.message }

data/lib/hecks/composer/bluebook/composer.bluebook

@@ -1,6 +1,6 @@
-# The Composer chapter: a bluebook being written in an editor, by hand or by asking an agent.
+# The Composer bluebook: a bluebook being written in an editor, by hand or by asking an agent.
 #
-# A Draft is the editor's working copy of one chapter: the text on screen, the conversation that
+# A Draft is the editor's working copy of one bluebook: the text on screen, the conversation that
 # shaped it, and whether the last check of it passed. The files on disk stay the truth; a Draft
 # only holds what is being changed and what was said about it. The check itself (parse, load,
 # project, model-check) and the agent that rewrites the text are the outside, reached through the
@@ -9,10 +9,10 @@ Hecks.bluebook "Composer" do
   vision "Write a bluebook in an editor and watch the domain draw itself, with an agent that can change the draft when asked."
 
   aggregate "Draft" do
-    description "One chapter being edited: its text, the conversation about it, and whether its last check passed."
+    description "One bluebook being edited: its text, the conversation about it, and whether its last check passed."
 
     attribute :slug,         DraftSlug
-    attribute :chapter_name, ChapterName
+    attribute :bluebook_name, BluebookName
     attribute :text,         SourceText
     attribute :note,         Note, optional: true
     attribute :turns,        list_of(Turn)
@@ -20,17 +20,17 @@ Hecks.bluebook "Composer" do
     identified_by :slug
 
     value_object "DraftSlug" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a draft is named") { !value.to_s.empty? }
     end
 
-    # The name a chapter's `Hecks.bluebook "Name"` header declares, which is also the name the
+    # The name a bluebook's `Hecks.bluebook "Name"` header declares, which is also the name the
     # check loads it under.
-    value_object "ChapterName" do
-      attribute :value, String, pattern: '[A-Z][A-Za-z0-9]*'
+    value_object "BluebookName" do
+      attribute :value, String, matches: :capitalized
 
-      invariant("a chapter is named") { !value.to_s.empty? }
+      invariant("a bluebook is named") { !value.to_s.empty? }
     end
 
     # What is on screen. A draft may be empty or half-written; the check judges it, not this.
@@ -60,7 +60,7 @@ Hecks.bluebook "Composer" do
     end
 
     # The sequence is supplied by the caller, who already knows how many turns are on screen, so
-    # the order of a conversation is not a fact this chapter invents on write.
+    # the order of a conversation is not a fact this bluebook invents on write.
     entity "Turn" do
       description "One thing said in the conversation about the draft, by the author or by the agent."
 
@@ -80,15 +80,12 @@ Hecks.bluebook "Composer" do
 
     command "Begin" do
       role "Author"
-      goal "Open a chapter for editing, with the text it starts from"
+      goal "Open a bluebook for editing, with the text it starts from"
 
-      attribute :slug,         DraftSlug
-      attribute :chapter_name, ChapterName
-      attribute :text,         SourceText
+      attribute :slug,         DraftSlug, sets: true
+      attribute :bluebook_name, BluebookName, sets: true
+      attribute :text,         SourceText, sets: true
 
-      sets :slug
-      sets :chapter_name
-      sets :text
 
       emits "DraftBegun"
     end
@@ -98,9 +95,8 @@ Hecks.bluebook "Composer" do
       goal "Replace the draft's text with what is now on screen"
 
       reference_to Draft
-      attribute :text, SourceText
+      attribute :text, SourceText, sets: true
 
-      sets :text
 
       emits "DraftRevised"
     end
@@ -110,9 +106,8 @@ Hecks.bluebook "Composer" do
       goal "Record that the draft's text passed its check"
 
       reference_to Draft
-      attribute :note, Note
+      attribute :note, Note, sets: true
 
-      sets :note
 
       emits "DraftAccepted"
     end
@@ -122,9 +117,8 @@ Hecks.bluebook "Composer" do
       goal "Record that the draft's text failed its check, and why"
 
       reference_to Draft
-      attribute :note, Note
+      attribute :note, Note, sets: true
 
-      sets :note
 
       emits "DraftRejected"
     end
@@ -149,9 +143,8 @@ Hecks.bluebook "Composer" do
       reference_to Draft
       attribute :sequence, TurnSequence
       attribute :said,     Utterance
-      attribute :text,     SourceText
+      attribute :text,     SourceText, sets: true
 
-      sets :text
       sets :turns, append: { sequence: :sequence, speaker: { value: "agent" }, said: :said }
 
       emits "TurnAnswered"

data/lib/hecks/composer/bluebook/composer.hecksagon

@@ -10,7 +10,7 @@ Hecks.hecksagon "Composer" do
   driven_by "Ruby"
 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/composer/board.rb

@@ -1,22 +1,22 @@
 module Hecks
   module Composer
-    # The event-storming board of a chapter, on the hecksagon side: its aggregates with their
+    # The event-storming board of a bluebook, on the hecksagon side: its aggregates with their
     # commands, the events each command emits, and the policies that make one event trigger another
-    # command. It is read off the booted chapter, so it always shows what the text declares; the
+    # command. It is read off the booted bluebook, so it always shows what the text declares; the
     # board's own edits go through {BoardEdit}, which rewrites the text.
     module Board
       module_function
 
-      # @param chapter [Bluebook::Chapter] the booted chapter
+      # @param bluebook [Bluebook::Declaration] the booted bluebook
       # @param outline [Array<Hash>] the text outline (see {Outline}), which says where each note
       #   is declared
       # @return [Hash] `aggregates` (each with `name`, `at` and its `commands`, each command with
       #   `name`, `role`, `goal`, `emits` and `at`) and `policies` (`name`, `on`, `trigger`, `at`),
       #   where `at` is `{file:, line:}` or nil, and `on` and `trigger` read `Aggregate.Name`
-      def call(chapter, outline:)
+      def call(declaration, outline:)
         places = Places.new(outline)
-        { aggregates: chapter.aggregates.map { |aggregate| aggregate_note(aggregate, places) },
-          policies:   chapter.policies.map { |policy| policy_note(policy, places) } }
+        { aggregates: declaration.aggregates.map { |aggregate| aggregate_note(aggregate, places) },
+          policies:   declaration.policies.map { |policy| policy_note(policy, places) } }
       end
 
       # @api private

data/lib/hecks/composer/board_edit/command_text.rb

@@ -5,6 +5,9 @@ module Hecks
       # the key the aggregate is known by; every later one acts on a record of it. A command with an
       # event says so on a line of its own.
       module CommandText
+        # An `identified_by :field` line, capturing the key field's name.
+        IDENTIFIED_BY = /\A\s*identified_by\s+:(\w+)\s*\z/
+
         module_function
 
         # @param block [Array<String>] the lines of the aggregate's block, after its declaration
@@ -27,7 +30,7 @@ module Hecks
         # The attribute and `sets` that give a new record its key.
         # @api private
         def creates(block, aggregate)
-          field = block.filter_map { |line| line[/\A\s*identified_by\s+:(\w+)\s*\z/, 1] }.first
+          field = block.filter_map { |line| line[IDENTIFIED_BY, 1] }.first
           type = field && block.filter_map { |line| line[/\A\s*attribute\s+:#{field},\s*([A-Za-z:]+)/, 1] }.first
           raise Refused, "#{aggregate} has no key the board can read; write its first command in the text" unless type