hecks 2.8.0 → 3.0.0

data/lib/hecks/doors.rb

@@ -0,0 +1,61 @@
+module Hecks
+  # The class-free public surface, installed per boot by `Runtime::Loader.bind_runtime`.
+  module Doors
+    # The removal release of the `Facade` and `install_facade:` spellings.
+    REMOVAL = "3.1.0".freeze
+
+    module_function
+
+    # Resolves the boot switch from the current keyword and its deprecated spelling.
+    #
+    # @param install_doors [Boolean] the `install_doors:` keyword
+    # @param install_facade [Boolean, nil] the deprecated `install_facade:` keyword; nil when
+    #   the caller did not pass it
+    # @return [Boolean] whether to install the Ruby door constants
+    def install?(install_doors, install_facade = nil)
+      return install_doors if install_facade.nil?
+
+      warn "[hecks] `install_facade:` is deprecated and is removed in #{REMOVAL}; use `install_doors:`"
+      install_facade
+    end
+  end
+
+  # Installs facade constants at top level, replacing only what it installed itself.
+  # A constant owned by user code or the stdlib is left alone with a warning.
+  module Namespace
+    # A live registry, mutated by `install`, so it cannot be frozen.
+    # rubocop:disable-next Style/MutableConstant
+    GENERATED = {}
+
+    module_function
+
+    # Sets `container::name` to `value`, replacing only a constant this module installed.
+    #
+    # @param container [Module] the namespace to define the constant in
+    # @param name [String, Symbol] the constant name
+    # @param value [Module] the facade module to install
+    # @return [Object] `value` when installed, else the foreign constant left in place
+    # @raise [NameError] if `name` is not a valid constant name
+    def install(container, name, value)
+      name = name.to_s
+
+      if container.const_defined?(name, false)
+        current = container.const_get(name)
+        unless GENERATED[[container, name]].equal?(current)
+          warn "[hecks] #{name} is already defined — leaving it alone"
+          return current
+        end
+        container.send(:remove_const, name)
+      end
+
+      container.const_set(name, value)
+      GENERATED[[container, name]] = value
+      value
+    end
+  end
+end
+
+require_relative "doors/handle"
+require_relative "doors/ruby_door"
+require_relative "doors/command_request"
+require_relative "doors/json_door"

data/lib/hecks/embryonaut_bluebook/lock.rb

@@ -2,31 +2,10 @@ require "digest"
 
 module Hecks
   module EmbryonautBluebook
-    # What a vendored package records about the release it came from:
-    # `vendor/embryonaut_bluebooks/<name>/bluebook.lock`.
-    #
-    # ## File format
-    #
-    # One `key: value` line each for `package`, `version`, `tag`, `commit`
-    # and `digest`, then one `shape: <Domain> <label>` line per domain:
-    #
-    #     package: payments
-    #     version: 1.2.0
-    #     tag: payments-v1.2.0
-    #     commit: <full commit id the tag points at>
-    #     digest: <sha256 of the vendored *.bluebook files>
-    #     shape: Payments d33c23
-    #
-    # The digest is the sha256 of the `<sha256>  <name>` lines of every
-    # top-level `*.bluebook` file, sorted by name. The source repository's own
-    # `bin/bluebook_digest` prints the same number for the tagged release, which
-    # is how a vendored copy is proven to be exactly what it claims to be.
+    # The digest here must match the source repo's own bin/bluebook_digest
+    # output for the same tag, or a vendored copy cannot be trusted.
     Lock = Struct.new(:package, :version, :tag, :commit, :digest, :shape, keyword_init: true) do
-      # Computes the content digest of a directory's `*.bluebook` files.
-      #
-      # @param dir [String] the directory to measure
-      # @return [String, nil] 64 lowercase hex characters, nil when the directory holds
-      #   no bluebook file
+      # Sorted by name so the digest never depends on directory listing order.
       def self.digest_of(dir)
         names = Dir.children(dir).select { |name| name.end_with?(".bluebook") }.sort
         return nil if names.empty?
@@ -35,20 +14,12 @@ module Hecks
         Digest::SHA256.hexdigest(lines.join)
       end
 
