hecks 3.11.0 → 3.13.0

data/lib/hecks/framework/bluebook/change.bluebook

@@ -0,0 +1,162 @@
+Hecks.bluebook "Change" do
+  vision "A change you can preview: it is planned, shown, confirmed against exactly that plan, and only then carried out, whatever script it runs."
+  supporting
+
+  # A framework member like Governance and Identity: attach it with `attaches "Change"` in the
+  # consuming domain's own `.hecksagon`. The script is the port's adapter, so what a change
+  # does lives behind the `Script` port, and this chapter holds only how any change moves.
+  aggregate "Change" do
+    description "One change a script makes, previewed before it is carried out and applied only if its plan is unchanged."
+
+    attribute :run,            RunKey
+    attribute :script,         ScriptName
+    attribute :arguments,      list_of(Argument), optional: true
+    attribute :plan,           Report,            optional: true
+    attribute :planned_digest, Digest,            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 change is named") { !value.to_s.empty? }
+    end
+
+    # The name the script is registered under with the adapter.
+    value_object "ScriptName" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a change names its script") { !value.to_s.empty? }
+    end
+
+    # One argument of the script, spelled as text; the script says what each key means.
+    value_object "Argument" do
+      attribute :key,   String
+      attribute :value, String
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    # A fingerprint of the plan, the script and its arguments: confirming one digest applies
+    # that plan and no other.
+    value_object "Digest" do
+      attribute :value, String, pattern: '[0-9a-f]+'
+
+      invariant("a plan has a digest") { !value.to_s.empty? }
+    end
+
+    lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
+      transition "Plan"     => "planned",   from: "requested"
+      transition "Confirm"  => "confirmed", from: "planned"
+      transition "Complete" => "applied",   from: "confirmed"
+      transition "Fault"    => "faulted",   from: ["requested", "planned", "confirmed"]
+    end
+
+    command "Request" do
+      role "Maintainer"
+      goal "Ask for a change by naming its script and giving the script's arguments"
+
+      attribute :run,       RunKey
+      attribute :script,    ScriptName
+      attribute :arguments, list_of(Argument), optional: true
+
+      sets :run
+      sets :script
+      sets :arguments
+
+      emits ChangeRequested
+    end
+
+    command "Plan" do
+      role "System"
+      goal "Record what the script would do, and the digest that stands for it"
+
+      reference_to Change
+      attribute :plan,   Report
+      attribute :digest, Digest
+
+      sets :plan
+      sets :planned_digest, to: :digest
+
+      emits ChangePlanned
+    end
+
+    command "Confirm" do
+      role "Maintainer"
+      goal "Agree to the plan shown, by naming its digest"
+
+      reference_to Change
+      attribute :digest, Digest
+
+      given("the digest confirmed is the digest planned") { digest.value == planned_digest.value }
+
+      emits ChangeConfirmed
+    end
+
+    command "Complete" do
+      role "System"
+      goal "Record that the confirmed plan was carried out, and what the script reported"
+
+      reference_to Change
+      attribute :report, Report
+
+      sets :report
+
+      emits ChangeApplied
+    end
+
+    command "Fault" do
+      role "System"
+      goal "Record that the change was refused or could not be carried out, and why"
+
+      reference_to Change
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits ChangeFaulted
+    end
+
+    query "Outcome" do
+      description "How one change stands: its status, its plan, and what it reported or why it failed."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Faulted" do
+      description "Every change that was refused or could not be carried out."
+      where(status: "faulted")
+      order_by :run
+    end
+  end
+
+  policy "ExamineWhenRequested" do
+    on      "Change.ChangeRequested"
+    trigger Change::Script::Examine, with: { run: :run }
+  end
+
+  policy "RecordThePlanWhenExamined" do
+    on      "Change.ChangeExamined"
+    trigger Change::Plan, with: { plan: :plan, digest: :digest }
+  end
+
+  policy "PerformWhenConfirmed" do
+    on      "Change.ChangeConfirmed"
+    trigger Change::Script::Perform, with: { run: :run }
+  end
+
+  policy "RecordTheOutcomeWhenPerformed" do
+    on      "Change.ChangeAnswered"
+    trigger Change::Complete, with: { report: :report }
+  end
+
+  policy "RecordTheRefusal" do
+    on      "Change.ChangeRefused"
+    trigger Change::Fault, with: { refusal: :refusal }
+  end
+end

