hecks 3.4.2 → 3.6.0

data/lib/hecks/hecks/hecks.hecksagon

@@ -364,6 +364,22 @@ Hecks.hecksagon "Hecks" do
     end
   end
 
+  # Promotion: the SourceTree adapter reads the lane's head and where each required check stands
+  # against the commit, and carries out the move only after Accept.
+  Hecks::PromotionRun.port "SourceTree" do
+    asks "Examine", to: PromotionRun do
+      attribute :run, RunKey
+      answers "PromotionExamined"
+      refuses "PromotionRefused"
+    end
+
+    asks "Perform", to: PromotionRun do
+      attribute :run, RunKey
+      answers "PromotionAnswered"
+      refuses "PromotionRefused"
+    end
+  end
+
   # Deploy, attached above: its bluebook loads without deploy.hecksagon, so the outside its
   # commands reach is named here as well. TenantProvisioning writes a tenant's overlay world;
   # DeployToolchain generates and checks a recipe and projects the OIDC manifests.
@@ -404,11 +420,68 @@ Hecks.hecksagon "Hecks" do
   Deploy::SmokeRun.port "DeployToolchain" do
     asks "Smoke", to: SmokeRun do
       attribute :run, RunKey
+      attribute :after, Origin, default: { value: "alone" }
       answers "SmokeAnswered"
       refuses "SmokeRefused"
     end
   end
 
+  Deploy::ServiceRoll.port "DeployToolchain" do
+    asks "RollService", to: ServiceRoll do
+      attribute :run, RunKey
+      answers "ServiceRollAnswered"
+      refuses "ServiceRollRefused"
+    end
+  end
+
+  Deploy::BoxRoll.port "DeployToolchain" do
+    asks "RollBox", to: BoxRoll do
+      attribute :run, RunKey
+      answers "BoxRollAnswered"
+      refuses "BoxRollRefused"
+    end
+  end
+
+  Deploy::DataCopy.port "DeployToolchain" do
+    asks "CopyData", to: DataCopy do
+      attribute :run, RunKey
+      answers "DataCopyAnswered"
+      refuses "DataCopyRefused"
+    end
+  end
+
+  Deploy::CopyVerification.port "DeployToolchain" do
+    asks "CompareCopy", to: CopyVerification do
+      attribute :run, RunKey
+      answers "CopyVerificationAnswered"
+      refuses "CopyVerificationRefused"
+    end
+  end
+
+  Deploy::BluebookDiff.port "DeployToolchain" do
+    asks "CompareBluebooks", to: BluebookDiff do
+      attribute :run, RunKey
+      answers "BluebookDiffAnswered"
+      refuses "BluebookDiffRefused"
+    end
+  end
+
+  Deploy::PreviewRun.port "DeployToolchain" do
+    asks "RunPreview", to: PreviewRun do
+      attribute :run, RunKey
+      answers "PreviewRunAnswered"
+      refuses "PreviewRunRefused"
+    end
+  end
+
+  Deploy::CompanionRoll.port "DeployToolchain" do
+    asks "RollCompanion", to: CompanionRoll do
+      attribute :run, RunKey
+      answers "CompanionRollAnswered"
+      refuses "CompanionRollRefused"
+    end
+  end
+
   Deploy::TemplateComparison.port "DeployToolchain" do
     asks "Compare", to: TemplateComparison do
       attribute :run, RunKey

data/lib/hecks/hecks/hecks.world

@@ -1,7 +1,7 @@
 # Where the Hecks domain keeps its journal: every command's events, one entry per aggregate.
 #
 # **PostgresEra** is the default, for real runs: a client's `hecks` and a maintainer's on main
-# or in the merge queue. The journal then survives the process, and `hecks stores` and
+# or stable. The journal then survives the process, and `hecks stores` and
 # `hecks history` read it back. `default_adapter` binds every aggregate of the chapter (and of
 # the attached Governance chapter, see governance.world) in one line, which is what lets the
 # environments/memory.world overlay swap the whole domain to Memory.
