metanorma-plugin-lutaml 0.7.45 → 0.7.50

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecadace3879b75e1ec4f08f435da722a2151c32a419fed84476646f2dc7314f6
-  data.tar.gz: bc0e618b7252c140a1b9acc404194f2fdfa30e65c8b4ae8823c6bc19222a4a8a
+  metadata.gz: f27b6ec54fcac0ddd7555f3058124ff88197ebed8b616200deacb2e62ab796d5
+  data.tar.gz: b765db1783fd82e76ffcd22c3ec8340d335dfcc27058da3be7ce5127a0ca1136
 SHA512:
-  metadata.gz: 8d621151fd02cf3582d75366b8fc943f51286357d95584863c3158b7911b082dfaa877919505ba3483219d5c08eeae1ad449fe9862f0aa63b3507f08764f9a3a
-  data.tar.gz: 54823d6d7ae810e8791dc27d3dec120a44eb224fadce8ccedbd4884d4d8a28c54127bb1e8bf6b2c54e0c740085c52c5968d1e8181964902371cee15f329b990e
+  metadata.gz: 5c2ab27419d029d9b28a8fc6a03ee906505718d64a91cb405a4af15cb4761918b50c2d84668d33bd68ce2c444c72e6ae29a701367d98d5de0e0b35489741abdf
+  data.tar.gz: '0112029fbc5e4998a3a5ec2e19b0785db703b02eb379902ef47c720e2799965491d06947e40d35222694b81a8a2a5fbd432edeadf5a4d4ba55c87d8d4337c0d0'

data/.github/workflows/release.yml

@@ -19,6 +19,9 @@ jobs:
     uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
     with:
       next_version: ${{ github.event.inputs.next_version }}
+      release_command: |
+        bundle install
+        bundle exec rake release
     secrets:
       rubygems-api-key: ${{ secrets.METANORMA_CI_RUBYGEMS_API_KEY }}
       pat_token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}

data/.gitignore

@@ -4,6 +4,7 @@ spec/assets/lutaml
 test.err
 test.err.html
 TODO.cleanup/
+TODO.optimize/
 pkg/
 
 .rubocop-https--*

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-05-15 01:32:12 UTC using RuboCop version 1.86.1.
+# on 2026-05-15 10:38:23 UTC using RuboCop version 1.86.2.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -37,7 +37,7 @@ Metrics/CyclomaticComplexity:
   Exclude:
     - 'lib/metanorma/plugin/lutaml/utils.rb'
 
-# Offense count: 7
+# Offense count: 8
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 19
@@ -81,7 +81,7 @@ RSpec/ContextWording:
     - 'spec/metanorma/plugin/lutaml/macros_data2text_spec.rb'
     - 'spec/support/shared_examples/structured_data_2_text_preprocessor.rb'
 
-# Offense count: 44
+# Offense count: 47
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 26
@@ -157,3 +157,11 @@ RSpec/SpecFilePathFormat:
 RSpec/SubjectDeclaration:
   Exclude:
     - 'spec/metanorma/plugin/lutaml/config/root_spec.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
+Style/TrailingCommaInArguments:
+  Exclude:
+    - 'spec/metanorma/plugin/lutaml/express_remark_adapter_spec.rb'

data/Gemfile

@@ -14,7 +14,6 @@ end
 
 gem "canon"
 gem "html2doc", github: "metanorma/html2doc", branch: "main"
-gem "lutaml"
 gem "metanorma", github: "metanorma/metanorma", branch: "main"
 gem "metanorma-standoc", github: "metanorma/metanorma-standoc", branch: "main"
 gem "rake"

data/README.adoc

@@ -12,6 +12,8 @@ within a Metanorma document:
 * EXPRESS files (`*.exp`)
 * LutaML-UML files (`*.lutaml`)
 * Enterprise Architect exported UML files in XMI format (`*.xmi`)
+* Enterprise Architect QEA files (`*.qea`)
+* Enterprise Architect LUR files (`*.lur`)
 * LutaML GML Dictionary files (`*.xml`)
 * JSON or YAML files (`*.json|*.yml|*.yaml`)
 * XML Schema files (`*.xsd`)
@@ -31,6 +33,8 @@ link:docs/usages/lutaml-uml.adoc[Usage with LutaML files by lutaml_diagram]
 
 link:docs/usages/enterprise_architect.adoc[Usage with Enterprise Architect XMI files by lutaml_ea_xmi, lutaml_ea_diagram, lutaml_klass_table or lutaml_enum_table]
 
