hecks 3.9.1 → 3.11.0

data/lib/hecks/doors/ruby_door/aggregate_door.rb

@@ -1,162 +0,0 @@
-require_relative "../../bluebook/dsl/hecksagon_builder"
-require_relative "../../bluebook/dsl/world_builder"
-require_relative "../../bluebook/dsl/domain_port_builder"
-require_relative "../../bluebook/dsl/const_shim"
-require_relative "../../bluebook/dsl/binding_proxy"
-require_relative "../../bluebook/hecksagon"
-require_relative "../handle"
-require_relative "../../naming"
-
-module Hecks
-  module Doors
-    module RubyDoor
-      # One aggregate's door: creating verbs and queries as module methods, CRUD
-      # delegation, and the `.hecksagon` binding/port hooks it lands on.
-      module AggregateDoor
-        # Builds one aggregate's door module: creating-command methods, query methods,
-        # find/all/count/events, project/docs/narrate, and the port/binding hooks.
-        #
-        # Kept as one method: `:port`/`:method_missing`/`:const_missing` below
-        # cross-reference each other and would lose that thread if split up.
-        # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-        def aggregate_module(dispatcher, domain, aggregate)
-          fqn  = "#{domain}::#{aggregate.hecks_name}"
-          door = Module.new
-
-          aggregate.attributes.each do |attribute|
-            next unless RESERVED.include?(attribute.name.to_sym)
-
-            warn "[hecks] #{aggregate.hecks_name}##{attribute.name} shadows a built-in — no reader defined"
-          end
-
-          # `!` marks a creating command (Ruby's mutate-and-may-refuse convention).
-          # Without it, a query sharing the same business name (e.g. Account's
-          # "Open") would collide with the creating command's own bare name.
-          aggregate.commands.select(&:creates?).each do |command|
-            door.define_singleton_method("#{Naming.snake(command.hecks_name)}!") do |**args|
-              Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate,
-                         instance: dispatcher.dispatch("#{fqn}.#{command.hecks_name}", with: args).instance)
-            end
-          end
-
-          # A query is a bare module method (no `!`): it just reads and returns
-          # the same raw row array `dispatcher.query` itself answers.
-          aggregate.queries.each do |query|
-            door.define_singleton_method(Naming.snake(query.hecks_name)) do |**args|
-              dispatcher.query("#{fqn}.#{query.hecks_name}", **args)
-            end
-          end
-
-          door.define_singleton_method(:fqn)        { fqn }
-          door.define_singleton_method(:ir)         { aggregate }
-
-          # Every construct emits its own IR, so an aggregate is a legitimate
-          # `project` target too. A chapter-scoped target refuses here via
-          # `Projector.admits!` rather than answering a confidently empty result.
-          door.define_singleton_method(:project) do |target, out: nil, **options|
-            key      = Projector.key_for(target)
-            artifact = Projector.call(key, bluebook: aggregate, options: options)
-            return artifact unless out
-
-            Projector.write(artifact, out, as: Projector.emits_for(key))
-          end
-          door.define_singleton_method(:repository) { dispatcher.registry.repository(domain, aggregate) }
-          door.define_singleton_method(:commands) do
-            aggregate.commands.map { |c| "#{Naming.snake(c.hecks_name)}!" }.sort
-          end
-          door.define_singleton_method(:queries) { aggregate.queries.map { |q| Naming.snake(q.hecks_name) }.sort }
-          # This chapter's own `:docs` projection, narrowed to this aggregate.
-          door.define_singleton_method(:docs) do |**options|
-            Projector.call(:docs, bluebook: dispatcher.registry.bluebook(domain),
-                                  options:  options.merge(aggregate: aggregate.hecks_name))
-          end
-          # Same narrowing as `:docs`, aimed at `:narrate`.
-          door.define_singleton_method(:narrate) do |**options|
-            Projector.call(:narrate, bluebook: dispatcher.registry.bluebook(domain),
-                                     options:  options.merge(aggregate: aggregate.hecks_name))
-          end
-          door.define_singleton_method(:count)      { dispatcher.registry.repository(domain, aggregate).count }
-          door.define_singleton_method(:events)     { dispatcher.events.select { |event| event.aggregate == fqn } }
-
-          door.define_singleton_method(:find) do |id|
-            found = dispatcher.registry.repository(domain, aggregate).find(id)
-            found && Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate, instance: found)
-          end
-
-          door.define_singleton_method(:all) do |**opts|
-            dispatcher.registry.repository(domain, aggregate).all(**opts).map do |instance|
-              Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate, instance: instance)
-            end
-          end
-
-          # Re-resolves via `Hecks.current_registry` rather than the closed-over
-          # `aggregate`: this door can be stale from an earlier boot, and its own
-          # `aggregate` would silently port a discarded one instead of the live one.
-          door.define_singleton_method(:port) do |name, &block|
-            current = Hecks.current_registry&.bluebook(domain)&.aggregate(aggregate.hecks_name) or
-              raise Bluebook::DSL::Malformed, "#{fqn}.port(#{name.inspect}) called outside a boot"
-
-            built = Bluebook::DSL::ConstShim.with(->(const) { const }) do
-              Bluebook::DSL::DomainPortBuilder.build(name, owner: current.hecks_name, &block)
-            end
-
-            # A `verb`-shaped port is a plain `Port`, the same struct `Hecks.port` registers —
-            # it belongs to no aggregate IR the way an operations-shaped `DomainPort` does, so
-            # it takes the registry's `add_port` directly. Mirrors `DSL::BindingProxy#port`,
-            # which handles the identical shape on a domain's first in-process boot (before
-            # this facade constant exists); this method is what a repeat boot reaches instead.
-            if built.is_a?(Bluebook::Port)
-              Hecks.current_registry.add_port(built)
-              return self
-            end
-
-            built.operations.each do |operation|
-              operation.attributes.select(&:reference?).each { |attribute| attribute.type.declared_in = current }
-            end
-            current.add_port(built)
-            self
-          end
-
-          door.define_singleton_method(:method_missing) do |verb, *args, **kwargs, &block|
-            # A bare call starts a Privacy marking chain (see
-            # `BindingProxy#method_missing`), reached here when the door is already
-            # installed (a second in-process boot) rather than at parse time.
-            return Bluebook::DSL::AttributePath.new(fqn, [verb.to_s]) if args.empty? && kwargs.empty? && !block
-
-            collector = Bluebook::DSL::HecksagonBuilder.collector
-            world     = Bluebook::DSL::WorldBuilder.current
-            # Inside a `.world` block the same qualified spelling records a world setting.
-            return world.record_binding(verb, args, kwargs, block) if world && !collector
-            return super(verb, *args, **kwargs, &block) unless collector
-
-            collector << Bluebook::Bind.new(
-              aggregate: fqn,
-              verb:      verb.to_s,
-              adapter:   args.first.to_s,
-              role:      kwargs[:role]&.to_s
-            )
-            block&.call
-            self
-          end
-
-          door.define_singleton_method(:respond_to_missing?) do |name, include_private = false|
-            !Bluebook::DSL::HecksagonBuilder.collector.nil? || !Bluebook::DSL::WorldBuilder.current.nil? ||
-              super(name, include_private)
-          end
-
-          # Uses `aggregate.hecks_name`, not the qualified `fqn`: qualifying it here
-          # would make `Account::Debit`'s meaning depend on whether a stale door
-          # from an earlier boot happens to be sitting on this process.
-          door.define_singleton_method(:const_missing) do |name|
-            resolver = Bluebook::DSL::ConstShim.resolver
-            return resolver.call("#{aggregate.hecks_name}::#{name}") if resolver
-
-            super(name)
-          end
-
-          door
-        end
-      end
-    end
-  end
-end

