expressir 2.4.36 → 2.4.38

data/lib/expressir/eval/population.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Eval
+    # Population-scale rule engine (TODO.instance/02). Each rule
+    # resolves once per schema edition and applies to many instances.
+    # Entity WHERE rules scope over the entity and its subtypes
+    # (ISO 10303-11 9.2.1, applicability via P21::Typing); UNIQUE
+    # rules (9.2.2.1) compare value tuples across the whole
+    # population; global rules (9.4) evaluate once per rule with the
+    # FOR entities bound to their instance aggregates. Per 9.4 a rule
+    # is violated only when it evaluates to false.
+    class Population
+      Finding = Struct.new(:kind, :instance, :rule_id, :message,
+                           keyword_init: true)
+
+      attr_reader :schema, :population, :typing
+
+      def self.check(schema, population, short_names: nil)
+        new(schema, population, short_names: short_names).check
+      end
+
+      def initialize(schema, population, short_names: nil)
+        @schema = schema
+        @population = population
+        @typing = P21::Typing.new(schema, short_names: short_names)
+        @by_entity = nil
+        @slots = {}
+      end
+
+      def check
+        where_findings + unique_findings + global_findings
+      end
+
+      # Instances conforming to the named entity, including subtypes.
+      def instances_for(entity)
+        by_entity[entity.id&.safe_downcase] || []
+      end
+
+      private
+
+      def by_entity
+        @by_entity ||= begin
+          index = Hash.new { |hash, key| hash[key] = [] }
+          @population.instances.each do |id, record|
+            @typing.of(record).each do |entity|
+              index[entity.id&.safe_downcase] << [id, record]
+            end
+          end
+          index
+        end
+      end
+
+      def where_findings
+        @schema.entities.flat_map do |entity|
+          rules = Array(entity.where_rules)
+          next [] if rules.empty?
+
+          instances_for(entity).flat_map do |(id, record)|
+            rules.filter_map do |rule|
+              where_finding(id, record, entity, rule)
+            end
+          end
+        end
+      end
+
+      def where_finding(id, record, entity, rule)
+        env = Rules.environment_for(@population, @schema, id, record, entity)
+        value = Expression.evaluate(rule.expression, env)
+        return unless false?(value)
+
+        Finding.new(kind: :where, instance: id, rule_id: rule.id,
+                    message: "#{id}: #{entity.id}.#{rule.id} (9.4)")
+      rescue Expressir::Eval::Error => e
+        Finding.new(kind: :where, instance: id, rule_id: rule.id,
+                    message: "#{id}: #{entity.id}.#{rule.id}: #{e.message}")
+      end
+
+      def unique_findings
+        @schema.entities.flat_map do |entity|
+          Array(entity.unique_rules).flat_map do |rule|
+            unique_rule_findings(entity, rule)
+          end
+        end
+      end
+
+      # 9.2.2.1: the value tuple of the referenced attributes must be
+      # unique across all instances of the entity and its subtypes.
+      def unique_rule_findings(entity, rule)
+        seen = {}
+        instances_for(entity).filter_map do |(id, record)|
+          env = Rules.environment_for(@population, @schema, id, record,
+                                      entity)
+          instance = Values::Instance.new(id: id.delete_prefix("#"),
+                                          record: record)
+          key = unique_key(rule, entity, env, instance)
+          if key.nil?
+            next error_finding(:unique, id, rule.id,
+                               "#{id}: UNIQUE '#{rule.id}' references an " \
+                               "attribute outside '#{entity.id}' (9.2.2.1)")
+          end
+
+          first = seen[key]
+          seen[key] = id
+          next unless first
+
+          Finding.new(kind: :unique, instance: id, rule_id: rule.id,
+                      message: "#{id}: UNIQUE '#{rule.id}' duplicates " \
+                               "#{first} (9.2.2.1)")
+        end
+      end
+
+      def unique_key(rule, entity, env, instance)
+        Array(rule.attributes).map do |reference|
+          name = reference.respond_to?(:id) ? reference.id : reference.to_s
+          return nil unless slots_for(entity).key?(name.safe_downcase)
+
+          Expression.instance_attribute(instance, name, env).inspect
+        end
+      end
+
+      def slots_for(entity)
+        @slots[entity] ||= Environment.new(schema: @schema).slots_for(entity)
+      end
+
+      # 9.4 global rules: the FOR entities are bound, in the rule's
+      # scope, to the aggregates of all their instances.
+      def global_findings
+        Array(@schema.rules).flat_map do |rule|
+          env = global_environment(rule)
+          if env.nil?
+            next [error_finding(:global, nil, rule.id,
+                                "global rule '#{rule.id}' names no entity " \
+                                "(9.4)")]
+          end
+
+          Array(rule.where_rules).filter_map do |where|
+            value = Expression.evaluate(where.expression, env)
+            next unless false?(value)
+
+            Finding.new(kind: :global, instance: nil, rule_id: rule.id,
+                        message: "global rule '#{rule.id}' (9.4)")
+          rescue Expressir::Eval::Error => e
+            error_finding(:global, nil, rule.id,
+                          "global rule '#{rule.id}': #{e.message}")
+          end
+        end
+      end
+
+      def global_environment(rule)
+        env = Environment.new(schema: @schema, population: @population)
+        bound = 0
+        Array(rule.applies_to).each do |reference|
+          name = reference.respond_to?(:id) ? reference.id : nil
+          entity = name && @schema.entities.find do |candidate|
+            candidate.id&.safe_downcase == name.safe_downcase
+          end
+          return nil unless entity
+
+          env = env.define(
+            name.safe_downcase,
+            Values::Aggregate.of(
+              :list, instances_for(entity).map do |(id, record)|
+                Values::Instance.new(id: id.delete_prefix("#"), record: record)
+              end
+            ),
+          )
+          bound += 1
+        end
+        bound.positive? ? env : nil
+      end
+
+      def error_finding(kind, instance, rule_id, message)
+        Finding.new(kind: kind, instance: instance, rule_id: rule_id,
+                    message: message)
+      end
+
+      def false?(value)
+        return true if value == Values::LOGICAL_FALSE
+        return value.value == Values::LOGICAL_FALSE if value.is_a?(Values::Logical)
+
+        false
+      end
+    end
+  end
+end

