rails-hyperdrive 0.6.0 → 0.7.0

data/lib/rails/hyperdrive/canonical_skill_render.rb

@@ -1,6 +1,8 @@
 require "fileutils"
 require "yaml"
 require "rails/hyperdrive/bundler_artifact_discovery"
+require "rails/hyperdrive/gem_manifest"
+require "rails/hyperdrive/gemspec_locator"
 require "rails/hyperdrive/skill_template"
 
 module Rails
@@ -9,75 +11,102 @@ module Rails
     # SKILL.md it pairs with, using the canonical fail-open binding.
     # Companion-repo dev tooling: problems raise.
     module CanonicalSkillRender
-      Error = Class.new(StandardError)
+      Error = GemspecLocator::Error
+
+      PUBLIC_SKILLS_DIR = "skills".freeze
 
       Rendered = Struct.new(:template, :dest, :body, keyword_init: true)
 
+      # `public_skills_root` is where generic skills.sh consumers read whether
+      # or not the gem declares a content root; `skills_root` is where this
+      # gem's rendered faces belong.
+      Roots = Struct.new(:skills_root, :templates_root, :public_skills_root, keyword_init: true)
+
       module_function
 
-      def write(gemspec: nil, dir: Dir.pwd)
-        render_all(gemspec: gemspec, dir: dir).each do |r|
+      # Resolved once per task so a check does not load the gemspec twice.
+      def resolve_roots(gemspec: nil, dir: Dir.pwd)
+        spec, gem_root = GemspecLocator.load_spec(gemspec, dir)
+        path = File.join(gem_root, GemManifest.manifest_relpath(spec))
+        # Rendering with default roots over a manifest the installer cannot
+        # read would mask the bug this surface exists to catch.
+        manifest, failure = GemManifest.read_root(path)
+        raise Error, "#{path}: #{failure}" if failure
+
+        Roots.new(
+          skills_root: File.join(gem_root, manifest_dir(manifest, "skills_dir", path) || PUBLIC_SKILLS_DIR),
+          templates_root: File.join(gem_root, manifest_dir(manifest, "skill_templates_dir", path) ||
+            File.join("lib", spec.name, "hyperdrive", "skills")),
+          public_skills_root: File.join(gem_root, PUBLIC_SKILLS_DIR)
+        )
+      end
+
+      def manifest_dir(manifest, key, path)
+        value, failure = GemManifest.read_dir(manifest, key)
+        raise Error, "#{path}: #{failure}" if failure
+        value
+      end
+
+      def write(gemspec: nil, dir: Dir.pwd, roots: nil)
+        render_all(gemspec: gemspec, dir: dir, roots: roots).each do |r|
           FileUtils.mkdir_p(File.dirname(r.dest))
           File.write(r.dest, r.body)
         end
       end
 
-      def stale(gemspec: nil, dir: Dir.pwd)
-        render_all(gemspec: gemspec, dir: dir).reject do |r|
+      def stale(gemspec: nil, dir: Dir.pwd, roots: nil)
+        render_all(gemspec: gemspec, dir: dir, roots: roots).reject do |r|
           File.file?(r.dest) && File.read(r.dest) == r.body
         end
       end
 
-      def render_all(gemspec: nil, dir: Dir.pwd)
-        spec_path = resolve_gemspec_path(gemspec, dir)
-        spec = Gem::Specification.load(spec_path)
-        raise Error, "could not load gemspec #{spec_path}" unless spec
-
-        gem_root = File.dirname(File.expand_path(spec_path))
-        skills_root = File.join(gem_root, metadata_dir(spec, "rails_hyperdrive_skills_dir"))
-        templates_root = File.join(gem_root, metadata_dir(spec, "rails_hyperdrive_skill_templates_dir"))
+      def render_all(gemspec: nil, dir: Dir.pwd, roots: nil)
+        roots ||= resolve_roots(gemspec: gemspec, dir: dir)
+        templates_root = roots.templates_root
 
-        Dir.glob(File.join(templates_root, "**", "SKILL.md.erb")).sort.map do |template|
+        Dir.glob(File.join(templates_root, "**", "SKILL.md.erb")).sort.flat_map do |template|
           rel = File.dirname(template).delete_prefix(templates_root).delete_prefix("/")