@@ -31,7 +31,10 @@
 # gem's `exe/hecks`), `streams` lists the questions `--stream` may tail (`Follow`), `memory_commands` names
 # the commands that launcher runs on the Memory environment unless `HECKS_ENVIRONMENT` is set (so
 # `hecks console` needs no database), and `legacy` names the commands it hands to `Hecks::CLI` in the
-# positional forms ADR 0066 shipped.
+# positional forms ADR 0066 shipped. `maintainer` names the aggregates only someone working on a hecks
+# checkout runs (Codebase, and releasing hecks itself): the help leaves them out anywhere else and
+# `--maintainer` lists them; `chapters` names the attached chapters the help points at, one line each
+# (`hecks deploy`), and `maintainer_chapters` the language's own, added inside a checkout.
 Hecks.world "Hecks" do
   realm "Hecks"
   default_adapter "PostgresEra"
@@ -40,13 +43,22 @@ Hecks.world "Hecks" do
                        failure_states: %w[flagged failed drifted unreachable refused faulted halted stopped
                                           abandoned red needs_fix],
                        settled: %w[package.vendor package.revendor package.release
-                                  operation.bootstrap_admin smoke_run.run],
+                                  operation.bootstrap_admin smoke_run.run
+                                  service_roll.run box_roll.run data_copy.restore
+                                  data_copy.verify bluebook_diff.run preview_run.name
+                                  preview_run.url preview_run.list preview_run.deploy
+                                  preview_run.destroy preview_run.login companion_roll.run],
                        names: { "mcp" => "door.serve_mcp", "console" => "operation.open_console", "init" => "door.init",
                                 "interview" => "door.interview", "package.check" => "registry.check",
                                 "package.digest" => "registry.digest",
                                 "package.release" => "registry.release" },
                        streams: %w[Follow],
                        executable: "exe/hecks",
+                       maintainer: %w[LanguageRun KernelRun ConformanceRun RegenerationRun GateRun StyleRun
+                                      CodemodRun TestSuiteRun CorpusRun PublishingRun PromotionRun Release
+                                      SyntaxBootCache],
+                       chapters: %w[Deploy Governance Tenancy Site Tickets QualityControl],
+                       maintainer_chapters: %w[Bluebook Hecksagon World Adapter Port Translation Expression],
                        memory_commands: %w[console init interview],
                        legacy: %w[run docs narrate ir stores model_check smoke_test
                                   project_diagrams project_cli mcp]

