browsable 0.1.0

data/lib/browsable/finding.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Browsable
+  # A single feature-usage event discovered in the project's frontend code.
+  #
+  # A Finding records *what* feature was used, *where*, which browser versions
+  # it requires, and how that compares against the project's declared target.
+  # It is an immutable value object — analyzers produce them, formatters and
+  # the LSP server consume them.
+  Finding = Data.define(
+    :feature_id,                # e.g. "html.global_attributes.popover"
+    :feature_name,              # e.g. "popover"
+    :file,                      # absolute path
+    :line,                      # 1-based
+    :column,                    # 1-based
+    :required_browser_versions, # { "firefox" => "125", "safari" => "17" }
+    :target_browser_versions,   # { "firefox" => "121", "safari" => "17.2" }
+    :severity,                  # :error | :warning | :info
+    :message                    # human-readable explanation
+  ) do
+    def error?   = severity == :error
+    def warning? = severity == :warning
+    def info?    = severity == :info
+
+    # A stable, JSON-friendly hash. This is the wire format the JSON formatter
+    # and the LSP server both rely on.
+    def as_json
+      {
+        feature_id: feature_id,
+        feature_name: feature_name,
+        file: file,
+        line: line,
+        column: column,
+        required_browser_versions: required_browser_versions,
+        target_browser_versions: target_browser_versions,
+        severity: severity.to_s,
+        message: message
+      }
+    end
+  end
+end

data/lib/browsable/formatters/github.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Browsable
+  module Formatters
+    # Emits GitHub Actions workflow commands so findings surface as inline
+    # annotations on a pull request. See:
+    # https://docs.github.com/actions/reference/workflow-commands-for-github-actions
+    class Github
+      LEVELS = { error: "error", warning: "warning", info: "notice" }.freeze
+
+      def initialize(report)
+        @report = report
+      end
+
+      def render
+        lines = @report.findings.map { |finding| annotation(finding) }
+
+        if (suggestion = @report.suggestion)
+          lines << "::notice title=#{escape_property('browsable: suggested allow_browser')}::" \
+                   "#{escape_data(suggestion.line)}"
+        end
+
+        lines.join("\n")
+      end
+
+      private
+
+      def annotation(finding)
+        level = LEVELS.fetch(finding.severity, "warning")
+        properties = [
+          "file=#{finding.file}",
+          "line=#{finding.line}",
+          "col=#{finding.column}",
+          "title=#{escape_property("browsable: #{finding.feature_name}")}"
+        ].join(",")
+
+        "::#{level} #{properties}::#{escape_data(finding.message)}"
+      end
+
+      # GitHub requires these characters escaped within workflow commands.
+      def escape_data(value)
+        value.to_s.gsub("%", "%25").gsub("\r", "%0D").gsub("\n", "%0A")
+      end
+
+      def escape_property(value)
+        escape_data(value).gsub(":", "%3A").gsub(",", "%2C")
+      end
+    end
+  end
+end

