hecks 3.5.0 → 3.7.0

data/lib/hecks/query_specification/common/comparison.rb

@@ -57,24 +57,44 @@ module Hecks
         # @param registry [Runtime::Registry, nil] used only by `none_in_state`
         # @return [Boolean] whether the comparison holds
         # @raise [Runtime::WiringError] if `operation` names no comparator in this table
-        # rubocop:disable-next Metrics/CyclomaticComplexity
         def holds?(operation, held, want, registry: nil)
           # A NULL satisfies no comparison (`none_in_state` is exempt); see NullPolicy.
           return false if NullPolicy.unmatchable?(operation, held, want)
 
-          case operation.to_s
-          when "eq"       then held == want
-          when "ne"       then held != want
+          name = operation.to_s
+          return lower_bound_holds?(name, held, want) if %w[lt lte].include?(name)
+          return upper_bound_holds?(name, held, want) if %w[gt gte].include?(name)
+
+          other_holds?(name, held, want, registry)
+        end
+
+        # The `lt` and `lte` cases of `holds?`.
+        def lower_bound_holds?(name, held, want)
+          case name
           when "lt"       then ordered?(held, want) && held < want
           when "lte"      then ordered?(held, want) && held <= want
+          end
+        end
+
+        # The `gt` and `gte` cases of `holds?`.
+        def upper_bound_holds?(name, held, want)
+          case name
           when "gt"       then ordered?(held, want) && held > want
           when "gte"      then ordered?(held, want) && held >= want
+          end
+        end
+
+        # The remaining cases of `holds?`.
+        def other_holds?(name, held, want, registry)
+          case name
+          when "eq"       then held == want
+          when "ne"       then held != want
           when "in"       then any_member_in?(held, want)
           when "contains" then contains?(held, want)
           when "none_in_state" then none_in_state?(held, want, registry)
           else
             # Backstop: an unrecognized comparator must refuse, never read as `eq`.
-            raise Runtime::WiringError, "no comparator handles #{operation.to_s.inspect} — add one before declaring it"
+            raise Runtime::WiringError, "no comparator handles #{name.inspect} — add one before declaring it"
           end
         end
 

data/lib/hecks/query_specification/common/dsl.rb

@@ -93,7 +93,7 @@ module Hecks
           op, operand = value.first
           unless value.size == 1 && COMPARATORS.include?(op.to_sym)
             raise ArgumentError,
-                  "unknown comparator #{value.inspect} — expected one of #{COMPARATORS.join(', ')}"
+                  "unknown comparator #{value.inspect} — expected one of #{COMPARATORS.join(", ")}"
           end
           [op.to_sym, operand]
         end

data/lib/hecks/query_specification/common/null_policy.rb

@@ -20,12 +20,7 @@ module Hecks
         # @return [Array<Object>] a new Array in the requested order
         def order(records, direction:, policy: nil, &key)
           descending = direction.to_s.downcase == "desc"
-          null_rows, valued_rows = records.partition { |record| key.call(record).nil? }
-          sorted = valued_rows.each_with_index.sort_by { |record, index| [key.call(record), index] }.map(&:first)
-          if descending
-            sorted.reverse!
-            null_rows.reverse!
-          end
+          null_rows, sorted = null_and_sorted(records, descending, &key)
           case policy&.mode.to_s
           when "first" then null_rows + sorted
           when "last" then sorted + null_rows
@@ -33,6 +28,14 @@ module Hecks
           end
         end
 
+        # @return [Array(Array, Array)] the null-keyed rows and the valued rows in key order, each
+        #   in the order the direction asks for
+        def null_and_sorted(records, descending, &)
+          null_rows, valued_rows = records.partition { |record| yield(record).nil? }
+          sorted = valued_rows.each_with_index.sort_by { |record, index| [yield(record), index] }.map(&:first)
+          descending ? [null_rows.reverse, sorted.reverse] : [null_rows, sorted]
+        end
+
         # Renders the `ORDER BY` terms for one expression, with an explicit
         # `NULLS FIRST`/`NULLS LAST` and an `id` tiebreak in the same direction.
         #

data/lib/hecks/query_specification/common/options.rb