data/lib/hecks/kernel_capabilities/templates.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Hecks
+  module KernelCapabilities
+    # The Rust source of the two capability modules. Extended onto `KernelCapabilities`.
+    module Templates
+      # One capability module, with `%{...}` where its parts go.
+      RUST = <<~RUST
+        // GENERATED by hecks project_kernel_capabilities from %<doc_line>s.
+        // Do not hand-edit — re-run hecks project_kernel_capabilities instead.
+        //
+        %<header>s
+
+        %<mods>s
+
+        /// One variant per real %<kind>s the Ruby
+        /// grammar admits, in the order %<doc_line>s declares them. Every match
+        /// over this enum in the kernel (rust/src/kernel/expr.rs) is written
+        /// WITHOUT a wildcard `_ =>` arm — see expr.rs's own header for why:
+        /// a wildcard here would let a newly-admitted capability compile
+        /// silently into a router that never calls the new file this same
+        /// regeneration adds a `pub mod` line for above.
+        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+        pub enum %<enum_name>s {
+        %<variants>s
+        }
+
+        impl %<enum_name>s {
+            /// The `rust/src/kernel/%<directory>s/<name>.rs` file this
+            /// variant names — `hecks measure_kernel_coverage`'s own existence
+            /// check reads this, so the file-name spelling here is the ONE
+            /// place that ever needs to change if a name is renamed.
+            pub fn module_name(&self) -> &'static str {
+                match self {
+        %<arms>s
+                }
+            }
+
+            pub const ALL: &'static [%<enum_name>s] = &[%<all>s];
+        }
+      RUST
+
+      # @return [String] the whole `attribute_shapes/mod.rs`
+      def shapes_module
+        header = <<~HEADER.strip
+          // Ground truth: Hecks::Runtime::Value::Coercion::SHAPES
+          // (lib/hecks/runtime/value/coercion.rb) — the four branches
+          // `for_attribute` itself takes, read directly rather than
+          // re-derived here.
+        HEADER
+        render(header: header, enum_name: "AttributeShape", names: Hecks::Runtime::Value::Coercion::SHAPES,
+               doc_line: "Coercion::SHAPES")
+      end
+
+      # @return [String] the whole `expression_operators/mod.rs`
+      def operators_module
+        header = <<~HEADER.strip
+          // Ground truth: Hecks::Grammar.admitted_operators (lib/hecks/
+          // grammar.rb), the SAME live-booted call hecks project_expression_tables
+          // uses — grouped by the `category` field Evaluator::PROJECTION already
+          // partitions comparison operators by (evaluator.rb).
+        HEADER
+        render(header: header, enum_name: "OperatorCategory", names: operator_categories,
+               doc_line: "Grammar.admitted_operators's own `category` field")
+      end
+
+      # Renders one capability module: `pub mod` lines, the enum, and its `ALL`.
+      #
+      # @param header [String] the ground-truth comment
+      # @param enum_name [String] `AttributeShape` or `OperatorCategory`
+      # @param names [Array<String>] the capabilities, in declaration order
+      # @param doc_line [String] where the capabilities are declared
+      # @return [String] the Rust source
+      def render(header:, enum_name:, names:, doc_line:)
+        shapes = enum_name == "AttributeShape"
+        format(RUST, header: header, doc_line: doc_line, enum_name: enum_name,
+                     kind: shapes ? "attribute shape" : "expression-operator category",
+                     directory: shapes ? "attribute_shapes" : "expression_operators",
+                     mods: names.map { |name| "pub mod #{name};" }.join("\n"),
+                     variants: names.map { |name| "    #{pascal(name)}," }.join("\n"),
+                     arms: names.map { |name| "            #{enum_name}::#{pascal(name)} => #{name.to_s.inspect}," }.join("\n"),
+                     all: names.map { |name| "#{enum_name}::#{pascal(name)}" }.join(", "))
+      end
+
+      # @param name [String, Symbol] a snake_case capability name
+      # @return [String] the PascalCase Rust variant
+      def pascal(name)
+        name.to_s.split("_").map { |part| part[0].upcase + part[1..] }.join
+      end
+    end
+  end
+end

data/lib/hecks/kernel_capabilities.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "projection_files"
+require_relative "kernel_capabilities/templates"
 
 module Hecks
   # The capability enums the hand-written Rust kernel is matched against, and the check that every
@@ -24,6 +25,8 @@ module Hecks
     #   @return [String] where the capability is declared
     Row = Struct.new(:name, :path, :present, :source)
 
+    extend Templates
+
     module_function
 
     # Renders both capability modules without writing them.
@@ -71,16 +74,26 @@ module Hecks
     def coverage_report(root: ProjectionFiles::ROOT)
       rows = coverage(root: root)
       prefix = "#{root}/"
-      lines = rows.map do |row|
-        "#{row.present ? 'OK  ' : 'MISS'}  #{row.path.delete_prefix(prefix)}  (#{row.source}: #{row.name.inspect})"
-      end
+      lines = rows.map { |row| report_line(row, prefix) }.join("\n")
       missing = rows.reject(&:present)
