klenod-lsp 0.0.15

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 86a3abc50bc2960a548b3c8a5bf3df849886fdf454127fd004293721410833a2
+  data.tar.gz: d769bd57a7a6bfb32db8fdb6d2bf200fdb8db983f9a1f4096819c4ffe9e4b0c0
+SHA512:
+  metadata.gz: dfdb72434f5c00387969e9e76af3fbf40e123c5ec1d17c14281001ff00f8690dce7f5e7fe7c5c889b66ad17cfa47afe575061ad1f0a69b75d2e8f4103129ac2b
+  data.tar.gz: 70d80cb81f695470069ee10db6ae3ce38c44c957b218450a9c5a775e27a32ee881f2ef10053020747e294d5049528be29e0c64c05af4c62f7d09b96676f295d2

data/README.md

@@ -0,0 +1,114 @@
+# klenod-lsp
+
+Language Server Protocol support for Klenod applications. It uses the configured
+Klenod plugins to analyze Haml, Ruby imports, and CSS without evaluating
+application code.
+
+## Features
+
+- Diagnostics for Haml, generated Ruby, unresolved imports, unused imports,
+  unknown component props, and unknown scoped CSS classes.
+- Definition, hover, document links, and completion for imports and Haml
+  component tags.
+- Import navigation for Ruby and for CSS `@import`, `url()`, and
+  `composes ... from` references.
+- Find references, document and workspace symbols, and reference-count code
+  lenses.
+- Symbol rename within a Haml or Ruby file and import-preserving edits when
+  files or directories move.
+- Prop and slot information for Haml components, including spelling suggestions
+  for unknown props.
+- Scoped CSS class definition, hover, completion, and validation in Haml.
+- Route lenses and hovers when `RouterPlugin` is configured.
+
+Ruby support is intentionally limited to Klenod imports and their bound
+constants. Use a Ruby language server alongside Klenod for general Ruby
+features.
+
+## Installation
+
+Add the gem to the application Gemfile:
+
+```ruby
+gem "klenod-lsp"
+```
+
+Install it and start the server from a project containing `klenod.config.rb`:
+
+```sh
+bundle install
+bundle exec klenod lsp
+```
+
+The `klenod` command comes from the `klenod` meta gem. The meta gem does not
+install `klenod-lsp` automatically.
+
+Configure the editor to run that command for `.haml` files. Ruby and CSS files
+can also use it alongside their usual language servers.
+
+For example, with Neovim:
+
+```lua
+vim.api.nvim_create_autocmd("FileType", {
+  pattern = "haml",
+  callback = function()
+    vim.lsp.start({
+      name = "klenod",
+      cmd = { "bundle", "exec", "klenod", "lsp" },
+      root_dir = vim.fs.root(0, { "klenod.config.rb", "Gemfile" }),
+    })
+  end,
+})
+```
+
+## Configuration
+
+The CLI has no LSP-specific options. It loads the nearest `klenod.config.rb`
+and uses its source directory, plugins, and entrypoints. Position encoding is
+negotiated with the editor.
+
+Frameworks that construct their configuration in Ruby can start the server
+directly:
+
+```ruby
+require "klenod/lsp"
+
+config = MyFramework.build_config(mode: :development)
+context = config.context(analysis: true)
+
+exit Klenod::LSP::Server.new(
+  context: context,
+  entrypoints: config.entrypoints
+).start
+```
+
+`Server.new` accepts:
+
+- `context:` — a required `Klenod::Build::Context`; use `analysis: true`.
+- `entrypoints:` — roots collected in addition to source files; defaults to
+  none.
+- `input:` and `output:` — the JSON-RPC streams; default to stdin and stdout.
+- `logger:` — server logging; defaults to stderr.
+
+The web example has a complete runner at `example/web/bin/lsp`.
+
+## How it works
+
+Open buffers are transformed with the build plugins for immediate diagnostics.
+A background graph indexes Ruby, Haml, and CSS files for cross-file features,
+including lazy dependencies. Analysis mode skips network fetches, JavaScript
+compilation, image generation, and filesystem output.
+
+The editor reports file changes to the server. Clients without dynamic watched
+file registration need to configure a watcher for the application source
+directory.
+
+## Limitations
+
+- References and rename edits cover application source files. Definition and
+  hover can also reach installed gems, while virtual modules have no file
+  location.
+- Cross-file results can be incomplete while the initial background index is
+  still running.
+- Documents use full-text synchronization, and completion examines only the
+  current line up to the cursor.

