browsable 0.1.0 → 0.2.0.pre.1

data/bin/benchmark-asset-resolution

@@ -0,0 +1,91 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Measures Browsable::AssetResolver's success rate against a corpus of fixture
+# HTML files. The runtime-mode v0.2 success bar is ≥95% — this script is the
+# pre-merge guard against regressions in the resolver's heuristics.
+#
+# Usage:
+#   bin/benchmark-asset-resolution [CORPUS_DIR]
+#
+# CORPUS_DIR defaults to ./benchmark/corpus. Each subdirectory of the corpus
+# is treated as a synthetic Rails app: it should contain an `app/` (or
+# `public/`) tree mirroring an app's layout, plus a `pages/` directory of
+# representative rendered HTML responses.
+
+require_relative "../lib/browsable"
+
+DEFAULT_CORPUS = File.expand_path("../benchmark/corpus", __dir__)
+
+corpus = ARGV[0] || DEFAULT_CORPUS
+
+unless File.directory?(corpus)
+  warn "No corpus at #{corpus}. Create one under benchmark/corpus/<app-name>."
+  warn "Each subdirectory should look like a Rails app with a pages/ folder of HTML samples."
+  exit 1
+end
+
+results = { total: 0, resolved: 0, by_strategy: Hash.new(0), unresolved: [] }
+
+Dir.children(corpus).sort.each do |app_dir|
+  app_root = File.join(corpus, app_dir)
+  next unless File.directory?(app_root)
+
+  resolver = Browsable::AssetResolver.new(root: app_root)
+  pages = Dir.glob(File.join(app_root, "pages", "**/*.html"))
+
+  pages.each do |page|
+    html = File.read(page)
+    extraction = Browsable::HtmlExtractor.extract(html)
+
+    extraction.asset_paths.each do |ref|
+      results[:total] += 1
+      detailed = resolver.detailed_resolve(ref.url)
+      if detailed.resolved?
+        results[:resolved] += 1
+        results[:by_strategy][detailed.strategy] += 1
+      else
+        results[:by_strategy][detailed.strategy] += 1
+        results[:unresolved] << { app: app_dir, page: File.basename(page), url: ref.url }
+      end
+    end
+  end
+end
+
+if results[:total].zero?
+  warn "No asset references found in any page of #{corpus}."
+  exit 1
+end
+
+ratio = results[:resolved].fdiv(results[:total])
+percent = (ratio * 100).round(2)
+
+puts "Browsable asset resolver — benchmark"
+puts "------------------------------------"
+puts "Corpus:          #{corpus}"
+puts "Total refs:      #{results[:total]}"
+puts "Resolved:        #{results[:resolved]} (#{percent}%)"
+puts ""
+puts "By strategy:"
+results[:by_strategy].sort_by { |k, _| k.to_s }.each do |strategy, count|
+  puts "  #{strategy.to_s.ljust(12)} #{count}"
+end
+
+unless results[:unresolved].empty?
+  puts ""
+  puts "Unresolved (first 20):"
+  results[:unresolved].first(20).each do |miss|
+    puts "  #{miss[:app]} / #{miss[:page]}: #{miss[:url]}"
+  end
+end
+
+# Exit non-zero if below the v0.2 success bar so CI can gate the merge.
+threshold = (ENV["BROWSABLE_RESOLVER_THRESHOLD"] || "95").to_f
+if percent < threshold
+  warn ""
+  warn "BELOW THRESHOLD (#{percent}% < #{threshold}%) — fix the resolver before merging v0.2."
+  exit 1
+end
+
+puts ""
+puts "Meets the #{threshold}% bar."