data/lib/expressir/eval/rules.rb

@@ -18,7 +18,6 @@ module Expressir
 
       def check(population, schema)
         population.instances.flat_map do |id, record|
-          entity_for(schema, record)
           entity = entity_for(schema, record)
           next [] unless entity
 

data/lib/expressir/eval.rb

@@ -13,5 +13,6 @@ module Expressir
     autoload :Expression, "#{__dir__}/eval/expression"
     autoload :Interpreter, "#{__dir__}/eval/interpreter"
     autoload :Rules, "#{__dir__}/eval/rules"
+    autoload :Population, "#{__dir__}/eval/population"
   end
 end

data/lib/expressir/mapping/instance_verification.rb

@@ -0,0 +1,405 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Mapping
+    # ARM↔MIM instance mapping verification (TODO.instance/04): given
+    # a module's mapping tables (Mapping::Document) and two
+    # populations — an ARM-typed one and a MIM one — verify the MIM
+    # population is the image of the ARM population. Each application
+    # element is an instance predicate: every ARM instance of the
+    # element's entity must have a MIM image whose typing includes the
+    # mapped MIM entity, whose element refpath (or an alt_map route)
+    # resolves from that image, whose attribute-mapping refpaths
+    # terminate at values equal to the ARM attribute values, and whose
+    # inline element rules evaluate true (Eval WHERE semantics, self
+    # bound to the image).
+    #
+    # Reference values correspond across the two populations through
+    # the mapping itself: an ARM `#n` terminal matches the MIM image
+    # of ARM instance n under the element that maps its keyword.
+    #
+    # Instance-level path walking covers the mapping-corpus RefPath
+    # constructs: bare and attribute-qualified nodes, `->`/`<-`
+    # navigation, `<=`/`=>` restatements, the §5 `||supertype||` and
+    # `*tree*` markers, and `{entity.attr = literal}` constraints
+    # (with `!` negation). Rules fields that name global rules rather
+    # than inline expressions are the domain of Mapping.rule_issues;
+    # they are not re-checked per instance here. Complex (multi-role)
+    # records are outside v1 scope: a complex candidate fails its
+    # route rather than silently passing.
+    class InstanceVerification
+      Finding = Struct.new(:arm_instance, :entity, :message, keyword_init: true)
+
+      # Part 21 value normalization for equality: enumerations compare
+      # by name, typed parameters by keyword+value.
+      module ValueCompare
+        module_function
+
+        def comparable(value)
+          case value
+          when P21::Enumeration then value.name
+          when P21::TypedValue then [value.keyword, comparable(value.value)]
+          when Array then value.map { |item| comparable(item) }
+          else value
+          end
+        end
+      end
+
+      include ValueCompare
+
+      attr_reader :findings
+
+      def initialize(mapping:, arm_schema:, mim_schema:,
+                     arm_population:, mim_population:)
+        @mapping = mapping
+        @arm_schema = arm_schema
+        @mim_schema = mim_schema
+        @arm_population = arm_population
+        @mim_population = mim_population
+        @arm_typing = P21::Typing.new(arm_schema)
+        @mim_typing = P21::Typing.new(mim_schema)
+        @arm_slots = Eval::Environment.new(schema: arm_schema)
+        @mim_slots = Eval::Environment.new(schema: mim_schema)
+        @findings = []
+        @image_cache = {}
+        @rule_cache = {}
+      end
+
+      def verify
+        @mapping.ae.to_a.each { |element| verify_element(element) }
+        @findings
+      end
+
+      private
+
+      def verify_element(element)
+        arm_entity = find_entity(@arm_schema, element.entity)
+        unless arm_entity
+          @findings << Finding.new(arm_instance: nil, entity: element.entity,
+                                   message: "ARM schema declares no entity " \
+                                            "'#{element.entity}'")
+          return
+        end
+
+        arm_instances(arm_entity).each do |(id, record)|
+          next if image_of(element, record, id, {}.compare_by_identity)
+
+          @findings << Finding.new(
+            arm_instance: id, entity: element.entity,
+            message: "no MIM image of #{element.entity} instance #{id} " \
+                     "through the mapping"
+          )
+        end
+      end
+
+      def arm_instances(entity)
+        @arm_population.instances.filter_map do |id, record|
+          next unless typed?(@arm_typing, record, entity)
+
+          [id, record]
+        end
+      end
+
+      # The MIM image id of one ARM instance, or nil. Tries the
+      # element's primary route then each alt_map route; memoized so
+      # cross-population reference correspondence stays linear.
+      def image_of(element, arm_record, arm_id, seen)
+        key = [element.object_id, arm_id]
+        return @image_cache[key] if @image_cache.key?(key)
+        return nil if seen[arm_id]
+
+        seen[arm_id] = true
+        @image_cache[key] = routes(element).filter_map do |route|
+          mim_entity = find_entity(@mim_schema, route[:entity])
+          next unless mim_entity
+
+          mim_candidates(mim_entity).find do |(mim_id, mim_record)|
+            route_matches?(route, element, arm_record,
+                           arm_entity_of(element), mim_id, mim_record,
+                           mim_entity, seen)
+          end&.first
+        end.first
+      end
+
+      def routes(element)
+        [{ entity: Mapping.entity_item(element.aimelt),
+           path: element.refpath&.content }].concat(
+             element.alt_map.to_a.map do |alt|
+               { entity: Mapping.entity_item(alt.aimelt),
+                 path: alt.refpath&.content }
+             end,
+           ).reject { |route| route[:entity].nil? || route[:entity].empty? }
+      end
+
+      def route_matches?(route, element, arm_record, arm_entity,
+                         mim_id, mim_record, mim_entity, seen)
+        walk = Walker.new(@mim_population, @mim_typing, @mim_slots, @mim_schema)
+        walk.follow(route[:path], mim_id, mim_record, mim_entity) if route[:path]
+        element.aa.to_a.all? do |aa|
+          attribute_matches?(aa, arm_record, arm_entity,
+                             mim_id, mim_record, mim_entity, seen)
+        end && rules_hold?(element, mim_entity, mim_id, mim_record)
+      rescue Walker::BrokenPath
+        false
+      end
+
+      def attribute_matches?(attr_mapping, arm_record, arm_entity,
+                             mim_id, mim_record, mim_entity, seen)
+        arm_value = arm_attribute_value(arm_record, arm_entity, attr_mapping)
+        walk = Walker.new(@mim_population, @mim_typing, @mim_slots, @mim_schema)
+        walk.follow(attr_mapping.refpath&.content, mim_id, mim_record, mim_entity)
+        values_match?(walk.terminal, arm_value, seen)
+      rescue Walker::BrokenPath
+        false
+      end
+
+      def values_match?(mim_value, arm_value, seen)
+        comparable(mim_value) == comparable(arm_value) ||
+          reference_corresponds?(mim_value, arm_value, seen)
+      end
+
+      # Reference values correspond through the mapping: the ARM `#n`
+      # must map to exactly the MIM instance the path reached.
+      def reference_corresponds?(mim_value, arm_value, seen)
+        return false unless reference?(mim_value) && reference?(arm_value)
+
+        arm_record = @arm_population.instances[arm_value]
+        return false unless arm_record
+
+        element = @mapping.ae.to_a.find do |ae|
+          ae.entity&.safe_downcase == arm_record.keyword&.safe_downcase
+        end
+        return false unless element
+
+        image_of(element, arm_record, arm_value, seen) == mim_value
+      end
+
+      def reference?(value)
+        value.is_a?(String) && value.start_with?("#")
+      end
+
+      def arm_attribute_value(arm_record, arm_entity, attr_mapping)
+        name = attr_mapping.attribute.to_s.split(".").last
+        index = @arm_slots.slots_for(arm_entity)[name&.safe_downcase]
+        raise Walker::BrokenPath, "ARM entity has no attribute '#{name}'" unless index
+
+        arm_record.params[index]
+      end
+
+      # Inline expression rules are instance predicates; a rules field
+      # that is not an expression (a named global rule) is left to
+      # Mapping.rule_issues.
+      def rules_hold?(element, mim_entity, mim_id, mim_record)
+        content = element.rules&.content
+        return true unless content
+
+        expression = @rule_cache[content] ||= parse_rule_expression(content)
+        return true unless expression
+
+        env = Eval::Rules.environment_for(@mim_population, @mim_schema,
+                                          mim_id, mim_record, mim_entity)
+        !logical_false?(Eval::Expression.evaluate(expression, env))
+      rescue Eval::Error, Walker::BrokenPath
+        false
+      end
+
+      def parse_rule_expression(content)
+        parsed = Expressir::Express::Parser.from_exp(
+          "SCHEMA mapping_rule_wrap; ENTITY wrap; " \
+          "WHERE rule_expr : #{content}; END_ENTITY; END_SCHEMA;",
+        )
+        parsed.schemas.first.entities.first.where_rules.first.expression
+      rescue StandardError
+        nil
+      end
+
+      def logical_false?(result)
+        return [false, Eval::Values::LOGICAL_FALSE].include?(result) unless
+          result.is_a?(Eval::Values::Logical)
+
+        result.value == Eval::Values::LOGICAL_FALSE
+      end
+
+      def mim_candidates(entity)
+        @mim_population.instances.filter_map do |id, record|
+          next unless typed?(@mim_typing, record, entity)
+
+          [id, record]
+        end
+      end
+
+      def typed?(typing, record, entity)
+        typing.issues(record).empty? &&
+          typing.of(record)
+            .any? { |decl| decl.id&.safe_downcase == entity.id&.safe_downcase }
+      end
+
+      def arm_entity_of(element)
+        find_entity(@arm_schema, element.entity)
+      end
+
+      def find_entity(schema, name)
+        key = Mapping.entity_item(name).to_s.safe_downcase
+        Array(schema.entities).find { |entity| entity.id&.safe_downcase == key }
+      end
+
+      # Walks a reference path through actual population instances,
+      # starting at a candidate MIM image. Raises BrokenPath the
+      # moment the population contradicts the path.
+      class Walker
+        class BrokenPath < StandardError
+        end
+
+        include ValueCompare
+
+        attr_reader :terminal
+
+        def initialize(population, typing, slots, schema)
+          @population = population
+          @typing = typing
+          @slots = slots
+          @schema = schema
+        end
+
+        def follow(content, id, record, entity)
+          @id = id
+          @record = record
+          @entity = entity
+          @last_attr = nil
+          @terminal = nil
+          RefPath.parse(content).steps.each { |step| follow_step(step) } if content
+          self
+        end
+
+        private
+
+        def follow_step(step)
+          return if marker_step?(step)
+          return constraint(step) if step.operator == "{"
+          return move_to(step.name) if step.name && %w[<= => || = *].include?(step.operator)
+          return navigate(step) if step.operator == "->"
+          return inverse(step) if step.operator == "<-"
+          return step_over(step) if step.name
+
+          raise BrokenPath, "unsupported path step '#{step.operator}'"
+        end
+
+        def marker_step?(step)
+          step.name.nil? && step.attribute.nil? && step.link.nil? &&
+            step.operator != "{" && step.operator != "(" && step.operator != ")"
+        end
+
+        # {entity.attr = literal} against the instance the walk sits
+        # on; `!{` negates.
+        def constraint(step)
+          unless step.name.nil? ||
+              step.name&.safe_downcase == @entity&.id&.safe_downcase
+            raise BrokenPath,
+                  "constraint on '#{step.name}' does not name the " \
+                  "walk's entity"
+          end
+          return unless step.attribute
+
+          actual = read(step.attribute)
+          expected = step.literal.to_s
+          expected = expected[1..-2] if expected.start_with?("'")
+          holds = comparable(actual).to_s.casecmp?(expected)
+          holds = !holds if step.negated
+          return if holds
+
+          raise BrokenPath,
+                "constraint '#{step.name}.#{step.attribute} = " \
+                "#{step.literal}' does not hold"
+        end
+
+        # The instance must conform to the named declaration; the walk
+        # context moves there so later slots resolve against it.
+        def move_to(name)
+          target = find_entity(name)
+          raise BrokenPath, "no declaration '#{name}'" unless target
+
+          conforms = @typing.of(@record)
+            .any? { |decl| decl.id&.safe_downcase == target.id&.safe_downcase }
+          raise BrokenPath, "instance does not conform to '#{name}'" unless conforms
+
+          @entity = target
+        end
+
+        # A bare or attribute-qualified node: restatement plus, when
+        # qualified, the attribute read — the terminal value, and the
+        # attribute a following `->` navigates through.
+        def step_over(step)
+          move_to(step.name)
+          @last_attr = step.attribute
+          @terminal = read(step.attribute) if step.attribute
+        end
+
+        # `attr -> entity`: the recorded attribute must hold a
+        # reference to an instance of the named entity.
+        def navigate(step)
+          attribute = step.attribute || @last_attr
+          raise BrokenPath, "'->' without an attribute" unless attribute
+
+          value = read(attribute)
+          target = @population.instances[value.to_s]
+          raise BrokenPath, "'#{attribute}' does not hold a reference" unless target
+
+          @record = target
+          @id = value.to_s
+          move_to(step.name)
+          @last_attr = nil
+        end
+
+        # `<- entity.attr`: some instance of the named entity must
+        # reference the current one through the attribute; the walk
+        # moves there.
+        def inverse(step)
+          raise BrokenPath, "'<-' without an attribute" unless step.attribute
+
+          found = @population.instances.find do |_, candidate|
+            keyword = candidate.keyword&.safe_downcase
+            next false unless keyword == step.name&.safe_downcase
+
+            read_attribute(candidate, step.attribute) == @id
+          end
+          unless found
+            raise BrokenPath,
+                  "no '#{step.name}' instance references '#{@id}' " \
+                  "through '#{step.attribute}'"
+          end
+
+          @record = found[1]
+          @id = found[0]
+          move_to(step.name)
+          @last_attr = step.attribute
+        end
+
+        def read(attribute)
+          read_attribute(@record, attribute, entity: @entity)
+        end
+
+        def read_attribute(record, attribute, entity: nil)
+          target = entity || entity_for_record(record)
+          index = @slots.slots_for(target)[attribute&.safe_downcase]
+          unless index
+            raise BrokenPath,
+                  "no attribute '#{attribute}' on '#{target&.id}'"
+          end
+          raise BrokenPath, "complex records are outside v1 scope" if
+            record.is_a?(P21::ComplexRecord)
+
+          record.params[index]
+        end
+
+        def entity_for_record(record)
+          find_entity(record.keyword)
+        end
+
+        def find_entity(name)
+          key = name&.safe_downcase
+          Array(@schema.entities).find { |entity| entity.id&.safe_downcase == key }
+        end
+      end
+    end
+  end
+end