lutaml-lml 0.3.3 → 0.3.4

data/lib/lutaml/lml/symbol_index.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    # A flat, positioned index of the document's symbols and the uses
+    # that reference them. Backs navigation, hover, and completion in
+    # tooling, and is available as Document#symbols.
+    class SymbolIndex
+      Entry = Struct.new(:name, :kind, :container, :position, :detail, :record,
+                         keyword_init: true)
+
+      # LSP SymbolKind values.
+      KINDS = {
+        package: 4, class: 5, method: 6, field: 8,
+        enum: 10, instance: 19, enum_member: 22, data_type: 23
+      }.freeze
+
+      attr_reader :entries
+
+      def initialize(document)
+        @entries = []
+        return unless document
+
+        walk_document(document)
+      end
+
+      def definitions(name)
+        @entries.select { |entry| entry.name.to_s == name.to_s }
+      end
+
+      def uses(name)
+        token = name.to_s
+        @entries.select do |entry|
+          if entry.record.is_a?(TopElementAttribute)
+            reference?(entry.record, token)
+          elsif entry.record.is_a?(Instance)
+            [entry.record.type.to_s, entry.record.isa.to_s].include?(token)
+          else
+            false
+          end
+        end
+      end
+
+      def attribute_entries
+        @entries.select { |entry| entry.kind == :field }
+      end
+
+      def entity_entries
+        @entries.reject { |entry| %i[field method enum_member].include?(entry.kind) }
+      end
+
+      def names
+        @entries.map(&:name).compact.uniq
+      end
+
+      private
+
+      def walk_document(document)
+        walk_members(document, nil)
+        walk_instance(document.instance, nil) if document.instance
+        walk_collection(document.instances) if document.instances
+      end
+
+      def walk_members(owner, container)
+        Array(owner.classes).each { |klass| walk_class(klass, container) }
+        Array(owner.enums).each { |enum| walk_enum(enum, container) }
+        Array(owner.data_types).each { |type| walk_data_type(type, container) }
+        Array(owner.packages).each { |package| walk_package(package, container) }
+      end
+
+      def walk_package(package, container)
+        name = package.name.to_s
+        add(name, :package, container, package.source_position, nil, package)
+        walk_members(package, name)
+      end
+
+      def walk_class(klass, container)
+        name = klass.name.to_s
+        add(name, :class, container, klass.source_position, parent_detail(klass), klass)
+        Array(klass.attributes).each do |attribute|
+          add(attribute.name, :field, name, attribute.source_position,
+              attribute_detail(attribute), attribute)
+        end
+        Array(klass.operations).each do |operation|
+          add(operation.name, :method, name, operation.source_position,
+              operation_detail(operation), operation)
+        end
+        Array(klass.data_types).each { |type| walk_data_type(type, name) }
+      end
+
+      def walk_enum(enum, container)
+        name = enum.name.to_s
+        add(name, :enum, container, enum.source_position, nil, enum)
+        Array(enum.attributes).each do |member|
+          add(member.name, :enum_member, name, member.source_position,
+              enum_member_detail(member), member)
+        end
+        Array(enum.member_fields).each do |field|
+          add(field.name, :field, name, field.source_position,
+              field.type.to_s, field)
+        end
+      end
+
+      def walk_data_type(type, container)
+        name = type.name.to_s
+        add(name, :data_type, container, type.source_position, nil, type)
+        Array(type.attributes).each do |attribute|
+          add(attribute.name, :field, name, attribute.source_position,
+              attribute_detail(attribute), attribute)
+        end
+      end
+
+      def walk_collection(collection)
+        return unless collection.is_a?(InstanceCollection)
+
+        name = collection.name.to_s
+        add(name, :package, nil, collection.source_position, 'instances', collection)
+        Array(collection.instances).each { |instance| walk_instance(instance, name) }
+      end
+
+      def walk_instance(instance, container)
+        name = instance_label(instance)
+        add(name, :instance, container, instance.source_position, name, instance)
+        Array(instance.attributes).each do |attribute|
+          next if attribute.name.to_s.empty?
+
+          add(attribute.name, :field, name, attribute.source_position,
+              attribute_value_detail(attribute), attribute)
+          Array(attribute.instances).each { |nested| walk_instance(nested, name) }
+        end
+        walk_instance(instance.instance, name) if instance.instance
+      end
+
+      def add(name, kind, container, position, detail, record)
+        return if name.to_s.empty? || position.nil?
+
+        @entries << Entry.new(
+          name: name.to_s, kind: kind, container: container,
+          position: position, detail: detail, record: record
+        )
+      end
+
+      def parent_detail(klass)
+        klass.parent_class.to_s.empty? ? nil : "< #{klass.parent_class}"
+      end
+
+      def attribute_detail(attribute)
+        detail = attribute.type.to_s.dup
+        cardinality = attribute.cardinality
+        if cardinality
+          max = cardinality.max.to_s
+          detail << " [#{cardinality.min}#{"..#{max}" unless max.empty?}]"
+        end
+        detail.empty? ? nil : detail
+      end
+
+      def operation_detail(operation)
+        params = Array(operation.owned_parameter)
+                 .map { |param| "#{param.name}: #{param.type}" }.join(', ')
+        detail = "(#{params})"
+        detail += " : #{operation.return_type}" if operation.return_type.to_s != ''
+        detail
+      end
+
+      def enum_member_detail(member)
+        description = Array(member.attributes).find { |a| a.name == 'description' }
+        description&.type&.to_s
+      end
+
+      def attribute_value_detail(attribute)
+        value = attribute.value
+        value = value.value if value.is_a?(LiteralValue)
+        value.nil? ? attribute.type.to_s : value.to_s
+      end
+
+      def instance_label(instance)
+        type = instance.type.to_s
+        name = instance.name.to_s
+        return name unless name.empty?
+        return type unless type.empty?
+
+        'instance'
+      end
+
+      def reference?(attribute, token)
+        type = attribute.type.to_s
+        return true if type == token || type.split('[]').first == token
+
+        value = attribute.value
+        value = value.value if value.is_a?(LiteralValue)
+        return false unless value.is_a?(Hash)
+
+        reference = value[:reference] || value['reference']
+        return false unless reference
+
+        reference.to_s.split('.').include?(token)
+      end
+    end
+  end
+end

