hecks 3.13.0 → 4.0.0

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

@@ -0,0 +1,84 @@
+require_relative "../board"
+require_relative "../outline"
+require_relative "../workspace"
+
+module Hecks
+  module Composer
+    module BoardEdit
+      # The bluebook text of a staged workspace as lines, with what a board edit needs to change
+      # 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
+        # @return [Board::Places] where each aggregate, command and policy is declared
+        attr_reader :places
+
+        # @param stage [String] a staged directory (see {Workspace.stage})
+        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)] }
+        end
+
+        # @param at [Hash] `{file:, line:}` of a declaration
+        # @return [Integer] the 0-based index of the `end` that closes it
+        # @raise [Refused] if the block has no closing `end` at its own indentation
+        def block_end(at)
+          lines = @lines.fetch(at[:file])
+          start = at[:line] - 1
+          pattern = /\A {#{indent_of(lines[start])}}end\b/
+          ((start + 1)...lines.size).find { |index| lines[index].match?(pattern) } or
+            raise Refused, "cannot find where the block at #{at[:file]}:#{at[:line]} ends"
+        end
+
+        # @param at [Hash] `{file:, line:}` of a declaration
+        # @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
+
+          { file: file, line: @lines[file].index { |line| line.match?(/\A\s*Hecks\.bluebook\s+"/) } + 1 }
+        end
+
+        # @param file [String] a bluebook path
+        # @param from [Integer] first 0-based line to read
+        # @param upto [Integer] last 0-based line to read
+        # @return [Array<String>] those lines
+        def slice(file, from, upto) = @lines.fetch(file)[from..upto]
+
+        # Puts new lines before a line of a file, with a blank line above them unless one is there.
+        # @return [Hash] the patched file as `{path:, text:, line:}`
+        def insert(file, before, new_lines)
+          lines = @lines.fetch(file)
+          added = spaced(lines, before, new_lines)
+          lines.insert(before, *added)
+          patched(file, before + 1 + added.index { |line| !line.strip.empty? }.to_i)
+        end
+
+        # Takes lines out of a file, and the blank line above them when there is one.
+        # @return [Hash] the patched file as `{path:, text:, line:}`
+        def remove(file, from, upto)
+          lines = @lines.fetch(file)
+          from -= 1 if from.positive? && lines[from - 1].strip.empty?
+          lines.slice!(from..upto)
+          patched(file, nil)
+        end
+
+        private
+
+        def indent_of(line) = line[/\A */].size
+
+        # The new lines, without their leading blank line when one is already above the spot.
+        def spaced(lines, before, added)
+          added.first.to_s.empty? && lines[before - 1].to_s.strip.empty? ? added.drop(1) : added
+        end
+
+        def patched(file, line) = { path: file, text: "#{@lines.fetch(file).join("\n")}\n", line: line }
+      end
+    end
+  end
+end

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