data/lib/klenod/lsp/analysis.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Klenod
+  module LSP
+    # Everything the server learned from transforming one document's text.
+    #
+    # `build_error` is the Klenod::Build::Error that stopped the transform, if
+    # any. `ruby_errors` are Prism syntax errors in the generated Ruby, and
+    # `resolve_errors` are per-dependency ResolveErrors. A document can carry
+    # resolved dependencies and errors at the same time.
+    Analysis =
+      Data.define(:module_id, :source, :transform, :resolved_dependencies, :build_error, :ruby_errors, :resolve_errors) do
+        def lines
+          source.lines(chomp: true)
+        end
+
+        def source_map
+          transform&.source_map
+        end
+
+        def resolved_module_id_for(specifier)
+          resolved = resolved_dependencies.find { |candidate| candidate.dependency.specifier.to_s == specifier }
+          resolved&.module_id
+        end
+      end
+
+    RubyError = Data.define(:message, :generated_line)
+  end
+end

data/lib/klenod/lsp/cli.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "klenod/build/cli"
+
+require_relative "../lsp"
+
+module Klenod
+  module LSP
+    module CLI
+      class Command < Samovar::Command
+        self.description = "Start a language server for editors."
+
+        def call
+          config_path = Klenod::Build::ConfigLoader.find
+          unless config_path
+            output.puts "Could not find klenod.config.rb"
+            return 1
+          end
+
+          config = nil
+          Dir.chdir(File.dirname(config_path)) do
+            config = Klenod::Build::ConfigLoader.load(config_path)
+          end
+
+          Dir.chdir(config.base_dir) do
+            context = config.context(mode: :development, analysis: true)
+            Klenod::LSP::Server.new(context: context, entrypoints: config.entrypoints).start
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klenod/lsp/diagnostics.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "klenod/build/source_error"
+
+require_relative "languages/syntax"
+require_relative "text"
+
+module Klenod
+  module LSP
+    # Turns the errors in an Analysis into LSP diagnostics on the original
+    # document. Every diagnostic is an error: Klenod has no warnings yet.
+    module Diagnostics
+      Interface = LanguageServer::Protocol::Interface
+      Constant = LanguageServer::Protocol::Constant
+
+      SOURCE = "klenod"
+
+      module_function
+
+      def for_analysis(analysis, syntax: Languages::Syntax::Ruby)
+        lines = analysis.lines
+        diagnostics = []
+        diagnostics << build_error(analysis, lines) if analysis.build_error
+        diagnostics.concat(ruby_errors(analysis, lines))
+        diagnostics.concat(resolve_errors(analysis, lines, syntax))
+        diagnostics
+      end
+
+      def build_error(analysis, lines)
+        error = analysis.build_error
+
+        if error.is_a?(Klenod::Build::SourceError)
+          source_error(analysis, error, lines)
+        else
+          diagnostic(Text.line_span(lines, 0), "#{short_class_name(error)}: #{error.message}")
+        end
+      end
+
+      def source_error(analysis, error, lines)
+        message = [error.kind, error.detail].compact.join(": ")
+        message = "#{message}\n#{error.hints.join("\n")}" unless error.hints.empty?
+
+        if error.module_id.to_s == analysis.module_id.to_s
+          line = error.line ? error.line - 1 : 0
+          diagnostic(Text.line_span(lines, line), message)
+        else
+          diagnostic(Text.line_span(lines, 0), "#{error.module_id}: #{message}")
+        end
+      end
+
+      def ruby_errors(analysis, lines)
+        source_map = analysis.source_map
+
+        analysis.ruby_errors.map { |error|
+          original_line = source_map&.find_original_line_no(error.generated_line)
+          line = original_line ? original_line - 1 : 0
+          diagnostic(Text.line_span(lines, line), "Generated Ruby syntax error: #{error.message}")
+        }.uniq { |diagnostic| [diagnostic.range.start.line, diagnostic.message] }
+      end
+
+      def resolve_errors(analysis, lines, syntax)
+        analysis.resolve_errors.map do |error|
+          diagnostic(resolve_error_span(error, lines, syntax), error.message)
+        end
+      end
+
+      # Resolve errors know their import's line and column, but for imports
+      # outside the leading `:ruby` filter the location points into generated
+      # Ruby, so the literal is looked up in the document text first.
+      def resolve_error_span(error, lines, syntax = Languages::Syntax::Ruby)
+        specifier = error.requested_specifier || error.dependency&.specifier&.to_s
+        span = specifier && literal_span(specifier, lines, syntax: syntax)
+        return span if span
+
+        line = error.source_location&.line
+        line = line&.between?(1, lines.length) ? line - 1 : 0
+        Text.line_span(lines, line)
+      end
+
+      def literal_span(specifier, lines, syntax: Languages::Syntax::Ruby)
+        literal_spans(specifier, lines, syntax: syntax).first
+      end
+
+      # Every occurrence of a specifier; stylesheets repeat one across
+      # `@import` and `composes`.
+      def literal_spans(specifier, lines, syntax: Languages::Syntax::Ruby)
+        spans = []
+        lines.each_with_index do |line_text, index|
+          syntax.each_literal(line_text, index) do |literal|
+            spans << literal.span if literal.specifier == specifier
+          end
+        end
+        spans
+      end
+
+      def diagnostic(span, message)
+        Interface::Diagnostic.new(
+          range: span.to_range,
+          severity: Constant::DiagnosticSeverity::ERROR,
+          source: SOURCE,
+          message: message
+        )
+      end
+
+      def short_class_name(error)
+        error.class.name.to_s.split("::").last
+      end
+    end
+  end
+end

