browsable 0.1.0 → 0.2.0.pre.1

data/lib/browsable/html_extractor.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Browsable
+  # Pure-Ruby parser for a rendered HTML response. Walks the document for asset
+  # references (`<link rel="stylesheet">`, `<script src>`) and inline CSS/JS
+  # blocks, then asks the configured AssetResolver to translate each external
+  # URL into an on-disk path.
+  #
+  # This is the only HTML work the runtime middleware performs per request.
+  # No analysis happens here — that is the TestReport's job, end of suite.
+  class HtmlExtractor
+    # url           — the raw href/src as written in the HTML
+    # resolved_path — absolute on-disk path, or nil when AssetResolver missed
+    # kind          — :css or :js
+    AssetRef = Data.define(:url, :resolved_path, :kind)
+
+    # content — the textual body of an inline <style> or <script>
+    # kind    — :css or :js
+    InlineBlock = Data.define(:content, :kind)
+
+    # The aggregated extraction result returned to the middleware.
+    Extraction = Data.define(:asset_paths, :inline_blocks) do
+      # Just the resolved on-disk paths — the shape downstream callers want.
+      def resolved_paths
+        asset_paths.filter_map(&:resolved_path).uniq
+      end
+    end
+
+    EMPTY = Extraction.new(asset_paths: [], inline_blocks: []).freeze
+
+    attr_reader :html, :asset_resolver
+
+    def initialize(html, asset_resolver: nil)
+      @html = html.to_s
+      @asset_resolver = asset_resolver
+    end
+
+    # Convenience entry point used by the middleware so a single call replaces
+    # both `new(...)` and `.extract` at the call site.
+    def self.extract(html, asset_resolver: nil)
+      new(html, asset_resolver: asset_resolver).run
+    end
+
+    def run
+      return EMPTY if html.strip.empty?
+
+      doc = Nokogiri::HTML5.parse(html)
+      Extraction.new(
+        asset_paths: extract_assets(doc),
+        inline_blocks: extract_inline_blocks(doc)
+      )
+    rescue StandardError
+      EMPTY
+    end
+
+    private
+
+    def extract_assets(doc)
+      refs = []
+
+      doc.css('link[rel~="stylesheet"][href]').each do |link|
+        href = link["href"].to_s.strip
+        next if href.empty?
+
+        refs << AssetRef.new(url: href, resolved_path: resolve(href), kind: :css)
+      end
+
+      doc.css("script[src]").each do |script|
+        src = script["src"].to_s.strip
+        next if src.empty?
+
+        refs << AssetRef.new(url: src, resolved_path: resolve(src), kind: :js)
+      end
+
+      refs.uniq(&:url)
+    end
+
+    def extract_inline_blocks(doc)
+      blocks = []
+
+      doc.css("style").each do |node|
+        content = node.content.to_s
+        blocks << InlineBlock.new(content: content, kind: :css) unless content.strip.empty?
+      end
+
+      doc.css("script:not([src])").each do |node|
+        # Skip non-executable script blocks: importmaps, JSON payloads, etc. —
+        # they aren't JavaScript and eslint would choke on them.
+        next if inert_script?(node)
+
+        content = node.content.to_s
+        blocks << InlineBlock.new(content: content, kind: :js) unless content.strip.empty?
+      end
+
+      blocks
+    end
+
+    def inert_script?(node)
+      type = node["type"].to_s.downcase
+      return false if type.empty? || type == "text/javascript" || type == "module"
+      return false if type == "application/javascript"
+
+      true
+    end
+
+    def resolve(url)
+      return nil unless asset_resolver
+
+      asset_resolver.resolve(url)
+    end
+  end
+end