+link:docs/usages/enterprise_architect_uml.adoc[Usage with Enterprise Architect UML files (XMI, QEA, LUR) by lutaml_ea_uml]
+
 link:docs/usages/lutaml-gml.adoc[Usage with LutaML GML Dictionary by lutaml_gml_dictionary]
 
 link:docs/usages/json_yaml.adoc[Usage with JSON or YAML files by data2text, yaml2text or json2text]

data/docs/usages/enterprise_architect_uml.adoc

@@ -0,0 +1,173 @@
+
+== Usage with Enterprise Architect UML files (XMI, QEA, LUR) by lutaml_ea_uml
+
+=== General
+
+The `lutaml_ea_uml` command renders UML data models from Enterprise Architect
+files using custom Liquid templates. It supports three file formats:
+
+* XMI (`*.xmi`) -- Enterprise Architect XML Metadata Interchange export
+* QEA (`*.qea`) -- Enterprise Architect native database format
+* LUR (`*.lur`) -- Enterprise Architect model exchange format
+
+The command parses the file into a Liquid template context, allowing full
+control over the rendered output through custom Liquid templates.
+
+
+=== Basic usage
+
+[source,adoc]
+----
+[lutaml_ea_uml,path/to/example.xmi]
+--
+Name of the Lutaml UML Document: {{ context.name }}
+
+Number of packages: {{ context.packages | size }}
+--
+----
+
+Where:
+
+* `path/to/example.xmi` -- path to the XMI, QEA, or LUR file to render.
+
+The content between `--` delimiters is a Liquid template. The parsed UML
+document is available as `context` by default.
+
+
+=== Usage with a configuration file
+
+[source,adoc]
+----
+[lutaml_ea_uml,path/to/example.xmi,path/to/config.yml]
+--
+Name of the Lutaml UML Document: {{ my_uml_document.name }}
+
+Number of packages: {{ my_uml_document.packages | size }}
+
+{% render "package", package: my_uml_document.packages.first %}
+--
+----
+
+Where:
+
+* `path/to/example.xmi` -- path to the XMI, QEA, or LUR file.
+* `path/to/config.yml` -- path to the YAML configuration file.
+
+
+=== Configuration file format
+
+[source,yaml]
+----
+---
+ea_extension:
+  - "CityGML_MDG_Technology.xml"
+  - "ISO19103MDG v1.0.0-beta.xml"
+context_name: my_uml_document
+template_path: "path/to/liquid/templates"
+guidance: "path/to/guidance.yml"
+----
+
+Where:
+
+* `ea_extension` -- optional, list of EA extension XML files to load. Some
+  XMI/QEA/LUR files contain elements that cannot be resolved by default (e.g.
+  CityGML elements). Load their definitions here. Paths are relative to the
+  config YAML file.
+
+* `context_name` -- optional, the Liquid context variable name for the parsed
+  document. Defaults to `context`. When set, the document is accessible as
+  `{{ my_uml_document }}` instead of `{{ context }}`.
+
+* `template_path` -- optional, path to a directory containing custom Liquid
+  templates. When specified, `render` tags in the block content will use
+  templates from this directory.
+
+* `guidance` -- optional, path to a YAML guidance file for adding annotations
+  to rendered output.
+
+
+=== Usage with document index
+
+You can define an XMI/QEA/LUR file index at the document level and reference
+it by name:
+
+[source,adoc]
+----
+:lutaml-xmi-index: my-model; /path/to/example.qea
+
+[lutaml_ea_uml,index=my-model]
+--
+Name: {{ context.name }}
+--
+----
+
+Syntax for the index attribute:
+
+[source,adoc]
+----
+:lutaml-xmi-index: index_name; file_path[; config=config_path]
+----
+
+Where:
+
+* `index_name` -- name to reference later with `index=`.
+* `file_path` -- path to the XMI, QEA, or LUR file.
+* `config_path` -- optional, path to the configuration YAML file.
+
+
+=== Liquid template context
+
+The parsed UML document is exposed to Liquid templates with the following
+structure:
+
+* `context.name` -- name of the root UML model.
+* `context.packages` -- array of packages in the model.
+* `context.packages.first.name` -- name of a package.
+* `context.packages.first.packages` -- nested sub-packages.
+* `context.packages.first.classes` -- array of classes in a package.
+* `context.packages.first.classes.first.name` -- name of a class.
+* `context.packages.first.classes.first.attributes` -- array of attributes.
+* `context.packages.first.classes.first.associations` -- array of associations.
+
+When `context_name` is set in the configuration, replace `context` with the
+configured name (e.g. `my_uml_document`).
+
+
+=== Example: rendering class tables with a custom template
+
+Given a custom template at `templates/_klass.liquid`:
+
+[source,liquid]
+----
+{% for package in context.packages %}
+== {{ package.name }}
+
+{% for klass in package.classes %}
+=== {{ klass.name }}
+
+{{ klass.definition | html2adoc }}
+
+[cols="a,a"]
+|===
+| Attribute | Type
+
+{% for attr in klass.owned_props %}
+| {{ attr.name }} | {{ attr.type }}
+{% endfor %}
+
+|===
+{% endfor %}
+{% endfor %}
+----
+
+The AsciiDoc block would be:
+
+[source,adoc]
+----
+[lutaml_ea_uml,path/to/example.xmi,path/to/config.yml]
+--
+{% render "klass", context: context %}
+--
+----
+
+Where the config specifies `template_path` pointing to the templates directory.

