browsable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8fbd1c4932fbe740cf4d0560fbeb4738c51c3129efdb3c7a3e48b86bc47a743d
+  data.tar.gz: f6d98e30cc6e54c6c5fe643dbf3eada45a08af171e2632561c8d91f1b49c74b6
+SHA512:
+  metadata.gz: 5f21b860c35d76a1011a2152a40ab9cbb232e7378d93f61fec3c75f4cea1cd5b69829ea4e77ffd2ae5f7406334e436d4997a17ad41fb769f253362e579d5baa6
+  data.tar.gz: 9e996ecdb1dded29f78c2b30c3b5c37178bd7c339800680bca51947934c6addf965534d09a1b3b03b5358b2134b542b056eab354b9582ba9864dc2dc806f57d7

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+## [0.1.0]
+
+- Initial release.

data/README.md

@@ -0,0 +1,240 @@
+# browsable
+
+**Rails-aware browser-compatibility auditing for your frontend code.**
+
+`browsable` audits a Rails application's CSS, HTML, ERB, and JavaScript and
+reports which browsers can actually render and run it — then compares that
+against the project's declared `allow_browser` policy.
+
+The name is a play on Rails 8's `allow_browser` controller API. Instead of
+*declaring* which browsers you allow, `browsable` tells you which browsers your
+code is actually **browsable by**.
+
+> This is the core gem of the [`browsable` monorepo](https://github.com/romanhood/browsable).
+> See also [`browsable-lsp`](../browsable-lsp) (editor diagnostics) and
+> [`browsable.nvim`](../browsable.nvim) (Neovim plugin).
+
+## Philosophy
+
+- **The gem owns no parsing or compat-data logic.** It shells out to mature
+  tools that already do this well — [Herb](https://github.com/marcoroth/herb)
+  for ERB, [stylelint](https://stylelint.io/) for CSS,
+  [eslint-plugin-compat](https://github.com/amilajack/eslint-plugin-compat) for
+  JavaScript. The gem's value is the Rails-aware glue.
+- **No `package.json`, no `node_modules` in your Rails repo.** The external
+  tools live globally on your machine. `browsable doctor` detects them and
+  guides installation.
+- **It reports, it doesn't decide.** It tells you what your code requires and
+  what your config permits. You decide what to do.
+- **Configuration is optional.** `browsable` runs with zero config.
+
+## Installation
+
+Add it to your Rails app's `Gemfile`:
+
+```ruby
+group :development, :test do
+  gem "browsable"
+end
+```
+
+Then `bundle install`. Or install it standalone:
+
+```bash
+gem install browsable
+```
+
+## System dependencies — the `doctor` workflow
+
+`browsable` shells out to `stylelint` and `eslint` (and the `node` runtime they
+need). Those are *not* gem dependencies — they live globally on your machine.
+Check what you have:
+
+```bash
+bundle exec browsable doctor
+```
+
+`doctor` prints, for each missing tool, the exact command to install it. Let it
+do the work for you:
+
+```bash
+bundle exec browsable doctor --fix   # installs missing tools via brew / npm
+```
+
+ERB and HTML analysis needs nothing extra — the `herb` gem is a dependency and
+runs in-process.
+
+## Quick start
+
+```bash
+bundle exec browsable audit
+```
+
+That's it. With no configuration, `browsable`:
+
+1. reads `ApplicationController`'s `allow_browser` policy to learn your target,
+2. discovers your stylesheets, views, JavaScript, and importmap pins,
+3. audits each against that target, and
+4. prints a report grouped by file.
+
+## CLI reference
+
+| Command | Purpose |
+| --- | --- |
+| `browsable` / `browsable audit [PATH]` | Full project audit |
+| `browsable doctor` | Check system dependencies |
+| `browsable doctor --fix` | Install missing dependencies (opt-in) |
+| `browsable check FILE [FILE...]` | Audit specific files (used by editors) |
+| `browsable target [PATH]` | Show the inferred browser-support target |
+| `browsable init` | Generate a `.browsable.yml` (non-Rails projects) |
+| `browsable version` | Print the version |
+
+### Flags
+
+| Flag | Effect |
+| --- | --- |
+| `--target QUERY` | Override the inferred browserslist query |
+| `--json` | Emit findings as JSON (shortcut for `--format json`) |
+| `--format human\|json\|github` | Choose the output formatter |
+| `--no-build` | Scan only what is on disk (`browsable` never builds assets itself) |
+| `--include GLOB` | Add a path glob to the audit (repeatable) |
+| `--exclude GLOB` | Exclude a path glob (repeatable) |
+| `--fail-on warning\|error` | Exit-code policy for CI |
+| `--config PATH` | Override the config file location |
+
+The `--json` output is the universal interface: the LSP server (and any future
+MCP server) consume exactly that structure. The human and GitHub formatters are
+just alternate presentations of the same data.
+
+## Rails generator
+
+```bash
+rails g browsable:install
+```
+
+This writes a fully-commented `config/browsable.yml` — every option present,
+commented out, set to its default. It is a self-documenting reference: uncomment
+a line to override it. Flags: `--minimal`, `--target QUERY`, `--force`.
+
+Non-Rails projects use `browsable init`, which writes `.browsable.yml` instead.
+
+## Configuration
+
+`browsable` needs no config file. When one is present it is discovered in this
+order:
+
+1. the path passed to `--config`
+2. `config/browsable.yml` (preferred in Rails apps)
+3. `.browsable.yml` in the working directory
+
+Resolution precedence (highest wins): **CLI flags → config file → inferred Rails
+config → gem defaults**. See the generated `config/browsable.yml` for the full,
+commented option reference.
+
+## How it works — the inference chain
+
+```
+ApplicationController.allow_browser  →  Target (browserslist query)  →  Analyzers
+        :modern                          chrome 120, safari 17.2          │
+                                                                          ▼
+   config/importmap.rb ─┐                                         CSS  → stylelint
+   app/assets/**       ─┼─→  Sources  ─→  files by kind  ─────────  ERB  → Herb + BCD
+   app/views/**        ─┤                                          HTML → Herb + BCD
+   app/javascript/**   ─┘                                          JS   → eslint
+                                                                          │
+                                                                          ▼
+                                                            Report → Formatter
+```
+
+`browsable` translates between Rails-land and browserslist-land: it reads
+`allow_browser :modern`, expands it to concrete browser versions, configures
+stylelint/eslint with that target, and runs Herb against the bundled MDN
+browser-compat-data snapshot for ERB/HTML.
+
+### Partial `allow_browser` policies
+
+If your `allow_browser` policy is a hash that pins only some browsers — say
+`versions: { safari: 16.4, firefox: 121 }` — Rails leaves every browser you
+*don't* list allowed at **any** version (it only blocks a browser it was given a
+minimum, or `false`, for). browsable audits exactly the browsers you pinned and
+prints a note naming the rest. To audit against more, set an explicit `target:`
+in `config/browsable.yml`. The same note-and-fall-back-to-`defaults` behaviour
+applies when browsable cannot resolve your policy statically.
+
+### Where `defaults` comes from
+
+When there is no `allow_browser` policy at all, browsable audits against the
+[browserslist](https://github.com/browserslist/browserslist) `defaults` query —
+the "reasonable broad support" baseline the wider frontend ecosystem uses. It is
+resolved **live** from caniuse data when the `browserslist` CLI is installed
+(`npm install -g browserslist`); otherwise browsable uses a small **built-in
+approximation** and says so in a note. Either way these versions are *not* a
+Rails concept — Rails blocks nothing unless you call `allow_browser` — and they
+are not derived from stylelint or eslint. For a precise, stable target, set
+`target:` in `config/browsable.yml`.
+
+### Suggested `allow_browser` fix
+
+When an audit finds errors that are purely a version conflict — your code needs
+a browser version newer than your policy permits — browsable prints a ready-to-paste
+`allow_browser` line that raises *only* the offending browsers to the minimum
+those features require, leaving every other browser untouched:
+
+```
+Suggested allow_browser policy
+    allow_browser versions: { chrome: 120, edge: 120, firefox: 125, safari: 17.2, opera: 106 }
+    firefox: 121 → 125
+```
+
+It is a suggestion, not an instruction: tightening the policy is one fix, changing
+the code (a fallback, a `@supports` rule) is another. browsable reports; you
+decide. The suggestion is derived from HTML/ERB findings, which carry exact
+version data; it also appears in `--json` (`suggested_policy`) and as a GitHub
+Actions notice.
+
+### Per-controller and per-action policies
+
+Rails lets any controller override `allow_browser`, and scope the override to
+certain actions with `only:`/`except:`. browsable scans every file under
+`app/controllers/` (including `concerns/`) and lists each `allow_browser` call
+it finds — its versions and any action scope — under **Browser policies** in the
+report.
+
+The audit itself runs against a single target (ApplicationController's policy,
+or your `config/browsable.yml`). browsable does **not** try to map each frontend
+asset to the exact endpoints — and policies — that serve it. CSS and importmap
+JavaScript are global assets, included via layout helpers on nearly every page,
+so they have no single owning controller action; a per-asset policy graph would
+be guesswork. Instead, browsable shows you the whole policy landscape: if a
+controller serves shared assets to a broader range of browsers than
+ApplicationController, audit against that policy explicitly with `--target` or
+`config/browsable.yml`. Per-action auditing of `app/views/<controller>/`
+templates against their controller's policy is a planned refinement.
+
+## Rake tasks
+
+Inside a Rails app, the railtie registers:
+
+- `rake browsable:audit` — audit `app/assets/builds/` as it stands
+- `rake browsable:audit:fresh` — run `assets:precompile` first, then audit
+- `rake browsable:doctor` — run the dependency check
+
+`browsable` never precompiles assets on its own. In CI, compose the pipeline
+explicitly: `bundle exec rails assets:precompile && bundle exec browsable audit`.
+
+## Contributing
+
+This gem lives in the `browsable/` subdirectory of the
+[monorepo](https://github.com/romanhood/browsable). To work on it:
+
+```bash
+cd browsable
+bundle install
+bundle exec rspec
+```
+
+Refresh the bundled compat data with `ruby bin/update-bcd-snapshot`.
+
+## License
+
+MIT — see the [LICENSE](../LICENSE) at the monorepo root.

data/bin/update-bcd-snapshot

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Maintenance script — refresh data/bcd-snapshot.json from the latest published
+# @mdn/browser-compat-data. The gem ships the generated snapshot; this script
+# is run by maintainers, never at gem runtime.
+#
+#   ruby bin/update-bcd-snapshot
+#
+# It downloads the full dataset (several MB) and keeps only the subtrees
+# browsable's ERB/HTML analyzer actually consults, so the committed file stays
+# small.
+
+require "net/http"
+require "uri"
+require "json"
+require "time"
+
+SOURCE = "https://cdn.jsdelivr.net/npm/@mdn/browser-compat-data/data.json"
+OUTPUT = File.expand_path("../data/bcd-snapshot.json", __dir__)
+
+# Only these subtrees are retained.
+SUBTREES = [
+  %w[html elements],
+  %w[html global_attributes],
+  %w[css properties]
+].freeze
+
+def fetch(url, redirects: 5)
+  raise "Too many redirects" if redirects.negative?
+
+  response = Net::HTTP.get_response(URI.parse(url))
+  case response
+  when Net::HTTPSuccess     then response.body
+  when Net::HTTPRedirection then fetch(response["location"], redirects: redirects - 1)
+  else raise "HTTP #{response.code} fetching #{url}"
+  end
+end
+
+puts "Fetching #{SOURCE} ..."
+full = JSON.parse(fetch(SOURCE))
+
+snapshot = {
+  "__meta" => {
+    "source" => SOURCE,
+    "generated_at" => Time.now.utc.iso8601,
+    "subtrees" => SUBTREES.map { |path| path.join(".") }
+  }
+}
+
+SUBTREES.each do |path|
+  node = full.dig(*path)
+  unless node
+    warn "  ! subtree #{path.join('.')} not found — skipping"
+    next
+  end
+
+  # Rebuild the nested structure: ["html", "elements"] => { "html" => { "elements" => node } }
+  nested = path[1..].reverse.reduce(node) { |acc, key| { key => acc } }
+  snapshot[path.first] = (snapshot[path.first] || {}).merge(nested)
+  puts "  + kept #{path.join('.')} (#{node.size} entries)"
+end
+
+File.write(OUTPUT, "#{JSON.pretty_generate(snapshot)}\n")
+puts "Wrote #{OUTPUT} (#{File.size(OUTPUT)} bytes)"

data/data/bcd-snapshot.json

@@ -0,0 +1,341 @@
+{
+  "__meta": {
+    "source": "https://cdn.jsdelivr.net/npm/@mdn/browser-compat-data/data.json",
+    "generated_at": "2026-05-01T00:00:00Z",
+    "subtrees": ["html.elements", "html.global_attributes", "css.properties"],
+    "note": "A curated subset of MDN browser-compat-data. Regenerate with bin/update-bcd-snapshot."
+  },
+  "html": {
+    "elements": {
+      "dialog": {
+        "__compat": {
+          "mdn_url": "https://developer.mozilla.org/docs/Web/HTML/Element/dialog",
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "37" },
+            "edge": { "version_added": "79" },
+            "firefox": { "version_added": "98" },
+            "safari": { "version_added": "15.4" }
+          }
+        }
+      },
+      "details": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "12" },
+            "edge": { "version_added": "79" },
+            "firefox": { "version_added": "49" },
+            "safari": { "version_added": "6" }
+          }
+        }
+      },
+      "summary": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "12" },
+            "edge": { "version_added": "79" },
+            "firefox": { "version_added": "49" },
+            "safari": { "version_added": "6" }
+          }
+        }
+      },
+      "search": {
+        "__compat": {
+          "mdn_url": "https://developer.mozilla.org/docs/Web/HTML/Element/search",
+          "status": { "baseline": "low" },
+          "support": {
+            "chrome": { "version_added": "118" },
+            "edge": { "version_added": "118" },
+            "firefox": { "version_added": "118" },
+            "safari": { "version_added": "17" }
+          }
+        }
+      },
+      "picture": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "38" },
+            "edge": { "version_added": "13" },
+            "firefox": { "version_added": "38" },
+            "safari": { "version_added": "9.1" }
+          }
+        }
+      },
+      "template": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "35" },
+            "edge": { "version_added": "13" },
+            "firefox": { "version_added": "22" },
+            "safari": { "version_added": "8" }
+          }
+        }
+      },
+      "slot": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "53" },
+            "edge": { "version_added": "79" },
+            "firefox": { "version_added": "63" },
+            "safari": { "version_added": "10.1" }
+          }
+        }
+      },
+      "datalist": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "20" },
+            "edge": { "version_added": "12" },
+            "firefox": { "version_added": "4" },
+            "safari": { "version_added": "12.1" }
+          }
+        }
+      },
+      "output": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "10" },
+            "edge": { "version_added": "13" },
+            "firefox": { "version_added": "6" },
+            "safari": { "version_added": "5.1" }
+          }
+        }
+      },
+      "meter": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "8" },
+            "edge": { "version_added": "13" },
+            "firefox": { "version_added": "16" },
+            "safari": { "version_added": "6" }
+          }
+        }
+      },
+      "progress": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "8" },
+            "edge": { "version_added": "12" },
+            "firefox": { "version_added": "6" },
+            "safari": { "version_added": "6" }
+          }
+        }
+      },
+      "canvas": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "4" },
+            "edge": { "version_added": "12" },
+            "firefox": { "version_added": "2" },
+            "safari": { "version_added": "3.1" }
+          }
+        }
+      },
+      "video": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "4" },
+            "edge": { "version_added": "12" },
+            "firefox": { "version_added": "3.5" },
+            "safari": { "version_added": "3.1" }
+          }
+        }
+      },
+      "audio": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "4" },
+            "edge": { "version_added": "12" },
+            "firefox": { "version_added": "3.5" },
+            "safari": { "version_added": "3.1" }
+          }
+        }
+      }
+    },
+    "global_attributes": {
+      "popover": {
+        "__compat": {
+          "mdn_url": "https://developer.mozilla.org/docs/Web/HTML/Global_attributes/popover",
+          "status": { "baseline": "low" },
+          "support": {
+            "chrome": { "version_added": "114" },
+            "edge": { "version_added": "114" },
+            "firefox": { "version_added": "125" },
+            "safari": { "version_added": "17" }
+          }
+        }
+      },
+      "inert": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "102" },
+            "edge": { "version_added": "102" },
+            "firefox": { "version_added": "112" },
+            "safari": { "version_added": "15.5" }
+          }
+        }
+      },
+      "loading": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "77" },
+            "edge": { "version_added": "79" },
+            "firefox": { "version_added": "75" },
+            "safari": { "version_added": "16.4" }
+          }
+        }
+      },
+      "enterkeyhint": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "77" },
+            "edge": { "version_added": "79" },
+            "firefox": { "version_added": "94" },
+            "safari": { "version_added": "13.1" }
+          }
+        }
+      },
+      "autocapitalize": {
+        "__compat": {
+          "status": { "baseline": "low" },
+          "support": {
+            "chrome": { "version_added": "43" },
+            "edge": { "version_added": "79" },
+            "firefox": { "version_added": "111" },
+            "safari": { "version_added": "5" }
+          }
+        }
+      },
+      "is": {
+        "__compat": {
+          "mdn_url": "https://developer.mozilla.org/docs/Web/HTML/Global_attributes/is",
+          "status": { "baseline": false },
+          "support": {
+            "chrome": { "version_added": "67" },
+            "edge": { "version_added": "79" },
+            "firefox": { "version_added": "63" },
+            "safari": { "version_added": false }
+          }
+        }
+      },
+      "contenteditable": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "4" },
+            "edge": { "version_added": "12" },
+            "firefox": { "version_added": "3" },
+            "safari": { "version_added": "3.1" }
+          }
+        }
+      },
+      "hidden": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "6" },
+            "edge": { "version_added": "12" },
+            "firefox": { "version_added": "4" },
+            "safari": { "version_added": "5" }
+          }
+        }
+      },
+      "draggable": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "4" },
+            "edge": { "version_added": "12" },
+            "firefox": { "version_added": "3.5" },
+            "safari": { "version_added": "6" }
+          }
+        }
+      }
+    }
+  },
+  "css": {
+    "properties": {
+      "aspect-ratio": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "88" },
+            "edge": { "version_added": "88" },
+            "firefox": { "version_added": "89" },
+            "safari": { "version_added": "15" }
+          }
+        }
+      },
+      "gap": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "84" },
+            "edge": { "version_added": "84" },
+            "firefox": { "version_added": "63" },
+            "safari": { "version_added": "14.1" }
+          }
+        }
+      },
+      "inset": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "87" },
+            "edge": { "version_added": "87" },
+            "firefox": { "version_added": "66" },
+            "safari": { "version_added": "14.1" }
+          }
+        }
+      },
+      "container-type": {
+        "__compat": {
+          "status": { "baseline": "low" },
+          "support": {
+            "chrome": { "version_added": "105" },
+            "edge": { "version_added": "105" },
+            "firefox": { "version_added": "110" },
+            "safari": { "version_added": "16" }
+          }
+        }
+      },
+      "accent-color": {
+        "__compat": {
+          "status": { "baseline": "high" },
+          "support": {
+            "chrome": { "version_added": "93" },
+            "edge": { "version_added": "93" },
+            "firefox": { "version_added": "92" },
+            "safari": { "version_added": "15.4" }
+          }
+        }
+      },
+      "text-wrap": {
+        "__compat": {
+          "status": { "baseline": "low" },
+          "support": {
+            "chrome": { "version_added": "114" },
+            "edge": { "version_added": "114" },
+            "firefox": { "version_added": "121" },
+            "safari": { "version_added": "17.4" }
+          }
+        }
+      }
+    }
+  }
+}

data/exe/browsable

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "browsable"
+
+Browsable::CLI.start(ARGV)