-      # Reads a lock file.
-      #
-      # @param path [String] the `bluebook.lock` path
-      # @return [Lock, nil] the parsed lock, nil when the file does not exist
       def self.read(path)
         return nil unless File.file?(path)
 
         parse(File.read(path))
       end
 
-      # Parses a lock's text.
-      #
-      # @param text [String] the file's content
-      # @return [Lock] the lock, with `shape` as an Array of lines (empty when none)
       def self.parse(text)
         fields = { shape: [] }
         text.each_line do |line|
@@ -60,9 +31,6 @@ module Hecks
         new(**fields.slice(*members))
       end
 
-      # Renders the lock as the text written to `bluebook.lock`.
-      #
-      # @return [String] the lines described above, newline terminated
       def to_s
         header = %i[package version tag commit digest].map { |key| "#{key}: #{self[key]}\n" }
         (header + Array(shape).map { |line| "shape: #{line}\n" }).join

data/lib/hecks/embryonaut_bluebook/shape.rb

@@ -2,21 +2,10 @@ require_relative "../ports/persistence/plugins/era/storage_shape"
 
 module Hecks
   module EmbryonautBluebook
-    # The storage-shape labels of a directory of `*.bluebook` files.
-    #
-    # A label is what `PostgresEra` mints an era from, so a vendored package
-    # whose label changed is one whose next deploy mints a new era. This reads
-    # the files the way the era guard reads a held era's text: parse only, no
-    # boot, no wiring, no database, each file loaded into a scratch registry.
+    # A label change here means a vendored package's next deploy mints a new PostgresEra.
     module Shape
       module_function
 
-      # Measures every domain a directory's bluebook files declare.
-      #
-      # @param dir [String] a directory holding `*.bluebook` files
-      # @return [Array<String>] one `"<Domain> <label>"` line per domain, sorted by domain name
-      # @raise [Vendoring::Error] if the directory holds no bluebook file, or the files do
-      #   not load, the refusal a boot would raise
       def labels(dir)
         files = Dir[File.join(dir, "*.bluebook")]
         raise Vendoring::Error, "no *.bluebook files in #{dir}" if files.empty?
@@ -26,11 +15,6 @@ module Hecks
         end
       end
 
-      # Loads bluebook files into a registry of their own.
-      #
-      # @param files [Array<String>] absolute bluebook file paths, in load order
-      # @return [Runtime::Registry] the scratch registry holding what the files declared
-      # @raise [Vendoring::Error] if any file fails to load
       def load_all(files)
         scratch = Runtime::Registry.new
         library = Ports::Loading.bootstrap

data/lib/hecks/embryonaut_bluebook/vendor.rb

@@ -5,32 +5,8 @@ require_relative "shape"
 
 module Hecks
   module EmbryonautBluebook
-    # Vendors one package of the bluebook registry into a consuming project.
-    #
-    # ## What it does
-    #
-    # Pins the package's top-level `bluebook/*.bluebook` files from one commit
-    # of a local source repository into
-    # `<root>/vendor/embryonaut_bluebooks/<name>/bluebook/`, where `load!`
-    # resolves them. Only bluebook files are taken: a `.hecksagon`, `.port` or
-    # `.adapter` is a wiring decision for whoever deploys, never part of the
-    # vendored package.
-    #
-    # ## Releases and bare commits
-    #
-    # The source repository tags each release `<name>-v<X.Y.Z>` on a commit
-    # whose `<name>/bluebook.yml` says that version. A release pin (`ref` nil for
-    # the newest tag, `"1.2.0"`, or the tag name) also writes `bluebook.lock`,
-    # which records version, tag, commit, content digest and storage shape, and
-    # holds two refusals, because a production project is bound to `PostgresEra`:
-    #
-    # - a version lower than the vendored one, unless `allow_downgrade`;
-    # - a storage-shape change that does not raise the version by at least a
-    #   minor, so a new era shows in the version number and not only in a hash.
-    #
-    # Any other commit-ish pins that commit and writes only the marker, with no
-    # lock and no version checks. Either way nothing on disk changes when a
-    # pin is refused or its files do not load.
+    # Pins a package's `bluebook/*.bluebook` files from a source repo commit; a
+    # release pin also refuses a downgrade or an era-breaking storage-shape change.
     class Vendor
       # A release version, `X.Y.Z`.
       VERSION = /\A\d+\.\d+\.\d+\z/