-          dest_dir = File.join(skills_root, rel)
+          dest_dir = File.join(roots.skills_root, rel)
           # A SKILL.md written beside the SKILL.md.erb would take precedence
           # over it at discovery time, silently demoting the skill to its
           # static face.
           if File.expand_path(dest_dir) == File.expand_path(File.dirname(template))
             raise Error, "#{template}: content dir equals template dir; set " \
-                         "spec.metadata[\"rails_hyperdrive_skills_dir\"] to a separate root"
+                         "skills_dir: in hyperdrive.yml to a separate root"
           end
 
           body = render_template(template)
           validate_output!(body, template)
-          Rendered.new(template: template, dest: File.join(dest_dir, "SKILL.md"), body: body)
+          [Rendered.new(template: template, dest: File.join(dest_dir, "SKILL.md"), body: body)] +
+            support_renders(File.dirname(template), dest_dir)
         end
       end
 
-      def resolve_gemspec_path(explicit, dir)
-        if explicit && !explicit.to_s.strip.empty?
-          path = File.expand_path(explicit.to_s, dir)
-          raise Error, "gemspec not found: #{path}" unless File.file?(path)
-          return path
-        end
-
-        found = Dir.glob(File.join(dir, "*.gemspec"))
-        case found.size
-        when 1 then File.expand_path(found.first)
-        when 0 then raise Error, "no .gemspec found in #{dir}; pass an explicit path, " \
-                                 "e.g. rake \"hyperdrive:skills:render[path/to/name.gemspec]\""
-        else raise Error, "multiple gemspecs found in #{dir} " \
-                          "(#{found.map { |f| File.basename(f) }.join(", ")}); pass an explicit path"
+      # Supporting files carry no frontmatter contract, so their faces are
+      # written unvalidated.
+      def support_renders(template_dir, dest_dir)
+        Dir.glob(File.join(template_dir, "**", "*.md.erb")).sort.filter_map do |template|
+          rel = template.delete_prefix("#{template_dir}/")
+          next if File.basename(rel) == "SKILL.md.erb"
+          Rendered.new(
+            template: template,
+            dest: File.join(dest_dir, rel.delete_suffix(".erb")),
+            body: render_template(template)
+          )
         end
       end
 
-      def metadata_dir(spec, key)
-        default = File.join("lib", spec.name, "hyperdrive", "skills")
-        raw = spec.metadata && spec.metadata[key]
-        return default if raw.nil? || raw.to_s.strip.empty?
-        raise Error, "gemspec metadata #{key} must not contain '..' segments" if
-          raw.to_s.split(%r{[/\\]}).include?("..")
-        raw.to_s
+      # A *.md.erb reachable through a public skills root is copied verbatim by
+      # generic skills.sh consumers.
+      def public_erb_templates(gemspec: nil, dir: Dir.pwd, roots: nil)
+        roots ||= resolve_roots(gemspec: gemspec, dir: dir)
+        templates_root = File.expand_path(roots.templates_root)
+
+        [roots.public_skills_root, roots.skills_root]
+          .uniq { |r| File.expand_path(r) }
+          .flat_map { |root| Dir.glob(File.join(root, "**", "*.md.erb")) }
+          .reject { |path| File.expand_path(path).start_with?("#{templates_root}/") }
+          .uniq.sort
       end
 
       def render_template(template)
@@ -99,7 +128,7 @@ module Rails
         raise Error, "#{template}: rendered frontmatter is not parseable YAML"
       end
 
-      private_class_method :resolve_gemspec_path, :metadata_dir, :render_template, :validate_output!
+      private_class_method :manifest_dir, :support_renders, :render_template, :validate_output!
     end
   end
 end

data/lib/rails/hyperdrive/companion_discovery.rb

@@ -10,11 +10,10 @@ require "bundler"
 module Rails
   module Hyperdrive
     class CompanionDiscovery
