browsable-lsp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 87c10b50ca49f864d9d2b0793c69ecf77db137a97eccac37c9ab21ba76490006
+  data.tar.gz: 44ff7ce5d57863ee5d6b2b9fd914bff2e16cf18b1b8292c7eb32400d39336af6
+SHA512:
+  metadata.gz: 36f4c19a6bb502bf67a31260a6a96496a5fec457c6b282c9452ec7e8a627d1fbc45390866fa8661c6d8da7203c0411a52300bc7b8df15972108408a5b72f8bc4
+  data.tar.gz: c0a514689ca863de6dc31d5eb53141a26f466021b9a170bd1dd3649cc1d1fea8c010ce736e7156872fdc2c36b8afacdc010dc4a9831494821553e2fe212a81e6

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to the `browsable-lsp` 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,142 @@
+# browsable-lsp
+
+**A Language Server Protocol server for [`browsable`](../browsable).**
+
+`browsable-lsp` exposes browsable's browser-compatibility audit to your editor.
+As you open and edit CSS, ERB, HTML, and JavaScript files, it reports — inline —
+which features your code uses that fall outside your project's `allow_browser`
+target.
+
+> Part of the [`browsable` monorepo](https://github.com/romanhood/browsable).
+> Neovim users want [`browsable.nvim`](../browsable.nvim) instead — it bundles
+> this server's wiring.
+
+## What is a language server?
+
+A *language server* is a background program your editor talks to over a small
+JSON-RPC protocol (the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/)).
+The editor tells the server which files you open and edit; the server tells the
+editor what to underline. One server works in every LSP-capable editor, so
+browsable's analysis is written once and reused everywhere.
+
+`browsable-lsp` communicates over stdio and pushes **diagnostics** — the
+squiggly underlines — for each document you touch.
+
+## Installation
+
+```bash
+gem install browsable-lsp
+```
+
+This installs the `browsable-lsp` executable. Confirm it is on your `PATH`:
+
+```bash
+which browsable-lsp
+```
+
+ERB and HTML are audited in-process and need nothing else. For CSS and
+JavaScript diagnostics, install stylelint and eslint as described in the
+[`browsable` README](../browsable/README.md#system-dependencies--the-doctor-workflow)
+(`browsable doctor` will guide you).
+
+## Severity mapping
+
+| browsable category          | LSP severity   |
+| --------------------------- | -------------- |
+| `below_target`              | Error          |
+| `baseline_newly_available`  | Warning        |
+| `baseline_widely_available` | Information    |
+
+A diagnostic reads, for example:
+
+> The `popover` attribute requires Firefox 125+, but your `:modern`
+> `allow_browser` policy permits Firefox 121.
+
+## Editor setup
+
+Configuration is **inherited from the browsable gem** — `browsable-lsp` discovers
+`config/browsable.yml` / `.browsable.yml` from the workspace root exactly as the
+CLI does. There is nothing to configure in the server itself.
+
+### VS Code
+
+There is no dedicated extension yet. Use a generic LSP bridge such as
+[`vscode-glspc`](https://marketplace.visualstudio.com/items?itemName=qugu.glspc)
+and point it at the executable:
+
+```jsonc
+// settings.json
+{
+  "glspc.languageServerPath": "browsable-lsp",
+  "glspc.languageId": ["css", "html", "erb", "javascript"]
+}
+```
+
+### Helix
+
+Add to `~/.config/helix/languages.toml`:
+
+```toml
+[language-server.browsable]
+command = "browsable-lsp"
+
+[[language]]
+name = "erb"
+language-servers = ["browsable"]
+
+[[language]]
+name = "css"
+language-servers = ["browsable"]
+```
+
+### Zed
+
+In your Zed settings, register the server (Zed discovers stdio servers via an
+extension or the `lsp` settings block):
+
+```jsonc
+{
+  "lsp": {
+    "browsable-lsp": {
+      "binary": { "path": "browsable-lsp" }
+    }
+  }
+}
+```
+
+### Neovim
+
+Don't wire this up by hand — install [`browsable.nvim`](../browsable.nvim),
+which configures the client, the filetypes, and the root-directory detection for
+you.
+
+## How it works
+
+```
+editor  ──(LSP/JSON-RPC over stdio)──▶  browsable-lsp
+                                            │
+                                            ▼
+                            Browsable::Analyzers (the core gem)
+                                            │
+                                            ▼
+                            Findings ──▶ LSP diagnostics
+```
+
+On `textDocument/didOpen` and `textDocument/didChange`, the server runs
+browsable's analyzers against the buffer's *in-memory* contents (no need to
+save), converts the Findings to LSP diagnostics, and publishes them.
+
+## Contributing
+
+This gem lives in the `browsable-lsp/` subdirectory of the
+[monorepo](https://github.com/romanhood/browsable):
+
+```bash
+cd browsable-lsp
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT — see the [LICENSE](../LICENSE) at the monorepo root.

data/exe/browsable-lsp

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# The binary editors invoke. browsable-lsp speaks LSP over stdio, the standard
+# convention — there are no arguments to parse.
+
+require "browsable-lsp"
+
+Browsable::LSP::Server.new.start

data/lib/browsable/lsp/diagnostics.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+module Browsable
+  module LSP
+    # Audits a single document's contents and converts the resulting browsable
+    # Findings into LSP diagnostic hashes ready for textDocument/publishDiagnostics.
+    class Diagnostics
+      # browsable severity -> LSP DiagnosticSeverity
+      #   below_target            -> Error (1)
+      #   baseline_newly_available -> Warning (2)
+      #   baseline_widely_available -> Information (3)
+      SEVERITY = { error: 1, warning: 2, info: 3 }.freeze
+
+      def self.for(uri:, content:, root: Dir.pwd)
+        new(uri: uri, content: content, root: root).call
+      end
+
+      def initialize(uri:, content:, root:)
+        @uri = uri
+        @content = content.to_s
+        @root = root
+      end
+
+      def call
+        findings.map { |finding| to_diagnostic(finding) }
+      rescue StandardError
+        # A diagnostics pass must never crash the editor session.
+        []
+      end
+
+      private
+
+      def findings
+        config = Browsable::Config.load(root: @root)
+        analyzer_class = analyzer_for(path)
+        return [] unless analyzer_class
+
+        analyzer = analyzer_class.new(target: config.target, config: config)
+
+        if analyzer.is_a?(Browsable::Analyzers::ERB)
+          # ERB/HTML analysis is in-process — audit the buffer contents directly.
+          analyzer.analyze_source(@content, file: path)
+        else
+          # CSS/JS need a real file for stylelint/eslint.
+          # TODO(v0.2): debounce changes and reuse a per-document temp file.
+          audit_via_tempfile(analyzer)
+        end
+      end
+
+      def audit_via_tempfile(analyzer)
+        Dir.mktmpdir("browsable-lsp") do |dir|
+          tmp = File.join(dir, File.basename(path))
+          File.write(tmp, @content)
+          analyzer.analyze([tmp])
+        end
+      end
+
+      def analyzer_for(file)
+        case File.extname(file).downcase
+        when ".erb"          then Browsable::Analyzers::ERB
+        when ".html", ".htm" then Browsable::Analyzers::HTML
+        when ".css", ".scss" then Browsable::Analyzers::CSS
+        when ".js", ".mjs"   then Browsable::Analyzers::Javascript
+        end
+      end
+
+      def path
+        @path ||= @uri.to_s.sub(%r{\Afile://}, "")
+      end
+
+      def to_diagnostic(finding)
+        line = [finding.line.to_i - 1, 0].max
+        character = [finding.column.to_i - 1, 0].max
+        span = finding.feature_name.to_s.length.clamp(1, 200)
+
+        {
+          range: {
+            start: { line: line, character: character },
+            end:   { line: line, character: character + span }
+          },
+          severity: SEVERITY.fetch(finding.severity, 2),
+          source: "browsable",
+          code: finding.feature_id,
+          message: finding.message
+        }
+      end
+    end
+  end
+end

data/lib/browsable/lsp/handlers/did_change.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Browsable
+  module LSP
+    module Handlers
+      # Handles textDocument/didChange — re-audits a document as it is edited.
+      class DidChange
+        def initialize(server)
+          @server = server
+        end
+
+        def call(params)
+          uri = params.dig("textDocument", "uri")
+          return unless uri
+
+          # Full-sync mode: the final content change carries the whole document.
+          text = Array(params["contentChanges"]).last&.fetch("text", nil)
+          return if text.nil?
+
+          @server.store(uri, text)
+          @server.publish_diagnostics(uri, text)
+        end
+      end
+    end
+  end
+end

data/lib/browsable/lsp/handlers/did_open.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Browsable
+  module LSP
+    module Handlers
+      # Handles textDocument/didOpen — audits a freshly-opened document and
+      # publishes its diagnostics.
+      class DidOpen
+        def initialize(server)
+          @server = server
+        end
+
+        def call(params)
+          document = params["textDocument"] || {}
+          uri = document["uri"]
+          return unless uri
+
+          text = document["text"].to_s
+          @server.store(uri, text)
+          @server.publish_diagnostics(uri, text)
+        end
+      end
+    end
+  end
+end

data/lib/browsable/lsp/handlers/initialize.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Browsable
+  module LSP
+    module Handlers
+      # Handles the `initialize` request: advertises the server's capabilities.
+      class Initialize
+        def call(_params)
+          {
+            capabilities: {
+              # 1 = Full document sync — the client resends the whole buffer on
+              # every change. Simple and fine for the file sizes browsable sees.
+              textDocumentSync: { openClose: true, change: 1 }
+            },
+            serverInfo: { name: "browsable-lsp", version: Browsable::LSP::VERSION }
+          }
+        end
+
+        # Best-effort extraction of the workspace root from initialize params.
+        # browsable's Config is then loaded relative to it.
+        def self.workspace_root(params)
+          uri = params["rootUri"] || params.dig("workspaceFolders", 0, "uri")
+          return params["rootPath"] if uri.nil?
+
+          uri.to_s.sub(%r{\Afile://}, "")
+        end
+      end
+    end
+  end
+end

data/lib/browsable/lsp/server.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Browsable
+  module LSP
+    # The JSON-RPC server loop.
+    #
+    # Reads LSP messages from stdin, dispatches them to handlers, and writes
+    # responses and diagnostics back to stdout — the standard stdio LSP
+    # convention. All compatibility analysis is delegated to the browsable gem;
+    # this class only speaks the protocol.
+    class Server
+      def initialize(input: $stdin, output: $stdout)
+        # Io::Reader/Writer take an explicit IO (the Stdio:: subclasses hard-code
+        # STDIN/STDOUT); passing $stdin/$stdout keeps the default behaviour while
+        # letting tests drive the server over StringIO pipes.
+        @reader = ::LanguageServer::Protocol::Transport::Io::Reader.new(input)
+        @writer = ::LanguageServer::Protocol::Transport::Io::Writer.new(output)
+        @documents = {}
+        @workspace_root = Dir.pwd
+        @shutdown_requested = false
+      end
+
+      # Block reading messages until the client disconnects or sends `exit`.
+      def start
+        @reader.read { |message| dispatch(normalize(message)) }
+      end
+
+      # Cache the latest known contents of a document.
+      def store(uri, content)
+        @documents[uri] = content
+      end
+
+      # Audit `content` and push its diagnostics to the client.
+      def publish_diagnostics(uri, content)
+        diagnostics = Diagnostics.for(uri: uri, content: content, root: @workspace_root)
+        notify("textDocument/publishDiagnostics", { uri: uri, diagnostics: diagnostics })
+      end
+
+      private
+
+      def dispatch(message)
+        method = message["method"]
+        id = message["id"]
+        params = message["params"] || {}
+
+        case method
+        when "initialize"
+          @workspace_root = Handlers::Initialize.workspace_root(params) || @workspace_root
+          respond(id, Handlers::Initialize.new.call(params))
+        when "initialized"
+          nil # nothing to do — diagnostics are pushed on open/change
+        when "textDocument/didOpen"
+          Handlers::DidOpen.new(self).call(params)
+        when "textDocument/didChange"
+          Handlers::DidChange.new(self).call(params)
+        when "textDocument/didClose"
+          @documents.delete(params.dig("textDocument", "uri"))
+        when "shutdown"
+          @shutdown_requested = true
+          respond(id, nil)
+        when "exit"
+          exit(@shutdown_requested ? 0 : 1)
+        # TODO(v0.2): textDocument/codeAction — offer "Add @supports fallback"
+        # and "Tighten allow_browser to require Safari 15.4+" as quick fixes.
+        end
+      rescue StandardError => e
+        log("error handling #{method}: #{e.class}: #{e.message}")
+      end
+
+      def respond(id, result)
+        write(jsonrpc: "2.0", id: id, result: result)
+      end
+
+      def notify(method, params)
+        write(jsonrpc: "2.0", method: method, params: params)
+      end
+
+      def write(message)
+        @writer.write(message)
+      end
+
+      # Diagnostics go to stderr — stdout is reserved for the JSON-RPC channel.
+      def log(text)
+        warn("[browsable-lsp] #{text}")
+      end
+
+      # Normalize every hash key to a String so handlers need not care whether
+      # the transport produced symbol or string keys.
+      def normalize(object)
+        case object
+        when Hash  then object.each_with_object({}) { |(k, v), h| h[k.to_s] = normalize(v) }
+        when Array then object.map { |element| normalize(element) }
+        else object
+        end
+      end
+    end
+  end
+end

data/lib/browsable/lsp/version.rb

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

data/lib/browsable-lsp.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# browsable-lsp — a Language Server Protocol server built on the browsable gem.
+#
+# The core gem already sets up Zeitwerk for the Browsable namespace; this small
+# companion gem uses an explicit require manifest instead. With only a handful
+# of files, a flat manifest is clearer than a second autoloader co-managing the
+# shared Browsable:: namespace.
+
+require "browsable"
+require "language_server-protocol"
+
+require_relative "browsable/lsp/version"
+require_relative "browsable/lsp/diagnostics"
+require_relative "browsable/lsp/handlers/initialize"
+require_relative "browsable/lsp/handlers/did_open"
+require_relative "browsable/lsp/handlers/did_change"
+require_relative "browsable/lsp/server"

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: browsable-lsp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Roman Hood
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-05-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: browsable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: language_server-protocol
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.17'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: |
+  browsable-lsp exposes browsable's browser-compatibility audit as a Language
+  Server Protocol server, so editors can show inline diagnostics as you type.
+  It wraps the browsable gem's analyzers and speaks LSP over stdio.
+email:
+- roman.hood@aigility.com
+executables:
+- browsable-lsp
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- exe/browsable-lsp
+- lib/browsable-lsp.rb
+- lib/browsable/lsp/diagnostics.rb
+- lib/browsable/lsp/handlers/did_change.rb
+- lib/browsable/lsp/handlers/did_open.rb
+- lib/browsable/lsp/handlers/initialize.rb
+- lib/browsable/lsp/server.rb
+- lib/browsable/lsp/version.rb
+homepage: https://github.com/romanhood/browsable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/romanhood/browsable
+  source_code_uri: https://github.com/romanhood/browsable/tree/main/browsable-lsp
+  changelog_uri: https://github.com/romanhood/browsable/blob/main/browsable-lsp/CHANGELOG.md
+  bug_tracker_uri: https://github.com/romanhood/browsable/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Language Server Protocol server for browsable.
+test_files: []