capybara-simulated 0.0.7 → 0.1.1

data/lib/capybara/simulated/script_cache.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+
+module Capybara
+  module Simulated
+    # Process-wide + on-disk cache of V8 `ScriptCompiler::CachedData`
+    # blobs keyed by `(version_tag, sha256(body))`. V8Runtime feeds
+    # every `__csim_runScript` body through here so the second visit
+    # (and every subsequent process) skips the parse + JIT step on
+    # large app bundles — Discourse's main chunk goes from ~140 ms of
+    # recompile per visit to a deserialize + run path.
+    #
+    # Cross-process portability requires snapshot-bytes equality:
+    # `RustyRacer::Snapshot.new(source)` is non-deterministic, so the
+    # blobs we produce here are only consumable by another process if
+    # that process loads the SAME snapshot bytes via `Snapshot.load`.
+    # `V8Runtime.build_snapshot` handles that side.
+    #
+    # **Produce path stays at top level.** `Context#compile(produce_
+    # cache: true)` is unsafe inside a host-fn callback (V8's
+    # `CreateCodeCache` corrupts the parser when re-entered — rusty_racer
+    # raises immediately). The host-fn consumer queues misses;
+    # `V8Runtime#call` drains the queue from top-level Ruby after each
+    # bridge call returns.
+    module ScriptCache
+      DEFAULT_DIR = File.join(ENV['HOME'] || '/tmp', '.cache', 'capybara-simulated', 'script-cache')
+
+      @lock     = Mutex.new
+      @mem      = {}
+      @pending  = {}
+      @writer_q = nil
+      @writer_t = nil
+
+      at_exit { ScriptCache.flush! }
+
+      class << self
+        def dir = ENV['CSIM_SCRIPT_CACHE_DIR'] || DEFAULT_DIR
+        # `V8Runtime#call` drains `warm_pending!` after EVERY host-fn call (finds,
+        # polls, dispatch), so this is one of the hottest Ruby methods — memoize
+        # the env decision instead of re-reading ENV + allocating a string per
+        # call (the var is fixed per process).
+        def enabled?
+          return @enabled unless @enabled.nil?
+          @enabled = !ENV['CSIM_SCRIPT_CACHE'].to_s.casecmp('off').zero?
+        end
+
+        def lookup(sha, version_tag, kind: :script)
+          return nil unless enabled?
+          key = cache_key(sha, version_tag, kind)
+          mem_hit = @lock.synchronize { @mem[key] }
+          return mem_hit if mem_hit
+          blob = File.binread(disk_path_for(sha, version_tag, kind)) rescue nil
+          return nil unless blob
+          @lock.synchronize { @mem[key] ||= blob }
+        end
+
+        def store(sha, version_tag, blob, kind: :script)
+          return unless enabled? && blob
+          key = cache_key(sha, version_tag, kind)
+          @lock.synchronize { @mem[key] = blob }
+          enqueue_disk_write(disk_path_for(sha, version_tag, kind), blob)
+        end
+
+        # `stale: true` = the caller HAD a blob and V8 rejected it (the
+        # snapshot bytes changed under the same version tag — a bridge edit
+        # rebuilds the snapshot, and `Snapshot.new` is non-deterministic).
+        # The rejected blob must be evicted from `@mem`, or this guard would
+        # treat it as "already cached" and skip the re-produce forever:
+        # every visit then hits the stale blob, rejects, and full-parses —
+        # a silent, permanent loss of the bytecode cache (caught 2026-06-12:
+        # 113/113 rejects on the Discourse perf sample).
+        def queue_warm(ctx, sha, label, body, version_tag, kind: :script, stale: false)
+          return unless enabled?
+          key = cache_key(sha, version_tag, kind)
+          @lock.synchronize {
+            @mem.delete(key) if stale
+            return if @mem.key?(key) || @pending.key?(key)
+            @pending[key] = {ctx: ctx, label: label, body: body, version_tag: version_tag, sha: sha, kind: kind}
+          }
+        end
+
+        def warm_pending!
+          # Fast path: `V8Runtime#call` drains here after every host-fn
+          # call (including hot polling like `__settleGenGet` /
+          # `__hasReadyTimer`), so the empty-queue branch must not pay
+          # the mutex round-trip. `@pending.empty?` lock-free read is
+          # safe — at worst a queued miss waits one extra `call`.
+          return unless enabled? && !@pending.empty?
+          pending = @lock.synchronize { p = @pending; @pending = {}; p }
+          return if pending.empty?
+          pending.each_value {|job|
+            ctx = job[:ctx]
+            next unless ctx.respond_to?(:compile)
+            begin
+              handle = if job[:kind] == :module
+                         ctx.compile_module(job[:body], filename: job[:label].to_s, produce_cache: true)
+                       else
+                         ctx.compile(job[:body], filename: job[:label].to_s, produce_cache: true)
+                       end
+              blob = handle.cached_data
+              handle.dispose
+              store(job[:sha], job[:version_tag], blob, kind: job[:kind]) if blob
+            rescue StandardError
+              # Best effort: a body that fails to produce a cache
+              # just keeps doing a parse-from-source next encounter.
+            end
+          }
+        end
+
+        def flush!
+          q = @lock.synchronize { @writer_q }
+          return unless q
+          done = Queue.new
+          q.push([:sync, done])
+          done.pop
+        end
+
+        private
+
+        def cache_key(sha, version_tag, kind = :script)
+          prefix = kind == :module ? 'm:' : ''
+          "#{version_tag}/#{prefix}#{sha}"
+        end
+
+        def disk_path_for(sha, version_tag, kind = :script)
+          prefix = kind == :module ? 'm-' : ''
+          File.join(dir, version_tag.to_s, "#{prefix}#{sha}.bin")
+        end
+
+        # Single background writer serialises disk I/O so the host-fn
+        # callback returns immediately. Parallel-worker writes to the
+        # same path are made safe by the tempfile+rename pattern.
+        def enqueue_disk_write(path, blob)
+          q = @lock.synchronize {
+            unless @writer_q
+              @writer_q = Queue.new
+              @writer_t = Thread.new { writer_loop(@writer_q) }
+              @writer_t.name = 'csim-script-cache-writer'
+            end
+            @writer_q
+          }
+          q.push([:write, path, blob])
+        end
+
+        def writer_loop(q)
+          while (job = q.pop)
+            case job[0]
+            when :write
+              _, path, blob = job
+              write_atomically(path, blob) rescue nil
+            when :sync
+              job[1].push(:done)
+            end
+          end
+        end
+
+        def write_atomically(path, blob)
+          FileUtils.mkdir_p(File.dirname(path))
+          tmp = "#{path}.#{Process.pid}.#{Thread.current.object_id}.tmp"
+          File.binwrite(tmp, blob)
+          File.rename(tmp, path)
+        end
+      end
+    end
+  end
+end