-      TARGETS_KEY         = "rails_hyperdrive_targets".freeze
-      ARTIFACTS_KEY       = "rails_hyperdrive_artifacts".freeze
-      # Field-scoped metadata search is an undocumented passthrough to the
-      # rubygems search backend, so it fails open: if it ever stops matching, the
-      # query returns an empty 200 page and discovery reports no suggestions.
+      TARGETS_KEY         = "hyperdrive_targets".freeze
+      ARTIFACTS_KEY       = "hyperdrive_artifacts".freeze
+      # An undocumented passthrough to the rubygems search backend: if it stops
+      # matching, it degrades to an empty 200 page (no suggestions), never an error.
       SEARCH_QUERY        = "metadata.#{TARGETS_KEY}:*".freeze
       SEARCH_ENDPOINT     = "https://rubygems.org/api/v1/search.json".freeze
       CACHE_RELATIVE_PATH = ".hyperdrive/discover_cache.json".freeze

data/lib/rails/hyperdrive/gem_manifest.rb

@@ -1,26 +1,64 @@
 require "yaml"
+require "rails/hyperdrive/install_layout"
 
 module Rails
   module Hyperdrive
-    # A companion gem's root manifest (hyperdrive.yml) declares artifact
-    # gating: top-level gem:/versions: defaults for the whole gem,
-    # per-skill entries keyed by the skill dir's relative path from its skills
-    # root, per-guideline entries keyed by filename. Fail-open at every level:
-    # malformed input warns and resolves to an ungated install — an artifact is
-    # never skipped because its gating could not be read, and nothing raises.
+    # Everything the installer reads from a companion gem: where each artifact
+    # kind lives, and which artifacts a given bundle gets.
+    # Fail-open at every level — malformed input warns and resolves to an
+    # ungated install at the default roots; an artifact is never skipped for
+    # unreadable config, and nothing raises.
     class GemManifest
       FILE_NAME = "hyperdrive.yml"
-      METADATA_KEY = "rails_hyperdrive_manifest"
+      METADATA_KEY = "hyperdrive_manifest"
+
+      SKILL_TEMPLATES_DIR_KEY = "skill_templates_dir".freeze
+      DIR_KEYS = (InstallLayout.dir_keys + [SKILL_TEMPLATES_DIR_KEY]).freeze
 
       UNGATED = ["*"].freeze
+      MATCH_MODES = %w[any all].freeze
+      GEM_FORMS = "a gem, a comma-separated list, a YAML list of names and name: requirement " \
+                  "pairs, or an any:/all: map (gems: is an alias)".freeze
+      VERSIONS_REMOVED = "versions: is no longer supported; version constraints ignored — " \
+                         "put the requirement on the gem: member, e.g. `- name: \">= 1.0\"`".freeze
+
+      Gate = Struct.new(:targets, :versions, :hyperdrive_version, :conditional, :match_mode,
+        keyword_init: true)
+
+      # `warning`, when set, is phrased for the caller to prefix with its own
+      # context — the parser has no idea which entry it is reading.
+      TargetSpec = Struct.new(:targets, :match_mode, :versions, :warning, keyword_init: true)
 
-      Gate = Struct.new(:targets, :versions, :conditional, keyword_init: true)
+      GemKey = Struct.new(:value, :present, :conflict, :warning, keyword_init: true)
 
       class << self
         def load(spec, warnings: [])
           new(spec, warnings: warnings)
         end
 
+        # gems: and gem: are exact aliases. A map carrying both is a stylistic
+        # slip, not malformed input: picking a winner keeps the gate intact
+        # where failing open would silently widen it.
+        def gem_key(map)
+          both = map.key?("gem") && map.key?("gems")
+          GemKey.new(
+            value: map.key?("gems") ? map["gems"] : map["gem"],
+            present: map.key?("gem") || map.key?("gems"),
+            conflict: both,
+            warning: ("gem: and gems: are aliases; reading gems: and ignoring gem:" if both)
+          )
+        end
+
+        # ".." segments are rejected (silent fallback to the conventional path)
+        # to prevent escaping the gem root.
+        def manifest_relpath(spec)
+          return FILE_NAME unless spec.respond_to?(:metadata)
+          raw = spec.metadata && spec.metadata[METADATA_KEY]
+          return FILE_NAME if raw.nil? || raw.to_s.strip.empty?
+          return FILE_NAME if raw.to_s.split(%r{[/\\]}).include?("..")
+          raw.to_s
+        end
+
         # The metadata key counts even when its value is unusable — declaring
         # it at all signals companion intent.
         def opt_in?(spec)
