lutaml-lml 0.3.3 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f79d537da7c7fa27b8a630593350a988eecee947b4b32ed1621e02962df27e71
-  data.tar.gz: ba8ba31cda8051fc5dee369e04e4548c62ea7f6f6e613689856fd231bb4be61c
+  metadata.gz: 3d2253a295aed1a2d3218c34818aa1fddf38ca68be9830695175a52ba777719b
+  data.tar.gz: 6a070753dfcf0acf67b5196c8f8fca550f8b7ae41f01a15ad969f8d3e423de4f
 SHA512:
-  metadata.gz: 4cfee5710eb7c59e10c8ea3438e7ce65176a6a42ac296072da6ccd52cea2709f244acac691b45e1b9250bc7aa3c89a2e367e5719655575ece7b6425774d218e6
-  data.tar.gz: c011827fc8554815cca6119741b597ad779e0966b6e5fadf0cf8c729fae28974151b18994a11d38a68ee544c3511e035042f6a6eaa3687dcf0070064605e25b9
+  metadata.gz: f1190e583a4ed9f86af817b45863ab26a40668dc38f4f1d17458f5df869e47e409c2454a7282d60ba2a601896e53697a852a263ab6148390f972c29519a8af61
+  data.tar.gz: ec32fdc80d72afa8a7173655c3f47115acbab0c1b14535126954e0edd0bd2c809b218884c8e98287beb53bd740f225ec552f741171f5fded67dadeaced305ca5

data/exe/lutaml-lml-lsp

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "lutaml/lml"
+
+# JSON-RPC framing is byte-oriented; text-mode newline translation would
+# turn \r\n into \r\r\n and break Content-Length.
+$stdin.binmode
+$stdout.binmode
+
+exit Lutaml::Lml::Lsp::Server.new.run

data/lib/lutaml/lml/cli.rb

@@ -2,6 +2,7 @@
 
 require 'thor'
 require 'pathname'
+require 'json'
 require 'lutaml/lml'
 
 module Lutaml
@@ -103,11 +104,38 @@ module Lutaml
       DESC
       method_option :input_format, type: :string, aliases: '-i',
                                    desc: 'Input format (lutaml, yaml, exp)'
+      method_option :format, type: :string, enum: %w[text json], default: 'text',
+                             desc: 'Report format: text (default) or json'
       def validate(*paths)
         assert_input_paths(paths)
         @input_format = options[:input_format] || DEFAULT_INPUT_FORMAT
-        errors = paths.map { |p| validate_single_file(p) }.compact
-        report_validation(errors)
+        diagnostics = paths.flat_map { |path| validate_single_file(path) }
+        report_validation(diagnostics)
+      end
+
+      desc 'format [PATHS]', 'Render LML files in canonical form'
+      long_desc <<-DESC
+        Rewrite LML files into the RS 3001 canonical form (deterministic
+        member order, two-space layout, canonical attribute forms and
+        quoting).
+
+        With --check, files are not modified: each non-canonical file is
+        reported with a diff and the command exits 1.
+
+        Examples:
+          lutaml lml format model.lml
+
+          lutaml lml format model.lml --check
+      DESC
+      method_option :check, type: :boolean, default: false,
+                            desc: 'Report non-canonical files instead of rewriting them'
+      def format(*paths)
+        assert_input_paths(paths)
+
+        noncanonical = paths.reject { |path| file_canonical?(path) }
+        return if noncanonical.empty?
+
+        exit 1
       end
 
       desc 'compile PATH', 'Compile LML model definitions into Ruby classes'
@@ -206,6 +234,84 @@ module Lutaml
           name.split('::').last.gsub(/[^a-zA-Z0-9]+/, '_').downcase
         end
 