data/lib/hecks/doors/ruby_door/chapter.rb

@@ -1,89 +0,0 @@
-require_relative "../../bluebook/dsl/binding_proxy"
-require_relative "../../bluebook/dsl/const_shim"
-require_relative "../../bluebook/dsl/hecksagon_builder"
-
-module Hecks
-  module Doors
-    module RubyDoor
-      # One chapter's module: vision and aggregate list on the singleton, one
-      # aggregate door per declared head, and a `const_missing` hook for undeclared names.
-      module Chapter
-        # Builds the anonymous module that stands for one booted chapter: `vision`,
-        # `aggregates`, `docs`, `narrate` and `project` as singleton methods, plus one
-        # nested constant per aggregate holding that aggregate's door.
-        #
-        # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
-        #   dispatcher each aggregate door closes over
-        # @param bluebook [Bluebook::Chapter] the chapter to project into a module
-        # @return [Module] a fresh, unnamed module; `RubyDoor.install` gives it its
-        #   top-level name
-        # @raise [NameError] if an aggregate's name is not a valid constant name
-        def chapter_module(dispatcher, bluebook)
-          chapter = Module.new
-          define_readers(chapter, bluebook)
-          define_projections(chapter, bluebook)
-
-          bluebook.aggregates.each do |aggregate|
-            chapter.const_set(aggregate.hecks_name, aggregate_module(dispatcher, bluebook.name, aggregate))
-          end
-
-          define_const_missing(chapter, bluebook)
-          chapter
-        end
-
-        private
-
-        # The chapter's vision and its aggregate names.
-        def define_readers(chapter, bluebook)
-          chapter.define_singleton_method(:vision)     { bluebook.vision }
-          chapter.define_singleton_method(:aggregates) { bluebook.aggregates.map(&:name).sort }
-        end
-
-        # The chapter's documents and projections, each projected from its IR on every call so
-        # none can go stale.
-        def define_projections(chapter, bluebook)
-          chapter.define_singleton_method(:docs) do |**options|
-            Projector.call(:docs, bluebook: bluebook, options: options)
-          end
-
-          # The chapter read back in english, via `Projector::NarrateProjector`.
-          chapter.define_singleton_method(:narrate) do |**options|
-            Projector.call(:narrate, bluebook: bluebook, options: options)
-          end
-
-          define_project(chapter, bluebook)
-        end
-
-        # Projects the chapter's IR through a target; `out:` writes the artifact and
-        # the remaining options go to the projector (`audience:` for OIDC).
-        #
-        #   Pizzas.project(Projections::OIDC)
-        #   Pizzas.project(Projections::Shape, out: "shape.json")
-        def define_project(chapter, bluebook)
-          chapter.define_singleton_method(:project) do |target, out: nil, **options|
-            key      = Projector.key_for(target)
-            artifact = Projector.call(key, bluebook: bluebook, options: options)
-            return artifact unless out
-
-            Projector.write(artifact, out, as: Projector.emits_for(key))
-          end
-        end
-
-        # Inside a hecksagon a name is a declaration: with a collector open it becomes
-        # a `BindingProxy`. Otherwise a scoped reference from a bluebook mid-declaration
-        # goes to the `ConstShim` resolver, so it resolves whether or not a facade exists.
-        def define_const_missing(chapter, bluebook)
-          chapter.define_singleton_method(:const_missing) do |name|
-            collector = Bluebook::DSL::HecksagonBuilder.collector
-            return Bluebook::DSL::BindingProxy.new("#{bluebook.name}::#{name}", collector) if collector
-
-            resolver = Bluebook::DSL::ConstShim.resolver
-            return resolver.call("#{bluebook.name}::#{name}") if resolver
-
-            super(name)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/hecks/doors/ruby_door.rb

