bundler-spinel 0.0.1.pre

data/lib/bundler/spinel/cli.rb

@@ -0,0 +1,225 @@
+require_relative "../spinel"
+
+module Bundler
+  module Spinel
+    # Thin command dispatcher shared by the `spinel-compat` executable and the
+    # Bundler plugin command. Keeps all logic in the library classes.
+    class CLI
+      VERDICT_GLYPH = {
+        "clean" => "✓", "verified" => "★", "risky" => "~", "rejected" => "✗"
+      }.freeze
+
+      def initialize(out: $stdout, err: $stderr)
+        @out = out
+        @err = err
+      end
+
+      def run(argv)
+        cmd = argv.shift
+        case cmd
+        when "engine"  then cmd_engine
+        when "probe"   then cmd_probe(argv)
+        when "verify"  then cmd_verify(argv)
+        when "vendor"  then cmd_vendor(argv)
+        when "check"   then cmd_check(argv)
+        when "serve"   then cmd_serve(argv)
+        when "build-index" then cmd_build_index(argv)
+        when "ledger"  then cmd_ledger(argv)
+        when "reprobe" then cmd_reprobe(argv)
+        when "survey"  then cmd_survey(argv)
+        when nil, "-h", "--help", "help" then usage; 0
+        else
+          @err.puts "unknown command: #{cmd}"; usage; 2
+        end
+      rescue Error => e
+        @err.puts "[spinel-compat] #{e.message}"; 1
+      end
+
+      private
+
+      def cmd_engine
+        e = Engine.new
+        @out.puts "spinel binary : #{e.bin} (#{e.available? ? 'found' : 'MISSING'})"
+        @out.puts "engine rev    : #{e.rev}"
+        @out.puts "ledger        : #{Ledger.new.path}"
+        e.available? ? 0 : 1
+      end
+
+      def cmd_probe(argv)
+        dir = (i = argv.index("--dir")) ? argv.delete_at(i + 1).tap { argv.delete_at(i) } : nil
+        name = argv.shift or raise Error, "usage: spinel-compat probe NAME [VERSION] [--dir PATH]"
+        engine = Engine.new
+        if dir
+          # Local source (a path:/git: sibling, or a checkout under test).
+          version = argv.shift || "path"
+          v = Probe.new(engine, Ledger.new).probe(name, version, File.expand_path(dir))
+        else
+          version = argv.shift || latest_version(name)
+          v = Probe.new(engine, Ledger.new).probe(name, version, GemFetcher.new.fetch(name, version))
+        end
+        print_verdict(v)
+        v.rejected? ? 1 : 0
+      end
+
+      def cmd_verify(argv)
+        dir = (i = argv.index("--dir")) ? argv.delete_at(i + 1).tap { argv.delete_at(i) } : nil
+        smoke = (j = argv.index("--smoke")) ? argv.delete_at(j + 1).tap { argv.delete_at(j) } : nil
+        name = argv.shift or raise Error, "usage: spinel-compat verify NAME [VERSION] [--dir PATH] [--smoke FILE]"
+        engine = Engine.new
+        if dir
+          version = argv.shift || "path"
+          gem_dir = File.expand_path(dir)
+        else
+          version = argv.shift || latest_version(name)
+          gem_dir = GemFetcher.new.fetch(name, version)
+        end
+        v = Verifier.new(engine, Ledger.new).verify(name, version, gem_dir, smoke: smoke && File.expand_path(smoke))
+        print_verdict(v)
+        v.verified? ? 0 : 1
+      end
+
+      def cmd_vendor(argv)
+        into = (i = argv.index("--into")) ? argv.delete_at(i + 1).tap { argv.delete_at(i) } : "vendor/spinel"
+        lock = argv.shift || "Gemfile.lock"
+        raise Error, "no #{lock}; run `bundle lock` first" unless File.exist?(lock)
+
+        res = Vendorer.new.vendor(lock, into: into)
+        @out.puts "vendored #{res[:count]} gem(s) -> #{res[:into]}"
+        @out.puts "  require_relative \"#{res[:into]}/deps\" from your Spinel entrypoint"
+        0
+      end
+
+      def cmd_check(argv)
+        strict = argv.delete("--strict")
+        lock = argv.shift || "Gemfile.lock"
+        raise Error, "no #{lock}; run `bundle lock` first" unless File.exist?(lock)
+
+        res = Checker.new.check(lock, strict: !!strict)
+        res.probed.sort_by(&:gem).each { |v| print_verdict(v) }
+        @out.puts "—" * 48
+        if res.verdict
+          @out.puts "OK: #{res.probed.size} gems compatible with #{Engine.new.rev}" \
+                    "#{strict ? ' (strict)' : ''}"
+          0
+        else
+          @err.puts "REJECTED under #{Engine.new.rev}:"
+          res.rejected.each { |v| @err.puts "  ✗ #{v.gem} #{v.version} — #{v.reasons.join(', ')}" }
+          res.risky.each { |v| @err.puts "  ~ #{v.gem} #{v.version} — risky: #{v.risks.join(', ')}" } if strict
+          1
+        end
+      end
+
+      def cmd_serve(argv)
+        require_relative "proxy"
+        store = (i = argv.index("--store")) ? argv[i + 1] : raise(Error, "serve needs --store DIR (vetted .gem files)")
+        port = (j = argv.index("--port")) ? argv[j + 1].to_i : 9292
+        min = (k = argv.index("--min")) ? argv[k + 1].to_sym : :verified
+        Proxy.new(store: File.expand_path(store), min_verdict: min).serve(port: port)
+        0
+      end
+
+      def cmd_build_index(argv)
+        require_relative "proxy"
+        store = (i = argv.index("--store")) ? argv[i + 1] : raise(Error, "build-index needs --store DIR")
+        out = (j = argv.index("--out")) ? argv[j + 1] : raise(Error, "build-index needs --out DIR")
+        min = (k = argv.index("--min")) ? argv[k + 1].to_sym : :verified
+        dir = Proxy.new(store: File.expand_path(store), min_verdict: min).write_static(File.expand_path(out))
+        @out.puts "wrote static curated index to #{dir} (serve it as a `source`)"
+        0
+      end
+
+      def cmd_ledger(argv)
+        rev = (i = argv.index("--rev")) ? argv[i + 1] : nil
+        Ledger.new.each do |v|
+          next if rev && v.rev != rev
+
+          print_verdict(v, show_rev: true)
+        end
+        0
+      end
+
+      # Forward-compat sweep: re-probe every gem the ledger has ever seen under
+      # the *current* engine rev, surfacing what newly passes after a Spinel
+      # upgrade. Skips triples already probed at this rev.
+      def cmd_reprobe(_argv)
+        engine = Engine.new
+        ledger = Ledger.new
+        probe = Probe.new(engine, ledger)
+        flips = 0
+        ledger.known_gems.each do |name, version|
+          next if ledger.lookup(name, version, engine.rev)
+
+          dir = GemFetcher.new.fetch(name, version)
+          v = probe.probe(name, version, dir)
+          flips += 1
+          print_verdict(v)
+        rescue Error => e
+          @err.puts "  ! #{name} #{version}: #{e.message}"
+        end
+        @out.puts "re-probed #{flips} gem(s) under #{engine.rev}"
+        0
+      end
+
+      # Wholesale review: probe a list of gems in parallel, then emit a report
+      # (the rejection-reason histogram prioritises Spinel's roadmap).
+      def cmd_survey(argv)
+        jobs = (i = argv.index("--jobs")) ? argv.delete_at(i + 1).to_i.tap { argv.delete_at(i) } : 4
+        out_file = (j = argv.index("--out")) ? argv.delete_at(j + 1).tap { argv.delete_at(j) } : nil
+        list = (k = argv.index("--list")) ? argv.delete_at(k + 1).tap { argv.delete_at(k) } : nil
+        names = if list
+                  File.readlines(File.expand_path(list)).map(&:strip).reject { |l| l.empty? || l.start_with?("#") }
+                else
+                  argv.dup
+                end
+        raise Error, "usage: spinel-compat survey GEM... | --list FILE [--jobs N] [--out report.md]" if names.empty?
+
+        survey = Survey.new(jobs: jobs)
+        survey.run(names)
+        report = survey.report(names)
+        if out_file
+          File.write(File.expand_path(out_file), report)
+          @out.puts "wrote #{out_file} (#{names.size} gems)"
+        else
+          @out.puts report
+        end
+        0
+      end
+
+      def print_verdict(v, show_rev: false)
+        glyph = VERDICT_GLYPH[v.verdict] || "?"
+        labels = v.reasons + v.risks.map { |r| r.include?(":") ? r : "risk:#{r}" }
+        tail = labels.empty? ? "" : " — #{labels.join(', ')}"
+        rev = show_rev ? " [#{v.rev}]" : ""
+        @out.puts format("  %s %-22s %-10s %-9s%s%s", glyph, v.gem, v.version, v.verdict, tail, rev)
+      end
+
+      def latest_version(name)
+        require "open3"
+        out, st = Open3.capture2e("gem", "list", "-r", "-e", name)
+        raise Error, "cannot resolve latest version of #{name}" unless st.success?
+
+        out[/#{Regexp.escape(name)} \(([^,)]+)/, 1] or
+          raise Error, "no remote versions found for #{name}"
+      end
+
+      def usage
+        @out.puts <<~USAGE
+          spinel-compat — Spinel gem-compatibility ledger
+
+            spinel-compat engine                 show detected compiler + engine rev
+            spinel-compat probe NAME [VERSION]    probe one gem, record a verdict
+            spinel-compat verify NAME [--smoke F]  differential CRuby-vs-Spinel run -> verified
+            spinel-compat vendor [LOCK] [--into D] place deps where Spinel finds them + deps.rb
+            spinel-compat check [LOCK] [--strict] gate a Gemfile.lock (exit 1 if rejected)
+            spinel-compat survey GEM... | --list F  wholesale review -> reason histogram
+            spinel-compat serve --store DIR        curated source (only vetted gems)
+            spinel-compat build-index --store DIR --out DIR   static curated index
+            spinel-compat ledger [--rev REV]      dump recorded verdicts
+            spinel-compat reprobe                 re-probe known gems under current rev
+
+          Verdicts: ✓ clean   ★ verified   ~ risky   ✗ rejected
+        USAGE
+      end
+    end
+  end
+end

data/lib/bundler/spinel/command.rb

@@ -0,0 +1,37 @@
+require_relative "../spinel"
+require_relative "cli"
+
+module Bundler
+  module Spinel
+    # Bundler plugin command. Registered in ../../../plugins.rb so that, once
+    # installed via `bundle plugin install bundler-spinel`, these run as
+    # first-class bundler subcommands:
+    #
+    #   bundle spinel-lock   # `bundle lock`, then gate the resulting lockfile
+    #   bundle spinel-check  # gate an existing Gemfile.lock
+    #
+    # `spinel-lock` is the headline: it makes the Spinel-incompatibility failure
+    # land at resolution time. `bundle lock` itself ignores the `engine: spinel`
+    # directive (it resolves fine); the engine guard only fires at `bundle
+    # install`. This wraps lock so the *compatibility* gate fires immediately
+    # after resolution instead of waiting for a compile that may silently
+    # mis-emit rather than fail.
+    class Command < Bundler::Plugin::API
+      def exec(command, args)
+        cli = CLI.new
+        case command
+        when "spinel-lock"
+          unless system("bundle", "lock", *args)
+            exit($?.exitstatus.nonzero? || 1)
+          end
+          exit cli.run(["check", "Gemfile.lock"])
+        when "spinel-check"
+          exit cli.run(["check", *args])
+        else
+          warn "bundler-spinel: unknown command #{command}"
+          exit 2
+        end
+      end
+    end
+  end
+end

data/lib/bundler/spinel/engine.rb

@@ -0,0 +1,96 @@
+require "open3"
+require "digest"
+require "rbconfig"
+
+module Bundler
+  module Spinel
+    # Locates the Spinel compiler and derives a stable *revision* identity for it.
+    #
+    # Forward-compatibility hinges on this: every compatibility verdict in the
+    # ledger is keyed on the engine revision, never on a gem name alone. Spinel
+    # ships no version string (`spinel --version` just prints usage; `git
+    # describe` returns a bare SHA with no tags), so we key on the git revision
+    # of the Spinel checkout — falling back to a content hash of the binary when
+    # it isn't a git checkout. Upgrade Spinel → new rev → no ledger entry → the
+    # gem is re-probed automatically. A gem that is `rejected` today and works
+    # after a Spinel feature lands flips to `clean` on the next probe, with no
+    # manual blocklist to maintain.
+    class Engine
+      attr_reader :dir, :bin
+
+      def initialize(dir: ENV.fetch("SPINEL_DIR", File.expand_path("~/spinel")))
+        @dir = dir
+        # Prefer a checkout at `dir` (gives a git rev); otherwise fall back to a
+        # `spinel` on PATH (installed binary — rev becomes a binary hash). This
+        # makes the default work for most setups without configuration.
+        local = File.join(dir, "spinel")
+        @bin = File.executable?(local) ? local : (which("spinel") || local)
+      end
+
+      def available?
+        File.executable?(@bin)
+      end
+
+      def ensure!
+        return if available?
+
+        raise Error, "spinel compiler not found at #{@bin} " \
+                     "(set SPINEL_DIR or pass --spinel-dir)"
+      end
+
+      # Short, human-facing engine id, platform-scoped:
+      #   "git:0adca86/arm64-darwin"  or  "git:0adca86+dirty/aarch64-linux".
+      # Platform matters because verdicts that depend on the C compile + runtime
+      # (analyze-failed, miscompile, build-error, verified) are not portable
+      # across targets — only `unresolved:X` (pure analysis) is. So the same
+      # Spinel commit built on the Mac and on the gx10 are *distinct* ledger revs.
+      def rev
+        @rev ||= "#{compute_rev}/#{platform}"
+      end
+
+      def platform
+        cpu = RbConfig::CONFIG["host_cpu"]
+        os  = RbConfig::CONFIG["host_os"].sub(/\d.*\z/, "").sub(/darwin.*/, "darwin")
+        "#{cpu}-#{os}"
+      end
+
+      # The label a Gemfile declares via `engine_version:`. Advisory only — the
+      # ledger key is `rev`, not this. Recorded so `check` can warn when the
+      # declared label and the actual binary drift apart.
+      def declared_version
+        @declared_version
+      end
+
+      attr_writer :declared_version
+
+      private
+
+      def compute_rev
+        if File.directory?(File.join(@dir, ".git"))
+          sha = capture("git", "-C", @dir, "rev-parse", "--short", "HEAD")
+          if sha && !sha.empty?
+            dirty = capture("git", "-C", @dir, "status", "--porcelain")
+            return "git:#{sha}" + (dirty.to_s.strip.empty? ? "" : "+dirty")
+          end
+        end
+        # Not a git checkout: hash the binary so distinct builds get distinct keys.
+        return "missing" unless available?
+
+        "bin:#{Digest::SHA256.file(@bin).hexdigest[0, 12]}"
+      end
+
+      def which(cmd)
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR)
+           .map { |p| File.join(p, cmd) }
+           .find { |f| File.executable?(f) && !File.directory?(f) }
+      end
+
+      def capture(*cmd)
+        out, st = Open3.capture2e(*cmd)
+        st.success? ? out.strip : nil
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/bundler/spinel/gem_fetcher.rb

