browsable 0.1.0

data/lib/browsable/report.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Browsable
+  # The aggregated result of an audit: every Finding produced by every
+  # analyzer, plus a record of any analyzer or source that was skipped.
+  #
+  # A Report makes no decisions. It tells the user what their code requires and
+  # how that compares against their target; the formatters present it and the
+  # exit-code policy lives entirely in the caller's chosen --fail-on value.
+  class Report
+    # A skipped unit of work, e.g. { kind: :css, reason: "stylelint missing" }.
+    Skip = Data.define(:kind, :reason)
+
+    # A suggested allow_browser line that would resolve the below-target errors.
+    # `bumps` maps each raised browser to { from:, to: }.
+    Suggestion = Data.define(:line, :bumps)
+
+    attr_reader :findings, :skips, :notes, :policies, :target, :root, :config_file
+
+    # @param notes [Array<String>] caveats about the run itself (e.g. a target
+    #   that could not be inferred) — distinct from per-file findings.
+    # @param policies [Array<PolicyScanner::Policy>] every allow_browser callsite
+    #   discovered across the app's controllers — the policy landscape.
+    def initialize(findings: [], skips: [], notes: [], policies: [],
+                   target: nil, root: nil, config_file: nil)
+      @findings = findings
+      @skips = skips
+      @notes = notes
+      @policies = policies
+      @target = target
+      @root = root
+      @config_file = config_file
+    end
+
+    def errors   = findings.select(&:error?)
+    def warnings = findings.select(&:warning?)
+    def infos    = findings.select(&:info?)
+
+    def empty? = findings.empty?
+
+    # Findings grouped by file path, files sorted, findings sorted by position.
+    def findings_by_file
+      findings
+        .group_by(&:file)
+        .sort_by(&:first)
+        .to_h
+        .transform_values { |group| group.sort_by { |f| [f.line, f.column] } }
+    end
+
+    # Exit code implementing the --fail-on policy.
+    def exit_code(fail_on:)
+      case fail_on.to_s
+      when "warning"
+        errors.any? || warnings.any? ? 1 : 0
+      when "error"
+        errors.any? ? 1 : 0
+      else
+        0
+      end
+    end
+
+    # An allow_browser line that raises the offending browsers just enough to
+    # cover every below-target error, leaving the other browsers untouched.
+    #
+    # Returns nil when no error carries comparable version data — CSS/JS
+    # findings come from stylelint/eslint, which do not expose exact versions,
+    # so a suggestion can only be derived from HTML/ERB findings.
+    def suggestion
+      return @suggestion if defined?(@suggestion)
+
+      @suggestion = build_suggestion
+    end
+
+    def as_json
+      {
+        target: target&.as_json,
+        notes: notes,
+        summary: {
+          errors: errors.size,
+          warnings: warnings.size,
+          infos: infos.size,
+          files: findings_by_file.size
+        },
+        findings: findings.map(&:as_json),
+        skips: skips.map { |skip| { kind: skip.kind.to_s, reason: skip.reason } },
+        policies: policies.map { |policy| policy_as_json(policy) },
+        suggested_policy: suggestion && { line: suggestion.line, bumps: suggestion.bumps }
+      }
+    end
+
+    private
+
+    def policy_as_json(policy)
+      {
+        scope: policy.scope,
+        file: policy.file,
+        concern: policy.concern,
+        versions: policy.result.policy,
+        note: policy.result.note,
+        only: policy.only,
+        except: policy.except
+      }
+    end
+
+    def build_suggestion
+      return nil unless target
+
+      # The highest version each browser must reach to clear every error that
+      # offends it. A finding only contributes where required > current floor.
+      bumps = {}
+      errors.each do |finding|
+        finding.required_browser_versions.each do |browser, required|
+          floor = finding.target_browser_versions[browser]
+          next unless floor && newer?(required, floor)
+
+          bumps[browser] = required if bumps[browser].nil? || newer?(required, bumps[browser])
+        end
+      end
+      return nil if bumps.empty?
+
+      # Start from the current target and raise only the offending browsers.
+      versions = target.browsers.dup
+      detail = {}
+      bumps.each do |browser, raised_to|
+        detail[browser] = { from: versions[browser], to: raised_to }
+        versions[browser] = raised_to
+      end
+
+      pairs = versions.map { |browser, version| "#{browser}: #{version}" }
+      Suggestion.new(line: "allow_browser versions: { #{pairs.join(', ')} }", bumps: detail)
+    end
+
+    def newer?(left, right)
+      Gem::Version.new(left.to_s) > Gem::Version.new(right.to_s)
+    rescue ArgumentError
+      false
+    end
+  end
+end

