hecks 2.8.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/vendoring/git_environment.rb

@@ -1,13 +1,7 @@
 module Hecks
   module Vendoring
-    # The environment a `git` subprocess needs so it resolves its repository
-    # from the directory it is pointed at, not from whoever launched Ruby.
-    #
-    # Git exports `GIT_DIR`, `GIT_INDEX_FILE` and their kin to the hooks it
-    # runs (a push from a linked worktree runs `pre-push` this way). Every
-    # `git` that a hook's process tree starts inherits them, and they outrank
-    # both `git -C` and the working directory: a command aimed at a scratch
-    # repository would read, or commit into, the repository that was pushing.
+    # The environment a `git` subprocess needs to target one repository:
+    # inherited GIT_DIR variables outrank `-C` and would redirect it elsewhere.
     module GitEnvironment
       # The variables that pin git to one repository, work tree or index.
       INHERITED = %w[

data/lib/hecks/vendoring/git_source.rb

@@ -4,14 +4,8 @@ require_relative "git_environment"
 
 module Hecks
   module Vendoring
-    # A local git repository read through the `git` executable, never through
-    # its working tree.
-    #
-    # Everything here names a commit and reads what that commit holds, so a
-    # shared checkout with uncommitted edits, or a different branch checked
-    # out, cannot leak into what gets vendored. Every command runs under
-    # {GitEnvironment.clean}, so a `GIT_DIR` inherited from a hook cannot
-    # redirect it to some other repository.
+    # Reads one commit of a local git repository via the `git` executable,
+    # under {GitEnvironment.clean} so an inherited `GIT_DIR` can't redirect it.
     class GitSource
       # @param path [String] a directory that is a git repository (or a
       #   worktree of one)
@@ -57,8 +51,8 @@ module Hecks
 
       # Lists the files directly inside a directory of a commit.
       #
-      # Subdirectories are left out on purpose: a vendored package carries the
-      # top-level files of its subtree and nothing nested beneath.
+      # Subdirectories are excluded on purpose; only the subtree's own
+      # top-level files are vendored.
       #
       # @param ref [String] the commit-ish to read from
       # @param subtree [String] a repository-relative directory, such as `"payments/bluebook"`

data/lib/hecks/vendoring.rb

@@ -5,29 +5,7 @@ require_relative "vendoring/git_source"
 
 module Hecks
   # Pins an exact commit of one directory of another repository into a
-  # project's own tree.
-  #
-  # ## What it is
-  #
-  # A project that consumes a package from a private repository cannot clone
-  # that repository when its image builds, and a live pull would make the build
-  # depend on whatever is checked out. So the files are exported from one
-  # commit, committed into the consumer, and a marker file beside them records
-  # which commit they came from. Only the files directly inside the named
-  # subtree are taken; the source's own specs, ports, adapters and data stay
-  # where they are.
-  #
-  # ## Marker
-  #
-  # `VENDORED_COMMIT` holds the full 40-character commit id and a newline, so
-  # `git -C <source> show <id>:<subtree>` reproduces the vendored files. The
-  # marker sits in `into`, beside the exported directory.
-  #
-  # ## Whole-directory replacement
-  #
-  # A pin replaces `into` entirely, so a file the source dropped does not
-  # linger. Nothing is touched until the export succeeded and the optional
-  # block accepted it.
+  # project's own tree, so a build doesn't depend on a live clone.
   module Vendoring
     # Raised when a pin cannot be made or is refused.
     class Error < StandardError; end
@@ -45,27 +23,17 @@ module Hecks
     #   @return [Array<String>] the exported files' names, sorted
     Pin = Struct.new(:commit, :dir, :files, keyword_init: true)
 
-    # Exports the top-level files of one directory at one commit into `into`.
-    #
-    # The exported files land in `into/<last segment of subtree>/`; the marker
-    # lands in `into` itself. The optional block sees the staged files before
-    # anything is replaced and may raise to refuse the pin.
+    # Exports the top-level files of one directory at one commit into `into`,
+    # replacing it wholly; the optional block may refuse before that happens.
     #
     # @param from [String] path of the local source repository
-    # @param ref [String] the commit-ish to export (branch, tag or commit id)
-    # @param subtree [String] repository-relative directory to export, such as
-    #   `"payments/bluebook"`
+    # @param ref [String] the commit-ish to export
+    # @param subtree [String] repository-relative directory to export
     # @param into [String] the directory to replace with the export
-    # @param glob [String] `File.fnmatch` pattern each exported file's name must match
+    # @param glob [String] pattern each exported file's name must match
     # @param marker [String] name of the file recording the commit
-    # @yield [staged, commit] the staged files, before `into` is touched
-    # @yieldparam staged [String] directory holding the exported files
-    # @yieldparam commit [String] the resolved commit id
-    # @yieldreturn [Hash{String => String}, nil] extra files to write into `into`,
-    #   keyed by file name; nil for none
     # @return [Pin] the commit and where the files landed
-    # @raise [Vendoring::Error] if the source is missing, `ref` names no commit,
-    #   the subtree holds no matching file, or the block refuses
+    # @raise [Vendoring::Error] if the source or a matching file is missing
     def self.pin(from:, ref:, subtree:, into:, glob: "*", marker: MARKER)
       source = GitSource.new(from)
       commit = source.commit(ref)
@@ -83,13 +51,6 @@ module Hecks
     end
 
     # Replaces `into` with the staged files, the marker and any extras.
-    #
-    # @param staged [String] directory holding the exported files
-    # @param into [String] the directory to replace
-    # @param marker [String] marker file name
-    # @param commit [String] commit id the marker records
-    # @param extras [Hash{String => String}] more files to write into `into`
-    # @return [void]
     def self.install(staged, into, marker, commit, extras)
       FileUtils.rm_rf(into)
       FileUtils.mkdir_p(into)

data/lib/hecks/version.rb

@@ -1,16 +1,5 @@
 module Hecks
-  # **Isolated, on purpose** — the gemspec reads this file directly rather
-  # than `require_relative "lib/hecks"` (the whole framework),
-  # specifically so evaluating the gemspec never triggers any of this
-  # gem's own dependencies (prism among them) before Bundler has even
-  # resolved what to install. A real, live chicken-and-egg bug caught
-  # deploying to a Ruby version that doesn't bundle prism for free
-  # (AWS Lambda's ruby3.2): the gemspec's own `require_relative
-  # "lib/hecks"` pulled in adapters/driven/prism.rb's
-  # unconditional `require "prism"`, which failed before Bundler ever
-  # read what the gemspec itself declared as a dependency — declaring
-  # it there, or even in the consuming Gemfile, never closed the gap,
-  # because gemspec evaluation happens before anything Bundler
-  # resolves is actually loadable yet.
-  VERSION = "2.8.0".freeze
+  # 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.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,81 +29,65 @@ 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 root namespace and public facade of the whole DSL/runtime: `Hecks.boot`/
-# `.boot_files` assemble a running domain from `.bluebook`/`.hecksagon`/
-# `.world` files, and `.bluebook`/`.hecksagon`/`.port`/`.adapter`/`.world`/
-# `.data_translation` are the top-level declaration words every such file
-# opens with, each collecting its built construct into the currently booting
-# Registry (`#collect`, private below).
+# 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
   class LoadOutsideBoot < StandardError; end
 
   class << self
-    # The loading words below collect into the registry the runtime is
-    # holding open ; booting and that ambient state belong to the runtime
-    # layer, so this module is their facade and Hecks::Runtime is where
-    # they live.
-    # `install_facade:` — see Runtime::Loader.boot. Defaults on; a caller
-    # that only dispatches by FQN string can skip the global sugar.
-    #
-    # `environment:` — recovered, not new: this parameter (and the
-    # `environments/<name>.hecksagon` / `.world` overlay it loads —
-    # see Adapters::Folder#load_domain) existed on a prior commit of
-    # this repo (933d1dd), was vendored out to a real consumer
-    # (a client site's domain), and was then lost from this repo's own
-    # history (no branch here reaches that commit). Ported forward
-    # from the consumer's vendor snapshot — the only surviving copy —
-    # and generalized: the original only loaded a `.hecksagon`
-    # overlay; this also loads a same-named `.world` overlay, both
-    # merged into the base rather than replacing it (Registry#add_hecksagon
-    # / #add_world). hecks never reads ENV itself — a caller
-    # resolves its own env var name and passes the resulting string
-    # straight through, e.g. `Hecks.boot(path, environment:
-    # ENV.fetch("MYAPP_ENV", "development"))`.
-    #
+    # Boots a domain from `path`, assembling a running dispatcher from its
+    # `.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] whether to install the `Widget::Item.Add`-style
-    #   Ruby facade constants for this boot
-    # @param environment [String, nil] the environment name whose
-    #   `environments/<name>.hecksagon`/`.world` overlay, if present, loads after the
-    #   domain's own
-    # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the dispatcher bound
-    #   to the booted domain
-    def boot(path, shared: nil, install_facade: true, environment: nil)
-      Runtime.boot(path, shared: shared, install_facade: install_facade, environment: environment)
+    # @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. 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, install_facade: nil, environment: Runtime::Loader::FROM_ENV)
+      Runtime.boot(path, shared: shared, install_doors: install_doors, environment: environment,
+        install_facade: install_facade)
     end
 
-    # `paths` — an explicit list of files to boot (a `.bluebook`, its
-    # `.hecksagon`, optionally a `.world`), loaded in place from wherever
-    # they actually live — see Runtime::Loader.boot_files's own header for
-    # why this exists beside `boot` rather than as a special case of it.
+    # 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
+    # `.hecksagon`, optionally a `.world`) instead of a whole directory —
+    # see `Runtime::Loader.boot_files` for why this exists beside `boot`.
     # @param paths [String, Array<String>] one or more file paths within the domain
-    #   to load, instead of the whole directory
     # @param shared [String, nil] a shared-root override; see `Runtime::Loader.boot_files`
-    # @param install_facade [Boolean] whether to install the `Widget::Item.Add`-style
-    #   Ruby facade constants for this boot
-    # @param environment [String, nil] the environment name passed through to the
-    #   selected-file loader
-    # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the dispatcher bound
-    #   to the booted domain
-    def boot_files(paths, shared: nil, install_facade: true, environment: nil)
-      Runtime.boot_files(paths, shared: shared, install_facade: install_facade, environment: environment)
+    # @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_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.
@@ -117,21 +102,8 @@ module Hecks
     # @return [Runtime::Registry, nil] the current registry, or nil outside a boot
     def current_registry = Runtime.current_registry
 
-    # Bind who is dispatching for the duration of the block — checked
-    # against a command's declared `role`, if it has one. Unbound (the
-    # default), a command's role stays exactly what it is without this:
-    # decoration.
-    #
-    # `actor_id` is optional — a caller naming only a role is checked by
-    # string equality against the command's own `role`, exactly as
-    # before. A caller that also names who it is lets the check run
-    # against a real Governance `RoleAssignment` instead, once the
-    # command's domain has Governance attached — see
-    # `CommandRules::Authorization`'s own header.
-    #
-    # `as_of` and `scope` are optional too, same shape — see
-    # `Runtime.as_caller`'s own header for what each does.
-    #
+    # Binds who is dispatching for the duration of the block, checked against
+    # a command's declared `role`; unbound (the default) is a no-op.
     # @param role [String, Symbol] the role to check the caller against
     # @param actor_id [String, nil] who is calling, checked against a real Governance
     #   `RoleAssignment` when given; string-equality only against `role` when nil
@@ -165,26 +137,16 @@ module Hecks
     # @return [Bluebook::Hecksagon] the built hecksagon
     # @raise [LoadOutsideBoot] if called outside `Hecks.boot`/`.boot_files`
     def hecksagon(name, &) = collect(:add_hecksagon, Bluebook::DSL::HecksagonBuilder.build(name, &))
-    # Repointed to DomainPortBuilder — the migration DomainPort's own
-    # class comment names as its goal, now landed for the top-level
-    # `.port` file callers too (the aggregate-scoped `Thing.port(...)`,
-    # binding_proxy.rb, already went through this builder). Every real
-    # `.port` file only ever spells `verb`/`signal` (no `.port` file
-    # declares operations — that's DomainPort's own newer shape), and
-    # DomainPortBuilder's own bare-verb branch produces the exact same
-    # `Port` object PortBuilder itself did (dsl_spec.rb's own byte-
-    # identity check) — a pure repoint, no behavior change for any
-    # existing caller reading `.verb`/`.signal` off what comes back.
+
+    # Declares a port — a `.port` file's top-level word.
+    #
+    # `legacy_bare_port: true` — only this entry point allows a completely
+    # empty port body; see `DomainPortBuilder#initialize`'s own doc.
     #
-    # `legacy_bare_port: true` — the one real semantic gap this repoint
-    # would otherwise open: `PortBuilder#build` never refused a
-    # completely empty build (no verb, no signal even), a real shape
-    # dsl_spec.rb's own "a port" tests exercise (`signal`-only, no
-    # `verb`). `DomainPortBuilder`'s own "declares no verb and no
-    # operations" refusal is real and correct for its other two callers
-    # (`BindingProxy#port`, `HecksagonBuilder#port_impl`) — only this,
-    # the literal top-level `.port` file entry point, keeps the older,
-    # looser rule (see `DomainPortBuilder#initialize`'s own comment).
+    # @param name [String] the port's name
+    # @yield the port's body, evaluated against a `Bluebook::DSL::DomainPortBuilder`
+    # @return [Bluebook::Port, Bluebook::DomainPort] the built port
+    # @raise [LoadOutsideBoot] if called outside `Hecks.boot`/`.boot_files`
     def port(name, &) = collect(:add_port, Bluebook::DSL::DomainPortBuilder.build(name, legacy_bare_port: true, &))
 
     # Declares an adapter — an `.adapter` file's top-level word.

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

@@ -1,55 +1,15 @@
 module RuboCop
   module Cop
     module Hecks
-      # Flags the exact shape behind 8+ real bugs already fixed one at a
-      # time across this codebase (Tiers 1-5): `holder[a] || holder[b]` —
-      # the same receiver looked up by two different keys, falling back to
-      # the second lookup whenever the first is falsy. `||` cannot tell a
-      # genuinely stored `false` from a missing key — both are falsy in
-      # Ruby — so a real `false` sitting at `holder[a]` is silently
-      # discarded and `holder[b]` (usually absent, so `nil`) is returned
-      # instead. Every one of those 8+ instances was the identical
-      # AST shape with a different pair of keys (most commonly
-      # `h[k.to_sym] || h[k]`, reading a value that could arrive keyed
-      # either by symbol or by string off the wire).
+      # Flags `holder[a] || holder[b]`: the same receiver looked up by two keys, falling back
+      # to the second when the first is falsy.
       #
-      # ## The fix
-      #
-      # The fix this codebase already converged on — see
-      # `lib/hecks/query_specification/field_path.rb#read`, the shared
-      # digger this whole bug class got consolidated behind: check
-      # `key?` first, never fall back through `||`.
-      #
-      #   sym = segment.to_sym
-      #   return current.key?(sym) ? current[sym] : current[segment]
-      #
-      # That method's own comment says it plainly: "`key?` first, never
-      # `||`, because `||` falls through a genuinely-stored `false` to
-      # the other spelling (usually absent) and returns `nil` instead."
-      # This cop exists so the next `holder[a] || holder[b]` gets caught
-      # mechanically, before it becomes bug #9, rather than found by
-      # hand again in a future audit.
-      #
-      # ## Scope
-      #
-      # Scoped to the `[]`/`[]` shape only, deliberately — a receiver
-      # method-call is compared by AST structure (`==`, which ignores
-      # source location), so `hash[a] || hash[b]` is flagged whether
-      # `hash` is a local variable, a method call, or a constant, but
-      # `a[k] || b[k]` (different receivers) and `value || default`
-      # (an ordinary default, not a second lookup at all) are both left
-      # alone — neither one can silently drop a stored `false` the way
-      # a same-receiver double-lookup can.
+      # `||` cannot tell a stored `false` from a missing key, so a real `false` at `holder[a]` is
+      # discarded. Different receivers (`a[k] || b[k]`) and plain defaults are left alone.
       #
       # @example
-      #   # bad — a stored `false` at hash[:active] is discarded
-      #   hash[:active] || hash["active"]
-      #
-      #   # good
-      #   hash.key?(:active) ? hash[:active] : hash["active"]
-      #
-      #   # good — or the shared digger this codebase already has
-      #   Hecks::QuerySpecification::FieldPath.dig(hash, "active")
+      #   hash[:active] || hash["active"]                      # bad
+      #   hash.key?(:active) ? hash[:active] : hash["active"]  # good
       class FallbackHashLookup < Base
         MSG = "`%<receiver>s[...] || %<receiver>s[...]` falls back to the second lookup " \
               "whenever the first is falsy — but `||` cannot tell a genuinely stored `false` " \
@@ -96,3 +56,5 @@ module RuboCop
     end
   end
 end
+
+# AST `==` ignores source location, so two parses of the same receiver compare equal.

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

@@ -1,67 +1,17 @@
 module RuboCop
   module Cop
     module Hecks
-      # Flags `hash[new] = hash.delete(old)` inside a loop — a method that
-      # both reads and writes the same hash across a loop's iterations,
-      # in the specific rename/permutation shape this codebase has
-      # already lost real data to once.
-      #
-      # ## The bug this follows up on
-      #
-      # The bug this is the mechanical follow-up to (M27,
-      # docs/audits/2026-08-10-main-bug-audit.md,
-      # docs/audits/2026-08-11-bug-triage.md; fixed in
-      # `Hecks::Ports::Persistence::Lineage#apply_renames`,
-      # lib/hecks/ports/persistence/plugins/era/lineage.rb): a rename
-      # rule set applied one rule at a time, `state[new_name] =
-      # state.delete(old_name)` per rule, against the same hash it was
-      # reading from — so a swap (`rename :a, to: :b` alongside `rename
-      # :b, to: :a`) on `{a: 1, b: 2}` collapsed to `{a: 1}`. The first
-      # rule wrote `b: 1` (clobbering the real `b: 2`) before the second
-      # rule ever got a chance to read the value that was supposed to
-      # move to `:a` — sequential edits stepping on each other, not the
-      # simultaneous permutation a rename set actually means. The same
-      # shape loses data identically for any chain longer than one link
-      # (`a->b->c->a`), not just a two-element swap.
-      #
-      # ## The fix this cop points at
-      #
-      # Snapshot every old key's value
-      # first, delete all old keys, then write all new keys, so no
-      # rename in the pass ever reads a key this same pass has already
-      # written:
-      #
-      #   snapshot = renames.filter_map { |old_name, new_name| [old_name, new_name, state[old_name]]
-      #   if state.key?(old_name) }
-      #   snapshot.each { |old_name, _new_name, _value| state.delete(old_name) }
-      #   snapshot.each { |_old_name, new_name, value| state[new_name] = value }
-      #
-      # ## What this cop does not attempt
-      #
-      # The general checklist item is
-      # broader than any AST pattern can safely automate ("any method
-      # that both reads and writes the same collection across a loop"
-      # covers plenty of correct code too — accumulating into a result
-      # hash, memoizing into a cache). This cop stays narrow and
-      # precise: only the exact `recv[x] = recv.delete(y)` shape, same
-      # receiver both sides, inside something that iterates. A single
-      # rename outside any loop is not this bug (nothing else can have
-      # run first); `hash.store(...)` instead of `hash[...] =`, or
-      # `hash.delete(...)` whose result is not immediately written back
-      # into the same hash, are not this shape either and are left to
-      # the broader code-review checklist item, not this cop.
+      # Flags `hash[new] = hash.delete(old)` inside a loop.
+      # Applying renames one at a time to the hash being read loses data on swaps and chains.
       #
       # @example
-      #   # bad — one rule at a time against the hash it reads from
-      #   renames.each do |old_name, new_name|
-      #     state[new_name] = state.delete(old_name)
-      #   end
+      #   # bad
+      #   renames.each { |old, new| state[new] = state.delete(old) }
       #
-      #   # good — snapshot first, then delete, then write: one permutation
-      #   snapshot = renames.filter_map { |old_name, new_name| [old_name, new_name, state[old_name]]
-      #   if state.key?(old_name) }
-      #   snapshot.each { |old_name, _new_name, _value| state.delete(old_name) }
-      #   snapshot.each { |_old_name, new_name, value| state[new_name] = value }
+      #   # good: snapshot the values, delete every old key, then write the new keys
+      #   pairs = renames.select { |old, _| state.key?(old) }.map { |old, new| [new, state[old]] }
+      #   renames.each_key { |old| state.delete(old) }
+      #   pairs.each { |new, value| state[new] = value }
       class SequentialHashRenameInLoop < Base
         MSG = "`%<recv>s[new] = %<recv>s.delete(old)` inside a loop applies one rename at a time against the " \
               "SAME hash it reads from — a swap (`{a: :b, b: :a}`) on `{a: 1, b: 2}` collapses to `{a: 1}` " \
@@ -78,22 +28,12 @@ module RuboCop
           inject reduce each_slice each_cons
         ].freeze
 
