hecks 3.14.0 → 4.0.0

data/lib/hecks/composer/board_edit.rb

@@ -0,0 +1,144 @@
+require_relative "board_edit/command_text"
+require_relative "board_edit/source"
+
+module Hecks
+  module Composer
+    # What the board does to the text, on the hecksagon side: each action on a note is one exact
+    # edit of the bluebook, with no model in the loop, so a board change is instant and the text
+    # stays the single source of truth. It answers the patched file; the editor applies it as an
+    # ordinary edit, so Undo takes it back.
+    #
+    # Fields, rules and givens are not on the board: they stay in the text, where the agent can
+    # fill them in.
+    module BoardEdit
+      # Raised when an action cannot be carried out, in the board's own words.
+      class Refused < StandardError; end
+
+      NAME = /\A[A-Z][A-Za-z0-9]*\z/
+      DOTTED = /\A([A-Z][A-Za-z0-9]*)\.([A-Z][A-Za-z0-9]*)\z/
+
+      # Each action and the arguments it takes.
+      OPERATIONS = {
+        "add_aggregate" => %i[name], "add_command" => %i[aggregate name event],
+        "add_event" => %i[aggregate command name], "add_policy" => %i[name on trigger],
+        "delete" => %i[kind name aggregate], "delete_event" => %i[aggregate command name]
+      }.freeze
+
+      module_function
+
+      # @param stage [String] a staged directory holding the workspace as it is on screen
+      # @param action [String] one of the keys of `OPERATIONS`
+      # @param args [Hash{String => String}] the action's arguments
+      # @return [Hash] the patched file: `path`, its whole new `text`, and the `line` to show
+      # @raise [Refused] if the action is unknown or cannot be carried out
+      def call(stage:, action:, args:)
+        wanted = OPERATIONS.fetch(action) { raise Refused, "the board has no action called #{action.inspect}" }
+        values = wanted.to_h { |key| [key, args[key.to_s].to_s.strip] }
+        public_send(action, Source.new(stage), **values)
+      end
+
+      # @api private
+      def add_aggregate(source, name:)
+        named!(name, "an aggregate")
+        refuse!("#{name} is already an aggregate") if source.places.of("aggregate", name)
+        header = source.chapter
+        source.insert(header[:file], source.block_end(header), aggregate_lines(name))
+      end
+
+      # A new aggregate is known by a key of its own, so its first command can create it.
+      # @api private
+      def aggregate_lines(name)
+        ["", "  aggregate \"#{name}\" do", "    description \"Describe #{name}.\"", "",
+         "    attribute :key, #{name}Key", "    identified_by :key", "",
+         "    value_object \"#{name}Key\" do", "      attribute :value, String", "    end", "  end"]
+      end
+
+      # @api private
+      def add_command(source, aggregate:, name:, event:)
+        named!(name, "a command")
+        named!(event, "an event") unless event.empty?
+        where = aggregate_at(source, aggregate)
+        refuse!("#{aggregate} already has a command #{name}") if source.places.of("command", name, owner: aggregate)
+        close = source.block_end(where)
+        block = source.slice(where[:file], where[:line], close)
+        lines = CommandText.lines(block: block, indent: source.indent(where), aggregate: aggregate, name: name, event: event)
+        source.insert(where[:file], close, lines)
+      end
+
+      # @api private
+      def add_event(source, aggregate:, command:, name:)
+        named!(name, "an event")
+        where = command_at(source, aggregate, command)
+        refuse!("#{command} already emits #{name}") if emit_line(source, where, name)
+        pad = " " * (source.indent(where) + 2)
+        source.insert(where[:file], source.block_end(where), ["#{pad}emits #{name}"])
+      end
+
+      # @api private
+      def add_policy(source, name:, on:, trigger:)
+        named!(name, "a policy")
+        refuse!("there is already a policy #{name}") if source.places.of("policy", name)
+        event = dotted!(on, "the event")
+        target = dotted!(trigger, "the command")
+        command_at(source, target[1], target[2])
+        header = source.chapter
+        source.insert(header[:file], source.block_end(header), policy_lines(name, event, target))
+      end
+
+      # @api private
+      def policy_lines(name, event, target)
+        ["", "  policy \"#{name}\" do", "    on #{event[1]}::#{event[2]}", "    trigger #{target[1]}::#{target[2]}", "  end"]
+      end
+
+      # @api private
+      def delete(source, kind:, name:, aggregate:)
+        where = case kind
+                when "aggregate" then aggregate_at(source, name)
+                when "command" then command_at(source, aggregate, name)
+                when "policy" then source.places.of("policy", name) || refuse!("there is no policy #{name}")
+                else refuse!("the board cannot delete a #{kind.inspect}")
+                end
+        source.remove(where[:file], where[:line] - 1, source.block_end(where))
+      end
+
+      # @api private
+      def delete_event(source, aggregate:, command:, name:)
+        where = command_at(source, aggregate, command)
+        line = emit_line(source, where, name) or refuse!("#{command} does not emit #{name}")
+        source.remove(where[:file], line, line)
+      end
+
+      # @api private
+      def aggregate_at(source, name)
+        source.places.of("aggregate", name) || refuse!("there is no aggregate #{name}")
+      end
+
+      # @api private
+      def command_at(source, aggregate, name)
+        source.places.of("command", name, owner: aggregate) || refuse!("#{aggregate} has no command #{name}")
+      end
+
+      # The 0-based index of the line in a command's block that emits the event, or nil.
+      # @api private
+      def emit_line(source, where, name)
+        from = where[:line]
+        block = source.slice(where[:file], from, source.block_end(where))
+        found = block.index { |text| text.match?(/\A\s*emits\s+("?)#{Regexp.escape(name)}\1\s*\z/) }
+        found && (from + found)
+      end
+
+      # @api private
+      def dotted!(text, what)
+        DOTTED.match(text) || refuse!("#{what} is written Aggregate.Name, not #{text.inspect}")
+      end
+
+      # @api private
+      def named!(name, what)
+        refuse!("#{what} needs a name that starts with a capital letter, with letters and digits only") unless NAME.match?(name)
+      end
+
+      # @api private
+      def refuse!(message) = raise(Refused, message)
+    end
+  end
+end

data/lib/hecks/composer/check.rb

@@ -0,0 +1,89 @@
+require "hecks"
+require "hecks/bluebook/model_check"
+require "hecks/runtime/capability_graph"
+require_relative "board"
+
+module Hecks
+  module Composer
+    # Judges a workspace as it stands on screen: parse it, boot it, then draw and read back what
+    # it declares. It changes nothing on disk and holds nothing between calls, so a caller may
+    # run it on every pause in typing.
+    module Check
+      module_function
+
+      # @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
+      # @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
+      #   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)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = Workspace.stage(dir: dir, buffers: buffers) { |stage| judge(stage, chapter_name) }
+        result.merge(elapsed_ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round)
+      end
+
+      # @api private
+      def judge(stage, chapter_name)
+        files = Workspace.files(stage)
+        verdict(stage, empty(files, Outline.call(stage, files)), chapter_name)
+      end
+
+      # What the parser and the boot say of the staged text, laid over `base`.
+      # @api private
+      def verdict(stage, base, chapter_name)
+        refusal = Parse.call(stage)
+        return base.merge(diagnostic: refusal) if refusal
+
+        project(stage, base, chapter_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: [] })
+      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)))
+      end
+
+      # The diagrams, statements and model-check findings of a booted chapter.
+      # @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) }
+      end
+
+      # What the chapter is wired to: the binds its hecksagon declares, the chapters 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
+      # @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 || [],
+          driving:         hecksagon&.driving || [],
+          default_adapter: registry.world(name)&.default_adapter,
+          ports:           Runtime::CapabilityGraph.new(registry).fulfillments
+        }
+      end
+
+      # @api private
+      def empty(files, outline)
+        { diagnostic: nil, files: files, outline: outline, chapter: nil, diagrams: {}, statements: [],
+          findings: [], wiring: nil, board: nil }
+      end
+    end
+  end
+end