-      return [lines.join("\n"), coverage_verdict(rows.size), true] if missing.empty?
+      return [lines, coverage_verdict(rows.size), true] if missing.empty?
+
+      [lines, missing_verdict(missing, prefix), false]
+    end
+
+    # @return [String] one capability's line: whether its file is there, where, and why it is wanted
+    def report_line(row, prefix)
+      "#{row.present ? "OK  " : "MISS"}  #{row.path.delete_prefix(prefix)}  (#{row.source}: #{row.name.inspect})"
+    end
 
+    # @param missing [Array<Row>] the capabilities with no file
+    # @param prefix [String] the checkout's root, with its trailing slash
+    # @return [String] the complaint naming each missing file
+    def missing_verdict(missing, prefix)
       gaps = missing.map { |row| "  #{row.path.delete_prefix(prefix)}" }
       head = "#{missing.size} capability file(s) missing — the grammar admits these but no " \
              "hand-written Rust interpretation exists for them yet:"
-      [lines.join("\n"), [head, *gaps].join("\n"), false]
+      [head, *gaps].join("\n")
     end
 
     # @param count [Integer] how many capabilities there are
@@ -91,12 +104,6 @@ module Hecks
         "at its conventional path."
     end
 
-    # @param name [String, Symbol] a snake_case capability name
-    # @return [String] the PascalCase Rust variant
-    def pascal(name)
-      name.to_s.split("_").map { |part| part[0].upcase + part[1..] }.join
-    end
-
     # `category` in first-appearance order over the admission ledger, never alphabetized, so a
     # re-run does not reshuffle variants.
     #
@@ -116,79 +123,5 @@ module Hecks
         Row.new(name, path, File.file?(path), source)
       end
     end
-
-    # @return [String] the whole `attribute_shapes/mod.rs`
-    def shapes_module
-      header = <<~HEADER.strip
-        // Ground truth: Hecks::Runtime::Value::Coercion::SHAPES
-        // (lib/hecks/runtime/value/coercion.rb) — the four branches
-        // `for_attribute` itself takes, read directly rather than
-        // re-derived here.
-      HEADER
-      render(header: header, enum_name: "AttributeShape", names: Hecks::Runtime::Value::Coercion::SHAPES,
-             doc_line: "Coercion::SHAPES")
-    end
-
-    # @return [String] the whole `expression_operators/mod.rs`
-    def operators_module
-      header = <<~HEADER.strip
-        // Ground truth: Hecks::Grammar.admitted_operators (lib/hecks/
-        // grammar.rb), the SAME live-booted call hecks project_expression_tables
-        // uses — grouped by the `category` field Evaluator::PROJECTION already
-        // partitions comparison operators by (evaluator.rb).
-      HEADER
-      render(header: header, enum_name: "OperatorCategory", names: operator_categories,
-             doc_line: "Grammar.admitted_operators's own `category` field")
-    end
-
-    # Renders one capability module: `pub mod` lines, the enum, and its `ALL`.
-    #
-    # @param header [String] the ground-truth comment
-    # @param enum_name [String] `AttributeShape` or `OperatorCategory`
-    # @param names [Array<String>] the capabilities, in declaration order
-    # @param doc_line [String] where the capabilities are declared
-    # @return [String] the Rust source
-    def render(header:, enum_name:, names:, doc_line:)
-      shapes   = enum_name == "AttributeShape"
-      variants = names.map { |name| "    #{pascal(name)}," }.join("\n")
-      mods     = names.map { |name| "pub mod #{name};" }.join("\n")
-      arms     = names.map { |name| "            #{enum_name}::#{pascal(name)} => #{name.to_s.inspect}," }.join("\n")
-      all      = names.map { |name| "#{enum_name}::#{pascal(name)}" }.join(", ")
-
-      <<~RUST
-        // GENERATED by hecks project_kernel_capabilities from #{doc_line}.
-        // Do not hand-edit — re-run hecks project_kernel_capabilities instead.
-        //
-        #{header}
-
-        #{mods}
-
-        /// One variant per real #{shapes ? 'attribute shape' : 'expression-operator category'} the Ruby
-        /// grammar admits, in the order #{doc_line} declares them. Every match
-        /// over this enum in the kernel (rust/src/kernel/expr.rs) is written
-        /// WITHOUT a wildcard `_ =>` arm — see expr.rs's own header for why:
-        /// a wildcard here would let a newly-admitted capability compile
-        /// silently into a router that never calls the new file this same
-        /// regeneration adds a `pub mod` line for above.
-        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
-        pub enum #{enum_name} {
-        #{variants}
-        }
-
-        impl #{enum_name} {
-            /// The `rust/src/kernel/#{shapes ? 'attribute_shapes' : 'expression_operators'}/<name>.rs` file this
-            /// variant names — `hecks measure_kernel_coverage`'s own existence
-            /// check reads this, so the file-name spelling here is the ONE
-            /// place that ever needs to change if a name is renamed.
-            pub fn module_name(&self) -> &'static str {
-                match self {
-        #{arms}
-                }
-            }
-
-            pub const ALL: &'static [#{enum_name}] = &[#{all}];
-        }
-      RUST
-    end
   end
 end

