lutaml-lml 0.3.2 → 0.3.4

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lutaml
+  module Lml
+    module Lsp
+      # LSP base protocol framing: `Content-Length: N\r\n\r\n<json>`.
+      # Reads one message at a time and writes responses to the output
+      # stream. stdout is the protocol channel; stderr is for logging.
+      class Transport
+        def initialize(input: $stdin, output: $stdout)
+          @input = input
+          @output = output
+        end
+
+        def read_message
+          headers = read_headers
+          return nil unless headers
+
+          length = headers["content-length"]
+          return nil unless length
+
+          body = @input.read(length.to_i)
+          body.nil? || body.empty? ? nil : JSON.parse(body)
+        end
+
+        def write_message(payload)
+          body = JSON.generate(payload)
+          @output.write("Content-Length: #{body.bytesize}\r\n\r\n#{body}")
+          @output.flush
+        end
+
+        private
+
+        def read_headers
+          headers = {}
+          loop do
+            line = @input.gets
+            return nil if line.nil?
+
+            line = line.chomp
+            break if line.empty?
+
+            key, value = line.split(":", 2)
+            headers[key.to_s.strip.downcase] = value.to_s.strip
+          end
+          headers
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/lml/lsp.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    # Language Server Protocol support: a stdio JSON-RPC server exposing
+    # diagnostics, symbols, navigation, hover, completion, and canonical
+    # formatting over the parsed document model.
+    module Lsp
+      autoload :Transport, "lutaml/lml/lsp/transport"
+      autoload :Server, "lutaml/lml/lsp/server"
+      autoload :Store, "lutaml/lml/lsp/store"
+      autoload :Keywords, "lutaml/lml/lsp/keywords"
+      autoload :Conversions, "lutaml/lml/lsp/conversions"
+    end
+  end
+end

data/lib/lutaml/lml/model_compiler.rb

@@ -73,6 +73,17 @@ module Lutaml
         return {} unless doc.instance
 
         hydrate_instance(doc.instance)
+      rescue Lutaml::Lml::Error
+        raise
+      rescue StandardError => e
+        raise HydrationError.new(
+          "hydration failed: #{e.message}",
+          diagnostic: Diagnostic.build(
+            'hydration/LML-H01',
+            message: e.message,
+            file: input.is_a?(Document) ? input.source_path : nil,
+          ),
+        )
       end
 
       def compiled_classes
@@ -236,7 +247,11 @@ module Lutaml
         return Float::INFINITY if UNBOUNDED_TOKENS.include?(val.to_s)
         return val.to_i if val.to_s.match?(/\A\d+\z/)
 
-        raise ValidationError, "Unrecognized cardinality token: #{val.inspect}"
+        message = "Unrecognized cardinality token: #{val.inspect}"
+        raise ValidationError.new(
+          message,
+          diagnostic: Diagnostic.build('contract/LML-C04', message: message),
+        )
       end
 
       def declare_derived_fields(compiled_klass, def_obj)

data/lib/lutaml/lml/models/association.rb

@@ -2,7 +2,10 @@
 
 module Lutaml
   module Lml
+    # A relationship between two class ends.
     class Association < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
       # From TopElement
       attribute :name, :string
       attribute :definition, Lutaml::Lml::Types::TextType

data/lib/lutaml/lml/models/constraint.rb

@@ -2,7 +2,10 @@
 
 module Lutaml
   module Lml
+    # A named constraint on a class.
     class Constraint < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
       # From TopElement
       attribute :name, :string
       attribute :definition, Lutaml::Lml::Types::TextType

data/lib/lutaml/lml/models/data_type.rb

@@ -2,7 +2,10 @@
 
 module Lutaml
   module Lml
+    # A user-defined data type declaration.
     class DataType < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
       # From TopElement
       attribute :name, :string
       attribute :wire_mappings, "Lutaml::Lml::Mapping", collection: true, default: -> { [] }

