bundler-spinel 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99f01821538cfb0ce86a06e2ecb1251f89e1086530c59423715f509d18e0c717
-  data.tar.gz: ca1c456f3bf3c4d9e4424a0466daa23bb4495b64357adfed8a69145953d54a06
+  metadata.gz: 12d700f606c1cf8b69ae4fe623c16293bfbc560fe09b59c8fadeb4529a8a02f6
+  data.tar.gz: e08a61f93c03930e4c85b0e1effbaf3dfb2e05f3bd1d1979459fe4e667de4f4c
 SHA512:
-  metadata.gz: fa08674c1d4206f15713004a9452d3aba7b43c2f6a1997c5c0d6d97ac7bbe00a4b2a986eb50673518acebcf807cab58ad785916aa1c3d3c71dab939d1e4c9163
-  data.tar.gz: 41b3407d8dd4d7f115a50c3294e0e0204e9c3c719ee52042876245ff0a63fa1cfd4b1e2ba8b97037d94ba27a2f25c25f893660999b306ce912663e050ed674d6
+  metadata.gz: 3390679f31399277e342e4853530a15d9017aa8de9cbb822dc933420953e4badc97ca497302cbfa8acf29dc6cb1380f2508c515b7e00aa1e5a0eaca502a64e73
+  data.tar.gz: ccf7ac613f132909ae9598f01be97c14c6f4fc12dcd70a5352c2ea4f62beb2303589463039c7c98d8787918131323c83cbe2f101ababae9e2161afa6a64c8a5e

data/CHANGELOG.md

@@ -4,6 +4,47 @@ 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).
 
+## [0.2.0] — 2026-06-01
+
+### Added
+- **`verify` self-localizes a miscompile.** When the differential smoke diverges
+  (CRuby and Spinel both run but disagree on stdout), `verify` now runs the
+  value-bisection harness (`spinel-dev tools/value-bisect/bisect.sh --json`) on
+  the still-on-disk harness and, when it pins the first scalar local to part
+  ways, appends a `localized:<file>:<line> <var> cruby=… spinel=…` reason. This
+  upgrades a bare `diff:L2 cruby=… spinel=…` ("the outputs differ") into a line
+  to look at ("`x` is wrong here"). Strictly best-effort and non-fatal: if the
+  harness can't be found (it's a separate repo — override with `SPINEL_BISECT`,
+  else probed next to the engine and at `~/sites/spinel-dev`) or can't attribute
+  the divergence to a traced scalar, the verdict is returned unchanged.
+
+### Changed
+- **`init` scaffold uses the published tep gem.** Now that tep is on RubyGems
+  (`tep 0.11.1`), the generated `Gemfile` emits plain `gem "tep", ">= 0.11.1"`
+  instead of the `git:`-fallback comment. Docs (`README`, `docs/adoption.md`)
+  updated to the published-gem form. spinelgems#10.
+- **`init`'s `bin/build` made self-sufficient + correct.** A clean-room run
+  showed the old `bundle install && ./bin/build` flow couldn't run: the
+  `engine: spinel` marker makes `bundle install` refuse under CRuby (by design),
+  and `bundle lock` + `vendor` place tep's *lib* but never install the `tep`
+  *CLI*. `bin/build` now `gem install`s tep if absent, uses `bundle lock` (not
+  install), exports `SPINEL` (so tep finds the provisioned engine), then
+  provisions + vendors + compiles; the `init` next-steps reflect this.
+  **The full onboarding now runs end-to-end** — validated in a clean `ruby:3.3`
+  container: `gem install bundler-spinel` → `init` → `./bin/build` → `./app`
+  serves a Spinel-compiled Tep app (needs `tep ≥ 0.11.1`, which builds its C
+  helpers on demand). spinelgems#10.
+
+## [0.1.1] — 2026-06-01
+
+### Fixed
+- **`init` scaffold produced an unlockable Gemfile.** It wrote the engine git SHA
+  into `engine_version:`, which bundler parses as a Gem version requirement —
+  `bundle lock` died with `Illformed requirement [...]`. The scaffold now writes a
+  version-literal `engine_version: "0.0.0"` (advisory) and pins the real revision
+  in a `SPINEL_PIN` file, which `install-engine` already reads. Caught by a
+  clean-room `ruby:3.3` Docker run of the full onboarding flow.
+
 ## [0.1.0] — 2026-06-01
 
 First non-prerelease. Installable without `--pre`. Closes the onboarding gap
