browsable 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5cc4db4361dc825b6a61dc6cca4fcefd98e8583e0f2962b9e365fdc41344100
-  data.tar.gz: a4fe3eff5c21e781e2fe707147cb0c614b2c7a4a93947c21b8dd36ce06eaf9b0
+  metadata.gz: e0e36477f3fd4bb8e494212d0bc76eb3b9bd7ec96fcb51af0e3e4e8df04e9428
+  data.tar.gz: 5f25664cd5d1e76644d77952844559de5ed95407d2d73e5a2ce2e9a8e18b9e22
 SHA512:
-  metadata.gz: 237fb7ab7d9218781175c9a0f3cd3d4389da33256b91b58d16bd38ddc52a8019de9d2e85553991b47672300f0c66745a3502725b2fec2052f3388133271998f6
-  data.tar.gz: 33e9031f23d9d7acfa1fcea3d92be4664f1335229257495504f688ed86361a2659c15a05d65527185e9da54020fbb30969152f7540b7cc0d4a33415a473e3d63
+  metadata.gz: 8d1cb051b2e1c9e16f4dc56af0d76bf51d883860676f0877057a746a3029ff4ba8173f19b3f9d597171aa3541294ac05a96bd0807dc65eeedcd72def9e29c42b
+  data.tar.gz: dc5143e15d4dc5c17e2b1ecaa715b6413272df5bbb3e792ffafd90f6ff69696c599992f3cdbb62515afc6adc5567cd9d9b067112bd7292ddd15a7a9dcadb4ec6

data/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to the `browsable` gem are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-05-25
+
+### Added — Sprockets asset-pipeline support
+
+- **Pipeline detection (`Browsable::AssetPipeline`).** Identifies whether the
+  project uses Propshaft, Sprockets, both, or neither. Surfaces the name in the
+  audit header (`pipeline: sprockets`) and as a top-level field in `--json`
+  output (`"pipeline": "sprockets"`). Live `defined?` checks win when available;
+  otherwise the `Gemfile.lock` is the fallback.
+- **Sprockets-layout JS discovery.** Default JS globs now include
+  `app/assets/javascripts/**/*.{js,mjs}` alongside the Propshaft/importmap
+  `app/javascript/**`. Sprockets directives (`//= require`, `*= require_tree`)
+  live inside comments and are passed through untouched — no preprocessing.
+- **SCSS routing.** `.scss` and `.sass` are discovered and routed to stylelint
+  with `--customSyntax postcss-scss` when any are present.
+- **`postcss-scss` in `doctor`.** Listed as an optional dependency, only flagged
+  as missing when the project actually has SCSS files on disk.
+- **`examples/sprockets_app`.** New fixture mirroring `examples/rails_app` with
+  the Sprockets layout.
+
 ## [0.2.0] - 2026-05-25
 
 ### Added — Runtime response auditing

data/README.md