data/lib/lutaml/lml/models/diagram.rb

@@ -2,7 +2,10 @@
 
 module Lutaml
   module Lml
+    # A diagram declaration.
     class Diagram < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
       attribute :name, :string
       attribute :definition, Lutaml::Lml::Types::TextType
       attribute :keyword, :string

data/lib/lutaml/lml/models/document.rb

@@ -2,9 +2,18 @@
 
 module Lutaml
   module Lml
+    # The parsed LML document model.
     class Document < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
+      # Non-serialized navigation index (definitions and uses).
+      def symbols
+        @symbols ||= SymbolIndex.new(self)
+      end
+
       # Core attributes
       attribute :name, :string
+      attribute :lml_version, :string
       attribute :title, :string
       attribute :caption, :string
       attribute :groups, "Lutaml::Lml::Group", collection: true, default: -> { [] }
@@ -47,9 +56,7 @@ module Lutaml
       def merge_instances(incoming)
         names = @instances.collections.map(&:name)
         incoming.collections.each do |collection|
-          if names.include?(collection.name)
-            raise Lutaml::Lml::Error, "duplicate collection name '#{collection.name}'"
-          end
+          raise Lutaml::Lml::Error, "duplicate collection name '#{collection.name}'" if names.include?(collection.name)
         end
         @instances.instances.concat(incoming.instances)
         @instances.imports.concat(incoming.imports)

data/lib/lutaml/lml/models/enum.rb

@@ -2,7 +2,10 @@
 
 module Lutaml
   module Lml
+    # An enumeration declaration with its value members.
     class Enum < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
       # From TopElement
       attribute :name, :string
       attribute :definition, Lutaml::Lml::Types::TextType
@@ -15,7 +18,7 @@ module Lutaml
 
       # From Enum
       attribute :attributes, "Lutaml::Lml::TopElementAttribute", collection: true,
-                                                                   default: -> { [] }
+                                                                 default: -> { [] }
       attribute :modifier, :string
       attribute :member_fields, "Lutaml::Lml::MemberField", collection: true, default: -> { [] }
       attribute :from_table_name, :string

data/lib/lutaml/lml/models/instance.rb

@@ -2,7 +2,10 @@
 
 module Lutaml
   module Lml
+    # An instance with attribute assignments.
     class Instance < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
       attribute :name, :string
       attribute :type, :string
       attribute :isa, :string

data/lib/lutaml/lml/models/instance_collection.rb

@@ -2,7 +2,10 @@
 
 module Lutaml
   module Lml
+    # A named instances collection with its instances and imports/exports.
     class InstanceCollection < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
       attribute :name, :string
       attribute :instances, "Lutaml::Lml::Instance", collection: true, default: []
       attribute :imports, "Lutaml::Lml::InstancesImport", collection: true, default: []

data/lib/lutaml/lml/models/member_field.rb

@@ -5,6 +5,8 @@ module Lutaml
     # A typed payload field declared on an enum:
     #   member_fields { abbreviation String  urn_segment String }
     class MemberField < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
       attribute :name, :string
       attribute :type, :string
     end

data/lib/lutaml/lml/models/namespace.rb

@@ -6,6 +6,8 @@ module Lutaml
     # The compiler generates the corresponding Lutaml::Model::XmlNamespace
     # subclass for the compiled model namespace.
     class Namespace < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
       attribute :name, :string
       attribute :uri, :string
       attribute :prefix, :string

data/lib/lutaml/lml/models/operation.rb

@@ -2,7 +2,10 @@
 
 module Lutaml
   module Lml
+    # A class operation with parameters and a return type.
     class Operation < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
       # From TopElement
       attribute :name, :string
       attribute :definition, Lutaml::Lml::Types::TextType
@@ -17,7 +20,7 @@ module Lutaml
       attribute :is_static, :boolean, default: false
       attribute :is_abstract, :boolean, default: false
       attribute :owned_parameter, "Lutaml::Lml::OperationParameter", collection: true,
