proscenium 0.26.0-x86_64-linux-gnu

data/lib/proscenium/builder.rb

@@ -0,0 +1,403 @@
+# frozen_string_literal: true
+
+require 'ffi'
+require 'pathname'
+require_relative 'error'
+
+module Proscenium
+  class Builder
+    ENVIRONMENTS = { development: 1, test: 2, production: 3 }.freeze
+
+    class Result < FFI::Struct
+      layout :success, :bool,
+             :response, :pointer,
+             :content_hash, :pointer
+    end
+
+    class ResolveResult < FFI::Struct
+      layout :success, :bool,
+             :url_path, :pointer,
+             :abs_path, :pointer
+    end
+
+    class CompileResult < FFI::Struct
+      layout :success, :bool,
+             :messages, :pointer
+    end
+
+    # The compiled Go library. It ships in the platform gems only, gated in the gemspec, so a
+    # host that matches no platform gem installs the platform-less gem and finds nothing here.
+    #
+    # Named explicitly rather than left to the loader: LoadLibrary appends `.dll` to a bare module
+    # name, but the documentation does not promise it for a full path, and being wrong here means
+    # every call fails at load with an error about a missing file rather than anything useful.
+    LIBRARY_NAME = Gem.win_platform? ? 'proscenium.dll' : 'proscenium'
+    LIBRARY_PATH = Pathname.new(__dir__).join('ext', LIBRARY_NAME)
+
+    # Raised in place of letting `ffi_lib` fail on its own. FFI reports a missing library as
+    # `Could not open library <path>` followed by the system search paths, which reads like a
+    # broken install and says nothing about platforms - so the one thing the reader needs to know,
+    # that Proscenium ships no binary for their platform, is the one thing it leaves out.
+    class UnsupportedPlatform < Error
+      def initialize(path)
+        super(<<~MESSAGE)
+          Proscenium has no compiled library for this platform (#{Gem::Platform.local}).
+
+          Proscenium is a Ruby gem wrapped around a Go library, so it ships a separate gem per
+          platform. Yours matched none of them, so you have the platform-less gem, which carries
+          no library at all. Nothing is corrupted - this platform is simply not built for.
+
+          Expected the library at: #{path}
+
+          The supported platforms are listed in the README. If yours should be among them, please
+          open an issue at https://github.com/joelmoss/proscenium/issues.
+        MESSAGE
+      end
+    end
+
+    module Request
+      extend FFI::Library
+
+      raise UnsupportedPlatform, LIBRARY_PATH unless LIBRARY_PATH.exist?
+
+      ffi_lib LIBRARY_PATH.to_s
+
+      # Windows unmaps the library at interpreter exit, and the Go runtime does not survive it.
+      #
+      # ffi's library_free calls dl_close on every platform but macOS, which is FreeLibrary here,
+      # and Ruby runs every T_DATA free during VM teardown. Go's c-shared runtime cannot be
+      # unloaded: its threads are still running when the mapping goes. On Linux this never bites,
+      # because the Go linker marks the library nodelete and dlclose is a no-op; Windows has no
+      # equivalent. Measured on windows-latest: three of five plain `require` runs exited 139,
+      # while five of five exited 0 when the script ended in `exit!`, which skips the teardown.
+      #
+      # Pinning the module means the reference count never reaches zero, so FreeLibrary returns
+      # without unmapping anything. Nothing here needs the handle, only the pin.
+      if Gem.win_platform?
+        module Kernel32
+          extend FFI::Library
+
+          ffi_lib 'kernel32'
+          attach_function :GetModuleHandleExW, %i[uint32 buffer_in pointer], :int
+        end
+
+        # GET_MODULE_HANDLE_EX_FLAG_PIN. Backslashes, because GetModuleHandle documents that a full
+        # path must use them, and LIBRARY_PATH is built from __dir__, which uses "/". Checked,
+        # because a pin that quietly failed would bring back an exit crash that only happens some
+        # of the time, with nothing to say why.
+        name = "#{LIBRARY_PATH.to_s.tr('/', '\\')}\0".encode(Encoding::UTF_16LE)
+        if Kernel32.GetModuleHandleExW(0x1, name, FFI::MemoryPointer.new(:pointer)).zero?
+          warn "Proscenium could not pin #{LIBRARY_PATH} (Windows error " \
+               "#{FFI::LastError.winapi_error}), so Ruby may crash when it exits."
+        end
+      end
+
+      enum :environment, [:development, 1, :test, :production]
+
+      # `blocking: true` releases the GVL for the duration of the call, so a build/resolve
+      # doesn't stall unrelated Ruby threads (eg. other requests in a multi-threaded server).
+      # Safe to do because the Go side shares nothing between calls: each call parses its own
+      # config, and the caches that outlive a call (i18n, svg, npm replacements) carry their own
+      # locks. See the note in main.go. There is no serialising mutex any more; a new piece of
+      # global state on the Go side needs its own.
+
+      attach_function :build_to_string, [
+        :string, # Path or entry point.
+        :pointer # Config as JSON.
+      ], Result.by_value, blocking: true
+
+      attach_function :resolve, [
+        :string, # path or entry point
+        :pointer # Config as JSON.
+      ], ResolveResult.by_value, blocking: true
+
+      attach_function :compile, [
+        :pointer # Config as JSON.
+      ], CompileResult.by_value, blocking: true
+
+      attach_function :reset_config, [], :void, blocking: true
+
+      attach_function :free_cstr, [:pointer], :void
+    end
+
+    class BuildError < Error
+      attr_reader :error, :path
+
+      # One esbuild message as text: its text, detail and location on one line, then each note
+      # with its own location on a line of its own. A note is where a recovered Go panic carries
+      # its stack, and where a failure inside a nested build names the file that imported it -
+      # without this they never left the JSON.
+      def self.format_message(message)
+        msg = message['Text'].to_s.dup
+        msg << ' - ' << message['Detail'] if message['Detail'].is_a?(String)
+        msg << format_location(message['Location'])
+        Array(message['Notes']).each do |note|
+          msg << "\n" << note['Text'].to_s << format_location(note['Location'])
+        end
+
+        msg
+      end
+
+      def self.format_location(location)
+        location ? " at #{location['File']}:#{location['Line']}:#{location['Column']}" : ''
+      end
+
+      # Go always answers with a JSON object. Anything else - a nil pointer, a bare scalar, text -
+      # is a contract violation, and is shown as the message rather than replaced by a parse error
+      # that hides it.
+      def self.parse_json(json)
+        parsed = JSON.parse(json)
+        parsed if parsed.is_a?(Hash)
+      rescue JSON::ParserError, TypeError
+        nil
+      end
+
+      def initialize(path, error)
+        @path = path
+        @error = self.class.parse_json(error) || { 'Text' => error.to_s }
+
+        super("Failed to build #{path} - #{self.class.format_message(@error)}")
+      end
+    end
+
+    # Raised by `compile` with every error esbuild reported. It used to return `false` and throw
+    # the messages away, so a failed precompile gave no reason at all.
+    class CompileError < Error
+      attr_reader :messages
+
+      def initialize(messages)
+        @messages = BuildError.parse_json(messages) || { 'Errors' => [{ 'Text' => messages.to_s }] }
+
+        errors = Array(@messages['Errors']).map { |message| BuildError.format_message(message) }
+
+        super("Failed to compile assets - #{errors.join("\n")}")
+      end
+    end
+
+    class ResolveError < Error
+      attr_reader :path
+
+      def initialize(path, msg)
+        @path = path
+        super("Failed to resolve #{path} - #{msg}")
+      end
+    end
+
+    def self.build_to_string(path, root: nil, **overrides)
+      new(root:, **overrides).build_to_string(path)
+    end
+
+    def self.resolve(path, root: nil, **overrides)
+      new(root:, **overrides).resolve(path)
+    end
+
+    def self.compile(root: nil, **overrides)
+      new(root:, **overrides).compile
+    end
+
+    # Why no build may run now, or nil (#154): an install is under way or stopped before it
+    # finished, or the committed gem dependency contexts are stale. With
+    # PROSCENIUM_STALE_CONTEXT=warn, for an incident, stale contexts are logged once instead.
+    def self.refusal(root = Rails.root)
+      project = ContextMap.project_root
+      return ContextMap::INSTALLING_MESSAGE if ContextMap.installing?(project)
+
+      outside = outside_rails_root(project, root) and return outside
+
+      stale = StaleContexts.message(project, generation) or return
+      return stale unless ENV['PROSCENIUM_STALE_CONTEXT'] == 'warn'
+
+      @warned ||= Set.new
+      Rails.logger.warn("[Proscenium] #{stale}") if @warned.add?(stale)
+      nil
+    end
+
+    # Why an adopted app's contexts cannot be served from `root`, the root builds run in (the Rails
+    # app's), or nil (#154). They live at the bundle's root, beside the Gemfile; one outside `root`
+    # has no URL the engine serves, so such a layout is refused plainly, not left to fail
+    # mid-page. Only compares paths unless they differ.
+    def self.outside_rails_root(project, root = Rails.root)
+      return if within?(project, root) || !ContextMap.adopted?(project)
+
+      "Gem dependency contexts are under #{project}, outside the Rails app at #{root}, " \
+        'which Proscenium cannot serve yet. Keep the Gemfile in the Rails root to use them.'
+    end
+
+    # Whether `path` is `root` or under it, as spelled or, through a link such as a Capistrano
+    # `current`, as resolved.
+    def self.within?(path, root)
+      under?(path, root) || under?(File.realpath(path), File.realpath(root))
+    rescue SystemCallError
+      false
+    end
+
+    def self.under?(path, root) = "#{path}/".start_with?("#{root}/")
+    private_class_method :within?, :under?
+
+    # The mapping generation builds use now (#154). See Resolver.generation.
+    def self.generation = Resolver.generation
+
+    # Resets nothing any more - Go keeps no config between calls. Kept because it is the one call
+    # into Go that needs no Rails app, which is how bin/verify-installed-gem and the packaging test
+    # prove the library loads, and benchmarks/bridge.rb times it as the bare cost of an FFI call.
+    def self.reset_config!
+      Request.reset_config
+    end
+
+    # `overrides` are merged over the config derived from `Proscenium.config`, and are passed
+    # straight through to the Go side. Intended for callers that are not serving a browser request
+    # and so want different build settings - `Bundle: false`, `Write: false`, `CodeSplitting: false`
+    # - than the app's own configuration. Keys must match `types.ConfigT`; Go silently ignores
+    # any it does not know.
+    def initialize(root: nil, **overrides)
+      @root = root
+      @overrides = overrides
+      @generation = self.class.generation
+      @request_config = configure(@generation)
+    end
+
+    # The config pointer for the current mapping generation: a Builder kept past an install, or
+    # made just before one finished, sends Go the context map builds now use, not the one it was
+    # made with (#154).
+    def request_config
+      generation = self.class.generation
+      @request_config = configure(@generation = generation) if generation != @generation
+      @request_config
+    end
+    private :request_config
+
+    def configure(generation)
+      config_hash = {
+        RootPath: (@root || Rails.root).to_s,
+        OutputDir: "public#{Proscenium.config.output_dir}",
+        GemPath: gem_root,
+        Environment: ENVIRONMENTS.fetch(Rails.env.to_sym, 2),
+        EnvVars: env_vars,
+        CodeSplitting: Proscenium.config.code_splitting,
+        RubyGems: Proscenium::BundledGems.paths,
+        Bundle: Proscenium.config.bundle,
+        Aliases: Proscenium.config.aliases,
+        External: Proscenium.config.external,
+        Precompile: Proscenium.config.precompile,
+        Debug: Proscenium.config.debug,
+        **ContextMap.config(ContextMap.project_root, generation)
+      }.merge(@overrides)
+
+      self.class.request_config_pointer(config_hash)
+    end
+    private :configure
+
+    class << self
+      # Building the config JSON and copying it into an FFI::MemoryPointer is the only real cost
+      # in instantiating a Builder (everything else is memoized attribute reads). Since the
+      # config is identical across the vast majority of calls (same root, same Rails env, same
+      # Proscenium.config), skip re-serializing and re-allocating it when nothing has changed.
+      #
+      # Callers keep their own reference to the returned pointer, so a later call replacing the
+      # memo does not invalidate a pointer already in use.
+      #
+      # The hash and its pointer are stored as one frozen pair in one ivar, and assigned once. Two
+      # ivars would need a lock: a reader could see a hash already updated while its pointer still
+      # pointed at the previous config, and get a build made with someone else's settings. One
+      # assignment cannot be observed half-done, so a reader sees either the old pair or the new
+      # one - never a mix - and there is no window for a test to have to reproduce.
+      def request_config_pointer(config_hash)
+        memo = @config_memo
+        return memo[1] if memo && memo[0] == config_hash
+
+        pointer = FFI::MemoryPointer.from_string(config_hash.to_json)
+        @config_memo = [config_hash, pointer].freeze
+
+        pointer
+      end
+    end
+
+    def build_to_string(path)
+      if (reason = self.class.refusal(@root || Rails.root))
+        raise BuildError.new(path, reason)
+      end
+
+      ActiveSupport::Notifications.instrument('build.proscenium', identifier: path) do
+        raw = Request.build_to_string(path, request_config)
+        result = { success: raw[:success], response: read_and_free(raw[:response]),
+                   content_hash: read_and_free(raw[:content_hash]) }
+
+        raise BuildError.new(path, result[:response]) unless result[:success]
+
+        result
+      end
+    end
+
+    def resolve(path)
+      if (reason = self.class.refusal(@root || Rails.root))
+        raise ResolveError.new(path, reason)
+      end
+
+      ActiveSupport::Notifications.instrument('resolve.proscenium', identifier: path) do
+        raw = Request.resolve(path, request_config)
+        success = raw[:success]
+        url_path = read_and_free(raw[:url_path])
+        abs_path = read_and_free(raw[:abs_path])
+
+        raise ResolveError.new(path, url_path) unless success
+
+        [url_path, abs_path]
+      end
+    end
+
+    # Returns true, or raises CompileError with esbuild's messages.
+    def compile
+      if (reason = self.class.refusal(@root || Rails.root))
+        raise CompileError, reason
+      end
+
+      raw = Request.compile(request_config)
+      messages = read_and_free(raw[:messages])
+
+      raise CompileError, messages unless raw[:success]
+
+      raw[:success]
+    end
+
+    private
+
+    # The Go side allocates each of these strings with C.CString, which the Go runtime cannot
+    # see or collect - it must be freed from this side once we're done reading it.
+    #
+    # `read_string` always returns ASCII-8BIT, but everything Go sends is UTF-8: paths, esbuild's
+    # output and its messages. Left binary, a non-ASCII character is several "characters" to
+    # anything working on the string, and JSON.generate warns (a later json will raise).
+    def read_and_free(ptr)
+      return nil if ptr.null?
+
+      ptr.read_string.force_encoding(Encoding::UTF_8)
+    ensure
+      Request.free_cstr(ptr)
+    end
+
+    # Build the ENV variables as determined by `Proscenium.config.env_vars` and
+    # `Proscenium::DEFAULT_ENV_VARS` to pass to esbuild.
+    #
+    # Each name becomes the esbuild define `proscenium.env.<NAME>`, so one that is not a JS
+    # identifier would fail every build, or with a dot define a nested path. Checked whether or not
+    # the variable is set, so a bad name fails the first build everywhere, not only where it is set.
+    #
+    # Only the ASCII rules are checked, on the raw bytes: Ruby's Unicode tables differ from
+    # esbuild's by Ruby version, so non-ASCII characters are left for esbuild to judge, and the
+    # bytes cannot raise an encoding error. An empty name passes, and `ENV.slice` drops it.
+    def env_vars
+      names = Array(Proscenium.config.env_vars).map(&:to_s)
+      if (invalid = names.select { |name| name.b.match?(/\A\d|[^\w$\x80-\xff]/n) }).any?
+        raise ArgumentError, 'config.proscenium.env_vars must be JavaScript identifiers, but got ' \
+                             "#{invalid.map(&:inspect).join(', ')}"
+      end
+
+      ENV['NODE_ENV'] = ENV.fetch('RAILS_ENV', nil)
+      ENV.slice(*Proscenium::DEFAULT_ENV_VARS, *names)
+    end
+
+    def gem_root
+      Pathname.new(__dir__).join('..', '..').to_s
+    end
+  end
+end

data/lib/proscenium/bundled_gems.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'error'
+
+module Proscenium
+  # The one reader of the bundle, for the engine and the `proscenium` CLI alike, so the two never
+  # disagree about which gems exist or which take part in JavaScript dependency installation
+  # (#154). It must not load ActiveSupport or anything else the CLI may not.
+  module BundledGems
+    # The app's package.json, or its `proscenium` key, is unreadable or not in the documented
+    # shape.
+    class ConfigError < Proscenium::Error; end
+
+    module_function
+
+    def paths
+      @paths ||= begin
+        specs = Bundler.load.specs.reject { |s| s.name == 'bundler' }.sort_by(&:name)
+
+        raise 'No gems in your Gemfile' if specs.empty?
+
+        bundle = {}
+        specs.each do |s|
+          bundle[s.name] = if s.name == 'proscenium'
+                             Pathname(s.full_gem_path).join('lib/proscenium').to_s
+                           else
+                             s.full_gem_path
+                           end
+        end
+        bundle
+      end
+    end
+
+    # The `@rubygems/` form of an absolute path inside a bundled gem, or nil when it is in none.
+    # A plain prefix match: a gem path is text, not a pattern, and may hold `+` or `(`.
+    #
+    # The longest root wins, which is Go's rule in `GemFromFsPath`, so a file under a gem nested in
+    # another gem's tree gets one URL from both sides. `max_by` keeps the first of equal roots, and
+    # `paths` is sorted by name, so a tie goes to the first name, as it does in Go.
+    def virtual_path(abs_path)
+      name, root = paths.select { |_, v| abs_path.start_with? "#{v}/" }.max_by { |_, v| v.length }
+      name && "@rubygems/#{name}#{abs_path.delete_prefix(root)}"
+    end
+
+    # Every installed gem but Bundler, sorted by name: the specs of the groups Bundler loaded.
+    def installed_specs = Bundler.load.specs.reject { it.name == 'bundler' }.sort_by(&:name)
+
+    # The names in Gemfile.lock, installed or not, or nil without a lockfile. A gem in a group
+    # BUNDLE_WITHOUT excludes, or locked for another platform, is here but not installed.
+    def locked_names
+      locked = Bundler.locked_gems
+      locked && locked.specs.map(&:name).uniq.sort
+    end
+
+    # Locked gems that are not installed: their committed contexts are trusted as they are (the
+    # production rule).
+    def excluded_names(specs = installed_specs)
+      (locked_names || []) - specs.map(&:name)
+    end
+
+    # `proscenium.gemOverrides` from the app's package.json: gem name => true or false, or {}
+    # without one.
+    def overrides(root)
+      path = File.join(root, 'package.json')
+      return {} unless File.exist?(path)
+
+      package = JSON.parse(File.read(path, encoding: 'bom|utf-8'))
+      raise ConfigError, 'package.json does not hold a JSON object' unless package.is_a?(Hash)
+
+      config = package['proscenium'] || {}
+      raise ConfigError, '"proscenium" in package.json must be an object' unless config.is_a?(Hash)
+
+      overrides = config['gemOverrides'] || {}
+      unless overrides.is_a?(Hash)
+        raise ConfigError, '"proscenium.gemOverrides" in package.json must be an object'
+      end
+
+      overrides.to_h do |gem, settings|
+        participate = settings.is_a?(Hash) ? settings['participate'] : nil
+        unless [true, false].include?(participate)
+          raise ConfigError,
+                "\"proscenium.gemOverrides.#{gem}.participate\" in package.json must be true " \
+                'or false'
+        end
+
+        [gem, participate]
+      end
+    rescue JSON::ParserError => e
+      raise ConfigError, "package.json is not valid JSON (#{e.message.lines.first.strip})"
+    end
+
+    # Whether the gem's author opted it in, with gemspec metadata.
+    def opted_in?(spec) = spec.metadata['proscenium.dependencies'] == 'true'
+
+    # The gem's `proscenium.frontend_root`, relative to the gem: '' for its root, nil if it names a
+    # place outside the gem.
+    def frontend_root(spec)
+      relative = spec.metadata['proscenium.frontend_root'].to_s.delete_prefix('./').chomp('/')
+      return nil if relative.start_with?('/') || relative.split('/').include?('..')
+
+      relative
+    end
+
+    # The installed directory holding the gem's package.json, or nil if its frontend root is
+    # outside the gem.
+    def manifest_root(spec)
+      relative = frontend_root(spec)
+      return nil unless relative
+
+      relative.empty? ? spec.full_gem_path : File.join(spec.full_gem_path, relative)
+    end
+
+    # The participating installed specs, by name: opted in by their author or the app, and not
+    # opted out by the app.
+    def participating(specs = installed_specs, overrides: {})
+      specs.select { |spec| overrides.fetch(spec.name) { opted_in?(spec) } }.to_h { [it.name, it] }
+    end
+
+    # Installed gems that ship a root package.json but do not participate, for `inspect`.
+    def unparticipating_with_manifest(specs = installed_specs, overrides: {})
+      chosen = participating(specs, overrides:)
+      specs.reject { chosen.key?(it.name) }
+           .select { File.exist?(File.join(it.full_gem_path, 'package.json')) }
+           .map(&:name)
+    end
+
+    def pathname_for(name)
+      (path = paths[name]) ? Pathname(path) : nil
+    end
+
+    def pathname_for!(name)
+      unless (path = pathname_for(name))
+        raise "Gem `#{name}` not found in your Gemfile"
+      end
+
+      path
+    end
+  end
+end

data/lib/proscenium/cli/brackets.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Proscenium
+  module CLI
+    # Quote-aware bracket scanning for the textual splices of pnpm-workspace.yaml flow lists and
+    # package.json (#154): a bracket or brace inside a quoted string is text, not structure.
+    module Brackets
+      module_function
+
+      # The index of the `]` closing the flow list or JSON array whose `[` ends at `start`, or nil:
+      # a bracket inside a quoted string, as a glob such as `packages/[ab]` has, or in a nested
+      # list, does not close it.
+      def array_end(text, start)
+        depth = 0
+        structure(text, start) do |char, index|
+          if char == '['
+            depth += 1
+          elsif char == ']'
+            return index if depth.zero?
+
+            depth -= 1
+          end
+        end
+        nil
+      end
+
+      # Where the first match of `key` from `from` at `depth` (1 for a JSON document's own keys)
+      # ends, or nil: another object's key of the same name is not it.
+      def key_end(text, key, depth, from = 0)
+        text.to_enum(:scan, key).map { Regexp.last_match }
+            .find { it.begin(0) >= from && depth(text, it.begin(0)) == depth }&.end(0)
+      end
+
+      # How deep `index` sits in `text`'s brackets and braces, outside quoted strings.
+      def depth(text, index)
+        nesting = { '[' => 1, '{' => 1, ']' => -1, '}' => -1 }
+        structure(text).take_while { |_, at| at < index }.sum { |char, _| nesting.fetch(char, 0) }
+      end
+
+      # Each character of `text` from `from` that is outside a quoted string or a YAML comment, with
+      # its index.
+      def structure(text, from = 0)
+        return enum_for(__method__, text, from) unless block_given?
+
+        quote = nil
+        index = from
+        while index < text.length
+          char = text[index]
+          if quote
+            index += 1 if char == '\\' && quote == '"'
+            quote = nil if char == quote
+          elsif ['"', "'"].include?(char)
+            quote = char
+          elsif char == '#' && (index.zero? || text[index - 1].match?(/[\s\[{,]/))
+            # A YAML comment, to the end of its line, after a space or a flow delimiter, as Psych
+            # reads it. JSON has no `#` outside a string.
+            index = (text.index("\n", index) || text.length) - 1
+          else
+            yield char, index
+          end
+          index += 1
+        end
+      end
+    end
+  end
+end

data/lib/proscenium/cli/bun_linker.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../context_map'
+require_relative 'manager'
+
+module Proscenium
+  module CLI
+    # The Bun linker an app uses today, written into bunfig.toml when the app sets none (#154,
+    # C48). Registering contexts adds `workspaces`, and with no linker set that alone can switch
+    # Bun from a hoisted node_modules to its isolated store (Stage A), so the first install pins
+    # the layout the app already has. Shown in the registration diff before it is written.
+    module BunLinker
+      # An `[install]` header, its name bare or quoted, and any comment after it.
+      HEADER = /^\[[ \t]*#{Manager::INSTALL}[ \t]*\][ \t]*(?:#[^\r\n]*)?(?=\r?$)/
+
+      module_function
+
+      # Bun's names for each layout: `node-linker`'s, and `install-strategy`'s, which node-linker
+      # overrides (probed on Bun 1.4.2).
+      NODE_LINKERS = { 'isolated' => 'isolated', 'pnpm' => 'isolated', 'hoisted' => 'hoisted',
+                       'npm' => 'hoisted' }.freeze
+      STRATEGIES = { 'linked' => 'isolated', 'hoisted' => 'hoisted', 'nested' => 'hoisted' }.freeze
+      NPMRC_LINKER = /^[ \t]*(node-linker|install-strategy)[ \t]*=[ \t]*["']?([^\s"']+)/
+
+      # The linker the project's .npmrc chooses. Otherwise `isolated` if Bun's isolated store is
+      # there, `hoisted` for any other node_modules. With nothing installed yet: what Bun would
+      # pick for the app as it stands, which is isolated only for an app that already declares
+      # workspaces under a lock of configVersion 1 or later.
+      def current(root)
+        chosen = configured(root)
+        return chosen if chosen
+
+        modules = File.join(root, 'node_modules')
+        return 'isolated' if File.directory?(File.join(modules, '.bun'))
+        return 'hoisted' if File.directory?(modules)
+
+        workspaces?(root) && config_version(root) >= 1 ? 'isolated' : 'hoisted'
+      end
+
+      # bunfig.toml's text with `linker` set in its `[install]` table, adding the table if need be.
+      def splice(text, linker)
+        line = "linker = \"#{linker}\""
+        eol = text.include?("\r\n") ? "\r\n" : "\n"
+        if (header = text.match(HEADER))
+          text.dup.insert(header.end(0), "#{eol}#{line}")
+        else
+          separator = text.empty? || text.end_with?("\n") ? '' : eol
+          "#{text}#{separator}#{eol unless text.empty?}[install]#{eol}#{line}#{eol}"
+        end
+      end
+
+      # The linker the project's own .npmrc sets. Bun also reads the developer's ~/.npmrc,
+      # $XDG_CONFIG_HOME/.npmrc and global .bunfig.toml, but this is committed for the whole team,
+      # so only the project decides it.
+      def configured(root) = npmrc_linker(File.join(root, '.npmrc'))
+
+      # The linker an .npmrc sets, by node-linker or else install-strategy, or nil.
+      def npmrc_linker(path)
+        return unless File.exist?(path)
+
+        settings = File.read(path).scan(NPMRC_LINKER).to_h
+        NODE_LINKERS[settings['node-linker']] || STRATEGIES[settings['install-strategy']]
+      end
+
+      def workspaces?(root)
+        path = File.join(root, 'package.json')
+        File.exist?(path) && ContextMap.read_json(path).key?('workspaces')
+      rescue JSON::ParserError
+        false
+      end
+
+      def config_version(root)
+        path = File.join(root, 'bun.lock')
+        File.exist?(path) ? File.read(path)[/"configVersion":\s*(\d+)/, 1].to_i : 0
+      end
+    end
+  end
+end