suma 0.2.6 → 0.3.0

data/lib/suma/schema_naming.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Suma
+  # Converts EXPRESS schema identifiers into human-readable display names.
+  #
+  # Naming is model-driven: the schema type (resource/module) and suffix
+  # determine how the identifier is formatted. Acronyms and numeric
+  # prefixes are preserved to match ISO 10303 conventions.
+  #
+  # @example
+  #   SchemaNaming.display_name("topology_schema")
+  #   # => "Topology"
+  #   SchemaNaming.display_name("Activity_method_assignment_mim")
+  #   # => "Activity Method Assignment (MIM)"
+  #   SchemaNaming.display_name("aic_advanced_brep")
+  #   # => "AIC Advanced Brep"
+  module SchemaNaming
+    # Acronyms preserved as uppercase during title-casing.
+    # Source: ISO 10303 naming conventions.
+    ACRONYMS = %w[
+      aic aec apu bom csg edraw id ifc pdf pld
+      xml xpdl 2d 3d
+    ].freeze
+
+    # Lowercase function words (ISO title-case convention).
+    LOWERCASE_WORDS = %w[a an and as for in of on or the to].freeze
+
+    # Suffixes stripped from the schema name before title-casing,
+    # mapped to the parenthesised label appended to the display name.
+    # A +nil+ label means the suffix is stripped silently.
+    SUFFIXES = {
+      "_arm" => "ARM",
+      "_mim" => "MIM",
+      "_bom" => "BOM",
+      "_schema" => nil,
+    }.freeze
+
+    class << self
+      # Produce a human-readable display name from a schema identifier.
+      #
+      # @param schema_id [String] the EXPRESS schema identifier
+      # @return [String] human-readable name
+      def display_name(schema_id)
+        base, label = decompose(schema_id)
+        title_cased = title_case(base)
+        label ? "#{title_cased} (#{label})" : title_cased
+      end
+
+      # Produce a prefixed display name with the schema category.
+      #
+      # @param schema_id [String] the EXPRESS schema identifier
+      # @param path [String, Pathname] the schema file path (for classification)
+      # @return [String] e.g. "Resource: Topology" or "Module: Activity (ARM)"
+      def prefixed_name(schema_id, path: nil)
+        type = ExpressSchema::Type.classify(id: schema_id, path: path)
+        prefix = category_prefix(type)
+        "#{prefix}: #{display_name(schema_id)}"
+      end
+
+      # Determine the category prefix for a schema type.
+      #
+      # @param type [Symbol] one of ExpressSchema::Type constants
+      # @return [String]
+      def category_prefix(type)
+        SchemaCategory.for_type(type).prefix
+      end
+
+      private
+
+      # Split a schema ID into (base_without_suffix, suffix_label_or_nil).
+      #
+      # @return [(String, String, nil)]
+      def decompose(schema_id)
+        SUFFIXES.each do |suffix, label|
+          if schema_id.end_with?(suffix)
+            return [schema_id.delete_suffix(suffix),
+                    label]
+          end
+        end
+        [schema_id, nil]
+      end
+
+      # Title-case a snake_case identifier, preserving acronyms.
+      # The +tr+ collapses runs of underscores (leading, trailing, and
+      # consecutive) into spaces, which +split+ then treats as a single
+      # separator.
+      #
+      # @param name [String] snake_case identifier
+      # @return [String] title-cased name
+      def title_case(name)
+        words = name.tr("_", " ").split
+        words.each_with_index.map do |word, i|
+          capitalize_word(word, first: i.zero?)
+        end.join(" ")
+      end
+
+      # Capitalise a single word, preserving acronyms and
+      # lowercasing function words (except when first in the name).
+      #
+      # @param word [String]
+      # @param first [Boolean] whether this is the first word
+      # @return [String]
+      def capitalize_word(word, first: false)
+        return word.upcase if ACRONYMS.include?(word.downcase)
+        return word.downcase if LOWERCASE_WORDS.include?(word.downcase) && !first
+
+        word.capitalize
+      end
+    end
+  end
+end

