expressir 2.4.15 → 2.4.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 714b13d808744a329002460e108fdb35f4a8fcf0d3095517cd241d411bce215e
-  data.tar.gz: 8cf66567212cc463ab351cd6e0cbb70ee63ec11ae2c0b31036cd3d0aff264384
+  metadata.gz: 6fb8953f2f2e9d76be3693148c8951ae36f562bbaf8214a8bc510b68888700d2
+  data.tar.gz: dfbcc336cc1a580501ca69632d6e6bb348e196be470cbc712a637131ffe1993c
 SHA512:
-  metadata.gz: 1c13e1c4cdb0a551e86e2d557c6df01fc2a1b36e1ff536cd4afc6a2255c922d0bcb8252debdc600479514963b38b8482d41de118fb55933472ed173cca77e2aa
-  data.tar.gz: 3f4107ac13feea2a5fdc9d5659312e44af1c7288d957132a119fb1799df396f709ed5c9d82c970669ceda5e64238506abe412a4850c310b4e173f347c67cc31d
+  metadata.gz: 2e5259fb143ac5419ab85b8a97e8ab50a3a809826f799b8cd74242a673599c5cac0bd21cfe1dc33af562c16a806afc95f9f43f75f8eba43e18b68377104d5406
+  data.tar.gz: 0d2520a7a817f1c8d72a6f768887e803c91a6070f3cf8d4230bde9e66dcb6a1580ff7ee39ac6e9c886106cde64db14e175db57e81be0b798ea8f45af57bfaaa7

data/TODO.parity-ee/18-mim-mapping.md

@@ -0,0 +1,47 @@
+# 18 — EXPRESS MIM mapping parser (expressir#88)
+
+## Goal
+
+Parse and validate MIM "reference path" mappings — the application ↔
+interpretation mapping every STEP module carries — into a typed model,
+with the mapping paths validated against the ARM/MIM schemas.
+
+## Sources
+
+- This checkout's canonical form: `schemas/modules/*/mapping.yaml` —
+  structured ae/aimelt/aa records whose values use the
+  `<<express:SCHEMA.ITEM,ITEM>>` link markup (the same markup
+  `Suma::LinkValidation` validates today). Generated upstream from
+  module.xml.
+- Upstream SMRL module.xml: `mapping`/`ae`/`aimelt` elements with
+  `reference_path` bodies — the ISO 10303-1x mapping methodology
+  grammar: entity chains `A -> B -> C`, qualifiers `[attr => val]`,
+  `=>` derived references, `->>` subtype traversal, `<>` select
+  member. Port the grammar from the Part 1x mapping annex text
+  (detached docs) + existing module corpus as the oracle.
+- eeng has no counterpart — this is an expressir-first capability.
+
+## Design
+
+1. `Expressir::Model::Mapping` — MappingDocument →
+   ApplicationElements (entity, aimelt, attributes) and
+   ReferencePath nodes (path-expression AST: steps, qualifiers,
+   subtype traversals).
+2. `mapping.yaml` reader (lutaml-model typed) — yaml → MappingDocument.
+3. Reference-path expression parser — parsanol grammar over the path
+   syntax; AST reuses Model::References where shapes coincide.
+4. Validation: every path resolves against the resolved ARM+MIM
+   repository (rides SchemaIndex / ItemGraph); unknown step = error
+   note (Checker id `check-mapping-path`).
+5. CLI: `expressir mapping validate DIR|FILE` over module dirs.
+
+## Acceptance
+
+- All module mapping.yaml files in the SMRL parse; path validation
+  reports zero unknown steps (or a classified, explained residue).
+- Round-trip: MappingDocument → yaml byte-stable.
+
+## Test cases
+
+- module corpus (603 modules); hand fixtures for each path grammar
+  production; invalid-path fixtures.

data/lib/expressir/commands/parity_inputs.rb

@@ -61,15 +61,18 @@ module Expressir
         end
       end
 
-      # Schema-name → path index from the ELF schema manifest.
+      # Schema-name → path index from the ELF schema manifest. An
+      # explicitly given manifest that cannot be loaded is fatal (#455):
+      # when the root has no interface dependencies the lookup would
+      # never consult the index, so a typo'd --manifest would exit 0.
       def manifest_index(manifest_path)
         manifest = Expressir::SchemaManifest.from_file(manifest_path)
         manifest.schemas.to_h do |entry|
           [entry.id.downcase, entry.path]
         end
       rescue StandardError => e
