rails-hyperdrive 0.4.0 → 0.6.0

data/lib/rails/hyperdrive/bundler_artifact_discovery.rb

@@ -1,17 +1,17 @@
 require "yaml"
 require "bundler"
+require "rails/hyperdrive/gem_manifest"
 require "rails/hyperdrive/skill_template"
 
 module Rails
   module Hyperdrive
     module BundlerArtifactDiscovery
       SKILL_FILE_NAMES = ["SKILL.md", "SKILL.md.erb"].freeze
-      INSTALLER_KEY = /\A(?:gem|versions|conditional):/.freeze
 
       Artifact = Struct.new(
         :name, :description, :target_gem, :versions, :artifact_type,
         :source_gem, :path, :body, :spec_version, :support_files,
-        :source_root,
+        :source_root, :support_root,
         keyword_init: true
       ) do
         def skill?
@@ -34,17 +34,30 @@ module Rails
       module_function
 
       # Non-fatal problems are appended to `warnings` and the artifact is
-      # dropped; discovery never raises.
-      def discover(specs: nil, warnings: [])
+      # dropped; discovery never raises. A gem that has not opted in as a
+      # companion is never scanned — its skills.sh content is only reported
+      # through `notices`.
+      def discover(specs: nil, warnings: [], enabled_gems: [], notices: [])
         specs ||= safe_bundler_specs
+        enabled = Array(enabled_gems).map(&:to_s)
         resolved = specs.each_with_object({}) { |s, h| h[s.name.to_s] = s.version }
 
         candidates = []
         specs.each do |spec|
-          each_artifact_path(spec, warnings: warnings) do |path, type|
-            artifact = parse(path, source_spec: spec, type: type, resolved: resolved, warnings: warnings)
+          unless opted_in?(spec, enabled_gems: enabled)
+            notice_skills_sh_content(spec, notices: notices)
+            next
+          end
+          manifest = GemManifest.load(spec, warnings: warnings)
+          seen = { skill: [], guideline: [] }
+          each_artifact_path(spec, warnings: warnings) do |path, type, support_root, key|
+            seen[type] << key
+            gate = type == :skill ? manifest.skill_gate(key) : manifest.guideline_gate(key)
+            artifact = parse(path, source_spec: spec, type: type, resolved: resolved,
+              warnings: warnings, support_root: support_root, gate: gate)
             candidates << artifact if artifact
           end
+          warn_unknown_manifest_keys(manifest, spec, seen, warnings)
         end
 
         # Collapse same-name variants within one source gem (highest
@@ -55,29 +68,137 @@ module Rails
         end
       end
 
+      # Yields each candidate with its manifest join key: a skill's relpath
+      # from its skills root, a guideline's filename. Keys are collected before
+      # parsing, so a candidate later dropped (e.g. an ERB render failure)
+      # still counts as known to the manifest.
       def each_artifact_path(spec, warnings: [])
-        skill_paths(spec, warnings: warnings).each { |p| yield p, :skill }
-        guideline_paths(spec).each { |p| yield p, :guideline }
+        skill_paths(spec, warnings: warnings).each { |path, support_root, rel| yield path, :skill, support_root, rel }
+        guideline_paths(spec).each { |p| yield p, :guideline, nil, File.basename(p) }
+      end
+
+      # The staleness signal for gating detached from content: an entry
+      # matching nothing means a renamed or removed skill dir/guideline.
+      def warn_unknown_manifest_keys(manifest, spec, seen, warnings)
+        (manifest.skill_keys - seen[:skill]).each do |key|
+          warnings << "#{spec.name}: manifest skills entry '#{key}' names no shipped skill directory"
+        end
+        (manifest.guideline_keys - seen[:guideline]).each do |key|
+          warnings << "#{spec.name}: manifest guidelines entry '#{key}' names no shipped guideline"
+        end
       end
 
       def skill_paths(spec, warnings: [])
-        roots = [File.join(spec.full_gem_path, "lib", spec.name, "hyperdrive", "skills")]
+        roots = [
+          File.join(spec.full_gem_path, "lib", spec.name, "hyperdrive", "skills"),
+          File.join(spec.full_gem_path, "skills")
+        ]
         if (override = skills_dir_override(spec))
           roots << File.join(spec.full_gem_path, override)
         end