@@ -31,6 +31,7 @@ The name is a play on Rails 8's `allow_browser` controller API. Instead of *decl
 - [CLI reference](#cli-reference)
 - [Configuration](#configuration)
 - [How it works](#how-it-works)
+- [Asset pipelines](#asset-pipelines)
 - [Runtime auditing (test-suite mode)](#runtime-auditing-test-suite-mode)
 - [Per-controller policies](#per-controller-and-per-action-policies)
 - [Suggested policy fixes](#suggested-allow_browser-fix)
@@ -115,6 +116,7 @@ Browsable shells out to a few external tools that live globally on your machine:
 | `node` | JavaScript runtime for `stylelint` & `eslint` | Yes |
 | `stylelint` | CSS compatibility analysis | Yes (CSS audits) |
 | `eslint` + `eslint-plugin-compat` | JavaScript compatibility analysis | Yes (JS audits) |
+| `postcss-scss` | Lets `stylelint` parse SCSS sources | Optional (SCSS audits only) |
 | `browserslist` | Live resolution of `defaults` queries | Optional |
 | `herb` | ERB parsing | Bundled (gem dep) |
 
@@ -256,6 +258,37 @@ It's a suggestion, not an instruction. Tightening the policy is one fix; changin
 
 The suggestion is derived from HTML/ERB findings, which carry exact version data. It also appears in `--json` output as `suggested_policy` and as a GitHub Actions notice.
 
+## Asset pipelines
+
+Browsable's audit pipeline (sources → analyzers → report) is **pipeline-agnostic**: the analyzers don't care how Rails assembles your assets. Only the static-mode source-discovery layer needs to know where to look.
+
+| Pipeline | Static-mode support | What gets discovered |
+| --- | --- | --- |
+| **Propshaft** *(primary target)* | Full | `app/javascript/**`, `app/assets/stylesheets/**`, `app/assets/builds/**`, importmap pins |
+| **Sprockets** | Full | `app/assets/javascripts/**`, `app/assets/stylesheets/**` (incl. `.scss`) |
+| **Both (migration)** | Full — Sprockets discovery wins | Superset of both layouts |
+| **Neither** | Best-effort | Whatever the default globs find on disk |
+
+The detected pipeline appears in the audit header (e.g. `pipeline: sprockets`) and as a top-level field in `--json` output (`"pipeline": "sprockets"`). Detection prefers a live `defined?(Sprockets)` / `defined?(Propshaft)` check (set by the railtie inside a Rails process) and falls back to your `Gemfile.lock` for standalone CLI runs.
+
+### SCSS audits
+
+SCSS files (`.scss`) are routed to stylelint with `--customSyntax postcss-scss`. Install the parser globally:
+
+```bash
+npm install -g postcss-scss
+```
+
+`browsable doctor` flags `postcss-scss` as missing **only when** the project actually has SCSS files. Without it, SCSS files are still analyzed — but as plain CSS, so SCSS-specific syntax (nested selectors, variables) may produce parse warnings.
+
+### What is not analyzed
+
+- **CoffeeScript** (`*.coffee`) — no static-mode support.
+- **ERB-templated JS/CSS** (`*.js.erb`, `*.css.erb`) — only the literal source is read; the ERB is not expanded.
+- **Indented Sass** (`*.sass`) — discovered, but `postcss-scss` parses braced SCSS, not the indented dialect.
+
+These are documented limitations of static mode. **Runtime mode** (below) sidesteps them entirely by reading the HTML, CSS, and JS that Rails actually renders during a test run — so any pipeline, preprocessor, or templating that ends up serving real content is covered.
+
 ## Runtime auditing (test-suite mode)
 
 Static mode answers the question *“does my codebase satisfy a single browser-support target?”*. Runtime mode answers a sharper one: *“for every endpoint in my app, does the HTML it actually renders satisfy that endpoint's policy?”* It does this without trying to build a static asset → endpoint graph — instead, it lets Rails itself say what each endpoint renders during a test run, and audits *that*.

data/lib/browsable/analyzers/css.rb

@@ -10,13 +10,26 @@ module Browsable
     # project's target. browsable supplies the config; stylelint (and its
     # bundled caniuse data) does the actual compatibility reasoning.
     class CSS < Base
+      # Extensions that stylelint cannot parse with its default PostCSS
+      # syntax. We route them through postcss-scss when any are present.
+      SCSS_EXTENSIONS = %w[.scss .sass].freeze
+
+      def self.scss_like?(file)
+        SCSS_EXTENSIONS.include?(File.extname(file).downcase)
+      end
+
       def required_tools = ["stylelint"]
 
       def analyze(files)
         return [] if files.empty?
 
         argv = ["stylelint", "--config", write_stylelintrc,
-                "--formatter", "json", *files]
+                "--formatter", "json"]
+        # SCSS is a strict superset of CSS for the constructs we audit; running
+        # plain .css through postcss-scss is safe, so one invocation covers
+        # mixed inputs as long as any SCSS-like file is present.
+        argv.push("--customSyntax", "postcss-scss") if files.any? { |f| self.class.scss_like?(f) }
+        argv.concat(files)
         parse(shell_out(argv, dry_run_key: "BROWSABLE_DRY_RUN_CSS"))
       end
 

data/lib/browsable/asset_pipeline.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Browsable
+  # Identifies which Rails asset pipeline (Propshaft, Sprockets, both, or
+  # neither) is in use for a project. Reported in the audit header so the user
+  # sees at a glance which pipeline browsable inferred — and surfaced in the
+  # JSON output so editor integrations and CI can branch on it.
+  #
+  # Detection prefers a live `defined?` check (set when running inside the host
+  # Rails process, e.g. via the railtie or a rake task). Standalone CLI runs
+  # never load the host app, so the fallback inspects the project's
+  # Gemfile.lock — the canonical record of which asset-pipeline gem the app
+  # actually uses.
+  class AssetPipeline
+    PROPSHAFT = "propshaft"
+    SPROCKETS = "sprockets"
+    BOTH      = "sprockets+propshaft"
+    NONE      = "none"
+
+    # Build a pipeline descriptor for the project at `root`.
+    def self.detect(root:)
+      new(root: root)
+    end
+
+    attr_reader :root
+
+    def initialize(root:)
+      @root = File.expand_path(root)
+    end
+
+    # One of PROPSHAFT, SPROCKETS, BOTH, NONE.
+    def name
+      @name ||= identify
+    end
+
+    def propshaft? = name == PROPSHAFT || name == BOTH
+    def sprockets? = name == SPROCKETS || name == BOTH
+    def none?      = name == NONE
+
+    # When both pipelines are loaded (typical during a Propshaft migration),
+    # prefer Sprockets-style discovery — its source tree is the broader
+    # superset, so its globs match everything Propshaft would have found too.
+    def prefer_sprockets_layout? = sprockets?
+
+    private
+
+    def identify
+      live_propshaft = defined?(::Propshaft) ? true : false
+      live_sprockets = defined?(::Sprockets) ? true : false
+
+      # Live `defined?` is authoritative — the host app actually loaded these.
+      return BOTH      if live_propshaft && live_sprockets
+      return PROPSHAFT if live_propshaft
+      return SPROCKETS if live_sprockets
+
+      # Standalone CLI mode: fall back to what the Gemfile.lock declares.
+      lock_propshaft = gemfile_lock_mentions?("propshaft")
+      lock_sprockets = gemfile_lock_mentions?("sprockets-rails") ||
+                       gemfile_lock_mentions?("sprockets")
+
+      return BOTH      if lock_propshaft && lock_sprockets
+      return PROPSHAFT if lock_propshaft
+      return SPROCKETS if lock_sprockets
+
+      NONE
+    end
+
+    def gemfile_lock_mentions?(gem_name)
+      path = File.join(root, "Gemfile.lock")
+      return false unless File.file?(path)
+
+      # `bundle` indents direct gem entries with four spaces; transitive deps
+      # appear under DEPENDENCIES with two. Either form counts as "in use".
+      File.read(path).match?(/^\s+#{Regexp.escape(gem_name)}\b/)
+    end
+  end
+end

data/lib/browsable/cli.rb

@@ -61,7 +61,7 @@ module Browsable
     option :fix, type: :boolean, default: false,
                  desc: "Attempt to install missing dependencies via brew/npm"
     def doctor
-      doc = Doctor.new
+      doc = Doctor.new(root: Dir.pwd)
       puts doc.render(color: color?)
 
       if options[:fix] && !doc.ok?
@@ -172,12 +172,15 @@ module Browsable
     # --- pipeline ------------------------------------------------------------
 
     def run_audit(root:, config:, target:, file_list: nil)
-      available = Doctor.new.available_kinds
+      doctor = Doctor.new(root: root)
+      available = doctor.available_kinds
       skips = []
       files_by_kind = file_list ? route_files(file_list) : discover_files(root: root, config: config)
 
       collect_importmap(root: root, config: config, files_by_kind: files_by_kind, skips: skips) if file_list.nil?
 
+      check_scss_tooling!(doctor: doctor, files_by_kind: files_by_kind, skips: skips)
+
       findings = []
       ANALYZERS.each do |kind, analyzer_class|
         files = files_by_kind[kind] || []
@@ -212,7 +215,22 @@ module Browsable
       policies = file_list ? [] : PolicyScanner.call(root)
 
       Report.new(findings: findings, skips: skips, notes: notes, policies: policies,
-                 target: target, root: root, config_file: config.config_file)
+                 target: target, root: root, config_file: config.config_file,
+                 pipeline: AssetPipeline.detect(root: root).name)
+    end
+
+    # Warn (and skip the SCSS subset) when SCSS files were discovered but
+    # postcss-scss — the syntax stylelint needs to parse them — is missing.
+    def check_scss_tooling!(doctor:, files_by_kind:, skips:)
+      css_files = files_by_kind[:css] || []
+      return unless css_files.any? { |file| Analyzers::CSS.scss_like?(file) }
+      return if doctor.postcss_scss_installed?
+
+      skips << Report::Skip.new(
+        kind: :scss,
+        reason: "postcss-scss not found — SCSS files will be analyzed as plain CSS. " \
+                "Run `browsable doctor` for setup instructions."
+      )
     end
 
     def collect_importmap(root:, config:, files_by_kind:, skips:)
@@ -253,10 +271,10 @@ module Browsable
       buckets = { css: [], erb: [], html: [], js: [] }
       files.each do |file|
         case File.extname(file).downcase
-        when ".css", ".scss" then buckets[:css] << file
-        when ".js", ".mjs"   then buckets[:js] << file
-        when ".erb"          then buckets[:erb] << file
-        when ".html", ".htm" then buckets[:html] << file
+        when ".css", ".scss", ".sass" then buckets[:css] << file
+        when ".js", ".mjs"            then buckets[:js] << file
+        when ".erb"                   then buckets[:erb] << file
+        when ".html", ".htm"          then buckets[:html] << file
         end
         # TODO(v0.2): route Ruby view components (app/components/**/*.rb).
       end

data/lib/browsable/config.rb

@@ -20,11 +20,16 @@ module Browsable
         "manual_query" => "defaults"
       },
       "sources" => {
-        "stylesheets" => ["app/assets/stylesheets/**/*.{css,scss}"],
+        "stylesheets" => ["app/assets/stylesheets/**/*.{css,scss,sass}"],
         "builds"      => ["app/assets/builds/**/*.css"],
         "views"       => ["app/views/**/*.{html.erb,turbo_stream.erb}",
                           "app/components/**/*.{rb,html.erb}"],
-        "javascript"  => ["app/javascript/**/*.{js,mjs}"],
+        # `app/javascript` is the Propshaft/importmap convention;
+        # `app/assets/javascripts` is the Sprockets convention. Globbing both
+        # is harmless on a Propshaft-only app (no files match) and lets the
+        # CLI work on Sprockets apps with zero configuration.
+        "javascript"  => ["app/javascript/**/*.{js,mjs}",
+                          "app/assets/javascripts/**/*.{js,mjs}"],
         "importmap"   => true,
         "public"      => ["public/**/*.{html,css,js}"],
         "custom"      => []

data/lib/browsable/doctor.rb

@@ -42,12 +42,25 @@ module Browsable
       Tool.new(key: :eslint_plugin_compat, label: "eslint-plugin-compat", binary: nil,
                npm_package: "eslint-plugin-compat",
                purpose: "the eslint plugin that performs the JS compat checks",
-               enables: %i[js], required: true)
+               enables: %i[js], required: true),
+      Tool.new(key: :postcss_scss, label: "postcss-scss", binary: nil,
+               npm_package: "postcss-scss",
+               purpose: "lets stylelint parse SCSS sources (Sprockets apps)",
+               enables: %i[scss], required: false)
     ].freeze
 
     # Analyzer kinds that need no external tooling at all.
     ALWAYS_AVAILABLE = %i[erb html].freeze
 
+    # @param root [String, nil] the project root. When provided, optional tools
+    #   (e.g. postcss-scss) are only flagged as missing if the project actually
+    #   has files that need them.
+    def initialize(root: nil)
+      @root = root && File.expand_path(root)
+    end
+
+    attr_reader :root
+
     def statuses
       @statuses ||= TOOLS.map do |tool|
         present = installed?(tool)
@@ -64,6 +77,33 @@ module Browsable
       statuses.reject(&:installed?).map(&:tool)
     end
 
+    def postcss_scss_installed?
+      tool = TOOLS.find { |t| t.key == :postcss_scss }
+      installed?(tool)
+    end
+
+    # Whether the project at `root` actually has files that need this tool.
+    # For unconditional tools (e.g. node, stylelint) this is always true; for
+    # optional tools (e.g. postcss-scss) it depends on what's on disk.
+    def needs_tool?(tool)
+      return true if tool.required
+      return true if tool.enables.empty? # tools that enable nothing are housekeeping
+      return true unless root            # no project context: assume needed
+
+      tool.enables.all? { |kind| project_has_kind?(kind) }
+    end
+
+    # Optional tools that *would* be needed by this project but aren't installed.
+    # Used by the audit CLI to surface targeted skips (e.g. postcss-scss missing
+    # only when the project has SCSS files).
+    def needed_optional_missing
+      missing.select do |tool|
+        next false if tool.required
+
+        needs_tool?(tool)
+      end
+    end
+
     # Which analyzer kinds can actually run on this machine right now.
     def available_kinds
       # In dry-run mode the external tools are never invoked, so treat them all
@@ -84,8 +124,9 @@ module Browsable
       lines = [pastel.bold("browsable doctor — system dependencies"), ""]
 
       statuses.each do |status|
-        mark = status.installed? ? pastel.green("✓") : pastel.red("✗")
-        lines << "  #{mark} #{pastel.bold(status.tool.label)} — #{status.tool.purpose}"
+        mark = render_mark(pastel, status)
+        suffix = render_suffix(pastel, status)
+        lines << "  #{mark} #{pastel.bold(status.tool.label)} — #{status.tool.purpose}#{suffix}"
         lines << pastel.dim("      #{status.detail}") if status.detail
       end
 
@@ -130,8 +171,12 @@ module Browsable
 
     private
 
+    # Install commands cover every required tool plus any optional tool the
+    # current project actually needs (e.g. postcss-scss when SCSS is present).
     def install_commands
-      missing.map { |tool| install_command(tool) }.uniq
+      missing.select { |tool| tool.required || needs_tool?(tool) }
+             .map { |tool| install_command(tool) }
+             .uniq
     end
 
     def install_command(tool)
@@ -146,11 +191,40 @@ module Browsable
     def detail_for(tool, present)
       if present
         tool.binary? ? (tool_version(tool) || "installed") : "installed"
-      else
+      elsif tool.required || needs_tool?(tool)
         "not found — #{install_command(tool)}"
+      else
+        "not installed (not needed for this project)"
+      end
+    end
+
+    def project_has_kind?(kind)
+      case kind
+      when :scss
+        Dir.glob(File.join(root, "app/assets/stylesheets/**/*.{scss,sass}"),
+                 File::FNM_EXTGLOB).any?
+      else
+        true
       end
     end
 
+    # Optional tools that are missing-but-needed get the same red ✗ as required
+    # tools. Optional tools the project doesn't need are shown as a dim "—".
+    def render_mark(pastel, status)
+      return pastel.green("✓") if status.installed?
+      return pastel.red("✗") if status.tool.required || needs_tool?(status.tool)
+
+      pastel.dim("—")
+    end
+
+    def render_suffix(pastel, status)
+      return "" if status.tool.required
+      return pastel.dim("  (optional)") if status.installed?
+      return pastel.yellow("  (optional, but needed for this project)") if needs_tool?(status.tool)
+
+      pastel.dim("  (optional)")
+    end
+
     def installed?(tool)
       @installed_cache ||= {}
       @installed_cache.fetch(tool.key) do

data/lib/browsable/formatters/human.rb

@@ -33,6 +33,7 @@ module Browsable
           lines << pastel.dim("target: #{target.query}  (#{browsers})")
         end
         lines << pastel.dim("config: #{report.config_file || 'none (no config file)'}")
+        lines << pastel.dim("pipeline: #{report.pipeline}") if report.pipeline
         lines.join("\n") + "\n"
       end
 

data/lib/browsable/replay.rb

@@ -69,6 +69,7 @@ module Browsable
     def policies   = []
     def root       = data.dig("target", "root") || Dir.pwd
     def config_file = nil
+    def pipeline   = data["pipeline"]
 
     def target
       tdata = data["target"]

data/lib/browsable/report.rb

@@ -15,14 +15,16 @@ module Browsable
     # `bumps` maps each raised browser to { from:, to: }.
     Suggestion = Data.define(:line, :bumps)
 
-    attr_reader :findings, :skips, :notes, :policies, :target, :root, :config_file
+    attr_reader :findings, :skips, :notes, :policies, :target, :root, :config_file, :pipeline
 
     # @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.
+    # @param pipeline [String, nil] the detected asset pipeline
+    #   ("propshaft", "sprockets", "sprockets+propshaft", or "none").
     def initialize(findings: [], skips: [], notes: [], policies: [],
-                   target: nil, root: nil, config_file: nil)
+                   target: nil, root: nil, config_file: nil, pipeline: nil)
       @findings = findings
       @skips = skips
       @notes = notes
@@ -30,6 +32,7 @@ module Browsable
       @target = target
       @root = root
       @config_file = config_file
+      @pipeline = pipeline
     end
 
     def errors   = findings.select(&:error?)
@@ -74,6 +77,7 @@ module Browsable
     def as_json
       {
         target: target&.as_json,
+        pipeline: pipeline,
         notes: notes,
         summary: {
           errors: errors.size,

data/lib/browsable/test_report.rb

@@ -69,7 +69,8 @@ module Browsable
         policies: PolicyScanner.call(root),
         target: batch_target,
         root: root,
-        config_file: config.config_file
+        config_file: config.config_file,
+        pipeline: AssetPipeline.detect(root: root).name
       )
     end
 

data/lib/browsable/version.rb

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

data/lib/generators/browsable/install/templates/browsable.yml.tt

@@ -25,10 +25,12 @@ target:
 
 # sources:
 #   # Globs are relative to the project root. The values shown are the defaults.
-#   stylesheets: ["app/assets/stylesheets/**/*.{css,scss}"]
+#   stylesheets: ["app/assets/stylesheets/**/*.{css,scss,sass}"]
 #   builds:      ["app/assets/builds/**/*.css"]
 #   views:       ["app/views/**/*.{html.erb,turbo_stream.erb}", "app/components/**/*.{rb,html.erb}"]
-#   javascript:  ["app/javascript/**/*.{js,mjs}"]
+#   # Both Propshaft/importmap (app/javascript) and Sprockets
+#   # (app/assets/javascripts) layouts are discovered by default.
+#   javascript:  ["app/javascript/**/*.{js,mjs}", "app/assets/javascripts/**/*.{js,mjs}"]
 #   importmap:   true   # resolve config/importmap.rb pins and audit pinned JS
 #   public:      ["public/**/*.{html,css,js}"]
 #   custom:      []     # extra globs to fold into the audit

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: browsable
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Roman Hood
@@ -174,6 +174,7 @@ files:
 - lib/browsable/analyzers/erb.rb
 - lib/browsable/analyzers/html.rb
 - lib/browsable/analyzers/javascript.rb
+- lib/browsable/asset_pipeline.rb
 - lib/browsable/asset_resolver.rb
 - lib/browsable/audit_log.rb
 - lib/browsable/cli.rb