hecks 3.10.0 → 3.11.0

data/lib/hecks/storehouse.rb

@@ -3,8 +3,8 @@ require "json"
 require "fileutils"
 require "time"
 require_relative "cache_dir"
-require_relative "doors/command_request"
-require_relative "doors/json_door"
+require_relative "adapters/driving/command_request"
+require_relative "adapters/driving/json"
 require_relative "naming"
 require_relative "projector"
 require_relative "runtime/errors"
@@ -55,7 +55,7 @@ module Hecks
             "own root (HECKS_STOREHOUSE_ROOT to widen it)"
     end
 
-    # The one bluebook this runtime booted; every whole-domain door assumes
+    # The one bluebook this runtime booted; every whole-domain entry point assumes
     # the same one-bluebook-per-boot shape.
     # :nodoc:
     def bluebook_for(runtime)
@@ -137,7 +137,7 @@ module Hecks
     def audit_fields(request) = request.to_h.slice(:summary, :source, :role, :actor_id)
 
     # dry_run? (Runtime::Dispatcher) only understands the pre-envelope flat
-    # args shape; this is the one door back into it from dispatch's own envelope.
+    # args shape; this is the one entry point back into it from dispatch's own envelope.
     # :nodoc:
     def flatten_legacy(envelope, receiver, legacy_receiver)
       facts = envelope[:with] || {}

data/lib/hecks/tools/comment_style/source_file.rb

@@ -14,6 +14,9 @@ module Hecks
     module CommentStyle
       # One parsed source file and the violations found in it.
       class SourceFile
+        # Raised when an automatic fix would change code rather than comments.
+        class Error < RuntimeError; end
+
         include LongBlocks
         include Masking
         include CapsWords
@@ -51,7 +54,7 @@ module Hecks
           return @source if output == @source
 
           unchanged = CommentStyle.code_tokens(@source) == CommentStyle.code_tokens(output)
-          raise "#{path}: fix would change code, refusing" unless unchanged
+          raise Error, "#{path}: fix would change code, refusing" unless unchanged
 
           output
         end

data/lib/hecks/tools/deploy_recipe_lint/fixtures.rb

@@ -9,6 +9,9 @@ module Hecks
     module DeployRecipeLint
       # Generated fixture domains for the deploy generator, so the lint has real Makefiles to read.
       module Fixtures
+        # Raised when a deploy fixture cannot be generated.
+        class Error < RuntimeError; end
+
         # The fixture's bluebook, where `__NAME__` stands for the domain's name.
         FIXTURE_BLUEBOOK = <<~BLUEBOOK
           Hecks.bluebook "__NAME__" do
@@ -59,7 +62,7 @@ module Hecks
           Dir.mktmpdir do |dir|
             domain_dir = write_fixture(dir, basename, world_body, env_local: env_local)
             outcome = Hecks::Adapters::ConsoleCapture.capture { DeployRecipe.main([domain_dir], root: root) }
-            outcome.ok? or raise "hecks deploy project failed generating the #{basename} fixture: #{outcome.output}"
+            outcome.ok? or raise Error, "hecks deploy project failed generating the #{basename} fixture: #{outcome.output}"
           end
           File.join(root, "deploy", basename)
         end

data/lib/hecks/tools/lanes/rows.rb

@@ -29,9 +29,15 @@ module Hecks
           return "#{name} has guarded #{lane["guarded"].inspect}" unless %w[yes no].include?(lane["guarded"])
           return "#{name} has alert_after #{lane["alert_after"].inspect}, not whole hours" unless hours?(lane)
 
+          return "#{name} has release_trailer #{lane["release_trailer"].inspect}, not a trailer word" unless trailer?(lane)
+
           follows_problem(lane, names)
         end
 