-        found = roots.flat_map { |root| Dir.glob(File.join(root, "**", "{SKILL.md,SKILL.md.erb}")) }.uniq
-        found.group_by { |p| File.dirname(p) }.flat_map do |dir, group|
-          next group unless group.size > 1
-          warnings << "skip #{File.join(dir, "SKILL.md.erb")}: SKILL.md in the same directory takes precedence"
-          group.select { |p| File.basename(p) == "SKILL.md" }
+
+        candidates = []
+        seen = {}
+        roots.each do |root|
+          Dir.glob(File.join(root, "**", "{SKILL.md,SKILL.md.erb}"))
+             .group_by { |p| File.dirname(p) }.each do |dir, group|
+            next if seen[File.expand_path(dir)]
+            seen[File.expand_path(dir)] = true
+            candidates << {
+              dir: dir,
+              rel: dir.delete_prefix(root).delete_prefix("/"),
+              path: resolve_same_dir_tie(dir, group, warnings)
+            }
+          end
+        end
+
+        pair_with_templates(candidates, spec, warnings: warnings)
+      end
+
+      def resolve_same_dir_tie(dir, group, warnings)
+        return group.first unless group.size > 1
+        warnings << "skip #{File.join(dir, "SKILL.md.erb")}: SKILL.md in the same directory takes precedence"
+        group.find { |p| File.basename(p) == "SKILL.md" }
+      end
+
+      # A dir holding a static SKILL.md pairs with <templates root>/<same
+      # relative path>/SKILL.md.erb in a distinct dir: the rendered template is
+      # the definition, the static dir the support root. The static SKILL.md is
+      # never parsed — falling back to it when the template fails to render
+      # would silently un-condition the skill.
+      def pair_with_templates(candidates, spec, warnings:)
+        templates_root = File.join(spec.full_gem_path, skill_templates_dir(spec))
+
+        pairs = {}
+        candidates.each do |cand|
+          next unless File.basename(cand[:path]) == "SKILL.md"
+          template_dir = File.expand_path(File.join(templates_root, cand[:rel]))
+          next if template_dir == File.expand_path(cand[:dir])
+          template = File.join(template_dir, "SKILL.md.erb")
+          next unless File.file?(template)
+          warn_template_extras(template_dir, warnings)
+          pairs[cand[:dir]] = { template: template, template_dir: template_dir }
+        end
+
+        consumed = pairs.values.map { |p| p[:template_dir] }
+        candidates.filter_map do |cand|
+          if (pair = pairs[cand[:dir]])
+            [pair[:template], cand[:dir], cand[:rel]]
+          elsif consumed.include?(File.expand_path(cand[:dir]))
+            nil
+          else
+            [cand[:path], File.dirname(cand[:path]), cand[:rel]]
+          end
         end
       end
 
+      # The content dir is the single source of truth for supporting files.
+      def warn_template_extras(template_dir, warnings)
+        extras = Dir.glob(File.join(template_dir, "**", "*"))
+                    .select { |f| File.file?(f) && f != File.join(template_dir, "SKILL.md.erb") }
+        return if extras.empty?
+        warnings << "#{template_dir}: ignoring #{extras.size} file(s) besides SKILL.md.erb; " \
+                    "supporting files ship in the paired content directory"
+      end
+
       def guideline_paths(spec)
         root = File.join(spec.full_gem_path, "lib", spec.name, "hyperdrive", "guidelines")
         Dir.glob(File.join(root, "*.md"))
       end
 
+      # Many gemspecs package files via `git ls-files`, so a contributor-facing
+      # skills/ dir ships by accident — package contents don't signal consumer
+      # intent. Only an explicit signal makes a gem's content installable.
+      def opted_in?(spec, enabled_gems:)
+        return true if enabled_gems.include?(spec.name.to_s)
+        return true if metadata_present?(spec, "rails_hyperdrive_skills_dir")
+        return true if metadata_present?(spec, "rails_hyperdrive_skill_templates_dir")
+        return true if metadata_present?(spec, "rails_hyperdrive_targets")
+        return true if GemManifest.opt_in?(spec)
+
+        convention_root = File.join(spec.full_gem_path, "lib", spec.name, "hyperdrive")
+        Dir.glob(File.join(convention_root, "skills", "**", "{SKILL.md,SKILL.md.erb}")).any? ||
+          Dir.glob(File.join(convention_root, "guidelines", "*.md")).any?
+      end
+
+      def metadata_present?(spec, key)
+        return false unless spec.respond_to?(:metadata)
+        raw = spec.metadata && spec.metadata[key]
+        !raw.to_s.strip.empty?
+      end
+
+      # Report-only, glob-only (no file reads): SKILL.md presence is the
+      # signal, and SKILL.md.erb is excluded — raw ERB is not skills.sh
+      # content. Parse problems surface as warnings once the gem is enabled.
+      def notice_skills_sh_content(spec, notices:)
+        found = Dir.glob(File.join(spec.full_gem_path, "skills", "**", "SKILL.md"))
+        return if found.empty?
+
+        count = found.map { |p| File.dirname(p) }.uniq.size
+        notices << "gem '#{spec.name}' ships #{count} skills.sh skill(s); add \"#{spec.name}\" to enabled: " \
+                   "in .hyperdrive/lock.yml and re-run bin/rails hyperdrive:sync to install them"
+      end
+
       # ".." segments are rejected to prevent escaping the gem root.
       def skills_dir_override(spec)
         return nil unless spec.respond_to?(:metadata)