data/lib/hecks/composer/domains.rb

@@ -0,0 +1,81 @@
+require "fileutils"
+require_relative "workspace"
+
+module Hecks
+  module Composer
+    # The domains the editor can open, on the hecksagon side: every directory under a checkout
+    # that holds a bluebook, in groups, and the copy of one that the editor works on.
+    #
+    # A domain is opened as a scratch copy under `tmp/composer/`, so saving, the agent and Undo
+    # never touch the real files. Only an id from {known} can be opened, so a request cannot name
+    # a path of its own.
+    module Domains
+      # Where scratch copies live, relative to the checkout (it is not committed).
+      SCRATCH = "tmp/composer".freeze
+
+      # 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/}],
+                ["Quality control", /\Aqa\z/],
+                ["Composer fixtures", %r{\Aspec/fixtures/composer/[^/]+\z}]].freeze
+
+      # Raised when an id is not one of the known domains.
+      class Unknown < ArgumentError; end
+
+      module_function
+
+      # @param root [String] the checkout to search
+      # @return [Array<Hash>] `{id:, group:}` for each known domain, in group then id order, where
+      #   `id` is the domain's directory relative to `root`
+      def known(root:)
+        entries = owners(root).filter_map { |id| entry_for(id) }
+        entries.sort_by { |entry| [rank(entry[:group]), entry[:id]] }
+      end
+
+      # Copies a known domain's declaration files into a fresh scratch directory.
+      #
+      # @param root [String] the checkout
+      # @param id [String] one of the ids {known} lists
+      # @return [String] the scratch directory the editor should open
+      # @raise [Unknown] if `id` is not a known domain
+      def open(root:, id:)
+        raise Unknown, "#{id.inspect} is not a domain this checkout knows" unless known?(root, id)
+
+        scratch = File.join(root, SCRATCH, id.tr("/", "_"))
+        FileUtils.rm_rf(scratch)
+        FileUtils.mkdir_p(scratch)
+        Workspace.copy_declarations(source(root, id), scratch)
+        scratch
+      end
+
+      # @api private
+      def known?(root, id) = known(root: root).any? { |entry| entry[:id] == id }
+
+      # @api private
+      def entry_for(id)
+        group = GROUPS.find { |_, pattern| pattern.match?(id) }
+        { id: id, group: group.first } if group
+      end
+
+      # @api private
+      def rank(group) = GROUPS.index { |name, _| name == group }
+
+      # @api private
+      def owners(root)
+        Dir.glob("**/*.bluebook", base: root).map { |path| owner(File.dirname(path)) }.uniq
+      end
+
+      # A `bluebook/` folder stands for the domain that holds it.
+      # @api private
+      def owner(dir) = File.basename(dir) == "bluebook" ? File.dirname(dir) : dir
+
+      # Where a domain's bluebooks are: its `bluebook/` folder if it has one, else itself.
+      # @api private
+      def source(root, id)
+        folder = File.join(root, id, "bluebook")
+        File.directory?(folder) ? folder : File.join(root, id)
+      end
+    end
+  end
+end