data/lib/capybara/simulated/sourcemap.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Capybara
+  module Simulated
+    # Minimal source-map v3 decoder. Just enough for the stack-trace
+    # rewriter to map `<asset URL>:<line>:<col>` back to
+    # `<source file>:<line>:<col>` so failing-test traces point at the
+    # original TS/JS instead of a 100k-char minified blob.
+    #
+    # Not handled:
+    #   - `sections` (composite maps) — Vite/Rolldown don't emit them
+    #   - `names` lookup — we don't need them for source-only resolution
+    class Sourcemap
+      Position = Struct.new(:source, :line, :column, keyword_init: true)
+
+      BASE64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+      BASE64_LOOKUP = BASE64_CHARS.each_char.with_index.to_h.freeze
+
+      def initialize(json)
+        @sources = (json['sources'] || []).map(&:to_s)
+        @source_root = json['sourceRoot'].to_s
+        @segments_by_line = parse_mappings(json['mappings'].to_s)
+      end
+
+      # Returns the nearest mapping at-or-before (line, column). Line/col
+      # are 1-based to match V8's stack-trace convention.
+      def resolve(line, column)
+        return nil if line < 1
+        row = @segments_by_line[line - 1]
+        return nil unless row && !row.empty?
+        # Per-line row is a flat Integer array of stride 4: [gen_col,
+        # source_idx, src_line, src_col, ...]. `bsearch_index` finds the
+        # first segment whose gen_col is *strictly greater* than target;
+        # the segment before that is the match.
+        target = column - 1
+        idx = (0...(row.length / 4)).bsearch {|i| row[i * 4] > target }
+        match_i = (idx || row.length / 4) - 1
+        return nil if match_i < 0
+        base = match_i * 4
+        source_idx = row[base + 1]
+        return nil unless source_idx && @sources[source_idx]
+        Position.new(
+          source: full_source(@sources[source_idx]),
+          line:   row[base + 2] + 1,
+          column: row[base + 3] + 1
+        )
+      end
+
+      private
+
+      def full_source(name)
+        return name if @source_root.empty?
+        return name if name.start_with?('/', 'http://', 'https://')
+        @source_root.end_with?('/') ? "#{@source_root}#{name}" : "#{@source_root}/#{name}"
+      end
+
+      # Decodes the `mappings` field into per-line flat Integer arrays.
+      # Each generated line's row is a stride-4 array:
+      # `[gen_col_0, source_idx_0, src_line_0, src_col_0, gen_col_1, ...]`.
+      # Flat layout cuts allocation count ~4× vs an array of 4-tuples,
+      # which matters for Vite bundles with 100k+ segments.
+      #
+      # Source-map v3 segments encode deltas against the previous segment
+      # (gen_col resets per line; the others persist across lines).
+      # Segments with fewer than 4 fields (rare — markers without source
+      # info) get sentinel `nil`s in their source slots.
+      def parse_mappings(mappings)
+        lines = mappings.split(';', -1)
+        out = Array.new(lines.length) { [] }
+        source_idx = 0
+        src_line   = 0
+        src_col    = 0
+        lines.each_with_index do |line, line_no|
+          gen_col = 0
+          row = out[line_no]
+          line.split(',').each do |seg|
+            next if seg.empty?
+            fields = decode_vlqs(seg)
+            gen_col += fields[0]
+            if fields.length >= 4
+              source_idx += fields[1]
+              src_line   += fields[2]
+              src_col    += fields[3]
+              row.push(gen_col, source_idx, src_line, src_col)
+            else
+              row.push(gen_col, nil, nil, nil)
+            end
+          end
+        end
+        out
+      end
+
+      def decode_vlqs(segment)
+        values = []
+        value  = 0
+        shift  = 0
+        segment.each_char do |c|
+          digit = BASE64_LOOKUP[c]
+          raise ArgumentError, "invalid base64 char: #{c.inspect}" unless digit
+          continuation = (digit & 0b100000) != 0
+          digit &= 0b011111
+          value |= digit << shift
+          if continuation
+            shift += 5
+          else
+            negative = (value & 1) == 1
+            value >>= 1
+            values << (negative ? -value : value)
+            value  = 0
+            shift  = 0
+          end
+        end
+        values
+      end
+    end
+  end
+end

