hecks 2.9.0 → 3.0.0

data/lib/hecks/tools.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Hecks
+  # The repository's command-line tools as library code: the comment linters, the regeneration
+  # run, the deploy generators and the conformance matrix.
+  #
+  # Each tool is a module with `main(argv, root:)` that prints to `$stdout` and `$stderr` and
+  # refuses with `abort` or `exit`, as the script it replaced did, and answers an exit status. An
+  # adapter runs a tool in this process under `Adapters::ConsoleCapture`; `script` runs one as a
+  # child's whole program. `require "hecks"` loads none of them: each is required by the command
+  # that needs it.
+  module Tools
+    # The checkout this file lives in, which a tool works on when it is given no other.
+    ROOT = File.expand_path("../..", __dir__)
+
+    # Each tool by the name of the retired script it replaced: the file that defines it, and its
+    # constant.
+    REGISTRY = {
+      "standardize_comments"           => ["tools/comment_style", "CommentStyle"],
+      "standardize_comments_rust"      => ["tools/rust_comment_style", "RustCommentStyle"],
+      "regen_codegen_domains"          => ["tools/regeneration_run", "RegenerationRun"],
+      "argument_gate_matrix"           => ["tools/argument_gate_matrix", "ArgumentGateMatrix"],
+      "project_deploy"                 => ["tools/deploy_recipe", "DeployRecipe"],
+      "lint_deploy_recipes"            => ["tools/deploy_recipe_lint", "DeployRecipeLint"],
+      "project_oidc"                   => ["tools/oidc_manifests", "OidcManifests"],
+      "project_tenant"                 => ["tools/tenant_provisioning", "TenantProvisioning"],
+      "translation_audit"              => ["tools/translation_audit", "TranslationAudit"],
+      "scaffold_translation"           => ["tools/translation_scaffold", "TranslationScaffold"],
+      "reattest_era"                   => ["tools/era_reattest", "EraReattest"],
+      "merge_tail"                     => ["tools/tail_merge", "TailMerge"],
+      "backfill_era_projections"       => ["tools/era_projection_backfill", "EraProjectionBackfill"],
+      "compact"                        => ["tools/journal_compaction", "JournalCompaction"],
+      "heki_compact"                   => ["tools/heki_compaction", "HekiCompaction"],
+      "fuzz"                           => ["tools/fuzz_sweep", "FuzzSweep"],
+      "generate"                       => ["tools/sequence_script", "SequenceScript"],
+      "corpus"                         => ["tools/corpus_report", "CorpusReport"],
+      "evolve"                         => ["tools/evolve_run", "EvolveRun"],
+      "query_ir"                       => ["tools/query_ir_run", "QueryIrRun"],
+      "codemod_hoist_local_givens"     => ["tools/hoist_local_givens", "HoistLocalGivens"],
+      "codemod_implicit_append_fields" => ["tools/drop_implicit_append_fields", "DropImplicitAppendFields"]
+    }.freeze
+
+    module_function
+
+    # @param name [String] a tool's name, as in `REGISTRY`
+    # @return [Boolean] whether the script's body lives here
+    def tool?(name) = REGISTRY.key?(name)
+
+    # Loads a tool and returns it.
+    #
+    # @param name [String] a tool's name, as in `REGISTRY`
+    # @return [Module] the tool, which answers `main(argv, root:)`
+    # @raise [KeyError] when no tool replaced a script of that name
+    def fetch(name)
+      file, constant = REGISTRY.fetch(name)
+      require File.join(__dir__, file)
+      const_get(constant)
+    end
+
+    # Runs a tool as a program's whole body and exits with its status. Paths in `argv` are read
+    # from the directory the caller stands in.
+    #
+    # @param name [String] a tool's name, as in `REGISTRY`
+    # @param argv [Array<String>] the arguments the script took
+    # @return [void]
+    def script(name, argv)
+      exit(fetch(name).main(argv) || 0)
+    end
+
+    # Runs a tool from a checkout's root in this process.
+    #
+    # @param name [String] a tool's name, as in `REGISTRY`
+    # @param argv [Array<String>] the arguments the script took
+    # @param root [String] the checkout to work on
+    # @return [Integer] the exit status: 0 when the tool ends normally; 1, with the error's class
+    #   and message on `$stderr`, when the tool raises
+    def run(name, argv, root: ROOT)
+      Dir.chdir(root) { fetch(name).main(argv, root: root) || 0 }
+    rescue SystemExit => e
+      e.status
+    rescue StandardError, ScriptError => e
+      warn "#{name}: #{e.class}: #{e.message}"
+      1
+    end
+  end
+end

data/lib/hecks/version.rb

@@ -1,5 +1,5 @@
 module Hecks
   # Read directly by the gemspec, so this file must never require the
   # rest of the gem (its dependencies aren't resolved yet at that point).