data/lib/hecks/composer/jobs.rb

@@ -0,0 +1,134 @@
+require "time"
+
+module Hecks
+  module Composer
+    # Runs one long-running command at a time in the background, on the hecksagon side like the
+    # other composer files. Fuzzing and conformance runs take seconds to minutes, so the caller
+    # starts a job and the page polls {#state}.
+    #
+    # A job is a call to the injected runner on a worker thread. A watchdog thread ends it when
+    # it outlives the timeout. Cancelling or timing out kills the worker thread only: a child
+    # process the command spawned is not killed and keeps running until it exits on its own.
+    # All state sits behind one mutex, so {#state} is safe to call from any thread.
+    class Jobs
+      # Raised by {#start} while another job is still running.
+      class Busy < StandardError; end
+
+      # How much of a job's output {#state} keeps, counted from the end.
+      OUTPUT_LIMIT = 20_000
+
+      # @param runner [#call] takes `kind:, verb:, args:, confirm:` and returns
+      #   `{ok:, status:, output:}`
+      # @param timeout [Numeric] seconds a job may run before it is marked "timed_out"
+      def initialize(runner:, timeout: 600)
+        @runner = runner
+        @timeout = timeout
+        @mutex = Mutex.new
+        @settled = ConditionVariable.new
+        @generation = 0
+        @state = blank
+      end
+
+      # @param kind [String] the kind of command the runner dispatches on
+      # @param verb [String] the command's verb
+      # @param args [Hash] the command's arguments
+      # @param confirm [String, nil] the confirmation the runner requires, if any
+      # @return [true]
+      # @raise [Busy] when a job is running
+      def start(kind:, verb:, args: {}, confirm: nil) # rubocop:disable Naming/PredicateMethod
+        @mutex.synchronize do
+          raise Busy, "a job is already running" if running?
+
+          @state = blank.merge(status: "running", verb: verb, started_at: stamp)
+          launch(@generation += 1, { kind: kind, verb: verb, args: args, confirm: confirm })
+        end
+        true
+      end
+
+      # @return [Hash] `status` ("idle", "running", "done", "failed", "cancelled" or
+      #   "timed_out"), `verb`, `started_at` and `finished_at` (ISO 8601 or nil), `ok` (nil until
+      #   the job settles) and `output` (the last {OUTPUT_LIMIT} characters)
+      def state
+        @mutex.synchronize { @state.dup }
+      end
+
+      # Stops the running job's worker thread. A child process it spawned is not killed.
+      # @return [Boolean] true when a job was running
+      def cancel
+        @mutex.synchronize do
+          return false unless running?
+
+          @worker.kill
+          settle("cancelled", "")
+          true
+        end
+      end
+
+      private
+
+      # @api private
+      def blank
+        { status: "idle", verb: nil, started_at: nil, finished_at: nil, ok: nil, output: "" }
+      end
+
+      # @api private
+      def running? = @state[:status] == "running"
+
+      # @api private
+      def current?(generation) = generation == @generation && running?
+
+      # @api private
+      def stamp = Time.now.utc.iso8601(3)
+
+      # @api private
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      # Starts the worker and its watchdog; the caller holds the mutex.
+      # @api private
+      def launch(generation, call)
+        @worker = Thread.new { work(generation, call) }
+        Thread.new { watch(generation) }
+      end
+
+      # @api private
+      def work(generation, call)
+        result = @runner.call(**call)
+        conclude(generation, result[:ok] ? "done" : "failed", result[:output])
+      rescue StandardError => e
+        conclude(generation, "failed", e.message)
+      end
+
+      # @api private
+      def conclude(generation, status, output)
+        @mutex.synchronize { settle(status, output) if current?(generation) }
+      end
+
+      # Ends the job when it outlives the timeout; wakes early when the job settles first.
+      # @api private
+      def watch(generation)
+        deadline = now + @timeout
+        @mutex.synchronize do
+          @settled.wait(@mutex, deadline - now) while current?(generation) && now < deadline
+          expire(generation)
+        end
+      end
+
+      # @api private
+      def expire(generation)
+        return unless current?(generation)
+
+        @worker.kill
+        settle("timed_out", "timed out after #{@timeout} seconds")
+      end
+
+      # Records how the job ended; the caller holds the mutex.
+      # @api private
+      def settle(status, output)
+        text = output.to_s
+        text = text[-OUTPUT_LIMIT..] if text.length > OUTPUT_LIMIT
+        @state = @state.merge(status: status, finished_at: stamp, ok: status == "done", output: text)
+        @settled.broadcast
+      end
+    end
+  end
+end