@@ -6,6 +6,9 @@ module Hecks
       # The attribute set every query-shaped construct shares, plus `options_to_h` and
       # `extra_options_to_h` for serializing it.
       class Options
+        # The options besides `wheres`, in the order `options_to_h` writes them.
+        SPEC_OPTIONS = %i[order_by limit offset cursor authorization null_semantics inspection].freeze
+
         attr_reader :wheres, :order_by, :limit, :offset, :cursor,
                     :authorization, :null_semantics, :inspection
 
@@ -21,17 +24,16 @@ module Hecks
         # @param null_semantics [NullSemantics, nil] where nulls sort; stored as given, so
         #   an explicit `nil` (what `ReadModelBuilder` passes when `nulls` was never
         #   written) stays `nil` rather than becoming the `native` default
-        def initialize(wheres: [], order_by: nil, limit: nil, offset: nil, cursor: nil,
-                       authorization: nil,
-                       inspection: nil, null_semantics: NullSemantics.default)
-          @wheres = wheres
-          @order_by = order_by
-          @limit = limit
-          @offset = offset
-          @cursor = cursor
-          @authorization = authorization
-          @null_semantics = null_semantics
-          @inspection = inspection
+        def initialize(**options)
+          refuse_unknown!(options)
+          @wheres = options.fetch(:wheres, [])
+          @order_by = options[:order_by]
+          @limit = options[:limit]
+          @offset = options[:offset]
+          @cursor = options[:cursor]
+          @authorization = options[:authorization]
+          @null_semantics = options.fetch(:null_semantics) { NullSemantics.default }
+          @inspection = options[:inspection]
         end
 
         # Serializes every shared option, declared or not, so a subclass's `to_h`
@@ -42,9 +44,7 @@ module Hecks
         #   `:authorization`, `:null_semantics` and `:inspection`, each that spec's own
         #   `to_h` or `nil` when undeclared
         def options_to_h
-          { wheres: @wheres.map(&:to_h), order_by: @order_by&.to_h, limit: @limit&.to_h,
-            offset: @offset&.to_h, cursor: @cursor&.to_h, authorization: @authorization&.to_h,
-            null_semantics: @null_semantics&.to_h, inspection: @inspection&.to_h }
+          { wheres: @wheres.map(&:to_h) }.merge(SPEC_OPTIONS.to_h { |name| [name, public_send(name)&.to_h] })
         end
 
         # Serializes only the declared options beyond the settled three, so a
@@ -59,6 +59,13 @@ module Hecks
           end
                       .except(:wheres, :order_by, :limit)
         end
+
+        private
+
+        def refuse_unknown!(options)
+          unknown = options.keys - SPEC_OPTIONS - [:wheres]
+          raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
+        end
       end
     end
   end

data/lib/hecks/query_specification/field_path.rb

@@ -85,9 +85,12 @@ module Hecks
         leaf = leaf_attribute(attribute, segments, &)
         return false if leaf.nil? || leaf.list? || leaf.reference?
         return true if primitives.include?(leaf.type.to_s)
-        return false unless segments.empty?
 
-        shape = yield(leaf.type.to_s)
+        segments.empty? && member_typed_as?(yield(leaf.type.to_s), primitives)
+      end
+
+      # @return [Boolean] whether a value object shape has a member typed as one of `primitives`
+      def member_typed_as?(shape, primitives)
         !shape.nil? && shape.attributes.any? { |member| primitives.include?(member.type.to_s) }
       end
 

data/lib/hecks/query_specification/hop_path.rb

@@ -77,28 +77,25 @@ module Hecks
       #   target is not found, `:too_deep` when the chain exceeds `MAX_HOPS`
       # @raise [Bluebook::DSL::Malformed] if a reference on the path has no `declared_in`
       #   aggregate to resolve its target through
-      def plan(field, attributes)
-        hops = []
-        remaining = field.to_s
-        current = attributes
+      def plan(field, attributes) = walk(field.to_s, attributes, [])
 
-        loop do
-          step = next_hop(remaining, current)
-          break unless step
+      # @param remaining [String] the part of the path not yet resolved
+      # @param current [Array<Bluebook::Attribute>] the attributes the next hop is looked up in
+      # @param hops [Array<Hop>] the hops resolved so far, added to in place
+      # @return [Plan] as for `plan`
+      def walk(remaining, current, hops)
+        step = next_hop(remaining, current)
+        return Plan.new(hops: hops, tail: remaining, refusal: nil) unless step
 