@@ -31,52 +69,194 @@ module Rails
           !raw.to_s.strip.empty?
         end
 
+        # nil signals malformed; the caller decides how to fail open.
         def parse_targets(raw)
-          entries = raw.is_a?(Array) ? raw : [raw]
-          return nil if entries.any? { |e| e.nil? || e.is_a?(Array) || e.is_a?(Hash) }
-          entries.flat_map { |e| e.to_s.split(",") }.map(&:strip).reject(&:empty?)
+          return parse_target_map(raw) if raw.is_a?(Hash)
+          parse_target_names(raw)
         end
 
-        # versions: is optional everywhere; nil means unconstrained.
+        # A version requirement is optional everywhere; nil means unconstrained.
         def malformed_requirements?(versions)
           requirements = versions.is_a?(Hash) ? versions.values : [versions]
           requirements.compact.any? do |req|
-            parts = Array(req).flat_map { |s| s.is_a?(String) ? s.split(",").map(&:strip) : s }
             begin
-              Gem::Requirement.new(*parts)
+              Gem::Requirement.new(*requirement_parts(req))
               false
             rescue ArgumentError
               true
             end
           end
         end
+
+        # The fence names one requirement against one version, so a per-gem
+        # requirement map is meaningless here.
+        def malformed_fence?(value)
+          return true if value.is_a?(Hash)
+          malformed_requirements?(value)
+        end
+
+        def requirement_parts(req)
+          Array(req).flat_map { |s| s.is_a?(String) ? s.split(",").map(&:strip) : s }
+        end
+
+        # Returns [relative directory or nil, failure reason or nil]. Absent or
+        # blank is no failure — the caller uses its own default root. ".."
+        # segments are rejected to prevent escaping the gem root.
+        def read_dir(root, key)
+          raw = root[key]
+          return [nil, nil] if raw.nil?
+          return [nil, "#{key}: must be a directory path relative to the gem root"] unless raw.is_a?(String)
+          return [nil, nil] if raw.strip.empty?
+          return [nil, "#{key}: must not contain '..' segments"] if raw.split(%r{[/\\]}).include?("..")
+
+          [raw, nil]
+        end
+
+        # Returns [root map or nil, failure reason or nil]. An absent or empty
+        # file is a valid empty manifest; the caller phrases the failure and
+        # decides whether to fall open on it.
+        def read_root(path)
+          return [{}, nil] unless File.file?(path)
+
+          data = YAML.safe_load(File.read(path), permitted_classes: [Symbol])
+          return [{}, nil] if data.nil?
+          return [data.transform_keys(&:to_s), nil] if data.is_a?(Hash)
+
+          [nil, "root must be a YAML map"]
+        rescue Psych::SyntaxError => e
+          [nil, "malformed YAML (#{e.message})"]
+        rescue StandardError => e
+          [nil, "unreadable (#{e.message})"]
+        end
+
+        private
+
+        # A list member is either a bare gem name (unconstrained, comma-split
+        # for the inline multi-name spelling) or a single-pair map carrying
+        # that member's own version requirement.
+        def parse_target_names(raw)
+          entries = raw.is_a?(Array) ? raw : [raw]
+          names = []
+          requirements = {}
+          dropped_star = false
+
+          entries.each do |entry|
+            case entry
+            when Hash
+              name, requirement = pair_member(entry)
+              return nil unless name
+              if name == "*"
+                dropped_star = true
+                next
+              end
+              names << name
+              requirements[name] = requirement if requirement
+            when nil, Array
+              return nil
+            else
+              names.concat(entry.to_s.split(",").map(&:strip).reject(&:empty?))
+            end
+          end
+
+          names = UNGATED.dup if names.empty? && dropped_star
+          TargetSpec.new(
+            targets: names,
+            match_mode: :any,
+            versions: requirements.empty? ? nil : requirements,
+            warning: ("a version requirement on '*' is meaningless; ignoring that member" if dropped_star)
+          )
+        end
+
+        # nil signals a malformed member. A "*" key is kept for the caller to
+        # drop — its requirement is meaningless, not unreadable.
+        def pair_member(entry)
+          return nil unless entry.size == 1
+
+          name, requirement = entry.first
+          name = name.to_s.strip
+          return nil if name.empty?
+          return [name, nil] if name == "*"
+          return nil if requirement.is_a?(Hash)
+          return [name, nil] if requirement.nil? || requirement == "*"
+          return nil if malformed_requirements?(requirement)
+
+          [name, requirement]
+        end
+
+        def parse_target_map(raw)
+          keys = raw.keys.map(&:to_s)
+          return nil unless keys.size == 1 && MATCH_MODES.include?(keys.first)
+
+          # The list is the only container a mode key accepts. Reading a bare
+          # map as a one-member pair would make `{sidekiq: ">= 7"}` gate while
+          # its two-gem sibling falls open to ungated.
+          return nil if raw.values.first.is_a?(Hash)
+
+          spec = parse_target_names(raw.values.first)
+          return nil if spec.nil?
+          return spec if keys.first == "any"
+
+          all_target_spec(spec)
+        end
+
+        # "*" is satisfied by definition, so dropping it leaves the remaining
+        # targets gating; a list of nothing else has no targets left to gate on.
+        def all_target_spec(spec)
+          kept = spec.targets.reject { |n| n == "*" }
+          dropped = kept.size != spec.targets.size
+
+          TargetSpec.new(
+            targets: dropped && kept.empty? ? UNGATED : kept,
+            match_mode: :all,
+            versions: spec.versions,
+            warning: [spec.warning, ("'*' in all: is always satisfied; ignoring it" if dropped)]
+              .compact.join("; ").then { |w| w.empty? ? nil : w }
+          )
+        end
       end
 
       def initialize(spec, warnings:)
         @spec = spec
         @warnings = warnings
         root = load_root