@@ -87,7 +208,19 @@ module Rails
         raw.to_s
       end
 
-      def parse(path, source_spec:, type:, resolved:, warnings:)
+      def skill_templates_dir(spec)
+        default = File.join("lib", spec.name, "hyperdrive", "skills")
+        return default unless spec.respond_to?(:metadata)
+        raw = spec.metadata && spec.metadata["rails_hyperdrive_skill_templates_dir"]
+        return default if raw.nil? || raw.to_s.strip.empty?
+        return default if raw.to_s.split(%r{[/\\]}).include?("..")
+        raw.to_s
+      end
+
+      # Frontmatter's schema is exactly name and description; any other key is
+      # unknown to the parser and rides untouched in the installed body.
+      def parse(path, source_spec:, type:, resolved:, warnings:, gate:, support_root: nil)
+        support_root ||= File.dirname(path)
         body = File.read(path)
         if erb_template?(path)
           begin
@@ -103,25 +236,20 @@ module Rails
           return nil
         end
 
-        meta        = YAML.safe_load(frontmatter, permitted_classes: [Symbol]) || {}
+        # Date is permitted because unknown frontmatter keys are user content;
+        # a bare date value must not fail the parse.
+        meta        = YAML.safe_load(frontmatter, permitted_classes: [Symbol, Date]) || {}
         name        = meta["name"]
         description = meta["description"]
-        versions    = meta["versions"]
-
-        unless name && description && meta["gem"] && versions
-          warnings << "skip #{path}: missing a required field (name, description, gem, versions)"
-          return nil
-        end
 
-        targets = parse_targets(meta["gem"])
-        if targets.nil? || targets.empty?
-          warnings << "skip #{name} (from #{source_spec.name}): gem: must name a gem, a comma-separated list, or a YAML list"
+        unless name && description
+          warnings << "skip #{path}: missing a required field (name, description)"
           return nil
         end
 
-        matched = match_targets(targets, versions, resolved)
+        matched = match_targets(gate.targets, gate.versions, resolved)
         if matched.empty?
-          warnings << "skip #{name} (from #{source_spec.name}): #{no_match_reason(targets, versions, resolved)}"
+          warnings << "skip #{name} (from #{source_spec.name}): #{no_match_reason(gate.targets, gate.versions, resolved)}"
           return nil
         end
 
@@ -129,17 +257,18 @@ module Rails
           name: name.to_s,
           description: description.to_s,
           target_gem: matched,
-          versions: versions,
+          versions: gate.versions,
           artifact_type: type,
           source_gem: source_spec.name.to_s,
           path: path,
           body: body,
           spec_version: source_spec.version.to_s,
           source_root: source_spec.full_gem_path.to_s,
+          support_root: support_root,
           support_files:
             if type == :skill
               conditioned_support_files(
-                File.dirname(path), meta["conditional"],
+                support_root, gate.conditional,
                 resolved: resolved, warnings: warnings,
                 label: "#{name} (from #{source_spec.name})"
               )
@@ -147,7 +276,7 @@ module Rails
               []
             end
         )
-      rescue Psych::SyntaxError
+      rescue Psych::Exception
         warnings << "skip #{path}: malformed YAML frontmatter"
         nil
       end
@@ -185,7 +314,7 @@ module Rails
         shipped = files.map { |f| f[:path] }
         conditions.each_key do |key|
           if SKILL_FILE_NAMES.include?(key)
-            warnings << "#{label}: conditional key '#{key}' ignored; the skill's own gem:/versions: gate the whole skill"
+            warnings << "#{label}: conditional key '#{key}' ignored; the entry's own gem:/versions: gate the whole skill"
           elsif !shipped.include?(key)
             warnings << "#{label}: conditional key '#{key}' names no shipped supporting file"
           end