data/lib/browsable/asset_resolver.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Browsable
+  # Translates an asset URL discovered in an HTML response into an on-disk file
+  # path under the Rails app. Runtime mode hands every <link> / <script src>
+  # through here so the end-of-suite analyzers can read those files directly.
+  #
+  # The resolver is intentionally conservative: it returns `nil` rather than
+  # guessing when a URL clearly belongs to a third-party CDN, when the digested
+  # filename does not map back to a real source on disk, or when the host Rails
+  # app cannot be introspected. The TestReport surfaces those misses as skipped
+  # entries — never as fabricated findings.
+  class AssetResolver
+    # The strategy used to resolve a given URL, exposed for diagnostics.
+    Result = Data.define(:path, :strategy) do
+      def resolved? = !path.nil?
+    end
+
+    DIGEST_PATTERN = /-[0-9a-f]{7,64}(?=\.\w+\z)/.freeze
+
+    DEFAULT_ROOTS = %w[
+      app/assets/stylesheets
+      app/assets/javascripts
+      app/javascript
+      app/assets/builds
+      vendor/assets/stylesheets
+      vendor/assets/javascripts
+      public
+    ].freeze
+
+    attr_reader :rails_app
+
+    def initialize(rails_app: nil, root: nil, search_roots: nil)
+      @rails_app = rails_app || (defined?(Rails) ? Rails.application : nil)
+      @root = root && File.expand_path(root)
+      @search_roots = search_roots
+    end
+
+    # Resolve a URL to an absolute on-disk path. Returns nil for URLs we cannot
+    # honestly attribute to a file in the host application.
+    def resolve(url)
+      detailed_resolve(url).path
+    end
+
+    # Same as #resolve, but returns a Result carrying which strategy matched —
+    # useful for the benchmark script and for skipped-entry diagnostics.
+    def detailed_resolve(url)
+      return Result.new(path: nil, strategy: :empty) if url.nil? || url.empty?
+
+      path = path_component(url)
+      return Result.new(path: nil, strategy: :external) if path.nil?
+
+      undigested = strip_digest(path)
+
+      if (hit = resolve_via_propshaft(undigested))
+        return Result.new(path: hit, strategy: :propshaft)
+      end
+
+      if (hit = resolve_via_sprockets(undigested))
+        return Result.new(path: hit, strategy: :sprockets)
+      end
+
+      if (hit = resolve_via_filesystem(undigested))
+        return Result.new(path: hit, strategy: :filesystem)
+      end
+
+      if (hit = resolve_via_public(undigested))
+        return Result.new(path: hit, strategy: :public)
+      end
+
+      Result.new(path: nil, strategy: :unresolved)
+    end
+
+    private
+
+    # Reduce a URL to its path component. Returns nil for absolute URLs whose
+    # host does not match the application's configured asset host — those are
+    # treated as external (CDN-hosted) and skipped.
+    #
+    # TODO(v0.2.1): handle CDN-hosted absolute URLs that *do* match
+    # `config.asset_host`, including digest-only URLs (e.g. a CloudFront prefix
+    # that retains the same path layout the Rails app uses).
+    def path_component(url)
+      uri = URI.parse(url)
+      return nil if uri.scheme == "data" || uri.scheme == "javascript"
+
+      if uri.absolute?
+        return nil unless matches_asset_host?(uri)
+
+        uri.path
+      else
+        uri.path
+      end
+    rescue URI::InvalidURIError
+      url.split("?", 2).first
+    end
+
+    def matches_asset_host?(uri)
+      hosts = configured_asset_hosts
+      return false if hosts.empty?
+
+      hosts.any? { |host| host == uri.host || (host.respond_to?(:include?) && host.include?(uri.host.to_s)) }
+    end
+
+    def configured_asset_hosts
+      return [] unless rails_app
+
+      asset_host = rails_app.config.action_controller.asset_host rescue nil
+      Array(asset_host).compact.map do |entry|
+        URI.parse(entry).host || entry rescue entry
+      end
+    end
+
+    def strip_digest(path)
+      path.sub(DIGEST_PATTERN, "")
+    end
+
+    # --- Propshaft (Rails 7+ default) ---------------------------------------
+
+    def resolve_via_propshaft(path)
+      return nil unless rails_app
+      return nil unless rails_app.respond_to?(:assets)
+
+      assets = rails_app.assets
+      return nil unless assets.respond_to?(:resolver)
+
+      logical = path.sub(%r{\A/assets/}, "").sub(%r{\A/}, "")
+      asset = assets.resolver.asset_for(logical) rescue nil
+      return nil unless asset
+
+      candidate = asset.respond_to?(:path) ? asset.path.to_s : nil
+      return nil unless candidate && File.file?(candidate)
+
+      candidate
+    rescue StandardError
+      nil
+    end
+
+    # --- Sprockets fallback --------------------------------------------------
+
+    def resolve_via_sprockets(path)
+      return nil unless rails_app
+      assets = rails_app.config.assets rescue nil
+      return nil unless assets
+
+      paths = Array(assets.respond_to?(:paths) ? assets.paths : nil)
+      return nil if paths.empty?
+
+      logical = path.sub(%r{\A/assets/}, "").sub(%r{\A/}, "")
+      paths.each do |asset_root|
+        candidate = File.expand_path(logical, asset_root.to_s)
+        return candidate if File.file?(candidate)
+      end
+      nil
+    rescue StandardError
+      nil
+    end
+
+    # --- Filesystem walk -----------------------------------------------------
+
+    # Many Rails apps emit `<script src="/application-abc123.js">` (jsbundling)
+    # or `<link href="/application.css">` (cssbundling). Neither Propshaft nor
+    # Sprockets owns those — they live under app/assets/builds and public/.
+    def resolve_via_filesystem(path)
+      basename = File.basename(path)
+      return nil if basename.empty? || basename == "/"
+
+      app_root = root
+      return nil unless app_root
+
+      search_roots.each do |root_segment|
+        absolute = File.join(app_root, root_segment, basename)
+        return absolute if File.file?(absolute)
+      end
+      nil
+    end
+
+    # As a last resort try the URL path verbatim under public/, where Rails
+    # serves precompiled assets and any static file mounted with sendfile.
+    def resolve_via_public(path)
+      app_root = root
+      return nil unless app_root
+
+      candidate = File.join(app_root, "public", path.sub(%r{\A/}, ""))
+      return candidate if File.file?(candidate)
+
+      nil
+    end
+
+    def root
+      @root || (rails_app.respond_to?(:root) ? rails_app.root.to_s : nil)
+    end
+
+    def search_roots
+      @search_roots ||= DEFAULT_ROOTS
+    end
+  end
+end