-        @skills = section(root, "skills", "skill relpath")
-        @guidelines = section(root, "guidelines", "guideline filename")
-        @default_targets, @default_versions = defaults(root)
+        @sections = {}
+        @prefixes = {}
+        InstallLayout.content_kinds.each do |kind|
+          entries, settings = section(root, kind)
+          @sections[kind.type] = entries
+          @prefixes[kind.type] = read_name_prefix(kind, settings)
+        end
+        @dirs = DIR_KEYS.each_with_object({}) { |key, h| h[key] = resolve_dir(root, key) }
+        @default_spec, @default_fence = defaults(root)
+      end
+
+      def gate(type, key)
+        entries = @sections[type] || {}
+        return default_gate unless entries.key?(key)
+        entry_gate(entries[key], key, with_conditional: InstallLayout.kind(type).dir_shaped?)
+      end
+
+      def section_keys(type)
+        (@sections[type] || {}).keys
       end
 
-      def skill_gate(rel)
-        return default_gate unless @skills.key?(rel)
-        entry_gate(@skills[rel], rel, with_conditional: true)
+      # The section-level scalar a kind prepends to every artifact name it
+      # discovers; nil when absent or unusable.
+      def name_prefix(type)
+        @prefixes[type]
       end
 
-      def guideline_gate(filename)
-        return default_gate unless @guidelines.key?(filename)
-        entry_gate(@guidelines[filename], filename, with_conditional: false)
+      # nil means the caller's default root.
+      def dir(key)
+        @dirs[key.to_s]
       end
 
-      def skill_keys
-        @skills.keys
+      def skills_dir
+        dir(InstallLayout.kind(:skill).dir_key)
       end
 
-      def guideline_keys
-        @guidelines.keys
+      def skill_templates_dir
+        dir(SKILL_TEMPLATES_DIR_KEY)
       end
 
       private
@@ -85,88 +265,139 @@ module Rails
         @warnings << "#{@spec.name}: #{message}"
       end
 
-      # ".." segments are rejected (silent fallback to the conventional path)
-      # to prevent escaping the gem root.
       def manifest_relpath
-        return FILE_NAME unless @spec.respond_to?(:metadata)
-        raw = @spec.metadata && @spec.metadata[METADATA_KEY]
-        return FILE_NAME if raw.nil? || raw.to_s.strip.empty?
-        return FILE_NAME if raw.to_s.split(%r{[/\\]}).include?("..")
-        raw.to_s
+        self.class.manifest_relpath(@spec)
       end
 
-      # An empty file is a valid manifest (nothing gated); only content that
-      # cannot be read as a YAML map warns.
+      # Gating that cannot be read must never keep content out, so a failure
+      # here resolves to an absent manifest.
       def load_root
-        path = File.join(@spec.full_gem_path, manifest_relpath)
-        return {} unless File.file?(path)
-
-        data = YAML.safe_load(File.read(path), permitted_classes: [Symbol])
-        return {} if data.nil?
-        unless data.is_a?(Hash)
-          report("ignoring manifest #{manifest_relpath}: root must be a YAML map")
-          return {}
-        end
-        data.transform_keys(&:to_s)
-      rescue Psych::SyntaxError
-        report("ignoring manifest #{manifest_relpath}: malformed YAML")
-        {}
-      rescue StandardError => e
-        report("ignoring manifest #{manifest_relpath}: unreadable (#{e.message})")
+        root, failure = self.class.read_root(File.join(@spec.full_gem_path, manifest_relpath))
+        return root if root
+
+        report("ignoring manifest #{manifest_relpath}: #{failure}")
         {}
       end
 
-      def section(root, key, key_label)
-        value = root[key]
-        return {} if value.nil?
+      def resolve_dir(root, key)
+        value, failure = self.class.read_dir(root, key)
+        report("manifest top-level #{failure}; ignoring it") if failure
+        value
+      end
+
+      # Returns [gating entries, the kind's reserved section-level settings].
+      def section(root, kind)
+        value = root[kind.section]
+        return [{}, {}] if value.nil?
         unless value.is_a?(Hash)
-          report("manifest #{key}: must be a map of #{key_label} to {gem:, versions:}; ignoring the section")
-          return {}
+          report("manifest #{kind.section}: must be a map of #{kind.key_label} to a gating map; ignoring the section")
+          return [{}, {}]
         end
-        value.transform_keys(&:to_s)
+
+        entries = value.transform_keys(&:to_s)
+        reserved = Array(kind.prefix_key)
+        [entries.reject { |k, _| reserved.include?(k) }, entries.slice(*reserved)]
       end
 
+      # A prefix becomes part of the installed filename, so anything that could
+      # reach outside the kind's directory is refused rather than sanitized.
+      def read_name_prefix(kind, settings)
+        key = kind.prefix_key
+        return nil unless key
+
+        raw = settings[key]
+        return nil if raw.nil?
+        unless raw.is_a?(String)
+          report("manifest #{kind.section} #{key}: must be a name prefix string; ignoring it")
+          return nil
+        end
+
+        prefix = raw.strip
+        return nil if prefix.empty?
+        return prefix unless prefix.match?(%r{[/\\]}) || prefix.include?("..")
+
+        report("manifest #{kind.section} #{key}: must not contain path separators or '..' segments; ignoring it")
+        nil
+      end
+
+      # Independent axes: an unusable gem: must not silence a parseable fence,
+      # the one gate that keeps content out of an installer too old to read it.
       def defaults(root)
-        targets = root.key?("gem") ? self.class.parse_targets(root["gem"]) : nil
-        bad_targets = root.key?("gem") && (targets.nil? || targets.empty?)
-        if bad_targets || self.class.malformed_requirements?(root["versions"])
-          report("manifest top-level gem:/versions: defaults are unusable; ignoring them")
-          return [nil, nil]
+        report("manifest top-level #{VERSIONS_REMOVED}") if root.key?("versions")
+        [default_target_spec(root), default_fence(root)]
+      end
+
+      def default_target_spec(root)
+        gem_key = self.class.gem_key(root)
+        report("manifest top-level #{gem_key.warning}") if gem_key.warning
+        return nil unless gem_key.present
+
+        parsed = self.class.parse_targets(gem_key.value)
+        if parsed.nil? || parsed.targets.empty?
+          report("manifest top-level gem: default is unusable; ignoring it")
+          return nil
         end