data/lib/hecks/composer/layout.rb

@@ -0,0 +1,37 @@
+module Hecks
+  module Composer
+    # Proposes which panels the editor shows beside the text, on the hecksagon side like the
+    # other composer files. It is a small rule set, not a model call: the same inputs always give
+    # the same answer, and it reads only the author's intent and the check's verdict.
+    module Layout
+      module_function
+
+      # @param intent [String] "edit", "wire", "question" or "new_domain"
+      # @param check [Hash] the result of {Check.call}
+      # @param changed [Hash] the files the last request changed, by path
+      # @return [Hash] `right` (one of the panel names) and `bottom` (always "agent")
+      def propose(intent:, check:, changed:)
+        { right: right(intent, check, changed), bottom: "agent" }
+      end
+
+      # A refusal or an error finding comes first; then the author's intent decides.
+      # @api private
+      def right(intent, check, _changed)
+        return "findings" if refused?(check)
+
+        case intent
+        when "wire" then "wiring"
+        when "question" then "statements"
+        else "diagram"
+        end
+      end
+
+      # @api private
+      def refused?(check)
+        return true if check[:diagnostic]
+
+        Array(check[:findings]).any? { |finding| finding[:severity].to_s == "error" }
+      end
+    end
+  end
+end

data/lib/hecks/composer/live.rb

