expressir 2.4.17 → 2.4.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fb8953f2f2e9d76be3693148c8951ae36f562bbaf8214a8bc510b68888700d2
-  data.tar.gz: dfbcc336cc1a580501ca69632d6e6bb348e196be470cbc712a637131ffe1993c
+  metadata.gz: a5174add01b6b7053e2317d479e746ba330901c6bdc547d5ba7429ea46889ae3
+  data.tar.gz: 66bd27f4a626a956e840f90013bbe5ce7dc6817f127c554bccf5cb413cbd2981
 SHA512:
-  metadata.gz: 2e5259fb143ac5419ab85b8a97e8ab50a3a809826f799b8cd74242a673599c5cac0bd21cfe1dc33af562c16a806afc95f9f43f75f8eba43e18b68377104d5406
-  data.tar.gz: 0d2520a7a817f1c8d72a6f768887e803c91a6070f3cf8d4230bde9e66dcb6a1580ff7ee39ac6e9c886106cde64db14e175db57e81be0b798ea8f45af57bfaaa7
+  metadata.gz: 6aa415b0bd88d3cf5bd95d3786b01dff6f66e00e13ca95a3a19755f1e60cc17163800841fd9f7ea21d98acee505c0b67ae1ef6a3e3e032394cfb848395b1295d
+  data.tar.gz: ce39ba436ff04bf239e16744625c2e989b75db1674ffed24314d9fb75ae393e0f3b9ca8f0ab9263a47cd79572807e958f29ebfcedc88c42f00e886c9dd75a14f

data/lib/expressir/commands/mapping_validate.rb

@@ -2,27 +2,47 @@
 
 module Expressir
   module Commands
-    # `expressir mapping validate` (#88): load a module mapping.yaml
-    # and resolve every <<express:...>> link against the ARM/MIM
-    # interface closure. Exits 1 when unknown links remain.
+    # `expressir mapping validate` (#88): load a module mapping.yaml,
+    # resolve every <<express:...>> link and every reference path
+    # against the ARM/MIM interface closure. Exits 1 when unknown
+    # links or refpath issues remain.
     class MappingValidate < Base
       def run(path)
         document = Expressir::Mapping.load_file(path)
-        unknown = Expressir::Mapping.unknown_links(document, repository_for(path))
-
-        if unknown.empty?
-          say "all links resolve"
-          return
-        end
+        repository = repository_for(path)
 
+        unknown = Expressir::Mapping.unknown_links(document, repository)
         unknown.each do |link|
           say "unknown: #{link.text}"
         end
-        raise Thor::Error, "#{unknown.size} unknown link(s)"
+
+        issues = refpath_issues(document, repository)
+        issues.each do |location, issue|
+          say "refpath #{location} [step #{issue.step}]: #{issue.message}"
+        end
+
+        total = unknown.size + issues.size
+        unless total.zero?
+          raise Thor::Error, "#{unknown.size} unknown link(s), " \
+                             "#{issues.size} refpath issue(s)"
+        end
+
+        say "all links and reference paths resolve"
       end
 
       private
 
+      def refpath_issues(document, repository)
+        Expressir::Mapping.refpaths(document).flat_map do |location, content|
+          parsed = Expressir::Mapping::RefPath.parse(content)
+          parsed.parse_errors.map do |error|
+            [location, Expressir::Mapping::RefPath::Issue.new(step: nil,
+                                                              message: error)]
+          end + Expressir::Mapping::RefPath.validate(parsed, repository)
+            .map { |issue| [location, issue] }
+        end
+      end
+
       def repository_for(path)
         dir = File.dirname(File.expand_path(path))
         arm = Dir[File.join(dir, "arm.exp")].first

data/lib/expressir/mapping/refpath.rb

