rails-hyperdrive 0.3.0 → 0.5.0

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

data/lib/rails/hyperdrive/install_layout.rb

@@ -20,6 +20,10 @@ module Rails
         end
       end
 
+      def sidecar_path(dest)
+        "#{dest}.new"
+      end
+
       def installed_name(type, dest)
         case type
         when :skill         then File.basename(File.dirname(dest))

data/lib/rails/hyperdrive/install_pipeline.rb

@@ -1,8 +1,9 @@
 require "time"
-require "rails/hyperdrive/audit_header"
+require "rails/hyperdrive/ancestor_locator"
 require "rails/hyperdrive/bundler_artifact_discovery"
 require "rails/hyperdrive/claude_md_import"
 require "rails/hyperdrive/drift_verdict"
+require "rails/hyperdrive/three_way_merge"
 require "rails/hyperdrive/eager_footprint"
 require "rails/hyperdrive/index_document"
 require "rails/hyperdrive/install_layout"
@@ -20,11 +21,12 @@ module Rails
       WARN_LINES = 150
       WARN_TOKENS = 1_500
 
-      MODES = %i[preserve overwrite additive].freeze
+      MODES = %i[preserve overwrite additive sidecar merge].freeze
 
-      Result = Struct.new(:installed, :updated, :unchanged, :skipped, :orphaned, :removed, keyword_init: true)
+      Result = Struct.new(:installed, :updated, :unchanged, :skipped, :orphaned, :removed, :merged, :sidecars,
+        keyword_init: true)
 
-      def initialize(root:, shell:, artifacts:, mode: :preserve, warnings: [])
+      def initialize(root:, shell:, artifacts:, mode: :preserve, warnings: [], notices: [])
         raise ArgumentError, "unknown mode #{mode.inspect}" unless MODES.include?(mode)
 
         @root = File.expand_path(root.to_s)
@@ -32,7 +34,10 @@ module Rails
         @artifacts = artifacts
         @mode = mode
         @warnings = warnings
-        @result = Result.new(installed: [], updated: [], unchanged: [], skipped: [], orphaned: [], removed: [])
+        @notices = notices
+        @result = Result.new(
+          installed: [], updated: [], unchanged: [], skipped: [], orphaned: [], removed: [], merged: [], sidecars: []
+        )
       end
 
       def call
@@ -50,6 +55,7 @@ module Rails
         write_claude_md(guidelines)
         write_lock
         print_warnings
+        print_notices
         print_footprint(guidelines: eager_guidelines)
         warn_if_destinations_gitignored
         @result
@@ -81,6 +87,14 @@ module Rails
         @mode == :overwrite
       end
 
+      def merge_mode?
+        @mode == :merge
+      end
+
+      def reconcile_mode?
+        @mode == :sidecar || @mode == :merge
+      end
+
       def abs(path)
         File.join(@root, path)
       end
@@ -102,7 +116,10 @@ module Rails
 
       def install_skills
         @plan.select { |e| e.type == :skill }.each do |entry|
-          install_file(entry: entry, type: :skill, install_ready_body: entry.install_ready_body)
+          skill_relpath = source_relpath_for(entry.artifact)
+          support_base = support_relpath_base(entry.artifact, skill_relpath)
+          install_file(entry: entry, type: :skill, install_ready_body: entry.install_ready_body,
+            source_relpath: skill_relpath, final_name: entry.final_name)
           entry.support_files.each do |file|
             install_file(
               dest: file[:dest],
@@ -110,7 +127,8 @@ module Rails
               install_ready_body: file[:body],
               source_gem: entry.source_gem,
               version: entry.version,
-              artifact_kind: "skill_support"
+              artifact_kind: "skill_support",
+              source_relpath: support_base && File.join(support_base, file[:path])
             )
           end
         end
@@ -120,12 +138,44 @@ module Rails
         @plan.select { |e| e.type == :guideline }.map do |entry|
           body = entry.install_ready_body
           warn_if_oversize(entry.dest, body)