+        def file_canonical?(path)
+          input = Pathname.new(path)
+          raise Thor::Error, "File does not exist: #{path}" unless input.exist?
+
+          source = input.read
+          canonical = canonical_source(source)
+          return true if source == canonical
+
+          if options[:check]
+            say diff_source(source, canonical, path)
+            say "#{path} is not canonical", :red
+            false
+          else
+            input.write(canonical)
+            say "Formatted: #{path}", :green
+            true
+          end
+        end
+
+        def canonical_source(source)
+          document = Lutaml::Lml.parse_document(source)
+          ::Lutaml::Formatter::Canonical.new(document).render
+        end
+
+        def diff_source(source, canonical, path)
+          old_lines = source.lines.map(&:chomp)
+          new_lines = canonical.lines.map(&:chomp)
+          out = ["--- #{path}", "+++ #{path} (canonical)"]
+          out.concat(diff_lines(old_lines, new_lines))
+          out.join("\n")
+        end
+
+        def diff_lines(old_lines, new_lines)
+          return ['(diff omitted: file too large)'] if old_lines.length * new_lines.length > 4_000_000
+
+          table = Array.new(old_lines.length + 1) do
+            Array.new(new_lines.length + 1, 0)
+          end
+          (old_lines.length - 1).downto(0) do |i|
+            (new_lines.length - 1).downto(0) do |j|
+              table[i][j] = if old_lines[i] == new_lines[j]
+                              table[i + 1][j + 1] + 1
+                            else
+                              [table[i + 1][j], table[i][j + 1]].max
+                            end
+            end
+          end
+          walk_diff(old_lines, new_lines, table)
+        end
+
+        def walk_diff(old_lines, new_lines, table)
+          result = []
+          i = 0
+          j = 0
+          while i < old_lines.length && j < new_lines.length
+            if old_lines[i] == new_lines[j]
+              result << "  #{old_lines[i]}"
+              i += 1
+              j += 1
+            elsif table[i + 1][j] >= table[i][j + 1]
+              result << "- #{old_lines[i]}"
+              i += 1
+            else
+              result << "+ #{new_lines[j]}"
+              j += 1
+            end
+          end
+          while i < old_lines.length
+            result << "- #{old_lines[i]}"
+            i += 1
+          end
+          while j < new_lines.length
+            result << "+ #{new_lines[j]}"
+            j += 1
+          end
+          result
+        end
+
         def assert_input_paths(paths)
           return unless paths.empty?
 
@@ -250,33 +356,75 @@ module Lutaml
 
         def validate_single_file(path_string)
           input_path = Pathname.new(path_string)
-          return report_file_error(input_path, 'File does not exist') unless input_path.exist?
+          return [missing_file_diagnostic(input_path)] unless input_path.exist?
 
           document = parse_document(input_path)
-          violations = Lutaml::Lml::Validator.violations(document)
-          if violations.any?
-            report_file_error(input_path, violations_message(violations))
-          else
+          diagnostics = Lutaml::Lml::Validator.diagnostics(document)
+          if diagnostics.any?
+            if text_output?
+              diagnostics.each do |diagnostic|
+                say diagnostic_line(diagnostic),
+                    (diagnostic.severity == 'warning' ? :yellow : :red)
+              end
+            end
+          elsif text_output?
             say "✓ #{input_path}", :green
-            nil
           end
+          diagnostics
+        rescue Thor::Error => e
+          [contract_diagnostic('contract/LML-C02', e.message, input_path)]
+        rescue Lutaml::Lml::Error => e
+          [error_diagnostic(e, input_path)]
         rescue StandardError => e
-          report_file_error(input_path, e.message)
+          [contract_diagnostic('contract/LML-C03', e.message, input_path)]
+        end
+
+        def missing_file_diagnostic(input_path)
+          contract_diagnostic('contract/LML-C01', 'File does not exist', input_path)
+        end
+
+        def contract_diagnostic(code, message, input_path)
+          diagnostic = Diagnostic.build(code, message: message, file: input_path.to_s)
+          say "✗ #{diagnostic}", :red if text_output?
+          diagnostic
+        end
+
+        def error_diagnostic(error, input_path)
+          diagnostic = error.diagnostic
+          return diagnostic if diagnostic&.file
+
+          Diagnostic.build(
+            diagnostic&.code || 'parse/LML-001',
+            message: diagnostic&.message || error.message.lines.first.to_s.strip,
+            file: input_path.to_s,
+            line: diagnostic&.line,
+            column: diagnostic&.column,
+            length: diagnostic&.length,
+          )
         end
 
-        def violations_message(violations)
-          violations.map { |v| "[#{v.rule}] #{v.message}" }.join('; ')
+        def text_output?
+          options[:format] != 'json'
         end
 
-        def report_file_error(input_path, message)
-          say "✗ #{input_path}: #{message}", :red
-          "#{input_path}: #{message}"
+        def diagnostic_line(diagnostic)
+          marker = diagnostic.severity == 'warning' ? '⚠' : '✗'
+          "#{marker} #{diagnostic}"
         end
 
-        def report_validation(errors)
-          if errors.any?
-            say "\nValidation failed with #{errors.size} error(s)", :red
+        def report_validation(diagnostics)
+          errors = diagnostics.count { |diagnostic| diagnostic.severity != 'warning' }
+          if options[:format] == 'json'
+            puts JSON.pretty_generate(diagnostics.map(&:to_hash))
+            exit 1 if errors.positive?
+            return
+          end
+
+          if errors.positive?
+            say "\nValidation failed with #{errors} error(s)", :red
             exit 1