data/lib/klenod/lsp/documents.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Klenod
+  module LSP
+    Document = Data.define(:uri, :path, :module_id, :text, :version) do
+      def lines
+        text.lines(chomp: true)
+      end
+
+      def extname
+        path ? File.extname(path) : ""
+      end
+    end
+
+    # Open editor documents, synchronized with full text on every change, and
+    # the analysis computed for each document version.
+    class Documents
+      def initialize(workspace)
+        @workspace = workspace
+        @documents = {}
+        @analyses = {}
+      end
+
+      def open(uri:, text:, version:)
+        document =
+          Document.new(
+            uri: uri,
+            path: @workspace.path_for_uri(uri),
+            module_id: @workspace.module_id_for_uri(uri),
+            text: text,
+            version: version
+          )
+        @documents[uri] = document
+      end
+
+      def change(uri:, text:, version:)
+        existing = @documents[uri]
+        return self.open(uri: uri, text: text, version: version) unless existing
+
+        @documents[uri] = existing.with(text: text, version: version)
+      end
+
+      def close(uri)
+        @analyses.delete(uri)
+        @documents.delete(uri)
+      end
+
+      def fetch(uri)
+        @documents[uri]
+      end
+
+      def each(&)
+        @documents.each_value(&)
+      end
+
+      def invalidate(uri)
+        @analyses.delete(uri)
+      end
+
+      def analysis_for(document)
+        cached_analysis(document) || @workspace.analyze(document.module_id, document.text).tap do |analysis|
+          @analyses[document.uri] = [document.version, analysis]
+        end
+      end
+
+      def cached_analysis(document)
+        cached_version, cached = @analyses[document.uri]
+        cached if cached && cached_version == document.version
+      end
+    end
+  end
+end

