expressir 2.4.16 → 2.4.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca7a970fe2d30edcb570639ddd4c178b2edf7bdee839844df7946fdb1e842d1b
-  data.tar.gz: a5a5b1c703de8027892d77792fbc957155101b8875fe1aa080feefec9d278ac7
+  metadata.gz: 71c43838ba6c2853f84bfa1faca26760abe4919d35b98895ef224866bd49da62
+  data.tar.gz: 715a55be95f4ead656b98e0df59ccf06c2036eb532d6990a8ea036ee5f0f78c4
 SHA512:
-  metadata.gz: '0950891e9ddb51792aaf69c1c82af9224ae6126b5ff77dd481e48105b2e39215dd23a1d1c3e30d060be4ef2988132b4aec47cf306903dc9081a05e73c5e6f42d'
-  data.tar.gz: 976131ab90fedb6e659129ca1f0aa6a3e8a8d5df40cb00950dc8b6b237789dcc4d896df03c35532e3afac6483e2f3674983bb0bc092adbf0534ed355d155a507
+  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/express/lazy_repository.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "liquid"
+
+module Expressir
+  module Express
+    # Lazy read path over a compiled-set artifact (M2 slice 2,
+    # TODO.parity-ee/19): schemas hydrate individually, on first touch,
+    # instead of the whole repository at once. Metanorma schema-doc
+    # rendering touches one schema per page — the lazy repository makes
+    # that pay: one hydration per page, not one per schema in the set.
+    #
+    # Duck-types the read surface of Model::Repository used by
+    # rendering (schemas, files, each, size, children). Anything beyond
+    # the read surface should wait for eager hydration via
+    # #to_eager (returns a real Model::Repository).
+    class LazyRepository
+      attr_reader :set_path
+
+      # @param set_path [String] compiled-set artifact path
+      # @param read_paths [Hash{String => String}] wire path => source path
+      def initialize(set_path, read_paths = {})
+        @set_path = set_path
+        @set = Core.lazy_set(set_path)
+        @read_paths = read_paths
+        @wire_paths = @set.wire_paths
+        @mutex = Mutex.new
+        @file_cache = {}
+        @hydration_count = 0
+      end
+
+      # Wire paths in artifact order — no hydration.
+      # @return [Array<String>]
+      def wire_paths
+        @wire_paths.dup
+      end
+
+      # Files in artifact order, each wrapped so it hydrates on first
+      # use. The file is the hydration grain: an artifact stores wire
+      # JSON per source file.
+      # @return [Array<LazyFile>]
+      def files
+        @wire_paths.map { |wire_path| file_by_wire_path(wire_path) }
+      end
+
+      # Hydrated (or hydrating) file for one wire path.
+      def file_by_wire_path(wire_path)
+        @mutex.synchronize do
+          @file_cache[wire_path] ||= LazyFile.new(wire_path) do
+            hydrate(wire_path)
+          end
+        end
+      end
+
+      # Schemas across all files. EAGER by definition: it hydrates
+      # every file. Lazy callers iterate #files, or render through
+      # #to_liquid, which keeps per-file hydration lazy.
+      # @return [Array<Declarations::Schema>]
+      def schemas
+        files.map(&:__target__).flat_map(&:schemas).compact
+      end
+
+      # Liquid binding for metanorma (M2): returns a Drop whose
+      # `schemas` is a lazy per-file list — each entry hydrates only
+      # its own file when the template touches it. Schema count per
+      # file is unknown until hydration, so the Drop presents one
+      # entry per FILE; single-schema files (the corpus norm) render
+      # identically to the eager path.
+      def to_liquid
+        LazyRepositoryDrop.new(self)
+      end
+
+      # How many files have actually been hydrated (observability for
+      # the laziness contract).
+      def hydration_count
+        @hydration_count
+      end
+
+      # Hydrate everything and return a real Model::Repository — the
+      # escape hatch for callers needing the full read surface.
+      def to_eager
+        repo = Model::Repository.new
+        repo.files = files.map(&:__target__)
+        repo
+      end
+
+      def each(&)
+        files.each(&)
+      end
+
+      def size
+        @wire_paths.size
+      end
+
+      def children
+        schemas
+      end
+
+      # The read path on disk for a wire path (may be nil when the
+      # caller did not supply source paths).
+      def read_path_for(wire_path)
+        @read_paths[wire_path]
+      end
+
+      def matches_sources?
+        @set.matches_sources(@read_paths.dup) == true
+      end
+
+      private
+
+      def hydrate(wire_path)
+        @mutex.synchronize do
+          _wire, model = @set.hydrate_one(wire_path)
+          @hydration_count += 1
+          model
+        end
+      end
+    end
+
+    # Liquid::Drop over a LazyRepository: `schemas` enumerates lazy
+    # per-file entries; touching an entry hydrates that file and
+    # presents its schemas (single-schema files present the schema
+    # itself, matching the eager Drop's element contract).
+    class LazyRepositoryDrop < ::Liquid::Drop
+      def initialize(repo)
+        @repo = repo
+        super()
+      end
+
+      def schemas
+        @repo.files.map do |file|
+          LazyFileDrop.new(file)
+        end
+      end
+
+      def size
+        @repo.size
+      end
+    end
+
+    # Per-file lazy drop: hydrates on first access, then presents the
+    # file's single schema directly (or the schema list for
+    # multi-schema files).
+    class LazyFileDrop < ::Liquid::Drop
+      def initialize(file)
+        @file = file
+        super()
+      end
+
+      def __file__
+        @file.__target__
+      end
+
+      def method_missing(name, *, &)
+        schemas = __file__.schemas
+        if schemas.size == 1
+          schemas.first.public_send(name, *, &)
+        else
+          __file__.public_send(name, *, &)
+        end
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        __file__.respond_to?(name, include_private) ||
+          __file__.schemas.first.respond_to?(name, include_private)
+      end
+    end
+
+    # Stands in for a Model::ExpFile until first method access, then
+    # hydrates through the block and forwards everything.
+    class LazyFile
+      def initialize(wire_path, &hydrator)
+        @wire_path = wire_path
+        @hydrator = hydrator
+        @mutex = Mutex.new
+        @target = nil
+      end
+
+      attr_reader :wire_path
+
+      # The real Schema, hydrating on first call.
+      def __target__
+        @mutex.synchronize do
+          @__target__ ||= @hydrator.call
+        end
+      end
+
+      def method_missing(name, *, &)
+        __target__.public_send(name, *, &)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        __target__.respond_to?(name, include_private)
+      end
+
+      # Identity through the wrapper: rendering compares and groups by
+      # class/is_a?, which the real file answers.
+      def is_a?(klass)
+        super || __target__.is_a?(klass)
+      end
+
+      def instance_of?(klass)
+        __target__.instance_of?(klass)
+      end
+
+      def class
+        __target__.class
+      end
+    end
+  end
+end

data/lib/expressir/express.rb

@@ -44,6 +44,7 @@ module Expressir
              "#{__dir__}/express/schema_plain_source_formatter"
     autoload :SchemaSourceFormatter, "#{__dir__}/express/schema_source_formatter"
     autoload :ScopeResolver, "#{__dir__}/express/scope_resolver"
+    autoload :LazyRepository, "#{__dir__}/express/lazy_repository"
     autoload :SmrlXml, "#{__dir__}/express/smrl_xml"
     autoload :Xsd, "#{__dir__}/express/xsd"
     autoload :SourceFormatter, "#{__dir__}/express/source_formatter"

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.16".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.16
+  version: 2.4.18
 platform: ruby
 authors:
 - Ribose Inc.
@@ -506,6 +506,7 @@ files:
 - lib/expressir/express/grammar/parser.rb
 - lib/expressir/express/hyperlink_formatter.rb
 - lib/expressir/express/interface_dot.rb
+- lib/expressir/express/lazy_repository.rb
 - lib/expressir/express/line_map.rb
 - lib/expressir/express/listing.rb
 - lib/expressir/express/model_traversal.rb
@@ -536,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