data/lib/browsable/audit_log.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "concurrent"
+require "set"
+
+module Browsable
+  # Thread-safe, in-memory accumulator for responses observed by the runtime
+  # middleware. Recording is per-request; analysis is one-shot at suite end.
+  #
+  # A single global instance lives at `Browsable.audit_log`. Tests can replace
+  # it (or call `#clear`) for isolation. Nothing in this class invokes an
+  # analyzer — recording must be cheap and side-effect-free.
+  class AuditLog
+    # One observed response.
+    #
+    #   endpoint     "PostsController#show"
+    #   request_path "/posts/42"
+    #   policy       Browsable::Policy (the effective policy for this endpoint)
+    #   html         the rendered response body as a String
+    #   asset_paths  Array<HtmlExtractor::AssetRef>
+    #   inline_blocks Array<HtmlExtractor::InlineBlock>
+    #   recorded_at  Time (used for debugging only, not analysis)
+    Entry = Data.define(
+      :endpoint, :request_path, :policy, :html,
+      :asset_paths, :inline_blocks, :recorded_at
+    )
+
+    def initialize
+      @entries = Concurrent::Array.new
+    end
+
+    def record(endpoint:, request_path:, policy:, html:, asset_paths:, inline_blocks:)
+      @entries << Entry.new(
+        endpoint: endpoint,
+        request_path: request_path,
+        policy: policy,
+        html: html,
+        asset_paths: asset_paths,
+        inline_blocks: inline_blocks,
+        recorded_at: Time.now
+      )
+    end
+
+    def entries
+      @entries.to_a
+    end
+
+    def empty?
+      @entries.empty?
+    end
+
+    def size
+      @entries.size
+    end
+
+    # The deduplicated union of every resolved asset path seen across all
+    # entries — what TestReport hands to stylelint and eslint in one go.
+    def asset_path_universe
+      paths = Set.new
+      @entries.each do |entry|
+        entry.asset_paths.each do |ref|
+          paths << ref.resolved_path if ref.resolved_path
+        end
+      end
+      paths
+    end
+
+    # Every entry whose response loaded the given asset path. Used to attribute
+    # an end-of-suite finding back to the endpoints that triggered it.
+    def entries_loading(asset_path)
+      @entries.select do |entry|
+        entry.asset_paths.any? { |ref| ref.resolved_path == asset_path }
+      end
+    end
+
+    def clear
+      @entries.clear
+    end
+  end
+
+  class << self
+    def audit_log
+      @audit_log ||= AuditLog.new
+    end
+
+    # Tests / drivers can install their own instance.
+    attr_writer :audit_log
+
+    # The shared AssetResolver. Lazily constructed against the current Rails
+    # app the first time it's asked for.
+    def asset_resolver
+      @asset_resolver ||= AssetResolver.new
+    end
+
+    attr_writer :asset_resolver
+  end
+end