data/lib/klenod/lsp/graph_index.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/semaphore"
+
+require "klenod/build/dependency"
+require "klenod/build/module_id"
+
+module Klenod
+  module LSP
+    # The collected module graph behind cross-file features.
+    #
+    # Roots are the configured entrypoints plus every Ruby and Haml file under
+    # the source directory, so orphan components and test files are indexed
+    # too. Lazy dependencies such as router pages are walked as well. Nothing
+    # is ever evaluated. Root collections are serialized so two walks cannot
+    # deadlock on a shared import cycle; the graph parallelizes inside each.
+    class GraphIndex
+      ROOT_EXTENSIONS = [".rb", ".haml", ".css"].freeze
+
+      attr_reader :failed
+
+      def initialize(workspace:, logger:, entrypoints: [])
+        @workspace = workspace
+        @graph = workspace.context.graph
+        @entrypoints = entrypoints
+        @logger = logger
+        @failed = {}
+        @unresolved_entrypoints = []
+        @semaphore = Async::Semaphore.new(1)
+        @task = nil
+      end
+
+      # Collect every root in the background, yielding to other work between
+      # roots. `progress` responds to `begin(total)`, `report(done, total)`,
+      # and `finish`; the block runs once the pass completed.
+      def start(parent_task, progress: nil, &on_complete)
+        @task =
+          parent_task.async do |task|
+            roots = root_module_ids
+            progress&.begin(roots.length)
+            roots.each_with_index do |module_id, index|
+              ensure_collected(module_id)
+              progress&.report(index + 1, roots.length)
+              task.yield
+            end
+            progress&.finish
+            on_complete&.call
+          rescue => error
+            progress&.finish
+            @logger.error { "Graph index failed: #{error.class}: #{error.message}" }
+          end
+      end
+
+      def stop
+        @task&.stop
+      end
+
+      def running?
+        @task ? !@task.finished? : false
+      end
+
+      def wait
+        @task&.wait
+      end
+
+      def records
+        @graph.records
+      end
+
+      def record(module_id)
+        @graph.records[module_id]
+      end
+
+      def dependents(module_id)
+        @graph.dependents(module_id)
+      end
+
+      # Collect one module and everything reachable from it, remembering
+      # failures so they can be retried when files change.
+      def ensure_collected(module_id, force: false)
+        @semaphore.acquire { collect_root(module_id, force: force) }
+      end
+
+      # Apply file changes through the build's own invalidation, collect new
+      # modules, retry earlier failures, and return the ids whose records may
+      # have changed, including their dependents.
+      def invalidate(changed_paths, removed_paths)
+        @semaphore.acquire do
+          result = @workspace.context.invalidate_paths(changed_paths, removed_paths: removed_paths)
+          affected = Set.new
+          [result.changed_module_ids, result.removed_module_ids, result.reloaded_module_ids, result.reevaluated_module_ids].each do |ids|
+            ids.each { |module_id| affected << module_id.to_s }
+          end
+          result.errors.each do |module_id, error|
+            next unless module_id
+
+            @failed[module_id.to_s] = error
+            affected << module_id.to_s
+          end
+
+          changed_paths.each do |path|
+            module_id = @workspace.module_id_for_path(path)
+            next unless module_id && ROOT_EXTENSIONS.include?(module_id.extname)
+            next if @graph.records.key?(module_id)
+
+            collect_root(module_id)
+            affected << module_id.to_s
+          end
+
+          # A retried module is affected whether or not it recovers: its
+          # diagnostics changed either way. The retry forces a re-collect,
+          # because a module that failed after its record was stored still has
+          # that stale record.
+          @failed.keys.each do |module_id_string|
+            collect_root(Klenod::Build::ModuleId.new(module_id_string), force: true)
+            affected << module_id_string
+          end
+          @unresolved_entrypoints.dup.each do |specifier|
+            module_id = resolve_entrypoint(specifier)
+            affected << module_id.to_s if module_id && collect_root(module_id)
+          end
+
+          dependents_closure(affected)
+        end
+      end
+
+      private
+
+      def root_module_ids
+        roots = []
+        @entrypoints.each do |specifier|
+          module_id = resolve_entrypoint(specifier)
+          roots << module_id if module_id
+        end
+        Dir.glob("**/*", base: @workspace.source_dir).sort.each do |relative|
+          next if relative.split("/").any? { |segment| segment.start_with?(".") }
+          next unless ROOT_EXTENSIONS.include?(File.extname(relative))
+          next unless File.file?(File.join(@workspace.source_dir, relative))
+
+          roots << Klenod::Build::ModuleId.new("app:/#{relative}")
+        end
+        roots.uniq
+      end
+
+      def resolve_entrypoint(specifier)
+        dependency = Klenod::Build::Dependency.create(specifier: specifier, importer_id: nil, kind: :entrypoint)
+        module_id = @graph.resolve_dependency(dependency).module_id
+        @unresolved_entrypoints.delete(specifier)
+        module_id
+      rescue Klenod::Build::ResolveError => error
+        @unresolved_entrypoints << specifier unless @unresolved_entrypoints.include?(specifier)
+        @logger.warn { "Entrypoint #{specifier.inspect} did not resolve: #{error.message}" }
+        nil
+      end
+
+      # Returns true when the root is collected, false when it failed.
+      def collect_root(module_id, force: false)
+        if force
+          @graph.collect_module(module_id, force: true)
+        else
+          @graph.records[module_id] || @graph.collect_module(module_id)
+        end
+        @failed.delete(module_id.to_s)
+        @graph.collect_reachable(module_id) do |reached_id, error|
+          if error
+            @failed[reached_id.to_s] = error
+          else
+            @failed.delete(reached_id.to_s)
+          end
+        end
+        true
+      rescue StandardError, ScriptError => error
+        @failed[module_id.to_s] = error
+        false
+      end
+
+      def dependents_closure(module_id_strings)
+        seen = Set.new(module_id_strings)
+        queue = module_id_strings.to_a
+
+        until queue.empty?
+          module_id_string = queue.shift
+          @graph.dependents(Klenod::Build::ModuleId.new(module_id_string)).each do |dependent_id|
+            queue << dependent_id.to_s if seen.add?(dependent_id.to_s)
+          end
+        end
+
+        seen
+      end
+    end
+  end
+end