data/lib/metanorma/plugin/lutaml/base_preprocessor.rb

@@ -171,7 +171,7 @@ module Metanorma
             )
             parsed_template.assigns["schemas_order"] =
               options["selected_schemas"]
-            parsed_template.render.split("\n", -1)
+            parsed_template.render
           end.flatten
         rescue StandardError => e
           ::Metanorma::Util.log(

data/lib/metanorma/plugin/lutaml/cache_registry.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Lutaml
+      module CacheRegistry
+        def self.xmi_cache
+          XmiCache::XMI_PARSE_CACHE
+        end
+
+        def self.xsd_cache
+          LutamlXsdPreprocessor::CACHE
+        end
+
+        def self.clear_all
+          xmi_cache.clear
+          xsd_cache.clear
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/lutaml/config.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "yaml"
-require "lutaml"
+require "lutaml/uml"
 require "lutaml/model"
 
 module Metanorma

data/lib/metanorma/plugin/lutaml/express_remark_adapter.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "expressir"
+
+module Metanorma
+  module Plugin
+    module Lutaml
+      module ExpressRemarkAdapter
+        def self.relative_path_prefix(options, model)
+          return if options.nil? || options["document"].nil?
+
+          document = options["document"]
+          file_path = File.dirname(model.file)
+          docfile_directory = File.dirname(
+            document.attributes["docfile"] || ".",
+          )
+          resolved = document.path_resolver
+            .system_path(file_path, docfile_directory)
+          File.expand_path(resolved, docfile_directory)
+        end
+
+        def self.for(model)
+          case model
+          when Expressir::Model::Cache
+            CachedRepoAdapter.new(model)
+          when Expressir::Model::Repository, Expressir::Model::ExpFile
+            RepoAdapter.new(model)
+          when Expressir::Model::ModelElement
+            ModelAdapter.new(model)
+          else
+            NullAdapter.new(model)
+          end
+        end
+
+        class Base
+          def initialize(model)
+            @model = model
+          end
+
+          def unwrap
+            @model
+          end
+
+          def decorate_remarks(options)
+            decorate_own_remarks(options)
+            decorate_child_remark_items(options)
+            traverse_children(options)
+          end
+
+          private
+
+          def decorate_own_remarks(options)
+            @model.remarks = ExpressRemarksDecorator.decorate_array(
+              @model.remarks, options
+            )
+          end
+
+          def decorate_child_remark_items(options)
+            return unless @model.is_a?(Expressir::Model::HasRemarkItems)
+
+            @model.remark_items&.each do |ri|
+              ri.remarks = ExpressRemarksDecorator.decorate_array(
+                ri.remarks, options
+              )
+            end
+          end
+
+          def traverse_children(options)
+            @model.children&.each do |child|
+              next unless traversable?(child)
+
+              ExpressRemarkAdapter.for(child).decorate_remarks(options)
+            end
+          end
+
+          def traversable?(child)
+            child.is_a?(Expressir::Model::ModelElement) &&
+              !child.is_a?(Expressir::Model::Declarations::RemarkItem)
+          end
+        end
+
+        class RepoAdapter < Base
+          def decorate_remarks(options)
+            @model.schemas.each do |schema|
+              options["relative_path_prefix"] =
+                ExpressRemarkAdapter.relative_path_prefix(options, schema)
+              ExpressRemarkAdapter.for(schema).decorate_remarks(options)
+            end
+          end
+        end
+
+        class CachedRepoAdapter < Base
+          def unwrap
+            @model.content
+          end
+
+          def decorate_remarks(options)
+            ExpressRemarkAdapter.for(@model.content).decorate_remarks(options)
+          end
+        end
+
+        class ModelAdapter < Base; end
+
+        class NullAdapter
+          def initialize(_model); end
+
+          def unwrap; end
+
+          def decorate_remarks(_options); end
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/lutaml/express_remarks_decorator.rb

@@ -24,6 +24,12 @@ module Metanorma
           new(remark, options).call
         end
 
+        def self.decorate_array(remarks, options)
+          return [] unless remarks
+
+          remarks.map { |remark| call(remark, options) }
+        end
+
         def initialize(remark, options)
           @remark = remark
           @options = options

data/lib/metanorma/plugin/lutaml/lutaml_diagram_base.rb

@@ -3,16 +3,15 @@
 require "liquid"
 require "asciidoctor"
 require "asciidoctor/reader"
-require "lutaml"
 require "lutaml/uml"
-require "lutaml/formatter"
+require "lutaml/lml"
 
 module Metanorma
   module Plugin
     module Lutaml
       module LutamlDiagramBase
         def process(parent, reader, attrs)
-          uml_document = ::Lutaml::Uml::Parsers::Dsl
+          uml_document = ::Lutaml::Lml::Parser
             .parse(lutaml_file(parent.document, reader))
           filename = generate_file(parent, reader, uml_document)
           through_attrs = generate_attrs(attrs)

data/lib/metanorma/plugin/lutaml/lutaml_ea_diagram_block_macro.rb

@@ -27,24 +27,45 @@ module Metanorma
         private
 
         def parse_result_document(full_path, guidance = nil)
-          ::Lutaml::Xmi::Parsers::Xml.serialize_xmi_to_liquid(
-            File.new(full_path, encoding: "UTF-8"),
+          ::Ea::Xmi::Parser.serialize_to_liquid(
+            full_path,
             guidance,
           )
         end
 
-        def get_original_document(parent, index = nil)
+        def get_original_document(parent, index = nil) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
           path = get_path_from_index(parent, index) if index
 
           if index && path
-            doc = lutaml_document_from_file_or_cache(
+            return lutaml_document_from_file_or_cache(
               parent.document, path,
               Metanorma::Plugin::Lutaml::Config::Root.new
             )
           end
 
-          doc ||= parent.document.attributes["lutaml_xmi_cache"].values.first
-          doc
+          # get the first document from lutaml_xmi_cache
+          first_path = parent
+            .document.attributes["lutaml_xmi_cache"]&.keys&.first
+          if first_path
+            return lutaml_document_from_file_or_cache(
+              parent.document, first_path,
+              Metanorma::Plugin::Lutaml::Config::Root.new
+            )
+          end
+
+          # get the first document from the first lutaml_xmi_index
+          first_index = parent
+            .document.attributes["lutaml_xmi_index"]&.keys&.first
+
+          return unless first_index
+
+          path_from_index = get_path_from_index(parent, first_index)
+          return unless path_from_index
+
+          lutaml_document_from_file_or_cache(
+            parent.document, path_from_index,
+            Metanorma::Plugin::Lutaml::Config::Root.new
+          )
         end
 
         def img_src_path(document, attrs, diagram)

data/lib/metanorma/plugin/lutaml/lutaml_ea_uml_preprocessor.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "liquid"
+require "asciidoctor"
+require "asciidoctor/reader"
+require "lutaml/uml"
+require_relative "utils"
+require "metanorma/plugin/lutaml/asciidoctor/preprocessor"
+require "metanorma/plugin/lutaml/lutaml_ea_xmi_base"
+
+module Metanorma
+  module Plugin
+    module Lutaml
+      #  Macro for rendering Lutaml::Uml models which are parsing from
+      #  XMI/QEA/LUR file
+      class LutamlEaUmlPreprocessor < ::Asciidoctor::Extensions::Preprocessor
+        include LutamlEaXmiBase
+
+        MACRO_REGEXP = /\[lutaml_ea_uml,([^,]+),?(.+)?\]/
+
+        private
+
+        def parse_result_document(full_path, _guidance)
+          case File.extname(full_path).downcase
+          when ".xmi"
+            ::Ea::Xmi::Parser.parse(full_path)
+          when ".qea"
+            ::Ea.to_uml(full_path)
+          when ".lur"
+            repo = ::Lutaml::UmlRepository::Repository.from_file(full_path)
+            repo.document
+          end
+        end
+
+        def process_text_blocks(document, input_lines) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+          line = input_lines.next
+
+          process_xmi_index_lines(document, line)
+          block_match = line.match(get_macro_regexp)
+
+          return [line] if block_match.nil?
+
+          config_yaml_path = block_match[2]&.strip
+          filepath_or_index = block_match[1]&.strip
+
+          lutaml_document, yaml_config = load_lutaml_doc_and_config(
+            document,
+            filepath_or_index,
+            config_yaml_path,
+          )
+
+          block_lines = collect_block_lines(input_lines, input_lines.next)
+
+          render_result, errors = Utils.render_liquid_string(
+            template_string: block_lines.join("\n"),
+            contexts: create_default_context_object(
+              lutaml_document, yaml_config
+            ),
+            document: document,
+            include_path: template_path(document, yaml_config.template_path),
+          )
+          Utils.notify_render_errors(document, errors)
+
+          render_result.split("\n")
+        end
+
+        def create_default_context_object(uml_document, options)
+          context_name = "context"
+          if options.context_name
+            context_name = options.context_name
+          end
+          contexts = {}
+          contexts[context_name] = uml_document.to_liquid
+          contexts
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/lutaml/lutaml_ea_xmi_base.rb

@@ -39,6 +39,61 @@ module Metanorma
 
         private
 
+        def lutaml_document_from_file_or_cache(document, file_path, yaml_config, yaml_config_path = nil) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Metrics/CyclomaticComplexity,Layout/LineLength,Metrics/PerceivedComplexity
+          full_path = Utils.relative_file_path(document, file_path)
+          if document.attributes["lutaml_xmi_cache"] &&
+              document.attributes["lutaml_xmi_cache"][full_path]
+            return document.attributes["lutaml_xmi_cache"][full_path]
+          end
+
+          guidance = get_guidance(document, yaml_config.guidance)
+          result_document = parse_result_document(full_path, guidance)
+
+          # load EA extensions for Xmi::EaRoot
+          yaml_config.ea_extension&.each do |ea_extension_path|
+            # resolve paths of ea extensions based on the location of
+            # config yaml file
+            ea_extension_full_path = File.expand_path(
+              ea_extension_path, File.dirname(yaml_config_path)
+            )
+
+            # unload the extension if it is already loaded
+            xmi_doc = Nokogiri::XML(File.read(ea_extension_full_path))
+            extension_id = Xmi::EaRoot.get_module_name(xmi_doc)
+            if Xmi::EaRoot.extension_loaded?(extension_id)
+              Xmi::EaRoot.unload_extension(extension_id)
+            end
+
+            Xmi::EaRoot.load_extension(ea_extension_full_path)
+          end
+
+          # store in document.attributes as cache
+          document.attributes["lutaml_xmi_cache"] ||= {}
+          document.attributes["lutaml_xmi_cache"][full_path] = result_document
+
+          result_document
+        end
+
+        def get_guidance(document, guidance_config)
+          return unless guidance_config
+
+          guidance_yaml = Utils.relative_file_path(document, guidance_config)
+          guidance = Metanorma::Plugin::Lutaml::Config::Guidance.from_yaml(
+            File.read(guidance_yaml, encoding: "UTF-8"),
+          )
+          guidance.to_yaml_hash
+        end
+
+        def parse_yaml_config_file(document, file_path)
+          return Metanorma::Plugin::Lutaml::Config::Root.new if file_path.nil?
+
+          relative_file_path = Utils.relative_file_path(document, file_path)
+
+          Metanorma::Plugin::Lutaml::Config::Root.from_yaml(
+            File.read(relative_file_path, encoding: "UTF-8"),
+          )
+        end
+
         def get_xmi_path(parent, target, attrs)
           return get_path_from_index(parent, attrs["index"]) if attrs["index"]
 
@@ -106,8 +161,8 @@ module Metanorma
           )
         end
 
-        def load_lutaml_doc_and_config(document, xmi_or_index, config_yaml_path) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
-          index = xmi_or_index.match(/index=(.*)/)
+        def load_lutaml_doc_and_config(document, filepath_or_index, config_yaml_path) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Layout/LineLength
+          index = filepath_or_index.match(/index=(.*)/)
 
           if index
             index_name = index[1]
@@ -121,7 +176,7 @@ module Metanorma
               )
             end
 
-            xmi_or_index = document
+            filepath_or_index = document
               .attributes["lutaml_xmi_index"][index_name][:path]
             config_yaml_path = document
               .attributes["lutaml_xmi_index"][index_name][:config]
@@ -130,7 +185,7 @@ module Metanorma
           yaml_config = parse_yaml_config_file(document, config_yaml_path)
           lutaml_document = lutaml_document_from_file_or_cache(
             document,
-            xmi_or_index,
+            filepath_or_index,
             yaml_config,
             Utils.relative_file_path(document, config_yaml_path),
           )