data/lib/browsable/sources/base.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Browsable
+  module Sources
+    # Base class for a file source. A source expands a set of globs (relative
+    # to the project root) into a concrete, de-duplicated list of file paths.
+    #
+    # Sources only *discover* files — routing each file to the right analyzer
+    # is the orchestrator's job, done by extension.
+    class Base
+      attr_reader :root, :globs, :excludes
+
+      def initialize(root:, globs:, excludes: [])
+        @root = File.expand_path(root)
+        @globs = Array(globs)
+        @excludes = Array(excludes)
+      end
+
+      # A short symbol naming this source, used in reports (e.g. :stylesheets).
+      def name
+        self.class.name.split("::").last.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym
+      end
+
+      # The discovered files: existing, non-excluded, sorted, unique.
+      def files
+        globs
+          .flat_map { |glob| Dir.glob(File.join(root, glob), File::FNM_EXTGLOB) }
+          .select { |path| File.file?(path) }
+          .reject { |path| excluded?(path) }
+          .uniq
+          .sort
+      end
+
+      def any? = files.any?
+
+      private
+
+      def excluded?(path)
+        excludes.any? do |glob|
+          File.fnmatch?(File.join(root, glob), path, File::FNM_EXTGLOB | File::FNM_PATHNAME)
+        end
+      end
+    end
+  end
+end

data/lib/browsable/sources/builds.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Browsable
+  module Sources
+    # Compiled CSS under app/assets/builds — typically Tailwind output produced
+    # by the tailwindcss-rails gem. This is what Propshaft actually serves.
+    class Builds < Base
+    end
+  end
+end

data/lib/browsable/sources/importmap.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "tmpdir"
+require "digest"
+
+module Browsable
+  module Sources
+    # Resolves importmap pins to their source and makes that source available
+    # to the JavaScript analyzer.
+    #
+    # Rails importmap apps keep no node_modules: vendored JS is referenced by
+    # CDN URL in config/importmap.rb. This source reads those pins and downloads
+    # each remote file into a tmpdir so eslint can be pointed at real files.
+    #
+    # config/importmap.rb is *parsed as text*, never evaluated — running an
+    # arbitrary project file just to read string literals is not worth the risk.
+    class Importmap
+      # `pin "name", to: "url", ...` — captures the name and an optional `to:`.
+      PIN_PATTERN = /^\s*pin\s+["']([^"']+)["'](?:[^\n]*?\bto:\s*["']([^"']+)["'])?/
+
+      Pin = Data.define(:name, :url) do
+        def remote? = url&.start_with?("http://", "https://")
+      end
+
+      attr_reader :root
+
+      def initialize(root:)
+        @root = File.expand_path(root)
+      end
+
+      def importmap_path
+        File.join(root, "config/importmap.rb")
+      end
+
+      def present?
+        File.file?(importmap_path)
+      end
+
+      # All pins declared in config/importmap.rb.
+      def pins
+        return [] unless present?
+
+        File.read(importmap_path).each_line.filter_map do |line|
+          next if line.strip.start_with?("#")
+
+          m = line.match(PIN_PATTERN)
+          m && Pin.new(name: m[1], url: m[2])
+        end
+      end
+
+      # Download every remote pin into `dir` and return the local file paths.
+      #
+      # Remote fetches are skipped entirely when BROWSABLE_OFFLINE=1 — useful in
+      # CI, in air-gapped environments, or when a fast offline audit is wanted.
+      def fetch(dir: Dir.mktmpdir("browsable-importmap"))
+        return [] if ENV["BROWSABLE_OFFLINE"] == "1"
+
+        pins.select(&:remote?).filter_map do |pin|
+          download(pin, dir)
+        end
+      end
+
+      private
+
+      def download(pin, dir)
+        body = http_get(pin.url)
+        return nil unless body
+
+        filename = "#{pin.name.gsub(%r{[^\w.-]}, '_')}-#{Digest::SHA1.hexdigest(pin.url)[0, 8]}.js"
+        path = File.join(dir, filename)
+        File.write(path, body)
+        path
+      rescue StandardError
+        # A single unreachable CDN must not abort the whole audit.
+        nil
+      end
+
+      def http_get(url, redirects: 3)
+        return nil if redirects.negative?
+
+        uri = URI.parse(url)
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                                       open_timeout: 5, read_timeout: 10) do |http|
+          http.get(uri.request_uri)
+        end
+
+        case response
+        when Net::HTTPSuccess
+          response.body
+        when Net::HTTPRedirection
+          http_get(response["location"], redirects: redirects - 1)
+        end
+      end
+    end
+  end
+end

