expressir 2.4.32 → 2.4.34

data/lib/expressir/model/declarations/schema.rb

@@ -127,6 +127,19 @@ module Expressir
           @formatted_hyperlinked_adoc ||= Expressir::Express::AdocSourceFormatter.format(self)
         end
 
+        USE_ITEM_KINDS = [
+          Expressir::Model::Declarations::Entity,
+          Expressir::Model::Declarations::Type,
+        ].freeze
+
+        REFERENCE_ITEM_KINDS = [
+          Expressir::Model::Declarations::Constant,
+          Expressir::Model::Declarations::Entity,
+          Expressir::Model::Declarations::Function,
+          Expressir::Model::Declarations::Procedure,
+          Expressir::Model::Declarations::Type,
+        ].freeze
+
         private
 
         # @param [String] id
@@ -142,6 +155,7 @@ module Expressir
         end
 
         # @return [Array<InterfacedItem>]
+
         def interfaced_items
           return [] unless parent
 
@@ -151,6 +165,11 @@ module Expressir
           end.compact
         end
 
+        # ISO 10303-11 implicit interfacing: USE exposes entities and
+        # types only; REFERENCE has no implicit interfacing. Listed
+        # items follow eeng resolve-interface: use-from resolves via
+        # find-type/entity, reference-from via the 5-kind or-chain.
+
         # Direct items of one interface plus the items visible through
         # the foreign schema's own USE interfaces (transitive USE
         # visibility, eeng :use-only → :use-from recursion).
@@ -171,16 +190,23 @@ module Expressir
           end
 
           own = if interface.items.empty?
-                  safe_children.map do |base_item|
-                    create_interfaced_item(base_item.id, base_item)
+                  if interface.kind == Interface::REFERENCE
+                    []
+                  else
+                    safe_children.filter_map do |base_item|
+                      next nil unless USE_ITEM_KINDS.any? { |k| base_item.is_a?(k) }
+
+                      create_interfaced_item(base_item.id, base_item)
+                    end
                   end
                 else
                   interface.items.filter_map do |item|
                     base_item = children_by_id[item.ref.id.safe_downcase]
-                    if base_item
-                      create_interfaced_item(item.id || base_item.id,
-                                             base_item)
-                    end
+                    next nil unless base_item
+                    next nil unless item_kind_interfacable?(interface.kind, base_item)
+
+                    create_interfaced_item(item.id || base_item.id,
+                                           base_item)
                   end
                 end
 
@@ -197,6 +223,11 @@ module Expressir
           end.flatten
         end
 
+        def item_kind_interfacable?(kind, node)
+          kinds = kind == Interface::REFERENCE ? REFERENCE_ITEM_KINDS : USE_ITEM_KINDS
+          kinds.any? { |k| node.is_a?(k) }
+        end
+
         # Find a foreign schema by name: same file first, then the
         # enclosing repository (expressir's compiled/batch repository).
         def foreign_schema(name)