@@ -0,0 +1,45 @@
+require "open3"
+require "tmpdir"
+require "fileutils"
+
+module Bundler
+  module Spinel
+    # Downloads and unpacks a gem's *source* so the probe can compile it.
+    # Reuses RubyGems' own `gem fetch` / `gem unpack` — we want the source tree,
+    # not an install. Sources are cached under a content dir so re-probes are
+    # free.
+    class GemFetcher
+      CACHE = File.expand_path("~/.cache/spinel-compat/gems")
+
+      def initialize(cache: CACHE)
+        @cache = cache
+      end
+
+      # Returns the path to the unpacked gem dir, fetching+unpacking if needed.
+      def fetch(name, version)
+        dest = File.join(@cache, "#{name}-#{version}")
+        return dest if File.directory?(dest)
+
+        FileUtils.mkdir_p(@cache)
+        Dir.mktmpdir do |tmp|
+          out, st = Open3.capture2e(
+            "gem", "fetch", name, "-v", version, "--platform", "ruby",
+            chdir: tmp
+          )
+          raise Error, "gem fetch #{name} #{version} failed:\n#{out}" unless st.success?
+
+          gemfile = Dir[File.join(tmp, "#{name}-*.gem")].first
+          raise Error, "no .gem produced for #{name} #{version}" unless gemfile
+
+          out, st = Open3.capture2e("gem", "unpack", gemfile, "--target", @cache)
+          raise Error, "gem unpack failed:\n#{out}" unless st.success?
+        end
+        # `gem unpack` may name the dir with a platform suffix; normalise.
+        return dest if File.directory?(dest)
+
+        actual = Dir[File.join(@cache, "#{name}-#{version}*")].find { |d| File.directory?(d) }
+        actual or raise Error, "unpacked dir for #{name} #{version} not found"
+      end
+    end
+  end
+end