-          hop, rest = step
-          return Plan.new(hops: hops, tail: nil, refusal: :too_deep) if hops.size >= MAX_HOPS
+        hop, rest = step
+        return Plan.new(hops: hops, tail: nil, refusal: :too_deep) if hops.size >= MAX_HOPS
 
-          # Pushed even unresolved: a caller reporting :unresolvable needs this hop's
-          # target_name, and `.target` is nil on this one entry.
-          hops << hop
-          return Plan.new(hops: hops, tail: nil, refusal: :unresolvable) unless hop.target
+        # Pushed even unresolved: a caller reporting :unresolvable needs this hop's
+        # target_name, and `.target` is nil on this one entry.
+        hops << hop
+        return Plan.new(hops: hops, tail: nil, refusal: :unresolvable) unless hop.target
 
-          current = hop.target.attributes
-          remaining = rest
-        end
-
-        Plan.new(hops: hops, tail: remaining, refusal: nil)
+        walk(rest, hop.target.attributes, hops)
       end
     end
   end

data/lib/hecks/release/lane.rb

@@ -0,0 +1,22 @@
+require "hecks/vocabulary"
+
+module Hecks
+  module Release
+    # The lane a release is cut from, read from the `Lane` rows of the Vocabulary chapter.
+    #
+    # A release ships what the gates passed, so it is cut from the guarded lane that feeds a tag
+    # (`stable`, which feeds `edge`), never from the lane that takes pushes with no gate.
+    module Lane
+      module_function
+
+      # @return [String] the name of the lane a release is cut from
+      # @raise [KeyError] when no `Lane` row feeds a tag
+      def release
+        row = Hecks::Vocabulary.rows("Lane").find { |lane| !lane["feeds"].to_s.empty? }
+        raise KeyError, "no Lane row feeds a tag, so no lane a release is cut from" unless row
+
+        row.fetch("name")
+      end
+    end
+  end
+end

data/lib/hecks/release/runner/clean_tree.rb

@@ -33,8 +33,8 @@ module Hecks
           paths = stray
           return if paths.empty?
 
-          raise Refusal, "#{paths.size} file(s) under #{SHIPPED.join(', ')} are modified, untracked or " \
-                         "ignored (#{paths.first(5).join(', ')}); commit or delete them before releasing"
+          raise Refusal, "#{paths.size} file(s) under #{SHIPPED.join(", ")} are modified, untracked or " \
+                         "ignored (#{paths.first(5).join(", ")}); commit or delete them before releasing"
         end
       end
     end

data/lib/hecks/release/runner/commands.rb

@@ -52,7 +52,7 @@ module Hecks
         def run!(*argv, env: {}, chdir: nil)
           return true if system(env, *argv, **directory(chdir))
 
-          raise CommandFailed, "`#{argv.first(2).join(' ')}` failed"
+          raise CommandFailed, "`#{argv.first(2).join(" ")}` failed"
         end
 
         private

data/lib/hecks/release/runner/options.rb