data/lib/expressir/p21/builder.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Expressir
+  module P21
+    # Turns a {Grammar} capture tree into a {Population}.
+    module Builder
+      module_function
+
+      def build(tree)
+        header = build_header(tree[:header_section])
+        instances = build_instances(tree[:data_section])
+        Population.new(header: header, instances: instances)
+      end
+
+      def build_header(section)
+        Array(section[:header_entity]).each_with_object({}) do |entry, hash|
+          record = entry[:simple_record]
+          hash[record_keyword(record)] = record_params(record)
+        end
+      end
+
+      def build_instances(section)
+        list = section[:instance_list]
+        entries = list.is_a?(Array) ? list : [list]
+        entries.each_with_object({}) do |entry, hash|
+          if (complex = entry[:complex_entity_instance])
+            hash[instance_id(complex)] = build_complex(complex)
+          elsif (simple = entry[:simple_entity_instance])
+            record = simple[:simple_record]
+            hash[instance_id(simple)] = Record.new(record_keyword(record),
+                                                   record_params(record))
+          end
+        end
+      end
+
+      def instance_id(body)
+        "##{body[:entity_instance_name].to_s.delete_prefix('#')}"
+      end
+
+      def build_complex(body)
+        subs = body[:subsuper_record]
+        subs = [subs] unless subs.is_a?(Array)
+        records = subs.map do |sub|
+          record = sub[:simple_record]
+          Record.new(record_keyword(record), record_params(record))
+        end
+        ComplexRecord.new(records)
+      end
+
+      def record_keyword(record)
+        record[:keyword].to_s.delete_prefix("!")
+      end
+
+      # A parameter_list capture is a hash when there is a single parameter
+      # and an array of {parameter: ...} entries otherwise.
+      def parameter_list_values(capture)
+        return [] if capture.nil?
+
+        entries = capture.is_a?(Array) ? capture : [capture]
+        entries.map { |entry| build_value(entry[:parameter]) }
+      end
+
+      def record_params(record)
+        parameter_list_values(record[:parameter_list])
+      end
+
+      def build_value(param)
+        if (typed = param[:typed_parameter])
+          TypedValue.new(typed[:keyword].to_s.delete_prefix("!"),
+                         parameter_list_values(typed[:parameter_list]))
+        elsif param[:parameter_list]
+          parameter_list_values(param[:parameter_list])
+        elsif param[:entity_instance_name]
+          "##{param[:entity_instance_name].to_s.delete_prefix('#')}"
+        elsif param[:number_literal]
+          text = param[:number_literal].to_s
+          text.match?(/[.Ee]/) ? text.to_f : text.to_i
+        elsif param[:enumeration]
+          Enumeration.new(param[:enumeration].to_s.delete_prefix(".").delete_suffix("."))
+        elsif param[:binary_literal]
+          Binary.new(param[:binary_literal].to_s.delete_prefix('"').delete_suffix('"'))
+        elsif param[:string_literal]
+          param[:string_literal].to_s[1..-2].gsub("''", "'")
+        elsif param[:unset]
+          :unset
+        elsif param[:derived]
+          :derived
+        end
+      end
+    end
+  end
+end

data/lib/expressir/p21/grammar.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "parsanol"
+
+module Expressir
+  module P21
+    # ISO 10303-21 exchange-structure grammar (TODO.eengine/06 step 1).
+    # Parses the HEADER section and the DATA section's instance list
+    # into a capture tree; {Expressir::P21::PopulationBuilder} turns
+    # the tree into a {Expressir::P21::Population}.
+    #
+    # Reference: ISO 10303-21 exchange structure grammar
+    # (`~/src/mn/iso-10303-detached-docs/sources/iso-10303-21*/`);
+    # scope ladder in TODO.eengine/06 — the supported subset is the
+    # header FILE_* entities plus simple/complex data instances with
+    # lists, typed parameters, references, enumerations, binaries,
+    # strings, unset ($) and derived (*).
+    class Grammar < Parsanol::Parser
+      root(:exchange_structure)
+
+      rule(:comment) { str("/*") >> (str("*/").absent? >> any).repeat >> str("*/") }
+      rule(:ws?) { (match[" \t\r\n"] | comment).repeat }
+      rule(:ws1) { (match[" \t\r\n"] | comment).repeat(1) }
+      rule(:keyword) { match["!"].maybe >> match["A-Za-z0-9_"].repeat(1) }
+      rule(:entity_instance_name) { str("#") >> match["0-9"].repeat(1) }
+
+      rule(:string_literal) do
+        # ISO 10303-21: doubled quotes are escaped quotes
+        str("'") >> ((str("'").absent? >> any) | str("''")).repeat >> str("'")
+      end
+      rule(:binary_literal) { str('"') >> match["0-9A-Fa-f"].repeat >> str('"') }
+      rule(:enumeration) { str(".") >> match["A-Za-z0-9_"].repeat(1) >> str(".") }
+      rule(:unset) { str("$") }
+      rule(:derived) { str("*") }
+
+      rule(:parameter_list) do
+        str("(") >> ws? >>
+          (parameter.as(:parameter) >>
+            (str(",") >> ws? >> parameter.as(:parameter)).repeat).maybe >>
+          str(")") >> ws?
+      end
+
+      rule(:typed_parameter) do
+        keyword.as(:keyword) >> ws? >> parameter_list.as(:parameter_list)
+      end
+      rule(:list_parameter) { parameter_list }
+
+      rule(:number_literal) do
+        match["+-"].maybe >> match["0-9"].repeat(1) >>
+          (str(".") >> match["0-9"].repeat(1)).maybe >>
+          (match["Ee"] >> match["+-"].maybe >> match["0-9"].repeat(1)).maybe
+      end
+
+      rule(:parameter) do
+        typed_parameter.as(:typed_parameter) |
+          list_parameter.as(:parameter_list) |
+          entity_instance_name.as(:entity_instance_name) |
+          number_literal.as(:number_literal) |
+          enumeration.as(:enumeration) |
+          binary_literal.as(:binary_literal) |
+          string_literal.as(:string_literal) |
+          unset.as(:unset) | derived.as(:derived)
+      end
+
+      rule(:simple_record) do
+        keyword.as(:keyword) >> ws? >> parameter_list.as(:parameter_list)
+      end
+
+      rule(:subsuper_record) do
+        str("(") >> ws? >> simple_record.as(:simple_record).repeat(1) >>
+          str(")") >> ws?
+      end
+
+      rule(:simple_entity_instance) do
+        (entity_instance_name.as(:entity_instance_name) >> ws? >>
+          str("=") >> ws? >> simple_record.as(:simple_record) >>
+          str(";") >> ws?).as(:simple_entity_instance)
+      end
+      rule(:complex_entity_instance) do
+        (entity_instance_name.as(:entity_instance_name) >> ws? >>
+          str("=") >> ws? >> subsuper_record.as(:subsuper_record) >>
+          str(";") >> ws?).as(:complex_entity_instance)
+      end
+      rule(:entity_instance) { complex_entity_instance | simple_entity_instance }
+
+      rule(:header_entity) do
+        simple_record.as(:simple_record) >> str(";") >> ws?
+      end
+      rule(:header_section) do
+        str("HEADER;") >> ws? >> header_entity.repeat(1).as(:header_entity) >>
+          str("ENDSEC;") >> ws?
+      end
+      rule(:data_section) do
+        str("DATA;") >> ws? >>
+          (str("(") >> ws? >> parameter >> str(");") >> ws?).maybe >>
+          entity_instance.repeat.as(:instance_list) >>
+          str("ENDSEC;") >> ws?
+      end
+      rule(:exchange_structure) do
+        ws? >> str("ISO-10303-21;") >> ws? >>
+          header_section.as(:header_section) >>
+          data_section.as(:data_section) >>
+          str("END-ISO-10303-21;") >> ws?
+      end
+    end
+  end
+end

data/lib/expressir/p21/parser.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Expressir
+  module P21
+    # Facade: parse an ISO 10303-21 exchange structure into a
+    # {Population} (TODO.eengine/06 step 1).
+    module Parser
+      module_function
+
+      def parse(source)
+        tree = Grammar.new.parse(source)
+        Builder.build(tree)
+      end
+    end
+  end
+end

data/lib/expressir/p21/population.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Expressir
+  module P21
+    # A parsed ISO 10303-21 exchange structure (TODO.eengine/06).
+    # `header`   — Hash: keyword => parameters (Array of values).
+    # `instances`— Hash: "#id" => Record.
+    #
+    # Values: String (string literal), Integer (reference id, keyed as
+    # "#id" in instances), Expressir::P21::Enumeration,
+    # Expressir::P21::Binary, Expressir::P21::TypedValue,
+    # Expressir::P21::ComplexRecord, :unset, :derived, or nested
+    # Arrays for lists.
+    class Population
+      attr_reader :header, :instances
+
+      def initialize(header: {}, instances: {})
+        @header = header
+        @instances = instances
+      end
+    end
+
+    # A data-section instance: `#12 = KEYWORD(param, ...) ;`
+    Record = Struct.new(:keyword, :params)
+
+    # `#21 = (A(...) B(...))` — complex entity instance.
+    ComplexRecord = Struct.new(:records)
+
+    TypedValue = Struct.new(:keyword, :value)
+
+    Enumeration = Struct.new(:name)
+
+    Binary = Struct.new(:hex)
+  end
+end

data/lib/expressir/p21/validator.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Expressir
+  module P21
+    # Validates a {Population} against a loaded schema
+    # (TODO.eengine/06 step 2). Single-schema scope: instance keywords
+    # must be declared in the given schema; USE/REFERENCE visibility is
+    # a later ladder step.
+    #
+    # Mapping follows ISO 10303-21 clause 12: derived attributes are
+    # not mapped (a supertype attribute redeclared as DERIVED keeps its
+    # slot, valued `*`), inverse attributes are not mapped, and the
+    # value order is supertype attributes first.
+    module Validator
+      Note = Struct.new(:id, :severity, :instance, :message, keyword_init: true)
+
+      module_function
+
+      # `short_names` maps exchange-structure short names (ISO 10303-21,
+      # clause 12.3) to schema entity names, e.g. {"CPT" => "cartesian_point"}.
+      def validate(population, schema, short_names: nil)
+        short_names = short_names&.transform_keys(&:downcase)
+        notes = []
+        check_file_schema(notes, population, schema)
+        population.instances.each do |id, instance|
+          if instance.is_a?(ComplexRecord)
+            check_complex(notes, schema, population, id, instance, short_names)
+          else
+            check_simple(notes, schema, population, id, instance, short_names)
+          end
+        end
+        notes
+      end
+
+      def errors(notes)
+        notes.select { |note| note.severity == :error }
+      end
+
+      def warnings(notes)
+        notes.select { |note| note.severity == :warning }
+      end
+
+      def valid?(notes)
+        errors(notes).empty?
+      end
+
+      def note!(notes, id, severity, instance, message)
+        notes << Note.new(id: id, severity: severity, instance: instance,
+                          message: message)
+      end
+
+      def check_file_schema(notes, population, schema)
+        declared = Array(population.header["FILE_SCHEMA"]).flatten.first
+        return unless declared && schema.id
+        return if declared.downcase == schema.id.downcase
+
+        note!(notes, :p21_schema_mismatch, :warning, nil,
+              "FILE_SCHEMA '#{declared}' does not match schema '#{schema.id}'")
+      end
+
+      def check_simple(notes, schema, population, id, record, short_names)
+        entity = find_entity(schema, record.keyword, short_names)
+        unless entity
+          note!(notes, :p21_unknown_entity, :error, id,
+                "#{record.keyword} is not declared in schema '#{schema.id}'")
+          return
+        end
+
+        check_params(notes, schema, population, id, record.params,
+                     mapped_slots(entity))
+      end
+
+      def check_complex(notes, schema, population, id, complex, short_names)
+        pairs = complex.records.filter_map do |record|
+          entity = find_entity(schema, record.keyword, short_names)
+          unless entity
+            note!(notes, :p21_unknown_entity, :error, id,
+                  "#{record.keyword} is not declared in schema '#{schema.id}'")
+            next nil
+          end
+
+          [record, entity]
+        end
+        return if pairs.empty?
+
+        check_clique(notes, id, pairs.map { |_, entity| entity })
+        pairs.each do |record, entity|
+          slots = explicit_attributes(entity).map { |attr| [attr, false] }
+          check_params(notes, schema, population, id, record.params, slots)
+        end
+      end
+
+      # A complex instance's records must form a valid supertype graph
+      # path: they share at least one common supertype.
+      def check_clique(notes, id, entities)
+        common = closure_keys(entities.first)
+        entities.drop(1).each { |entity| common &= closure_keys(entity) }
+        return unless common.empty?
+
+        note!(notes, :p21_complex_clique, :error, id,
+              "#{id}: complex records share no common supertype")
+      end
+
+      def closure_keys(entity)
+        keys = entity.supertype_closure.filter_map { |e| e.id&.downcase }
+        keys << entity.id&.downcase
+      end
+
+      # Part 21 value order: supertype attributes first; an attribute
+      # redeclared as DERIVED in the entity keeps its inherited slot,
+      # valued `*` (12.2.6).
+      def mapped_slots(entity)
+        own_derived_keys = own_derived_attributes(entity)
+          .filter_map { |attr| attr.id&.downcase }
+        inherited = entity.supertype_closure.flat_map do |supertype|
+          explicit_attributes(supertype)
+        end
+        inherited.map do |attr|
+          [attr, own_derived_keys.include?(attr.id&.downcase)]
+        end + explicit_attributes(entity).map { |attr| [attr, false] }
+      end
+
+      def check_params(notes, schema, population, id, params, slots)
+        if params.size != slots.size
+          note!(notes, :p21_arity_mismatch, :error, id,
+                "#{id}: #{params.size} values for #{slots.size} mapped attributes")
+        end
+
+        slots.zip(params).each do |(attr, derived_slot), value|
+          next if value.nil?
+
+          if derived_slot
+            next if value == :derived
+
+            note!(notes, :p21_derived_slot, :error, id,
+                  "#{id}: attribute '#{attr.id}' redeclared DERIVED must be '*'")
+            next
+          end
+
+          check_value(notes, schema, population, id, attr, value)
+        end
+      end
+
+      def check_value(notes, schema, population, id, attr, value)
+        case value
+        when String
+          return unless value.match?(/\A#\d+\z/)
+
+          return if population.instances.key?(value)
+
+          note!(notes, :p21_unknown_reference, :error, id,
+                "#{id}: reference #{value} has no instance")
+        when :derived
+          note!(notes, :p21_derived_value, :error, id,
+                "#{id}: '*' outside a derived slot")
+        when TypedValue
+          return if find_entity(schema, value.keyword) || find_type(schema, value.keyword)
+
+          note!(notes, :p21_unknown_typed_keyword, :error, id,
+                "#{id}: typed parameter '#{value.keyword}' does not resolve")
+        when Enumeration
+          items = enumeration_items(schema, attr)
+          return unless items
+
+          names = items.filter_map { |item| item.id&.downcase }
+          return if names.include?(value.name.downcase)
+
+          note!(notes, :p21_enum_value, :error, id,
+                "#{id}: .#{value.name}. is not in attribute '#{attr.id}' enumeration")
+        when Array
+          value.each { |item| check_value(notes, schema, population, id, attr, item) }
+        end
+      end
+
+      def explicit_attributes(entity)
+        Array(entity.attributes)
+          .select { |attr| attr.instance_of?(Model::Declarations::Attribute) }
+      end
+
+      def own_derived_attributes(entity)
+        Array(entity.attributes)
+          .select { |attr| attr.instance_of?(Model::Declarations::DerivedAttribute) }
+      end
+
+      def find_entity(schema, keyword, short_names = nil)
+        key = keyword.downcase
+        Array(schema.entities).find { |entity| entity.id&.downcase == key } ||
+          resolve_short_name(schema, key, short_names)
+      end
+
+      def resolve_short_name(schema, key, short_names)
+        return nil unless short_names.is_a?(Hash) && short_names[key]
+
+        find_entity(schema, short_names[key], nil)
+      end
+
+      def find_type(schema, keyword)
+        Array(schema.types).find { |type| type.id&.downcase == keyword.downcase }
+      end
+
+      def enumeration_items(schema, attr)
+        type = attr&.type
+        return Array(type.items) if type.is_a?(Model::DataTypes::Enumeration)
+
+        return nil unless type.is_a?(Model::References::SimpleReference)
+
+        declaration = find_type(schema, type.id.to_s)
+        underlying = declaration&.underlying_type
+        underlying.is_a?(Model::DataTypes::Enumeration) ? Array(underlying.items) : nil
+      end
+    end
+  end
+end

data/lib/expressir/p21.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Expressir
+  # ISO 10303-21 exchange-structure support (TODO.eengine/06).
+  module P21
+    autoload :Population, "#{__dir__}/p21/population"
+    autoload :Record, "#{__dir__}/p21/population"
+    autoload :ComplexRecord, "#{__dir__}/p21/population"
+    autoload :TypedValue, "#{__dir__}/p21/population"
+    autoload :Enumeration, "#{__dir__}/p21/population"
+    autoload :Binary, "#{__dir__}/p21/population"
+    autoload :Grammar, "#{__dir__}/p21/grammar"
+    autoload :Builder, "#{__dir__}/p21/builder"
+    autoload :Validator, "#{__dir__}/p21/validator"
+    autoload :Parser, "#{__dir__}/p21/parser"
+  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.32".freeze
+    VERSION = "2.4.34".freeze
   end
 end

data/lib/expressir.rb

@@ -30,6 +30,7 @@ module Expressir
 
   autoload :Version, "#{__dir__}/expressir/version"
   autoload :Mapping, "#{__dir__}/expressir/mapping"
+  autoload :P21, "#{__dir__}/expressir/p21"
 
   # Error classes — autoload the same errors.rb file from each name.
   # The first reference triggers the load; the file defines all 21 classes.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: expressir
 version: !ruby/object:Gem::Version
-  version: 2.4.32
+  version: 2.4.34
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-14 00:00:00.000000000 Z
+date: 2026-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -303,6 +303,16 @@ files:
 - TODO.bugs/29-validate-ascii-god-class.md
 - TODO.bugs/30-unicode-map-extraction.md
 - TODO.bugs/README.md
+- TODO.eengine/00-overview.md
+- TODO.eengine/01-resolution-diagnostics.md
+- TODO.eengine/02-check-catalog-completion.md
+- TODO.eengine/03-entity-computations.md
+- TODO.eengine/04-shtolo-rule-audit.md
+- TODO.eengine/05-shtolo-longform-flatten.md
+- TODO.eengine/06-population-p21.md
+- TODO.eengine/07-schema-compare-patch.md
+- TODO.eengine/08-official-corpus-gate.md
+- TODO.eengine/09-mim-mapping-parser.md
 - TODO.max-perf/01-restore-ci-green.md
 - TODO.max-perf/02-streaming-parse-path.md
 - TODO.max-perf/03-cli-parallel-opt-in.md
@@ -552,6 +562,7 @@ files:
 - lib/expressir/express/remark_scanner.rb
 - lib/expressir/express/resolve_references_model_visitor.rb
 - lib/expressir/express/schema_block_scanner.rb
+- lib/expressir/express/schema_compare.rb
 - lib/expressir/express/schema_head_formatter.rb
 - lib/expressir/express/schema_plain_source_formatter.rb
 - lib/expressir/express/schema_source_formatter.rb
@@ -664,6 +675,12 @@ files:
 - lib/expressir/model/supertype_expressions.rb
 - lib/expressir/model/supertype_expressions/binary_supertype_expression.rb
 - lib/expressir/model/supertype_expressions/oneof_supertype_expression.rb
+- lib/expressir/p21.rb
+- lib/expressir/p21/builder.rb
+- lib/expressir/p21/grammar.rb
+- lib/expressir/p21/parser.rb
+- lib/expressir/p21/population.rb
+- lib/expressir/p21/validator.rb
 - lib/expressir/package.rb
 - lib/expressir/package/builder.rb
 - lib/expressir/package/metadata.rb