data/lib/browsable/middleware.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Browsable
+  # The Rack middleware behind runtime-mode auditing.
+  #
+  # Inserted by the RSpec / Minitest drivers (or manually in development), it
+  # observes each HTML response, identifies the controller#action that
+  # produced it, resolves the effective allow_browser policy for that
+  # endpoint, parses the response HTML for asset references, and records the
+  # whole tuple into the AuditLog. **No analysis happens here.**
+  #
+  # The middleware refuses to initialize in `Rails.env.production?` — runtime
+  # auditing is strictly for development and test.
+  class Middleware
+    # Paths under these prefixes are owned by Rails or Action Cable and never
+    # represent user-rendered HTML. Auditing them produces noise at best and
+    # false attributions at worst.
+    SKIP_PREFIXES = ["/rails/", "/assets/", "/packs/", "/cable", "/__"].freeze
+
+    def initialize(app, audit_log: nil, asset_resolver: nil)
+      raise Browsable::Error, "Browsable::Middleware refuses to run in production" if production?
+
+      @app = app
+      @audit_log = audit_log
+      @asset_resolver = asset_resolver
+    end
+
+    def call(env)
+      status, headers, body = @app.call(env)
+      return [status, headers, body] unless auditable?(env, status, headers)
+
+      chunks = drain(body)
+      record(env, status, headers, chunks)
+      [status, headers, replay(chunks)]
+    end
+
+    private
+
+    def production?
+      return false unless defined?(Rails) && Rails.respond_to?(:env) && Rails.env
+
+      Rails.env.production?
+    end
+
+    def auditable?(env, status, headers)
+      return false unless env["REQUEST_METHOD"] == "GET"
+      return false unless status.to_i == 200
+      return false unless html_content_type?(headers)
+      return false if skip_path?(env["PATH_INFO"].to_s)
+
+      true
+    end
+
+    def html_content_type?(headers)
+      type = content_type(headers)
+      return false unless type
+
+      type.include?("text/html")
+    end
+
+    # Rack 3 lowercases header keys; Rack 2 preserved the original case. Look
+    # both up so we work on either generation.
+    def content_type(headers)
+      headers["Content-Type"] || headers["content-type"]
+    end
+
+    def skip_path?(path)
+      SKIP_PREFIXES.any? { |prefix| path.start_with?(prefix) }
+    end
+
+    def record(env, _status, _headers, chunks)
+      controller = env["action_controller.instance"]
+      return unless controller
+      return unless controller.respond_to?(:action_name) && controller.respond_to?(:class)
+
+      action = controller.action_name.to_s
+      return if action.empty?
+
+      html = chunks.join
+      return if html.empty?
+
+      extraction = HtmlExtractor.extract(html, asset_resolver: asset_resolver)
+      policy = PolicyResolver.for(controller.class, action)
+
+      audit_log.record(
+        endpoint: "#{controller.class.name}##{action}",
+        request_path: env["PATH_INFO"].to_s,
+        policy: policy,
+        html: html,
+        asset_paths: extraction.asset_paths,
+        inline_blocks: extraction.inline_blocks
+      )
+    rescue StandardError
+      # Recording must never break the request cycle. If something failed,
+      # silently drop the entry rather than corrupt the response.
+      nil
+    end
+
+    # Rack body is an Enumerable<String>; calling .each consumes single-shot
+    # streamed bodies, so we drain into chunks once and replay below.
+    def drain(body)
+      chunks = []
+      body.each { |chunk| chunks << chunk.to_s }
+      chunks
+    ensure
+      body.close if body.respond_to?(:close)
+    end
+
+    # Reconstruct a body that downstream middleware (and the server) can
+    # iterate normally. Returning the array directly satisfies Rack's body
+    # contract.
+    def replay(chunks)
+      chunks
+    end
+
+    def audit_log
+      @audit_log ||= Browsable.audit_log
+    end
+
+    def asset_resolver
+      @asset_resolver ||= Browsable.asset_resolver
+    end
+  end
+end