-  VERSION = "2.9.0".freeze
+  VERSION = "3.0.0".freeze
 end

data/lib/hecks.rb

@@ -12,6 +12,7 @@ require_relative "hecks/construct"
 # extends this to declare what it emits.
 require_relative "hecks/ir"
 require_relative "hecks/literal"
+require_relative "hecks/doors"
 require_relative "hecks/facade"
 require_relative "hecks/query_specification"
 
@@ -28,20 +29,22 @@ require_relative "hecks/projector"
 require_relative "hecks/projections"
 # After `Projector` (dispatches against the `:cli` projection) and
 # `Ports::Clock` (fills a staleness rule's `now` at the door) both exist.
-require_relative "hecks/facade/cli_door"
-require_relative "hecks/facade/cli_runner"
+require_relative "hecks/doors/cli_door"
+require_relative "hecks/doors/cli_runner"
 require_relative "hecks/storehouse"
 require_relative "hecks/mcp_stdio_guard"
-require_relative "hecks/mcp_door_scope"
+require_relative "hecks/doors/mcp_door_scope"
 require_relative "hecks/framework"
 require_relative "hecks/vendoring"
 require_relative "hecks/embryonaut_bluebook"
 
-# Repository-only tooling: the corpus table walks `examples/`, `qa/` and
-# `spec/`, which only a checkout has, so it loads on first use and the
-# packaged gem leaves it out (ADR 0066).
+# The corpus table walks `examples/`, `qa/` and `spec/`, which only a checkout
+# has, so it loads on first use.
 Hecks.autoload(:Corpus, File.expand_path("hecks/corpus", __dir__))
 
+# The chapters a hecksagon can `attaches` by name (ADR 0080); loads on first use.
+Hecks.autoload(:Chapters, File.expand_path("hecks/chapters", __dir__))
+
 # Root namespace and public facade of the DSL/runtime: `Hecks.boot`/`.boot_files`
 # assemble a running domain from `.bluebook`/`.hecksagon`/`.world` files.
 module Hecks
@@ -49,16 +52,28 @@ module Hecks
 
   class << self
     # Boots a domain from `path`, assembling a running dispatcher from its
-    # `.bluebook`/`.hecksagon`/`.world` files. hecks never reads ENV itself —
-    # a caller resolves its own env var name and passes it as `environment`.
+    # `.bluebook`/`.hecksagon`/`.world` files. `environment` defaults to
+    # the `HECKS_ENVIRONMENT` variable; pass a name to choose one, or `nil` for none.
     # @param path [String] path to a domain directory, or a file inside one
     # @param shared [String, nil] a shared-root override; see `Runtime::Loader.boot`
-    # @param install_facade [Boolean] install the `Widget::Item.Add`-style facade
+    # @param install_doors [Boolean] install the `Widget::Item.Add`-style facade
+    # @param install_facade [Boolean, nil] the deprecated spelling of `install_doors`; warns
     # @param environment [String, nil] env name; its `.hecksagon`/`.world` overlay,
-    #   if present, loads after the domain's own
+    #   if present, loads after the domain's own. Defaults to `HECKS_ENVIRONMENT`; nil loads none
     # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] dispatcher bound to the domain
-    def boot(path, shared: nil, install_facade: true, environment: nil)
-      Runtime.boot(path, shared: shared, install_facade: install_facade, environment: environment)
+    def boot(path, shared: nil, install_doors: true, install_facade: nil, environment: Runtime::Loader::FROM_ENV)
+      Runtime.boot(path, shared: shared, install_doors: install_doors, environment: environment,
+        install_facade: install_facade)
+    end
+
+    # Loads a domain's declarations without binding any adapter or opening any store.
+    #
+    # @param path [String] path to a domain directory, or a file inside one
+    # @param shared [String, nil] a shared-root override; see `Runtime::Loader.describe`
+    # @param environment [String, nil] env overlay; defaults to `HECKS_ENVIRONMENT`
+    # @return [Runtime::Loader::Described] the loaded registry, answering `registry`
+    def describe(path, shared: nil, environment: Runtime::Loader::FROM_ENV)
+      Runtime.describe(path, shared: shared, environment: environment)
     end
 
     # Boots a domain from an explicit list of files (a `.bluebook`, its
@@ -66,11 +81,13 @@ module Hecks
     # see `Runtime::Loader.boot_files` for why this exists beside `boot`.
     # @param paths [String, Array<String>] one or more file paths within the domain
     # @param shared [String, nil] a shared-root override; see `Runtime::Loader.boot_files`
-    # @param install_facade [Boolean] install the `Widget::Item.Add`-style facade
+    # @param install_doors [Boolean] install the `Widget::Item.Add`-style facade
+    # @param install_facade [Boolean, nil] the deprecated spelling of `install_doors`; warns
     # @param environment [String, nil] environment name passed to the selected-file loader
     # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] dispatcher bound to the domain