+          elsif diagnostics.any?
+            say "\nAll files valid (#{diagnostics.size} warning(s))", :yellow
           else
             say "\nAll files valid!", :green
           end

data/lib/lutaml/lml/data_processor/attribute_processing.rb

@@ -120,9 +120,11 @@ module Lutaml
         end
 
         # `default: "Clear"` uses the colon separator (RS 3001 §Attribute);
-        # the colon lands in the captured name and must not.
+        # the colon lands in the captured name and must not. A quoted key
+        # is verbatim, so a trailing colon there is content.
         def strip_argument_colon(name)
-          name = name[:string] if name.is_a?(Hash) && name.key?(:string)
+          return name[:string] if name.is_a?(Hash) && name.key?(:string)
+
           name.to_s.sub(/:\z/, "")
         end
       end

data/lib/lutaml/lml/data_processor/value_declaration_processing.rb

@@ -13,6 +13,7 @@ module Lutaml
         # member payload properties.
         def process_value_declaration(decl)
           inner = { name: unwrap_string(decl[:value_name]) }
+          inner[:position] = decl[:position] if decl[:position]
           Array(decl[:members]).each do |member|
             normalize_value_member(inner, member)
           end

data/lib/lutaml/lml/data_processor.rb

@@ -2,6 +2,8 @@
 
 module Lutaml
   module Lml
+    # Post-transform normalization: turns parse captures into the flat
+    # member hashes the document builder consumes.
     class DataProcessor
       autoload :ValueProcessing, "lutaml/lml/data_processor/value_processing"
       autoload :AttributeProcessing, "lutaml/lml/data_processor/attribute_processing"
@@ -18,13 +20,14 @@ module Lutaml
       include ViewProcessing
 
       KEY_HANDLERS = {
+        lml_version: :process_lml_version,
         requires: :process_requires,
         instances: :process_instances,
         instance: :process_instance,
         attributes: :process_attributes,
         value_decl: :process_value_declaration,
         show_list: :process_show_list,
-        hide_list: :process_hide_list
+        hide_list: :process_hide_list,
       }.freeze
 
       def self.process(obj)
@@ -47,6 +50,10 @@ module Lutaml
       def process_requires(obj)
         obj.map { |req| process_value(req).last }
       end
+
+      def process_lml_version(value)
+        value.is_a?(Hash) ? value[:string] : value
+      end
     end
   end
 end