+        # @return [Boolean] whether `release_trailer` is empty (nothing is released from the lane)
+        #   or a git trailer key such as `Release-Approved-By`
+        def trailer?(lane) = lane["release_trailer"].to_s.match?(/\A([A-Za-z][A-Za-z0-9]*(-[A-Za-z0-9]+)*)?\z/)
+
         # @return [Boolean] whether `alert_after` is empty (never late) or whole hours
         def hours?(lane) = lane["alert_after"].to_s.match?(/\A\d*\z/)
 

data/lib/hecks/tools/oidc_manifests.rb

@@ -10,9 +10,8 @@ module Hecks
     #
     # A domain that has no bluebook is skipped and one that cannot be projected is reported, so a
     # sweep over the whole checkout carries on past either. `hecks deploy
-    # oidc_manifest.project_oidc` loads
-    # `bundler/setup` first, which pins the `json` gem: newer releases pretty-print an empty array
-    # as `[\n\n]`, a diff spec/oidc_manifest_spec.rb would report as drift.
+    # oidc_manifest.project_oidc` writes through `Hecks::Projections::OIDC.render`, which spells an
+    # empty list `[]` whichever json release is loaded, so the text does not depend on the machine.
     module OidcManifests
       # Directories that hold a `.hecksagon` but are never domains.
       NOT_DOMAINS = %r{\A(rust|deploy|tmp|coverage)/}
@@ -50,7 +49,7 @@ module Hecks
       # @param path [String] a domain directory, relative to `root`
       # @return [void]
       def project(root, path)
-        runtime = Hecks.boot(File.join(root, path), install_doors: false)
+        runtime = Hecks.boot(File.join(root, path), install_driving: false)
         name    = runtime.registry.bluebooks.keys.first
         return warn("  #{path}: no bluebook found — skipped") unless name
 
@@ -65,7 +64,7 @@ module Hecks
       # @param out [String] where the manifest goes
       # @return [void]
       def write_manifest(registry, name, out)
-        Hecks::Projector.write(Hecks::Projector.call(:oidc, bluebook: registry.bluebook(name)), out)
+        File.write(out, Hecks::Projections::OIDC.render(Hecks::Projector.call(:oidc, bluebook: registry.bluebook(name))))
       end
     end
   end

data/lib/hecks/tools/regeneration_run.rb

@@ -8,13 +8,13 @@ require_relative "../corpus"
 
 module Hecks
   module Tools
-    # Regenerates every corpus domain's committed Rust output with `hecks project_rust`, or checks
-    # that the committed output is what a regeneration would write.
+    # Regenerates every corpus domain's Rust output with `hecks project_rust`, or checks that the
+    # output on disk is what that would write. Only pizzas, `mod.rs` and `Cargo.toml` are committed.
     #
     # The domain list comes from `Hecks::Corpus.rust_regen_order`, never a hand-kept list. The
     # order is fixed (sorted by relative path): domains that share governance/, identity/,
-    # Cargo.toml and generated/mod.rs stamp them with whichever ran last, so it must not flap. If
-    # the domain set or the sort rule changes, re-run and commit the output; never hand-edit stamps.
+    # Cargo.toml and generated/mod.rs stamp them with whichever ran last, so it must not flap.
+    # If the domain set or the sort rule changes, re-run and commit what changed.
     #
     #   hecks regenerate_corpus         # discover, regenerate, print the plan
     #   hecks regenerate_corpus --check # regenerate into a scratch crate; fail on any difference
@@ -27,6 +27,11 @@ module Hecks
                    "wrong directory, or something upstream deleted rust/src/generated/ entirely. Refusing " \
                    "to silently treat that as \"nothing to regenerate.\""
 
+      # The refusal when a check finds nothing generated to compare.
+      NOT_MATERIALIZED = "hecks regenerate_corpus --check: rust/src/generated has no generated output to compare. " \
+                         "Only pizzas, mod.rs and Cargo.toml are committed; run " \
+                         "`hecks regenerate_corpus --confirm` first, then the check."
+
       module_function
 
       # Regenerates the corpus, or checks it.