data/lib/browsable/minitest.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Opt-in entry point for runtime-mode auditing inside a Minitest suite.
+#
+# Place this at the top of `test/test_helper.rb`:
+#
+#   require "browsable/minitest"
+#
+# After loading Rails. The driver inserts Browsable::Middleware into the
+# Rails app's middleware stack and uses Minitest.after_run to render the
+# report at the end of the suite.
+#
+# Customize via Browsable::Drivers::Minitest.configure:
+#
+#   Browsable::Drivers::Minitest.configure do |c|
+#     c.fail_on = :error
+#     c.format  = :github
+#   end
+require_relative "../browsable"
+
+Browsable::Drivers::Minitest.install!
+
+module Browsable
+  Minitest = Drivers::Minitest
+end

data/lib/browsable/policy.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Browsable
+  # The effective `allow_browser` policy for a specific controller#action.
+  #
+  # Policy is what runtime mode produces per response — distinct from
+  # PolicyScanner::Policy, which is a discovery record for one callsite. A
+  # Policy carries enough information to (a) build a Target against which the
+  # endpoint's assets are audited, and (b) explain *why* this is the policy in
+  # play, when the TestReport renders findings.
+  class Policy
+    attr_reader :versions, :note, :scope, :only, :except, :source
+
+    # @param versions [Hash, Symbol, nil] the resolved allow_browser argument
+    # @param note     [String, nil]       caveat when the versions could not be resolved
+    # @param scope    [String, nil]       the owning class name (nil for the fallback)
+    # @param only     [Array<String>, nil] action filter from the call
+    # @param except   [Array<String>, nil] action filter from the call
+    # @param source   [Symbol]            :controller, :ancestor, or :default
+    def initialize(versions:, note: nil, scope: nil, only: nil, except: nil, source: :controller)
+      @versions = versions
+      @note = note
+      @scope = scope
+      @only = only
+      @except = except
+      @source = source
+    end
+
+    # The Browsable::Target this policy implies. Falls back to the browserslist
+    # `defaults` query when no allow_browser versions could be resolved.
+    def target
+      return Target.from_rails_policy(versions) if versions
+
+      Target.new("defaults")
+    end
+
+    # A short human label, e.g. ":modern" or "{ chrome: 120, ... }" — used by
+    # the TestReport when it wants to print which policy applied.
+    def label
+      case versions
+      when Symbol then ":#{versions}"
+      when Hash   then "{ #{versions.map { |k, v| "#{k}: #{v}" }.join(', ')} }"
+      else            "(unresolved)"
+      end
+    end
+
+    # True when this Policy is the application-wide fallback rather than a
+    # specific allow_browser call. Distinguished so reports can say
+    # "no controller policy — audited against the project default".
+    def default? = source == :default
+
+    def as_json
+      {
+        versions: versions,
+        note: note,
+        scope: scope,
+        only: only,
+        except: except,
+        source: source.to_s
+      }
+    end
+  end
+end