data/lib/browsable/sources/javascripts.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Browsable
+  module Sources
+    # First-party JavaScript under app/javascript (importmap-managed apps keep
+    # their own source here; pinned vendor code is handled by Sources::Importmap).
+    class Javascripts < Base
+    end
+  end
+end

data/lib/browsable/sources/public_assets.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Browsable
+  module Sources
+    # Static assets shipped verbatim from public/ (error pages, etc.).
+    class PublicAssets < Base
+    end
+  end
+end

data/lib/browsable/sources/stylesheets.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Browsable
+  module Sources
+    # Hand-written stylesheets under app/assets/stylesheets.
+    class Stylesheets < Base
+    end
+  end
+end

data/lib/browsable/sources/views.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Browsable
+  module Sources
+    # ERB templates under app/views and view components under app/components.
+    class Views < Base
+    end
+  end
+end

data/lib/browsable/target.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Browsable
+  # A browser-support target: the browsers and minimum versions the project
+  # intends to support, expressed as a browserslist query.
+  #
+  # Target resolves a query into concrete minimum versions. It prefers the
+  # `browserslist` CLI (installed alongside node) and falls back to a small
+  # built-in table when node is not available.
+  class Target
+    # Rails 8's `allow_browser versions: :modern` resolves to roughly this set.
+    # Mirrors ActionController's modern-browser baseline so browsable can read
+    # the policy without booting Rails.
+    MODERN = {
+      "chrome" => "120", "edge" => "120", "firefox" => "121",
+      "safari" => "17.2", "opera" => "106"
+    }.freeze
+
+    # browsable's built-in approximation of the browserslist `defaults` query —
+    # a frozen snapshot, used only as a last resort when the `browserslist` CLI
+    # is not installed (so live caniuse data cannot be queried) and there is no
+    # policy or explicit target. #note flags whenever this fallback is in play.
+    DEFAULTS = {
+      "chrome" => "109", "edge" => "109", "firefox" => "115", "safari" => "15.6"
+    }.freeze
+
+    # Maps browserslist's browser codes onto the names browsable reports with.
+    BROWSERSLIST_ALIASES = {
+      "ios_saf" => "safari", "and_chr" => "chrome", "and_ff" => "firefox",
+      "samsung" => "samsung", "op_mob" => "opera"
+    }.freeze
+
+    attr_reader :query
+
+    # The Rails `:modern` baseline, fully resolved.
+    def self.modern
+      new("modern", resolved: MODERN)
+    end
+
+    # Build a Target from a Rails `allow_browser versions:` argument.
+    def self.from_rails_policy(versions)
+      case versions
+      when :modern, "modern", nil
+        modern
+      when Hash
+        new("custom allow_browser policy", resolved: normalize_hash(versions))
+      else
+        # A named policy we don't special-case — treat the name as a query.
+        new(versions.to_s)
+      end
+    end
+
+    def self.normalize_hash(hash)
+      hash.each_with_object({}) do |(browser, version), out|
+        out[browser.to_s] = version.to_s
+      end
+    end
+
+    def initialize(query, resolved: nil)
+      @query = query
+      @resolved = resolved
+      # How #browsers was obtained: :explicit (a caller supplied it, e.g. a
+      # Rails policy), :browserslist (the CLI), or :builtin (the frozen table).
+      @resolved_via = resolved ? :explicit : nil
+    end
+
+    # The resolved minimum versions, e.g. { "chrome" => "120", ... }.
+    def browsers
+      @resolved ||= resolve
+    end
+
+    # The minimum supported version of a browser, or nil if untargeted.
+    def minimum_version(browser)
+      browsers[browser.to_s]
+    end
+
+    # True when `version` of `browser` falls within the target.
+    def includes?(browser, version)
+      min = minimum_version(browser)
+      return false unless min && version
+
+      Gem::Version.new(version.to_s) >= Gem::Version.new(min.to_s)
+    rescue ArgumentError
+      false
+    end
+
+    # Format the target as browserslist query fragments, e.g.
+    # ["chrome >= 120", "safari >= 17.2"]. Used to configure stylelint/eslint.
+    def to_browserslist
+      browsers.map { |browser, version| "#{browser} >= #{version}" }
+    end
+
+    def to_s = query.to_s
+
+    # How #browsers was resolved: :explicit, :browserslist, or :builtin.
+    def resolved_via
+      browsers # force resolution
+      @resolved_via
+    end
+
+    # A caveat about this target's accuracy, or nil. Set when browsable had to
+    # fall back to its built-in table instead of querying live browserslist data.
+    def note
+      return nil unless resolved_via == :builtin
+      return nil if query.to_s.strip.downcase == "modern" # the builtin :modern set is exact
+
+      "The versions above are browsable's built-in approximation — the `browserslist` " \
+        "CLI is not installed, so live browser-share data could not be queried. Install " \
+        "it (npm install -g browserslist) or set an explicit `target:` in " \
+        "config/browsable.yml for accurate, stable versions."
+    end
+
+    def as_json
+      { query: query.to_s, browsers: browsers, resolved_via: resolved_via }
+    end
+
+    private
+
+    def resolve
+      if (from_cli = from_browserslist_cli)
+        @resolved_via = :browserslist
+        from_cli
+      else
+        @resolved_via = :builtin
+        builtin_fallback
+      end
+    end
+
+    # Shell out to the `browserslist` CLI when available. It emits one
+    # "<browser> <version>" line per supported version; we keep the lowest.
+    def from_browserslist_cli
+      stdout, _stderr, status = Open3.capture3("browserslist", query.to_s)
+      return nil unless status.success?
+
+      mins = {}
+      stdout.each_line do |line|
+        code, version = line.strip.split(/\s+/, 2)
+        next unless code && version
+
+        name = BROWSERSLIST_ALIASES.fetch(code, code)
+        version = version.split("-").first # ranges like "16.0-16.3"
+        current = mins[name]
+        mins[name] = version if current.nil? || gem_version(version) < gem_version(current)
+      end
+      mins.empty? ? nil : mins
+    rescue Errno::ENOENT
+      # `browserslist` is not installed — fall back to the built-in table.
+      nil
+    end
+
+    # A deliberately small parser for the common queries browsable sees when
+    # node is absent. Full browserslist semantics live in the CLI above.
+    def builtin_fallback
+      q = query.to_s.downcase.strip
+      return MODERN.dup if q == "modern"
+      return DEFAULTS.dup if q.empty? || q.include?("defaults")
+
+      parsed = {}
+      q.split(",").each do |clause|
+        if (m = clause.strip.match(/\A(\w[\w ]*?)\s*>=\s*([\d.]+)\z/))
+          parsed[m[1].strip] = m[2]
+        end
+      end
+      parsed.empty? ? DEFAULTS.dup : parsed
+    end
+
+    def gem_version(value)
+      Gem::Version.new(value)
+    rescue ArgumentError
+      Gem::Version.new("0")
+    end
+  end
+end

