proscenium 0.26.0-aarch64-linux-gnu

data/exe/proscenium

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run as `bundle exec proscenium`. Loads the CLI alone: never `proscenium` itself, Rails, FFI or
+# the engine library (see lib/proscenium/cli.rb).
+# When the CLI started loading, for the timings install reports (C40).
+PROSCENIUM_STARTED = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+# Every file the CLI reads (package.json, contexts, pnpm-workspace.yaml) is UTF-8, whatever the
+# locale: under LANG=C, as minimal Docker and CI images run, Ruby would read them as US-ASCII.
+# Ruby warns of the setting, which is meant for this process alone.
+verbose = $VERBOSE
+$VERBOSE = nil
+Encoding.default_external = Encoding::UTF_8
+$VERBOSE = verbose
+
+require 'proscenium/cli'
+
+exit Proscenium::CLI.start(ARGV)

data/exe/psm

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# `bundle exec psm`: a shorter name for `bundle exec proscenium`, which it runs as is.
+load File.expand_path('proscenium', __dir__)

data/lib/generators/proscenium/bun/bun_generator.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module Proscenium
+  module Generators
+    # Sets up `bun test` so it can import the same JS, TS, JSX and CSS the app serves.
+    #
+    #   rails generate proscenium:bun
+    #
+    # Safe to run more than once: the preload is created if missing, and bunfig.toml is merged
+    # rather than overwritten, because an app may already have one with its own preloads.
+    class BunGenerator < Rails::Generators::Base
+      PRELOAD_PATH = 'test/proscenium.preload.js'
+      PRELOAD_ENTRY = './test/proscenium.preload.js'
+      BUNFIG_PATH = 'bunfig.toml'
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Configure bun test to run against your Proscenium-bundled JavaScript.'
+
+      def create_preload
+        template 'proscenium.preload.js', PRELOAD_PATH
+      end
+
+      def configure_bunfig
+        return create_file(BUNFIG_PATH, default_bunfig) unless File.exist?(bunfig_full_path)
+
+        contents = File.read(bunfig_full_path)
+
+        if already_preloaded?(contents)
+          say_status :identical, BUNFIG_PATH, :blue
+        elsif (updated = with_preload(contents))
+          File.write(bunfig_full_path, updated)
+          say_status :update, BUNFIG_PATH, :green
+        else
+          say_manual_step
+        end
+      end
+
+      def report
+        say ''
+        say 'Now write a test that imports your app code, and run `bun test`:'
+        say ''
+        say '  // test/js/button.test.jsx'
+        say '  import { expect, test } from "bun:test";'
+        say '  import Button from "/app/components/button.jsx";'
+        say ''
+      end
+
+      private
+
+      # Only a real entry counts. The bare string can also appear in a commented-out line, and
+      # reporting "identical" then would silently do nothing for someone who had disabled it.
+      def already_preloaded?(contents)
+        test_table(contents).to_s.match?(/^[^#\n]*["']#{Regexp.escape(PRELOAD_ENTRY)}["']/o)
+      end
+
+      # Returns the whole file with our entry added inside the `[test]` table, or nil when that
+      # cannot be done without risking the file.
+      #
+      # Editing TOML with a regex is how this went wrong before, so the rules are narrow and each
+      # refusal falls through to printing the two lines for the user to add:
+      #
+      #   - a `preload` key outside `[test]` is left alone. It belongs to `bun run`, and appending
+      #     to it put the test preload somewhere `bun test` never reads.
+      #   - `[test]` already present without a `preload` key gets the key inserted into it. The
+      #     previous version appended a second `[test]` table, which is invalid TOML.
+      #   - an existing `[test] preload` array is extended in place, respecting a trailing comma.
+      #     Appending `, "entry"` after one produced `,\n, "entry"`, also invalid TOML.
+      def with_preload(contents)
+        table = test_table(contents)
+
+        return "#{contents.sub(/\n*\z/, "\n")}\n#{default_bunfig}" if table.nil?
+
+        if (array = table[/^[^#\n]*\bpreload\s*=\s*\[.*?\]/m])
+          extended = extend_array(array)
+          return nil if extended.nil?
+
+          # Substituted inside the table, then the table inside the document. `contents.sub(array)`
+          # replaces the FIRST occurrence of that text anywhere - so a root-level `preload` holding
+          # the same entries as `[test]`'s got edited instead, which put the harness in `bun run`,
+          # left `bun test` without it, and reported success.
+          return contents.sub(table) { table.sub(array) { extended } }
+        end
+
+        # `[test]` exists but has no preload key: put one directly under its header.
+        header = table[/\A\[test\][^\n]*\n/]
+        return nil if header.nil?
+
+        contents.sub(table) { table.sub(header, %(#{header}preload = ["#{PRELOAD_ENTRY}"]\n)) }
+      end
+
+      # The `[test]` table's text, from its header to the next table header or end of file. Nil
+      # when the file has no `[test]` table.
+      # The header line may end at EOF rather than a newline. Requiring the newline made a bunfig
+      # whose last line is `[test]` look like it had no `[test]` table at all, and the nil branch
+      # above then appended a second one - the invalid-TOML shape this rewrite exists to avoid.
+      # Matching it here instead leaves `with_preload` unable to find a header to insert under, so
+      # it refuses and prints the two lines for the user to add.
+      def test_table(contents)
+        contents[/^\[test\][^\n]*(?:\n|\z).*?(?=^\[|\z)/m]
+      end
+
+      # Adds our entry to an existing array, keeping the file's own shape. A trailing comma is
+      # respected rather than doubled - appending ", entry" after one is what produced invalid
+      # TOML before. Returns nil when the array's shape is one this cannot edit safely.
+      def extend_array(array)
+        inner = array[/\[(.*)\]/m, 1]
+        entry = %("#{PRELOAD_ENTRY}")
+
+        return array.sub(/\[\s*\]/m, "[#{entry}]") if inner.strip.empty?
+
+        # A comment after the last entry swallows the separator: the inserted `, ` lands inside
+        # `# DOM shim` and the two entries end up with no comma between them - valid input, invalid
+        # output. Putting the comma before the comment means parsing TOML comments, which is the
+        # approximation this file keeps getting punished for. Refuse and let the user do it.
+        # A comment after the last entry swallows the separator: the inserted `, ` lands inside
+        # `# DOM shim` and the two entries end up with no comma between them - valid input, invalid
+        # output. Putting the comma before the comment means parsing TOML comments, which is the
+        # approximation this file keeps getting punished for. Refuse and let the user do it.
+        return nil if inner.match?(/(?<!["'])#/)
+
+        separator = inner.rstrip.end_with?(',') ? '' : ', '
+        array.sub(/(\s*)\]\z/) { "#{separator}#{::Regexp.last_match(1)}#{entry}]" }
+      end
+
+      def say_manual_step
+        say_status :skip, BUNFIG_PATH, :yellow
+        say ''
+        say "  Could not edit #{BUNFIG_PATH} safely. Add this to it by hand:"
+        say ''
+        say '    [test]'
+        say %(    preload = ["#{PRELOAD_ENTRY}"])
+        say ''
+      end
+
+      def bunfig_full_path
+        File.expand_path(BUNFIG_PATH, destination_root)
+      end
+
+      def default_bunfig
+        <<~TOML
+          [test]
+          preload = ["#{PRELOAD_ENTRY}"]
+        TOML
+      end
+    end
+  end
+end

data/lib/generators/proscenium/bun/templates/proscenium.preload.js

@@ -0,0 +1,61 @@
+// Registers Proscenium's Bun plugin, so `bun test` can import the same JS, TS, JSX and CSS your
+// Rails app serves. Generated by `rails generate proscenium:bun`.
+//
+// Everything of substance lives in the gem, so this file should not need to change when
+// Proscenium does.
+//
+// Keep this LAST in bunfig.toml's `preload` list. The plugin claims every uncached JS module, so
+// anything that has to come from node_modules - a DOM shim, a testing library - must already be
+// imported and cached by an earlier preload, or it gets fetched from your Rails app instead.
+
+import { existsSync, mkdirSync, mkdtempSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+// Written to a file rather than read off a pipe, because a pipe cannot be relied on from here.
+// Once happy-dom's GlobalRegistrator has run and a DOM-touching package has been imported - which
+// is the normal state of a preload that comes before this one - every `Bun.spawn`/`Bun.spawnSync`
+// in the process returns a zero-length stdout: exit status 0, empty stderr, no bytes, for any
+// command at all.
+//
+// The file goes in a private directory under the app's own tmp/, beside where the daemon
+// materialises `.rjs` modules, rather than in the shared system temp dir. `mkdtemp` is what makes
+// it safe either way - the name stops being guessable and the create is exclusive by construction,
+// so nobody else on the machine can pre-place a file here and break or redirect the run - but an
+// app-private parent means there is no one else in the directory to begin with.
+mkdirSync("tmp/proscenium", { recursive: true });
+const gemDirDir = mkdtempSync(join("tmp/proscenium", "gem-dir-"));
+const gemDirFile = join(gemDirDir, "gem-dir");
+
+let gemDir = "";
+try {
+  Bun.spawnSync(["bundle", "exec", "ruby", "-e", "print Gem.loaded_specs['proscenium'].gem_dir"], {
+    stdout: Bun.file(gemDirFile),
+    stderr: "inherit",
+  });
+
+  gemDir = (await Bun.file(gemDirFile).text()).trim();
+} catch (error) {
+  // `Bun.spawnSync` throws rather than returning when the command cannot be run at all - no
+  // bundler on PATH, or not a Ruby project - and then the output file was never created, so the
+  // read throws too. Both land here so the message below is the one thing the developer sees.
+  gemDir = "";
+  if (error?.code !== "ENOENT") throw error;
+} finally {
+  rmSync(gemDirDir, { recursive: true, force: true });
+}
+
+// Checked for being a directory, not merely non-empty: bundler writes some of its own
+// diagnostics to stdout ("Could not locate Gemfile", for one), which would otherwise sail past a
+// truthiness check and fail later as an unreadable module path.
+if (!gemDir || !existsSync(gemDir) || !statSync(gemDir).isDirectory()) {
+  throw new Error(
+    "could not locate the proscenium gem. `bundle exec ruby -e \"print " +
+      "Gem.loaded_specs['proscenium'].gem_dir\"` did not name a directory" +
+      (gemDir ? ` - it produced ${JSON.stringify(gemDir.slice(0, 200))}` : " - it produced nothing") +
+      ". Is this a Rails app with proscenium in its Gemfile, and is bundler on PATH?",
+  );
+}
+
+const { register } = await import(`${gemDir}/lib/proscenium/runtime/bootstrap.js`);
+
+await register();

data/lib/proscenium/app_package.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Proscenium
+  # What the app's own package.json says that the context map needs (#154). Like ContextMap, which
+  # it reads JSON through, it loads nothing the `proscenium` CLI may not.
+  module AppPackage
+    LOCAL_SPECS = %w[link: file: workspace: portal:].freeze
+
+    module_function
+
+    # The names of the app's own `link:`, `file:` and workspace dependencies, peers included, as
+    # pnpm installs those too, and in a Bun app any workspace member it depends on by version,
+    # which Bun links. They keep their link paths once dependency contexts make other packages
+    # real-path.
+    def local_packages(root)
+      package = read(root) or return []
+
+      members = bun?(root, package) ? workspace_members(root, package['workspaces']) : []
+      %w[dependencies devDependencies optionalDependencies peerDependencies].flat_map do |field|
+        deps = package[field]
+        next [] unless deps.is_a?(Hash)
+
+        deps.select { |name, spec| spec.to_s.start_with?(*LOCAL_SPECS) || members.include?(name) }
+            .keys
+      end.uniq.sort
+    end
+
+    # Whether Bun installs the app: packageManager names it, or else its lockfile is there.
+    def bun?(root, package)
+      named = package['packageManager']
+      return named.split('@').first == 'bun' if named.is_a?(String)
+
+      %w[bun.lock bun.lockb].any? { File.exist?(File.join(root, it)) }
+    end
+
+    # The names of the packages `workspaces` (an array, or an object's `packages`) takes in, less
+    # those a `!` pattern leaves out, read as Bun's glob does: braces and `**` included.
+    def workspace_members(root, workspaces)
+      patterns = Array(workspaces.is_a?(Hash) ? workspaces['packages'] : workspaces).grep(String)
+      excluded, included = patterns.map { it.delete_prefix('./').chomp('/') }
+                                   .partition { it.start_with?('!') }
+      dirs = included.flat_map { Dir.glob(it, File::FNM_EXTGLOB, base: root) }.uniq
+      dirs.reject { |dir| excluded.any? { File.fnmatch?(it[1..], dir, File::FNM_EXTGLOB) } }
+          .filter_map { read(File.join(root, it))&.dig('name') }
+    end
+
+    # Whether package.json's text, for a file JSON.parse refuses, registers the contexts in its
+    # `workspaces`, decoding JSON's `\/` and `\uXXXX`
+    # escapes in the key and the pattern, as Bun does.
+    def workspaces?(text) = unescape(text).match?(WORKSPACES)
+
+    # JSON text with its `\uXXXX` and `\/` escapes decoded, as Bun reads them, for matching a file
+    # JSON.parse refuses.
+    # A surrogate pair is one character; a lone half, which JSON allows, becomes U+FFFD rather
+    # than raising.
+    def unescape(text)
+      text.gsub(ESCAPE) do
+        high, low, single = ::Regexp.last_match.captures
+        if high then (0x10000 + ((high.hex - 0xD800) << 10) + (low.hex - 0xDC00)).chr(Encoding::UTF_8)
+        elsif single then SURROGATES.cover?(single.hex) ? "\uFFFD" : single.hex.chr(Encoding::UTF_8)
+        else '/'
+        end
+      end
+    end
+
+    ESCAPE = %r{\\u([dD][89abAB]\h{2})\\u([dD][c-fC-F]\h{2})|\\u(\h{4})|\\/}
+    SURROGATES = (0xD800..0xDFFF)
+
+    # The pattern inside package.json's `workspaces`, an array or an object's `packages`.
+    WORKSPACES = /"workspaces"\s*:\s*(?:\{[^}]*"packages"\s*:\s*)?\[[^\]]*
+                  "\.proscenium\/packages\/\*"/x
+
+    # The manager `packageManager` names, or nil.
+    def package_manager(root)
+      field = read(root)&.dig('packageManager')
+      field.split('@').first if field.is_a?(String)
+    end
+
+    # The app's package.json as an object, or nil when it is missing or not one.
+    def read(root)
+      path = File.join(root, 'package.json')
+      package = File.exist?(path) && ContextMap.read_json(path)
+      package if package.is_a?(Hash)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end