data/lib/bundler/spinel/ledger.rb

@@ -0,0 +1,97 @@
+require "json"
+require "fileutils"
+require "time"
+require "thread"
+
+module Bundler
+  module Spinel
+    # Append-only JSONL record of compatibility verdicts, one line per
+    # `(gem, version, engine_rev)`. The single source of truth that the
+    # lock-time gate, the curated-source whitelist, and the platform-variant
+    # opt-in are all views over.
+    #
+    # Append-only because verdicts are facts-as-of-a-rev: we never mutate
+    # history, we add a newer probe. `lookup` returns the most recent matching
+    # line, so a re-probe naturally supersedes an older one.
+    class Ledger
+      Verdict = Struct.new(
+        :gem, :version, :rev, :verdict, :reasons, :risks, :probe, :at,
+        keyword_init: true
+      ) do
+        # Hard no: will not compile, or compiles to silent no-ops we detected.
+        def rejected? = verdict == "rejected"
+        # Compiles clean *and* no risky dynamic constructs found statically.
+        def clean? = verdict == "clean"
+        # Compiles clean but uses constructs Spinel degrades silently
+        # (define_method/eval/…): allowed by default, fails under --strict.
+        def risky? = verdict == "risky"
+        # Compiles clean AND the gem's own tests pass through a Spinel-compiled
+        # harness. The only verdict that earns a whitelist slot / platform badge.
+        def verified? = verdict == "verified"
+
+        def to_line = JSON.generate(to_h.transform_keys(&:to_s))
+      end
+
+      DEFAULT_PATH = File.expand_path("../../../ledger/compat.jsonl", __dir__)
+
+      attr_reader :path
+
+      def initialize(path: ENV.fetch("SPINEL_COMPAT_LEDGER", DEFAULT_PATH))
+        @path = path
+        @write_mutex = Mutex.new
+      end
+
+      # Thread-safe: the survey probes gems in parallel and records from many
+      # threads. One `write` of the whole line under O_APPEND is a single
+      # atomic syscall, so a concurrent `each`/`lookup` reader never sees a
+      # torn line; the mutex just serialises writers among themselves.
+      def record(verdict)
+        FileUtils.mkdir_p(File.dirname(@path))
+        @write_mutex.synchronize do
+          File.open(@path, "a") { |f| f.write("#{verdict.to_line}\n") }
+        end
+        verdict
+      end
+
+      # Most recent verdict for this exact triple, or nil.
+      def lookup(gem, version, rev)
+        result = nil
+        each { |v| result = v if v.gem == gem && v.version == version && v.rev == rev }
+        result
+      end
+
+      # Every distinct (gem, version) the ledger has ever seen — the candidate
+      # set for a forward-compat re-probe sweep under a new rev.
+      def known_gems
+        seen = {}
+        each { |v| seen[[v.gem, v.version]] = true }
+        seen.keys
+      end
+
+      def each
+        return enum_for(:each) unless block_given?
+        return unless File.exist?(@path)
+
+        File.foreach(@path) do |line|
+          line = line.strip
+          next if line.empty?
+
+          h = JSON.parse(line)
+          yield Verdict.new(
+            gem: h["gem"], version: h["version"], rev: h["rev"],
+            verdict: h["verdict"], reasons: h["reasons"] || [],
+            risks: h["risks"] || [], probe: h["probe"], at: h["at"]
+          )
+        end
+      end
+
+      def build(gem:, version:, rev:, verdict:, reasons: [], risks: [], probe: "compile")
+        Verdict.new(
+          gem: gem, version: version, rev: rev, verdict: verdict,
+          reasons: reasons, risks: risks, probe: probe,
+          at: Time.now.utc.iso8601
+        )
+      end
+    end
+  end
+end

data/lib/bundler/spinel/platform.rb

@@ -0,0 +1,24 @@
+module Bundler
+  module Spinel
+    # STUB — designed, not built. See ARCHITECTURE.md §"Platform variant".
+    #
+    # Opt-in mechanism to mark a gem "verified under Spinel" using RubyGems'
+    # existing platform machinery — the same lever JRuby uses with the `java`
+    # platform. A `verified` gem can be republished (to the curated source) with
+    # a `spinel` platform; Bundler's normal platform resolution then *prefers*
+    # the spinel variant and a missing variant is a clean resolution miss.
+    #
+    # `Gem::Platform.new("spinel")` parses to os="unknown" today, so the concrete
+    # token is TBD (likely "<cpu>-spinel-<engine_rev>" so the badge is rev-scoped
+    # — a variant verified under git:0adca86 should not silently satisfy a newer
+    # engine). This is the bridge from "our private ledger says verified" to
+    # "stock Bundler resolution selects it," and the reason verification is
+    # opt-in: earning a platform badge means someone ran the gem's tests through
+    # a Spinel-compiled harness.
+    class Platform
+      def initialize(*)
+        raise Error, "Platform is a design stub — see ARCHITECTURE.md"
+      end
+    end
+  end
+end