data/lib/lutaml/lml/diagnostic.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Lutaml
+  module Lml
+    # One diagnostic record: a code, severity, source location, message,
+    # and a remedy. Codes are namespaced by stage (parse/validation/
+    # hydration/contract) and listed in CODES, the single source of
+    # truth also documented in the README.
+    class Diagnostic < Lutaml::Model::Serializable
+      CODES = {
+        'parse/LML-001' => {
+          severity: 'error',
+          remedy: 'Fix the syntax at the reported position.',
+        },
+        'parse/LML-002' => {
+          severity: 'error',
+          remedy: 'Terminate the block comment with */.',
+        },
+        'parse/LML-003' => {
+          severity: 'error',
+          remedy: 'Check the include path and the included file.',
+        },
+        'validation/LML-V01' => {
+          severity: 'error',
+          remedy: 'Rename or remove the duplicate definition.',
+        },
+        'validation/LML-V02' => {
+          severity: 'error',
+          remedy: 'Rename or remove the duplicate attribute.',
+        },
+        'validation/LML-V03' => {
+          severity: 'error',
+          remedy: 'Populate the mandatory attribute on the instance.',
+        },
+        'validation/LML-V04' => {
+          severity: 'error',
+          remedy: 'Use a value matching the declared primitive type.',
+        },
+        'validation/LML-V05' => {
+          severity: 'error',
+          remedy: 'Use one of the values declared for the attribute.',
+        },
+        'validation/LML-V06' => {
+          severity: 'error',
+          remedy: 'Declare the attribute or remove it from the instance.',
+        },
+        'validation/LML-V07' => {
+          severity: 'error',
+          remedy: 'Point the reference at an existing instance or attribute.',
+        },
+        'validation/LML-V08' => {
+          severity: 'error',
+          remedy: 'Break the reference cycle.',
+        },
+        'validation/LML-V09' => {
+          severity: 'error',
+          remedy: 'Use a value matching the attribute pattern.',
+        },
+        'validation/LML-V10' => {
+          severity: 'error',
+          remedy: 'Fix the attribute pattern so that it compiles.',
+        },
+        'hydration/LML-H01' => {
+          severity: 'error',
+          remedy: 'Check the instance data against the compiled model.',
+        },
+        'contract/LML-C01' => {
+          severity: 'error',
+          remedy: 'Check the path of the input file.',
+        },
+        'contract/LML-C02' => {
+          severity: 'error',
+          remedy: 'Use one of the supported input formats.',
+        },
+        'contract/LML-C03' => {
+          severity: 'error',
+          remedy: 'Check the input file and its format.',
+        },
+        'contract/LML-C04' => {
+          severity: 'error',
+          remedy: 'Use a cardinality token such as 1, 0..1, or 0..n.',
+        },
+        'contract/LML-C05' => {
+          severity: 'error',
+          remedy: 'Check the imported view path and the imported files.',
+        },
+        'contract/LML-C06' => {
+          severity: 'warning',
+          remedy: 'Use a supported language version or upgrade lutaml-lml.',
+        },
+      }.freeze
+
+      attribute :code, :string
+      attribute :severity, :string, default: 'error'
+      attribute :file, :string
+      attribute :line, :integer
+      attribute :column, :integer
+      attribute :length, :integer
+      attribute :message, :string
+      attribute :remedy, :string
+
+      key_value do
+        map 'code', to: :code
+        map 'severity', to: :severity
+        map 'file', to: :file
+        map 'line', to: :line
+        map 'column', to: :column
+        map 'length', to: :length
+        map 'message', to: :message
+        map 'remedy', to: :remedy
+      end
+
+      def self.build(code, message:, file: nil, line: nil, column: nil,
+                     length: nil, severity: nil, remedy: nil)
+        entry = CODES.fetch(code)
+        new(
+          code: code,
+          severity: severity || entry[:severity],
+          file: file,
+          line: line,
+          column: column,
+          length: length,
+          message: message,
+          remedy: remedy || entry[:remedy],
+        )
+      end
+
+      # Human rendering: `path:line:col: [CODE] message`, then the
+      # remedy. Position segments are omitted when the parser could not
+      # attach them.
+      def to_s
+        "#{location}[#{code}] #{message}#{remedy_suffix}"
+      end
+
+      def location
+        parts = [file, line, column].compact
+        parts.empty? ? '' : "#{parts.join(':')}: "
+      end
+
+      private
+
+      def remedy_suffix
+        remedy.to_s.empty? ? '' : "\n  remedy: #{remedy}"
+      end
+    end
+  end
+end

data/lib/lutaml/lml/document_builder.rb

@@ -2,6 +2,8 @@
 
 module Lutaml
   module Lml
+    # Builds domain model objects from processed parse hashes, applying
+    # source positions as non-serialized metadata.
     class DocumentBuilder
       # Default registry: builder keys → LML model classes.
       # Callers needing a different mapping can pass their own registry
@@ -19,6 +21,8 @@ module Lutaml
         operation: ::Lutaml::Lml::Operation,
         constraint: ::Lutaml::Lml::Constraint,
         value: ::Lutaml::Lml::Value,
+        instance: ::Lutaml::Lml::Instance,
+        instance_collection: ::Lutaml::Lml::InstanceCollection,
         view_import: ::Lutaml::Lml::ViewImport,
         view_filter: ::Lutaml::Lml::ViewFilter,
         mapping: ::Lutaml::Lml::Mapping,
@@ -26,7 +30,7 @@ module Lutaml
         derived_field: ::Lutaml::Lml::DerivedField,
         member_field: ::Lutaml::Lml::MemberField,
         namespace: ::Lutaml::Lml::Namespace,
-        serialization_mapping: ::Lutaml::Lml::SerializationMapping
+        serialization_mapping: ::Lutaml::Lml::SerializationMapping,
       }.freeze
 
       attr_reader :registry
@@ -39,6 +43,7 @@ module Lutaml
         document package class enum data_type diagram view_import view_filter
         attribute association operation constraint value cardinality mapping
         string_format derived_field namespace serialization_mapping
+        instance instance_collection
       ].freeze
 
       MEMBER_KEY_MAP = {
@@ -56,7 +61,8 @@ module Lutaml
         mappings: :mapping,
         member_fields: :member_field,
         namespaces: :namespace,
-        serialization_mappings: :serialization_mapping
+        serialization_mappings: :serialization_mapping,
+        instances: :instance,
       }.freeze
 
       FACTORY_KEYS.each do |key|
@@ -71,6 +77,7 @@ module Lutaml
 
       def set_model(model, hash)
         hash = build_members(model, hash)
