hecks 5.0.0 → 6.0.0

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
 

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

@@ -9,6 +9,15 @@ module Hecks
       # it: where a declaration is, where its block ends (found by indentation, as the bluebooks
       # are laid out), and a way to put a patched file back as one result.
       class Source
+        # A bluebook file's path.
+        BLUEBOOK_FILE = /\.bluebook\z/
+
+        # The `Hecks.bluebook "Name"` line that declares a bluebook.
+        BLUEBOOK_HEADER = /\A\s*Hecks\.bluebook\s+"/
+
+        # The spaces a line starts with.
+        LEADING_SPACES = /\A */
+
         # @return [Board::Places] where each aggregate, command and policy is declared
         attr_reader :places
 
@@ -16,7 +25,7 @@ module Hecks
         def initialize(stage)
           files = Workspace.files(stage)
           @places = Board::Places.new(Outline.call(stage, files))
-          @lines = files.grep(/\.bluebook\z/).to_h { |file| [file, File.read(File.join(stage, file)).lines.map(&:chomp)] }
+          @lines = files.grep(BLUEBOOK_FILE).to_h { |file| [file, File.read(File.join(stage, file)).lines.map(&:chomp)] }
         end
 
         # @param at [Hash] `{file:, line:}` of a declaration
@@ -34,14 +43,14 @@ module Hecks
         # @return [Integer] how many spaces its line is indented
         def indent(at) = indent_of(@lines.fetch(at[:file])[at[:line] - 1])
 
