hecks 3.9.1 → 3.11.0

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module SiteRoutes
+      # The editor's files, written under the `--editor` directory when the project declares an
+      # `Editor` row.
+      module EditorFiles
+        # @param editor [String] the directory the files are written under
+        # @param project [String] the project directory; the row's `domain` is relative to it
+        # @param site [Site] the project's route-table chapter, checked table and registry
+        # @return [Hash{String => String}] each file's absolute path to its text
+        # @raise [SystemExit] when `--editor` is named and the project declares no `Editor` row, or
+        #   the row names a domain or chapter that is not there
+        def editor_files(editor, project, site)
+          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?
+
+          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, name = setting.chapter)
+          domain_root = File.join(project, setting.domain)
+          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
+    end
+  end
+end

data/lib/hecks/tools/site_routes.rb

@@ -13,9 +13,11 @@ require_relative "../projections/site/admin_cms"
 require_relative "../projections/site/site_root"
 require_relative "../projections/site/site_host"
 require_relative "../projections/site/payload_driver"
+require_relative "../projections/site/cms_editor"
 require_relative "site_routes/cli"
 require_relative "site_routes/templates"
 require_relative "site_routes/root_files"
+require_relative "site_routes/editor_files"
 
 module Hecks
   module Tools
@@ -39,13 +41,14 @@ module Hecks
       EXTENSIONS = %w[ts mts].freeze
 
       USAGE = "usage: hecks site site_projection.project_site [<project>] [--out=<dir>] " \
-              "[--template=<file>] [--cms=<dir>] [--root=<dir>] [--extension=#{EXTENSIONS.join("|")}] [--check]".freeze
+              "[--template=<file>] [--cms=<dir>] [--root=<dir>] [--editor=<dir>] " \
+              "[--extension=#{EXTENSIONS.join("|")}] [--check]".freeze
 
       # The directory `ports/` and `adapters/` live under, loaded into every project's registry.
       LIB_HECKS = File.expand_path("..", __dir__)
 
       # The keywords `projection` takes, each nil until given.
-      Settings = Struct.new(:out, :template, :extension, :cms, :root_dir, keyword_init: true)
+      Settings = Struct.new(:out, :template, :extension, :cms, :root_dir, :editor, keyword_init: true)
 
       # A project's route-table chapter with its checked table and the registry it booted into.
       Site = Struct.new(:chapter, :table, :registry)
@@ -53,6 +56,7 @@ module Hecks
       extend Cli
       extend Templates
       extend RootFiles
+      extend EditorFiles
 
       module_function
 
@@ -85,6 +89,7 @@ module Hecks
       #   `extension:` `ts` (the default) or `mts`, the module's file extension
       #   `cms:` the directory for the content system's half of the admin sign-in
       #   `root_dir:` the directory for the project's root files
+      #   `editor:` the directory for the content editor
       # @return [Hash{String => String}] each file's absolute path to the text it should hold
       # @raise [SystemExit] when the project declares no route table, the table is refused, or a
       #   path or the extension is refused
@@ -106,7 +111,7 @@ module Hecks
         written = route_files(dir, site, settings.extension)
         admin = Projections::Site::Admin.read(site.chapter, table: site.table)
         written.merge!(admin_files(dir, site.chapter, admin, settings.extension))
-        written.merge!(optional_files(settings, site.chapter, admin))
+        written.merge!(optional_files(settings, site, admin, root))
         written.merge(template_files(root, settings.out, site, template: settings.template))
       end
 
@@ -116,11 +121,13 @@ module Hecks
         renamed(dir, files, extension)
       end
 
-      # The content system's files and the project's root files, each when its flag was given.
-      def optional_files(settings, chapter, admin)
+      # The content system's files, the project's root files and the editor, each when its flag was
+      # given.
+      def optional_files(settings, site, admin, project)
         files = {}
-        files.merge!(cms_files(settings.cms, chapter, admin)) if settings.cms
-        files.merge!(root_files(settings.root_dir, chapter)) if settings.root_dir
+        files.merge!(cms_files(settings.cms, site.chapter, admin)) if settings.cms
+        files.merge!(root_files(settings.root_dir, site.chapter)) if settings.root_dir
+        files.merge!(editor_files(settings.editor, project, site)) if settings.editor
         files
       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.9.1".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

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

@@ -0,0 +1,50 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # Flags one method that reads the same receiver by `[:name]` and by `["name"]`.
+      #
+      # A hash is symbol-keyed under one persistence adapter and string-keyed under another, so a
+      # method that reaches for both is guessing which one it was handed. Read it through
+      # `Hecks::IndifferentKey.read` so the guess is made in one place that honors a stored `false`.
+      #
+      # @example
+      #   settings.key?(:era) ? settings[:era] : settings["era"]  # bad
+      #   IndifferentKey.read(settings, :era)                     # good
+      class SymbolStringKeyMix < Base
+        MSG = "`%<receiver>s[:%<name>s]` and `%<receiver>s[\"%<name>s\"]` are both read here, so this " \
+              "method guesses whether the hash is symbol- or string-keyed. Read it through one " \
+              "helper, or normalize the keys once at the boundary.".freeze
+
+        # @!method keyed_read(node)
+        def_node_matcher :keyed_read, "(send $_receiver :[] ({sym str} $_name))"
+
+        # Flags the string-keyed read when the same name is also read by symbol.
+        #
+        # @param node [RuboCop::AST::DefNode] the method being visited
+        # @return [void]
+        def on_def(node)
+          reads = node.each_descendant(:send).filter_map { |send| read_of(send) }
+          reads.group_by { |read| read.values_at(:receiver, :name) }.each_value do |group|
+            report(group) if group.map { |read| read[:type] }.uniq.size > 1
+          end
+        end
+        alias on_defs on_def
+
+        private
+
+        def read_of(send)
+          receiver, name = keyed_read(send)
+          return unless receiver
+
+          { receiver: receiver.source, name: name.to_s, type: send.first_argument.type, node: send }
+        end
+
+        def report(group)
+          string_read = group.find { |read| read[:type] == :str }
+          message = format(MSG, receiver: string_read[:receiver], name: string_read[:name])
+          add_offense(string_read[:node], message: message)
+        end
+      end
+    end
+  end
+end