data/lib/browsable/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Browsable
+  VERSION = "0.1.0"
+end

data/lib/browsable.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require_relative "browsable/version"
+
+# browsable — a Rails-aware browser-compatibility audit toolkit.
+#
+# This file boots the Zeitwerk autoloader and declares the gem's error
+# hierarchy. Every other constant under Browsable:: is autoloaded on first use.
+module Browsable
+  # Base class for every error browsable raises deliberately.
+  class Error < StandardError; end
+
+  # Raised when a required external tool (node, stylelint, ...) is missing.
+  class DependencyError < Error; end
+
+  # Raised when a config file exists but cannot be parsed or is invalid.
+  class ConfigError < Error; end
+
+  class << self
+    # The shared Zeitwerk loader. Exposed so specs (and rake) can eager-load.
+    attr_accessor :loader
+
+    # Absolute path to the gem's bundled `data/` directory.
+    def data_dir
+      File.expand_path("../data", __dir__)
+    end
+  end
+end
+
+Browsable.loader = Zeitwerk::Loader.for_gem
+Browsable.loader.inflector.inflect(
+  "cli"  => "CLI",
+  "css"  => "CSS",
+  "erb"  => "ERB",
+  "html" => "HTML"
+)
+# These files intentionally do not define a constant matching their path.
+Browsable.loader.ignore("#{__dir__}/browsable/version.rb")
+Browsable.loader.ignore("#{__dir__}/browsable/rake_tasks.rb")
+Browsable.loader.ignore("#{__dir__}/browsable/railtie.rb")
+# Rails generators are discovered and loaded by Rails itself, not Zeitwerk.
+Browsable.loader.ignore("#{__dir__}/generators")
+Browsable.loader.setup
+
+# The railtie wires rake tasks into a host Rails app. Only relevant inside Rails.
+require_relative "browsable/railtie" if defined?(Rails::Railtie)