-    def boot_files(paths, shared: nil, install_facade: true, environment: nil)
-      Runtime.boot_files(paths, shared: shared, install_facade: install_facade, environment: environment)
+    def boot_files(paths, shared: nil, install_doors: true, install_facade: nil, environment: Runtime::Loader::FROM_ENV)
+      Runtime.boot_files(paths, shared: shared, install_doors: install_doors, environment: environment,
+        install_facade: install_facade)
     end
 
     # Binds the ambient registry for the duration of the block.

data/qa/settings.yml

@@ -0,0 +1,66 @@
+# Dials for the hecks_qa practice; edit values here and review the diff.
+# Meaning and rationale per key live in lib/hecks/quality_control/quality_control.bluebook;
+# loaded by Hecks::Fuzzing::QaSettings, which rejects missing, extra, or mistyped keys.
+#
+# automated_engineer stays a literal in the bluebook: spec/quality_control_spec.rb pins it.
+
+cadence_seconds: 0
+pr_cap_per_day: 0
+
+widening_tiers:
+  - { upto: 4,    seeds: 10, steps: 25 }
+  - { upto: 19,   seeds: 25, steps: 50 }
+  - { upto: .inf, seeds: 50, steps: 100 }
+
+sweep_max_parallel: 4
+liveness_fallback_seconds: 1500
+
+draft_only: false
+auto_merge: true
+branch_prefix: "qa/"
+
+adversarial_fraction: 0.3
+guided_generation: true
+corpus_splice_probability: 0.0
+favor_rare_verbs: 3
+self_consistency_checks: true
+shrink_budget: 200
+
+yield_weight_seconds: 1800
+yield_decay_percent: 50
+rotation_stale_floor_seconds: 21600
+
+persistence_parity_seed_cap: 5
+concurrency_seed_cap: 3
+
+adapter_parity_pairs:
+  persistence_parity:
+    left: memory
+    right: postgres_era
+  adapter_parity_sqlite:
+    left: memory
+    right: sqlite
+
+modes:
+  differential: true
+  ruby_only: true
+  self_consistency: true
+  properties_in_differential: true
+  structural_skip_report: true
+  adapter_parity_sqlite: false
+  persistence_parity: true
+  adapter_parity_postgres: false
+  era_boundary: false
+  concurrency: false
+  wasm_front: false
+
+role_draw_probability: 0.25
+dry_run_fraction: 0.10
+
+generated_domains_per_tick: 2
+generated_domains_rust: true
+generated_domain_seeds: 5
+
+# Construct families a sweep may skip. Shrink-only: spec/fuzzing/rust_gap_manifest_spec.rb fails
+# when a family here is not declared `generated: false` by a committed manifest.
+structural_refusal_boundary: []

data/rust/.cargo/config.toml

@@ -0,0 +1,6 @@
+# Links the main crate (rust/src/generated/, built by most ci.yml jobs) with lld.
+# It has no native C dependencies, so lld has nothing to trip over.
+#
+# Applies only when building for the linux target; a local macOS build never matches.
+[target.x86_64-unknown-linux-gnu]
+rustflags = ["-C", "link-arg=-fuse-ld=lld"]

data/rust/.gitignore

@@ -0,0 +1,2 @@
+/target
+/dist

data/rust/Cargo.lock

@@ -0,0 +1,54 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "regex"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "rust"
+version = "0.1.0"
+dependencies = [
+ "regex",
+]

data/rust/Cargo.toml

@@ -0,0 +1,61 @@
+# Selects which domain's generated module `generated::active` re-exports
+# (rust/src/generated/mod.rs); hecks project_rust adds an entry per generated
+# domain and never removes one, since a domain's own directory is the
+# source of truth for whether it still exists. `default` tracks whichever
+# domain was generated most recently; any other stays reachable via
+# `--no-default-features --features <name>`.
+[features]
+default = ["read_model_on_target_fixture"]
+composite_line_ledger = []
+read_model_on_target_fixture = []
+group_by_collision_fixture = []
+compliance = []
+checkout_fixture = []
+embryonaut_vendoring_demo = []
+generated_route_append = []
+generated_entity_no_identity = []
+generated_revalued_shape = []
+generated_reaction_wording = []
+bug28_existence_fixture = []
+lease_clock = []
+referral_chain = []
+tenant_ledger = []
+corrections = []
+has_many_fixture = []
+ledger_ordering = []
+waybill = []
+nested_pieces = []
+chess = []
+roster = []
+meta = []
+pizzas = []
+banking = []
+
+[package]
+name = "rust"
+version = "0.1.0"
+edition = "2021"
+
+# The one dependency exception to this crate's zero-Cargo-dependency
+# discipline (ADR 0012): `expression_operators/pattern_match.rs`'s `.match?`
+# needs a real, audited regex engine. `default-features = false` keeps out
+# the SIMD-driven `perf` feature; `std`/`unicode` alone cover the Ruby-
+# Regexp-style `\d`/`\w`/case-insensitive matching this grammar's own
+# predicates use.
+[dependencies]
+regex = { version = "1", default-features = false, features = ["std", "unicode"] }
+
+[lib]
+name = "rust"
+path = "src/lib.rs"
+
+[[bin]]
+name = "rust"
+path = "src/main.rs"
+
+# CI runs every binary this crate produces once and throws it away, never
+# attaching a debugger, so the debuginfo a plain `cargo build`/`cargo test`
+# normally embeds is pure build time and disk cost with nothing reading it.
+# Only this dev profile is affected; release builds are unchanged.
+[profile.dev]
+debug = 0