@@ -57,5 +98,7 @@ and the ledger format may all change before `0.0.1`. Install with `--pre`.
 - Wholesale `survey` with a thread-safe ledger, a per-compile wall-clock
   timeout (`analyze-timeout` reject reason), and a ledger-based report.
 
+[0.2.0]: https://github.com/OriPekelman/spinelgems/releases/tag/v0.2.0
+[0.1.1]: https://github.com/OriPekelman/spinelgems/releases/tag/v0.1.1
 [0.1.0]: https://github.com/OriPekelman/spinelgems/releases/tag/v0.1.0
 [0.0.1.pre]: https://github.com/OriPekelman/spinelgems/releases/tag/v0.0.1.pre

data/README.md

@@ -37,8 +37,8 @@ limited and still growing. So we surveyed the ecosystem and publish a
 source "https://rubygems.org"
 ruby "3.3.0", engine: "spinel", engine_version: "0.0.0"
 
-gem "tep", git: "https://…/tep.git"   # siblings via path:/git:
-gem "some_pure_ruby_lib"
+gem "tep"                             # published on RubyGems
+gem "some_unreleased_lib", git: "…"   # or a sibling via path:/git:
 ```
 
 `bundle lock` resolves normally (it ignores the engine marker); the marker guards

data/lib/bundler/spinel/engine_installer.rb

@@ -160,7 +160,12 @@ module Bundler
       def init(dir, out: $stdout, rev: nil)
         FileUtils.mkdir_p(dir)
         engine_rev = rev || EngineInstaller::DEFAULT_REV
-        write(out, File.join(dir, "Gemfile"), gemfile(engine_rev))
+        write(out, File.join(dir, "Gemfile"), gemfile)
+        # The engine revision is a git SHA — NOT a valid `engine_version:` (bundler
+        # parses that as a Gem version requirement and `bundle lock` errors on a
+        # SHA). So the rev lives in a SPINEL_PIN file, which `install-engine`
+        # reads; the Gemfile keeps a version-literal advisory marker.
+        write(out, File.join(dir, "SPINEL_PIN"), "#{engine_rev}\n")
         write(out, File.join(dir, "app.rb"), app_rb)
         bin = File.join(dir, "bin", "build")
         FileUtils.mkdir_p(File.dirname(bin))
@@ -171,9 +176,11 @@ module Bundler
         out.puts "Scaffolded a Spinel + Tep project in #{dir}/"
         out.puts "Next:"
         out.puts "  cd #{dir}" unless File.expand_path(dir) == Dir.pwd
-        out.puts "  bundle install        # resolves deps (gated by the compat ledger)"
-        out.puts "  ./bin/build           # provisions Spinel, vendors deps, compiles app.rb"
+        out.puts "  ./bin/build           # ensures tep, resolves + vendors deps, provisions Spinel, compiles"
         out.puts "  ./app -p 4567         # run the native binary"
+        out.puts ""
+        out.puts "(The `engine: spinel` Gemfile marker makes `bundle install` refuse to run"
+        out.puts " under CRuby by design — bin/build uses `bundle lock` + `spinel-compat vendor`.)"
       end
 
       def write(out, path, body)
@@ -185,17 +192,20 @@ module Bundler
         end
       end
 
-      def gemfile(rev)
+      def gemfile
         <<~RUBY
           source "https://rubygems.org"
 
           # Spinel is the engine: code here is compiled ahead-of-time to a native
-          # binary, not run on CRuby. The compat ledger (bundler-spinel) gates the
-          # lock so you only resolve gems known to compile under this engine rev.
-          ruby "3.3.0", engine: "spinel", engine_version: "#{rev}"
-
-          # The web framework — Sinatra-style, compiles via Spinel.
-          gem "tep"
+          # binary, not run on CRuby. `engine_version` is advisory and must be a
+          # version literal (bundler parses it as a Gem requirement); the actual
+          # engine revision install-engine builds is pinned in ./SPINEL_PIN.
+          ruby "3.3.0", engine: "spinel", engine_version: "0.0.0"
+
+          # The web framework — Sinatra-style, compiles via Spinel. >= 0.11.1 builds
+          # its C helpers on demand (needed for `gem install tep` without `make`).
+          # (For an unreleased sibling instead: gem "tep", git: "https://github.com/OriPekelman/tep.git")
+          gem "tep", ">= 0.11.1"
         RUBY
       end
 
@@ -212,12 +222,16 @@ module Bundler
       def build_sh
         <<~SH
           #!/usr/bin/env bash
-          # Provision the Spinel compiler, vendor deps where Spinel finds them,
-          # and compile app.rb to a native binary.
+          # From a fresh checkout to a native binary. The Gemfile's `engine: spinel`
+          # marker makes `bundle install` refuse to run under CRuby, so we resolve
+          # with `bundle lock` and place deps with `spinel-compat vendor` instead.
           set -e
-          spinel-compat install-engine          # fetch+build the pinned engine (cached)
-          spinel-compat vendor                  # place deps + write deps.rb
-          tep build app.rb -o app               # compile -> ./app
+          command -v tep >/dev/null 2>&1 || gem install tep   # the tep build CLI (a compile-time tool)
+          [ -f Gemfile.lock ] || bundle lock                  # resolve deps (NOT `bundle install`)
+          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
           echo "built ./app — run it with: ./app -p 4567"
         SH
       end

data/lib/bundler/spinel/localizer.rb

@@ -0,0 +1,83 @@
+require "open3"
+require "json"
+
+module Bundler
+  module Spinel
+    # Upgrades a bare `miscompile` verdict (CRuby and Spinel agree to run but
+    # disagree on stdout) into a *located* one: the (file, line, variable) where
+    # a scalar local first diverges — via the value-bisection harness that lives
+    # in the spinel-dev repo (tools/value-bisect/bisect.sh).
+    #
+    # Why: a miscompile reason of `diff:L2 cruby="42" spinel="0"` says two outputs
+    # differ but not *why*. The bisector traces every scalar local under both
+    # CRuby and a Spinel --debug build and reports the first to part ways, turning
+    # that into `localized:foo.rb:12 total cruby=42 spinel=0` — a line to look at.
+    #
+    # Strictly best-effort and non-fatal. If the harness can't be found (it's a
+    # separate repo), can't run (the engine dir is a bare binary with no compiler
+    # sources / no lldb), or can't pin a scalar (the divergence is in output
+    # formatting, not a traced local), verify still returns the miscompile verdict
+    # unchanged — this only ever *adds* a `localized:` reason when it has one.
+    class Localizer
+      def initialize(engine)
+        @engine = engine
+      end
+
+      # Run the bisector on `harness` (a self-contained .rb; require_relative'd
+      # files are traced too) and return a short reason string, or nil when
+      # localization isn't possible or didn't pin a value.
+      def localize(harness)
+        script = bisect_script or return nil
+        # SPINEL_DIR points the bisector at the same compiler the engine uses;
+        # it shells out to that checkout's spinel_analyze.rb / spinel_codegen.rb.
+        # bisect.sh exits 1 *on divergence* (the case we want), so the exit code
+        # is not a success signal — parse stdout regardless. stdout carries only
+        # the single JSON object in --json mode; progress goes to stderr.
+        out, _err, _st = Open3.capture3(
+          { "SPINEL_DIR" => @engine.dir }, "sh", script, "--json", harness
+        )
+        line = out.lines.map(&:strip).reject(&:empty?).last or return nil
+        verdict = begin
+          JSON.parse(line)
+        rescue JSON::ParserError
+          return nil
+        end
+        format_verdict(verdict)
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def format_verdict(v)
+        case v["verdict"]
+        when "diverge"
+          "localized:#{loc(v)} #{v['variable']} cruby=#{v['cruby']} spinel=#{v['spinel']}"
+        when "crash"
+          "localized:crash@#{loc(v)} signal=#{v['signal']}"
+        end
+        # Any other verdict (ok / exit-differ / abort) means the bisector couldn't
+        # attribute the divergence to a traced scalar; leave the verdict un-enriched.
+      end
+
+      def loc(v)
+        file = v["file"].to_s
+        file.empty? ? "line #{v['line']}" : "#{file}:#{v['line']}"
+      end
+
+      # Resolve bisect.sh. It lives in spinel-dev (separate from the compiler
+      # engine), so there's no fixed relation to the engine dir — probe a few
+      # conventional spots, newest-intent first: an explicit override, a sibling
+      # spinel-dev checkout next to the engine, the conventional ~/sites layout.
+      def bisect_script
+        rel = "tools/value-bisect/bisect.sh"
+        candidates = [
+          ENV["SPINEL_BISECT"],
+          File.expand_path(File.join(@engine.dir, "..", "spinel-dev", rel)),
+          File.expand_path("~/sites/spinel-dev/#{rel}")
+        ]
+        candidates.find { |c| c && File.exist?(c) }
+      end
+    end
+  end
+end

data/lib/bundler/spinel/verifier.rb

@@ -1,4 +1,5 @@
 require "open3"
+require_relative "localizer"
 
 module Bundler
   module Spinel
@@ -50,6 +51,15 @@ module Bundler
         unless verdict == "verified" || verdict == "loaded" || verdict == "clean"
           reasons = ["rubric:#{rubric(ruby_ok, ruby_err, spin_ok, spin_err, ruby_out, spin_out, gem_name)}"] + reasons
         end
+        # Self-localize a miscompile: a `diff:L2 cruby=… spinel=…` reason says
+        # the outputs differ but not where the value went wrong. The bisector
+        # traces the still-on-disk harness (require_relative'd gem files included)
+        # and, when it pins a diverging scalar, appends `localized:<file>:<line>
+        # <var> cruby=… spinel=…`. Best-effort: nil when it can't localize.
+        if verdict == "rejected" && reasons.include?("miscompile")
+          loc = Localizer.new(@engine).localize(harness)
+          reasons += [loc] if loc
+        end
         @ledger.record(@ledger.build(
           gem: gem_name, version: version, rev: @engine.rev,
           verdict: verdict, reasons: reasons, probe: full ? "verify-full" : "verify"

data/lib/bundler/spinel/version.rb

@@ -4,6 +4,6 @@ module Bundler
     # are proven, and `install-engine` now provisions the compiler too, so a
     # newcomer can `gem install bundler-spinel` and onboard without an
     # out-of-band Spinel build (spinelgems#9).
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/bundler/spinel.rb

@@ -10,6 +10,7 @@ require_relative "spinel/ledger"
 require_relative "spinel/gem_fetcher"
 require_relative "spinel/probe"
 require_relative "spinel/verifier"
+require_relative "spinel/localizer"
 require_relative "spinel/vendorer"
 require_relative "spinel/survey"
 require_relative "spinel/checker"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bundler-spinel
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ori Pekelman
@@ -37,6 +37,7 @@ files:
 - lib/bundler/spinel/gem_fetcher.rb
 - lib/bundler/spinel/history.rb
 - lib/bundler/spinel/ledger.rb
+- lib/bundler/spinel/localizer.rb
 - lib/bundler/spinel/platform.rb
 - lib/bundler/spinel/probe.rb
 - lib/bundler/spinel/proxy.rb