data/lib/hecks/language/bluebook/vocabulary.bluebook

@@ -622,7 +622,7 @@ Hecks.bluebook "Bluebook" do
       attribute :label,    String
 
       member name: "runtime_changed", workflow: "ci.yml", mode: "touches",
-             pattern: '^lib/hecks/runtime/', push: "skip",
+             pattern: '^lib/hecks/runtime/', push: "before_sha",
              label: "does this change touch lib/hecks/runtime/**?"
       member name: "postgres_io_relevant_changed", workflow: "ci-postgres-io-parallel.yml", mode: "skips_unless",
              pattern: '^(docs/|editors/|release/|deploy/|\.claude/|\.githooks/|rust/(parser|codegen|host|build|lsp|web|tests)/|\.rubocop\.yml$|\.rubocop_todo\.yml$|\.mcp\.json$|\.rspec-local\.example$|README\.md$|CHANGELOG\.md$|CONTRIBUTING\.md$|SECURITY\.md$|LICENSE$|\.gitignore$)',
@@ -630,6 +630,48 @@ Hecks.bluebook "Bluebook" do
              label: "does this change touch anything rspec_postgres_io_parallel covers?"
     end
 
+    # The checks a commit must have passed before a `Promotion` moves it onto a guarded lane. Each
+    # is the name of a job in .github/workflows that reports to a commit as a check run; a check
+    # that a path gate skipped reports `skipped`, which counts as passed. `hecks promote` reads
+    # these rows, and hecks project_lanes writes them into the ruleset of any lane that requires
+    # them, so the list lives here and nowhere else.
+    value_object "RequiredCheck" do
+      attribute :name, String
+
+      member name: "rspec"
+      member name: "checks"
+      member name: "rspec_postgres_io"
+      member name: "rspec_postgres_io_parallel"
+      member name: "rspec_rust_io"
+      member name: "rspec_rust_parser"
+      member name: "rspec_rust_codegen"
+      member name: "rspec_rust_host"
+      member name: "rspec_fuzzing"
+    end
+
+    # The branches a change travels along. `main` takes pushes with no gate; `stable` takes only
+    # what a `Promotion` moves onto it once every `CiGate` check is green on that commit.
+    # hecks project_lanes writes each row's ruleset into .github/rulesets/<name>.json, and
+    # `hecks promote` reads `follows` to know which lane a promotion fast-forwards.
+    #
+    # `guarded` says whether a ruleset restricts the branch. `pushers` says what it takes: `anyone`
+    # (any commit), or `green` (only a commit on which every `RequiredCheck` has already passed,
+    # which is how a promotion moves the lane). `feeds` is the tag that moves with the lane, or
+    # empty when none does; `follows` is the lane a promotion draws from, or empty. `alert_after`
+    # is the whole hours the lane may stand behind the lane it follows before `hecks
+    # promotion_run.watch` files a finding, or empty for a lane that is never late.
+    value_object "Lane" do
+      attribute :name,        String
+      attribute :guarded,     String
+      attribute :pushers,     String
+      attribute :feeds,       String
+      attribute :follows,     String
+      attribute :alert_after, String
+
+      member name: "main",   guarded: "no",  pushers: "anyone", feeds: "",     follows: "",     alert_after: ""
+      member name: "stable", guarded: "yes", pushers: "green",  feeds: "edge", follows: "main", alert_after: "4"
+    end
+
     # The dials of the hecks_qa loop: what each is called, the type of value it takes and what it
     # does. qa/settings.yml holds the values, which are edited and reviewed as a diff; this table
     # holds the rest, so the loader (`Hecks::Fuzzing::QaSettings`) checks the file against it and