data/lib/generators/browsable/install/install_generator.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "browsable"
+
+module Browsable
+  module Generators
+    # `rails g browsable:install` — writes a fully-commented config/browsable.yml.
+    #
+    # The generated file is a self-documenting reference: every option is
+    # present, commented out, and set to its default. browsable needs no config
+    # to run; this file exists only so overriding a default is one uncomment away.
+    class InstallGenerator < Rails::Generators::Base
+      desc "Creates a commented config/browsable.yml you can edit to override defaults."
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :minimal, type: :boolean, default: false,
+                             desc: "Write section headers only, not the full commented body"
+      class_option :target, type: :string,
+                            desc: "Pre-populate target.source: manual with this query"
+      class_option :force, type: :boolean, default: false,
+                           desc: "Overwrite an existing config/browsable.yml"
+
+      def create_config_file
+        if File.exist?(config_destination) && !options[:force]
+          say_status :skip, "config/browsable.yml already exists (pass --force to overwrite)", :yellow
+          @skipped = true
+          return
+        end
+
+        template "browsable.yml.tt", "config/browsable.yml", force: options[:force]
+      end
+
+      def print_summary
+        return if @skipped
+
+        say ""
+        say "browsable: created config/browsable.yml", :green
+        say "  Every option is commented out and set to its default — the file is", :white
+        say "  optional and exists only for overrides. Uncomment a line to change it.", :white
+        say "  Run `bundle exec browsable audit` for your first audit.", :white
+      end
+
+      private
+
+      def config_destination
+        File.join(destination_root, "config/browsable.yml")
+      end
+
+      # The following three methods are referenced as bare names by the ERB
+      # template (templates/browsable.yml.tt). They are private so Rails does
+      # not run them as generator steps.
+
+      def detected_comment
+        case allow_browser_policy
+        when nil
+          "# (No allow_browser call detected in ApplicationController.)"
+        when Hash
+          "# Detected: ApplicationController declares an explicit allow_browser versions hash."
+        else
+          "# Detected: ApplicationController uses `allow_browser versions: :#{allow_browser_policy}`"
+        end
+      end
+
+      def manual_query
+        options[:target]
+      end
+
+      def minimal
+        options[:minimal]
+      end
+
+      # Reuse the core gem's detector so the generator and the CLI agree on
+      # exactly which allow_browser forms (symbol, hash, commented-out) count.
+      def allow_browser_policy
+        return @allow_browser_policy if defined?(@allow_browser_policy)
+
+        @allow_browser_policy = Browsable::Config.load(root: destination_root).detected_policy
+      end
+    end
+  end
+end