-        warn "expressir: could not load schema manifest #{manifest_path}: #{e.message}"
-        nil
+        raise Thor::Error,
+              "expressir: could not load schema manifest #{manifest_path}: #{e.message}"
       end
 
       # Schema-name → path index over a STEPmod checkout root (the
@@ -94,10 +97,16 @@ module Expressir
 
         # Default: the file's own directory plus, when the root sits
         # inside a STEPmod checkout, its enclosing `schemas/` tree —
-        # the layout wg12-step modules live in.
+        # the layout wg12-step modules live in. Same-directory
+        # declarations win over tree hits for the same schema name:
+        # the file next to the root is the intentional one (#455).
         index = same_dir_index(root_path)
         ancestor = ancestor_schemas_dir(root_path)
-        index.update(stepmod_index(File.dirname(ancestor))) if ancestor
+        if ancestor
+          tree = stepmod_index(File.dirname(ancestor))
+          tree.update(index)
+          index = tree
+        end
         index
       end
 

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/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.15".freeze
+    VERSION = "2.4.17".freeze
   end
 end

data/rakelib/oracle.rake

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+
+ORACLE_TAG = "eeng-5.2.8"
+ORACLE_BASE =
+  "https://github.com/expresslang/eengine-releases/releases/download/#{ORACLE_TAG}".freeze
+# Release-asset naming convention for the pinned tag: platform prefix
+# and CPU tag used by expresslang/eengine-releases.
+ORACLE_ASSET_NAMES = {
+  %w[darwin arm64] => "mac-arm64",
+  %w[darwin x86_64] => "mac-x86-64",
+  %w[linux x86_64] => "lnx-x86-64",
+  %w[linux arm64] => "lnx-arm64",
+  %w[mingw x86_64] => "win-x86-64",
+}.freeze
+
+namespace :oracle do
+  desc "Fetch the eengine oracle (#{ORACLE_TAG}) into tmp/oracle/eengine " \
+       "for the SHTOLO corpus differential"
+  task :fetch do
+    platform = [Gem::Platform.local.os, Gem::Platform.local.cpu]
+    tag = ORACLE_ASSET_NAMES[platform]
+    abort "no #{ORACLE_TAG} asset for #{platform.join('-')}" unless tag
+
+    version = ORACLE_TAG.delete_prefix("eeng-")
+    asset = "eengine-#{version}-#{tag}-sbcl#{'.exe' if platform.first == 'mingw'}"
+    target = File.expand_path("../tmp/oracle/eengine", __dir__)
+    digest = "#{target}.sha256"
+
+    if File.executable?(target)
+      expected = File.read(digest).strip.split(/\s+/).first if File.exist?(digest)
+      if expected && Digest::SHA256.file(target).hexdigest == expected
+        warn "oracle already present: #{target}"
+        exit 0
+      end
+      warn "cached oracle is missing or corrupt; refetching"
+      rm_f target
+    end
+
+    dir = File.dirname(target)
+    mkdir_p dir
+    download = File.join(dir, "#{asset}.part")
+    sh "curl", "-fSL", "-o", download, "#{ORACLE_BASE}/#{asset}"
+    sha = Digest::SHA256.file(download).hexdigest
+    mv download, target
+    chmod 0o755, target
+    File.write(digest, "#{sha}  eengine\n")
+    puts "oracle ready: #{target} (#{sha})"
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: expressir
 version: !ruby/object:Gem::Version
-  version: 2.4.15
+  version: 2.4.17
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-23 00:00:00.000000000 Z
+date: 2026-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -318,6 +318,7 @@ files:
 - TODO.parity-ee/15-part28-xml.md
 - TODO.parity-ee/16-compare-patch.md
 - TODO.parity-ee/17-official-tests.md
+- TODO.parity-ee/18-mim-mapping.md
 - TODO.parity-ee/19-architecture.md
 - TODO.parity-ee/parity-matrix.md
 - benchmark/srl_benchmark.rb
@@ -505,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
@@ -639,6 +641,7 @@ files:
 - lib/expressir/schema_manifest_entry.rb
 - lib/expressir/version.rb
 - lib/tasks/verify_remarks.rake
+- rakelib/oracle.rake
 - rakelib/verify_remarks.rake
 homepage: https://github.com/lutaml/expressir
 licenses: