hecks 3.9.1 → 3.11.0

data/lib/hecks/hecks/adapters/terminal.rb

@@ -6,7 +6,7 @@ require "hecks/cli/console"
 module Hecks
   module Adapters
     # The `Terminal` port's adapter: the sessions an operator or a program drives through stdin and
-    # stdout, an IRB console (`open`) or the stdio MCP door (`serve`).
+    # stdout, an IRB console (`open`) or the stdio MCP server (`serve`).
     #
     # The journal records that a session was opened and how it ended, not what was said in it.
     # Each starts here and nowhere else; a caller that must not open a real session (a spec)
@@ -43,26 +43,28 @@ module Hecks
         { output: { value: "console session ended (#{domain || "pizzas"})" } }
       end
 
-      # Hands the process over to the MCP door until the client closes stdin. The door writes its
+      # Hands the process over to the MCP server until the client closes stdin. The server writes
+      # its
       # JSON-RPC on stdout, so nothing here is captured, and the launcher's own answer follows
       # only once the client is gone.
       #
-      # @param held [Hash] the `Door` record: `stdio` (whether `--stdio` was given)
-      # @return [Hash{Symbol => Hash}] `output:` a one-line note that the door closed
-      # @raise [ConsoleCapture::Failure] when the process is not set up for stdio: the door
+      # @param held [Hash] the `Launch` record: `stdio` (whether `--stdio` was given)
+      # @return [Hash{Symbol => Hash}] `output:` a one-line note that the server closed
+      # @raise [ConsoleCapture::Failure] when the process is not set up for stdio: the server
       #   refused to start, and said why on stderr
       def serve(**held)
-        run_door(plain(held[:stdio]) ? ["--stdio"] : [])
+        run_server(plain(held[:stdio]) ? ["--stdio"] : [])
 
-        { output: { value: "mcp door closed" } }
+        { output: { value: "mcp server closed" } }
       rescue SystemExit => e
-        raise ConsoleCapture::Failure, "the mcp door refused to start (status #{e.status}); see stderr"
+        raise ConsoleCapture::Failure, "the mcp server refused to start (status #{e.status}); see stderr"
       end
 
       # Holds an interview at the terminal and writes the domain it drafts (ADR 0088). Asking is IO,
       # so it happens here and nowhere else; the journal records that one was held, not its words.
       #
-      # @param held [Hash] the `Door` record: `name`; optionally `adapter`, `dir`, `expert`, `no_ai`
+      # @param held [Hash] the `Launch` record: `name`; optionally `adapter`, `dir`, `expert`,
+      #   `no_ai`
       # @return [Hash{Symbol => Hash}] `output:` what the interview wrote, or that it wrote nothing
       # @raise [ConsoleCapture::Failure] when the name or adapter is refused, or a file is there
       def converse(**held)
@@ -76,8 +78,8 @@ module Hecks
 
       private
 
-      # Hands the process to the server a spec set, or else to the real MCP door.
-      def run_door(argv)
+      # Hands the process to the server a spec set, or else to the real MCP server.
+      def run_server(argv)
         server = self.class.server
         if server
           server.call(argv)