data/lib/browsable/formatters/human.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "pastel"
+
+module Browsable
+  module Formatters
+    # Pretty terminal output: findings grouped by file, then sorted by position.
+    # File paths are emitted as OSC 8 hyperlinks so modern terminals make them
+    # clickable; colour is disabled automatically when stdout is not a TTY.
+    class Human
+      ICONS = { error: "✗", warning: "▲", info: "•" }.freeze
+
+      def initialize(report, color: $stdout.tty?)
+        @report = report
+        @pastel = Pastel.new(enabled: color)
+      end
+
+      def render
+        sections = [header, notes, body, skips, summary,
+                    controller_policies, policy_suggestion].reject(&:empty?)
+        sections.join("\n")
+      end
+
+      private
+
+      attr_reader :report, :pastel
+
+      def header
+        target = report.target
+        lines = [pastel.bold("browsable audit")]
+        if target
+          browsers = target.browsers.map { |name, version| "#{name} #{version}" }.join(", ")
+          lines << pastel.dim("target: #{target.query}  (#{browsers})")
+        end
+        lines << pastel.dim("config: #{report.config_file || 'none (no config file)'}")
+        lines.join("\n") + "\n"
+      end
+
+      # Run-level caveats — most importantly, a target that could not be
+      # inferred. Shown right under the header so the target line above makes
+      # sense.
+      def notes
+        return "" if report.notes.empty?
+
+        report.notes.map { |note| pastel.yellow("! #{note}") }.join("\n") + "\n"
+      end
+
+      def body
+        return pastel.green("✓ No browser-compatibility issues found.\n") if report.empty?
+
+        report.findings_by_file.map { |file, findings| file_section(file, findings) }.join("\n")
+      end
+
+      def file_section(file, findings)
+        lines = [pastel.underline(hyperlink(file))]
+        findings.each { |finding| lines << finding_line(finding) }
+        lines.join("\n") + "\n"
+      end
+
+      def finding_line(finding)
+        icon = colorize(finding.severity, ICONS.fetch(finding.severity, "•"))
+        location = pastel.dim("#{finding.line}:#{finding.column}")
+        feature = pastel.cyan(finding.feature_name)
+        "  #{icon} #{location}  #{feature}  #{finding.message}"
+      end
+
+      def skips
+        return "" if report.skips.empty?
+
+        lines = [pastel.yellow.bold("Skipped:")]
+        report.skips.each do |skip|
+          lines << pastel.yellow("  ! #{skip.kind}: #{skip.reason}")
+        end
+        lines.join("\n") + "\n"
+      end
+
+      def summary
+        e = report.errors.size
+        w = report.warnings.size
+        i = report.infos.size
+        parts = [
+          colorize(:error, "#{e} error#{'s' unless e == 1}"),
+          colorize(:warning, "#{w} warning#{'s' unless w == 1}"),
+          colorize(:info, "#{i} info#{'s' unless i == 1}")
+        ]
+        pastel.bold("#{parts.join('  ')}  across #{report.findings_by_file.size} file(s)") + "\n"
+      end
+
+      # A copy-pasteable allow_browser line that raises the offending browsers
+      # to the versions the flagged code requires.
+      def policy_suggestion
+        suggestion = report.suggestion
+        return "" unless suggestion
+
+        lines = [pastel.bold("Suggested allow_browser policy")]
+        lines << pastel.dim("  Raises the minimums so every permitted browser can run the flagged code:")
+        lines << ""
+        lines << "    #{pastel.cyan(suggestion.line)}"
+        lines << ""
+        suggestion.bumps.each do |browser, change|
+          lines << pastel.dim("    #{browser}: #{change[:from]} → #{change[:to]}")
+        end
+        lines << pastel.dim("  Or address it in the code instead — browsable reports, you decide.")
+        lines.join("\n") + "\n"
+      end
+
+      # The policy landscape: every allow_browser callsite found across the
+      # app's controllers. Shown only when there is more than one policy, or a
+      # policy somewhere other than ApplicationController — otherwise the
+      # `target:` line in the header already says everything.
+      def controller_policies
+        policies = report.policies
+        return "" if policies.empty?
+        return "" if policies.size == 1 && policies.first.application_controller?
+
+        lines = [pastel.bold("Browser policies (#{policies.size} allow_browser callsite(s) found)")]
+        policies.each { |policy| lines << "  #{describe_policy(policy)}" }
+        lines << ""
+        lines << pastel.dim("  The audit above ran against one target. CSS and importmap JS are served")
+        lines << pastel.dim("  globally, so a controller with a broader policy means those assets must")
+        lines << pastel.dim("  satisfy it too — re-audit with --target, or set `target:` in config, to check.")
+        lines.join("\n") + "\n"
+      end
+
+      def describe_policy(policy)
+        scope = policy.concern ? "#{policy.scope} (concern)" : policy.scope
+        scope = scope.ljust(34)
+        actions =
+          if policy.only then "  (only: #{policy.only.join(', ')})"
+          elsif policy.except then "  (except: #{policy.except.join(', ')})"
+          else ""
+          end
+        "#{scope}#{pastel.cyan(policy_versions_label(policy.result))}#{pastel.dim(actions)}"
+      end
+
+      def policy_versions_label(result)
+        if result.policy.is_a?(Hash)
+          "{ #{result.policy.map { |browser, version| "#{browser}: #{version}" }.join(', ')} }"
+        elsif result.policy
+          ":#{result.policy}"
+        else
+          result.note ? "(could not resolve)" : "(no versions:)"
+        end
+      end
+
+      def colorize(severity, text)
+        case severity
+        when :error   then pastel.red(text)
+        when :warning then pastel.yellow(text)
+        else pastel.blue(text)
+        end
+      end
+
+      # OSC 8 hyperlink — clickable in modern terminals, plain text elsewhere.
+      def hyperlink(path)
+        return path unless $stdout.tty?
+
+        "\e]8;;file://#{path}\e\\#{path}\e]8;;\e\\"
+      end
+    end
+  end
+end