@@ -0,0 +1,82 @@
+module Hecks
+  module Release
+    class Runner
+      # Which steps to run and how.
+      class Options
+        # The switches, each off unless a caller turns it on.
+        FLAGS = %i[dry_run gem_only npm_only npm_local no_wait yes].freeze
+
+        # @return [Boolean] run every check and build, but tag, push and publish nothing
+        attr_reader :dry_run
+
+        # @param flags [Hash{Symbol => Boolean}] any of:
+        #   `dry_run` run every check and build, but tag, push and publish nothing;
+        #   `gem_only` publish the gem, not the package;
+        #   `npm_only` do the npm step only, not the gem: wait for CI's publish, or with `npm_local`
+        #   publish from here;
+        #   `npm_local` publish the package from this machine, not by CI;
+        #   `no_wait` do not wait for CI's publish to reach npm;
+        #   `yes` answer every confirmation yes
+        # @raise [ArgumentError] if the flags contradict each other, or one is not a switch
+        def initialize(**flags)
+          unknown = flags.keys - FLAGS
+          raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
+
+          check_flags(flags)
+          @dry_run = flags.fetch(:dry_run, false)
+          @gem_only = flags.fetch(:gem_only, false)
+          @npm_only = flags.fetch(:npm_only, false)
+          @npm_local = flags.fetch(:npm_local, false)
+          @no_wait = flags.fetch(:no_wait, false)
+          @yes = flags.fetch(:yes, false)
+        end
+
+        # Says whether confirmations are answered automatically.
+        #
+        # @return [Boolean] true under `--yes`
+        def yes?
+          @yes
+        end
+
+        # Says whether the gem step is in scope.
+        #
+        # @return [Boolean] true unless `--npm-only`
+        def gem?
+          !@npm_only
+        end
+
+        # Says whether the npm step is in scope.
+        #
+        # @return [Boolean] true unless `--gem-only`
+        def npm?
+          !@gem_only
+        end
+
+        # Says whether the package is published from this machine.
+        #
+        # @return [Boolean] true under `--npm-local`
+        def npm_local?
+          @npm_local
+        end
+
+        # Says whether to wait for CI's publish to reach npm.
+        #
+        # @return [Boolean] true unless `--no-wait`
+        def wait?
+          !@no_wait
+        end
+
+        private
+
+        def check_flags(flags)
+          gem_only, npm_only, npm_local, no_wait = flags.values_at(:gem_only, :npm_only, :npm_local, :no_wait)
+          raise ArgumentError, "--gem-only and --npm-only cannot be combined" if gem_only && npm_only
+          raise ArgumentError, "--gem-only and --npm-local cannot be combined" if gem_only && npm_local
+          return unless no_wait && npm_local
+
+          raise ArgumentError, "--no-wait applies to CI's publish, so it cannot be combined with --npm-local"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/release/runner/preflight.rb

@@ -2,14 +2,15 @@ require "json"
 require_relative "commands"
 require_relative "git"
 require_relative "clean_tree"
+require_relative "../lane"
 
 module Hecks
   module Release
     class Runner
       # The checks that run before a release does anything: tools installed, a
-      # clean current `main`, matching versions, and a changelog entry.
+      # clean current release lane (`stable`), matching versions, and a changelog entry.
       class Preflight
