lutaml-lml 0.3.3 → 0.3.5

data/lib/lutaml/lml/grammar/lml.parg

@@ -9,7 +9,28 @@
 # capture binds the whole match (Parslet's `.repeat.as(:x)` shape);
 # `[ x as k ]` yields k: nil when absent (Parslet omits the key —
 # consumers treat nil and absent as equivalent).
-grammar Lml version "1.0.0" {
+grammar Lml version "1.0.0" edition 2 {
+  # ---- Glue (parsanol-ruby#364) ----
+  # Edition 2 names every uncaptured rule reference; these are the
+  # token mechanics the tree must not see: separators that eat `;` and
+  # comments, verbatim-scan classes, quote delimiters, identifier
+  # runs and keyword tokens. Declaring the whole chain keeps the tree
+  # the authored captures only — byte-identical to edition 1 (the
+  # corpus differential proves it). Un-glue a rule when its node
+  # should surface.
+  glue whitespace line_comment block_comment
+  glue any_char quotes
+  glue word nonspace class_run class_name_chars type_run type_token quoted_name_run
+  glue definition_content
+  glue kw_abstract_sp kw_artifact_sp kw_association_sp kw_attribute_sp kw_caption_sp
+  glue kw_class_sp kw_collection_sp kw_condition_sp kw_data_type_sp kw_definition_sp
+  glue kw_derive_sp kw_element_sp kw_enum_sp kw_fontname_sp kw_format_sp kw_hide_sp
+  glue kw_import_sp kw_instance_sp kw_isa_sp kw_lml_sp kw_map_attribute_sp kw_map_content_sp
+  glue kw_map_element_sp kw_map_key_sp kw_map_sp kw_map_value_sp kw_mapping_sp kw_member_sp
+  glue kw_member_type_sp kw_namespace_sp kw_owner_sp kw_owner_type_sp kw_package_sp
+  glue kw_pattern_sp kw_prefix_sp kw_primitive_sp kw_require_sp kw_show_sp
+  glue kw_string_format_sp kw_title_sp kw_to_instance_sp kw_uri_sp kw_value_sp
+  glue kw_values_sp kw_version_sp kw_visibility_sp
   # ---- Trivia (parsanol-ruby#134 skip rule) ----
   # Grammar-native trivia replaces the pre-parse comment stripping:
   # `//` line and `/* */` block comments (RS 3001 par. Comment) plus
@@ -29,6 +50,11 @@ grammar Lml version "1.0.0" {
   atomic kw_visibility_sp = "visibility" 1*" "
   atomic kw_version_sp = "version" 1*" "
   version_declaration = kw_version_sp quoted_string as version
+  # ---- Language version ----
+  # `lml "1.0"` prologue: the grammar version a document speaks. It is
+  # optional and, when present, comes before every other construct.
+  atomic kw_lml_sp = "lml" 1*" "
+  lml_prologue = [ whitespace ] kw_lml_sp quoted_string as lml_version
   atomic kw_abstract_sp = "abstract" 1*" "
   atomic kw_collection_sp = "collection" 1*" "
   atomic kw_condition_sp = "condition" 1*" "
@@ -96,7 +122,7 @@ grammar Lml version "1.0.0" {
 
   boolean = ( "true" / "false" ) as boolean
   null_literal = "null" as null
-  number = ( 1*%x30-39 "." 1*%x30-39 ) as float / ( 1*%x30-39 ) as number
+  number = ( [ "-" ] 1*%x30-39 "." 1*%x30-39 ) as float / ( [ "-" ] 1*%x30-39 ) as number
   variable = quoted_string / 1*word
   reference = ( "reference:(" / "ref:(" ) ( variable *( "." variable ) ) as reference ")"
   range = ( variable as start ".." variable as end ) as range
@@ -131,14 +157,17 @@ grammar Lml version "1.0.0" {
   visibility = kw_visibility_modifier as visibility_modifier
   attribute_stereotype = "<<" ( 1*( %x41-5A / %x61-7A / %x30-39 / "_" / "-" / "/" ) ) as stereotype ">>"
   atomic type_run = 1*( !( "//" / "/*" ) ( %x41-5A / %x61-7A / %x30-39 / "_" / "-" / ":" / "/" / "+" ) )
-  atomic type_token = type_run *( %x20 type_run )
+  atomic type_token = type_run *( %x20 !( "as" 1*" " ":" ) type_run )
   atomic namechar = %x41-5A / %x61-7A / %x30-39 / "_" / "-" / "/" / "+"
   attribute_type = [ ":" ] [ attribute_stereotype ] [ quotes as type_literal ] ( type_token ) as type [ quotes ]
   attribute_name = ( 1*namechar ) as name
   atomic quoted_name_run = 1*( %x41-5A / %x61-7A / %x30-39 / "_" / "-" / "/" / "+" )
   atomic quoted_name_body = quoted_name_run *( %x20 quoted_name_run )
   attribute_definition_name = ( quotes ( quoted_name_body ) as name quotes ) / attribute_name
-  attribute_definition = ( [ visibility ] as visibility attribute_definition_name [ attribute_type ] [ cardinality ] [ class_body ] ) as attributes
+  # Issue lutaml/lutaml#49: `as :element` / `as :attribute` picks the XML
+  # node kind of an attribute (lutaml-model map_element / map_attribute).
+  atomic xml_role_suffix = "as" 1*" " ":" ( ( "element" / "attribute" ) as xml_role )
+  attribute_definition = ( [ visibility ] as visibility attribute_definition_name [ attribute_type ] [ cardinality ] [ xml_role_suffix ] [ class_body ] ) as attributes
 
   keyword_type_argument = "type" ( 1*nonspace ) as type [ whitespace ]
   keyword_cardinality_argument = "cardinality" cardinality_body_definition as cardinality [ whitespace ]
@@ -149,7 +178,7 @@ grammar Lml version "1.0.0" {
   value_set_body = "{" [ whitespace ] ( *( ( ( data_value / variable ) as item ) [ "," ] [ whitespace ] ) ) as items "}"
   keyword_attribute_options = *( keyword_type_argument / keyword_cardinality_argument / keyword_values_argument / keyword_pattern_argument / ( keyword_any_argument ) as properties )
   keyword_attribute_body = "{" [ whitespace ] keyword_attribute_options [ whitespace ] "}"
-  keyword_attribute_definition = ( kw_attribute_sp attribute_name keyword_attribute_body ) as attributes
+  keyword_attribute_definition = ( kw_attribute_sp attribute_name [ xml_role_suffix ] keyword_attribute_body ) as attributes
 
   # ---- Associations ----
   owner_cardinality = "[" cardinality_body_definition as owner_end_cardinality "]"
@@ -230,7 +259,10 @@ grammar Lml version "1.0.0" {
   string_format_body = "{" [ whitespace ] ( *( string_format_item ) ) as items [ whitespace ] "}"
   string_format_definition = ( [ whitespace ] kw_string_format_sp ( variable ) as format string_format_body ) as string_format
 
-  class_inner_definitions = visibility_declaration / abstract_declaration / definition_body / definition_line / class_mapping_section / derive_definition / string_format_definition / ( operation_definition ) as operations / attribute_comma_definition / ( !( kw_attribute_sp ) attribute_definition ) / keyword_attribute_definition / comment_definition / comment_multiline_definition
+  # Issue lutaml/lutaml#49: a quoted `namespace "uri" [prefix "p"]` line
+  # inside a class declares the class's XML namespace.
+  class_namespace_definition = ( kw_namespace_sp ( quoted_string ) as uri [ kw_prefix_sp ( quoted_string / ( 1*word ) ) as prefix ] ) as class_namespace [ whitespace ]
+  class_inner_definitions = class_namespace_definition / visibility_declaration / abstract_declaration / definition_body / definition_line / class_mapping_section / derive_definition / string_format_definition / ( operation_definition ) as operations / attribute_comma_definition / ( !( kw_attribute_sp ) attribute_definition ) / keyword_attribute_definition / comment_definition / comment_multiline_definition
   class_inner_definition = class_inner_definitions [ whitespace ]
   class_body = "{" [ whitespace ] ( *( class_inner_definition ) ) as members "}"
   parent_class = "<" ( class_name_chars ) as parent_class
@@ -306,11 +338,11 @@ grammar Lml version "1.0.0" {
   instance_named = ( [ whitespace ] kw_instance_sp quoted_string as name [ ( namespaced_identifier ) as instance_type ] "{" [ whitespace ] ( ( instance ) / attributes ) "}" [ whitespace ] ) as instance
   isa_definition = [ whitespace ] kw_isa_sp ( namespaced_identifier ) as isa [ whitespace ]
   keyword_instance = ( [ whitespace ] "instance" [ ( namespaced_identifier ) as instance_type ] "{" [ whitespace ] [ isa_definition ] ( ( instance ) / attributes ) "}" ) as instance [ whitespace ]
-  class_instance = ( variable as instance_type [ whitespace ] quoted_string as name [ whitespace ] [ [ whitespace ] "extends" [ whitespace ] quoted_string as parent [ whitespace ] ] "{" [ whitespace ] [ lml_instance_body ] "}" ) as instance [ whitespace ]
+  class_instance = ( [ whitespace ] variable as instance_type [ whitespace ] quoted_string as name [ whitespace ] [ [ whitespace ] "extends" [ whitespace ] quoted_string as parent [ whitespace ] ] "{" [ whitespace ] [ lml_instance_body ] "}" ) as instance [ whitespace ]
   lml_instance_body = lml_instance_members [ whitespace ]
   instance_template = [ whitespace ] "template" [ whitespace ] "{" [ whitespace ] attributes [ whitespace ] "}"
   lml_instance_members = ( instance_template ) as template / attributes
-  models = [ whitespace ] "models" [ whitespace ] variable as name [ version_declaration ] [ whitespace ] "{" ( *( ( ( string_format_definition ) as default_string_formats ) / model_body ) ) as members "}" [ whitespace ]
+  models = [ whitespace ] "models" [ whitespace ] variable as name [ version_declaration ] [ whitespace ] "{" [ whitespace ] ( *( ( ( string_format_definition ) as default_string_formats ) / model_body ) ) as members "}" [ whitespace ]
   model_body = diagram_inner_definition
 
   # ---- Data structures ----
@@ -330,7 +362,7 @@ grammar Lml version "1.0.0" {
   export_format = [ whitespace ] kw_format_sp variable as format_type [ whitespace ] "{" [ whitespace ] attributes "}" [ whitespace ]
 
   # ---- Root (RS 3001: a document interleaves declarations) ----
-  diagram = [ require_block ] ( *( top_level_definition ) ) as members
+  diagram = [ lml_prologue ] [ require_block ] ( *( top_level_definition ) ) as members
 
   top_level_definition = ( models / diagram_definitions / view_definitions / instances / instance / model_definitions ) [ whitespace ]
 }
@@ -342,6 +374,12 @@ entry diagram: diagram
 test diagram {
   accept "// leading\nclass Ceramic { }\n"
   accept "class /* inline */ Ceramic { }\n"
+  accept "lml \"1.0\"\nclass A { }\n"
+  accept "lml \"1.0\"\n\nThing \"t0\" { }\n"
+  reject "lml 1.0\nclass A { }\n"
+  accept "models M {\n}\n"
+  accept "instance X {\n  a = -42\n}\n"
+  accept "models M { }"
   accept "class Ceramic { } // trailing"
   accept "instances {\n  P \"p\" {\n    url = \"http://a//b\"\n  }\n}\n"
   reject "classCeramic Foo { }"

data/lib/lutaml/lml/grammar.rb

@@ -20,6 +20,19 @@ module Lutaml
       GRAMMAR_PATH = File.expand_path('grammar/lml.parg', __dir__)
       ARTIFACT_PATH = File.expand_path('grammar/lml.artifact.json', __dir__)
 
+      # The language version this build implements, read from the
+      # compiled artifact (falling back to the grammar text when the
+      # artifact is absent). Version negotiation compares document
+      # prologues against it.
+      def self.version
+        @version ||= begin
+          envelope = JSON.parse(File.read(ARTIFACT_PATH, encoding: 'UTF-8'))
+          envelope['version'].to_s
+        rescue StandardError
+          File.read(GRAMMAR_PATH, encoding: 'UTF-8')[/grammar \w+ version "([^"]+)"/, 1] || '0.0.0'
+        end
+      end
+
       def self.artifact
         @artifact ||= load_artifact || compile_artifact
       end

data/lib/lutaml/lml/import_resolver.rb

@@ -4,6 +4,7 @@ require "set"
 
 module Lutaml
   module Lml
+    # Resolves `view import` paths and merges the imported entities.
     class ImportResolver
       def initialize(base_dir)
         @base_dir = base_dir
@@ -24,7 +25,16 @@ module Lutaml
 
         collect_local_entities(document, entity_index, associations)
 
-        raise ImportError, @failures.join("\n") if @failures.any?
+        if @failures.any?
+          raise ImportError.new(
+            @failures.join("\n"),
+            diagnostic: Diagnostic.build(
+              'contract/LML-C05',
+              message: @failures.first,
+              file: document.source_path,
+            ),
+          )
+        end
 
         [entity_index, associations]
       end
@@ -34,12 +44,11 @@ module Lutaml
       def resolve_import(path, entity_index, associations, visited, base_dir)
         abs_pattern = File.expand_path(path, base_dir)
         files = Dir.glob(abs_pattern)
-        if files.empty?
-          @failures << "import matched no files: #{path} (resolved to #{abs_pattern})"
-        end
+        @failures << "import matched no files: #{path} (resolved to #{abs_pattern})" if files.empty?
 
         files.each do |file_path|
           next if visited.include?(file_path)
+
           visited.add(file_path)
 
           doc = parse_file(file_path)

data/lib/lutaml/lml/lsp/conversions.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Lutaml
+  module Lml
+    module Lsp
+      # Conversions between the parser's 1-based positions and LSP's
+      # 0-based positions, plus diagnostic records.
+      module Conversions
+        module_function
+
+        def position(source_position)
+          return { line: 0, character: 0 } unless source_position
+
+          {
+            line: source_position.line.to_i - 1,
+            character: source_position.column.to_i - 1,
+          }
+        end
+
+        def range(source_position)
+          start = position(source_position)
+          {
+            start: start,
+            end: {
+              line: start[:line],
+              character: start[:character] + source_position.length.to_i,
+            },
+          }
+        end
+
+        def diagnostic(record)
+          {
+            range: diagnostic_range(record),
+            severity: severity(record.severity),
+            code: record.code,
+            source: "lutaml-lml",
+            message: diagnostic_message(record),
+          }
+        end
+
+        def diagnostic_range(record)
+          line = [record.line.to_i - 1, 0].max
+          character = [record.column.to_i - 1, 0].max
+          length = record.length.to_i
+          length = 1 if length.zero?
+          {
+            start: { line: line, character: character },
+            end: { line: line, character: character + length },
+          }
+        end
+
+        def diagnostic_message(record)
+          return record.message.to_s if record.remedy.to_s.empty?
+
+          "#{record.message}\nremedy: #{record.remedy}"
+        end
+
+        def severity(value)
+          value.to_s == "warning" ? 2 : 1
+        end
+
+        # file:///path → local path. Windows drive paths lose the leading
+        # slash (file:///C:/x → C:/x).
+        def uri_to_path(uri)
+          path = uri.to_s.sub(%r{\Afile://}, "")
+          path = CGI.unescape(path)
+          path.sub(%r{\A/([A-Za-z]:/)}, '\1')
+        end
+
+        def path_to_uri(path)
+          "file://#{CGI.escape(path.to_s).gsub('+', '%20')}"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/lml/lsp/keywords.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lutaml
+  module Lml
+    module Lsp
+      # The completion keyword list, read from the compiled grammar
+      # artifact so it cannot drift from the language.
+      module Keywords
+        ARTIFACT = File.expand_path("../grammar/lml.artifact.json", __dir__)
+
+        module_function
+
+        def all
+          @all ||= begin
+            artifact = JSON.parse(File.read(ARTIFACT))
+            literals = []
+            collect(artifact["entries"], literals)
+            literals.grep(/\A[a-z][a-z0-9_]*\z/)
+                    .uniq
+                    .sort
+          end
+        end
+
+        def collect(node, literals)
+          case node
+          when Hash
+            node.each do |key, value|
+              if key.to_s == "Str" && value.is_a?(Hash)
+                literals << value["pattern"].to_s
+              else
+                collect(value, literals)
+              end
+            end
+          when Array
+            node.each { |item| collect(item, literals) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/lml/lsp/server.rb

@@ -0,0 +1,378 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    module Lsp
+      # The stdio JSON-RPC server. One message at a time; every document
+      # change reparses the full text. Errors are contained per message
+      # so a broken document never crashes the server.
+      class Server
+        WORD = /[A-Za-z0-9_:.-]/
+
+        CAPABILITIES = {
+          textDocumentSync: 1,
+          documentSymbolProvider: true,
+          definitionProvider: true,
+          referencesProvider: true,
+          hoverProvider: true,
+          completionProvider: { triggerCharacters: [' ', ':'] },
+          documentFormattingProvider: true,
+          diagnosticProvider: {
+            interFileDependencies: false,
+            workspaceDiagnostics: false,
+          },
+        }.freeze
+
+        def initialize(transport: Transport.new, store: Store.new)
+          @transport = transport
+          @store = store
+          @shutdown = false
+          @stopped = false
+        end
+
+        # Runs the message loop; returns the process exit code.
+        def run
+          until @stopped
+            message = @transport.read_message
+            break if message.nil?
+
+            dispatch(message)
+          end
+          @shutdown ? 0 : 1
+        end
+
+        private
+
+        def dispatch(message)
+          id = message['id']
+          method = message['method']
+          params = message['params'] || {}
+
+          case method
+          when 'initialize' then respond(id, initialize_result)
+          when 'initialized' then nil
+          when 'shutdown'
+            @shutdown = true
+            respond(id, nil)
+          when 'exit'
+            @stopped = true
+          when 'textDocument/didOpen' then did_open(params)
+          when 'textDocument/didChange' then did_change(params)
+          when 'textDocument/didClose' then did_close(params)
+          when 'textDocument/diagnostic' then respond(id, diagnostic_report(params))
+          when 'textDocument/documentSymbol' then respond(id, document_symbols(params))
+          when 'textDocument/definition' then respond(id, definition(params))
+          when 'textDocument/references' then respond(id, references(params))
+          when 'textDocument/hover' then respond(id, hover(params))
+          when 'textDocument/completion' then respond(id, completion(params))
+          when 'textDocument/formatting' then respond(id, formatting(params))
+          else
+            respond_error(id, -32_601, "Method not found: #{method}") unless id.nil?
+          end
+        rescue StandardError => e
+          respond_error(id, -32_603, e.message) unless id.nil?
+        end
+
+        def initialize_result
+          {
+            capabilities: CAPABILITIES,
+            serverInfo: { name: 'lutaml-lml-lsp', version: Lutaml::Lml::VERSION },
+          }
+        end
+
+        # ---- documents ----
+
+        def did_open(params)
+          document = params['textDocument'] || {}
+          entry = @store.open(
+            uri: document['uri'], text: document['text'].to_s,
+            version: document['version']
+          )
+          publish(entry)
+        end
+
+        def did_change(params)
+          document = params['textDocument'] || {}
+          changes = params['contentChanges'] || []
+          text = changes.last.is_a?(Hash) ? changes.last['text'].to_s : ''
+          entry = @store.change(
+            uri: document['uri'], text: text, version: document['version'],
+          )
+          publish(entry) if entry
+        end
+
+        def did_close(params)
+          document = params['textDocument'] || {}
+          uri = document['uri']
+          @store.close(uri)
+          @transport.write_message(
+            jsonrpc: '2.0', method: 'textDocument/publishDiagnostics',
+            params: { uri: uri, diagnostics: [] }
+          )
+        end
+
+        def publish(entry)
+          @transport.write_message(
+            jsonrpc: '2.0', method: 'textDocument/publishDiagnostics',
+            params: {
+              uri: entry.uri,
+              diagnostics: entry.diagnostics.map { |record| Conversions.diagnostic(record) },
+            }
+          )
+        end
+
+        def diagnostic_report(params)
+          entry = entry_for(params)
+          return { kind: 'full', items: [] } unless entry
+
+          {
+            kind: 'full',
+            items: entry.diagnostics.map { |record| Conversions.diagnostic(record) },
+          }
+        end
+
+        # ---- symbols ----
+
+        def document_symbols(params)
+          entry = entry_for(params)
+          return [] unless entry&.model
+
+          SymbolIndex.new(entry.model).entries.map do |symbol|
+            {
+              name: symbol.name,
+              kind: SymbolIndex::KINDS.fetch(symbol.kind),
+              location: location(entry.uri, symbol.position),
+              containerName: symbol.container,
+            }.compact
+          end
+        end
+
+        def definition(params)
+          entry = entry_for(params)
+          return nil unless entry&.model
+
+          token = token_at(entry, params['position'])
+          return nil if token.empty?
+
+          index = SymbolIndex.new(entry.model)
+          locations = resolve(index, token).map { |symbol| location(entry.uri, symbol.position) }
+          locations.empty? ? nil : locations
+        end
+
+        def references(params)
+          entry = entry_for(params)
+          return [] unless entry&.model
+
+          token = token_at(entry, params['position'])
+          return [] if token.empty?
+
+          index = SymbolIndex.new(entry.model)
+          symbols = index.uses(token)
+          symbols += index.definitions(token) if params.dig('context', 'includeDeclaration')
+
+          symbols.map { |symbol| location(entry.uri, symbol.position) }.uniq
+        end
+
+        def hover(params)
+          entry = entry_for(params)
+          return nil unless entry&.model
+
+          position = params['position']
+          token = token_at(entry, position)
+          return nil if token.empty?
+
+          symbol = resolve(SymbolIndex.new(entry.model), token).first
+          return nil unless symbol
+
+          {
+            contents: { kind: 'markdown', value: hover_markdown(symbol) },
+            range: token_range(entry, position, token),
+          }
+        end
+
+        def hover_markdown(symbol)
+          case symbol.kind
+          when :class then class_markdown(symbol.record)
+          when :enum then enum_markdown(symbol.record)
+          when :field then field_markdown(symbol.record)
+          when :instance then instance_markdown(symbol.record)
+          when :enum_member then enum_member_markdown(symbol.record)
+          else "**#{symbol.name}**"
+          end
+        end
+
+        def class_markdown(klass)
+          text = "```lml\nclass #{klass.name}"
+          text << " < #{klass.parent_class}" unless klass.parent_class.to_s.empty?
+          text << "\n```"
+          append_definition(text, klass.definition)
+        end
+
+        def enum_markdown(enum)
+          members = Array(enum.attributes).map { |member| member.name.to_s }
+          text = "```lml\nenum #{enum.name}\n```"
+          text << "\n\nMembers: #{members.join(', ')}" unless members.empty?
+          append_definition(text, enum.definition)
+        end
+
+        def field_markdown(attribute)
+          label = attribute.name.to_s
+          type = attribute.type.to_s
+          text = "```lml\n#{label}"
+          text << ": #{type}" unless type.empty?
+          cardinality = attribute.cardinality
+          if cardinality
+            max = cardinality.max.to_s
+            text << " [#{cardinality.min}#{"..#{max}" unless max.empty?}]"
+          end
+          text << "\n```"
+          text << "\n\ndefault: `#{attribute.default}`" if attribute.default
+          text << "\npattern: `#{attribute.pattern}`" if attribute.pattern
+          text << "\nvalues: #{attribute.value_set.join(', ')}" if Array(attribute.value_set).any?
+          append_definition(text, attribute.definition)
+          text << "\n\n`null`, `\"\"`, and an unassigned attribute are distinct." if type == 'String'
+          text
+        end
+
+        def instance_markdown(instance)
+          label = instance.type.to_s.empty? ? instance.name.to_s : instance.type.to_s
+          text = "```lml\ninstance #{label}\n```"
+          text << "\n\n#{Array(instance.attributes).size} assignment(s)"
+          text
+        end
+
+        def enum_member_markdown(member)
+          text = "**value #{member.name}**"
+          description = Array(member.attributes).find { |attribute| attribute.name == 'description' }
+          text << "\n\n#{description.type}" if description
+          text
+        end
+
+        def append_definition(text, definition)
+          value = definition.to_s
+          text << "\n\n#{value}" unless value.empty?
+          text
+        end
+
+        # ---- completion ----
+
+        def completion(params)
+          entry = entry_for(params)
+          prefix = completion_prefix(entry, params['position'])
+          items = completion_items(entry)
+          items = items.select { |item| item[:label].start_with?(prefix) } unless prefix.empty?
+
+          { isIncomplete: false, items: items }
+        end
+
+        def completion_items(entry)
+          items = Keywords.all.map do |keyword|
+            { label: keyword, kind: 14, detail: 'LML keyword' }
+          end
+          return dedupe(items) unless entry&.model
+
+          index = SymbolIndex.new(entry.model)
+          index.entity_entries.each do |symbol|
+            items << {
+              label: symbol.name,
+              kind: SymbolIndex::KINDS.fetch(symbol.kind),
+              detail: symbol.detail || symbol.container,
+            }
+          end
+          index.attribute_entries.each do |symbol|
+            items << { label: symbol.name, kind: 8, detail: symbol.detail }
+          end
+          dedupe(items)
+        end
+
+        def dedupe(items)
+          seen = {}
+          items.each_with_object([]) do |item, result|
+            next if seen[item[:label]]
+
+            seen[item[:label]] = true
+            result << item.compact
+          end
+        end
+
+        # ---- formatting ----
+
+        def formatting(params)
+          entry = entry_for(params)
+          return nil unless entry&.model
+
+          canonical = Lutaml::Formatter::Canonical.new(entry.model).render
+          return [] if canonical == entry.text
+
+          [{ range: full_range(entry.text), newText: canonical }]
+        end
+
+        def full_range(text)
+          {
+            start: { line: 0, character: 0 },
+            end: { line: text.lines.length, character: 0 },
+          }
+        end
+
+        # ---- helpers ----
+
+        def entry_for(params)
+          document = params['textDocument'] || {}
+          @store[document['uri']]
+        end
+
+        def location(uri, position)
+          { uri: uri, range: Conversions.range(position) }
+        end
+
+        def resolve(index, token)
+          symbols = index.definitions(token)
+          return symbols unless symbols.empty?
+
+          token.split('.').flat_map { |segment| index.definitions(segment) }.uniq
+        end
+
+        def token_at(entry, position)
+          line = entry.text.lines[position['line'].to_i].to_s
+          index = [position['character'].to_i, line.length].min
+          start = index
+          start -= 1 while start.positive? && line[start - 1].match?(WORD)
+          finish = index
+          finish += 1 while finish < line.length && line[finish].match?(WORD)
+          line[start...finish].to_s
+        end
+
+        def token_range(entry, position, token)
+          line = entry.text.lines[position['line'].to_i].to_s
+          finish = [position['character'].to_i, line.length].min
+          start = [finish - token.length, 0].max
+          {
+            start: { line: position['line'].to_i, character: start },
+            end: { line: position['line'].to_i, character: start + token.length },
+          }
+        end
+
+        def completion_prefix(entry, position)
+          return '' unless entry
+
+          line = entry.text.lines[position['line'].to_i].to_s
+          before = line[0...[position['character'].to_i, line.length].min].to_s
+          before[/[A-Za-z0-9_]*\z/].to_s
+        end
+
+        def respond(id, result)
+          return if id.nil?
+
+          @transport.write_message(jsonrpc: '2.0', id: id, result: result)
+        end
+
+        def respond_error(id, code, message)
+          @transport.write_message(
+            jsonrpc: '2.0', id: id,
+            error: { code: code, message: message }
+          )
+        end
+      end
+    end
+  end
+end