hecks 3.14.0 → 5.0.0

data/lib/hecks/composer/panels.rb

@@ -0,0 +1,142 @@
+require "digest"
+require "json"
+require_relative "live"
+require_relative "toolbox"
+require_relative "behavior_run"
+require_relative "board_edit"
+require_relative "jobs"
+
+module Hecks
+  module Composer
+    # What the editor's lower panels ask of the server, on the hecksagon side: the Console and
+    # Records panels (a booted copy of the workspace), the Behaviors panel, Hecks's own commands for
+    # the palette and Eras, and the one background job the Fuzz panel polls. Every method takes the
+    # request's JSON body as a Hash and answers a Hash, so the router stays a table.
+    #
+    # The booted copy is kept between requests and rebuilt when the files or unsaved text change, so
+    # the records a Console command made survive until the text does.
+    class Panels
+      # Replaced, in a command's argument values, by the workspace directory.
+      WORKSPACE_TOKEN = "$WORKSPACE".freeze
+
+      # @param workspace [String] the domain directory the editor opens
+      # @param session [Session] the editor's in-memory draft bookkeeping, which keeps the timeline
+      def initialize(workspace:, session:)
+        @workspace = workspace
+        @session = session
+        @lock = Mutex.new
+        at_exit { close }
+      end
+
+      # Removes the booted copy of the workspace, if one is held.
+      # @return [void]
+      def close
+        @live&.close
+        @live = @live_key = nil
+      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 } }
+
+      # @param body [Hash] `buffers`, `verb`, `to` and `with`
+      # @return [Hash] see {Live#dispatch}, or `error` when the text does not boot
+      def dispatch(body)
+        with_live(body) { |live| live.dispatch(verb: body.fetch("verb"), to: body["to"], with: body.fetch("with", {})) }
+      end
+
+      # @param body [Hash] `buffers`
+      # @return [Hash] `records` by aggregate and `history` of events, or `error`
+      def records(body) = with_live(body) { |live| { records: live.records, history: live.history } }
+
+      # @param body [Hash] `buffers`
+      # @return [Hash] see {BehaviorRun.call}
+      def behaviors(body) = BehaviorRun.call(dir: @workspace, buffers: body.fetch("buffers", {}))
+
+      # Carries out one board action on the workspace as it is on screen.
+      #
+      # @param body [Hash] `buffers`, `op` (see {BoardEdit::OPERATIONS}) and `args`
+      # @return [Hash] the patched file as `path`, `text` and `line`, or `error` when the action
+      #   is refused
+      def board_edit(body)
+        Workspace.stage(dir: @workspace, buffers: body.fetch("buffers", {})) do |stage|
+          BoardEdit.call(stage: stage, action: body.fetch("op"), args: body.fetch("args", {}))
+        end
+      rescue BoardEdit::Refused => e
+        { error: e.message }
+      end
+
+      # @param body [Hash] `path`
+      # @return [Hash] `revisions`, newest first (see {Session#timeline})
+      def timeline(body) = { revisions: @session.timeline(body.fetch("path")) }
+
+      # @param _body [Hash] unused
+      # @return [Hash] `catalog` of Hecks's commands and queries (see {Toolbox#catalog})
+      def catalog(_body) = { catalog: toolbox.catalog }
+
+      # @param body [Hash] `kind` and `verb`
+      # @return [Hash] `help` text
+      def help(body) = { help: toolbox.help(kind: body.fetch("kind"), verb: body.fetch("verb")) }
+
+      # @param body [Hash] `kind`, `verb`, `args` and `confirm`
+      # @return [Hash] see {Toolbox#run}
+      def run(body) = toolbox.run(**request_of(body))
+
+      # @param _body [Hash] unused
+      # @return [Hash] the era queries over the workspace (see {Toolbox#eras})
+      def eras(_body) = toolbox.eras(@workspace)
+
+      # Starts the background job, unless one is running.
+      #
+      # @param body [Hash] `kind`, `verb`, `args` and `confirm`
+      # @return [Hash] `started`, and `error` when a job was already running
+      def start_job(body)
+        jobs.start(**request_of(body))
+        { started: true }
+      rescue Jobs::Busy => e
+        { started: false, error: e.message }
+      end
+
+      # @param _body [Hash] unused
+      # @return [Hash] the job's state (see {Jobs#state})
+      def job_state(_body) = jobs.state
+
+      # @param _body [Hash] unused
+      # @return [Hash] `cancelled`, whether a job was running
+      def cancel_job(_body) = { cancelled: jobs.cancel }
+
+      private
+
+      def with_live(body)
+        @lock.synchronize { yield live_for(body.fetch("buffers", {})) }
+      rescue StandardError, ScriptError => e
+        { error: e.message.lines.first.to_s.chomp }
+      end
+
+      def live_for(buffers)
+        key = digest(buffers)
+        return @live if @live && key == @live_key
+
+        close
+        @live = Live.open(dir: @workspace, buffers: buffers)
+        @live_key = key
+        @live
+      end
+
+      def digest(buffers)
+        disk = Workspace.files(@workspace).to_h { |path| [path, File.read(File.join(@workspace, path))] }
+        Digest::SHA256.hexdigest(JSON.generate([disk.sort, buffers.sort]))
+      end
+
+      def request_of(body)
+        args = body.fetch("args", {}).transform_values { |value| value.to_s.gsub(WORKSPACE_TOKEN, @workspace) }
+        { kind: body.fetch("kind"), verb: body.fetch("verb"), args: args, confirm: body["confirm"] }
+      end
+
+      def toolbox = @toolbox ||= Toolbox.new
+
+      # A second toolbox, so a long job does not hold up the palette.
+      def jobs = @jobs ||= Jobs.new(runner: ->(**request) { Toolbox.new.run(**request) })
+    end
+  end
+end