@@ -203,14 +332,14 @@ module Rails
           return true
         end
 
-        targets = entry["gem"] && parse_targets(entry["gem"])
+        targets = entry["gem"] && GemManifest.parse_targets(entry["gem"])
         if targets.nil? || targets.empty?
           warnings << "#{label}: conditional entry for '#{key}' needs gem: naming a gem, a comma-separated list, or a YAML list; installing the file"
           return true
         end
 
         versions = entry["versions"]
-        if malformed_requirements?(versions)
+        if GemManifest.malformed_requirements?(versions)
           warnings << "#{label}: conditional entry for '#{key}' has an unparsable versions: requirement; installing the file"
           return true
         end
@@ -218,20 +347,6 @@ module Rails
         match_targets(targets, versions, resolved).any?
       end
 
-      # versions: is optional in a conditional entry; 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)
-            false
-          rescue ArgumentError
-            true
-          end
-        end
-      end
-
       def render_support_templates(files, skill_dir, resolved:, warnings:)
         plain_paths = files.map { |f| f[:path] }
         files.filter_map do |file|
@@ -256,36 +371,15 @@ module Rails
         path.end_with?(".md.erb")
       end
 
+      # Guideline frontmatter is stripped because the installed file is
+      # @-included eagerly into agent context, where it would be inert noise.
       def install_ready_body(artifact)
-        return strip_installer_keys(artifact.body) if artifact.skill?
+        return artifact.body if artifact.skill?
 
         _frontmatter, rest = split_frontmatter(artifact.body)
         (rest || artifact.body).sub(/\A\n+/, "")
       end
 
-      # gem:/versions:/conditional: are install-time inputs with no reader
-      # after install, and conditional: keys name *shipped* paths that gating
-      # and ERB retargeting can leave pointing at files absent from disk — so
-      # the installed frontmatter carries neither.
-      def strip_installer_keys(body)
-        frontmatter, rest = split_frontmatter(body)
-        return body unless frontmatter
-
-        kept = []
-        skipping = false
-        frontmatter.lines.each do |line|
-          if line =~ INSTALLER_KEY
-            skipping = true
-          elsif skipping && (line.start_with?(" ", "\t") || line.strip.empty?)
-            # continuation of a stripped key's block
-          else
-            skipping = false
-            kept << line
-          end
-        end
-        "---\n#{kept.join}---\n#{rest}"
-      end
-
       def split_frontmatter(body)
         lines = body.lines
         return [nil, body] unless lines.first&.strip == "---"
@@ -297,12 +391,6 @@ module Rails
         [lines[1...absolute_closing].join, lines[(absolute_closing + 1)..].join]
       end
 
-      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?)
-      end
-
       def match_targets(targets, versions, resolved)
         return ["*"] if targets.include?("*")
 
@@ -334,13 +422,15 @@ module Rails
         []
       end
 
-      private_class_method :each_artifact_path, :skill_paths, :guideline_paths,
-                           :skills_dir_override, :parse, :support_files_for,
+      private_class_method :each_artifact_path, :warn_unknown_manifest_keys, :skill_paths,
+                           :guideline_paths,
+                           :resolve_same_dir_tie, :pair_with_templates, :warn_template_extras,
+                           :opted_in?, :metadata_present?, :notice_skills_sh_content,
+                           :skills_dir_override, :skill_templates_dir, :parse, :support_files_for,
                            :conditioned_support_files, :apply_conditional_filter,
-                           :conditional_satisfied?, :malformed_requirements?,
+                           :conditional_satisfied?,
                            :render_support_templates, :erb_template?,
-                           :strip_installer_keys,
-                           :split_frontmatter, :parse_targets, :match_targets,
+                           :match_targets,
                            :version_satisfied?, :no_match_reason, :safe_bundler_specs
     end
   end

data/lib/rails/hyperdrive/canonical_skill_render.rb