data/lib/browsable/policy_resolver.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Browsable
+  # Maps a `(controller_class, action_name)` pair to the effective Browsable
+  # Policy. This is what runtime mode uses, per response, to decide which
+  # browsers an endpoint's assets must support.
+  #
+  # Resolution rules (matching Rails' own filter-callback semantics):
+  #
+  #   1. Walk the controller's ancestor chain from the most-specific class up
+  #      to ApplicationController, ignoring anonymous classes and modules.
+  #   2. For each class, look up its allow_browser callsites (PolicyScanner
+  #      data) and pick the *last* call whose `only:`/`except:` filter matches.
+  #   3. The first ancestor with a matching call wins — its last matching call
+  #      becomes the effective policy.
+  #   4. If no call matches, return the configured default Policy (the policy
+  #      from ApplicationController, falling through to the project default).
+  #
+  # The scanned policy data is built lazily on first use. Tests can call
+  # `.reset!` between examples to swap roots without process restart.
+  class PolicyResolver
+    class << self
+      # Convenience: resolve a single controller#action using the shared state.
+      def for(controller_class, action_name)
+        new(controller_class, action_name).resolve
+      end
+
+      # Inject pre-scanned data — used by drivers (which know the Rails root)
+      # and by tests (which want to bypass disk).
+      def configure(root: nil, policies: nil, default: nil)
+        @root = root
+        @policies = policies
+        @default = default
+        @lookup = nil
+      end
+
+      # Forget any cached state. Called between test files.
+      def reset!
+        @root = nil
+        @policies = nil
+        @default = nil
+        @lookup = nil
+      end
+
+      def root
+        @root ||= (defined?(Rails) && Rails.application ? Rails.root.to_s : Dir.pwd)
+      end
+
+      def policies
+        @policies ||= PolicyScanner.call(root)
+      end
+
+      def default_policy
+        @default ||= build_default_policy
+      end
+
+      # { "PostsController" => [PolicyScanner::Policy, ...] }, built once.
+      def lookup
+        @lookup ||= policies.group_by(&:scope)
+      end
+
+      private
+
+      def build_default_policy
+        config = Config.load(root: root)
+        Policy.new(
+          versions: config.detected_policy,
+          note: config.policy_note,
+          scope: nil,
+          source: :default
+        )
+      rescue StandardError
+        Policy.new(versions: nil, note: nil, scope: nil, source: :default)
+      end
+    end
+
+    attr_reader :controller_class, :action_name
+
+    def initialize(controller_class, action_name)
+      @controller_class = controller_class
+      @action_name = action_name&.to_s
+    end
+
+    def resolve
+      return self.class.default_policy if controller_class.nil? || action_name.nil? || action_name.empty?
+
+      ancestor_class_names.each do |name|
+        calls = self.class.lookup[name]
+        next unless calls && !calls.empty?
+
+        match = calls.reverse.find { |call| applies?(call) }
+        next unless match
+
+        return policy_from(match, scope: name, source: same_class?(name) ? :controller : :ancestor)
+      end
+
+      self.class.default_policy
+    end
+
+    private
+
+    # Most-specific → least-specific class names in the controller's ancestor
+    # chain. We stop at ActionController::Base / ActionController::API because
+    # nothing above is user code that could carry an allow_browser call.
+    def ancestor_class_names
+      seen = []
+      controller_class.ancestors.each do |ancestor|
+        break if action_controller_root?(ancestor)
+        next unless ancestor.is_a?(Class)
+
+        name = ancestor.name
+        next if name.nil? || name.empty?
+
+        seen << name unless seen.include?(name)
+      end
+      seen
+    end
+
+    def action_controller_root?(ancestor)
+      return false unless ancestor.is_a?(Class)
+
+      name = ancestor.name.to_s
+      name == "ActionController::Base" || name == "ActionController::API"
+    end
+
+    # Does this allow_browser call's only:/except: filter apply to our action?
+    def applies?(call)
+      return action_in?(call.only) if call.only
+      return !action_in?(call.except) if call.except
+
+      true
+    end
+
+    def action_in?(list)
+      Array(list).map(&:to_s).include?(action_name)
+    end
+
+    def same_class?(name)
+      name == controller_class.name
+    end
+
+    def policy_from(call, scope:, source:)
+      Policy.new(
+        versions: call.result.policy,
+        note: call.result.note,
+        scope: scope,
+        only: call.only,
+        except: call.except,
+        source: source
+      )
+    end
+  end
+end