data/lib/hecks/framework/bluebook/change.hecksagon

@@ -0,0 +1,21 @@
+Hecks.hecksagon "Change" do
+  # `Change.Request` and `Change.Confirm` declare roles; same reason as Compliance.
+  attaches "Governance"
+  persisted_by "Memory"
+
+  # The change moves through two asks: `Examine` plans it, `Perform` carries it out. What a
+  # script does is the adapter's, so the chapter never names one.
+  Change::Change.port "Script" do
+    asks "Examine", to: Change do
+      attribute :run, RunKey
+      answers "ChangeExamined"
+      refuses "ChangeRefused"
+    end
+
+    asks "Perform", to: Change do
+      attribute :run, RunKey
+      answers "ChangeAnswered"
+      refuses "ChangeRefused"
+    end
+  end
+end

data/lib/hecks/framework/change.oidc.json

@@ -0,0 +1,34 @@
+{
+  "audience": "Change",
+  "scopes": [
+    {
+      "scope": "change:change.complete",
+      "verb": "Change::Change.Complete",
+      "role": "System"
+    },
+    {
+      "scope": "change:change.confirm",
+      "verb": "Change::Change.Confirm",
+      "role": "Maintainer"
+    },
+    {
+      "scope": "change:change.fault",
+      "verb": "Change::Change.Fault",
+      "role": "System"
+    },
+    {
+      "scope": "change:change.plan",
+      "verb": "Change::Change.Plan",
+      "role": "System"
+    },
+    {
+      "scope": "change:change.request",
+      "verb": "Change::Change.Request",
+      "role": "Maintainer"
+    }
+  ],
+  "roles": [
+    "Maintainer",
+    "System"
+  ]
+}

data/lib/hecks/framework/console_settings.oidc.json

@@ -0,0 +1,103 @@
+{
+  "audience": "ConsoleSettings",
+  "scopes": [
+    {
+      "scope": "console_settings:collection.declare",
+      "verb": "ConsoleSettings::Collection.Declare",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.replace_columns",
+      "verb": "ConsoleSettings::Collection.ReplaceColumns",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.replace_detail_field_columns",
+      "verb": "ConsoleSettings::Collection.ReplaceDetailFieldColumns",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.replace_detail_fields",
+      "verb": "ConsoleSettings::Collection.ReplaceDetailFields",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.replace_field_formats",
+      "verb": "ConsoleSettings::Collection.ReplaceFieldFormats",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.replace_preconditions",
+      "verb": "ConsoleSettings::Collection.ReplacePreconditions",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_extra",
+      "verb": "ConsoleSettings::Collection.SetExtra",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_identity",
+      "verb": "ConsoleSettings::Collection.SetIdentity",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_key",
+      "verb": "ConsoleSettings::Collection.SetKey",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_label",
+      "verb": "ConsoleSettings::Collection.SetLabel",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_list_query",
+      "verb": "ConsoleSettings::Collection.SetListQuery",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_nav_order",
+      "verb": "ConsoleSettings::Collection.SetNavOrder",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_primary_field",
+      "verb": "ConsoleSettings::Collection.SetPrimaryField",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:overview.declare",
+      "verb": "ConsoleSettings::Overview.Declare",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:overview.replace_stats",
+      "verb": "ConsoleSettings::Overview.ReplaceStats",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:state_style.declare",
+      "verb": "ConsoleSettings::StateStyle.Declare",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:state_style.set_attention",
+      "verb": "ConsoleSettings::StateStyle.SetAttention",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:state_style.set_extra",
+      "verb": "ConsoleSettings::StateStyle.SetExtra",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:state_style.set_tone",
+      "verb": "ConsoleSettings::StateStyle.SetTone",
+      "role": "Console"
+    }
+  ],
+  "roles": [
+    "Console"
+  ]
+}

data/lib/hecks/framework/governance.oidc.json