-                                                                          default: -> { [] }
+                                                                     default: -> { [] }
     end
   end
 end

data/lib/lutaml/lml/models/package.rb

@@ -2,7 +2,10 @@
 
 module Lutaml
   module Lml
+    # A package grouping model definitions.
     class Package < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
       # From TopElement
       attribute :name, :string
       attribute :definition, Lutaml::Lml::Types::TextType

data/lib/lutaml/lml/models/primitive_type.rb

@@ -2,7 +2,10 @@
 
 module Lutaml
   module Lml
+    # A primitive type declaration.
     class PrimitiveType < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
       # Primitives in LML are name-only entities, but the formatter
       # accesses the same attributes as DataType via format_class.
       attribute :name, :string
@@ -12,11 +15,11 @@ module Lutaml
       attribute :visibility, :string, default: "public"
       attribute :is_abstract, :boolean, default: false
       attribute :attributes, "Lutaml::Lml::TopElementAttribute", collection: true,
-                                                                   default: -> { [] }
+                                                                 default: -> { [] }
       attribute :operations, "Lutaml::Lml::Operation", collection: true,
-                                                         default: -> { [] }
+                                                       default: -> { [] }
       attribute :associations, "Lutaml::Lml::Association", collection: true,
-                                                             default: -> { [] }
+                                                           default: -> { [] }
 
       def self.entity_type
         :primitives

data/lib/lutaml/lml/models/serialization_mapping.rb

@@ -6,6 +6,8 @@ module Lutaml
     # its class and linked by target name —
     #   mapping xml Ceramic { element "ceramic" … }
     class SerializationMapping < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
       attribute :format, :string
       attribute :target, :string
       attribute :element_name, :string

data/lib/lutaml/lml/models/top_element_attribute.rb

@@ -2,7 +2,10 @@
 
 module Lutaml
   module Lml
+    # An attribute declaration or instance assignment entry.
     class TopElementAttribute < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
       # Core attributes
       attribute :name, :string
       attribute :visibility, :string, default: "public"

data/lib/lutaml/lml/models/uml_class.rb

@@ -2,7 +2,10 @@
 
 module Lutaml
   module Lml
+    # A class declaration with its members.
     class UmlClass < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
       # From TopElement. TextType unescapes \{ \} and normalizes lines
       # on every assignment (builder, yaml, direct).
       attribute :name, :string

data/lib/lutaml/lml/models/value.rb

@@ -2,7 +2,10 @@
 
 module Lutaml
   module Lml
+    # A value construct member.
     class Value < Lutaml::Model::Serializable
+      include Lutaml::Lml::Positioned
+
       attribute :name, :string
       attribute :id, :string
       attribute :type, :string

data/lib/lutaml/lml/pipeline.rb

@@ -29,7 +29,18 @@ module Lutaml
       def parse_raw(data)
         Transform.new.apply(Parser.new.parse(data))
       rescue Parsanol::ParseFailed => e
-        raise(ParsingError, failure_message(e))
+        raise ParsingError.new(failure_message(e), diagnostic: parse_diagnostic(e))
+      end
+
+      def parse_diagnostic(error)
+        line, column = failure_location(error)
+        Diagnostic.build(
+          'parse/LML-001',
+          message: error.message.lines.first.to_s.strip,
+          file: @input.path,
+          line: line,
+          column: column,
+        )
       end
 
       # Parsanol releases up to 1.3.57 annotate native failures with a
@@ -38,18 +49,24 @@ module Lutaml
       # rebuild the location when the marker is present.
       def failure_message(error)
         detail = error.message.lines.first.to_s.strip
+        line, column = failure_location(error)
+        location = (" at line #{line} char #{column}." if line && !detail.match?(/at line \d+ char \d+/))
+        "#{detail}#{location}\ncause: #{error.parse_failure_cause&.ascii_tree}"
+      end
+
+      def failure_location(error)
         cause = error.parse_failure_cause
         offset = error.message[/@@parsanol_pos:(\d+)/, 1]&.to_i