data/lib/hecks/composer/parse.rb

@@ -0,0 +1,83 @@
+require "open3"
+
+module Hecks
+  module Composer
+    # The fast stage of a check: the Rust parser's verdict on the staged bluebooks, which it gives
+    # in milliseconds, before anything is loaded. It reports the first refusal only, with the
+    # words that would have been accepted there.
+    module Parse
+      # The repository root, where the parser's build lands under `rust/parser/target/`.
+      ROOT = File.expand_path("../../..", __dir__).freeze
+
+      # Raised when no `hecks-parse` binary can be found.
+      class ParserMissing < StandardError; end
+
+      module_function
+
+      # Parses every bluebook in a staged workspace, one chapter 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)
+          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
+      #   header names
+      def bluebooks(stage)
+        Workspace.files(stage).grep(/\.bluebook\z/).group_by { |relative| chapter_name(File.join(stage, relative)) }
+                 .reject { |name, _| name.nil? }
+      end
+
+      # @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
+
+      # @api private
+      def refusal_for(stage, chapter, files)
+        paths = files.map { |relative| File.join(stage, relative) }
+        _out, err, status = Open3.capture3(binary, "chapter", "--chapter", chapter, *paths)
+        return nil if status.success?
+
+        diagnostic(err.lines.first.to_s.chomp, stage)
+      end
+
+      # Reads `<file>:<line>: <message>` 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 }
+      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`"
+      end
+    end
+  end
+end

data/lib/hecks/composer/plain.rb

@@ -0,0 +1,28 @@
+module Hecks
+  module Composer
+    # Reduces what a booted domain hands back (records, events, value objects) to plain Hashes,
+    # Arrays and scalars, so the page can show it as JSON.
+    module Plain
+      module_function
+
+      # @param item [Object] a value object, record, event, or a Hash or Array of them
+      # @return [Object] the same, with every value object replaced by its bare value: one of a
+      #   single field is that field's value, and one of several is a Hash of them
+      def call(item)
+        case item
+        when Runtime::Value then bare(item)
+        when Runtime::Instance, Runtime::Event then call(item.to_h)
+        when Hash then item.transform_values { |inner| call(inner) }
+        when Array then item.map { |inner| call(inner) }
+        else item
+        end
+      end
+
+      # @api private
+      def bare(value)
+        fields = call(value.to_h)
+        fields.size == 1 ? fields.values.first : fields
+      end
+    end
+  end
+end

data/lib/hecks/composer/ports/composer_agent.port

@@ -0,0 +1,7 @@
+Hecks.port "composer_agent" do
+  verb    "asked_by"
+  signal  :reply
+  answers :draft
+  answers :wire
+  answers :classify
+end

data/lib/hecks/composer/session.rb

@@ -0,0 +1,141 @@
+require "hecks"
+require_relative "../adapters/driving/admission"
+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
+    # 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
+      VERB = "Composer::Draft".freeze
+
+      # @return [Runtime::Dispatcher] the booted Composer chapter
+      attr_reader :runtime
+
+      # Boots the Composer chapter, 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")
+        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.
+      #
+      # @param slug [String] the draft's name
+      # @param chapter_name [String] the chapter's name
+      # @param text [String] the text it starts from
+      # @return [void]
+      def open(slug:, chapter_name:, text:)
+        return if draft(slug)
+
+        dispatch("Begin", slug: wrap(slug), chapter_name: wrap(chapter_name), text: wrap(text))
+      end
+
+      # Records the text now on screen.
+      # @param slug [String] the draft's name
+      # @param text [String] the text
+      # @return [void]
+      def revise(slug:, text:)
+        dispatch("Revise", to: slug, text: wrap(text))
+      end
+
+      # Keeps the text of one workspace file, one draft per file with the path as its slug: the
+      # first record of a path begins its draft, later ones revise it.
+      #
+      # @param path [String] the file's path relative to the workspace
+      # @param text [String] the text now on screen
+      # @return [void]
+      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)
+      end
+
+      # The text a file has held, from the chapter'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
+      #   when the path was never recorded (`text` is nil for an event that carries none)
+      def timeline(path)
+        @runtime.events.filter_map { |event| revision(event.to_h, path) }.reverse
+      end
+
+      # Records a check's verdict: accepted when it found no refusal, rejected with its words
+      # when it did.
+      #
+      # @param slug [String] the draft's name
+      # @param diagnostic [Hash, nil] the check's refusal, or nil
+      # @return [void]
+      def judge(slug:, diagnostic:)
+        return dispatch("Accept", to: slug, note: wrap("ok")) unless diagnostic
+
+        where = diagnostic[:line] ? "#{diagnostic[:file]}:#{diagnostic[:line]} " : ""
+        dispatch("Reject", to: slug, note: wrap(where + diagnostic[:message].to_s))
+      end
+
+      # Puts the author's request into the draft's conversation.
+      # @param slug [String] the draft's name
+      # @param said [String] the request
+      # @return [void]
+      def ask(slug:, said:)
+        dispatch("Ask", to: slug, sequence: wrap(next_sequence(slug)), said: wrap(said))
+      end
+
+      # Puts the agent's reply into the draft's conversation, with the text it left behind.
+      #
+      # @param slug [String] the draft's name
+      # @param said [String] the reply
+      # @param text [String] the text the draft holds after the agent's edit
+      # @return [void]
+      def answer(slug:, said:, text:)
+        dispatch("Answer", to: slug, sequence: wrap(next_sequence(slug)), said: wrap(said), text: wrap(text))
+      end
+
+      # @param slug [String] the draft's name
+      # @return [Hash, nil] the draft as the chapter holds it, or nil when none is open
+      def draft(slug)
+        @runtime.registry.repository("Composer", aggregate).find(slug)&.then { |row| plain(row) }
+      rescue StandardError
+        nil
+      end
+
+      # The draft in plain terms, for the page.
+      #
+      # @param slug [String] the draft's name
+      # @return [Hash, nil] `status`, `note` and `turns` (`sequence`, `speaker`, `said`), or nil
+      def summary(slug)
+        held = draft(slug) or return nil
+        { status: held[:status], note: Plain.call(held[:note]), turns: Plain.call(Array(held[:turns])) }
+      end
+
+      private
+
+      # @api private
+      def chapter_name_in(text) = text[/Hecks\.\w+\s+"([A-Z][A-Za-z0-9]*)"/, 1] || "Workspace"
+
+      # @api private
+      def revision(event, path)
+        return unless event[:aggregate] == VERB && event[:id] == path
+
+        { name: event[:name], at: event[:occurred_at], text: Plain.call(event[:payload])&.dig(:text) }
+      end
+
+      def aggregate = @runtime.registry.bluebook("Composer").aggregate("Draft")
+
+      def dispatch(command, to: nil, **facts)
+        @runtime.dispatch("#{VERB}.#{command}", to: to, with: facts)
+      end
+
+      def wrap(value) = { value: value }
+
+      def next_sequence(slug) = @sequence[slug] += 1
+
+      def plain(row) = row.respond_to?(:to_h) ? row.to_h : row
+    end
+  end
+end

data/lib/hecks/composer/toolbox.rb

@@ -0,0 +1,166 @@
+require "hecks"
+require "hecks/composer/parse"
+
+module Hecks
+  module Composer
+    # Runs Hecks's own commands and queries in-process for a command palette and an Eras panel.
+    # It is on the hecksagon side like the other composer files: it boots the Hecks chapter once,
+    # on first use, and sends argv to the CLI runner one call at a time. A command that is not on
+    # the safe list is guarded: it runs only when the caller echoes back a confirmation phrase.
+    class Toolbox
+      SAFE_COMMANDS = %w[
+        model_check_run.model_check operation.run operation.run_behaviors operation.smoke_test
+        operation.refresh_projections fuzz_run.fuzz fuzz_run.bench build.check_conformance
+        build.fuzz_conformance conformance_run.check_engine_agreement
+        conformance_run.measure_doc_coverage kernel_run.measure_kernel_coverage
+        style_run.check_comments style_run.check_rust_comments style_run.check_comments_unchanged
+      ].freeze
+
+      ERA_QUERIES = {
+        shape: "introspection.shape", scaffold_translation: "era.scaffold_translation",
+        audit_translation: "era.audit_translation", compaction: "era.compaction"
+      }.freeze
+
+      # @return [Toolbox] a toolbox that boots the Hecks chapter on first use
+      def initialize
+        @lock = Mutex.new
+        @runtime = nil
+      end
+
+      # Everything the palette can offer, commands and queries together.
+      #
+      # @return [Array<Hash>] `{kind:, verb:, goal:, guarded:}` sorted by verb, without the
+      #   commands whose role is System
+      def catalog
+        (rows("command", commands, :goal) + rows("query", queries, :description))
+          .sort_by { |row| [row[:verb], row[:kind]] }
+      end
+
+      # The runner's own help text for one verb.
+      #
+      # @param kind [String] "command" or "query"
+      # @param verb [String] a qualified verb such as `model_check_run.model_check`
+      # @return [String] the help text
+      def help(kind:, verb:)
+        invoke(argv_for(kind, verb, [], help: true)).first
+      end
+
+      # Runs one command or query and says what it printed.
+      #
+      # @param kind [String] "command" or "query"
+      # @param verb [String] a qualified verb
+      # @param args [Hash{String => #to_s}] argument names and values, such as `domain.value`
+      # @param confirm [String, nil] the phrase `RUN <verb>` that a guarded command requires
+      # @return [Hash] `ok`, `status`, `output` and, when nothing ran or the run failed, `error`
+      def run(kind:, verb:, args: {}, confirm: nil)
+        refusal = refusal_for(kind, verb, args, confirm)
+        return refusal if refusal
+
+        output, status = invoke(argv_for(kind, verb, pairs(args)))
+        { ok: status.zero?, status: status, output: output }
+      end
+
+      # The four era readings of a workspace.
+      #
+      # @param dir [String] the workspace directory
+      # @return [Hash{Symbol => Hash}] `shape`, `scaffold_translation`, `audit_translation` and
+      #   `compaction`, each a {#run} result
+      def eras(dir)
+        ERA_QUERIES.transform_values { |verb| run(kind: "query", verb: verb, args: { "domain.value" => dir }) }
+      end
+
+      private
+
+      # @api private
+      def rows(kind, items, reader)
+        items.map { |verb, item| entry(kind, verb, item.public_send(reader)) }
+      end
+
+      # @api private
+      def entry(kind, verb, goal)
+        guarded = kind == "command" && !SAFE_COMMANDS.include?(verb)
+        { kind: kind, verb: verb, goal: goal.to_s, guarded: guarded }
+      end
+
+      # @api private
+      def refusal_for(kind, verb, args, confirm)
+        return failure(2, "unknown kind #{kind.inspect}") unless %w[command query].include?(kind)
+        return failure(2, "unknown #{kind} #{verb.inspect}") unless known(kind).key?(verb.to_s)
+        return failure(2, "arguments may not contain a newline") if newline?(args)
+        return unless kind == "command" && !SAFE_COMMANDS.include?(verb) && confirm != "RUN #{verb}"
+
+        failure(2, "#{verb} is guarded: confirm with \"RUN #{verb}\"")
+      end
+
+      # @api private
+      def failure(status, message)
+        { ok: false, status: status, output: "", error: message }
+      end
+
+      # @api private
+      def newline?(args)
+        args.any? { |name, value| [name, value].any? { |text| text.to_s.match?(/[\r\n]/) } }
+      end
+
+      # @api private
+      def pairs(args)
+        args.map { |name, value| "#{name}=#{value}" }
+      end
+
+      # @api private
+      def argv_for(kind, verb, pairs, help: false)
+        tail = help ? ["--help"] : pairs
+        return ["query", verb, *tail] if kind == "query"
+
+        [verb, *tail, *(help ? [] : ["--wait"])]
+      end
+
+      # @api private
+      def known(kind)
+        kind == "query" ? queries : commands
+      end
+
+      # @api private
+      def commands
+        @commands ||= verbs(:commands).reject { |_verb, command| command.role.to_s == "System" }
+      end
+
+      # @api private
+      def queries
+        @queries ||= verbs(:queries)
+      end
+
+      # @api private
+      def verbs(member)
+        chapter.aggregates.flat_map do |aggregate|
+          aggregate.public_send(member).map do |item|
+            ["#{Naming.snake(aggregate.hecks_name)}.#{Naming.snake(item.hecks_name)}", item]
+          end
+        end.to_h
+      end
+
+      # @api private
+      def chapter
+        runtime.registry.bluebook("Hecks")
+      end
+
+      # @api private
+      def runtime
+        @lock.synchronize { @runtime ||= boot }
+      end
+
+      # @api private
+      def boot
+        Hecks.boot(File.join(Parse::ROOT, "lib/hecks/hecks"), install_driving: false, environment: "memory")
+      end
+
+      # @api private
+      def invoke(argv)
+        rt = runtime
+        @lock.synchronize do
+          Hecks::Adapters::Driving::CliRunner.call(runtime: rt, program: "hecks", argv: argv)
+        end
+      end
+    end
+  end
+end