@@ -0,0 +1,28 @@
+{
+  "audience": "Governance",
+  "scopes": [
+    {
+      "scope": "governance:role_assignment.assign",
+      "verb": "Governance::RoleAssignment.Assign",
+      "role": "Governance administrator"
+    },
+    {
+      "scope": "governance:role_assignment.revoke",
+      "verb": "Governance::RoleAssignment.Revoke",
+      "role": "Governance administrator"
+    },
+    {
+      "scope": "governance:role_transition.grant",
+      "verb": "Governance::RoleTransition.Grant",
+      "role": "Governance administrator"
+    },
+    {
+      "scope": "governance:role_transition.revoke",
+      "verb": "Governance::RoleTransition.Revoke",
+      "role": "Governance administrator"
+    }
+  ],
+  "roles": [
+    "Governance administrator"
+  ]
+}

data/lib/hecks/framework/identity.oidc.json

@@ -0,0 +1,18 @@
+{
+  "audience": "Identity",
+  "scopes": [
+    {
+      "scope": "identity:external_identifier.link",
+      "verb": "Identity::ExternalIdentifier.Link",
+      "role": "Identity registrar"
+    },
+    {
+      "scope": "identity:identity.register",
+      "verb": "Identity::Identity.Register",
+      "role": "Identity registrar"
+    }
+  ],
+  "roles": [
+    "Identity registrar"
+  ]
+}

data/lib/hecks/framework/privacy.oidc.json

@@ -0,0 +1,30 @@
+{
+  "audience": "Privacy",
+  "scopes": [
+    {
+      "scope": "privacy:marking.mark",
+      "verb": "Privacy::Marking.Mark",
+      "role": "Deployment"
+    },
+    {
+      "scope": "privacy:marking.unmark",
+      "verb": "Privacy::Marking.Unmark",
+      "role": "Deployment"
+    },
+    {
+      "scope": "privacy:subject_key.issue",
+      "verb": "Privacy::SubjectKey.Issue",
+      "role": "System"
+    },
+    {
+      "scope": "privacy:subject_key.shred",
+      "verb": "Privacy::SubjectKey.Shred",
+      "role": "Privacy officer"
+    }
+  ],
+  "roles": [
+    "Deployment",
+    "Privacy officer",
+    "System"
+  ]
+}

data/lib/hecks/gate/stages.yml

@@ -20,8 +20,11 @@
 # with `only=`: several of them write generated files and compare, so the stage is not meant to
 # run whole in one checkout.
 pre_push:
+  # HECKS_PROCESS_SPECS keeps the examples tagged `process` (they start child processes, so a plain
+  # `rspec` leaves them out) in the suite this stage runs.
   env:
     HECKS_ENVIRONMENT: memory
+    HECKS_PROCESS_SPECS: "1"
   checks:
     - id: rspec
       title: rspec (parallel)
@@ -94,6 +97,38 @@ unguarded_push:
     - *check_comment_blocks
     - *check_fuzzing
 
+# The Rust io specs `ci-rust-io.yml` runs in its `rspec_rust_io` job, for a push that wants their
+# answer first: `hecks gate_run.gate stage=rust_io --wait`. No hook or workflow runs it. It sets CI
+# as the job does, so a skipped example fails here as it fails there. rust/src/generated is not
+# committed, so the check materializes it first, as the job's generated-rust action does. The specs
+# mutate rust/, and a stage's checks run at once, so the job's two legs run one after the other in
+# a single check. spec/gate_rust_io_stage_spec.rb pins the spec lists to the workflow's matrix.
+rust_io:
+  env:
+    CI: "true"
+    HECKS_ENVIRONMENT: memory
+  checks:
+    - id: rust_io
+      title: rust io specs, conformance, coercion, has_many, semantics corpus and feature exclusivity
+      run:
+        - sh
+        - -ec
+        - |
+          # Building the banking crate makes banking the default feature and rewrites the module
+          # list, both tracked. They are put back on the way out, and the check will not start over
+          # a person's uncommitted edits to them.
+          rewritten="rust/Cargo.toml rust/src/generated/mod.rs"
+          if [ -n "$(git status --porcelain -- $rewritten)" ]; then
+            echo "uncommitted changes in $rewritten; commit or discard them first" >&2
+            exit 1
+          fi
+          trap 'git checkout -q -- $rewritten' EXIT
+          env -u CARGO_TARGET_DIR bundle exec exe/hecks regeneration_run.regenerate_corpus --confirm --wait
+          bundle exec exe/hecks build.project_rust domain=examples/banking --wait
+          bundle exec rspec --tag io --profile 8 spec/rust_conformance_spec.rb spec/rust_conformance_fuzz_spec.rb spec/rust_numeric_coercion_spec.rb spec/rust_generated/has_many_spec.rb spec/semantics_corpus_spec.rb
+          bundle exec rspec --tag io --profile 8 spec/rust_generated/domain_feature_exclusivity_spec.rb
+      blocked: a Rust io spec failed, or skipped; the crate it built is under rust/target.
+
 # The checks `.github/workflows/ci-checks.yml` runs. It sets no `env`: the job's journal choice
 # (the `hecks-environment` action) reaches every check, as it reached each command before.
 ci:

