hecks 3.0.3 → 3.0.4

data/lib/hecks/grammar/expression.bluebook

@@ -211,6 +211,11 @@ Hecks.bluebook "Expression" do
 
       member strategy: "collapse_whitespace", source_token: "", replacement: "", boundary: "none", position: 1
       member strategy: "replace", source_token: ".length", replacement: ".size", boundary: "word", position: 2
+      # A duration written as a call on a whole number is that many seconds: `days(730)` is
+      # `63072000`. `source_token` names the call and `replacement` the seconds one unit is worth.
+      member strategy: "scale_call", source_token: "days",    replacement: "86400", boundary: "word", position: 3
+      member strategy: "scale_call", source_token: "hours",   replacement: "3600",  boundary: "word", position: 4
+      member strategy: "scale_call", source_token: "minutes", replacement: "60",    boundary: "word", position: 5
     end
 
     value_object "Reading" do
@@ -233,7 +238,7 @@ Hecks.bluebook "Expression" do
       attribute :position,     Position, optional: true
 
       given("a rule must name a linked strategy") do
-        strategy.value == "collapse_whitespace" || strategy.value == "replace"
+        strategy.value == "collapse_whitespace" || strategy.value == "replace" || strategy.value == "scale_call"
       end
 
       given("a rule must state its boundary") { boundary.value == "none" || boundary.value == "word" }

data/lib/hecks/grammar/expression_operators.json

@@ -1644,6 +1644,141 @@
         }
       }
     },