-        # The file and `end` of the chapter's own block, where new aggregates and policies go.
-        # @return [Hash] `{file:, line:}` of the chapter header
-        # @raise [Refused] if no file declares the chapter
-        def chapter
-          file = @lines.keys.sort.find { |path| @lines[path].any? { |line| line.match?(/\A\s*Hecks\.bluebook\s+"/) } }
-          raise Refused, "no file declares the chapter" unless file
+        # The file and `end` of the bluebook's own block, where new aggregates and policies go.
+        # @return [Hash] `{file:, line:}` of the bluebook header
+        # @raise [Refused] if no file declares the bluebook
+        def declaration
+          file = @lines.keys.sort.find { |path| @lines[path].any? { |line| line.match?(BLUEBOOK_HEADER) } }
+          raise Refused, "no file declares the bluebook" unless file
 
-          { file: file, line: @lines[file].index { |line| line.match?(/\A\s*Hecks\.bluebook\s+"/) } + 1 }
+          { file: file, line: @lines[file].index { |line| line.match?(BLUEBOOK_HEADER) } + 1 }
         end
 
         # @param file [String] a bluebook path
@@ -70,7 +79,7 @@ module Hecks
 
         private
 
-        def indent_of(line) = line[/\A */].size
+        def indent_of(line) = line[LEADING_SPACES].size
 
         # The new lines, without their leading blank line when one is already above the spot.
         def spaced(lines, before, added)

data/lib/hecks/composer/board_edit.rb

@@ -41,7 +41,7 @@ module Hecks
       def add_aggregate(source, name:)
         named!(name, "an aggregate")
         refuse!("#{name} is already an aggregate") if source.places.of("aggregate", name)
-        header = source.chapter
+        header = source.declaration
         source.insert(header[:file], source.block_end(header), aggregate_lines(name))
       end
 
@@ -81,7 +81,7 @@ module Hecks
         event = dotted!(on, "the event")
         target = dotted!(trigger, "the command")
         command_at(source, target[1], target[2])
-        header = source.chapter
+        header = source.declaration
         source.insert(header[:file], source.block_end(header), policy_lines(name, event, target))
       end
 

data/lib/hecks/composer/check.rb

@@ -13,66 +13,66 @@ module Hecks
 
       # @param dir [String] the workspace directory
       # @param buffers [Hash{String => String}] unsaved text by path relative to `dir`
-      # @param chapter_name [String, nil] the chapter to draw; the first bluebook's when nil
+      # @param declaration_name [String, nil] the bluebook to draw; the first bluebook's when nil
       # @return [Hash] `diagnostic` (nil, or `{file:, line:, message:, expected:}` for the first
       #   refusal), `files` (the workspace's declaration files), `outline` (see {Outline}),
-      #   `chapter` (the name drawn), `diagrams` (Mermaid text by file name), `statements` (plain
+      #   `bluebook` (the name drawn), `diagrams` (Mermaid text by file name), `statements` (plain
       #   sentences), `findings` (`{kind:, severity:, subject:, message:}` per model-check
       #   finding), `wiring` (see {wiring}, nil until the workspace boots), `board` (the
       #   event-storming notes, see {Board}, nil until it boots) and `elapsed_ms`
-      def call(dir:, buffers: {}, chapter_name: nil)
+      def call(dir:, buffers: {}, declaration_name: nil)
         started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        result = Workspace.stage(dir: dir, buffers: buffers) { |stage| judge(stage, chapter_name) }
+        result = Workspace.stage(dir: dir, buffers: buffers) { |stage| judge(stage, declaration_name) }
         result.merge(elapsed_ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round)
       end
 
       # @api private
-      def judge(stage, chapter_name)
+      def judge(stage, declaration_name)
         files = Workspace.files(stage)
-        verdict(stage, empty(files, Outline.call(stage, files)), chapter_name)
+        verdict(stage, empty(files, Outline.call(stage, files)), declaration_name)
       end
 
       # What the parser and the boot say of the staged text, laid over `base`.
       # @api private
-      def verdict(stage, base, chapter_name)
+      def verdict(stage, base, declaration_name)
         refusal = Parse.call(stage)
         return base.merge(diagnostic: refusal) if refusal
 
-        project(stage, base, chapter_name || Parse.bluebooks(stage).keys.first)
+        project(stage, base, declaration_name || Parse.bluebooks(stage).keys.first)
       rescue Parse::ParserMissing
         raise
       rescue StandardError => e
-        base.merge(diagnostic: { file: nil, line: nil, message: e.message.lines.first.to_s.chomp, expected: [] })
+        base.merge(diagnostic: { file: nil, line: nil, message: Text.headline(e.message), expected: [] })
       end
 
       # @api private
       def project(stage, base, name)
         registry = Hecks.boot(stage, install_driving: false, environment: "memory").registry
-        chapter = registry.bluebook(name)
-        base.merge(chapter: name, wiring: wiring(registry, name), board: Board.call(chapter, outline: base[:outline]),
-                   **read(chapter, registry.hecksagon(name)))
+        declaration = registry.bluebook(name)
+        base.merge(bluebook: name, wiring: wiring(registry, name),
+                   board: Board.call(declaration, outline: base[:outline]), **read(declaration, registry.hecksagon(name)))
       end
 
-      # The diagrams, statements and model-check findings of a booted chapter.
+      # The diagrams, statements and model-check findings of a booted bluebook.
       # @api private
-      def read(chapter, hecksagon)
-        { diagrams:   Projections::Diagrams.call(bluebook: chapter, options: { hecksagon: hecksagon }),
-          statements: Projections::Statements.call(bluebook: chapter),
-          findings:   Bluebook::ModelCheck.call(chapter, hecksagon: hecksagon).map(&:to_h) }
+      def read(declaration, hecksagon)
+        { diagrams:   Projections::Diagrams.call(bluebook: declaration, options: { hecksagon: hecksagon }),
+          statements: Projections::Statements.call(bluebook: declaration),
+          findings:   Bluebook::ModelCheck.call(declaration, hecksagon: hecksagon).map(&:to_h) }
       end
 
-      # What the chapter is wired to: the binds its hecksagon declares, the chapters it attaches,
+      # What the bluebook is wired to: the binds its hecksagon declares, the bluebooks it attaches,
       # the driving adapters it admits, the world's default adapter, and each declared port with
       # the adapters bound to it.
       #
       # @param registry [Runtime::Registry] a booted registry
-      # @param name [String] the chapter's name
+      # @param name [String] the bluebook's name
       # @return [Hash] `binds`, `attaches`, `driving`, `default_adapter` and `ports`
       def wiring(registry, name)
         hecksagon = registry.hecksagon(name)
         {
           binds:           (hecksagon&.binds || []).map { |bind| bind.to_h.slice(:aggregate, :verb, :adapter, :role) },
-          attaches:        hecksagon&.member_chapters || [],
+          attaches:        hecksagon&.member_bluebooks || [],
           driving:         hecksagon&.driving || [],
           default_adapter: registry.world(name)&.default_adapter,
           ports:           Runtime::CapabilityGraph.new(registry).fulfillments
@@ -81,8 +81,8 @@ module Hecks
 
       # @api private
       def empty(files, outline)
-        { diagnostic: nil, files: files, outline: outline, chapter: nil, diagrams: {}, statements: [],
-          findings: [], wiring: nil, board: nil }
+        { diagnostic: nil, files: files, outline: outline, bluebook: nil, diagrams: {},
+          statements: [], findings: [], wiring: nil, board: nil }
       end
     end
   end

data/lib/hecks/composer/domains.rb

@@ -16,7 +16,7 @@ module Hecks
       # The groups the picker shows, in order, each with the ids it takes.
       GROUPS = [["Examples", %r{\Aexamples/[^/]+\z}],
                 ["Stress domains", %r{\Aqa/stress_domains/[^/]+\z}],
-                ["Hecks chapters", %r{\Alib/hecks/}],
+                ["Hecks bluebooks", %r{\Alib/hecks/}],
                 ["Quality control", /\Aqa\z/],
                 ["Composer fixtures", %r{\Aspec/fixtures/composer/[^/]+\z}]].freeze
 

data/lib/hecks/composer/live.rb

@@ -11,8 +11,8 @@ module Hecks
     # hecksagon: the editor drives the domain, the domain keeps its records in memory, and the
     # staged copy of the files lives until `close`.
     class Live
-      # @return [String] the chapter the workspace booted
-      attr_reader :chapter_name
+      # @return [String] the bluebook the workspace booted
+      attr_reader :declaration_name
 
       # Stages the workspace and boots it in memory.
       #
@@ -25,7 +25,7 @@ module Hecks
         stage = Workspace.materialize(dir: dir, buffers: buffers)
         begin
           runtime = Hecks.boot(stage, install_driving: false, environment: "memory")
-          new(stage: stage, runtime: runtime, chapter_name: Parse.bluebooks(stage).keys.first)
+          new(stage: stage, runtime: runtime, declaration_name: Parse.bluebooks(stage).keys.first)
         rescue StandardError, ScriptError
           FileUtils.rm_rf(stage)
           raise
@@ -34,14 +34,14 @@ module Hecks
 
       # @param stage [String] the staged directory this domain booted from
       # @param runtime [Runtime::Dispatcher] the booted domain
-      # @param chapter_name [String] the chapter's name
-      def initialize(stage:, runtime:, chapter_name:)
+      # @param declaration_name [String] the bluebook's name
+      def initialize(stage:, runtime:, declaration_name:)
         @stage = stage
         @runtime = runtime
-        @chapter_name = chapter_name
+        @declaration_name = declaration_name
       end
 
-      # The aggregate commands the chapter declares, each with a starter value for every argument.
+      # The aggregate commands the bluebook declares, each with a starter value for every argument.
       #
       # @return [Array<Hash>] per command: `verb`, `aggregate`, `command`, `goal`, `creates`,
       #   `args` (`{name:, type:, optional:}` each) and `template` (argument name to starter value)
@@ -67,7 +67,7 @@ module Hecks
       # @return [Hash{String => Array<Hash>}] each aggregate's name to its records as plain rows
       def records
         aggregates.to_h do |aggregate|
-          rows = @runtime.registry.repository(@chapter_name, aggregate).all
+          rows = @runtime.repository(@declaration_name, aggregate).all
           [aggregate.hecks_name, Plain.call(rows.to_a)]
         end
       end
@@ -76,7 +76,8 @@ module Hecks
       # @return [Array<Hash>] the last `limit` events, oldest first, as plain Hashes with `name`,
       #   `aggregate`, `id`, `payload` and `occurred_at`
       def history(limit = 200)
-        @runtime.events.to_a.last(limit).map { |event| Plain.call(event.to_h) }
+        latest = @runtime.events.to_a.last(limit)
+        latest.map { |event| Plain.call(event.to_h) }
       end
 
       # Removes the staged copy of the workspace. Calling it again does nothing.
@@ -87,7 +88,7 @@ module Hecks
       end
 
       # @api private
-      def aggregates = @runtime.registry.bluebook(@chapter_name).aggregates
+      def aggregates = @runtime.bluebook(@declaration_name).aggregates
 
       # @api private
       def accepted(result)
@@ -97,14 +98,19 @@ module Hecks
 
       # @api private
       def refused(error)
-        { ok: false, kind: error.class.name.to_s.split("::").last,
-          error: error.message.lines.first.to_s.chomp }
+        { ok: false, kind: short_class_name(error), error: Text.headline(error.message) }
+      end
+
+      # @api private
+      def short_class_name(error)
+        name = error.class.name.to_s
+        name.split("::").last
       end
 
       # @api private
       def describe(aggregate, command)
         args = arguments(command)
-        { verb: "#{@chapter_name}::#{aggregate.hecks_name}.#{command.hecks_name}",
+        { verb: "#{@declaration_name}::#{aggregate.hecks_name}.#{command.hecks_name}",
           aggregate: aggregate.hecks_name, command: command.hecks_name, goal: command.goal.to_s,
           creates: command.references.nil?, args: args, template: template(aggregate, args) }
       end

data/lib/hecks/composer/outline.rb

@@ -10,6 +10,9 @@ module Hecks
       DECLARATION = /\A\s*(#{KINDS.join("|")})\s+"([^"]+)"/
       SUMMARY = /\A\s*(?:goal|description)\s+"((?:[^"\\]|\\.)*)"/
 
+      # The path of a file that declares things: a bluebook, hecksagon, behaviors or world file.
+      DECLARING_FILE = /\.(bluebook|hecksagon|behaviors|world)\z/
+
       # How many lines below a declaration its `goal` or `description` may sit.
       REACH = 6
 
@@ -20,7 +23,7 @@ module Hecks
       # @return [Array<Hash>] `{file:, line:, kind:, name:, summary:}` for each declaration, in file
       #   then line order; `line` counts from 1 and `summary` is nil when none follows
       def call(stage, files)
-        files.grep(/\.(bluebook|hecksagon|behaviors|world)\z/).flat_map do |file|
+        files.grep(DECLARING_FILE).flat_map do |file|
           entries(file, File.readlines(File.join(stage, file), chomp: true))
         end
       end

data/lib/hecks/composer/page.html

@@ -735,7 +735,7 @@
   editor.on("change", (cm, change) => { if (change.origin !== "setValue") changed(); });
   editor.on("inputRead", (cm, change) => { if (/\w/.test(change.text.join("")) && state.diagnostic && state.diagnostic.expected.length) complete(); });
 
-  // The board: the chapter as event-storming notes, one lane per aggregate, read from the check's
+  // The board: the bluebook as event-storming notes, one lane per aggregate, read from the check's
   // `board`. Every action on a note is one edit of the text (see BoardEdit), applied to the editor
   // like typing, so the board never holds anything the text does not.
   const NOTE = { w: 140, h: 46, pillW: 130, pillH: 26 };

data/lib/hecks/composer/panels.rb

@@ -1,3 +1,4 @@
+require_relative "../text"
 require "digest"
 require "json"
 require_relative "live"
@@ -36,8 +37,10 @@ module Hecks
       end
 
       # @param body [Hash] `buffers`
-      # @return [Hash] `chapter` and `commands` (see {Live#commands}), or `error`
-      def commands(body) = with_live(body) { |live| { chapter: live.chapter_name, commands: live.commands } }
+      # @return [Hash] `bluebook` and `commands` (see {Live#commands}), or `error`
+      def commands(body)
+        with_live(body) { |live| { bluebook: live.declaration_name, commands: live.commands } }
+      end
 
       # @param body [Hash] `buffers`, `verb`, `to` and `with`
       # @return [Hash] see {Live#dispatch}, or `error` when the text does not boot
@@ -110,7 +113,7 @@ module Hecks
       def with_live(body)
         @lock.synchronize { yield live_for(body.fetch("buffers", {})) }
       rescue StandardError, ScriptError => e
-        { error: e.message.lines.first.to_s.chomp }
+        { error: Text.headline(e.message) }
       end
 
       def live_for(buffers)

data/lib/hecks/composer/parse.rb

@@ -1,4 +1,5 @@
 require "open3"
+require_relative "../sentence_form"
 
 module Hecks
   module Composer
@@ -9,75 +10,91 @@ module Hecks
       # The repository root, where the parser's build lands under `rust/parser/target/`.
       ROOT = File.expand_path("../../..", __dir__).freeze
 
+      # A bluebook file's path.
+      BLUEBOOK_FILE = /\.bluebook\z/
+
+      # A line number: digits and nothing else.
+      LINE_NUMBER = /\A\d+\z/
+
+      # A column then the message, as the sentence form's refusals give them: `63: this is not`.
+      COLUMN_PREFIX = /\A(\d+): (.*)\z/m
+
+      # A message ending in `(expected one of: a, b)`, capturing the message and the list.
+      EXPECTED_SUFFIX = /\A(.*) \(expected one of: (.*)\)\z/
+
       # Raised when no `hecks-parse` binary can be found.
-      class ParserMissing < StandardError; end
+      ParserMissing = SentenceForm::ParserMissing
 
       module_function
 
-      # Parses every bluebook in a staged workspace, one chapter at a time.
+      # Parses every bluebook in a staged workspace, one bluebook at a time.
       #
       # @param stage [String] a staged directory (see {Workspace.stage})
       # @return [Hash, nil] nil when everything parses; otherwise `{file:, line:, message:,
       #   expected:}` for the first refusal, with `file` relative to the stage
       # @raise [ParserMissing] if `hecks-parse` is not built
       def call(stage)
-        bluebooks(stage).each do |chapter, files|
-          refusal = refusal_for(stage, chapter, files)
+        bluebooks(stage).each do |declaration, files|
+          refusal = refusal_for(stage, declaration, files)
           return refusal if refusal
         end
         nil
       end
 
       # @param stage [String] a staged directory
-      # @return [Hash{String => Array<String>}] relative bluebook paths by the chapter their
+      # @return [Hash{String => Array<String>}] relative bluebook paths by the bluebook their
       #   header names
       def bluebooks(stage)
-        Workspace.files(stage).grep(/\.bluebook\z/).group_by { |relative| chapter_name(File.join(stage, relative)) }
-                 .reject { |name, _| name.nil? }
+        bluebook_files(stage).group_by { |relative| declaration_name(File.join(stage, relative)) }
+                             .reject { |name, _| name.nil? }
       end
 
+      # @api private
+      def bluebook_files(stage) = Workspace.files(stage).grep(BLUEBOOK_FILE)
+
       # @param path [String] a bluebook file
-      # @return [String, nil] the name its `Hecks.bluebook "Name"` header declares
-      def chapter_name(path)
-        File.foreach(path) { |line| return Regexp.last_match(1) if line =~ /\A\s*Hecks\.bluebook\s+"([^"]+)"/ }
-        nil
-      end
+      # @return [String, nil] the name its `Hecks.bluebook "Name"` or `Domain: name` header declares
+      def declaration_name(path) = SentenceForm.declaration_name(path)
 
       # @api private
-      def refusal_for(stage, chapter, files)
+      def refusal_for(stage, declaration, files)
         paths = files.map { |relative| File.join(stage, relative) }
-        _out, err, status = Open3.capture3(binary, "chapter", "--chapter", chapter, *paths)
+        _out, err, status = Open3.capture3(binary, "bluebook", "--bluebook", declaration, *paths)
         return nil if status.success?
 
-        diagnostic(err.lines.first.to_s.chomp, stage)
+        first_line = err.lines.first
+        diagnostic(first_line.to_s.chomp, stage)
       end
 
-      # Reads `<file>:<line>: <message>` with an optional `(expected one of: a, b, c)` suffix.
+      # Reads `<file>:<line>: <message>`, or `<file>:<line>:<column>: <message>` for a file written
+      # as sentences, with an optional `(expected one of: a, b, c)` suffix.
       # @api private
       def diagnostic(line, stage)
-        rest = line.delete_prefix("#{stage}/")
-        file, number, message = rest.split(":", 3)
-        return { file: nil, line: nil, message: line, expected: [] } unless number.to_s.strip.match?(/\A\d+\z/)
-
-        message = message.to_s.strip
-        expected = []
-        if (found = message.match(/\A(.*) \(expected one of: (.*)\)\z/))
-          message = found[1]
-          expected = found[2].split(", ")
-        end
-        { file: file, line: number.to_i, message: message, expected: expected }
+        file, number, message = line.delete_prefix("#{stage}/").split(":", 3)
+        return { file: nil, line: nil, column: nil, message: line, expected: [] } unless number.to_s.strip.match?(LINE_NUMBER)
+
+        column, message = split_column(message.to_s.strip)
+        message, expected = split_expected(message)
+        { file: file, line: number.to_i, column: column, message: message, expected: expected }
       end
 
-      # @return [String] the path to `hecks-parse`: `HECKS_PARSE_BIN`, then the release or debug
-      #   build under `rust/parser/target/`
-      # @raise [ParserMissing] if none exists
-      def binary
-        candidates = [ENV.fetch("HECKS_PARSE_BIN", nil)] +
-                     %w[release debug].map { |profile| File.join(ROOT, "rust/parser/target/#{profile}/hecks-parse") }
-        candidates.compact.find { |path| File.executable?(path) } or
-          raise ParserMissing, "hecks-parse is not built — run `cargo build --release " \
-                               "--manifest-path rust/parser/Cargo.toml`"
+      # @param message [String] a diagnostic's text after the line number
+      # @return [Array(Integer, String), Array(nil, String)] the column it names, and the rest
+      def split_column(message)
+        positioned = message.match(COLUMN_PREFIX)
+        positioned ? [positioned[1].to_i, positioned[2]] : [nil, message]
       end
+
+      # @param message [String] a diagnostic's text with its column taken off
+      # @return [Array(String, Array<String>)] the message, and the phrases that would have fitted
+      def split_expected(message)
+        found = message.match(EXPECTED_SUFFIX)
+        found ? [found[1], found[2].split(", ")] : [message, []]
+      end
+
+      # @return [String] the path to `hecks-parse`; see {SentenceForm.binary}
+      # @raise [ParserMissing] if none exists
+      def binary = SentenceForm.binary
     end
   end
 end

data/lib/hecks/composer/session.rb

@@ -4,36 +4,39 @@ require_relative "plain"
 
 module Hecks
   module Composer
-    # The editor's own bookkeeping, held in memory: one Composer chapter booted for the life of the
-    # server, with a `Draft` per chapter being edited. The files on disk stay the truth; the draft
+    # The editor's own bookkeeping, held in memory: one Composer bluebook booted for the life of the
+    # server, with a `Draft` per bluebook being edited. The files on disk stay the truth; the draft
     # keeps the text last seen, the conversation about it, and what its last check said, so the
     # page can show a history and an agent's turns survive a refresh.
     class Session
-      CHAPTER_DIR = File.expand_path("bluebook", __dir__).freeze
+      BLUEBOOK_DIR = File.expand_path("bluebook", __dir__).freeze
       VERB = "Composer::Draft".freeze
 
-      # @return [Runtime::Dispatcher] the booted Composer chapter
+      # A `Hecks.<construct> "Name"` header, capturing the bluebook's name.
+      BLUEBOOK_DECLARATION = /Hecks\.\w+\s+"([A-Z][A-Za-z0-9]*)"/
+
+      # @return [Runtime::Dispatcher] the booted Composer bluebook
       attr_reader :runtime
 
-      # Boots the Composer chapter, which admits only the `Web` driving adapter.
+      # Boots the Composer bluebook, which admits only the `Web` driving adapter.
       #
       # @raise [Adapters::Driving::Admission::Refused] if the hecksagon does not admit `Web`
       def initialize
-        @runtime = Hecks.boot(CHAPTER_DIR, install_driving: false, environment: "memory")
+        @runtime = Hecks.boot(BLUEBOOK_DIR, install_driving: false, environment: "memory")
         Adapters::Driving::Admission.admit!(@runtime.registry, "Web")
         @sequence = Hash.new(0)
       end
 
-      # Opens a draft for a chapter, or leaves an open one as it is.
+      # Opens a draft for a bluebook, or leaves an open one as it is.
       #
       # @param slug [String] the draft's name
-      # @param chapter_name [String] the chapter's name
+      # @param bluebook_name [String] the bluebook's name
       # @param text [String] the text it starts from
       # @return [void]
-      def open(slug:, chapter_name:, text:)
+      def open(slug:, bluebook_name:, text:)
         return if draft(slug)
 
-        dispatch("Begin", slug: wrap(slug), chapter_name: wrap(chapter_name), text: wrap(text))
+        dispatch("Begin", slug: wrap(slug), bluebook_name: wrap(bluebook_name), text: wrap(text))
       end
 
       # Records the text now on screen.
@@ -53,10 +56,10 @@ module Hecks
       def record(path:, text:)
         return revise(slug: path, text: text) if draft(path)
 
-        self.open(slug: path, chapter_name: chapter_name_in(text), text: text)
+        self.open(slug: path, bluebook_name: bluebook_name_in(text), text: text)
       end
 
-      # The text a file has held, from the chapter's own events.
+      # The text a file has held, from the bluebook's own events.
       #
       # @param path [String] the file's path relative to the workspace
       # @return [Array<Hash>] `name`, `at` and `text` per recorded revision, newest first; empty
@@ -97,9 +100,9 @@ module Hecks
       end
 
       # @param slug [String] the draft's name
-      # @return [Hash, nil] the draft as the chapter holds it, or nil when none is open
+      # @return [Hash, nil] the draft as the bluebook holds it, or nil when none is open
       def draft(slug)
-        @runtime.registry.repository("Composer", aggregate).find(slug)&.then { |row| plain(row) }
+        drafts.find(slug)&.then { |row| plain(row) }
       rescue StandardError
         nil
       end
@@ -116,7 +119,7 @@ module Hecks
       private
 
       # @api private
-      def chapter_name_in(text) = text[/Hecks\.\w+\s+"([A-Z][A-Za-z0-9]*)"/, 1] || "Workspace"
+      def bluebook_name_in(text) = text[BLUEBOOK_DECLARATION, 1] || "Workspace"
 
       # @api private
       def revision(event, path)
@@ -125,7 +128,10 @@ module Hecks
         { name: event[:name], at: event[:occurred_at], text: Plain.call(event[:payload])&.dig(:text) }
       end
 
-      def aggregate = @runtime.registry.bluebook("Composer").aggregate("Draft")
+      def aggregate = @runtime.bluebook("Composer").aggregate("Draft")
+
+      # @api private
+      def drafts = @runtime.repository("Composer", aggregate)
 
       def dispatch(command, to: nil, **facts)
         @runtime.dispatch("#{VERB}.#{command}", to: to, with: facts)