data/lib/hecks/literal/item_splitter.rb

@@ -0,0 +1,50 @@
+module Hecks
+  module Literal
+    # Splits the text between a literal's outer braces or brackets on separator commas only:
+    # never one inside a quoted string or a nested brace or bracket.
+    class ItemSplitter
+      # @param body [String] the text between a literal's outer braces or brackets
+      def initialize(body)
+        @body = body
+        @items = []
+        @current = +""
+        @depth = 0
+        @quoting = false
+        @escaping = false
+      end
+
+      # @return [Array<String>] each item's raw text, stripped, with empty items dropped
+      def call
+        @body.each_char do |char|
+          @current << char
+          consume(char)
+        end
+        @items << @current
+        @items.map(&:strip).reject(&:empty?)
+      end
+
+      private
+
+      def consume(char)
+        return @escaping = false if @escaping
+        return @escaping = true if @quoting && char == "\\"
+        return @quoting = !@quoting if char == '"'
+
+        track_nesting(char) unless @quoting
+      end
+
+      # Follows brace and bracket depth, and separates at a comma outside any.
+      def track_nesting(char)
+        @depth += 1 if "{[".include?(char)
+        @depth -= 1 if "}]".include?(char)
+        separate if char == "," && @depth.zero?
+      end
+
+      def separate
+        @current.chop!
+        @items << @current
+        @current = +""
+      end
+    end
+  end
+end

data/lib/hecks/literal.rb

@@ -1,3 +1,5 @@
+require_relative "literal/item_splitter"
+
 module Hecks
   # A mutation source that reads the record's own state: `append: { knights: state(:knights) }`.
   # A bare Symbol in a mutation source names a command argument, so this is the only way to say it.
@@ -23,38 +25,51 @@ module Hecks
       when Symbol then ":#{value}"
       when String then quote(value)
       when StateRef, true, false, Integer, Float then value.to_s
-      when Hash   then "{#{value.map { |key, held| "#{key}: #{render(held)}" }.join(', ')}}"
-      when Array  then "[#{value.map { |held| render(held) }.join(', ')}]"
+      when Hash, Array then render_collection(value)
       else
         raise ArgumentError, "#{value.class} has no pinned literal spelling — teach Literal.render one " \
                              "rather than letting #to_s decide it"
       end
     end
 
+    # @param value [Hash, Array] a collection to render
+    # @return [String] `{key: value}` for a Hash, `[value, ...]` for an Array, each element rendered
+    def render_collection(value)
+      return "[#{value.map { |held| render(held) }.join(", ")}]" if value.is_a?(Array)
+
+      "{#{value.map { |key, held| "#{key}: #{render(held)}" }.join(", ")}}"
+    end
+
     # Parses a wire spelling back into a Ruby value; the exact inverse of `render`.
     # A bare word stays a String, since some fields are stored as plain text, never rendered.
     #
     # @param text [String, #to_s] wire spelling produced by `render`, or a bare word
     # @return [Object] nil, true, false, Integer, Float, Symbol, StateRef, String,
     #   Hash, or Array — or `text` itself, stripped, when it matches no known spelling