data/lib/lutaml/lml/transform.rb

@@ -4,11 +4,13 @@ require 'parsanol'
 
 module Lutaml
   module Lml
+    # Converts the raw parsanol tree into the processed hash, retaining
+    # source positions as non-serialized metadata.
     class Transform < Parsanol::Transform
       VISIBILITY_MAP = {
         '-' => 'private',
         '#' => 'protected',
-        '~' => 'package'
+        '~' => 'package',
       }.freeze
 
       rule(visibility_modifier: simple(:visibility_value)) do
@@ -50,7 +52,52 @@ module Lutaml
       BLOCK_KEYS = %i[definition comments].freeze
 
       def apply(tree, context = nil)
-        strip_block_layout(super)
+        processed = super
+        attach_positions(tree, processed)
+        strip_block_layout(processed)
+      end
+
+      # Retains the source position of name/key captures as a :position
+      # hash beside the transformed value. The document builder moves it
+      # onto the model as non-serialized metadata (see Positioned).
+      def attach_positions(raw, processed)
+        case raw
+        when Hash
+          return unless processed.is_a?(Hash)
+
+          slice = capture_slice(raw[:name]) || capture_slice(raw[:key]) ||
+                  capture_slice(raw[:value_name]) || capture_slice(raw[:lml_version])
+          processed[:position] = position_hash(slice) if slice
+
+          raw.each_key do |key|
+            attach_positions(raw[key], processed[key]) if processed.key?(key)
+          end
+        when Array
+          return unless processed.is_a?(Array)
+
+          raw.each_with_index do |item, index|
+            attach_positions(item, processed[index]) if index < processed.length
+          end
+        end
+      end
+
+      # A name capture is either a bare token (a Slice) or a quoted
+      # string (a hash holding the inner Slice).
+      def capture_slice(node)
+        return node if node.is_a?(Parsanol::Slice)
+        return node[:string] if node.is_a?(Hash) && node[:string].is_a?(Parsanol::Slice)
+
+        nil
+      end
+
+      def position_hash(slice)
+        line, column = slice.line_and_column
+        {
+          line: line,
+          column: column,
+          offset: slice.offset,
+          length: slice.content.to_s.bytesize,
+        }
       end
 
       def strip_block_layout(node)

data/lib/lutaml/lml/validator.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rubygems/version"
+
 module Lutaml
   module Lml
     # RS 3001 §Validation rules evaluated over a parsed document:
@@ -8,14 +10,27 @@ module Lutaml
     # matching declared types) and reference validity (ref: paths resolve
     # to instances and are acyclic).
     class Validator
-      Violation = Struct.new(:rule, :message, keyword_init: true)
+      Violation = Struct.new(:rule, :message, :position, keyword_init: true)
+
+      RULE_CODES = {
+        'unique_names' => 'validation/LML-V01',
+        'unique_attribute_names' => 'validation/LML-V02',
+        'mandatory_attributes' => 'validation/LML-V03',
+        'type_conformity' => 'validation/LML-V04',
+        'values_set_membership' => 'validation/LML-V05',
+        'unknown_attributes' => 'validation/LML-V06',
+        'reference_validity' => 'validation/LML-V07',
+        'reference_circularity' => 'validation/LML-V08',
+        'pattern_conformity' => 'validation/LML-V09',
+        'pattern_compiles' => 'validation/LML-V10',
+      }.freeze
 
       PRIMITIVE_CONFORMITY = {
         'Integer' => /\A-?\d+\z/,
         'Number' => /\A-?\d+\z/,
         'Float' => /\A-?\d+\.\d+\z/,
         'Boolean' => /\A(true|false)\z/,
-        'Null' => /\Anull\z/
+        'Null' => /\Anull\z/,
       }.freeze
 
       COLLECTION_KEYS = %i[properties attributes instances].freeze
@@ -24,10 +39,55 @@ module Lutaml
         new(document).violations
       end
 
+      # The structured form of the same rules: one Diagnostic per
+      # violation, with its code and the source position of the
+      # offending member when the parser retained one.
+      def self.diagnostics(document)
+        new(document).diagnostics
+      end
+
       def initialize(document)
         @document = document
       end
 
+      def diagnostics
+        version_diagnostics + violations.map do |violation|
+          Diagnostic.build(
+            RULE_CODES.fetch(violation.rule),
+            message: violation.message,
+            file: @document.source_path,
+            line: violation.position&.line,
+            column: violation.position&.column,
+            length: violation.position&.length,
+          )
+        end
+      end
+
+      # Version negotiation: a document may declare the language version
+      # it speaks with an `lml "x.y"` prologue. A version newer than this
+      # build is a warning, not an error (forward compatibility).
+      def version_diagnostics
+        declared = @document.lml_version.to_s
+        return [] if declared.empty?
+        return [] unless newer_language_version?(declared)
+
+        position = @document.source_position
+        [Diagnostic.build(
+          'contract/LML-C06',
+          message: "document declares LML #{declared}; this build supports #{Grammar.version}",
+          file: @document.source_path,
+          line: position&.line,
+          column: position&.column,
+          length: position&.length,
+        )]
+      end
+
+      def newer_language_version?(declared)
+        Gem::Version.new(declared) > Gem::Version.new(Grammar.version)
+      rescue ArgumentError
+        false
+      end
+
       def violations
         unique_name_violations +
           unique_attribute_violations +
@@ -47,7 +107,7 @@ module Lutaml
         [
           *Array(@document.classes),
           *Array(@document.enums),
-          *Array(@document.data_types)
+          *Array(@document.data_types),
         ]
       end
 
@@ -61,10 +121,9 @@ module Lutaml
 
       def all_definitions
         @all_definitions ||= begin
-          pairs = []
-          Array(@document.classes).each { |c| pairs << [c.name.to_s, c] }
-          Array(@document.enums).each { |e| pairs << [e.name.to_s, e] }
-          Array(@document.data_types).each { |d| pairs << [d.name.to_s, d] }
+          pairs = Array(@document.classes).map { |c| [c.name.to_s, c] } +
+                  Array(@document.enums).map { |e| [e.name.to_s, e] } +
+                  Array(@document.data_types).map { |d| [d.name.to_s, d] }
           Array(@document.packages).each { |pkg| collect_package_definitions(pkg, pairs) }
           pairs
         end
@@ -91,7 +150,8 @@ module Lutaml
 
             Violation.new(
               rule: 'unique_names',
-              message: "'#{name}' is defined #{count} times in #{scope_label}"
+              message: "'#{name}' is defined #{count} times in #{scope_label}",
+              position: definitions.find { |definition| definition.name.to_s == name }&.source_position,
             )
           end
         end
@@ -105,7 +165,8 @@ module Lutaml
 
           Violation.new(
             rule: 'unique_attribute_names',
-            message: "#{name}: duplicate attribute(s) #{dupes.inspect}"
+            message: "#{name}: duplicate attribute(s) #{dupes.inspect}",
+            position: definition.source_position,
           )
         end
       end
@@ -114,11 +175,58 @@ module Lutaml
         Array(definition.attributes).map(&:name).map(&:to_s)
       end
 
+      def entry_position(instance, name)
+        entry = Array(instance.attributes).find { |attribute| attribute.name.to_s == name }
+        entry&.source_position || instance.source_position
+      end
+
+      # RS 3001 par. Attribute: a `pattern` declaration constrains
+      # string values; a pattern that does not compile is itself a
+      # definition error.
+      def pattern_violations(instance)
+        definition = type_definitions[definition_type(instance)]
+        return [] unless definition.is_a?(UmlClass) || definition.is_a?(DataType)
+
+        instance_attribute_pairs(instance).filter_map do |name, value|
+          attr = Array(definition.attributes).find { |a| a.name.to_s == name }
+          next unless attr&.pattern
+
+          regexp = compile_pattern(attr.pattern)
+          next invalid_pattern_violation(definition_type(instance), name, attr) unless regexp
+
+          literal = value.respond_to?(:value) ? value.value : value
+          next unless literal.is_a?(String)
+          next if regexp.match?(literal)
+
+          Violation.new(
+            rule: 'pattern_conformity',
+            message: "instance '#{instance_name(instance)}': attribute '#{name}' " \
+                     "does not match #{attr.pattern.inspect}, got #{literal.inspect}",
+            position: entry_position(instance, name),
+          )
+        end
+      end
+
+      def compile_pattern(pattern)
+        Regexp.new(pattern)
+      rescue RegexpError
+        nil
+      end
+
+      def invalid_pattern_violation(type, name, attr)
+        Violation.new(
+          rule: 'pattern_compiles',
+          message: "#{type}: attribute '#{name}' has an invalid pattern #{attr.pattern.inspect}",
+          position: attr.source_position,
+        )
+      end
+
       def instance_violations
         instances.flat_map do |instance|
           mandatory_violations(instance) +
             type_conformity_violations(instance) +
             values_set_violations(instance) +
+            pattern_violations(instance) +
             unknown_attribute_violations(instance) +
             reference_violations(instance)
         end.compact
@@ -140,7 +248,8 @@ module Lutaml
           Violation.new(
             rule: 'values_set_membership',
             message: "instance '#{instance_name(instance)}': attribute '#{name}' " \
-                     "must be one of #{attr.value_set.inspect}, got #{literal.to_s.inspect}"
+                     "must be one of #{attr.value_set.inspect}, got #{literal.to_s.inspect}",
+            position: entry_position(instance, name),
           )
         end
       end
@@ -151,12 +260,13 @@ module Lutaml
 
         declared = attribute_names(definition)
         instance_attribute_pairs(instance)
-          .reject { |name, _value| declared.include?(name) }
+          .reject { |pair| declared.include?(pair[0]) }
           .map do |name, _value|
             Violation.new(
               rule: 'unknown_attributes',
               message: "instance '#{instance_name(instance)}' (#{definition_type(instance)}): " \
-                       "unknown attribute '#{name}'"
+                       "unknown attribute '#{name}'",
+              position: entry_position(instance, name),
             )
           end
       end
@@ -176,7 +286,8 @@ module Lutaml
           Violation.new(
             rule: 'mandatory_attributes',
             message: "instance '#{instance_name(instance)}' (#{definition_type(instance)}): " \
-                     "mandatory attribute '#{attr.name}' is not populated"
+                     "mandatory attribute '#{attr.name}' is not populated",
+            position: instance.source_position,
           )
         end
       end
@@ -185,8 +296,6 @@ module Lutaml
         attr.cardinality && attr.cardinality.min == '1'
       end
 
-
-
       def type_conformity_violations(instance)
         definition = type_definitions[definition_type(instance)]
         return [] unless definition.respond_to?(:attributes)
@@ -207,7 +316,8 @@ module Lutaml
         Violation.new(
           rule: 'type_conformity',
           message: "instance '#{instance_name(instance)}': attribute '#{name}' " \
-                   "expects #{attr.type}, got #{value.to_s.inspect}"
+                   "expects #{attr.type}, got #{value.to_s.inspect}",
+          position: entry_position(instance, name),
         )
       end
 
@@ -218,7 +328,8 @@ module Lutaml
             next Violation.new(
               rule: 'reference_validity',
               message: "instance '#{instance_name(instance)}': attribute '#{name}' " \
-                       "references unknown path '#{path}'"
+                       "references unknown path '#{path}'",
+              position: entry_position(instance, name),
             )
           end
 
@@ -241,7 +352,7 @@ module Lutaml
         @collection_names ||= [@document.instances&.name].compact
       end
 
-      def attribute_violation(instance, _name, path, target)
+      def attribute_violation(instance, name, path, target)
         segment = path.to_s.split('.')[1]
         target_instance = instances.find { |i| instance_name(i) == target }
         return if segment.nil? || target_instance.nil? ||
@@ -250,7 +361,8 @@ module Lutaml
         Violation.new(
           rule: 'reference_validity',
           message: "instance '#{instance_name(instance)}': reference '#{path}' " \
-                   "does not resolve (no attribute '#{segment}' on '#{target}')"
+                   "does not resolve (no attribute '#{segment}' on '#{target}')",
+          position: entry_position(instance, name),
         )
       end
 
@@ -306,7 +418,8 @@ module Lutaml
         cycles.map do |cycle|
           Violation.new(
             rule: 'reference_circularity',
-            message: "circular reference: #{cycle.join(' -> ')}"
+            message: "circular reference: #{cycle.join(' -> ')}",
+            position: instances.find { |instance| instance_name(instance) == cycle.first }&.source_position,
           )
         end
       end
@@ -317,7 +430,7 @@ module Lutaml
           path = walk_for_cycle(graph, start)
           cycles << path if path
         end
-        cycles.uniq { |cycle| cycle.sort }
+        cycles.uniq(&:sort)
       end
 
       def walk_for_cycle(graph, start)

data/lib/lutaml/lml/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Lml
-    VERSION = "0.3.3"
+    VERSION = "0.3.4"
   end
 end

data/lib/lutaml/lml.rb

@@ -17,9 +17,20 @@ module Lutaml
   # and renders diagrams. See the entry-point contract under .parse /
   # .parse_document below.
   module Lml
-    class Error < Lutaml::Error; end
+    # Base error for LML failures; carries an optional Diagnostic.
+    class Error < Lutaml::Error
+      # Structured record for the failure, when one could be built.
+      attr_reader :diagnostic
+
+      def initialize(message = nil, diagnostic: nil)
+        @diagnostic = diagnostic
+        super(message)
+      end
+    end
+
     class ParsingError < Error; end
     class ImportError < Error; end
+    class HydrationError < Error; end
 
     def self.compile(input, namespace: nil)
       ModelCompiler.new(namespace: namespace).compile(input)
@@ -64,8 +75,14 @@ module Lutaml
     autoload :EntityTypes, "lutaml/lml/entity_types"
     autoload :AssociationLabelResolver, "lutaml/lml/association_label_resolver"
     autoload :Executor, "lutaml/lml/executor"
+    autoload :Lsp, "lutaml/lml/lsp"
+    autoload :SymbolIndex, "lutaml/lml/symbol_index"
     autoload :YamlParser, "lutaml/lml/yaml_parser"
     autoload :HasAttributes, "lutaml/lml/has_attributes"
+    autoload :Quoting, "lutaml/lml/quoting"
+    autoload :Diagnostic, "lutaml/lml/diagnostic"
+    autoload :SourcePosition, "lutaml/lml/source_position"
+    autoload :Positioned, "lutaml/lml/positioned"
     autoload :VERSION, "lutaml/lml/version"
 
     # Type classes (Lutaml::Model::Type::Value subclasses, not models)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-lml
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.4
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
@@ -73,10 +73,12 @@ email:
 - open.source@ribose.com
 executables:
 - lutaml-lml
+- lutaml-lml-lsp
 extensions: []
 extra_rdoc_files: []
 files:
 - exe/lutaml-lml
+- exe/lutaml-lml-lsp
 - lib/lutaml/lml.rb
 - lib/lutaml/lml/association_label_resolver.rb
 - lib/lutaml/lml/cli.rb
@@ -87,6 +89,7 @@ files:
 - lib/lutaml/lml/data_processor/value_declaration_processing.rb
 - lib/lutaml/lml/data_processor/value_processing.rb
 - lib/lutaml/lml/data_processor/view_processing.rb
+- lib/lutaml/lml/diagnostic.rb
 - lib/lutaml/lml/document_builder.rb
 - lib/lutaml/lml/entity_types.rb
 - lib/lutaml/lml/executor.rb
@@ -102,6 +105,7 @@ files:
 - lib/lutaml/lml/format/adapter/transform.rb
 - lib/lutaml/lml/formatter.rb
 - lib/lutaml/lml/formatter/base.rb
+- lib/lutaml/lml/formatter/canonical.rb
 - lib/lutaml/lml/formatter/elk.rb
 - lib/lutaml/lml/formatter/graphviz.rb
 - lib/lutaml/lml/formatter/graphviz/document_formatter.rb
@@ -123,6 +127,12 @@ files:
 - lib/lutaml/lml/layout/engine.rb
 - lib/lutaml/lml/layout/graph_viz_engine.rb
 - lib/lutaml/lml/literal_value.rb
+- lib/lutaml/lml/lsp.rb
+- lib/lutaml/lml/lsp/conversions.rb
+- lib/lutaml/lml/lsp/keywords.rb
+- lib/lutaml/lml/lsp/server.rb
+- lib/lutaml/lml/lsp/store.rb
+- lib/lutaml/lml/lsp/transport.rb
 - lib/lutaml/lml/model_compiler.rb
 - lib/lutaml/lml/model_compiler/enums.rb
 - lib/lutaml/lml/model_compiler/hydration.rb
@@ -163,8 +173,12 @@ files:
 - lib/lutaml/lml/models/view_import.rb
 - lib/lutaml/lml/parser.rb
 - lib/lutaml/lml/pipeline.rb
+- lib/lutaml/lml/positioned.rb
 - lib/lutaml/lml/preprocessor.rb
+- lib/lutaml/lml/quoting.rb
 - lib/lutaml/lml/source.rb
+- lib/lutaml/lml/source_position.rb
+- lib/lutaml/lml/symbol_index.rb
 - lib/lutaml/lml/transform.rb
 - lib/lutaml/lml/types.rb
 - lib/lutaml/lml/types/text_type.rb