+        apply_collection_members(model, hash)
         set_model_attributes(model, hash)
         expand_class_specializer(model, hash)
       end
@@ -86,10 +93,21 @@ module Lutaml
 
       def set_model_attributes(model, hash)
         hash.each do |key, value|
+          if key == :position
+            attach_position(model, value)
+            next
+          end
+
           apply_attribute(model, key, value)
         end
       end
 
+      def attach_position(model, value)
+        return unless model.is_a?(Positioned) && value.is_a?(Hash)
+
+        model.source_position = SourcePosition.new(**value)
+      end
+
       def build_members(model, hash)
         members = hash.delete(:members)
         members.to_a.each do |member_hash|
@@ -133,15 +151,26 @@ module Lutaml
         normalize_serialization_mapping(hash)
         expand_instances_collection_name(hash)
         expand_nested_members(model, hash)
+        apply_collection_members(model, hash)
+
+        remap_filter_keys(hash, model)
+      end
+
+      # Builds collection-shaped keys through the registry rather than
+      # letting lutaml-model cast raw hashes, so nested entities keep
+      # their non-serialized source metadata (positions).
+      def apply_collection_members(model, hash)
+        model.instances = build(:instance_collection, hash.delete(:instances)) if model.is_a?(Document) && hash.key?(:instances)
+
         MEMBER_KEY_MAP.each do |plural_key, singular_key|
           data = hash.delete(plural_key)
           next if data.nil?
 
-          member = build(singular_key, data)
-          ensure_collection(model, plural_key) << member
+          entries = data.is_a?(Array) ? data : [data]
+          entries.each do |entry|
+            ensure_collection(model, plural_key) << build(singular_key, entry)
+          end
         end
-
-        remap_filter_keys(hash, model)
       end
 
       # RS 3001 §Enums: an enum-level `values { v1, v2 }` shorthand
@@ -165,12 +194,15 @@ module Lutaml
         # become the entry's instances (RS 3001 §Enums values carrying
         # instances).
         entry = { name: inner[:name] }
+        entry[:position] = inner[:position] if inner[:position]
         entry[:attributes] = inner[:attributes] if inner[:attributes]
-        entry[:properties] = Array(inner[:properties]).flat_map do |pair|
-          pair.is_a?(Hash) ? [pair] : Array(pair)
-        end if inner[:properties]
+        if inner[:properties]
+          entry[:properties] = Array(inner[:properties]).flat_map do |pair|
+            pair.is_a?(Hash) ? [pair] : Array(pair)
+          end
+        end
         entry[:instances] = inner[:instances] if inner[:instances]
-        apply_attribute(model, :attributes, entry)
+        append_collection(model, :attributes, build(:attribute, entry))
       end
 
       # Namespace declaration bodies arrive as keyword-line members
@@ -293,22 +325,22 @@ module Lutaml
         end
       end
 
-      def normalize_operation_hash(op)
-        op = op.dup
-        if (vis = op.delete(:visibility_modifier))
-          op[:visibility] = Transform::VISIBILITY_MAP.fetch(vis.to_s, 'public')
+      def normalize_operation_hash(operation)
+        operation = operation.dup
+        if (vis = operation.delete(:visibility_modifier))
+          operation[:visibility] = Transform::VISIBILITY_MAP.fetch(vis.to_s, 'public')
         end
-        stereo = op[:stereotype]
+        stereo = operation[:stereotype]
         if stereo
           items = stereo.is_a?(Array) ? stereo : [stereo]
-          op[:stereotype] = items.map { |x| x.is_a?(Hash) ? x[:stereotype].to_s : x.to_s }
+          operation[:stereotype] = items.map { |x| x.is_a?(Hash) ? x[:stereotype].to_s : x.to_s }
         end
-        params = op[:owned_parameter]
+        params = operation[:owned_parameter]
         if params
           list = params.is_a?(Array) ? params : [params]
-          op[:owned_parameter] = list.map { |param| normalize_operation_param(param) }
+          operation[:owned_parameter] = list.map { |param| normalize_operation_param(param) }
         end
-        op
+        operation
       end
 
       def normalize_operation_param(param)
@@ -406,8 +438,8 @@ module Lutaml
       end
 
       def build_string_format(section)
-        items = section[:items].to_a.each_with_object({}) do |item, acc|
-          acc[item[:key].to_sym] = unquote(item[:value])
+        items = section[:items].to_a.to_h do |item|
+          [item[:key].to_sym, unquote(item[:value])]
         end
         build(:string_format,
               format: unquote(section[:format]),