@@ -147,6 +152,8 @@ module Hecks
       # @param root [String] the checkout
       # @return [String] the scratch directory
       def scratch_crate(root)
+        abort NOT_MATERIALIZED unless File.directory?(File.join(root, "rust/src/generated/meta"))
+
         scratch = Dir.mktmpdir("regen-codegen-check")
         FileUtils.mkdir_p(File.join(scratch, "src"))
         FileUtils.cp_r(File.join(root, "rust/src/generated"), File.join(scratch, "src/generated"))

data/lib/hecks/tools/site_routes/editor_files.rb

@@ -18,18 +18,25 @@ module Hecks
           setting = Projections::Site::CmsEditor::Setting.read(site.chapter, table: site.table)
           abort "project_site: --editor names #{editor}, but the project declares no Editor row" if setting.nil?
 
-          options = { domain_chapter: domain_chapter(project, setting), table: site.table }
-          files = Projector.call(:site_cms_editor, bluebook: site.chapter, options: options)
+          files = Projector.call(:site_cms_editor, bluebook: site.chapter, options: options(project, setting, site))
           files.to_h { |name, text| [File.join(File.expand_path(editor), name), text] }
         rescue ArgumentError, Projections::Site::Table::Invalid => e
           abort "project_site: #{e.message}"
         end
 
+        # @return [Hash{Symbol => Object}] the chapters the editor reads, and the route table
+        def options(project, setting, site)
+          chosen = { domain_chapters: setting.chapters.map { |name| domain_chapter(project, setting, name) }, table: site.table }
+          chosen[:media_chapter] = domain_chapter(project, setting, setting.media_chapter) if setting.media_chapter
+          chosen
+        end
+
+        # @param name [String] the chapter to find; the row's first `chapter` unless given
         # @return [Bluebook::Chapter] the chapter the `Editor` row names, from its domain directory
-        def domain_chapter(project, setting)
+        def domain_chapter(project, setting, name = setting.chapter)
           domain_root = File.join(project, setting.domain)
-          chapter = registry_for(domain_root).bluebooks.values.find { |candidate| candidate.name == setting.chapter }
-          abort "project_site: #{domain_root} declares no chapter #{setting.chapter}" unless chapter
+          chapter = registry_for(domain_root).bluebooks.values.find { |candidate| candidate.name == name }
+          abort "project_site: #{domain_root} declares no chapter #{name}" unless chapter
           chapter
         end
       end

data/lib/hecks/tools/tenant_provisioning.rb

@@ -80,7 +80,7 @@ module Hecks
       # @raise [SystemExit] when the declared shape is refused, or provisioning is refused
       def provision(slug, options, domain_directory)
         lib_hecks  = File.expand_path("..", __dir__)
-        dispatcher = Hecks.boot_files(CHAPTER_FILES.map { |file| File.join(lib_hecks, file) }, install_doors: false)
+        dispatcher = Hecks.boot_files(CHAPTER_FILES.map { |file| File.join(lib_hecks, file) }, install_driving: false)
         provision_tenant(dispatcher, slug, tenant_facts(slug, options, domain_directory))
         refuse_if_refused(dispatcher, slug)
 
@@ -126,7 +126,7 @@ module Hecks
       # @return [void]
       # @raise [SystemExit] when the tenant was never registered in Tenancy
       def confirm(dispatcher, slug, options, domain_directory)
-        target = Hecks.boot(domain_directory, environment: slug, install_doors: false)
+        target = Hecks.boot(domain_directory, environment: slug, install_driving: false)
         puts "booted #{options[:domain]} for tenant #{slug.inspect} under realm #{options[:realm].inspect}"
 
         refuse_unless_tenant_capable(target.registry)

data/lib/hecks/tools/tools_doc.rb

@@ -177,7 +177,7 @@ module Hecks
       class Context
         # @param root [String] the checkout
         def initialize(root)
-          @runtime = Hecks.boot(File.join(root, "lib/hecks/hecks"), install_doors: false)
+          @runtime = Hecks.boot(File.join(root, "lib/hecks/hecks"), install_driving: false)
           @projections = {}
         end
 