@@ -0,0 +1,357 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Mapping
+    # Formalization, parser, and validator for MIM reference paths
+    # (expressir#88): the "Reference path" sections of module
+    # mapping.yaml files, written in the ISO 10303 module mapping
+    # notation. Until now the notation was prose for humans only; this
+    # makes it machine-readable and checks it against real schemas.
+    #
+    # Grammar (corpus-verified over all module mapping.yaml refpaths):
+    #   path       := step+
+    #   step       := [link] node [index] [constraint]
+    #               | MARKER
+    #   link       := "->" | "<-" | "<=" | "=>" | "=" NAME
+    #                                            (relation to the previous node)
+    #   node       := NAME ["." ATTRIBUTE]
+    #   index      := "[" ("i" | DIGITS) "]"
+    #   MARKER     := "{" | "}" | "[" | "]" | "(" | ")" | ":" | "|" | "!"
+    #               | "," | "/" | "*"           (grouping/annotation; no
+    #                                            node semantics; never
+    #                                            breaks a pending link)
+    #   constraint := "=" STRING
+    #
+    # Operator semantics per the module conventions:
+    #   ->   the attribute named before -> references the entity or
+    #        select type named after ->
+    #   <-   the attribute named before <- is referenced by the type
+    #        named after <-
+    #   <=   the entity named before <= is a subtype of the entity after
+    #   =>   the entity named before => is a supertype of the entity after
+    #   =    the node before = is of the type named after (used inside
+    #        parenthesized alternatives, e.g. `(unit = named_unit)`)
+    #   [i]  the attribute named before [i] is an aggregate; any element
+    #        of that aggregate is referred to
+    module RefPath
+      # Wire-name mapping is declared here so a parsed path can itself
+      # be serialized with lutaml-model.
+      class Step < Lutaml::Model::Serializable
+        attribute :operator, :string
+        attribute :name, :string
+        attribute :attribute, :string
+        attribute :index, :string
+        attribute :literal, :string
+
+        key_value do
+          map "operator", to: :operator
+          map "name", to: :name
+          map "attribute", to: :attribute
+          map "index", to: :index
+          map "literal", to: :literal
+        end
+      end
+
+      class Path < Lutaml::Model::Serializable
+        attribute :steps, Step, collection: true
+        attribute :parse_errors, :string, collection: true
+
+        key_value do
+          map "steps", to: :steps
+          map "parse_errors", to: :parse_errors
+        end
+      end
+
+      TOKEN = /->|<-|<=|=>|[{}\[\]()=:|!,*\/]|'(?:''|[^'])*'|\w+(?:\.\w+)?/
+      MARKERS = ["{", "}", "[", "]", "(", ")", ":", "|", "!", ",", "/",
+                 "*", "MAPPING_OF"].freeze
+      LINKS = ["->", "<-", "<=", "=>"].freeze
+      DECLARATION_COLLECTIONS = %i[types entities].freeze
+      private_constant :TOKEN, :MARKERS, :LINKS, :DECLARATION_COLLECTIONS
+
+      Issue = Struct.new(:step, :message, keyword_init: true)
+
+      module_function
+
+      # @param content [String] the mapping.yaml refpath content block
+      # @return [Path]
+      def parse(content)
+        tokens = content.to_s.scan(TOKEN)
+        steps = []
+        errors = []
+        pending_link = nil
+        pending_type_assign = false
+        i = 0
+        while i < tokens.length
+          token = tokens[i]
+          case token
+          when *LINKS
+            pending_link = token
+          when "="
+            literal = tokens[i + 1]
+            if literal&.start_with?("'")
+              attach(steps, errors, :literal, literal)
+              i += 1
+            elsif literal.nil?
+              errors << "constraint '=' with nothing after it"
+            else
+              # `x = Type` type assignment: the following node (however
+              # many markers it sits behind, e.g. /MAPPING_OF(X)/)
+              # carries the "=" link.
+              pending_type_assign = true
+            end
+          when "["
+            if index_token?(tokens[i + 1])
+              attach(steps, errors, :index, tokens[i + 1])
+              i += 2 # the index token and the closing "]"
+            else
+              steps << Step.new(operator: "[")
+            end
+          when *MARKERS
+            steps << Step.new(operator: token)
+          else
+            name, _, attribute = token.partition(".")
+            operator = pending_link || ("=" if pending_type_assign)
+            steps << Step.new(operator: operator, name: name,
+                              attribute: attribute.empty? ? nil : attribute)
+            pending_link = nil
+            pending_type_assign = false
+          end
+          i += 1
+        end
+        Path.new(steps: steps, parse_errors: errors)
+      end
+
+      def index_token?(token)
+        token == "i" || token&.match?(/\A\d+\z/)
+      end
+
+      # Attach an index or constraint literal to the most recent node
+      # step that does not carry one yet.
+      def attach(steps, errors, field, value)
+        step = steps.reverse.each.find { |s| s.name && !s.public_send(field) }
+        if step
+          step.public_send("#{field}=", value)
+        else
+          case field
+          when :index then errors << "aggregate index [#{value}] has no node"
+          when :literal then errors << "constraint #{value} has no node"
+          end
+        end
+      end
+
+      # Validate a parsed path against a repository. Issues reference
+      # the step index they attach to.
+      # @return [Array<Issue>]
+      def validate(path, repository)
+        by_name = name_index(repository)
+        issues = []
+        prev = nil
+        last_qualified = nil
+        path.steps.each_with_index do |step, pos|
+          # markers never break the running link, mirroring parse
+          next if MARKERS.include?(step.operator)
+
+          issues.concat(check_step(step, pos, prev, last_qualified, by_name))
+          prev = step if step.name
+          last_qualified = step if step.name && step.attribute
+        end
+        issues
+      end
+
+      EXPRESS_BUILTINS = %w[NUMBER INTEGER REAL STRING BOOLEAN LOGICAL
+                            BINARY].freeze
+      private_constant :EXPRESS_BUILTINS
+
+      def name_index(repository)
+        index = EXPRESS_BUILTINS.to_h { |b| [b.downcase, [nil, nil]] }
+        repository.schemas.flat_map do |schema|
+          DECLARATION_COLLECTIONS.flat_map do |coll|
+            Array(schema.public_send(coll))
+              .select { |d| d.respond_to?(:id) && d.id }
+              .map { |d| [d.id.safe_downcase, [schema, d]] }
+          end
+        end.each { |pair| index[pair[0]] = pair[1] }
+        index
+      end
+
+      def check_step(step, pos, prev, last_qualified, by_name)
+        found = by_name[step.name&.safe_downcase]
+        return [Issue.new(step: pos, message: "unknown type '#{step.name}'")] unless found
+
+        issues = attribute_issues(step, pos, found[1], by_name)
+        issues.concat(link_issues(step, pos, prev, last_qualified, by_name))
+        issues
+      end
+
+      def attribute_issues(step, pos, decl, by_name)
+        return [] unless step.attribute
+
+        unless decl.is_a?(Model::Declarations::Entity)
+          return [Issue.new(step: pos,
+                            message: "'#{step.name}' is not an entity, " \
+                                     "cannot carry '#{step.name}.#{step.attribute}'")]
+        end
+
+        attribute = find_attribute(decl, step.attribute, by_name)
+        unless attribute
+          return [Issue.new(step: pos,
+                            message: "entity '#{step.name}' has no attribute " \
+                                     "'#{step.attribute}'")]
+        end
+
+        aggregate_issue(step, pos, attribute)
+      end
+
+      # Direct or inherited attribute: inheritance follows the
+      # subtype_of chain, resolved through the repository-wide index.
+      def find_attribute(entity, attribute_id, by_name)
+        key = attribute_id.safe_downcase
+        supertype_chain(entity, by_name).lazy.flat_map do |candidate|
+          Array(candidate.attributes)
+        end.find { |a| a.id&.safe_downcase == key }
+      end
+
+      def supertype_chain(entity, by_name)
+        seen = {}.compare_by_identity
+        queue = [entity]
+        result = []
+        until queue.empty?
+          current = queue.shift
+          next if seen[current]
+
+          seen[current] = true
+          result << current
+          current.subtype_of.to_a.each do |ref|
+            sup = by_name[ref.respond_to?(:id) ? ref.id&.safe_downcase : nil]&.last
+            queue << sup if sup.is_a?(Model::Declarations::Entity)
+          end
+        end
+        result
+      end
+
+      def aggregate_issue(step, pos, attribute)
+        return [] unless step.index
+        return [] if attribute.type.respond_to?(:bound1)
+
+        [Issue.new(step: pos,
+                   message: "'#{step.name}.#{step.attribute}' is not an " \
+                            "aggregate but carries [#{step.index}]")]
+      end
+
+      def link_issues(step, pos, prev, last_qualified, by_name)
+        return [] unless LINKS.include?(step.operator)
+        unless prev && step.name
+          return [Issue.new(step: pos,
+                            message: "#{step.operator} with no preceding node")]
+        end
+
+        case step.operator
+        when "->", "<-"
+          attribute_link_issues(step, pos, prev, last_qualified)
+        when "<=" then subtype_link_issues(step, pos, prev, by_name)
+        when "=>" then supertype_link_issues(step, pos, prev, by_name)
+        end
+      end
+
+      # `->`: the attribute-qualified node precedes the operator;
+      # `<-`: it follows (the entity before <- is referenced BY the
+      # attribute after it). An aggregate dereference `[i]` keeps the
+      # running attribute owner qualified for the next link
+      # (`attr -> list_type[i] -> element_type`).
+      def attribute_link_issues(step, pos, prev, last_qualified)
+        if step.operator == "->"
+          qualified = if prev&.attribute
+                        prev
+                      else
+                        (prev&.index ? last_qualified : nil)
+                      end
+          unless qualified&.attribute
+            return [Issue.new(step: pos,
+                              message: "'->' requires an attribute-qualified " \
+                                       "node before it, got '#{prev&.name}'")]
+          end
+
+          return []
+        end
+
+        return [] if step.attribute
+
+        [Issue.new(step: pos,
+                   message: "'<-' requires an attribute-qualified node " \
+                            "after it, got '#{step.name}'")]
+      end
+
+      # `a <= b`: a is a subtype of b.
+      def subtype_link_issues(step, pos, prev, by_name)
+        source = by_name[prev.name&.safe_downcase]&.last
+        target = by_name[step.name&.safe_downcase]&.last
+        return [] unless source.is_a?(Model::Declarations::Entity) &&
+          target.is_a?(Model::Declarations::Entity)
+
+        return [] if supertype_ids(source, by_name)
+          .any? { |id| id&.safe_downcase == step.name&.safe_downcase }
+
+        [Issue.new(step: pos,
+                   message: "'#{prev.name}' is not a subtype of '#{step.name}'")]
+      end
+
+      # `a => b`: a is a supertype of b.
+      def supertype_link_issues(step, pos, prev, by_name)
+        source = by_name[step.name&.safe_downcase]&.last
+        target = by_name[prev.name&.safe_downcase]&.last
+        return [] unless source.is_a?(Model::Declarations::Entity) &&
+          target.is_a?(Model::Declarations::Entity)
+
+        return [] if supertype_ids(source, by_name)
+          .any? { |id| id&.safe_downcase == prev.name&.safe_downcase }
+
+        [Issue.new(step: pos,
+                   message: "'#{prev.name}' is not a supertype of '#{step.name}'")]
+      end
+
+      # Supertype entity names of +entity+: the subtype_of references
+      # plus the leaves of the supertype expression tree, resolved
+      # through the repository-wide name index so inherited chains
+      # (including cross-schema USE FROM) walk correctly.
+      def supertype_ids(entity, by_name)
+        seen = {}.compare_by_identity
+        queue = [entity]
+        names = []
+        until queue.empty?
+          current = queue.shift
+          next if seen[current]
+
+          seen[current] = true
+          direct = current.subtype_of.to_a.filter_map do |ref|
+            ref.respond_to?(:id) ? ref.id : nil
+          end
+          leaves = expression_leaves(current.supertype_expression)
+            .filter_map { |leaf| leaf.respond_to?(:id) ? leaf.id : nil }
+          names.concat(direct)
+          names.concat(leaves)
+          direct.concat(leaves).each do |id|
+            sup = by_name[id&.safe_downcase]&.last
+            queue << sup if sup.is_a?(Model::Declarations::Entity)
+          end
+        end
+        names.uniq
+      end
+
+      # Leaf reference nodes of a supertype expression tree.
+      def expression_leaves(expr)
+        return [] unless expr
+
+        if expr.respond_to?(:operands)
+          Array(expr.operands).flat_map { |o| expression_leaves(o) }
+        elsif expr.respond_to?(:operand1)
+          expression_leaves(expr.operand1) + expression_leaves(expr.operand2)
+        elsif expr.respond_to?(:id) && expr.id
+          [expr]
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/expressir/mapping.rb