@@ -38,33 +14,17 @@ module Hecks
       # A package name is a directory name and a bluebook name stem.
       NAME = /\A[a-z][a-z0-9_]*\z/
 
-      # What a vendoring changed.
-      #
-      # @!attribute [r] previous_version
-      #   @return [String, nil] the version recorded before, nil when there was none
-      # @!attribute [r] previous_shape
-      #   @return [Array<String>, nil] the shape lines measured before, nil when there was
-      #   no earlier copy
+      # What a vendoring changed; previous_version/previous_shape are nil when
+      # there was no earlier vendored copy.
       Result = Struct.new(:package, :commit, :version, :tag, :digest, :shape,
                           :previous_version, :previous_shape, :dir, keyword_init: true) do
-        # Says whether this was a release pin, which writes a lock.
-        #
-        # @return [Boolean] true for a release, false for a bare commit
         def release? = !tag.nil?
 
-        # Says whether the storage shape moved since the earlier copy.
-        #
-        # @return [Boolean] true when an earlier copy existed and its shape differs
         def shape_changed? = !previous_shape.nil? && previous_shape != shape
       end
 
-      # @param name [String, Symbol] the package's directory name, such as `"payments"`
-      # @param from [String] path of the local source repository
-      # @param ref [String, nil] `X.Y.Z`, a release tag name, any commit-ish, or nil for the
-      #   newest release
-      # @param root [String] the consuming project's root
-      # @param allow_downgrade [Boolean] whether a release older than the vendored one is allowed
-      # @raise [Vendoring::Error] if the name is not a plain package name
+      # `ref` accepts `X.Y.Z`, a release tag name, any commit-ish, or nil for
+      # the newest release.
       def initialize(name, from:, root:, ref: nil, allow_downgrade: false)
         @name = name.to_s
         raise Vendoring::Error, "#{name.inspect} is not a package name" unless @name.match?(NAME)
@@ -76,10 +36,6 @@ module Hecks
       end
 
       # Pins the package and reports what changed.
-      #
-      # @return [Result] the commit, version and shape now vendored
-      # @raise [Vendoring::Error] if the release or commit is not found, the tagged commit
-      #   disagrees with its own version, the files do not load, or a refusal above applies
       def call
         tag, version = release
         previous_version, previous_shape = existing
@@ -99,9 +55,8 @@ module Hecks
 
       def package_dir = File.join(@root, "vendor", "embryonaut_bluebooks", @name)
 
-      # Resolves what `ref` asks for into a release tag and its version.
-      #
-      # @return [Array(String, String), nil] tag and version for a release, nil for a bare commit
+      # Resolves what `ref` asks for into a release tag and its version, or nil
+      # for a bare commit.
       def release
         tag = release_tag
         return nil unless tag

data/lib/hecks/embryonaut_bluebook/vendor_cli.rb

@@ -3,21 +3,10 @@ require_relative "vendor"
 
 module Hecks
   module EmbryonautBluebook
-    # The command line behind `bin/vendor_bluebook`.
+    # The command line behind `hecks vendor`; lives in the gem so a
+    # consuming project reaches it through its own bundle, no script to copy.
     #
-    # It lives in the gem, not in a script, so a consuming project reaches it
-    # through its own bundle without a copy of the script:
-    #
-    #     bundle exec ruby -rhecks \
-    #       -e 'exit Hecks::EmbryonautBluebook::VendorCli.run(ARGV)' payments@1.2.0
-    #
-    # ## Usage
-    #
-    #     vendor_bluebook <package>[@<version-or-commit>] [--from <path>] [--root <path>]
-    #
-    # `--from` defaults to `$EMBRYONAUT_BLUEBOOKS_SRC` and `--root` to the current
-    # directory. `ALLOW_DOWNGRADE=1` in the environment permits a release older
-    # than the vendored one.
+    #     vendor_bluebook <package>[@<version-or-commit>] [--from path] [--root path]
     module VendorCli
       USAGE = "usage: vendor_bluebook <package>[@<version-or-commit>] [--from PATH] [--root PATH]".freeze
 