@@ -1,80 +0,0 @@
-require_relative "../chapters"
-require_relative "ruby_door/chapter"
-require_relative "ruby_door/aggregate_door"
-
-module Hecks
-  module Doors
-    # The door without classes: anonymous per-boot modules whose singleton methods
-    # dispatch by FQN, installed by `Loader.bind_runtime` and replaced whole on the next boot.
-    #
-    # `persisted_by("Heki")` in a `.hecksagon` file lands on the module's `method_missing`,
-    # which records a `Bind` into the open `HecksagonBuilder.collector`.
-    module RubyDoor
-      # Names that would shadow the machinery a Handle runs on; a field with one gets no reader.
-      RESERVED = %i[id state events reload inspect to_h hash class].freeze
-
-      extend Chapter
-      extend AggregateDoor
-
-      module_function
-
-      # Installs one top-level module per booted chapter, and one per aggregate, each
-      # closing over `dispatcher`, so `Pizzas::Pizza` and the bare `Pizza` both open the
-      # door of the boot that ran last.
-      #
-      # A gem chapter a hecksagon `attaches` installs nothing (`Query`, `Port` stay free).
-      # An aggregate sharing its chapter's name gets no second constant. A name that user
-      # code or the stdlib already owns is left alone with a warning (see `Namespace.install`).
-      #
-      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
-      #   dispatcher every installed door dispatches and queries through
-      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the same `dispatcher`
-      # @raise [NameError] if a chapter or aggregate name is not a valid constant name
-      def install(dispatcher)
-        dispatcher.registry.bluebooks.each_value do |bluebook|
-          install_chapter(dispatcher, bluebook) unless attached_chapter?(dispatcher.registry, bluebook)
-        end
-        dispatcher
-      end
-
-      # Installs one chapter's module, and the top-level shortcut of each of its aggregates.
-      def install_chapter(dispatcher, bluebook)
-        chapter = chapter_module(dispatcher, bluebook)
-        Namespace.install(*placement(bluebook), chapter)
-        # A namespaced chapter keeps its aggregates inside its namespace: top-level
-        # shortcuts would bring back the collisions the namespace exists to avoid.
-        return if bluebook.namespace
-
-        bluebook.aggregates.each do |aggregate|
-          next if aggregate.hecks_name == bluebook.name
-
-          Namespace.install(Object, aggregate.hecks_name, chapter.const_get(aggregate.hecks_name, false))
-        end
-      end
-
-      # Whether `bluebook` is a gem chapter that a hecksagon attached rather than a domain's own.
-      #
-      # @param registry [Runtime::Registry] the booted registry
-      # @param bluebook [Bluebook::Chapter] the chapter under test
-      # @return [Boolean]
-      def attached_chapter?(registry, bluebook)
-        registry.bounded?(bluebook.name) && Hecks::Chapters.index.key?(bluebook.name)
-      end
-
-      # Where a chapter's module installs: `Object::<name>`, or the constant path its
-      # `namespace` names, creating any missing parent modules along the way.
-      #
-      # @param bluebook [Bluebook::Chapter] the chapter being installed
-      # @return [Array(Module, String)] the parent module and the constant name within it
-      def placement(bluebook)
-        return [Object, bluebook.name] unless bluebook.namespace
-
-        *parents, leaf = bluebook.namespace.split("::")
-        parent = parents.reduce(Object) do |outer, name|
-          outer.const_defined?(name, false) ? outer.const_get(name, false) : outer.const_set(name, Module.new)
-        end
-        [parent, leaf]
-      end
-    end
-  end
-end