-          install_file(entry: entry, type: :guideline, install_ready_body: body)
+          install_file(entry: entry, type: :guideline, install_ready_body: body,
+            source_relpath: source_relpath_for(entry.artifact), final_name: entry.final_name)
           { base: "#{entry.final_name}.md", dest: entry.dest, body: body }
         end
       end
 
-      def install_file(dest: nil, type:, install_ready_body:, entry: nil, source_gem: nil, version: nil, artifact_kind: nil)
+      # The shipped file's path relative to its gem root, normalized to the
+      # install-target form (.md.erb -> .md).
+      def source_relpath_for(artifact)
+        root = artifact.source_root
+        return nil if root.nil? || root.to_s.empty?
+
+        prefix = "#{File.expand_path(root.to_s)}/"
+        expanded = File.expand_path(artifact.path.to_s)
+        return nil unless expanded.start_with?(prefix)
+
+        rel = expanded.delete_prefix(prefix)
+        rel.end_with?(".md.erb") ? rel.delete_suffix(".erb") : rel
+      end
+
+      # Supporting files live under the artifact's support root, which for a
+      # template-paired skill is not the definition file's directory.
+      def support_relpath_base(artifact, skill_relpath)
+        support_root = artifact.support_root
+        return skill_relpath && File.dirname(skill_relpath) if support_root.nil? || support_root.to_s.empty?
+
+        root = artifact.source_root
+        return nil if root.nil? || root.to_s.empty?
+
+        prefix = "#{File.expand_path(root.to_s)}/"
+        expanded = File.expand_path(support_root.to_s)
+        return nil unless expanded.start_with?(prefix)
+
+        expanded.delete_prefix(prefix)
+      end
+
+      def install_file(dest: nil, type:, install_ready_body:, entry: nil, source_gem: nil, version: nil,
+                       artifact_kind: nil, source_relpath: nil, final_name: nil)
         write = {
           dest: dest || entry.dest,
           type: type,
@@ -140,25 +190,152 @@ module Rails
         return additive_install(write, old) if additive?
 
         file = abs(write[:dest])
-        case DriftVerdict.verdict(file: file, kind: write[:artifact_kind], lock_entry: old, gem_sha: write[:gem_sha])
+        case DriftVerdict.verdict(file: file, lock_entry: old, gem_sha: write[:gem_sha])
         when :missing
           @shell.say_status(:reinstall, "#{write[:dest]} (was missing)", :yellow) if old
           write_artifact(**write)
+          sweep_sidecar(write, old)
         when :current
           @new_lock.carry(old)
           @result.unchanged << write[:dest]
           @shell.say_status :unchanged, write[:dest], :blue
+          sweep_sidecar(write, old)
         when :outdated
           write_artifact(**write)
+          sweep_sidecar(write, old)
         when :edited
           if overwrite_mode?
             write_artifact(**write)
+            sweep_sidecar(write, old)
+          elsif reconcile_mode?
+            reconcile_edited(write, old, source_relpath: source_relpath, final_name: final_name)
+          else
+            skip_edited(write, old)
+          end
+        end
+      end
+
+      def skip_edited(write, old)
+        @result.skipped << write[:dest]
+        @shell.say_status :skip,
+          "#{write[:dest]} (locally modified; run hyperdrive:sync with --merge, --sidecar, or --overwrite to reconcile)",
+          :yellow
+        @new_lock.carry(old) if old
+      end
+
+      # Reconciliation for a locally-modified destination in :sidecar/:merge
+      # mode. The lock records the newest upstream *delivered* — installed
+      # live, merged in, or written as a sidecar — never the live file's own
+      # hash, so the same upstream version is offered exactly once.
+      def reconcile_edited(write, old, source_relpath:, final_name:)
+        dest = write[:dest]
+        sidecar = InstallLayout.sidecar_path(dest)
+
+        if old && old.source_sha == write[:gem_sha]
+          skip_edited(write, old)
+          if File.exist?(abs(sidecar))
+            @shell.say_status :warn, "#{sidecar} (unresolved sidecar; reconcile it with #{dest}, then delete it)", :yellow
+          end
+          return
+        end
+
+        # An edited sidecar is user work: leave it, and leave the lock at the
+        # old upstream so this delivery is re-offered once the user clears it.
+        if File.exist?(abs(sidecar)) && !sidecar_pristine?(sidecar, write, old)
+          @result.skipped << dest
+          @shell.say_status :warn, "#{sidecar} (sidecar locally modified; resolve or delete it)", :yellow
+          @new_lock.carry(old) if old
+          return
+        end
+
+        reason = nil
+        if merge_mode?
+          if File.exist?(abs(sidecar))
+            # A pending sidecar means the last delivered upstream never reached
+            # the live file, so the reconstructable ancestor is stale; merging
+            # over it would silently revert that delivery.
+            reason = "previous delivery still unresolved"
           else
-            @result.skipped << write[:dest]
-            @shell.say_status :skip, "#{write[:dest]} (locally modified; run hyperdrive:sync --overwrite to overwrite)", :yellow
-            @new_lock.carry(old) if old
+            merged, reason = attempt_merge(write, old, source_relpath: source_relpath, final_name: final_name)
+            if merged
+              write_merged(write, merged)
+              sweep_sidecar(write, old)
+              return
+            end
           end
         end
+
+        write_sidecar(write, reason)
+      end
+
+      def attempt_merge(write, old, source_relpath:, final_name:)
+        return [nil, "no previous install recorded"] unless old
+
+        ancestor = AncestorLocator.locate(
+          kind: write[:artifact_kind], relpath: source_relpath, lock_entry: old, final_name: final_name
+        )
+        return [nil, "#{old.source_label} not found in installed gems"] unless ancestor
+
+        ours = live_body(write)
+        if ours.nil? || [ours, ancestor, write[:body]].any? { |b| ThreeWayMerge.binary?(b) }
+          return [nil, "binary content"]
+        end
+
+        outcome = ThreeWayMerge.merge(ours: ours, base: ancestor, theirs: write[:body])
+        case outcome.status
+        when :clean      then [outcome.body, nil]
+        when :conflicted then [nil, "conflicting edits"]
+        else                  [nil, "git merge-file unavailable"]
+        end
+      end
+
+      def live_body(write)
+        file = abs(write[:dest])
+        return File.binread(file) if write[:type] == :skill_support
+        File.read(file)
+      rescue StandardError
+        nil
+      end
+
+      def write_merged(write, merged_body)
+        @shell.create_file write[:dest], merged_body
+        @result.merged << write[:dest]
+        @shell.say_status :merged, "#{write[:dest]} (local edits merged with #{write[:source_gem]}@#{write[:version]})", :green
+        upsert_lock(write, Time.now.utc)
+      end
+
+      # The sidecar is byte-identical to what a live install of the new
+      # upstream would write, so `mv <dest>.new <dest>` accepts it wholesale
+      # and the lock already verifies it.
+      def write_sidecar(write, reason)
+        sidecar = InstallLayout.sidecar_path(write[:dest])
+        @shell.create_file sidecar, write[:body]
+        @result.sidecars << write[:dest]
+        message = "#{write[:dest]} (locally modified; new upstream delivered to #{sidecar}"
+        message += "; #{reason}" if reason
+        @shell.say_status :sidecar, "#{message})", :yellow
+        upsert_lock(write, Time.now.utc)
+      end
+
+      # Only a machine-pristine sidecar — one still hashing to a delivered
+      # upstream — may be refreshed or removed; anything else is user work.
+      def sidecar_pristine?(sidecar, write, old)
+        sha = DriftVerdict.disk_sha(abs(sidecar))
+        [old&.source_sha, write[:gem_sha]].compact.include?(sha)
+      rescue StandardError
+        false
+      end
+
+      def sweep_sidecar(write, old)
+        sidecar = InstallLayout.sidecar_path(write[:dest])
+        return unless File.exist?(abs(sidecar))
+
+        if sidecar_pristine?(sidecar, write, old)
+          @shell.remove_file sidecar
+          @result.removed << sidecar
+        else
+          @shell.say_status :warn, "#{sidecar} (sidecar locally modified; resolve or delete it)", :yellow
+        end
       end
 
       # Additive installs can create a file and never overwrite one, so an
@@ -174,24 +351,11 @@ module Rails
         end
       end
 
-      # Supporting files land byte-identical to what the gem ships — no audit
-      # header, since they may be non-markdown or binary; provenance and sha
-      # live in the lock alone.
+      # Every artifact lands byte-identical to its install-ready body;
+      # provenance and sha live in the lock alone.
       def write_artifact(dest:, type:, body:, source_gem:, version:, gem_sha:, artifact_kind:)
-        installed_at = Time.now.utc
-        header_args = { source_gem: source_gem, version: version, sha256: gem_sha, installed_at: installed_at }
-        on_disk =
-          case type
-          when :skill
-            AuditHeader.inject_into_frontmatter(body, AuditHeader.build(**header_args))
-          when :skill_support
-            body
-          else
-            AuditHeader.prepend_html(body, AuditHeader.build_html(**header_args))
-          end
-
         existed = old_lock.entry(dest)
-        @shell.create_file dest, on_disk
+        @shell.create_file dest, body
         (existed ? @result.updated : @result.installed) << dest
         @new_lock.upsert(
           path: dest,
@@ -199,6 +363,17 @@ module Rails
           source_gem: source_gem,
           source_version: version,
           source_sha: gem_sha,
+          installed_at: Time.now.utc.iso8601
+        )
+      end
+
+      def upsert_lock(write, installed_at)
+        @new_lock.upsert(
+          path: write[:dest],
+          kind: write[:artifact_kind],
+          source_gem: write[:source_gem],
+          source_version: write[:version],
+          source_sha: write[:gem_sha],
           installed_at: installed_at.iso8601
         )
       end
@@ -284,11 +459,11 @@ module Rails
         old_lock.each_entry do |entry|
           next if planned.include?(entry.path)
           next if @new_lock.entry(entry.path)
-          next unless DriftVerdict.verdict(file: abs(entry.path), kind: entry.kind, lock_entry: entry, gem_sha: nil) == :orphaned
+          next unless DriftVerdict.verdict(file: abs(entry.path), lock_entry: entry, gem_sha: nil) == :orphaned
 
           @result.orphaned << entry.path
           @shell.say_status :orphan,
-            "#{entry.path} (source #{entry.source_label} no longer in bundle; left in place)", :yellow
+            "#{entry.path} (no longer shipped by #{entry.source_label}; left in place)", :yellow
           @new_lock.carry(entry)
         end
       end
@@ -368,6 +543,12 @@ module Rails
         @warnings.each { |w| @shell.say "    - #{w}" }
       end
 
+      def print_notices
+        return if additive? || Array(@notices).empty?
+        @shell.say ""
+        @notices.each { |n| @shell.say_status :info, n, :blue }
+      end
+
       def print_footprint(guidelines:)
         return if additive?
 

data/lib/rails/hyperdrive/lock_file.rb

@@ -33,6 +33,7 @@ module Rails
         @files = {}            # path(String) => Entry
         @document = {}         # raw parsed YAML, kept so unknown keys survive
         @disabled = empty_disabled
+        @enabled = []
       end
 
       def read
@@ -45,6 +46,7 @@ module Rails
         claude_md = data["claude_md"]
         @claude_md_state = claude_md["state"] if claude_md.is_a?(Hash)
         @disabled = parse_disabled(data["disabled"])
+        @enabled = parse_enabled(data["enabled"])
         Array(data["files"]).each do |raw|
           next unless raw.is_a?(Hash)
           entry = build_entry(raw)
@@ -71,11 +73,17 @@ module Rails
         Array(@disabled[type.to_sym]).include?(name.to_s)
       end
 
+      # Hand-editable list of gems the app opts into as companions.
+      def enabled_gems
+        @enabled
+      end
+
       # Adopt the state that is not derived from installed content, so
       # rewriting the file preserves it.
       def carry_settings(other)
         @document = other.document.dup
         @disabled = other.disabled_lists.dup
+        @enabled = other.enabled_gems.dup
         self
       end
 
@@ -103,6 +111,7 @@ module Rails
           "version"   => SCHEMA_VERSION,
           "claude_md" => carried.merge("state" => @claude_md_state),
           "disabled"  => DISABLED_KEYS.each_with_object({}) { |(type, key), h| h[key] = @disabled[type] },
+          "enabled"   => @enabled,
           "files"     => @files.values.sort_by(&:path).map { |e| serialize_entry(e) }
         )
         # A nil state means no import line is being managed. Recording one anyway