@@ -44,11 +33,7 @@ module Hecks
         1
       end
 
-      # Reads the options into a hash and picks out the package argument.
-      #
-      # @param argv [Array<String>] the command-line arguments
-      # @param options [Hash{Symbol => String}] receives `:from` and `:root` when given
-      # @return [String, nil] the one positional argument, nil unless exactly one was given
+      # nil unless argv held exactly one positional argument.
       def self.parse(argv, options)
         parser = OptionParser.new
         parser.on("--from PATH") { |path| options[:from] = path }

data/lib/hecks/embryonaut_bluebook.rb

@@ -1,75 +1,6 @@
 module Hecks
-  # A vendored, external bluebook.
-  #
-  # ## What it is
-  #
-  # Same shape as Framework (framework.rb), for members that don't ship
-  # inside hecks's own lib/ at all: a separate, independently-versioned
-  # package (github.com/chrisyoung/embryonaut_bluebooks) that a consuming
-  # project vendors into its own checkout, the same way a project already
-  # vendors hecks itself (bin/vendor_hecks, vendor/hecks/).
-  #
-  # ## Recovered, not rebuilt
-  #
-  # This module and its `uses_embryonaut_bluebook`
-  # DSL word (hecksagon_builder.rb) were built on a prior commit of this
-  # repo (933d1dd), vendored out to a real consumer (a client site's domain,
-  # for embryonaut_bluebooks/payments), and then lost from this repo's own
-  # reachable history — a hard reset or rebase left no branch containing
-  # that commit. The consumer's vendor snapshot (a `git archive` of that
-  # commit, committed into their repo) was the only surviving copy; this
-  # file is ported forward from it, checked against current `main`'s own
-  # conventions rather than copied wholesale, since the two trees had
-  # otherwise diverged for weeks in both directions.
-  #
-  # ## Resolution
-  #
-  # Resolved from the consuming registry's own root, not this gem's
-  # __dir__ — Framework::ROOT can be a fixed, `__dir__`-relative constant
-  # because framework members ship inside this gem; an embryonaut bluebook
-  # ships inside the consumer's own checkout instead, at
-  # `<registry.root>/vendor/embryonaut_bluebooks/<name>/bluebook/`. There
-  # is no fixed answer until a registry (and its root) actually exists, so
-  # this resolves lazily, per call — the same reason `uses_framework`
-  # itself only runs at hecksagon-build time, when a real registry is
-  # current.
-  #
-  # ## Load order
-  #
-  # Every `.bluebook` file in the package, sorted — not just one. Unlike a
-  # framework member (one file, named by its own stem), a vendored package
-  # can span several bluebook files that reopen the same `Hecks.bluebook`
-  # (embryonaut_bluebooks/payments/bluebook/{payment,payments,policies}
-  # .bluebook all reopen "Payments"). Load order matters — policies
-  # .bluebook names `Payment::Succeed` and needs the aggregate already
-  # built — and a plain alphabetical sort already gives the right order:
-  # payment < payments < policies, the same reason that package's own
-  # files are named to fall in that order in the first place.
-  #
-  # ## Scope
-  #
-  # Only the bluebook files — same restriction Framework draws, same
-  # reason: a `.hecksagon`/`.port`/`.adapter` is a wiring decision
-  # (persistence, which processor adapter is bound) that belongs to
-  # whoever is deploying, never baked into the vendored package itself.
-  # embryonaut_bluebooks/payments ships its own mock `.hecksagon` for its
-  # own spec suite; a consumer declares its own separate
-  # `Hecks.hecksagon "Payments" do ... end` to bind real storage/adapters
-  # — see Framework's own comment for the fuller reasoning, identical here.
-  #
-  # ## Idempotency
-  #
-  # Idempotent the same way `Framework.load!` is — checked against the
-  # bluebook this package actually declares (`Naming.pascal("payments")`
-  # => "Payments"), not a separate ledger. A vendored package's directory
-  # name and its declared `Hecks.bluebook` name are the one convention
-  # this reuses from Framework rather than reinventing.
-  #
-  # ## Vendoring
-  #
-  # `vendor!` is the other direction: it pins a package from a local checkout
-  # of the registry into a consuming project's own `vendor/` tree, and is the
-  # one implementation behind `bin/vendor_bluebook` (see Vendoring and Vendor).
+  # A vendored, external bluebook: same shape as Framework, but for a
+  # package that ships outside hecks's own lib/ (see .load! and .vendor!).
   module EmbryonautBluebook
     autoload :Lock, File.join(__dir__, "embryonaut_bluebook/lock")
     autoload :Shape, File.join(__dir__, "embryonaut_bluebook/shape")