data/rust/build/.cargo/config.toml

@@ -0,0 +1,3 @@
+# Link with lld; this crate has no native C library dependencies.
+[target.x86_64-unknown-linux-gnu]
+rustflags = ["-C", "link-arg=-fuse-ld=lld"]

data/rust/build/.gitignore

@@ -0,0 +1 @@
+/target

data/rust/build/Cargo.lock

@@ -0,0 +1,7 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "hecks_build"
+version = "0.1.0"

data/rust/build/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "hecks_build"
+version = "0.1.0"
+edition = "2021"
+
+# Empty table makes this crate its own workspace root (own target/ and Cargo.lock).
+# Kept out of rust/src/ so this build-time orchestrator does not inflate the shipped artifacts.
+[workspace]
+
+[[bin]]
+name = "hecks-build"
+path = "src/main.rs"
+
+# No dependencies beyond std: this crate only shells out and never ships in a deployed artifact.
+[dependencies]
+
+# Debug info is off: CI binaries are run once and never attached to a debugger.
+[profile.dev]
+debug = 0

data/rust/build/src/build_artifact.rs

@@ -0,0 +1,47 @@
+//! Runs `cargo build` for the generated domain crate, native or WASM.
+
+use std::path::Path;
+
+use crate::subprocess;
+
+/// Runs `cargo build --release` in `rust_dir`, building the `default` feature that
+/// `cargo_sync::run` just set.
+pub fn build_native(rust_dir: &Path) -> Result<(), String> {
+    println!("== cargo build --release (native) ==");
+    subprocess::run_in(rust_dir, "cargo", &["build", "--release"])
+}
+
+/// Cross-compiles to `wasm32-wasip1` and copies the `.wasm` plus its `ir.json` sidecar
+/// into `rust/dist/`.
+///
+/// Builds through `rustup run stable cargo`: a Homebrew `cargo` earlier on the path never
+/// saw `rustup target add` and fails opaquely.
+pub fn build_wasm(root: &Path, rust_dir: &Path, target_mod_name: &str) -> Result<(), String> {
+    let installed = subprocess::run_capture("rustup", &["target", "list", "--installed"])
+        .map_err(|e| format!("checking installed rustup targets: {e}"))?;
+    if !installed.lines().any(|l| l.trim() == "wasm32-wasip1") {
+        return Err(
+            "wasm32-wasip1 isn't installed for this toolchain (environment limitation, not a code bug) — install it once with:\n\n    rustup target add wasm32-wasip1\n\nthen re-run hecks-build --wasm.".to_string(),
+        );
+    }
+
+    println!("== cargo build --release --target wasm32-wasip1 (via rustup run stable) ==");
+    subprocess::run_in(rust_dir, "rustup", &["run", "stable", "cargo", "build", "--release", "--target", "wasm32-wasip1"])?;
+
+    let dist_dir = root.join("rust/dist");
+    std::fs::create_dir_all(&dist_dir).map_err(|e| format!("creating {}: {e}", dist_dir.display()))?;
+
+    let built = rust_dir.join("target/wasm32-wasip1/release/rust.wasm");
+    let out = dist_dir.join(format!("{target_mod_name}.wasm"));
+    std::fs::copy(&built, &out).map_err(|e| format!("copying {} to {}: {e}", built.display(), out.display()))?;
+    println!("wrote {}", out.display());
+
+    let ir_json = root.join("rust/src/generated").join(target_mod_name).join("ir.json");
+    if ir_json.is_file() {
+        let ir_out = dist_dir.join(format!("{target_mod_name}.ir.json"));
+        std::fs::copy(&ir_json, &ir_out).map_err(|e| format!("copying {} to {}: {e}", ir_json.display(), ir_out.display()))?;
+        println!("wrote {}", ir_out.display());
+    }
+
+    Ok(())
+}