@@ -201,8 +201,8 @@ module Hecks
 
         def projection(chapter)
           @projections[chapter] ||= begin
-            launcher = Doors::LauncherOptions.settings(@runtime, chapter)
-            options = Doors::LauncherOptions.projection(launcher, "hecks")
+            launcher = Adapters::Driving::LauncherOptions.settings(@runtime, chapter)
+            options = Adapters::Driving::LauncherOptions.projection(launcher, "hecks")
             Projector.call(:cli, bluebook: @runtime.registry.bluebook(chapter), options: options)
           end
         end
@@ -210,7 +210,7 @@ module Hecks
         # `hecks ir`, `hecks console`, `hecks quality_control sweep.run`, `hecks host.check_era`.
         # The launcher takes a name that is only a query as a query, so no `query` word is needed.
         def words(chapter, name, row)
-          route = route_for(Doors::LauncherOptions.settings(@runtime, chapter) || {}, chapter, name, row)
+          route = route_for(Adapters::Driving::LauncherOptions.settings(@runtime, chapter) || {}, chapter, name, row)
           return [route] if route
 
           [*(Naming.snake(chapter) unless chapter == "Hecks"), name]

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 = "3.10.0".freeze
+  VERSION = "3.11.0".freeze
 end

data/lib/hecks/vocabulary.rb