data/lib/browsable/formatters/json.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Browsable
+  module Formatters
+    # Machine-readable formatter. This is the universal interface: the LSP
+    # server and any future MCP server consume exactly this structure. The
+    # human and github formatters are just alternate presentations of it.
+    class Json
+      def initialize(report)
+        @report = report
+      end
+
+      def render
+        JSON.pretty_generate(@report.as_json)
+      end
+    end
+  end
+end

data/lib/browsable/policy_detector.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Browsable
+  # Understands Rails `allow_browser` call sites.
+  #
+  # Parses controller source with Prism (no Rails boot, no eval) and resolves a
+  # call's `versions:` argument — following a constant into the same file, then
+  # across the app. It is used two ways:
+  #
+  #   * PolicyDetector.call(root) — ApplicationController's policy, which drives
+  #     the audit target (see Config).
+  #   * #scan_calls(source) — every allow_browser call in one file, for the
+  #     project-wide policy landscape (see PolicyScanner).
+  #
+  # When an argument cannot be resolved statically the Result carries a `note`
+  # instead of a policy.
+  class PolicyDetector
+    # policy: Symbol (a named policy, e.g. :modern)
+    #         | Hash ("browser" => "version")
+    #         | nil
+    # note:   why an allow_browser call could not be resolved; nil otherwise.
+    Result = Data.define(:policy, :note) do
+      def resolved? = !policy.nil?
+    end
+
+    # One allow_browser call: its resolved versions plus any only:/except: scope.
+    CallInfo = Data.define(:result, :only, :except)
+
+    # The "nothing found" result.
+    NONE = Result.new(policy: nil, note: nil)
+
+    # Where to look for a constant defined outside the file being scanned.
+    SEARCH_GLOBS = ["app/**/*.rb", "config/**/*.rb", "lib/**/*.rb"].freeze
+    MAX_SEARCH_FILES = 600
+
+    def self.call(root) = new(root).application_policy
+
+    def initialize(root)
+      @root = root
+    end
+
+    # The policy declared on ApplicationController — the app-wide audit target.
+    # When the controller has several allow_browser calls, the first wins.
+    def application_policy
+      return NONE unless File.file?(controller_path)
+
+      calls = scan_calls(File.read(controller_path))
+      calls.empty? ? NONE : calls.first.result
+    rescue StandardError => e
+      Result.new(policy: nil, note: "could not read the allow_browser policy: #{e.message}")
+    end
+
+    # Every allow_browser call in a single source file, each resolved.
+    def scan_calls(source)
+      allow_browser_calls(parse(source)).map do |call|
+        CallInfo.new(
+          result: resolve(versions_argument(call), controller_source: source),
+          only:   action_names(keyword_argument(call, :only)),
+          except: action_names(keyword_argument(call, :except))
+        )
+      end
+    rescue StandardError
+      []
+    end
+
+    private
+
+    def controller_path
+      @controller_path ||= File.join(@root, "app/controllers/application_controller.rb")
+    end
+
+    def parse(source)
+      Prism.parse(source).value
+    end
+
+    # --- locating calls and arguments ----------------------------------------
+
+    def allow_browser_calls(root_node)
+      each_node(root_node).select do |node|
+        node.is_a?(Prism::CallNode) && %i[allow_browser allow_browsers].include?(node.name)
+      end
+    end
+
+    def versions_argument(call_node)
+      keyword_argument(call_node, :versions) || positional_symbol(call_node)
+    end
+
+    # The value node of a keyword argument, e.g. `only:` in an allow_browser call.
+    def keyword_argument(call_node, name)
+      Array(call_node.arguments&.arguments).each do |arg|
+        next unless arg.is_a?(Prism::KeywordHashNode) || arg.is_a?(Prism::HashNode)
+
+        assoc = arg.elements.find do |element|
+          element.is_a?(Prism::AssocNode) && symbol_name(element.key) == name
+        end
+        return assoc.value if assoc
+      end
+      nil
+    end
+
+    def positional_symbol(call_node)
+      Array(call_node.arguments&.arguments).find { |arg| arg.is_a?(Prism::SymbolNode) }
+    end
+
+    # A `:show` or `[:show, :edit]` argument as an array of action-name strings.
+    def action_names(node)
+      case node
+      when Prism::SymbolNode
+        [node.value]
+      when Prism::ArrayNode
+        names = node.elements.filter_map { |e| e.value if e.is_a?(Prism::SymbolNode) }
+        names.empty? ? nil : names
+      end
+    end
+
+    # --- resolving the versions argument -------------------------------------
+
+    def resolve(node, controller_source:)
+      # A literal hash — possibly wrapped in .freeze/.dup — short-circuits here.
+      if (hash = hash_node(node))
+        return from_hash(hash)
+      end
+
+      case node
+      when nil
+        Result.new(policy: nil, note: "an allow_browser call was found but has no versions: argument")
+      when Prism::SymbolNode
+        Result.new(policy: node.value.to_sym, note: nil)
+      when Prism::ConstantReadNode, Prism::ConstantPathNode
+        resolve_constant(node, controller_source: controller_source)
+      else
+        Result.new(policy: nil, note: unresolved_note(describe(node)))
+      end
+    end
+
+    # The literal HashNode behind a node, unwrapping a no-argument .freeze/.dup/
+    # .clone call. Returns nil when there is no literal hash.
+    def hash_node(node)
+      case node
+      when Prism::HashNode
+        node
+      when Prism::CallNode
+        if %i[freeze dup clone].include?(node.name) && node.receiver
+          hash_node(node.receiver)
+        end
+      end
+    end
+
+    def from_hash(hash_node)
+      versions = read_versions_hash(hash_node)
+      if versions
+        Result.new(policy: versions, note: nil)
+      else
+        Result.new(policy: nil, note: "the allow_browser versions hash contained no numeric versions")
+      end
+    end
+
+    def resolve_constant(node, controller_source:)
+      name = node.name # the leaf segment, for a namespaced ConstantPathNode
+      return Result.new(policy: nil, note: unresolved_note(describe(node))) unless name
+
+      hash = find_constant_hash(controller_source, name) || search_constant(name)
+      return Result.new(policy: hash, note: nil) if hash
+
+      Result.new(
+        policy: nil,
+        note: "allow_browser references the constant #{name}, which browsable could not " \
+              "resolve to a literal versions hash. Set `target:` in config/browsable.yml " \
+              "or pass --target to be explicit."
+      )
+    end
+
+    # --- reading a versions hash ---------------------------------------------
+
+    def read_versions_hash(hash_node)
+      versions = {}
+      hash_node.elements.each do |element|
+        next unless element.is_a?(Prism::AssocNode)
+
+        browser = symbol_name(element.key)
+        version = numeric_literal(element.value)
+        # A browser mapped to false (blocked) or true (any version) has no
+        # version floor, so it is left out of the target entirely.
+        versions[browser.to_s] = version if browser && version
+      end
+      versions.empty? ? nil : versions
+    end
+
+    def numeric_literal(node)
+      node.value.to_s if node.is_a?(Prism::IntegerNode) || node.is_a?(Prism::FloatNode)
+    end
+
+    # --- constant lookup -----------------------------------------------------
+
+    def find_constant_hash(source, name)
+      write = each_node(parse(source)).find { |node| constant_write?(node, name) }
+      return nil unless write
+
+      hash = hash_node(write.value)
+      hash && read_versions_hash(hash)
+    rescue StandardError
+      nil
+    end
+
+    def constant_write?(node, name)
+      case node
+      when Prism::ConstantWriteNode
+        node.name == name
+      when Prism::ConstantPathWriteNode
+        node.target.respond_to?(:name) && node.target.name == name
+      else
+        false
+      end
+    end
+
+    # Scan the app for the constant's definition. Files are filtered by a cheap
+    # string match before the relatively expensive Prism parse.
+    def search_constant(name)
+      needle = name.to_s
+      candidate_files.each do |file|
+        text = File.read(file)
+        next unless text.include?(needle)
+
+        hash = find_constant_hash(text, name)
+        return hash if hash
+      end
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def candidate_files
+      SEARCH_GLOBS
+        .flat_map { |glob| Dir.glob(File.join(@root, glob)) }
+        .select { |path| File.file?(path) }
+        .reject { |path| path == controller_path }
+        .first(MAX_SEARCH_FILES)
+    end
+
+    # --- helpers -------------------------------------------------------------
+
+    # Depth-first enumeration of every node in a Prism tree.
+    def each_node(node, &block)
+      return enum_for(:each_node, node) unless block
+
+      return unless node.is_a?(Prism::Node)
+
+      block.call(node)
+      node.compact_child_nodes.each { |child| each_node(child, &block) }
+    end
+
+    def symbol_name(node)
+      node.is_a?(Prism::SymbolNode) ? node.value&.to_sym : nil
+    end
+
+    def describe(node)
+      node.class.name.to_s.split("::").last.sub(/Node\z/, "")
+    end
+
+    def unresolved_note(kind)
+      "allow_browser's versions: argument is a #{kind} expression that browsable cannot " \
+      "evaluate statically. Set `target:` in config/browsable.yml or pass --target."
+    end
+  end
+end