-        location =
-          if offset && cause&.source
-            line, column = cause.source.line_and_column(offset)
-            " at line #{line} char #{column}."
-          end
-        "#{detail}#{location}\ncause: #{cause&.ascii_tree}"
+        return cause.source.line_and_column(offset) if offset && cause&.source
+
+        match = error.message.match(/at line (\d+) char (\d+)/)
+        match ? [match[1].to_i, match[2].to_i] : [nil, nil]
       end
 
       def build_document(hash)
-        DocumentBuilder.new(DocumentBuilder::DEFAULT_REGISTRY).build(:document, hash)
+        document = DocumentBuilder.new(DocumentBuilder::DEFAULT_REGISTRY).build(:document, hash)
+        document.source_path = @input.path
+        document
       end
     end
   end

data/lib/lutaml/lml/positioned.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    # Non-serialized source metadata carried by parsed entities. These
+    # accessors are deliberately not lutaml-model attributes: positions
+    # and the source path are diagnostics metadata, not document data,
+    # and must not appear in to_hash/YAML/JSON output.
+    module Positioned
+      attr_accessor :source_position, :source_path
+    end
+  end
+end

data/lib/lutaml/lml/preprocessor.rb

@@ -2,6 +2,8 @@
 
 module Lutaml
   module Lml
+    # Expands `include` directives before parsing. Unterminated block
+    # comments are rejected here; line comments are grammar trivia.
     class Preprocessor
       attr_reader :input_file
 
@@ -16,7 +18,7 @@ module Lutaml
       end
 
       def call
-        expand_lines(@input_file.read, @input_file.base_dir, [])
+        expand_lines(@input_file.read, @input_file.base_dir, [], @input_file.path)
       end
 
       private
@@ -25,24 +27,38 @@ module Lutaml
       # skip (parsanol-ruby#134); only include directives are expanded
       # here. Line structure is preserved so parse-error positions
       # match the source.
-      def expand_lines(text, base_dir, chain)
-        validate_block_comments(text)
+      def expand_lines(text, base_dir, chain, file_path)
+        validate_block_comments(text, file_path)
         text.split(/\r?\n/)
-            .flat_map { |line| expand_line(line, base_dir, chain) }
+            .each_with_index
+            .flat_map { |line, index| expand_line(line, base_dir, chain, file_path, index + 1) }
             .join("\n")
       end
 
-      def expand_line(line, base_dir, chain)
+      def expand_line(line, base_dir, chain, file_path, line_number)
         path = include_path(line, base_dir)
         return [line] unless path
 
-        raise Error, "circular include detected: #{path}" if chain.include?(path)
+        if chain.include?(path)
+          raise Error.new(
+            "circular include detected: #{path}",
+            diagnostic: Diagnostic.build(
+              'parse/LML-003',
+              message: "circular include detected: #{path}",
+              file: file_path, line: line_number, column: 1
+            ),
+          )
+        end
 
-        expand_lines(read_included(path), File.dirname(path), chain + [path])
+        expand_lines(read_included(path, file_path, line_number),
+                     File.dirname(path), chain + [path], path)
       end
 
       def include_path(line, base_dir)
-        match = line.match(/^\s*include\s+(.+)$/)
+        # Linear-time match: `\S.*` cannot overlap the leading `[ \t]+`,
+        # so a line of spaces after `include` fails in O(n) rather than
+        # backtracking quadratically (CodeQL ReDoS).
+        match = line.match(/\A[ \t]*include[ \t]+(\S.*)\z/)
         return nil unless match
 
         File.expand_path(trim_trailing_comment(match[1].strip), base_dir)