-        # `hash[new_name] = hash.delete(old_name)` parses as a `send`
-        # node (indexed assignment has no dedicated node type in Ruby's
-        # own grammar): `(send recv :[]= new_key (send recv2 :delete
-        # old_key))`. `$_recv`/`$_recv2` are captured (not merely
-        # matched) so `same_receiver?` below can compare them
-        # structurally — node-pattern has no built-in "same subtree
-        # twice" backreference, so the equality check is real Ruby, not
-        # the pattern itself.
+        # Indexed assignment parses as a `send`. Both receivers are captured because node-pattern
+        # has no backreference; `same_receiver?` compares them.
         def_node_matcher :rename_write?, <<~PATTERN
           (send $_recv :[]= _new_key (send $_recv2 :delete _old_key))
         PATTERN
 
-        # Flags a `recv[new] = recv.delete(old)` write inside a loop, same receiver both sides.
-        #
-        # @param node [RuboCop::AST::SendNode] the `[]=` send node being visited
-        # @return [void]
         def on_send(node)
           rename_write?(node) do |recv, recv2|
             next unless same_receiver?(recv, recv2)
@@ -105,20 +45,11 @@ module RuboCop
 
         private
 
-        # Structural equality (type + children, recursively) — exactly
-        # what `Parser::AST::Node#==` already gives, ignoring source
-        # location, so `state` vs `state` (two separate `send(nil,
-        # :state)` reader calls) and `@state` vs `@state` both count as
-        # "the same collection", not just an identical local variable.
         def same_receiver?(recv, recv2)
           recv == recv2
         end
 
-        # Walks every ancestor looking for something that iterates —
-        # not just the immediate parent, since the offending assignment
-        # may sit one or more non-loop nodes deep inside a loop's block
-        # (an `if` guarding it, say) and still carries the exact same
-        # hazard.
+        # Checks every ancestor: a guard node may sit between the assignment and the loop block.
         def in_loop?(node)
           node.each_ancestor(:block, :numblock, :for, :while, :until, :while_post, :until_post).any? do |ancestor|
             loop_ancestor?(ancestor)