hecks 3.14.0 → 4.0.0

data/lib/hecks/composer/assistant.rb

@@ -0,0 +1,110 @@
+require_relative "agent"
+require_relative "check"
+require_relative "layout"
+require_relative "session"
+
+module Hecks
+  module Composer
+    # Carries one request from the author to the agent and back, on the hecksagon side: records it
+    # in the draft's conversation, has the prompt classified, asks the agent to change the
+    # workspace's files, judges what it left, asks once more when the check refused the result, and
+    # records the agent's reply and the verdict.
+    #
+    # The agent edits the workspace on disk, so the files it changes are read before and after to
+    # show the author what moved.
+    class Assistant
+      # How many times the agent may be asked about one request: the request, then a repair.
+      ROUNDS = 2
+
+      QUESTION_NOTE = "That reads as a question, so nothing was edited.".freeze
+
+      # @param workspace [String] the domain directory the agent edits
+      # @param agents [Runtime::Registry] a registry holding the `composer_agent` port and one
+      #   adapter
+      # @param session [Session] the editor's in-memory draft bookkeeping
+      def initialize(workspace:, agents:, session:)
+        @workspace = workspace
+        @agents = agents
+        @session = session
+      end
+
+      # @param prompt [String] what the author asked for
+      # @return [Hash] `intent`, `note` (the agent's one-line account), `rounds` (how many times it
+      #   was asked), `changed` (`{path => {before:, after:}}` for each file that differs), `check`
+      #   (the whole check on what is now on disk) and `layout` (the panels to open, see {Layout})
+      def ask(prompt)
+        slug = File.basename(@workspace)
+        before = snapshot
+        open_draft(slug, before)
+        @session.ask(slug: slug, said: prompt)
+        intent = classify(prompt)
+        note, rounds = edit(intent, prompt)
+        outcome(slug, intent, note, rounds, before)
+      end
+
+      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)
+      end
+
+      # The prompt's intent; a classifier that cannot answer leaves it an edit.
+      def classify(prompt)
+        Agent.classify(@agents, prompt: prompt)
+      rescue Agent::Unavailable
+        "edit"
+      end
+
+      def edit(intent, prompt)
+        return [QUESTION_NOTE, 0] if intent == "question"
+
+        note = ask_agent(intent, prompt)
+        refusal = Check.call(dir: @workspace)[:diagnostic]
+        return [note, 1] unless refusal
+
+        [ask_agent(intent, repair(prompt, refusal)), ROUNDS]
+      end
+
+      def ask_agent(intent, prompt)
+        return Agent.wire(@agents, prompt: prompt, dir: @workspace) if intent == "wire"
+
+        Agent.draft(@agents, prompt: prompt, dir: @workspace)
+      end
+
+      def repair(prompt, refusal)
+        where = refusal[:line] ? "#{refusal[:file]} line #{refusal[:line]}: " : ""
+        expected = refusal[:expected].to_a.empty? ? "" : " (expected one of: #{refusal[:expected].join(", ")})"
+        "#{prompt}\n\nYour last edit was refused by the check, so fix it: #{where}#{refusal[:message]}#{expected}"
+      end
+
+      def outcome(slug, intent, note, rounds, before)
+        after = snapshot
+        check = Check.call(dir: @workspace)
+        @session.answer(slug: slug, said: note, text: after.values.first.to_s)
+        @session.judge(slug: slug, diagnostic: check[:diagnostic])
+        moved = changed(before, after)
+        record(moved)
+        { intent: intent, note: note, rounds: rounds, changed: moved, check: check,
+          layout: Layout.propose(intent: intent, check: check, changed: moved) }
+      end
+
+      # Keeps each file the agent changed in the timeline, as a save would.
+      def record(moved)
+        moved.each { |path, text| @session.record(path: path, text: text[:after]) if text[:after] }
+      end
+
+      def changed(before, after)
+        (before.keys | after.keys).sort.each_with_object({}) do |path, moved|
+          next if before[path] == after[path]
+
+          moved[path] = { before: before[path], after: after[path] }
+        end
+      end
+
+      def snapshot
+        Workspace.files(@workspace).to_h { |path| [path, File.read(File.join(@workspace, path))] }
+      end
+    end
+  end
+end

data/lib/hecks/composer/behavior_run.rb