data/lib/browsable/cli.rb

@@ -137,6 +137,30 @@ module Browsable
       end
     end
 
+    desc "replay PATH", "Reformat a JSON audit dump from a previous test-suite run"
+    long_desc <<~DESC
+      Reads the JSON produced by `Browsable::TestReport#to_json` (runtime mode)
+      or `--json` (static mode) and re-renders it through any formatter. Handy
+      for emitting GitHub annotations in CI from a saved test-suite dump.
+    DESC
+    option :"fail-on", type: :string, enum: %w[warning error never], default: "error"
+    def replay(path)
+      abort_with("Cannot read #{path}: not a file") unless File.file?(path)
+
+      replay = Replay.from_file(path)
+      formatter = case (options[:format] || (options[:json] ? "json" : "human"))
+                  when "json"   then Formatters::Json
+                  when "github" then Formatters::Github
+                  else               Formatters::Human
+                  end
+      puts formatter.new(replay).render
+
+      fail_on = options["fail-on"] || "error"
+      exit(fail_on == "never" ? 0 : replay.exit_code(fail_on: fail_on))
+    rescue JSON::ParserError => e
+      abort_with("#{path} is not valid JSON: #{e.message}")
+    end
+
     desc "version", "Print the browsable version"
     def version
       puts "browsable #{Browsable::VERSION}"