-    # rubocop:disable-next Metrics/CyclomaticComplexity
-    # rubocop:disable-next Metrics/PerceivedComplexity
     def read(text)
       raw = text.to_s.strip
       return nil if raw.empty? || raw == "nil"
-      return true if raw == "true"
-      return false if raw == "false"
-      return raw.to_i if raw.match?(/\A-?\d+\z/)
-      return raw.to_f if raw.match?(/\A-?\d+\.\d+\z/)
-      return raw[1..].to_sym if raw.start_with?(":")
-      return StateRef.new(raw[7..-2].to_sym) if raw.match?(/\Astate\(:[A-Za-z_][A-Za-z0-9_]*\)\z/)
-      return unquote(raw) if quoted?(raw)
-      return read_hash(raw) if raw.start_with?("{") && raw.end_with?("}")
-      return read_array(raw) if raw.start_with?("[") && raw.end_with?("]")
+      return KEYWORD_VALUES[raw] if KEYWORD_VALUES.key?(raw)
 
+      READERS.each { |matches, convert| return convert.call(raw) if matches.call(raw) }
       raw
     end
 
+    # The words that read as `true` and `false`.
+    KEYWORD_VALUES = { "true" => true, "false" => false }.freeze
+
+    # Each spelling `read` recognizes after the keywords, in the order it tries them: whether the
+    # text is that spelling, and how to turn it into its value.
+    READERS = [
+      [->(raw) { raw.match?(/\A-?\d+\z/) }, :to_i.to_proc],
+      [->(raw) { raw.match?(/\A-?\d+\.\d+\z/) }, :to_f.to_proc],
+      [->(raw) { raw.start_with?(":") }, ->(raw) { raw[1..].to_sym }],
+      [->(raw) { raw.match?(/\Astate\(:[A-Za-z_][A-Za-z0-9_]*\)\z/) }, ->(raw) { StateRef.new(raw[7..-2].to_sym) }],
+      [->(raw) { quoted?(raw) }, ->(raw) { unquote(raw) }],
+      [->(raw) { raw.start_with?("{") && raw.end_with?("}") }, ->(raw) { read_hash(raw) }],
+      [->(raw) { raw.start_with?("[") && raw.end_with?("]") }, ->(raw) { read_array(raw) }]
+    ].freeze
+
     ESCAPED = { '"' => '\\"', "\\" => "\\\\" }.freeze
 
     # Wraps `text` in double quotes, escaping embedded quotes and backslashes.
@@ -96,30 +111,6 @@ module Hecks
     #
     # @param body [String] the text between a literal's outer braces or brackets
     # @return [Array<String>] each item's raw text, stripped, with empty items dropped
-    def split_items(body)
-      items = []
-      current = +""
-      depth = 0
-      quoting = false
-      escaping = false
-
-      body.each_char do |char|
-        current << char
-        next (escaping = false) if escaping
-        next (escaping = true) if quoting && char == "\\"
-        next (quoting = !quoting) if char == '"'
-        next if quoting
-
-        depth += 1 if "{[".include?(char)
-        depth -= 1 if "}]".include?(char)
-        next unless char == "," && depth.zero?
-
-        current.chop!
-        items << current
-        current = +""
-      end
-      items << current
-      items.map(&:strip).reject(&:empty?)
-    end
+    def split_items(body) = ItemSplitter.new(body).call
   end
 end

data/lib/hecks/mcp_stdio_guard.rb

@@ -42,15 +42,15 @@ module Hecks
     # carries the MCP protocol, and a stray line there corrupts the client's framing.
     #
     # @param server [String] the server's name, used as the line prefix