@@ -136,6 +145,12 @@ module Rails
         end
       end
 
+      def parse_enabled(raw)
+        return [] unless raw.is_a?(Array)
+
+        raw.map { |name| name.to_s.strip }.reject(&:empty?).uniq
+      end
+
       def build_entry(raw)
         source_gem, source_version = split_source(raw["source"])
         Entry.new(

data/lib/rails/hyperdrive/resources/stack_profile.rb

@@ -14,7 +14,7 @@ module Rails
           ::MCP::Resource.new(
             uri: URI,
             name: "Stack Profile",
-            description: "Parsed Gemfile.lock + categorization (rails, ruby, database, test, jobs, frontend, auth, authz, db_gems, gem_skills).",
+            description: "Parsed Gemfile.lock (rails, ruby, database, direct_dependencies, gem_skills).",
             mime_type: "application/json"
           )
         end

data/lib/rails/hyperdrive/skill_tasks.rb

@@ -0,0 +1,27 @@
+# Rake tasks for companion gem repos: add `require "rails/hyperdrive/skill_tasks"`
+# to the Rakefile. Both tasks take an optional gemspec-path argument, e.g.
+# rake "hyperdrive:skills:render[path/to/name.gemspec]".
+require "rake"
+require "rails/hyperdrive/canonical_skill_render"
+
+namespace :hyperdrive do
+  namespace :skills do
+    desc "Render each SKILL.md.erb template to its canonical static SKILL.md"
+    task :render, [:gemspec] do |_t, args|
+      written = Rails::Hyperdrive::CanonicalSkillRender.write(gemspec: args[:gemspec])
+      written.each { |r| puts "render #{r.dest}" }
+      puts "no skill templates found" if written.empty?
+    end
+
+    desc "Fail when a canonical SKILL.md is stale relative to its template"
+    task :check, [:gemspec] do |_t, args|
+      stale = Rails::Hyperdrive::CanonicalSkillRender.stale(gemspec: args[:gemspec])
+      if stale.empty?
+        puts "canonical skill files up to date"
+      else
+        stale.each { |r| warn "stale: #{r.dest}" }
+        abort "#{stale.size} canonical skill file(s) stale; run `rake hyperdrive:skills:render`"
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/skill_template.rb

@@ -31,6 +31,27 @@ module Rails
         end
       end
 
+      # Fail-open binding for the canonical render: every gem reads as present
+      # at any requested version, so the output includes every conditional
+      # branch. There is no bundle to resolve against, so gem_version is nil.
+      class CanonicalContext
+        def gem?(_name, _requirement = nil)
+          true
+        end
+
+        def any_gem?(*)
+          true
+        end
+
+        def gem_version(_name)
+          nil
+        end
+
+        def template_binding
+          binding
+        end
+      end
+
       module_function
 
       # Errors (ERB SyntaxError included) propagate; the caller decides how to
@@ -39,6 +60,10 @@ module Rails
         ERB.new(source, trim_mode: "-").result(Context.new(resolved).template_binding)
       end
 
+      def render_canonical(source)
+        ERB.new(source, trim_mode: "-").result(CanonicalContext.new.template_binding)
+      end
+
       # Gem::Requirement.new does not parse a single comma-separated string, so
       # such strings are split into separate constraints first.
       def version_matches?(requirement_str, version)