data/lib/hecks/grammar/translation.oidc.json

@@ -0,0 +1,48 @@
+{
+  "audience": "Translation",
+  "scopes": [
+    {
+      "scope": "translation:map.declare",
+      "verb": "Translation::Map.Declare",
+      "role": "Author"
+    },
+    {
+      "scope": "translation:map.draft",
+      "verb": "Translation::Map.Draft",
+      "role": "Author"
+    },
+    {
+      "scope": "translation:map.seal",
+      "verb": "Translation::Map.Seal",
+      "role": "Author"
+    },
+    {
+      "scope": "translation:map.supersede",
+      "verb": "Translation::Map.Supersede",
+      "role": "Author"
+    },
+    {
+      "scope": "translation:rule.admit",
+      "verb": "Translation::Rule.Admit",
+      "role": "Author"
+    },
+    {
+      "scope": "translation:rule.execute",
+      "verb": "Translation::Rule.Execute",
+      "role": "Author"
+    },
+    {
+      "scope": "translation:rule.propose",
+      "verb": "Translation::Rule.Propose",
+      "role": "Author"
+    },
+    {
+      "scope": "translation:rule.retire",
+      "verb": "Translation::Rule.Retire",
+      "role": "Author"
+    }
+  ],
+  "roles": [
+    "Author"
+  ]
+}

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

@@ -45,12 +45,23 @@ module Hecks
         # What the runner printed for the example, when it passed.
         def run_example(path, example)
           out = StringIO.new
-          status = Dir.chdir(@tree.root) { runner.call(["--example", example, path], out, out) }
+          status = Dir.chdir(@tree.root) { at_reaction_depth_zero { runner.call(["--example", example, path], out, out) } }
           raise ConsoleCapture::Failure, out.string.strip unless status.zero?
 
           out.string.strip
         end
 
+        # The runner is asked for from inside a command's own reaction cascade, and the dispatcher
+        # keeps that cascade's depth on the thread. An example starts at depth zero, as a plain run
+        # does, so a spec that cascades four deep is not cut off by the cascade that launched it.
+        def at_reaction_depth_zero
+          depth = Thread.current[:hecks_reaction_depth]
+          Thread.current[:hecks_reaction_depth] = 0
+          yield
+        ensure
+          Thread.current[:hecks_reaction_depth] = depth
+        end
+
         def runner
           return self.class.runner if self.class.runner
 

data/lib/hecks/hecks/adapters/deploy_toolchain.rb

@@ -74,7 +74,8 @@ module Hecks
         { report: { value: child(:lint, paths).dig(:output, :value) } }
       end
 
-      # Projects each domain's OIDC client and scope manifest into its `oidc.json`, through
+      # Projects each domain's OIDC client and scope manifest into its `oidc.json`, or into one
+      # `<chapter>.oidc.json` for each chapter of a directory that holds several, through
       # `hecks deploy oidc_manifest.project_oidc`.
       #
       # @param held [Hash] the `OidcManifest` record: `domains` (comma separated directories; every