data/lib/browsable/replay.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Browsable
+  # Rehydrates a JSON audit dump (the kind produced by
+  # `Browsable::TestReport#to_json`) into a Report-shaped object that any v0.1
+  # formatter can render. Used by the `browsable replay` CLI to translate
+  # a test-suite report into a different format in CI without re-running tests.
+  class Replay
+    Suggestion = Data.define(:line, :bumps)
+
+    attr_reader :data
+
+    def self.from_file(path)
+      raw = File.read(path)
+      data = JSON.parse(raw)
+      new(data)
+    end
+
+    def initialize(data)
+      @data = data
+    end
+
+    def render(format: :human, io: $stdout)
+      io.puts(formatter_for(format).new(self).render)
+    end
+
+    # ---- Report-compatible interface -----------------------------------------
+    # Browsable::Formatters::* call these on the report they're handed. We
+    # implement the same surface here so the same formatters work for replay.
+
+    def findings
+      @findings ||= Array(data["findings"]).map do |f|
+        Finding.new(
+          feature_id: f["feature_id"],
+          feature_name: f["feature_name"],
+          file: f["file"],
+          line: (f["line"] || 1).to_i,
+          column: (f["column"] || 1).to_i,
+          required_browser_versions: f["required_browser_versions"] || {},
+          target_browser_versions: f["target_browser_versions"] || {},
+          severity: (f["severity"] || "warning").to_sym,
+          message: f["message"].to_s
+        )
+      end
+    end
+
+    def errors   = findings.select(&:error?)
+    def warnings = findings.select(&:warning?)
+    def infos    = findings.select(&:info?)
+    def empty?   = findings.empty?
+
+    def findings_by_file
+      findings
+        .group_by(&:file)
+        .sort_by(&:first)
+        .to_h
+        .transform_values { |g| g.sort_by { |f| [f.line, f.column] } }
+    end
+
+    def skips
+      Array(data["skips"]).map do |skip|
+        Report::Skip.new(kind: skip["kind"].to_sym, reason: skip["reason"])
+      end
+    end
+
+    def notes      = Array(data["notes"])
+    def policies   = []
+    def root       = data.dig("target", "root") || Dir.pwd
+    def config_file = nil
+
+    def target
+      tdata = data["target"]
+      return nil unless tdata
+
+      Target.new(tdata["query"] || "replay", resolved: tdata["browsers"])
+    end
+
+    def suggestion
+      s = data["suggested_policy"]
+      return nil unless s
+
+      Suggestion.new(line: s["line"].to_s, bumps: symbolize_bumps(s["bumps"]))
+    end
+
+    def as_json = data
+
+    def exit_code(fail_on:)
+      case fail_on.to_s
+      when "warning" then errors.any? || warnings.any? ? 1 : 0
+      when "error"   then errors.any? ? 1 : 0
+      else                0
+      end
+    end
+
+    private
+
+    def symbolize_bumps(bumps)
+      return {} unless bumps.is_a?(Hash)
+
+      bumps.each_with_object({}) do |(browser, change), out|
+        out[browser] = { from: change["from"], to: change["to"] }
+      end
+    end
+
+    def formatter_for(format)
+      case format.to_sym
+      when :json   then Formatters::Json
+      when :github then Formatters::Github
+      else              Formatters::Human
+      end
+    end
+  end
+end

data/lib/browsable/rspec.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Opt-in entry point for runtime-mode auditing inside an RSpec suite.
+#
+# Place this at the top of `spec/rails_helper.rb`:
+#
+#   require "browsable/rspec"
+#
+# After loading Rails. The driver inserts Browsable::Middleware into the
+# Rails app's middleware stack (idempotent — safe to require twice) and
+# registers before(:suite) / after(:suite) hooks so the audit log is reset
+# and the report rendered automatically.
+#
+# Customize via Browsable::Drivers::RSpec.configure:
+#
+#   Browsable::Drivers::RSpec.configure do |c|
+#     c.fail_on = :error
+#     c.output  = "tmp/browsable_report.json"
+#     c.format  = :json
+#   end
+require_relative "../browsable"
+
+Browsable::Drivers::RSpec.install!
+
+# Convenience shim so `Browsable::RSpec.configure { ... }` works at top level.
+module Browsable
+  RSpec = Drivers::RSpec
+end