data/lib/browsable/policy_scanner.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Browsable
+  # Scans every controller and controller-concern for `allow_browser` callsites,
+  # so the report can show the full policy landscape — not just the one on
+  # ApplicationController that drives the audit target.
+  #
+  # This is deliberately *discovery only*. browsable does not try to map each
+  # frontend asset to the endpoints (and therefore policies) that serve it:
+  # CSS and importmap JavaScript are global assets, pulled in by layout helpers
+  # on essentially every page, so they have no single owning controller action.
+  # The scanner surfaces the policies; the user decides what to audit against.
+  class PolicyScanner
+    # One discovered allow_browser callsite.
+    #   scope   — the controller/concern it lives in (e.g. "Api::PostsController")
+    #   file    — path relative to the project root
+    #   result  — a PolicyDetector::Result (the resolved versions, or a note)
+    #   only    — action-name strings the policy is limited to, or nil
+    #   except  — action-name strings the policy excludes, or nil
+    #   concern — true when the callsite is in app/controllers/concerns
+    Policy = Data.define(:scope, :file, :result, :only, :except, :concern) do
+      def application_controller? = scope == "ApplicationController"
+      def scoped? = !only.nil? || !except.nil?
+    end
+
+    CONTROLLER_GLOB = "app/controllers/**/*.rb"
+
+    def self.call(root) = new(root).call
+
+    def initialize(root)
+      @root = File.expand_path(root)
+      @detector = PolicyDetector.new(@root)
+    end
+
+    # => Array<Policy>, in a stable (path-sorted) order.
+    def call
+      Dir.glob(File.join(@root, CONTROLLER_GLOB)).sort.flat_map { |file| scan_file(file) }
+    rescue StandardError
+      []
+    end
+
+    private
+
+    def scan_file(file)
+      @detector.scan_calls(File.read(file)).map do |call|
+        Policy.new(
+          scope: scope_for(file),
+          file: file.sub("#{@root}/", ""),
+          result: call.result,
+          only: call.only,
+          except: call.except,
+          concern: file.include?("/concerns/")
+        )
+      end
+    rescue StandardError
+      []
+    end
+
+    # Derive the controller/concern constant name from the file path — robust
+    # and free of AST class-name edge cases. app/controllers/api/posts_controller.rb
+    # => "Api::PostsController"; concerns/ is dropped from the name.
+    def scope_for(file)
+      relative = file.sub(%r{\A.*?app/controllers/}, "")
+                     .sub(/\.rb\z/, "")
+                     .sub(%r{\Aconcerns/}, "")
+      relative.split("/").map { |segment| camelize(segment) }.join("::")
+    end
+
+    def camelize(segment)
+      segment.split("_").map(&:capitalize).join
+    end
+  end
+end

data/lib/browsable/railtie.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Browsable
+  # Wires browsable into a host Rails application: registers the rake tasks and
+  # lets Rails discover the install generator under lib/generators.
+  #
+  # Loaded only when Rails is present (see the conditional require in
+  # lib/browsable.rb).
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("rake_tasks.rb", __dir__)
+    end
+  end
+end

data/lib/browsable/rake_tasks.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# browsable rake tasks, loaded into a host Rails app by Browsable::Railtie.
+#
+# browsable never precompiles assets on its own — `audit:fresh` is the opt-in
+# task for that. In CI, compose the pipeline explicitly:
+#   bundle exec rails assets:precompile && bundle exec browsable audit
+
+require "browsable"
+
+namespace :browsable do
+  desc "Audit the app's frontend for browser-compatibility issues"
+  task :audit do
+    Browsable::CLI.start(["audit", Rails.root.to_s])
+  end
+
+  namespace :audit do
+    desc "Precompile assets first, then audit the fresh build output"
+    task fresh: ["assets:precompile"] do
+      Browsable::CLI.start(["audit", Rails.root.to_s])
+    end
+  end
+
+  desc "Check that browsable's system dependencies are installed"
+  task :doctor do
+    Browsable::CLI.start(["doctor"])
+  end
+end