@@ -52,17 +68,24 @@ module Lutaml
         path.sub(%r{\s+(//|/\*).*}, '')
       end
 
-      def read_included(path)
+      def read_included(path, file_path, line_number)
         File.read(path, encoding: 'UTF-8')
-      rescue Errno::ENOENT, Errno::EACCES => e
-        raise Error, "cannot read include #{path}: #{e.message}"
+      rescue SystemCallError => e
+        raise Error.new(
+          "cannot read include #{path}: #{e.message}",
+          diagnostic: Diagnostic.build(
+            'parse/LML-003',
+            message: "cannot read include: #{path}",
+            file: file_path, line: line_number, column: 1
+          ),
+        )
       end
 
       # Quote-aware scan: a `/*` opened outside a string literal or a
       # line comment must close before end of input. The grammar's
       # trivia would otherwise reject the text with an unrelated
       # expected-token error.
-      def validate_block_comments(text)
+      def validate_block_comments(text, file_path)
         quote = nil
         pos = 0
         open_index = nil
@@ -92,7 +115,15 @@ module Lutaml
         return unless open_index
 
         line = text[0...open_index].count("\n") + 1
-        raise Error, "unterminated block comment at line #{line}"
+        column = open_index - (text.rindex("\n", open_index) || -1)
+        raise Error.new(
+          "unterminated block comment at line #{line}",
+          diagnostic: Diagnostic.build(
+            'parse/LML-002',
+            message: 'unterminated block comment',
+            file: file_path, line: line, column: column
+          ),
+        )
       end
     end
   end

data/lib/lutaml/lml/quoting.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    # The single source of truth for scalar quoting on the emit side:
+    # bare only for runs of [A-Za-z0-9_] (the grammar's word rule);
+    # double quotes with the two RS 3001 escapes otherwise. Values,
+    # attribute keys, and the canonical form all emit through here.
+    module Quoting
+      BARE_WORD = /\A\w+\z/
+
+      module_function
+
+      # @param scalar [String, #to_s]
+      # @return [String] the emitted form: parseable back to scalar
+      def quote_scalar(scalar)
+        str = scalar.to_s
+        return str if str.match?(BARE_WORD)
+
+        quote_always(str)
+      end
+
+      # Double-quoted form even when the scalar is a bare word. Used
+      # where the grammar only accepts quoted strings (definitions,
+      # requires, instance data values, wire names).
+      #
+      # @param scalar [String, #to_s]
+      # @return [String] the double-quoted, escaped form
+      def quote_always(scalar)
+        escaped = scalar.to_s.gsub('\\') { |bs| bs * 2 }.gsub('"') { |q| "\\#{q}" }
+        "\"#{escaped}\""
+      end
+
+      # Float#to_s may use exponent notation, for which the language has
+      # no literal. Expand it to a plain decimal that parses back to the
+      # same Float.
+      #
+      # @param number [Numeric]
+      # @return [String] the emitted form
+      def number_scalar(number)
+        text = number.to_s
+        match = text.match(/\A(-?)(\d+)(?:\.(\d+))?[eE]([+-]?\d+)\z/)
+        return text unless match
+
+        integer = match[2]
+        digits = integer + match[3].to_s
+        point = integer.length + match[4].to_i
+        plain =
+          if point <= 0
+            "0.#{'0' * -point}#{digits}"
+          elsif point >= digits.length
+            "#{digits}#{'0' * (point - digits.length)}.0"
+          else
+            "#{digits[0...point]}.#{digits[point..]}"
+          end
+        "#{match[1]}#{plain}"
+      end
+    end
+  end
+end

data/lib/lutaml/lml/source_position.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    # A position in the parsed source: 1-based line and column, with the
+    # byte offset and captured length when the parser provides them.
+    # Attached to model objects as non-serialized metadata so diagnostics
+    # can cite it without changing the document model's wire form.
+    class SourcePosition
+      attr_reader :line, :column, :offset, :length
+
+      def initialize(line:, column:, offset: nil, length: nil)
+        @line = line
+        @column = column
+        @offset = offset
+        @length = length
+      end
+    end
+  end
+end