@@ -107,8 +107,8 @@ module Hecks
         {"type"=>"String", "strategy"=>"substring"}.freeze
       ].freeze,
       "Lane" => [
-        {"name"=>"main", "guarded"=>"no", "pushers"=>"anyone", "feeds"=>"", "follows"=>"", "alert_after"=>""}.freeze,
-        {"name"=>"stable", "guarded"=>"yes", "pushers"=>"green", "feeds"=>"edge", "follows"=>"main", "alert_after"=>"4"}.freeze
+        {"name"=>"main", "guarded"=>"no", "pushers"=>"anyone", "feeds"=>"", "follows"=>"", "alert_after"=>"", "release_trailer"=>""}.freeze,
+        {"name"=>"stable", "guarded"=>"yes", "pushers"=>"green", "feeds"=>"edge", "follows"=>"main", "alert_after"=>"4", "release_trailer"=>"Release-Approved-By"}.freeze
       ].freeze,
       "LoadOrder" => [
         {"glob"=>"*.port"}.freeze,
@@ -402,8 +402,8 @@ module Hecks
         {"script"=>"compact", "section"=>"Custodian", "aggregate"=>"Era", "verb"=>"compact"}.freeze,
         {"script"=>"heki_compact", "section"=>"Custodian", "aggregate"=>"Era", "verb"=>"compact_heki"}.freeze,
         {"script"=>"vendor_bluebook", "section"=>"Custodian", "aggregate"=>"Package", "verb"=>"vendor", "note"=>"waits: a refusal exits 1 with its reason on stderr"}.freeze,
-        {"script"=>"project_cli", "section"=>"Custodian", "aggregate"=>"Door", "verb"=>"project_cli"}.freeze,
-        {"script"=>"hecks_mcp_door", "section"=>"Custodian", "aggregate"=>"Door", "verb"=>"serve_mcp"}.freeze,
+        {"script"=>"project_cli", "section"=>"Custodian", "aggregate"=>"Launch", "verb"=>"project_cli"}.freeze,
+        {"script"=>"hecks_mcp_door", "section"=>"Custodian", "aggregate"=>"Launch", "verb"=>"serve_mcp"}.freeze,
         {"script"=>"project_rust", "section"=>"Custodian", "aggregate"=>"Build", "verb"=>"project_rust"}.freeze,
         {"script"=>"project_wasm", "section"=>"Custodian", "aggregate"=>"Build", "verb"=>"build_wasm"}.freeze,
         {"script"=>"project_host", "section"=>"Custodian", "aggregate"=>"Build", "verb"=>"build_host"}.freeze,

data/lib/hecks.rb

@@ -12,7 +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/adapters/driving"
 require_relative "hecks/query_specification"
 
 require_relative "hecks/ports"
@@ -27,13 +27,13 @@ require_relative "hecks/projector"
 # installation of them.
 require_relative "hecks/projections"
 # After `Projector`, which dispatches against the `:cli` projection.
-require_relative "hecks/doors/cli_door"
-require_relative "hecks/doors/usage_cache"
-require_relative "hecks/doors/cli_runner"
+require_relative "hecks/adapters/driving/cli"
+require_relative "hecks/adapters/driving/usage_cache"
+require_relative "hecks/adapters/driving/cli_runner"
 require_relative "hecks/storehouse"
 require_relative "hecks/mcp_stdio_guard"
-require_relative "hecks/doors/mcp_door_scope"
-require_relative "hecks/doors/mcp_guide_cache"
+require_relative "hecks/adapters/driving/mcp_scope"
+require_relative "hecks/adapters/driving/mcp_guide_cache"
 require_relative "hecks/framework"
 require_relative "hecks/vendoring"
 require_relative "hecks/embryonaut_bluebook"
@@ -56,12 +56,12 @@ module Hecks
     # 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_doors [Boolean] install the `Widget::Item.Add`-style facade
+    # @param install_driving [Boolean] install the `Widget::Item.Add`-style facade
     # @param environment [String, nil] env name; its `.hecksagon`/`.world` overlay,
     #   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_doors: true, environment: Runtime::Loader::FROM_ENV)
-      Runtime.boot(path, shared: shared, install_doors: install_doors, environment: environment)
+    def boot(path, shared: nil, install_driving: true, environment: Runtime::Loader::FROM_ENV)
+      Runtime.boot(path, shared: shared, install_driving: install_driving, environment: environment)
     end
 
     # Loads a domain's declarations without binding any adapter or opening any store.
@@ -78,10 +78,10 @@ module Hecks
     # once. See `Runtime::Loader.boot_described`.
     #
     # @param described [Runtime::Loader::Described] what `describe` answered
-    # @param install_doors [Boolean] install the `Widget::Item.Add`-style facade
+    # @param install_driving [Boolean] install the `Widget::Item.Add`-style facade
     # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] dispatcher bound to the domain
-    def boot_described(described, install_doors: true)
-      Runtime.boot_described(described, install_doors: install_doors)
+    def boot_described(described, install_driving: true)
+      Runtime.boot_described(described, install_driving: install_driving)
     end
 
     # Boots a domain from an explicit list of files (a `.bluebook`, its
@@ -89,11 +89,11 @@ 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_doors [Boolean] install the `Widget::Item.Add`-style facade
+    # @param install_driving [Boolean] install the `Widget::Item.Add`-style facade
     # @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_doors: true, environment: Runtime::Loader::FROM_ENV)
-      Runtime.boot_files(paths, shared: shared, install_doors: install_doors, environment: environment)
+    def boot_files(paths, shared: nil, install_driving: true, environment: Runtime::Loader::FROM_ENV)
+      Runtime.boot_files(paths, shared: shared, install_driving: install_driving, environment: environment)
     end
 
     # Binds the ambient registry for the duration of the block.

data/lib/rubocop/cop/hecks/env_dump.rb

@@ -0,0 +1,69 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a secret leaving the process in output: the whole environment printed, or a
+      # `*_KEY` / `*_SECRET` / `*_TOKEN` / `*_PASSWORD` variable interpolated into a string.
+      #
+      # An interpolated secret ends up in a log line, a failure message or a command line. Reading
+      # one into a local (or an HTTP header) is fine; building a string around it is not. Restoring
+      # the environment in a spec (`saved = ENV.to_h`) is not output, so it is left alone.
+      #
+      # @example
+      #   puts ENV.to_h                                  # bad
+      #   warn "using #{ENV.fetch("API_TOKEN")}"         # bad
+      #   headers["Authorization"] = ENV.fetch("API_TOKEN")  # good
+      class EnvDump < Base
+        MSG_DUMP = "This prints the whole environment, which carries every secret the process holds. " \
+                   "Print only the variable names you need.".freeze
+        MSG_SECRET = "`%<read>s` is a secret read into a string, so it will land in a log line or a message. " \
+                     "Pass it straight to the call that needs it instead of interpolating it.".freeze
+
+        OUTPUT_CALLS = %i[puts p pp print warn].freeze
+        SECRET_NAME = /(KEY|SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIAL)/i
+
+        # @!method whole_env?(node)
+        def_node_matcher :whole_env?, <<~PATTERN
+          {(const {nil? cbase} :ENV) (send (const {nil? cbase} :ENV) {:to_h :to_a :to_s :inspect})}
+        PATTERN
+
+        # @!method env_read(node)
+        def_node_matcher :env_read, <<~PATTERN
+          (send (const {nil? cbase} :ENV) {:[] :fetch} (str $_) ...)
+        PATTERN
+
+        # Flags the whole environment handed to an output call.
+        #
+        # @param node [RuboCop::AST::SendNode] the call being visited
+        # @return [void]
+        def on_send(node)
+          return unless node.receiver.nil? && OUTPUT_CALLS.include?(node.method_name)
+          return unless node.arguments.any? { |argument| whole_env?(argument) }
+
+          add_offense(node, message: MSG_DUMP)
+        end
+
+        # Flags a secret variable interpolated into a string.
+        #
+        # @param node [RuboCop::AST::BeginNode] the `#{}` part being visited
+        # @return [void]
+        def on_begin(node)
+          return unless interpolation?(node)
+
+          read = node.children.filter_map { |child| secret_read(child) }.first
+          add_offense(node, message: format(MSG_SECRET, read: read)) if read
+        end
+
+        private
+
+        def interpolation?(node)
+          %i[dstr dsym xstr].include?(node.parent&.type)
+        end
+
+        def secret_read(node)
+          name = env_read(node)
+          node.source if name&.match?(SECRET_NAME)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/hecks/monotonic_duration.rb

@@ -0,0 +1,53 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a duration measured as `Time.now - start`, where `start` was read from the clock.
+      #
+      # The wall clock steps when it is corrected, so a subtraction can go negative or jump.
+      # Elapsed time comes from the monotonic clock. `Time.now - seconds` (a past timestamp)
+      # and `Time.now - File.mtime(path)` (an age against a stored time) are left alone.
+      #
+      # @example
+      #   started = Time.now
+      #   elapsed = Time.now - started                                         # bad
+      #
+      #   started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      #   elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started  # good
+      class MonotonicDuration < Base
+        MSG = "`Time.now - %<start>s` measures elapsed time on the wall clock, which can step. " \
+              "Take both ends from `Process.clock_gettime(Process::CLOCK_MONOTONIC)`.".freeze
+
+        # @!method wall_clock_minus_variable(node)
+        def_node_matcher :wall_clock_minus_variable, <<~PATTERN
+          (send #clock_read? :- ${lvar ivar})
+        PATTERN
+
+        # @!method clock_read?(node)
+        def_node_matcher :clock_read?, <<~PATTERN
+          {(send (const {nil? cbase} :Time) :now) (send (send (const {nil? cbase} :Time) :now) :to_f)}
+        PATTERN
+
+        # Flags `Time.now - <variable>` when the variable holds an earlier clock read.
+        #
+        # @param node [RuboCop::AST::SendNode] the subtraction being visited
+        # @return [void]
+        def on_send(node)
+          start = wall_clock_minus_variable(node)
+          return unless start && assigned_from_clock?(node, start)
+
+          add_offense(node, message: format(MSG, start: start.source))
+        end
+
+        private
+
+        # Whether the variable is assigned a clock read anywhere in the enclosing method or class.
+        def assigned_from_clock?(node, variable)
+          scope = node.each_ancestor(:def, :defs, :class, :module).first || processed_source.ast
+          scope.each_descendant(:lvasgn, :ivasgn).any? do |assignment|
+            assignment.name == variable.children.first && clock_read?(assignment.expression)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/hecks/no_wall_clock_in_runtime.rb

@@ -0,0 +1,34 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a direct wall-clock read (`Time.now`, `Date.today`, `Time.current`) in the runtime.
+      #
+      # The runtime must stay replayable (ADR 0081), so time reaches a command through `needs :now`
+      # or through the one stamping seam, `Hecks::Runtime::Event.stamp`; a stray read makes a
+      # replay differ from the original run and cannot be pinned in a test.
+      #
+      # @example
+      #   Event.new(name: n, occurred_at: Time.now.utc.iso8601)  # bad
+      #   Event.new(name: n, occurred_at: Event.stamp)           # good
+      class NoWallClockInRuntime < Base
+        MSG = "`%<call>s` reads the wall clock inside the runtime, so a replay cannot reproduce it. " \
+              "Declare `needs :now` on the command, or stamp an event with `Hecks::Runtime::Event.stamp`.".freeze
+
+        # @!method wall_clock_read?(node)
+        def_node_matcher :wall_clock_read?, <<~PATTERN
+          (send (const {nil? cbase} {:Time :Date :DateTime}) {:now :today :current})
+        PATTERN
+
+        # Flags a `Time.now`-style call.
+        #
+        # @param node [RuboCop::AST::SendNode] the call being visited
+        # @return [void]
+        def on_send(node)
+          return unless wall_clock_read?(node)
+
+          add_offense(node, message: format(MSG, call: node.source))
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/hecks/raw_shell_interpolation.rb

@@ -0,0 +1,79 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a shell command built by interpolating a value into one string.
+      #
+      # `system("rm -rf #{dir}")` hands the shell a string it re-parses, so a value with a space
+      # or a metacharacter changes the command. The array form (`system("rm", "-rf", dir)`)
+      # passes each argument as-is. An interpolation wrapped in `Shellwords.escape` or
+      # `shellescape` is left alone.
+      #
+      # @example
+      #   system("git checkout #{branch}")         # bad
+      #   system("git", "checkout", branch)        # good
+      class RawShellInterpolation < Base
+        MSG = "`%<call>s` runs a string with `\#{}` interpolated into it, so the shell re-parses the value. " \
+              "Pass the command as separate arguments (`%<call>s(\"cmd\", arg)`), or wrap the value in " \
+              "`Shellwords.escape`.".freeze
+
+        XSTR_MSG = "A backtick or `%x` command with `\#{}` interpolated into it is re-parsed by the shell. " \
+                   "Use `IO.popen([\"cmd\", arg], &:read)` or `Open3.capture2(\"cmd\", arg)`, or wrap the " \
+                   "value in `Shellwords.escape`.".freeze
+
+        SHELL_CALLS = %i[system exec spawn].freeze
+        OPEN3_CALLS = %i[capture2 capture2e capture3 popen2 popen2e popen3 pipeline pipeline_r pipeline_w
+                         pipeline_rw pipeline_start].freeze
+
+        # @!method open3_receiver?(node)
+        def_node_matcher :open3_receiver?, "(const {nil? cbase} :Open3)"
+
+        # @!method escaped?(node)
+        def_node_matcher :escaped?, <<~PATTERN
+          {(send (const {nil? cbase} :Shellwords) {:escape :shellescape :join :shelljoin} ...)
+           (send _ {:shellescape :shelljoin})}
+        PATTERN
+
+        # Flags a single-string command with a raw interpolation.
+        #
+        # @param node [RuboCop::AST::SendNode] the call being visited
+        # @return [void]
+        def on_send(node)
+          return unless shell_call?(node)
+
+          command = command_argument(node)
+          return unless command&.dstr_type? && raw_interpolation?(command)
+
+          add_offense(node, message: format(MSG, call: node.method_name))
+        end
+
+        # Flags a backtick or `%x` literal with a raw interpolation.
+        #
+        # @param node [RuboCop::AST::StrNode] the command literal being visited
+        # @return [void]
+        def on_xstr(node)
+          return unless raw_interpolation?(node)
+
+          add_offense(node, message: XSTR_MSG)
+        end
+
+        private
+
+        def shell_call?(node)
+          return SHELL_CALLS.include?(node.method_name) if node.receiver.nil? || node.receiver.cbase_type?
+
+          open3_receiver?(node.receiver) && OPEN3_CALLS.include?(node.method_name)
+        end
+
+        # The lone command string, after an optional leading env hash; nil when it passes argv.
+        def command_argument(node)
+          args = node.arguments.drop_while(&:hash_type?)
+          args.first if args.size == 1
+        end
+
+        def raw_interpolation?(node)
+          node.each_child_node(:begin).any? { |part| !escaped?(part.children.first) }
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/hecks/sleep_in_spec.rb

@@ -0,0 +1,34 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a fixed `sleep` in a spec.
+      #
+      # A fixed sleep is a guess about how long another thread needs: too short and the example is
+      # flaky, too long and the suite is slow. Wait on the thing itself instead, with a Queue, a
+      # latch, or `ThreadParking.wait_until_parked(thread)` when the assertion is "still blocked".
+      #
+      # @example
+      #   sleep 0.2                                   # bad
+      #   ThreadParking.wait_until_parked(waiter)     # good
+      class SleepInSpec < Base
+        MSG = "A fixed `sleep` guesses how long another thread needs, so the example is either flaky or " \
+              "slow. Wait on the thread itself: a Queue, or `ThreadParking.wait_until_parked(thread)`.".freeze
+
+        RESTRICT_ON_SEND = %i[sleep].freeze
+
+        # @!method fixed_sleep?(node)
+        def_node_matcher :fixed_sleep?, <<~PATTERN
+          (send {nil? (const {nil? cbase} :Kernel)} :sleep ...)
+        PATTERN
+
+        # Flags a `sleep` call.
+        #
+        # @param node [RuboCop::AST::SendNode] the call being visited
+        # @return [void]
+        def on_send(node)
+          add_offense(node, message: MSG) if fixed_sleep?(node)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/hecks/swallowed_rescue.rb

@@ -0,0 +1,37 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags a broad `rescue` whose whole body is `nil`, `false` or `next`.
+      #
+      # A bare `rescue` or `rescue StandardError` that answers a literal turns any crash into an
+      # ordinary "no result". Rescuing a named error is left alone; a deliberate guard goes
+      # through `Hecks::Runtime::BestEffort.call(default) { ... }`.
+      #
+      # @example
+      #   adapter.capable? rescue false                           # bad
+      #   BestEffort.call(false) { adapter.capable? }             # good
+      class SwallowedRescue < Base
+        MSG = "This broad `rescue` answers `%<answer>s` for any failure, so a crash reads as an ordinary " \
+              "\"no result\". Rescue the specific error, or use `Runtime::BestEffort.call(default) { ... }` " \
+              "for a deliberate guard.".freeze
+
+        # @!method swallowed_answer(node)
+        def_node_matcher :swallowed_answer, <<~PATTERN
+          (resbody {nil? (array (const {nil? cbase} {:StandardError :Exception}))} _
+            ${(nil) (false) (next)})
+        PATTERN
+
+        # Flags a broad rescue clause that answers a bare literal.
+        #
+        # @param node [RuboCop::AST::ResbodyNode] the rescue clause being visited
+        # @return [void]
+        def on_resbody(node)
+          answer = swallowed_answer(node)
+          return unless answer
+
+          add_offense(node, message: format(MSG, answer: answer.source))
+        end
+      end
+    end
+  end
+end