data/lib/hecks/hecks/adapters/world_clearing.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    # Empties the `deployed_to(...) do ... end` blocks of a `.world` file's text: the region,
+    # stacks, secrets, domain and buckets a host deploys with, which a project handed to a client
+    # must not carry. Each block keeps its opening and closing lines and holds one comment naming
+    # the settings it held, so the file still loads and shows what to set.
+    #
+    # A block closes at the first `end` at its own indent, and a setting is a line one indent
+    # step inside it that starts with its name. A block that holds only comments is already clear
+    # and is left as it is, so clearing twice changes nothing the second time.
+    class WorldClearing
+      BLOCK = /^(?<indent>[ \t]*)deployed_to\b[^\n]*[ \t]do\b[^\n]*\n(?<body>.*?)^\k<indent>end\b[^\n]*\n/m
+
+      # What clearing one world's text produced.
+      #
+      # @!attribute [r] text
+      #   @return [String] the text with every block emptied
+      # @!attribute [r] settings
+      #   @return [Array<String>] the setting names removed, in order, without repeats
+      Result = Struct.new(:text, :settings) do
+        # @return [Boolean] whether any block was emptied
+        def changed? = !settings.empty?
+      end
+
+      # @param text [String] the contents of a `.world` file
+      # @return [Result] the cleared text and the settings that were in the blocks
+      def self.call(text)
+        names = []
+        cleared = text.gsub(BLOCK) { |block| empty(Regexp.last_match, block, names) }
+        Result.new(cleared, names.uniq)
+      end
+
+      # @param match [MatchData] one `deployed_to` block
+      # @param block [String] the block's text
+      # @param names [Array<String>] collects the setting names removed
+      # @return [String] the block's replacement
+      def self.empty(match, block, names)
+        indent = match[:indent]
+        held = match[:body].scan(/^#{indent} {2}([a-z_]\w*)/).flatten
+        return block if held.empty?
+
+        names.concat(held)
+        "#{block.lines.first}#{comment(indent, note(held.uniq))}#{indent}end\n"
+      end
+
+      # @param held [Array<String>] the setting names the block held
+      # @return [String] the comment that stands where the settings were
+      def self.note(held)
+        "The host's deployment settings were removed from this handoff. Set your own: #{held.join(", ")}."
+      end
+
+      # @param indent [String] the block's indent
+      # @param note [String] the sentence to put in the block
+      # @return [String] the sentence as comment lines inside the block, folded under 100 columns
+      def self.comment(indent, note)
+        width = 96 - indent.size
+        note.scan(/(.{1,#{width}})(?:\s+|\z)/).flatten.map { |line| "#{indent}  # #{line}\n" }.join
+      end
+
+      private_class_method :empty, :note, :comment
+    end
+  end
+end

data/lib/hecks/hecks/codebase.behaviors

@@ -1,7 +1,7 @@
 Hecks.behaviors "Codebase" do
   vision "A request to work on this repository is recorded, the tree is examined, and only a hecks checkout lets it through."
 
-  loads "hecks.bluebook", "custodian.bluebook", "codebase.bluebook", "context_map.hecksagon", "hecks.hecksagon", "environments/memory.world"
+  loads "hecks.bluebook", "custodian.bluebook", "tooling.bluebook", "rehearsal.bluebook", "codebase.bluebook", "context_map.hecksagon", "hecks.hecksagon", "environments/memory.world"
 
   test "ProjectModel reports what the language projects, and keeps the answer" do
     tests "ProjectModel", on: "LanguageRun"
@@ -187,4 +187,16 @@ Hecks.behaviors "Codebase" do
     input run: { value: "" }
     expect refused: "must match"
   end
+
+  test "Flog refuses a list of paths that is not one" do
+    tests "Flog", on: "InspectionRun"
+    input paths: { value: "lib, spec" }, run: { value: "paths" }
+    expect refused: "must match"
+  end
+
+  test "Reek refuses a count that is not positive" do
+    tests "Reek", on: "InspectionRun"
+    input top: { value: 0 }, run: { value: "top" }
+    expect refused: "positive"
+  end
 end

data/lib/hecks/hecks/codebase.bluebook

@@ -98,6 +98,7 @@ Hecks.bluebook "Hecks" do
     end
 
     lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
       transition "Accept"   => "accepted",  from: "requested"
       transition "Complete" => "completed", from: "accepted"
       transition "Fault"    => "faulted",   from: %w[requested accepted]
@@ -658,6 +659,7 @@ Hecks.bluebook "Hecks" do
     end
 
     lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
       transition "Accept"   => "accepted",  from: "requested"
       transition "Complete" => "completed", from: "accepted"
       transition "Fault"    => "faulted",   from: %w[requested accepted]
@@ -812,6 +814,7 @@ Hecks.bluebook "Hecks" do
     end
 
     lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
       transition "Accept"   => "accepted",  from: "requested"
       transition "Complete" => "completed", from: "accepted"
       transition "Fault"    => "faulted",   from: %w[requested accepted]
@@ -991,6 +994,7 @@ Hecks.bluebook "Hecks" do
     end
 
     lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
       transition "Accept"   => "accepted",  from: "requested"
       transition "Complete" => "completed", from: "accepted"
       transition "Fault"    => "faulted",   from: %w[requested accepted]
@@ -1225,6 +1229,7 @@ Hecks.bluebook "Hecks" do
     end
 
     lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
       transition "Accept"   => "accepted",  from: "requested"
       transition "Complete" => "completed", from: "accepted"
       transition "Fault"    => "faulted",   from: %w[requested accepted]
@@ -1397,6 +1402,7 @@ Hecks.bluebook "Hecks" do
     end
 
     lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
       transition "Accept"   => "accepted",  from: "requested"
       transition "Complete" => "completed", from: "accepted"
       transition "Fault"    => "faulted",   from: %w[requested accepted]
@@ -1654,6 +1660,222 @@ Hecks.bluebook "Hecks" do
     trigger StyleRun::Fault, with: { refusal: :refusal }
   end
 
+  # Inspection: ranking the Ruby by complexity, finding copied code, listing design smells and
+  # writing the combined report. A read of the tree: nothing is rewritten. The files the style
+  # config excludes (generated output, vendored code) are left out of every tool.
+  aggregate "InspectionRun" do
+    description "One inspection of the Ruby by flog, flay, reek or rubycritic."
+
+    attribute :run,       RunKey
+    attribute :operation, Operation, optional: true
+    attribute :paths,     PathList, optional: true
+    attribute :top,       Top, optional: true
+    attribute :checkout,  Switch, optional: true
+    attribute :report,    Report, optional: true
+    attribute :refusal,   Report, optional: true
+    identified_by :run
+
+    value_object "RunKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a run is named") { !value.to_s.empty? }
+    end
+
+    value_object "Operation" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    # Files or directories, comma separated; lib when none is named.
+    value_object "PathList" do
+      attribute :value, String, pattern: '^[^ \t\n\r,]+(,[^ \t\n\r,]+)*$'
+    end
+
+    # How many lines of the report are kept.
+    value_object "Top" do
+      attribute :value, Integer
+
+      invariant("a count is positive") { value > 0 }
+    end
+
+    lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
+      transition "Accept"   => "accepted",  from: "requested"
+      transition "Complete" => "completed", from: "accepted"
+      transition "Fault"    => "faulted",   from: %w[requested accepted]
+    end
+
+    command "Flog" do
+      role "Maintainer"
+      goal "Rank the Ruby methods by complexity, worst first"
+
+      attribute :paths, PathList, optional: true
+      attribute :top,   Top, optional: true
+      attribute :run,   RunKey
+
+      sets :paths
+      sets :top
+      sets :run
+      sets :operation, to: "flog"
+
+      emits FlogRequested
+    end
+
+    command "Flay" do
+      role "Maintainer"
+      goal "Find Ruby code that is copied or nearly copied"
+
+      attribute :paths, PathList, optional: true
+      attribute :top,   Top, optional: true
+      attribute :run,   RunKey
+
+      sets :paths
+      sets :top
+      sets :run
+      sets :operation, to: "flay"
+
+      emits FlayRequested
+    end
+
+    command "Reek" do
+      role "Maintainer"
+      goal "List the design smells in the Ruby"
+
+      attribute :paths, PathList, optional: true
+      attribute :top,   Top, optional: true
+      attribute :run,   RunKey
+
+      sets :paths
+      sets :top
+      sets :run
+      sets :operation, to: "reek"
+
+      emits ReekRequested
+    end
+
+    command "Rubycritic" do
+      role "Maintainer"
+      goal "Write the combined quality report, with git churn"
+
+      attribute :paths, PathList, optional: true
+      attribute :top,   Top, optional: true
+      attribute :run,   RunKey
+
+      sets :paths
+      sets :top
+      sets :run
+      sets :operation, to: "rubycritic"
+
+      emits RubycriticRequested
+    end
+
+    # What the tree reported about itself, held against every request: nothing here runs
+    # outside a hecks checkout (hecks.gemspec beside lib/).
+    command "Accept" do
+      role "System"
+      goal "Let a request through only when the working tree is a hecks checkout"
+
+      reference_to InspectionRun
+      attribute :checkout, Switch
+
+      given("needs a hecks checkout: hecks.gemspec stands beside lib/") { checkout.value }
+
+      sets :checkout
+
+      emits InspectionAccepted
+    end
+
+    command "Complete" do
+      role "System"
+      goal "Record that the inspection was carried out, and what it reported"
+
+      reference_to InspectionRun
+      attribute :report, Report
+
+      sets :report
+
+      emits InspectionCompleted
+    end
+
+    command "Fault" do
+      role "System"
+      goal "Record that the inspection was refused or could not be carried out, and why"
+
+      reference_to InspectionRun
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits InspectionFaulted
+    end
+
+    query "InspectionOutcome" do
+      description "How one inspection ended: its status, and what it reported or why it failed."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "InspectionsFaulted" do
+      description "Every inspection that was refused or could not be carried out."
+      where(status: "faulted")
+      order_by :run
+    end
+  end
+
+  policy "ExamineWhenFlogRequested" do
+    on      "InspectionRun.FlogRequested"
+    trigger InspectionRun::SourceTree::Examine, with: { run: :run }
+  end
+
+  policy "ExamineWhenFlayRequested" do
+    on      "InspectionRun.FlayRequested"
+    trigger InspectionRun::SourceTree::Examine, with: { run: :run }
+  end
+
+  policy "ExamineWhenReekRequested" do
+    on      "InspectionRun.ReekRequested"
+    trigger InspectionRun::SourceTree::Examine, with: { run: :run }
+  end
+
+  policy "ExamineWhenRubycriticRequested" do
+    on      "InspectionRun.RubycriticRequested"
+    trigger InspectionRun::SourceTree::Examine, with: { run: :run }
+  end
+
+  policy "AcceptInspectionWhenExamined" do
+    on      "InspectionRun.InspectionExamined"
+    trigger InspectionRun::Accept, with: { checkout: :checkout }
+  end
+
+  policy "FaultInspectionWhenNotAccepted" do
+    on      "InspectionRun.InspectionExamined"
+    where   { !checkout.value }
+    trigger InspectionRun::Fault, with: { refusal: "needs a hecks checkout: hecks.gemspec stands beside lib/" }
+  end
+
+  policy "PerformInspectionWhenAccepted" do
+    on      "InspectionRun.InspectionAccepted"
+    trigger InspectionRun::SourceTree::Perform, with: { run: :run }
+  end
+
+  policy "RecordInspectionOutcome" do
+    on      "InspectionRun.InspectionAnswered"
+    trigger InspectionRun::Complete, with: { report: :report }
+  end
+
+  policy "RecordInspectionFault" do
+    on      "InspectionRun.InspectionRefused"
+    trigger InspectionRun::Fault, with: { refusal: :refusal }
+  end
+
   # Codemod: the mechanical rewrites of the example bluebooks. Each one edits tracked files, so
   # unconfirmed it rehearses the edit (the script reboots every bluebook and puts the files back)
   # and reports what it would change; the files stay changed only when it is confirmed.
@@ -1687,6 +1909,7 @@ Hecks.bluebook "Hecks" do
     end
 
     lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
       transition "Accept"   => "accepted",  from: "requested"
       transition "Complete" => "completed", from: "accepted"
       transition "Fault"    => "faulted",   from: %w[requested accepted]
@@ -1900,6 +2123,7 @@ Hecks.bluebook "Hecks" do
     end
 
     lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
       transition "Accept"   => "accepted",  from: "requested"
       transition "Complete" => "completed", from: "accepted"
       transition "Fault"    => "faulted",   from: %w[requested accepted]
@@ -2145,7 +2369,7 @@ Hecks.bluebook "Hecks" do
   # Corpus: what this repository's committed domains are, and what the language's own IR holds.
   # Every question about them is a pure read, answered by the SourceTree port: which domains carry
   # a Rust feature, the order they regenerate in, whether each generated module is covered, and the
-  # structural queries over the IR. Two commands open a long-running door: the query MCP server
+  # structural queries over the IR. Two commands open a long-running server: the query MCP server
   # on stdio and the forms app on a local port; each is recorded, runs until it is closed, and
   # answers when it ends.
   aggregate "CorpusRun" do
@@ -2211,6 +2435,7 @@ Hecks.bluebook "Hecks" do
     end
 
     lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
       transition "Accept"   => "accepted",  from: "requested"
       transition "Complete" => "completed", from: "accepted"
       transition "Fault"    => "faulted",   from: %w[requested accepted]
@@ -2395,6 +2620,7 @@ Hecks.bluebook "Hecks" do
     attribute :version,        Version, optional: true
     attribute :client_version, Version, optional: true
     attribute :changelog,      Switch, optional: true
+    attribute :approved,       Switch, optional: true
     attribute :tag_state,      Word, optional: true
     attribute :head,           Word, optional: true
     attribute :ir_version,     Version, optional: true
@@ -2439,6 +2665,7 @@ Hecks.bluebook "Hecks" do
     end
 
     lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
       transition "Accept"     => "accepted",  from: "requested"
       transition "AcceptGem"  => "accepted",  from: "requested"
       transition "Complete"   => "completed", from: "accepted"
@@ -2496,6 +2723,7 @@ Hecks.bluebook "Hecks" do
       attribute :version,        Version
       attribute :client_version, Version
       attribute :changelog,      Switch
+      attribute :approved,       Switch
       attribute :tag_state,      Word
       attribute :head,           Word
       attribute :ir_version,     Version
@@ -2511,6 +2739,9 @@ Hecks.bluebook "Hecks" do
         client_version.value == version.value
       end
       given("CHANGELOG.md has a heading for the version: add the release entry") { changelog.value }
+      given("the commit that set the version carries a Release-Approved-By line: the owner decides when a release happens") do
+        approved.value || tag_state.value == "at_release_commit"
+      end
       given("a tag for the version points at the release commit, not elsewhere") do
         tag_state.value != "elsewhere"
       end
@@ -2523,6 +2754,7 @@ Hecks.bluebook "Hecks" do
       sets :version
       sets :client_version
       sets :changelog
+      sets :approved
       sets :tag_state
       sets :head
       sets :ir_version
@@ -2617,8 +2849,8 @@ Hecks.bluebook "Hecks" do
     trigger PublishingRun::Accept, with: { checkout: :checkout, branch: :branch, release_lane: :release_lane,
                                            on_origin: :on_origin, clean: :clean, version: :version,
                                            client_version: :client_version,
-                                           changelog: :changelog, tag_state: :tag_state, head: :head,
-                                           ir_version: :ir_version, ships_from: :ships_from }
+                                           changelog: :changelog, approved: :approved, tag_state: :tag_state,
+                                           head: :head, ir_version: :ir_version, ships_from: :ships_from }
   end
 
   policy "AcceptTheGemWhenExamined" do
@@ -2634,9 +2866,10 @@ Hecks.bluebook "Hecks" do
     where do
       operation.value == "publish" &&
         (!checkout.value || branch.value != release_lane.value || !on_origin.value || !clean.value ||
-          client_version.value != version.value || !changelog.value || tag_state.value == "elsewhere")
+          client_version.value != version.value || !changelog.value || tag_state.value == "elsewhere" ||
+          (!approved.value && tag_state.value != "at_release_commit"))
     end
-    trigger PublishingRun::Fault, with: { refusal: "a release rule is not met: check the branch, tree, versions, CHANGELOG and tag" }
+    trigger PublishingRun::Fault, with: { refusal: "a release rule is not met: check the branch, tree, versions, CHANGELOG, tag and the Release-Approved-By line" }
   end
 
   policy "FaultTheGemWhenNotAccepted" do
@@ -2763,6 +2996,7 @@ Hecks.bluebook "Hecks" do
     end
 
     lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
       transition "Accept"   => "accepted",  from: "requested"
       transition "Observe"  => "observed",  from: "requested"
       transition "Complete" => "completed", from: %w[accepted observed]

data/lib/hecks/hecks/custodian.behaviors

@@ -1,7 +1,7 @@
 Hecks.behaviors "Custodian" do
   vision "A check and an operation are recorded as requested before anything outside is asked."
 
-  loads "hecks.bluebook", "custodian.bluebook", "codebase.bluebook", "context_map.hecksagon", "hecks.hecksagon", "environments/memory.world"
+  loads "hecks.bluebook", "custodian.bluebook", "tooling.bluebook", "rehearsal.bluebook", "codebase.bluebook", "context_map.hecksagon", "hecks.hecksagon", "environments/memory.world"
 
   test "ModelCheck records the request, runs the analysis and keeps a clean verdict" do
     tests "ModelCheck", on: "ModelCheckRun"
@@ -69,14 +69,14 @@ Hecks.behaviors "Custodian" do
     expect emits: %w[VendorRequested PinRefused VendoringRefused]
   end
 
-  test "ProjectCli keeps a domain it cannot boot as a stopped door, and writes nothing" do
-    tests "ProjectCli", on: "Door"
+  test "ProjectCli keeps a domain it cannot boot as a stopped launch, and writes nothing" do
+    tests "ProjectCli", on: "Launch"
     input run: { value: "launchers" }, domains: { value: "no/such/domain" }
-    expect emits: %w[LaunchersRequested DoorRefused DoorStopped]
+    expect emits: %w[LaunchersRequested LaunchRefused LaunchStopped]
   end
 
-  test "ServeMcp refuses a door that is not named" do
-    tests "ServeMcp", on: "Door"
+  test "ServeMcp refuses a launch that is not named" do
+    tests "ServeMcp", on: "Launch"
     input run: { value: "" }
     expect refused: "must match"
   end
@@ -188,4 +188,22 @@ Hecks.behaviors "Custodian" do
     input domain: { value: "examples/pizzas" }, run: { value: "host" }, target: { value: "arm64" }
     expect refused: "must match"
   end
+
+  test "Request refuses a rehearsal that is not named" do
+    tests "Request", on: "RehearsalRun"
+    input run: { value: "" }, domain: { value: "examples/pizzas" }
+    expect refused: "must match"
+  end
+
+  test "Request refuses a pin that is neither a release nor a commit" do
+    tests "Request", on: "RehearsalRun"
+    input run: { value: "rehearse" }, domain: { value: "examples/pizzas" }, pin: { value: "main" }
+    expect refused: "must match"
+  end
+
+  test "Request keeps a domain that is not there as a withheld rehearsal" do
+    tests "Request", on: "RehearsalRun"
+    input run: { value: "rehearse" }, domain: { value: "/tmp/hecks-behaviors-absent/shop" }
+    expect emits: %w[RehearsalRequested StoreSurveyed RehearsalWithheld]
+  end
 end