data/lib/suma/schema_template/document.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Suma
+  module SchemaTemplate
+    # Emits an AsciiDoc body with cross-reference anchors for every
+    # schema element so other documents can deep-link into the compiled
+    # HTML. Only XML is produced — the anchors only resolve against the
+    # XML output, not the HTML rendering.
+    class Document
+      EXTENSIONS = "xml"
+
+      attr_reader :schema_id
+
+      def initialize(schema_id)
+        @schema_id = schema_id
+      end
+
+      def extensions
+        EXTENSIONS
+      end
+
+      def render(path_to_schema_yaml)
+        <<~ADOC
+          = #{schema_id}
+          :lutaml-express-index: schemas; #{path_to_schema_yaml};
+          :bare: true
+          :mn-document-class: iso
+          :mn-output-extensions: #{extensions}
+
+          [lutaml_express_liquid,schemas,context]
+          ----
+          {% for schema in context.schemas %}
+
+          [[#{schema_id}]]
+          [%unnumbered,type=express]
+          == #{schema_id} #{rendered_anchors}
+
+          [source%unnumbered]
+          --
+          {{ schema.formatted }}
+          --
+          {% endfor %}
+          ----
+
+        ADOC
+      end
+
+      private
+
+      # The raw anchor block contains Liquid comments and newlines that
+      # are illegal on the section header line; strip them before
+      # interpolating.
+      def rendered_anchors
+        schema_anchors.gsub(%r{//[^\r\n]+}, "").gsub(/[\n\r]+/, "").gsub(
+          /^[\n\r]/, ""
+        )
+      end
+
+      def schema_anchors
+        <<~HEREDOC
+          // _fund_cons.liquid
+          [[#{schema_id}_funds]]
+
+          // _constants.liquid
+          {% if schema.constants.size > 0 %}
+          #{bookmark('constants')}
+          {% for thing in schema.constants %}
+          #{bookmark('{{thing.id}}')}
+          {% endfor %}
+          {% endif %}
+
+          // _types.liquid
+          {% if schema.types.size > 0 %}
+          #{bookmark('types')}
+          // _type.liquid
+          {% for thing in schema.types %}
+          #{bookmark('{{thing.id}}')}
+          {% if thing.items.size > 0 %}
+          // _type_items.liquid
+          #{bookmark('{{thing.id}}.items')}
+          {% for item in thing.items %}
+          #{bookmark('{{thing.id}}.items.{{item.id}}')}
+          {% endfor %}
+          {% endif %}
+          {% endfor %}
+          {% endif %}
+
+          // _entities.liquid
+          {% if schema.entities.size > 0 %}
+          #{bookmark('entities')}
+          {% for thing in schema.entities %}
+          // _entity.liquid
+          #{bookmark('{{thing.id}}')}
+          {% endfor %}
+          {% endif %}
+
+          // _subtype_constraints.liquid
+          {% if schema.subtype_constraints.size > 0 %}
+          #{bookmark('subtype_constraints')}
+          // _subtype_constraint.liquid
+          {% for thing in schema.subtype_constraints %}
+          #{bookmark('{{thing.id}}')}
+          {% endfor %}
+          {% endif %}
+
+          // _functions.liquid
+          {% if schema.functions.size > 0 %}
+          #{bookmark('functions')}
+          // _function.liquid
+          {% for thing in schema.functions %}
+          #{bookmark('{{thing.id}}')}
+          {% endfor %}
+          {% endif %}
+
+          // _procedures.liquid
+          {% if schema.procedures.size > 0 %}
+          #{bookmark('procedures')}
+          // _procedure.liquid
+          {% for thing in schema.procedures %}
+          #{bookmark('{{thing.id}}')}
+          {% endfor %}
+          {% endif %}
+
+          // _rules.liquid
+          {% if schema.rules.size > 0 %}
+          #{bookmark('rules')}
+          // _rule.liquid
+          {% for thing in schema.rules %}
+          #{bookmark('{{thing.id}}')}
+          {% endfor %}
+          {% endif %}
+        HEREDOC
+      end
+
+      def bookmark(anchor)
+        mangled = anchor.gsub("}}", ' | replace: "\", "-", "-}}')
+        "[[#{schema_id}.#{mangled}]]"
+      end
+    end
+  end
+end

data/lib/suma/schema_template/plain.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Suma
+  module SchemaTemplate
+    # Emits a plain AsciiDoc body for a single EXPRESS schema, producing
+    # both HTML and XML outputs via Metanorma.
+    class Plain
+      EXTENSIONS = "xml,html"
+
+      attr_reader :schema_id
+
+      def initialize(schema_id)
+        @schema_id = schema_id
+      end
+
+      def extensions
+        EXTENSIONS
+      end
+
+      def render(path_to_schema_yaml)
+        <<~ADOC
+          = #{schema_id}
+          :lutaml-express-index: schemas; #{path_to_schema_yaml};
+          :bare: true
+          :mn-document-class: iso
+          :mn-output-extensions: #{extensions}
+
+          [lutaml_express_liquid,schemas,context]
+          ----
+          {% for schema in context.schemas %}
+
+          [%unnumbered]
+          == #{schema_id}
+
+          [source%unnumbered]
+          --
+          {{ schema.formatted }}
+          --
+          {% endfor %}
+          ----
+
+        ADOC
+      end
+    end
+  end
+end

data/lib/suma/schema_template.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Suma
+  # Pure renderers for the AsciiDoc source fed to Metanorma when compiling
+  # an EXPRESS schema to HTML/XML.
+  #
+  # Each template knows how to produce the adoc body for one compilation
+  # flavour (plain HTML, or HTML with cross-reference anchors). Templates
+  # have no I/O and no knowledge of the underlying ExpressSchema — they
+  # only need the schema id, because the rendered adoc is consumed by
+  # Liquid inside Metanorma, which fetches the schema by id from the
+  # surrounding lutaml-express-index.
+  #
+  # Composition with the compiler lives in SchemaCompiler.
+  module SchemaTemplate
+    autoload :Plain, "suma/schema_template/plain"
+    autoload :Document, "suma/schema_template/document"
+  end
+end

data/lib/suma/svg_quality/batch_report.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "report"
-
 module Suma
   module SvgQuality
     # Batch report wrapping multiple SVG quality reports

data/lib/suma/svg_quality/formatters.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Suma
+  module SvgQuality
+    module Formatters
+      autoload :TerminalFormatter,
+               "suma/svg_quality/formatters/terminal_formatter"
+      autoload :JsonFormatter,     "suma/svg_quality/formatters/json_formatter"
+      autoload :YamlFormatter,     "suma/svg_quality/formatters/yaml_formatter"
+    end
+  end
+end

data/lib/suma/svg_quality.rb

@@ -4,7 +4,9 @@ require "svg_conform"
 
 module Suma
   module SvgQuality
-    # Quality levels computed from error count
+    autoload :Report,      "suma/svg_quality/report"
+    autoload :BatchReport, "suma/svg_quality/batch_report"
+
     module QualityTiers
       CRITICAL = { name: :critical, min_errors: 200, emoji: "💥" }.freeze
       HIGH = { name: :high, min_errors: 100, emoji: "🔴" }.freeze

data/lib/suma/term_extractor.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "fileutils"
-require_relative "utils"
 require "expressir"
 require "glossarist"
 
@@ -16,13 +15,16 @@ module Suma
         \s*?\.?$               # Optional whitespace and period at the end
       }x
 
-    def initialize(schema_manifest_file, output_path, language_code: "eng")
+    def initialize(schema_manifest_file, output_path, urn:,
+                   language_code: "eng")
       @schema_manifest_file = File.expand_path(schema_manifest_file)
       @output_path = output_path
       @language_code = language_code
+      @urn = Suma::Urn.new(urn)
     end
 
     def call
+      validate_inputs
       get_exp_files.map do |exp_file|
         extract(exp_file)
       end
@@ -30,12 +32,24 @@ module Suma
 
     private
 
+    def validate_inputs
+      unless File.exist?(@schema_manifest_file)
+        raise Errno::ENOENT, "Specified SCHEMA_MANIFEST_FILE " \
+                             "`#{@schema_manifest_file}` not found."
+      end
+      unless File.file?(@schema_manifest_file)
+        raise Errno::ENOENT, "Specified SCHEMA_MANIFEST_FILE " \
+                             "`#{@schema_manifest_file}` is not a file."
+      end
+    end
+
     def get_exp_files
       config = Expressir::SchemaManifest.from_file(@schema_manifest_file)
       paths = config.schemas.map(&:path)
 
       if paths.empty?
-        raise Errno::ENOENT, "No EXPRESS files found in `#{@schema_manifest_file}`."
+        raise Errno::ENOENT,
+              "No EXPRESS files found in `#{@schema_manifest_file}`."
       end
 
       paths
@@ -56,33 +70,55 @@ module Suma
     end
 
     def output_data(collection)
-      FileUtils.mkdir_p(File.expand_path(@output_path)) unless File.exist?(@output_path)
+      output_dir = File.expand_path(@output_path)
+      FileUtils.mkdir_p(output_dir)
       Utils.log "Saving collection to files in: #{@output_path}"
-      collection.save_to_files(File.expand_path(@output_path))
+
+      collection.each do |concept|
+        doc = Glossarist::V3::ConceptDocument.from_managed_concept(concept)
+        doc.localizations = concept.data.localizations.keys.map do |lang|
+          concept.localization(lang)
+        end
+
+        filename = "#{concept.uuid.gsub(/[^\w.-]/, '_')}.yaml"
+        File.write(File.join(output_dir, filename), doc.to_yamls,
+                   encoding: "utf-8")
+      end
     end
 
     def build_managed_concept_collection(schema)
       source_ref = get_source_ref(schema)
+      section_ref = get_section_ref(schema)
 
       Glossarist::ManagedConceptCollection.new.tap do |collection|
         schema.entities.each do |entity|
+          localized_concept_id = Glossarist::Utilities::UUID.uuid_v5(
+            Glossarist::Utilities::UUID::OID_NAMESPACE,
+            "#{schema.id}.#{entity.id}-#{@language_code}",
+          )
+
           localized_concept = build_localized_concept(
             schema: schema,
             entity: entity,
             source_ref: source_ref,
+            uuid: localized_concept_id,
           )
-          localized_concept_id = get_localized_concept_identifier(schema, entity)
 
-          managed_data = Glossarist::ManagedConceptData.new.tap do |data|
-            data.id = get_entity_identifier(schema, entity)
-            data.localizations[@language_code] = localized_concept
+          managed_data = Glossarist::V3::ManagedConceptData.new.tap do |data|
+            data.id = "#{schema.id}.#{entity.id}"
+            data.localizations.store(@language_code, localized_concept)
             data.localized_concepts = { @language_code => localized_concept_id }
+            data.domains = [section_ref] if section_ref
           end
 
-          managed_concept = Glossarist::ManagedConcept.new.tap do |concept|
-            concept.id = get_entity_identifier(schema, entity)
-            concept.uuid = concept.id
+          managed_concept = Glossarist::V3::ManagedConcept.new.tap do |concept|
+            concept.id = managed_data.id
+            concept.uuid = Glossarist::Utilities::UUID.uuid_v5(
+              Glossarist::Utilities::UUID::OID_NAMESPACE,
+              managed_data.id,
+            )
             concept.data = managed_data
+            concept.schema_version = "v3"
           end
 
           collection.store(managed_concept)
@@ -90,10 +126,10 @@ module Suma
       end
     end
 
-    def build_localized_concept(schema:, entity:, source_ref:)
+    def build_localized_concept(schema:, entity:, source_ref:, uuid:)
       schema_domain = get_domain(schema)
 
-      localized_concept_data = Glossarist::ConceptData.new.tap do |data|
+      localized_concept_data = Glossarist::V3::ConceptData.new.tap do |data|
         data.terms = get_entity_terms(entity)
         data.definition = get_entity_definitions(entity, schema)
         data.language_code = @language_code
@@ -105,34 +141,60 @@ module Suma
         data.examples = []
       end
 
-      Glossarist::LocalizedConcept.new.tap { |c| c.data = localized_concept_data }
+      Glossarist::V3::LocalizedConcept.new(
+        data: localized_concept_data, uuid: uuid,
+      )
+    end
+
+    def schema_urn(schema)
+      @urn.for_schema(schema.id)
+    end
+
+    def term_urn(concept_identifier)
+      @urn.for_term(concept_identifier)
     end
 
-    def get_entity_identifier(schema, entity)
-      "#{schema.id}.#{entity.id}"
+    def express_entity_urn(full_ref)
+      @urn.for_entity(full_ref)
     end
 
-    def get_localized_concept_identifier(schema, entity)
-      "#{schema.id}.#{entity.id}-#{@language_code}"
+    def urn_mention(urn, display)
+      "{{#{urn},#{display}}}"
+    end
+
+    def get_section_ref(schema)
+      return nil unless @urn
+
+      Glossarist::ConceptReference.new(
+        concept_id: "section-#{schema.id}",
+        source: schema_urn(schema),
+        ref_type: "section",
+      )
     end
 
     def get_source_ref(schema)
-      origin = Glossarist::Citation.new.tap do |citation|
-        citation.ref = "ISO 10303"
-        custom_locality = build_custom_locality(schema)
-        citation.custom_locality = custom_locality unless custom_locality.empty?
+      ref = Glossarist::Citation::Ref.new
+      ref.source = schema_urn(schema)
+
+      build_custom_locality(schema).each do |cl|
+        case cl.name
+        when "version" then ref.version = cl.value
+        end
       end
 
-      Glossarist::ConceptSource.new(type: "authoritative", origin: origin)
+      origin = Glossarist::V3::Citation.new
+      origin.ref = ref
+      Glossarist::V3::ConceptSource.new(id: schema.id, type: "authoritative",
+                                        origin: origin)
     end
 
     def build_custom_locality(schema)
       localities = []
-      localities << Glossarist::CustomLocality.new(name: "schema", value: schema.id)
 
       version_item = schema.version.items.detect { |i| i.name == "version" }
       if version_item
-        localities << Glossarist::CustomLocality.new(name: "version", value: version_item.value)
+        localities << Glossarist::CustomLocality.new(name: "version",
+                                                     value: version_item.value)
       end
 
       localities
@@ -160,10 +222,10 @@ module Suma
 
     def get_entity_definitions(entity, schema)
       schema_type = extract_file_type(schema.file)
-      schema_domain = get_domain(schema)
+      get_domain(schema)
 
-      definition = generate_entity_definition(entity, schema_domain, schema_type)
-      [Glossarist::DetailedDefinition.new(content: definition)]
+      definition = generate_entity_definition(entity, schema, schema_type)
+      [Glossarist::V3::DetailedDefinition.new(content: definition)]
     end
 
     def get_entity_notes(entity, schema_domain, definitions)
@@ -172,7 +234,7 @@ module Suma
       if entity.remarks && !entity.remarks.empty?
         trimmed_def = trim_definition(entity.remarks)
         if trimmed_def && !trimmed_def.empty?
-          notes << Glossarist::DetailedDefinition.new(
+          notes << Glossarist::V3::DetailedDefinition.new(
             content: convert_express_xref(trimmed_def, schema_domain),
           )
         end
@@ -343,11 +405,14 @@ module Suma
 
     def express_reference_to_mention(description)
       description
-        .gsub(/<<express:([^,]+)>>/) do |_match|
-          "{{#{Regexp.last_match[1].split('.').last}}}"
-        end.gsub(/<<express:([^,]+),([^>]+)>>/) do |_match|
-          "{{#{Regexp.last_match[1].split('.').last}," \
-            "#{Regexp.last_match[2]}}}"
+        .gsub(/<<express:([\w.]+)>>/) do |_match|
+          full_ref = Regexp.last_match[1]
+          entity_id = full_ref.split(".").last
+          urn_mention(express_entity_urn(full_ref), entity_id)
+        end.gsub(/<<express:([\w.]+),([\w. ][\w. ]*)>>/) do |_match|
+          full_ref = Regexp.last_match[1]
+          display = Regexp.last_match(2)
+          urn_mention(express_entity_urn(full_ref), display)
         end
     end
 
@@ -355,38 +420,46 @@ module Suma
       entity_id.downcase.gsub("_", " ")
     end
 
-    def generate_entity_definition(entity, _domain, schema_type)
+    def generate_entity_definition(entity, schema, schema_type)
       return "" if entity.nil?
 
       entity_type = case schema_type
                     when "module_arm"
-                      "{{application object}}"
+                      urn_mention(term_urn("general.application_object"),
+                                  "application object")
                     when "module_mim"
-                      "{{entity data type}}"
+                      urn_mention(term_urn("express-language.entity_data_type"),
+                                  "entity data type")
                     when "resource", "business_object_model"
-                      "{{entity data type}}"
+                      urn_mention(term_urn("express-language.entity_data_type"),
+                                  "entity data type")
                     else
                       raise Error, "[suma] encountered unsupported schema_type"
                     end
 
+      entity_ref = urn_mention(term_urn("express-language.entity"), "entity")
+
       if entity.subtype_of.empty?
         "#{entity_type} " \
           "that represents the " \
-          "#{entity_name_to_text(entity.id)} {{entity}}"
+          "#{entity_name_to_text(entity.id)} #{entity_ref}"
       else
-        entity_subtypes = entity.subtype_of.map { |e| "{{#{e.id}}}" }
+        entity_subtypes = entity.subtype_of.map do |e|
+          urn_mention(express_entity_urn("#{schema.id}.#{e.id}"), e.id)
+        end
 
         "#{entity_type} that is a type of " \
           "#{entity_subtypes.join(' and ')} " \
           "that represents the " \
-          "#{entity_name_to_text(entity.id)} {{entity}}"
+          "#{entity_name_to_text(entity.id)} #{entity_ref}"
       end
     end
 
-    def convert_express_xref(content, schema_domain)
-      content.gsub(/<<express:(.*),(.*)>>/) do
-        "{{<#{schema_domain}>" \
-          "#{Regexp.last_match(1).split('.').last},#{Regexp.last_match(2)}}}"
+    def convert_express_xref(content, _schema_domain)
+      content.gsub(/<<express:([\w.]+),([\w. ][\w. ]*)>>/) do
+        full_ref = Regexp.last_match(1)
+        display = Regexp.last_match(2)
+        urn_mention(express_entity_urn(full_ref), display)
       end
     end
   end