-        # What the checks learned; `sha` is also `origin/main`, enforced by check_current.
+        # What the checks learned; `sha` is also `origin/<release lane>`, enforced by check_current.
         Facts = Struct.new(:version, :sha, keyword_init: true)
 
         INSTALL_HINTS = {
@@ -63,9 +64,9 @@ module Hecks
 
         def check_branch
           branch = git("rev-parse", "--abbrev-ref", "HEAD").strip
-          return if branch == "main"
+          return if branch == lane
 
-          raise Refusal, "on branch #{branch}, not main; release from main: git checkout main"
+          raise Refusal, "on branch #{branch}, not #{lane}; release from #{lane}: git checkout #{lane}"
         end
 
         def check_current
@@ -73,13 +74,17 @@ module Hecks
           raise Refusal, "git fetch origin failed (#{fetch.stderr.strip}); check the network and the remote" unless fetch.success?
 
           head = git("rev-parse", "HEAD").strip
-          upstream = git("rev-parse", "origin/main").strip
+          upstream = git("rev-parse", "origin/#{lane}").strip
           return if head == upstream
 
-          raise Refusal, "main (#{head[0, 7]}) is not origin/main (#{upstream[0, 7]}); " \
-                         "merge the release PR, then git pull --ff-only"
+          raise Refusal, "#{lane} (#{head[0, 7]}) is not origin/#{lane} (#{upstream[0, 7]}); " \
+                         "wait for the release commit to be promoted, then git pull --ff-only"
         end
 
+        # The lane a release is cut from: the one that feeds a tag, never the one that takes
+        # pushes with no gate.
+        def lane = @lane ||= Lane.release
+
         def check_clean
           unless git("status", "--porcelain").strip.empty?
             raise Refusal, "the working tree has uncommitted changes; commit or discard them before releasing"

data/lib/hecks/release/runner/publishing.rb

@@ -0,0 +1,86 @@
+module Hecks
+  module Release
+    class Runner
+      # The publish half of a release: what to publish, the confirmation, and the gem and npm
+      # steps. Included in `Runner`.
+      module Publishing
+        private
+
+        def publish(facts, pending)
+          if pending.empty?
+            @console.say("Nothing to publish for #{facts.version}.")
+            @verified = registries_list?(facts.version, in_scope) unless @options.dry_run
+            return 0
+          end
+          run_steps(facts.version, pending)
+        end
+
+        # What pushing the tag sets off, for the tag question; nothing when CI publishes nothing.
+        def tag_note(version, pending)
+          return unless ci_publishes?(pending)
+
+          "CI then publishes @hecks/client #{version} to npm from the tag, which cannot be undone"
+        end
+
+        def publish_confirmed?(version, pending)
+          targets = []
+          targets << "hecks #{version} to rubygems.org" if pending.include?(:gem)
+          targets << "@hecks/client #{version} to npm" if pending.include?(:npm) && @options.npm_local?
+          return true if targets.empty?
+
+          suffix = ci_publishes?(pending) ? " (CI then publishes @hecks/client from the tag)" : ""
+          @console.confirm?("Publish #{targets.join(" and ")}#{suffix}? This cannot be undone.")
+        end
+
+        def run_steps(version, pending)
+          dry_run = @options.dry_run
+          publish_gem(version, dry_run) if pending.include?(:gem)
+          return 1 if pending.include?(:npm) && !publish_npm!(version, dry_run, ci_publishes?(pending))
+
+          @verified = registries_list?(version, pending) unless dry_run
+
+          @console.say(dry_run ? "Dry run complete; nothing was tagged, pushed or published." : "Released hecks #{version}.")
+          0
+        end
+
+        def publish_gem(version, dry_run)
+          GemPublisher.new(root: @root, commands: @commands, console: @console).publish!(version, dry_run: dry_run)
+          @steps << :gem unless dry_run
+        end
+
+        # Asks each registry a step published to whether it now lists the version.
+        def registries_list?(version, pending)
+          (!pending.include?(:gem) || @published.gem?(version)) && (!pending.include?(:npm) || @published.npm?(version))
+        rescue Refusal
+          false
+        end
+
+        def publish_npm!(version, dry_run, via_ci)
+          return wait_for_ci!(version, dry_run) if via_ci
+
+          NpmPublisher.new(root: @root, commands: @commands, console: @console).publish!(version, dry_run: dry_run)
+          @steps << :npm unless dry_run
+          true
+        rescue CommandFailed => e
+          warn_npm_failed(e, dry_run)
+          raise
+        end
+
+        def warn_npm_failed(error, dry_run)
+          @console.warn("npm publish failed: #{error.message}")
+          return if dry_run
+
+          @console.warn("Finish the release with: hecks publish --npm-only --npm-local --confirm " \
+                        "(published steps are not repeated)")
+        end
+
+        def wait_for_ci!(version, dry_run)
+          arrived = @ci.wait!(version, dry_run: dry_run, wait: @options.wait?)
+          @steps << :npm if arrived && !dry_run
+          @console.warn(CiPublisher.timeout_hint(version)) unless arrived
+          arrived
+        end
+      end
+    end
+  end
+end

data/lib/hecks/release/runner/tagger.rb

@@ -33,10 +33,15 @@ module Hecks
           return true.tap { preview(tag, facts.sha, local) } if @dry_run
           return false unless @console.confirm?(question(tag, facts.sha, local, note))
 
-          create(tag, facts.sha) unless local
+          change_tag(tag, facts.sha, local)
+          true
+        end
+
+        # Creates the tag if it is missing and pushes it, which this run then reports as a change.
+        def change_tag(tag, sha, local)
+          create(tag, sha) unless local
           push(tag)
           @changed = true
-          true
         end
 
         # @param tag [String] the tag, such as `v3.0.0`
@@ -72,7 +77,7 @@ module Hecks
         end
 
         def create(tag, sha)
-          @git.run!("tag", "-a", tag, "-m", "Release #{tag.delete_prefix('v')}", sha)
+          @git.run!("tag", "-a", tag, "-m", "Release #{tag.delete_prefix("v")}", sha)
         end
 
         def push(tag)