@@ -100,9 +31,11 @@ module Hecks
       if files.empty?
         raise Runtime::WiringError,
               "no vendored embryonaut bluebook named #{name.inspect} at #{dir} — " \
-              "vendor it with bin/vendor_bluebook #{name}"
+              "vendor it with hecks vendor #{name}"
       end
 
+      # Loaded in the glob's alphabetical order; a package with several
+      # files that reopen the same bluebook is named to rely on that.
       files.each { |file| Kernel.load(file) }
     end
 

data/lib/hecks/engine_agreement.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Hecks
+  # The grep-based gate that keeps the query engines agreeing on what a comparator means.
+  #
+  # It fails when an engine re-grows its own comparator dispatch, or when a declared comparator
+  # lacks a shared `Comparison` case or a cross-engine agreement spec. Every declared comparator
+  # is read from `Hecks::Vocabulary`, as `Common::COMPARATORS` is: one live source, no copied list.
+  module EngineAgreement
+    # The engine files that must route every comparator through `Comparison.holds?`.
+    ENGINE_FILES = {
+      "in-memory port (Memory/Heki-backed aggregate queries)"                    => "lib/hecks/ports/query/in_memory.rb",
+      "reference interpreter (entity/sub-list queries, no-native-hook fallback)" => "lib/hecks/runtime/query_interpreter.rb"
+    }.freeze
+
+    # Where the shared comparison logic lives.
+    SHARED_COMPARISON_FILE = "lib/hecks/query_specification/common/comparison.rb"
+
+    # Specs that put each comparator in front of both engines. `none_in_state` needs a second
+    # aggregate and a registry, so the two dedicated growth specs cover it instead.
+    AGREEMENT_SPEC_FILES = %w[
+      spec/adapters/query_agreement_spec.rb
+      spec/query_none_in_state_aggregate_level_growth_spec.rb
+      spec/query_none_in_state_growth_spec.rb
+    ].freeze
+
+    # What a check found.
+    #
+    # @!attribute [r] declared
+    #   @return [Array<String>] the comparators the vocabulary declares
+    # @!attribute [r] problems
+    #   @return [Array<String>] each disagreement, in words; empty when the engines agree
+    Finding = Struct.new(:declared, :problems)
+
+    module_function
+
+    # Checks the engines against the vocabulary.
+    #
+    # @param root [String] the checkout whose files are read
+    # @return [Finding] the declared comparators and every problem found
+    def check(root:)
+      require "hecks"
+      declared = Hecks::Vocabulary.symbols("QueryComparator").map(&:to_s)
+      if declared.empty?
+        return Finding.new(declared, ["Vocabulary::QueryComparator declared no comparators at all — " \
+                                      "vocabulary.bluebook failed to register, or Hecks::Vocabulary changed " \
+                                      "shape. Refusing to report a clean pass."])
+      end
+
+      problems = vocabulary_problems(declared) + engine_problems(root, declared) + shared_problems(root, declared)
+      Finding.new(declared, problems)
+    end
+
+    # @param declared [Array<String>] the declared comparators
+    # @return [Array<String>] a problem when the language and the runtime table disagree
+    def vocabulary_problems(declared)
+      runtime = Hecks::QuerySpecification::Common::COMPARATORS.map(&:to_s)
+      differ = (declared - runtime) | (runtime - declared)
+      return [] if differ.empty?
+
+      ["Vocabulary::QueryComparator #{declared.sort.inspect} and " \
+       "QuerySpecification::Common::COMPARATORS #{runtime.sort.inspect} disagree " \
+       "(only in one: #{differ.sort.inspect}) — the language and the runtime table it drives " \
+       "have drifted apart."]
+    end
+
+    # @param root [String] the checkout
+    # @param declared [Array<String>] the declared comparators
+    # @return [Array<String>] a problem for each engine that lost `Comparison.holds?` or grew a case
+    def engine_problems(root, declared)
+      ENGINE_FILES.flat_map do |label, relative|
+        source = File.read(File.join(root, relative))
+        found = []
+        unless source =~ /Comparison\.holds\?/
+          found << "#{relative} (#{label}) no longer calls Comparison.holds? at all — " \
+                   "has it grown its own comparator dispatch again?"
+        end
+        declared.each do |comparator|
+          escaped = Regexp.escape(comparator)
+          next unless source =~ /when\s+"#{escaped}"/ || source =~ /when\s+:#{escaped}\b/
+
+          found << "#{relative} (#{label}) has its own `when #{comparator.inspect}` — comparator logic " \
+                   "belongs ONLY in #{SHARED_COMPARISON_FILE}, not re-implemented per engine."
+        end
+        found
+      end
+    end
+
+    # @param root [String] the checkout
+    # @param declared [Array<String>] the declared comparators
+    # @return [Array<String>] a problem for a comparator with no shared case, or no agreement spec
+    def shared_problems(root, declared)
+      comparison = File.read(File.join(root, SHARED_COMPARISON_FILE))
+      specs = AGREEMENT_SPEC_FILES.map { |path| File.read(File.join(root, path)) }
+      missing_case = declared.reject { |comparator| comparison =~ /when\s+"#{Regexp.escape(comparator)}"/ }
+      missing_spec = declared.reject { |comparator| specs.any? { |text| mentions_operator?(text, comparator) } }
+
+      [missing_case_problem(missing_case), missing_spec_problem(missing_spec)].compact
+    end
+
+    # @param missing [Array<String>] comparators with no `when` case in the shared file
+    # @return [String, nil] the problem, or nil when none is missing
+    def missing_case_problem(missing)
+      return nil if missing.empty?
+
+      "#{SHARED_COMPARISON_FILE} has no `when` case for: #{missing.sort.inspect} — " \
+        "a declared comparator with no shared implementation falls to Comparison.holds?'s own `else`, " \
+        "which RAISES (by design), but only the first time anything actually asks for it at runtime. " \
+        "Add a `when #{missing.first.inspect} then ...` case before shipping this comparator."
+    end
+
+    # @param missing [Array<String>] comparators no agreement spec exercises
+    # @return [String, nil] the problem, or nil when none is missing
+    def missing_spec_problem(missing)
+      return nil if missing.empty?
+
+      "no example in #{AGREEMENT_SPEC_FILES.inspect} exercises: #{missing.sort.inspect} — " \
+        "a comparator with a case but no cross-engine spec has never actually had both engines asked " \
+        "the same question. Add a declared query using it, with a hand-computed expected id list, to one " \
+        "of those files (see spec/adapters/query_agreement_spec.rb's own header for why a hand-computed " \
+        "oracle, not mere pairwise agreement, is the standard)."
+    end
+
+    # @param text [String] a spec's source
+    # @param comparator [String] the comparator name, such as `"eq"`
+    # @return [Boolean] whether the spec puts the comparator in front of an engine
+    def mentions_operator?(text, comparator)
+      # Explicit form: the comparator as a bare hash key, bounded so `in:` cannot match
+      # mid-identifier.
+      return true if text =~ /(?<![A-Za-z0-9_])#{Regexp.escape(comparator)}(?![A-Za-z0-9_])\s*:/
+
+      # `eq` is normally implicit (`where(status: "open")`), so an example description naming it
+      # counts; no other comparator gets that leniency.
+      return false unless comparator == "eq"
+
+      text =~ /\b(?:it|describe)\s+"[^"]*\beq\b[^"]*"/i ? true : false
+    end
+
+    # @param finding [Finding] what a check found
+    # @return [String] the clean-pass line
+    def clean_line(finding)
+      "check_engine_agreement: #{finding.declared.size} declared comparator(s) " \
+        "(#{finding.declared.sort.join(', ')}) — every one has a shared Comparison case, a cross-engine " \
+        "agreement spec, and both engine files still route through Comparison.holds? alone. 0 problems."
+    end
+
+    # @param finding [Finding] what a check found
+    # @return [String] every problem, numbered, with where the mechanism is explained
+    def problem_lines(finding)
+      numbered = finding.problems.each_with_index.map { |problem, index| "  #{index + 1}. #{problem}\n\n" }
+      ["check_engine_agreement: #{finding.problems.size} problem(s) found:\n\n", *numbered,
+       "See lib/hecks/query_specification/common/comparison.rb's own header for what this mechanism " \
+       "replaced and why a grep-based gate exists here at all."].join
+    end
+  end
+end

data/lib/hecks/facade.rb

@@ -1,59 +1,31 @@
-module Hecks
-  # The class-free public surface — see facade/surface.rb for the door and
-  # facade/handle.rb for the record in hand. Installed per boot by
-  # `Runtime::Loader.bind_runtime`.
-  module Facade
-  end
+# The deprecated alias shim: `Hecks::Facade` is now `Hecks::Doors` and `Doors::Surface` is
+# `Doors::RubyDoor`. Both old constants still resolve and warn; they are removed in
+# `Hecks::Doors::REMOVAL`.
+require_relative "doors"
 
-  # The one careful way to put something at top level.
+# The root namespace; this file holds only the deprecated aliases.
+module Hecks
+  # Resolves the constants that now live in `Doors` under their old names, warning on each use.
   #
-  # Overwrites only what it itself installed (tracked in `GENERATED`), refuses —
-  # with a warning, never a raise — to clobber a constant belonging to user
-  # code or the stdlib. Which is why a chapter named `Set` never becomes a
-  # constant, and why `Registry` keeps its own table of chapters rather than
-  # trusting Ruby's. Each re-install replaces the previous boot's entry, so
-  # what `GENERATED` retains is one small facade module per name, not a graph
-  # per boot.
-  module Namespace
-    # Not frozen — a real registry, mutated below
-    # (`GENERATED[[container, name]] = value`). False positive for
-    # Style/MutableConstant.
-    # rubocop:disable-next Style/MutableConstant
-    GENERATED = {}
-
-    module_function
+  # Extended onto `Hecks` and `Hecks::Doors`, ahead of `Module#const_missing`.
+  module DoorsAliases
+    # Old constant name mapped to the new one, per namespace that carried it.
+    RENAMED = { Hecks => { Facade: "Hecks::Doors" }, Hecks::Doors => { Surface: "Hecks::Doors::RubyDoor" } }.freeze
 
-    # Sets `container::name` to `value`, replacing only a constant this module installed
-    # itself and leaving any other existing constant in place with a warning.
+    # Answers a renamed constant with its replacement and a warning; anything else
+    # goes to the next `const_missing`.
     #
-    # @param container [Module] the namespace to define the constant in; every caller in
-    #   this repository passes `Object`
-    # @param name [String, Symbol] the constant name, such as a chapter or aggregate name
-    # @param value [Module] the facade module to install under that name
-    # @return [Object] `value` when it was installed; otherwise the constant already
-    #   defined under `name`, which this module does not own and did not replace
-    # @raise [NameError] if `name` is not a valid constant name (raised by
-    #   `const_defined?`)
-    def install(container, name, value)
-      name = name.to_s
+    # @param name [Symbol] the missing constant
+    # @return [Module] the replacement module
+    def const_missing(name)
+      target = RENAMED.fetch(self, {})[name]
+      return super unless target
 
-      if container.const_defined?(name, false)
-        current = container.const_get(name)
-        unless GENERATED[[container, name]].equal?(current)
-          warn "[hecks] #{name} is already defined — leaving it alone"
-          return current
-        end
-        container.send(:remove_const, name)
-      end
-
-      container.const_set(name, value)
-      GENERATED[[container, name]] = value
-      value
+      warn "[hecks] #{self}::#{name} is deprecated and is removed in #{Hecks::Doors::REMOVAL}; use #{target}"
+      Object.const_get(target)
     end
   end
-end
 
-require_relative "facade/handle"
-require_relative "facade/surface"
-require_relative "facade/command_request"
-require_relative "facade/json_door"
+  extend DoorsAliases
+  Doors.extend(DoorsAliases)
+end