-        [targets, root["versions"]]
+        report("manifest top-level gem: #{parsed.warning}") if parsed.warning
+        parsed
+      end
+
+      def default_fence(root)
+        return root["hyperdrive_version"] unless self.class.malformed_fence?(root["hyperdrive_version"])
+
+        report("manifest top-level hyperdrive_version: default is unusable; ignoring it")
+        nil
       end
 
       def default_gate
-        Gate.new(targets: @default_targets || UNGATED, versions: @default_versions, conditional: nil)
+        build_gate(@default_spec, hyperdrive_version: @default_fence)
       end
 
-      def ungated
-        Gate.new(targets: UNGATED, versions: nil, conditional: nil)
+      def ungated(hyperdrive_version: nil)
+        build_gate(nil, hyperdrive_version: hyperdrive_version)
       end
 
-      # A malformed entry drops the gem-wide defaults too: gating that cannot
-      # be read must not skip the artifact, so it installs ungated.
+      def build_gate(target_spec, hyperdrive_version: nil, conditional: nil)
+        Gate.new(
+          targets: target_spec ? target_spec.targets : UNGATED,
+          versions: target_spec&.versions,
+          hyperdrive_version: hyperdrive_version,
+          conditional: conditional,
+          match_mode: target_spec ? target_spec.match_mode : :any
+        )
+      end
+
+      # Gating that cannot be read must not skip the artifact, so a malformed
+      # entry installs ungated, gem-wide gem: default and all. The fence is
+      # resolved first and rides those fall-throughs — except where it is
+      # itself the unparsable part, since the gem-wide default would then apply
+      # a constraint this entry never asked for.
       def entry_gate(entry, key, with_conditional:)
         unless entry.is_a?(Hash)
-          report("manifest entry for '#{key}' must be a map with gem:/versions:; installing ungated")
-          return ungated
+          report("manifest entry for '#{key}' must be a map with gem:; installing ungated unless fenced out")
+          return ungated(hyperdrive_version: @default_fence)
         end
 
         entry = entry.transform_keys(&:to_s)
-        targets = entry.key?("gem") ? self.class.parse_targets(entry["gem"]) : nil
-        if entry.key?("gem") && (targets.nil? || targets.empty?)
-          report("manifest entry for '#{key}': gem: must name a gem, a comma-separated list, " \
-                 "or a YAML list; installing ungated")
+        if self.class.malformed_fence?(entry["hyperdrive_version"])
+          report("manifest entry for '#{key}' has an unparsable hyperdrive_version: requirement; " \
+                 "installing ungated and unfenced")
           return ungated
         end
-        if self.class.malformed_requirements?(entry["versions"])
-          report("manifest entry for '#{key}' has an unparsable versions: requirement; installing ungated")
-          return ungated
+        fence = entry.key?("hyperdrive_version") ? entry["hyperdrive_version"] : @default_fence
+
+        gem_key = self.class.gem_key(entry)
+        report("manifest entry for '#{key}': #{gem_key.warning}") if gem_key.warning
+        parsed = gem_key.present ? self.class.parse_targets(gem_key.value) : nil
+        if gem_key.present && (parsed.nil? || parsed.targets.empty?)
+          report("manifest entry for '#{key}': gem: must name #{GEM_FORMS}; installing ungated unless fenced out")
+          return ungated(hyperdrive_version: fence)
         end
+        report("manifest entry for '#{key}': #{VERSIONS_REMOVED}") if entry.key?("versions")
+        report("manifest entry for '#{key}' gem: #{parsed.warning}") if parsed&.warning
 
-        Gate.new(
-          targets: targets || @default_targets || UNGATED,
-          versions: entry.key?("versions") ? entry["versions"] : @default_versions,
+        build_gate(
+          parsed || @default_spec,
+          hyperdrive_version: fence,
           conditional: with_conditional ? entry["conditional"] : nil
         )
       end