data/lib/hecks/hecks/adapters/rehearsal/postgres_store.rb

@@ -119,9 +119,13 @@ module Hecks
           ["pg_restore", "--no-owner", "--no-privileges", "-d", database_name, file]
         end
 
+        # What the URL names, and nothing it leaves out: `postgres:///postgres` parses with an empty
+        # host, which would override a `PGHOST` the environment sets and send the restore to the
+        # local socket while the rest of the rehearsal reached the server by TCP.
         def restore_env
           uri = URI.parse(server_url)
-          { "PGHOST" => uri.host, "PGPORT" => uri.port&.to_s, "PGUSER" => uri.user, "PGPASSWORD" => uri.password }.compact
+          { "PGHOST" => uri.host, "PGPORT" => uri.port&.to_s, "PGUSER" => uri.user, "PGPASSWORD" => uri.password }
+            .reject { |_name, value| value.to_s.empty? }
         end
       end
     end

data/lib/hecks/hecks/hecks.world

@@ -36,6 +36,8 @@
 # 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.
+# `newcomer` names the only commands the help lists in a folder holding no bluebook yet
+# (`hecks --all` lists the rest), so a first run shows how to start and nothing else.
 Hecks.world "Hecks" do
   realm "Hecks"
   default_adapter "PostgresEra"
@@ -58,6 +60,7 @@ Hecks.world "Hecks" do
                        maintainer: %w[LanguageRun KernelRun ConformanceRun RegenerationRun GateRun StyleRun InspectionRun
                                       CodemodRun TestSuiteRun CorpusRun PublishingRun PromotionRun Release
                                       SyntaxBootCache],
+                       newcomer: %w[launch.init launch.interview operation.open_console],
                        chapters: %w[Deploy Governance Tenancy Site Tickets QualityControl],
                        maintainer_chapters: %w[Bluebook Hecksagon World Adapter Port Translation Expression],
                        memory_commands: %w[console init interview],

data/lib/hecks/language/bluebook/bluebook.behaviors

@@ -0,0 +1,23 @@
+Hecks.behaviors "Bluebook" do
+  vision "A chapter is opened with a name, a vision and a classification, and refuses a classification the language does not admit."
+
+  loads "bluebook.bluebook", "bluebook.hecksagon"
+
+  test "Declare opens a chapter" do
+    tests "Declare", on: "Bluebook"
+    input name: "Pizzas", vision: "Pizzas, built and sold.", classification: "core"
+    expect emits: ["ChapterDeclared"]
+  end
+
+  test "Declare refuses a classification that is not core, supporting or generic" do
+    tests "Declare", on: "Bluebook"
+    input name: "Pizzas", vision: "Pizzas, built and sold.", classification: "huge"
+    expect refused: "a chapter is core, supporting, or generic"
+  end
+
+  test "Declare refuses a chapter with no name" do
+    tests "Declare", on: "Bluebook"
+    input name: "", vision: "Pizzas, built and sold.", classification: "core"
+    expect refused: "a chapter is named"
+  end
+end

data/lib/hecks/language/bluebook/policy.behaviors

@@ -0,0 +1,19 @@
+Hecks.behaviors "Bluebook" do
+  vision "A policy hangs off a chapter and names the event it watches; an unnamed policy is refused."
+
+  loads "bluebook.bluebook", "policy.bluebook", "bluebook.hecksagon"
+
+  test "Declare puts a policy on a chapter" do
+    tests "Declare", on: "Policy"
+    setup  "Bluebook::Bluebook.Declare", name: "Pizzas", vision: "Pizzas, built and sold.", classification: "core"
+    input  bluebook: "Pizzas", name: "NotifyKitchen", on_event: "OrderPlaced"
+    expect emits: ["ReactionDeclared"]
+  end
+
+  test "Declare refuses a policy with no name" do
+    tests "Declare", on: "Policy"
+    setup  "Bluebook::Bluebook.Declare", name: "Pizzas", vision: "Pizzas, built and sold.", classification: "core"
+    input  bluebook: "Pizzas", name: "", on_event: "OrderPlaced"
+    expect refused: "a policy is named"
+  end
+end