-    # @param argv [Array<String>] the command-line arguments
-    # @param env [Hash{String => String}] the process environment
-    # @param stdin [IO] the stream requests arrive on
-    # @param stdout [IO] the stream responses leave on
     # @param stderr [IO] where the refusal is written
+    # @param checks [Hash{Symbol => Object}] what `violations` looks at: `argv:` (the command-line
+    #   arguments), `env:` (the process environment), `stdin:` (the stream requests arrive on) and
+    #   `stdout:` (the stream responses leave on)
     # @return [void]
     # @raise [SystemExit] with status `EXIT_STATUS` when `violations` is not empty
-    def enforce_stdio!(server:, argv: ARGV, env: ENV, stdin: $stdin, stdout: $stdout, stderr: $stderr)
-      found = violations(argv: argv, env: env, stdin: stdin, stdout: stdout)
+    # @raise [ArgumentError] for any other keyword
+    def enforce_stdio!(server:, stderr: $stderr, **checks)
+      found = violations(**checks)
       refuse!(server, found, stderr) unless found.empty?
     end
 
@@ -88,7 +88,7 @@ module Hecks
     # @api private
     def argument_violations(argv)
       (argv - ACCEPTED_ARGS).map do |arg|
-        "argument #{arg.inspect} is not accepted (only #{ACCEPTED_ARGS.join(', ')}); network options are refused, not ignored"
+        "argument #{arg.inspect} is not accepted (only #{ACCEPTED_ARGS.join(", ")}); network options are refused, not ignored"
       end
     end
 
@@ -96,7 +96,7 @@ module Hecks
     def environment_violations(env)
       env.select { |name, value| name.start_with?(ENV_PREFIX) && ACCEPTED_ENV[name] != value }.map do |name, value|
         "environment #{name}=#{value.inspect} is not accepted; the servers take no #{ENV_PREFIX}* options " \
-          "except #{ACCEPTED_ENV.map { |k, v| "#{k}=#{v}" }.join(', ')}"
+          "except #{ACCEPTED_ENV.map { |k, v| "#{k}=#{v}" }.join(", ")}"
       end
     end
 

data/lib/hecks/naming.rb

@@ -74,7 +74,7 @@ module Hecks
       when 0 then ""
       when 1 then items[0].to_s
       when 2 then "#{items[0]} #{conj} #{items[1]}"
-      else "#{items[0..-2].join(', ')}, #{conj} #{items[-1]}"
+      else "#{items[0..-2].join(", ")}, #{conj} #{items[-1]}"
       end
     end
 
@@ -112,13 +112,19 @@ module Hecks
 
       # Undo `plural`'s "es" after s/x/z/ch/sh before the bare-"s" rule, so "Boxes"
       # gives "Box" while "Invoices" still gives "Invoice".
-      return word[0..-3] if word.length > 3 && word.end_with?("es") && word[0..-3].match?(/(s|x|z|ch|sh)\z/)
+      return word[0..-3] if sibilant_es?(word)
 
       return word[0..-2] if word.length > 1 && word.end_with?("s")
 
       word
     end
 
+    # @param word [String] a plural name
+    # @return [Boolean] whether it is a sibilant stem plus `plural`'s "es"
+    def sibilant_es?(word)
+      word.length > 3 && word.end_with?("es") && word[0..-3].match?(/(s|x|z|ch|sh)\z/)
+    end
+
     # Derives the attribute name a reference to `type` is stored under.
     #
     # @param type [Module, String, Symbol, #to_s] the referenced construct's name
@@ -175,7 +181,7 @@ module Hecks
       domain, aggregate, *rest = path.to_s.split("::")
       return nil unless domain && aggregate
 
-      command = "#{rest.join('.')}.#{command}" unless rest.empty?
+      command = "#{rest.join(".")}.#{command}" unless rest.empty?
 
       [domain, aggregate, command]
     end