@@ -13,6 +13,8 @@ module Expressir
   # are ignored by the mapping and survive round-trips untouched in
   # the source files.
   module Mapping
+    autoload :RefPath, "#{__dir__}/mapping/refpath"
+
     EXPRESS_LINK = /<<express:([^,>]+)(?:,([^>]+))?>>/
 
     class ReferencePath < Lutaml::Model::Serializable
@@ -137,5 +139,23 @@ module Expressir
           element.aa.to_a.flat_map { |aa| [aa.attribute, aa.aimelt] }
       end.compact
     end
+
+    # Every reference path in the document as [location, content]
+    # pairs; location names the application element (and attribute,
+    # for attribute-level paths) the path belongs to.
+    def refpaths(document)
+      document.ae.to_a.flat_map do |element|
+        entries = []
+        if element.refpath&.content
+          entries << [element.entity.to_s, element.refpath.content]
+        end
+        element.aa.to_a.each do |aa|
+          next unless aa.refpath&.content
+
+          entries << ["#{element.entity}.#{aa.attribute}", aa.refpath.content]
+        end
+        entries
+      end
+    end
   end
 end

data/lib/expressir/version.rb

@@ -3,6 +3,6 @@ module Expressir
   # autoload it (Ruby autoload only works for module/class constants, not
   # for string constants like `Expressir::VERSION`).
   module Version
-    VERSION = "2.4.17".freeze
+    VERSION = "2.4.19".freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: expressir
 version: !ruby/object:Gem::Version
-  version: 2.4.17
+  version: 2.4.19
 platform: ruby
 authors:
 - Ribose Inc.
@@ -537,6 +537,7 @@ files:
 - lib/expressir/manifest/resolver.rb
 - lib/expressir/manifest/validator.rb
 - lib/expressir/mapping.rb
+- lib/expressir/mapping/refpath.rb
 - lib/expressir/model.rb
 - lib/expressir/model/cache.rb
 - lib/expressir/model/concerns.rb