@@ -0,0 +1,53 @@
+require "hecks"
+require "hecks/behaviors"
+require_relative "workspace"
+
+module Hecks
+  module Composer
+    # Runs a workspace's `.behaviors` files as they stand on screen and reports each test as plain
+    # data. Like the other composer files it sits on the hecksagon side: it stages the text, calls
+    # the behaviors runner and changes nothing on disk.
+    module BehaviorRun
+      module_function
+
+      # @param dir [String] the workspace directory
+      # @param buffers [Hash{String => String}] unsaved text by path relative to `dir`
+      # @return [Hash] `files` (`{path:, parse_error:, runs: [{status:, description:, message:}]}`
+      #   per behaviors file, paths relative to the workspace, status "pass", "fail" or "error")
+      #   and `summary` (`total`, `passed`, `failed`, `errored` and `parse_errors` counts)
+      # @raise [Workspace::OutsideWorkspace] if a buffer's path leaves the workspace
+      def call(dir:, buffers: {})
+        Workspace.stage(dir: dir, buffers: buffers) do |stage|
+          files = Hecks::Behaviors.run_all(stage).files.map { |file| report(stage, file) }
+          { files: files, summary: tally(files) }
+        end
+      end
+
+      # @api private
+      def report(stage, file)
+        {
+          path:        file.path.to_s.delete_prefix("#{File.realpath(stage)}/").delete_prefix("#{stage}/"),
+          parse_error: file.parse_error,
+          runs:        file.runs.map { |run| run_hash(run) }
+        }
+      end
+
+      # @api private
+      def run_hash(run)
+        { status: run.status.to_s, description: run.description, message: run.message }
+      end
+
+      # @api private
+      def tally(files)
+        runs = files.flat_map { |file| file[:runs] }
+        {
+          total:        runs.size,
+          passed:       runs.count { |run| run[:status] == "pass" },
+          failed:       runs.count { |run| run[:status] == "fail" },
+          errored:      runs.count { |run| run[:status] == "error" },
+          parse_errors: files.count { |file| file[:parse_error] }
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,178 @@
+# The Composer chapter: 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
+# 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
+# Composer's hecksagon, so nothing here knows how either is done.
+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."
+
+    attribute :slug,         DraftSlug
+    attribute :chapter_name, ChapterName
+    attribute :text,         SourceText
+    attribute :note,         Note, optional: true
+    attribute :turns,        list_of(Turn)
+
+    identified_by :slug
+
+    value_object "DraftSlug" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      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
+    # check loads it under.
+    value_object "ChapterName" do
+      attribute :value, String, pattern: '[A-Z][A-Za-z0-9]*'
+
+      invariant("a chapter 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.
+    value_object "SourceText" do
+      attribute :value, String
+    end
+
+    # The check's last word on the draft, or the agent's one-line account of what it changed.
+    value_object "Note" do
+      attribute :value, String
+    end
+
+    value_object "TurnSequence" do
+      attribute :value, Integer
+
+      invariant("a turn sequence is positive") { value.positive? }
+    end
+
+    value_object "Speaker" do
+      attribute :value, String, one_of: ["author", "agent"]
+    end
+
+    value_object "Utterance" do
+      attribute :value, String
+
+      invariant("a turn says something") { !value.to_s.empty? }
+    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.
+    entity "Turn" do
+      description "One thing said in the conversation about the draft, by the author or by the agent."
+
+      attribute :sequence, TurnSequence
+
+      identified_by :sequence
+
+      attribute :speaker, Speaker
+      attribute :said,    Utterance
+    end
+
+    lifecycle :status, default: "drafting" do
+      transition "Accept" => "valid",    from: %w[drafting valid invalid]
+      transition "Reject" => "invalid",  from: %w[drafting valid invalid]
+      transition "Revise" => "drafting", from: %w[drafting valid invalid]
+    end
+
+    command "Begin" do
+      role "Author"
+      goal "Open a chapter for editing, with the text it starts from"
+
+      attribute :slug,         DraftSlug
+      attribute :chapter_name, ChapterName
+      attribute :text,         SourceText
+
+      sets :slug
+      sets :chapter_name
+      sets :text
+
+      emits "DraftBegun"
+    end
+
+    command "Revise" do
+      role "Author"
+      goal "Replace the draft's text with what is now on screen"
+
+      reference_to Draft
+      attribute :text, SourceText
+
+      sets :text
+
+      emits "DraftRevised"
+    end
+
+    command "Accept" do
+      role "System"
+      goal "Record that the draft's text passed its check"
+
+      reference_to Draft
+      attribute :note, Note
+
+      sets :note
+
+      emits "DraftAccepted"
+    end
+
+    command "Reject" do
+      role "System"
+      goal "Record that the draft's text failed its check, and why"
+
+      reference_to Draft
+      attribute :note, Note
+
+      sets :note
+
+      emits "DraftRejected"
+    end
+
+    command "Ask" do
+      role "Author"
+      goal "Put a request for the agent to the draft's conversation"
+
+      reference_to Draft
+      attribute :sequence, TurnSequence
+      attribute :said,     Utterance
+
+      sets :turns, append: { sequence: :sequence, speaker: { value: "author" }, said: :said }
+
+      emits "TurnAsked"
+    end
+
+    command "Answer" do
+      role "System"
+      goal "Record the agent's reply and the text it left the draft with"
+
+      reference_to Draft
+      attribute :sequence, TurnSequence
+      attribute :said,     Utterance
+      attribute :text,     SourceText
+
+      sets :text
+      sets :turns, append: { sequence: :sequence, speaker: { value: "agent" }, said: :said }
+
+      emits "TurnAnswered"
+    end
+
+    query "Drafting" do
+      description "Every draft still being edited."
+      where(status: "drafting")
+      order_by :slug
+    end
+
+    query "Valid" do
+      description "Every draft whose last check passed."
+      where(status: "valid")
+      order_by :slug
+    end
+
+    query "Invalid" do
+      description "Every draft whose last check failed."
+      where(status: "invalid")
+      order_by :slug
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# The Composer domain, bound so it boots standing alone (a fuzz or model_check boot of this
+# directory). Drafts are working state; the files on disk are the truth, so nothing here outlives
+# the process.
+Hecks.hecksagon "Composer" do
+  attaches "Governance"
+  persisted_by "Memory"
+  # The editor reaches this domain through Web, and every tool that boots a corpus domain (fuzz,
+  # model_check, the Composer's own Session) through Ruby; the launcher, the forms and MCP do not.
+  driven_by "Web"
+  driven_by "Ruby"
+end
+
+# The anti-corruption layer for Governance, which the chapter's roles are checked against.
+Hecks.hecksagon "Governance" do
+  persisted_by "Memory"
+end

data/lib/hecks/composer/board.rb

@@ -0,0 +1,65 @@
+module Hecks
+  module Composer
+    # The event-storming board of a chapter, 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
+    # board's own edits go through {BoardEdit}, which rewrites the text.
+    module Board
+      module_function
+
+      # @param chapter [Bluebook::Chapter] the booted chapter
+      # @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:)
+        places = Places.new(outline)
+        { aggregates: chapter.aggregates.map { |aggregate| aggregate_note(aggregate, places) },
+          policies:   chapter.policies.map { |policy| policy_note(policy, places) } }
+      end
+
+      # @api private
+      def aggregate_note(aggregate, places)
+        name = aggregate.hecks_name
+        { name: name, at: places.of("aggregate", name),
+          commands: aggregate.commands.map { |command| command_note(name, command, places) } }
+      end
+
+      # @api private
+      def command_note(owner, command, places)
+        name = command.hecks_name
+        { name: name, role: command.role, goal: command.goal, emits: Array(command.emits).map(&:to_s),
+          at: places.of("command", name, owner: owner) }
+      end
+
+      # @api private
+      def policy_note(policy, places)
+        { name: policy.name, on: policy.on_event, trigger: policy.trigger_command,
+          at: places.of("policy", policy.name) }
+      end
+
+      # Where each declaration sits in the text, found by kind and name, and for a command by the
+      # aggregate that holds it.
+      class Places
+        # @param outline [Array<Hash>] see {Outline}
+        def initialize(outline)
+          owner = nil
+          @entries = outline.map do |entry|
+            owner = entry[:name] if entry[:kind] == "aggregate"
+            entry.merge(owner: entry[:kind] == "command" ? owner : nil)
+          end
+        end
+
+        # @param kind [String] `aggregate`, `command` or `policy`
+        # @param name [String] the declared name
+        # @param owner [String, nil] the aggregate, for a command
+        # @return [Hash, nil] `{file:, line:}` of the first match, or nil when the text has none
+        def of(kind, name, owner: nil)
+          found = @entries.find { |e| e[:kind] == kind && e[:name] == name && e[:owner] == owner }
+          found && { file: found[:file], line: found[:line] }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+module Hecks
+  module Composer
+    module BoardEdit
+      # The text of a command the board adds. The first command of an aggregate creates it, setting
+      # 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
+        module_function
+
+        # @param block [Array<String>] the lines of the aggregate's block, after its declaration
+        # @param indent [Integer] how far the aggregate's declaration is indented
+        # @param aggregate [String] the aggregate's name
+        # @param name [String] the new command's name
+        # @param event [String] the event it emits, or an empty string for none
+        # @return [Array<String>] the command's lines, indented one step inside the aggregate
+        # @raise [Refused] if the aggregate's key cannot be read, for a command that must set it
+        def lines(block:, indent:, aggregate:, name:, event:)
+          pad = " " * (indent + 2)
+          body = acts_on_a_record?(block, indent) ? ["reference_to #{aggregate}"] : creates(block, aggregate)
+          inner = [%(goal "Describe #{name}."), *body, (event.empty? ? nil : "emits #{event}")].compact
+          ["", %(#{pad}command "#{name}" do), *inner.map { |line| "#{pad}  #{line}" }, "#{pad}end"]
+        end
+
+        # @api private
+        def acts_on_a_record?(block, indent) = block.any? { |line| line.match?(/\A {#{indent + 2}}command\s+"/) }
+
+        # 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
+          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
+
+          ["attribute :#{field}, #{type}", "sets :#{field}"]
+        end
+      end
+    end
+  end
+end

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