data/lib/klenod/lsp/languages/css.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../diagnostics"
+require_relative "imports"
+require_relative "syntax"
+
+module Klenod
+  module LSP
+    module Languages
+      # Stylesheets under the source directory: build diagnostics plus
+      # navigation and completion for `@import`, `url()`, and `composes ...
+      # from` references, resolved the way the CSS plugin resolves them.
+      class CSS
+        include ImportNavigation
+
+        Interface = LanguageServer::Protocol::Interface
+
+        def syntax
+          Syntax::CSS
+        end
+
+        def diagnostics(analysis, _workspace = nil, _index = nil)
+          Diagnostics.for_analysis(analysis, syntax: syntax)
+        end
+
+        def completion(analysis, position, workspace, _index = nil)
+          line_text = analysis.lines[position.line]
+          return nil unless line_text
+
+          items = Imports.completion_items(line_text[0...position.character].to_s, position, analysis, workspace, syntax: syntax)
+          items && Interface::CompletionList.new(is_incomplete: false, items: items)
+        end
+
+        def document_symbols(_analysis)
+          []
+        end
+
+        def target_at(analysis, position)
+          line_text = analysis.lines[position.line]
+          line_text && Imports.target_at(line_text, position, syntax: syntax)
+        end
+      end
+    end
+  end
+end