data/lib/capybara/simulated/stack_resolver.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+
+require_relative 'sourcemap'
+
+module Capybara
+  module Simulated
+    # Annotates a V8 stack-trace string with original-source positions
+    # from each frame's `.map` companion file. Resolves once per frame,
+    # caches loaded Sourcemap objects process-wide (built bundles are
+    # fingerprinted; identical URL → identical map).
+    #
+    # Frames whose URL has no `.map` (snapshot stubs, eval'd app inline
+    # scripts) pass through unchanged.
+    class StackResolver
+      # Matches `(URL:LINE:COL)` inside V8 stack frames. URLs can contain
+      # `:` (e.g. `:port`), so the URL class includes `:` and the engine
+      # backtracks to find the trailing `:digits:digits)`. `file:` and
+      # `csim-eval:` schemes are matched too because both appear in
+      # snapshot-warmup frames where the host wraps eval'd content.
+      FRAME_RE = /\((?<url>(?:https?:\/\/|file:\/\/|csim-eval:)[^\s()]+):(?<line>\d+):(?<col>\d+)\)/
+
+      @@maps = {}
+      @@lock = Mutex.new
+
+      def initialize(browser)
+        @browser = browser
+      end
+
+      # Returns the input stack/text with `→ source:line:col` appended to
+      # every frame whose URL maps to a `.map`. If no frame resolves, the
+      # input is returned unchanged.
+      def annotate(text)
+        return text unless text.is_a?(String) && !text.empty?
+        text.gsub(FRAME_RE) {
+          m = ::Regexp.last_match
+          url  = m[:url]
+          line = m[:line].to_i
+          col  = m[:col].to_i
+          resolved = resolve(url, line, col)
+          resolved ? "#{m[0]} → #{resolved}" : m[0]
+        }
+      end
+
+      private
+
+      def resolve(url, line, col)
+        map = load_map(url)
+        return nil unless map
+        pos = map.resolve(line, col)
+        return nil unless pos
+        "#{pos.source}:#{pos.line}:#{pos.column}"
+      end
+
+      def load_map(url)
+        return @@maps[url] if @@maps.key?(url)
+        @@lock.synchronize {
+          return @@maps[url] if @@maps.key?(url)
+          @@maps[url] = build_map(url)
+        }
+      end
+
+      def build_map(url)
+        body = fetch_map_body(url)
+        return nil unless body
+        Sourcemap.new(JSON.parse(body))
+      rescue JSON::ParserError, ArgumentError
+        nil
+      end
+
+      # Tries the conventional `<url>.map` location; falls back to the
+      # inline `sourceMappingURL` directive at the bottom of the bundle
+      # if the sibling `.map` 404s. data: URLs (inline base64 maps) are
+      # also supported via `sourceMappingURL`.
+      def fetch_map_body(url)
+        body = @browser.rack_fetch_body("#{url}.map")
+        return body if body
+        bundle = @browser.rack_fetch_body(url)
+        return nil unless bundle
+        directive = bundle[/\/\/[#@]\s*sourceMappingURL=([^\s]+)\s*\z/, 1]
+        return nil unless directive
+        if directive.start_with?('data:')
+          decode_data_url(directive)
+        else
+          @browser.rack_fetch_body(@browser.resolve_against(directive, url))
+        end
+      end
+
+      def decode_data_url(uri)
+        return nil unless uri =~ %r{\Adata:application/json(?:;charset=[^;,]+)?;base64,(.+)\z}m
+        Base64.decode64(::Regexp.last_match(1))
+      end
+    end
+  end
+end

data/lib/capybara/simulated/trace.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+
+module Capybara
+  module Simulated
+    # Per-test trace of Capybara actions with DOM snapshots, console
+    # output, and network requests interleaved. JSON output, one file
+    # per test — downstream tooling builds whatever viewer it wants.
+    #
+    # Off by default. `CSIM_TRACE_DIR=/path/to/dir` enables auto-mode
+    # via `Browser#record_action`; the RSpec hook in `csim_rspec.rb`
+    # persists with a slugged filename. Programmatic activation is via
+    # `Driver#start_tracing` / `#stop_tracing`.
+    class Trace
+      Step = Struct.new(
+        :index,
+        :kind,
+        :description,
+        :url_before,
+        :url_after,
+        :dom_after,    # only the post-action snapshot — the previous step's `dom_after` is the implicit "before"
+        :console,
+        :network,
+        :elapsed_ms,
+        :duration_ms,
+        :error,
+        keyword_init: true
+      )
+
+      attr_reader :steps, :metadata
+
+      def initialize(metadata: {})
+        @steps        = []
+        @metadata     = metadata
+        @started_at   = monotonic_ms
+        @console_buf  = []
+        @network_buf  = []
+        @open_step    = nil
+      end
+
+      # Pushed from `Browser#log_console` (the JS bridge's `console.*`
+      # host-fn target) and `Browser#rack_request` (network). Entries
+      # land on the currently-open step; outside a step they're dropped
+      # (boot noise, post-test cleanup).
+      def log_console(severity, message)
+        return unless @open_step
+        @console_buf << {severity: severity.to_s, message: message.to_s}
+      end
+
+      def log_network(method, url, status)
+        return unless @open_step
+        @network_buf << {method: method.to_s, url: url.to_s, status: status}
+      end
+
+      def begin_step(kind, description:, url_before: nil)
+        finish_step if @open_step
+        @open_step = {
+          kind:        kind,
+          description: description,
+          url_before:  url_before,
+          start_ms:    monotonic_ms
+        }
+        @console_buf = []
+        @network_buf = []
+      end
+
+      def finish_step(url_after: nil, dom_after: nil, error: nil)
+        return unless @open_step
+        s = @open_step
+        @steps << Step.new(
+          index:        @steps.size,
+          kind:         s[:kind],
+          description:  s[:description],
+          url_before:   s[:url_before],
+          url_after:    url_after,
+          dom_after:    dom_after,
+          console:      @console_buf,
+          network:      @network_buf,
+          elapsed_ms:   (s[:start_ms] - @started_at).round,
+          duration_ms:  (monotonic_ms - s[:start_ms]).round,
+          error:        error
+        )
+        @open_step   = nil
+        @console_buf = []
+        @network_buf = []
+      end
+
+      def empty? = @steps.empty?
+
+      def to_h
+        {version: 1, metadata: @metadata, steps: @steps.map(&:to_h)}
+      end
+
+      def to_json(*args) = JSON.generate(to_h, *args)
+
+      def write_json(path)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, to_json)
+        path
+      end
+
+      private
+
+      def monotonic_ms
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000.0
+      end
+    end
+  end
+end