expressir 2.4.17 → 2.4.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fb8953f2f2e9d76be3693148c8951ae36f562bbaf8214a8bc510b68888700d2
-  data.tar.gz: dfbcc336cc1a580501ca69632d6e6bb348e196be470cbc712a637131ffe1993c
+  metadata.gz: 71c43838ba6c2853f84bfa1faca26760abe4919d35b98895ef224866bd49da62
+  data.tar.gz: 715a55be95f4ead656b98e0df59ccf06c2036eb532d6990a8ea036ee5f0f78c4
 SHA512:
-  metadata.gz: 2e5259fb143ac5419ab85b8a97e8ab50a3a809826f799b8cd74242a673599c5cac0bd21cfe1dc33af562c16a806afc95f9f43f75f8eba43e18b68377104d5406
-  data.tar.gz: 0d2520a7a817f1c8d72a6f768887e803c91a6070f3cf8d4230bde9e66dcb6a1580ff7ee39ac6e9c886106cde64db14e175db57e81be0b798ea8f45af57bfaaa7
+  metadata.gz: dac93ad5688fc8e2d3814fd6933b352ea35d78b89f157e99f30114ddafb07b53aaeb80aaa45fd63540a9ee400ac1aacc3724800446f868472499d9d4cf501629
+  data.tar.gz: 12cd7ef87afa0510215d0c1315e68ba5bbaed5a910255ebfa40e18b328b25f87ef3a24f93ce1073a798ce0e748e6344861f05900f863377ed801d9f1f66e7bab

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,338 @@
+# 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 = ["{", "}", "[", "]", "(", ")", ":", "|", "!", ",", "/",
+                 "*"].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(".")
+            if name.casecmp("MAPPING_OF").zero? && tokens[i + 1] == "("
+              # notation wrapper: /MAPPING_OF(X)/ refers to X; the
+              # wrapper itself carries no node semantics
+              steps << Step.new(operator: token)
+            else
+              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
+          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
+        path.steps.each_with_index do |step, pos|
+          if MARKERS.include?(step.operator)
+            prev = nil
+            next
+          end
+
+          issues.concat(check_step(step, pos, prev, by_name))
+          prev = step if step.name
+        end
+        issues
+      end
+
+      def name_index(repository)
+        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.to_h
+      end
+
+      def check_step(step, pos, prev, 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, 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, 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 "->", "<-" then attribute_link_issues(step, pos, prev)
+        when "<=" then subtype_link_issues(step, pos, prev, by_name)
+        when "=>" then supertype_link_issues(step, pos, prev, by_name)
+        end
+      end
+
+      def attribute_link_issues(_step, pos, prev)
+        unless prev.attribute
+          return [Issue.new(step: pos,
+                            message: "'->' requires an attribute-qualified " \
+                                     "node before it, got '#{prev.name}'")]
+        end
+
+        []
+      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.18".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.18
 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