vendor: emit spinel-flags + committed-sibling drift guard (zero hand-wiring)

Closing the remaining cross-repo communication in the vendoring convention
(audit of #3/#8/#13/#14/#19/#20/#21). The machinery is already zero-hand-wiring
when the producer is a clean published gem (toy proves it); the residual
talking concentrated in two gaps:

1. vendor emits vendor/spinel/spinel-flags — the compile flags to use what
   vendor produced (today --rbs <into>/sig for the #13 type roots). The
   scaffold's bin/build sources it, so the consumer never hand-passes --rbs
   or hand-symlinks the sig root. Empty when no sig roots (cat-safe).

2. drift guard: vendor warns when a gem ships a hand-copied sibling — the
   lib/<X>/ + sig/<X>/ double-copy fingerprint for an undeclared <X> (tep's
   stale lib/spinel_kit/ + sig/spinel_kit/). Tells the producer to declare
   gem "<X>" so vendor manages it. Surfaces the exact drift the convention
   kills, at consume time. Confirmed firing on the real tep checkout.

+tests in test/rbs_sig_root_test.rb (flags emission project-relative + cat-safe;
drift guard: undeclared fires, declared silent, own-namespace + lib-only safe).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: OriPekelman

CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to `bundler-spinel` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
 project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- **Vendor emits `vendor/spinel/spinel-flags`** — the engine flags a compile
+  must pass to use what `vendor` produced (today the aggregated `--rbs
+  <into>/sig` type root, #13), so a build step auto-applies them
+  (`spinel app.rb $(cat vendor/spinel/spinel-flags) -o app`) instead of the
+  consumer hand-wiring `--rbs`/a sig-symlink. Always written (empty when no
+  sig roots) so the `$(cat …)` idiom never errors; the scaffold's `bin/build`
+  now sources it. Closes the last per-consumer hand-step in the vendoring
+  convention's happy path.
+- **Drift guard: committed-sibling-copy detection.** `vendor` now warns when a
+  gem ships a *hand-copied* sibling gem inside its own tree — the fingerprint
+  is BOTH `lib/<X>/` and `sig/<X>/` for an `<X>` that's neither the gem's own
+  namespace nor a declared dependency (e.g. `tep` carrying `lib/spinel_kit/` +
+  `sig/spinel_kit/` instead of depending on the gem; the copies drift). The
+  message tells the producer to declare `gem "<X>"` so `vendor` manages it.
+  This surfaces, at consume time, the cross-repo drift the convention exists
+  to eliminate (spinelgems#19). +tests.
+
 ## [0.4.0] — 2026-06-15
 
 ### Fixed

lib/bundler/spinel/cli.rb

@@ -208,7 +208,9 @@ def cmd_vendor(argv)
         sigs = res[:sig_gems] || []
         unless sigs.empty?
           @out.puts "  #{sigs.size} gem(s) ship sig/*.rbs type roots -> #{res[:into]}/sig"
-          @out.puts "  compile with: spinel ... --rbs #{res[:into]}/sig   (spinelgems#13)"
+        end
+        if (ff = res[:flags_file])
+          @out.puts "  compile flags -> #{ff}  (e.g. `spinel app.rb $(cat #{ff}) -o app`)"
         end
         0
       end

lib/bundler/spinel/engine_installer.rb

@@ -237,7 +237,11 @@ def build_sh
           spinel-compat install-engine                        # fetch+build the pinned engine (cached)
           export SPINEL="${SPINEL:-$HOME/.cache/spinel/current/spinel}"  # tell tep where the engine is
           spinel-compat vendor                                # place deps where Spinel follows them
-          tep build app.rb -o app                             # compile -> ./app
+          # vendor writes vendor/spinel/spinel-flags (e.g. `--rbs vendor/spinel/sig`
+          # for the aggregated sig type roots, spinelgems#13) so the compile uses
+          # what vendor produced with no hand-wiring.
+          SPINEL_FLAGS="$(cat vendor/spinel/spinel-flags 2>/dev/null || true)"
+          tep build app.rb $SPINEL_FLAGS -o app               # compile -> ./app
           echo "built ./app — run it with: ./app -p 4567"
         SH
       end

lib/bundler/spinel/vendorer.rb

@@ -65,14 +65,38 @@ def vendor(lockfile = "Gemfile.lock", into: "vendor/spinel", warn_incompatible:
             manifest << { require: target, libdir: "#{File.basename(dest)}/lib" }
           end
           note_compat(name, version) if warn_incompatible
+          warn_committed_siblings(src, spec) if warn_incompatible
         end
 
         unless (unknown = enable - @ext_names_seen).empty?
           warn "[vendor] --with-ext/SPINEL_EXT_ENABLE names matched no optional " \
                "entry in any vendored manifest: #{unknown.join(', ')}"
         end
         write_manifest(into, manifest, sig_gems)
-        { into: into, count: manifest.size, extensions: exts, sig_gems: sig_gems }
+        flags = write_compile_flags(into, sig_gems)
+        { into: into, count: manifest.size, extensions: exts, sig_gems: sig_gems, flags_file: flags }
+      end
+
+      # Emit `<into>/spinel-flags` — the engine flags a compile must pass to use
+      # what vendor produced, so the build step auto-applies them instead of the
+      # consumer hand-wiring `--rbs` (the per-project sig-symlink/Makefile hack).
+      # Today that's the aggregated sig type root (#13); the file is the seam for
+      # future global flags. A build script does:
+      #   spinel app.rb $(cat vendor/spinel/spinel-flags) -o app
+      # Project-relative when `into` is under cwd (the normal case) so the flag
+      # survives a project move. Always written (empty when no sig roots) so the
+      # `$(cat ...)` idiom never errors on a missing file.
+      def write_compile_flags(into, sig_gems)
+        path = File.join(into, "spinel-flags")
+        parts = []
+        unless sig_gems.empty?
+          sig_root = File.join(into, "sig")
+          pwd = Dir.pwd + File::SEPARATOR
+          rel = sig_root.start_with?(pwd) ? sig_root.delete_prefix(pwd) : sig_root
+          parts << "--rbs" << rel
+        end
+        File.write(path, parts.empty? ? "" : parts.join(" ") + "\n")
+        path
       end
 
       # Order specs so every gem's runtime dependencies come before it — a DFS
@@ -531,6 +555,44 @@ def note_compat(name, version)
              "— may not compile (run `spinel-compat check`)"
       end
 
+      # Drift guard: a gem that ships a *hand-copied* sibling gem inside its own
+      # tree — the fingerprint is BOTH `lib/<X>/` and `sig/<X>/` for an `<X>`
+      # that is neither the gem's own namespace nor a declared runtime dependency
+      # (tep carries `lib/spinel_kit/`+`sig/spinel_kit/` instead of depending on
+      # the gem; the copies have already gone stale). Copying both lib + sig is
+      # unambiguously vendoring, not a coincidental sub-namespace. Warn so the
+      # producer declares `gem "<X>"` and lets vendor manage it (#19 retired the
+      # interim that forced these copies) — this is the cross-repo-drift the
+      # convention exists to kill, surfaced at consume time. Returns warnings.
+      def committed_sibling_warnings(src, spec)
+        libdir = File.join(src, "lib")
+        sigdir = File.join(src, "sig")
+        return [] unless File.directory?(libdir) && File.directory?(sigdir)
+
+        own = own_namespaces(spec.name)
+        declared = spec.dependencies.map { |d| d.respond_to?(:name) ? d.name : d.to_s }
+        Dir.children(libdir).filter_map do |child|
+          x = child[%r{\A(.+?)(?:\.rb)?\z}, 1]
+          next if x.nil? || own.include?(x) || declared.include?(x)
+          next unless File.directory?(File.join(libdir, x))      # a lib/<X>/ tree
+          next unless File.directory?(File.join(sigdir, x))      # AND sig/<X>/ — the copy fingerprint
+          "[vendor] #{spec.name} ships a hand-copied `#{x}` (lib/#{x}/ + sig/#{x}/) " \
+            "but does not declare it as a dependency — it will drift. Declare " \
+            "`gem \"#{x}\"` so `spinel-compat vendor` manages it (spinelgems#19)."
+        end
+      end
+
+      def warn_committed_siblings(src, spec)
+        committed_sibling_warnings(src, spec).each { |w| warn w }
+      end
+
+      # Names that legitimately belong to this gem's own tree: its gem name and
+      # the dashed→slashed first segment (`a-b` → `a`), so a gem's own nested
+      # namespace never trips the sibling-copy guard.
+      def own_namespaces(name)
+        [name, name.tr("-", "/").split("/").first].compact.uniq
+      end
+
       def write_manifest(into, entries, sig_gems = [])
         es = entries.compact
         body = +"# Generated by bundler-spinel. require_relative this from a\n" \

test/rbs_sig_root_test.rb

@@ -98,6 +98,58 @@ def ensure! = true
   vend.send(:write_manifest, into, [{ require: "g/lib/g", libdir: "g/lib" }], [])
   check(!File.read(File.join(into, "deps.rb")).include?("--rbs"),
         "no sig gems -> no --rbs note")
+
+  # spinel-flags: vendor emits the compile flags so the build auto-applies --rbs
+  # (no per-consumer hand-wiring). Project-relative, empty when no sig roots.
+  Dir.chdir(dir) do
+    rel_into = "vendor"
+    ff = vend.send(:write_compile_flags, rel_into, ["g"])
+    flags = File.read(ff).strip
+    check(flags == "--rbs vendor/sig", "spinel-flags carries project-relative --rbs (#{flags.inspect})")
+    vend.send(:write_compile_flags, rel_into, [])
+    check(File.read(ff).strip.empty?, "spinel-flags empty when no sig roots (cat-safe)")
+  end
+end
+
+# --- Vendorer: committed-sibling drift guard (audit gap 1) -------------------
+puts "\ndrift guard: a gem shipping lib/<X>/ + sig/<X>/ for an undeclared dep warns"
+Dir.mktmpdir("rbssib") do |src|
+  # a producer (like tep) that hand-copied a sibling gem (like spinel_kit)
+  FileUtils.mkdir_p(File.join(src, "lib", "spinel_kit"))
+  FileUtils.mkdir_p(File.join(src, "sig", "spinel_kit"))
+  File.write(File.join(src, "lib", "spinel_kit", "json.rb"), "module SpinelKit; end\n")
+  File.write(File.join(src, "sig", "spinel_kit", "json.rbs"), "module SpinelKit\nend\n")
+  # the producer's own tree (must NOT trip the guard)
+  FileUtils.mkdir_p(File.join(src, "lib", "tep"))
+  FileUtils.mkdir_p(File.join(src, "sig", "tep"))
+
+  vend = Bundler::Spinel::Vendorer.allocate
+  Dep = Struct.new(:name) unless defined?(Dep)
+  Spec = Struct.new(:name, :dependencies) unless defined?(Spec)
+
+  # case A: spinel_kit NOT declared -> warns
+  spec_a = Spec.new("tep", [])
+  w = vend.send(:committed_sibling_warnings, src, spec_a)
+  check(w.size == 1 && w.first.include?("hand-copied `spinel_kit`"),
+        "undeclared committed sibling -> 1 warning about spinel_kit (#{w.inspect})")
+  check(w.none? { |s| s.include?("hand-copied `tep`") }, "own namespace (tep) not flagged")
+
+  # case B: spinel_kit declared as a dependency -> no warning (vendor manages it)
+  spec_b = Spec.new("tep", [Dep.new("spinel_kit")])
+  check(vend.send(:committed_sibling_warnings, src, spec_b).empty?,
+        "declared dependency -> no warning")
+end
+
+# a gem with lib/<X>/ but NO matching sig/<X>/ is not the copy fingerprint
+puts "\ndrift guard: lib-only sub-namespace (no sig/<X>/) is NOT flagged"
+Dir.mktmpdir("rbssib2") do |src|
+  FileUtils.mkdir_p(File.join(src, "lib", "helpers"))
+  FileUtils.mkdir_p(File.join(src, "sig"))
+  File.write(File.join(src, "lib", "helpers", "x.rb"), "module Helpers; end\n")
+  vend = Bundler::Spinel::Vendorer.allocate
+  spec = Struct.new(:name, :dependencies).new("mygem", [])
+  check(vend.send(:committed_sibling_warnings, src, spec).empty?,
+        "lib/<X>/ without sig/<X>/ -> no warning")
 end
 
 puts(@fails.zero? ? "\nall checks passed" : "\n#{@fails} check(s) FAILED")