data/lib/hecks/doors/usage_cache.rb

@@ -1,139 +0,0 @@
-require "digest"
-require "fileutils"
-require "json"
-
-module Hecks
-  module Doors
-    # Remembers the help a launcher prints, so a repeat `hecks` need not read the domain again.
-    #
-    # The help is a pure function of the domain's declarations and of the gem that projects them,
-    # and reading those is most of what a launcher costs. The answer is kept in a file named for a
-    # digest of everything it depends on (the domain's declaration files, the gem's judging code and
-    # doors, the hecks and Ruby versions, the environment overlay, the command line and the
-    # program name),
-    # so any edit to one of them is simply a different entry: nothing is ever stale, only unused.
-    # Only an answer that ended well is kept, and any trouble with the cache itself is ignored
-    # and the help is worked out as if it did not exist.
-    #
-    # `HECKS_NO_USAGE_CACHE=1` turns it off; `HECKS_CACHE_DIR` moves it.
-    module UsageCache
-      # The variable that turns the cache off when set to anything but empty or `0`.
-      DISABLE_VARIABLE = "HECKS_NO_USAGE_CACHE".freeze
-      # The variable that names the directory the cache lives in.
-      DIRECTORY_VARIABLE = "HECKS_CACHE_DIR".freeze
-      # The declaration files whose contents shape a help text.
-      DECLARATIONS = "*.{bluebook,world,hecksagon,rb}".freeze
-      # How long an unused entry stays before the next write sweeps it away.
-      KEEP_SECONDS = 14 * 24 * 60 * 60
-
-      module_function
-
-      # Answers the cached help for this command line, or works it out with the block and
-      # remembers it.
-      #
-      # @param runtime [#directory] what `Hecks.describe` answered; anything else bypasses the cache
-      # @param argv [Array<String>] the command line
-      # @param program [String] how the caller was invoked
-      # @param audience [String] who the help is for, since the same line reads differently to each
-      # @yield works the answer out, loading the domain
-      # @yieldreturn [Array(String, Integer), nil] the text and status; nil if it runs a command
-      # @return [Array(String, Integer), nil] the block's answer, or the remembered one
-      def fetch(runtime, argv, program, audience: "")
-        directory = runtime.respond_to?(:directory) ? runtime.directory : nil
-        return yield unless directory && enabled?
-
-        file = entry_path(directory, argv, program, audience)
-        remembered = file && recall(file)
-        return remembered if remembered
-
-        answer = yield
-        remember(file, answer) if worth_keeping?(file, answer)
-        answer
-      end
-
-      # Whether an answer that ended well can be written to the entry's file.
-      def worth_keeping?(file, answer)
-        file && answer&.last&.zero?
-      end
-
-      # @return [Boolean] whether the cache is on
-      def enabled?
-        off = ENV[DISABLE_VARIABLE].to_s
-        off.empty? || off == "0"
-      end
-
-      # @return [String] the directory entries live in
-      def directory
-        ENV[DIRECTORY_VARIABLE] || File.join(ENV["XDG_CACHE_HOME"] || File.join(Dir.home, ".cache"), "hecks")
-      end
-
-      # The file that holds the answer for this command line, named by what it depends on.
-      #
-      # @return [String, nil] nil when the digest cannot be taken
-      def entry_path(domain, argv, program, audience = "")
-        digest = Digest::SHA256.new
-        key_parts(program, audience, argv).each { |part| digest << part.to_s << "\0" }
-        fingerprint_code(domain, digest)
-        File.join(directory, "usage-#{digest.hexdigest}.json")
-      rescue SystemCallError
-        nil
-      end
-
-      # @return [Array<String>] what the answer depends on besides the files: the gem and Ruby
-      #   series, the environment overlay, the program and audience and the command line
-      def key_parts(program, audience, argv)
-        [Hecks::VERSION, Hecks::Bluebook::MetaValidator::VerdictCache.ruby_series,
-         ENV["HECKS_ENVIRONMENT"].to_s, program, audience, argv.join("\0")]
-      end
-
-      # Feeds the digest every declaration file under `root`: its path below `root` and its bytes,
-      # so a touch or a checkout elsewhere keeps the entry and an edit does not.
-      def fingerprint(root, digest)
-        Dir.glob(File.join(root, "**", DECLARATIONS)).each do |file|
-          digest << file.delete_prefix(root) << "\0" << File.binread(file) << "\0"
-        end
-      end
-
-      # Feeds the digest what shapes a help text: the domain's declarations, the judging trees of
-      # the gem (the same set the verdict cache keys on) and the doors that render the text. An
-      # edit to the gem's projections, deploy or release code cannot change a help line.
-      def fingerprint_code(domain, digest)
-        fingerprint(domain, digest)
-        digest << Hecks::Bluebook::MetaValidator::VerdictCache.code_digest << "\0"
-        fingerprint(__dir__, digest)
-      end
-
-      # Reads the remembered answer and marks the entry as used, so a sweep keeps what is read.
-      #
-      # @return [Array(String, Integer), nil] the remembered answer, or nil when none can be trusted
-      def recall(file)
-        record = JSON.parse(File.read(file))
-        File.utime(nil, nil, file)
-        [record.fetch("text"), record.fetch("status")]
-      rescue SystemCallError, JSON::ParserError, KeyError
-        nil
-      end
-
-      # Writes the answer beside its name and sweeps entries nobody has read for a while.
-      def remember(file, answer)
-        FileUtils.mkdir_p(File.dirname(file))
-        scratch = "#{file}.#{Process.pid}"
-        File.write(scratch, JSON.generate("text" => answer.first, "status" => answer.last))
-        File.rename(scratch, file)
-        sweep(File.dirname(file))
-      rescue SystemCallError
-        nil
-      end
-
-      # Removes the entries older than `KEEP_SECONDS`.
-      def sweep(dir)
-        cutoff = Time.now - KEEP_SECONDS
-        Dir.glob(File.join(dir, "usage-*.json")).each do |entry|
-          File.delete(entry) if File.mtime(entry) < cutoff
-        end
-      rescue SystemCallError
-        nil
-      end
-    end
-  end
-end