@@ -0,0 +1,105 @@
+require "fileutils"
+require "yaml"
+require "rails/hyperdrive/bundler_artifact_discovery"
+require "rails/hyperdrive/skill_template"
+
+module Rails
+  module Hyperdrive
+    # Renders each SKILL.md.erb template in a companion gem repo to the static
+    # SKILL.md it pairs with, using the canonical fail-open binding.
+    # Companion-repo dev tooling: problems raise.
+    module CanonicalSkillRender
+      Error = Class.new(StandardError)
+
+      Rendered = Struct.new(:template, :dest, :body, keyword_init: true)
+
+      module_function
+
+      def write(gemspec: nil, dir: Dir.pwd)
+        render_all(gemspec: gemspec, dir: dir).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|
+          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"))
+
+        Dir.glob(File.join(templates_root, "**", "SKILL.md.erb")).sort.map do |template|
+          rel = File.dirname(template).delete_prefix(templates_root).delete_prefix("/")
+          dest_dir = File.join(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"
+          end
+
+          body = render_template(template)
+          validate_output!(body, template)
+          Rendered.new(template: template, dest: File.join(dest_dir, "SKILL.md"), body: body)
+        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"
+        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
+      end
+
+      def render_template(template)
+        SkillTemplate.render_canonical(File.read(template))
+      rescue SyntaxError, StandardError => e
+        raise Error, "#{template}: canonical render failed (#{e.message})"
+      end
+
+      # A static face with unusable frontmatter would ship a broken skill to
+      # consumers that read it directly.
+      def validate_output!(body, template)
+        frontmatter, = BundlerArtifactDiscovery.split_frontmatter(body)
+        raise Error, "#{template}: rendered output has no YAML frontmatter" unless frontmatter
+
+        meta = YAML.safe_load(frontmatter, permitted_classes: [Symbol]) || {}
+        return if meta["name"] && meta["description"]
+        raise Error, "#{template}: rendered frontmatter lacks name: or description:"
+      rescue Psych::SyntaxError
+        raise Error, "#{template}: rendered frontmatter is not parseable YAML"
+      end
+
+      private_class_method :resolve_gemspec_path, :metadata_dir, :render_template, :validate_output!
+    end
+  end
+end

data/lib/rails/hyperdrive/gem_manifest.rb

@@ -0,0 +1,175 @@
+require "yaml"
+
+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.
+    class GemManifest
+      FILE_NAME = "hyperdrive.yml"
+      METADATA_KEY = "rails_hyperdrive_manifest"
+
+      UNGATED = ["*"].freeze
+
+      Gate = Struct.new(:targets, :versions, :conditional, keyword_init: true)
+
+      class << self
+        def load(spec, warnings: [])
+          new(spec, warnings: warnings)
+        end
+
+        # The metadata key counts even when its value is unusable — declaring
+        # it at all signals companion intent.
+        def opt_in?(spec)
+          return true if File.file?(File.join(spec.full_gem_path, FILE_NAME))
+          return false unless spec.respond_to?(:metadata)
+
+          raw = spec.metadata && spec.metadata[METADATA_KEY]
+          !raw.to_s.strip.empty?
+        end
+
+        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?)
+        end
+
+        # versions: 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)
+              false
+            rescue ArgumentError
+              true
+            end
+          end
+        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)
+      end
+
+      def skill_gate(rel)
+        return default_gate unless @skills.key?(rel)
+        entry_gate(@skills[rel], rel, with_conditional: true)
+      end
+
+      def guideline_gate(filename)
+        return default_gate unless @guidelines.key?(filename)
+        entry_gate(@guidelines[filename], filename, with_conditional: false)
+      end
+
+      def skill_keys
+        @skills.keys
+      end
+
+      def guideline_keys
+        @guidelines.keys
+      end
+
+      private
+
+      def report(message)
+        @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
+      end
+
+      # An empty file is a valid manifest (nothing gated); only content that
+      # cannot be read as a YAML map warns.
+      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})")
+        {}
+      end
+
+      def section(root, key, key_label)
+        value = root[key]
+        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 {}
+        end
+        value.transform_keys(&:to_s)
+      end
+
+      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]
+        end
+        [targets, root["versions"]]
+      end
+
+      def default_gate
+        Gate.new(targets: @default_targets || UNGATED, versions: @default_versions, conditional: nil)
+      end
+
+      def ungated
+        Gate.new(targets: UNGATED, versions: nil, conditional: nil)
+      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 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
+        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")
+          return ungated
+        end
+        if self.class.malformed_requirements?(entry["versions"])
+          report("manifest entry for '#{key}' has an unparsable versions: requirement; installing ungated")
+          return ungated
+        end
+
+        Gate.new(
+          targets: targets || @default_targets || UNGATED,
+          versions: entry.key?("versions") ? entry["versions"] : @default_versions,
+          conditional: with_conditional ? entry["conditional"] : nil
+        )
+      end
+    end
+  end
+end