+    {
+      "verb": "Expression::Normalisation.Propose",
+      "args": {
+        "name": {
+          "value": "days_to_seconds"
+        },
+        "strategy": {
+          "value": "scale_call"
+        },
+        "source_token": {
+          "value": "days"
+        },
+        "replacement": {
+          "value": "86400"
+        },
+        "boundary": {
+          "value": "word"
+        },
+        "position": {
+          "value": 3
+        }
+      }
+    },
+    {
+      "verb": "Expression::Normalisation.Read",
+      "args": {
+        "name": {
+          "value": "days_to_seconds"
+        },
+        "target": {
+          "value": "ruby"
+        },
+        "form": {
+          "value": "text.gsub(/(?<![[:alnum:]_.])days\\(\\s*(\\d+)\\s*\\)/) { $1.to_i * 86400 }"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Normalisation.Admit",
+      "args": {
+        "name": {
+          "value": "days_to_seconds"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Normalisation.Propose",
+      "args": {
+        "name": {
+          "value": "hours_to_seconds"
+        },
+        "strategy": {
+          "value": "scale_call"
+        },
+        "source_token": {
+          "value": "hours"
+        },
+        "replacement": {
+          "value": "3600"
+        },
+        "boundary": {
+          "value": "word"
+        },
+        "position": {
+          "value": 4
+        }
+      }
+    },
+    {
+      "verb": "Expression::Normalisation.Read",
+      "args": {
+        "name": {
+          "value": "hours_to_seconds"
+        },
+        "target": {
+          "value": "ruby"
+        },
+        "form": {
+          "value": "text.gsub(/(?<![[:alnum:]_.])hours\\(\\s*(\\d+)\\s*\\)/) { $1.to_i * 3600 }"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Normalisation.Admit",
+      "args": {
+        "name": {
+          "value": "hours_to_seconds"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Normalisation.Propose",
+      "args": {
+        "name": {
+          "value": "minutes_to_seconds"
+        },
+        "strategy": {
+          "value": "scale_call"
+        },
+        "source_token": {
+          "value": "minutes"
+        },
+        "replacement": {
+          "value": "60"
+        },
+        "boundary": {
+          "value": "word"
+        },
+        "position": {
+          "value": 5
+        }
+      }
+    },
+    {
+      "verb": "Expression::Normalisation.Read",
+      "args": {
+        "name": {
+          "value": "minutes_to_seconds"
+        },
+        "target": {
+          "value": "ruby"
+        },
+        "form": {
+          "value": "text.gsub(/(?<![[:alnum:]_.])minutes\\(\\s*(\\d+)\\s*\\)/) { $1.to_i * 60 }"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Normalisation.Admit",
+      "args": {
+        "name": {
+          "value": "minutes_to_seconds"
+        }
+      }
+    },
     {
       "verb": "Expression::Operator.Propose",
       "args": {

data/lib/hecks/hecks/adapters/codebase/gate.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "ruby_child"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `GateRun` asks of the working tree: running a stage's checks.
+      #
+      # It runs `Hecks::Tools::Gate` in this process. The tool starts the stage's checks together,
+      # each as its own process, and answers 1 when any is red; the refusal is what the red checks
+      # printed, so `--wait` and the journal both say which check failed.
+      module Gate
+        # Every operation this family carries out.
+        OPERATIONS = %w[gate].freeze
+
+        module_function
+
+        # Runs the stage.
+        #
+        # @param _operation [String] `gate`
+        # @param held [Hash] the `GateRun` record's fields: `stage`, and `only` when given
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture, nil] unused: the tool runs in this process
+        # @return [String] which checks passed
+        # @raise [ConsoleCapture::Failure] with what the red checks printed
+        def call(_operation, held, tree, shell: nil)
+          plain = ->(name) { held[name].is_a?(Hash) ? held[name][:value] : held[name] }
+          only = plain.call(:only).to_s
+          argv = [plain.call(:stage).to_s, *("only=#{only}" unless only.empty?)]
+          RubyChild.new(tree).answer("gate", *argv).strip
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/regeneration.rb

@@ -7,7 +7,7 @@ module Hecks
   module Adapters
     module Codebase
       # What Codebase's `RegenerationRun` asks of the working tree: regenerating every corpus
-      # domain's committed Rust output.
+      # domain's committed Rust output, and projecting the CI path gates into the workflows.
       #
       # It runs `Hecks::Tools::RegenerationRun` in this process: the run forks once for each
       # domain, in a fixed order, because the domains share the files they stamp. With `check` it
@@ -16,7 +16,7 @@ module Hecks
       # files reports drift and writes only when it is confirmed.
       module Regeneration
         # Every operation this family carries out.
-        OPERATIONS = %w[regenerate_corpus].freeze
+        OPERATIONS = %w[regenerate_corpus project_ci_gates decide_ci_gate].freeze
 
         # How many lines of a script's output a refusal keeps.
         KEPT_LINES = 60
@@ -25,23 +25,43 @@ module Hecks
 
         # Carries out the regeneration.
         #
-        # @param _operation [String] `regenerate_corpus`
+        # @param operation [String] `regenerate_corpus` or `project_ci_gates`
         # @param held [Hash] the `RegenerationRun` record's fields: `check`, `confirm`
         # @param tree [Tree] the working tree, already known to be a hecks checkout
         # @param shell [#capture, nil] unused: the tool runs in this process
         # @return [String] how many domains were checked or regenerated
         # @raise [ConsoleCapture::Failure] with the difference, when a check finds drift, or with
         #   what the script printed when it ends badly
-        def call(_operation, held, tree, shell: nil)
+        def call(operation, held, tree, shell: nil)
           flag = ->(name) { (held[name].is_a?(Hash) ? held[name][:value] : held[name]) == true }
           check = flag.call(:check) || !flag.call(:confirm)
           child = RubyChild.new(tree)
+          return project_ci_gates(child, check) if operation == "project_ci_gates"
+          return decide_ci_gate(child, held) if operation == "decide_ci_gate"
+
           result = child.capture("regen_codegen_domains", *("--check" if check))
           raise ConsoleCapture::Failure, refusal(result) unless result.ok?
 
           summary(result.out, check)
         end
 
+        # @param child [RubyChild] the checkout's tool runner
+        # @param check [Boolean] whether to only compare
+        # @return [String] what the tool printed
+        # @raise [ConsoleCapture::Failure] with the stale workflows, when a check finds drift
+        def project_ci_gates(child, check)
+          child.answer("project_ci_gates", *("--check" if check))
+        end
+
+        # @param child [RubyChild] the checkout's tool runner
+        # @param held [Hash] the record's fields: `gate`, a `CiGate` row's name
+        # @return [String] `touched=true` or `touched=false`
+        # @raise [ConsoleCapture::Failure] when no row has that name
+        def decide_ci_gate(child, held)
+          gate = held[:gate].is_a?(Hash) ? held[:gate][:value] : held[:gate]
+          child.answer("decide_ci_gate", "gate=#{gate}")
+        end
+
         # @param output [String] what the script printed
         # @param check [Boolean] whether it only compared
         # @return [String] the verdict, with how many domains it covered

data/lib/hecks/hecks/adapters/codebase/source_tree.rb

@@ -5,6 +5,7 @@ require_relative "language"
 require_relative "kernel_tables"
 require_relative "conformance"
 require_relative "regeneration"
+require_relative "gate"
 require_relative "style"
 require_relative "codemods"
 require_relative "test_suite"
@@ -178,7 +179,8 @@ module Hecks
 
       # The task families, each carrying out the operations it lists.
       FAMILIES = [Codebase::Language, Codebase::KernelTables, Codebase::Conformance, Codebase::Regeneration,
-                  Codebase::Style, Codebase::Codemods, Codebase::TestSuite, Codebase::CorpusTasks, Codebase::Publishing].freeze
+                  Codebase::Gate, Codebase::Style, Codebase::Codemods, Codebase::TestSuite,
+                  Codebase::CorpusTasks, Codebase::Publishing].freeze
       private_constant :FAMILIES
 
       def tree = Codebase::Tree.new

data/lib/hecks/hecks/codebase.behaviors

@@ -79,6 +79,18 @@ Hecks.behaviors "Codebase" do
     expect refused: "must match"
   end
 
+  test "ProjectCiGates refuses a run that is not named" do
+    tests "ProjectCiGates", on: "RegenerationRun"
+    input run: { value: "" }
+    expect refused: "must match"
+  end
+
+  test "DecideCiGate refuses a run that is not named" do
+    tests "DecideCiGate", on: "RegenerationRun"
+    input run: { value: "" }, gate: { value: "runtime_changed" }
+    expect refused: "must match"
+  end
+
   test "CheckComments keeps a file with no violations as a completed check" do
     tests "CheckComments", on: "StyleRun"
     input paths: { value: "lib/hecks/canonical_json.rb" }, run: { value: "clean" }

data/lib/hecks/hecks/codebase.bluebook

@@ -960,6 +960,7 @@ Hecks.bluebook "Hecks" do
     attribute :operation, Operation, optional: true
     attribute :confirm,   Switch, optional: true
     attribute :check,     Switch, optional: true
+    attribute :gate,      GateName, optional: true
     attribute :checkout,  Switch, optional: true
     attribute :report,    Report, optional: true
     attribute :refusal,   Report, optional: true
@@ -983,6 +984,11 @@ Hecks.bluebook "Hecks" do
       attribute :value, String
     end
 
+    # A `CiGate` row of the Vocabulary chapter, by name.
+    value_object "GateName" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
     lifecycle :status, default: "requested" do
       transition "Accept"   => "accepted",  from: "requested"
       transition "Complete" => "completed", from: "accepted"
@@ -1005,6 +1011,36 @@ Hecks.bluebook "Hecks" do
       emits RegenerateCorpusRequested
     end
 
+    command "ProjectCiGates" do
+      role "Maintainer"
+      goal "Project the CiGate rows into the workflows' marked detector jobs, or with check only compare them"
+
+      attribute :check,   Switch, optional: true
+      attribute :run,     RunKey
+      attribute :confirm, Switch, optional: true
+
+      sets :check
+      sets :run
+      sets :confirm
+      sets :operation, to: "project_ci_gates"
+
+      emits ProjectCiGatesRequested
+    end
+
+    command "DecideCiGate" do
+      role "Maintainer"
+      goal "Say whether this run's change touches what a CiGate row guards, as the gated job's detector"
+
+      attribute :gate, GateName
+      attribute :run,  RunKey
+
+      sets :gate
+      sets :run
+      sets :operation, to: "decide_ci_gate"
+
+      emits DecideCiGateRequested
+    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
@@ -1064,6 +1100,16 @@ Hecks.bluebook "Hecks" do
     trigger RegenerationRun::SourceTree::Examine, with: { run: :run }
   end
 
+  policy "ExamineWhenProjectCiGatesRequested" do
+    on      "RegenerationRun.ProjectCiGatesRequested"
+    trigger RegenerationRun::SourceTree::Examine, with: { run: :run }
+  end
+
+  policy "ExamineWhenDecideCiGateRequested" do
+    on      "RegenerationRun.DecideCiGateRequested"
+    trigger RegenerationRun::SourceTree::Examine, with: { run: :run }
+  end
+
   policy "AcceptRegenerationWhenExamined" do
     on      "RegenerationRun.RegenerationExamined"
     trigger RegenerationRun::Accept, with: { checkout: :checkout }
@@ -1090,6 +1136,154 @@ Hecks.bluebook "Hecks" do
     trigger RegenerationRun::Fault, with: { refusal: :refusal }
   end
 
+  # Gate: the checks a stage holds a change against before it is let through. The checks are data
+  # (lib/hecks/gate/stages.yml), run together, and a red one faults the run, so `--wait` fails the
+  # push or the build that asked, and the journal keeps when the gate went red.
+  aggregate "GateRun" do
+    description "One run of a stage's checks: every check of the stage, or the ones named."
+
+    attribute :run,       RunKey
+    attribute :operation, Operation, optional: true
+    attribute :stage,     Stage
+    attribute :only,      CheckList, 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 "Stage" do
+      attribute :value, String, pattern: '^[a-z][a-z0-9_]*$'
+
+      invariant("a stage is named") { !value.to_s.empty? }
+    end
+
+    value_object "CheckList" do
+      attribute :value, String, pattern: '^[a-z][a-z0-9_]*(,[a-z][a-z0-9_]*)*$'
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Accept"   => "accepted",  from: "requested"
+      transition "Complete" => "completed", from: "accepted"
+      transition "Fault"    => "faulted",   from: %w[requested accepted]
+    end
+
+    command "Gate" do
+      role "Maintainer"
+      goal "Run every check of a stage, or the ones named, and keep whether the gate is green"
+
+      attribute :stage, Stage
+      attribute :only,  CheckList, optional: true
+      attribute :run,   RunKey
+
+      sets :stage
+      sets :only
+      sets :run
+      sets :operation, to: "gate"
+
+      emits GateRequested
+    end
+
+    command "Accept" do
+      role "System"
+      goal "Let a request through only when the working tree is a hecks checkout"
+
+      reference_to GateRun
+      attribute :checkout, Switch
+
+      given("needs a hecks checkout: hecks.gemspec stands beside lib/") { checkout.value }
+
+      sets :checkout
+
+      emits GateAccepted
+    end
+
+    command "Complete" do
+      role "System"
+      goal "Record that every check passed, and which"
+
+      reference_to GateRun
+      attribute :report, Report
+
+      sets :report
+
+      emits GateCompleted
+    end
+
+    command "Fault" do
+      role "System"
+      goal "Record that a check was red or the run could not be made, and why"
+
+      reference_to GateRun
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits GateFaulted
+    end
+
+    query "GateOutcome" do
+      description "How one run ended: its status, and what it reported or why it failed."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "GateFaulted" do
+      description "Every run that went red or could not be made."
+      where(status: "faulted")
+      order_by :run
+    end
+  end
+
+  policy "ExamineWhenGateRequested" do
+    on      "GateRun.GateRequested"
+    trigger GateRun::SourceTree::Examine, with: { run: :run }
+  end
+
+  policy "AcceptGateWhenExamined" do
+    on      "GateRun.GateExamined"
+    trigger GateRun::Accept, with: { checkout: :checkout }
+  end
+
+  policy "FaultGateWhenNotAccepted" do
+    on      "GateRun.GateExamined"
+    where   { !checkout.value }
+    trigger GateRun::Fault, with: { refusal: "needs a hecks checkout: hecks.gemspec stands beside lib/" }
+  end
+
+  policy "PerformGateWhenAccepted" do
+    on      "GateRun.GateAccepted"
+    trigger GateRun::SourceTree::Perform, with: { run: :run }
+  end
+
+  policy "RecordGateOutcome" do
+    on      "GateRun.GateAnswered"
+    trigger GateRun::Complete, with: { report: :report }
+  end
+
+  policy "RecordGateFault" do
+    on      "GateRun.GateRefused"
+    trigger GateRun::Fault, with: { refusal: :refusal }
+  end
+
   # Style: the comment style guides (Ruby and Rust) and the canonical form of a JSON document. A
   # check finds every violation; a fix rewrites files, so it lists what it would rewrite unless
   # it is confirmed. The baseline of tolerated long blocks is written only when confirmed.

data/lib/hecks/hecks/custodian.bluebook

@@ -460,6 +460,8 @@ Hecks.bluebook "Hecks" do
 
     # A launcher answers once, so a follow is a bounded poll: it answers the entries past `since`
     # and a `cursor` to pass as the next `since`, waiting up to `wait` seconds for the first one.
+    # `hecks follow <domain> --stream` asks again from each cursor and prints every entry as it
+    # arrives, until interrupted (the world's `launcher` setting lists the question under `streams`).
     query "Follow" do
       description "A domain's persisted event log past a cursor, for tailing it call by call."
       attribute :domain,    Subject

data/lib/hecks/hecks/hecks.hecksagon

@@ -229,6 +229,20 @@ Hecks.hecksagon "Hecks" do
     end
   end
 
+  Hecks::GateRun.port "SourceTree" do
+    asks "Examine", to: GateRun do
+      attribute :run, RunKey
+      answers "GateExamined"
+      refuses "GateRefused"
+    end
+
+    asks "Perform", to: GateRun do
+      attribute :run, RunKey
+      answers "GateAnswered"
+      refuses "GateRefused"
+    end
+  end
+
   Hecks::StyleRun.port "SourceTree" do
     asks "Examine", to: StyleRun do
       attribute :run, RunKey

data/lib/hecks/hecks/hecks.world

@@ -26,8 +26,8 @@
 # `failure_states` are the lifecycle states `--wait` reports as exit 1 (every failure state the
 # chapter's lifecycles declare), `names` gives a command the launcher name clients type,
 # `executable` is where `hecks project_cli` writes this chapter's launcher (the gem's
-# `exe/hecks`), and `legacy` names the verbs that launcher hands to `Hecks::CLI` in the
-# positional forms ADR 0066 shipped.
+# `exe/hecks`), `streams` lists the questions `--stream` may tail (`Follow`), and `legacy` names
+# the verbs that launcher hands to `Hecks::CLI` in the positional forms ADR 0066 shipped.
 Hecks.world "Hecks" do
   realm "Hecks"
   default_adapter "PostgresEra"
@@ -36,6 +36,7 @@ Hecks.world "Hecks" do
                        failure_states: %w[flagged failed drifted unreachable refused faulted halted stopped
                                           abandoned red needs_fix],
                        names: { "mcp" => "serve_mcp", "console" => "open_console" },
+                       streams: %w[Follow],
                        executable: "exe/hecks",
                        legacy: %w[run docs narrate ir stores model_check smoke_test
                                   project_diagrams project_cli mcp]

data/lib/hecks/language/bluebook/command.bluebook

@@ -21,6 +21,8 @@ Hecks.bluebook "Bluebook" do
     attribute :givens,     list_of(Rule)
     # Postconditions: same Rule shape as givens, checked after the mutations.
     attribute :ensures,    list_of(Rule)
+    # Outside facts the runtime supplies before any given runs (ADR 0081): `needs :now`.
+    attribute :needs,      list_of(Need)
     attribute :mutations,  list_of(Change)
     attribute :provenance, CommandText
     # Lifecycle guard as a literal (`from: "open"` or `from: ["open", "frozen"]`); ADR 0025.
@@ -48,6 +50,10 @@ Hecks.bluebook "Bluebook" do
       attribute :name, String
     end
 
+    value_object "Need" do
+      attribute :fact, String
+    end
+
     value_object "Argument" do
       attribute :name,    String
       attribute :type,    String
@@ -254,6 +260,23 @@ Hecks.bluebook "Bluebook" do
       emits AnnouncementNamed
     end
 
+    command "Need" do
+      role "Language"
+      goal "Name an outside fact the runtime supplies before any given runs"
+
+      attribute :fact, FactName
+
+      given("a fact is named") { !fact.value.to_s.empty? }
+
+      sets :needs, append: { fact: :fact }
+
+      emits NeedNamed
+    end
+
+    value_object "FactName" do
+      attribute :value, String
+    end
+
     # Keyword rows for this chapter; SyntaxBoot discovers aggregate-local seed tables.
     value_object "KeywordSeed" do
       attribute :word,          String
@@ -283,6 +306,8 @@ Hecks.bluebook "Bluebook" do
       member word: "state",           context: "Command", body: "none",   inner: "", opens: "", fills: "mutations"
       member word: "attribute",       context: "Command", body: "none",   inner: "", opens: "", fills: "attributes", calls: "attribute_impl"
       member word: "ensures", context: "Command", body: "source", inner: "", opens: "", fills: "ensures"
+      # An outside fact the runtime supplies before any given runs (ADR 0081; CommandBuilder#needs_impl).
+      member word: "needs",           context: "Command", body: "none",   inner: "", opens: "", fills: "needs", calls: "needs_impl"
       # Amends a specific past event. Stored as a mutation so it round-trips with the other
       # mutation words (CommandBuilder#corrects_impl).
       member word: "corrects",        context: "Command", body: "none",   inner: "", opens: "", fills: "mutations", calls: "corrects_impl"
@@ -314,6 +339,7 @@ Hecks.bluebook "Bluebook" do
       member keyword: "reference_to",    context: "Command", at: "",  named: "optional",  kind: "flag",     required: "false", fills: "optional"
       member keyword: "given",           context: "Command", at: "1", named: "",          kind: "text",     required: "true",  fills: "description"
       member keyword: "ensures",         context: "Command", at: "1", named: "",          kind: "text",     required: "true",  fills: "description"
+      member keyword: "needs",           context: "Command", at: "1", named: "",          kind: "symbol",   required: "true",  fills: "fact"
       member keyword: "sets",            context: "Command", at: "1", named: "",          kind: "symbol",   required: "true",  fills: "target"
       member keyword: "sets",            context: "Command", at: "",  named: "to",        kind: "literal",  required: "false", fills: "source", selects: "op=set"
       member keyword: "sets",            context: "Command", at: "",  named: "append",    kind: "literal",  required: "false", fills: "source", selects: "op=append"