data/lib/browsable/drivers/minitest.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Browsable
+  module Drivers
+    # The Minitest driver — activated by `require "browsable/minitest"`.
+    #
+    # Mirrors the RSpec driver: insert the middleware, clear the audit log on
+    # boot, render the TestReport once Minitest finishes. Uses
+    # `Minitest.after_run` for end-of-suite reporting.
+    class Minitest
+      DEFAULTS = {
+        fail_on: :error,
+        format: :human,
+        output: :stdout,
+        enabled: true
+      }.freeze
+
+      class Configuration
+        attr_accessor :fail_on, :format, :output, :enabled
+
+        def initialize
+          DEFAULTS.each { |key, value| public_send("#{key}=", value) }
+        end
+      end
+
+      class << self
+        def configuration
+          @configuration ||= Configuration.new
+        end
+
+        def configure
+          yield configuration
+        end
+
+        def reset!
+          @configuration = nil
+        end
+
+        def install!
+          require "minitest"
+          ensure_rails!
+          insert_middleware
+          Browsable.audit_log.clear
+          ::Minitest.after_run { Browsable::Drivers::Minitest.after_run }
+        end
+
+        def rails_application
+          return nil unless defined?(::Rails)
+
+          ::Rails.application
+        end
+
+        def after_run
+          return unless configuration.enabled
+          return if Browsable.audit_log.empty?
+
+          report = Browsable::TestReport.new
+          emit(report)
+          report.fail_suite_if_errors!(fail_on: configuration.fail_on) unless configuration.fail_on == :never
+        end
+
+        private
+
+        def ensure_rails!
+          return if defined?(::Rails) && rails_application
+
+          raise Browsable::Error,
+                "browsable/minitest requires a Rails application — load it after Rails is initialized."
+        end
+
+        def insert_middleware
+          app = rails_application
+          return unless app
+
+          stack = app.config.middleware
+          return if middleware_present?(stack)
+
+          stack.use(Browsable::Middleware)
+        end
+
+        def middleware_present?(stack)
+          stack.respond_to?(:include?) && stack.include?(Browsable::Middleware)
+        rescue StandardError
+          false
+        end
+
+        def emit(report)
+          rendered = report.render(format: configuration.format)
+          target = configuration.output
+          case target
+          when :stdout then $stdout.puts(rendered)
+          when :stderr then $stderr.puts(rendered)
+          when IO, StringIO then target.puts(rendered)
+          else File.write(target.to_s, rendered)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/browsable/drivers/rspec.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Browsable
+  module Drivers
+    # The RSpec driver — activated by `require "browsable/rspec"`.
+    #
+    # On load it (a) verifies a Rails app is reachable, (b) inserts the
+    # runtime middleware idempotently, and (c) registers before(:suite) /
+    # after(:suite) hooks so the audit log is cleared and the report rendered
+    # automatically without per-spec boilerplate.
+    class RSpec
+      DEFAULTS = {
+        fail_on: :error,        # :error | :warning | :never
+        format: :human,         # :human | :json | :github
+        output: :stdout,        # :stdout | :stderr | "path/to/file"
+        enabled: true
+      }.freeze
+
+      class Configuration
+        attr_accessor :fail_on, :format, :output, :enabled
+
+        def initialize
+          DEFAULTS.each { |key, value| public_send("#{key}=", value) }
+        end
+      end
+
+      class << self
+        def configuration
+          @configuration ||= Configuration.new
+        end
+
+        def configure
+          yield configuration
+        end
+
+        def reset!
+          @configuration = nil
+        end
+
+        # Wire the middleware and RSpec hooks. Called once when the entry-point
+        # file is required.
+        def install!
+          require "rspec/core"
+          ensure_rails!
+          insert_middleware
+          register_hooks
+        end
+
+        # The Rails app whose middleware stack we mutate. Extracted so tests
+        # can stub the lookup.
+        def rails_application
+          return nil unless defined?(::Rails)
+
+          ::Rails.application
+        end
+
+        private
+
+        def ensure_rails!
+          return if defined?(::Rails) && rails_application
+
+          raise Browsable::Error,
+                "browsable/rspec requires a Rails application — load it after Rails is initialized."
+        end
+
+        def insert_middleware
+          app = rails_application
+          return unless app
+
+          stack = app.config.middleware
+          return if middleware_present?(stack)
+
+          stack.use(Browsable::Middleware)
+        end
+
+        def middleware_present?(stack)
+          stack.respond_to?(:include?) && stack.include?(Browsable::Middleware)
+        rescue StandardError
+          false
+        end
+
+        def register_hooks
+          ::RSpec.configure do |c|
+            c.before(:suite) { Browsable::Drivers::RSpec.before_suite }
+            c.after(:suite)  { Browsable::Drivers::RSpec.after_suite }
+          end
+        end
+
+        public
+
+        def before_suite
+          Browsable.audit_log.clear
+        end
+
+        def after_suite
+          return unless configuration.enabled
+          return if Browsable.audit_log.empty?
+
+          report = Browsable::TestReport.new
+          emit(report)
+          report.fail_suite_if_errors!(fail_on: configuration.fail_on) unless configuration.fail_on == :never
+        end
+
+        def emit(report)
+          rendered = report.render(format: configuration.format)
+          target = configuration.output
+          case target
+          when :stdout then $stdout.puts(rendered)
+          when :stderr then $stderr.puts(rendered)
+          when IO, StringIO then target.puts(rendered)
+          else File.write(target.to_s, rendered)
+          end
+        end
+      end
+    end
+  end
+end