@@ -0,0 +1,150 @@
+require "fileutils"
+require "hecks"
+require_relative "parse"
+require_relative "plain"
+require_relative "workspace"
+
+module Hecks
+  module Composer
+    # A workspace domain booted once and kept, so the Console and Records panels can dispatch
+    # commands against it and read back what it holds. It sits on the driving side of the
+    # 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
+
+      # Stages the workspace and boots it in memory.
+      #
+      # @param dir [String] the workspace directory
+      # @param buffers [Hash{String => String}] unsaved text by path relative to `dir`
+      # @return [Live] a booted workspace
+      # @raise [StandardError, ScriptError] whatever the parse or the boot refused with (a
+      #   bluebook that is not valid Ruby raises a SyntaxError); the stage is removed
+      def self.open(dir:, buffers: {})
+        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)
+        rescue StandardError, ScriptError
+          FileUtils.rm_rf(stage)
+          raise
+        end
+      end
+
+      # @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:)
+        @stage = stage
+        @runtime = runtime
+        @chapter_name = chapter_name
+      end
+
+      # The aggregate commands the chapter 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)
+      def commands
+        aggregates.flat_map do |aggregate|
+          aggregate.commands.map { |command| describe(aggregate, command) }
+        end
+      end
+
+      # Runs one command against the booted domain.
+      #
+      # @param verb [String] the dispatcher's form, such as "Ledger::Account.Credit"
+      # @param to [String, nil] the identity of the record the command addresses
+      # @param with [Hash] the command's facts by argument name; keys may be strings
+      # @return [Hash] `{ok: true, events:, instance:}` with the event names and the plain row, or
+      #   `{ok: false, kind:, error:}` with the refusal's class name and first message line
+      def dispatch(verb:, to: nil, with: {})
+        accepted(@runtime.dispatch(verb, to: to, with: symbolize(with)))
+      rescue StandardError => e
+        refused(e)
+      end
+
+      # @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
+          [aggregate.hecks_name, Plain.call(rows.to_a)]
+        end
+      end
+
+      # @param limit [Integer] how many of the latest events to return
+      # @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) }
+      end
+
+      # Removes the staged copy of the workspace. Calling it again does nothing.
+      #
+      # @return [void]
+      def close
+        FileUtils.rm_rf(@stage)
+      end
+
+      # @api private
+      def aggregates = @runtime.registry.bluebook(@chapter_name).aggregates
+
+      # @api private
+      def accepted(result)
+        { ok: true, events: result.events.map { |event| event.to_h[:name] },
+          instance: Plain.call(result.instance) }
+      end
+
+      # @api private
+      def refused(error)
+        { ok: false, kind: error.class.name.to_s.split("::").last,
+          error: error.message.lines.first.to_s.chomp }
+      end
+
+      # @api private
+      def describe(aggregate, command)
+        args = arguments(command)
+        { verb: "#{@chapter_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
+
+      # @api private
+      def template(aggregate, args)
+        args.to_h { |arg| [arg[:name], starter(aggregate, arg[:type])] }
+      end
+
+      # @api private
+      def arguments(command)
+        command.attributes.map do |attr|
+          { name: attr.name.to_s, type: attr.type.to_s, optional: attr.optional? }
+        end
+      end
+
+      # A value object of the aggregate gets a Hash of its attributes' defaults; any other type, "".
+      # @api private
+      def starter(aggregate, type)
+        shape = aggregate.value_object(type)
+        return "" unless shape
+
+        shape.attributes.to_h { |attr| [attr.name.to_s, default_for(attr)] }
+      end
+
+      # @api private
+      def default_for(attr)
+        return attr.default unless attr.default.nil?
+
+        attr.type.to_s == "Integer" ? 0 : ""
+      end
+
+      # @api private
+      def symbolize(item)
+        case item
+        when Hash then item.to_h { |key, inner| [key.to_sym, symbolize(inner)] }
+        when Array then item.map { |inner| symbolize(inner) }
+        else item
+        end
+      end
+    end
+  end
+end

data/lib/hecks/composer/outline.rb

@@ -0,0 +1,48 @@
+module Hecks
+  module Composer
+    # Where each named thing in a workspace is declared, read from the text alone so it works on a
+    # draft that does not parse: the editor jumps to a definition and shows a line's `goal` or
+    # `description` on hover from it.
+    module Outline
+      # The constructs that name something a reader may want to jump to.
+      KINDS = %w[aggregate entity value_object command query policy process_manager].freeze
+
+      DECLARATION = /\A\s*(#{KINDS.join("|")})\s+"([^"]+)"/
+      SUMMARY = /\A\s*(?:goal|description)\s+"((?:[^"\\]|\\.)*)"/
+
+      # How many lines below a declaration its `goal` or `description` may sit.
+      REACH = 6
+
+      module_function
+
+      # @param stage [String] a staged directory (see {Workspace.stage})
+      # @param files [Array<String>] the staged files, relative to `stage`
+      # @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|
+          entries(file, File.readlines(File.join(stage, file), chomp: true))
+        end
+      end
+
+      # @api private
+      def entries(file, lines)
+        lines.each_with_index.filter_map do |text, index|
+          found = text.match(DECLARATION) or next
+          { file: file, line: index + 1, kind: found[1], name: found[2], summary: summary(lines, index) }
+        end
+      end
+
+      # @api private
+      def summary(lines, index)
+        lines[(index + 1)..(index + REACH)].to_a.each do |text|
+          break if text.match?(DECLARATION)
+
+          found = text.match(SUMMARY)
+          return found[1].gsub('\"', '"') if found
+        end
+        nil
+      end
+    end
+  end
+end